@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/cli/commands/info.js

@@ -1,14 +1,14 @@
 /** `fastagent info [dir] [--json]`: print what the directory ASSEMBLES into, WITHOUT booting a server. Read-only. */
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
-import { discoverChannelFiles } from "../../engines/pi/channel.js";
+import { discoverChannelFiles } from "../../channels/discover.js";
 import { defaultSessionsDir, loadConfig, resolveAuthPath, resolveModel, resolveModelSpec, resolveSessionsDirOverride, } from "../../engines/pi/config.js";
 import { createPiModelRuntime } from "../../engines/pi/models.js";
 import { resolveStateRoot, workspaceHint } from "../../paths.js";
-import { resolveAgentTools } from "../../engines/pi/create.js";
+import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
-import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
-import { log } from "../../log.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures, log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { failStartup, placementOrExit } from "../fail.js";
@@ -25,7 +25,7 @@ export async function runInfo(dirArg, opts) {
     // tool), is isolated the same way everywhere (G2): info, dev, AND start report it and keep going with
     // the tools that loaded. The `error`/`.catch` below only fires for a whole-load fault (an unreadable
     // tools/ dir), not a single bad file.
-    const tools = await resolveAgentTools(config, agentDir)
+    const tools = await resolveAgentTools(config, agentDir, workspace)
         .then((r) => ({
         names: r.toolNames,
         deferred: r.deferredToolNames,
@@ -78,6 +78,7 @@ export async function runInfo(dirArg, opts) {
             model: modelSpec ?? null,
             modelError: modelError ?? null,
             thinkingLevel: config.thinkingLevel ?? null,
+            codingTools: [...CODING_TOOL_NAMES],
             context: definition.contextFiles.map((f) => f.path),
             persona: definition.persona !== undefined,
             skills: definition.skills.map((skill) => ({ name: skill.name, description: skill.description })),
@@ -114,6 +115,7 @@ export async function runInfo(dirArg, opts) {
         cont(`⚠ does not resolve: ${modelError}`);
     if (config.thinkingLevel)
         line("thinking", config.thinkingLevel);
+    line("codingTools", CODING_TOOL_NAMES.join(", "));
     line("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     line("persona", definition.persona ? "persona.md" : "(none)");
     line("skills", definition.skills.map((skill) => skill.name).join(", ") || "(none)");

package/dist/cli/commands/init.js

@@ -7,10 +7,9 @@
  */
 import { spawn } from "node:child_process";
 import { basename, join, resolve } from "node:path";
-import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt } from "../../paths.js";
+import { DEFAULT_AGENT_DIRNAME, SECRETS_DIRNAME, agentsAt, displayPath } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
 import { agentDirName, agentDirNameError, scaffoldAgent } from "../../scaffold/init.js";
-import { displayPath } from "../../paths.js";
 import { failStartup, failUsage } from "../fail.js";
 export async function runInit(dirArg, opts) {
     const dir = resolve(dirArg);

package/dist/cli/commands/schedule.js

@@ -6,7 +6,7 @@
 import { resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { resolveStateRoot } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
 import { readRuns } from "../../schedule/audit.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";

package/dist/cli/commands/start.js

@@ -2,26 +2,24 @@
  * `fastagent start [dir]`: run the agent in production posture — the SAME assembly as dev (your
  * directory is the agent), just no file-watching. No build step: start reads the definition directly.
  */
-import { mkdir, writeFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
-import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.js";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
 import { loadDotEnv } from "../../env.js";
 import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
-import { resolveSecretsDir, workspaceHint } from "../../paths.js";
-import { isUnderDir } from "../../engines/pi/definition.js";
-import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
-import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { SECRET_FILE_MODE, ensureSecretsDir, resolveSecretsDir, isUnderDir, exists } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
-import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
-import { setWakeupsSink } from "../../schedule/wakeups.js";
+import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { mountAgentService } from "../../service.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
-import { exists } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
-import { parseRouteKey } from "../../host/node.js";
+import { isAgentcoreRuntime, mountAgentcoreService } from "../../channels/agentcore-service.js";
+import { createWakeAlarmSink } from "../../schedule/wake-alarm.js";
+import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { assertTunnelBindable, maybeTunnel, mountAgentcore, mountSessionControl, routesFor, serve, startSchedules, } from "../serve.js";
-import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
+import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
+import { parseBind, parsePort, reportAssembly, resolveFirstRunModel } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
     // Flag validation first: a bad --port is a USAGE error (exit 2), and reporting it must not depend on
@@ -39,30 +37,16 @@ export async function runStart(dirArg, opts) {
     await maybeSeedAuth(resolveAuthPath(placement.agentDir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
     const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, sessionControl, } = await createPiAgentFromDir(dir, {
-        model: opts.model,
-        sessionsDir: sessionsDirOverride,
-        authPath: opts.authPath,
-        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
-    }).catch(failStartup);
-    reportLine("agent", agentDir);
-    reportLine("workspace", workspace);
-    reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
-    reportLine("model", `${modelSpec}${config.thinkingLevel ? ` (thinking: ${config.thinkingLevel})` : ""}`);
-    await reportAuth(agentDir, modelSpec, authPath);
-    reportLine("context", definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
-    if (definition.persona)
-        reportLine("persona", "persona.md");
-    reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
-    if (toolNames.length > 0)
-        reportLine("tools", toolNames.join(", "));
-    if (deferredToolNames.length > 0) {
-        reportLine("deferred", `${deferredToolNames.join(", ")} (activated via search_tools)`);
-    }
-    reportToolCollisions(toolCollisions);
-    reportModuleLoadFailures(toolFailures);
-    reportLine("state", stateRoot);
-    reportLine("sessions", sessionsDir);
+    const opened = await openStartDir(dir, opts, sessionsDirOverride);
+    const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
+    // The same report `dev` prints; `state:`/`sessions:` are start's own extras, and the persistence
+    // notes below are why (see reportAssembly on the asymmetry).
+    await reportAssembly(opened, {
+        afterTools: [
+            ["state", stateRoot],
+            ["sessions", sessionsDir],
+        ],
+    });
     // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
     // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
     // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
@@ -81,102 +65,52 @@ export async function runStart(dirArg, opts) {
         log.info(`[fastagent] note: secrets (.env, rotated auth.json) live under the definition dir; point ` +
             `FASTAGENT_SECRETS_DIR at a persistent volume so a redeploy that replaces the dir does not wipe them.`);
     }
-    reportFindingsIfChanged(definition.dir, definition);
-    // AgentCore Runtime posture (FASTAGENT_AGENTCORE=1, set by the generated deploy artifacts): the
-    // adapter (POST /invocations + GET /ping) is the container's only reachable surface, and cron
-    // slots arrive from the external clock through it — so no resident cron timers. In particular,
-    // do NOT mount the ordinary unauthenticated POST /invoke fallback: a selfSchedule-only topology
-    // needs a public Function URL for wake callbacks, and its forwarder can relay arbitrary paths.
-    const agentcore = process.env.FASTAGENT_AGENTCORE === "1";
     // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
     const traced = logAgentLoop(agent);
-    // On AgentCore the channels are constructed LAZILY (mountAgentcore's lazyChannels, resolved on the
-    // first envelope after the state-snapshot restore): construction loads channel state and replays
-    // turn intent, and at boot the state mount is PRE-RESTORE — empty after every version update — so
-    // an eager build would cache that emptiness (thread participation, delivery dedup, pending turns)
-    // and then clobber the restored files with it. Everywhere else the state root is durable at boot,
-    // so channels mount eagerly and a broken channel fails startup.
-    const routed = agentcore
-        ? undefined
-        : await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: true }).catch(failStartup);
     // `http.host` enters here the way the flag enters `parseBind` — through `bindAddress`, so a
     // configured `localhost` is an ADDRESS by the time anything binds, renders or dials it.
     const configured = config.http?.host;
     const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
     assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
-    const withControl = mountSessionControl(routed?.routes ?? {}, sessionControl, stateRoot, {
-        tunnel: opts.tunnel ?? false,
-        agent: traced,
-        host,
-    });
-    // AgentCore + selfSchedule: register the wake-ALARM sink BEFORE the scheduler starts — the boot
-    // wake pump may advance a recurring entry (a store save) and that save must already re-arm its
-    // alarm. The secret arrives via the stack (FASTAGENT_WAKE_SECRET); without it the deployment
-    // degrades to awake-only wakes — warned, never silent.
-    let onStateReady;
-    if (agentcore && config.selfSchedule) {
-        const wakeSecret = process.env.FASTAGENT_WAKE_SECRET;
-        if (wakeSecret) {
-            const sink = createWakeAlarmSink({ secret: wakeSecret });
-            setWakeupsSink(sink);
-            // NOT here: at boot the state mount is whatever the platform just provisioned — after a runtime
-            // version update that is EMPTY, so a reconcile now would see no pending wake-ups and conclude
-            // there is nothing to re-arm. It runs once the snapshot has been restored (mountAgentcore).
-            onStateReady = () => reconcileWakeAlarms(stateRoot, sink);
-            log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
-        }
-        else {
-            log.warn(`[fastagent] FASTAGENT_WAKE_SECRET is not set — wake-ups fire only while a session is awake ` +
-                `(redeploy with the current template to fix)`);
-        }
-    }
-    const schedules = await startSchedules(agentDir, traced, stateRoot, config.selfSchedule ?? false, {
-        externalClock: agentcore,
-    });
-    let routes = withControl.routes;
-    if (agentcore) {
-        // The lazy channel surface the adapter resolves post-restore. Control routes ride along so a
-        // forwarder-relayed /control/* request dispatches the same as on a direct host. Long-connection
-        // channels cannot serve here — scale-to-zero severs a resident connection and nothing
-        // re-establishes it — so their presence is a configuration error, surfaced per envelope and by
-        // the deploy driver's health probe (there is no boot to fail on this host).
-        const lazyChannels = async () => {
-            const surface = await routesFor(agentDir, traced, stateRoot, sessionControl, { builtinInvoke: false });
-            if (surface.longConnections.length > 0) {
-                throw new Error(`long-connection channel(s) ${surface.longConnections.map((c) => c.name).join(", ")} cannot serve on ` +
-                    `AgentCore (scale-to-zero severs resident connections) — use the channel's webhook form`);
-            }
-            // mountSessionControl's PATH-level collision rule, re-asserted here: with no channels at boot
-            // its own check ran against an empty base, and a spread merge would silently let control win —
-            // but a channel on /control/* is the same configuration error it is on every other host.
-            const controlPaths = new Set(Object.keys(withControl.routes).map((key) => parseRouteKey(key).path));
-            const collisions = Object.keys(surface.routes).filter((key) => controlPaths.has(parseRouteKey(key).path));
-            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`);
-            }
-            return { ...surface.routes, ...withControl.routes };
-        };
-        try {
-            routes = mountAgentcore(routes, { agent: traced, stateRoot, schedules, onStateReady, lazyChannels });
-        }
-        catch (e) {
-            failStartup(e);
-        }
-        log.info(`[fastagent] agentcore: serving POST /invocations + GET /ping (FASTAGENT_AGENTCORE=1)`);
-    }
-    serve({
-        ...(routed ?? { longConnections: [], routeChannels: [], builtinInvoke: false, markReady() { } }),
-        routes,
-    }, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, (p) => {
-        withControl.announce(p);
-        maybeTunnel(agentDir, routed?.routeChannels ?? [], p, opts.tunnel ?? false, stateRoot);
+    const control = { tunnel: opts.tunnel ?? false, ...(host !== undefined ? { host } : {}) };
+    // ONE branch for the whole posture. AgentCore assembles differently — lazy channels over a
+    // pre-restore state mount, an external clock, no resident connections — but it yields the same
+    // AgentService, so everything below this point is common.
+    // The wake-alarm sink is a PROCESS-global (schedule/wakeups.ts) — this process IS the AgentCore
+    // deployment, so the process entry installs it. A service can be closed; a global cannot be
+    // handed to something that can, without inventing an ownership the singleton does not have.
+    const onStateReady = isAgentcoreRuntime() && config.selfSchedule ? armWakeAlarms(stateRoot) : undefined;
+    const service = await (isAgentcoreRuntime()
+        ? mountAgentcoreService(opened, { wrapAgent: () => traced, control, onStateReady })
+        : mountAgentService(opened, {
+            wrapAgent: () => traced,
+            closeTimeoutMs: SHUTDOWN_GRACE_MS,
+            control,
+            onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
+        })).catch(failStartup);
+    serve(service.handler, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, {
+        ready: service.ready,
+        onListening: (p) => {
+            reportServing(service, host, p);
+            service.announce(p);
+            maybeTunnel(agentDir, service.channels.routes, p, opts.tunnel ?? false, stateRoot);
+        },
+        onShutdown: () => service.close(),
     });
     // No graceful drain: webhook turns run fire-and-forget; SIGTERM just exits mid-turn. Whether an
     // in-flight turn is LOST depends on the channel: the Telegram channel persists turn intent pre-ACK
     // and replays it next start (turn-store.ts, L1 durable execution, at-least-once); HTTP and other
     // channels have no such layer, so their in-flight turns are still lost (the asker re-invokes).
 }
+/** The opener, kept as its own call so `opened` can also feed the shared assembly below. */
+function openStartDir(dir, opts, sessionsDir) {
+    return createPiAgentFromDir(dir, {
+        model: opts.model,
+        sessionsDir,
+        authPath: opts.authPath,
+        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
+    }).catch(failStartup);
+}
 /**
  * Materialize `FASTAGENT_AUTH_SEED` (base64 of an auth.json, set by `deploy --run`) into the
  * writable secrets dir ONCE — only when the seed is set AND the auth file is absent, so a refreshed
@@ -189,7 +123,32 @@ async function maybeSeedAuth(authPath) {
     const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
-    await mkdir(dirname(authPath), { recursive: true });
-    await writeFile(authPath, bytes);
+    await ensureSecretsDir(dirname(authPath));
+    // Same spelling as the credential store: the mode is applied before the content is reachable, so
+    // the seed can never be published at some other file's looser permissions. It does NOT close the
+    // gap between the `exists` check and the write — the rename would overwrite a file created in
+    // between, against this function's absent-only promise. That window needs two `start` processes on
+    // one secrets dir, which no supported deployment runs (one container, one volume).
+    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE);
     log.info(`[fastagent] seeded ${authPath} from FASTAGENT_AUTH_SEED (first boot)`);
 }
+/**
+ * Install the wake-ALARM sink before the scheduler starts — the boot wake pump may advance a
+ * recurring entry, and that save must already re-arm its alarm. Returns the post-restore reconcile:
+ * running it at boot would read the pre-restore state mount, see no pending wake-ups, and conclude
+ * there is nothing to re-arm.
+ */
+function armWakeAlarms(stateRoot) {
+    const secret = process.env.FASTAGENT_WAKE_SECRET;
+    if (!secret) {
+        log.warn(`[fastagent] FASTAGENT_WAKE_SECRET is not set — wake-ups fire only while a session is awake ` +
+            `(redeploy with the current template to fix)`);
+        return undefined;
+    }
+    const sink = createWakeAlarmSink({ secret });
+    setWakeupsSink(sink);
+    log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
+    // Boot reconcile: pending wake-ups may exist while their alarms were lost (a deploy replaced the
+    // forwarder, a sink call failed). The sink re-reads the store, so a bare notification is enough.
+    return () => sink(stateRoot);
+}

package/dist/cli/commands/tool.js

@@ -4,7 +4,7 @@ import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { loadDotEnv } from "../../env.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
-import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
 import { turnContext } from "../../engines/pi/tool-context.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
@@ -14,10 +14,10 @@ export async function runTool(name, argsJson, dirArg) {
     const { agentDir, workspace } = placementOrExit(resolve(dirArg));
     loadDotEnv(agentDir); // a tool may read a key from .env
     const { config } = await loadConfig(agentDir).catch(failStartup);
-    // The same tool set dev/start mount (defaults + config.tools + discovered, deduped), so the runner
+    // The same tool set dev/start mount (all coding tools + config.tools + discovered, deduped), so the runner
     // exercises exactly what gets served — a shadowed tool is surfaced, not silently run. Resolve the
     // placement like the openers, so `fastagent tool` finds the SAME tools/ as dev/start.
-    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir).catch(failStartup);
+    const { tools, toolCollisions, toolFailures } = await resolveAgentTools(config, agentDir, workspace).catch(failStartup);
     for (const c of toolCollisions) {
         console.error(`[fastagent] warn: tool "${c.name}" (${c.source}) is shadowed by a default/config tool — not mounted`);
     }
@@ -26,10 +26,8 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    // Two contexts, because the two tool families read different ones and this command must serve both
-    // exactly as serving does: fastagent's own tools take cwd/session/activation from `turnContext`
-    // (AsyncLocalStorage), and pi's default coding tools take the ExecutionEnv from the harness's TOOL
-    // context — which no harness supplies here, so this stands in for it, rooted at the same workspace.
+    // Authored tools read cwd from turnContext; coding tools are already rooted at the workspace. Keep
+    // the fifth-argument env for lower-level MountedTools that explicitly consume it.
     const env = new NodeExecutionEnv({ cwd: workspace });
     const result = await turnContext
         .run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args, undefined, undefined, { env }))

package/dist/cli/program.js

@@ -171,7 +171,7 @@ const tool = {
         DIR_ARG,
     ],
     examples: [{ cmd: `fastagent tool add '{"a":2,"b":3}'` }],
-    notes: "Mounts the same tool set dev/start serve (defaults + config.tools + discovered tools/, " +
+    notes: "Mounts the same tool set dev/start serve (all coding tools + config.tools + discovered tools/, " +
         "deduped), so a shadowed or broken tool is surfaced here exactly as it would be when serving.",
     run: async (args) => (await import("./commands/tool.js")).runTool(args[0], args[1], args[2]),
 };

package/dist/cli/serve.d.ts

@@ -1,59 +1,5 @@
-import type { Agent } from "../agent.ts";
-import { type LoadedLongConnectionChannel } from "../engines/pi/channel.ts";
-import { type Routes } from "../host/node.ts";
-import type { LoadedSchedule } from "../schedule/schedule.ts";
-import type { SessionControl } from "../session.ts";
-export interface ServingSurface {
-    routes: Routes;
-    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. */
-    markReady(): 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, options?: {
-    builtinInvoke?: boolean;
-}): Promise<ServingSurface>;
-/**
- * Mount the session control plane (`/control/*`) when the agent enabled it
- * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
- * writes `<stateRoot>/control.json` — `{ url, token }`, 0600 — once the port is known. The file is
- * the LOCAL discovery channel (`fastagent attach`, a local desktop app); filesystem permissions are
- * its trust boundary, and each boot overwrites it with a fresh per-boot token. A user channel
- * colliding on `/control/*` fails startup — the same disposition as a channel-channel collision
- * (routesFor): `sessionControl` is an explicit opt-in, so declaring both is a configuration error,
- * and silently shadowing either side would serve a surface the author didn't write.
- */
-export declare function mountSessionControl(routes: Routes, control: SessionControl | undefined, stateRoot: string, options?: {
-    tunnel?: boolean;
-    agent?: Agent;
-    host?: string;
-}): {
-    routes: Routes;
-    announce: (boundPort: number) => void;
-};
-/**
- * Mount the AgentCore Runtime adapter (`POST /invocations` + `GET /ping`) over the serving routes —
- * the deployed container's ONLY reachable surface (channels/agentcore.ts). Wired by `start` when
- * `FASTAGENT_AGENTCORE=1` (set by the generated deploy artifacts, never by hand). A channel colliding
- * on either path fails startup, same disposition as the control-plane mount: the adapter's paths are
- * the platform's contract, so a channel shadowing them would silently unserve the whole deployment.
- */
-export declare function mountAgentcore(routes: Routes, options: {
-    agent: Agent;
-    stateRoot: string;
-    schedules: LoadedSchedule[];
-    onStateReady?: () => void;
-    /** The serving path's LAZY channel surface: constructed by the adapter on the first envelope
-     *  AFTER the state-snapshot restore, never at boot (channels/agentcore.ts). When absent,
-     *  `routes` is the dispatch target — for wirings whose state root is already authoritative. */
-    lazyChannels?: () => Promise<Routes>;
-}): Routes;
+import type { ChannelHandler } from "../channel.ts";
+import type { AgentService } from "../service.ts";
 /**
  * Refuse `--tunnel` with a bind that cloudflared cannot reach: it dials the NAME `localhost:<port>`
  * (the dev supervisor's tunnel too), so anything outside `127.0.0.1`/`::1`/wildcard — including a
@@ -64,6 +10,12 @@ export declare function mountAgentcore(routes: Routes, options: {
  * came from config is broken runtime configuration (1).
  */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The "we are serving" report: the supervisor message `dev`'s watcher waits for, the addresses, and
+ * what mounted. One function because both commands must say the same thing at the same moment —
+ * after readiness, never at socket bind.
+ */
+export declare function reportServing(service: AgentService, host: string | undefined, boundPort: number): void;
 /**
  * The startup lines that name WHERE the serve is: the bind report, and the curl the reader copies.
  * ONE function because they are one message — they were two, and `--bind` updated the first while the
@@ -74,23 +26,23 @@ export declare function assertTunnelBindable(host: string | undefined, tunnel: b
  * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
  */
 export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
+/** What the CLI gives a service to stop in, and the hard exit that follows it. The order matters:
+ *  a forced exit before the service answers would report a clean shutdown over a stuck channel. */
+export declare const SHUTDOWN_GRACE_MS = 800;
 /**
- * Bind HTTP, open long-connection channels, and report ready only when both forms are usable. Each
- * adapter owns reconnects; a terminal close rejects `closed` and fails the process visibly. Abort is
- * the sole clean-shutdown command. `host` unset binds all interfaces.
+ * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
+ * socket is not a serving agent while a declared long-connection channel is still dialling, so this
+ * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
+ * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
  */
-export declare function serve(surface: ServingSurface, bind: {
+export declare function serve(handler: ChannelHandler, bind: {
     port: number;
     host?: string;
-}, onListening?: (boundPort: number) => void): void;
+}, hooks?: {
+    /** Awaited before anything is reported ready — see the listening handler. */
+    ready?: Promise<void>;
+    onListening?: (boundPort: number) => void;
+    onShutdown?: () => Promise<void> | void;
+}): void;
 /** Start a Cloudflare tunnel for route channels only. */
 export declare function maybeTunnel(agentDir: string, routeChannels: string[], boundPort: number, tunnel: boolean, stateRoot?: string): 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<LoadedSchedule[]>;