@fastagent-sh/fastagent 0.18.0 → 0.19.0

package/dist/cli/serve.js

@@ -1,61 +1,17 @@
 /**
- * The serving spine shared by `dev` (its worker) and `start`: channel assembly, Node HTTP binding,
- * long-connection lifecycle, scheduler lifecycle, and the optional Cloudflare quick tunnel.
+ * What `dev` (its worker) and `start` need beyond the service itself: binding a port, the shutdown
+ * order, the startup report, and the optional Cloudflare quick tunnel.
+ *
+ * The ASSEMBLY is not here — it lives in `src/service.ts`, which a public entry may import and this
+ * directory may not be (it decides process-level things: `fail.ts` calls `process.exit`).
  */
-import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { createStateSync } from "../channels/agentcore-state.js";
-import { agentcoreRoutes, UnknownScheduleError } from "../channels/agentcore.js";
-import { activeWork } from "../channels/busy.js";
-import { controlRoutes } from "../channels/control.js";
-import { INVOKE_EXAMPLE_BODY, createInvokeHandler } from "../channels/http.js";
-import { text } from "../channels/respond.js";
-import { loadChannels } from "../engines/pi/channel.js";
-import { reportModuleLoadFailures } from "../engines/pi/report.js";
+import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
 import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
-import { parseRouteKey, router, serveNode } from "../host/node.js";
+import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
-import { loadSchedules } from "../schedule/discover.js";
-import { createScheduler, fireScheduleOnce } from "../schedule/scheduler.js";
 import { announceWebhooks, startCloudflareTunnel } from "../tunnel.js";
 import { failStartup, failUsage } from "./fail.js";
