agent-tempo 1.3.1 → 1.4.1

package/dist/server-tools.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAllTempoTools = buildAllTempoTools;
 exports.registerAllTempoTools = registerAllTempoTools;
 exports.buildServerInstructions = buildServerInstructions;
+const descriptor_1 = require("./tools/descriptor");
 const ensemble_1 = require("./tools/ensemble");
 const cue_1 = require("./tools/cue");
 const set_part_1 = require("./tools/set-part");
@@ -32,6 +34,7 @@ const stages_1 = require("./tools/stages");
 const cancel_stage_1 = require("./tools/cancel-stage");
 const restart_1 = require("./tools/restart");
 const destroy_1 = require("./tools/destroy");
+const reset_1 = require("./tools/reset");
 const migrate_1 = require("./tools/migrate");
 const attachment_info_1 = require("./tools/attachment-info");
 const hosts_1 = require("./tools/hosts");
@@ -55,55 +58,56 @@ const coat_check_evict_1 = require("./tools/coat-check-evict");
  * `opts.isConductor` — non-conductor players don't see them on either
  * surface.
  */
-function registerAllTempoTools(server, opts) {
+function buildAllTempoTools(opts) {
     const { client, config, getPlayerId, setPlayerId, handle, workflowId, ownAgentType, isConductor } = opts;
-    (0, ensemble_1.registerEnsembleTool)(server, client, config, getPlayerId, workflowId);
-    (0, cue_1.registerCueTool)(server, client, config, getPlayerId, handle);
-    (0, set_part_1.registerSetPartTool)(server, handle);
-    (0, set_name_1.registerSetNameTool)(server, client, config, handle, getPlayerId, setPlayerId);
-    (0, listen_1.registerListenTool)(server, handle);
-    (0, recruit_1.registerRecruitTool)(server, client, config, getPlayerId, handle, ownAgentType);
-    (0, report_1.registerReportTool)(server, handle);
-    (0, schedule_1.registerScheduleTool)(server, client, config, getPlayerId);
-    (0, unschedule_1.registerUnscheduleTool)(server, client, config);
-    (0, schedules_1.registerSchedulesTool)(server, client, config);
-    (0, save_lineup_1.registerSaveLineupTool)(server, client, config, getPlayerId, isConductor);
-    (0, load_lineup_1.registerLoadLineupTool)(server, client, config, getPlayerId, ownAgentType, handle, setPlayerId, isConductor);
-    (0, agent_types_1.registerAgentTypesTool)(server);
-    (0, who_am_i_1.registerWhoAmITool)(server, handle, getPlayerId);
-    (0, broadcast_1.registerBroadcastTool)(server, client, config, getPlayerId, handle);
-    (0, recall_1.registerRecallTool)(server, handle, getPlayerId);
-    (0, release_1.registerReleaseTool)(server, client, config, getPlayerId, handle);
-    (0, pause_1.registerPauseTool)(server, client, config, getPlayerId);
-    (0, play_1.registerPlayTool)(server, client, config, getPlayerId);
-    (0, shutdown_1.registerShutdownTool)(server, client, config, getPlayerId);
-    (0, restore_1.registerRestoreTool)(server, client, config, getPlayerId);
-    (0, restart_1.registerRestartTool)(server, client, config, getPlayerId, handle);
-    (0, destroy_1.registerDestroyTool)(server, client, config, getPlayerId, handle);
-    (0, migrate_1.registerMigrateTool)(server, client, config, getPlayerId, handle);
-    (0, attachment_info_1.registerAttachmentInfoTool)(server, client, config);
-    (0, hosts_1.registerHostsTool)(server, client, config);
-    (0, set_ensemble_description_1.registerSetEnsembleDescriptionTool)(server, client, config);
-    // #334 PR-1 — owner-write / peer-read player saveable state.
-    (0, save_state_1.registerSaveStateTool)(server, handle, getPlayerId);
-    (0, fetch_state_1.registerFetchStateTool)(server, client, config, handle, getPlayerId);
-    (0, clear_state_1.registerClearStateTool)(server, handle);
-    // #318 — ensemble-shared coat-check (put/get/list/evict). Any player can put;
-    // any player can get/list; owner-or-conductor can evict. Audit identity is
-    // set at the tool layer via getPlayerId() — no playerId arg on any schema.
-    (0, coat_check_put_1.registerCoatCheckPutTool)(server, client, config, getPlayerId);
-    (0, coat_check_get_1.registerCoatCheckGetTool)(server, client, config, getPlayerId);
-    (0, coat_check_list_1.registerCoatCheckListTool)(server, client, config);
-    (0, coat_check_evict_1.registerCoatCheckEvictTool)(server, client, config, getPlayerId);
+    const tools = [
+        (0, ensemble_1.buildEnsembleTool)(client, config, getPlayerId, workflowId),
+        (0, cue_1.buildCueTool)(client, config, getPlayerId, handle),
+        (0, set_part_1.buildSetPartTool)(handle),
+        (0, set_name_1.buildSetNameTool)(client, config, handle, getPlayerId, setPlayerId),
+        (0, listen_1.buildListenTool)(handle),
+        (0, recruit_1.buildRecruitTool)(client, config, getPlayerId, handle, ownAgentType),
+        (0, report_1.buildReportTool)(handle),
+        (0, schedule_1.buildScheduleTool)(client, config, getPlayerId),
+        (0, unschedule_1.buildUnscheduleTool)(client, config),
+        (0, schedules_1.buildSchedulesTool)(client, config),
+        (0, save_lineup_1.buildSaveLineupTool)(client, config, getPlayerId, isConductor),
+        (0, load_lineup_1.buildLoadLineupTool)(client, config, getPlayerId, ownAgentType, handle, setPlayerId, isConductor),
+        (0, agent_types_1.buildAgentTypesTool)(),
+        (0, who_am_i_1.buildWhoAmITool)(handle, getPlayerId),
+        (0, broadcast_1.buildBroadcastTool)(client, config, getPlayerId, handle),
+        (0, recall_1.buildRecallTool)(handle, getPlayerId),
+        (0, release_1.buildReleaseTool)(client, config, getPlayerId, handle),
+        (0, pause_1.buildPauseTool)(client, config, getPlayerId),
+        (0, play_1.buildPlayTool)(client, config, getPlayerId),
+        (0, shutdown_1.buildShutdownTool)(client, config, getPlayerId),
+        (0, restore_1.buildRestoreTool)(client, config, getPlayerId),
+        (0, restart_1.buildRestartTool)(client, config, getPlayerId, handle),
+        (0, destroy_1.buildDestroyTool)(client, config, getPlayerId, handle),
+        (0, reset_1.buildResetTool)(handle, getPlayerId),
+        (0, migrate_1.buildMigrateTool)(client, config, getPlayerId, handle),
+        (0, attachment_info_1.buildAttachmentInfoTool)(client, config),
+        (0, hosts_1.buildHostsTool)(client, config),
+        (0, set_ensemble_description_1.buildSetEnsembleDescriptionTool)(client, config),
+        // #334 PR-1 — owner-write / peer-read player saveable state.
+        (0, save_state_1.buildSaveStateTool)(handle, getPlayerId),
+        (0, fetch_state_1.buildFetchStateTool)(client, config, handle, getPlayerId),
+        (0, clear_state_1.buildClearStateTool)(handle),
+        // #318 — ensemble-shared coat-check (put/get/list/evict). Any player can put;
+        // any player can get/list; owner-or-conductor can evict. Audit identity is
+        // set at the tool layer via getPlayerId() — no playerId arg on any schema.
+        (0, coat_check_put_1.buildCoatCheckPutTool)(client, config, getPlayerId),
+        (0, coat_check_get_1.buildCoatCheckGetTool)(client, config, getPlayerId),
+        (0, coat_check_list_1.buildCoatCheckListTool)(client, config),
+        (0, coat_check_evict_1.buildCoatCheckEvictTool)(client, config, getPlayerId),
+    ];
     if (isConductor) {
-        (0, quality_gate_1.registerQualityGateTool)(server, handle, getPlayerId);
-        (0, evaluate_gate_1.registerEvaluateGateTool)(server, handle, getPlayerId);
-        (0, gates_1.registerGatesTool)(server, handle);
-        (0, worktree_1.registerWorktreeTool)(server, client, config, handle, getPlayerId);
-        (0, stage_1.registerStageTool)(server, handle, getPlayerId);
-        (0, stages_1.registerStagesTool)(server, handle);
-        (0, cancel_stage_1.registerCancelStageTool)(server, handle);
+        tools.push((0, quality_gate_1.buildQualityGateTool)(handle, getPlayerId), (0, evaluate_gate_1.buildEvaluateGateTool)(handle, getPlayerId), (0, gates_1.buildGatesTool)(handle), (0, worktree_1.buildWorktreeTool)(client, config, handle, getPlayerId), (0, stage_1.buildStageTool)(handle, getPlayerId), (0, stages_1.buildStagesTool)(handle), (0, cancel_stage_1.buildCancelStageTool)(handle));
     }
+    return tools;
+}
+function registerAllTempoTools(server, opts) {
+    (0, descriptor_1.renderToMcp)(server, buildAllTempoTools(opts));
 }
 /**
  * Build the `instructions` string that lands in `McpServer`'s `instructions`

package/dist/spawn.d.ts

@@ -236,6 +236,61 @@ export interface OpenCodeAdapterResult {
  * specific provider key since the model is opaque pass-through).
  */
 export declare function spawnOpenCodeAdapter(opts: OpenCodeAdapterOpts): OpenCodeAdapterResult;
+/**
+ * Options for {@link spawnPiHeadless}. Mirrors {@link OpenCodeAdapterOpts} for
+ * identity + Temporal connection + attachment handoff; adds Pi-specific knobs:
+ * `model` (provider/model via `AGENT_TEMPO_PI_MODEL`), `continueSessionId`
+ * (restart-resume via `AGENT_TEMPO_PI_CONTINUE_SESSION` → Pi `continueSession`),
+ * and `toolAccess` (MD-C tool-class policy via `AGENT_TEMPO_TOOL_ACCESS`).
+ *
+ * Unlike the other headless adapters, the Pi entry does NOT drive a
+ * `BaseAttachment` loop — it injects the `src/pi` extension into Pi's
+ * `createAgentSession`; the module-scope extension singleton owns the lifecycle.
+ */
+export interface PiHeadlessAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Pi provider/model selector (e.g. `anthropic/claude-opus-4-7`); absent → Pi default. */
+    model?: string;
+    /** Restart-resume: the Pi conversation id to continue (from `metadata.sessionId`). */
+    continueSessionId?: string;
+    /** MD-C tool-class policy: `restricted` (default) | `standard` | `full`. */
+    toolAccess?: string;
+    /**
+     * 3c Tier-2 ingest token (minted by the daemon outbox, scoped to this player's
+     * workflowId). Threaded into the subprocess env as `AGENT_TEMPO_INGEST_TOKEN`
+     * so the inner-loop publisher can authenticate `POST /inner/ingest`. NOTE:
+     * spawn.ts only THREADS the token — minting lives in the daemon-only outbox
+     * (this module runs outside the daemon and must not import the registry).
+     */
+    ingestToken?: string;
+    /** PR-D attachment-lease handoff (renew rather than fresh-claim on boot). */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface PiHeadlessAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * 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.
+ */
+export declare function spawnPiHeadless(opts: PiHeadlessAdapterOpts): PiHeadlessAdapterResult;
 /**
  * Options for {@link spawnClaudeCodeHeadlessAdapter}. Mirrors
  * {@link ClaudeApiAdapterOpts} for identity + Temporal connection +

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");
@@ -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;