agent-tempo 1.3.1 → 1.4.1

package/dist/pi/workflow-client.js

@@ -0,0 +1,289 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PiWorkflowClient = exports.PI_LEASE_MS = exports.PI_HEARTBEAT_MS = void 0;
+/**
+ * Thin CLIENT-SIDE Temporal wrapper for the Pi extension (D4 = (a)).
+ *
+ * The durable Temporal `Worker` stays in the daemon. This holds only a
+ * `WorkflowClient` that signals/queries/updates the session workflow — it never
+ * runs workflow code, so NOTHING here (or anywhere in src/pi/) is imported into
+ * the V8 workflow sandbox. The determinism boundary is preserved.
+ *
+ * Reuses the existing wire surface verbatim:
+ *   - `claimAttachment` / `heartbeat`        — lease lifecycle (drives `attached`)
+ *   - `processingStart` / `processingEnd`    — drives `processing` / `awaiting`
+ *   - `requestDetach` + `adapterExited`      — drives `draining` → `detached`
+ *   - `submitOutbox`                         — report routing (outbox compliance)
+ *   - `pendingMessages` + `markDelivered`    — cue intake + ack
+ */
+const client_1 = require("@temporalio/client");
+const connection_1 = require("../connection");
+const config_1 = require("../config");
+const signals_1 = require("../workflows/signals");
+/** Adapter identity advertised on claim. Pi interactive players are `interactive`-class. */
+const PI_ADAPTER_ID = 'pi';
+/**
+ * MD-A liveness timings (Phase 2, maintainer-approved): 30s heartbeat / 90s
+ * lease, holding the **lease = 3×heartbeat** invariant — a single (or even
+ * second) missed beat never expires the lease, but a dead process is reaped
+ * within ~one lease window. Parity with the other SDK adapters' `heartbeatMs`.
+ * Overridable per-session via `PiWorkflowClientOptions.{leaseMs,heartbeatMs}`.
+ * Exported so a guard test can assert the invariant doesn't silently drift.
+ */
+exports.PI_HEARTBEAT_MS = 30_000;
+exports.PI_LEASE_MS = 90_000;
+const log = (...args) => {
+    // eslint-disable-next-line no-console
+    console.error('[agent-tempo:pi]', ...args);
+};
+/**
+ * One instance per attached Pi session — holds the session `WorkflowHandle`,
+ * lease token, and heartbeat timer for one fixed-workflowId player. Tool
+ * handlers reach this player's handle via the D11 lazy proxy (`get handle()`).
+ */
+class PiWorkflowClient {
+    client;
+    config;
+    metadata;
+    leaseMs;
+    heartbeatMs;
+    expectedAttachmentId;
+    coarseProvider;
+    wfHandle = null;
+    token = null;
+    heartbeatTimer = null;
+    constructor(opts) {
+        this.client = opts.client;
+        this.config = opts.config;
+        this.metadata = opts.metadata;
+        this.leaseMs = opts.leaseMs ?? exports.PI_LEASE_MS;
+        this.heartbeatMs = opts.heartbeatMs ?? exports.PI_HEARTBEAT_MS;
+        this.expectedAttachmentId = opts.expectedAttachmentId;
+        this.coarseProvider = opts.coarseProvider;
+    }
+    /**
+     * 3c — wire the coarse-activity provider after construction (the inner-loop
+     * publisher is created alongside, then handed in). Each heartbeat samples it.
+     */
+    setCoarseProvider(provider) {
+        this.coarseProvider = provider;
+    }
+    /** Build a client from config (connection-pooled; safe to share — see D12a). */
+    static async connect(config = (0, config_1.getConfig)()) {
+        const connection = await (0, connection_1.createTemporalConnection)(config);
+        return new client_1.Client({ connection, namespace: config.temporalNamespace });
+    }
+    get attachmentId() {
+        return this.token?.attachmentId ?? null;
+    }
+    /**
+     * The live session `WorkflowHandle`, or `null` before {@link ensureSessionWorkflow}.
+     * Exposed so the D11 lazy-proxy (src/pi/lazy-proxy.ts) can resolve the player's
+     * OWN handle per tool call — tool handlers route through it (e.g. `submitOutbox`)
+     * and never `.signal()` a peer workflow directly.
+     */
+    get handle() {
+        return this.wfHandle;
+    }
+    get workflowId() {
+        return (0, config_1.sessionWorkflowId)(this.metadata.ensemble, this.metadata.playerId);
+    }
+    /**
+     * Ensure the session workflow exists and grab a handle. For a human-launched
+     * `pi`, the workflow may not exist yet; `USE_EXISTING` makes this idempotent
+     * when `agent-tempo up`/recruit already started it.
+     */
+    async ensureSessionWorkflow() {
+        if (this.wfHandle)
+            return this.wfHandle;
+        this.wfHandle = await this.client.workflow.start('agentSessionWorkflow', {
+            workflowId: this.workflowId,
+            taskQueue: this.config.taskQueue,
+            workflowIdConflictPolicy: 'USE_EXISTING',
+            args: [{ metadata: this.metadata, phase: 'booting' }],
+        });
+        return this.wfHandle;
+    }
+    requireHandle() {
+        if (!this.wfHandle) {
+            throw new Error('PiWorkflowClient: call ensureSessionWorkflow() before lifecycle ops');
+        }
+        return this.wfHandle;
+    }
+    /**
+     * Claim (or, with a handoff token, ADOPT) the attachment: phase
+     * `booting → attached`. Fresh claim when `expectedAttachmentId` is absent;
+     * renewal/adoption branch when the restart tool handed one in. Stores the token.
+     */
+    async claim() {
+        const handle = this.requireHandle();
+        this.token = await handle.executeUpdate(signals_1.claimAttachmentUpdate, {
+            args: [
+                {
+                    host: this.metadata.hostname,
+                    adapterId: PI_ADAPTER_ID,
+                    adapterClass: 'interactive',
+                    leaseMs: this.leaseMs,
+                    ...(this.expectedAttachmentId ? { expectedAttachmentId: this.expectedAttachmentId } : {}),
+                },
+            ],
+        });
+        log(`${this.expectedAttachmentId ? 'renewed' : 'claimed'} attachment ` +
+            `${this.token.attachmentId} (lease ${this.leaseMs}ms)`);
+        return this.token;
+    }
+    /**
+     * Liveness heartbeat — renews the lease. This is the ENTIRE reason an abrupt
+     * Pi death is detectable: stop heart-beating and `expiresAt` lapses (see
+     * src/pi/README.md "Abrupt-death finding" / MD-A).
+     */
+    async heartbeat() {
+        if (!this.token)
+            return;
+        const handle = this.requireHandle();
+        // 3c Tier-1 — piggyback the latest coarse sample (currentTool + context).
+        // Sampled per-beat; a throwing/absent provider degrades to a plain heartbeat.
+        let coarse;
+        try {
+            coarse = this.coarseProvider?.();
+        }
+        catch {
+            coarse = undefined;
+        }
+        await handle.signal(signals_1.heartbeatSignal, {
+            attachmentId: this.token.attachmentId,
+            at: new Date().toISOString(),
+            ...(coarse ? coarse : {}),
+        });
+    }
+    /** Start the heartbeat loop. The timer is `unref`'d so it never holds the process open. */
+    startHeartbeat() {
+        if (this.heartbeatTimer)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            this.heartbeat().catch((err) => log('heartbeat failed:', err));
+        }, this.heartbeatMs);
+        if (typeof this.heartbeatTimer.unref === 'function')
+            this.heartbeatTimer.unref();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    /** agent_start → phase `processing`. */
+    async processingStart(messageId) {
+        const handle = this.requireHandle();
+        await handle.executeUpdate(signals_1.processingStartUpdate, {
+            args: [{ messageId, expectedAttachmentId: this.token?.attachmentId }],
+        });
+    }
+    /** agent_end → phase `awaiting`. */
+    async processingEnd(messageId) {
+        const handle = this.requireHandle();
+        await handle.executeUpdate(signals_1.processingEndUpdate, {
+            args: [{ messageId, expectedAttachmentId: this.token?.attachmentId }],
+        });
+    }
+    /**
+     * Graceful self-initiated detach: stopHeartbeat → adapterExited (→ detached).
+     *
+     * `adapterExited` ALONE collapses any live phase (attached/processing/awaiting/
+     * draining) straight to `detached` — see the workflow handler at
+     * `session.ts` adapterExitedSignal (returns early only on detached/gone). No
+     * `requestDetach` is needed for a self-exit; that signal is the EXTERNAL ask to
+     * drain a running adapter someone else controls. This matches the proven
+     * `BaseAttachment.stopV2Lifecycle(graceful)` path. Idempotent-safe to call on
+     * `session_shutdown` and from the headless exit sequence.
+     */
+    async detach(reason = 'agent-exited') {
+        if (!this.wfHandle || !this.token)
+            return;
+        this.stopHeartbeat();
+        // Signal-DELIVERY (not a processing-ack) is sufficient by design, ruled won't-fix:
+        // the session workflow runs in the DAEMON worker, not this Pi process, so once
+        // signal() resolves the exit is durably in history and the worker transitions to
+        // `detached` regardless of this process disposing/exiting. stopHeartbeat() above is
+        // the independent backstop — a missed transition still reaps via lease expiry. No
+        // caller reads phase synchronously at detach()-return, so an executeUpdate ack would
+        // only add shutdown latency + drag determinism-sensitive workflow code into scope.
+        // If a future synchronous re-claim/migrate ever needs an OBSERVED `detached`, poll the
+        // existing attachmentInfoQuery client-side — never add an adapterExitedUpdate.
+        await this.wfHandle.signal(signals_1.adapterExitedSignal, {
+            attachmentId: this.token.attachmentId,
+            reason,
+        });
+        log(`detached (${reason})`);
+    }
+    /**
+     * Stash the currently-active Pi SessionManager session id onto durable
+     * workflow metadata (`metadata.sessionId`). This is the MUTABLE resume pointer
+     * — SEPARATE from the fixed workflowId (identity). A later restart of this
+     * player reads it to resume the same conversation via Pi `continueSession`
+     * (reuses the #334 sessionId resume field). No-op when the id is absent.
+     */
+    async updateSessionId(sessionId) {
+        if (!sessionId)
+            return;
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.updateMetadataSignal, { sessionId });
+    }
+    // ── Outbox ──
+    /** Route an outbox entry through the workflow outbox (player's own handle). */
+    async submitOutbox(entry) {
+        const handle = this.requireHandle();
+        return handle.executeUpdate(signals_1.submitOutboxUpdate, { args: [entry] });
+    }
+    // ── Cue intake ──
+    /** Pull undelivered messages (cues) queued on the workflow. */
+    async fetchPending() {
+        const handle = this.requireHandle();
+        return handle.query(signals_1.pendingMessagesQuery);
+    }
+    /** Acknowledge delivered cue ids so the workflow stops re-serving them. */
+    async ackDelivered(messageIds) {
+        if (messageIds.length === 0)
+            return;
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.markDeliveredSignal, messageIds);
+    }
+    // ── Reset intake (3d D14) ──
+    /** Poll the workflow's single-slot pending reset (null = none). */
+    async fetchPendingReset() {
+        const handle = this.requireHandle();
+        return handle.query(signals_1.pendingResetQuery);
+    }
+    /**
+     * Ack a performed reset by id — the workflow clears the slot ONLY if the id
+     * still matches (race-safe: a newer reset that landed mid-wipe is preserved).
+     */
+    async ackReset(resetId) {
+        const handle = this.requireHandle();
+        await handle.signal(signals_1.ackResetSignal, resetId);
+    }
+    /**
+     * Dispatch a {@link WorkflowAction} produced by {@link PhaseDriver}. Centralizes
+     * the action→wire-call mapping so the extension wiring stays declarative.
+     */
+    async performAction(action) {
+        switch (action.kind) {
+            case 'claim':
+                await this.claim();
+                this.startHeartbeat();
+                return;
+            case 'processingStart':
+                await this.processingStart(action.messageId);
+                return;
+            case 'processingEnd':
+                await this.processingEnd(action.messageId);
+                return;
+            case 'detach':
+                await this.detach();
+                return;
+            case 'none':
+                return;
+        }
+    }
+}
+exports.PiWorkflowClient = PiWorkflowClient;

