@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/pi/pi-stream-fn.js

@@ -0,0 +1,504 @@
+/**
+ * Cleo-owned Pi `StreamFn` — the Gate-13-respecting LLM route (T11761 · S2 · T11898).
+ *
+ * Pi's agent loop performs every LLM call through a single pluggable seam: the
+ * `streamFn` passed as the 6th positional arg to `runAgentLoop`. The DEFAULT
+ * streamFn (`pi-ai`'s `streamSimple`) resolves a provider from `pi-ai`'s own
+ * registry and falls back to reading `process.env[<PROVIDER>_API_KEY]` when no
+ * explicit key is supplied — a credential-resolution path OUTSIDE Cleo's E9
+ * chokepoint, and a Gate-13 violation.
+ *
+ * {@link createPiStreamFn} supplies a Cleo-owned replacement that routes the
+ * loop's LLM calls through {@link resolveLLMForSystem} (the E9 resolution
+ * chokepoint) → {@link ModelRunner.build} (the single SSoT transport factory).
+ * Passing this streamFn to `runAgentLoop` means `pi-ai`'s `stream.ts` /
+ * `withEnvApiKey` is NEVER reached for the loop — the registry env-fallback
+ * cannot fire (foundation §5.1, the single most important suppression lever).
+ *
+ * ## Detached-producer teardown (T11898)
+ *
+ * The returned `StreamFn` MUST return its stream synchronously, so the async
+ * producer is detached (`void produce(...)`). To stop that producer outliving
+ * the call that started it, `ctx.signal` (the `wrapPiCall`-managed loop abort
+ * signal) is threaded into the per-call `SendOptions.signal` AND the producer's
+ * consumption loop bails on `signal.aborted` and explicitly returns the
+ * iterator. Teardown therefore holds even against a transport that ignores the
+ * signal option — closing the residual exit-escape window the daemon exit-guard
+ * (`installDaemonExitGuard`) backstops.
+ *
+ * ## Gate-13 cleanliness (verified)
+ *
+ * This file CALLS `resolveLLMForSystem` + `ModelRunner.build` only. It constructs
+ * NO transport (`new *Transport`), NO SDK client (`createAnthropic` /
+ * `new Anthropic`), reads NO `*_API_KEY` env var, and carries NO hardcoded model
+ * literal — all of that stays inside `model-runner.ts` / `transports/**` (the
+ * Gate-13 allowlist). The descriptor's `model` comes from the resolver
+ * (registry / role-config), never a literal here.
+ *
+ * ## Tool wire-through (T1739 — registry consumability)
+ *
+ * The Pi loop carries its tools (the agent registry's `toOpenAITools()` output) on
+ * `Context.tools`. {@link toTransportTools} projects them onto the per-call
+ * `SendOptions.tools`, which `ConcreteSession._buildRequest` forwards onto
+ * `TransportRequest.tools` — so the wire-level transport advertises them to the
+ * model. This closes the streamFn → transport tool link: registry tools given to
+ * the loop are reachable by the model. (Tool-CALL *execution* — binding Pi's
+ * `ExecutionEnv` onto the guarded surface — is a later subtask; only the schema
+ * advertisement flows here.)
+ *
+ * ## Zod ↔ TypeBox quarantine (Gate 10)
+ *
+ * Pi tool schemas are TypeBox, but `pi-ai`'s `validateToolArguments` also accepts
+ * plain JSON-schema tools. Cleo tool definitions are Zod (live in `core/src/llm/`).
+ * {@link zodToolToTransportTool} converts a Zod schema → JSON Schema via Zod v4's
+ * native `z.toJSONSchema` (NO `zod-to-json-schema` dep, NO typebox value-import),
+ * so the cleo↔Pi tool boundary carries ZERO typebox. {@link toTransportTools}
+ * passes the loop's Pi `Tool.parameters` (a TypeBox `TSchema` that is structurally
+ * a JSON Schema object) through verbatim — also WITHOUT a typebox value-import.
+ * typebox remains a transitive dep used only INSIDE `pi-agent-core`; it never
+ * appears in cleo source and never reaches `packages/contracts/`.
+ *
+ * @epic T10403
+ * @task T11761
+ * @task T11898
+ * @task T1739
+ */
+// VALUE import: the FACTORY that builds the stream Pi's `StreamFn` MUST return.
+// `AssistantMessageEventStream` itself collides in the `pi-ai` barrel (re-exported
+// both as a value AND as a type-only name), so the class cannot be value-imported;
+// `createAssistantMessageEventStream()` is the clean value export. Importing it
+// from the `pi-ai` barrel evaluates `register-builtins` (populates the registry
+// with inert lazy closures — NO env read, NO client construction at import;
+// foundation §3.2). We OWN the loop's LLM path via this custom streamFn, so the
+// registry is never CONSULTED — populated-but-unused, the accepted inert side
+// effect, not a leak.
+import { createAssistantMessageEventStream } from '@earendil-works/pi-ai';
+import { getLogger } from '../../logger.js';
+import { zodSchemaToOpenAITool } from '../../tools/schema-gen.js';
+import { ModelRunner } from '../model-runner.js';
+import { resolveLLMForSystem } from '../system-resolver.js';
+import { wrapPiError } from './pi-errors.js';
+/**
+ * Convert a Cleo Zod-schema tool into a JSON-schema {@link TransportTool}.
+ *
+ * Thin wrapper over the SINGLE shared generator
+ * {@link zodSchemaToOpenAITool} (`core/src/tools/schema-gen.ts`) so the Pi bridge
+ * and the agent registry (T1739 · AC3) share ONE conversion doctrine and cannot
+ * drift (DRY). Uses Zod v4's native `z.toJSONSchema` — no `zod-to-json-schema`
+ * dependency and, crucially, NO typebox value-import. The resulting `inputSchema`
+ * is a plain JSON Schema object the transport passes through verbatim.
+ *
+ * @param tool - The Cleo Zod tool.
+ * @returns The transport-shaped JSON-schema tool.
+ */
+export function zodToolToTransportTool(tool) {
+    return zodSchemaToOpenAITool(tool);
+}
+const logger = getLogger('pi-stream-fn');
+/**
+ * Build a Cleo-owned {@link StreamFn} for one Pi agent run.
+ *
+ * The returned function matches Pi's `StreamFn` contract structurally:
+ * `(model, context, options?) => AssistantMessageEventStream`. It MUST NOT throw
+ * — every failure is encoded as a terminal `error` event on the returned stream
+ * (Pi's never-throw streaming contract).
+ *
+ * Flow per call:
+ *   1. `resolveLLMForSystem(ctx.system)` — the E9 resolution chokepoint.
+ *   2. Build a clean {@link ResolvedLLMDescriptor} from the resolved fields.
+ *   3. `ModelRunner.build(descriptor)` — the single SSoT transport factory.
+ *   4. Stream `NormalizedDelta` chunks from the built transport session and
+ *      project them onto Pi's `AssistantMessageEvent` protocol, terminating with
+ *      a `done` (success) or `error` (failure) event.
+ *
+ * `pi-ai`'s `stream.ts` / `withEnvApiKey` is never reached — the registry
+ * env-fallback cannot fire for the loop.
+ *
+ * @param ctx - The Pi run context (system-of-use label + identity + signal).
+ * @returns A Cleo-owned `StreamFn`.
+ */
+export function createPiStreamFn(ctx) {
+    return (model, context, options) => {
+        const out = createAssistantMessageEventStream();
+        // Detach the async producer; the stream itself is returned synchronously so
+        // the loop can begin consuming immediately (Pi's contract).
+        void produce(out, model, context, options, ctx).catch((err) => {
+            // A failure escaping the producer is encoded as a terminal error event —
+            // never thrown (Pi's `StreamFn` must not throw / reject).
+            emitError(out, model, wrapPiError(err).message);
+        });
+        return out;
+    };
+}
+/**
+ * Drive the cleo transport session and project its deltas onto Pi's event stream.
+ *
+ * @param out - The Pi event stream to push events onto.
+ * @param model - Pi's model descriptor for this call (id/provider/api carried for
+ *   the terminal `AssistantMessage` shape; resolution is by `ctx.system`, NOT by
+ *   this model id — the resolver/registry is the SSoT).
+ * @param context - The Pi request context (system prompt + messages + tools). The
+ *   `tools` (the agent registry's `toOpenAITools()` output, set on `Context.tools`
+ *   by the loop) are projected onto the per-call `SendOptions.tools` →
+ *   `TransportRequest.tools`, so the wire-level transport advertises them.
+ * @param _options - Pi stream options (reserved; thinking/temperature flow via
+ *   the resolved descriptor's capabilities in a later subtask).
+ * @param ctx - The Pi run context (system-of-use label + loop abort `signal`
+ *   threaded into the per-call `SendOptions` and the producer teardown).
+ */
+async function produce(out, model, context, _options, ctx) {
+    // 1. E9 resolution chokepoint. Never throws (resolver contract).
+    const resolved = await resolveLLMForSystem(ctx.system, {
+        ...(ctx.projectRoot !== undefined ? { projectRoot: ctx.projectRoot } : {}),
+    });
+    if (!resolved.sealedCredential && resolved.authType !== 'aws_sdk') {
+        // No credential reachable — surface a typed terminal error (graceful: the
+        // loop sees an error AssistantMessage and stops, the daemon is unharmed).
+        emitError(out, model, `no credential resolved for system "${ctx.system}"`);
+        return;
+    }
+    // 2. Clean descriptor from resolved fields (NO model literal here — the model
+    //    is whatever the resolver/registry produced). The plaintext token is
+    //    materialized from the sealed handle ONLY here, at the wire boundary that
+    //    feeds ModelRunner — never carried inline on the resolver envelope (E10).
+    const descriptor = await toDescriptor(resolved);
+    // 3. Single SSoT transport factory. The transport/client construction lives
+    //    inside ModelRunner — this file constructs nothing.
+    const built = await ModelRunner.build(descriptor);
+    // 4. Stream deltas → Pi events.
+    const aggregate = freshAssistantMessage(descriptor.model, model);
+    out.push({ type: 'start', partial: aggregate });
+    const messages = toTransportMessages(context);
+    let text = '';
+    let stop = 'stop';
+    let started = false;
+    // Thread the run's abort signal into the per-call SendOptions so the session
+    // can observe it. The signal is the SAME `wrapPiCall`-managed signal handed to
+    // the loop — when the loop aborts (or `wrapPiCall` settles/tears down), this
+    // detached producer is told to stop. CRUCIALLY, abort teardown does NOT rely on
+    // the transport honouring the signal: the `for await` below also bails on
+    // `signal.aborted` and explicitly returns the iterator, so the producer cannot
+    // outlive the call even against a transport that ignores the option (T11898).
+    const signal = ctx.signal;
+    if (signal?.aborted) {
+        emitAborted(out, model);
+        return;
+    }
+    // Thread the loop's tools (the agent registry's `toOpenAITools()` output, set on
+    // `Context.tools` by the loop) onto the per-call `SendOptions` so the wire-level
+    // transport advertises them to the model. This is the streamFn → session.stream
+    // → `TransportRequest.tools` link that makes registry tools reachable by the
+    // model. Omitted when the loop carries no tools (a tool-free call).
+    const tools = toTransportTools(context);
+    const sendOpts = signal && tools.length > 0
+        ? { signal, tools }
+        : signal
+            ? { signal }
+            : tools.length > 0
+                ? { tools }
+                : {};
+    const stream = built.session.stream(messages, sendOpts);
+    const iterator = stream[Symbol.asyncIterator]();
+    // Proactive teardown: the instant the signal aborts — even mid-`next()` await —
+    // call the iterator's `return()` so a transport that ignores `SendOptions.signal`
+    // still has its underlying stream torn down. The per-iteration `signal.aborted`
+    // check below is the cooperative second line that emits the terminal event.
+    const onAbort = () => {
+        void closeIterator(iterator);
+    };
+    if (signal)
+        signal.addEventListener('abort', onAbort, { once: true });
+    try {
+        while (true) {
+            if (signal?.aborted) {
+                // Loop aborted (or wrapPiCall settled) — tear the iterator down so the
+                // detached producer stops streaming, then emit a terminal aborted event.
+                await closeIterator(iterator);
+                emitAborted(out, model);
+                return;
+            }
+            const next = await iterator.next();
+            if (next.done)
+                break;
+            const delta = next.value;
+            if (delta.text) {
+                if (!started) {
+                    started = true;
+                    out.push({ type: 'text_start', contentIndex: 0, partial: aggregate });
+                }
+                text += delta.text;
+                setText(aggregate, text);
+                out.push({ type: 'text_delta', contentIndex: 0, delta: delta.text, partial: aggregate });
+            }
+            if (delta.stopReason) {
+                stop = normalizeStop(delta.stopReason);
+            }
+        }
+    }
+    catch (err) {
+        // An abort surfacing as a thrown error → terminal aborted event; any other
+        // mid-stream transport failure → terminal error event (never thrown).
+        await closeIterator(iterator);
+        if (signal?.aborted || isAbortError(err)) {
+            emitAborted(out, model);
+            return;
+        }
+        emitError(out, model, wrapPiError(err).message);
+        return;
+    }
+    finally {
+        // Always detach the abort listener — every early `return` above runs this.
+        if (signal)
+            signal.removeEventListener('abort', onAbort);
+    }
+    if (started) {
+        out.push({ type: 'text_end', contentIndex: 0, content: text, partial: aggregate });
+    }
+    setText(aggregate, text);
+    aggregate.stopReason = stop;
+    logger.debug({ system: ctx.system, model: descriptor.model, stop }, 'pi stream complete');
+    out.push({ type: 'done', reason: doneReason(stop), message: aggregate });
+    out.end(aggregate);
+}
+/**
+ * Build a {@link ResolvedLLMDescriptor} from a resolved-for-system envelope.
+ *
+ * Only the descriptor surface `ModelRunner.build` consumes is projected — the
+ * resolver's extra `client` field is dropped so no SDK client leaks through this
+ * boundary. The `model` comes from the resolver (registry/role-config), never a
+ * literal.
+ *
+ * E10 (T11753): the plaintext token is materialized HERE — at the wire boundary
+ * that feeds `ModelRunner` — by invoking `resolved.sealedCredential.fetch()`.
+ * It is written into the descriptor's `credential.apiKey` (consumed only inside
+ * the `ModelRunner` chokepoint) and never returned up the resolver stack. This
+ * is async because `fetch()` is the on-demand decrypt point.
+ *
+ * @param resolved - The `resolveLLMForSystem` envelope.
+ * @returns A clean descriptor for `ModelRunner.build`.
+ */
+async function toDescriptor(resolved) {
+    // Materialize the plaintext from the sealed handle ONLY at this wire boundary.
+    const apiKey = resolved.sealedCredential ? (await resolved.sealedCredential.fetch()).value : null;
+    return {
+        provider: resolved.provider,
+        model: resolved.model,
+        credential: resolved.credential
+            ? {
+                provider: resolved.credential.provider,
+                apiKey,
+                source: resolved.credential.source,
+                authType: resolved.credential.authType,
+            }
+            : null,
+        source: resolved.source,
+        ...(resolved.credentialLabel !== undefined
+            ? { credentialLabel: resolved.credentialLabel }
+            : {}),
+        apiMode: resolved.apiMode,
+        baseUrl: resolved.baseUrl,
+        authType: resolved.authType,
+        ...(resolved.capabilities !== undefined ? { capabilities: resolved.capabilities } : {}),
+    };
+}
+/**
+ * Project a Pi {@link Context} onto Cleo {@link TransportMessage}s.
+ *
+ * Pi messages carry rich content blocks; for the v0 read/stream path we project
+ * to the transport's text form. The system prompt is threaded separately by the
+ * transport (carried on the request, not as a message), so only user/assistant/
+ * tool turns are mapped.
+ *
+ * @param context - Pi's request context.
+ * @returns Cleo transport messages.
+ */
+function toTransportMessages(context) {
+    return context.messages.map((m) => {
+        const role = m.role === 'assistant' ? 'assistant' : m.role === 'toolResult' ? 'tool' : 'user';
+        const content = extractText(m);
+        const msg = { role, content };
+        if (m.role === 'toolResult' && m.toolCallId) {
+            return { ...msg, toolUseId: m.toolCallId };
+        }
+        return msg;
+    });
+}
+/**
+ * Project the Pi {@link Context}'s tools onto OpenAI-format {@link TransportTool}[]
+ * for the wire request.
+ *
+ * The agent registry (T1739) emits OpenAI-format tools via `toOpenAITools()`; the
+ * Pi loop carries tools on `Context.tools` as Pi `Tool`s whose `parameters` is a
+ * TypeBox `TSchema` — which IS a plain JSON Schema object at runtime. We map it
+ * straight onto `inputSchema` WITHOUT importing typebox's `Value` (Gate-10 / Zod↔
+ * TypeBox quarantine): the schema object is passed through structurally. This is
+ * the `streamFn → SendOptions.tools → TransportRequest.tools` link that makes the
+ * registry's tools reachable by the model.
+ *
+ * @param context - The Pi request context.
+ * @returns OpenAI-format transport tools (empty when the context carries none).
+ */
+function toTransportTools(context) {
+    const tools = context.tools;
+    if (!tools || tools.length === 0)
+        return [];
+    return tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        // `t.parameters` is a TypeBox `TSchema`, structurally a JSON Schema object.
+        // Structural pass-through — no typebox value-import crosses the boundary.
+        inputSchema: t.parameters,
+    }));
+}
+/**
+ * Extract a plain-text representation of a Pi message's content for the v0
+ * transport projection.
+ *
+ * @param m - A Pi message (user/assistant/toolResult).
+ * @returns The concatenated visible text.
+ */
+function extractText(m) {
+    const content = m.content;
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((c) => typeof c === 'object' && c !== null && 'text' in c ? String(c.text) : '')
+            .join('');
+    }
+    return '';
+}
+/** Build a fresh, empty Pi {@link AssistantMessage} to accumulate the response into. */
+function freshAssistantMessage(model, piModel) {
+    return {
+        role: 'assistant',
+        content: [],
+        api: piModel.api,
+        provider: piModel.provider,
+        model,
+        usage: zeroUsage(),
+        stopReason: 'stop',
+        timestamp: Date.now(),
+    };
+}
+/** Set (or replace) the single text content block on an accumulating message. */
+function setText(message, text) {
+    const block = { type: 'text', text };
+    // Replace the content array with a single text block (v0 — no tool-call/
+    // thinking projection on this path yet).
+    message.content = text ? [block] : [];
+}
+/** A zeroed {@link AssistantMessage} usage record (token accounting is S3+). */
+function zeroUsage() {
+    return {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        totalTokens: 0,
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    };
+}
+/** Map a Cleo normalized stop-reason string onto Pi's {@link StopReason} union. */
+function normalizeStop(reason) {
+    switch (reason) {
+        case 'length':
+        case 'max_tokens':
+            return 'length';
+        case 'tool_use':
+        case 'toolUse':
+            return 'toolUse';
+        case 'error':
+            return 'error';
+        case 'aborted':
+            return 'aborted';
+        default:
+            return 'stop';
+    }
+}
+/** Narrow a {@link StopReason} to the subset valid on Pi's `done` event. */
+function doneReason(stop) {
+    return stop === 'length' ? 'length' : stop === 'toolUse' ? 'toolUse' : 'stop';
+}
+/**
+ * Emit a terminal `error` event + `end` on a Pi stream (the never-throw failure
+ * channel). Used for resolution/credential/transport failures.
+ *
+ * @param out - The Pi event stream.
+ * @param piModel - The Pi model descriptor (for the error AssistantMessage shape).
+ * @param message - Human-readable failure reason.
+ */
+function emitError(out, piModel, message) {
+    const errMsg = {
+        role: 'assistant',
+        content: [],
+        api: piModel.api,
+        provider: piModel.provider,
+        model: piModel.id,
+        usage: zeroUsage(),
+        stopReason: 'error',
+        errorMessage: message,
+        timestamp: Date.now(),
+    };
+    out.push({ type: 'error', reason: 'error', error: errMsg });
+    out.end(errMsg);
+}
+/**
+ * Emit a terminal aborted `error` event + `end` on a Pi stream.
+ *
+ * Distinct from {@link emitError}: an abort is an intentional teardown (loop
+ * cancelled / `wrapPiCall` settled), so the terminal message carries
+ * `stopReason: 'aborted'` rather than `'error'`. The daemon survives either way;
+ * this just gives the loop the precise terminal reason.
+ *
+ * @param out - The Pi event stream.
+ * @param piModel - The Pi model descriptor (for the aborted AssistantMessage shape).
+ */
+function emitAborted(out, piModel) {
+    const abortedMsg = {
+        role: 'assistant',
+        content: [],
+        api: piModel.api,
+        provider: piModel.provider,
+        model: piModel.id,
+        usage: zeroUsage(),
+        stopReason: 'aborted',
+        errorMessage: 'pi stream aborted',
+        timestamp: Date.now(),
+    };
+    out.push({ type: 'error', reason: 'error', error: abortedMsg });
+    out.end(abortedMsg);
+}
+/**
+ * Tear down a stream iterator on abort/failure so the detached producer cannot
+ * keep the underlying transport stream open after the call has ended.
+ *
+ * Calls the iterator's optional `return()` (the async-iterator cancellation
+ * hook) and swallows any error it raises — teardown is best-effort and MUST NOT
+ * throw past the never-throw producer boundary.
+ *
+ * @param iterator - The async iterator driving the transport stream.
+ */
+async function closeIterator(iterator) {
+    try {
+        await iterator.return?.();
+    }
+    catch {
+        // Best-effort teardown — a transport that throws on early return must not
+        // escape the producer (Pi's StreamFn never throws).
+    }
+}
+/**
+ * Whether a thrown value represents an abort (a `DOMException`/`Error` whose
+ * `name` is `AbortError`).
+ *
+ * @param err - The thrown value.
+ * @returns `true` when `err` is an abort error.
+ */
+function isAbortError(err) {
+    return (typeof err === 'object' &&
+        err !== null &&
+        'name' in err &&
+        err.name === 'AbortError');
+}
+//# sourceMappingURL=pi-stream-fn.js.map

