agent-tempo 1.3.1 → 1.4.1

package/dist/tools/cue.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.formatDetachedDeliveryError = formatDetachedDeliveryError;
-exports.registerCueTool = registerCueTool;
+exports.buildCueTool = buildCueTool;
 exports.formatUnknownPlayerError = formatUnknownPlayerError;
 exports.findClosestPlayers = findClosestPlayers;
 exports.levenshtein = levenshtein;
@@ -10,7 +10,7 @@ const resolve_1 = require("./resolve");
 const resolve_2 = require("../activities/resolve");
 const signals_1 = require("../workflows/signals");
 const query_timeout_1 = require("../utils/query-timeout");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
 /**
  * Max Levenshtein distance for a fuzzy-match candidate to surface in the
@@ -55,60 +55,65 @@ function formatDetachedDeliveryError(playerId, phase) {
         `(2) 'restart' to re-attach the session and retry the cue, ` +
         `(3) the workflow inbox queues the signal and auto-delivers on re-attach.`);
 }
-function registerCueTool(server, client, config, getPlayerId, handle) {
-    (0, helpers_1.defineTool)(server, 'cue', 'Send a message to another Claude Code session by player name. Delivered instantly via Temporal signal. For content larger than ~100 KB, use `coat_check_put` to stash the body and pass the returned ticket via `attachmentTicket` — the cue body itself should carry a short summary the recipient can act on without fetching.', {
-        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name of the target session'),
-        message: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The message to send'),
-        attachmentTicket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).optional().describe('Optional coat-check ticket (#318). Reference content stashed via `coat_check_put`; the receiver sees the ticket on their `recall` message and can pull the body via `coat_check_get`. Backward-compatible — omit for normal cues.'),
-    }, async (args) => {
-        const { playerId, message, attachmentTicket } = 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) {
-                // #560: replace the generic "no active session found" with an
-                // actionable error — active-player list + fuzzy-match suggestion
-                // + Agent-tool surface hint. We pay the extra `scanEnsembleSessions`
-                // round-trip ONLY on the error path, so the success path is
-                // unchanged.
-                const sessions = await (0, resolve_2.scanEnsembleSessions)(client, config.ensemble);
-                const activePlayers = sessions.map((s) => s.playerId).sort();
-                return (0, helpers_1.fail)(formatUnknownPlayerError(playerId, activePlayers));
-            }
-            // #562: phase pre-flight. Resolves the gap where `cue` to a
-            // detached/gone player returns "Message sent" — wire-truthful (the
-            // signal IS delivered to the workflow inbox), but operator-
-            // misleading because no live adapter surfaces the message.
-            let phase;
+function buildCueTool(client, config, getPlayerId, handle) {
+    return {
+        name: 'cue',
+        description: 'Send a message to another Claude Code session by player name. Delivered instantly via Temporal signal. For content larger than ~100 KB, use `coat_check_put` to stash the body and pass the returned ticket via `attachmentTicket` — the cue body itself should carry a short summary the recipient can act on without fetching.',
+        params: {
+            playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name of the target session'),
+            message: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The message to send'),
+            attachmentTicket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).optional().describe('Optional coat-check ticket (#318). Reference content stashed via `coat_check_put`; the receiver sees the ticket on their `recall` message and can pull the body via `coat_check_get`. Backward-compatible — omit for normal cues.'),
+        },
+        handler: async (args) => {
+            const { playerId, message, attachmentTicket } = args;
+            const nameError = (0, validation_1.validatePlayerName)(playerId);
+            if (nameError)
+                return (0, descriptor_1.fail)(nameError);
             try {
-                const info = await (0, query_timeout_1.queryHandleWithTimeout)(resolved, signals_1.attachmentInfoQuery, { timeoutMs: CUE_PHASE_PREFLIGHT_TIMEOUT_MS });
-                phase = info.phase;
+                const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
+                if (!resolved) {
+                    // #560: replace the generic "no active session found" with an
+                    // actionable error — active-player list + fuzzy-match suggestion
+                    // + Agent-tool surface hint. We pay the extra `scanEnsembleSessions`
+                    // round-trip ONLY on the error path, so the success path is
+                    // unchanged.
+                    const sessions = await (0, resolve_2.scanEnsembleSessions)(client, config.ensemble);
+                    const activePlayers = sessions.map((s) => s.playerId).sort();
+                    return (0, descriptor_1.fail)(formatUnknownPlayerError(playerId, activePlayers));
+                }
+                // #562: phase pre-flight. Resolves the gap where `cue` to a
+                // detached/gone player returns "Message sent" — wire-truthful (the
+                // signal IS delivered to the workflow inbox), but operator-
+                // misleading because no live adapter surfaces the message.
+                let phase;
+                try {
+                    const info = await (0, query_timeout_1.queryHandleWithTimeout)(resolved, signals_1.attachmentInfoQuery, { timeoutMs: CUE_PHASE_PREFLIGHT_TIMEOUT_MS });
+                    phase = info.phase;
+                }
+                catch (err) {
+                    // Query timed out or threw — workflow may be wedged. Don't
+                    // penalize the operator: fall through to best-effort submit.
+                    // Auto-redelivery on re-attach still applies. Stderr log keeps
+                    // the observability trail without surfacing noise to the user.
+                    console.error(`[agent-tempo:cue] phase pre-flight failed for "${playerId}" — proceeding best-effort:`, err instanceof Error ? err.message : err);
+                }
+                if (phase && UNDELIVERABLE_PHASES.has(phase)) {
+                    return (0, descriptor_1.fail)(formatDetachedDeliveryError(playerId, phase));
+                }
+                const entry = {
+                    type: 'cue',
+                    targetPlayerId: playerId,
+                    message,
+                    ...(attachmentTicket !== undefined ? { attachmentTicket } : {}),
+                };
+                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                return (0, descriptor_1.ok)(`Message sent to ${playerId}. (outbox: ${entryId})`);
             }
             catch (err) {
-                // Query timed out or threw — workflow may be wedged. Don't
-                // penalize the operator: fall through to best-effort submit.
-                // Auto-redelivery on re-attach still applies. Stderr log keeps
-                // the observability trail without surfacing noise to the user.
-                console.error(`[agent-tempo:cue] phase pre-flight failed for "${playerId}" — proceeding best-effort:`, err instanceof Error ? err.message : err);
-            }
-            if (phase && UNDELIVERABLE_PHASES.has(phase)) {
-                return (0, helpers_1.fail)(formatDetachedDeliveryError(playerId, phase));
+                return (0, descriptor_1.fail)(`Failed to send message to ${playerId}: ${(0, descriptor_1.formatError)(err)}`);
             }
-            const entry = {
-                type: 'cue',
-                targetPlayerId: playerId,
-                message,
-                ...(attachmentTicket !== undefined ? { attachmentTicket } : {}),
-            };
-            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
-            return (0, helpers_1.ok)(`Message sent to ${playerId}. (outbox: ${entryId})`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to send message to ${playerId}: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+        },
+    };
 }
 /**
  * Format the cue tool's "unknown player" error with actionable suggestions.

package/dist/tools/descriptor.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Transport-neutral tool descriptor (MD-B seam, Phase 1).
+ *
+ * agent-tempo tools used to be defined directly against an `McpServer`
+ * (`defineTool` → `server.tool(...)`). MD-B splits that into:
+ *
+ *   1. A neutral **descriptor** — `{ name, description, params, handler }` —
+ *      with NO MCP or Pi coupling. zod is the single source of truth for
+ *      params; the handler returns neutral `{ text, isError? }`.
+ *   2. Per-front-end **renderers** — `renderToMcp` (here) and `renderToPi`
+ *      (`src/pi/render-tools.ts`). MCP consumes the zod shape raw; Pi derives
+ *      a TypeBox schema from it. No dual-define, no drift.
+ *
+ * Backward-compat is load-bearing: `renderToMcp` reproduces the EXACT output
+ * of the old `defineTool` so `src/server.ts` and the claude-api in-process MCP
+ * bridge keep byte-identical behavior. `registerAllTempoTools` stays a thin
+ * wrapper over `renderToMcp(server, buildAllTempoTools(opts))` — its callers
+ * never change.
+ *
+ * Determinism note: this module is client-side (src/tools). `src/pi/` imports
+ * the descriptor type FROM here; this module never imports `src/pi/`.
+ *
+ * Design reference: architect's MD-B implementation spec (Phase 1).
+ */
+import type { z } from 'zod';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Neutral tool result. Every current tool returns a single text block via
+ * `ok()` / `fail()`. Richer multi-block / structured output is an ADDITIVE
+ * future extension (e.g. an optional `data?`) — intentionally not modeled now.
+ */
+export interface TempoToolResult {
+    text: string;
+    isError?: boolean;
+}
+/**
+ * A transport-neutral tool definition. Each tool module exports a
+ * `build<X>Tool(...deps): TempoToolDescriptor` factory that closes over its
+ * existing dependencies (client, config, handle, getPlayerId, …) exactly as
+ * the old `register<X>Tool` did.
+ */
+export interface TempoToolDescriptor {
+    name: string;
+    description: string;
+    /**
+     * zod is the SINGLE SOURCE OF TRUTH for parameters. The MCP renderer passes
+     * this shape straight to `server.tool`; the Pi renderer derives a TypeBox
+     * schema from it via the zod→TypeBox converter. `z.ZodRawShape` is
+     * `Record<string, z.ZodTypeAny>` — the same shape `defineTool` accepted.
+     */
+    params: z.ZodRawShape;
+    /** Neutral handler. No MCP `extra` param (zero tools use it). */
+    handler: (args: Record<string, unknown>) => Promise<TempoToolResult>;
+}
+/** Return a successful tool result. (Neutral replacement for the old MCP `ok`.) */
+export declare function ok(text: string): TempoToolResult;
+/** Return an error tool result. (Neutral replacement for the old MCP `fail`.) */
+export declare function fail(text: string): TempoToolResult;
+/** Extract a human-readable message from an unknown error. */
+export declare function formatError(err: unknown): string;
+/**
+ * Render descriptors onto an MCP server — the backward-compatible path.
+ *
+ * Reproduces the old `defineTool` EXACTLY (see the removed `helpers.ts`):
+ *   - `(server.tool as Function)(name, description, paramsSchema, handler)` —
+ *     the `as Function` cast is the TS2589 deep-instantiation workaround for
+ *     Zod 3.25 + MCP SDK type inference; preserve it.
+ *   - The handler wraps the neutral `{ text, isError? }` back into MCP's
+ *     `{ content: [{ type: 'text', text }], isError? }` — byte-identical to
+ *     what `ok()` / `fail()` produced before MD-B.
+ */
+export declare function renderToMcp(server: McpServer, descriptors: TempoToolDescriptor[]): void;

