@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/engines/pi/session-store.js

@@ -0,0 +1,313 @@
+/**
+ * Session persistence for the `AgentSession` L0 — open-or-create a durable record by the Caller's
+ * opaque session id, on pi-coding-agent's `SessionManager` (the v3 jsonl every pi surface reads).
+ *
+ * Records written before this store existed (by the pi-agent-core `Session` the serving path used
+ * to run on) are the same v3 jsonl and are continued in place — see `legacySessionId`. That is a
+ * READ path for existing conversations, not a second engine.
+ */
+import { existsSync, mkdirSync, renameSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { SessionManager } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
+import { copyBranchInto, forkForInheritance, inheritanceCut } from "./session-inheritance.js";
+/**
+ * A Caller's session id, as a name pi will accept.
+ *
+ * `SessionManager` enforces `^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$` — which no built-in
+ * channel satisfies: telegram's `-1001234567890` leads with a dash, feishu and slack keys carry
+ * `:` and `/`, and any custom `route()` may mint anything at all.
+ *
+ * The mapping is INJECTIVE, because two conversations resolving to one record is two rooms sharing a
+ * memory. `s` prefix (the pattern demands an alphanumeric head, and prefixing unconditionally is what
+ * keeps it injective — a conditional one would map `-a` and `s-a` alike), then each character
+ * outside `[A-Za-z0-9.-]` becomes `_XX` / `_uXXXX`, self-describing widths so no two inputs can
+ * produce one output. `_` escapes itself for the same reason. A trailing `.` or `-` is legal
+ * mid-name but not at the end, so it escapes too.
+ *
+ * Injective within this encoding — which is only sufficient because new records live in their own
+ * directory. The older spelling draws names from the same character set (it stored a room literally
+ * called `s42` as `s42`, which is also this encoding of `42`), so one directory would make some
+ * names ambiguous no matter how either side spells them.
+ *
+ * Readability is deliberate: `-1001234567890` becomes `s-1001234567890`, so an operator can still
+ * tell which room a file belongs to.
+ */
+export function piSessionId(sessionId) {
+    const hex = (c) => {
+        const code = c.charCodeAt(0);
+        return code < 0x100
+            ? `_${code.toString(16).toUpperCase().padStart(2, "0")}`
+            : `_u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+    };
+    const body = sessionId.replace(/[^A-Za-z0-9.-]/g, hex).replace(/[.-]$/, hex);
+    return `s${body}`;
+}
+/**
+ * Disk-backed store under `dir`: restart the process, conversations continue.
+ *
+ * Lookup is a directory scan (`SessionManager.list`) because pi names files `<timestamp>_<id>.jsonl`
+ * and the timestamp is not ours to predict — the same trade sessions.ts makes today.
+ *
+ * A record written before this store existed keeps ITS id (the older path spelled them differently),
+ * so the scan accepts either: a conversation that predates this store is continued rather than
+ * silently restarted as an empty one. Nothing is rewritten on disk.
+ *
+ * NEW records live in a subdirectory of their own, because the two engines cannot share a namespace:
+ * both spell ids into `[A-Za-z0-9._-]`, so neither can claim a prefix the other cannot produce, and
+ * a directory holding both would have names that belong to two conversations at once — in whichever
+ * direction it is read. Separate directories make each side's own injectivity sufficient.
+ *
+ * A PRE-EXISTING record is still continued in place: it is looked up by the older spelling, which is
+ * injective on its own terms, and appended to where it lies. Both spellings are the same v3 jsonl,
+ * so a conversation started before this store keeps going rather than restarting empty.
+ *
+ * SCOPE OF "open-or-create": idempotent against a store that is serialized per session, which is what
+ * the serving path provides — the single-writer lease is taken before any store call, so no two
+ * turns of one conversation reach this at once. What it does NOT do is arbitrate a FIRST open racing
+ * across processes: two instances that scan before either writes will both create, and the
+ * conversation forks into two records. sessions.ts states the same boundary for the same reason
+ * ("the serving path serializes it with the single-writer lease before reaching any store"), and a
+ * horizontally-scaled deployment that wants more owes a lease that spans its instances — an
+ * in-process one cannot arbitrate between them, and a file lock here would only look like it could.
+ */
+export function piSessionRecordStore(options) {
+    const cwd = options.cwd ?? process.cwd();
+    // Resolved against the workspace this store serves, not against wherever the process happens to
+    // have been started: a relative `dir` means "inside this agent", and a serving process may chdir.
+    const root = resolve(cwd, options.dir);
+    const own = join(root, OWN_RECORDS_DIR);
+    /** Where a forked record is finished before it becomes discoverable. A SUBDIRECTORY of the store,
+     *  so `list()` (one level, `*.jsonl`) never sees a record that is still being prepared. */
+    const staging = join(own, ".staging");
+    /** Fork the named parent into `id`, or answer undefined so the caller starts empty. Every failure
+     *  is a warn: a thread must not lose its first turn to an inheritance edge. */
+    const inheritInto = async (id, inherit) => {
+        const parentId = piSessionId(inherit.parentSession);
+        const found = (await SessionManager.list(cwd, own)).find((r) => r.id === parentId) ??
+            (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(inherit.parentSession));
+        if (!found) {
+            log.warn(`[fastagent] session "${id}" names parent "${inherit.parentSession}", which has no record — starting empty`);
+            return undefined;
+        }
+        try {
+            const parentDir = found.id === parentId ? own : root;
+            mkdirSync(staging, { recursive: true });
+            const staged = forkForInheritance({
+                // A parent that crashed mid tool-execution would otherwise pass its dangling tool_use down
+                // to the child, whose very first request the provider then rejects.
+                parent: reconcileInterruptedToolCalls(SessionManager.open(found.path, parentDir)),
+                id,
+                cwd,
+                stagingDir: staging,
+                branchHints: inherit.branchHints,
+            });
+            if (!staged)
+                return undefined;
+            // Publish only once the record is complete: same-filesystem rename, so a reader sees the whole
+            // thing or nothing at all.
+            const stagedFile = staged.getSessionFile();
+            if (!stagedFile)
+                return staged; // non-persisting backend: nothing to publish
+            const target = join(own, basename(stagedFile));
+            renameSync(stagedFile, target);
+            return SessionManager.open(target, own);
+        }
+        catch (error) {
+            // Unattributed on purpose: this spans reading the parent AND writing the child.
+            log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${id}" (${String(error)}) — starting empty`);
+            return undefined;
+        }
+    };
+    return {
+        async openOrCreate(sessionId, inherit) {
+            const id = piSessionId(sessionId);
+            const mine = (await SessionManager.list(cwd, own)).find((r) => r.id === id);
+            if (mine)
+                return reconcileInterruptedToolCalls(SessionManager.open(mine.path, own));
+            const legacy = (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(sessionId));
+            if (legacy)
+                return reconcileInterruptedToolCalls(SessionManager.open(legacy.path, root));
+            mkdirSync(own, { recursive: true });
+            // Inheritance is a CREATE-path decision: an existing session above ignores it entirely, which
+            // is what makes it one-time by construction.
+            if (inherit) {
+                const inherited = await inheritInto(id, inherit);
+                if (inherited)
+                    return inherited;
+            }
+            return publish(SessionManager.create(cwd, own, { id }), own);
+        },
+        async openIfExists(sessionId) {
+            const id = piSessionId(sessionId);
+            const mine = (await SessionManager.list(cwd, own)).find((r) => r.id === id);
+            if (mine)
+                return SessionManager.open(mine.path, own);
+            const legacy = (await SessionManager.list(cwd, root)).find((r) => r.id === legacySessionId(sessionId));
+            return legacy ? SessionManager.open(legacy.path, root) : undefined;
+        },
+    };
+}
+/**
+ * Crash-safety reconciliation, run on every OPEN of an existing record.
+ *
+ * A turn that dies mid tool-execution leaves an assistant `tool_use` with no matching result (the
+ * assistant message is persisted before the tool runs). The next turn would then hand the provider
+ * an `assistant(tool_use) -> user` sequence that Anthropic and OpenAI reject — the session is
+ * poisoned. An honest "interrupted" error result is appended for each dangling call, restoring a
+ * valid transcript. Tool side-effect idempotency stays the tool's responsibility (SPEC §6); this
+ * restores transcript validity, not exactly-once execution.
+ *
+ * Pairing is TURN-LOCAL: a tool_use is paired only by a toolResult that immediately follows it (up
+ * to the next non-toolResult). Tool-call ids are not unique across turns — a local model may restart
+ * them each response — so matching against the whole transcript could falsely settle a leaf call
+ * against an earlier turn's identical id. An append-only log can only repair a gap AT THE LEAF; an
+ * earlier one is surfaced via log.warn rather than "fixed" with an orphaned result.
+ *
+ * The synthetic result splits its audiences: `content` (read by the model, may reach the end user)
+ * stays neutral — it must NOT say "aborted" (pi's word for a user cancellation) or leak infra
+ * detail; `details` carries the operational marker for developers and never reaches the provider.
+ */
+function reconcileInterruptedToolCalls(record) {
+    const messages = record.getBranch().flatMap((entry) => {
+        const message = entry.message;
+        return entry.type === "message" && message ? [message] : [];
+    });
+    let leafIdx = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i]?.role === "assistant") {
+            leafIdx = i;
+            break;
+        }
+    }
+    if (leafIdx === -1)
+        return record; // no assistant turn yet
+    const leafReparable = messages.slice(leafIdx + 1).every((m) => m.role === "toolResult");
+    const toRepair = [];
+    const orphaned = [];
+    messages.forEach((m, idx) => {
+        if (m.role !== "assistant")
+            return;
+        const paired = new Set();
+        for (let j = idx + 1; j < messages.length; j++) {
+            const next = messages[j];
+            if (next?.role !== "toolResult")
+                break;
+            paired.add(next.toolCallId);
+        }
+        for (const block of m.content) {
+            if (block.type !== "toolCall" || paired.has(block.id))
+                continue;
+            if (idx === leafIdx && leafReparable)
+                toRepair.push({ id: block.id, name: block.name });
+            else
+                orphaned.push(block.id);
+        }
+    });
+    if (orphaned.length > 0) {
+        log.warn(`[fastagent] unmatched tool_use is not at the session leaf; leaving it unreconciled ` +
+            `(an append-only log cannot repair a mid-history gap): toolCallIds=${orphaned.join(",")}`);
+    }
+    for (const { id, name } of toRepair) {
+        record.appendMessage({
+            role: "toolResult",
+            toolCallId: id,
+            toolName: name,
+            content: [
+                {
+                    type: "text",
+                    text: "This tool call did not complete and its result is unavailable. Re-run it if the result is still needed.",
+                },
+            ],
+            details: { fastagent: "interrupted-tool-call" },
+            isError: true,
+            timestamp: Date.now(),
+        });
+    }
+    return record;
+}
+/** Where this engine's own records live, under the sessions directory both engines are pointed at. */
+const OWN_RECORDS_DIR = "agent-session";
+/**
+ * Make a NEW record exist on disk before anyone can act on it.
+ *
+ * `SessionManager` buffers a new session in memory and writes nothing until the first ASSISTANT
+ * message arrives (`_persist` returns early while no assistant entry exists). Two consequences, and
+ * the second is why this cannot be left to the engine:
+ *
+ * - a crash between "the user asked" and "the model answered" loses the question, while the record
+ *   pi-agent-core's storage wrote it immediately (conformance-levels.md §5 named this gap);
+ * - **open-or-create stops being idempotent**: the second call cannot find the first call's record,
+ *   so one conversation forks into two files, each with half the history.
+ *
+ * Writing pi's OWN header (`getHeader()`, not a hand-built literal) and reopening puts the manager
+ * on its normal "file exists" path, where every append lands immediately.
+ */
+function publish(session, dir) {
+    const file = session.getSessionFile();
+    if (!file || existsSync(file))
+        return session; // in-memory, or already on disk
+    const header = session.getHeader();
+    if (!header)
+        return session;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, `${JSON.stringify(header)}\n`, { flag: "wx" });
+    return SessionManager.open(file, dir);
+}
+/** In-process store: continuity lives and dies with the instance. */
+export function piInMemorySessionRecordStore(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const live = new Map();
+    return {
+        async openOrCreate(sessionId, inherit) {
+            // Keyed by the CALLER's id: the encoding exists to satisfy pi's filename rule, and in memory
+            // there are no filenames — two rooms whose encodings collide must still not share a map slot.
+            const existing = live.get(sessionId);
+            if (existing)
+                return reconcileInterruptedToolCalls(existing);
+            const fresh = () => SessionManager.inMemory(cwd, { id: piSessionId(sessionId) });
+            // Same semantics as the durable store, different mechanism: with no file to fork, the parent's
+            // path is copied entry by entry. Inheritance is a property of the CONTRACT, not of the medium —
+            // a caller must not get a thread that forgot its room because the store is in memory.
+            //
+            // And the same atomicity: the session is REGISTERED only once it is complete. Registering
+            // first and copying after would leave a half-inherited thread in place on any failure, while
+            // the log claimed it started empty — the disk path stages a fork for exactly this reason.
+            const parent = inherit ? live.get(inherit.parentSession) : undefined;
+            if (inherit && !parent) {
+                log.warn(`[fastagent] session "${sessionId}" names parent "${inherit.parentSession}", which has no record — starting empty`);
+            }
+            let created;
+            if (inherit && parent) {
+                try {
+                    const staged = fresh();
+                    const cut = inheritanceCut(reconcileInterruptedToolCalls(parent), inherit.branchHints);
+                    if (cut)
+                        copyBranchInto(parent, staged, cut.at);
+                    created = staged;
+                }
+                catch (error) {
+                    log.warn(`[fastagent] could not inherit from "${inherit.parentSession}" into "${sessionId}" (${String(error)}) — starting empty`);
+                    created = fresh(); // the partially-copied one is discarded, never registered
+                }
+            }
+            else {
+                created = fresh();
+            }
+            live.set(sessionId, created);
+            return created;
+        },
+        async openIfExists(sessionId) {
+            return live.get(sessionId);
+        },
+    };
+}
+/** The spelling used before this store existed — read-only, so older records still resolve. */
+function legacySessionId(sessionId) {
+    return sessionId.replace(/[^A-Za-z0-9._-]/g, (c) => {
+        const code = c.charCodeAt(0);
+        return code < 0x100
+            ? `%${code.toString(16).toUpperCase().padStart(2, "0")}`
+            : `%u${code.toString(16).toUpperCase().padStart(4, "0")}`;
+    });
+}

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

