@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/tool-context.d.ts

@@ -1,12 +1,7 @@
-/**
- * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
- * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
- * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
- */
+/** Per-turn capabilities shared by every FastAgent-defined tool. */
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { SessionEntry as PiSessionEntry, AgentSession } from "@earendil-works/pi-coding-agent";
-/** FastAgent's read-only port over the current conversation manager. Serving and chat adapt their
- * different concrete session implementations to this one tool-runtime contract. */
+/** FastAgent's read-only port over the current conversation manager. */
 export interface ReadonlySessionManager {
     getSessionId(): string;
     getHeader(): Promise<{
@@ -15,22 +10,16 @@ export interface ReadonlySessionManager {
     }>;
     getBranch(): Promise<PiSessionEntry[]>;
 }
-/**
- * pi's AgentSession as the port above — the SAME adapter for both of its consumers: chat's resident
- * session (session-builder.ts) and serving's per-invoke one (agent-session-factory.ts).
- *
- * `sessionId` is the CALLER's, not pi's. A tool correlates its own state by the id the channel
- * minted; pi's is that id encoded into a filename-safe record name, and leaking the encoding here
- * would hand a telegram tool `s-1001234567890` for a room it knows as `-1001234567890`.
- */
+/** pi's AgentSession as the port above — the SAME adapter for both of its consumers. */
 export declare function agentSessionManager(session: AgentSession, sessionId: string): ReadonlySessionManager;
 /**
- * The turn's tool-activation bridge — narrow closures over the CURRENT session (bound per turn), so
- * a loader tool can activate deferred tools mid-turn without tool.ts importing the engine. pi records
- * the change in the session (`active_tools_change`) and the per-invoke restore
- * (agent-session-factory.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
- * the tool result (`addedToolNames`) — the load point native deferred-loading providers preserve the
- * prompt-cache prefix with.
+ * The turn's tool-activation bridge — narrow closures over the CURRENT session (bound per turn), so a loader tool can
+ * activate deferred tools mid-turn without tool.ts importing the engine. pi anchors the addition in the transcript
+ * (a system message carrying `toolsAdded`, written after the batch of tool results the activating call belongs to),
+ * so providers with native deferred loading keep their
+ * prompt-cache prefix; that message describes the run that wrote it, so what carries an activation into LATER turns
+ * is fastagent's own `fastagent:tool-activation` entry, replayed by the per-invoke restore
+ * (agent-session-factory.ts).
  */
 export interface ToolActivation {
     /** Names of the currently ACTIVE tools. */
@@ -40,36 +29,19 @@ export interface ToolActivation {
         name: string;
         description: string;
     }>;
-    /** ADDITIVE activation. Unknown names are filtered out before reaching pi (whose `setActiveTools`
-     *  THROWS on them); answers the names actually newly activated (already-active names don't repeat).
-     *
-     *  SYNCHRONOUS, and that is the contract, not an implementation detail: read-modify-write against
-     *  pi's active set cannot be interleaved as long as no caller can await inside it. An async
-     *  signature would need a lock to say the same thing, and the lock is what a previous version had
-     *  — one rebuilt per tool call, so the parallel batch it existed for never met on it. If pi's
-     *  setters ever become async, this signature is where that breaks, loudly. */
+    /**
+     * ADDITIVE activation. Returns ONLY the names this call actually added — a name a batch sibling activated first
+     * is not in it. That return value is the caller's truth for both what to report and what to charge an activation
+     * cap: the call is atomic, but an `active()` -> await -> `activate()` sequence around it is not.
+     */
     activate(names: string[]): string[];
 }
-/**
- * The activation bridge over a live pi session — the ONE implementation, for both consumers.
- *
- * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
- * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
- * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
- * what a served session uses to record the delta that carries the discovery into its next turn,
- * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
- *
- * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
- */
+/** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
 export declare function sessionToolActivation(session: AgentSession, onActivated?: (added: string[]) => void): ToolActivation;
 export interface TurnContext {
-    /** Working directory for this execution. Falls back to process.cwd() only for an unbound direct call. */
+    /** Working directory for this execution. */
     cwd?: string;
-    /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
     sessionManager?: ReadonlySessionManager;
-    /** Tool activation for the current turn. Two producers, one consumer surface: agent-session-factory.ts
-     *  bridges the served session; session-builder.ts bridges the resident one (chat emulates deferral —
-     *  same loader, same semantics). Absent only outside any turn (a bare `fastagent tool` run). */
     tools?: ToolActivation;
 }
 export declare const turnContext: AsyncLocalStorage<TurnContext>;