package/dist/tools/descriptor.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ok = ok;
+exports.fail = fail;
+exports.formatError = formatError;
+exports.renderToMcp = renderToMcp;
+/** Return a successful tool result. (Neutral replacement for the old MCP `ok`.) */
+function ok(text) {
+    return { text };
+}
+/** Return an error tool result. (Neutral replacement for the old MCP `fail`.) */
+function fail(text) {
+    return { text, isError: true };
+}
+/** Extract a human-readable message from an unknown error. */
+function formatError(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Render descriptors onto an MCP server — the backward-compatible path.
+ *
+ * Reproduces the old `defineTool` EXACTLY (see the removed `helpers.ts`):
+ *   - `(server.tool as Function)(name, description, paramsSchema, handler)` —
+ *     the `as Function` cast is the TS2589 deep-instantiation workaround for
+ *     Zod 3.25 + MCP SDK type inference; preserve it.
+ *   - The handler wraps the neutral `{ text, isError? }` back into MCP's
+ *     `{ content: [{ type: 'text', text }], isError? }` — byte-identical to
+ *     what `ok()` / `fail()` produced before MD-B.
+ */
+function renderToMcp(server, descriptors) {
+    for (const d of descriptors) {
+        server.tool(d.name, d.description, d.params, async (args) => {
+            const r = await d.handler(args);
+            return r.isError
+                ? { content: [{ type: 'text', text: r.text }], isError: true }
+                : { content: [{ type: 'text', text: r.text }] };
+        });
+    }
+}

package/dist/tools/destroy.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 registerDestroyTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildDestroyTool(client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): TempoToolDescriptor;

package/dist/tools/destroy.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerDestroyTool = registerDestroyTool;
+exports.buildDestroyTool = buildDestroyTool;
 /**
  * `destroy` — terminal end of either a single session or the whole ensemble.
  *
@@ -24,165 +24,170 @@ const zod_1 = require("zod");
 const config_1 = require("../config");
 const signals_1 = require("../workflows/signals");
 const resolve_1 = require("../activities/resolve");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
 const log = (...args) => console.error('[agent-tempo:destroy]', ...args);
-function registerDestroyTool(server, client, config, getPlayerId, handle) {
-    (0, helpers_1.defineTool)(server, 'destroy', 'Terminally destroy a session workflow (when `playerId` is given) or the entire ensemble (when omitted): every peer session, the scheduler, the maestro, and the conductor. COMPLETEs workflows and cannot be undone. For graceful reap use `shutdown`; for a clean revive use `restart`.', {
-        // #306: `.min(1)` rejects `{playerId: ""}` at the SDK boundary so a
-        // buggy MCP caller can't silently fall through to ensemble-wide
-        // destroy mode. The handler also guards programmatic callers that
-        // bypass Zod (see explicit `playerId === ''` rejection below).
-        playerId: zod_1.z.string().min(1).max(validation_1.PLAYER_NAME_MAX).optional().describe('Target player name. Omit to destroy the entire ensemble.'),
-        reason: zod_1.z.string().max(500).optional().describe('Optional reason recorded in the workflow\'s audit event'),
-    }, async (args) => {
-        const { playerId, reason } = args;
-        const callerId = getPlayerId();
-        // #306: defense-in-depth for callers that bypass Zod (test harnesses,
-        // direct handler invocation). Zod's `.min(1)` already covers normal
-        // MCP traffic; this guard ensures empty-string never falls through to
-        // ensemble-wide destroy mode regardless of how the handler is reached.
-        if (playerId === '') {
-            return (0, helpers_1.fail)('`playerId` cannot be an empty string. Omit it to destroy the entire ensemble.');
-        }
-        // ── Single-player mode (existing behaviour) ─────────────────────────
-        if (playerId !== undefined) {
-            const nameError = (0, validation_1.validatePlayerName)(playerId);
-            if (nameError)
-                return (0, helpers_1.fail)(nameError);
-            if (playerId === callerId) {
-                return (0, helpers_1.fail)('Cannot destroy your own session.');
+function buildDestroyTool(client, config, getPlayerId, handle) {
+    return {
+        name: 'destroy',
+        description: 'Terminally destroy a session workflow (when `playerId` is given) or the entire ensemble (when omitted): every peer session, the scheduler, the maestro, and the conductor. COMPLETEs workflows and cannot be undone. For graceful reap use `shutdown`; for a clean revive use `restart`.',
+        params: {
+            // #306: `.min(1)` rejects `{playerId: ""}` at the SDK boundary so a
+            // buggy MCP caller can't silently fall through to ensemble-wide
+            // destroy mode. The handler also guards programmatic callers that
+            // bypass Zod (see explicit `playerId === ''` rejection below).
+            playerId: zod_1.z.string().min(1).max(validation_1.PLAYER_NAME_MAX).optional().describe('Target player name. Omit to destroy the entire ensemble.'),
+            reason: zod_1.z.string().max(500).optional().describe('Optional reason recorded in the workflow\'s audit event'),
+        },
+        handler: async (args) => {
+            const { playerId, reason } = args;
+            const callerId = getPlayerId();
+            // #306: defense-in-depth for callers that bypass Zod (test harnesses,
+            // direct handler invocation). Zod's `.min(1)` already covers normal
+            // MCP traffic; this guard ensures empty-string never falls through to
+            // ensemble-wide destroy mode regardless of how the handler is reached.
+            if (playerId === '') {
+                return (0, descriptor_1.fail)('`playerId` cannot be an empty string. Omit it to destroy the entire ensemble.');
             }
-            try {
-                const entry = {
-                    type: 'destroy',
-                    targetPlayerId: playerId,
-                    ...(reason !== undefined ? { reason } : {}),
-                    notifyConductor: true,
-                };
-                const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
-                return (0, helpers_1.ok)(`Destroy queued for **${playerId}**${reason ? ` (reason: ${reason})` : ''}. (outbox: ${entryId})`);
-            }
-            catch (err) {
-                return (0, helpers_1.fail)(`Failed to destroy: ${(0, helpers_1.formatError)(err)}`);
-            }
-        }
-        // ── Ensemble-scope mode (#287) ──────────────────────────────────────
-        // Order: peer sessions (parallel) → scheduler + maestro (parallel) →
-        // conductor last. The conductor-last step is the invariant the
-        // architect's spec relies on so the conductor sees every peer
-        // teardown before its own destroy.
-        try {
-            const destroyReason = reason ?? `ensemble destroy via ${callerId}`;
-            const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
-            const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
-            const peers = [];
-            let conductorPresent = false;
-            for (const s of sessions) {
-                if (s.workflowId === conductorWfId) {
-                    conductorPresent = true;
-                }
-                else {
-                    peers.push(s);
+            // ── Single-player mode (existing behaviour) ─────────────────────────
+            if (playerId !== undefined) {
+                const nameError = (0, validation_1.validatePlayerName)(playerId);
+                if (nameError)
+                    return (0, descriptor_1.fail)(nameError);
+                if (playerId === callerId) {
+                    return (0, descriptor_1.fail)('Cannot destroy your own session.');
                 }
-            }
-            const details = [];
-            let destroyed = 0;
-            let terminated = 0;
-            let failed = 0;
-            // Phase 1: destroy every peer in parallel (conductor excluded). Skip
-            // the caller's own session — self-destroy is a no-op guard.
-            const peerResults = await Promise.allSettled(peers.map(async (s) => {
-                if (s.playerId === callerId)
-                    return { session: s, outcome: 'skipped-self' };
                 try {
-                    await client.workflow.getHandle(s.workflowId).executeUpdate(signals_1.destroyUpdate, {
-                        args: [{ reason: destroyReason, terminatedBy: callerId }],
-                    });
-                    return { session: s, outcome: 'destroyed' };
+                    const entry = {
+                        type: 'destroy',
+                        targetPlayerId: playerId,
+                        ...(reason !== undefined ? { reason } : {}),
+                        notifyConductor: true,
+                    };
+                    const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+                    return (0, descriptor_1.ok)(`Destroy queued for **${playerId}**${reason ? ` (reason: ${reason})` : ''}. (outbox: ${entryId})`);
                 }
                 catch (err) {
-                    return { session: s, outcome: 'failed', error: (0, helpers_1.formatError)(err) };
+                    return (0, descriptor_1.fail)(`Failed to destroy: ${(0, descriptor_1.formatError)(err)}`);
                 }
-            }));
-            for (const r of peerResults) {
-                if (r.status !== 'fulfilled')
-                    continue;
-                const v = r.value;
-                if (v.outcome === 'destroyed') {
-                    details.push({ target: v.session.playerId, outcome: 'destroyed' });
-                    destroyed++;
+            }
+            // ── Ensemble-scope mode (#287) ──────────────────────────────────────
+            // Order: peer sessions (parallel) → scheduler + maestro (parallel) →
+            // conductor last. The conductor-last step is the invariant the
+            // architect's spec relies on so the conductor sees every peer
+            // teardown before its own destroy.
+            try {
+                const destroyReason = reason ?? `ensemble destroy via ${callerId}`;
+                const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
+                const conductorWfId = (0, config_1.conductorWorkflowId)(config.ensemble);
+                const peers = [];
+                let conductorPresent = false;
+                for (const s of sessions) {
+                    if (s.workflowId === conductorWfId) {
+                        conductorPresent = true;
+                    }
+                    else {
+                        peers.push(s);
+                    }
                 }
-                else if (v.outcome === 'failed') {
-                    details.push({ target: v.session.playerId, outcome: 'failed', error: v.error });
-                    failed++;
+                const details = [];
+                let destroyed = 0;
+                let terminated = 0;
+                let failed = 0;
+                // Phase 1: destroy every peer in parallel (conductor excluded). Skip
+                // the caller's own session — self-destroy is a no-op guard.
+                const peerResults = await Promise.allSettled(peers.map(async (s) => {
+                    if (s.playerId === callerId)
+                        return { session: s, outcome: 'skipped-self' };
+                    try {
+                        await client.workflow.getHandle(s.workflowId).executeUpdate(signals_1.destroyUpdate, {
+                            args: [{ reason: destroyReason, terminatedBy: callerId }],
+                        });
+                        return { session: s, outcome: 'destroyed' };
+                    }
+                    catch (err) {
+                        return { session: s, outcome: 'failed', error: (0, descriptor_1.formatError)(err) };
+                    }
+                }));
+                for (const r of peerResults) {
+                    if (r.status !== 'fulfilled')
+                        continue;
+                    const v = r.value;
+                    if (v.outcome === 'destroyed') {
+                        details.push({ target: v.session.playerId, outcome: 'destroyed' });
+                        destroyed++;
+                    }
+                    else if (v.outcome === 'failed') {
+                        details.push({ target: v.session.playerId, outcome: 'failed', error: v.error });
+                        failed++;
+                    }
+                    // #299: `'skipped-self'` is an internal control-flow tag for the
+                    // caller's own session — intentionally NOT surfaced in `details`
+                    // because `EnsembleDestroyDetail` is consumed publicly via
+                    // `EnsembleDestroySummary` (TempoClient.destroy), which has no
+                    // caller-self concept. The skip is a bookkeeping no-op here.
                 }
-                // #299: `'skipped-self'` is an internal control-flow tag for the
-                // caller's own session — intentionally NOT surfaced in `details`
-                // because `EnsembleDestroyDetail` is consumed publicly via
-                // `EnsembleDestroySummary` (TempoClient.destroy), which has no
-                // caller-self concept. The skip is a bookkeeping no-op here.
-            }
-            // Phase 2: scheduler + maestro terminate in parallel (non-session
-            // workflows — no destroy handler). `terminate` rejects when the
-            // workflow isn't running; treat as "not present" instead of failure.
-            const [schedRes, maestroRes] = await Promise.allSettled([
-                client.workflow.getHandle((0, config_1.schedulerWorkflowId)(config.ensemble)).terminate(destroyReason),
-                client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble)).terminate(destroyReason),
-            ]);
-            if (schedRes.status === 'fulfilled') {
-                details.push({ target: 'scheduler', outcome: 'terminated' });
-                terminated++;
-            }
-            if (maestroRes.status === 'fulfilled') {
-                details.push({ target: 'maestro', outcome: 'terminated' });
-                terminated++;
-            }
-            // Phase 3: conductor last, so it observes peer teardown. Skipped if
-            // the caller IS the conductor (same self-destroy guard). #299: the
-            // skip is a control-flow no-op — no `details` entry, mirroring the
-            // peer-self skip. `EnsembleDestroyDetail.outcome` no longer carries
-            // a self-skip member.
-            if (callerId === 'conductor') {
-                // self-skip; no recording
-            }
-            else if (conductorPresent) {
-                try {
-                    await client.workflow.getHandle(conductorWfId).executeUpdate(signals_1.destroyUpdate, {
-                        args: [{ reason: destroyReason, terminatedBy: callerId }],
-                    });
-                    details.push({ target: 'conductor', outcome: 'destroyed' });
-                    destroyed++;
+                // Phase 2: scheduler + maestro terminate in parallel (non-session
+                // workflows — no destroy handler). `terminate` rejects when the
+                // workflow isn't running; treat as "not present" instead of failure.
+                const [schedRes, maestroRes] = await Promise.allSettled([
+                    client.workflow.getHandle((0, config_1.schedulerWorkflowId)(config.ensemble)).terminate(destroyReason),
+                    client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble)).terminate(destroyReason),
+                ]);
+                if (schedRes.status === 'fulfilled') {
+                    details.push({ target: 'scheduler', outcome: 'terminated' });
+                    terminated++;
                 }
-                catch (err) {
-                    details.push({ target: 'conductor', outcome: 'failed', error: (0, helpers_1.formatError)(err) });
-                    failed++;
+                if (maestroRes.status === 'fulfilled') {
+                    details.push({ target: 'maestro', outcome: 'terminated' });
+                    terminated++;
                 }
+                // Phase 3: conductor last, so it observes peer teardown. Skipped if
+                // the caller IS the conductor (same self-destroy guard). #299: the
+                // skip is a control-flow no-op — no `details` entry, mirroring the
+                // peer-self skip. `EnsembleDestroyDetail.outcome` no longer carries
+                // a self-skip member.
+                if (callerId === 'conductor') {
+                    // self-skip; no recording
+                }
+                else if (conductorPresent) {
+                    try {
+                        await client.workflow.getHandle(conductorWfId).executeUpdate(signals_1.destroyUpdate, {
+                            args: [{ reason: destroyReason, terminatedBy: callerId }],
+                        });
+                        details.push({ target: 'conductor', outcome: 'destroyed' });
+                        destroyed++;
+                    }
+                    catch (err) {
+                        details.push({ target: 'conductor', outcome: 'failed', error: (0, descriptor_1.formatError)(err) });
+                        failed++;
+                    }
+                }
+                const summaryLine = `${destroyed} destroyed, ${terminated} terminated, ${failed} failed`;
+                const headline = failed > 0
+                    ? `Ensemble **${config.ensemble}** partially destroyed.`
+                    : `Ensemble **${config.ensemble}** destroyed.`;
+                const lines = [headline, summaryLine];
+                const failures = details.filter((d) => d.outcome === 'failed');
+                if (failures.length > 0) {
+                    lines.push(`Errors:\n${failures.map((d) => `  - ${d.target}: ${d.error}`).join('\n')}`);
+                    // #306 follow-up: surface the indeterminate-state hint from my own
+                    // PR-#306 holistic review (regression risk #3). `Promise.allSettled`
+                    // returned `failed` outcomes for these peers — the workflows may
+                    // be in any state from "still running" to "destroyed but RPC
+                    // timed out". Re-running `destroy` is safe (idempotent on the
+                    // workflow side: `destroyUpdate` on a `gone` workflow is a no-op
+                    // via the `isDestroyedQuery` guard) and the cleanest recovery.
+                    const noun = failed === 1 ? 'peer' : 'peers';
+                    lines.push(`⚠ ${failed} ${noun} in indeterminate state — ` +
+                        `run \`/destroy ${config.ensemble}\` again to clean up.`);
+                }
+                log(`Ensemble destroy by ${callerId}: ${summaryLine}`);
+                return (0, descriptor_1.ok)(lines.join('\n'));
             }
-            const summaryLine = `${destroyed} destroyed, ${terminated} terminated, ${failed} failed`;
-            const headline = failed > 0
-                ? `Ensemble **${config.ensemble}** partially destroyed.`
-                : `Ensemble **${config.ensemble}** destroyed.`;
-            const lines = [headline, summaryLine];
-            const failures = details.filter((d) => d.outcome === 'failed');
-            if (failures.length > 0) {
-                lines.push(`Errors:\n${failures.map((d) => `  - ${d.target}: ${d.error}`).join('\n')}`);
-                // #306 follow-up: surface the indeterminate-state hint from my own
-                // PR-#306 holistic review (regression risk #3). `Promise.allSettled`
-                // returned `failed` outcomes for these peers — the workflows may
-                // be in any state from "still running" to "destroyed but RPC
-                // timed out". Re-running `destroy` is safe (idempotent on the
-                // workflow side: `destroyUpdate` on a `gone` workflow is a no-op
-                // via the `isDestroyedQuery` guard) and the cleanest recovery.
-                const noun = failed === 1 ? 'peer' : 'peers';
-                lines.push(`⚠ ${failed} ${noun} in indeterminate state — ` +
-                    `run \`/destroy ${config.ensemble}\` again to clean up.`);
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to destroy ensemble: ${(0, descriptor_1.formatError)(err)}`);
             }
-            log(`Ensemble destroy by ${callerId}: ${summaryLine}`);
-            return (0, helpers_1.ok)(lines.join('\n'));
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to destroy ensemble: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+        },
+    };
 }

package/dist/tools/ensemble.d.ts

@@ -1,7 +1,7 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from '@temporalio/client';
 import { Config } from '../config';
 import { type EnsembleSessionInfo } from '../activities/resolve';
+import { type TempoToolDescriptor } from './descriptor';
 /**
  * Default dormancy threshold (1 hour). Per #563: a `detached` player whose
  * last activity is older than this is considered dormant. `phase === 'gone'`
@@ -29,4 +29,4 @@ export type DormantFilter = 'show' | 'hide' | 'show-only';
  * Exported for unit testing.
  */
 export declare function classifyDormancy(session: Pick<EnsembleSessionInfo, 'phase' | 'lastActivityAt'>, now: number, thresholdMs?: number): 'active' | 'dormant';
-export declare function registerEnsembleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, ownWorkflowId: string): void;
+export declare function buildEnsembleTool(client: Client, config: Config, getPlayerId: () => string, ownWorkflowId: string): TempoToolDescriptor;