agent-tempo 1.0.1

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

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

package/dist/tools/agent-types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAgentTypesTool = registerAgentTypesTool;
+const helpers_1 = require("./helpers");
+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'));
+    });
+}

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

@@ -0,0 +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;

package/dist/tools/attachment-info.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerAttachmentInfoTool = registerAttachmentInfoTool;
+/**
+ * `attachment_info` — diagnostic query for the V2 attachment lifecycle (design §§2.2, 2.4).
+ *
+ * Thin wrapper over the `attachmentInfoQuery` primitive (PR-A). Read-only; does not
+ * mutate state. Used by operators + the TUI to inspect a session's phase, current
+ * attachment holder, preferred host, and in-flight count.
+ */
+const zod_1 = require("zod");
+const resolve_1 = require("./resolve");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+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}`);
+            }
+            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)}`);
+        }
+    });
+}

package/dist/tools/broadcast.d.ts

@@ -0,0 +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;

package/dist/tools/broadcast.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerBroadcastTool = registerBroadcastTool;
+const zod_1 = require("zod");
+const crypto_1 = require("crypto");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+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,
+                    });
+                }
+                catch {
+                    // Workflow may have just completed — skip it
+                }
+            }
+            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);
+            }
+            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

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

package/dist/tools/cancel-stage.js

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

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

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

package/dist/tools/clear-state.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerClearStateTool = registerClearStateTool;
+/**
+ * `clear_state` — remove one of the calling player's saved-state slots
+ * (#334 PR-1, ADR 0011).
+ *
+ * Owner-only by structure: there is no `playerId` arg — the tool always
+ * clears via the calling player's own session-workflow handle.
+ *
+ * Idempotent: clearing an already-empty slot returns `cleared: false`.
+ * Surfaces a UX-friendly "was already empty" message rather than treating
+ * the no-op as an error.
+ */
+const zod_1 = require("zod");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+function registerClearStateTool(server, handle) {
+    (0, helpers_1.defineTool)(server, 'clear_state', `Clear one of your saved-state slots. Owner-only — you can only clear your own state. Idempotent (clearing an empty slot is a no-op). Returns whether the slot was non-empty before the clear.`, {
+        key: zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX).optional().describe(`Slot name (default "${validation_1.PLAYER_STATE_DEFAULT_KEY}").`),
+    }, async (args) => {
+        const { key } = args;
+        const slotKey = key ?? validation_1.PLAYER_STATE_DEFAULT_KEY;
+        try {
+            const result = await handle.executeUpdate(signals_1.clearPlayerStateUpdate, {
+                args: [{ key: slotKey }],
+            });
+            return (0, helpers_1.ok)(result.cleared
+                ? `Cleared slot **"${slotKey}"**.`
+                : `Slot **"${slotKey}"** was already empty.`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to clear state: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

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

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

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

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

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

@@ -0,0 +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;

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

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCoatCheckGetTool = registerCoatCheckGetTool;
+/**
+ * `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
+ * fields, or `null` when the ticket is missing / expired / evicted (no
+ * error-class proliferation for the common "ticket already gone" case).
+ *
+ * Audit identity (`fetchedBy`) is set by the tool layer from `getPlayerId()`
+ * — there is NO `fetchedBy` arg on the MCP schema. The workflow handler
+ * bumps `lastFetchedAt` / `lastFetchedBy` / `fetchCount` on the entry so
+ * the putter can later see whether anyone has redeemed.
+ *
+ * Implemented as a workflow Update (not Query) because the fetch-audit
+ * counters mutate state — Queries cannot mutate.
+ */
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const maestro_signals_1 = require("../workflows/maestro-signals");
+const helpers_1 = require("./helpers");
+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).`);
+            }
+            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)}`);
+        }
+    });
+}

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

@@ -0,0 +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;

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

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCoatCheckListTool = registerCoatCheckListTool;
+/**
+ * `coat_check_list` — list coat-check entry headers (#318, ADR 0008) for
+ * the calling player's ensemble. Read-only — does NOT bump fetch-audit
+ * counters (only an actual `coat_check_get` redemption counts).
+ *
+ * Returns headers (no `content` body) sorted newest-first. Optional
+ * `putBy` / `prefix` / `unfetchedOnly` filters narrow the result.
+ */
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const maestro_signals_1 = require("../workflows/maestro-signals");
+const helpers_1 = require("./helpers");
+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}.`);
+            }
+            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, 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

@@ -0,0 +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;

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerCoatCheckPutTool = registerCoatCheckPutTool;
+/**
+ * `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
+ * later redeem via `coat_check_get` (or pass on a `cue`'s `attachmentTicket`
+ * field so the recipient knows what to fetch).
+ *
+ * Audit identity (`putBy`) is set by the tool layer from `getPlayerId()` —
+ * the MCP schema has NO `playerId` arg, so callers cannot spoof. Same
+ * structural-permission pattern as `save_state` (#334).
+ */
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const maestro_signals_1 = require("../workflows/maestro-signals");
+const helpers_1 = require("./helpers");
+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)}`);
+        }
+    });
+}

package/dist/tools/cue.d.ts

@@ -0,0 +1,44 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+import type { AttachmentPhase } from '../types';
+/**
+ * Build the operator-facing error message when the cue target is in an
+ * undeliverable phase. Lists three actionable next steps per the issue
+ * body's AC #3.
+ *
+ * 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;
+/**
+ * Format the cue tool's "unknown player" error with actionable suggestions.
+ * Exported for direct unit testing — the production path passes the active
+ * player list from `scanEnsembleSessions`.
+ *
+ * The message disambiguates the two common causes per the issue body (#560):
+ *   1. Typo / destroyed player → fuzzy-match suggestion (Levenshtein ≤ 3),
+ *      active-player listing, hint about `recall` for destroyed targets.
+ *   2. Agent-tool sub-agent confusion → explicit note that Claude Code
+ *      `subagent_type:` agents run in the spawner's process and are NOT
+ *      addressable via `cue`; `recruit` is the cross-process surface.
+ *
+ * Returns a multi-line string. Caller wraps in {@link fail}.
+ */
+export declare function formatUnknownPlayerError(target: string, activePlayers: string[]): string;
+/**
+ * Find the closest matching player names by Levenshtein distance.
+ * Returns the top-N nearest within {@link FUZZY_MATCH_MAX_DISTANCE},
+ * sorted by ascending distance then alphabetically. Empty array if no
+ * candidate is close enough.
+ *
+ * Exported for unit testing.
+ */
+export declare function findClosestPlayers(target: string, candidates: string[]): string[];
+/**
+ * Plain Levenshtein edit distance — single-row DP, O(|a| · |b|) time,
+ * O(min) space. No library dependency.
+ *
+ * Exported for unit testing.
+ */
+export declare function levenshtein(a: string, b: string): number;