@fastagent-sh/fastagent 0.20.0 → 0.21.1

package/dist/cli/commands/dev.js

@@ -3,34 +3,23 @@
  * assemble + serve, restarting it on agent edits. A fresh process per reload means what is served
  * is always the latest code, including modules a tool/config imports.
  */
-import { resolve } from "node:path";
 import { runDevSupervisor } from "../../dev-supervisor.js";
-import { loadDotEnv } from "../../env.js";
 import { setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
 import { logAgentLoop } from "../../observe.js";
-import { installProxyFetch } from "../../proxy.js";
-import { bindAddress } from "../../bind.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAssembly, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { assertTunnelBindable, cliMountOptions, resolveBindHost, serveService } from "../serve.js";
+import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shared.js";
 export async function runDev(dirArg, opts) {
-    const dir = resolve(dirArg);
-    const placement = placementOrExit(dir);
     setLogLevel("debug"); // dev posture: verbose, includes the debug turn trace (content) — supervisor and worker both
     const isWorker = process.env.FASTAGENT_DEV_WORKER === "1";
-    // Pick a model interactively once, in the parent (both watch and --no-watch have a TTY); a spawned
-    // watch worker inherits the choice via FASTAGENT_MODEL, so it must not prompt again. Load .env and
-    // the proxy FIRST (as invoke/start do): the picker reads FASTAGENT_MODEL and provider keys from
-    // .env, and getAuth's OAuth refresh must go through HTTPS_PROXY. The worker re-loads both in serveOnce.
-    if (!isWorker) {
-        loadDotEnv(placement.agentDir);
-        installProxyFetch();
-        await resolveFirstRunModel(placement.agentDir, opts);
-    }
+    // The model is picked ONCE, in the parent process (a TTY; watch and --no-watch both); a spawned
+    // worker inherits the choice through FASTAGENT_MODEL and must not prompt even when the pick was
+    // cancelled.
+    const placement = await enterAgentCommand(dirArg, { ...opts, input: isWorker ? false : opts.input });
     if (isWorker || opts.watch === false) {
-        await serveOnce(dir, opts);
+        await serveOnce(placement, opts);
         return;
     }
     parsePort(opts.port, "--port", "flag"); // flag-shape checks before spawning
@@ -40,41 +29,23 @@ export async function runDev(dirArg, opts) {
     await runDevSupervisor(placement, { tunnel: opts.tunnel ?? false });
 }
 /** Assemble the agent and serve it once (the dev worker; also the --no-watch path). */
-async function serveOnce(dir, opts) {
+async function serveOnce(placement, opts) {
     const portFlag = parsePort(opts.port, "--port", "flag");
     const bindFlag = parseBind(opts.bind);
-    loadDotEnv(placementOrExit(dir).agentDir);
-    installProxyFetch();
-    const a = await createPiAgentFromDir(dir, {
+    const tunnel = opts.tunnel ?? false;
+    const a = await createPiAgentFromDir(placement.workspace, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
         serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
     }).catch(failStartup);
     // The same report `start` prints; `config:` is dev's own extra (see reportAssembly on the asymmetry).
     await reportAssembly(a, { beforeModel: [["config", a.configPath ?? "(none)"]] });
-    // `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 host = resolveBindHost(bindFlag, a.config.http?.host, tunnel);
     // 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(),
-    });
+    // prints the opened values before anything mounts. The turn trace (tool calls + reply) logs at
+    // debug level: shown here, gated out in start (level info), keeping end-user content out of
+    // production logs.
+    const service = await mountAgentService(a, cliMountOptions(logAgentLoop)).catch(failStartup);
+    serveService(service, { port: portFlag ?? a.config.http?.port ?? 8787, host }, { tunnel, agentDir: a.agentDir, stateRoot: a.stateRoot });
 }

package/dist/cli/commands/fire.js

@@ -4,23 +4,17 @@
  * the schedule's stable session (faithful to the served behavior). Does NOT advance the schedule's fire
  * state — a test run must never make the scheduler skip the real next run.
  */
-import { join, resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
+import { join } from "node:path";
 import { displayPath } from "../../paths.js";
-import { reportModuleLoadFailures } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
-import { installProxyFetch } from "../../proxy.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { scheduleSession } from "../../schedule/scheduler.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { reportAuth, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runFire(name, dirArg, opts) {
-    const fireDir = resolve(dirArg);
-    const placement = placementOrExit(fireDir);
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
+    const placement = await enterAgentCommand(dirArg, opts);
     // Schedules are agent surface — discover them where dev/start/`schedule list` do (the agent
     // dir), so `fire` sees the same set the scheduler serves.
     const { schedules, failures } = await loadSchedules(placement.agentDir).catch(failStartup);
@@ -32,7 +26,7 @@ export async function runFire(name, dirArg, opts) {
         failStartup(new Error(`unknown schedule "${name}" (looked in ${displayPath(process.cwd(), join(placement.agentDir, "schedules")) ?? "schedules"}). ` +
             `available: ${schedules.map((s) => s.name).join(", ") || "(none)"}`));
     }
-    const { agent, modelSpec, authPath } = await createPiAgentFromDir(fireDir, {
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);

package/dist/cli/commands/info.js

@@ -8,7 +8,8 @@ import { resolveStateRoot, workspaceHint } from "../../paths.js";
 import { CODING_TOOL_NAMES, resolveAgentTools } from "../../engines/pi/create.js";
 import { loadAgentDefinition } from "../../engines/pi/definition.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "../../engines/pi/report.js";
-import { reportModuleLoadFailures, log } from "../../log.js";
+import { log } from "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { nextRun } from "../../schedule/cron.js";
 import { loadSchedules } from "../../schedule/discover.js";
 import { failStartup, placementOrExit } from "../fail.js";

package/dist/cli/commands/invoke.js

@@ -1,19 +1,12 @@
 /** `fastagent invoke <message> [dir]`: run ONE turn against the assembled agent, then exit. */
 import { randomUUID } from "node:crypto";
-import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { runInvokeStream } from "../invoke-stream.js";
-import { installProxyFetch } from "../../proxy.js";
-import { failStartup, placementOrExit } from "../fail.js";
-import { reportAuth, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { enterAgentCommand, reportAuth } from "../shared.js";
 export async function runInvoke(message, dirArg, opts) {
-    const invokeDir = resolve(dirArg);
-    const placement = placementOrExit(invokeDir);
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
-    const { agent, modelSpec, authPath } = await createPiAgentFromDir(invokeDir, {
+    const placement = await enterAgentCommand(dirArg, opts);
+    const { agent, modelSpec, authPath } = await createPiAgentFromDir(placement.workspace, {
         model: opts.model,
         authPath: opts.authPath, // flag > FASTAGENT_AUTH_PATH > default — resolved by the opener (one owner)
     }).catch(failStartup);

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 "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.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,42 +2,40 @@
  * `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 { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 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 { SECRET_FILE_MODE, ensureSecretsDir, resolveSecretsDir, isUnderDir, exists } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
 import { mountAgentService } from "../../service.js";
 import { logAgentLoop } from "../../observe.js";
-import { installProxyFetch } from "../../proxy.js";
-import { bindAddress } from "../../bind.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 { SHUTDOWN_GRACE_MS, assertTunnelBindable, maybeTunnel, reportServing, serve } from "../serve.js";
-import { parseBind, parsePort, reportAssembly, resolveFirstRunModel } from "../shared.js";
+import { failStartup } from "../fail.js";
+import { cliMountOptions, resolveBindHost, serveService } from "../serve.js";
+import { enterAgentCommand, parseBind, parsePort, reportAssembly } 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
     // the directory being an agent (which is a runtime/environment failure, exit 1).
     const portFlag = parsePort(opts.port, "--port", "flag");
     const bindFlag = parseBind(opts.bind);
-    const placement = placementOrExit(dir);
+    const tunnel = opts.tunnel ?? false;
     setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
-    await resolveFirstRunModel(placement.agentDir, opts);
+    const placement = await enterAgentCommand(dirArg, opts);
     // A `deploy --run` may carry the operator's local credential as FASTAGENT_AUTH_SEED —
     // materialize it into the writable secrets dir BEFORE the opener resolves auth (once, absent-only).
     // Same resolveAuthPath the opener uses — ONE owner of the flag > env > default chain.
     await maybeSeedAuth(resolveAuthPath(placement.agentDir, opts.authPath));
     // The same opener dev uses (single assembly source), just no watch.
-    const sessionsDirOverride = resolveSessionsDirOverride(opts.sessionsDir);
-    const opened = await openStartDir(dir, opts, sessionsDirOverride);
+    const opened = await createPiAgentFromDir(placement.workspace, {
+        model: opts.model,
+        sessionsDir: resolveSessionsDirOverride(opts.sessionsDir),
+        authPath: opts.authPath,
+        serving: true, // long-running serve: the scheduler poller runs (wake mounts iff config.selfSchedule)
+    }).catch(failStartup);
     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).
@@ -65,14 +63,9 @@ 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.`);
     }
-    // Same debug turn trace as dev; gated out here by the info level (see dev.ts serveOnce).
+    // Same debug turn trace as dev; gated out here by the info level.
     const traced = logAgentLoop(agent);
-    // `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 control = { tunnel: opts.tunnel ?? false, ...(host !== undefined ? { host } : {}) };
+    const host = resolveBindHost(bindFlag, config.http?.host, tunnel);
     // 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.
@@ -81,36 +74,14 @@ export async function runStart(dirArg, opts) {
     // 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(),
-    });
+        ? mountAgentcoreService(opened, { wrapAgent: () => traced, onStateReady })
+        : mountAgentService(opened, cliMountOptions(() => traced))).catch(failStartup);
+    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? config.http?.port ?? 8787, host }, { tunnel, agentDir, stateRoot });
     // 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

package/dist/cli/commands/tool.js

@@ -1,10 +1,9 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
-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 "../../log.js";
+import { reportModuleLoadFailures } from "../../loader.js";
 import { turnContext } from "../../engines/pi/tool-context.js";
 import { failStartup, failUsage, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
@@ -26,12 +25,8 @@ export async function runTool(name, argsJson, dirArg) {
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
-    // 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 }))
-        .catch(failStartup);
+    // Authored tools read cwd from turnContext; coding tools are already rooted at the workspace.
+    const result = await turnContext.run({ cwd: workspace }, () => tool.execute(`cli-${name}`, args)).catch(failStartup);
     const out = result?.details !== undefined
         ? result.details
         : (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");

package/dist/cli/kernel.d.ts

@@ -24,8 +24,6 @@ interface ArgSpec {
 export interface FlagSpec {
     flags: string;
     description: string;
-    /** Parses but does not appear in help — for retired flags that should still explain themselves. */
-    hidden?: boolean;
     /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
     conflicts?: string[];
 }

package/dist/cli/kernel.js

@@ -114,8 +114,6 @@ function register(parent, spec) {
     }
     for (const f of spec.flags ?? []) {
         const opt = new Option(f.flags, f.description);
-        if (f.hidden)
-            opt.hideHelp();
         if (f.conflicts)
             opt.conflicts(f.conflicts);
         cmd.addOption(opt);

package/dist/cli/program.js

@@ -6,6 +6,7 @@
  */
 import { fastagentVersion } from "../version.js";
 import { buildProgram } from "./kernel.js";
+import { DEPLOY_HOSTS } from "../deploy/hosts.js";
 // Help groups (clig: most common commands first) — the authoring loop leads, operations close.
 // Shared flags — same name, same meaning, on every command that supports them (clig: consistency).
 const DIR_ARG = {
@@ -256,8 +257,6 @@ const start = {
         input: f.input !== false,
     }),
 };
-/** The retired app-creation flag — parsed so it can explain itself, hidden from help. */
-const CREATE_APP = { flags: "--create-app", description: "(retired)", hidden: true };
 const INGRESS = {
     flags: "--ingress <mode>",
     description: "Feishu/Lark ingress: websocket or webhook (interactive when omitted)",
@@ -280,18 +279,14 @@ const channelSub = (kind, summary, description, notes) => ({
     summary,
     description,
     args: [DIR_ARG],
-    flags: [
-        CREATE_APP,
-        ...(kind === "feishu" || kind === "lark"
-            ? [INGRESS, GROUP_BEHAVIOR]
-            : kind === "slack"
-                ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
-                : []),
-    ],
+    flags: kind === "feishu" || kind === "lark"
+        ? [INGRESS, GROUP_BEHAVIOR]
+        : kind === "slack"
+            ? [GROUP_BEHAVIOR, NO_ONBOARD, REPLACE_CONFIG]
+            : [],
     examples: [{ cmd: `fastagent add ${kind}` }],
     ...(notes ? { notes } : {}),
     run: async (args, f) => (await import("./commands/add.js")).runAddChannel(kind, args[0], {
-        createApp: f.createApp === true,
         ingress: f.ingress,
         groupBehavior: f.groupBehavior,
         onboard: f.onboard !== false,
@@ -357,7 +352,7 @@ const deploy = {
         "CloudFormation stack (AWS Bedrock AgentCore Runtime + forwarder Lambda for webhooks + " +
         "EventBridge rules for schedules; linux/arm64 image built locally). Durable ingress " +
         "remains operator-owned (agentcore's forwarder URL is the exception — the stack owns it).",
-    args: [{ name: "<host>", description: "deploy target", choices: ["docker", "fly", "railway", "agentcore"] }, DIR_ARG],
+    args: [{ name: "<host>", description: "deploy target", choices: [...DEPLOY_HOSTS] }, DIR_ARG],
     flags: [
         {
             flags: "--run",

package/dist/cli/serve.d.ts

@@ -1,5 +1,5 @@
-import type { ChannelHandler } from "../channel.ts";
-import type { AgentService } from "../service.ts";
+import type { Agent } from "../agent.ts";
+import type { AgentService, MountAgentServiceOptions } 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
@@ -10,6 +10,26 @@ import type { AgentService } from "../service.ts";
  * came from config is broken runtime configuration (1).
  */
 export declare function assertTunnelBindable(host: string | undefined, tunnel: boolean, source: "flag" | "config"): void;
+/**
+ * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
+ * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
+ * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
+ */
+export declare function resolveBindHost(bindFlag: string | undefined, configured: string | undefined, tunnel: boolean): string | undefined;
+/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
+export declare function cliMountOptions(wrapAgent: (agent: Agent) => Agent): MountAgentServiceOptions;
+/**
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
+ * tail dev's worker and start share once the service is assembled.
+ */
+export declare function serveService(service: AgentService, bind: {
+    port: number;
+    host?: string;
+}, posture: {
+    tunnel: boolean;
+    agentDir: string;
+    stateRoot: string;
+}): 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 —
@@ -26,23 +46,20 @@ export declare function reportServing(service: AgentService, host: string | unde
  * 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 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.
+ * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
+ * once the port is known, and say what reaches it. Returns the file's removal — wired into the
+ * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
+ * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
+ * file behind: advisory, overwritten by the next boot.
+ *
+ * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
+ * operator finds and protects the plane. An embedder distributes `service.control` itself.
  */
-export declare function serve(handler: ChannelHandler, bind: {
-    port: number;
+export declare function announceControl(control: {
+    token: string;
+    prefix: string;
+} | undefined, stateRoot: string, bind: {
     host?: string;
-}, 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;
+    tunnel: boolean;
+}, boundPort: number): () => void;

package/dist/cli/serve.js

@@ -1,12 +1,16 @@
 /**
  * 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.
+ * order, the startup report, the optional Cloudflare quick tunnel, and the options the CLI hands the
+ * assembly (`cliMountOptions`, `resolveBindHost` — policy ABOUT the assembly, decided per command).
  *
- * 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`).
+ * The ASSEMBLY itself 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 { mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
 import { INVOKE_EXAMPLE_BODY } from "../channels/http.js";
-import { answersLocalhost, bindLabel, classifyBind, clientHost } from "../bind.js";
+import { answersLocalhost, bindAddress, bindLabel, classifyBind, clientHost } from "../bind.js";
+import { writeFileAtomic } from "../atomic-write.js";
 import { serveNode } from "../channels/serve.js";
 import { log } from "../log.js";
 import { openExternalUrl } from "../open-url.js";
@@ -35,6 +39,45 @@ export function assertTunnelBindable(host, tunnel, source) {
         failUsage(message);
     failStartup(new Error(message));
 }
+/**
+ * The bind address a serve uses: the flag, else `http.host` from the config — through `bindAddress`,
+ * so a configured `localhost` is an ADDRESS by the time anything binds, renders or dials it — checked
+ * against `--tunnel` with the exit code the SOURCE of the value earns (serve.ts assertTunnelBindable).
+ */
+export function resolveBindHost(bindFlag, configured, tunnel) {
+    const host = bindFlag ?? (configured === undefined ? undefined : bindAddress(configured));
+    assertTunnelBindable(host, tunnel, bindFlag ? "flag" : "config");
+    return host;
+}
+/** What the CLI adds to the assembly: its shutdown grace, and exit on a connection that drops. */
+export function cliMountOptions(wrapAgent) {
+    return {
+        wrapAgent,
+        closeTimeoutMs: SHUTDOWN_GRACE_MS,
+        onChannelClosed: (name, error) => failStartup(new Error(`${name} ${error === undefined ? "closed unexpectedly" : `failed: ${String(error)}`}`)),
+    };
+}
+/**
+ * Bind, report, announce the control plane, open the tunnel, and close in order on a signal — the
+ * tail dev's worker and start share once the service is assembled.
+ */
+export function serveService(service, bind, posture) {
+    const { host } = bind;
+    const { tunnel, agentDir, stateRoot } = posture;
+    let unannounce = () => { };
+    serve(service.handler, bind, {
+        ready: service.ready,
+        onListening: (p) => {
+            reportServing(service, host, p);
+            unannounce = announceControl(service.control, stateRoot, { host, tunnel }, p);
+            maybeTunnel(agentDir, service.channels.routes, p, tunnel, stateRoot);
+        },
+        onShutdown: () => {
+            unannounce();
+            return service.close();
+        },
+    });
+}
 /**
  * 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 —
@@ -68,9 +111,50 @@ export function readyAddressLines(host, boundPort, builtinInvoke) {
     }
     return lines;
 }
+/**
+ * Write `<stateRoot>/control.json` so a LOCAL client (`fastagent attach`) can find the control plane
+ * once the port is known, and say what reaches it. Returns the file's removal — wired into the
+ * shutdown so a stale file cannot point a client at a dead port (`attach` then fails with "cannot
+ * read", accurate, instead of a stale token's misleading 401/ECONNREFUSED). A hard exit leaves the
+ * file behind: advisory, overwritten by the next boot.
+ *
+ * Here and not in the assembly: the file, its permissions and the warnings are how THIS process's
+ * operator finds and protects the plane. An embedder distributes `service.control` itself.
+ */
+export function announceControl(control, stateRoot, bind, boundPort) {
+    if (!control)
+        return () => { };
+    mkdirSync(stateRoot, { recursive: true, mode: 0o700 });
+    const path = join(stateRoot, "control.json");
+    const url = `http://${clientHost(bind.host)}:${boundPort}`;
+    writeFileAtomic(path, `${JSON.stringify({ url, token: control.token })}\n`, 0o600);
+    log.info(`[fastagent] session control on ${control.prefix}/* (token in ${path})`);
+    // LAN-reachable with the bearer token as the only protection — the tunnel and deploy paths warn
+    // loudly, and the LAN path must not be the silent third way past the local trust story. A
+    // loopback bind closes exactly that reach, so it earns silence.
+    const reach = classifyBind(bind.host);
+    if (reach !== "loopback") {
+        log.warn(`[fastagent] the port binds ${reach === "wildcard" ? "all interfaces" : `${bind.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/session-control.md §14)");
+    }
+    if (bind.tunnel) {
+        // Local trust = the token + its file permissions; --tunnel takes the whole port PUBLIC.
+        log.warn("[fastagent] --tunnel exposes /control/* (steer, stop, rewrite or delete a session) at the public tunnel URL, " +
+            "protected ONLY by the bearer token — wrap it with real auth before sharing that URL (docs/design/session-control.md §14)");
+    }
+    return () => {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            /* the file is advisory — shutdown must not fail on it */
+        }
+    };
+}
 /** 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 SHUTDOWN_GRACE_MS = 800;
 const FORCED_EXIT_MS = 1_500;
 /**
  * Bind HTTP and report ready — but only once the SERVICE is, which is not the same moment: a bound
@@ -78,7 +162,7 @@ const FORCED_EXIT_MS = 1_500;
  * awaits `hooks.ready` (mountAgentService owns the connections themselves) before announcing
  * anything. Signals are the sole clean-shutdown command; `host` unset binds all interfaces.
  */
-export function serve(handler, bind, hooks = {}) {
+function serve(handler, bind, hooks = {}) {
     const { port, host } = bind;
     const hosted = serveNode(handler, { port, host });
     let stopping = false;
@@ -141,7 +225,7 @@ export function serve(handler, bind, hooks = {}) {
     });
 }
 /** Start a Cloudflare tunnel for route channels only. */
-export function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
+function maybeTunnel(agentDir, routeChannels, boundPort, tunnel, stateRoot) {
     if (!tunnel || process.env.FASTAGENT_DEV_WORKER === "1")
         return;
     void startCloudflareTunnel(boundPort).then((instance) => {