-/**
- * 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,
-        markReady() {
-            ready = true;
-        },
-    };
-}
 /**
  * Mount the session control plane (`/control/*`) when the agent enabled it
  * (`config.sessionControl`): merge the bearer-authenticated routes and return an announcer that
@@ -66,123 +22,6 @@ export async function routesFor(agentDir, agent, stateRoot, control, options = {
  * (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 function mountSessionControl(routes, control, stateRoot, options = {}) {
-    if (!control)
-        return { routes, announce: () => { } };
-    const token = crypto.randomUUID();
-    const mounted = controlRoutes(control, { token, agent: options.agent });
-    // PATH-level collision, matching the router's semantics (an any-method "/control/dispatch"
-    // channel key would dodge an exact-key check yet still shadow the method-qualified control
-    // route at match time — the router matches by path first).
-    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
-    const collisions = Object.keys(routes).filter((key) => mountedPaths.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 {
-        routes: { ...routes, ...mounted },
-        announce: (boundPort) => {
-            // The state root normally exists (the opener mkdirs the sessions dir under it), but an
-            // external --sessions-dir leaves it uncreated — and announce runs inside serve's listening
-            // callback, where a throw is an unhandled rejection, not a one-line startup diagnostic.
-            mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
-            const path = join(stateRoot, "control.json");
-            // Atomic (tmp+rename, the state.ts pattern): attach re-reads this file exactly during the
-            // restart window — a torn read would be misdiagnosed as "serve gone".
-            const tmp = `${path}.tmp`;
-            writeFileSync(tmp, `${JSON.stringify({ url: `http://${clientHost(options.host)}:${boundPort}`, token })}\n`, {
-                mode: 0o600,
-            });
-            chmodSync(tmp, 0o600); // an existing file keeps its old mode on rewrite — pin it
-            renameSync(tmp, path);
-            log.info(`[fastagent] session control on /control/* (token in ${path})`);
-            // The serve binds ALL interfaces by DEFAULT (containers require it), so /control/* is
-            // 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
-                // (beyond even the LAN reach the mount already warned about). The operator asked for the tunnel (webhooks), but must not DISCOVER the control
-                // plane went public with it — say it loudly.
-                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)");
-            }
-            // Best-effort lifecycle end: a clean exit removes the discovery file so a later `attach`
-            // fails with "cannot read" (accurate) instead of a stale token's misleading 401/ECONNREFUSED.
-            const unlink = () => {
-                try {
-                    rmSync(path, { force: true });
-                }
-                catch {
-                    /* the file is advisory — exit must not fail on it */
-                }
-            };
-            // Signal handlers MUST NOT absorb termination: registering any listener disables Node's
-            // default kill, so clean up and RE-RAISE. The mechanism: `process.kill` delivery is ASYNC —
-            // it lands after the current emit completes, so every listener of this same emit (scheduler
-            // stop, tunnel close — regardless of registration order) runs first, and the re-raised
-            // signal then hits the default action because each `once` handler is already consumed. When
-            // some listener exits the process itself (the tunnel path calls process.exit(0)), the
-            // re-raise is harmless redundancy. Without this, the first Ctrl+C would leave the serve
-            // alive minus its control.json, and dev's watch restart (SIGTERM → wait for exit → respawn)
-            // would hang on a worker that never exits.
-            const unlinkAndReraise = (signal) => () => {
-                unlink();
-                process.kill(process.pid, signal);
-            };
-            process.once("SIGINT", unlinkAndReraise("SIGINT"));
-            process.once("SIGTERM", unlinkAndReraise("SIGTERM"));
-            process.once("exit", unlink);
-        },
-    };
-}
-/**
- * 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 function mountAgentcore(routes, options) {
-    const { agent, stateRoot, schedules, onStateReady, lazyChannels } = options;
-    const mounted = agentcoreRoutes({
-        routes: lazyChannels ?? routes,
-        agent,
-        stateRoot,
-        isBusy: () => activeWork() > 0,
-        // Cross-deploy durability: AgentCore wipes the state mount on every runtime version update, so
-        // the state root is restored from (and pushed to) an S3 snapshot through presigned URLs the
-        // forwarder mints per envelope. Always wired on this path — the platform gives no other way to
-        // keep an agent's memory across a deploy.
-        stateSync: createStateSync({ stateRoot }),
-        // What separates a forwarder envelope from any IAM principal's InvokeAgentRuntime call. Absent =
-        // no forwarder in this topology, so only the public `invoke` kind is servable.
-        ingressSecret: process.env.FASTAGENT_INGRESS_SECRET,
-        onStateReady,
-        fire: schedules.length === 0
-            ? undefined
-            : (name, slot) => {
-                const schedule = schedules.find((s) => s.name === name);
-                if (!schedule)
-                    throw new UnknownScheduleError(name);
-                return fireScheduleOnce({ agent, stateRoot, schedule, slot });
-            },
-    });
-    const mountedPaths = new Set(Object.keys(mounted).map((key) => parseRouteKey(key).path));
-    const collisions = Object.keys(routes).filter((key) => mountedPaths.has(parseRouteKey(key).path));
-    if (collisions.length > 0) {
-        throw new Error(`channel route(s) ${collisions.map((key) => `"${key}"`).join(", ")} collide with the AgentCore adapter ` +
-            `(/invocations, /ping) — rename the channel route`);
-    }
-    return { ...routes, ...mounted };
-}
 /**
  * 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
@@ -214,6 +53,20 @@ export function assertTunnelBindable(host, tunnel, source) {
  * 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 function reportServing(service, host, boundPort) {
+    process.send?.({ type: "ready", port: boundPort, routeChannels: service.channels.routes });
+    for (const line of readyAddressLines(host, boundPort, service.channels.builtinInvoke))
+        log.info(line);
+    log.info(`[fastagent] routes: ${Object.keys(service.routes).join(", ") || "(none)"}`);
+    if (service.channels.longConnections.length > 0) {
+        log.info(`[fastagent] long connections: ${service.channels.longConnections.join(", ")}`);
+    }
+}
 export function readyAddressLines(host, boundPort, builtinInvoke) {
     const dial = `${clientHost(host)}:${boundPort}`;
     const lines = [
@@ -229,76 +82,58 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
  * 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 function serve(surface, bind, onListening) {
+/** 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 const SHUTDOWN_GRACE_MS = 800;
+const FORCED_EXIT_MS = 1_500;
+export function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
-    const hosted = serveNode(router(surface.routes), { port, host });
-    const abort = new AbortController();
+    const hosted = serveNode(handler, { port, host });
     let stopping = false;
     const stop = (exitCode) => {
         if (stopping)
             return;
         stopping = true;
-        abort.abort();
-        const deadline = setTimeout(() => process.exit(exitCode), 1_000);
-        void hosted
-            .close()
-            .catch(() => { })
-            .finally(() => {
+        // Bounded: shutdown must not hang on a channel that will not close, so the deadline fires
+        // regardless. No drain — an in-flight turn is cut, which is the existing contract.
+        // Later than the service's own close deadline (SHUTDOWN_GRACE_MS below), or the process leaves
+        // at 0 before `close()` has said a channel would not stop.
+        const deadline = setTimeout(() => {
+            log.error(`[fastagent] shutdown did not finish within ${FORCED_EXIT_MS}ms; exiting`);
+            process.exit(1);
+        }, FORCED_EXIT_MS);
+        // Stop accepting FIRST, before anything is awaited. `onShutdown` waits for long connections to
+        // close, and a socket still listening through that wait would dispatch new work into channels
+        // and a scheduler that are already shutting down.
+        const closingServer = hosted.close();
+        hosted.closeAllConnections();
+        // A cleanup that failed is not a clean exit: `close()` reports a channel that would not stop,
+        // and swallowing it here would end the process at 0 over a resource still holding on.
+        void Promise.allSettled([closingServer, Promise.resolve(hooks.onShutdown?.())]).then((outcomes) => {
+            let code = exitCode;
+            for (const outcome of outcomes) {
+                if (outcome.status === "rejected") {
+                    log.error(`[fastagent] shutdown failed: ${String(outcome.reason)}`);
+                    code = 1;
+                }
+            }
             clearTimeout(deadline);
-            process.exit(exitCode);
+            process.exit(code);
         });
-        // Preserve the existing no-drain shutdown contract: stop accepting first, then cut active streams.
-        hosted.closeAllConnections();
     };
     process.once("SIGINT", () => stop(0));
     process.once("SIGTERM", () => stop(0));
     hosted.listening.then(async (boundPort) => {
         try {
-            const runs = surface.longConnections.map((connection) => {
-                const run = connection.connect(abort.signal);
-                if (run === null ||
-                    typeof run !== "object" ||
-                    typeof run.ready?.then !== "function" ||
-                    typeof run.closed?.then !== "function") {
-                    throw new Error(`${connection.name} connect(signal) must return { ready: Promise, closed: Promise }`);
-                }
-                void run.closed.then(() => {
-                    if (!abort.signal.aborted)
-                        failStartup(new Error(`${connection.name} closed unexpectedly`));
-                }, (error) => {
-                    if (!abort.signal.aborted)
-                        failStartup(new Error(`${connection.name} failed: ${String(error)}`));
-                });
-                return { connection, run };
-            });
-            await Promise.all(runs.map(async ({ connection, run }) => {
-                await run.ready;
-                if (!abort.signal.aborted)
-                    log.info(`[fastagent] long connection ready: ${connection.name}`);
-            }));
-            // Shutdown raced startup: a pre-ready abort settles `ready` as cancellation, not readiness —
-            // stop() already owns the exit; don't mark ready or report a surface being torn down.
-            if (abort.signal.aborted)
+            // A bound socket is NOT a serving agent: a declared socket-mode channel still has to come
+            // up, and reporting ready before it does tells the supervisor (and --tunnel, and the
+            // operator) that a surface is live while a channel is dead.
+            await hooks.ready;
+            if (stopping)
                 return;
-            surface.markReady();
-            process.send?.({
-                type: "ready",
-                port: boundPort,
-                routeChannels: surface.routeChannels,
-            });
-            for (const line of readyAddressLines(host, boundPort, surface.builtinInvoke))
-                log.info(line);
-            log.info(`[fastagent] routes: ${Object.keys(surface.routes).join(", ") || "(none)"}`);
-            if (surface.longConnections.length > 0) {
-                log.info(`[fastagent] long connections: ${surface.longConnections.map((connection) => connection.name).join(", ")}`);
-            }
-            onListening?.(boundPort);
+            hooks.onListening?.(boundPort);
         }
         catch (error) {
-            abort.abort();
-            const closing = hosted.close().catch(() => { });
-            hosted.closeAllConnections();
-            await closing;
             failStartup(error);
         }
     }, (error) => {
@@ -326,24 +161,3 @@ export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoo
         process.once("SIGTERM", cleanup);
     });
 }
-/**
- * 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 = {}) {
-    const { schedules, failures } = await loadSchedules(agentDir).catch(failStartup);
-    reportModuleLoadFailures(failures);
-    if (schedules.length === 0 && !selfSchedule)
-        return schedules;
-    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)" : ""}`);
-    }
-    const stop = () => scheduler.stop();
-    process.once("SIGINT", stop);
-    process.once("SIGTERM", stop);
-    return schedules;
-}

package/dist/cli/shared.d.ts

@@ -2,7 +2,7 @@ import { type LoginIO, type LoginMethod, type LoginResult } from "../engines/pi/
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
  * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
  */

