agent-tempo 1.3.1 → 1.4.0

package/dist/pi/zod-to-typebox.js

@@ -0,0 +1,191 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnsupportedZodFeatureError = void 0;
+exports.zodShapeToTypeBox = zodShapeToTypeBox;
+const typebox_1 = require("typebox");
+/**
+ * Thrown when a tool param schema uses a zod construct outside the audited
+ * subset. Carries the field path + offending feature so CI / callers can point
+ * at the exact source. A named class lets the parity test assert "raised on
+ * nothing" precisely.
+ */
+class UnsupportedZodFeatureError extends Error {
+    context;
+    feature;
+    constructor(context, feature) {
+        const where = `${context.tool ? `${context.tool}.` : ''}${context.path || '<root>'}`;
+        super(`zod→TypeBox: unsupported feature "${feature}" at ${where}. ` +
+            `Extend src/pi/zod-to-typebox.ts (and a unit test) if this construct is intentional.`);
+        this.context = context;
+        this.feature = feature;
+        this.name = 'UnsupportedZodFeatureError';
+    }
+}
+exports.UnsupportedZodFeatureError = UnsupportedZodFeatureError;
+function defOf(zt) {
+    return zt._def;
+}
+const SCALAR_TYPE_NAMES = new Set([
+    'ZodString',
+    'ZodNumber',
+    'ZodBoolean',
+    'ZodEnum',
+    'ZodLiteral',
+]);
+/**
+ * Convert a tool's zod param shape into a TypeBox object schema suitable for
+ * `pi.registerTool({ parameters })`. This is the public entry point consumed by
+ * the Pi front-end (`src/pi/render-tools.ts`).
+ *
+ * @param shape    The tool's `z.ZodRawShape` (the `paramsSchema` from `defineTool`).
+ * @param toolName Optional tool name, woven into error messages.
+ * @throws {UnsupportedZodFeatureError} on any zod construct outside the subset.
+ */
+function zodShapeToTypeBox(shape, toolName) {
+    return buildObject(shape, { tool: toolName, path: '' });
+}
+function buildObject(shape, ctx, meta = {}) {
+    const props = {};
+    for (const [key, zt] of Object.entries(shape)) {
+        const fieldCtx = {
+            tool: ctx.tool,
+            path: ctx.path ? `${ctx.path}.${key}` : key,
+        };
+        const { inner, isOptional, outerDescription } = stripOptional(zt);
+        const schema = convert(inner, fieldCtx, outerDescription);
+        props[key] = isOptional ? typebox_1.Type.Optional(schema) : schema;
+    }
+    return typebox_1.Type.Object(props, meta);
+}
+/**
+ * Peel a single `.optional()` wrapper. Captures the description authored on the
+ * wrapper (e.g. `z.string().optional().describe('…')` puts it on the optional)
+ * so it survives onto the inner schema.
+ */
+function stripOptional(zt) {
+    const def = defOf(zt);
+    if (def?.typeName === 'ZodOptional') {
+        return { inner: def.innerType, isOptional: true, outerDescription: def.description };
+    }
+    return { inner: zt, isOptional: false };
+}
+/** Convert a NON-optional zod type. `descOverride` wins over the node's own description. */
+function convert(zt, ctx, descOverride) {
+    const def = defOf(zt);
+    const typeName = def?.typeName;
+    const description = descOverride ?? def?.description;
+    const meta = description !== undefined ? { description } : {};
+    switch (typeName) {
+        case 'ZodString':
+            return typebox_1.Type.String({ ...meta, ...stringConstraints(zt, ctx) });
+        case 'ZodNumber': {
+            const { isInt, opts } = numberConstraints(zt, ctx);
+            const numMeta = { ...meta, ...opts };
+            return isInt ? typebox_1.Type.Integer(numMeta) : typebox_1.Type.Number(numMeta);
+        }
+        case 'ZodBoolean':
+            return typebox_1.Type.Boolean(meta);
+        case 'ZodEnum': {
+            const values = def.values;
+            return typebox_1.Type.Union(values.map((v) => typebox_1.Type.Literal(v)), meta);
+        }
+        case 'ZodLiteral':
+            return typebox_1.Type.Literal(def.value, meta);
+        case 'ZodArray':
+            return typebox_1.Type.Array(arrayElement(def.type, ctx), {
+                ...meta,
+                ...arrayConstraints(zt, ctx),
+            });
+        case 'ZodObject':
+            return buildObject(def.shape(), ctx, meta);
+        case 'ZodUnion':
+            return convertUnion(zt, ctx, meta);
+        default:
+            throw new UnsupportedZodFeatureError(ctx, typeName ?? 'unknown (not a zod type)');
+    }
+}
+/** Array elements are converted as non-optional types; an optional element is rejected. */
+function arrayElement(el, ctx) {
+    const { inner, isOptional } = stripOptional(el);
+    if (isOptional) {
+        throw new UnsupportedZodFeatureError({ ...ctx, path: `${ctx.path}[]` }, 'optional array element');
+    }
+    return convert(inner, { ...ctx, path: `${ctx.path}[]` });
+}
+function stringConstraints(zt, ctx) {
+    const out = {};
+    for (const check of (defOf(zt).checks ?? [])) {
+        switch (check.kind) {
+            case 'min':
+                out.minLength = check.value;
+                break;
+            case 'max':
+                out.maxLength = check.value;
+                break;
+            case 'regex':
+                out.pattern = check.regex.source;
+                break;
+            default:
+                throw new UnsupportedZodFeatureError(ctx, `z.string().${String(check.kind)}()`);
+        }
+    }
+    return out;
+}
+function numberConstraints(zt, ctx) {
+    let isInt = false;
+    const opts = {};
+    for (const check of (defOf(zt).checks ?? [])) {
+        switch (check.kind) {
+            case 'int':
+                isInt = true;
+                break;
+            case 'min':
+                if (check.inclusive === false) {
+                    throw new UnsupportedZodFeatureError(ctx, 'z.number() exclusive minimum (.gt)');
+                }
+                opts.minimum = check.value;
+                break;
+            case 'max':
+                if (check.inclusive === false) {
+                    throw new UnsupportedZodFeatureError(ctx, 'z.number() exclusive maximum (.lt)');
+                }
+                opts.maximum = check.value;
+                break;
+            default:
+                throw new UnsupportedZodFeatureError(ctx, `z.number().${String(check.kind)}()`);
+        }
+    }
+    return { isInt, opts };
+}
+function arrayConstraints(zt, ctx) {
+    // NOTE: zod stores array length bounds as named `_def` FIELDS
+    // (`minLength`/`maxLength`/`exactLength`), NOT as `_def.checks[]` entries like
+    // string and number bounds. Don't "unify" this with stringConstraints /
+    // numberConstraints — they read a genuinely different zod representation.
+    const def = defOf(zt);
+    const out = {};
+    if (def.exactLength) {
+        throw new UnsupportedZodFeatureError(ctx, 'z.array().length() (exact length)');
+    }
+    if (def.minLength)
+        out.minItems = def.minLength.value;
+    if (def.maxLength)
+        out.maxItems = def.maxLength.value;
+    return out;
+}
+function convertUnion(zt, ctx, meta) {
+    const options = defOf(zt).options;
+    const members = options.map((member, i) => {
+        const memberCtx = { ...ctx, path: `${ctx.path}|${i}` };
+        const { inner, isOptional } = stripOptional(member);
+        if (isOptional) {
+            throw new UnsupportedZodFeatureError(memberCtx, 'optional union member');
+        }
+        const memberTypeName = defOf(inner)?.typeName;
+        if (memberTypeName === undefined || !SCALAR_TYPE_NAMES.has(memberTypeName)) {
+            throw new UnsupportedZodFeatureError(memberCtx, `non-scalar union member (${memberTypeName ?? 'unknown'}); only string/number/boolean/enum/literal members are supported`);
+        }
+        return convert(inner, memberCtx);
+    });
+    return typebox_1.Type.Union(members, meta);
+}

