@fastagent-sh/fastagent 0.12.0

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

@@ -0,0 +1,72 @@
+import type { ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+/** A same-name skill collision (the discarded side). Surfaced, never swallowed. */
+export interface SkillCollision {
+    name: string;
+    winnerPath: string;
+    loserPath: string;
+}
+/** Result of loading a definition directory. Produced by {@link loadAgentDefinition}. */
+export interface LoadedDefinition {
+    /**
+     * Project-context files feeding segment ② `<project_context>`, sourced via pi's `loadProjectContextFiles`:
+     * the agentDir's own AGENTS.md/CLAUDE.md FIRST, then every AGENTS.md from root down to `cwd` (so the
+     * file nearest `cwd` comes LAST — pi's array order). Empty when none exist. This WALKS cwd's ancestors (pi's coding-agent behaviour) — see core.md §6.
+     */
+    contextFiles: Array<{
+        path: string;
+        content: string;
+    }>;
+    /**
+     * Verbatim `persona.md` content — the authored persona that OVERRIDES segment ①'s identity line
+     * (piBasePrompt keeps the tool list + guidelines; NOT a full system-prompt replacement — that is L1
+     * createPiAgent's `instructions`). undefined when absent → segment ① is the default engine identity.
+     */
+    persona?: string;
+    skills: Skill[];
+    /** Non-fatal per-file skill problems reported by pi's loader. */
+    diagnostics: SkillDiagnostic[];
+    /** Same-name conflicts across mounts (first-wins). */
+    collisions: SkillCollision[];
+    /** Absolute agent-definition directory path (persona.md/skills/ live here). */
+    dir: string;
+}
+export interface LoadAgentDefinitionOptions {
+    /**
+     * Working directory whose ancestors are walked for context files (segment ②). Default = `agentDir`
+     * (flat: the agent dir is also the run root). The opener passes the run root so a coding agent that
+     * lives in `agentDir` picks up the host repo's AGENTS.md up the tree (core.md scenario grid).
+     */
+    cwd?: string;
+    env?: ExecutionEnv;
+}
+/** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
+export declare function loadAgentDefinition(agentDir: string, options?: LoadAgentDefinitionOptions): Promise<LoadedDefinition>;
+/**
+ * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
+ * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
+ * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
+ * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
+ * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ */
+export declare function isUnderDir(targetPath: string, baseDir: string): boolean;
+/**
+ * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
+ * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
+ * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
+ * write a `.gitignore` bypassing this.
+ *
+ * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
+ * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
+ * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
+ * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
+ * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
+ * `.gitignore` into it (it may be a directory the operator deliberately tracks).
+ *
+ * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
+ * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
+ * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
+ */
+export declare function ensureStateRootSelfIgnored(dir: string, stateRoot: string): Promise<void>;
+/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
+ *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
+export declare function canonicalPath(p: string): string;

package/dist/engines/pi/definition.js

@@ -0,0 +1,129 @@
+/**
+ * Definition domain: read an agent definition directory (AGENTS.md + skills/) into memory. Produces
+ * data; create.ts consumes it.
+ *
+ * IO policy: persona.md + skills load through ExecutionEnv (portable across local/sandbox/remote); the
+ * invoke path never touches disk. EXCEPTION — ② project context comes from pi's loadProjectContextFiles,
+ * which reads via node fs DIRECTLY (not the injected `env`) and, on failure, at best warns to stderr and
+ * at worst is fully silent (its `existsSync` probe swallows a permission error) — no structured signal. So under a
+ * non-local ExecutionEnv the ② files still resolve against THIS process's filesystem, not the target env
+ * — a known break in the portability contract, deferred with the sandbox work (core.md §6). config/auth/
+ * sessions and this module's Node helpers are composition-root code and may use node fs.
+ *
+ * Errors: a broken persona.md / unresolvable dir throws (fail loudly at startup); non-fatal findings
+ * (bad skill files, name collisions) are returned as data. An unreadable ② context file only warns (pi).
+ */
+import { realpathSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { loadSkills } from "@earendil-works/pi-agent-core";
+import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
+import { loadProjectContextFiles } from "@earendil-works/pi-coding-agent";
+/** Read an agent definition. persona.md/skills come from `agentDir`; ② context = pi's loadProjectContextFiles({ cwd, agentDir }). */
+export async function loadAgentDefinition(agentDir, options = {}) {
+    // One resolved default for the working directory (env cwd AND the context-walk start), so they can
+    // never diverge if a caller passes a relative agentDir.
+    const cwd = options.cwd ?? agentDir;
+    const e = options.env ?? new NodeExecutionEnv({ cwd });
+    const rootResult = await e.absolutePath(agentDir);
+    if (!rootResult.ok) {
+        throw new Error(`cannot resolve agent dir "${agentDir}": ${rootResult.error.message}`);
+    }
+    const root = rootResult.value;
+    // ② project context, following pi: the agentDir's own AGENTS.md + every AGENTS.md walking cwd up to
+    // root (loadProjectContextFiles). It reads via node fs directly (mirrors pi), NOT the ExecutionEnv —
+    // a deliberate, deferred deviation from this module's portable-IO policy (revisit with the sandbox; core.md §6).
+    const contextFiles = loadProjectContextFiles({ cwd, agentDir: root });
+    // persona.md → segment ① persona (overrides the identity line). Same error policy as AGENTS.md:
+    // only not_found means "absent"; any other read error surfaces rather than silently dropping the persona.
+    const personaPath = join(root, "persona.md");
+    const personaRead = await e.readTextFile(personaPath);
+    if (!personaRead.ok && personaRead.error.code !== "not_found") {
+        throw new Error(`cannot read ${personaPath}: ${personaRead.error.message}`);
+    }
+    const persona = personaRead.ok ? personaRead.value : undefined;
+    // Skills come ONLY from the definition's own skills/ (no external/global mount), so the same
+    // definition loads the same skills on every machine.
+    const { skills: raw, diagnostics } = await loadSkills(e, [join(root, "skills")]);
+    const byName = new Map();
+    const collisions = [];
+    for (const skill of raw) {
+        const existing = byName.get(skill.name);
+        if (existing) {
+            collisions.push({ name: skill.name, winnerPath: existing.filePath, loserPath: skill.filePath });
+        }
+        else {
+            byName.set(skill.name, skill);
+        }
+    }
+    return { contextFiles, persona, skills: [...byName.values()], diagnostics, collisions, dir: root };
+}
+/**
+ * Whether `targetPath` lives inside `baseDir` (same path counts). The self-ignore guard uses it to ask
+ * "does the resolved state root land inside the workspace tree?" — an in-tree root (the default
+ * `.fastagent`, or a custom `FASTAGENT_STATE_DIR` pointed inside the agent dir) is ours to self-ignore;
+ * a root on an external volume resolves outside and must not be (we never write a `.gitignore` outside
+ * the tree). Whether a relative override lands in-tree is a cwd question — see `resolveStateRoot`.
+ */
+export function isUnderDir(targetPath, baseDir) {
+    const rel = relative(baseDir, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+/**
+ * Self-ignore a state dir: create it if missing, then write `<stateDir>/.gitignore` = "*" (idempotent
+ * — an existing one is kept), so a workspace that runs dev/start never shows machine state as
+ * untracked. Creates the dir because a caller may self-ignore it before anything else populates it
+ * (e.g. `login` writing auth.json into a not-yet-created root).
+ *
+ * Module-PRIVATE on purpose: the only entry to the leak guard is {@link ensureStateRootSelfIgnored}
+ * (home exclusion + containment). Keeping this unexported makes that single-owner claim hold at the
+ * type level — a sibling command can't bypass those checks by writing a `.gitignore` directly.
+ */
+async function ensureStateDirSelfIgnored(stateDir) {
+    await mkdir(stateDir, { recursive: true });
+    await writeFile(join(stateDir, ".gitignore"), "*\n", { flag: "wx" }).catch((e) => {
+        if (e.code !== "EEXIST")
+            throw e;
+    });
+}
+/**
+ * The single owner of the self-ignore MECHANISM: iff the resolved state ROOT lands inside the workspace
+ * tree, write `<stateRoot>/.gitignore="*"` — which then covers EVERYTHING under it (sessions, auth.json,
+ * every channel's `channels/<kind>` home). `ensureStateDirSelfIgnored` is private, so a caller cannot
+ * write a `.gitignore` bypassing this.
+ *
+ * ROOT-based, not path-based: everything derives from the state root (config.ts), so protecting the
+ * root protects all of it — INCLUDING a custom in-tree root (a `FASTAGENT_STATE_DIR` inside the agent
+ * dir), the case a path-based (`.fastagent`-only) guard would leak. A per-path override
+ * (`--sessions-dir`/`--auth-path`) is operator-owned: pointed at an external volume it is out-of-tree
+ * (correctly not ours to ignore); pointed at a custom in-tree dir WE DON'T OWN, we do not write a
+ * `.gitignore` into it (it may be a directory the operator deliberately tracks).
+ *
+ * Excludes the user's HOME-global `~/.fastagent` (e.g. `login`/`dev` run from `$HOME`): self-ignore is
+ * for protecting state inside an agent PROJECT tree, not for writing a `.gitignore` into the user's
+ * home, which a dotfiles repo may track. The global credential file there was never self-ignored.
+ */
+export async function ensureStateRootSelfIgnored(dir, stateRoot) {
+    // Compare CANONICAL paths for the home check: `dir` arrives realpath-resolved (it is `process.cwd()`
+    // or `resolve(".")`) but `homedir()` returns the raw `$HOME`, so a symlinked home would slip past raw
+    // equality and we'd write a `.gitignore` into the real `~/.fastagent` — the very thing the doc forbids
+    // (chat.ts canonicalizes for the same reason).
+    if (canonicalPath(dir) === canonicalPath(homedir()))
+        return;
+    // Containment on RAW paths: stateRoot is resolve()'d (config.ts) and `dir` is absolute, so it is exact
+    // by construction. An external-volume root resolves outside the tree → skip (not ours to ignore).
+    if (isUnderDir(stateRoot, dir))
+        await ensureStateDirSelfIgnored(stateRoot);
+}
+/** Resolve to a canonical (symlink-free) absolute path so comparisons match `process.cwd()`'s realpath.
+ *  A non-existent path can't be realpath'd, so it stays as the plain absolute resolve. */
+export function canonicalPath(p) {
+    const resolved = resolve(p);
+    try {
+        return realpathSync(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}

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

@@ -0,0 +1,50 @@
+/**
+ * pi harness wiring: construct one pi `AgentHarness` per session. The agent definition (AGENTS.md +
+ * skills) is content fed INTO the harness (see definition.ts), not part of it.
+ *
+ * Under the stateless design the harness is discarded after each use; continuity comes from
+ * persisting the session (PiSessionStore) and re-opening it per invoke — pi's prompt() folds the
+ * historical entries back into context via buildContext().
+ */
+import { AgentHarness } from "@earendil-works/pi-agent-core";
+import type { AgentTool, ExecutionEnv, Skill } from "@earendil-works/pi-agent-core";
+import type { Model, Models } from "@earendil-works/pi-ai";
+import type { PiSessionStore } from "./sessions.ts";
+/**
+ * pi's Model with the API-shape generic erased — fastagent only passes models through to the
+ * harness, so the generic carries no information. One alias keeps the `any` auditable.
+ */
+export type AnyModel = Model<any>;
+/** Builds a pi harness bound to the given session — called once per invoke. */
+export type PiHarnessFactory = (session: string) => AgentHarness | Promise<AgentHarness>;
+export interface PiHarnessFactoryOptions {
+    /** Session persistence. Continuity = same backing store + same session id. */
+    sessions: PiSessionStore;
+    env: ExecutionEnv;
+    /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
+    models: Models;
+    model: AnyModel;
+    tools?: AgentTool[];
+    /**
+     * Final assembled prompt, or a SYNC factory re-evaluated per invoke (how L1 serves dynamic
+     * `instructions` + the skills listing). Distinct from {@link live}, which is the directory rung's
+     * ASYNC re-read of prompt AND skills as one pair — both are exercised, by different rungs.
+     */
+    systemPrompt?: string | (() => string);
+    /** Skills visible to the model / explicitly invokable (injected as harness resources). */
+    skills?: Skill[];
+    /**
+     * Per-invoke source for the prompt+skills PAIR, re-evaluated on every harness build. When set it
+     * supersedes {@link systemPrompt}/{@link skills} — one call yields both, so the skills listing
+     * inside the prompt and the mounted skill resources can never come from two different reads. The
+     * directory rung (L2) uses it to re-read the definition, so AGENTS.md/skills edits — the author's or
+     * the agent's own — take effect on the next turn without a process restart. A rejection surfaces
+     * as that invoke's `failed` event (the factory throw path), never a crash.
+     */
+    live?: () => Promise<{
+        systemPrompt?: string;
+        skills?: Skill[];
+    }>;
+}
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;

package/dist/engines/pi/harness.js

@@ -0,0 +1,41 @@
+/**
+ * pi harness wiring: construct one pi `AgentHarness` per session. The agent definition (AGENTS.md +
+ * skills) is content fed INTO the harness (see definition.ts), not part of it.
+ *
+ * Under the stateless design the harness is discarded after each use; continuity comes from
+ * persisting the session (PiSessionStore) and re-opening it per invoke — pi's prompt() folds the
+ * historical entries back into context via buildContext().
+ */
+import { AgentHarness } from "@earendil-works/pi-agent-core";
+/**
+ * Provider request retries. The OpenAI-family / Anthropic / Azure / Codex pi-ai adapters
+ * implement client-side retries (429/5xx/request-phase network failures with backoff, honoring
+ * Retry-After; a Codex websocket that fails before the stream starts falls back to SSE) but all
+ * default maxRetries to 0 (even SDK-backed ones override the SDK default), so a single transient
+ * `fetch failed` would otherwise kill the whole turn; 2 matches the OpenAI/Anthropic SDK default.
+ * The google / vertex / bedrock / mistral adapters ignore this option (a pi-ai upstream gap) —
+ * transients there still fail the turn. Mid-stream drops are deliberately NOT retried anywhere on
+ * this path — partial output was already streamed and the SPEC event stream cannot retract it,
+ * so a mid-stream failure surfaces as a `failed` event.
+ */
+const PROVIDER_MAX_RETRIES = 2;
+/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
+export function piHarnessFactory(options) {
+    return async (sessionId) => {
+        const session = await options.sessions.openOrCreate(sessionId);
+        const fresh = options.live ? await options.live() : undefined;
+        const { systemPrompt } = options;
+        const prompt = fresh ? fresh.systemPrompt : typeof systemPrompt === "function" ? systemPrompt() : systemPrompt;
+        const skills = fresh ? fresh.skills : options.skills;
+        return new AgentHarness({
+            env: options.env,
+            session,
+            models: options.models,
+            model: options.model,
+            tools: options.tools,
+            systemPrompt: prompt,
+            resources: skills ? { skills } : undefined,
+            streamOptions: { maxRetries: PROVIDER_MAX_RETRIES },
+        });
+    };
+}

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

@@ -0,0 +1,28 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { type Agent, type AgentEvent } from "../../agent.ts";
+import type { PiHarnessFactory } from "./harness.ts";
+export type Release = () => void;
+export interface Lease {
+    /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */
+    tryAcquire(session: string): Release | null;
+}
+export declare function inProcessLease(): Lease;
+/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
+export declare function classifyRetryable(details: string, signal: {
+    status?: number;
+    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).
+ */
+export declare function toTerminal(message: AssistantMessage): AgentEvent;
+export declare function errorToTerminal(error: unknown): AgentEvent;
+export interface CreatePiAgentFromHarnessOptions {
+    harnessFactory: PiHarnessFactory;
+    /** Single-writer lease. Defaults to the in-process per-session fail-fast lease. */
+    lease?: Lease;
+}
+/** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
+export declare function createPiAgentFromHarness(options: CreatePiAgentFromHarnessOptions): Agent;

package/dist/engines/pi/invoke.js

@@ -0,0 +1,298 @@
+import { DEFAULT_COMPACTION_SETTINGS, calculateContextTokens, shouldCompact } from "@earendil-works/pi-agent-core";
+import { SESSION_BUSY_CODE } from "../../agent.js";
+import { log } from "../../log.js";
+import { turnContext } from "./tool-context.js";
+export function inProcessLease() {
+    const busy = new Set();
+    return {
+        tryAcquire(session) {
+            if (busy.has(session))
+                return null;
+            busy.add(session);
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                busy.delete(session);
+            };
+        },
+    };
+}
+// ── §2 translate: the single pi↔SPEC translation point ───────────────────────
+//
+// `retryable` = worth re-sending with the same session (SPEC §6: advisory, not a session-atomicity
+// guarantee). Classify from the STRUCTURED signal first, prose only as the last-resort ceiling. What
+// is actually available differs by path, and the two are NOT symmetric:
+//   - thrown error (errorToTerminal): an HTTP `.status`/`.statusCode` AND a network `.code` (incl.
+//     `.cause.code`) — this is where a numeric status genuinely drives the decision.
+//   - failed message (toTerminal): ONLY `diagnostics[].error.code`. pi's `DiagnosticErrorInfo` carries
+//     a `code` (a network code, or a status delivered as a code), with no separate HTTP-status field —
+//     so a message whose provider `code` is a string label (e.g. "rate_limit_exceeded") is not
+//     decisive here and falls to prose.
+// The prose fallback is bounded, not a cop-out: pi-ai already ran its own status-code-based client
+// retries (harness.ts PROVIDER_MAX_RETRIES) before surfacing, so an error that reaches this point has
+// already exhausted the cleanly-retryable cases. The regex is the narrow ceiling, not the classifier.
+// Upstream ask: a first-class `retryable`/`kind` on pi's terminal error would retire the prose path
+// entirely (mirrors the §11 "the deeper fix is upstream in pi" pattern).
+/** Clearly-transient network error codes (Node/undici), decisive on their own. */
+const RETRYABLE_CODES = new Set([
+    "ECONNRESET",
+    "ETIMEDOUT",
+    "ENETUNREACH",
+    "ENETDOWN",
+    "EAI_AGAIN",
+    "EPIPE",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_SOCKET",
+]);
+/** 429 (rate limit) and 5xx (server) are worth retrying; other statuses are decisive NON-retryable. */
+const statusIsRetryable = (status) => status === 429 || (status >= 500 && status < 600);
+/** Last-resort prose match, used only when no structured status/code is available. */
+const RETRYABLE_MESSAGE = /\b(429|5\d\d|timeout|timed out|rate.?limit|overloaded|ECONNRESET|ETIMEDOUT|ENETUNREACH|EAI_AGAIN|socket hang up)\b/i;
+/** A structured status/code decision, or `null` when the signal is absent/undecisive → fall to prose. */
+function retryableFromSignal(signal) {
+    if (typeof signal.status === "number")
+        return statusIsRetryable(signal.status);
+    const { code } = signal;
+    if (typeof code === "number")
+        return statusIsRetryable(code);
+    if (typeof code === "string") {
+        if (RETRYABLE_CODES.has(code))
+            return true;
+        if (/^\d{3}$/.test(code))
+            return statusIsRetryable(Number(code)); // a status carried as a string
+    }
+    return null; // no code, or an unknown one — not decisive on its own
+}
+/** Classify `retryable`: structured status/code first, message prose only as the last-resort ceiling. */
+export function classifyRetryable(details, signal) {
+    return retryableFromSignal(signal) ?? RETRYABLE_MESSAGE.test(details);
+}
+/** Pull a structured status/code off a thrown error (HTTP status or a network code, incl. its cause). */
+function errorSignal(error) {
+    if (!error || typeof error !== "object")
+        return {};
+    const e = error;
+    const status = typeof e.status === "number" ? e.status : typeof e.statusCode === "number" ? e.statusCode : undefined;
+    const causeCode = e.cause && typeof e.cause === "object" ? e.cause.code : undefined;
+    return { status, code: e.code ?? causeCode };
+}
+/**
+ * Pull the structured error `code` pi records on a failed message's diagnostics. `diagnostics`
+ * accumulates across attempts (`appendAssistantMessageDiagnostic`), so the terminal cause is the LAST
+ * code-bearing entry — `findLast`, not `find`: an earlier attempt's transient 503 must not classify a
+ * terminal 400/auth failure as retryable. (Reverse scan rather than `findLast` — the tsconfig lib is
+ * ES2022.)
+ */
+function messageSignal(message) {
+    const diagnostics = message.diagnostics ?? [];
+    for (let i = diagnostics.length - 1; i >= 0; i--) {
+        const code = diagnostics[i]?.error?.code;
+        if (code !== undefined)
+            return { code };
+    }
+    return {};
+}
+/** In-stream event mapping. Non text/tool_* pi events (turn_start, message_start, …) are dropped. */
+function toAgentEvent(pe) {
+    switch (pe.type) {
+        case "message_update": {
+            const ev = pe.assistantMessageEvent;
+            if (ev.type === "text_delta")
+                return { type: "text", delta: ev.delta };
+            if (ev.type === "thinking_delta")
+                return { type: "thinking", delta: ev.delta };
+            return null;
+        }
+        case "tool_execution_start":
+            return { type: "tool_started", id: pe.toolCallId, name: pe.toolName, args: pe.args };
+        case "tool_execution_end":
+            return { type: "tool_ended", id: pe.toolCallId, isError: pe.isError, content: pe.result };
+        default:
+            return null;
+    }
+}
+/**
+ * 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).
+ */
+export function toTerminal(message) {
+    if (message.stopReason === "error" || message.stopReason === "aborted") {
+        const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
+        return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
+    }
+    return { type: "completed" };
+}
+export function errorToTerminal(error) {
+    const details = error instanceof Error ? error.message : String(error);
+    return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
+}
+/**
+ * After a successful turn, compact the session if its context has grown past pi's threshold — a long
+ * shared (group) or 1:1 conversation otherwise overflows the model's window. pi owns the mechanism
+ * (`harness.compact()` writes a summary entry into the session, so the next reopen is compacted); the
+ * bare harness does NOT auto-trigger it, so fastagent checks `shouldCompact` here and fires it. The
+ * context size is the provider's own count from the turn's assistant message (`usage`).
+ */
+async function maybeCompact(harness, message) {
+    const contextWindow = harness.getModel().contextWindow;
+    if (!contextWindow)
+        return;
+    if (shouldCompact(calculateContextTokens(message.usage), contextWindow, DEFAULT_COMPACTION_SETTINGS)) {
+        await harness.compact();
+    }
+}
+/**
+ * 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.
+ */
+async function toPiPromptOptions(prompt) {
+    if (!prompt.images || prompt.images.length === 0)
+        return undefined;
+    const { resizeImage } = await import("@earendil-works/pi-coding-agent");
+    const images = await Promise.all(prompt.images.map(async (img) => {
+        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType, {
+            maxWidth: 1568,
+            maxHeight: 1568,
+            maxBytes: 5 * 1024 * 1024,
+        }).catch(() => null);
+        return resized
+            ? { type: "image", data: resized.data, mimeType: resized.mimeType }
+            : { type: "image", data: img.data, mimeType: img.mimeType };
+    }));
+    return { images };
+}
+// ── §3 EventQueue: push→pull plumbing for pi's two-port shape ────────────────
+//
+// Single-consumer async queue; single-threaded JS means no await interleaves between push and
+// drain, so no locking. Engines that are natively async-iterable would not need it.
+class EventQueue {
+    buffer = [];
+    wake;
+    push(item) {
+        this.buffer.push(item);
+        const wake = this.wake;
+        this.wake = undefined;
+        wake?.();
+    }
+    /**
+     * 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.
+     */
+    async *drainUntil(done) {
+        let settled = false;
+        const onSettle = () => {
+            settled = true;
+            const wake = this.wake;
+            this.wake = undefined;
+            wake?.();
+        };
+        const finished = done.then(onSettle, onSettle);
+        while (true) {
+            while (this.buffer.length > 0) {
+                yield this.buffer.shift();
+            }
+            if (settled)
+                break;
+            await new Promise((resolve) => {
+                this.wake = resolve;
+            });
+        }
+        await finished;
+    }
+}
+/** "From a harness factory": engine wired by the caller; adds only the concurrency/stream shell. */
+export function createPiAgentFromHarness(options) {
+    const { harnessFactory, lease = inProcessLease() } = options;
+    async function* invoke(scope, prompt) {
+        const release = lease.tryAcquire(scope.session);
+        if (!release) {
+            yield {
+                type: "failed",
+                details: "session busy: a turn is already in flight for this session",
+                retryable: true,
+                code: SESSION_BUSY_CODE,
+            };
+            return;
+        }
+        try {
+            let harness;
+            try {
+                harness = await harnessFactory(scope.session);
+            }
+            catch (error) {
+                // Setup failures (session open / auth / …) MUST surface as a failed event, never a throw.
+                yield errorToTerminal(error);
+                return;
+            }
+            const queue = new EventQueue();
+            const unsub = harness.subscribe((pe) => {
+                const event = toAgentEvent(pe);
+                if (event)
+                    queue.push(event);
+            });
+            let completed; // the assistant message of a cleanly completed turn
+            try {
+                // Run the turn inside the session context so a tool's `execute` can read which session it is in
+                // (turnContext / ToolContext.session). prompt() starts the async work synchronously here, so the
+                // store propagates to the tool calls awaited within it.
+                const opts = await toPiPromptOptions(prompt);
+                const run = turnContext.run({ session: scope.session }, () => harness.prompt(prompt.text, opts));
+                yield* queue.drainUntil(run);
+                let terminal;
+                try {
+                    const message = await run;
+                    terminal = toTerminal(message);
+                    if (terminal.type === "completed")
+                        completed = message;
+                }
+                catch (error) {
+                    terminal = errorToTerminal(error);
+                }
+                yield terminal;
+            }
+            finally {
+                // After a successful turn, keep the session under the model's context window (a long shared group
+                // or 1:1 conversation would otherwise overflow). Runs HERE — before teardown (it uses the harness)
+                // and BEFORE the lease release below, and is awaited via the generator's return(), so the next
+                // turn for this session waits and never reopens mid-compaction. That await rides the consumer's
+                // iteration: a STREAMING consumer (e.g. telegram) already sent the reply on the terminal before
+                // returning, so compaction — rare, only over threshold — does not delay it; a `collect`-style
+                // consumer returns the reply FROM the loop, so it waits for the (occasional) compaction. Non-fatal:
+                // a failed compaction leaves the (still-valid) session for the next turn to retry.
+                if (completed) {
+                    try {
+                        await maybeCompact(harness, completed);
+                    }
+                    catch (error) {
+                        log.warn(`[fastagent] auto-compaction failed during cleanup: ${String(error)}`);
+                    }
+                }
+                // Cleanup MUST NOT throw after the terminal was yielded — that would make an already-closed
+                // event stream throw on iteration (violating SPEC MUST 2 / MUST 3). Contain it, but surface it
+                // (a cleanup failure is abnormal).
+                try {
+                    unsub();
+                }
+                catch (error) {
+                    log.warn(`[fastagent] harness unsubscribe failed during cleanup: ${String(error)}`);
+                }
+                try {
+                    await harness.abort();
+                }
+                catch (error) {
+                    log.warn(`[fastagent] harness abort failed during cleanup: ${String(error)}`);
+                }
+            }
+        }
+        finally {
+            release(); // after cleanup, so the next invoke for this session can enter
+        }
+    }
+    return { invoke };
+}