agent-tempo 1.0.1

package/dist/tools/report.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerReportTool = registerReportTool;
+const zod_1 = require("zod");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+function registerReportTool(server, handle) {
+    (0, helpers_1.defineTool)(server, 'report', 'Send an update to the conductor. Use this to report task completion, blockers, or questions. No-op if no conductor is running.', {
+        text: zod_1.z.string().max(validation_1.MESSAGE_MAX).describe('The report content'),
+        type: zod_1.z.enum(['result', 'blocker', 'question', 'update']).optional()
+            .describe('Type of report: "result" (default, task done), "blocker" (stuck), "question" (need input), "update" (progress update, still working)'),
+    }, async (args) => {
+        const text = args.text;
+        const type = (args.type ?? 'result');
+        try {
+            const entry = {
+                type: 'report',
+                text,
+                reportType: type,
+            };
+            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+            return (0, helpers_1.ok)(`Report sent to conductor: [${type}] ${text} (outbox: ${entryId})`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to send report: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/resolve.d.ts

@@ -0,0 +1 @@
+export { resolveSession } from '../activities/resolve';

package/dist/tools/resolve.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSession = void 0;
+// Re-export from the canonical location.
+// Tools and activities share the same resolveSession implementation.
+var resolve_1 = require("../activities/resolve");
+Object.defineProperty(exports, "resolveSession", { enumerable: true, get: function () { return resolve_1.resolveSession; } });

package/dist/tools/restart.d.ts

@@ -0,0 +1,35 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { Client, WorkflowHandle } from '@temporalio/client';
+import { Config } from '../config';
+export interface RestartToolArgs {
+    playerId: string;
+    host?: string;
+    fresh?: boolean;
+    force?: boolean;
+    contextMessages?: number;
+    confirmStealFromHost?: string;
+    /** #334 PR-2 — see {@link RestartOutboxEntry.loadFromState}. */
+    loadFromState?: boolean | string;
+    /** #334 PR-2 — see {@link RestartOutboxEntry.transcript}. */
+    transcript?: 'suppress' | 'replay';
+}
+/**
+ * Shared `--yes-steal` guard (design §16.5 Option B).
+ *
+ * Returns `null` if the call is allowed, or a user-facing error message
+ * (matching the brief's copy-paste-friendly format) if not. Exported for
+ * the `migrate` CLI command and unit tests.
+ *
+ * Only fires when BOTH:
+ *   - caller passed `force: true`
+ *   - target session currently has an attachment on a host other than ours
+ *
+ * Graceful (non-force) restarts always pass. Non-cross-host force restarts
+ * always pass. Missing `confirmStealFromHost` + mismatched
+ * `confirmStealFromHost` are both rejected with the same copy-paste format.
+ */
+export declare function enforceYesStealGuard(client: Client, ensemble: string, playerId: string, args: {
+    force?: boolean;
+    confirmStealFromHost?: string;
+}, localHostname?: string): Promise<string | null>;
+export declare function registerRestartTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, handle: WorkflowHandle): void;

package/dist/tools/restart.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.enforceYesStealGuard = enforceYesStealGuard;
+exports.registerRestartTool = registerRestartTool;
+/**
+ * `restart` — reap the current attachment, claim a fresh one, spawn a new adapter.
+ *
+ * QA B3: enqueues a `RestartOutboxEntry` on the caller's workflow outbox
+ * rather than running the multi-step §8.2 algorithm inline from tool code.
+ * The session workflow's dispatch loop runs the `deliverRestart` activity on
+ * the target, which owns the full algorithm:
+ *
+ *   graceful `requestDetach` → re-query phase → optional `forceDetach`
+ *   → `claimAttachment` → optional `receiveMessage` context replay
+ *   → `enqueueSpawn` on the target's outbox
+ *
+ * PR-F adds two cross-host pieces:
+ *
+ * 1. `host` param — routes the eventual `spawnProcess` to the
+ *    `agent-tempo-{host}` task queue. Threaded through the existing
+ *    `RestartOutboxEntry.host` → `deliverRestart` activity → `enqueueSpawn`
+ *    update → `SpawnOutboxEntry.targetHostname` → `case 'spawn':`
+ *    dispatcher → `getSpawnProxy(host)` → per-host task queue. All the
+ *    plumbing already exists; this PR just surfaces the input.
+ *
+ * 2. `--yes-steal` guard (design §16.5 Option B) — when `force: true`
+ *    AND the target's current attachment is on a different host, the
+ *    caller must pass `confirmStealFromHost` matching that hostname.
+ *    Client-side only; the workflow trusts the caller (P1 gotcha).
+ *
+ * Durability bonus: mid-algorithm failures surface as ApplicationFailures
+ * and retry per the activity's policy. Design §8.2.
+ */
+const zod_1 = require("zod");
+const os_1 = require("os");
+const signals_1 = require("../workflows/signals");
+const resolve_1 = require("./resolve");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+const DEFAULT_CONTEXT_MESSAGES = 10;
+/**
+ * Shared `--yes-steal` guard (design §16.5 Option B).
+ *
+ * Returns `null` if the call is allowed, or a user-facing error message
+ * (matching the brief's copy-paste-friendly format) if not. Exported for
+ * the `migrate` CLI command and unit tests.
+ *
+ * Only fires when BOTH:
+ *   - caller passed `force: true`
+ *   - target session currently has an attachment on a host other than ours
+ *
+ * Graceful (non-force) restarts always pass. Non-cross-host force restarts
+ * always pass. Missing `confirmStealFromHost` + mismatched
+ * `confirmStealFromHost` are both rejected with the same copy-paste format.
+ */
+async function enforceYesStealGuard(client, ensemble, playerId, args, localHostname = (0, os_1.hostname)()) {
+    if (!args.force)
+        return null;
+    const resolved = await (0, resolve_1.resolveSession)(client, ensemble, playerId);
+    if (!resolved)
+        return null; // No target — downstream enqueue will handle the error.
+    let info;
+    try {
+        info = await resolved.query(signals_1.attachmentInfoQuery);
+    }
+    catch {
+        // If we can't read the phase, let the downstream algorithm handle the
+        // state. Not our job to synthesize cross-host errors here.
+        return null;
+    }
+    const currentHost = info.currentAttachment?.hostname;
+    if (!currentHost || currentHost === localHostname)
+        return null;
+    // Cross-host force-restart detected — demand --yes-steal match.
+    if (!args.confirmStealFromHost) {
+        return (`session "${playerId}" is attached to host "${currentHost}". ` +
+            `To force-restart from there, pass confirmStealFromHost: "${currentHost}". ` +
+            `This safety flag prevents accidental cross-host session takeover.`);
+    }
+    if (args.confirmStealFromHost !== currentHost) {
+        return (`confirmStealFromHost mismatch: session "${playerId}" is on ` +
+            `"${currentHost}", not "${args.confirmStealFromHost}". ` +
+            `Re-run with confirmStealFromHost: "${currentHost}".`);
+    }
+    return null;
+}
+function registerRestartTool(server, client, config, getPlayerId, handle) {
+    (0, helpers_1.defineTool)(server, 'restart', 'Restart a session — reap the current attachment (gracefully, or with force=true), claim a fresh attachment, spawn a new adapter, and optionally replay recent context. Replaces `encore`, `recruit --force`, and `stop`-then-`recruit`. Pass `host` to restart on a different machine; when `force=true` AND the target is currently on a different host, pass `confirmStealFromHost` matching that hostname (design §16.5). Pass `loadFromState` to seed the restarted session from a saved-state slot (#334) instead of (or alongside) transcript replay.', {
+        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to restart'),
+        host: zod_1.z.string().optional().describe('Target host for the new attachment (defaults to the session\'s preferredHost or last-known hostname). When set, the spawn is routed to the per-host task queue `agent-tempo-{host}`.'),
+        fresh: zod_1.z.boolean().optional().describe('Skip context replay — spawn a clean slate (default false)'),
+        force: zod_1.z.boolean().optional().describe('Steal a live attachment via forceDetach (default false; graceful detach is tried first regardless)'),
+        contextMessages: zod_1.z.number().min(0).max(validation_1.RESTART_CONTEXT_MESSAGES_MAX).optional().describe(`Number of recent messages to include in context (default ${DEFAULT_CONTEXT_MESSAGES}, max ${validation_1.RESTART_CONTEXT_MESSAGES_MAX})`),
+        confirmStealFromHost: zod_1.z.string().optional().describe('Required when `force=true` and the target\'s current attachment is on a different host. Must match the hostname currently holding the attachment (design §16.5 Option B).'),
+        // #334 PR-2 — saved-state seed integration.
+        loadFromState: zod_1.z.union([
+            zod_1.z.boolean(),
+            zod_1.z.string().regex(validation_1.PLAYER_STATE_KEY_REGEX).max(validation_1.PLAYER_STATE_KEY_MAX),
+        ]).optional().describe(`Seed the restarted session with a saved-state slot. \`true\` resolves to the default key "${validation_1.PLAYER_STATE_DEFAULT_KEY}"; a string names a specific slot. By default, transcript replay is suppressed when this is set — pass \`transcript: 'replay'\` to stack both. Falls back to transcript replay if the slot is empty.`),
+        transcript: zod_1.z.enum(['suppress', 'replay']).optional().describe('When `loadFromState` is set, controls transcript-replay interaction: `suppress` (default) seeds only the saved state; `replay` seeds the saved state and then replays the recent transcript on top of it. Ignored when `loadFromState` is absent.'),
+    }, async (args) => {
+        const input = args;
+        const nameError = (0, validation_1.validatePlayerName)(input.playerId);
+        if (nameError)
+            return (0, helpers_1.fail)(nameError);
+        // Client-side --yes-steal guard (§16.5). Cross-host force-restart
+        // requires an explicit confirmStealFromHost matching the current holder.
+        const guardError = await enforceYesStealGuard(client, config.ensemble, input.playerId, input);
+        if (guardError)
+            return (0, helpers_1.fail)(guardError);
+        try {
+            const entry = {
+                type: 'restart',
+                targetPlayerId: input.playerId,
+                invokerPlayerId: getPlayerId(),
+                ...(input.host !== undefined ? { host: input.host } : {}),
+                ...(input.fresh !== undefined ? { fresh: input.fresh } : {}),
+                ...(input.force !== undefined ? { force: input.force } : {}),
+                ...(input.contextMessages !== undefined ? { contextMessages: input.contextMessages } : {}),
+                ...(input.loadFromState !== undefined ? { loadFromState: input.loadFromState } : {}),
+                ...(input.transcript !== undefined ? { transcript: input.transcript } : {}),
+            };
+            const entryId = await handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+            return (0, helpers_1.ok)(`Restart queued for **${input.playerId}**${input.host ? ` on ${input.host}` : ''}` +
+                `${input.fresh ? ' (fresh)' : ''}${input.force ? ' (force)' : ''}. (outbox: ${entryId})`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to restart: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/restore.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 registerRestoreTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string): void;

package/dist/tools/restore.js

@@ -0,0 +1,107 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRestoreTool = registerRestoreTool;
+/**
+ * `restore` — ensemble-wide revive (#287).
+ *
+ * Counterpart to `shutdown`:
+ *   1. Reattach every local orphan (delegates to the shared
+ *      `restoreOrphansOnce` helper from `src/reconcile/orphans.ts`, which
+ *      is the same code the daemon runs at boot and the CLI resume flow
+ *      runs on `up` option 2 / `conduct --resume`).
+ *   2. Unpause the maestro + scheduler so new work flows again.
+ *   3. Fan out `setPaused=false` to every session so per-session outbox
+ *      dispatchers (gated on `!paused`) start delivering again. Mirrors
+ *      `play()` and `TempoClient.restore()` — the maestro/scheduler hub
+ *      toggle is necessary but not sufficient: a session that was paused
+ *      via `/pause` keeps its own `paused=true` flag and the outbox loop
+ *      `canDispatch = !outboxLocked && !paused && hasPendingOutbox()`
+ *      silently swallows messages until the per-session flag clears.
+ *
+ * Scope note: conductor-auto-spawn is intentionally NOT handled here
+ * (#287 product decision). MCP tools run inside the daemon worker; opening
+ * a GUI terminal from that context is platform-fragile and surprising for
+ * headless / programmatic callers. The CLI `restore` surface (S4 of #285)
+ * owns terminal spawning where a TTY context is available.
+ */
+const os_1 = require("os");
+const zod_1 = require("zod");
+const orphans_1 = require("../reconcile/orphans");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const ensemble_ops_1 = require("../utils/ensemble-ops");
+const log = (...args) => console.error('[agent-tempo:restore]', ...args);
+function registerRestoreTool(server, client, config, getPlayerId) {
+    (0, helpers_1.defineTool)(server, 'restore', 'Revive the ensemble after `shutdown`: reattach orphaned sessions and unpause the maestro + scheduler. Defaults to scanning the local host; pass `hostname` to target a remote machine in distributed setups (per-host task queues). Does NOT spawn a conductor terminal — use the CLI for that.', {
+        // #306 follow-up: cross-host restore. The default (omitted) preserves
+        // the original behavior — scan the local daemon's host. When supplied,
+        // we route the orphan-visibility query against the named host's
+        // `AgentTempoAttachedHost`/`AgentTempoHostname` search attributes,
+        // so an operator on host A can revive sessions parked on host B.
+        // Surfaced from my own #306 review (regression risk #2): "MCP
+        // restore hard-codes hostname: osHostname() — won't see orphans on
+        // other hosts in distributed setups."
+        hostname: zod_1.z.string().min(1).max(253).optional().describe('Target host whose orphans should be restored. Defaults to the local OS hostname. Use this when the conductor / TUI is on a different machine than the workers that owned the parked sessions.'),
+    }, async (args) => {
+        const { hostname: explicitHostname } = args;
+        const targetHostname = explicitHostname ?? (0, os_1.hostname)();
+        try {
+            let summary;
+            try {
+                summary = await (0, orphans_1.restoreOrphansOnce)(client, {
+                    hostname: targetHostname,
+                    invokerPlayerId: getPlayerId(),
+                    policy: 'auto',
+                    // #306: narrow to detached-only so a live attached/processing
+                    // session is never flagged as an orphan by user-invoked
+                    // `/restore`. Daemon reconcile-on-boot + CLI `up --resume`
+                    // keep the broad live-phase default (no PID memory after
+                    // crash → must treat every live phase as presumed orphan).
+                    phases: ['detached'],
+                }, log);
+            }
+            catch (err) {
+                return (0, helpers_1.fail)(`Failed to scan for orphans: ${(0, helpers_1.formatError)(err)}`);
+            }
+            // Maestro/scheduler hub unpause + per-session `setPaused=false`
+            // fan-out run in parallel — independent calls and a slow session
+            // shouldn't gate the hub toggle (or vice-versa).
+            const [toggle, sessions] = await Promise.all([
+                (0, ensemble_ops_1.unpauseMaestroAndScheduler)(client, config.ensemble),
+                (0, ensemble_ops_1.signalAllSessions)(client, config.ensemble, signals_1.setPausedSignal.name, false),
+            ]);
+            const hostSuffix = explicitHostname !== undefined
+                ? ` (host: ${explicitHostname})`
+                : '';
+            const lines = [
+                `Ensemble **${config.ensemble}** restored${hostSuffix}.`,
+                `${summary.reattached} reattached, ${summary.skipped} skipped, ${summary.failed} failed`,
+            ];
+            if (summary.details.length > 0) {
+                lines.push(...summary.details.map((d) => `  - ${d.playerId} (${d.ensemble}): ${(0, orphans_1.formatRestoreOutcome)(d.outcome)}`));
+            }
+            if (sessions.sent > 0) {
+                lines.push(`${sessions.sent} session(s) resumed`);
+            }
+            const unpausedBits = [];
+            if (toggle.maestro)
+                unpausedBits.push('maestro');
+            if (toggle.scheduler)
+                unpausedBits.push('scheduler');
+            if (unpausedBits.length > 0)
+                lines.push(`Unpaused: ${unpausedBits.join(', ')}`);
+            if (sessions.failed > 0) {
+                const errs = sessions.perSession
+                    .filter((p) => p.outcome === 'failed')
+                    .map((p) => `  - ${p.playerId}: ${'error' in p ? p.error : ''}`);
+                lines.push(`Errors:\n${errs.join('\n')}`);
+            }
+            log(`Restore by ${getPlayerId()} in "${config.ensemble}" on host "${targetHostname}": ` +
+                `${summary.reattached}/${summary.skipped}/${summary.failed}`);
+            return (0, helpers_1.ok)(lines.join('\n'));
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to restore ensemble: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/resume-ensemble.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 registerResumeEnsembleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string): void;

package/dist/tools/resume-ensemble.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerResumeEnsembleTool = registerResumeEnsembleTool;
+const zod_1 = require("zod");
+const config_1 = require("../config");
+const resolve_1 = require("../activities/resolve");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const log = (...args) => console.error('[claude-tempo:resume]', ...args);
+function registerResumeEnsembleTool(server, client, config, getPlayerId) {
+    (0, helpers_1.defineTool)(server, 'resume_ensemble', 'Resume all paused sessions in the ensemble — unlocks outbox dispatch and resumes the scheduler. Buffered outbox entries will be dispatched. Pass `release: true` to also release any held sessions (deliver deferred task messages and unlock their outboxes) in the same call.', {
+        release: zod_1.z.boolean().optional().describe('Also release any held sessions (deliver deferred task messages and unlock outboxes). Safe to call when no sessions are held — it is a no-op on those. Default: false.'),
+    }, async (args) => {
+        const release = args.release === true;
+        try {
+            const results = [];
+            const errors = [];
+            // 1. Signal maestro with unpaused state (ground truth)
+            try {
+                const maestroId = (0, config_1.maestroWorkflowId)(config.ensemble);
+                const maestroHandle = client.workflow.getHandle(maestroId);
+                await maestroHandle.signal('maestroSetPaused', false);
+                results.push('maestro resumed');
+            }
+            catch {
+                // Maestro may not be running
+            }
+            // 2. Signal all active sessions — unpause, and release held ones if opted in.
+            // `releaseHeld` is idempotent on sessions that aren't holding (no heldMessage,
+            // outboxLocked: false already), so it's safe to fan out unconditionally when
+            // `release: true`. See `src/workflows/session.ts` releaseHeldSignal handler.
+            const sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
+            let sessionCount = 0;
+            let releasedCount = 0;
+            for (const session of sessions) {
+                try {
+                    const sessionHandle = client.workflow.getHandle(session.workflowId);
+                    await sessionHandle.signal('setPaused', false);
+                    sessionCount++;
+                    if (release) {
+                        try {
+                            await sessionHandle.signal(signals_1.releaseHeldSignal);
+                            releasedCount++;
+                        }
+                        catch (err) {
+                            errors.push(`${session.playerId} release: ${(0, helpers_1.formatError)(err)}`);
+                        }
+                    }
+                }
+                catch (err) {
+                    errors.push(`${session.playerId}: ${(0, helpers_1.formatError)(err)}`);
+                }
+            }
+            results.push(`${sessionCount} session(s) resumed`);
+            if (release) {
+                results.push(`${releasedCount} session(s) signalled for release`);
+            }
+            // 3. Signal scheduler
+            try {
+                const schedulerId = (0, config_1.schedulerWorkflowId)(config.ensemble);
+                const schedulerHandle = client.workflow.getHandle(schedulerId);
+                await schedulerHandle.signal('setSchedulerPaused', false);
+                results.push('scheduler resumed');
+            }
+            catch {
+                // Scheduler may not be running
+            }
+            const lines = [`Ensemble **${config.ensemble}** resumed.`, results.join(', ')];
+            if (errors.length > 0) {
+                lines.push(`Errors:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+            }
+            log(`Resumed ensemble "${config.ensemble}" by ${getPlayerId()}${release ? ' (with release)' : ''}`);
+            return (0, helpers_1.ok)(lines.join('\n'));
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to resume ensemble: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/save-lineup.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 registerSaveLineupTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string, isConductor: boolean): void;

package/dist/tools/save-lineup.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSaveLineupTool = registerSaveLineupTool;
+const zod_1 = require("zod");
+const saver_1 = require("../ensemble/saver");
+const safe_path_1 = require("../utils/safe-path");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+const log = (...args) => console.error('[agent-tempo:save-lineup]', ...args);
+function registerSaveLineupTool(server, client, config, getPlayerId, isConductor) {
+    (0, helpers_1.defineTool)(server, 'save_lineup', 'Save the current ensemble state as a YAML lineup. Only available to the conductor.', {
+        name: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('Lineup name (defaults to ensemble name)'),
+        path: zod_1.z.string().max(validation_1.PATH_MAX).optional().describe('Explicit file path to save to'),
+    }, async (args) => {
+        if (!isConductor) {
+            return (0, helpers_1.fail)('Only the conductor can save ensemble lineups.');
+        }
+        const lineupName = args.name;
+        const filePath = args.path;
+        try {
+            // Validate user-supplied path if provided
+            let validatedPath = filePath;
+            if (validatedPath) {
+                validatedPath = (0, safe_path_1.safeLineupPath)(validatedPath, process.cwd());
+            }
+            // Pass lineupName as optional name override for the output filename.
+            // If no name or path is provided, saveLineup defaults to ensemble name.
+            const outputPath = await (0, saver_1.saveLineup)(client, config.ensemble, validatedPath, lineupName);
+            log(`Saved lineup to ${outputPath}`);
+            return (0, helpers_1.ok)(`Ensemble lineup saved to **${outputPath}**.`);
+        }
+        catch (err) {
+            return (0, helpers_1.fail)(`Failed to save ensemble: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

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

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

package/dist/tools/save-state.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerSaveStateTool = registerSaveStateTool;
+/**
+ * `save_state` — write a curated artifact to one of the calling player's
+ * saveable-state slots (#334 PR-1, ADR 0011).
+ *
+ * Owner-only by structure: there is no `playerId` arg — the tool always
+ * writes through the calling player's own session-workflow handle, so
+ * the workflow doesn't need an authorisation layer. The `savedBy` field
+ * captures the calling player's id as the audit identity.
+ *
+ * The tool docstring nudges the LLM toward a markdown structure
+ * (Current task / Findings / Next steps / Open questions) but the schema
+ * itself is opaque — no enforced typing.
+ */
+const zod_1 = require("zod");
+const signals_1 = require("../workflows/signals");
+const helpers_1 = require("./helpers");
+const validation_1 = require("../utils/validation");
+function registerSaveStateTool(server, handle, getPlayerId) {
+    (0, helpers_1.defineTool)(server, 'save_state', `Save curated state for yourself into a named slot — a peer can later read it via \`fetch_state\`, and a future restart can seed itself from this artifact instead of replaying the transcript.
+
+Recommended structure (markdown, not enforced):
+
+  ## Current task
+  ...
+  ## Findings
+  ...
+  ## Next steps
+  ...
+  ## Open questions
+  ...
+
+Limits: ${validation_1.PLAYER_STATE_CONTENT_MAX} bytes per slot, max ${validation_1.PLAYER_STATE_SLOTS_MAX} slots per player. Slot key defaults to "${validation_1.PLAYER_STATE_DEFAULT_KEY}". When all ${validation_1.PLAYER_STATE_SLOTS_MAX} slots are full, saving a new key fails with \`PlayerStateSlotsFull\` — call \`clear_state\` to free a slot.`, {
+        content: zod_1.z.string().min(1).max(validation_1.PLAYER_STATE_CONTENT_MAX).describe(`The state content — markdown encouraged, opaque to the system. Max ${validation_1.PLAYER_STATE_CONTENT_MAX} bytes (UTF-8).`),
+        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}"). Alphanumeric + underscore + hyphen, max ${validation_1.PLAYER_STATE_KEY_MAX} chars.`),
+    }, async (args) => {
+        const { content, key } = args;
+        const slotKey = key ?? validation_1.PLAYER_STATE_DEFAULT_KEY;
+        const savedBy = getPlayerId();
+        try {
+            const result = await handle.executeUpdate(signals_1.savePlayerStateUpdate, {
+                args: [{ key: slotKey, content, savedBy }],
+            });
+            return (0, helpers_1.ok)(`Saved to slot **"${slotKey}"** at ${result.savedAt}.`);
+        }
+        catch (err) {
+            // The workflow validator surfaces structured ApplicationFailure errors
+            // (`PlayerStateSlotsFull`, `PlayerStateContentTooLarge`,
+            // `PlayerStateInvalidKey`). The `formatError` message preserves the
+            // workflow-supplied text so the LLM sees the existing-keys list and
+            // can pick which slot to clear.
+            return (0, helpers_1.fail)(`Failed to save state: ${(0, helpers_1.formatError)(err)}`);
+        }
+    });
+}

package/dist/tools/schedule.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 registerScheduleTool(server: McpServer, client: Client, config: Config, getPlayerId: () => string): void;