@@ -4,7 +4,8 @@
  * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionTreeEntry } from "@earendil-works/pi-agent-core";
+import type { SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
+import type { 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. */
 export interface ReadonlySessionManager {
@@ -13,13 +14,22 @@ export interface ReadonlySessionManager {
         id: string;
         timestamp: string;
     }>;
-    getBranch(): Promise<SessionTreeEntry[]>;
+    getBranch(): Promise<PiSessionEntry[]>;
 }
 /**
- * The turn's tool-activation bridge — narrow closures over the CURRENT harness (invoke.ts builds it
- * per turn), so a loader tool can activate deferred tools mid-turn without tool.ts importing the
- * harness. pi records the change in the session (`active_tools_change`) and the per-invoke restore
- * (harness.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
+ * 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`.
+ */
+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.
  */
@@ -41,12 +51,12 @@ export interface TurnContext {
     /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
     sessionManager?: ReadonlySessionManager;
     /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
-     *  serving harness; chat.ts bridges pi's AgentSession (chat emulates deferral — same loader, same
+     *  served session; chat.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>;
-/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+/** The additive-activation contract, in ONE place for both bridges (the served session,
  *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
  *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
 export declare function additiveActivation(registered: string[], current: string[], names: string[]): string[];

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

@@ -4,8 +4,30 @@
  * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 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`.
+ */
+export function agentSessionManager(session, sessionId) {
+    return {
+        getSessionId: () => sessionId,
+        async getHeader() {
+            const header = session.sessionManager.getHeader();
+            if (!header)
+                throw new Error("session has no metadata header");
+            return { id: sessionId, timestamp: header.timestamp };
+        },
+        async getBranch() {
+            return session.sessionManager.getBranch();
+        },
+    };
+}
 export const turnContext = new AsyncLocalStorage();
-/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
+/** The additive-activation contract, in ONE place for both bridges (the served session,
  *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
  *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
 export function additiveActivation(registered, current, names) {

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

@@ -11,7 +11,7 @@ export interface ToolContext {
     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
-     *  (invoke.ts, over the harness) and chat (over pi's AgentSession); undefined only outside any turn
+     *  (agent-session-factory.ts) and chat (session-builder.ts); undefined only outside any turn
      *  (a bare `fastagent tool` run). */
     tools?: ToolActivation;
 }
@@ -35,9 +35,9 @@ export interface DefineToolOptions<I extends z.ZodType> {
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
 /**
- * A tool as MOUNTED: what the harness actually runs. Wider than the authored {@link AgentTool} on
- * purpose — pi's default coding tools read the turn's tool context (its ExecutionEnv) as a fifth
- * `execute` parameter, while fastagent's own tools take four and are assignable to it unchanged.
+ * A tool as MOUNTED: what the engine actually runs. Wider than the authored {@link AgentTool} on
+ * purpose — a lower-level mounted tool may read an `ExecutionEnv` from the fifth `execute` parameter,
+ * while coding-agent's cwd-bound tools ignore it and fastagent's authored tools take four arguments.
  * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
  * live in one array; every helper that only inspects or reorders tools is typed on THIS.
  */
@@ -73,7 +73,7 @@ export declare function loadTools(dir: string): Promise<{
     failures: ModuleLoadFailure[];
 }>;
 /**
- * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
 export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {

package/dist/engines/pi/tool.js

@@ -116,7 +116,7 @@ export async function loadTools(dir) {
     return { tools: [...byName.values()], collisions, failures };
 }
 /**
- * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
 export function mergeDiscoveredTools(existing, discovered) {

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

@@ -1,19 +1,22 @@
 /**
- * The turn mechanism's pi-CLASS-neutral half, shared by every pi L0. Not "engine-neutral" in this
- * repo's sense — that term is reserved for code with no engine import at all (src/agent.ts), and
- * everything here speaks pi's message and image types. What it is neutral about is which pi class
- * runs the turn.
+ * 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 — the harness's event vocabulary and its observation plane — stays in
- * invoke.ts, and the AgentSession's in invoke-session.ts.
+ * What is NOT neutral — pi's event vocabulary and how a turn is driven — stays in invoke-session.ts,
+ * the L0 that owns it.
  */
 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. */
@@ -43,6 +46,29 @@ export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
 export declare function toPiPromptOptions(prompt: Prompt): 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. */
+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. */
+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`. */
+export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
 export declare class EventQueue<T> {
     private buffer;
     private wake?;

package/dist/engines/pi/turn-kit.js

@@ -82,7 +82,7 @@ function messageSignal(message) {
  */
 export function toTerminal(message) {
     if (message.stopReason === "aborted") {
-        // A deliberate stop (control-plane abort / harness abort), not an error — see {@link ABORTED_CODE}
+        // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE}
         // for the consumer contract (design §6).
         const details = message.errorMessage ?? "run aborted";
         return { type: "failed", details, retryable: false, code: ABORTED_CODE };
@@ -119,6 +119,33 @@ export async function toPiPromptOptions(prompt) {
     }));
     return { images };
 }
+/** 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`. */
+export function projectAgentEvent(se) {
+    switch (se.type) {
+        case "message_delta": {
+            const d = se.data;
+            return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
+        }
+        case "tool_started": {
+            const d = se.data;
+            return { type: "tool_started", id: d.id, name: d.name, args: d.args };
+        }
+        case "tool_finished": {
+            const d = se.data;
+            return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
+        }
+        case "retry_scheduled": {
+            // `operation` (compaction | branch_summary) stays session-plane vocabulary — a turn renderer
+            // only needs "transient failure, retrying"; the engine detail lives in the control plane.
+            const d = se.data;
+            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
+        }
+        default:
+            return null;
+    }
+}
 // ── EventQueue: push→pull plumbing for a two-port engine ────────────────────
 //
 // Single-consumer async queue; single-threaded JS means no await interleaves between push and

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

@@ -2,7 +2,7 @@
  * The built-in `wake` tool: the agent's self-scheduling surface. Calling it records a one-shot wake-up
  * (wakeups.ts); the scheduler fires it back into the SAME session, so the agent resumes THIS
  * conversation after a delay ("check the deploy in 10 minutes"). The session comes from the turn
- * context (ToolContext.sessionManager, set around the harness turn); the state root is closed over at build
+ * context (ToolContext.sessionManager, set around the turn); the state root is closed over at build
  * time (where it is known — the workspace opener), never read from the turn.
  *
  * Mounted by the opener ONLY when `config.selfSchedule` is on AND on the serving path (`dev`/`start`, where

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./core.ts";
+export * from "./node.ts";
 export * from "./session.ts";
 export * from "./pi.ts";

package/dist/index.js

@@ -2,5 +2,6 @@
 // Contract/channel-only consumers should prefer `@fastagent-sh/fastagent/core`; pi-specific consumers
 // may use `@fastagent-sh/fastagent/pi`. The root remains the supported all-in-one surface.
 export * from "./core.js";
+export * from "./node.js";
 export * from "./session.js";
 export * from "./pi.js";

package/dist/log.d.ts

@@ -23,4 +23,7 @@ export declare function createLogger(opts: {
 /** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` override, if present, wins and is not changed. */
 export declare function setLogLevel(level: LogLevel): void;
 /** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
+import type { ModuleLoadFailure } from "./loader.ts";
 export declare const log: Logger;
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;

package/dist/log.js

@@ -47,5 +47,9 @@ const emit = (level) => (msg) => {
     if (ORDER[level] >= ORDER[currentLevel])
         console.error(format(level, msg));
 };
-/** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
 export const log = { debug: emit("debug"), info: emit("info"), warn: emit("warn"), error: emit("error") };
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export function reportModuleLoadFailures(failures) {
+    for (const f of failures)
+        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
+}

package/dist/node.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Binding a Fetch handler to a Node HTTP server.
+ *
+ * Its own entry point because it is the one piece of the neutral surface that is RUNTIME-specific:
+ * `@hono/node-server` bridges `node:http` ↔ Fetch, and that package is the only third-party weight
+ * anywhere behind `/core`. Keeping it here lets a channel package or another engine import the
+ * contract without pulling a Node HTTP bridge it will never call — and lets a non-Node runtime
+ * (Workers, Deno, Bun's own server) consume `/core` unchanged.
+ *
+ * Engine-neutral is not the same as runtime-neutral, and the two properties give the surface its
+ * three layers: `/core` is both (contract, fetch-shaped kit), `/node` is engine-neutral only (this
+ * file: the assembly and the HTTP binding, which need a filesystem, a clock and an environment),
+ * `/pi` is neither (it names an engine).
+ */
+export { nodeListener, serveNode } from "./channels/serve.ts";
+export { mountAgentService, type AgentService, type MountableAgent, type MountAgentServiceOptions, } from "./service.ts";

package/dist/node.js

@@ -0,0 +1,20 @@
+/**
+ * Binding a Fetch handler to a Node HTTP server.
+ *
+ * Its own entry point because it is the one piece of the neutral surface that is RUNTIME-specific:
+ * `@hono/node-server` bridges `node:http` ↔ Fetch, and that package is the only third-party weight
+ * anywhere behind `/core`. Keeping it here lets a channel package or another engine import the
+ * contract without pulling a Node HTTP bridge it will never call — and lets a non-Node runtime
+ * (Workers, Deno, Bun's own server) consume `/core` unchanged.
+ *
+ * Engine-neutral is not the same as runtime-neutral, and the two properties give the surface its
+ * three layers: `/core` is both (contract, fetch-shaped kit), `/node` is engine-neutral only (this
+ * file: the assembly and the HTTP binding, which need a filesystem, a clock and an environment),
+ * `/pi` is neither (it names an engine).
+ */
+export { nodeListener, serveNode } from "./channels/serve.js";
+// The assembly: a MountableAgent becomes a mounted service. Engine-neutral — it reads the SPEC
+// contract plus three paths, so a second engine reuses it with its own opener — but NOT runtime
+// neutral: it reads a directory, a cron and an environment. That is what makes this its entry
+// rather than `/core`.
+export { mountAgentService, } from "./service.js";

package/dist/paths.d.ts

@@ -142,3 +142,10 @@ export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv):
  * A missing target is fine (nothing to guard yet).
  */
 export declare function assertInsideAgentDir(agentDir: string, name: string): Promise<void>;
+/**
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
+ */
+export declare function isUnderDir(targetPath: string, baseDir: string): boolean;