agent-tempo 1.2.0 → 1.4.0

package/dist/tools/destroy.js

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

package/dist/tools/ensemble.d.ts

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

package/dist/tools/ensemble.js

@@ -35,11 +35,11 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DORMANT_THRESHOLD_MS = void 0;
 exports.classifyDormancy = classifyDormancy;
-exports.registerEnsembleTool = registerEnsembleTool;
+exports.buildEnsembleTool = buildEnsembleTool;
 const zod_1 = require("zod");
 const os = __importStar(require("os"));
 const resolve_1 = require("../activities/resolve");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const duration_1 = require("../utils/duration");
 /**
  * Default dormancy threshold (1 hour). Per #563: a `detached` player whose
@@ -79,75 +79,80 @@ function classifyDormancy(session, now, thresholdMs = exports.DORMANT_THRESHOLD_
     }
     return 'active';
 }
-function registerEnsembleTool(server, client, config, getPlayerId, ownWorkflowId) {
-    (0, helpers_1.defineTool)(server, 'ensemble', `Discover active Claude Code sessions in the "${config.ensemble}" ensemble. Returns player IDs, descriptions, and metadata. NOTE: returns tempo-registered players only — does NOT include Claude Code Agent-tool sub-agents (spawned via the Agent tool / subagent_type). Those are ephemeral and process-local; call TaskList separately to enumerate them. Tempo players are addressable via cue; Agent-tool sub-agents are not.`, {
-        scope: zod_1.z.string().optional().describe('Filter scope: "machine" (same hostname), "repo" (same git root), "all" (default). All scopes are within the current ensemble.'),
-        // #563: dormancy filter. Default `show` preserves the pre-#563 listing
-        // (everything visible) but groups gone/long-detached players into a
-        // separate "Dormant" section. `hide` suppresses dormant entries
-        // entirely; `show-only` is the inverse, useful for cleanup workflows.
-        dormant: zod_1.z.enum(['show', 'hide', 'show-only']).optional().describe('Dormancy filter: "show" (default — group dormant in a separate section), "hide" (suppress dormant entries), "show-only" (only show dormant). A player is dormant when phase=gone, or phase=detached with no activity in the last hour.'),
-    }, async (args) => {
-        const scope = (args.scope ?? 'all');
-        const dormantFilter = (args.dormant ?? 'show');
-        let sessions;
-        try {
-            sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Error listing workflows: ${(0, helpers_1.formatError)(err)}`);
-        }
-        // Apply scope filters
-        let ownGitRoot;
-        if (scope === 'repo') {
+function buildEnsembleTool(client, config, getPlayerId, ownWorkflowId) {
+    return {
+        name: 'ensemble',
+        description: `Discover active Claude Code sessions in the "${config.ensemble}" ensemble. Returns player IDs, descriptions, and metadata. NOTE: returns tempo-registered players only — does NOT include Claude Code Agent-tool sub-agents (spawned via the Agent tool / subagent_type). Those are ephemeral and process-local; call TaskList separately to enumerate them. Tempo players are addressable via cue; Agent-tool sub-agents are not.`,
+        params: {
+            scope: zod_1.z.string().optional().describe('Filter scope: "machine" (same hostname), "repo" (same git root), "all" (default). All scopes are within the current ensemble.'),
+            // #563: dormancy filter. Default `show` preserves the pre-#563 listing
+            // (everything visible) but groups gone/long-detached players into a
+            // separate "Dormant" section. `hide` suppresses dormant entries
+            // entirely; `show-only` is the inverse, useful for cleanup workflows.
+            dormant: zod_1.z.enum(['show', 'hide', 'show-only']).optional().describe('Dormancy filter: "show" (default — group dormant in a separate section), "hide" (suppress dormant entries), "show-only" (only show dormant). A player is dormant when phase=gone, or phase=detached with no activity in the last hour.'),
+        },
+        handler: async (args) => {
+            const scope = (args.scope ?? 'all');
+            const dormantFilter = (args.dormant ?? 'show');
+            let sessions;
             try {
-                const ownHandle = client.workflow.getHandle(ownWorkflowId);
-                const ownMeta = await ownHandle.query('getMetadata');
-                ownGitRoot = ownMeta.gitRoot;
+                sessions = await (0, resolve_1.scanEnsembleSessions)(client, config.ensemble);
             }
-            catch {
-                // Can't determine own git root — skip repo filtering
+            catch (err) {
+                return (0, descriptor_1.fail)(`Error listing workflows: ${(0, descriptor_1.formatError)(err)}`);
             }
-        }
-        const scoped = sessions.filter((s) => {
-            if (scope === 'machine' && s.hostname !== os.hostname())
-                return false;
-            if (scope === 'repo' && ownGitRoot && s.gitRoot !== ownGitRoot)
-                return false;
-            return true;
-        });
-        const now = Date.now();
-        const enriched = scoped.map((s) => ({
-            ...s,
-            isYou: s.playerId === getPlayerId(),
-            dormancy: classifyDormancy(s, now),
-        }));
-        const active = enriched.filter((p) => p.dormancy === 'active');
-        const dormant = enriched.filter((p) => p.dormancy === 'dormant');
-        if (active.length === 0 && dormant.length === 0) {
-            return (0, helpers_1.ok)('No active sessions found.');
-        }
-        // #563 summary line — surface both counts so operators can see what's
-        // being hidden behind the dormant filter without re-running.
-        const summary = `**${config.ensemble}**: ${active.length} active, ${dormant.length} dormant`;
-        const sections = [summary];
-        const showActive = dormantFilter !== 'show-only';
-        const showDormant = dormantFilter !== 'hide';
-        if (showActive) {
-            if (active.length > 0) {
-                sections.push(`\n=== Active (${active.length}) ===\n`);
-                sections.push(active.map((p) => renderPlayerLine(p, now, false)).join('\n\n'));
+            // Apply scope filters
+            let ownGitRoot;
+            if (scope === 'repo') {
+                try {
+                    const ownHandle = client.workflow.getHandle(ownWorkflowId);
+                    const ownMeta = await ownHandle.query('getMetadata');
+                    ownGitRoot = ownMeta.gitRoot;
+                }
+                catch {
+                    // Can't determine own git root — skip repo filtering
+                }
             }
-            else {
-                sections.push('\n=== Active (0) ===\n(none)');
+            const scoped = sessions.filter((s) => {
+                if (scope === 'machine' && s.hostname !== os.hostname())
+                    return false;
+                if (scope === 'repo' && ownGitRoot && s.gitRoot !== ownGitRoot)
+                    return false;
+                return true;
+            });
+            const now = Date.now();
+            const enriched = scoped.map((s) => ({
+                ...s,
+                isYou: s.playerId === getPlayerId(),
+                dormancy: classifyDormancy(s, now),
+            }));
+            const active = enriched.filter((p) => p.dormancy === 'active');
+            const dormant = enriched.filter((p) => p.dormancy === 'dormant');
+            if (active.length === 0 && dormant.length === 0) {
+                return (0, descriptor_1.ok)('No active sessions found.');
             }
-        }
-        if (showDormant && dormant.length > 0) {
-            sections.push(`\n=== Dormant (${dormant.length}) — last seen >1h ago or gone ===\n`);
-            sections.push(dormant.map((p) => renderPlayerLine(p, now, true)).join('\n\n'));
-        }
-        return (0, helpers_1.ok)(sections.join('\n'));
-    });
+            // #563 summary line — surface both counts so operators can see what's
+            // being hidden behind the dormant filter without re-running.
+            const summary = `**${config.ensemble}**: ${active.length} active, ${dormant.length} dormant`;
+            const sections = [summary];
+            const showActive = dormantFilter !== 'show-only';
+            const showDormant = dormantFilter !== 'hide';
+            if (showActive) {
+                if (active.length > 0) {
+                    sections.push(`\n=== Active (${active.length}) ===\n`);
+                    sections.push(active.map((p) => renderPlayerLine(p, now, false)).join('\n\n'));
+                }
+                else {
+                    sections.push('\n=== Active (0) ===\n(none)');
+                }
+            }
+            if (showDormant && dormant.length > 0) {
+                sections.push(`\n=== Dormant (${dormant.length}) — last seen >1h ago or gone ===\n`);
+                sections.push(dormant.map((p) => renderPlayerLine(p, now, true)).join('\n\n'));
+            }
+            return (0, descriptor_1.ok)(sections.join('\n'));
+        },
+    };
 }
 /**
  * Render one player as the multi-line block historically emitted by

package/dist/tools/evaluate-gate.d.ts

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

package/dist/tools/evaluate-gate.js

@@ -1,32 +1,38 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerEvaluateGateTool = registerEvaluateGateTool;
+exports.buildEvaluateGateTool = buildEvaluateGateTool;
 const zod_1 = require("zod");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
+const signals_1 = require("../workflows/signals");
 const validation_1 = require("../utils/validation");
-function registerEvaluateGateTool(server, handle, getPlayerId) {
-    (0, helpers_1.defineTool)(server, 'evaluate_gate', 'Mark one or more criteria on a quality gate as passed or failed. Conductor only.', {
-        task: zod_1.z.string().max(validation_1.GATE_TASK_MAX).describe('The task name of the gate to evaluate'),
-        evaluations: zod_1.z.array(zod_1.z.object({
-            index: zod_1.z.number().int().min(0).describe('Zero-based index of the criterion'),
-            status: zod_1.z.enum(['passed', 'failed']).describe('Whether this criterion passed or failed'),
-            notes: zod_1.z.string().max(validation_1.GATE_NOTES_MAX).optional().describe('Optional notes explaining the evaluation'),
-        })).min(1).describe('List of criterion evaluations'),
-    }, async (args) => {
-        const { task, evaluations } = args;
-        try {
-            await handle.signal('evaluateGateCriteria', {
-                task,
-                evaluations,
-                evaluatedBy: getPlayerId(),
-            });
-            const summary = evaluations
-                .map((ev) => `  ${ev.index}: ${ev.status === 'passed' ? '\u2705' : '\u274c'} ${ev.status}${ev.notes ? ` — ${ev.notes}` : ''}`)
-                .join('\n');
-            return (0, helpers_1.ok)(`Evaluated ${evaluations.length} criteria on gate **${task}**:\n${summary}`);
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to evaluate gate: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+function buildEvaluateGateTool(handle, getPlayerId) {
+    return {
+        name: 'evaluate_gate',
+        description: 'Mark one or more criteria on a quality gate as passed or failed. Conductor only.',
+        params: {
+            task: zod_1.z.string().max(validation_1.GATE_TASK_MAX).describe('The task name of the gate to evaluate'),
+            evaluations: zod_1.z.array(zod_1.z.object({
+                index: zod_1.z.number().int().min(0).describe('Zero-based index of the criterion'),
+                status: zod_1.z.enum(['passed', 'failed']).describe('Whether this criterion passed or failed'),
+                notes: zod_1.z.string().max(validation_1.GATE_NOTES_MAX).optional().describe('Optional notes explaining the evaluation'),
+            })).min(1).describe('List of criterion evaluations'),
+        },
+        handler: async (args) => {
+            const { task, evaluations } = args;
+            try {
+                await handle.signal(signals_1.evaluateGateCriteriaSignal, {
+                    task,
+                    evaluations,
+                    evaluatedBy: getPlayerId(),
+                });
+                const summary = evaluations
+                    .map((ev) => `  ${ev.index}: ${ev.status === 'passed' ? '\u2705' : '\u274c'} ${ev.status}${ev.notes ? ` — ${ev.notes}` : ''}`)
+                    .join('\n');
+                return (0, descriptor_1.ok)(`Evaluated ${evaluations.length} criteria on gate **${task}**:\n${summary}`);
+            }
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to evaluate gate: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

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

@@ -1,6 +1,6 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { WorkflowHandle, Client } from '@temporalio/client';
 import { Config } from '../config';
+import { type TempoToolDescriptor } from './descriptor';
 /**
  * Return type is monomorphic by design: `{ content, savedAt, savedBy } | null`.
  * ADR 0011 §Alternatives explicitly rejected a `list: boolean` flag because
@@ -10,4 +10,4 @@ import { Config } from '../config';
  * playerStateKeys`; v2 can graduate a dedicated `list_state` MCP tool if
  * telemetry shows real demand.
  */
-export declare function registerFetchStateTool(server: McpServer, client: Client, config: Config, handle: WorkflowHandle, getPlayerId: () => string): void;
+export declare function buildFetchStateTool(client: Client, config: Config, handle: WorkflowHandle, getPlayerId: () => string): TempoToolDescriptor;