@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/channels/telegram/turn-store.d.ts

@@ -1,10 +1,10 @@
 /**
  * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
  * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
  * turn execution ceiling, the fail-closed attempt bump).
  */
-import { type TurnStore } from "../turn-store.ts";
+import { type TurnStore } from "../kit/turn-store.ts";
 /** An accepted turn's persisted intent — the SOURCE for the fields a runner needs to re-execute it
  *  (telegram.ts's PendingTurn derives from this, so a new execution field added here propagates and
  *  cannot silently drop from the persisted record). Minus the live `previewId` (a restart's queue

package/dist/channels/telegram/turn-store.js

@@ -1,10 +1,10 @@
 /**
  * The telegram-shaped turn store: the channel's persisted record (what its runner needs to re-execute a
  * turn), its IO-boundary shape validator, and its arrival ordering, over the generic L1 turn store
- * (../turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
+ * (../kit/turn-store.ts — the semantics live there: pre-ACK persist, replay on the next start, the poison-
  * turn execution ceiling, the fail-closed attempt bump).
  */
-import { createTurnStore as createGenericTurnStore } from "../turn-store.js";
+import { createTurnStore as createGenericTurnStore } from "../kit/turn-store.js";
 /** State files are an IO boundary: valid JSON of the WRONG SHAPE must degrade like a corrupt file
  *  (warn + empty), not flow in as trusted data (mirrors context-buffer's isBufferEntry). */
 function isStoredTurn(t) {

package/dist/cli/commands/add.js

@@ -11,7 +11,7 @@ import { dotEnvPath, loadDotEnv } from "../../env.js";
 import { resolveStateRoot } from "../../paths.js";
 import { SECRETS_DIRNAME } from "../../paths.js";
 import { detectRuntime, readPackageJson } from "../../runtime.js";
-import { isUnderDir } from "../../engines/pi/definition.js";
+import { isUnderDir } from "../../paths.js";
 import { displayPath } from "../../paths.js";
 import { appendChannelDotEnv, appendChannelEnv, assertChannelReady, channelExists, channelSetup, scaffoldChannel, } from "../../scaffold/add-channel.js";
 import { exists } from "../../paths.js";

package/dist/cli/commands/dev.js

@@ -6,15 +6,18 @@
 import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
 import { loadDotEnv } from "../../env.js";
-import { reportFindingsIfChanged, reportModuleLoadFailures, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
+import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { mountAgentService } from "../../service.js";
 import { setLogLevel } from "../../log.js";
 import { logAgentLoop } from "../../observe.js";
 import { installProxyFetch } from "../../proxy.js";
 import { workspaceHint } from "../../paths.js";
 import { bindAddress } from "../../bind.js";
 import { failStartup, placementOrExit } from "../fail.js";
-import { assertTunnelBindable, maybeTunnel, mountSessionControl, routesFor, serve, startSchedules } from "../serve.js";
+import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
 import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runDev(dirArg, opts) {
     const dir = resolve(dirArg);
@@ -60,22 +63,30 @@ async function serveOnce(dir, opts) {
     reportAgentsSkillsTools(a);
     // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev, gated
     // out in start (level info), keeping end-user content out of production logs. Wired in both postures.
-    const traced = logAgentLoop(a.agent);
-    const routed = await routesFor(a.agentDir, traced, a.stateRoot, a.sessionControl).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 = a.config.http?.host;
     const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
     assertTunnelBindable(host, opts.tunnel ?? false, bindFlag ? "flag" : "config");
-    const withControl = mountSessionControl(routed.routes, a.sessionControl, a.stateRoot, {
-        tunnel: opts.tunnel ?? false,
-        agent: traced, // the remote data plane (POST /control/invoke) drives the SAME traced agent
-        host,
-    });
-    await startSchedules(a.agentDir, traced, a.stateRoot, a.config.selfSchedule ?? false);
-    serve({ ...routed, routes: withControl.routes }, { port: portFlag ?? a.config.http?.port ?? 8787, host }, (p) => {
-        withControl.announce(p);
-        maybeTunnel(a.agentDir, routed.routeChannels, p, opts.tunnel ?? false, a.stateRoot);
+    // The SAME assembly an embedder gets from `createAgentService` — channels, control plane,
+    // schedules, long connections. `dev` opens the directory itself only because its startup report
+    // prints the opened values before anything mounts.
+    const service = await mountAgentService(a, {
+        // Trace each turn's agent loop (tool calls + reply) to the log at debug level — shown in dev,
+        // gated out in start (level info), keeping end-user content out of production logs.
+        wrapAgent: logAgentLoop,
+        closeTimeoutMs: SHUTDOWN_GRACE_MS,
+        control: { tunnel: opts.tunnel ?? false, ...(host !== undefined ? { host } : {}) },
+        onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
+    }).catch(failStartup);
+    serve(service.handler, { port: portFlag ?? a.config.http?.port ?? 8787, host }, {
+        ready: service.ready,
+        onListening: (p) => {
+            reportServing(service, host, p);
+            service.announce(p);
+            maybeTunnel(a.agentDir, service.channels.routes, p, opts.tunnel ?? false, a.stateRoot);
+        },
+        onShutdown: () => service.close(),
     });
 }
 /** The agents/skills/tools/collisions report lines. */
@@ -84,6 +95,7 @@ function reportAgentsSkillsTools(a) {
     if (a.definition.persona)
         reportLine("persona", "persona.md");
     reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
+    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
     if (a.toolNames.length > 0)
         reportLine("tools", a.toolNames.join(", "));
     if (a.deferredToolNames.length > 0) {

package/dist/cli/commands/fire.js

@@ -7,7 +7,7 @@
 import { join, resolve } from "node:path";
 import { loadDotEnv } from "../../env.js";
 import { displayPath } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
 import { installProxyFetch } from "../../proxy.js";

package/dist/cli/commands/info.js

@@ -1,13 +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 { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
 import { log } from "../../log.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
@@ -25,7 +26,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 +79,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 +116,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/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

@@ -8,19 +8,22 @@ import { authSeedBytes, collectAuthSeed } from "../../deploy/fly/run.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 { isUnderDir } from "../../paths.js";
+import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
+import { reportModuleLoadFailures } from "../../log.js";
+import { CODING_TOOL_NAMES } from "../../engines/pi/create.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
+import { mountAgentService } from "../../service.js";
 import { log, setLogLevel } from "../../log.js";
-import { createWakeAlarmSink, reconcileWakeAlarms } from "../../schedule/wake-alarm.js";
-import { setWakeupsSink } from "../../schedule/wakeups.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, reconcileWakeAlarms } 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 { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
 import { parseBind, parsePort, reportAuth, reportLine, resolveFirstRunModel, reportWorkspaceHint } from "../shared.js";
 export async function runStart(dirArg, opts) {
     const dir = resolve(dirArg);
@@ -39,12 +42,8 @@ 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);
+    const opened = await openStartDir(dir, opts, sessionsDirOverride);
+    const { agent, definition, agentDir, workspace, config, modelSpec, stateRoot, sessionsDir, authPath, toolNames, deferredToolNames, toolCollisions, toolFailures, } = opened;
     reportLine("agent", agentDir);
     reportLine("workspace", workspace);
     reportWorkspaceHint(workspaceHint({ agentDir, workspace }));
@@ -54,6 +53,7 @@ export async function runStart(dirArg, opts) {
     if (definition.persona)
         reportLine("persona", "persona.md");
     reportLine("skills", definition.skills.map((s) => s.name).join(", ") || "(none)");
+    reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
     if (toolNames.length > 0)
         reportLine("tools", toolNames.join(", "));
     if (deferredToolNames.length > 0) {
@@ -82,95 +82,37 @@ export async function runStart(dirArg, opts) {
             `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
@@ -183,6 +125,15 @@ export async function runStart(dirArg, opts) {
  * volume copy is never clobbered by the stale seed. Lets a deploy carry the operator's local
  * OAuth/API credential so the box runs on the SAME subscription. No-op locally (the seed is unset).
  */
+/** 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);
+}
 async function maybeSeedAuth(authPath) {
     // collectAuthSeed: the seed may arrive CHUNKED (FASTAGENT_AUTH_SEED + _2…) on hosts with a small
     // env-value max length (AgentCore); single-var hosts are unchanged.
@@ -193,3 +144,21 @@ async function maybeSeedAuth(authPath) {
     await writeFile(authPath, bytes);
     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`);
+    return () => reconcileWakeAlarms(stateRoot, sink);
+}

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,24 +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>;
+import type { ChannelHandler } from "../channel.ts";
+import type { AgentService } from "../service.ts";
 /**
  * Mount the session control plane (`/control/*`) when the agent enabled it
  * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
@@ -29,31 +10,6 @@ export declare function routesFor(agentDir: string, agent: Agent, stateRoot: str
  * (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;
 /**
  * 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
@@ -73,24 +29,29 @@ export declare function assertTunnelBindable(host: string | undefined, tunnel: b
  * A wildcard bind is every interface, and naming one address there would understate it — but the curl
  * still needs one to dial, which is what `clientHost` gives (loopback for a wildcard, itself otherwise).
  */
+/**
+ * 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;
 export declare function readyAddressLines(host: string | undefined, boundPort: number, builtinInvoke: boolean): string[];
 /**
  * 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.
  */
-export declare function serve(surface: ServingSurface, bind: {
+/** 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;
+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[]>;