package/dist/server-tools.d.ts

@@ -20,6 +20,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client, WorkflowHandle } from '@temporalio/client';
 import { Config } from './config';
 import { AgentType } from './types';
+import { type TempoToolDescriptor } from './tools/descriptor';
 /**
  * Identity + state context every tool registration consumes. The two
  * surfaces (stdio MCP server in `src/server.ts`, in-process MCP server in
@@ -57,6 +58,7 @@ export interface RegisterAllTempoToolsOpts {
  * `opts.isConductor` — non-conductor players don't see them on either
  * surface.
  */
+export declare function buildAllTempoTools(opts: RegisterAllTempoToolsOpts): TempoToolDescriptor[];
 export declare function registerAllTempoTools(server: McpServer, opts: RegisterAllTempoToolsOpts): void;
 /**
  * Identity + ensemble context for {@link buildServerInstructions}.

package/dist/server-tools.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildAllTempoTools = buildAllTempoTools;
 exports.registerAllTempoTools = registerAllTempoTools;
 exports.buildServerInstructions = buildServerInstructions;
+const descriptor_1 = require("./tools/descriptor");
 const ensemble_1 = require("./tools/ensemble");
 const cue_1 = require("./tools/cue");
 const set_part_1 = require("./tools/set-part");
@@ -32,6 +34,7 @@ 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");
 const migrate_1 = require("./tools/migrate");
 const attachment_info_1 = require("./tools/attachment-info");
 const hosts_1 = require("./tools/hosts");
@@ -55,55 +58,56 @@ const coat_check_evict_1 = require("./tools/coat-check-evict");
  * `opts.isConductor` — non-conductor players don't see them on either
  * surface.
  */
