@fastagent-sh/fastagent 0.17.1 → 0.19.0

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

@@ -0,0 +1,188 @@
+import { ABORTED_CODE } from "../../agent.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);
+            };
+        },
+    };
+}
+/** 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 {};
+}
+/**
+ * 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 === "aborted") {
+        // 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 };
+    }
+    if (message.stopReason === "error") {
+        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)) };
+}
+/**
+ * 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.
+ */
+export 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 };
+}
+/** 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
+// drain, so no locking. Engines that are natively async-iterable would not need it.
+export 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;
+    }
+}

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

@@ -24,6 +24,12 @@ export declare const STATE_DIRNAME = ".state";
 /** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
  *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
 export declare const AGENT_CONFIG_NAMES: readonly ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). Definition
+ *  data, not machinery: it declares WHICH endpoint the agent talks to, so it belongs beside the config
+ *  and travels into the deployed image. The name lives HERE, with the other placement facts, because
+ *  two neutral readers need it — the loader in engines/pi/models.ts and `dev`'s watcher, whose restart
+ *  scope must not silently drift from what the worker actually loads. */
+export declare const AGENT_MODELS_FILE = "models.json";
 export interface ResolvedPlacement {
     /** The AGENT directory — where the definition (persona.md/skills/tools/channels/schedules), the
      *  config, and the machinery dirs (`.secrets/`, `.state/`) live. Absolute. */
@@ -136,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;

package/dist/paths.js

@@ -46,6 +46,12 @@ export const STATE_DIRNAME = ".state";
 /** The config filenames, in load precedence. ONE source: the loader (below) and `scaffoldAgent`'s
  *  already-an-agent refusal both read this, so "is there a config?" can't diverge between them. */
 export const AGENT_CONFIG_NAMES = ["fastagent.config.ts", "fastagent.config.js", "fastagent.config.mjs"];
+/** The optional custom-model-endpoint file inside an agent dir (pi's models.json schema). Definition
+ *  data, not machinery: it declares WHICH endpoint the agent talks to, so it belongs beside the config
+ *  and travels into the deployed image. The name lives HERE, with the other placement facts, because
+ *  two neutral readers need it — the loader in engines/pi/models.ts and `dev`'s watcher, whose restart
+ *  scope must not silently drift from what the worker actually loads. */
+export const AGENT_MODELS_FILE = "models.json";
 /** The definition paths an agent LOADS content from — the surface a second agent must not be scaffolded
  *  inside ({@link agentDefinitionOwner}), because the outer agent would read it as its own skills/tools.
  *  NOT evidence of an agent: `tools/` and `skills/` are ordinary names half the world's repositories
@@ -324,3 +330,13 @@ export async function assertInsideAgentDir(agentDir, name) {
             `use a real directory or a symlink that stays within it`);
     }
 }
+/**
+ * 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 function isUnderDir(targetPath, baseDir) {
+    const rel = relative(baseDir, targetPath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/dist/pi.d.ts

@@ -1,18 +1,25 @@
 export { createPiAgent, createPiAgentFromDefinition, type CreatePiAgentFromDefinitionOptions, type CreatePiAgentOptions, } from "./engines/pi/create.ts";
-export { defineTool, loadTools, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
+export { defineTool, type DefineToolOptions, type FastagentTool, type MountedTool, type ToolCollision, type ToolContext, } from "./engines/pi/tool.ts";
 export type { ReadonlySessionManager, ToolActivation } from "./engines/pi/tool-context.ts";
 export { z } from "zod";
-export type { AgentTool, ExecutionEnv, Session, SessionTreeEntry, Skill, SkillDiagnostic, } from "@earendil-works/pi-agent-core";
-export { loadChannels, type ChannelCollision } from "./engines/pi/channel.ts";
+export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+/**
+ * A conversation record, as the tool runtime and the control plane hold it. Its entries are pi's own
+ * — exported under a qualified name because `SessionEntry` in this package is the NEUTRAL one the
+ * control plane publishes (session.ts), and the two are different shapes.
+ */
+export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
 export { createPiAgentFromDir, type CreatePiAgentFromDirOptions, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
-export { defineConfig, listModels, resolveModel, type FastagentConfig } from "./engines/pi/config.ts";
-export { inProcessLease, type Lease, type Release, type SessionObserver } from "./engines/pi/invoke.ts";
+export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
+export type { SessionObserver } from "./engines/pi/turn-kit.ts";
+export { inProcessLease, type Lease, type Release } from "./engines/pi/turn-kit.ts";
 export { createPiSessionControl, type CreatePiSessionControlOptions, } from "./engines/pi/session-control.ts";
-export type { AnyModel } from "./engines/pi/harness.ts";
-export { inMemorySessionStore, jsonlSessionStore, type PiSessionReader, type PiSessionStore, } from "./engines/pi/sessions.ts";
+export { piInMemorySessionRecordStore, piSessionRecordStore, type PiSessionRecordStore, } from "./engines/pi/session-store.ts";
+export type { SessionInheritance } from "./engines/pi/session-inheritance.ts";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore, type FastagentAuthOptions } from "./engines/pi/auth.ts";
 export { createPiModels, probeAuthSource, type CreatePiModelsOptions } from "./engines/pi/models.ts";
 export type { Models } from "@earendil-works/pi-ai";
-export { createProvider, type Provider, type ProviderAuth } from "@earendil-works/pi-ai";
+export type { Provider, ProviderAuth } from "@earendil-works/pi-ai";
 export type { Model } from "@earendil-works/pi-ai";
+export { createAgentService, type CreateAgentServiceOptions } from "./engines/pi/service.ts";

package/dist/pi.js

@@ -1,13 +1,14 @@
 // The pi reference implementation: assembly, agent discovery, tools, config, models, auth, and state ports.
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
-export { defineTool, loadTools, } from "./engines/pi/tool.js";
+export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { loadChannels } from "./engines/pi/channel.js";
 export { createPiAgentFromDir, } from "./engines/pi/open.js";
-export { defineConfig, listModels, resolveModel } from "./engines/pi/config.js";
-export { inProcessLease } from "./engines/pi/invoke.js";
+export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
+export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";
-export { inMemorySessionStore, jsonlSessionStore, } from "./engines/pi/sessions.js";
+export { piInMemorySessionRecordStore, piSessionRecordStore, } from "./engines/pi/session-store.js";
 export { GLOBAL_AUTH_PATH, fastagentCredentialStore } from "./engines/pi/auth.js";
 export { createPiModels, probeAuthSource } from "./engines/pi/models.js";
-export { createProvider } from "@earendil-works/pi-ai";
+// The product's one-call assembly: a directory becomes a live service. On the pi surface because
+// it opens a directory the pi way (channels, schedules, the assembled agent).
+export { createAgentService } from "./engines/pi/service.js";

package/dist/scaffold/templates/fastagent.config.mjs

@@ -5,6 +5,8 @@
 // No model is preset: `fastagent dev` shows the full model catalog (models you already have
 // credentials for come first; picking one that needs auth logs you in inline) and writes your choice
 // below. Or set it by hand to a "provider/modelId" (`fastagent models` lists them).
+// Self-hosted model (vLLM/Ollama/…) or your own gateway? Declare it in a models.json next to this
+// file and select it like any other spec — see docs/configuration.md "Custom model endpoints".
 export default {
   // model: "openai-codex/gpt-5.5",
   // thinkingLevel: "high", // reasoning effort (off|minimal|low|medium|high|xhigh|max); default "medium" (pi TUI parity)

package/dist/scaffold/templates/persona.md

@@ -2,9 +2,9 @@
 
 You are this workspace's agent. This file is your identity — it overrides the engine's default identity line, and it is re-read every turn along with the rest of your definition (`skills/` — capabilities you load when a task calls for them; `tools/` — code tools your author added, in the same directory as this file). An edit to any of them takes effect on your next message, no restart.
 
-Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on, and where your `read` / `write` / `edit` / `bash` tools operate. It may be this same directory, or the one containing it; `fastagent info` prints both. If the workspace has an `AGENTS.md`, it is project context — read it to learn the project's conventions.
+Your definition is this directory: `persona.md`, `skills/`, `tools/`, and the config beside them. Your WORKSPACE is the directory you were started in — the project you work on. It may be this same directory, or the one containing it; `fastagent info` prints both. Use only the tools actually listed in your system prompt. If the workspace has an `AGENTS.md`, it is project context — follow it without assuming a file tool is available.
 
-You can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
+When your mounted tools allow it, you can improve yourself. When a task reveals something durable — a repeatable process, a standing preference, a hard-won fact — write it into your definition instead of losing it:
 
 - A repeatable process or capability → a new skill beside this file: `skills/<name>/SKILL.md`. Only the `skills/` next to this file is scanned. Read `skills/writing-great-skills/SKILL.md` first; it is the guide to authoring skills well.
 - A standing instruction or fact → edit this file.

package/dist/schedule/state.js

@@ -4,12 +4,10 @@
  *  - `fires.json` — schedule name → last-fired ISO (durability for the cron catch-up-once);
  *  - `wakeups.json` — the agent's pending self-scheduled one-shot wake-ups (wakeups.ts).
  * No .gitignore is written here: the agent's own (scaffolded by `init`) excludes `.state/`.
- *
- * ponytail: this atomic read/write duplicates channels/telegram/state.ts's primitive (both KB-JSON
- * tmp+rename). Extract a neutral src/state.ts and have both import it when a third consumer appears.
  */
-import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { writeFileAtomic } from "../atomic-write.js";
 import { log } from "../log.js";
 /** Path of a JSON file under `<stateRoot>/schedule/`. */
 export function scheduleFile(stateRoot, name) {
@@ -42,10 +40,7 @@ export function readScheduleFile(path) {
     }
 }
 export function writeScheduleFile(path, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp`;
-    writeFileSync(tmp, JSON.stringify(value));
-    renameSync(tmp, path);
+    writeFileAtomic(path, JSON.stringify(value));
 }
 export function loadFires(stateRoot) {
     const v = readScheduleFile(scheduleFile(stateRoot, "fires"));

package/dist/schedule/wakeups.d.ts

@@ -73,7 +73,7 @@ export declare function takeFirstDueWakeup(stateRoot: string, now?: Date): Wakeu
  * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
  *
  * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any harness IO) where an `unwake` for this id reports "not found"
+ * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
  * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
  * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
  */

package/dist/schedule/wakeups.js

@@ -201,7 +201,7 @@ export function takeFirstDueWakeup(stateRoot, now = new Date()) {
  * already advanced the entry, and its next occurrence comes by definition — a busy one is skipped + audited.
  *
  * Known residual: between the claim (removed from the store) and this re-add there is a microtask-scale
- * window (the busy reject yields before any harness IO) where an `unwake` for this id reports "not found"
+ * window (the busy reject yields before any engine IO) where an `unwake` for this id reports "not found"
  * and the defer then resurrects it — the one-shot cousin of the recurring resurrection the advance-in-place
  * claim eliminated. Accepted: closing it needs a claim-lease with expiry, disproportionate to the window.
  */

package/dist/service.d.ts

@@ -0,0 +1,158 @@
+import type { Agent } from "./agent.ts";
+import { type LoadedLongConnectionChannel } from "./channels/discover.ts";
+import type { SessionControl } from "./session.ts";
+import type { ChannelHandler, Routes } from "./channel.ts";
+import { type PrefixMount } from "./channels/serve.ts";
+import type { LoadedSchedule } from "./schedule/schedule.ts";
+export interface ServingSurface {
+    routes: Routes;
+    /** Prefix-owning handlers mounted beside the routes (the session control plane). */
+    mounts?: readonly PrefixMount[];
+    longConnections: LoadedLongConnectionChannel[];
+    /** Route-channel basenames; the tunnel registers only this subset. */
+    routeChannels: string[];
+    builtinInvoke: boolean;
+    /** Marks the built-in health route ready after every long-connection channel first connects. */
+    /** Flip health between 200 and 503. Two-way on purpose: a long connection that dies after coming
+     *  up leaves the surface serving something it no longer has, and a load balancer should hear it. */
+    setReady(value: boolean): void;
+}
+/**
+ * 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 declare function routesFor(agentDir: string, agent: Agent, stateRoot: string, control: SessionControl | undefined, options?: {
+    builtinInvoke?: boolean;
+}): Promise<ServingSurface>;
+/**
+ * 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 declare function assertNoControlPlaneCollision(channelRoutes: Routes, plane: PrefixMount): void;
+export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
+    tunnel?: boolean;
+    agent?: Agent;
+    host?: string;
+}): {
+    routes: Routes;
+    mounts: PrefixMount[];
+    /** The plane's bearer token and prefix — how an embedder distributes access without a discovery file. */
+    control?: {
+        token: string;
+        prefix: string;
+    };
+    /** Write the local discovery file; returns its removal. Installs no signal handlers. */
+    announce: (boundPort: number) => () => void;
+};
+/**
+ * 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 declare function startSchedules(agentDir: string, agent: Agent, stateRoot: string, selfSchedule: boolean, options?: {
+    externalClock?: boolean;
+}): Promise<{
+    schedules: LoadedSchedule[];
+    stop: () => void;
+}>;
+export interface AgentService {
+    /** The assembled Fetch handler: channel routes, the control plane, and health. Mount it wherever
+     *  your host speaks `(Request) => Response`; `nodeListener` bridges it to Node's `(req, res)`. */
+    handler: ChannelHandler;
+    /** The agent behind it — invoke it directly when you also want a programmatic path. */
+    agent: Agent;
+    /** The literal routes `handler` was composed from — for a startup line naming what is served.
+     *  Mounted prefixes are not here: nothing outside the assembly needed them, and a field kept for a
+     *  hypothetical caller is a field nobody maintains. */
+    routes: Routes;
+    agentDir: string;
+    workspace: string;
+    /** What actually mounted, for a startup line: channel files serving routes, long connections, and
+     *  whether the built-in `POST /invoke` fallback is one of the routes. That last one is a FACT of
+     *  the assembly, not something to re-infer from a path — a channel may legally author
+     *  `POST /invoke` with a protocol of its own. */
+    channels: {
+        routes: string[];
+        longConnections: string[];
+        builtinInvoke: boolean;
+    };
+    schedules: readonly LoadedSchedule[];
+    /** Settles when every long connection is up — immediately when there are none. REJECTS if one
+     *  fails to come up, after closing the service: a host must not report itself serving while a
+     *  declared channel is dead, and health answers 503 until this resolves. */
+    ready: Promise<void>;
+    /** The control plane's bearer token and prefix, when `sessionControl` is on — how an embedder
+     *  hands access to a client without a discovery file. */
+    control?: {
+        token: string;
+        prefix: string;
+    };
+    /** Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the plane,
+     *  once the port is known. Optional: an embedder mounted inside a larger app has no port of its
+     *  own to describe and uses {@link AgentService.control} instead.
+     *
+     *  Removed by `close()`. Not by an `exit` handler: installing one is a decision about the whole
+     *  process, which a mounted library does not get to make. A hard exit therefore leaves the file
+     *  behind — advisory, overwritten by the next boot, and the client's own error stays honest. */
+    announce(boundPort: number): void;
+    /** Stop long connections and schedules. Idempotent; also runs when `options.signal` aborts. */
+    close(): Promise<void>;
+}
+/** What {@link mountAgentService} needs beyond an opened directory. */
+export interface MountAgentServiceOptions {
+    /** Wrap the agent before anything consumes it — every consumer (routes, control plane, schedules)
+     *  must get the SAME one, which is why this is a hook rather than the caller's own call. `dev`
+     *  passes `logAgentLoop`. */
+    wrapAgent?: (agent: Agent) => Agent;
+    /** Passed through to the control plane mount: `--tunnel` widens its warning, `host` names the
+     *  bind address in the discovery file. */
+    control?: {
+        tunnel?: boolean;
+        host?: string;
+    };
+    /** Aborting this closes the service, exactly like calling {@link AgentService.close}. */
+    signal?: AbortSignal;
+    /** Called when a long connection ends on its own — a dropped socket-mode channel, say. The CLI
+     *  exits; an embedded host may prefer to log. Default: log an error. */
+    onChannelClosed?: (name: string, error?: unknown) => void;
+    /** How long `close()` waits for a channel to stop before reporting it stuck (default 5s). The CLI
+     *  shortens it so its own forced exit lands after this answer, not before it. */
+    closeTimeoutMs?: number;
+}
+/**
+ * What the assembly needs from an opened agent directory — the whole of it. Spelled as its own type
+ * rather than an engine's return shape: every field here is either the SPEC contract or a path, so
+ * an engine that is not pi can satisfy it without either side knowing about the other.
+ */
+export interface MountableAgent {
+    agent: Agent;
+    /** The definition dir: where channels/, tools/ and schedules/ are read from. */
+    agentDir: string;
+    /** The agent's cwd. */
+    workspace: string;
+    /** Where durable state lives (channel state, sessions, schedule fires). */
+    stateRoot: string;
+    /** Present iff this agent published a control plane. */
+    sessionControl?: SessionControl;
+    /** Whether the agent schedules its own follow-up turns. REQUIRED, not optional-with-a-default:
+     *  an engine that forgot it would turn self-scheduling off silently, which is exactly the bug
+     *  this type was introduced with. */
+    selfSchedule: boolean;
+}
+/**
+ * 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 declare function mountAgentService(opened: MountableAgent, options?: MountAgentServiceOptions): Promise<AgentService>;