Twining MCP Server

Instructions

Implementation Reference

• src/tools/coordination-tools.ts:226-311 (handler)

  The 'twining_handoff' tool handler logic in src/tools/coordination-tools.ts, which uses coordinationEngine.createHandoff and optionally graphPopulator.onHandoff.

  // twining_handoff — Create a handoff between agents
  server.registerTool(
    "twining_handoff",
    {
      description:
        "Create a handoff record from one agent to another, capturing work results and auto-assembling context snapshot. Posts a status entry to the blackboard.",
      inputSchema: {
        source_agent: z
          .string()
          .describe("ID of the agent handing off work"),
        target_agent: z
          .string()
          .optional()
          .describe("ID of the target agent (omit for open handoff to any agent)"),
        scope: z
          .string()
          .optional()
          .describe("Scope of the handoff (default: 'project')"),
        summary: z
          .string()
          .describe("Summary of work being handed off"),
        results: z
          .array(
            z.object({
              description: z.string().describe("What was done"),
              status: z
                .enum(["completed", "partial", "blocked", "failed"])
                .describe("Result status"),
              artifacts: z
                .array(z.string())
                .optional()
                .describe("File paths or artifact IDs produced"),
              notes: z
                .string()
                .optional()
                .describe("Additional notes"),
            }),
          )
          .describe("Results of the work being handed off"),
        auto_snapshot: z
          .boolean()
          .optional()
          .describe("Auto-assemble context snapshot from decisions/warnings (default: true)"),
      },
    },
    async (args) => {
      try {
        const record = await coordinationEngine.createHandoff({
          source_agent: args.source_agent,
          target_agent: args.target_agent,
          scope: args.scope,
          summary: args.summary,
          results: args.results,
          auto_snapshot: args.auto_snapshot,
        });
        // Auto-populate graph with handoff entities/relations
        if (graphPopulator) {
          await graphPopulator.onHandoff({
            source_agent: args.source_agent,
            target_agent: args.target_agent,
            scope: args.scope,
            results: args.results,
          });
        }
        return toolResult({
          id: record.id,
          created_at: record.created_at,
          source_agent: record.source_agent,
          target_agent: record.target_agent,
          scope: record.scope,
          summary: record.summary,
          result_count: record.results.length,
          context_snapshot_size: {
            decisions: record.context_snapshot.decision_ids.length,
            warnings: record.context_snapshot.warning_ids.length,
            findings: record.context_snapshot.finding_ids.length,
          },
        });
      } catch (e) {
        return toolError(
          e instanceof Error ? e.message : "Unknown error",
          "INTERNAL_ERROR",
        );
      }
    },
  );