932 lines
40 KiB
TypeScript
932 lines
40 KiB
TypeScript
/**
|
||
* Skill discovery, installation, and management tools for the agent.
|
||
*
|
||
* These tools let the agent dynamically discover capabilities it needs,
|
||
* install skills from the local filesystem or by creating them on the fly,
|
||
* and manage the active skill set — closing the gap to Claude Code's ecosystem.
|
||
*/
|
||
|
||
import * as fs from 'node:fs';
|
||
import * as path from 'node:path';
|
||
import type { ToolDefinition } from './tools.js';
|
||
import { SkillRecommender } from './skill-recommender.js';
|
||
import { searchCapabilities, validateInstallCandidate, type MarketplaceCandidate } from './capability-acquisition.js';
|
||
import { assessTrust, formatTrustSummary } from './trust-model.js';
|
||
import type { InstallAuditStore } from '@waggle/core';
|
||
// Type-only import — erased at runtime, so it does NOT reintroduce the
|
||
// agent ↔ marketplace runtime cycle that the lazy import below guards against.
|
||
import type { SecurityGate, MarketplacePackage } from '@waggle/marketplace';
|
||
// Lazy import to avoid circular dependency (agent ↔ marketplace)
|
||
let _SecurityGate: typeof SecurityGate | null = null;
|
||
async function getSecurityGate(): Promise<typeof SecurityGate> {
|
||
if (!_SecurityGate) {
|
||
const mod = await import('@waggle/marketplace');
|
||
_SecurityGate = mod.SecurityGate;
|
||
}
|
||
return _SecurityGate;
|
||
}
|
||
import { generateSkillMarkdown, type SkillTemplate } from './skill-creator.js';
|
||
import { redactSkillContent } from './skill-redaction.js';
|
||
import { writeSkill, deleteSkill as deleteSkillWrite } from './skill-write-service.js';
|
||
import {
|
||
parseSkillFrontmatter,
|
||
serializeFrontmatter,
|
||
nextScope,
|
||
SKILL_SCOPE_ORDER,
|
||
type SkillScope,
|
||
} from './skill-frontmatter.js';
|
||
import type { ImprovementSignalStore } from '@waggle/core';
|
||
import { autoExtractAndCreateSkill, type AutoExtractMessage } from './skill-autoextract.js';
|
||
import { retireStaleSkills } from './skill-retirement.js';
|
||
|
||
export interface SkillToolsDeps {
|
||
/** Path to ~/.waggle directory */
|
||
waggleHome: string;
|
||
/** Callback to reload skills into agent state after changes */
|
||
onSkillsChanged?: () => void;
|
||
/** Path to starter skills source directory (from @waggle/sdk) */
|
||
starterSkillsDir?: string;
|
||
/** Function to get current installed skills (for acquisition search) */
|
||
getInstalledSkills?: () => Array<{ name: string; content: string }>;
|
||
/** Native tool names (for acquisition search — avoids proposing install when a tool exists) */
|
||
nativeToolNames?: string[];
|
||
/** Audit store for recording install events (optional — degrades gracefully) */
|
||
auditStore?: InstallAuditStore;
|
||
/** Optional callback to search the marketplace catalog for capabilities */
|
||
searchMarketplace?: (query: string) => Promise<MarketplaceCandidate[]>;
|
||
/**
|
||
* Skills 2.0 gap E: promotion infrastructure. Each callback is optional.
|
||
* - getWorkspaceId / getTeamId resolve scope dirs dynamically at tool-call time.
|
||
* - hasTeamSkillLibrary / isEnterprise gate tier-restricted scopes.
|
||
* - improvementSignals records skill_promotion signals on successful moves.
|
||
*/
|
||
getWorkspaceId?: () => string | null;
|
||
getTeamId?: () => string | null;
|
||
hasTeamSkillLibrary?: () => boolean;
|
||
isEnterprise?: () => boolean;
|
||
improvementSignals?: ImprovementSignalStore;
|
||
/**
|
||
* Skills 2.0 gap A: session-message accessor for auto-extracting skills
|
||
* from repeated workflow patterns. When provided, enables the
|
||
* auto_extract_skills tool.
|
||
*/
|
||
getSessionMessages?: () => AutoExtractMessage[];
|
||
}
|
||
|
||
/**
|
||
* Skills 2.0 gap E: resolve the on-disk directory for a given scope.
|
||
* - personal: ~/.waggle/skills/
|
||
* - workspace: ~/.waggle/workspaces/{workspaceId}/skills/
|
||
* - team: ~/.waggle/teams/{teamId}/skills/
|
||
* - enterprise: ~/.waggle/enterprise/skills/
|
||
*
|
||
* Returns null when the required context (workspaceId, teamId) is missing.
|
||
*/
|
||
export function getSkillDirForScope(
|
||
waggleHome: string,
|
||
scope: SkillScope,
|
||
ctx: { workspaceId?: string | null; teamId?: string | null },
|
||
): string | null {
|
||
switch (scope) {
|
||
case 'personal':
|
||
return path.join(waggleHome, 'skills');
|
||
case 'workspace':
|
||
if (!ctx.workspaceId) return null;
|
||
return path.join(waggleHome, 'workspaces', ctx.workspaceId, 'skills');
|
||
case 'team':
|
||
if (!ctx.teamId) return null;
|
||
return path.join(waggleHome, 'teams', ctx.teamId, 'skills');
|
||
case 'enterprise':
|
||
return path.join(waggleHome, 'enterprise', 'skills');
|
||
}
|
||
}
|
||
|
||
export function createSkillTools(deps: SkillToolsDeps): ToolDefinition[] {
|
||
const { waggleHome, onSkillsChanged } = deps;
|
||
const skillsDir = path.join(waggleHome, 'skills');
|
||
const pluginsDir = path.join(waggleHome, 'plugins');
|
||
|
||
// Ensure directories exist
|
||
if (!fs.existsSync(skillsDir)) fs.mkdirSync(skillsDir, { recursive: true });
|
||
if (!fs.existsSync(pluginsDir)) fs.mkdirSync(pluginsDir, { recursive: true });
|
||
|
||
return [
|
||
// 1. list_skills — Show all installed skills and plugins
|
||
{
|
||
name: 'list_skills',
|
||
description: 'List all installed skills and plugins. Skills extend your capabilities. Use this to check what you already have before searching for new ones.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
verbose: { type: 'boolean', description: 'Show full skill content (default: false, shows preview only)' },
|
||
},
|
||
},
|
||
execute: async (args) => {
|
||
const verbose = args.verbose as boolean ?? false;
|
||
|
||
// List skills
|
||
const skillFiles = fs.existsSync(skillsDir)
|
||
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
|
||
: [];
|
||
|
||
const skills = skillFiles.map(f => {
|
||
const name = f.replace(/\.md$/, '');
|
||
const content = fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim();
|
||
return {
|
||
name,
|
||
type: 'skill' as const,
|
||
preview: verbose ? content : content.slice(0, 150) + (content.length > 150 ? '...' : ''),
|
||
size: content.length,
|
||
};
|
||
});
|
||
|
||
// List plugins
|
||
const pluginEntries = fs.existsSync(pluginsDir)
|
||
? fs.readdirSync(pluginsDir, { withFileTypes: true }).filter(d => d.isDirectory())
|
||
: [];
|
||
|
||
const plugins = pluginEntries.map(d => {
|
||
const manifestPath = path.join(pluginsDir, d.name, 'manifest.json');
|
||
let manifest: Record<string, unknown> = {};
|
||
if (fs.existsSync(manifestPath)) {
|
||
try { manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')); } catch { /* ignore */ }
|
||
}
|
||
return {
|
||
name: d.name,
|
||
type: 'plugin' as const,
|
||
description: (manifest.description as string) ?? 'No description',
|
||
version: (manifest.version as string) ?? 'unknown',
|
||
};
|
||
});
|
||
|
||
if (skills.length === 0 && plugins.length === 0) {
|
||
return 'No skills or plugins installed.\n\nYou can create a new skill with create_skill or search for existing ones with search_skills.';
|
||
}
|
||
|
||
let output = '';
|
||
if (skills.length > 0) {
|
||
output += `## Installed Skills (${skills.length})\n\n`;
|
||
for (const s of skills) {
|
||
output += `- **${s.name}** (${s.size} chars)\n ${s.preview}\n\n`;
|
||
}
|
||
}
|
||
if (plugins.length > 0) {
|
||
output += `## Installed Plugins (${plugins.length})\n\n`;
|
||
for (const p of plugins) {
|
||
output += `- **${p.name}** v${p.version} — ${p.description}\n`;
|
||
}
|
||
}
|
||
return output;
|
||
},
|
||
},
|
||
|
||
// 2. create_skill — Create a new skill on the fly (supports raw content OR structured template)
|
||
{
|
||
name: 'create_skill',
|
||
description: 'Create a new reusable skill from a workflow description or raw markdown content. Skills are loaded into your system prompt and persist across sessions. You can provide either raw `content` (markdown) or structured fields (`description`, `steps`, `tools`, `category`) and the skill markdown will be generated automatically.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
name: { type: 'string', description: 'Skill name (kebab-case, alphanumeric + hyphens, no spaces)' },
|
||
content: { type: 'string', description: 'Raw skill content in markdown. If provided, steps/tools/category are ignored.' },
|
||
description: { type: 'string', description: 'What this skill does (used when generating from structured input)' },
|
||
steps: { type: 'array', items: { type: 'string' }, description: 'Step-by-step workflow instructions' },
|
||
tools: { type: 'array', items: { type: 'string' }, description: 'Tools this skill uses (e.g., web_search, save_memory)' },
|
||
category: { type: 'string', description: 'Category (coding, research, writing, planning, knowledge, general)' },
|
||
},
|
||
required: ['name'],
|
||
},
|
||
execute: async (args) => {
|
||
const name = args.name as string;
|
||
const rawContent = args.content as string | undefined;
|
||
const description = args.description as string | undefined;
|
||
const steps = args.steps as string[] | undefined;
|
||
const tools = args.tools as string[] | undefined;
|
||
const category = args.category as string | undefined;
|
||
|
||
// Validate name
|
||
if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
|
||
return 'Error: Skill name must contain only letters, numbers, hyphens, and underscores.';
|
||
}
|
||
|
||
// Determine content: raw content takes priority, otherwise generate from template
|
||
let content: string;
|
||
if (rawContent) {
|
||
content = rawContent;
|
||
} else if (description && steps && steps.length > 0) {
|
||
const template: SkillTemplate = {
|
||
name,
|
||
description,
|
||
triggerPatterns: [],
|
||
steps,
|
||
tools: tools ?? [],
|
||
category: category ?? 'general',
|
||
};
|
||
content = generateSkillMarkdown(template);
|
||
} else {
|
||
return 'Error: Provide either "content" (raw markdown) or "description" + "steps" (structured input).';
|
||
}
|
||
|
||
// P5/D4(iii): one write path. The shared service strips secrets/paths,
|
||
// stamps agent provenance, records the install audit row, and fires the
|
||
// reload callback — same code the HTTP routes run.
|
||
const result = writeSkill(
|
||
{ skillsDir, auditStore: deps.auditStore, onChange: onSkillsChanged },
|
||
{ name, content, initiator: 'agent', source: 'chat' },
|
||
);
|
||
if (!result.ok) return `Error: ${result.error}`;
|
||
|
||
const redactions = result.redactions ?? [];
|
||
const redactNote = redactions.length
|
||
? `\n⚠️ Redacted ${redactions.length} secret(s)/path(s) before saving: ${redactions.join(', ')}.`
|
||
: '';
|
||
return `${result.existed ? 'Updated' : 'Created'} skill "${name}".${redactNote}\nLocation: ${result.path}\n\nThe skill is now active and will be included in your system prompt for all future messages.`;
|
||
},
|
||
},
|
||
|
||
// 3. delete_skill — Remove a skill
|
||
{
|
||
name: 'delete_skill',
|
||
description: 'Delete an installed skill by name.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
name: { type: 'string', description: 'Name of the skill to delete' },
|
||
},
|
||
required: ['name'],
|
||
},
|
||
execute: async (args) => {
|
||
const name = args.name as string;
|
||
// P5/D4(iii): one delete path — audits 'uninstalled' with agent provenance.
|
||
const result = deleteSkillWrite(
|
||
{ skillsDir, auditStore: deps.auditStore, onChange: onSkillsChanged },
|
||
{ name, initiator: 'agent', source: 'chat' },
|
||
);
|
||
if (!result.ok) return `Error: ${result.error}`;
|
||
return `Deleted skill "${name}".`;
|
||
},
|
||
},
|
||
|
||
// 4. read_skill — Read full content of a skill
|
||
{
|
||
name: 'read_skill',
|
||
description: 'Read the full content of an installed skill.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
name: { type: 'string', description: 'Name of the skill to read' },
|
||
},
|
||
required: ['name'],
|
||
},
|
||
execute: async (args) => {
|
||
const name = args.name as string;
|
||
if (name.includes('..') || name.includes('/') || name.includes('\\')) {
|
||
return 'Error: Invalid skill name.';
|
||
}
|
||
const filePath = path.join(skillsDir, `${name}.md`);
|
||
if (!fs.existsSync(filePath)) {
|
||
return `Error: Skill "${name}" not found.`;
|
||
}
|
||
return fs.readFileSync(filePath, 'utf-8');
|
||
},
|
||
},
|
||
|
||
// 5. search_skills — Search for skills/tools by description
|
||
{
|
||
name: 'search_skills',
|
||
description: 'Search for skills and tools you might need. Searches installed skills by content/name, and suggests built-in capabilities. Use when the user asks you to do something and you want to check if you have the right tool.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
query: { type: 'string', description: 'What capability are you looking for? (e.g., "generate PDF", "code review", "data analysis")' },
|
||
},
|
||
required: ['query'],
|
||
},
|
||
execute: async (args) => {
|
||
const query = (args.query as string).toLowerCase();
|
||
|
||
// Search installed skills
|
||
const skillFiles = fs.existsSync(skillsDir)
|
||
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
|
||
: [];
|
||
|
||
const matchingSkills = skillFiles
|
||
.map(f => {
|
||
const name = f.replace(/\.md$/, '');
|
||
const content = fs.readFileSync(path.join(skillsDir, f), 'utf-8');
|
||
const nameMatch = name.toLowerCase().includes(query);
|
||
const contentMatch = content.toLowerCase().includes(query);
|
||
return { name, content, match: nameMatch || contentMatch, nameMatch };
|
||
})
|
||
.filter(s => s.match)
|
||
.map(s => `- **${s.name}** (installed skill) — ${s.content.slice(0, 100)}...`);
|
||
|
||
// Built-in capability suggestions based on query keywords
|
||
const suggestions: string[] = [];
|
||
const builtins: Array<{ keywords: string[]; desc: string }> = [
|
||
{ keywords: ['document', 'docx', 'word', 'report'], desc: 'generate_docx — Create formatted Word documents from markdown' },
|
||
{ keywords: ['plan', 'planning', 'steps', 'strategy'], desc: 'create_plan — Create structured multi-step plans' },
|
||
{ keywords: ['git', 'commit', 'version', 'branch'], desc: 'git_status/git_diff/git_log/git_commit — Version control tools' },
|
||
{ keywords: ['memory', 'remember', 'recall', 'history'], desc: 'search_memory/save_memory — Persistent memory across sessions' },
|
||
{ keywords: ['web', 'search', 'internet', 'browse', 'fetch'], desc: 'web_search/web_fetch — Search and read web pages' },
|
||
{ keywords: ['file', 'read', 'write', 'edit', 'code'], desc: 'read_file/write_file/edit_file — File system operations' },
|
||
{ keywords: ['bash', 'command', 'terminal', 'shell', 'run'], desc: 'bash — Execute shell commands' },
|
||
{ keywords: ['knowledge', 'graph', 'entity', 'relation'], desc: 'query_knowledge/correct_knowledge — Knowledge graph operations' },
|
||
{ keywords: ['search', 'find', 'grep', 'pattern'], desc: 'search_files/search_content — Find files and search contents' },
|
||
];
|
||
|
||
for (const b of builtins) {
|
||
if (b.keywords.some(k => query.includes(k))) {
|
||
suggestions.push(`- ${b.desc} (built-in tool)`);
|
||
}
|
||
}
|
||
|
||
let output = '';
|
||
if (matchingSkills.length > 0) {
|
||
output += `## Matching Installed Skills\n${matchingSkills.join('\n')}\n\n`;
|
||
}
|
||
if (suggestions.length > 0) {
|
||
output += `## Relevant Built-in Tools\n${suggestions.join('\n')}\n\n`;
|
||
}
|
||
if (matchingSkills.length === 0 && suggestions.length === 0) {
|
||
output += `No installed skills or built-in tools match "${query}".\n\n`;
|
||
output += '**Suggestions:**\n';
|
||
output += '- Use `create_skill` to create a custom skill for this domain\n';
|
||
output += '- Use `web_search` to find instructions or templates online\n';
|
||
output += '- Use `bash` to check if relevant CLI tools are installed on the system\n';
|
||
}
|
||
|
||
return output;
|
||
},
|
||
},
|
||
|
||
// 6. suggest_skill — Context-aware skill recommendations
|
||
{
|
||
name: 'suggest_skill',
|
||
description: 'Get skill recommendations based on the current conversation context. Use this when you want to check if any installed skills could help with what the user is asking.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
context: { type: 'string', description: 'The current conversation topic or user request to match against installed skills' },
|
||
topN: { type: 'number', description: 'Maximum number of suggestions to return (default: 3)' },
|
||
},
|
||
required: ['context'],
|
||
},
|
||
execute: async (args) => {
|
||
const context = args.context as string;
|
||
const topN = (args.topN as number) ?? 3;
|
||
|
||
const recommender = new SkillRecommender({
|
||
getSkills: () => {
|
||
const files = fs.existsSync(skillsDir)
|
||
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
|
||
: [];
|
||
return files.map(f => ({
|
||
name: f.replace(/\.md$/, ''),
|
||
content: fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim(),
|
||
}));
|
||
},
|
||
activeSkills: [],
|
||
});
|
||
|
||
const suggestions = recommender.recommend(context, topN);
|
||
|
||
if (suggestions.length === 0) {
|
||
return 'No matching skills found. Consider creating a custom skill with create_skill.';
|
||
}
|
||
|
||
return suggestions.map((s, i) =>
|
||
`${i + 1}. **${s.skillName}** (relevance: ${(s.relevanceScore * 100).toFixed(0)}%)\n ${s.reason}`,
|
||
).join('\n\n');
|
||
},
|
||
},
|
||
|
||
// 7. acquire_capability — Structured gap detection + candidate search
|
||
{
|
||
name: 'acquire_capability',
|
||
description: `Detect capability gaps and find installable skills to fill them. Use this when:
|
||
- You encounter a task you don't have a specialized skill for
|
||
- The user asks for something that could benefit from structured guidance (risk assessment, research synthesis, code review, etc.)
|
||
- You want to check if there's a curated skill available before attempting a task with general abilities
|
||
|
||
Returns a structured proposal showing what's already available, what can be installed, and a recommendation with reasoning. If a native tool or active skill already covers the need, it tells you so instead of proposing an install.`,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
need: {
|
||
type: 'string',
|
||
description: 'What capability you need — describe the task or domain (e.g., "risk assessment for a project", "synthesize research from multiple sources", "code review checklist")',
|
||
},
|
||
},
|
||
required: ['need'],
|
||
},
|
||
execute: async (args) => {
|
||
const need = args.need as string;
|
||
if (!need || !need.trim()) {
|
||
return 'Error: "need" is required — describe what capability you are looking for.';
|
||
}
|
||
|
||
const installedSkills = deps.getInstalledSkills?.() ?? (() => {
|
||
const files = fs.existsSync(skillsDir)
|
||
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md'))
|
||
: [];
|
||
return files.map(f => ({
|
||
name: f.replace(/\.md$/, ''),
|
||
content: fs.readFileSync(path.join(skillsDir, f), 'utf-8').trim(),
|
||
}));
|
||
})();
|
||
|
||
const starterDir = deps.starterSkillsDir ?? '';
|
||
const nativeTools = deps.nativeToolNames ?? [];
|
||
|
||
// Search marketplace if callback is available (non-blocking — graceful fallback)
|
||
let marketplaceCandidates: MarketplaceCandidate[] = [];
|
||
if (deps.searchMarketplace) {
|
||
try {
|
||
marketplaceCandidates = await deps.searchMarketplace(need);
|
||
} catch {
|
||
// Marketplace unavailable — continue with local sources only
|
||
}
|
||
}
|
||
|
||
const proposal = searchCapabilities({
|
||
need,
|
||
installedSkills,
|
||
starterSkillsDir: starterDir,
|
||
nativeToolNames: nativeTools,
|
||
marketplaceCandidates,
|
||
});
|
||
|
||
// Record proposal audit event if a gap was detected with a recommendation
|
||
if (proposal.gapDetected && proposal.recommendation?.trust) {
|
||
const trust = proposal.recommendation.trust;
|
||
deps.auditStore?.record({
|
||
capabilityName: proposal.recommendation.name,
|
||
capabilityType: proposal.recommendation.type,
|
||
source: proposal.recommendation.source,
|
||
riskLevel: trust.riskLevel,
|
||
trustSource: trust.trustSource,
|
||
approvalClass: trust.approvalClass,
|
||
action: 'proposed',
|
||
initiator: 'agent',
|
||
detail: `Proposed for need: ${need}`,
|
||
});
|
||
}
|
||
|
||
return proposal.summary;
|
||
},
|
||
},
|
||
|
||
// 8. install_capability — Install a specific capability from a curated source (requires approval)
|
||
{
|
||
name: 'install_capability',
|
||
description: `Install a capability identified by acquire_capability. This copies a curated starter skill into your active skill set. Requires user approval before installation (approval gate will appear in the UI).
|
||
|
||
After installation, the skill content is returned so you can immediately apply it to the current task. The skill is also hot-loaded into your system prompt for all future messages.
|
||
|
||
Only use this after acquire_capability has identified a specific installable candidate. Do not guess names — use the exact name and source from the proposal.`,
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
name: {
|
||
type: 'string',
|
||
description: 'Exact name of the capability to install (from acquire_capability proposal)',
|
||
},
|
||
source: {
|
||
type: 'string',
|
||
description: 'Source of the capability (e.g., "starter-pack"). Must match the source from the proposal.',
|
||
},
|
||
},
|
||
required: ['name', 'source'],
|
||
},
|
||
execute: async (args) => {
|
||
const name = args.name as string;
|
||
const source = args.source as string;
|
||
|
||
// Path traversal protection
|
||
if (name.includes('..') || name.includes('/') || name.includes('\\')) {
|
||
return 'Error: Invalid capability name.';
|
||
}
|
||
|
||
const starterDir = deps.starterSkillsDir ?? '';
|
||
const installedNames = new Set(
|
||
fs.existsSync(skillsDir)
|
||
? fs.readdirSync(skillsDir).filter(f => f.endsWith('.md')).map(f => f.replace(/\.md$/, ''))
|
||
: [],
|
||
);
|
||
|
||
// Validate this is a real, installable candidate
|
||
const validation = validateInstallCandidate(name, source, starterDir, installedNames);
|
||
if (!validation.valid) {
|
||
// Record failed install attempt
|
||
deps.auditStore?.record({
|
||
capabilityName: name,
|
||
capabilityType: 'skill',
|
||
source,
|
||
riskLevel: 'low',
|
||
trustSource: 'unknown',
|
||
approvalClass: 'standard',
|
||
action: 'failed',
|
||
initiator: 'agent',
|
||
detail: validation.error ?? 'Validation failed',
|
||
});
|
||
return `Error: ${validation.error}`;
|
||
}
|
||
|
||
// Read content from starter pack for trust assessment
|
||
const sourceContent = fs.readFileSync(validation.starterPath!, 'utf-8');
|
||
|
||
// ── SecurityGate scan (heuristics-only) ──────────────────────
|
||
let securityNote = '';
|
||
try {
|
||
const SGClass = await getSecurityGate();
|
||
const gate = new SGClass({
|
||
enable_gen_trust_hub: false,
|
||
enable_cisco_scanner: false,
|
||
enable_mcp_guardian: false,
|
||
enable_heuristics: true,
|
||
});
|
||
// Heuristics-only scan needs just these identity fields; the rest of
|
||
// MarketplacePackage is irrelevant here. Build a typed partial and
|
||
// widen to the full param type (scan() reads only name/type fields).
|
||
const scanPkg: Partial<MarketplacePackage> = {
|
||
name,
|
||
package_type: 'skill',
|
||
waggle_install_type: 'skill',
|
||
};
|
||
const scanResult = await gate.scan(scanPkg as MarketplacePackage, sourceContent);
|
||
|
||
// CRITICAL: refuse installation
|
||
if (scanResult.overall_severity === 'CRITICAL') {
|
||
deps.auditStore?.record({
|
||
capabilityName: name,
|
||
capabilityType: 'skill',
|
||
source,
|
||
riskLevel: 'critical',
|
||
trustSource: 'security-gate',
|
||
approvalClass: 'blocked',
|
||
action: 'blocked',
|
||
initiator: 'system',
|
||
detail: `SecurityGate blocked: ${scanResult.findings.length} CRITICAL finding(s)`,
|
||
});
|
||
const findingsText = scanResult.findings.map((f) => `- [${f.severity}] ${f.title}: ${f.description}`).join('\n');
|
||
return (
|
||
`## Installation Blocked — CRITICAL Security Finding\n\n` +
|
||
`**${name}** cannot be installed due to critical security issues:\n\n` +
|
||
`${findingsText}\n\n` +
|
||
`Security score: ${scanResult.security_score}/100\n\n` +
|
||
`This skill has been blocked for your protection. Do NOT attempt to bypass this gate.`
|
||
);
|
||
}
|
||
|
||
// HIGH: include warning note — the agent should inform the user
|
||
if (scanResult.overall_severity === 'HIGH') {
|
||
const findingsText = scanResult.findings.map((f) => `- [${f.severity}] ${f.title}`).join('\n');
|
||
securityNote = (
|
||
`\n### Security Warning\n` +
|
||
`SecurityGate found HIGH severity issues (score: ${scanResult.security_score}/100):\n` +
|
||
`${findingsText}\n` +
|
||
`The user should review these findings before relying on this skill.\n`
|
||
);
|
||
}
|
||
|
||
// MEDIUM: include informational note
|
||
if (scanResult.overall_severity === 'MEDIUM') {
|
||
securityNote = (
|
||
`\n### Security Note\n` +
|
||
`SecurityGate found minor issues (score: ${scanResult.security_score}/100, ${scanResult.findings.length} finding(s)). ` +
|
||
`Review recommended but not blocking.\n`
|
||
);
|
||
}
|
||
|
||
// LOW/CLEAN: include score in summary
|
||
if (scanResult.overall_severity === 'LOW' || scanResult.overall_severity === 'CLEAN') {
|
||
securityNote = `\n- **Security Score**: ${scanResult.security_score}/100 (${scanResult.overall_severity})\n`;
|
||
}
|
||
} catch {
|
||
// SecurityGate scan failure is non-blocking — proceed with install
|
||
securityNote = '\n- **Security Scan**: Unavailable (scan engine error)\n';
|
||
}
|
||
|
||
// Assess trust before installing
|
||
const trust = assessTrust({
|
||
capabilityType: 'skill',
|
||
source,
|
||
content: sourceContent,
|
||
});
|
||
|
||
// Record proposal audit event
|
||
deps.auditStore?.record({
|
||
capabilityName: name,
|
||
capabilityType: 'skill',
|
||
source,
|
||
riskLevel: trust.riskLevel,
|
||
trustSource: trust.trustSource,
|
||
approvalClass: trust.approvalClass,
|
||
action: 'approved',
|
||
initiator: 'agent',
|
||
detail: trust.explanation,
|
||
});
|
||
|
||
// Copy from starter pack to installed skills directory
|
||
const targetPath = path.join(skillsDir, `${name}.md`);
|
||
fs.copyFileSync(validation.starterPath!, targetPath);
|
||
|
||
// Trigger hot-reload so the skill is immediately available in runtime
|
||
onSkillsChanged?.();
|
||
|
||
// Record successful install audit event
|
||
deps.auditStore?.record({
|
||
capabilityName: name,
|
||
capabilityType: 'skill',
|
||
source,
|
||
riskLevel: trust.riskLevel,
|
||
trustSource: trust.trustSource,
|
||
approvalClass: trust.approvalClass,
|
||
action: 'installed',
|
||
initiator: 'agent',
|
||
detail: `Installed successfully. ${trust.explanation}`,
|
||
});
|
||
|
||
// Read the content to return it — so the agent can use it in the same turn
|
||
const content = fs.readFileSync(targetPath, 'utf-8');
|
||
const trustSummary = formatTrustSummary(trust);
|
||
|
||
return (
|
||
`## Skill Installed Successfully\n\n` +
|
||
`**${name}** has been installed from the ${source} and is now active.\n\n` +
|
||
`- **Location**: ${targetPath}\n` +
|
||
`- **Status**: Active — loaded into your system prompt\n` +
|
||
`- **Runtime**: Available immediately for this and all future sessions\n` +
|
||
securityNote + `\n` +
|
||
`### Trust Assessment\n${trustSummary}\n\n` +
|
||
`### Skill Content\n\nUse the following instructions to complete the current task:\n\n` +
|
||
`---\n\n${content}\n\n---\n\n` +
|
||
`You can now apply this skill to the user's request.`
|
||
);
|
||
},
|
||
},
|
||
|
||
// Skills 2.0 gap E: promote_skill — move a skill up one scope rung.
|
||
// personal → workspace → team → enterprise. Enforces one-step-at-a-time,
|
||
// tier gates, and records a skill_promotion improvement signal on success.
|
||
{
|
||
name: 'promote_skill',
|
||
description:
|
||
'Promote an installed skill one scope up (personal → workspace → team → enterprise). '
|
||
+ 'Team scope requires the teamSkillLibrary capability (TEAMS or ENTERPRISE tier). '
|
||
+ 'Enterprise scope requires ENTERPRISE tier. '
|
||
+ 'The file is moved to the appropriate directory, frontmatter is rewritten '
|
||
+ '(scope + promoted_from history), and a skill_promotion signal is recorded.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
skill_name: {
|
||
type: 'string',
|
||
description: 'Name of the installed skill (SKILL.md filename without extension).',
|
||
},
|
||
target_scope: {
|
||
type: 'string',
|
||
enum: [...SKILL_SCOPE_ORDER],
|
||
description:
|
||
'Target scope. If omitted, auto-advances one step from the skill\'s current scope. '
|
||
+ 'Must be exactly one rung above the current scope — no jumps.',
|
||
},
|
||
},
|
||
required: ['skill_name'],
|
||
},
|
||
execute: async (args) => {
|
||
const skillName = args.skill_name as string;
|
||
const explicitTarget = args.target_scope as SkillScope | undefined;
|
||
|
||
// Resolve context for scope paths
|
||
const workspaceId = deps.getWorkspaceId?.() ?? null;
|
||
const teamId = deps.getTeamId?.() ?? null;
|
||
const ctx = { workspaceId, teamId };
|
||
|
||
// 1. Locate the skill: walk every scope dir the agent can see and
|
||
// find a SKILL file that matches the requested name. Preference
|
||
// order follows SKILL_SCOPE_ORDER so we pick the lowest scope
|
||
// available when multiple copies exist.
|
||
type Located = { scope: SkillScope; filePath: string; content: string };
|
||
let found: Located | null = null;
|
||
for (const s of SKILL_SCOPE_ORDER) {
|
||
const dir = getSkillDirForScope(waggleHome, s, ctx);
|
||
if (!dir || !fs.existsSync(dir)) continue;
|
||
const filePath = path.join(dir, `${skillName}.md`);
|
||
if (fs.existsSync(filePath)) {
|
||
found = {
|
||
scope: s,
|
||
filePath,
|
||
content: fs.readFileSync(filePath, 'utf-8'),
|
||
};
|
||
break;
|
||
}
|
||
}
|
||
if (!found) {
|
||
return `Skill "${skillName}" not found in any accessible scope. Use list_skills to see what's installed.`;
|
||
}
|
||
|
||
// 2. Read current scope from frontmatter (falling back to the
|
||
// dir-derived scope if the frontmatter is missing — handles
|
||
// pre-gap-E legacy skills).
|
||
const parsed = parseSkillFrontmatter(found.content);
|
||
const currentScope: SkillScope = parsed.frontmatter.scope ?? found.scope;
|
||
|
||
// 3. Determine target scope + validate one-step rule
|
||
const target = explicitTarget ?? nextScope(currentScope);
|
||
if (!target) {
|
||
return `Skill "${skillName}" is already at the top scope (${currentScope}). Cannot promote further.`;
|
||
}
|
||
const expectedNext = nextScope(currentScope);
|
||
if (target !== expectedNext) {
|
||
return (
|
||
`Invalid promotion: skill "${skillName}" is at scope "${currentScope}" and can only be promoted to "${expectedNext}". `
|
||
+ `Requested target "${target}" is not exactly one rung up. Multi-step promotions must be done one at a time.`
|
||
);
|
||
}
|
||
|
||
// 4. Tier + context gating
|
||
if (target === 'workspace' && !workspaceId) {
|
||
return `Cannot promote to workspace scope: no active workspace. Switch to a workspace first.`;
|
||
}
|
||
if (target === 'team') {
|
||
if (!deps.hasTeamSkillLibrary?.()) {
|
||
return `Cannot promote to team scope: your plan does not include the team skill library. Upgrade to TEAMS or ENTERPRISE.`;
|
||
}
|
||
if (!teamId) {
|
||
return `Cannot promote to team scope: this workspace is not linked to a team.`;
|
||
}
|
||
}
|
||
if (target === 'enterprise' && !deps.isEnterprise?.()) {
|
||
return `Cannot promote to enterprise scope: requires ENTERPRISE tier. Contact sales for KVARK.`;
|
||
}
|
||
|
||
// 5. Resolve destination dir + path
|
||
const destDir = getSkillDirForScope(waggleHome, target, ctx);
|
||
if (!destDir) {
|
||
return `Cannot resolve destination directory for scope "${target}".`;
|
||
}
|
||
if (!fs.existsSync(destDir)) {
|
||
fs.mkdirSync(destDir, { recursive: true });
|
||
}
|
||
const destPath = path.join(destDir, `${skillName}.md`);
|
||
if (fs.existsSync(destPath)) {
|
||
return `Cannot promote: a skill named "${skillName}" already exists at scope "${target}". Rename one of them first.`;
|
||
}
|
||
|
||
// 6. Rewrite frontmatter: set new scope, append old to promoted_from
|
||
const updatedFrontmatter = {
|
||
...parsed.frontmatter,
|
||
scope: target,
|
||
promoted_from: [...(parsed.frontmatter.promoted_from ?? []), currentScope],
|
||
};
|
||
const newContent = redactSkillContent(serializeFrontmatter(updatedFrontmatter, parsed.body)).content;
|
||
|
||
// 7. Atomic-ish move: write to new location, then remove old.
|
||
// Writing first means a crash before the unlink leaves two copies,
|
||
// which is recoverable; a crash after the unlink but before the
|
||
// write would be catastrophic and is avoided by this ordering.
|
||
fs.writeFileSync(destPath, newContent, 'utf-8');
|
||
try {
|
||
fs.unlinkSync(found.filePath);
|
||
} catch {
|
||
// Non-fatal — leave a copy at the old location rather than
|
||
// failing the promotion. An audit warning is fine.
|
||
}
|
||
|
||
// 8. Record skill_promotion signal
|
||
if (deps.improvementSignals) {
|
||
try {
|
||
deps.improvementSignals.record(
|
||
'skill_promotion',
|
||
`promote:${skillName}:${currentScope}->${target}`,
|
||
`Promoted skill "${skillName}" from ${currentScope} to ${target}`,
|
||
{ skillName, from: currentScope, to: target, workspaceId, teamId },
|
||
);
|
||
} catch { /* non-blocking */ }
|
||
}
|
||
|
||
// 9. Let the agent reload its skill list so the new scope is picked up
|
||
onSkillsChanged?.();
|
||
|
||
return (
|
||
`## Skill Promoted\n\n`
|
||
+ `**${skillName}**: ${currentScope} → ${target}\n\n`
|
||
+ `- Moved from \`${found.filePath}\`\n`
|
||
+ `- Now at \`${destPath}\`\n`
|
||
+ `- Promotion history: ${updatedFrontmatter.promoted_from!.join(' → ')} → ${target}\n`
|
||
+ `- Signal recorded: skill_promotion\n\n`
|
||
+ `The skill is available immediately at the new scope. Agents in other `
|
||
+ `workspaces${target === 'team' ? ' on this team' : target === 'enterprise' ? ' across the enterprise' : ''} `
|
||
+ `will pick it up on their next skill reload.`
|
||
);
|
||
},
|
||
},
|
||
|
||
// Skills 2.0 gap A: auto_extract_skills — analyze the current session
|
||
// for a repeated workflow pattern and auto-create a personal-scope
|
||
// SKILL.md from it. Wires the previously-dormant
|
||
// detectWorkflowPattern → generateSkillMarkdown pipeline so the agent
|
||
// can learn from its own repetition without an explicit create_skill.
|
||
{
|
||
name: 'auto_extract_skills',
|
||
description:
|
||
'Scan the current session for repeated workflow patterns (the same 3+ tools '
|
||
+ 'used in the same order 2+ times) and auto-create a SKILL.md for any pattern '
|
||
+ 'found. Creates personal-scope skills only — promote_skill moves them up '
|
||
+ 'afterwards. Dedups by filename. Records a workflow_pattern signal on each '
|
||
+ 'successful extraction.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {},
|
||
},
|
||
execute: async () => {
|
||
if (!deps.getSessionMessages) {
|
||
return 'auto_extract_skills is unavailable: session-message accessor not wired. (This is a local-only feature.)';
|
||
}
|
||
const messages = deps.getSessionMessages();
|
||
if (!messages || messages.length < 6) {
|
||
return `Not enough session history yet (${messages?.length ?? 0} messages). Need at least 6 to detect a pattern.`;
|
||
}
|
||
const result = await autoExtractAndCreateSkill(messages, {
|
||
personalSkillsDir: skillsDir,
|
||
improvementSignals: deps.improvementSignals,
|
||
});
|
||
if (result.filePath) {
|
||
onSkillsChanged?.();
|
||
return (
|
||
`## Skill Auto-Extracted\n\n`
|
||
+ `- Name: **${result.template!.name}**\n`
|
||
+ `- Category: ${result.template!.category}\n`
|
||
+ `- Tools: ${result.template!.tools.join(', ')}\n`
|
||
+ `- Written to: \`${result.filePath}\`\n`
|
||
+ `- Scope: personal (use promote_skill to move it up)\n`
|
||
+ `- Signal: workflow_pattern recorded\n`
|
||
);
|
||
}
|
||
if (result.reason === 'already_exists') {
|
||
return `Pattern "${result.template!.name}" detected, but a skill with that filename already exists. Skipped.`;
|
||
}
|
||
return 'No repeatable workflow pattern detected in this session yet. Keep using the tools — the pattern needs at least 2 repetitions.';
|
||
},
|
||
},
|
||
|
||
// Skills 2.0 gap F: retire_skills — archive personal-scope skills
|
||
// that haven't been used in N days. Keeps the skill library from
|
||
// growing monotonically. Runs in dry-run by default so the agent can
|
||
// report the plan before any file moves.
|
||
{
|
||
name: 'retire_skills',
|
||
description:
|
||
'Archive personal-scope skills that have not been used within the idle window. '
|
||
+ 'Moves stale SKILL.md files to ~/.waggle/skills-archive/ (recoverable — no deletion). '
|
||
+ 'Default max_idle_days is 90. Default dry_run is true — call with dry_run: false to '
|
||
+ 'actually move the files. Records a workflow_pattern signal per retirement.',
|
||
parameters: {
|
||
type: 'object',
|
||
properties: {
|
||
max_idle_days: {
|
||
type: 'number',
|
||
description: 'Skills not used within this many days are retired. Default 90.',
|
||
},
|
||
dry_run: {
|
||
type: 'boolean',
|
||
description: 'When true (default), reports the plan without moving files.',
|
||
},
|
||
},
|
||
},
|
||
execute: async (args) => {
|
||
const maxIdleDays = typeof args.max_idle_days === 'number' ? args.max_idle_days : 90;
|
||
const dryRun = args.dry_run !== false; // default true
|
||
const report = retireStaleSkills(waggleHome, {
|
||
maxIdleDays,
|
||
dryRun,
|
||
improvementSignals: deps.improvementSignals,
|
||
});
|
||
if (!dryRun && report.retired.length > 0) {
|
||
onSkillsChanged?.();
|
||
}
|
||
const lines: string[] = [
|
||
`## Skill Retirement ${dryRun ? '(dry run)' : ''}`,
|
||
'',
|
||
`- Scanned: ${report.scanned}`,
|
||
`- Retired: ${report.retired.length}${report.retired.length > 0 ? ` — ${report.retired.join(', ')}` : ''}`,
|
||
`- Skipped fresh: ${report.skipped.filter(s => s.reason === 'fresh').length}`,
|
||
];
|
||
const errors = report.skipped.filter(s => s.reason !== 'fresh');
|
||
if (errors.length > 0) {
|
||
lines.push(`- Errors: ${errors.map(e => `${e.name}: ${e.reason}`).join('; ')}`);
|
||
}
|
||
if (dryRun && report.retired.length > 0) {
|
||
lines.push('', `Run again with \`dry_run: false\` to move ${report.retired.length} file${report.retired.length > 1 ? 's' : ''} to the archive.`);
|
||
}
|
||
if (!dryRun && report.archived.length > 0) {
|
||
lines.push('', `Archive dir: \`${report.archived[0].replace(/\\[^\\]+$/, '')}\``);
|
||
}
|
||
return lines.join('\n');
|
||
},
|
||
},
|
||
];
|
||
}
|