package/dist/llm/pi/pi-stream-fn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-stream-fn.js","sourceRoot":"","sources":["../../../src/llm/pi/pi-stream-fn.ts"],"names":[],"mappings":"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"}

package/dist/llm/pi/pi-tool-bridge.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Pi ↔ dispatch-engine bridge (T1740 · AC6 · epic T11456).
+ *
+ * Closes the agent tool-call loop for the in-process Pi runner. Pi's agent loop
+ * executes a tool the model emits by calling the `execute(toolCallId, params,
+ * signal)` method of the matching `AgentTool` it finds on `AgentContext.tools`.
+ * Before T1740 the Pi adapter advertised the registry's tool SCHEMAS to the
+ * model (`pi-stream-fn.ts` → `SendOptions.tools`) but supplied NO executables —
+ * so a model tool-call had nothing to run and the loop could only stream text.
+ *
+ * {@link buildPiAgentTools} projects the {@link AgentToolRegistry} into the
+ * `AgentTool[]` the loop needs, binding each tool's `execute` body to the T1740
+ * {@link ToolDispatchEngine}. When the model emits a tool call, Pi invokes the
+ * bound `execute`, which runs the call THROUGH the dispatch engine — lookup +
+ * Zod-validate + availability + budget + guarded execution + LLM-safe
+ * formatting — and returns the classified result as an `AgentToolResult` Pi
+ * feeds back to the model as a `tool_result`. That is the closed loop:
+ *
+ *   model tool-call → Pi AgentTool.execute → ToolDispatchEngine.dispatch →
+ *   GuardedToolSurface side effect → formatted result → back to the model.
+ *
+ * ## Boundary cleanliness
+ *
+ * - **Gate-11** — this module defines NO atomic tool primitive; it CONSUMES the
+ *   frozen registry (`toOpenAITools`-shaped schemas) and the dispatch engine.
+ * - **Gate-13** — no LLM resolution / transport / client construction here; the
+ *   only LLM route stays in {@link createPiStreamFn}. Tool execution is pure
+ *   side-effect dispatch through the guard.
+ * - **Gate-10** — the Pi `AgentTool.parameters` is a TypeBox `TSchema`; the
+ *   registry carries Zod. We convert via the shared {@link zodSchemaToOpenAITool}
+ *   generator (Zod v4 native `z.toJSONSchema`) and pass the resulting JSON-Schema
+ *   object through as the (structurally-compatible) `parameters` WITHOUT a
+ *   typebox value-import, matching `pi-stream-fn.ts`'s quarantine.
+ *
+ * @task T1740
+ * @epic T11456
+ * @see ../../tools/dispatch.js — the dispatch engine this binds the loop to
+ * @see ./pi-stream-fn.js — the sibling that advertises the same tools' schemas
+ */
+import type { AgentToolRegistry } from '../../tools/agent-registry.js';
+import type { ToolDispatchEngine, ToolDispatchResult } from '../../tools/dispatch.js';
+/**
+ * The minimal `AgentTool` shape `pi-agent-core` requires on
+ * `AgentContext.tools`. Declared structurally here (NOT a type-only import of
+ * `@earendil-works/pi-agent-core`'s `AgentTool`) so the bridge stays decoupled
+ * from the loop package's generic `TSchema`/`TDetails` parameterization and so a
+ * `pi-agent-core` minor cannot silently widen the contract we satisfy. The
+ * fields mirror `AgentTool` member-for-member; the loop reads exactly these.
+ */
+export interface PiBridgeAgentTool {
+    /** Model-visible tool name. */
+    readonly name: string;
+    /** Human-readable description shown to the model. */
+    readonly description: string;
+    /** JSON-Schema (TypeBox-structural) parameter schema for the model. */
+    readonly parameters: Record<string, unknown>;
+    /** UI label (Pi requires it; we reuse the name). */
+    readonly label: string;
+    /**
+     * Execute the tool call. Pi calls this when the model emits a matching
+     * tool-call; it routes THROUGH the dispatch engine and returns the formatted
+     * result content. Never throws — a dispatch failure becomes an error-flagged
+     * `AgentToolResult` so the loop can feed it back and continue.
+     */
+    execute(toolCallId: string, params: unknown, signal?: AbortSignal): Promise<PiBridgeToolResult>;
+}
+/**
+ * The `AgentToolResult` subset the loop reads back from {@link
+ * PiBridgeAgentTool.execute}. `content` is the model-facing `tool_result` body;
+ * `details` carries the structured {@link ToolDispatchResult} for logs/UI; a
+ * dispatch failure is reported via the content + the `isError`-style detail.
+ */
+export interface PiBridgeToolResult {
+    /** Text content blocks fed back to the model (one text block in v0). */
+    readonly content: readonly {
+        readonly type: 'text';
+        readonly text: string;
+    }[];
+    /** Structured dispatch result for logs / UI rendering. */
+    readonly details: ToolDispatchResult;
+}
+/**
+ * Project an {@link AgentToolRegistry} into the `AgentTool[]` the Pi loop
+ * executes, binding every tool's `execute` to the shared {@link
+ * ToolDispatchEngine} (AC6).
+ *
+ * One {@link ToolDispatchEngine} instance is shared across all returned tools so
+ * the run-scoped budget (call count / time ceilings) is enforced ACROSS the
+ * whole turn, not per tool. Each `execute`:
+ *   1. wraps Pi's `(toolCallId, params)` into a {@link ToolCall};
+ *   2. dispatches it through the engine (validate → availability → budget →
+ *      guarded execution → format);
+ *   3. returns the formatted content as an `AgentToolResult` Pi feeds back.
+ *
+ * @param engine - The dispatch engine (carries registry + guard + budget).
+ * @returns The `AgentTool[]` to assign to `AgentContext.tools`.
+ */
+export declare function buildPiAgentTools(engine: ToolDispatchEngine, registry: AgentToolRegistry): PiBridgeAgentTool[];
+//# sourceMappingURL=pi-tool-bridge.d.ts.map

package/dist/llm/pi/pi-tool-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-tool-bridge.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-tool-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAGH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AACvE,OAAO,KAAK,EAAY,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAKhG;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAiB;IAChC,+BAA+B;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAAC;CACjG;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,SAAS;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9E,0DAA0D;IAC1D,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;CACtC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,kBAAkB,EAC1B,QAAQ,EAAE,iBAAiB,GAC1B,iBAAiB,EAAE,CAsCrB"}