@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/service.js

@@ -0,0 +1,354 @@
+/**
+ * The product, as one call: an agent directory becomes a live service.
+ *
+ * That phrase is the promise on the README, and until this existed only the CLI could keep it. The
+ * assembly parts live here too — `routesFor`, `mountSessionControl`, `startSchedules` — because a
+ * public entry may not reach into `cli/`: that directory decides process-level things (`fail.ts`
+ * calls `process.exit`) which a library mounted inside someone's app does not get to decide.
+ * Everything else was parts: assemble the agent, discover channels, mount the control plane, start
+ * schedules, open long connections, compose a router. An embedder had to know that list and get its
+ * order right, and getting it wrong is silent: a plane that 404s while advertising itself, a
+ * schedule that never fires.
+ *
+ * So the assembly lives here, and `dev`/`start` are callers. AgentCore is the one exception, and a
+ * substantive one: its channels load lazily after a state-snapshot restore, so it cannot use an
+ * assembly that discovers them eagerly (cli/commands/start.ts says so at the branch).
+ */
+import { mkdirSync, rmSync } from "node:fs";
+import { writeFileAtomic } from "./atomic-write.js";
+import { join } from "node:path";
+import { classifyBind, clientHost } from "./bind.js";
+import { createControlPlane } from "./channels/control.js";
+import { createInvokeHandler } from "./channels/http.js";
+import { text } from "./channels/respond.js";
+import { parseRouteKey, pathUnderPrefix } from "./channels/serve.js";
+import { loadChannels } from "./channels/discover.js";
+import { loadSchedules } from "./schedule/discover.js";
+import { createScheduler } from "./schedule/scheduler.js";
+import { router } from "./channels/serve.js";
+import { log, reportModuleLoadFailures } from "./log.js";
+/** Default wait for a channel's `closed` before reporting it stuck. A channel that ignores its
+ *  abort signal must not hang a caller's teardown — or, during a failed start, keep the original
+ *  error from arriving. The CLI passes a shorter one: its own forced exit must come AFTER this, or
+ *  the process leaves at 0 before the failure is known. */
+const CLOSE_DEADLINE_MS = 5_000;
+/** Settle when every connection has closed, or when the deadline passes. Reports the ones that did
+ *  NOT settle — named individually, so a single stuck channel is not reported as all of them. */
+async function closeWithin(runs, names, deadlineMs) {
+    const pending = new Set(runs.map((_, i) => i));
+    const failures = [];
+    const tracked = runs.map((run, i) => run.closed.then(() => {
+        pending.delete(i);
+    }, (error) => {
+        pending.delete(i);
+        failures.push(error);
+    }));
+    let timer;
+    try {
+        await Promise.race([
+            Promise.all(tracked),
+            // NOT unref'd: this timer is the thing being awaited, and an unref'd one lets the loop go
+            // idle with nothing left to advance it. Cleared below so a prompt close does not hold the
+            // process for the rest of the deadline.
+            new Promise((resolve) => {
+                timer = setTimeout(resolve, deadlineMs);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { stuck: [...pending].map((i) => names[i] ?? "channel"), failures };
+}
+/**
+ * The surface this deployment serves: default `GET /health` plus discovered channels, or the default
+ * POST `/invoke` only when neither a route nor a long-connection channel was declared.
+ */
+export async function routesFor(agentDir, agent, stateRoot, control, options = {}) {
+    const { routes, longConnections, routeChannels, collisions, failures } = await loadChannels(agentDir, {
+        agent,
+        stateRoot,
+        control,
+    });
+    for (const c of collisions) {
+        console.error(`[fastagent] warn: channel route "${c.route}" (${c.source}) collides with an earlier channel — not mounted`);
+    }
+    reportModuleLoadFailures(failures);
+    if (failures.length > 0 || collisions.length > 0) {
+        throw new Error(`channel setup is invalid (${failures.length} load failure(s), ${collisions.length} route collision(s)) — ` +
+            `fix it, or rename an intentionally disabled file to *.disabled`);
+    }
+    const builtinInvoke = options.builtinInvoke !== false && Object.keys(routes).length === 0 && longConnections.length === 0;
+    const channels = builtinInvoke ? { "POST /invoke": createInvokeHandler(agent) } : routes;
+    const healthCovered = Object.keys(channels).some((key) => {
+        const entry = parseRouteKey(key);
+        return entry.path === "/health" && (entry.method === undefined || entry.method === "GET");
+    });
+    let ready = longConnections.length === 0;
+    const health = () => (ready ? text("ok\n", 200) : text("starting\n", 503));
+    return {
+        routes: healthCovered ? channels : { "GET /health": health, ...channels },
+        longConnections,
+        routeChannels,
+        builtinInvoke,
+        setReady(value) {
+            ready = value;
+        },
+    };
+}
+/**
+ * Refuse channel routes the control plane would swallow.
+ *
+ * `router` refuses this too, and would catch it a moment later; this exists for the sentence, not
+ * the check — an author who lands a route under `/control` needs to hear about `sessionControl`,
+ * which the host has no way to mention. Both ask {@link pathUnderPrefix}, so there is one rule with
+ * two wordings, not two rules.
+ *
+ * Called from BOTH mount points: here at boot, and again on agentcore's lazy path, whose channels
+ * load after this ran against an empty base.
+ */
+export function assertNoControlPlaneCollision(channelRoutes, plane) {
+    const collisions = Object.keys(channelRoutes).filter((key) => pathUnderPrefix(parseRouteKey(key).path, plane.prefix));
+    if (collisions.length > 0) {
+        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the session control plane — ` +
+            `rename the channel route or disable sessionControl in fastagent.config`);
+    }
+}
+export function mountSessionControl(routes, control, stateRoot, options = {}) {
+    if (!control)
+        return { routes, mounts: [], announce: () => () => { } };
+    const token = crypto.randomUUID();
+    const plane = createControlPlane(control, { token, agent: options.agent });
+    assertNoControlPlaneCollision(routes, plane);
+    return {
+        routes,
+        mounts: [plane],
+        control: { token, prefix: plane.prefix },
+        // Writes the discovery file and hands back its removal. It installs NO signal handlers: a
+        // library mounted inside someone's app must not change how that app exits — the CLI wires the
+        // returned cleanup into its own shutdown, an embedder into `close()`.
+        announce: (boundPort) => {
+            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+            const path = join(stateRoot, "control.json");
+            const url = `http://${clientHost(options.host)}:${boundPort}`;
+            writeFileAtomic(path, `${JSON.stringify({ url, token })}\n`, 0o600);
+            log.info(`[fastagent] session control on /control/* (token in ${path})`);
+            // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths
+            // warn loudly, and the LAN path must not be the silent third way past the local trust story.
+            // A loopback bind closes exactly that reach, so it earns silence.
+            const bind = classifyBind(options.host);
+            if (bind !== "loopback") {
+                log.warn(`[fastagent] the port binds ${bind === "wildcard" ? "all interfaces" : `${options.host} (off this machine)`}: ` +
+                    "/control/* is reachable on your LAN, protected only by the bearer token — bind loopback " +
+                    "(--bind 127.0.0.1), firewall the port, or wrap it for real exposure (docs: design §14)");
+            }
+            if (options.tunnel) {
+                // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
+                log.warn("[fastagent] --tunnel exposes /control/* (steer/abort/set_model) at the public tunnel URL, " +
+                    "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs: design §14)");
+            }
+            // Removed on shutdown so a stale file cannot point a client at a dead port: `attach` then
+            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
+            return () => {
+                try {
+                    rmSync(path, { force: true });
+                }
+                catch {
+                    /* the file is advisory — shutdown must not fail on it */
+                }
+            };
+        },
+    };
+}
+/**
+ * Load and start the agent's `schedules/` — a time-trigger firing the agent on each cron. Starts iff
+ * there are static schedules OR `selfSchedule` is on. Best-effort stop on process signals. Returns the
+ * loaded schedules so a serving surface that needs them (the AgentCore adapter's fire binding) shares
+ * ONE load instead of re-discovering. `externalClock` (AgentCore) arms no resident cron timers.
+ */
+export async function startSchedules(agentDir, agent, stateRoot, selfSchedule, options = {}) {
+    // Thrown, not exited on: this runs inside an embedder's app as well as the CLI, and a library
+    // that calls process.exit takes a decision (degrade? retry? stop?) that belongs to its host. The
+    // CLI catches at its own boundary.
+    const { schedules, failures } = await loadSchedules(agentDir);
+    reportModuleLoadFailures(failures);
+    if (schedules.length === 0 && !selfSchedule)
+        return { schedules, stop: () => { } };
+    const scheduler = createScheduler({ agent, stateRoot, schedules, externalClock: options.externalClock });
+    scheduler.start();
+    if (schedules.length > 0) {
+        log.info(`[fastagent] schedules: ${schedules.map((s) => s.name).join(", ")}${options.externalClock ? " (external clock — no resident cron timers)" : ""}`);
+    }
+    // Returned rather than bound to process signals here: this runs inside an embedder's app as well
+    // as the CLI, and a library that installs SIGINT handlers is deciding something that is not its
+    // to decide. `runStart`/`runDev` wire it to their own shutdown.
+    return { schedules, stop: () => scheduler.stop() };
+}
+/**
+ * The assembly itself, over an already-opened directory: channels, the control plane, schedules and
+ * long connections, composed into one handler.
+ *
+ * {@link createAgentService} is this plus opening the directory. `dev`/`start` open separately — their
+ * startup report needs the opened values before anything mounts — and then arrive here, so there is
+ * one assembly rather than one per caller.
+ */
+export async function mountAgentService(opened, options = {}) {
+    const { agentDir, workspace, stateRoot, sessionControl } = opened;
+    // Wrapped BEFORE anything consumes it: routes, the control plane and schedules must all drive the
+    // same agent, so this is a hook rather than something a caller applies afterwards.
+    const agent = options.wrapAgent?.(opened.agent) ?? opened.agent;
+    const closeTimeoutMs = options.closeTimeoutMs ?? CLOSE_DEADLINE_MS;
+    const routed = await routesFor(agentDir, agent, stateRoot, sessionControl, { builtinInvoke: true });
+    const withControl = mountSessionControl(routed.routes, sessionControl, stateRoot, {
+        agent,
+        ...(options.control?.tunnel !== undefined ? { tunnel: options.control.tunnel } : {}),
+        ...(options.control?.host !== undefined ? { host: options.control.host } : {}),
+    });
+    // Composed BEFORE anything starts. `router` re-validates what `loadChannels` and the control
+    // mount already checked, so on THIS path it should not fail — but "should not" is not an ordering
+    // guarantee, and a throw after the scheduler ticks and channels dial would leave both running
+    // with no service for the caller to close. Free to order correctly; expensive to discover later.
+    const handler = router(withControl.routes, withControl.mounts);
+    const scheduled = await startSchedules(agentDir, agent, stateRoot, opened.selfSchedule);
+    const abort = new AbortController();
+    let unannounce;
+    // A connection that drops while others are still dialling must not be undone by their later
+    // readiness: the service is missing a declared channel from that moment on, whatever else arrives.
+    let dropped = false;
+    const onClosed = options.onChannelClosed ??
+        ((name, error) => log.error(`[fastagent] long connection ${name} ${error === undefined ? "closed" : `failed: ${String(error)}`}`));
+    const runs = [];
+    // A FUNCTION declaration, not a const: `close()` detaches this listener, and a rollback can call
+    // `close()` before this point is reached — a `const` would be in its temporal dead zone there, so
+    // the cleanup would throw a ReferenceError and silently skip everything after it.
+    //
+    // Detached because a caller that closes services itself while holding one long-lived signal would
+    // otherwise accumulate listeners, each pinning a whole service through its closure. The signal
+    // path has no caller awaiting the promise, so a failure to stop is reported rather than left as an
+    // unhandled rejection — in an embedded library, potentially the host's exit.
+    function onAbort() {
+        void close().catch((error) => log.error(`[fastagent] service close failed: ${String(error)}`));
+    }
+    let closing;
+    const close = () => {
+        // Awaits the connections rather than only signalling them: `close()` promises they are stopped,
+        // and a caller tearing down a test or a request-scoped service needs that to be true on return.
+        closing ??= (async () => {
+            abort.abort();
+            scheduled.stop();
+            options.signal?.removeEventListener("abort", onAbort);
+            unannounce?.(); // a stale discovery file would point a client at a dead port
+            // A failure to stop is the caller's to know about — swallowing it would let `close()` report
+            // success over a channel still holding on. Bounded, because a channel that ignores its abort
+            // signal must not hang the teardown either.
+            const { stuck, failures } = await closeWithin(runs, routed.longConnections.map((c) => c.name), closeTimeoutMs);
+            if (stuck.length > 0) {
+                throw new Error(`long connection(s) did not stop within ${closeTimeoutMs}ms: ${stuck.join(", ")}`);
+            }
+            if (failures.length > 0) {
+                throw failures.length === 1 ? failures[0] : new AggregateError(failures, "long connections failed to close");
+            }
+        })();
+        return closing;
+    };
+    // Rollback IS close(), plus keeping the original error: a failure to clean up is the aftermath,
+    // and replacing the reason the caller needs with it hides the actual cause.
+    const rollback = async (error) => {
+        await close().catch((closeError) => log.error(`[fastagent] cleanup after a failed start also failed: ${String(closeError)}`));
+        throw error;
+    };
+    // Rolled back on failure: a connection that throws while the ones before it are open, and the
+    // scheduler already ticking, would otherwise leave both running behind a rejected open().
+    for (const connection of routed.longConnections) {
+        let run;
+        try {
+            run = connection.connect(abort.signal);
+        }
+        catch (error) {
+            return rollback(error);
+        }
+        if (typeof run?.ready?.then !== "function" || typeof run?.closed?.then !== "function") {
+            return rollback(new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`));
+        }
+        void run.closed.then(() => {
+            if (abort.signal.aborted)
+                return;
+            // A channel that dies leaves the service serving something it no longer has.
+            dropped = true;
+            routed.setReady(false);
+            onClosed(connection.name);
+        }, (error) => {
+            if (abort.signal.aborted)
+                return;
+            dropped = true;
+            routed.setReady(false);
+            onClosed(connection.name, error);
+        });
+        runs.push(run);
+    }
+    if (options.signal?.aborted)
+        await close();
+    else
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+    // Health answers 503 until EVERY long connection is up, so a load balancer does not route into a
+    // service whose socket-mode channels are still dialling. An abort before that settles `ready` as
+    // cancellation, not readiness — a service being torn down must not report itself healthy.
+    const ready = (async () => {
+        try {
+            await Promise.all(runs.map(async (run, i) => {
+                const name = routed.longConnections[i]?.name ?? "channel";
+                // Raced against `closed`, because the contract puts a terminal failure THERE: a channel
+                // that dies dialling may leave `ready` pending forever, and waiting on it alone hangs
+                // startup with no diagnosis.
+                await Promise.race([
+                    run.ready,
+                    run.closed.then(() => Promise.reject(new Error(`${name} closed before it was ready`)), (error) => Promise.reject(new Error(`${name} failed before it was ready: ${String(error)}`))),
+                ]);
+                if (!abort.signal.aborted)
+                    log.info(`[fastagent] long connection ready: ${name}`);
+            }));
+        }
+        catch (error) {
+            // A connection that cannot come up is a startup failure, not a degraded service: tear the rest
+            // down before rejecting, so nothing is left running behind a caller that saw an error. A
+            // cleanup that ALSO fails is logged, never rethrown — it would replace the reason the caller
+            // actually needs with the aftermath of it.
+            await close().catch((closeError) => log.error(`[fastagent] cleanup after a failed start also failed: ${String(closeError)}`));
+            throw error;
+        }
+        // A `ready` that settles because the service was CLOSED is cancellation, not readiness — the
+        // contract lets a connection resolve it on abort. Returning normally would tell a caller its
+        // channels are up while the service is shut and health says 503.
+        if (abort.signal.aborted)
+            throw new Error("service closed before it became ready");
+        // A drop DURING startup fails it. `dropped` is only reachable here from the startup window —
+        // after this line `ready` has settled — and resolving while health is permanently 503 would
+        // hand the caller two contradictory answers about the same surface.
+        if (dropped) {
+            await close();
+            throw new Error("a long connection closed before startup completed");
+        }
+        routed.setReady(true);
+    })();
+    // Observed here so a rejection is never unhandled; every caller still sees it through `ready`.
+    ready.catch(() => { });
+    return {
+        handler,
+        agent,
+        routes: withControl.routes,
+        agentDir,
+        workspace,
+        channels: {
+            routes: routed.routeChannels,
+            longConnections: routed.longConnections.map((c) => c.name),
+            builtinInvoke: routed.builtinInvoke,
+        },
+        schedules: scheduled.schedules,
+        ready,
+        ...(withControl.control ? { control: withControl.control } : {}),
+        announce: (boundPort) => {
+            unannounce = withControl.announce(boundPort);
+        },
+        close,
+    };
+}

package/dist/session-remote.d.ts

@@ -1,6 +1,6 @@
 /**
  * The remote `SessionControl` — the client half of the Phase 3 transport (design §13). Engine- and
- * server-neutral: speaks only the wire protocol `controlRoutes` serves (HTTP JSON + SSE with the
+ * server-neutral: speaks only the wire protocol `createControlPlane` serves (HTTP JSON + SSE with the
  * {sessionId, epoch, seq, event} envelope) and re-exposes the SAME `SessionControl` interface, so
  * local and remote consumers are isomorphic — client code does not change when the agent moves out
  * of process.

package/dist/session-remote.js

@@ -202,7 +202,8 @@ export function connectAgent(options) {
     // (carry it or reject it), never vanish on the wire while the client believes it was sent.
     const _invokeDriftGuard = {};
     void _invokeDriftGuard;
-    // Same guard for Scope: the body carries session only — a new Scope field must force a decision.
+    // Same guard for Scope: the body carries session + the lineage extension — a new Scope field must
+    // force a decision (carry it or reject it), never vanish on the wire.
     const _scopeDriftGuard = {};
     void _scopeDriftGuard;
     return {
@@ -229,7 +230,14 @@ export function connectAgent(options) {
                     const res = await fetchFn(`${base}/control/invoke`, {
                         method: "POST",
                         headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-                        body: JSON.stringify({ session: scope.session, text: prompt.text }),
+                        body: JSON.stringify({
+                            session: scope.session,
+                            text: prompt.text,
+                            // Lineage rides the wire so a remote thread scope inherits server-side; the server
+                            // reads it on the session-create path only, same as in-process.
+                            ...(scope.parentSession !== undefined ? { parentSession: scope.parentSession } : {}),
+                            ...(scope.branchHints !== undefined ? { branchHints: scope.branchHints } : {}),
+                        }),
                         signal: abort.signal,
                     });
                     watchdog.disarm(); // headers arrived

package/dist/session.d.ts

@@ -91,7 +91,7 @@ export declare const INVALID_COMMAND_CODE = "invalid_command";
  *  before acceptance; retry after the session's first turn exists. */
 export declare const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
+ *  nothing durable landed — a failed override append, or compact's admission failing (binding the session
  *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as
@@ -289,7 +289,9 @@ export type CompactionFinishedEvent = SessionEvent<"compaction_finished", {
  *  the next event (message_*, `run_settled`, `compaction_finished`) is the closure, and the
  *  engine's `retry_finished` carries no outcome to forward. */
 export type RetryScheduledEvent = SessionEvent<"retry_scheduled", {
-    operation: "compaction" | "branch_summary";
+    /** "assistant" is an engine that retries the ANSWER request itself (pi's AgentSession does;
+     *  pi's own session does; a summarization call is the other two). */
+    operation: "assistant" | "compaction" | "branch_summary";
     attempt: number;
     maxAttempts: number;
     delayMs: number;

package/dist/session.js

@@ -16,7 +16,7 @@ export const INVALID_COMMAND_CODE = "invalid_command";
  *  before acceptance; retry after the session's first turn exists. */
 export const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a boundary mutation rejected BEFORE acceptance with
- *  nothing durable landed — a failed override append, or compact's admission failing (the harness
+ *  nothing durable landed — a failed override append, or compact's admission failing (binding the session
  *  build, the local preparation). Acceptance sits where the work becomes asynchronous and
  *  expensive: the model call — compact is accept-fast (holding the dispatch open for a full model
  *  call would make acceptance = outcome), and post-acceptance outcomes travel as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.17.1",
+  "version": "0.19.0",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, Telegram, Slack, or behind any channel.",
   "keywords": [
     "agent",
@@ -43,6 +43,10 @@
       "types": "./dist/core.d.ts",
       "default": "./dist/core.js"
     },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
     "./session": {
       "types": "./dist/session.d.ts",
       "default": "./dist/session.js"
@@ -101,9 +105,10 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.83.0",
-    "@earendil-works/pi-ai": "^0.83.0",
-    "@earendil-works/pi-coding-agent": "^0.83.0",
+    "@earendil-works/pi-agent-core": "^0.84.3",
+    "@earendil-works/pi-ai": "^0.84.3",
+    "@earendil-works/pi-coding-agent": "^0.84.3",
+    "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@octokit/webhooks-methods": "^6.0.0",
     "@octokit/webhooks-types": "^7.6.1",
@@ -118,9 +123,13 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.2",
+    "@types/express": "^5.0.6",
     "@types/proper-lockfile": "^4.1.4",
+    "express": "^5.2.1",
+    "fastify": "^5.12.1",
     "knip": "^6.29.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.9"
+    "vitest": "^4.1.9",
+    "yaml": "^2.9.0"
   }
 }

package/dist/channels/state.d.ts

@@ -1,16 +0,0 @@
-/** Create the channel's state home — the one shared spelling of it, so no channel invents its own. */
-export declare function ensureStateHome(dir: string): void;
-/** Returns `unknown` on purpose — no generic pretending otherwise: the file is an IO boundary, and the
- *  caller owns shape validation (a `<T>` here would be an unchecked cast wearing a type). */
-export declare function loadStateFile(path: string): unknown;
-export declare function saveStateFile(path: string, value: unknown): void;
-/**
- * Drop a state file a redesign retired. Best-effort by design: a leftover file is untidy, not fatal,
- * so a failure is debug-level and never blocks a boot. Only for files that are pure CACHE — anything
- * whose loss changes behaviour needs a migration, not a delete.
- *
- * Shared because a retired file is usually retired in every channel at once: one best-effort
- * semantic, one log shape, one place to check what "retired" means here. (The removal DEADLINE is not
- * here — it lives in test/migration-deadline.test.ts, which names every call site to delete.)
- */
-export declare function removeRetiredStateFile(stateHome: string, name: string, label: string): void;

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

@@ -1,112 +0,0 @@
-/**
- * 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 { ExecutionEnv, ExecutionToolContext, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
-import type { Model, Models } from "@earendil-works/pi-ai";
-import { type PiSessionStore } from "./sessions.ts";
-import { type MountedTool } from "./tool.ts";
-import { type OverrideEntryLike } from "./session-settings.ts";
-/**
- * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
- * tools a loader activated in that call. The DEDICATED record the resolve below reads: pi's own
- * `active_tools_change` entries are full active-set SNAPSHOTS (setActiveTools persists everything
- * active at that moment), and reinterpreting a snapshot as activations would keep a tool active in
- * old sessions after the author flips it to `deferred` — the session never discovered it. Deltas
- * carry only what was actually discovered.
- */
-export declare const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
-/** The session a factory-built harness is bound to — the seam the activation bridge (invoke.ts) uses
- *  to write {@link TOOL_ACTIVATION_ENTRY} deltas (pi's harness keeps its session private). Absent for
- *  a harness built outside {@link piHarnessFactory}: activation still works in-turn there, but is not
- *  recorded — the factory owns persistence. */
-type AnyHarness = AgentHarness<any>;
-export type PiSession = Awaited<ReturnType<PiSessionStore["openOrCreate"]>>;
-export declare function harnessSession(harness: AnyHarness): PiSession | undefined;
-/**
- * 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. */
-/** The harness fastagent builds: context-typed on {@link ExecutionToolContext}, because that is what
- *  pi's env-backed default tools read (pi 0.83). Custom tools are context-FREE and stay assignable — a
- *  four-parameter `execute` satisfies the five-parameter one, so `defineTool` is untouched by this. */
-type PiHarness = AgentHarness<ExecutionToolContext>;
-export type PiHarnessFactory = (session: string) => PiHarness | Promise<PiHarness>;
-export interface PiHarnessFactoryOptions {
-    /** Session persistence. Continuity = same backing store + same session id. */
-    sessions: PiSessionStore;
-    /** Filesystem/process environment for the default coding tools. Handed to the harness as the TURN's
-     *  tool context (pi 0.83), which is how read/bash/edit/write reach the machine at all — so this is the
-     *  ONE seam a sandbox adapter implements, not a knob beside the tools that ignore it. */
-    env: ExecutionEnv;
-    /** Provider collection for all model requests; {@link model} must belong to it (same provider id). */
-    models: Models;
-    model: AnyModel;
-    /** Reasoning effort for the model (pi's scale). Unset = fastagent's pinned default ("medium", pi
-     *  TUI parity — see {@link DEFAULT_THINKING_LEVEL}); unsupported levels are clamped by pi per model. */
-    thinkingLevel?: ThinkingLevel;
-    tools?: MountedTool[];
-    /**
-     * 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[];
-    }>;
-}
-/**
- * Retry policy for generated compaction/branch-summary model calls (pi ≥0.81.1, #6901). OPT-IN
- * upstream — an undefined policy means no retries — so both compaction paths pass it explicitly:
- * the harness config (auto-compaction inside a run) and the manual `compact()` dispatch in
- * session-control. Values mirror pi's own app defaults (maxRetries 3, base 2s exponential).
- */
-export declare const SUMMARIZATION_RETRY_POLICY: {
-    readonly enabled: true;
-    readonly maxRetries: 3;
-    readonly baseDelayMs: 2000;
-};
-/**
- * The serving default for reasoning effort, pinned to what pi's TUI defaults to (its
- * DEFAULT_THINKING_LEVEL) — NOT inherited from the bare harness, whose own fallback is "off": an
- * author vibes at "medium" in pi and must get "medium" when served (fidelity), and pinning the value
- * here means an upstream default change in either place cannot silently alter deployments. Models
- * that don't support a level are clamped by pi per model.
- */
-export declare const DEFAULT_THINKING_LEVEL: ThinkingLevel;
-/**
- * {@link resolveSessionSettings} plus the warn only the execution path owes: a recorded pair can stop
- * being executable with no control-plane command involved (pi appends these entries itself; a
- * deployment's configured model can change between restarts). Deduped per session+cause — it would
- * otherwise repeat every turn.
- */
-export declare function resolveHarnessOverrides(entries: OverrideEntryLike[], models: Models, defaults: {
-    model: AnyModel;
-    thinkingLevel: ThinkingLevel;
-}, sessionId: string): {
-    model: AnyModel;
-    thinkingLevel: ThinkingLevel;
-};
-export declare function resolveHarnessActiveToolNames(recorded: string[] | null, tools: MountedTool[], sessionId: string): string[] | undefined;
-/** Open-or-create the session per invoke: existing → open (history via buildContext); missing → create. */
-export declare function piHarnessFactory(options: PiHarnessFactoryOptions): PiHarnessFactory;
-export {};