package/dist/engines/pi/tool-context.js

@@ -1,17 +1,6 @@
-/**
- * Per-turn capabilities shared by every FastAgent-defined tool. A tool is built once and reused across
- * turns, so current cwd/session/activation bindings ride AsyncLocalStorage rather than definition
- * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
- */
+/** Per-turn capabilities shared by every FastAgent-defined tool. */
 import { AsyncLocalStorage } from "node:async_hooks";
-/**
- * pi's AgentSession as the port above — the SAME adapter for both of its consumers: chat's resident
- * session (session-builder.ts) and serving's per-invoke one (agent-session-factory.ts).
- *
- * `sessionId` is the CALLER's, not pi's. A tool correlates its own state by the id the channel
- * minted; pi's is that id encoded into a filename-safe record name, and leaking the encoding here
- * would hand a telegram tool `s-1001234567890` for a room it knows as `-1001234567890`.
- */
+/** pi's AgentSession as the port above — the SAME adapter for both of its consumers. */
 export function agentSessionManager(session, sessionId) {
     return {
         getSessionId: () => sessionId,
@@ -26,17 +15,7 @@ export function agentSessionManager(session, sessionId) {
         },
     };
 }
-/**
- * The activation bridge over a live pi session — the ONE implementation, for both consumers.
- *
- * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
- * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
- * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
- * what a served session uses to record the delta that carries the discovery into its next turn,
- * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
- *
- * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
- */
+/** The activation bridge over a live pi session — the ONE implementation, for both consumers. */
 export function sessionToolActivation(session, onActivated) {
     return {
         active: () => session.getActiveToolNames(),
@@ -53,8 +32,10 @@ export function sessionToolActivation(session, onActivated) {
     };
 }
 export const turnContext = new AsyncLocalStorage();
-/** dedupe → keep registered names only (pi's setters THROW on unknown) → exclude already-active →
- *  the names to actually add (empty = nothing to set). */
+/**
+ * dedupe → keep registered names only (pi's setters THROW on unknown) → exclude already-active → the names to actually
+ * add (empty = nothing to set).
+ */
 function additiveActivation(registered, current, names) {
     const known = new Set(registered);
     const active = new Set(current);

package/dist/engines/pi/tool.d.ts

@@ -2,77 +2,86 @@ import type { AgentTool } from "@earendil-works/pi-agent-core";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { z } from "zod";
 import { type ModuleLoadFailure } from "../../loader.ts";
+import { type DeclaredSecret } from "../../declared-secrets.ts";
 import { type ReadonlySessionManager, type ToolActivation } from "./tool-context.ts";
 export interface ToolContext {
     /** Working directory for this execution. */
     cwd: string;
     /** Abort signal for the current turn — honor it to cancel in-flight work on cancellation. */
     signal?: AbortSignal;
-    /** Current conversation manager. Present during serving/chat; absent for sessionless direct calls. */
     sessionManager?: ReadonlySessionManager;
-    /** Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred}
-     *  tools with it — the built-in `search_tools` is one consumer). Provided by both the serving path
-     *  (agent-session-factory.ts) and chat (session-builder.ts); undefined only outside any turn
-     *  (a bare `fastagent tool` run). */
+    /**
+     * Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred} tools with it —
+     * the built-in `search_tools` is one consumer).
+     */
     tools?: ToolActivation;
+    /** THE values of {@link DefineToolOptions.secrets}, keyed by the names this tool declared — read
+     *  from the process environment per call, so a value rotated THERE takes effect without a restart
+     *  (one rotated in `.secrets/.env` does not: that file is loaded once at startup). This is how a
+     *  tool gets a credential: reaching into `process.env` instead leaves the name undeclared, which
+     *  means nothing carries it to a deployed box and nothing checks it before the call fails. */
+    secrets: Record<string, string>;
 }
-export interface DefineToolOptions<I extends z.ZodType> {
-    /** Explicit name. Usually omitted — a `tools/<name>.ts` tool is named from its filename. */
+export interface DefineToolOptions<I extends z.ZodType, S extends readonly string[] = readonly []> {
     name?: string;
     description: string;
     input: I;
     /**
-     * Registered but NOT initially active: the tool's schema stays out of every request (and the model's
-     *  sight) until a loader — the built-in `search_tools`, mounted automatically when any deferred tool
-     *  exists — activates it mid-turn. For tool-heavy agents: fewer schemas per turn, and on providers
-     *  with native deferred loading the activation preserves the prompt-cache prefix. The trade-off:
-     *  discovery rides entirely on this description — write it for the search. Default: false.
+     * Registered but NOT initially active: the tool's schema stays out of every request (and the model's sight) until a
+     * loader.
      */
     deferred?: boolean;
-    /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially.
-     *  REQUIRED for a tool that activates others (a loader): pi's own diff around SDK tools (chat)
-     *  would attribute one activation to two parallel calls otherwise. */
+    /** pi's per-tool execution mode: "sequential" makes pi run any batch containing this tool serially. */
     executionMode?: "sequential" | "parallel";
-    execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
+    /**
+     * Env vars this tool needs (`secrets: ["X_API_KEY"]`). Their values arrive as `ctx.secrets.X_API_KEY`,
+     * typed from this list. Declaring buys the two guarantees a bare `process.env` read cannot have:
+     * `deploy` carries the value to the host without it being listed anywhere else, and `dev`/`start`
+     * REFUSE TO START while it is unset, naming this file — instead of the tool failing on its first
+     * real call (see src/declared-secrets.ts).
+     */
+    secrets?: S;
+    execute: (input: z.infer<I>, ctx: Omit<ToolContext, "secrets"> & {
+        secrets: Record<S[number], string>;
+    }) => unknown | Promise<unknown>;
 }
 /** AgentTool with Pi's optional per-call context; absent for sessionless CLI execution. */
 export type MountedTool = Omit<AgentTool, "execute"> & {
     execute(...args: [...Parameters<AgentTool["execute"]>, context?: ExtensionContext]): ReturnType<AgentTool["execute"]>;
 };
-/** An AgentTool with fastagent's deferral marker — the type for raw tools handed to fastagent
- *  (`config.tools`, L1/L2 `tools`): plain `AgentTool` has no `deferred`, so an object literal with the
- *  marker would fail excess-property checking against upstream's type. `defineTool` produces it. */
+/** An AgentTool with fastagent's deferral marker. */
 export type FastagentTool = AgentTool & {
     deferred?: boolean;
+    /** {@link DefineToolOptions.secrets} — read back by `readSecretDeclaration`; pi ignores it. */
+    secrets?: readonly string[];
 };
-/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
- *  AgentTool object — pi ignores it). */
+/**
+ * Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the AgentTool object — pi
+ * ignores it).
+ */
 export declare function isDeferredTool(tool: MountedTool): boolean;
-/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
- *  could never be activated and would strand every deferred tool). */
+/**
+ * The same tool without the deferred marker — for a loader that must stay active (a deferred loader could never be
+ * activated and would strand every deferred tool).
+ */
 export declare function stripDeferredMarker(tool: MountedTool): MountedTool;
-export declare function defineTool<I extends z.ZodType>(options: DefineToolOptions<I>): FastagentTool;
-/** A discarded same-name tool (within `tools/`, or against an existing tool). Surfaced, never silent. */
+export declare function defineTool<I extends z.ZodType, const S extends readonly string[] = readonly []>(options: DefineToolOptions<I, S>): FastagentTool;
+/** A discarded same-name tool (within `tools/`, or against an existing tool). */
 export interface ToolCollision {
     name: string;
     source: string;
 }
-/**
- * Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its
- * filename. A file broken for ANY reason — a failed import (from {@link loadModuleDir}) or not being a
- * tool (no `execute`) — is ISOLATED into `failures` (skipped + reported, not thrown) so one broken file
- * can't crash `start`; the agent serves the tools that loaded. A repo turned into an agent often has a
- * `tools/` dir of its OWN scripts, which is exactly this case.
- */
+/** Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its filename. */
 export declare function loadTools(dir: string): Promise<{
     tools: AgentTool[];
+    /** What each loaded tool declared it needs, BY TOOL NAME and attributed to the file. Per tool
+     *  because whether a declaration counts depends on whether that tool ends up MOUNTED — a name
+     *  shadowed by a coding tool never runs ({@link resolveAgentTools} makes that call). */
+    secrets: Map<string, DeclaredSecret[]>;
     collisions: ToolCollision[];
     failures: ModuleLoadFailure[];
 }>;
-/**
- * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
- * Existing tools win; dropped discovered tools surface as collisions.
- */
+/** Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name. */
 export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {
     tools: MountedTool[];
     collisions: ToolCollision[];

package/dist/engines/pi/tool.js

@@ -1,33 +1,40 @@
-/**
- * Tool authoring: `defineTool` (the authoring surface) and `loadTools` (filesystem discovery).
- * Drop a file in `tools/`, default-export `defineTool({...})`, and it is discovered, named from
- * the filename, validated, and injected.
- *
- *   // tools/lookup-order.ts            → tool "lookup-order"
- *   export default defineTool({
- *     description: "Look up an order by id.",
- *     input: z.object({ orderId: z.string() }),
- *     async execute({ orderId }) { return await db.find(orderId); },
- *   });
- */
+/** Tool authoring: `defineTool` (the authoring surface) and `loadTools` (filesystem discovery). */
 import { join } from "node:path";
 import { assertInsideAgentDir } from "../../paths.js";
 import { z } from "zod";
 import { loadModuleDir } from "../../loader.js";
+import { readSecretDeclaration, secretValues } from "../../declared-secrets.js";
 import { turnContext } from "./tool-context.js";
-/** Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the
- *  AgentTool object — pi ignores it). */
+/**
+ * Read the {@link DefineToolOptions.deferred} marker off a mounted tool (extra property on the AgentTool object — pi
+ * ignores it).
+ */
 export function isDeferredTool(tool) {
     return tool.deferred === true;
 }
-/** The same tool without the deferred marker — for a loader that must stay active (a deferred loader
- *  could never be activated and would strand every deferred tool). */
+/**
+ * The same tool without the deferred marker — for a loader that must stay active (a deferred loader could never be
+ * activated and would strand every deferred tool).
+ */
 export function stripDeferredMarker(tool) {
     if (!isDeferredTool(tool))
         return tool;
     const { deferred: _drop, ...active } = tool;
     return active;
 }
+/**
+ * Ask the provider to constrain sampling to the tool's schema, the posture pi's own built-ins take. `"prefer"`
+ * rather than `"require"`: a schema pi cannot express strictly, or a provider without strict mode, silently falls
+ * back to an ordinary function tool instead of failing the turn.
+ *
+ * Nothing here has to undo pi's strict rewrite. To express "optional" strictly, pi marks every property required and
+ * unions the optional ones with `null`, so a constrained model emits `null` where it would have omitted the key — and
+ * pi-ai's `validateToolArguments` drops those nulls (`normalizeOptionalNulls`) before `execute` is called. It drops
+ * one only where the author's OWN schema rejects null, so any nullable property keeps its `null`, and a
+ * `.nullable().optional()` property can no longer distinguish "absent" from "null" — the one place this changes
+ * what an author's `execute` receives.
+ */
+const CONSTRAINED_SAMPLING = { type: "json_schema", strict: "prefer" };
 /** Wrap a plain return value into pi's tool-result shape; pass a full result through unchanged. */
 function wrapResult(value) {
     if (value && typeof value === "object" && Array.isArray(value.content)) {
@@ -36,6 +43,10 @@ function wrapResult(value) {
     const text = typeof value === "string" ? value : JSON.stringify(value ?? null);
     return { content: [{ type: "text", text }], details: value };
 }
+// `S` defaults to the EMPTY tuple, not `readonly string[]`: a tool that declares nothing then gets
+// `ctx.secrets` with no keys, so `ctx.secrets.X_API_KEY` fails to compile instead of type-checking as
+// a `string` that is `undefined` at run time. "A typo is a compile error" has to hold for the tool
+// that forgot to declare, which is the one making the mistake.
 export function defineTool(options) {
     const { $schema: _drop, ...parameters } = z.toJSONSchema(options.input);
     const tool = {
@@ -43,8 +54,10 @@ export function defineTool(options) {
         label: options.name ?? "",
         description: options.description,
         parameters,
+        constrainedSampling: CONSTRAINED_SAMPLING,
         ...(options.deferred ? { deferred: true } : {}),
         ...(options.executionMode ? { executionMode: options.executionMode } : {}),
+        ...(options.secrets?.length ? { secrets: options.secrets } : {}),
         async execute(_toolCallId, rawParams, signal) {
             const parsed = options.input.safeParse(rawParams);
             if (!parsed.success) {
@@ -53,73 +66,46 @@ export function defineTool(options) {
                 return { content: [{ type: "text", text: `Invalid arguments: ${detail}` }], details: { error: detail } };
             }
             const store = turnContext.getStore();
-            // Stamp tools THIS execute activates on its result — the load point that lets native
-            // deferred-loading providers add the definitions at this transcript position without
-            // invalidating the cached prompt prefix. The names come from this execute's OWN activate()
-            // calls (accumulated below), NOT from an active-set before/after diff: pi runs tool calls of a
-            // batch in parallel, and a snapshot diff would stamp a sibling's activation onto the wrong tool
-            // result, drifting the load point.
-            const added = [];
-            const tools = store?.tools
-                ? {
-                    ...store.tools,
-                    activate: (names) => {
-                        // biome-ignore lint/style/noNonNullAssertion: guarded by the ternary above
-                        const activated = store.tools.activate(names);
-                        added.push(...activated);
-                        return activated;
-                    },
-                }
-                : undefined;
-            const result = wrapResult(await options.execute(parsed.data, {
+            return wrapResult(await options.execute(parsed.data, {
                 cwd: store?.cwd ?? process.cwd(),
                 signal,
                 sessionManager: store?.sessionManager,
-                tools,
+                tools: store?.tools,
+                secrets: secretValues(options.secrets),
             }));
-            if (added.length > 0) {
-                // A copy, not a mutation: wrapResult passes a full AgentToolResult through by REFERENCE, and an
-                // author may legally return a shared/frozen result object — stamping in place would corrupt it
-                // across calls (or throw on frozen), only on the rare activating path.
-                return { ...result, addedToolNames: [...new Set([...(result.addedToolNames ?? []), ...added])] };
-            }
-            return result;
         },
     };
     return tool;
 }
-/**
- * Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its
- * filename. A file broken for ANY reason — a failed import (from {@link loadModuleDir}) or not being a
- * tool (no `execute`) — is ISOLATED into `failures` (skipped + reported, not thrown) so one broken file
- * can't crash `start`; the agent serves the tools that loaded. A repo turned into an agent often has a
- * `tools/` dir of its OWN scripts, which is exactly this case.
- */
+/** Discover code tools in `<dir>/tools/`: each `*.ts|.js|.mjs` default-exports a tool, named from its filename. */
 export async function loadTools(dir) {
-    // The same containment guard channels/schedules/skills get — and `tools/` is the one that gets
-    // IMPORTED AND EXECUTED, so a symlink escaping the agent dir is exactly what it must refuse.
+    // The same containment guard channels/routines/skills get.
     await assertInsideAgentDir(dir, "tools");
     const { modules, failures } = await loadModuleDir(join(dir, "tools"));
     const byName = new Map();
     const collisions = [];
+    const secrets = new Map();
     for (const { name, label, file, mod } of modules) {
         const tool = mod.default;
         if (!tool || typeof tool.execute !== "function") {
             failures.push({ label, file, message: `${label} must default-export defineTool({...})` });
             continue;
         }
+        const declaration = readSecretDeclaration(tool, label);
+        if (declaration.error !== undefined) {
+            failures.push({ label, file, message: declaration.error });
+            continue;
+        }
         if (byName.has(name)) {
             collisions.push({ name, source: label });
             continue;
         }
         byName.set(name, { ...tool, name });
+        secrets.set(name, declaration.secrets);
     }
-    return { tools: [...byName.values()], collisions, failures };
+    return { tools: [...byName.values()], secrets, collisions, failures };
 }
-/**
- * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
- * Existing tools win; dropped discovered tools surface as collisions.
- */
+/** Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name. */
 export function mergeDiscoveredTools(existing, discovered) {
     const names = new Set(existing.map((t) => t.name));
     const tools = [...existing];

package/dist/engines/pi/turn-kit.d.ts

@@ -1,25 +1,10 @@
-/**
- * The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. Not
- * "engine-neutral" in this repo's sense — that term is reserved for code with no engine import at
- * all (src/agent.ts), and the terminals here read pi's message shape. What they do not touch is how
- * a turn is driven, which is why they survived the engine change unaltered.
- *
- *   Lease       — single-writer concurrency floor (injectable port + in-process default)
- *   Terminals   — a settled pi message or a thrown error → the SPEC terminal, `retryable` included
- *   EventQueue  — push→pull plumbing for engines that emit events beside their result
- *   Prompt prep — SPEC images → pi's ImageContent
- *   Projection  — the rich SessionEvent stream → the narrow SPEC one
- *   Observation — the seam a control-plane hub attaches to (RunControls + SessionObserver)
- *
- * What is NOT neutral — pi's event vocabulary and how a turn is driven — stays in invoke-session.ts,
- * the L0 that owns it.
- */
+/** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
 import type { AssistantMessage, ImageContent } from "@earendil-works/pi-ai";
 import { type AgentEvent, type Prompt } from "../../agent.ts";
 import type { SessionEvent } from "../../session.ts";
 export type Release = () => void;
 export interface Lease {
-    /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */
+    /** Try to acquire exclusive write access for the session (fail-fast). */
     tryAcquire(session: string): Release | null;
 }
 export declare function inProcessLease(): Lease;
@@ -29,54 +14,31 @@ export declare function classifyRetryable(details: string, signal: {
     code?: unknown;
 }): boolean;
 /**
- * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
- * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
- * entire failure class (violating SPEC MUST 1).
+ * Terminal mapping, decided by the resolved message's stopReason: pi's `prompt()` RESOLVES a message with stopReason
+ * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
+ * SPEC MUST 1.
  */
 export declare function toTerminal(message: AssistantMessage): AgentEvent;
 export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
     type: "failed";
 }>;
 /**
- * Map prompt images to pi ImageContent, resizing each to model-friendly dimensions/size with pi's
- * Photon resizer (reused from pi-coding-agent, lazy-imported so the common no-image headless path never
- * loads the TUI module graph). A null resize (unresizable / Photon unavailable) keeps the original
- * bytes — the provider then applies its own limit.
+ * Map prompt images to pi ImageContent. `prompt()` normalizes its images itself, with the bound model's resize
+ * profile (`inputLimits.images.resize`) and format conversion, so a `"prompt"` delivery hands them over as-is.
+ * `steer`/`followUp` do not, so a `"queued"` delivery resizes here with pi's default profile: the model is not known
+ * yet when a queued message is prepared. pi's resizer is lazy-imported so the no-image path never loads its module
+ * graph.
  */
-export declare function toPiPromptOptions(prompt: Prompt): Promise<{
+export declare function toPiPromptOptions(prompt: Prompt, delivery: "prompt" | "queued"): Promise<{
     images?: ImageContent[];
 } | undefined>;
-/** Live modulation handles for one active run — what the control plane's `dispatch` routes to.
- *  Built inside the turn (it owns the engine instance); registered with the observer at
- *  run_started, gone after run_settled. RACE WINDOW (all three commands, symmetric): the run may
- *  resolve between the settled-check and the engine call landing — an accepted `abort` can still
- *  settle `completed`, and an accepted `steer`/`followUp` can settle without the prompt ever being
- *  consumed. Acceptance is not outcome; the settlement is the truth. */
+/** Live modulation handles for one active run — what the control plane's `dispatch` routes to. */
 export interface RunControls {
     steer(prompt: Prompt): Promise<void>;
     followUp(prompt: Prompt): Promise<void>;
     abort(): Promise<void>;
 }
-/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. `run`
- *  carries the live {@link RunControls}, attached to the `run_started` event only. A hub
- *  (session-control.ts) implements this to serve `events()`/`state()`/`dispatch`; absent = zero
- *  overhead. Scope: RUN events only — the hub's own boundary-mutation events (`state_changed`,
- *  `compaction_*`) originate in the hub and reach full-vocabulary taps via the hub's `tap` option,
- *  not this seam. TRUST BOUNDARY: this seam hands every wired observer the run's modulation handles — it is the trusted hub seam, not a public fan-out point. Do not wire
- *  untrusted taps here; give third parties the read-only `events()` stream instead. */
+/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. */
 export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
-/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
- *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
- *  resolved message ({@link toTerminal}), not from `run_settled`. */
+/** The SPEC projection of the rich stream. */
 export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
-export declare class EventQueue<T> {
-    private buffer;
-    private wake?;
-    push(item: T): void;
-    /**
-     * Yield pushed events in order until `done` settles AND the buffer is drained. The terminal is
-     * produced separately (toTerminal); rejections of `done` are swallowed here (the caller awaits
-     * `run` itself) to avoid unhandled rejections.
-     */
-    drainUntil(done: Promise<unknown>): AsyncGenerator<T>;
-}