agent-tempo 1.2.0 → 1.4.0

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

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerCoatCheckGetTool = registerCoatCheckGetTool;
+exports.buildCoatCheckGetTool = buildCoatCheckGetTool;
 /**
  * `coat_check_get` — redeem a coat-check ticket and pull the stashed content
  * (#318, ADR 0008). Returns the entry's summary, content body, and audit
@@ -18,39 +18,44 @@ exports.registerCoatCheckGetTool = registerCoatCheckGetTool;
 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 registerCoatCheckGetTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_get', `Redeem a coat-check ticket (#318) and pull the stashed content. Returns the entry's summary, content body, and audit info — or "not found" when the ticket is missing / expired / evicted (no error, just empty).
-
-Successful redemptions bump the entry's fetch-audit counters (\`lastFetchedAt\` / \`lastFetchedBy\` / \`fetchCount\`) so the putter can later see whether anyone has redeemed. \`coat_check_list\` won't bump these — only an actual redemption counts.`, {
-        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 fetchedBy = getPlayerId();
-        try {
-            const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
-            const entry = await handle.executeUpdate(maestro_signals_1.coatCheckGetUpdate, {
-                args: [{ ticket, fetchedBy }],
-            });
-            if (!entry) {
-                return (0, helpers_1.ok)(`Ticket **${ticket}** is not found (missing, expired, or evicted).`);
+function buildCoatCheckGetTool(client, config, getPlayerId) {
+    return {
+        name: 'coat_check_get',
+        description: `Redeem a coat-check ticket (#318) and pull the stashed content. Returns the entry's summary, content body, and audit info — or "not found" when the ticket is missing / expired / evicted (no error, just empty).
+
+Successful redemptions bump the entry's fetch-audit counters (\`lastFetchedAt\` / \`lastFetchedBy\` / \`fetchCount\`) so the putter can later see whether anyone has redeemed. \`coat_check_list\` won't bump these — only an actual redemption counts.`,
+        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 fetchedBy = getPlayerId();
+            try {
+                const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
+                const entry = await handle.executeUpdate(maestro_signals_1.coatCheckGetUpdate, {
+                    args: [{ ticket, fetchedBy }],
+                });
+                if (!entry) {
+                    return (0, descriptor_1.ok)(`Ticket **${ticket}** is not found (missing, expired, or evicted).`);
+                }
+                const lines = [
+                    `**Ticket ${ticket}** — stashed by ${entry.putBy} at ${entry.putAt}, expires ${entry.expiresAt}`,
+                    `Summary: ${entry.summary}`,
+                ];
+                if (entry.contentType)
+                    lines.push(`Content-Type: ${entry.contentType}`);
+                lines.push(`Size: ${entry.size} bytes`);
+                lines.push(`Fetches: ${entry.fetchCount}${entry.lastFetchedBy ? ` (last by ${entry.lastFetchedBy} at ${entry.lastFetchedAt})` : ''}`);
+                lines.push('');
+                lines.push('---');
+                lines.push(entry.content);
+                return (0, descriptor_1.ok)(lines.join('\n'));
             }
-            const lines = [
-                `**Ticket ${ticket}** — stashed by ${entry.putBy} at ${entry.putAt}, expires ${entry.expiresAt}`,
-                `Summary: ${entry.summary}`,
-            ];
-            if (entry.contentType)
-                lines.push(`Content-Type: ${entry.contentType}`);
-            lines.push(`Size: ${entry.size} bytes`);
-            lines.push(`Fetches: ${entry.fetchCount}${entry.lastFetchedBy ? ` (last by ${entry.lastFetchedBy} at ${entry.lastFetchedAt})` : ''}`);
-            lines.push('');
-            lines.push('---');
-            lines.push(entry.content);
-            return (0, helpers_1.ok)(lines.join('\n'));
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to redeem ticket: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to redeem ticket: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/coat-check-list.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 registerCoatCheckListTool(server: McpServer, client: Client, config: Config): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildCoatCheckListTool(client: Client, config: Config): TempoToolDescriptor;

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerCoatCheckListTool = registerCoatCheckListTool;
+exports.buildCoatCheckListTool = buildCoatCheckListTool;
 /**
  * `coat_check_list` — list coat-check entry headers (#318, ADR 0008) for
  * the calling player's ensemble. Read-only — does NOT bump fetch-audit
@@ -12,49 +12,54 @@ exports.registerCoatCheckListTool = registerCoatCheckListTool;
 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 registerCoatCheckListTool(server, client, config) {
-    (0, helpers_1.defineTool)(server, 'coat_check_list', `List coat-check entries (#318) for this ensemble. Read-only — does NOT bump fetch-audit counters; only \`coat_check_get\` does. Sorted newest-first. Pass \`unfetchedOnly: true\` to surface entries nobody has redeemed yet — useful for an owner cleaning up stale stashes.`, {
-        putBy: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Optional filter — only entries stashed by this player.'),
-        prefix: zod_1.z.string().max(validation_1.COAT_CHECK_SUMMARY_MAX).optional().describe('Optional summary-prefix filter — narrows the listing to entries whose summary starts with this string.'),
-        unfetchedOnly: zod_1.z.boolean().optional().describe('When true, only return entries with fetchCount=0 (never redeemed). Default false.'),
-    }, async (args) => {
-        const { putBy, prefix, unfetchedOnly } = args;
-        try {
-            const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
-            const filter = {
-                ...(putBy !== undefined ? { putBy } : {}),
-                ...(prefix !== undefined ? { prefix } : {}),
-                ...(unfetchedOnly !== undefined ? { unfetchedOnly } : {}),
-            };
-            const headers = await handle.query(maestro_signals_1.coatCheckListQuery, filter);
-            if (headers.length === 0) {
-                const filters = [];
-                if (putBy)
-                    filters.push(`putBy="${putBy}"`);
-                if (prefix)
-                    filters.push(`prefix="${prefix}"`);
-                if (unfetchedOnly)
-                    filters.push('unfetchedOnly=true');
-                const suffix = filters.length > 0 ? ` (filter: ${filters.join(', ')})` : '';
-                return (0, helpers_1.ok)(`No coat-check entries in this ensemble${suffix}.`);
+function buildCoatCheckListTool(client, config) {
+    return {
+        name: 'coat_check_list',
+        description: `List coat-check entries (#318) for this ensemble. Read-only — does NOT bump fetch-audit counters; only \`coat_check_get\` does. Sorted newest-first. Pass \`unfetchedOnly: true\` to surface entries nobody has redeemed yet — useful for an owner cleaning up stale stashes.`,
+        params: {
+            putBy: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Optional filter — only entries stashed by this player.'),
+            prefix: zod_1.z.string().max(validation_1.COAT_CHECK_SUMMARY_MAX).optional().describe('Optional summary-prefix filter — narrows the listing to entries whose summary starts with this string.'),
+            unfetchedOnly: zod_1.z.boolean().optional().describe('When true, only return entries with fetchCount=0 (never redeemed). Default false.'),
+        },
+        handler: async (args) => {
+            const { putBy, prefix, unfetchedOnly } = args;
+            try {
+                const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
+                const filter = {
+                    ...(putBy !== undefined ? { putBy } : {}),
+                    ...(prefix !== undefined ? { prefix } : {}),
+                    ...(unfetchedOnly !== undefined ? { unfetchedOnly } : {}),
+                };
+                const headers = await handle.query(maestro_signals_1.coatCheckListQuery, filter);
+                if (headers.length === 0) {
+                    const filters = [];
+                    if (putBy)
+                        filters.push(`putBy="${putBy}"`);
+                    if (prefix)
+                        filters.push(`prefix="${prefix}"`);
+                    if (unfetchedOnly)
+                        filters.push('unfetchedOnly=true');
+                    const suffix = filters.length > 0 ? ` (filter: ${filters.join(', ')})` : '';
+                    return (0, descriptor_1.ok)(`No coat-check entries in this ensemble${suffix}.`);
+                }
+                const lines = [];
+                lines.push(`${headers.length}/${validation_1.COAT_CHECK_SLOTS_MAX} coat-check ${headers.length === 1 ? 'entry' : 'entries'}:`);
+                lines.push('');
+                for (const h of headers) {
+                    const fetchTag = h.fetchCount === 0
+                        ? ' (unfetched)'
+                        : ` (fetched ${h.fetchCount}× by ${h.lastFetchedBy ?? '(unknown)'} at ${h.lastFetchedAt ?? '(unknown)'})`;
+                    const typeTag = h.contentType ? ` [${h.contentType}]` : '';
+                    lines.push(`- **${h.ticket}** ${typeTag}— ${h.summary}`);
+                    lines.push(`    putBy=${h.putBy} · putAt=${h.putAt} · expires=${h.expiresAt} · ${h.size} bytes${fetchTag}`);
+                }
+                return (0, descriptor_1.ok)(lines.join('\n'));
             }
-            const lines = [];
-            lines.push(`${headers.length}/${validation_1.COAT_CHECK_SLOTS_MAX} coat-check ${headers.length === 1 ? 'entry' : 'entries'}:`);
-            lines.push('');
-            for (const h of headers) {
-                const fetchTag = h.fetchCount === 0
-                    ? ' (unfetched)'
-                    : ` (fetched ${h.fetchCount}× by ${h.lastFetchedBy ?? '(unknown)'} at ${h.lastFetchedAt ?? '(unknown)'})`;
-                const typeTag = h.contentType ? ` [${h.contentType}]` : '';
-                lines.push(`- **${h.ticket}** ${typeTag}— ${h.summary}`);
-                lines.push(`    putBy=${h.putBy} · putAt=${h.putAt} · expires=${h.expiresAt} · ${h.size} bytes${fetchTag}`);
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to list coat-check entries: ${(0, descriptor_1.formatError)(err)}`);
             }
-            return (0, helpers_1.ok)(lines.join('\n'));
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to list coat-check entries: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+        },
+    };
 }

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

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

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerCoatCheckPutTool = registerCoatCheckPutTool;
+exports.buildCoatCheckPutTool = buildCoatCheckPutTool;
 /**
  * `coat_check_put` — stash a large content body on per-ensemble Maestro state
  * (#318, ADR 0008). Returns a ticket id that any player in the ensemble can
@@ -14,40 +14,45 @@ exports.registerCoatCheckPutTool = registerCoatCheckPutTool;
 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 registerCoatCheckPutTool(server, client, config, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'coat_check_put', `Stash a large content body on this ensemble's coat-check (#318). Returns a ticket id any player can redeem later via \`coat_check_get\`. Pass the ticket on a \`cue\`'s \`attachmentTicket\` field so the recipient knows what to fetch.
-
-Use this when your message body would otherwise exceed the cue's 100 KB cap — researcher reports, review-item dumps, etc. The cue body should carry a short summary; the coat-check entry holds the full artifact.
-
-Limits: ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8) per entry, max ${validation_1.COAT_CHECK_SLOTS_MAX} live entries per ensemble. Saturation rejects with \`CoatCheckSlotsFull\` — wait for TTL or \`coat_check_evict\` an entry you own. TTL defaults to 7 days (configurable per put within [1h, 30d]).`, {
-        summary: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_SUMMARY_MAX).describe(`Short preamble surfaced in \`coat_check_list\` and on dashboards (≤${validation_1.COAT_CHECK_SUMMARY_MAX} chars). 1-2 sentences describing what the recipient gets if they redeem.`),
-        content: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_CONTENT_MAX).describe(`The full content body — markdown encouraged, opaque to the system. Max ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8).`),
-        contentType: zod_1.z.string().max(validation_1.COAT_CHECK_CONTENT_TYPE_MAX).optional().describe(`Optional MIME-shaped hint (e.g. "text/markdown"). Free-form; ≤${validation_1.COAT_CHECK_CONTENT_TYPE_MAX} chars.`),
-        ttlMs: zod_1.z.number().int().min(validation_1.COAT_CHECK_TTL_MIN_MS).max(validation_1.COAT_CHECK_TTL_MAX_MS).optional().describe(`Time-to-live in milliseconds. Default ${validation_1.COAT_CHECK_TTL_DEFAULT_MS} (7 days). Range [${validation_1.COAT_CHECK_TTL_MIN_MS}, ${validation_1.COAT_CHECK_TTL_MAX_MS}] (1h to 30d).`),
-    }, async (args) => {
-        const { summary, content, contentType, ttlMs } = args;
-        const putBy = getPlayerId();
-        try {
-            const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
-            const result = await handle.executeUpdate(maestro_signals_1.coatCheckPutUpdate, {
-                args: [{
-                        summary,
-                        content,
-                        ...(contentType !== undefined ? { contentType } : {}),
-                        ...(ttlMs !== undefined ? { ttlMs } : {}),
-                        putBy,
-                    }],
-            });
-            return (0, helpers_1.ok)(`Stashed as ticket **${result.ticket}** (expires ${result.expiresAt}). Slots: ${result.slotsUsed}/${result.slotsTotal}.`);
-        }
-        catch (err) {
-            // The workflow validator surfaces structured ApplicationFailure
-            // errors (`CoatCheckSlotsFull`, `CoatCheckEntryTooLarge`, …). The
-            // `formatError` message preserves the workflow text so the LLM
-            // sees the oldest-3 ticket list and can pick which to evict.
-            return (0, helpers_1.fail)(`Failed to stash content: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+function buildCoatCheckPutTool(client, config, getPlayerId) {
+    return {
+        name: 'coat_check_put',
+        description: `Stash a large content body on this ensemble's coat-check (#318). Returns a ticket id any player can redeem later via \`coat_check_get\`. Pass the ticket on a \`cue\`'s \`attachmentTicket\` field so the recipient knows what to fetch.
+
+Use this when your message body would otherwise exceed the cue's 100 KB cap — researcher reports, review-item dumps, etc. The cue body should carry a short summary; the coat-check entry holds the full artifact.
+
+Limits: ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8) per entry, max ${validation_1.COAT_CHECK_SLOTS_MAX} live entries per ensemble. Saturation rejects with \`CoatCheckSlotsFull\` — wait for TTL or \`coat_check_evict\` an entry you own. TTL defaults to 7 days (configurable per put within [1h, 30d]).`,
+        params: {
+            summary: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_SUMMARY_MAX).describe(`Short preamble surfaced in \`coat_check_list\` and on dashboards (≤${validation_1.COAT_CHECK_SUMMARY_MAX} chars). 1-2 sentences describing what the recipient gets if they redeem.`),
+            content: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_CONTENT_MAX).describe(`The full content body — markdown encouraged, opaque to the system. Max ${validation_1.COAT_CHECK_CONTENT_MAX} bytes (UTF-8).`),
+            contentType: zod_1.z.string().max(validation_1.COAT_CHECK_CONTENT_TYPE_MAX).optional().describe(`Optional MIME-shaped hint (e.g. "text/markdown"). Free-form; ≤${validation_1.COAT_CHECK_CONTENT_TYPE_MAX} chars.`),
+            ttlMs: zod_1.z.number().int().min(validation_1.COAT_CHECK_TTL_MIN_MS).max(validation_1.COAT_CHECK_TTL_MAX_MS).optional().describe(`Time-to-live in milliseconds. Default ${validation_1.COAT_CHECK_TTL_DEFAULT_MS} (7 days). Range [${validation_1.COAT_CHECK_TTL_MIN_MS}, ${validation_1.COAT_CHECK_TTL_MAX_MS}] (1h to 30d).`),
+        },
+        handler: async (args) => {
+            const { summary, content, contentType, ttlMs } = args;
+            const putBy = getPlayerId();
+            try {
+                const handle = client.workflow.getHandle((0, config_1.maestroWorkflowId)(config.ensemble));
+                const result = await handle.executeUpdate(maestro_signals_1.coatCheckPutUpdate, {
+                    args: [{
+                            summary,
+                            content,
+                            ...(contentType !== undefined ? { contentType } : {}),
+                            ...(ttlMs !== undefined ? { ttlMs } : {}),
+                            putBy,
+                        }],
+                });
+                return (0, descriptor_1.ok)(`Stashed as ticket **${result.ticket}** (expires ${result.expiresAt}). Slots: ${result.slotsUsed}/${result.slotsTotal}.`);
+            }
+            catch (err) {
+                // The workflow validator surfaces structured ApplicationFailure
+                // errors (`CoatCheckSlotsFull`, `CoatCheckEntryTooLarge`, …). The
+                // `formatError` message preserves the workflow text so the LLM
+                // sees the oldest-3 ticket list and can pick which to evict.
+                return (0, descriptor_1.fail)(`Failed to stash content: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/cue.d.ts

@@ -1,7 +1,7 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { Config } from '../config';
 import type { AttachmentPhase } from '../types';
+import { type TempoToolDescriptor } from './descriptor';
 /**
  * Build the operator-facing error message when the cue target is in an
  * undeliverable phase. Lists three actionable next steps per the issue
@@ -10,7 +10,7 @@ import type { AttachmentPhase } from '../types';
  * Exported for unit testing.
  */
 export declare function formatDetachedDeliveryError(playerId: string, phase: AttachmentPhase): string;
-export declare function registerCueTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;
+export declare function buildCueTool(client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): TempoToolDescriptor;
 /**
  * Format the cue tool's "unknown player" error with actionable suggestions.
  * Exported for direct unit testing — the production path passes the active

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;