agent-tempo 1.2.0 → 1.4.0

package/dist/spawn.js

@@ -12,6 +12,7 @@ exports.spawnCopilotBridge = spawnCopilotBridge;
 exports.spawnMockAdapter = spawnMockAdapter;
 exports.spawnClaudeApiAdapter = spawnClaudeApiAdapter;
 exports.spawnOpenCodeAdapter = spawnOpenCodeAdapter;
+exports.spawnPiHeadless = spawnPiHeadless;
 exports.spawnClaudeCodeHeadlessAdapter = spawnClaudeCodeHeadlessAdapter;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
@@ -262,12 +263,12 @@ function spawnInTerminal(claudeArgs, workDir, envVars, options) {
             // Append `; exit` so the wrapping shell exits when claude does (clean or killed).
             // Without it, claude exit returns control to the shell prompt and the tab lingers —
             // parity with the Windows WT `closeOnExit: 'always'` + parent-walk fix from #166.
-            const osaScript = `
-        tell application "Ghostty"
-          set cfg to new surface configuration
-          set initial working directory of cfg to ${JSON.stringify(workDir)}
-          set initial input of cfg to ${JSON.stringify(claudeInvocation + '; exit\n')}
-          set win to new window with configuration cfg
+            const osaScript = `
+        tell application "Ghostty"
+          set cfg to new surface configuration
+          set initial working directory of cfg to ${JSON.stringify(workDir)}
+          set initial input of cfg to ${JSON.stringify(claudeInvocation + '; exit\n')}
+          set win to new window with configuration cfg
         end tell`;
             log('Using Ghostty initial-input path');
             const child = (0, child_process_1.spawn)('osascript', ['-e', osaScript], {
@@ -285,12 +286,12 @@ function spawnInTerminal(claudeArgs, workDir, envVars, options) {
             // so any `"` or `\` in paths/args doesn't break the AppleScript parser. Parity with
             // the Ghostty path above.
             const shellCmd = `cd ${shellQuote(workDir)} && ${claudeInvocation} ; exit`;
-            const osaScript = `
-        tell application "iTerm2"
-          set newWindow to (create window with default profile)
-          tell current session of newWindow
-            write text ${JSON.stringify(shellCmd)}
-          end tell
+            const osaScript = `
+        tell application "iTerm2"
+          set newWindow to (create window with default profile)
+          tell current session of newWindow
+            write text ${JSON.stringify(shellCmd)}
+          end tell
         end tell`;
             log('Using iTerm2 write-text path');
             const child = (0, child_process_1.spawn)('osascript', ['-e', osaScript], {
@@ -671,6 +672,77 @@ function spawnOpenCodeAdapter(opts) {
     log(`Spawned opencode adapter (pid ${child.pid}) in ${opts.workDir} as "${opts.name}"${opts.model ? ` (model=${opts.model})` : ''}${opts.attachmentId ? ` (attachmentId=${opts.attachmentId})` : ''}`);
     return { pid: child.pid, logPath, pidPath };
 }
+/**
+ * Resolve the path to the Pi headless adapter entry point. Mirrors
+ * {@link resolveOpenCodePath} — dev (ts-node) + prod (compiled .js) both launch
+ * the same code through the same `require.main === module` gate.
+ */
+function resolvePiPath() {
+    const isDev = __filename.endsWith('.ts');
+    if (isDev) {
+        return { cmd: 'npx', args: ['ts-node', (0, path_1.resolve)(__dirname, 'adapters', 'pi', 'adapter.ts')] };
+    }
+    return { cmd: 'node', args: [(0, path_1.resolve)(__dirname, 'adapters', 'pi', 'adapter.js')] };
+}
+/**
+ * Spawn the headless Pi runtime as a detached subprocess. Pattern matches
+ * {@link spawnOpenCodeAdapter} — no TTY, log + PID files, env carries identity +
+ * Temporal settings + attachment handoff + the Pi model / continue-session /
+ * tool-access knobs. The entry constructs `createAgentSession` with the `src/pi`
+ * extension injected inline; the singleton claims + heartbeats + registers tools.
+ */
+function spawnPiHeadless(opts) {
+    const { cmd, args } = resolvePiPath();
+    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
+    const logName = opts.name || `pi-${Date.now()}`;
+    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
+    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
+    const logFd = (0, fs_1.openSync)(logPath, 'a');
+    const toolAccess = opts.toolAccess || 'restricted';
+    let child;
+    try {
+        child = (0, child_process_1.spawn)(cmd, args, {
+            cwd: opts.workDir,
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: {
+                ...process.env,
+                [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PLAYER_NAME]: opts.name,
+                [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
+                [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
+                ...(opts.temporalNamespace ? { [config_1.ENV.TEMPORAL_NAMESPACE]: opts.temporalNamespace } : {}),
+                ...(opts.temporalApiKey ? { [config_1.ENV.TEMPORAL_API_KEY]: opts.temporalApiKey } : {}),
+                ...(opts.temporalTlsCertPath ? { [config_1.ENV.TEMPORAL_TLS_CERT_PATH]: opts.temporalTlsCertPath } : {}),
+                ...(opts.temporalTlsKeyPath ? { [config_1.ENV.TEMPORAL_TLS_KEY_PATH]: opts.temporalTlsKeyPath } : {}),
+                // Model selection: recruit-arg → AGENT_TEMPO_PI_MODEL → Pi default.
+                ...(opts.model ? { [config_1.ENV.PI_MODEL]: opts.model } : {}),
+                // Restart-resume: continue the prior Pi conversation.
+                ...(opts.continueSessionId ? { [config_1.ENV.PI_CONTINUE_SESSION]: opts.continueSessionId } : {}),
+                // MD-C: tool-class policy. ALWAYS set (default 'restricted' — the safe
+                // unsupervised default + an explicit value for the gate + audit trail).
+                [config_1.ENV.TOOL_ACCESS]: toolAccess,
+                // 3c Tier-2: per-player ingest token (minted by the daemon outbox).
+                // Absent → the inner-loop publisher's HTTP client no-ops (no fine tail).
+                ...(opts.ingestToken ? { [config_1.ENV.INGEST_TOKEN]: opts.ingestToken } : {}),
+                // Attachment handoff — extension renews via claimAttachment(expectedAttachmentId).
+                ...(opts.attachmentId ? { [config_1.ENV.ATTACHMENT_ID]: opts.attachmentId } : {}),
+                ...(opts.attachmentRunId ? { [config_1.ENV.ATTACHMENT_RUN_ID]: opts.attachmentRunId } : {}),
+                ...(opts.adapterId ? { [config_1.ENV.ADAPTER_ID]: opts.adapterId } : {}),
+            },
+        });
+        child.unref();
+    }
+    finally {
+        (0, fs_1.closeSync)(logFd);
+    }
+    if (child.pid != null) {
+        (0, fs_1.writeFileSync)(pidPath, String(child.pid));
+    }
+    log(`Spawned pi headless adapter (pid ${child.pid}) in ${opts.workDir} as "${opts.name}" (toolAccess=${toolAccess})${opts.model ? ` (model=${opts.model})` : ''}${opts.continueSessionId ? ` (continue=${opts.continueSessionId})` : ''}${opts.attachmentId ? ` (attachmentId=${opts.attachmentId})` : ''}`);
+    return { pid: child.pid, logPath, pidPath };
+}
 /**
  * Resolve the path to the claude-code-headless adapter entry point.
  * Mirrors {@link resolveClaudeApiPath} so dev (ts-node) and prod

package/dist/tools/agent-types.d.ts

@@ -1,2 +1,2 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-export declare function registerAgentTypesTool(server: McpServer): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildAgentTypesTool(): TempoToolDescriptor;

package/dist/tools/agent-types.js

@@ -1,21 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerAgentTypesTool = registerAgentTypesTool;
-const helpers_1 = require("./helpers");
+exports.buildAgentTypesTool = buildAgentTypesTool;
+const descriptor_1 = require("./descriptor");
 const agent_types_1 = require("../ensemble/agent-types");
-function registerAgentTypesTool(server) {
-    (0, helpers_1.defineTool)(server, 'agent_types', 'List available player types (agent definitions) that can be used when recruiting', {}, async () => {
-        const types = (0, agent_types_1.listAgentTypes)();
-        if (types.length === 0) {
-            return (0, helpers_1.ok)('No agent types found.');
-        }
-        const lines = types.map(t => {
-            const src = t.source === 'shipped' ? '(shipped)' : t.source === 'user' ? '(user)' : '(project)';
-            const tools = t.allowedTools && t.allowedTools.length > 0
-                ? `\n  Allowed tools: ${t.allowedTools.join(', ')}`
-                : '';
-            return `**${t.name}** ${src}\n  ${t.description || 'No description'}${tools}`;
-        });
-        return (0, helpers_1.ok)(lines.join('\n\n'));
-    });
+function buildAgentTypesTool() {
+    return {
+        name: 'agent_types',
+        description: 'List available player types (agent definitions) that can be used when recruiting',
+        params: {},
+        handler: async () => {
+            const types = (0, agent_types_1.listAgentTypes)();
+            if (types.length === 0) {
+                return (0, descriptor_1.ok)('No agent types found.');
+            }
+            const lines = types.map(t => {
+                const src = t.source === 'shipped' ? '(shipped)' : t.source === 'user' ? '(user)' : '(project)';
+                const tools = t.allowedTools && t.allowedTools.length > 0
+                    ? `\n  Allowed tools: ${t.allowedTools.join(', ')}`
+                    : '';
+                return `**${t.name}** ${src}\n  ${t.description || 'No description'}${tools}`;
+            });
+            return (0, descriptor_1.ok)(lines.join('\n\n'));
+        },
+    };
 }

package/dist/tools/attachment-info.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from '@temporalio/client';
 import { Config } from '../config';
-export declare function registerAttachmentInfoTool(server: McpServer, client: Client, config: Config): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildAttachmentInfoTool(client: Client, config: Config): TempoToolDescriptor;

package/dist/tools/attachment-info.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerAttachmentInfoTool = registerAttachmentInfoTool;
+exports.buildAttachmentInfoTool = buildAttachmentInfoTool;
 /**
  * `attachment_info` — diagnostic query for the V2 attachment lifecycle (design §§2.2, 2.4).
  *
@@ -11,38 +11,43 @@ exports.registerAttachmentInfoTool = registerAttachmentInfoTool;
 const zod_1 = require("zod");
 const resolve_1 = require("./resolve");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
-function registerAttachmentInfoTool(server, client, config) {
-    (0, helpers_1.defineTool)(server, 'attachment_info', 'Query the V2 attachment lifecycle state of a session — phase (booting/attached/processing/awaiting/draining/detached/gone), current attachment holder (host + adapter + lease expiry), preferred host, and in-flight message count. Read-only diagnostic.', {
-        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to inspect'),
-    }, async (args) => {
-        const { playerId } = args;
-        const nameError = (0, validation_1.validatePlayerName)(playerId);
-        if (nameError)
-            return (0, helpers_1.fail)(nameError);
-        try {
-            const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
-            if (!resolved)
-                return (0, helpers_1.fail)(`No session found with name "${playerId}".`);
-            const info = await resolved.query(signals_1.attachmentInfoQuery);
-            const lines = [
-                `**${playerId}** — phase: \`${info.phase}\``,
-                `in-flight messages: ${info.inFlightCount}`,
-            ];
-            if (info.currentAttachment) {
-                const a = info.currentAttachment;
-                lines.push(`attached on: **${a.hostname}** (adapter: ${a.adapterId}/${a.adapterClass}, attachmentId: \`${a.attachmentId.slice(0, 8)}…\`)`);
-                lines.push(`lease expires: ${a.expiresAt}`);
+function buildAttachmentInfoTool(client, config) {
+    return {
+        name: 'attachment_info',
+        description: 'Query the V2 attachment lifecycle state of a session — phase (booting/attached/processing/awaiting/draining/detached/gone), current attachment holder (host + adapter + lease expiry), preferred host, and in-flight message count. Read-only diagnostic.',
+        params: {
+            playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to inspect'),
+        },
+        handler: async (args) => {
+            const { playerId } = args;
+            const nameError = (0, validation_1.validatePlayerName)(playerId);
+            if (nameError)
+                return (0, descriptor_1.fail)(nameError);
+            try {
+                const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
+                if (!resolved)
+                    return (0, descriptor_1.fail)(`No session found with name "${playerId}".`);
+                const info = await resolved.query(signals_1.attachmentInfoQuery);
+                const lines = [
+                    `**${playerId}** — phase: \`${info.phase}\``,
+                    `in-flight messages: ${info.inFlightCount}`,
+                ];
+                if (info.currentAttachment) {
+                    const a = info.currentAttachment;
+                    lines.push(`attached on: **${a.hostname}** (adapter: ${a.adapterId}/${a.adapterClass}, attachmentId: \`${a.attachmentId.slice(0, 8)}…\`)`);
+                    lines.push(`lease expires: ${a.expiresAt}`);
+                }
+                if (info.preferredHost)
+                    lines.push(`preferred host: ${info.preferredHost}`);
+                if (info.processingSince)
+                    lines.push(`processing since: ${info.processingSince}`);
+                return (0, descriptor_1.ok)(lines.join('\n'));
             }
-            if (info.preferredHost)
-                lines.push(`preferred host: ${info.preferredHost}`);
-            if (info.processingSince)
-                lines.push(`processing since: ${info.processingSince}`);
-            return (0, helpers_1.ok)(lines.join('\n'));
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to query attachment info: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to query attachment info: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/broadcast.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { Config } from '../config';
-export declare function registerBroadcastTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildBroadcastTool(client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): TempoToolDescriptor;

package/dist/tools/broadcast.js

@@ -1,76 +1,81 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerBroadcastTool = registerBroadcastTool;
+exports.buildBroadcastTool = buildBroadcastTool;
 const zod_1 = require("zod");
 const crypto_1 = require("crypto");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
 const search_attributes_1 = require("../utils/search-attributes");
-function registerBroadcastTool(server, client, config, getPlayerId, handle) {
-    (0, helpers_1.defineTool)(server, 'broadcast', 'Send a message to all active players in the ensemble. Optionally filter by player type.', {
-        message: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The message to broadcast'),
-        type: zod_1.z.string().optional().describe('Only send to players of this type (e.g., "tempo-soloist")'),
-        includeStale: zod_1.z.boolean().optional().describe('Include disconnected sessions (draining/detached phases; default: false). Argument name kept for backward compatibility.'),
-    }, async (args) => {
-        const { message, type: playerType, includeStale: rawIncludeStale } = args;
-        const includeDisconnected = rawIncludeStale === true;
-        try {
-            const query = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
-            const targets = [];
-            for await (const workflow of client.workflow.list({ query })) {
-                try {
-                    const wfHandle = client.workflow.getHandle(workflow.workflowId);
-                    const metadata = await wfHandle.query('getMetadata');
-                    // Filter by ensemble
-                    if (metadata.ensemble !== config.ensemble)
-                        continue;
-                    // Exclude sender
-                    if (metadata.playerId === getPlayerId())
-                        continue;
-                    // Filter by attachment phase (post-#176). Phase lives on the
-                    // `AgentTempoAttachmentState` search attribute.
-                    const phase = (0, search_attributes_1.getAttachmentPhase)(workflow);
-                    if (!(0, validation_1.shouldIncludeInBroadcast)(phase, includeDisconnected))
-                        continue;
-                    // Filter by player type if specified
-                    if (playerType && metadata.playerType !== playerType)
-                        continue;
-                    targets.push({
-                        playerId: metadata.playerId,
-                        playerType: metadata.playerType,
-                    });
+function buildBroadcastTool(client, config, getPlayerId, handle) {
+    return {
+        name: 'broadcast',
+        description: 'Send a message to all active players in the ensemble. Optionally filter by player type.',
+        params: {
+            message: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The message to broadcast'),
+            type: zod_1.z.string().optional().describe('Only send to players of this type (e.g., "tempo-soloist")'),
+            includeStale: zod_1.z.boolean().optional().describe('Include disconnected sessions (draining/detached phases; default: false). Argument name kept for backward compatibility.'),
+        },
+        handler: async (args) => {
+            const { message, type: playerType, includeStale: rawIncludeStale } = args;
+            const includeDisconnected = rawIncludeStale === true;
+            try {
+                const query = `WorkflowType = "agentSessionWorkflow" AND ExecutionStatus = "Running"`;
+                const targets = [];
+                for await (const workflow of client.workflow.list({ query })) {
+                    try {
+                        const wfHandle = client.workflow.getHandle(workflow.workflowId);
+                        const metadata = await wfHandle.query('getMetadata');
+                        // Filter by ensemble
+                        if (metadata.ensemble !== config.ensemble)
+                            continue;
+                        // Exclude sender
+                        if (metadata.playerId === getPlayerId())
+                            continue;
+                        // Filter by attachment phase (post-#176). Phase lives on the
+                        // `AgentTempoAttachmentState` search attribute.
+                        const phase = (0, search_attributes_1.getAttachmentPhase)(workflow);
+                        if (!(0, validation_1.shouldIncludeInBroadcast)(phase, includeDisconnected))
+                            continue;
+                        // Filter by player type if specified
+                        if (playerType && metadata.playerType !== playerType)
+                            continue;
+                        targets.push({
+                            playerId: metadata.playerId,
+                            playerType: metadata.playerType,
+                        });
+                    }
+                    catch {
+                        // Workflow may have just completed — skip it
+                    }
                 }
-                catch {
-                    // Workflow may have just completed — skip it
+                if (targets.length === 0) {
+                    return (0, descriptor_1.ok)('No active players matched the broadcast filter.');
                 }
+                // #357: stamp every fan-out cue with the same `broadcastId` so the
+                // TUI can fold the N deliveries into one chat row. Generated ONCE
+                // here in the MCP-tool process — not inside the workflow — so
+                // workflow determinism is preserved (the workflow only sees the id
+                // as an opaque string on `OutboxEntryInput`).
+                const broadcastId = (0, crypto_1.randomUUID)();
+                // Fan out cue outbox entries for each target.
+                const entryIds = [];
+                for (const target of targets) {
+                    const entry = {
+                        type: 'cue',
+                        targetPlayerId: target.playerId,
+                        message,
+                        broadcastId,
+                    };
+                    const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                    entryIds.push(entryId);
+                }
+                const names = targets.map((t) => t.playerId);
+                return (0, descriptor_1.ok)(`Broadcast sent to ${targets.length} player${targets.length === 1 ? '' : 's'}: ${names.join(', ')}`);
             }
-            if (targets.length === 0) {
-                return (0, helpers_1.ok)('No active players matched the broadcast filter.');
-            }
-            // #357: stamp every fan-out cue with the same `broadcastId` so the
-            // TUI can fold the N deliveries into one chat row. Generated ONCE
-            // here in the MCP-tool process — not inside the workflow — so
-            // workflow determinism is preserved (the workflow only sees the id
-            // as an opaque string on `OutboxEntryInput`).
-            const broadcastId = (0, crypto_1.randomUUID)();
-            // Fan out cue outbox entries for each target.
-            const entryIds = [];
-            for (const target of targets) {
-                const entry = {
-                    type: 'cue',
-                    targetPlayerId: target.playerId,
-                    message,
-                    broadcastId,
-                };
-                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
-                entryIds.push(entryId);
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to broadcast: ${(0, descriptor_1.formatError)(err)}`);
             }
-            const names = targets.map((t) => t.playerId);
-            return (0, helpers_1.ok)(`Broadcast sent to ${targets.length} player${targets.length === 1 ? '' : 's'}: ${names.join(', ')}`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to broadcast: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+        },
+    };
 }

package/dist/tools/cancel-stage.d.ts

@@ -1,3 +1,3 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkflowHandle } from '@temporalio/client';
-export declare function registerCancelStageTool(server: McpServer, handle: WorkflowHandle): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildCancelStageTool(handle: WorkflowHandle): TempoToolDescriptor;

package/dist/tools/cancel-stage.js

@@ -1,20 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerCancelStageTool = registerCancelStageTool;
+exports.buildCancelStageTool = buildCancelStageTool;
 const zod_1 = require("zod");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
-function registerCancelStageTool(server, handle) {
-    (0, helpers_1.defineTool)(server, 'cancel_stage', 'Cancel an active pipeline stage. Players are no longer tracked. Conductor only.', {
-        name: zod_1.z.string().max(validation_1.STAGE_NAME_MAX).describe('Name of the stage to cancel'),
-    }, async (args) => {
-        const { name } = args;
-        try {
-            await handle.signal('cancelStage', name);
-            return (0, helpers_1.ok)(`Stage **${name}** cancelled.`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to cancel stage: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+function buildCancelStageTool(handle) {
+    return {
+        name: 'cancel_stage',
+        description: 'Cancel an active pipeline stage. Players are no longer tracked. Conductor only.',
+        params: {
+            name: zod_1.z.string().max(validation_1.STAGE_NAME_MAX).describe('Name of the stage to cancel'),
+        },
+        handler: async (args) => {
+            const { name } = args;
+            try {
+                await handle.signal('cancelStage', name);
+                return (0, descriptor_1.ok)(`Stage **${name}** cancelled.`);
+            }
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to cancel stage: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/clear-state.d.ts

@@ -1,3 +1,3 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkflowHandle } from '@temporalio/client';
-export declare function registerClearStateTool(server: McpServer, handle: WorkflowHandle): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildClearStateTool(handle: WorkflowHandle): TempoToolDescriptor;

package/dist/tools/clear-state.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerClearStateTool = registerClearStateTool;
+exports.buildClearStateTool = buildClearStateTool;
 /**
  * `clear_state` — remove one of the calling player's saved-state slots
  * (#334 PR-1, ADR 0011).
@@ -14,24 +14,29 @@ exports.registerClearStateTool = registerClearStateTool;
  */
 const zod_1 = require("zod");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
-function registerClearStateTool(server, handle) {
-    (0, helpers_1.defineTool)(server, 'clear_state', `Clear one of your saved-state slots. Owner-only — you can only clear your own state. Idempotent (clearing an empty slot is a no-op). Returns whether the slot was non-empty before the clear.`, {
-        key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe(`Slot name (default "${validation_1.PLAYER_STATE_DEFAULT_KEY}").`),
-    }, async (args) => {
-        const { key } = args;
-        const slotKey = key ?? validation_1.PLAYER_STATE_DEFAULT_KEY;
-        try {
-            const result = await handle.executeUpdate(signals_1.clearPlayerStateUpdate, {
-                args: [{ key: slotKey }],
-            });
-            return (0, helpers_1.ok)(result.cleared
-                ? `Cleared slot **"${slotKey}"**.`
-                : `Slot **"${slotKey}"** was already empty.`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to clear state: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+function buildClearStateTool(handle) {
+    return {
+        name: 'clear_state',
+        description: `Clear one of your saved-state slots. Owner-only — you can only clear your own state. Idempotent (clearing an empty slot is a no-op). Returns whether the slot was non-empty before the clear.`,
+        params: {
+            key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe(`Slot name (default "${validation_1.PLAYER_STATE_DEFAULT_KEY}").`),
+        },
+        handler: async (args) => {
+            const { key } = args;
+            const slotKey = key ?? validation_1.PLAYER_STATE_DEFAULT_KEY;
+            try {
+                const result = await handle.executeUpdate(signals_1.clearPlayerStateUpdate, {
+                    args: [{ key: slotKey }],
+                });
+                return (0, descriptor_1.ok)(result.cleared
+                    ? `Cleared slot **"${slotKey}"**.`
+                    : `Slot **"${slotKey}"** was already empty.`);
+            }
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to clear state: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/coat-check-evict.d.ts

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from '@temporalio/client';
 import { Config } from '../config';
-export declare function registerCoatCheckEvictTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildCoatCheckEvictTool(client: Client, config: Config, getPlayerId: () => string): TempoToolDescriptor;

package/dist/tools/coat-check-evict.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerCoatCheckEvictTool = registerCoatCheckEvictTool;
+exports.buildCoatCheckEvictTool = buildCoatCheckEvictTool;
 /**
  * `coat_check_evict` — remove a coat-check entry (#318, ADR 0008) before
  * its TTL expires. Owner-or-conductor only: the workflow validator rejects
@@ -14,30 +14,35 @@ exports.registerCoatCheckEvictTool = registerCoatCheckEvictTool;
 const zod_1 = require("zod");
 const config_1 = require("../config");
 const maestro_signals_1 = require("../workflows/maestro-signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
-function registerCoatCheckEvictTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_evict', `Evict a coat-check entry (#318) before its TTL expires. Owner-or-conductor only — non-owners (and non-conductors) get a permission error.
-
-Use to free a slot when this ensemble is at the 20-entry cap and you want to make room. \`evicted: false\` means the ticket was already gone (TTL-expired or evicted by someone else).`, {
-        ticket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).describe(`The ticket id returned by an earlier \`coat_check_put\` (≤${validation_1.COAT_CHECK_TICKET_MAX} chars).`),
-    }, async (args) => {
-        const { ticket } = args;
-        const evictedBy = getPlayerId();
-        try {
-            const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
-            const result = await handle.executeUpdate(maestro_signals_1.coatCheckEvictUpdate, {
-                args: [{ ticket, evictedBy }],
-            });
-            if (!result.evicted) {
-                return (0, helpers_1.ok)(`Ticket **${ticket}** was already gone (no-op).`);
+function buildCoatCheckEvictTool(client, config, getPlayerId) {
+    return {
+        name: 'coat_check_evict',
+        description: `Evict a coat-check entry (#318) before its TTL expires. Owner-or-conductor only — non-owners (and non-conductors) get a permission error.
+
+Use to free a slot when this ensemble is at the 20-entry cap and you want to make room. \`evicted: false\` means the ticket was already gone (TTL-expired or evicted by someone else).`,
+        params: {
+            ticket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).describe(`The ticket id returned by an earlier \`coat_check_put\` (≤${validation_1.COAT_CHECK_TICKET_MAX} chars).`),
+        },
+        handler: async (args) => {
+            const { ticket } = args;
+            const evictedBy = getPlayerId();
+            try {
+                const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
+                const result = await handle.executeUpdate(maestro_signals_1.coatCheckEvictUpdate, {
+                    args: [{ ticket, evictedBy }],
+                });
+                if (!result.evicted) {
+                    return (0, descriptor_1.ok)(`Ticket **${ticket}** was already gone (no-op).`);
+                }
+                return (0, descriptor_1.ok)(`Evicted ticket **${ticket}**.`);
             }
-            return (0, helpers_1.ok)(`Evicted ticket **${ticket}**.`);
-        }
-        catch (err) {
-            // Surfaces `CoatCheckEvictPermissionDenied` ApplicationFailure with
-            // owner/conductor diagnostic from the workflow validator.
-            return (0, helpers_1.fail)(`Failed to evict ticket: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                // Surfaces `CoatCheckEvictPermissionDenied` ApplicationFailure with
+                // owner/conductor diagnostic from the workflow validator.
+                return (0, descriptor_1.fail)(`Failed to evict ticket: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }