@cleocode/core 2026.6.12 → 2026.6.13

package/dist/llm/pi/pi-session-storage.d.ts

@@ -0,0 +1,154 @@
+/**
+ * `CleoSessionStorage` — durable Pi `SessionStorage` over `cleo.db` (T11761 · S3 · T11899).
+ *
+ * The flag-ON, durable half of the Pi session-persistence seam. It implements
+ * Pi's tree-structured `SessionStorage` interface
+ * (`@earendil-works/pi-agent-core`) over the PROJECT-scope consolidated
+ * `cleo.db`, with ZERO write authority:
+ *
+ *  - **All durable writes go through {@link withWriterLease}** (`writer-lease.ts`,
+ *    PROJECT scope + `bulk` lane) — the daemon remains the sole arbitrated
+ *    Drizzle writer. This adapter NEVER opens a raw DB writer (Gate 3): it calls
+ *    the store-layer accessor ({@link import('../../store/pi-session-store.js')}),
+ *    which extracts the native handle the chokepoint already holds.
+ *  - **Identity is daemon-stamped, never minted.** The owning `sessionId` is
+ *    supplied at construction from `resolveCurrentSessionId` / `CLEO_SESSION_ID`
+ *    (resolved in `pi-agent-adapter.ts`). Unlike `InMemorySessionStorage`, this
+ *    storage NEVER calls `uuidv7()` to mint an id.
+ *
+ * {@link InMemorySessionStorage} (from `pi-agent-core`) remains the flag-OFF
+ * default that the S2 adapter body uses; this durable storage activates only when
+ * the Pi-runner flag is enabled AND a durable session is requested.
+ *
+ * The tree semantics mirror the upstream `InMemorySessionStorage` reference
+ * (memory-storage.ts) byte-for-byte — `appendEntry` advances the leaf via
+ * `leafIdAfterEntry`, `setLeafId` appends a synthetic `leaf` entry, label-cache
+ * and `getPathToRoot` walk parent chains — so a session tree written here reads
+ * back identical to the in-memory implementation. The ONLY difference is the
+ * backing store (durable cleo.db rows vs in-RAM arrays) and the lease boundary.
+ *
+ * @module
+ * @task T11899
+ * @task T11761
+ * @epic T10403
+ */
+import type { SessionMetadata, SessionStorage, SessionTreeEntry } from '@earendil-works/pi-agent-core';
+/**
+ * Construction options for {@link CleoSessionStorage}.
+ */
+export interface CleoSessionStorageOptions {
+    /**
+     * The daemon-stamped owning session id. MUST be a real, env-resolved id —
+     * never a freshly-minted one. The S2 adapter reads it from
+     * `resolveCurrentSessionId` / `CLEO_SESSION_ID` and passes it here.
+     */
+    readonly sessionId: string;
+    /**
+     * Project working directory for `cleo.db` resolution. Defaults to `cwd` inside
+     * the store accessor.
+     */
+    readonly cwd?: string;
+    /**
+     * Wall-clock provider (injectable for deterministic tests). Defaults to
+     * `() => new Date().toISOString()`.
+     */
+    readonly now?: () => string;
+}
+/**
+ * Durable Pi `SessionStorage` backed by the PROJECT-scope `cleo.db`.
+ *
+ * Every mutating method ({@link appendEntry}, {@link setLeafId}) runs its write
+ * inside `withWriterLease('project', 'bulk', …)`; read methods operate directly
+ * on the shared native handle (no lease — readers do not contend the writer
+ * arbitration row). The session id is fixed at construction and never minted.
+ */
+export declare class CleoSessionStorage implements SessionStorage {
+    #private;
+    /**
+     * @param options - The daemon-stamped session id + optional cwd / clock.
+     */
+    constructor(options: CleoSessionStorageOptions);
+    /**
+     * Return the session metadata. The `id` is ALWAYS the daemon-stamped id this
+     * storage was constructed with (never minted); `createdAt` is the persisted
+     * leaf-row anchor, lazily created on first read so a never-written session
+     * still yields stable metadata.
+     *
+     * @returns The session metadata.
+     */
+    getMetadata(): Promise<SessionMetadata>;
+    /**
+     * Return the active leaf id, or `null` when none is set.
+     *
+     * @returns The leaf id or `null`.
+     * @throws {SessionError} `invalid_session` when the recorded leaf entry is missing.
+     */
+    getLeafId(): Promise<string | null>;
+    /**
+     * Persist a leaf entry that records the active session-tree leaf.
+     *
+     * Mirrors the upstream reference: appends a synthetic `leaf` entry (parented at
+     * the current leaf) THEN advances the leaf pointer to `leafId`. The whole
+     * mutation runs inside ONE leased section.
+     *
+     * @param leafId - The new active leaf entry id, or `null` to reset to root.
+     * @throws {SessionError} `not_found` when `leafId` names no existing entry.
+     */
+    setLeafId(leafId: string | null): Promise<void>;
+    /**
+     * Allocate a fresh, unused entry id for this session.
+     *
+     * Read-only (no persistence until {@link appendEntry}) — matches the upstream
+     * `createEntryId`.
+     *
+     * @returns A fresh unused entry id.
+     */
+    createEntryId(): Promise<string>;
+    /**
+     * Append a tree entry and advance the leaf pointer (leased write).
+     *
+     * @param entry - The entry to persist.
+     */
+    appendEntry(entry: SessionTreeEntry): Promise<void>;
+    /**
+     * Return an entry by id, or `undefined` when absent.
+     *
+     * @param id - The entry id.
+     * @returns The entry or `undefined`.
+     */
+    getEntry(id: string): Promise<SessionTreeEntry | undefined>;
+    /**
+     * Return all entries of a given type in append order.
+     *
+     * @param type - The entry-type discriminator to filter on.
+     * @returns The matching entries.
+     */
+    findEntries<TType extends SessionTreeEntry['type']>(type: TType): Promise<Array<Extract<SessionTreeEntry, {
+        type: TType;
+    }>>>;
+    /**
+     * Return the most-recent label applied to an entry, or `undefined`.
+     *
+     * Computed from the `label` entries (last write wins; an empty label clears),
+     * mirroring the upstream label cache.
+     *
+     * @param id - The target entry id.
+     * @returns The label or `undefined`.
+     */
+    getLabel(id: string): Promise<string | undefined>;
+    /**
+     * Walk from a leaf to the root, returning the path in root→leaf order.
+     *
+     * @param leafId - The leaf to walk from, or `null` for an empty path.
+     * @returns The root→leaf entry path.
+     * @throws {SessionError} `not_found` / `invalid_session` on a broken chain.
+     */
+    getPathToRoot(leafId: string | null): Promise<SessionTreeEntry[]>;
+    /**
+     * Return all entries for this session in stable append order.
+     *
+     * @returns The ordered entries.
+     */
+    getEntries(): Promise<SessionTreeEntry[]>;
+}
+//# sourceMappingURL=pi-session-storage.d.ts.map

package/dist/llm/pi/pi-session-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-session-storage.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-session-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAGH,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,gBAAgB,EACjB,MAAM,+BAA+B,CAAC;AAwBvC;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AA8DD;;;;;;;GAOG;AACH,qBAAa,kBAAmB,YAAW,cAAc;;IAKvD;;OAEG;gBACS,OAAO,EAAE,yBAAyB;IAM9C;;;;;;;OAOG;IACG,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAU7C;;;;;OAKG;IACG,SAAS,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAUzC;;;;;;;;;OASG;IACG,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBrD;;;;;;;OAOG;IACG,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;IAKtC;;;;OAIG;IACG,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAezD;;;;;OAKG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMjE;;;;;OAKG;IACG,WAAW,CAAC,KAAK,SAAS,gBAAgB,CAAC,MAAM,CAAC,EACtD,IAAI,EAAE,KAAK,GACV,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,gBAAgB,EAAE;QAAE,IAAI,EAAE,KAAK,CAAA;KAAE,CAAC,CAAC,CAAC;IAO7D;;;;;;;;OAQG;IACG,QAAQ,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAWvD;;;;;;OAMG;IACG,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAwBvE;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;CA0BhD"}

package/dist/llm/pi/pi-session-storage.js

@@ -0,0 +1,314 @@
+/**
+ * `CleoSessionStorage` — durable Pi `SessionStorage` over `cleo.db` (T11761 · S3 · T11899).
+ *
+ * The flag-ON, durable half of the Pi session-persistence seam. It implements
+ * Pi's tree-structured `SessionStorage` interface
+ * (`@earendil-works/pi-agent-core`) over the PROJECT-scope consolidated
+ * `cleo.db`, with ZERO write authority:
+ *
+ *  - **All durable writes go through {@link withWriterLease}** (`writer-lease.ts`,
+ *    PROJECT scope + `bulk` lane) — the daemon remains the sole arbitrated
+ *    Drizzle writer. This adapter NEVER opens a raw DB writer (Gate 3): it calls
+ *    the store-layer accessor ({@link import('../../store/pi-session-store.js')}),
+ *    which extracts the native handle the chokepoint already holds.
+ *  - **Identity is daemon-stamped, never minted.** The owning `sessionId` is
+ *    supplied at construction from `resolveCurrentSessionId` / `CLEO_SESSION_ID`
+ *    (resolved in `pi-agent-adapter.ts`). Unlike `InMemorySessionStorage`, this
+ *    storage NEVER calls `uuidv7()` to mint an id.
+ *
+ * {@link InMemorySessionStorage} (from `pi-agent-core`) remains the flag-OFF
+ * default that the S2 adapter body uses; this durable storage activates only when
+ * the Pi-runner flag is enabled AND a durable session is requested.
+ *
+ * The tree semantics mirror the upstream `InMemorySessionStorage` reference
+ * (memory-storage.ts) byte-for-byte — `appendEntry` advances the leaf via
+ * `leafIdAfterEntry`, `setLeafId` appends a synthetic `leaf` entry, label-cache
+ * and `getPathToRoot` walk parent chains — so a session tree written here reads
+ * back identical to the in-memory implementation. The ONLY difference is the
+ * backing store (durable cleo.db rows vs in-RAM arrays) and the lease boundary.
+ *
+ * @module
+ * @task T11899
+ * @task T11761
+ * @epic T10403
+ */
+import { randomUUID } from 'node:crypto';
+import { SessionError } from '@earendil-works/pi-agent-core';
+import { getLogger } from '../../logger.js';
+import { getPiSessionNativeDb, insertPiSessionEntry, readPiSessionEntries, readPiSessionEntry, readPiSessionLeaf, upsertPiSessionLeaf, } from '../../store/pi-session-store.js';
+import { withWriterLease } from '../../store/writer-lease.js';
+/**
+ * Lazily-memoized module logger (import-time side-effect-free per the page-2 /
+ * mocked-import-graph invariant — see `writer-lease.ts` rationale).
+ */
+let _log = null;
+function log() {
+    if (_log === null)
+        _log = getLogger('pi-session-storage');
+    return _log;
+}
+/**
+ * Generate a fresh 8-char entry id NOT already present in `existing`.
+ *
+ * Mirrors the upstream `generateEntryId` (memory-storage.ts): up to 100 attempts
+ * at an 8-char `uuidv7` prefix, falling back to a full id. We avoid importing
+ * Pi's internal `uuidv7` (not a barrel export) and use `node:crypto`'s
+ * `randomUUID()` —
+ * the id is an opaque tree-node handle, NOT a session identity (which is always
+ * daemon-stamped), so its generator is irrelevant to the identity contract.
+ *
+ * @param existing - The set of ids already in use for this session.
+ * @returns A fresh unused entry id.
+ */
+function generateEntryId(existing) {
+    for (let i = 0; i < 100; i++) {
+        const id = randomUUID().replace(/-/g, '').slice(0, 8);
+        if (!existing.has(id))
+            return id;
+    }
+    return randomUUID();
+}
+/**
+ * Columnized fields hoisted out of a {@link SessionTreeEntry} into dedicated
+ * columns; the remainder is JSON-serialized into `payload_json`.
+ */
+const COLUMNIZED_KEYS = ['id', 'parentId', 'type', 'timestamp'];
+/** Split a Pi entry into its columnized fields + JSON residue. */
+function encodeEntry(sessionId, entry) {
+    const residue = {};
+    for (const [key, value] of Object.entries(entry)) {
+        if (!COLUMNIZED_KEYS.includes(key))
+            residue[key] = value;
+    }
+    return {
+        sessionId,
+        entryId: entry.id,
+        parentId: entry.parentId,
+        type: entry.type,
+        payloadJson: JSON.stringify(residue),
+        ts: entry.timestamp,
+    };
+}
+/** Re-hydrate a full Pi entry by merging columns back over the JSON residue. */
+function decodeEntry(row) {
+    const residue = JSON.parse(row.payloadJson);
+    return {
+        ...residue,
+        id: row.entryId,
+        parentId: row.parentId,
+        type: row.type,
+        timestamp: row.ts,
+    };
+}
+/** The leaf id an entry establishes (leaf entries point at `targetId`; others at own id). */
+function leafIdAfterEntry(entry) {
+    return entry.type === 'leaf' ? entry.targetId : entry.id;
+}
+/**
+ * Durable Pi `SessionStorage` backed by the PROJECT-scope `cleo.db`.
+ *
+ * Every mutating method ({@link appendEntry}, {@link setLeafId}) runs its write
+ * inside `withWriterLease('project', 'bulk', …)`; read methods operate directly
+ * on the shared native handle (no lease — readers do not contend the writer
+ * arbitration row). The session id is fixed at construction and never minted.
+ */
+export class CleoSessionStorage {
+    #sessionId;
+    #cwd;
+    #now;
+    /**
+     * @param options - The daemon-stamped session id + optional cwd / clock.
+     */
+    constructor(options) {
+        this.#sessionId = options.sessionId;
+        this.#cwd = options.cwd;
+        this.#now = options.now ?? (() => new Date().toISOString());
+    }
+    /**
+     * Return the session metadata. The `id` is ALWAYS the daemon-stamped id this
+     * storage was constructed with (never minted); `createdAt` is the persisted
+     * leaf-row anchor, lazily created on first read so a never-written session
+     * still yields stable metadata.
+     *
+     * @returns The session metadata.
+     */
+    async getMetadata() {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        const leaf = readPiSessionLeaf(native, this.#sessionId);
+        if (leaf)
+            return { id: this.#sessionId, createdAt: leaf.createdAt };
+        // No row yet — establish the createdAt anchor durably (leaf stays null).
+        const ts = this.#now();
+        await this.#leasedWrite((db) => upsertPiSessionLeaf(db, this.#sessionId, null, ts, ts));
+        return { id: this.#sessionId, createdAt: ts };
+    }
+    /**
+     * Return the active leaf id, or `null` when none is set.
+     *
+     * @returns The leaf id or `null`.
+     * @throws {SessionError} `invalid_session` when the recorded leaf entry is missing.
+     */
+    async getLeafId() {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        const leaf = readPiSessionLeaf(native, this.#sessionId);
+        const leafId = leaf?.leafId ?? null;
+        if (leafId !== null && readPiSessionEntry(native, this.#sessionId, leafId) === null) {
+            throw new SessionError('invalid_session', `Entry ${leafId} not found`);
+        }
+        return leafId;
+    }
+    /**
+     * Persist a leaf entry that records the active session-tree leaf.
+     *
+     * Mirrors the upstream reference: appends a synthetic `leaf` entry (parented at
+     * the current leaf) THEN advances the leaf pointer to `leafId`. The whole
+     * mutation runs inside ONE leased section.
+     *
+     * @param leafId - The new active leaf entry id, or `null` to reset to root.
+     * @throws {SessionError} `not_found` when `leafId` names no existing entry.
+     */
+    async setLeafId(leafId) {
+        await this.#leasedWrite((native) => {
+            if (leafId !== null && readPiSessionEntry(native, this.#sessionId, leafId) === null) {
+                throw new SessionError('not_found', `Entry ${leafId} not found`);
+            }
+            const ids = this.#entryIdSet(native);
+            const currentLeaf = readPiSessionLeaf(native, this.#sessionId);
+            const ts = this.#now();
+            const synthetic = {
+                type: 'leaf',
+                id: generateEntryId(ids),
+                parentId: currentLeaf?.leafId ?? null,
+                timestamp: ts,
+                targetId: leafId,
+            };
+            insertPiSessionEntry(native, encodeEntry(this.#sessionId, synthetic));
+            upsertPiSessionLeaf(native, this.#sessionId, leafId, currentLeaf?.createdAt ?? ts, ts);
+        });
+    }
+    /**
+     * Allocate a fresh, unused entry id for this session.
+     *
+     * Read-only (no persistence until {@link appendEntry}) — matches the upstream
+     * `createEntryId`.
+     *
+     * @returns A fresh unused entry id.
+     */
+    async createEntryId() {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        return generateEntryId(this.#entryIdSet(native));
+    }
+    /**
+     * Append a tree entry and advance the leaf pointer (leased write).
+     *
+     * @param entry - The entry to persist.
+     */
+    async appendEntry(entry) {
+        await this.#leasedWrite((native) => {
+            insertPiSessionEntry(native, encodeEntry(this.#sessionId, entry));
+            const existing = readPiSessionLeaf(native, this.#sessionId);
+            const ts = this.#now();
+            upsertPiSessionLeaf(native, this.#sessionId, leafIdAfterEntry(entry), existing?.createdAt ?? ts, ts);
+        });
+    }
+    /**
+     * Return an entry by id, or `undefined` when absent.
+     *
+     * @param id - The entry id.
+     * @returns The entry or `undefined`.
+     */
+    async getEntry(id) {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        const row = readPiSessionEntry(native, this.#sessionId, id);
+        return row === null ? undefined : decodeEntry(row);
+    }
+    /**
+     * Return all entries of a given type in append order.
+     *
+     * @param type - The entry-type discriminator to filter on.
+     * @returns The matching entries.
+     */
+    async findEntries(type) {
+        const entries = await this.getEntries();
+        return entries.filter((e) => e.type === type);
+    }
+    /**
+     * Return the most-recent label applied to an entry, or `undefined`.
+     *
+     * Computed from the `label` entries (last write wins; an empty label clears),
+     * mirroring the upstream label cache.
+     *
+     * @param id - The target entry id.
+     * @returns The label or `undefined`.
+     */
+    async getLabel(id) {
+        const entries = await this.getEntries();
+        let label;
+        for (const entry of entries) {
+            if (entry.type !== 'label' || entry.targetId !== id)
+                continue;
+            const trimmed = entry.label?.trim();
+            label = trimmed ? trimmed : undefined;
+        }
+        return label;
+    }
+    /**
+     * Walk from a leaf to the root, returning the path in root→leaf order.
+     *
+     * @param leafId - The leaf to walk from, or `null` for an empty path.
+     * @returns The root→leaf entry path.
+     * @throws {SessionError} `not_found` / `invalid_session` on a broken chain.
+     */
+    async getPathToRoot(leafId) {
+        if (leafId === null)
+            return [];
+        const native = await getPiSessionNativeDb(this.#cwd);
+        const byId = new Map(readPiSessionEntries(native, this.#sessionId).map((r) => {
+            const entry = decodeEntry(r);
+            return [entry.id, entry];
+        }));
+        const path = [];
+        let current = byId.get(leafId);
+        if (!current)
+            throw new SessionError('not_found', `Entry ${leafId} not found`);
+        while (current) {
+            path.unshift(current);
+            if (!current.parentId)
+                break;
+            const parent = byId.get(current.parentId);
+            if (!parent) {
+                throw new SessionError('invalid_session', `Entry ${current.parentId} not found`);
+            }
+            current = parent;
+        }
+        return path;
+    }
+    /**
+     * Return all entries for this session in stable append order.
+     *
+     * @returns The ordered entries.
+     */
+    async getEntries() {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        return readPiSessionEntries(native, this.#sessionId).map(decodeEntry);
+    }
+    /** The set of entry ids already in use for this session (collision avoidance). */
+    #entryIdSet(native) {
+        return new Set(readPiSessionEntries(native, this.#sessionId).map((r) => r.entryId));
+    }
+    /**
+     * Run `fn` against the native handle while holding the PROJECT/`bulk` writer
+     * lease — the ONLY durable-write path. The daemon stays the sole arbitrated
+     * writer; the adapter never opens a raw writer (Gate 3).
+     *
+     * @param fn - The synchronous write body to run under the lease.
+     */
+    async #leasedWrite(fn) {
+        const native = await getPiSessionNativeDb(this.#cwd);
+        await withWriterLease('project', 'bulk', async () => {
+            fn(native);
+        });
+        log().debug({ sessionId: this.#sessionId }, 'pi session leased write committed');
+    }
+}
+//# sourceMappingURL=pi-session-storage.js.map

package/dist/llm/pi/pi-session-storage.js.map

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

package/dist/llm/pi/pi-stream-fn.d.ts

@@ -0,0 +1,124 @@
+/**
+ * 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
+ */
+import type { TransportTool } from '@cleocode/contracts/llm/normalized-response.js';
+import type { StreamFn } from '@earendil-works/pi-agent-core';
+import type { z } from 'zod';
+import type { PiAgentRunContext } from './pi-types.js';
+/**
+ * A Cleo tool definition in the form the Pi streamFn bridges to Pi's loop.
+ *
+ * Cleo tools carry a Zod parameter schema; {@link createPiStreamFn} converts it
+ * to a JSON-schema {@link TransportTool} so NO typebox value-import is needed at
+ * the boundary (Gate 10). The bridge is intentionally one-directional: cleo →
+ * Pi as JSON-schema; Pi validates internally; cleo re-validates received args
+ * against the Zod schema at the guard boundary (defense in depth, S3+).
+ */
+export interface PiZodTool {
+    /** Tool name as Pi/the provider will see it. */
+    readonly name: string;
+    /** Human-readable description for the model. */
+    readonly description: string;
+    /** Zod schema for the tool's input parameters. */
+    readonly parameters: z.ZodType;
+}
+/**
+ * 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 declare function zodToolToTransportTool(tool: PiZodTool): TransportTool;
+/**
+ * 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 declare function createPiStreamFn(ctx: PiAgentRunContext): StreamFn;
+//# sourceMappingURL=pi-stream-fn.d.ts.map

package/dist/llm/pi/pi-stream-fn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pi-stream-fn.d.ts","sourceRoot":"","sources":["../../../src/llm/pi/pi-stream-fn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAIH,OAAO,KAAK,EAEV,aAAa,EACd,MAAM,gDAAgD,CAAC;AACxD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,+BAA+B,CAAC;AA0B9D,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAM7B,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,kDAAkD;IAClD,QAAQ,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,CAAC;CAChC;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,SAAS,GAAG,aAAa,CAErE;AAID;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,iBAAiB,GAAG,QAAQ,CAYjE"}