agent-tempo 2.0.0-beta.1 → 2.0.0-beta.2

package/dist/observability/nondeterminism-alarm.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Nondeterminism alarm (#886 slice 1).
+ *
+ * The #801 incident produced **57 workflow-task failures in 3 minutes with
+ * ZERO operator signal** — a nondeterminism flap (a 2.0 worker replaying a
+ * 1.x-recorded history, or a code/bundle skew) surfaces only as Temporal's
+ * own `WARN`-level Core log line, buried in `daemon.log` among normal chatter.
+ * Nothing NAMED the flap, counted it, or raised its severity.
+ *
+ * This module gives the daemon a tiny, process-global counter that:
+ *   1. Intercepts Temporal Runtime log records (via {@link wrapLoggerWithAlarm},
+ *      installed in the daemon's `Runtime.install({ logger })`).
+ *   2. Classifies nondeterminism / determinism-violation records
+ *      ({@link isNondeterminismLog}) — wording-tolerant, like the SA-preflight
+ *      marker set, so a Core/SDK phrasing change can't silently disarm it.
+ *   3. PROMOTES each hit to a prominent, greppable `[agent-tempo:ALARM]` line
+ *      with a running count — so a flap is named the instant it starts.
+ *   4. Keeps a small rolling snapshot ({@link NondeterminismAlarm.snapshot})
+ *      surfaced on `GET /v1/health` so external monitors / the dashboard can
+ *      poll the alarm state without scraping logs.
+ *
+ * **Temporal-VALUE-free by design:** this module imports only the `Logger`
+ * TYPE from `@temporalio/common` (erased at compile). The worker `Runtime` /
+ * `DefaultLogger` VALUES are imported by the daemon, which wraps a real logger
+ * with {@link wrapLoggerWithAlarm} and installs it. That keeps the HTTP layer
+ * (`/v1/health`) able to read {@link getGlobalNondeterminismAlarm} without
+ * pulling `@temporalio/worker` into the HTTP module graph.
+ *
+ * NOTE: daemon-side observability code — NOT workflow code — so `Date`/clocks
+ * are fine here; `now` is injected purely for deterministic unit tests.
+ */
+import type { Logger, LogMetadata } from '@temporalio/common';
+/**
+ * Substrings (matched case-insensitively against the log message) that mark a
+ * nondeterminism / determinism-violation record. A SET rather than one phrase
+ * because the exact wording varies across Core (Rust) and SDK (JS) sources and
+ * versions — `DeterminismViolationError` surfaces "Replay failed with a
+ * nondeterminism error", Core forwards a `WARN` referencing nondeterminism, and
+ * Temporal surfaces the incident class under the `TMPRL1100` code. Matching a
+ * set keeps the alarm armed across phrasing drift (same rationale as
+ * `UNREGISTERED_SA_MARKERS` in `sa-preflight.ts`).
+ */
+export declare const NONDETERMINISM_MARKERS: readonly string[];
+/** A single recorded nondeterminism hit (most-recent-N kept by the alarm). */
+export interface NondeterminismSample {
+    /** ISO timestamp of the hit. */
+    at: string;
+    /** Best-effort detail: workflow type / id from log meta + a message snippet. */
+    detail: string;
+}
+/** Pollable alarm state — embedded in `GET /v1/health` (`HealthV1.nondeterminism`). */
+export interface NondeterminismAlarmSnapshot {
+    /** Total nondeterminism records seen since daemon boot. */
+    count: number;
+    /** ISO timestamp of the first hit, or `undefined` when count === 0. */
+    firstSeenAt?: string;
+    /** ISO timestamp of the most recent hit, or `undefined` when count === 0. */
+    lastSeenAt?: string;
+    /** Most-recent samples (capped), newest last. */
+    recent: NondeterminismSample[];
+}
+export interface NondeterminismAlarmOpts {
+    /** Injectable clock (epoch ms) — defaults to `Date.now`. Test seam only. */
+    now?: () => number;
+    /**
+     * Promotion sink — invoked on EVERY hit with the running count + sample, so
+     * the daemon can emit the prominent `[agent-tempo:ALARM]` line. Defaults to a
+     * no-op; the daemon passes a `console.error`-backed promoter. Kept injectable
+     * so unit tests can assert promotion without capturing stderr.
+     */
+    onHit?: (count: number, sample: NondeterminismSample) => void;
+}
+/**
+ * Process-global nondeterminism counter. One per daemon. Records hits, promotes
+ * each, and exposes a rolling snapshot.
+ */
+export declare class NondeterminismAlarm {
+    private _count;
+    private _firstSeenAt?;
+    private _lastSeenAt?;
+    private readonly _recent;
+    private readonly now;
+    private readonly onHit;
+    constructor(opts?: NondeterminismAlarmOpts);
+    /** Record one nondeterminism hit from a log record. */
+    record(message: string, meta?: LogMetadata): void;
+    /** Current count (total hits since boot). */
+    get count(): number;
+    /** Immutable snapshot for `/v1/health`. */
+    snapshot(): NondeterminismAlarmSnapshot;
+}
+/**
+ * True when a log record (its message) signals a nondeterminism / determinism
+ * violation. Case-insensitive substring match over {@link NONDETERMINISM_MARKERS}.
+ */
+export declare function isNondeterminismLog(message: string, _meta?: LogMetadata): boolean;
+/**
+ * Wrap a base {@link Logger} so every record still flows to `base`, but any
+ * `WARN`/`ERROR` record matching {@link isNondeterminismLog} also feeds the
+ * alarm. Transparent: trace/debug/info pass straight through; warn/error/log are
+ * classified first, then forwarded unchanged.
+ *
+ * Only `WARN`/`ERROR` are inspected — a nondeterminism failure is always logged
+ * at one of those levels, and ignoring lower levels avoids a hot classifier on
+ * the (high-volume) debug/trace path.
+ */
+export declare function wrapLoggerWithAlarm(base: Logger, alarm: NondeterminismAlarm): Logger;
+/** Set the process-global alarm (daemon boot only). */
+export declare function setGlobalNondeterminismAlarm(alarm: NondeterminismAlarm): void;
+/** Read the process-global alarm, or `undefined` if not installed (e.g. tests, non-daemon). */
+export declare function getGlobalNondeterminismAlarm(): NondeterminismAlarm | undefined;
+/** Test seam — reset the singleton between unit tests. */
+export declare function __resetGlobalNondeterminismAlarmForTests(): void;

package/dist/observability/nondeterminism-alarm.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NondeterminismAlarm = exports.NONDETERMINISM_MARKERS = void 0;
+exports.isNondeterminismLog = isNondeterminismLog;
+exports.wrapLoggerWithAlarm = wrapLoggerWithAlarm;
+exports.setGlobalNondeterminismAlarm = setGlobalNondeterminismAlarm;
+exports.getGlobalNondeterminismAlarm = getGlobalNondeterminismAlarm;
+exports.__resetGlobalNondeterminismAlarmForTests = __resetGlobalNondeterminismAlarmForTests;
+/**
+ * Substrings (matched case-insensitively against the log message) that mark a
+ * nondeterminism / determinism-violation record. A SET rather than one phrase
+ * because the exact wording varies across Core (Rust) and SDK (JS) sources and
+ * versions — `DeterminismViolationError` surfaces "Replay failed with a
+ * nondeterminism error", Core forwards a `WARN` referencing nondeterminism, and
+ * Temporal surfaces the incident class under the `TMPRL1100` code. Matching a
+ * set keeps the alarm armed across phrasing drift (same rationale as
+ * `UNREGISTERED_SA_MARKERS` in `sa-preflight.ts`).
+ */
+exports.NONDETERMINISM_MARKERS = Object.freeze([
+    'nondetermin',
+    'non-determin',
+    'determinismviolation',
+    'tmprl1100',
+]);
+/** Max recent samples retained for the `/v1/health` snapshot. */
+const RECENT_CAP = 10;
+/** Max message characters kept per sample (logs can be long stack-y blobs). */
+const DETAIL_SNIPPET_MAX = 200;
+/**
+ * Process-global nondeterminism counter. One per daemon. Records hits, promotes
+ * each, and exposes a rolling snapshot.
+ */
+class NondeterminismAlarm {
+    _count = 0;
+    _firstSeenAt;
+    _lastSeenAt;
+    _recent = [];
+    now;
+    onHit;
+    constructor(opts = {}) {
+        this.now = opts.now ?? (() => Date.now());
+        this.onHit = opts.onHit ?? (() => { });
+    }
+    /** Record one nondeterminism hit from a log record. */
+    record(message, meta) {
+        const at = new Date(this.now()).toISOString();
+        this._count += 1;
+        if (this._firstSeenAt === undefined)
+            this._firstSeenAt = at;
+        this._lastSeenAt = at;
+        const sample = { at, detail: buildDetail(message, meta) };
+        this._recent.push(sample);
+        if (this._recent.length > RECENT_CAP)
+            this._recent.shift();
+        // Promote — fire the prominent, greppable alarm line (the whole point: the
+        // #801 flap produced zero operator signal). Never let a throwing sink eat
+        // the count.
+        try {
+            this.onHit(this._count, sample);
+        }
+        catch {
+            /* a broken promoter must not disarm the counter */
+        }
+    }
+    /** Current count (total hits since boot). */
+    get count() {
+        return this._count;
+    }
+    /** Immutable snapshot for `/v1/health`. */
+    snapshot() {
+        return {
+            count: this._count,
+            ...(this._firstSeenAt !== undefined ? { firstSeenAt: this._firstSeenAt } : {}),
+            ...(this._lastSeenAt !== undefined ? { lastSeenAt: this._lastSeenAt } : {}),
+            recent: this._recent.slice(),
+        };
+    }
+}
+exports.NondeterminismAlarm = NondeterminismAlarm;
+/** Build the best-effort sample detail from log meta + a message snippet. */
+function buildDetail(message, meta) {
+    const bits = [];
+    const wfType = meta?.['workflowType'];
+    const wfId = meta?.['workflowId'];
+    const runId = meta?.['runId'];
+    if (typeof wfType === 'string')
+        bits.push(`workflowType=${wfType}`);
+    if (typeof wfId === 'string')
+        bits.push(`workflowId=${wfId}`);
+    if (typeof runId === 'string')
+        bits.push(`runId=${runId}`);
+    const snippet = (message ?? '').slice(0, DETAIL_SNIPPET_MAX);
+    bits.push(snippet);
+    return bits.join(' · ');
+}
+/**
+ * True when a log record (its message) signals a nondeterminism / determinism
+ * violation. Case-insensitive substring match over {@link NONDETERMINISM_MARKERS}.
+ */
+function isNondeterminismLog(message, _meta) {
+    if (!message)
+        return false;
+    const m = message.toLowerCase();
+    return exports.NONDETERMINISM_MARKERS.some((marker) => m.includes(marker));
+}
+/**
+ * Wrap a base {@link Logger} so every record still flows to `base`, but any
+ * `WARN`/`ERROR` record matching {@link isNondeterminismLog} also feeds the
+ * alarm. Transparent: trace/debug/info pass straight through; warn/error/log are
+ * classified first, then forwarded unchanged.
+ *
+ * Only `WARN`/`ERROR` are inspected — a nondeterminism failure is always logged
+ * at one of those levels, and ignoring lower levels avoids a hot classifier on
+ * the (high-volume) debug/trace path.
+ */
+function wrapLoggerWithAlarm(base, alarm) {
+    const consider = (level, message, meta) => {
+        if ((level === 'WARN' || level === 'ERROR') && isNondeterminismLog(message, meta)) {
+            alarm.record(message, meta);
+        }
+    };
+    return {
+        log(level, message, meta) {
+            consider(level, message, meta);
+            base.log(level, message, meta);
+        },
+        trace(message, meta) {
+            base.trace(message, meta);
+        },
+        debug(message, meta) {
+            base.debug(message, meta);
+        },
+        info(message, meta) {
+            base.info(message, meta);
+        },
+        warn(message, meta) {
+            consider('WARN', message, meta);
+            base.warn(message, meta);
+        },
+        error(message, meta) {
+            consider('ERROR', message, meta);
+            base.error(message, meta);
+        },
+    };
+}
+// ── Process singleton ───────────────────────────────────────────────────────
+// The daemon installs ONE alarm at boot; `/v1/health` reads it without
+// threading a reference through the HTTP server constructor (and without
+// importing `@temporalio/worker` into the HTTP layer).
+let globalAlarm;
+/** Set the process-global alarm (daemon boot only). */
+function setGlobalNondeterminismAlarm(alarm) {
+    globalAlarm = alarm;
+}
+/** Read the process-global alarm, or `undefined` if not installed (e.g. tests, non-daemon). */
+function getGlobalNondeterminismAlarm() {
+    return globalAlarm;
+}
+/** Test seam — reset the singleton between unit tests. */
+function __resetGlobalNondeterminismAlarmForTests() {
+    globalAlarm = undefined;
+}

package/dist/server-tools.js

@@ -11,9 +11,8 @@ const listen_1 = require("./tools/listen");
 const recruit_1 = require("./tools/recruit");
 const report_1 = require("./tools/report");
 const set_name_1 = require("./tools/set-name");
+// #793 — canonical `schedule` (action create|cancel|list) + unschedule/schedules aliases.
 const schedule_1 = require("./tools/schedule");
-const unschedule_1 = require("./tools/unschedule");
-const schedules_1 = require("./tools/schedules");
 const save_lineup_1 = require("./tools/save-lineup");
 const load_lineup_1 = require("./tools/load-lineup");
 const agent_types_1 = require("./tools/agent-types");
@@ -25,13 +24,13 @@ const pause_1 = require("./tools/pause");
 const play_1 = require("./tools/play");
 const shutdown_1 = require("./tools/shutdown");
 const restore_1 = require("./tools/restore");
-const quality_gate_1 = require("./tools/quality-gate");
+// #793 — canonical `gate` (action define|list) + quality_gate/gates aliases.
+// `evaluate_gate` stays a SEPARATE tool (partial merge — runtime op, not CRUD).
+const gate_1 = require("./tools/gate");
 const evaluate_gate_1 = require("./tools/evaluate-gate");
-const gates_1 = require("./tools/gates");
 const worktree_1 = require("./tools/worktree");
+// #793 — canonical `stage` (action create|list|cancel) + stages/cancel_stage aliases.
 const stage_1 = require("./tools/stage");
-const stages_1 = require("./tools/stages");
-const cancel_stage_1 = require("./tools/cancel-stage");
 const restart_1 = require("./tools/restart");
 const destroy_1 = require("./tools/destroy");
 const reset_1 = require("./tools/reset");
@@ -39,15 +38,12 @@ const migrate_1 = require("./tools/migrate");
 const attachment_info_1 = require("./tools/attachment-info");
 const hosts_1 = require("./tools/hosts");
 const set_ensemble_description_1 = require("./tools/set-ensemble-description");
-// #334 PR-1 — player saveable state (save_state / fetch_state / clear_state).
-const save_state_1 = require("./tools/save-state");
-const fetch_state_1 = require("./tools/fetch-state");
-const clear_state_1 = require("./tools/clear-state");
-// #318 — ensemble-shared coat-check (put / get / list / evict).
-const coat_check_put_1 = require("./tools/coat-check-put");
-const coat_check_get_1 = require("./tools/coat-check-get");
-const coat_check_list_1 = require("./tools/coat-check-list");
-const coat_check_evict_1 = require("./tools/coat-check-evict");
+// #334 PR-1 / #793 — canonical `state` (action save|fetch|clear) + save_state/
+// fetch_state/clear_state aliases.
+const state_1 = require("./tools/state");
+// #318 / #793 — canonical `coat_check` (action put|get|list|evict) +
+// coat_check_put/get/list/evict aliases.
+const coat_check_1 = require("./tools/coat-check");
 const respond_1 = require("./tools/respond");
 /**
  * Register every tempo MCP tool onto `server`. Single source of truth — the
@@ -69,9 +65,10 @@ function buildAllTempoTools(opts) {
         (0, listen_1.buildListenTool)(handle),
         (0, recruit_1.buildRecruitTool)(client, config, getPlayerId, handle, ownAgentType, defaultAgentSource),
         (0, report_1.buildReportTool)(handle),
+        // #793 — canonical `schedule` (action defaults to "create") + legacy
+        // unschedule/schedules forwarding aliases.
         (0, schedule_1.buildScheduleTool)(client, config, getPlayerId),
-        (0, unschedule_1.buildUnscheduleTool)(client, config),
-        (0, schedules_1.buildSchedulesTool)(client, config),
+        ...(0, schedule_1.buildScheduleAliasTools)(client, config),
         (0, save_lineup_1.buildSaveLineupTool)(client, config, getPlayerId, isConductor),
         (0, load_lineup_1.buildLoadLineupTool)(client, config, getPlayerId, ownAgentType, handle, setPlayerId, isConductor),
         (0, agent_types_1.buildAgentTypesTool)(),
@@ -90,23 +87,27 @@ function buildAllTempoTools(opts) {
         (0, attachment_info_1.buildAttachmentInfoTool)(client, config),
         (0, hosts_1.buildHostsTool)(client, config),
         (0, set_ensemble_description_1.buildSetEnsembleDescriptionTool)(client, config),
-        // #334 PR-1 — owner-write / peer-read player saveable state.
-        (0, save_state_1.buildSaveStateTool)(handle, getPlayerId),
-        (0, fetch_state_1.buildFetchStateTool)(client, config, handle, getPlayerId),
-        (0, clear_state_1.buildClearStateTool)(handle),
-        // #318 — ensemble-shared coat-check (put/get/list/evict). Any player can put;
-        // any player can get/list; owner-or-conductor can evict. Audit identity is
-        // set at the tool layer via getPlayerId() — no playerId arg on any schema.
-        (0, coat_check_put_1.buildCoatCheckPutTool)(client, config, getPlayerId),
-        (0, coat_check_get_1.buildCoatCheckGetTool)(client, config, getPlayerId),
-        (0, coat_check_list_1.buildCoatCheckListTool)(client, config),
-        (0, coat_check_evict_1.buildCoatCheckEvictTool)(client, config, getPlayerId),
+        // #334 PR-1 / #793 — canonical `state` (owner-write / peer-read) + legacy
+        // save_state/fetch_state/clear_state forwarding aliases.
+        (0, state_1.buildStateTool)(client, config, handle, getPlayerId),
+        ...(0, state_1.buildStateAliasTools)(client, config, handle, getPlayerId),
+        // #318 / #793 — canonical `coat_check` (put/get/list/evict) + legacy
+        // coat_check_* forwarding aliases. Any player can put/get/list;
+        // owner-or-conductor can evict. Audit identity is set at the tool layer via
+        // getPlayerId() — no playerId arg on any schema.
+        (0, coat_check_1.buildCoatCheckTool)(client, config, getPlayerId),
+        ...(0, coat_check_1.buildCoatCheckAliasTools)(client, config, getPlayerId),
         // #700 P2 — answer a planner's correlated `[Q <id>]` question (writes the
         // maestro Q&A mailbox directly; from = getPlayerId(), no spoofable arg).
         (0, respond_1.buildRespondTool)(client, config, getPlayerId),
     ];
     if (isConductor) {
-        tools.push((0, quality_gate_1.buildQualityGateTool)(handle, getPlayerId), (0, evaluate_gate_1.buildEvaluateGateTool)(handle, getPlayerId), (0, gates_1.buildGatesTool)(handle), (0, worktree_1.buildWorktreeTool)(client, config, handle, getPlayerId), (0, stage_1.buildStageTool)(handle, getPlayerId), (0, stages_1.buildStagesTool)(handle), (0, cancel_stage_1.buildCancelStageTool)(handle));
+        tools.push(
+        // #793 — canonical `gate` (define|list) + quality_gate/gates aliases.
+        // `evaluate_gate` stays a separate tool (partial-merge boundary).
+        (0, gate_1.buildGateTool)(handle, getPlayerId), (0, evaluate_gate_1.buildEvaluateGateTool)(handle, getPlayerId), ...(0, gate_1.buildGateAliasTools)(handle, getPlayerId), (0, worktree_1.buildWorktreeTool)(client, config, handle, getPlayerId), 
+        // #793 — canonical `stage` (create|list|cancel) + stages/cancel_stage aliases.
+        (0, stage_1.buildStageTool)(handle, getPlayerId), ...(0, stage_1.buildStageAliasTools)(handle));
     }
     return tools;
 }

package/dist/server.js

@@ -59,6 +59,7 @@ const parent_death_watchdog_1 = require("./utils/parent-death-watchdog");
 const grpc_shutdown_guard_1 = require("./utils/grpc-shutdown-guard");
 const action_counters_1 = require("./utils/action-counters");
 const search_attributes_1 = require("./utils/search-attributes");
+const orphan_guard_1 = require("./utils/orphan-guard");
 const log = (...args) => console.error('[agent-tempo]', ...args);
 async function main() {
     (0, parent_death_watchdog_1.installParentDeathWatchdog)();
@@ -157,6 +158,12 @@ async function main() {
             isConductor,
             agentType: isBridgeMode ? 'copilot' : 'claude',
             adapterId,
+            // #704 — thread the adapter descriptor's dialog-blocking property onto
+            // durable metadata so the session workflow can ARM/DISARM the booting
+            // watchdog without importing the client-side registry. This self-bootstrap
+            // path is interactive `claude-code` (or the Copilot bridge), so it resolves
+            // to disarmed; recruited headless sessions arm via `startRecruitedSession`.
+            canBlockOnDialog: adapterDescriptor?.canBlockOnDialog === true,
         },
         // Issue #450 — self-bootstrap path has no resolved player type, so
         // this falls through to `'Conductor session'` for conductors and
@@ -170,6 +177,41 @@ async function main() {
             taskQueue: config.taskQueue,
         },
     };
+    // #704 Item 1b — late-orphan self-tombstone guard. A recruited process can
+    // launch LONG after its recruit was cancelled (slow / wedged cold start). If
+    // this derived id's latest run is CLOSED with a destroy / boot-timeout tombstone
+    // MEMO and NO newer RUNNING run exists, this process is that orphan — exit before
+    // `start(USE_EXISTING)` bootstraps a brand-new run that collides with whoever took
+    // over the worktree. The running-run × close-reason PAIR is the discriminator:
+    // every managed re-creation (recruit / restart / migrate / up) pre-creates a
+    // RUNNING run, so a legit reuse is seen as RUNNING and simply attaches — it never
+    // reaches this branch. Gated `!isConductor` (conductors are operator-driven via
+    // `up`, never a recruited orphan). A generous wall-clock TTL bounds a stale
+    // tombstone so a much-later legit manual reuse of the same name isn't blocked
+    // forever (observed orphan delay ~100min; default 6h, env-overridable).
+    if (!isConductor) {
+        const ttlMsRaw = Number(process.env[config_1.ENV.ORPHAN_TOMBSTONE_TTL_MS]);
+        const orphanTombstoneTtlMs = Number.isFinite(ttlMsRaw) && ttlMsRaw > 0 ? ttlMsRaw : 6 * 60 * 60 * 1000;
+        try {
+            const desc = await client.workflow.getHandle(workflowId).describe();
+            const closeReason = desc.memo?.[search_attributes_1.MEMO_KEYS.closeReason];
+            const orphan = (0, orphan_guard_1.shouldSelfExitAsOrphan)({
+                statusName: desc.status.name,
+                closeReason,
+                closeTimeMs: desc.closeTime ? desc.closeTime.getTime() : 0,
+            }, orphanTombstoneTtlMs, Date.now());
+            if (orphan) {
+                log(`recruit was cancelled (close-reason: ${closeReason}) — exiting to avoid ` +
+                    `re-registering an orphan session for ${workflowId}`);
+                process.exit(0);
+            }
+        }
+        catch {
+            // No prior run (NotFound) → first-ever start for this id → proceed. Any other
+            // describe() failure is non-fatal: the guard is a best-effort backstop, not a
+            // correctness gate — fall through and let the start proceed.
+        }
+    }
     const startedHandle = await client.workflow.start('agentSessionWorkflow', {
         workflowId,
         taskQueue: config.taskQueue,

package/dist/tools/action-guard.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Per-action runtime field guard for the canonical multi-action tools (#793).
+ *
+ * The tool-family merge (#793) collapses each family into one canonical tool
+ * with a flat `{ action, ...per-action optional fields }` param shape. Because
+ * the union makes every per-action field optional at the zod boundary (we do
+ * NOT use `z.discriminatedUnion` — see docs/design/793-tool-family-merge-brief.md
+ * §2), cross-field "this action requires that field" rules are enforced at
+ * RUNTIME inside the handler, before dispatch.
+ *
+ * {@link firstMissing} returns the first required field that is absent so the
+ * handler can return a friendly, actionable `fail(...)` message naming the
+ * exact tool, action, and field — instead of a cryptic downstream error.
+ */
+/**
+ * Return the first field name in `fields` whose value in `args` is "missing"
+ * (`undefined`, `null`, or an empty string), or `null` when all are present.
+ *
+ * Empty-string counts as missing so a canonical handler rejects e.g.
+ * `coat_check{action:'get', ticket:''}` with the same friendly error a wholly
+ * omitted ticket would produce.
+ */
+export declare function firstMissing(args: Record<string, unknown>, fields: readonly string[]): string | null;

package/dist/tools/action-guard.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Per-action runtime field guard for the canonical multi-action tools (#793).
+ *
+ * The tool-family merge (#793) collapses each family into one canonical tool
+ * with a flat `{ action, ...per-action optional fields }` param shape. Because
+ * the union makes every per-action field optional at the zod boundary (we do
+ * NOT use `z.discriminatedUnion` — see docs/design/793-tool-family-merge-brief.md
+ * §2), cross-field "this action requires that field" rules are enforced at
+ * RUNTIME inside the handler, before dispatch.
+ *
+ * {@link firstMissing} returns the first required field that is absent so the
+ * handler can return a friendly, actionable `fail(...)` message naming the
+ * exact tool, action, and field — instead of a cryptic downstream error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.firstMissing = firstMissing;
+/**
+ * Return the first field name in `fields` whose value in `args` is "missing"
+ * (`undefined`, `null`, or an empty string), or `null` when all are present.
+ *
+ * Empty-string counts as missing so a canonical handler rejects e.g.
+ * `coat_check{action:'get', ticket:''}` with the same friendly error a wholly
+ * omitted ticket would produce.
+ */
+function firstMissing(args, fields) {
+    for (const field of fields) {
+        const v = args[field];
+        if (v === undefined || v === null || v === '')
+            return field;
+    }
+    return null;
+}

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

@@ -0,0 +1,20 @@
+import { Client } from '@temporalio/client';
+import { Config } from '../config';
+import { type TempoToolDescriptor } from './descriptor';
+/**
+ * Canonical `coat_check` tool. Dispatches on `action` to the same per-action
+ * logic the legacy tools used. Per-action required fields are runtime-guarded
+ * (the flat union makes them optional at the zod boundary).
+ */
+export declare function buildCoatCheckTool(client: Client, config: Config, getPlayerId: () => string): TempoToolDescriptor;
+/**
+ * Legacy forwarding aliases — `coat_check_put` / `coat_check_get` /
+ * `coat_check_list` / `coat_check_evict`. Each keeps its EXACT original param
+ * schema and handler (reused verbatim from the legacy descriptor); only the
+ * description gains a deprecation note pointing at the canonical tool.
+ *
+ * Authored as explicit object literals (not loop-generated) so the
+ * surface-drift name scrape and any future static analysis see each alias name
+ * adjacent to its description (docs/design/793-tool-family-merge-brief.md §6).
+ */
+export declare function buildCoatCheckAliasTools(client: Client, config: Config, getPlayerId: () => string): TempoToolDescriptor[];

package/dist/tools/coat-check.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCoatCheckTool = buildCoatCheckTool;
+exports.buildCoatCheckAliasTools = buildCoatCheckAliasTools;
+/**
+ * `coat_check` — canonical multi-action coat-check tool (#793 tool-family merge).
+ *
+ * Merges the four legacy per-action tools (`coat_check_put` / `coat_check_get` /
+ * `coat_check_list` / `coat_check_evict`) into ONE canonical tool with a flat
+ * `{ action, ...per-action optional fields }` param shape (NOT a discriminated
+ * union — see docs/design/793-tool-family-merge-brief.md §2). The canonical name
+ * is **net-new**, so `action` is REQUIRED (no legacy caller to keep compatible).
+ *
+ * The legacy tools stay registered as thin forwarding aliases
+ * ({@link buildCoatCheckAliasTools}) so every existing caller keeps its exact
+ * original schema and behaviour — the alias-not-remove invariant (#793). Both the
+ * canonical handler and the aliases reuse the legacy descriptors' handler bodies
+ * verbatim, so there is a single implementation per action.
+ */
+const zod_1 = require("zod");
+const descriptor_1 = require("./descriptor");
+const action_guard_1 = require("./action-guard");
+const validation_1 = require("../utils/validation");
+const coat_check_put_1 = require("./coat-check-put");
+const coat_check_get_1 = require("./coat-check-get");
+const coat_check_list_1 = require("./coat-check-list");
+const coat_check_evict_1 = require("./coat-check-evict");
+/**
+ * Canonical `coat_check` tool. Dispatches on `action` to the same per-action
+ * logic the legacy tools used. Per-action required fields are runtime-guarded
+ * (the flat union makes them optional at the zod boundary).
+ */
+function buildCoatCheckTool(client, config, getPlayerId) {
+    const put = (0, coat_check_put_1.buildCoatCheckPutTool)(client, config, getPlayerId);
+    const get = (0, coat_check_get_1.buildCoatCheckGetTool)(client, config, getPlayerId);
+    const list = (0, coat_check_list_1.buildCoatCheckListTool)(client, config);
+    const evict = (0, coat_check_evict_1.buildCoatCheckEvictTool)(client, config, getPlayerId);
+    return {
+        name: 'coat_check',
+        description: 'Ensemble-shared transient store (stash large artifacts past the cue size cap). ' +
+            'action="put" stashes content (summary+content[, contentType, ttlMs]) and returns a ticket; ' +
+            'action="get" redeems a ticket (bumps fetch audit); ' +
+            'action="list" surveys entry headers (putBy/prefix/unfetchedOnly filters); ' +
+            'action="evict" removes an entry early (owner-or-conductor).',
+        params: {
+            action: zod_1.z.enum(['put', 'get', 'list', 'evict']).describe('Which coat-check operation to perform'),
+            // put:
+            summary: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_SUMMARY_MAX).optional().describe('put: short human-readable label for the entry'),
+            content: zod_1.z.string().min(1).max(validation_1.COAT_CHECK_CONTENT_MAX).optional().describe('put: the body to stash (≤32 KiB)'),
+            contentType: zod_1.z.string().max(validation_1.COAT_CHECK_CONTENT_TYPE_MAX).optional().describe('put: optional MIME/content-type hint'),
+            ttlMs: zod_1.z.number().int().min(validation_1.COAT_CHECK_TTL_MIN_MS).max(validation_1.COAT_CHECK_TTL_MAX_MS).optional().describe('put: optional time-to-live in ms (default 7d)'),
+            // get / evict:
+            ticket: zod_1.z.string().regex(validation_1.COAT_CHECK_TICKET_REGEX).max(validation_1.COAT_CHECK_TICKET_MAX).optional().describe('get/evict: the ticket id returned by put'),
+            // list:
+            putBy: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).optional().describe('list: filter to entries stashed by this player'),
+            prefix: zod_1.z.string().max(validation_1.COAT_CHECK_SUMMARY_MAX).optional().describe('list: filter to entries whose summary starts with this prefix'),
+            unfetchedOnly: zod_1.z.boolean().optional().describe('list: only entries that have never been fetched'),
+        },
+        handler: async (args) => {
+            const action = args.action;
+            switch (action) {
+                case 'put': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['summary', 'content']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`coat_check action="put" requires "${m}".`);
+                    return put.handler(args);
+                }
+                case 'get': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['ticket']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`coat_check action="get" requires "${m}".`);
+                    return get.handler(args);
+                }
+                case 'list':
+                    return list.handler(args);
+                case 'evict': {
+                    const m = (0, action_guard_1.firstMissing)(args, ['ticket']);
+                    if (m)
+                        return (0, descriptor_1.fail)(`coat_check action="evict" requires "${m}".`);
+                    return evict.handler(args);
+                }
+                default:
+                    return (0, descriptor_1.fail)(`Unknown coat_check action: ${String(action)}. Expected put | get | list | evict.`);
+            }
+        },
+    };
+}
+/**
+ * Legacy forwarding aliases — `coat_check_put` / `coat_check_get` /
+ * `coat_check_list` / `coat_check_evict`. Each keeps its EXACT original param
+ * schema and handler (reused verbatim from the legacy descriptor); only the
+ * description gains a deprecation note pointing at the canonical tool.
+ *
+ * Authored as explicit object literals (not loop-generated) so the
+ * surface-drift name scrape and any future static analysis see each alias name
+ * adjacent to its description (docs/design/793-tool-family-merge-brief.md §6).
+ */
+function buildCoatCheckAliasTools(client, config, getPlayerId) {
+    const put = (0, coat_check_put_1.buildCoatCheckPutTool)(client, config, getPlayerId);
+    const get = (0, coat_check_get_1.buildCoatCheckGetTool)(client, config, getPlayerId);
+    const list = (0, coat_check_list_1.buildCoatCheckListTool)(client, config);
+    const evict = (0, coat_check_evict_1.buildCoatCheckEvictTool)(client, config, getPlayerId);
+    return [
+        {
+            name: 'coat_check_put',
+            description: 'DEPRECATED — use `coat_check` with action="put". ' + put.description,
+            params: put.params,
+            handler: put.handler,
+        },
+        {
+            name: 'coat_check_get',
+            description: 'DEPRECATED — use `coat_check` with action="get". ' + get.description,
+            params: get.params,
+            handler: get.handler,
+        },
+        {
+            name: 'coat_check_list',
+            description: 'DEPRECATED — use `coat_check` with action="list". ' + list.description,
+            params: list.params,
+            handler: list.handler,
+        },
+        {
+            name: 'coat_check_evict',
+            description: 'DEPRECATED — use `coat_check` with action="evict". ' + evict.description,
+            params: evict.params,
+            handler: evict.handler,
+        },
+    ];
+}