@first-to-fly/orchestrator-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,1237 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tools = void 0;
+const TEXT_OUTPUT_SCHEMA = {
+    type: 'object',
+    properties: {
+        type: { const: 'text' },
+        text: { type: 'string' },
+    },
+};
+function textResult(text, isError = false) {
+    return { content: [{ type: 'text', text }], isError };
+}
+function smartTruncate(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    let cutPoint = text.lastIndexOf('\n', maxChars);
+    if (cutPoint < maxChars * 0.5)
+        cutPoint = maxChars;
+    let truncated = text.substring(0, cutPoint);
+    const fences = (truncated.match(/^```/gm) || []).length;
+    if (fences % 2 !== 0)
+        truncated += '\n```';
+    return truncated + `\n\n_(truncated to fit ${maxChars} char budget)_`;
+}
+function applyCharBudget(text, maxChars) {
+    if (!maxChars || text.length <= maxChars)
+        return text;
+    return smartTruncate(text, maxChars);
+}
+const ENTITY_TYPES_ENUM = ['module', 'decision', 'pattern', 'requirement', 'error', 'task', 'observation', 'session'];
+/**
+ * Build structured markdown content from base content + type-specific fields.
+ * Appends structured sections (## Rationale, ## Fix, etc.) to the base content.
+ */
+function buildStructuredContent(args) {
+    const sections = [args.content];
+    // Decision fields
+    if (args.rationale)
+        sections.push(`\n## Rationale\n${args.rationale}`);
+    if (args.alternatives?.length) {
+        sections.push(`\n## Alternatives Considered\n${args.alternatives.map((a) => `- ${a}`).join('\n')}`);
+    }
+    if (args.tradeoffs)
+        sections.push(`\n## Tradeoffs\n${args.tradeoffs}`);
+    // Error fields
+    if (args.root_cause)
+        sections.push(`\n## Root Cause\n${args.root_cause}`);
+    if (args.fix)
+        sections.push(`\n## Fix\n${args.fix}`);
+    if (args.file_path)
+        sections.push(`\n## File\n${args.file_path}`);
+    if (args.stack_trace)
+        sections.push(`\n## Stack Trace\n\`\`\`\n${args.stack_trace}\n\`\`\``);
+    // Pattern fields
+    if (args.example_files?.length) {
+        sections.push(`\n## Example Files\n${args.example_files.map((f) => `- ${f}`).join('\n')}`);
+    }
+    if (args.anti_pattern)
+        sections.push(`\n## Anti-Pattern\n${args.anti_pattern}`);
+    // Task fields
+    if (args.files_modified?.length) {
+        sections.push(`\n## Files Modified\n${args.files_modified.map((f) => `- ${f}`).join('\n')}`);
+    }
+    if (args.outcome)
+        sections.push(`\n## Outcome\n${args.outcome}`);
+    return sections.join('\n');
+}
+exports.tools = [
+    {
+        name: 'recall_context',
+        description: 'Recall relevant memory for a task. Returns summaries + last session + matching recipes. Use get_entity for full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                context: {
+                    type: 'string',
+                    description: 'Task description or context',
+                },
+                types: {
+                    type: 'array',
+                    items: { type: 'string', enum: ENTITY_TYPES_ENUM },
+                    description: 'Filter by types',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default: 10)',
+                },
+                pinnedEntityIds: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Entity IDs to always include regardless of score',
+                },
+                preview_chars: {
+                    type: 'number',
+                    description: 'Characters per entity preview (default: 200, max: 2000)',
+                },
+                max_chars: {
+                    type: 'number',
+                    description: 'Maximum output characters. Truncates output to fit context budget.',
+                },
+                scope: {
+                    type: 'string',
+                    description: 'Filter to entities relevant to a specific module/area (e.g., "payments", "pdf"). Modules and decisions always included.',
+                },
+            },
+            required: ['context'],
+        },
+        handler: async (client, args) => {
+            try {
+                const requestedLimit = args.limit || 10;
+                // Fetch recall, last session, and matching recipes in parallel
+                const [result, lastSession, recipes] = await Promise.all([
+                    client.recall(args.context, {
+                        types: args.types,
+                        limit: requestedLimit,
+                        mode: 'summary',
+                        pinnedEntityIds: args.pinnedEntityIds,
+                        previewChars: args.preview_chars,
+                        scope: args.scope,
+                    }),
+                    client.getLastSession().catch(() => null),
+                    client.matchRecipes(args.context).catch(() => []),
+                ]);
+                const lines = [];
+                // Prepend last session if available
+                if (lastSession) {
+                    lines.push('# Last Session\n');
+                    lines.push(lastSession.content);
+                    lines.push(`\n_Saved: ${lastSession.createdAt}_\n`);
+                }
+                if (result.entities.length === 0 && !lastSession) {
+                    return textResult('No relevant memory found for this context.');
+                }
+                if (result.entities.length > 0) {
+                    const totalAvailable = result.totalCount || result.entities.length;
+                    const truncated = totalAvailable > result.entities.length;
+                    lines.push('# Recalled Memory (summaries)\n');
+                    lines.push('_Use `get_entity(type, id)` to fetch full content._\n');
+                    const staleCount = result.entities.filter((e) => e.isStale).length;
+                    const previewLen = args.preview_chars || 200;
+                    // --- 6.3: Incremental budget — stop adding entities when budget is reached ---
+                    let charCount = lines.join('\n').length;
+                    const includedEntities = [];
+                    for (const entity of result.entities) {
+                        const staleFlag = entity.isStale ? ' **[STALE]**' : '';
+                        const preview = entity.summary || (entity.content?.length > previewLen ? entity.content.substring(0, previewLen - 3) + '...' : entity.content) || '';
+                        const entityLines = [`- **[${entity.type}] ${entity.name}**${staleFlag} (id: ${entity.id})`, `  ${preview}`];
+                        if (entity.tags?.length)
+                            entityLines.push(`  Tags: ${entity.tags.join(', ')}`);
+                        const entityText = entityLines.join('\n');
+                        if (args.max_chars && charCount + entityText.length + 1 > args.max_chars)
+                            break;
+                        lines.push(entityText);
+                        charCount += entityText.length + 1;
+                        includedEntities.push(entity);
+                    }
+                    if (staleCount > 0) {
+                        lines.push(`\n> **Warning**: ${staleCount} stale entit${staleCount === 1 ? 'y' : 'ies'} included (scores demoted). Use check_staleness for details.`);
+                    }
+                    if (truncated || includedEntities.length < result.entities.length) {
+                        lines.push(`\n_(showing ${includedEntities.length} of ${totalAvailable})_`);
+                    }
+                }
+                // --- 6.2 + 6.7: Relationship names using recalled + peripheral entities ---
+                if (result.relationships.length > 0) {
+                    const nameMap = new Map();
+                    for (const entity of result.entities) {
+                        nameMap.set(entity.id, { name: entity.name, type: entity.type });
+                    }
+                    if (result.peripheralEntities) {
+                        for (const pe of result.peripheralEntities) {
+                            nameMap.set(pe.id, { name: pe.name, type: pe.type });
+                        }
+                    }
+                    lines.push('\n## Relationships');
+                    for (const rel of result.relationships) {
+                        const from = nameMap.get(rel.fromEntityId);
+                        const to = nameMap.get(rel.toEntityId);
+                        const fromLabel = from ? `${from.name}` : rel.fromEntityId;
+                        const toLabel = to ? `${to.name}` : rel.toEntityId;
+                        lines.push(`- ${fromLabel} --${rel.type}--> ${toLabel}`);
+                    }
+                }
+                // Include matching recipes
+                if (recipes && recipes.length > 0) {
+                    lines.push('\n## Matching Recipes');
+                    lines.push('_Use `get_recipe(name)` to get a rendered recipe._\n');
+                    for (const recipe of recipes.slice(0, 3)) {
+                        lines.push(`- **${recipe.name}**: ${recipe.description || 'No description'}`);
+                    }
+                }
+                return textResult(applyCharBudget(lines.join('\n'), args.max_chars));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not recall context: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'search_memory',
+        description: 'Search memory by keyword. Returns summaries; use get_entity for full content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search keywords' },
+                types: {
+                    type: 'array',
+                    items: { type: 'string', enum: ENTITY_TYPES_ENUM },
+                    description: 'Filter by types',
+                },
+                limit: { type: 'number', description: 'Max results (default: 20)' },
+                mode: {
+                    type: 'string',
+                    enum: ['full', 'summary'],
+                    description: '"summary" (default) or "full"',
+                },
+                preview_chars: {
+                    type: 'number',
+                    description: 'Characters per entity preview (default: 200, max: 2000)',
+                },
+                max_chars: {
+                    type: 'number',
+                    description: 'Maximum output characters. Truncates output to fit context budget.',
+                },
+            },
+            required: ['query'],
+        },
+        handler: async (client, args) => {
+            try {
+                const requestedLimit = args.limit || 20;
+                const results = await client.search(args.query, {
+                    types: args.types,
+                    limit: requestedLimit,
+                    mode: args.mode || 'summary',
+                    previewChars: args.preview_chars,
+                });
+                if (!results || (Array.isArray(results) && results.length === 0)) {
+                    return textResult(`No results found for "${args.query}"`);
+                }
+                const items = Array.isArray(results) ? results : [];
+                const totalCount = results.totalCount || items.length;
+                const previewLen = args.preview_chars || 200;
+                const lines = items.map((e) => {
+                    const content = e.summary || (e.content?.length > previewLen ? e.content.substring(0, previewLen - 3) + '...' : e.content) || '';
+                    return `[${e.type}] **${e.name}** (id: ${e.id}): ${content}`;
+                });
+                if (totalCount > items.length) {
+                    lines.push(`\n_(truncated, showing ${items.length} of ${totalCount})_`);
+                }
+                return textResult(applyCharBudget(lines.join('\n\n'), args.max_chars));
+            }
+            catch (err) {
+                return textResult(`Warning: Search failed: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'list_recent',
+        description: 'List recent entities, optionally filtered by type.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: ENTITY_TYPES_ENUM,
+                    description: 'Filter by type',
+                },
+                limit: { type: 'number', description: 'Max results (default: 20)' },
+                max_chars: {
+                    type: 'number',
+                    description: 'Maximum output characters. Truncates output to fit context budget.',
+                },
+            },
+        },
+        handler: async (client, args) => {
+            try {
+                const requestedLimit = args.limit || 20;
+                const result = await client.listEntities({
+                    type: args.type,
+                    limit: requestedLimit,
+                });
+                const items = result?.items || [];
+                if (items.length === 0) {
+                    return textResult('No entities found.');
+                }
+                const lines = items.map((e) => `[${e.type}] **${e.name}** (${e.status}) - ${e.createdAt}`);
+                if (result?.cursor) {
+                    lines.push(`\n_(truncated, showing ${items.length} — more available, increase limit to see more)_`);
+                }
+                return textResult(applyCharBudget(lines.join('\n'), args.max_chars));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not list entities: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'get_entity',
+        description: 'Fetch full entity content by type and ID. Use after recall/search returns summaries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: {
+                    type: 'string',
+                    enum: ENTITY_TYPES_ENUM,
+                    description: 'Entity type',
+                },
+                id: { type: 'string', description: 'Entity ID' },
+            },
+            required: ['type', 'id'],
+        },
+        handler: async (client, args) => {
+            try {
+                const entity = await client.getEntity(args.type, args.id);
+                const MAX_CONTENT_LENGTH = 5000;
+                const content = entity.content || '';
+                const contentTruncated = content.length > MAX_CONTENT_LENGTH;
+                const displayContent = contentTruncated
+                    ? content.substring(0, MAX_CONTENT_LENGTH)
+                    : content;
+                const lines = [
+                    `## [${entity.type}] ${entity.name}`,
+                    '',
+                    displayContent,
+                ];
+                if (contentTruncated) {
+                    lines.push(`\n_(content truncated at ${MAX_CONTENT_LENGTH} chars, full length: ${content.length})_`);
+                }
+                lines.push('', `**Status**: ${entity.status}`, `**Tags**: ${entity.tags?.join(', ') || 'none'}`, `**Source**: ${entity.source || 'unknown'}`, `**Created**: ${entity.createdAt}`, `**Updated**: ${entity.updatedAt}`);
+                if (entity.version) {
+                    lines.push(`**Version**: ${entity.version}`);
+                }
+                if (entity.evidenceRefs?.length) {
+                    lines.push(`**Evidence**: ${entity.evidenceRefs.join(', ')}`);
+                }
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not fetch entity: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'store_entity',
+        description: 'Store a knowledge entity. Deduplicates by type+name. Supports type-specific structured fields.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Short name' },
+                type: {
+                    type: 'string',
+                    enum: ENTITY_TYPES_ENUM,
+                    description: 'Entity type',
+                },
+                content: { type: 'string', description: 'Detailed content' },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Tags',
+                },
+                evidenceRefs: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Evidence references (URLs, file paths, commit SHAs)',
+                },
+                // Decision-specific fields
+                alternatives: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Alternatives considered (for decisions)',
+                },
+                tradeoffs: { type: 'string', description: 'Tradeoffs analysis (for decisions)' },
+                rationale: { type: 'string', description: 'Decision rationale (for decisions)' },
+                // Error-specific fields
+                file_path: { type: 'string', description: 'File where error occurred (for errors)' },
+                root_cause: { type: 'string', description: 'Root cause analysis (for errors)' },
+                fix: { type: 'string', description: 'How the error was fixed (for errors)' },
+                stack_trace: { type: 'string', description: 'Stack trace (for errors)' },
+                // Pattern-specific fields
+                example_files: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Example files demonstrating the pattern (for patterns)',
+                },
+                anti_pattern: { type: 'string', description: 'What NOT to do (for patterns)' },
+                // Task-specific fields
+                files_modified: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Files modified (for tasks)',
+                },
+                outcome: { type: 'string', description: 'Task outcome (for tasks)' },
+            },
+            required: ['name', 'type', 'content'],
+        },
+        handler: async (client, args) => {
+            const entity = await client.createEntity({
+                name: args.name,
+                type: args.type,
+                content: buildStructuredContent(args),
+                tags: args.tags,
+                source: 'claude-code',
+                evidenceRefs: args.evidenceRefs,
+            });
+            const result = entity;
+            if (result.deduplicated) {
+                return textResult(`Updated existing entity: [${args.type}] ${args.name} (id: ${result.id}) — deduplicated`);
+            }
+            return textResult(`Stored entity: [${args.type}] ${args.name} (id: ${result.id})`);
+        },
+    },
+    {
+        name: 'store_entities',
+        description: 'Bulk store entities (max 50). Deduplicates by type+name. Supports type-specific structured fields.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                entities: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: { type: 'string', description: 'Short name' },
+                            type: {
+                                type: 'string',
+                                enum: ENTITY_TYPES_ENUM,
+                                description: 'Entity type',
+                            },
+                            content: { type: 'string', description: 'Detailed content' },
+                            tags: { type: 'array', items: { type: 'string' }, description: 'Tags (optional)' },
+                            evidenceRefs: { type: 'array', items: { type: 'string' }, description: 'Evidence references (optional)' },
+                            alternatives: { type: 'array', items: { type: 'string' }, description: 'Alternatives (decisions)' },
+                            tradeoffs: { type: 'string', description: 'Tradeoffs (decisions)' },
+                            rationale: { type: 'string', description: 'Rationale (decisions)' },
+                            file_path: { type: 'string', description: 'File path (errors)' },
+                            root_cause: { type: 'string', description: 'Root cause (errors)' },
+                            fix: { type: 'string', description: 'Fix description (errors)' },
+                            stack_trace: { type: 'string', description: 'Stack trace (errors)' },
+                            example_files: { type: 'array', items: { type: 'string' }, description: 'Example files (patterns)' },
+                            anti_pattern: { type: 'string', description: 'Anti-pattern (patterns)' },
+                            files_modified: { type: 'array', items: { type: 'string' }, description: 'Files modified (tasks)' },
+                            outcome: { type: 'string', description: 'Outcome (tasks)' },
+                        },
+                        required: ['name', 'type', 'content'],
+                    },
+                    description: 'Array of entities to store (max 50)',
+                },
+            },
+            required: ['entities'],
+        },
+        handler: async (client, args) => {
+            const result = await client.bulkCreateEntities(args.entities.map((e) => ({
+                name: e.name,
+                type: e.type,
+                content: buildStructuredContent(e),
+                tags: e.tags,
+                evidenceRefs: e.evidenceRefs,
+                source: 'claude-code',
+            })));
+            const items = result?.items || [];
+            const created = items.filter((i) => !i.deduplicated).length;
+            const deduped = items.filter((i) => i.deduplicated).length;
+            const lines = [`Stored ${items.length} entities (${created} new, ${deduped} deduplicated)`];
+            for (const item of items) {
+                const flag = item.deduplicated ? ' (deduplicated)' : '';
+                lines.push(`  - [${item.type}] ${item.name}${flag}`);
+            }
+            return textResult(lines.join('\n'));
+        },
+    },
+    {
+        name: 'update_entity',
+        description: 'Update an existing entity (name, content, tags, or status). Supports optimistic concurrency via expected_version.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', description: 'Entity type' },
+                id: { type: 'string', description: 'Entity ID' },
+                name: { type: 'string', description: 'New name' },
+                content: { type: 'string', description: 'New content' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'New tags' },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'superseded', 'resolved'],
+                    description: 'New status',
+                },
+                expected_version: {
+                    type: 'number',
+                    description: 'Expected version for optimistic concurrency. If provided and does not match, returns 409 Conflict.',
+                },
+            },
+            required: ['type', 'id'],
+        },
+        handler: async (client, args) => {
+            const updates = {};
+            if (args.name)
+                updates.name = args.name;
+            if (args.content)
+                updates.content = args.content;
+            if (args.tags)
+                updates.tags = args.tags;
+            if (args.status)
+                updates.status = args.status;
+            if (args.expected_version !== undefined)
+                updates.expectedVersion = args.expected_version;
+            const result = await client.updateEntity(args.type, args.id, updates);
+            const version = result?.version;
+            return textResult(`Updated entity ${args.id}${version ? ` (version: ${version})` : ''}`);
+        },
+    },
+    {
+        name: 'delete_entity',
+        description: 'Delete an entity by type and ID. Defaults to dry_run=true (preview without deleting). Set dry_run=false to request deletion (requires human approval). Pass approvalId after approval is granted.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                type: { type: 'string', description: 'Entity type' },
+                id: { type: 'string', description: 'Entity ID' },
+                dry_run: {
+                    type: 'boolean',
+                    description: 'Preview without deleting (default: true)',
+                },
+                approvalId: {
+                    type: 'string',
+                    description: 'Approval ID from a previously approved request. Required to complete deletion.',
+                },
+            },
+            required: ['type', 'id'],
+        },
+        handler: async (client, args) => {
+            const dryRun = args.dry_run !== false && !args.approvalId; // default true unless approvalId provided
+            if (dryRun) {
+                const result = await client.deleteEntity(args.type, args.id, { dryRun: true });
+                if (result?.entity) {
+                    const e = result.entity;
+                    return textResult(`**Dry run** — would delete:\n` +
+                        `[${e.type}] ${e.name} (id: ${e.id})\n` +
+                        `Content: ${e.content?.substring(0, 200) || ''}${e.content?.length > 200 ? '...' : ''}\n` +
+                        `Tags: ${e.tags?.join(', ') || 'none'}\n\n` +
+                        `Set dry_run=false to request deletion (requires human approval).`);
+                }
+                return textResult('Entity not found.');
+            }
+            const result = await client.deleteEntity(args.type, args.id, { approvalId: args.approvalId });
+            // Check if approval was required
+            if (result?.requiresApproval) {
+                return textResult(`**Approval required** to delete [${result.entity?.type}] ${result.entity?.name}\n` +
+                    `Approval ID: ${result.approvalId}\n\n` +
+                    `A human must approve this in the Orchestrator UI.\n` +
+                    `Use check_approval(id: "${result.approvalId}") to poll for a decision.\n` +
+                    `Once approved, call delete_entity(type: "${args.type}", id: "${args.id}", approvalId: "${result.approvalId}") to complete.`);
+            }
+            return textResult(`Deleted entity ${args.id}`);
+        },
+    },
+    {
+        name: 'store_relationship',
+        description: 'Link two entities with a typed relationship.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                fromEntityId: { type: 'string', description: 'Source entity ID' },
+                fromEntityType: { type: 'string', description: 'Source entity type' },
+                toEntityId: { type: 'string', description: 'Target entity ID' },
+                toEntityType: { type: 'string', description: 'Target entity type' },
+                type: {
+                    type: 'string',
+                    enum: ['depends_on', 'relates_to', 'supersedes', 'caused_by', 'part_of', 'implements'],
+                    description: 'Relationship type',
+                },
+            },
+            required: ['fromEntityId', 'fromEntityType', 'toEntityId', 'toEntityType', 'type'],
+        },
+        handler: async (client, args) => {
+            await client.createRelationship(args);
+            return textResult(`Created relationship: ${args.fromEntityId} --${args.type}--> ${args.toEntityId}`);
+        },
+    },
+    {
+        name: 'add_observation',
+        description: 'Quick shortcut to store an observation entity.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Short title' },
+                content: { type: 'string', description: 'Observation content' },
+                tags: { type: 'array', items: { type: 'string' }, description: 'Tags' },
+            },
+            required: ['name', 'content'],
+        },
+        handler: async (client, args) => {
+            const entity = await client.createEntity({
+                name: args.name,
+                type: 'observation',
+                content: args.content,
+                tags: args.tags,
+                source: 'claude-code',
+            });
+            const result = entity;
+            if (result.deduplicated) {
+                return textResult(`Updated existing observation: ${args.name} (id: ${result.id}) — deduplicated`);
+            }
+            return textResult(`Added observation: ${args.name} (id: ${result.id})`);
+        },
+    },
+    {
+        name: 'save_session_summary',
+        description: 'Save session handoff summary. Next session auto-receives this via recall_context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                summary: {
+                    type: 'string',
+                    description: 'What was accomplished and current state',
+                },
+                tasksCompleted: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Completed tasks',
+                },
+                tasksInProgress: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'In-progress tasks',
+                },
+                blockers: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Blockers',
+                },
+                filesModified: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Modified files',
+                },
+                decisionsMade: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Decisions made',
+                },
+                nextSteps: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Next steps',
+                },
+            },
+            required: ['summary'],
+        },
+        handler: async (client, args) => {
+            const result = await client.saveSession(args);
+            return textResult(`Session summary saved (id: ${result.id}). Next session will receive this via recall_context.`);
+        },
+    },
+    {
+        name: 'get_last_session',
+        description: 'Get the last session summary for cross-session continuity.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: async (client) => {
+            try {
+                const session = await client.getLastSession();
+                if (!session) {
+                    return textResult('No previous session found.');
+                }
+                const lines = [
+                    `# Last Session: ${session.name}`,
+                    `_Saved: ${session.createdAt}_\n`,
+                    session.content,
+                ];
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not retrieve last session: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'search_sessions',
+        description: 'Search across past session summaries by keyword. Find what was done in previous sessions.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search keywords' },
+                limit: { type: 'number', description: 'Max results (default: 5)' },
+                preview_chars: {
+                    type: 'number',
+                    description: 'Characters per session preview (default: 300)',
+                },
+                max_chars: {
+                    type: 'number',
+                    description: 'Maximum total output characters. Truncates output to fit context budget.',
+                },
+            },
+            required: ['query'],
+        },
+        handler: async (client, args) => {
+            try {
+                const results = await client.searchSessions(args.query, {
+                    limit: args.limit,
+                    previewChars: args.preview_chars,
+                });
+                if (!results || results.length === 0) {
+                    return textResult(`No sessions found matching "${args.query}"`);
+                }
+                const lines = [`# Session Search: "${args.query}" (${results.length} matches)\n`];
+                for (const session of results) {
+                    lines.push(`## ${session.name} (match: ${session.matchScore.toFixed(1)})`);
+                    lines.push(`_Created: ${session.createdAt}_\n`);
+                    lines.push(session.preview);
+                    lines.push('');
+                }
+                return textResult(applyCharBudget(lines.join('\n'), args.max_chars));
+            }
+            catch (err) {
+                return textResult(`Warning: Session search failed: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'check_error',
+        description: 'Check if a similar error was seen/resolved before. Call before debugging from scratch.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                errorMessage: {
+                    type: 'string',
+                    description: 'Error message to look up',
+                },
+                stackTrace: {
+                    type: 'string',
+                    description: 'Stack trace (improves matching)',
+                },
+                module: {
+                    type: 'string',
+                    description: 'Module where error occurred',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max results (default: 5)',
+                },
+            },
+            required: ['errorMessage'],
+        },
+        handler: async (client, args) => {
+            try {
+                const results = await client.checkError({
+                    errorMessage: args.errorMessage,
+                    stackTrace: args.stackTrace,
+                    module: args.module,
+                    limit: args.limit,
+                });
+                if (!results || results.length === 0) {
+                    return textResult('No matching past errors found. This appears to be a new error.');
+                }
+                const lines = ['# Matching Past Errors\n'];
+                for (const error of results) {
+                    const statusLabel = error.status === 'resolved' ? 'RESOLVED' : 'ACTIVE';
+                    lines.push(`## [${statusLabel}] ${error.name} (match: ${error.matchScore})`);
+                    // Parse and display structured sections prominently
+                    const content = error.content || '';
+                    const fixMatch = content.match(/## Fix\n([\s\S]*?)(?=\n## |\n*$)/);
+                    const rootCauseMatch = content.match(/## Root Cause\n([\s\S]*?)(?=\n## |\n*$)/);
+                    const fileMatch = content.match(/## File\n([\s\S]*?)(?=\n## |\n*$)/);
+                    if (fixMatch) {
+                        lines.push(`**Fix**: ${fixMatch[1].trim()}`);
+                    }
+                    if (rootCauseMatch) {
+                        lines.push(`**Root Cause**: ${rootCauseMatch[1].trim()}`);
+                    }
+                    if (fileMatch) {
+                        lines.push(`**File**: ${fileMatch[1].trim()}`);
+                    }
+                    // Show remaining content (without already-extracted sections)
+                    let remainingContent = content;
+                    if (fixMatch)
+                        remainingContent = remainingContent.replace(fixMatch[0], '');
+                    if (rootCauseMatch)
+                        remainingContent = remainingContent.replace(rootCauseMatch[0], '');
+                    if (fileMatch)
+                        remainingContent = remainingContent.replace(fileMatch[0], '');
+                    remainingContent = remainingContent.trim();
+                    if (remainingContent)
+                        lines.push(remainingContent);
+                    if (error.tags?.length)
+                        lines.push(`Tags: ${error.tags.join(', ')}`);
+                    if (error.status === 'resolved') {
+                        lines.push(`_Use resolve_error to update the fix if needed._`);
+                    }
+                    lines.push('');
+                }
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Warning: Error check failed: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'resolve_error',
+        description: 'Mark an error entity as resolved with a fix description. Completes the check→fix→resolve lifecycle.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Error entity ID' },
+                fix: { type: 'string', description: 'How the error was fixed' },
+                root_cause: { type: 'string', description: 'Root cause of the error' },
+            },
+            required: ['id', 'fix'],
+        },
+        handler: async (client, args) => {
+            try {
+                // Fetch current entity
+                const entity = await client.getEntity('error', args.id);
+                // Build updated content with fix/root_cause sections
+                let content = entity.content || '';
+                // Replace or append ## Fix section
+                const fixSection = `\n\n## Fix\n${args.fix}`;
+                if (content.includes('## Fix\n')) {
+                    content = content.replace(/## Fix\n[\s\S]*?(?=\n## |\n*$)/, `## Fix\n${args.fix}`);
+                }
+                else {
+                    content += fixSection;
+                }
+                // Replace or append ## Root Cause section
+                if (args.root_cause) {
+                    const rcSection = `\n\n## Root Cause\n${args.root_cause}`;
+                    if (content.includes('## Root Cause\n')) {
+                        content = content.replace(/## Root Cause\n[\s\S]*?(?=\n## |\n*$)/, `## Root Cause\n${args.root_cause}`);
+                    }
+                    else {
+                        content += rcSection;
+                    }
+                }
+                // Update entity: set content and status to resolved
+                await client.updateEntity('error', args.id, {
+                    content: content.trim(),
+                    status: 'resolved',
+                });
+                return textResult(`Error ${args.id} resolved with fix. Status set to resolved.`);
+            }
+            catch (err) {
+                return textResult(`Warning: Could not resolve error: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'prune_stale',
+        description: 'Remove stale entities that have never been accessed and are older than a threshold. Dry run by default — set confirm=true to delete. Protected types (session, decision, pattern) are never pruned.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                olderThanDays: {
+                    type: 'number',
+                    description: 'Age threshold in days (default: 90, min: 7, max: 365)',
+                },
+                confirm: {
+                    type: 'boolean',
+                    description: 'Set to true to actually delete (default: false = dry run)',
+                },
+            },
+        },
+        handler: async (client, args) => {
+            const result = await client.pruneStale({
+                olderThanDays: args.olderThanDays,
+                confirm: args.confirm,
+            });
+            if (result.dryRun) {
+                if (result.count === 0) {
+                    return textResult('No stale entities found.');
+                }
+                const lines = [`Found ${result.count} stale entities (dry run — set confirm=true to delete):\n`];
+                for (const item of result.candidates) {
+                    const connInfo = item.connections > 0 ? `, ${item.connections} connection(s)` : '';
+                    const multiplierInfo = item.typeMultiplier !== 1 ? ` (×${item.typeMultiplier})` : '';
+                    lines.push(`- [${item.type}] ${item.name}` +
+                        `\n  Age: ${item.ageDays}d, threshold: ${item.effectiveThreshold}d${multiplierInfo}${connInfo}` +
+                        `\n  Reason: ${item.reason}`);
+                }
+                return textResult(lines.join('\n'));
+            }
+            return textResult(`Pruned ${result.deletedCount} stale entities.`);
+        },
+    },
+    {
+        name: 'track_files',
+        description: 'Record file modifications for queryability across sessions. Stores as a tagged observation entity.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                files: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            path: { type: 'string', description: 'File path' },
+                            action: {
+                                type: 'string',
+                                enum: ['created', 'modified', 'deleted', 'renamed'],
+                                description: 'What was done to the file',
+                            },
+                            reason: { type: 'string', description: 'Why the file was changed' },
+                        },
+                        required: ['path', 'action'],
+                    },
+                    description: 'Files that were changed',
+                },
+                context: { type: 'string', description: 'Brief context for the changes (e.g., task name or feature)' },
+                relatedEntityId: { type: 'string', description: 'Link to a related task/error entity via relationship' },
+                relatedEntityType: { type: 'string', description: 'Type of the related entity' },
+            },
+            required: ['files', 'context'],
+        },
+        handler: async (client, args) => {
+            // Build structured markdown content
+            const lines = [`File changes for: ${args.context}\n`];
+            for (const file of args.files) {
+                const reason = file.reason ? ` — ${file.reason}` : '';
+                lines.push(`- **${file.action}**: \`${file.path}\`${reason}`);
+            }
+            // Build tags: file-tracking + file:{filename} + module scope for each file
+            const tags = ['file-tracking'];
+            for (const file of args.files) {
+                const parts = file.path.split('/');
+                const filename = parts.pop() || file.path;
+                tags.push(`file:${filename}`);
+                const moduleIdx = parts.indexOf('modules');
+                if (moduleIdx >= 0 && parts[moduleIdx + 1]) {
+                    tags.push(parts[moduleIdx + 1]);
+                }
+            }
+            const entity = await client.createEntity({
+                name: `File changes: ${args.context}`,
+                type: 'observation',
+                content: lines.join('\n'),
+                tags,
+                source: 'claude-code',
+            });
+            // Create relationship to related entity if specified
+            if (args.relatedEntityId && args.relatedEntityType) {
+                await client.createRelationship({
+                    fromEntityId: entity.id,
+                    fromEntityType: 'observation',
+                    toEntityId: args.relatedEntityId,
+                    toEntityType: args.relatedEntityType,
+                    type: 'relates_to',
+                }).catch(() => { }); // fire-and-forget
+            }
+            const action = entity.deduplicated ? 'Updated' : 'Tracked';
+            return textResult(`${action} ${args.files.length} file change(s) for "${args.context}" (id: ${entity.id})`);
+        },
+    },
+    {
+        name: 'check_staleness',
+        description: 'List all stale entities that are past their type\'s staleness window. Helps identify outdated knowledge that may need updating or removal.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: async (client) => {
+            try {
+                const staleEntities = await client.checkStaleness();
+                if (!staleEntities || staleEntities.length === 0) {
+                    return textResult('No stale entities found. All knowledge is within freshness windows.');
+                }
+                const lines = [`# Stale Entities (${staleEntities.length} found)\n`];
+                lines.push('_Entities past their type\'s staleness window. Consider updating or removing._\n');
+                for (const entity of staleEntities) {
+                    const overdue = entity.daysSinceActive - entity.staleAfterDays;
+                    lines.push(`- **[${entity.type}] ${entity.name}** (id: ${entity.id})` +
+                        `\n  ${entity.daysSinceActive}d since active (threshold: ${entity.staleAfterDays}d, overdue by ${overdue}d)` +
+                        `\n  Status: ${entity.status} | Last active: ${entity.lastActive}`);
+                }
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not check staleness: ${err.message}`);
+            }
+        },
+    },
+    // --- Recipes ---
+    {
+        name: 'get_recipe',
+        description: 'Get a rendered recipe by name. Recipes are reusable prompt templates with entity references.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Recipe name' },
+                variables: {
+                    type: 'object',
+                    description: 'Variables to substitute (key-value pairs for {{$VARIABLE}} placeholders)',
+                },
+            },
+            required: ['name'],
+        },
+        handler: async (client, args) => {
+            try {
+                const recipe = await client.getRecipeByName(args.name);
+                if (!recipe) {
+                    return textResult(`Recipe "${args.name}" not found. Use list_recipes to see available recipes.`);
+                }
+                const { rendered } = await client.renderRecipe(recipe.id, args.variables);
+                return textResult(`# Recipe: ${recipe.name}\n\n${rendered}`);
+            }
+            catch (err) {
+                return textResult(`Warning: Could not get recipe: ${err.message}`);
+            }
+        },
+    },
+    {
+        name: 'list_recipes',
+        description: 'List available recipes (reusable prompt templates).',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: async (client) => {
+            try {
+                const recipes = await client.listRecipes();
+                if (!recipes || recipes.length === 0) {
+                    return textResult('No recipes found.');
+                }
+                const lines = ['# Available Recipes\n'];
+                for (const recipe of recipes) {
+                    lines.push(`- **${recipe.name}**: ${recipe.description || 'No description'}`);
+                    if (recipe.triggers?.length)
+                        lines.push(`  Triggers: ${recipe.triggers.join(', ')}`);
+                    if (recipe.variables?.length)
+                        lines.push(`  Variables: ${recipe.variables.map((v) => `{{$${v}}}`).join(', ')}`);
+                }
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Warning: Could not list recipes: ${err.message}`);
+            }
+        },
+    },
+    // --- Work Queue ---
+    {
+        name: 'claim_next_task',
+        description: 'Claim the highest-priority unclaimed work item from the queue. Returns the task with its context and a claimToken for completing/failing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                agentId: {
+                    type: 'string',
+                    description: 'Identifier for this agent (default: session ID)',
+                },
+            },
+        },
+        handler: async (client, args) => {
+            try {
+                const task = await client.claimNextTask(args.agentId || 'claude-code');
+                if (!task) {
+                    return textResult('No work items available in the queue.');
+                }
+                const lines = [
+                    `# Claimed Task: ${task.title}`,
+                    `**ID**: ${task.id}`,
+                    `**Priority**: ${task.priority}/5`,
+                    `**Claim Token**: ${task.claimToken}`,
+                    `**Lease Expires**: ${task.leaseExpiresAt}`,
+                    `**Retry**: ${task.retryCount}/${task.maxRetries}`,
+                    '',
+                    task.description,
+                ];
+                if (task.entityRefs?.length) {
+                    lines.push('', '**Context entities**: ' + task.entityRefs.join(', '));
+                }
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Error: Could not claim task: ${err.message}`, true);
+            }
+        },
+    },
+    {
+        name: 'complete_task',
+        description: 'Mark a claimed work item as completed with a result summary and optional validation artifacts.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Work item ID' },
+                resultSummary: { type: 'string', description: 'Summary of what was accomplished' },
+                claimToken: { type: 'string', description: 'Claim token received when claiming the task' },
+                artifacts: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            type: {
+                                type: 'string',
+                                enum: ['test_result', 'diff', 'log', 'url'],
+                                description: 'Artifact type',
+                            },
+                            value: { type: 'string', description: 'Artifact content or reference' },
+                        },
+                        required: ['type', 'value'],
+                    },
+                    description: 'Validation artifacts providing evidence of correctness',
+                },
+            },
+            required: ['id', 'resultSummary'],
+        },
+        handler: async (client, args) => {
+            await client.completeTask(args.id, args.resultSummary, args.claimToken, args.artifacts);
+            const artifactNote = args.artifacts?.length ? ` with ${args.artifacts.length} artifact(s)` : '';
+            return textResult(`Task ${args.id} marked as completed${artifactNote}.`);
+        },
+    },
+    {
+        name: 'fail_task',
+        description: 'Mark a claimed work item as failed with error details. If under maxRetries, it will be requeued automatically.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Work item ID' },
+                errorDetails: { type: 'string', description: 'Description of what went wrong' },
+                claimToken: { type: 'string', description: 'Claim token received when claiming the task' },
+            },
+            required: ['id', 'errorDetails'],
+        },
+        handler: async (client, args) => {
+            const result = await client.failTask(args.id, args.errorDetails, args.claimToken);
+            if (result?.status === 'queued') {
+                return textResult(`Task ${args.id} requeued for retry (attempt ${result.retryCount}/${result.maxRetries}).`);
+            }
+            return textResult(`Task ${args.id} marked as failed.`);
+        },
+    },
+    // --- Approvals ---
+    {
+        name: 'request_approval',
+        description: 'Request human approval for a destructive or risky action. Returns an approval ID to poll with check_approval.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                scope: {
+                    type: 'string',
+                    enum: ['delete_entity', 'prune_stale', 'bulk_delete'],
+                    description: 'Type of action requiring approval',
+                },
+                riskLevel: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high'],
+                    description: 'Risk level (default: medium)',
+                },
+                context: {
+                    type: 'object',
+                    description: 'Context about the action (entityId, entityType, entityName, details)',
+                },
+            },
+            required: ['scope'],
+        },
+        handler: async (client, args) => {
+            try {
+                const approval = await client.requestApproval({
+                    scope: args.scope,
+                    riskLevel: args.riskLevel,
+                    context: args.context,
+                });
+                return textResult(`Approval requested (id: ${approval.id}).\n` +
+                    `Status: ${approval.status}\n` +
+                    `Expires: ${approval.expiresAt}\n\n` +
+                    `Use check_approval(id: "${approval.id}") to poll for a decision.`);
+            }
+            catch (err) {
+                return textResult(`Error: Could not request approval: ${err.message}`, true);
+            }
+        },
+    },
+    {
+        name: 'check_approval',
+        description: 'Check the status of a pending approval request.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string', description: 'Approval ID' },
+            },
+            required: ['id'],
+        },
+        handler: async (client, args) => {
+            try {
+                const approval = await client.checkApproval(args.id);
+                const lines = [
+                    `**Approval ${approval.id}**`,
+                    `Status: ${approval.status}`,
+                    `Scope: ${approval.scope}`,
+                    `Risk: ${approval.riskLevel}`,
+                ];
+                if (approval.approver)
+                    lines.push(`Approved by: ${approval.approver}`);
+                if (approval.decisionReason)
+                    lines.push(`Reason: ${approval.decisionReason}`);
+                if (approval.decidedAt)
+                    lines.push(`Decided: ${approval.decidedAt}`);
+                if (approval.status === 'pending')
+                    lines.push(`Expires: ${approval.expiresAt}`);
+                return textResult(lines.join('\n'));
+            }
+            catch (err) {
+                return textResult(`Error: Could not check approval: ${err.message}`, true);
+            }
+        },
+    },
+    // --- Cost ---
+    {
+        name: 'report_session_cost',
+        description: 'Report token usage and cost for the current session. Call at session end.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                inputTokens: { type: 'number', description: 'Input tokens consumed' },
+                outputTokens: { type: 'number', description: 'Output tokens consumed' },
+                cacheReadTokens: { type: 'number', description: 'Cache read tokens (optional)' },
+                estimatedCost: { type: 'number', description: 'Estimated cost in USD' },
+                model: { type: 'string', description: 'Model used (e.g., claude-sonnet-4-20250514)' },
+                durationMinutes: { type: 'number', description: 'Session duration in minutes' },
+            },
+            required: ['inputTokens', 'outputTokens', 'estimatedCost', 'model'],
+        },
+        handler: async (client, args) => {
+            await client.reportSessionCost({
+                inputTokens: args.inputTokens,
+                outputTokens: args.outputTokens,
+                cacheReadTokens: args.cacheReadTokens || 0,
+                estimatedCost: args.estimatedCost,
+                model: args.model,
+                durationMinutes: args.durationMinutes || 0,
+            });
+            return textResult(`Session cost recorded: $${args.estimatedCost.toFixed(4)} (${args.inputTokens + args.outputTokens} tokens)`);
+        },
+    },
+];
+//# sourceMappingURL=tools.js.map