twining-mcp 1.3.0

package/dist/tools/decision-tools.js

@@ -0,0 +1,265 @@
+/**
+ * MCP tool handlers for decision operations.
+ * Registers twining_decide, twining_why, twining_commits, twining_trace, twining_reconsider, twining_override.
+ */
+import { z } from "zod";
+import { toolResult, toolError, TwiningError } from "../utils/errors.js";
+export function registerDecisionTools(server, engine) {
+    // twining_decide — Record a decision with full rationale
+    server.registerTool("twining_decide", {
+        description: "Record a decision with full rationale, alternatives considered, and traceability. Creates a decision record and cross-posts to the blackboard.",
+        inputSchema: {
+            domain: z
+                .string()
+                .describe('Decision domain (e.g., "architecture", "implementation", "testing")'),
+            scope: z
+                .string()
+                .describe("What part of the codebase this affects"),
+            summary: z.string().describe("One-line decision statement"),
+            context: z.string().describe("Situation that prompted this decision"),
+            rationale: z.string().describe("Reasoning for the choice"),
+            constraints: z
+                .array(z.string())
+                .optional()
+                .describe("What limited the options"),
+            alternatives: z
+                .array(z.object({
+                option: z.string().describe("Alternative option considered"),
+                pros: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Advantages of this alternative"),
+                cons: z
+                    .array(z.string())
+                    .optional()
+                    .describe("Disadvantages of this alternative"),
+                reason_rejected: z
+                    .string()
+                    .describe("Why this alternative was rejected"),
+            }))
+                .optional()
+                .describe("Alternatives that were considered"),
+            depends_on: z
+                .array(z.string())
+                .optional()
+                .describe("IDs of prerequisite decisions"),
+            supersedes: z
+                .string()
+                .optional()
+                .describe("ID of decision this replaces"),
+            confidence: z
+                .enum(["high", "medium", "low"])
+                .optional()
+                .describe('Confidence level (default: "medium")'),
+            reversible: z
+                .boolean()
+                .optional()
+                .describe("Whether this decision is easily reversible (default: true)"),
+            affected_files: z
+                .array(z.string())
+                .optional()
+                .describe("File paths affected by this decision"),
+            affected_symbols: z
+                .array(z.string())
+                .optional()
+                .describe("Function/class names affected"),
+            agent_id: z
+                .string()
+                .optional()
+                .describe('Identifier for the deciding agent (default: "main")'),
+            commit_hash: z
+                .string()
+                .optional()
+                .describe("Git commit hash to associate with this decision"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.decide(args);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_why — Retrieve decision chain for a scope or file
+    server.registerTool("twining_why", {
+        description: 'Retrieve all decisions affecting a given scope or file. Shows the decision chain with rationale, confidence, and alternatives count. Essential for understanding "why was it done this way?"',
+        inputSchema: {
+            scope: z
+                .string()
+                .describe("File path, module name, or symbol to query"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.why(args.scope);
+            return toolResult(result);
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_trace — Trace a decision's dependency chain
+    server.registerTool("twining_trace", {
+        description: "Trace a decision's dependency chain upstream (what it depends on) and/or downstream (what depends on it). Uses BFS with cycle protection.",
+        inputSchema: {
+            decision_id: z.string().describe("ID of the decision to trace"),
+            direction: z
+                .enum(["upstream", "downstream", "both"])
+                .optional()
+                .describe('Direction to trace (default: "both")'),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.trace(args.decision_id, args.direction);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_reconsider — Flag a decision for reconsideration
+    server.registerTool("twining_reconsider", {
+        description: "Flag a decision for reconsideration. Sets active decisions to provisional status and posts a warning to the blackboard with downstream impact analysis.",
+        inputSchema: {
+            decision_id: z.string().describe("ID of the decision to reconsider"),
+            new_context: z
+                .string()
+                .describe("New context or reason for reconsideration"),
+            agent_id: z
+                .string()
+                .optional()
+                .describe("ID of the agent requesting reconsideration"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.reconsider(args.decision_id, args.new_context, args.agent_id);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_override — Override a decision with a reason
+    server.registerTool("twining_override", {
+        description: "Override a decision with a reason. Sets the decision to overridden status, records who overrode it and why, and optionally creates a replacement decision automatically.",
+        inputSchema: {
+            decision_id: z.string().describe("ID of the decision to override"),
+            reason: z.string().describe("Reason for the override"),
+            new_decision: z
+                .string()
+                .optional()
+                .describe("Summary of the replacement decision to auto-create"),
+            overridden_by: z
+                .string()
+                .optional()
+                .describe('Who is overriding (default: "human")'),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.override(args.decision_id, args.reason, args.new_decision, args.overridden_by);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_commits — Query decisions by commit hash
+    server.registerTool("twining_commits", {
+        description: "Query decisions by commit hash. Returns all decisions that were linked to a given commit, enabling traceability from code changes back to decision rationale.",
+        inputSchema: {
+            commit_hash: z
+                .string()
+                .describe("Git commit hash to look up"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.getByCommitHash(args.commit_hash);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_search_decisions — Search decisions across all scopes
+    server.registerTool("twining_search_decisions", {
+        description: "Search decisions across all scopes by keyword or semantic similarity. Returns ranked results without requiring a specific scope. Supports filtering by domain, status, and confidence level.",
+        inputSchema: {
+            query: z
+                .string()
+                .describe("Search query — keywords or natural language description of what you're looking for"),
+            domain: z
+                .string()
+                .optional()
+                .describe("Filter by decision domain (e.g., 'architecture', 'implementation')"),
+            status: z
+                .enum(["active", "provisional", "superseded", "overridden"])
+                .optional()
+                .describe("Filter by decision status"),
+            confidence: z
+                .enum(["high", "medium", "low"])
+                .optional()
+                .describe("Filter by confidence level"),
+            limit: z
+                .number()
+                .optional()
+                .describe("Maximum results to return (default: 20)"),
+        },
+    }, async (args) => {
+        try {
+            const filters = {};
+            if (args.domain)
+                filters.domain = args.domain;
+            if (args.status)
+                filters.status = args.status;
+            if (args.confidence)
+                filters.confidence = args.confidence;
+            const result = await engine.searchDecisions(args.query, Object.keys(filters).length > 0 ? filters : undefined, args.limit);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_link_commit — Link a git commit hash to an existing decision
+    server.registerTool("twining_link_commit", {
+        description: "Link a git commit hash to an existing decision. Enables bidirectional traceability between decisions and commits.",
+        inputSchema: {
+            decision_id: z.string().describe("ID of the decision to link"),
+            commit_hash: z.string().describe("Git commit hash to link"),
+            agent_id: z
+                .string()
+                .optional()
+                .describe("ID of the agent performing the link"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.linkCommit(args.decision_id, args.commit_hash, args.agent_id);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+}
+//# sourceMappingURL=decision-tools.js.map

package/dist/tools/decision-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-tools.js","sourceRoot":"","sources":["../../src/tools/decision-tools.ts"],"names":[],"mappings":"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"}

package/dist/tools/export-tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Exporter } from "../engine/exporter.js";
+export declare function registerExportTools(server: McpServer, exporter: Exporter): void;
+//# sourceMappingURL=export-tools.d.ts.map

package/dist/tools/export-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-tools.d.ts","sourceRoot":"","sources":["../../src/tools/export-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAGtD,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,QAAQ,GACjB,IAAI,CA+BN"}

package/dist/tools/export-tools.js

@@ -0,0 +1,30 @@
+/**
+ * MCP tool handlers for export operations.
+ * Registers twining_export for full state snapshot as markdown.
+ */
+import { z } from "zod";
+import { toolResult, toolError, TwiningError } from "../utils/errors.js";
+export function registerExportTools(server, exporter) {
+    // twining_export — Export full Twining state as markdown
+    server.registerTool("twining_export", {
+        description: "Export full Twining state as a single markdown document. Includes blackboard entries, decisions with full rationale, and knowledge graph entities/relations. Use for handoff between context windows, documentation, or debugging.",
+        inputSchema: {
+            scope: z
+                .string()
+                .optional()
+                .describe("Optional scope filter to export only a subset of state (e.g., 'src/auth/'). If omitted, exports everything."),
+        },
+    }, async (args) => {
+        try {
+            const result = await exporter.exportMarkdown(args.scope);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+}
+//# sourceMappingURL=export-tools.js.map

package/dist/tools/export-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-tools.js","sourceRoot":"","sources":["../../src/tools/export-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,UAAU,mBAAmB,CACjC,MAAiB,EACjB,QAAkB;IAElB,yDAAyD;IACzD,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;QACE,WAAW,EACT,oOAAoO;QACtO,WAAW,EAAE;YACX,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CACP,6GAA6G,CAC9G;SACJ;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzD,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,SAAS,CACd,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAChD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/graph-tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { GraphEngine } from "../engine/graph.js";
+export declare function registerGraphTools(server: McpServer, engine: GraphEngine): void;
+//# sourceMappingURL=graph-tools.d.ts.map

package/dist/tools/graph-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-tools.d.ts","sourceRoot":"","sources":["../../src/tools/graph-tools.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAGtD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,EACjB,MAAM,EAAE,WAAW,GAClB,IAAI,CAkKN"}

package/dist/tools/graph-tools.js

@@ -0,0 +1,127 @@
+/**
+ * MCP tool handlers for knowledge graph operations.
+ * Registers twining_add_entity, twining_add_relation, twining_neighbors, twining_graph_query.
+ */
+import { z } from "zod";
+import { toolResult, toolError, TwiningError } from "../utils/errors.js";
+export function registerGraphTools(server, engine) {
+    // twining_add_entity — Add or update a knowledge graph entity
+    server.registerTool("twining_add_entity", {
+        description: "Add or update a knowledge graph entity. Uses upsert semantics: if an entity with the same name and type exists, its properties are merged and updated. Returns the entity ID.",
+        inputSchema: {
+            name: z.string().describe("Entity name (e.g., class name, file path, concept)"),
+            type: z
+                .string()
+                .describe('Entity type: "module", "function", "class", "file", "concept", "pattern", "dependency", "api_endpoint"'),
+            properties: z
+                .record(z.string())
+                .optional()
+                .describe("Key-value properties for this entity"),
+        },
+    }, async (args) => {
+        try {
+            const entity = await engine.addEntity({
+                name: args.name,
+                type: args.type,
+                properties: args.properties,
+            });
+            return toolResult({ id: entity.id });
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_add_relation — Add a relation between two entities
+    server.registerTool("twining_add_relation", {
+        description: "Add a relation between two knowledge graph entities. Source and target can be entity IDs or names. Returns an error for ambiguous name matches.",
+        inputSchema: {
+            source: z
+                .string()
+                .describe("Source entity ID or name"),
+            target: z
+                .string()
+                .describe("Target entity ID or name"),
+            type: z
+                .string()
+                .describe('Relation type: "depends_on", "implements", "decided_by", "affects", "tested_by", "calls", "imports", "related_to"'),
+            properties: z
+                .record(z.string())
+                .optional()
+                .describe("Key-value properties for this relation"),
+        },
+    }, async (args) => {
+        try {
+            const relation = await engine.addRelation({
+                source: args.source,
+                target: args.target,
+                type: args.type,
+                properties: args.properties,
+            });
+            return toolResult({ id: relation.id });
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_neighbors — Traverse neighbors from an entity
+    server.registerTool("twining_neighbors", {
+        description: "Traverse the knowledge graph from an entity, returning neighbors up to a given depth (max 3). Supports filtering by relation type. Useful for understanding how entities connect.",
+        inputSchema: {
+            entity: z
+                .string()
+                .describe("Entity ID or name to start traversal from"),
+            depth: z
+                .number()
+                .optional()
+                .describe("Traversal depth (1-3, default: 1)"),
+            relation_types: z
+                .array(z.string())
+                .optional()
+                .describe("Filter to only these relation types"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.neighbors(args.entity, args.depth, args.relation_types);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_graph_query — Search entities by substring
+    server.registerTool("twining_graph_query", {
+        description: "Search the knowledge graph for entities by name or property substring match. Case-insensitive. Returns matching entities with their properties.",
+        inputSchema: {
+            query: z.string().describe("Substring to search for in entity names and properties"),
+            entity_types: z
+                .array(z.string())
+                .optional()
+                .describe("Filter to only these entity types"),
+            limit: z
+                .number()
+                .optional()
+                .describe("Maximum results to return (default: 10)"),
+        },
+    }, async (args) => {
+        try {
+            const result = await engine.query(args.query, args.entity_types, args.limit);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+}
+//# sourceMappingURL=graph-tools.js.map

package/dist/tools/graph-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-tools.js","sourceRoot":"","sources":["../../src/tools/graph-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEzE,MAAM,UAAU,kBAAkB,CAChC,MAAiB,EACjB,MAAmB;IAEnB,8DAA8D;IAC9D,MAAM,CAAC,YAAY,CACjB,oBAAoB,EACpB;QACE,WAAW,EACT,+KAA+K;QACjL,WAAW,EAAE;YACX,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,oDAAoD,CAAC;YAC/E,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,wGAAwG,CACzG;YACH,UAAU,EAAE,CAAC;iBACV,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBAClB,QAAQ,EAAE;iBACV,QAAQ,CAAC,sCAAsC,CAAC;SACpD;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC;gBACpC,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,IAAI,EAAE,IAAI,CAAC,IAAsD;gBACjE,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC,CAAC;YACH,OAAO,UAAU,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC;QACvC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,SAAS,CACd,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAChD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,6DAA6D;IAC7D,MAAM,CAAC,YAAY,CACjB,sBAAsB,EACtB;QACE,WAAW,EACT,iJAAiJ;QACnJ,WAAW,EAAE;YACX,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CAAC,0BAA0B,CAAC;YACvC,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CAAC,0BAA0B,CAAC;YACvC,IAAI,EAAE,CAAC;iBACJ,MAAM,EAAE;iBACR,QAAQ,CACP,mHAAmH,CACpH;YACH,UAAU,EAAE,CAAC;iBACV,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBAClB,QAAQ,EAAE;iBACV,QAAQ,CAAC,wCAAwC,CAAC;SACtD;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,WAAW,CAAC;gBACxC,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,MAAM,EAAE,IAAI,CAAC,MAAM;gBACnB,IAAI,EAAE,IAAI,CAAC,IAAwD;gBACnE,UAAU,EAAE,IAAI,CAAC,UAAU;aAC5B,CAAC,CAAC;YACH,OAAO,UAAU,CAAC,EAAE,EAAE,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;QACzC,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,SAAS,CACd,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAChD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,wDAAwD;IACxD,MAAM,CAAC,YAAY,CACjB,mBAAmB,EACnB;QACE,WAAW,EACT,mLAAmL;QACrL,WAAW,EAAE;YACX,MAAM,EAAE,CAAC;iBACN,MAAM,EAAE;iBACR,QAAQ,CAAC,2CAA2C,CAAC;YACxD,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,mCAAmC,CAAC;YAChD,cAAc,EAAE,CAAC;iBACd,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,EAAE;iBACV,QAAQ,CAAC,qCAAqC,CAAC;SACnD;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CACnC,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,cAAc,CACpB,CAAC;YACF,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,SAAS,CACd,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAChD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;IAEF,qDAAqD;IACrD,MAAM,CAAC,YAAY,CACjB,qBAAqB,EACrB;QACE,WAAW,EACT,iJAAiJ;QACnJ,WAAW,EAAE;YACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,wDAAwD,CAAC;YACpF,YAAY,EAAE,CAAC;iBACZ,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;iBACjB,QAAQ,EAAE;iBACV,QAAQ,CAAC,mCAAmC,CAAC;YAChD,KAAK,EAAE,CAAC;iBACL,MAAM,EAAE;iBACR,QAAQ,EAAE;iBACV,QAAQ,CAAC,yCAAyC,CAAC;SACvD;KACF,EACD,KAAK,EAAE,IAAI,EAAE,EAAE;QACb,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,YAAY,EACjB,IAAI,CAAC,KAAK,CACX,CAAC;YACF,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,YAAY,EAAE,CAAC;gBAC9B,OAAO,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YACtC,CAAC;YACD,OAAO,SAAS,CACd,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,EAChD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/lifecycle-tools.d.ts

@@ -0,0 +1,9 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { BlackboardStore } from "../storage/blackboard-store.js";
+import { DecisionStore } from "../storage/decision-store.js";
+import type { GraphStore } from "../storage/graph-store.js";
+import type { AgentStore } from "../storage/agent-store.js";
+import type { Archiver } from "../engine/archiver.js";
+import type { TwiningConfig } from "../utils/types.js";
+export declare function registerLifecycleTools(server: McpServer, twiningDir: string, blackboardStore: BlackboardStore, decisionStore: DecisionStore, graphStore: GraphStore, archiver: Archiver, config: TwiningConfig, agentStore?: AgentStore | null): void;
+//# sourceMappingURL=lifecycle-tools.d.ts.map

package/dist/tools/lifecycle-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-tools.d.ts","sourceRoot":"","sources":["../../src/tools/lifecycle-tools.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AACjE,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOvD,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,SAAS,EACjB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,eAAe,EAChC,aAAa,EAAE,aAAa,EAC5B,UAAU,EAAE,UAAU,EACtB,QAAQ,EAAE,QAAQ,EAClB,MAAM,EAAE,aAAa,EACrB,UAAU,GAAE,UAAU,GAAG,IAAW,GACnC,IAAI,CAyLN"}

package/dist/tools/lifecycle-tools.js

@@ -0,0 +1,142 @@
+/**
+ * MCP tool handlers for lifecycle operations.
+ * Registers twining_status (enhanced with graph counts and warnings) and twining_archive.
+ */
+import path from "node:path";
+import { z } from "zod";
+import { BlackboardStore } from "../storage/blackboard-store.js";
+import { DecisionStore } from "../storage/decision-store.js";
+import { computeLiveness, DEFAULT_LIVENESS_THRESHOLDS, } from "../utils/liveness.js";
+import { toolResult, toolError, TwiningError } from "../utils/errors.js";
+export function registerLifecycleTools(server, twiningDir, blackboardStore, decisionStore, graphStore, archiver, config, agentStore = null) {
+    // twining_status — Overall health check of the Twining state
+    server.registerTool("twining_status", {
+        description: "Overall health check of the Twining state. Shows blackboard entry count, decision counts, graph entity/relation counts, actionable warnings, and a human-readable summary.",
+    }, async () => {
+        try {
+            // Get project name from parent directory
+            const projectRoot = path.dirname(twiningDir);
+            const project = path.basename(projectRoot);
+            // Count blackboard entries
+            const { total_count: blackboard_entries } = await blackboardStore.read();
+            // Count decisions by status
+            const index = await decisionStore.getIndex();
+            const active_decisions = index.filter((e) => e.status === "active").length;
+            const provisional_decisions = index.filter((e) => e.status === "provisional").length;
+            // Graph counts
+            const entities = await graphStore.getEntities();
+            const relations = await graphStore.getRelations();
+            const graph_entities = entities.length;
+            const graph_relations = relations.length;
+            // Find last activity timestamp
+            const recentEntries = await blackboardStore.recent(1);
+            const lastBBActivity = recentEntries.length > 0 ? recentEntries[0].timestamp : null;
+            const lastDecisionActivity = index.length > 0
+                ? index.reduce((latest, e) => e.timestamp > latest ? e.timestamp : latest, index[0].timestamp)
+                : null;
+            let last_activity = "none";
+            if (lastBBActivity && lastDecisionActivity) {
+                last_activity =
+                    lastBBActivity > lastDecisionActivity
+                        ? lastBBActivity
+                        : lastDecisionActivity;
+            }
+            else if (lastBBActivity) {
+                last_activity = lastBBActivity;
+            }
+            else if (lastDecisionActivity) {
+                last_activity = lastDecisionActivity;
+            }
+            // Archiving threshold
+            const archiveThreshold = config.archive.max_blackboard_entries_before_archive;
+            const needs_archiving = blackboard_entries >= archiveThreshold;
+            // Actionable warnings
+            const warnings = [];
+            // Stale provisionals: older than 7 days
+            const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString();
+            const staleProvisionals = index.filter((e) => e.status === "provisional" && e.timestamp < sevenDaysAgo);
+            if (staleProvisionals.length > 0) {
+                warnings.push(`${staleProvisionals.length} provisional decisions older than 7 days need resolution`);
+            }
+            // Archive needed
+            if (needs_archiving) {
+                warnings.push(`Blackboard has ${blackboard_entries} entries, archive recommended (threshold: ${archiveThreshold})`);
+            }
+            // Orphan entities: entities with zero relations
+            if (graph_entities > 0) {
+                const entityIds = new Set(entities.map((e) => e.id));
+                const connectedIds = new Set();
+                for (const r of relations) {
+                    connectedIds.add(r.source);
+                    connectedIds.add(r.target);
+                }
+                const orphanCount = [...entityIds].filter((id) => !connectedIds.has(id)).length;
+                if (orphanCount > 0) {
+                    warnings.push(`${orphanCount} graph entities have no relations`);
+                }
+            }
+            // Agent counts
+            let registered_agents = 0;
+            let active_agents = 0;
+            if (agentStore) {
+                const agents = await agentStore.getAll();
+                registered_agents = agents.length;
+                const thresholds = config.agents?.liveness ?? DEFAULT_LIVENESS_THRESHOLDS;
+                const now = new Date();
+                active_agents = agents.filter((a) => computeLiveness(a.last_active, now, thresholds) === "active").length;
+            }
+            // Build summary string
+            const healthStatus = warnings.length === 0 ? "Healthy" : "Needs attention";
+            const warningsSummary = warnings.length > 0 ? ` ${warnings.join(". ")}.` : "";
+            const agentSummary = ` ${registered_agents} registered agents (${active_agents} active).`;
+            const summary = `${healthStatus}. ${blackboard_entries} blackboard entries, ${active_decisions} active decisions, ${graph_entities} graph entities.${agentSummary}${warningsSummary}`;
+            return toolResult({
+                project,
+                blackboard_entries,
+                active_decisions,
+                provisional_decisions,
+                graph_entities,
+                graph_relations,
+                registered_agents,
+                active_agents,
+                last_activity,
+                needs_archiving,
+                warnings,
+                summary,
+            });
+        }
+        catch (e) {
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+    // twining_archive — Archive old blackboard entries
+    server.registerTool("twining_archive", {
+        description: "Archive old blackboard entries. Moves entries older than a cutoff timestamp to an archive file, preserving decision entries. Optionally posts a summary finding.",
+        inputSchema: {
+            before: z
+                .string()
+                .optional()
+                .describe("ISO timestamp cutoff — archive entries before this time (default: now)"),
+            keep_decisions: z
+                .boolean()
+                .optional()
+                .describe("Whether to keep decision entries in the blackboard (default: true)"),
+            summarize: z
+                .boolean()
+                .optional()
+                .describe("Whether to post a summary finding after archiving (default: true)"),
+        },
+    }, async (args) => {
+        try {
+            const result = await archiver.archive(args);
+            return toolResult(result);
+        }
+        catch (e) {
+            if (e instanceof TwiningError) {
+                return toolError(e.message, e.code);
+            }
+            return toolError(e instanceof Error ? e.message : "Unknown error", "INTERNAL_ERROR");
+        }
+    });
+}
+//# sourceMappingURL=lifecycle-tools.js.map

package/dist/tools/lifecycle-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-tools.js","sourceRoot":"","sources":["../../src/tools/lifecycle-tools.ts"],"names":[],"mappings":"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"}