-function registerAllTempoTools(server, opts) {
+function buildAllTempoTools(opts) {
     const { client, config, getPlayerId, setPlayerId, handle, workflowId, ownAgentType, isConductor } = opts;
-    (0, ensemble_1.registerEnsembleTool)(server, client, config, getPlayerId, workflowId);
-    (0, cue_1.registerCueTool)(server, client, config, getPlayerId, handle);
-    (0, set_part_1.registerSetPartTool)(server, handle);
-    (0, set_name_1.registerSetNameTool)(server, client, config, handle, getPlayerId, setPlayerId);
-    (0, listen_1.registerListenTool)(server, handle);
-    (0, recruit_1.registerRecruitTool)(server, client, config, getPlayerId, handle, ownAgentType);
-    (0, report_1.registerReportTool)(server, handle);
-    (0, schedule_1.registerScheduleTool)(server, client, config, getPlayerId);
-    (0, unschedule_1.registerUnscheduleTool)(server, client, config);
-    (0, schedules_1.registerSchedulesTool)(server, client, config);
-    (0, save_lineup_1.registerSaveLineupTool)(server, client, config, getPlayerId, isConductor);
-    (0, load_lineup_1.registerLoadLineupTool)(server, client, config, getPlayerId, ownAgentType, handle, setPlayerId, isConductor);
-    (0, agent_types_1.registerAgentTypesTool)(server);
-    (0, who_am_i_1.registerWhoAmITool)(server, handle, getPlayerId);
-    (0, broadcast_1.registerBroadcastTool)(server, client, config, getPlayerId, handle);
-    (0, recall_1.registerRecallTool)(server, handle, getPlayerId);
-    (0, release_1.registerReleaseTool)(server, client, config, getPlayerId, handle);
-    (0, pause_1.registerPauseTool)(server, client, config, getPlayerId);
-    (0, play_1.registerPlayTool)(server, client, config, getPlayerId);
-    (0, shutdown_1.registerShutdownTool)(server, client, config, getPlayerId);
-    (0, restore_1.registerRestoreTool)(server, client, config, getPlayerId);
-    (0, restart_1.registerRestartTool)(server, client, config, getPlayerId, handle);
-    (0, destroy_1.registerDestroyTool)(server, client, config, getPlayerId, handle);
-    (0, migrate_1.registerMigrateTool)(server, client, config, getPlayerId, handle);
-    (0, attachment_info_1.registerAttachmentInfoTool)(server, client, config);
-    (0, hosts_1.registerHostsTool)(server, client, config);
-    (0, set_ensemble_description_1.registerSetEnsembleDescriptionTool)(server, client, config);
-    // #334 PR-1 — owner-write / peer-read player saveable state.
-    (0, save_state_1.registerSaveStateTool)(server, handle, getPlayerId);
-    (0, fetch_state_1.registerFetchStateTool)(server, client, config, handle, getPlayerId);
-    (0, clear_state_1.registerClearStateTool)(server, 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.registerCoatCheckPutTool)(server, client, config, getPlayerId);
-    (0, coat_check_get_1.registerCoatCheckGetTool)(server, client, config, getPlayerId);
-    (0, coat_check_list_1.registerCoatCheckListTool)(server, client, config);
-    (0, coat_check_evict_1.registerCoatCheckEvictTool)(server, client, config, getPlayerId);
+    const tools = [
+        (0, ensemble_1.buildEnsembleTool)(client, config, getPlayerId, workflowId),
+        (0, cue_1.buildCueTool)(client, config, getPlayerId, handle),
+        (0, set_part_1.buildSetPartTool)(handle),
+        (0, set_name_1.buildSetNameTool)(client, config, handle, getPlayerId, setPlayerId),
+        (0, listen_1.buildListenTool)(handle),
+        (0, recruit_1.buildRecruitTool)(client, config, getPlayerId, handle, ownAgentType),
+        (0, report_1.buildReportTool)(handle),
+        (0, schedule_1.buildScheduleTool)(client, config, getPlayerId),
+        (0, unschedule_1.buildUnscheduleTool)(client, config),
+        (0, schedules_1.buildSchedulesTool)(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)(),
+        (0, who_am_i_1.buildWhoAmITool)(handle, getPlayerId),
+        (0, broadcast_1.buildBroadcastTool)(client, config, getPlayerId, handle),
+        (0, recall_1.buildRecallTool)(handle, getPlayerId),
+        (0, release_1.buildReleaseTool)(client, config, getPlayerId, handle),
+        (0, pause_1.buildPauseTool)(client, config, getPlayerId),
+        (0, play_1.buildPlayTool)(client, config, getPlayerId),
+        (0, shutdown_1.buildShutdownTool)(client, config, getPlayerId),
+        (0, restore_1.buildRestoreTool)(client, config, getPlayerId),
+        (0, restart_1.buildRestartTool)(client, config, getPlayerId, handle),
+        (0, destroy_1.buildDestroyTool)(client, config, getPlayerId, handle),
+        (0, reset_1.buildResetTool)(handle, getPlayerId),
+        (0, migrate_1.buildMigrateTool)(client, config, getPlayerId, handle),
+        (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),
+    ];
     if (isConductor) {
-        (0, quality_gate_1.registerQualityGateTool)(server, handle, getPlayerId);
-        (0, evaluate_gate_1.registerEvaluateGateTool)(server, handle, getPlayerId);
-        (0, gates_1.registerGatesTool)(server, handle);
-        (0, worktree_1.registerWorktreeTool)(server, client, config, handle, getPlayerId);
-        (0, stage_1.registerStageTool)(server, handle, getPlayerId);
-        (0, stages_1.registerStagesTool)(server, handle);
-        (0, cancel_stage_1.registerCancelStageTool)(server, handle);
+        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));
     }
