@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/cli/commands/start.js

@@ -1,125 +1,175 @@
-/**
- * `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 } from "node:path";
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/** Production serving. */
+import { join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+import { readFile } from "node:fs/promises";
+import * as Effect from "effect/Effect";
 import { writeFileAtomic } from "../../atomic-write.js";
-import { authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
-import { resolveAuthPath, resolveSessionsDirOverride } from "../../engines/pi/config.js";
-import { SECRET_FILE_MODE, ensureSecretsDir, resolveSecretsDir, isUnderDir, exists } from "../../paths.js";
+import { applyCarriedEnv, authSeedBytes, collectAuthSeed } from "../../deploy/secrets.js";
+import { applyReleaseEnv, installAgentDependencies, parseDeploymentRelease, prepareDeployment, } from "../../deploy/workspace.js";
+import { resolveAuthPath } from "../../engines/pi/config.js";
+import { SECRET_FILE_MODE, resolveSecretsDir, isAgentcoreRuntime, isUnderDir, exists } from "../../paths.js";
 import { log, setLogLevel } from "../../log.js";
 import { createPiAgentFromDir } from "../../engines/pi/open.js";
-import { mountAgentService } from "../../service.js";
+import { DEFAULT_HTTP_PORT, mountAgentService } from "../../service.js";
 import { logAgentLoop } from "../../observe.js";
-import { isAgentcoreRuntime, mountAgentcoreService } from "../../channels/agentcore-service.js";
+import { mountAgentcoreService, deferAgentcoreService } from "../../channels/agentcore-service.js";
 import { createWakeAlarmSink } from "../../schedule/wake-alarm.js";
 import { setWakeupsSink } from "../../schedule/wakeups.js";
 import { failStartup } from "../fail.js";
-import { cliMountOptions, resolveBindHost, serveService } from "../serve.js";
+import { announceControl, assertTunnelBindable, bindLine, cliMountOptions, serveService, serve, withRunOverrides, } from "../serve.js";
 import { enterAgentCommand, parseBind, parsePort, reportAssembly } from "../shared.js";
 export async function runStart(dirArg, opts) {
-    // 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);
+    // A host that carries the value file as ONE encoded variable (AgentCore): expanded before anything reads the env.
+    try {
+        applyCarriedEnv();
+    }
+    catch (error) {
+        failStartup(error);
+    }
+    setLogLevel("info");
+    if (isAgentcoreRuntime()) {
+        // The generated Runtime resource sets PORT; 8080 is the platform's contract when nothing does.
+        const port = portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? 8080;
+        const deferred = deferAgentcoreService({
+            prepare: () => prepareStartWorkspace(dirArg),
+            assemble: async (prepared) => {
+                const service = await openPreparedWorkspace(prepared, opts);
+                await service.ready;
+                announceControl(service, { host: bindFlag, tunnel: false });
+                return service;
+            },
+        });
+        serve(deferred.handler, { port, host: bindFlag }, {
+            // The assembly report waits for the first envelope, so this line is the only sign of life a booted container
+            // gives.
+            onListening: (port) => {
+                // NOT `readyAddressLines`: this posture serves the Runtime's `/invocations` contract, not our `/invoke`.
+                log.info(bindLine(bindFlag, port));
+                log.info("[fastagent] agentcore: the definition opens on the first invocation");
+            },
+            onShutdown: () => deferred.close(),
+        });
+        return;
+    }
+    // Deployed storage refusals (no mount, a held lease, a missing `flock`, a failed install) are the operator's only
+    // clue in a crash-looping container.
+    const service = await openStartService(dirArg, opts).catch(failStartup);
     const tunnel = opts.tunnel ?? false;
-    setLogLevel("info"); // production posture: info+, the debug turn trace (and its end-user content) gated out
+    // An unset bind stays the wildcard: this is the container posture, and a published port needs it.
+    assertTunnelBindable(bindFlag, tunnel);
+    serveService(service, { port: portFlag ?? parsePort(process.env.PORT, "PORT env", "env") ?? service.port, host: bindFlag }, { tunnel, agentDir: service.agentDir, stateRoot: service.stateRoot });
+}
+/**
+ * Stage one — TAKE the workspace: verify the storage is mounted, apply the release, and point the machinery at the
+ * volume.
+ */
+export async function prepareStartWorkspace(dirArg) {
+    const manifestPath = process.env.FASTAGENT_RELEASE_FILE;
+    if (!manifestPath)
+        return { dir: dirArg };
+    const storage = process.env.FASTAGENT_STORAGE_DIR;
+    if (!storage)
+        throw new Error("FASTAGENT_STORAGE_DIR is required for a deployed workspace");
+    const root = resolve(storage);
+    const manifest = parseDeploymentRelease(await readFile(manifestPath, "utf8"));
+    const dir = await prepareDeployment(resolve(dirArg), root, manifest);
+    // Defaults, not overrides: an operator who pointed either dir somewhere else meant it, and silently relocating
+    // their state is the one failure they could not diagnose from the logs.
+    process.env.FASTAGENT_STATE_DIR ||= join(root, ".state");
+    process.env.FASTAGENT_SECRETS_DIR ||= join(root, ".secrets");
+    process.env.FASTAGENT_AGENT = manifest.agent;
+    // The release's own declarations, projected into the environment it was resolved FOR. This must stay BEFORE
+    // `enterAgentEnv` reads the workspace's `.env`, which is what makes either source outrank a value edited on the
+    // box (applyReleaseEnv's own tests pin the precedence).
+    applyReleaseEnv(manifest);
+    process.chdir(dir);
+    return { dir, deployed: { root, agent: manifest.agent } };
+}
+/**
+ * Stage two — RUN in the prepared workspace: install the agent's dependencies, then open through the workspace's own
+ * FastAgent install.
+ */
+export async function openPreparedWorkspace(prepared, opts) {
+    let open = openPreparedStartService;
+    if (prepared.deployed) {
+        const { root, agent } = prepared.deployed;
+        const agentDir = join(prepared.dir, agent);
+        if (await exists(join(agentDir, "package.json"))) {
+            await installAgentDependencies(root, agentDir);
+            // Tools and their session context must share the workspace's runtime module instance.
+            const entry = createRequire(join(agentDir, "package.json")).resolve("@fastagent-sh/fastagent");
+            const local = (await import(__rewriteRelativeImportExtension(new URL("./cli/commands/start.js", pathToFileURL(entry)).href)));
+            // A version-skewed dependency resolves and imports fine, then fails as "open is not a function" with nothing
+            // naming the two versions.
+            if (typeof local.openPreparedStartService !== "function") {
+                throw new Error(`${entry} does not export openPreparedStartService — align the agent's @fastagent-sh/fastagent version with the deploy CLI`);
+            }
+            open = local.openPreparedStartService;
+        }
+    }
+    return open(prepared.dir, opts);
+}
+export async function openStartService(dirArg, opts) {
+    return openPreparedWorkspace(await prepareStartWorkspace(dirArg), opts);
+}
+/** Internal entry loaded from the active workspace's installed package after storage initialization. */
+export async function openPreparedStartService(dirArg, 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 opened = await createPiAgentFromDir(placement.workspace, {
+    await maybeSeedAuth(resolveAuthPath(placement.agentDir));
+    const opened = await createPiAgentFromDir(placement.agentDir, {
         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);
+        serving: true,
+    });
     const { agent, agentDir, config, stateRoot, sessionsDir } = opened;
-    // The same report `dev` prints; `state:`/`sessions:` are start's own extras, and the persistence
-    // notes below are why (see reportAssembly on the asymmetry).
     await reportAssembly(opened, {
         afterTools: [
             ["state", stateRoot],
             ["sessions", sessionsDir],
         ],
     });
-    // State defaults under the agent dir, which a redeploy may replace wholesale. Gate on where the
-    // state root ACTUALLY resolved (inside the agent dir?), not on the raw env var: an empty
-    // `FASTAGENT_STATE_DIR=""` reads as unset (resolveStateRoot) and still lands in-agent, so a raw
-    // `=== undefined` check would wrongly silence the warning. A sessions override to a volume does not
-    // help — channel state (the telegram turn/context files replay depends on) is still in-agent.
-    // (auth.json is NOT under the state root — it lives in the secrets dir, resolveSecretsDir.)
     if (isUnderDir(stateRoot, agentDir)) {
-        log.info(`[fastagent] note: state (sessions, channel state) lives under the definition dir; point ` +
-            `FASTAGENT_STATE_DIR at a persistent volume so a redeploy that replaces the dir does not wipe it.`);
+        log.info("[fastagent] note: state lives under the definition; use FASTAGENT_STATE_DIR on persistent storage for deployment.");
     }
-    // The secrets dir is the SAME trap on a different lifecycle: auth.json is MACHINE-WRITTEN (OAuth
-    // rotation), so the copy under the definition dir is the only valid one — a redeploy that replaces
-    // the dir loses a credential no re-seed can restore. An independent check on purpose: moving ONE
-    // of the two to a volume must not silence the note about the other.
     if (isUnderDir(resolveSecretsDir(agentDir), agentDir)) {
-        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.`);
+        log.info("[fastagent] note: credentials live under the definition; use FASTAGENT_SECRETS_DIR on persistent storage for deployment.");
     }
-    // Same debug turn trace as dev; gated out here by the info level.
     const traced = logAgentLoop(agent);
-    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.
-    // 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 onStateReady = isAgentcoreRuntime() ? armWakeAlarms(stateRoot) : undefined;
+    const mountable = withRunOverrides(opened, opts);
     const service = await (isAgentcoreRuntime()
-        ? 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).
+        ? mountAgentcoreService(mountable, { wrapAgent: () => traced, onStateReady })
+        : mountAgentService(mountable, cliMountOptions(() => traced)));
+    return { ...service, stateRoot, port: config.http?.port ?? DEFAULT_HTTP_PORT };
 }
-/**
- * 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
- * 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).
- */
 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.
     const bytes = authSeedBytes(collectAuthSeed(process.env), await exists(authPath));
     if (!bytes)
         return;
-    await ensureSecretsDir(dirname(authPath));
-    // Same spelling as the credential store: the mode is applied before the content is reachable, so
-    // the seed can never be published at some other file's looser permissions. It does NOT close the
-    // gap between the `exists` check and the write — the rename would overwrite a file created in
-    // between, against this function's absent-only promise. That window needs two `start` processes on
-    // one secrets dir, which no supported deployment runs (one container, one volume).
-    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE);
+    writeFileAtomic(authPath, bytes, SECRET_FILE_MODE); // creates the directory it needs
     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.
+ * Install the wake-ALARM sink before the scheduler starts: the first wake poll may advance a recurring entry, and that
+ * save must already re-arm its alarm.
  */
 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)`);
+        log.warn("[fastagent] FASTAGENT_WAKE_SECRET is missing; external wake alarms cannot be registered");
         return undefined;
     }
-    const sink = createWakeAlarmSink({ secret });
+    const sink = Effect.runSync(createWakeAlarmSink({ secret }));
     setWakeupsSink(sink);
-    log.info(`[fastagent] wake alarms: EventBridge-backed via the forwarder`);
-    // Boot reconcile: pending wake-ups may exist while their alarms were lost (a deploy replaced the
-    // forwarder, a sink call failed). The sink re-reads the store, so a bare notification is enough.
     return () => sink(stateRoot);
 }

package/dist/cli/commands/tool.js

@@ -1,36 +1,50 @@
 /** `fastagent tool <name> '<json>' [dir]`: run one tool's body directly with JSON args — no model. */
 import { resolve } from "node:path";
-import { loadDotEnv } from "../../env.js";
+import { enterAgentEnv } from "../../env.js";
 import { loadConfig } from "../../engines/pi/config.js";
 import { resolveAgentTools } from "../../engines/pi/create.js";
 import { reportModuleLoadFailures } from "../../loader.js";
 import { turnContext } from "../../engines/pi/tool-context.js";
-import { failStartup, failUsage, placementOrExit } from "../fail.js";
+import { failStartup, failUsage, gateSecretsOrExit, placementOrExit } from "../fail.js";
 export async function runTool(name, argsJson, dirArg) {
-    // Argument shape first: malformed JSON is a USAGE error (exit 2), independent of whether the
-    // directory is an agent (a runtime failure, exit 1).
+    // Argument shape first: malformed JSON is a USAGE error (exit 2), independent of whether the directory is an agent
+    // (a runtime failure, exit 1).
     const args = parseToolArgs(argsJson);
     const { agentDir, workspace } = placementOrExit(resolve(dirArg));
-    loadDotEnv(agentDir); // a tool may read a key from .env
+    enterAgentEnv(agentDir); // a tool may read a key from .env — and fetch through the proxy it declares
     const { config } = await loadConfig(agentDir).catch(failStartup);
     // 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, workspace).catch(failStartup);
+    // exercises exactly what gets served.
+    const { tools, toolCollisions, toolFailures, toolSecrets } = 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`);
     }
+    // Reported BEFORE the name is looked up: a file that failed to import is missing from `tools`, so
+    // "unknown tool" is exactly the case where the author most needs to hear that something blew up
+    // rather than that they mistyped it.
     reportModuleLoadFailures(toolFailures);
     const tool = tools.find((t) => t.name === name);
     if (!tool) {
         failStartup(new Error(`unknown tool "${name}". available: ${tools.map((t) => t.name).join(", ") || "(none)"}`));
     }
+    // This command RUNS one tool body, so it takes the same guarantee dev/start take — for THAT tool
+    // only (`owner`): running one tool by hand must not require the credentials of the tools it is not
+    // running, and `routine run` scopes the same way for one routine.
+    // The failures go to the gate as well, even though they were just printed: the gate's guarantee is
+    // that a refusal never hides them, and it cannot know a caller already reported. A repeated line on
+    // the refusal path is the cheaper failure than one that depends on this call site remembering.
+    gateSecretsOrExit({ declared: toolSecrets, failures: toolFailures, owner: name });
     // 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("");
-    console.log(typeof out === "string" ? out : JSON.stringify(out, null, 2));
+    // What the MODEL receives, which is not what is printed below: the printed form is `details` (readable, indented),
+    // the model's is the content text (compact JSON). Piping stdout through `wc -c` therefore answers the wrong
+    // question, and there is nowhere else to ask this one — so the run that a tool author already does reports it.
+    const modelText = (result?.content ?? []).map((c) => ("text" in c ? c.text : "")).join("");
+    const out = result?.details !== undefined ? result.details : modelText;
+    console.log(typeof out === "string" ? out : JSON.stringify(out, null, 2)); // stdout stays DATA
+    // No threshold warning: context windows run from 128k to 1M, so any fixed ceiling here would be invented. The
+    // number is the signal; docs/api-reference.md carries the judgement. ~4 chars/token is the usual rough figure.
+    console.error(`[fastagent] result: ${modelText.length} chars ≈ ${Math.ceil(modelText.length / 4)} tokens to the model`);
 }
 /** Parse the CLI's JSON args blob; malformed input syntax is a usage error (exit 2). */
 function parseToolArgs(argsJson) {

package/dist/cli/fail.d.ts

@@ -1,34 +1,24 @@
 import { type ResolvedPlacement } from "../paths.ts";
-/**
- * The ONE error prefix every error message carries — bold red when stderr renders color, plain
- * otherwise. Errors are the only place the CLI uses color at all.
- */
+import { gateSecrets } from "../secrets-gate.ts";
+/** The ONE error prefix every error message carries — bold red when stderr renders color, plain otherwise. */
 export declare function errorPrefix(colors?: boolean): string;
 /**
- * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain
- * `Error` — print just the message. Anything else (TypeError, non-Error) is a bug: keep the stack.
- * Shared by the kernel and the command modules; exit 1 (runtime failure).
+ * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain `Error` — print
+ * just the message. Anything else (a TypeError, a non-Error throw) is a bug: keep the stack.
  */
 export declare function failStartup(error: unknown): never;
 /**
- * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
- * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
- * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
- *
- * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
- * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
- * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
- * which means a one-line `Error:` and exit 1, never a stack.
- *
- * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
- * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
- * the project-level credential and falls back to the global one, and `attach --url/--token` reads
- * nothing local. Everything else needs an agent, so it comes through here.
+ * {@link gateSecrets} at the process boundary, for a command that runs ONE owner's code (`fastagent
+ * tool`, `fastagent routine run`). The gate throws SYNCHRONOUSLY, so there is no promise to hang the usual
+ * `.catch(failStartup)` on, and a raw throw reaches `cli.ts`'s top-level await as a Node stack that
+ * buries the one line naming the file. The catch translates that expected failure into the CLI's
+ * single-line refusal and exits 1; nothing is recovered.
  */
+export declare function gateSecretsOrExit(input: Parameters<typeof gateSecrets>[0]): void;
+/** THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. */
 export declare function placementOrExit(dir: string): ResolvedPlacement;
 /**
- * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
- * discovered in a command body): print the message and exit 2 — the same class as a parse error.
- * Exit codes follow responsibility, not the layer that happens to discover the problem.
+ * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination discovered in a
+ * command body): print the message and exit 2.
  */
 export declare function failUsage(message: string): never;

package/dist/cli/fail.js

@@ -1,19 +1,16 @@
 import { resolvePlacement } from "../paths.js";
+import { gateSecrets } from "../secrets-gate.js";
 /** stderr renders color: a color TTY, with Node's `hasColors()` carrying the NO_COLOR/TERM=dumb veto. */
 function stderrHasColors() {
     return process.stderr.isTTY === true && (process.stderr.hasColors?.() ?? false);
 }
-/**
- * The ONE error prefix every error message carries — bold red when stderr renders color, plain
- * otherwise. Errors are the only place the CLI uses color at all.
- */
+/** The ONE error prefix every error message carries — bold red when stderr renders color, plain otherwise. */
 export function errorPrefix(colors = stderrHasColors()) {
     return colors ? "\x1b[1;31mError:\x1b[0m" : "Error:";
 }
 /**
- * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain
- * `Error` — print just the message. Anything else (TypeError, non-Error) is a bug: keep the stack.
- * Shared by the kernel and the command modules; exit 1 (runtime failure).
+ * User-fixable startup problems (missing model / bad config / broken definition) are thrown as plain `Error` — print
+ * just the message. Anything else (a TypeError, a non-Error throw) is a bug: keep the stack.
  */
 export function failStartup(error) {
     if (error instanceof Error && error.constructor === Error)
@@ -23,20 +20,21 @@ export function failStartup(error) {
     process.exit(1);
 }
 /**
- * THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. Every
- * command that needs an agent goes through this — the try/catch was hand-repeated at sixteen call
- * sites, which is sixteen chances to forget it (`dev`'s supervisor did, and surfaced a raw stack).
- *
- * The catch is what makes it a function at all: placement resolves SYNCHRONOUSLY, before any promise
- * exists, so it cannot ride the `.catch(failStartup)` every async startup chain carries — and its
- * refusals ("not a fastagent agent", plus the two dead ends with their own exits) are user-fixable,
- * which means a one-line `Error:` and exit 1, never a stack.
- *
- * Not every command calls it — and the exceptions are the useful part of this note. `init` CREATES the
- * agent (it must run where there is none). `models` is directory-independent. `login` needs one only for
- * the project-level credential and falls back to the global one, and `attach --url/--token` reads
- * nothing local. Everything else needs an agent, so it comes through here.
+ * {@link gateSecrets} at the process boundary, for a command that runs ONE owner's code (`fastagent
+ * tool`, `fastagent routine run`). The gate throws SYNCHRONOUSLY, so there is no promise to hang the usual
+ * `.catch(failStartup)` on, and a raw throw reaches `cli.ts`'s top-level await as a Node stack that
+ * buries the one line naming the file. The catch translates that expected failure into the CLI's
+ * single-line refusal and exits 1; nothing is recovered.
  */
+export function gateSecretsOrExit(input) {
+    try {
+        gateSecrets(input);
+    }
+    catch (error) {
+        failStartup(error);
+    }
+}
+/** THE placement entry point for commands: resolve `dir`, or exit 1 with the one-line refusal. */
 export function placementOrExit(dir) {
     try {
         return resolvePlacement(dir);
@@ -46,9 +44,8 @@ export function placementOrExit(dir) {
     }
 }
 /**
- * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination
- * discovered in a command body): print the message and exit 2 — the same class as a parse error.
- * Exit codes follow responsibility, not the layer that happens to discover the problem.
+ * A usage error the parser could not catch (a bad value shape, an invalid flag/argument combination discovered in a
+ * command body): print the message and exit 2.
  */
 export function failUsage(message) {
     console.error(`${errorPrefix()} ${message}`);

package/dist/cli/invoke-stream.d.ts

@@ -1,10 +1,3 @@
-/**
- * Render an Agent event stream to two sinks plus an exit code — the `fastagent invoke` contract, a
- * PURE function (IO injected) so it is unit-testable: text deltas → `out`; tool start + an ERRORED
- * tool_ended → `err`; `failed` → `err` + a non-zero exit code (the CI-gating guarantee).
- *
- * An errored tool inside an otherwise-completed turn still surfaces (the diagnostic the operator
- * needs); tool_ended carries no name, so it is remembered from the matching tool_started.
- */
+/** Render an Agent event stream to two sinks plus an exit code. */
 import type { AgentEvent } from "../agent.ts";
 export declare function runInvokeStream(events: AsyncIterable<AgentEvent>, out: (text: string) => void, err: (line: string) => void): Promise<number>;

package/dist/cli/kernel.d.ts

@@ -1,16 +1,4 @@
-/**
- * CLI kernel — commands as data. A {@link CommandSpec} carries everything the CLI surface needs
- * (summary, args/flags, examples, narrative notes, a lazy `run`), and {@link buildProgram} renders
- * the set through commander. Commander is called ONLY from this module; the notation specs are
- * written in — docopt-style argument brackets (`<required>`/`[optional]`), the flag DSL
- * (`--auth-path <file>`, `--no-x` negation), and the derived option keys ({@link optionKey}) — is a
- * contract this module owns and validates at build time. Replacing the parser means re-implementing
- * that notation here (one module), not editing the specs.
- *
- * Follows clig.dev: per-command help in four spellings (`-h`/`--help`/`help <cmd>`/bare-with-missing-args),
- * examples in help, "did you mean" suggestions (never auto-run), and one exit-code policy — 0 success,
- * 1 runtime failure (owned by the command bodies), 2 usage error (anything the parser itself rejects).
- */
+/** CLI kernel — commands as data. */
 import { Command } from "commander";
 /** One positional argument, in commander syntax: `<name>` required, `[dir]` optional. */
 interface ArgSpec {
@@ -20,12 +8,10 @@ interface ArgSpec {
     /** Closed value set — the parser rejects anything else as a usage error (exit 2). */
     choices?: string[];
 }
-/** One flag, in the flag DSL: `--json`, or `--auth-path <file>` for a value-taking flag. */
+/** One flag, in the flag DSL: `--json`, or `--bind <addr>` for a value-taking flag. */
 export interface FlagSpec {
     flags: string;
     description: string;
-    /** Mutually exclusive with these {@link optionKey} values — validated at build time. */
-    conflicts?: string[];
 }
 interface ExampleSpec {
     cmd: string;
@@ -46,13 +32,11 @@ export interface CommandSpec {
     /** A group command (e.g. `schedule`) declares subcommands instead of `run`. */
     subcommands?: CommandSpec[];
     /**
-     * The implementation: positional args in declaration order (an optional arg without a default is
-     * `undefined`), then the parsed flags. Lazy-import the actual work so `fastagent <cmd>` pays only
-     * for the modules that command uses. Runtime failures exit 1 from inside (fail visibly).
+     * The implementation: positional args in declaration order (an optional arg without a default is `undefined`), then
+     * the parsed flags.
      */
     run?: (args: (string | undefined)[], flags: Record<string, unknown>) => Promise<void> | void;
 }
-/** Program-level configuration. Output/exit/width seams let tests drive the program in-process. */
 export interface ProgramOptions {
     /** Printed by `-v`/`--version`. */
     version?: string;
@@ -60,29 +44,13 @@ export interface ProgramOptions {
     examples?: ExampleSpec[];
     /** Top-level closing prose (the docs link) — reflowed like any notes. */
     notes?: string;
-    /**
-     * Fixed help width — a TEST seam. Production omits it: commander then adapts to the terminal
-     * (and falls back to 80 when piped), the modern behavior. Our verbatim Examples/notes text is
-     * hand-wrapped at ≤78 columns so it reads well at any width ≥ 80 (prose caps, like man pages).
-     */
+    /** Fixed help width — a TEST seam. */
     helpWidth?: number;
-    /**
-     * Force help colors on/off — a TEST seam. Production omits it: commander detects per stream
-     * (color TTY → on; pipe, NO_COLOR, TERM=dumb → off) and strips every SGR code when off.
-     */
+    /** Force help colors on/off — a TEST seam. */
     colors?: boolean;
     out?: (chunk: string) => void;
     err?: (chunk: string) => void;
     exit?: (code: number) => never;
 }
-/**
- * The option key a flag string yields on the parsed-flags record — THE naming rule specs rely on:
- * camelCase of the long name (`--auth-path` → `authPath`); a `--no-x` flag negates and stores under
- * `x` (absent ⇒ `x !== false`). Owned and enforced here so `conflicts` references and run-body reads
- * answer to one authority, not to an implicit parser behavior. Throws on a flag without a long form
- * (clig: every flag has a full-length spelling).
- */
-export declare function optionKey(flags: string): string;
-/** Build the commander program for `specs`. The CLI entry parses with it; tests inject the IO seams. */
 export declare function buildProgram(specs: readonly CommandSpec[], options?: ProgramOptions): Command;
 export {};