@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/paths.js

@@ -330,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,19 +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 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, type SessionInheritance, } 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 { 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/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>;

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,
+    };
+}