+    return tools;
+}
+function registerAllTempoTools(server, opts) {
+    (0, descriptor_1.renderToMcp)(server, buildAllTempoTools(opts));
 }
 /**
  * Build the `instructions` string that lands in `McpServer`'s `instructions`

package/dist/spawn.d.ts

@@ -236,6 +236,61 @@ export interface OpenCodeAdapterResult {
  * specific provider key since the model is opaque pass-through).
  */
 export declare function spawnOpenCodeAdapter(opts: OpenCodeAdapterOpts): OpenCodeAdapterResult;
+/**
+ * Options for {@link spawnPiHeadless}. Mirrors {@link OpenCodeAdapterOpts} for
+ * identity + Temporal connection + attachment handoff; adds Pi-specific knobs:
+ * `model` (provider/model via `AGENT_TEMPO_PI_MODEL`), `continueSessionId`
+ * (restart-resume via `AGENT_TEMPO_PI_CONTINUE_SESSION` → Pi `continueSession`),
+ * and `toolAccess` (MD-C tool-class policy via `AGENT_TEMPO_TOOL_ACCESS`).
+ *
+ * Unlike the other headless adapters, the Pi entry does NOT drive a
+ * `BaseAttachment` loop — it injects the `src/pi` extension into Pi's
+ * `createAgentSession`; the module-scope extension singleton owns the lifecycle.
+ */
+export interface PiHeadlessAdapterOpts {
+    name: string;
+    ensemble: string;
+    temporalAddress: string;
+    temporalNamespace?: string;
+    temporalApiKey?: string;
+    temporalTlsCertPath?: string;
+    temporalTlsKeyPath?: string;
+    isConductor?: boolean;
+    workDir: string;
+    /** Directory for log + PID files. Defaults to `logs/` inside workDir. */
+    logDir?: string;
+    /** Pi provider/model selector (e.g. `anthropic/claude-opus-4-7`); absent → Pi default. */
+    model?: string;
+    /** Restart-resume: the Pi conversation id to continue (from `metadata.sessionId`). */
+    continueSessionId?: string;
+    /** MD-C tool-class policy: `restricted` (default) | `standard` | `full`. */
+    toolAccess?: string;
+    /**
+     * 3c Tier-2 ingest token (minted by the daemon outbox, scoped to this player's
+     * workflowId). Threaded into the subprocess env as `AGENT_TEMPO_INGEST_TOKEN`
+     * so the inner-loop publisher can authenticate `POST /inner/ingest`. NOTE:
+     * spawn.ts only THREADS the token — minting lives in the daemon-only outbox
+     * (this module runs outside the daemon and must not import the registry).
+     */
+    ingestToken?: string;
+    /** PR-D attachment-lease handoff (renew rather than fresh-claim on boot). */
+    attachmentId?: string;
+    attachmentRunId?: string;
+    adapterId?: string;
+}
+export interface PiHeadlessAdapterResult {
+    pid: number | undefined;
+    logPath: string;
+    pidPath: string;
+}
+/**
+ * Spawn the headless Pi runtime as a detached subprocess. Pattern matches
+ * {@link spawnOpenCodeAdapter} — no TTY, log + PID files, env carries identity +
+ * Temporal settings + attachment handoff + the Pi model / continue-session /
+ * tool-access knobs. The entry constructs `createAgentSession` with the `src/pi`
+ * extension injected inline; the singleton claims + heartbeats + registers tools.
+ */
+export declare function spawnPiHeadless(opts: PiHeadlessAdapterOpts): PiHeadlessAdapterResult;
 /**
  * Options for {@link spawnClaudeCodeHeadlessAdapter}. Mirrors
  * {@link ClaudeApiAdapterOpts} for identity + Temporal connection +

package/dist/spawn.js

@@ -12,6 +12,7 @@ exports.spawnCopilotBridge = spawnCopilotBridge;
 exports.spawnMockAdapter = spawnMockAdapter;
 exports.spawnClaudeApiAdapter = spawnClaudeApiAdapter;
 exports.spawnOpenCodeAdapter = spawnOpenCodeAdapter;
+exports.spawnPiHeadless = spawnPiHeadless;
 exports.spawnClaudeCodeHeadlessAdapter = spawnClaudeCodeHeadlessAdapter;
 const child_process_1 = require("child_process");
 const fs_1 = require("fs");
@@ -671,6 +672,77 @@ function spawnOpenCodeAdapter(opts) {
     log(`Spawned opencode adapter (pid ${child.pid}) in ${opts.workDir} as "${opts.name}"${opts.model ? ` (model=${opts.model})` : ''}${opts.attachmentId ? ` (attachmentId=${opts.attachmentId})` : ''}`);
     return { pid: child.pid, logPath, pidPath };
 }
+/**
+ * Resolve the path to the Pi headless adapter entry point. Mirrors
+ * {@link resolveOpenCodePath} — dev (ts-node) + prod (compiled .js) both launch
+ * the same code through the same `require.main === module` gate.
+ */
+function resolvePiPath() {
+    const isDev = __filename.endsWith('.ts');
+    if (isDev) {
+        return { cmd: 'npx', args: ['ts-node', (0, path_1.resolve)(__dirname, 'adapters', 'pi', 'adapter.ts')] };
+    }
+    return { cmd: 'node', args: [(0, path_1.resolve)(__dirname, 'adapters', 'pi', 'adapter.js')] };
+}
+/**
+ * Spawn the headless Pi runtime as a detached subprocess. Pattern matches
+ * {@link spawnOpenCodeAdapter} — no TTY, log + PID files, env carries identity +
+ * Temporal settings + attachment handoff + the Pi model / continue-session /
+ * tool-access knobs. The entry constructs `createAgentSession` with the `src/pi`
+ * extension injected inline; the singleton claims + heartbeats + registers tools.
+ */
+function spawnPiHeadless(opts) {
+    const { cmd, args } = resolvePiPath();
+    const logDirPath = opts.logDir || (0, path_1.join)(opts.workDir, 'logs');
+    const logName = opts.name || `pi-${Date.now()}`;
+    const logPath = (0, path_1.join)(logDirPath, `${logName}.log`);
+    const pidPath = (0, path_1.join)(logDirPath, `${logName}.pid`);
+    (0, fs_1.mkdirSync)(logDirPath, { recursive: true });
+    const logFd = (0, fs_1.openSync)(logPath, 'a');
+    const toolAccess = opts.toolAccess || 'restricted';
+    let child;
+    try {
+        child = (0, child_process_1.spawn)(cmd, args, {
+            cwd: opts.workDir,
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env: {
+                ...process.env,
+                [config_1.ENV.ENSEMBLE]: opts.ensemble,
+                [config_1.ENV.PLAYER_NAME]: opts.name,
+                [config_1.ENV.CONDUCTOR]: opts.isConductor ? 'true' : '',
+                [config_1.ENV.TEMPORAL_ADDRESS]: opts.temporalAddress,
+                ...(opts.temporalNamespace ? { [config_1.ENV.TEMPORAL_NAMESPACE]: opts.temporalNamespace } : {}),
+                ...(opts.temporalApiKey ? { [config_1.ENV.TEMPORAL_API_KEY]: opts.temporalApiKey } : {}),
+                ...(opts.temporalTlsCertPath ? { [config_1.ENV.TEMPORAL_TLS_CERT_PATH]: opts.temporalTlsCertPath } : {}),
+                ...(opts.temporalTlsKeyPath ? { [config_1.ENV.TEMPORAL_TLS_KEY_PATH]: opts.temporalTlsKeyPath } : {}),
+                // Model selection: recruit-arg → AGENT_TEMPO_PI_MODEL → Pi default.
+                ...(opts.model ? { [config_1.ENV.PI_MODEL]: opts.model } : {}),
+                // Restart-resume: continue the prior Pi conversation.
+                ...(opts.continueSessionId ? { [config_1.ENV.PI_CONTINUE_SESSION]: opts.continueSessionId } : {}),
+                // MD-C: tool-class policy. ALWAYS set (default 'restricted' — the safe
+                // unsupervised default + an explicit value for the gate + audit trail).
+                [config_1.ENV.TOOL_ACCESS]: toolAccess,
+                // 3c Tier-2: per-player ingest token (minted by the daemon outbox).
+                // Absent → the inner-loop publisher's HTTP client no-ops (no fine tail).
+                ...(opts.ingestToken ? { [config_1.ENV.INGEST_TOKEN]: opts.ingestToken } : {}),
+                // Attachment handoff — extension renews via claimAttachment(expectedAttachmentId).
+                ...(opts.attachmentId ? { [config_1.ENV.ATTACHMENT_ID]: opts.attachmentId } : {}),
+                ...(opts.attachmentRunId ? { [config_1.ENV.ATTACHMENT_RUN_ID]: opts.attachmentRunId } : {}),
+                ...(opts.adapterId ? { [config_1.ENV.ADAPTER_ID]: opts.adapterId } : {}),
+            },
+        });
+        child.unref();
+    }
+    finally {
+        (0, fs_1.closeSync)(logFd);
+    }
+    if (child.pid != null) {
+        (0, fs_1.writeFileSync)(pidPath, String(child.pid));
+    }
+    log(`Spawned pi headless adapter (pid ${child.pid}) in ${opts.workDir} as "${opts.name}" (toolAccess=${toolAccess})${opts.model ? ` (model=${opts.model})` : ''}${opts.continueSessionId ? ` (continue=${opts.continueSessionId})` : ''}${opts.attachmentId ? ` (attachmentId=${opts.attachmentId})` : ''}`);
+    return { pid: child.pid, logPath, pidPath };
+}
 /**
  * Resolve the path to the claude-code-headless adapter entry point.
  * Mirrors {@link resolveClaudeApiPath} so dev (ts-node) and prod

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

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

package/dist/tools/agent-types.js

@@ -1,21 +1,26 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerAgentTypesTool = registerAgentTypesTool;
-const helpers_1 = require("./helpers");
+exports.buildAgentTypesTool = buildAgentTypesTool;
+const descriptor_1 = require("./descriptor");
 const agent_types_1 = require("../ensemble/agent-types");
-function registerAgentTypesTool(server) {
-    (0, helpers_1.defineTool)(server, 'agent_types', 'List available player types (agent definitions) that can be used when recruiting', {}, async () => {
-        const types = (0, agent_types_1.listAgentTypes)();
-        if (types.length === 0) {
-            return (0, helpers_1.ok)('No agent types found.');
-        }
-        const lines = types.map(t => {
-            const src = t.source === 'shipped' ? '(shipped)' : t.source === 'user' ? '(user)' : '(project)';
-            const tools = t.allowedTools && t.allowedTools.length > 0
-                ? `\n  Allowed tools: ${t.allowedTools.join(', ')}`
-                : '';
-            return `**${t.name}** ${src}\n  ${t.description || 'No description'}${tools}`;
-        });
-        return (0, helpers_1.ok)(lines.join('\n\n'));
-    });
+function buildAgentTypesTool() {
+    return {
+        name: 'agent_types',
+        description: 'List available player types (agent definitions) that can be used when recruiting',
+        params: {},
+        handler: async () => {
+            const types = (0, agent_types_1.listAgentTypes)();
+            if (types.length === 0) {
+                return (0, descriptor_1.ok)('No agent types found.');
+            }
+            const lines = types.map(t => {
+                const src = t.source === 'shipped' ? '(shipped)' : t.source === 'user' ? '(user)' : '(project)';
+                const tools = t.allowedTools && t.allowedTools.length > 0
+                    ? `\n  Allowed tools: ${t.allowedTools.join(', ')}`
+                    : '';
+                return `**${t.name}** ${src}\n  ${t.description || 'No description'}${tools}`;
+            });
+            return (0, descriptor_1.ok)(lines.join('\n\n'));
+        },
+    };
 }

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

@@ -1,4 +1,4 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Client } from '@temporalio/client';
 import { Config } from '../config';
-export declare function registerAttachmentInfoTool(server: McpServer, client: Client, config: Config): void;
+import { type TempoToolDescriptor } from './descriptor';
+export declare function buildAttachmentInfoTool(client: Client, config: Config): TempoToolDescriptor;

package/dist/tools/attachment-info.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.registerAttachmentInfoTool = registerAttachmentInfoTool;
+exports.buildAttachmentInfoTool = buildAttachmentInfoTool;
 /**
  * `attachment_info` — diagnostic query for the V2 attachment lifecycle (design §§2.2, 2.4).
  *
@@ -11,38 +11,43 @@ exports.registerAttachmentInfoTool = registerAttachmentInfoTool;
 const zod_1 = require("zod");
 const resolve_1 = require("./resolve");
 const signals_1 = require("../workflows/signals");
-const helpers_1 = require("./helpers");
+const descriptor_1 = require("./descriptor");
 const validation_1 = require("../utils/validation");
-function registerAttachmentInfoTool(server, client, config) {
-    (0, helpers_1.defineTool)(server, 'attachment_info', 'Query the V2 attachment lifecycle state of a session — phase (booting/attached/processing/awaiting/draining/detached/gone), current attachment holder (host + adapter + lease expiry), preferred host, and in-flight message count. Read-only diagnostic.', {
-        playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to inspect'),
-    }, async (args) => {
-        const { playerId } = args;
-        const nameError = (0, validation_1.validatePlayerName)(playerId);
-        if (nameError)
-            return (0, helpers_1.fail)(nameError);
-        try {
-            const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
-            if (!resolved)
-                return (0, helpers_1.fail)(`No session found with name "${playerId}".`);
-            const info = await resolved.query(signals_1.attachmentInfoQuery);
-            const lines = [
-                `**${playerId}** — phase: \`${info.phase}\``,
-                `in-flight messages: ${info.inFlightCount}`,
-            ];
-            if (info.currentAttachment) {
-                const a = info.currentAttachment;
-                lines.push(`attached on: **${a.hostname}** (adapter: ${a.adapterId}/${a.adapterClass}, attachmentId: \`${a.attachmentId.slice(0, 8)}…\`)`);
-                lines.push(`lease expires: ${a.expiresAt}`);
+function buildAttachmentInfoTool(client, config) {
+    return {
+        name: 'attachment_info',
+        description: 'Query the V2 attachment lifecycle state of a session — phase (booting/attached/processing/awaiting/draining/detached/gone), current attachment holder (host + adapter + lease expiry), preferred host, and in-flight message count. Read-only diagnostic.',
+        params: {
+            playerId: zod_1.z.string().max(validation_1.PLAYER_NAME_MAX).describe('The player name to inspect'),
+        },
+        handler: async (args) => {
+            const { playerId } = args;
+            const nameError = (0, validation_1.validatePlayerName)(playerId);
+            if (nameError)
+                return (0, descriptor_1.fail)(nameError);
+            try {
+                const resolved = await (0, resolve_1.resolveSession)(client, config.ensemble, playerId);
+                if (!resolved)
+                    return (0, descriptor_1.fail)(`No session found with name "${playerId}".`);
+                const info = await resolved.query(signals_1.attachmentInfoQuery);
+                const lines = [
+                    `**${playerId}** — phase: \`${info.phase}\``,
+                    `in-flight messages: ${info.inFlightCount}`,
+                ];
+                if (info.currentAttachment) {
+                    const a = info.currentAttachment;
+                    lines.push(`attached on: **${a.hostname}** (adapter: ${a.adapterId}/${a.adapterClass}, attachmentId: \`${a.attachmentId.slice(0, 8)}…\`)`);
+                    lines.push(`lease expires: ${a.expiresAt}`);
+                }
+                if (info.preferredHost)
+                    lines.push(`preferred host: ${info.preferredHost}`);
+                if (info.processingSince)
+                    lines.push(`processing since: ${info.processingSince}`);
+                return (0, descriptor_1.ok)(lines.join('\n'));
             }
-            if (info.preferredHost)
-                lines.push(`preferred host: ${info.preferredHost}`);
-            if (info.processingSince)
-                lines.push(`processing since: ${info.processingSince}`);
-            return (0, helpers_1.ok)(lines.join('\n'));
-        }
-        catch (err) {
-            return (0, helpers_1.fail)(`Failed to query attachment info: ${(0, helpers_1.formatError)(err)}`);
-        }
-    });
+            catch (err) {
+                return (0, descriptor_1.fail)(`Failed to query attachment info: ${(0, descriptor_1.formatError)(err)}`);
+            }
+        },
+    };
 }

package/dist/tools/broadcast.d.ts

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