package/dist/cli/shared.js

@@ -19,12 +19,12 @@ import { failStartup, failUsage } from "./fail.js";
 /**
  * The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). Hand-spaced
  * labels drift out of alignment the moment a longer one appears — which is exactly what happened when
- * `workspace:` joined `config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
+ * `codingTools:` joined `workspace:`/`config:`/`model:`/`state:`. `info` keeps its own writer on purpose: its report is
  * stdout DATA (pipeable, its own label set, its own width), not a log line — the shared thing is the
  * policy (pad, never hand-space), not a constant.
  */
 export function reportLine(label, value) {
-    log.info(`[fastagent] ${`${label}:`.padEnd(11)}${value}`);
+    log.info(`[fastagent] ${`${label}:`.padEnd(13)}${value}`);
 }
 /** The workspace hint under the `agent:`/`workspace:` pair, when there is one ({@link workspaceHint}):
  *  you pointed at the agent, and the project around it is probably what you meant. A hint, so it renders

package/dist/core.d.ts

@@ -1,12 +1,10 @@
 export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
-export { createInvokeHandler, nodeListener } from "./channels/http.ts";
-export { controlRoutes, type ControlRoutesOptions, type WireEvent } from "./channels/control.ts";
+export { createInvokeHandler } from "./channels/http.ts";
+export type { WireEvent } from "./channels/control.ts";
 export { ControlRequestError, connectAgent, connectSessionControl, type RemoteEndpointOptions, } from "./session-remote.ts";
 export { readBodyCapped } from "./channels/body.ts";
 export { text, textHeaders } from "./channels/respond.ts";
-export { type ChannelContext, type ChannelHandler, type ChannelModule, type LongConnection, type LongConnectionChannelModule, type Routes, router, serveNode, } from "./host/node.ts";
+export type { ChannelContext, ChannelHandler, ChannelModule, LongConnection, LongConnectionChannelModule, Routes, } from "./channel.ts";
 export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.ts";
-export { createScheduler, scheduleSession, type Scheduler, type SchedulerOptions } from "./schedule/scheduler.ts";

package/dist/core.js

@@ -1,10 +1,12 @@
 export { collect, AgentFailure } from "./collect.js";
-export { createInvokeHandler, nodeListener } from "./channels/http.js";
-export { controlRoutes } from "./channels/control.js";
+export { createInvokeHandler } from "./channels/http.js";
 export { ControlRequestError, connectAgent, connectSessionControl, } from "./session-remote.js";
 export { readBodyCapped } from "./channels/body.js";
 export { text, textHeaders } from "./channels/respond.js";
-export { router, serveNode, } from "./host/node.js";
+// Mounting only. Composing a route table (`router`) and owning a prefix (`PrefixMount`) are how
+// `createAgentService` assembles a service — not something a caller has to reproduce.
+// Binding to a Node server lives at `/node`: it is the only runtime-specific piece here, and the
+// only one that costs a third-party package.
+// `defineSchedule` is what a `schedules/*.ts` file is written against. Discovering those files and
+// running the clock is what `createAgentService` does with them — parts a caller does not reproduce.
 export { defineSchedule } from "./schedule/schedule.js";
-export { discoverScheduleFiles, loadSchedules } from "./schedule/discover.js";
-export { createScheduler, scheduleSession } from "./schedule/scheduler.js";

package/dist/deploy/preflight.js

@@ -15,7 +15,7 @@ import ignore from "ignore";
 import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
-import { inspectChannels } from "../engines/pi/channel.js";
+import { inspectChannels } from "../channels/discover.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";

package/dist/dev-supervisor.js

@@ -14,14 +14,20 @@ import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
 import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot } from "./paths.js";
-import { isUnderDir } from "./engines/pi/definition.js";
+import { isUnderDir } from "./paths.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, models.json, .secrets/.env";
+/**
+ * The agent-dir directories loaded ONCE per worker: a restart is their only re-read. One list, so
+ * the watcher and the line printed at startup cannot disagree — a directory watched but unannounced
+ * looks broken, and one announced but unwatched silently strands the author mid-edit.
+ */
+const CODE_INPUT_DIRS = ["tools", "channels", "schedules", "extensions"];
+const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.*, models.json, .secrets/.env`;
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
  * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
@@ -56,7 +62,7 @@ export function devWatchIgnored(root, envFile) {
         if (rel === AGENT_MODELS_FILE)
             return false;
         const segments = rel.split(sep);
-        if (segments[0] === "tools" || segments[0] === "channels" || segments[0] === "schedules")
+        if (CODE_INPUT_DIRS.includes(segments[0]))
             return false;
         // The `.env` restarts too (credentials are process-bound). Keep it AND its ancestor directories
         // un-pruned so chokidar can descend to it; every sibling inside them (auth.json, .env.example)

package/dist/engines/pi/agent-session-factory.d.ts

@@ -0,0 +1,104 @@
+import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Model } from "@earendil-works/pi-ai";
+import { type AgentSessionServices, type CreateAgentSessionServicesOptions, type ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { PiAgentSessionFactory } from "./invoke-session.ts";
+import type { PiSessionRecordStore } from "./session-store.ts";
+import { type MountedTool } from "./tool.ts";
+/** pi's Model with the API-shape generic erased; fastagent only passes models through. */
+type AnyModel = Model<any>;
+export interface PiAgentSessionFactoryOptions {
+    /** Where conversations live. Continuity = same store + same session id. */
+    sessions: PiSessionRecordStore;
+    /**
+     * The model to run and the hub that authenticates it, resolved on FIRST USE and kept.
+     *
+     * A thunk because building a `ModelRuntime` is async while assembling an agent is not: the L1
+     * surface hands back an `Agent` synchronously, so the credential read that a runtime performs
+     * belongs on the first turn rather than in the caller's constructor. The two travel together
+     * because a model must be resolved against the runtime that holds its provider's auth.
+     */
+    engine: () => Promise<{
+        modelRuntime: ModelRuntime;
+        model: AnyModel;
+    }>;
+    thinkingLevel?: ThinkingLevel;
+    tools?: MountedTool[];
+    /** Final assembled prompt, or a factory re-evaluated per turn. */
+    systemPrompt?: string | (() => string);
+    skills?: Skill[];
+    /** Per-turn source for the prompt+skills PAIR; supersedes the two above. This is what keeps
+     *  "the directory is the agent, LIVE" true on a shared `services`: the ResourceLoader is built
+     *  once, but what it serves is re-read here. */
+    live?: () => Promise<{
+        systemPrompt?: string;
+        skills?: Skill[];
+    }>;
+    /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
+    cwd: string;
+    /**
+     * Where pi looks for ITS settings (retry budget, compaction thresholds, default thinking level).
+     *
+     * Deliberately NOT pi's machine-global `~/.pi/agent`: a served agent must behave the same on the
+     * author's laptop and in a container, and reading the operator's personal pi configuration is the
+     * artifact losing to the machine. Point it at a definition-scoped path; a missing directory simply
+     * means pi's own defaults, which is the intended baseline.
+     */
+    agentDir?: string;
+    /**
+     * The definition's own extension entry points, for ANNOUNCING that serving does not run them.
+     *
+     * pi's extension machinery is built for one process serving one session: `bindCore()` copies the
+     * session's actions into a runtime the pi source itself calls "the shared runtime", extension
+     * modules are cached per assembly, and `session_start`/`session_shutdown` are a matched pair.
+     * Serving breaks every one of those assumptions — concurrent turns for unrelated conversations —
+     * and the failure is silent cross-talk: with two turns in flight, an extension calling
+     * `pi.sendMessage()` can deliver into the other conversation.
+     *
+     * Loading them anyway would be a correctness bug dressed as a feature, so serving does not, and
+     * warns when a definition ships some. `chat` runs them fully: one session, one runtime, which is
+     * exactly the shape pi is built for.
+     *
+     * Isolating them per session is mechanically possible — pi's uncached loader path builds a fresh
+     * module (jiti with `moduleCache: false`) and takes the runtime as an argument — but that function
+     * is not exported and the deep path is blocked by the package's `exports`. Reopening this needs
+     * that entry point upstream, not a workaround here.
+     */
+    extensionPaths?: string[];
+    /** Built-ins omitted by an explicit lower-level tool list. */
+    excludedToolNames?: readonly string[];
+    /** Filesystem/process environment: definition loading, and the turn context for tools that read one. */
+    env: ExecutionEnv;
+}
+/**
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
+ * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
+ * A definition running without the extension it ships is exactly the "quietly missing" failure this
+ * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
+ * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ */
+export declare function reportExtensionErrors(services: AgentSessionServices): void;
+/** What pi is allowed to discover, minus the parts each assembly fills in itself. */
+type DefinitionLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
+/**
+ * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
+ * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
+ * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
+ * everything comes from the definition, nothing from the machine that happens to be running it.
+ *
+ * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
+ * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
+ * worked when served and vanished in chat. A difference between the two has to be visible AS a
+ * difference, which is what the parameters are for: serving reads a prompt and skills that change
+ * per turn and passes NO extension paths (it does not run them — see
+ * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
+ * own. Both are arguments now, rather than two files that happen to disagree.
+ */
+export declare function definitionResourceLoaderOptions(source: {
+    systemPrompt: () => string | undefined;
+    skills: () => Skill[];
+    /** Omitted by serving, which does not run them. */
+    extensionPaths?: readonly string[];
+}): DefinitionLoaderOptions;
+/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+export declare function piAgentSessionFactory(options: PiAgentSessionFactoryOptions): PiAgentSessionFactory;
+export {};