package/dist/pi/zod-to-typebox.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Narrow zod → TypeBox converter (D1 / MD-B, Phase 1).
+ *
+ * agent-tempo tools declare their parameters as a `z.ZodRawShape`
+ * (`Record<string, z.ZodTypeAny>`) — the exact object handed to
+ * `McpServer.tool(...)` today (see `src/tools/helpers.ts` `defineTool`). The Pi
+ * front-end (`pi.registerTool({ parameters })`) wants a TypeBox schema instead.
+ * This module derives the TypeBox object schema from the zod shape so **zod
+ * stays the single source of truth** and the two surfaces cannot drift.
+ *
+ * DESIGN: this is deliberately NOT a general-purpose zod→TypeBox shim. It
+ * handles ONLY the feature subset the ~30 tools actually use (audited
+ * 2026-06-03) and **throws** — naming the field + feature — on anything else.
+ * Failing loud is the whole point (D1): a faithless silent conversion would
+ * ship a wrong tool schema to the model. The CI parity test (Track A / S5b)
+ * asserts the converter raised on nothing across the real tool set, so any new
+ * unaudited zod construct trips CI instead of producing a bad schema.
+ *
+ * Supported subset:
+ *   - z.string()  (+ .min/.max → minLength/maxLength, .regex → pattern)
+ *   - z.number()  (+ .int() → integer, .min/.max → minimum/maximum [inclusive])
+ *   - z.boolean()
+ *   - z.enum([...])            → Type.Union of Type.Literal (anyOf of const)
+ *   - z.array(inner)           (+ .min/.max → minItems/maxItems)
+ *   - z.object({...})          (nested; appears as an array element today)
+ *   - z.union([...])           SCALAR members only (string/number/boolean/enum/
+ *                              literal) — object/array/nested-union members throw
+ *   - .optional()              → Type.Optional (drops the field from `required`)
+ *   - .describe(s)             → TypeBox `{ description: s }` (Pi surfaces it)
+ *
+ * Everything else (.default, .nullable, .refine/.transform, .coerce, .email,
+ * .gt/.lt, z.record/any/unknown/null/date/tuple/intersection/nativeEnum, …)
+ * raises {@link UnsupportedZodFeatureError}.
+ *
+ * `.min`/`.max` are CONTEXT-SENSITIVE — the same modifier maps to
+ * minLength/maxLength (string), minimum/maximum (number), or minItems/maxItems
+ * (array) depending on the base zod type. The mapping is keyed on the base
+ * type, never on the modifier alone.
+ *
+ * TypeBox note (D12, confirmed): a TypeBox `Type.*` value IS a plain JSON-Schema
+ * object at runtime (`{ type, required, properties, … }`), so the output drops
+ * straight into Pi's `parameters` field with no further transform.
+ */
+import { z } from 'zod';
+import { type TObject } from 'typebox';
+/** Where in the schema we are, for actionable error messages. */
+interface ConvertContext {
+    /** Tool name, when the caller supplies it (richer errors). */
+    readonly tool?: string;
+    /** Dotted field path within the shape, e.g. `evaluations.status`. */
+    readonly path: string;
+}
+/**
+ * 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.
+ */
+export declare class UnsupportedZodFeatureError extends Error {
+    readonly context: ConvertContext;
+    readonly feature: string;
+    constructor(context: ConvertContext, feature: string);
+}
+/**
+ * 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.
+ */
+export declare function zodShapeToTypeBox(shape: z.ZodRawShape, toolName?: string): TObject;
+export {};

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}.