@fastagent-sh/fastagent 0.21.1 → 0.22.1

package/dist/cli/shared.js

@@ -1,89 +1,49 @@
 /**
- * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report,
- * first-run model resolution, and the login terminal IO. Bodies moved verbatim from cli.ts; the
- * module-scoped flag access (`values.*`) became parameters.
+ * Helpers shared across command modules: interactivity gates, port parsing, the startup auth report, first-run model
+ * resolution, and the login terminal IO.
  */
 import { readFile, writeFile } from "node:fs/promises";
 import { relative, resolve } from "node:path";
 import { autocomplete, isCancel, log as clackLog, password, select, text as clackText } from "@clack/prompts";
 import { buildModelPickerOptions } from "./models-view.js";
 import { fastagentCredentialStore } from "../engines/pi/auth.js";
-import { isValidPort, listModels, loadConfig, providerOf, resolveAuthPath, resolveModel, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
+import { isValidPort, listModels, loadConfig, providerOf, resolveAuthLayers, resolveModelSpec, rewriteConfigModel, } from "../engines/pi/config.js";
 import { LoginCancelled, loginFlow } from "../engines/pi/login.js";
-import { createPiModelRuntime, createPiModels, probeApiKey, probeAuthSource, providerAuthStatuses, } from "../engines/pi/models.js";
+import { readMachine, withMachine } from "../engines/pi/machine.js";
+import { createPiModelRuntime, probeAuthSource, providerAuthStatuses } from "../engines/pi/models.js";
 import { formatAuthReport } from "./auth-view.js";
 import { CODING_TOOL_NAMES } from "../engines/pi/create.js";
-import { reportModuleLoadFailures } from "../loader.js";
 import { reportFindingsIfChanged, reportToolCollisions } from "../engines/pi/report.js";
-import { workspaceHint } from "../paths.js";
 import { log } from "../log.js";
-import { loadDotEnv } from "../env.js";
+import { enterAgentEnv } from "../env.js";
 import { openExternalUrl } from "../open-url.js";
-import { installProxyFetch } from "../proxy.js";
 import { bindAddress, isBindAddress } from "../bind.js";
 import { failStartup, failUsage, placementOrExit } from "./fail.js";
-/**
- * How every command that runs the model enters its agent directory, in the one order that works:
- * placement decides whose `.env` to read; `.env` may carry the proxy and the provider keys the
- * picker's auth probe needs; the picker runs last. Six commands wrote these steps out by hand, and
- * one carried the order as a comment. The result is the placement every later step reads.
- */
+/** How every command that runs the model enters its agent directory, in the one order that works. */
 export async function enterAgentCommand(dirArg, opts) {
     const placement = placementOrExit(resolve(dirArg));
-    loadDotEnv(placement.agentDir);
-    installProxyFetch();
+    enterAgentEnv(placement.agentDir);
     await resolveFirstRunModel(placement.agentDir, opts);
     return placement;
 }
-/**
- * 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
- * `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.
- *
- * Private to this module: {@link reportAssembly} is the report, and a command reaching past it for a
- * line of its own is how the two copies of that report came to differ.
- */
+/** The padded label writer for the STARTUP report (`dev`/`start`, stderr via the log level). */
 function reportLine(label, 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
- *  as one and is silent otherwise. */
-function reportWorkspaceHint(hint) {
-    if (hint)
-        reportLine("hint", hint);
-}
-/**
- * What `dev` and `start` say about the directory they just opened, in the order they say it.
- *
- * ONE function because it is one report: the two commands wrote it out line by line, and the copies
- * had already diverged over which lines exist at all — `dev` naming the config file, `start` naming
- * state and sessions. A line added to one of two hand-written copies is invisible in the other.
- *
- * The divergence itself is PRESERVED, not resolved: `start`'s `state:`/`sessions:` pair introduces the
- * persistence warnings that follow it in production posture, and `dev`'s `config:` has no counterpart
- * there. Both are passed as explicit extras by the caller, so the asymmetry is visible at the call
- * site rather than buried in two copies of a list. Whether it is RIGHT is a separate question from
- * whether it has one owner.
- *
- * Findings (skill collisions, definition diagnostics) CLOSE the report — they are about the assembly
- * just printed. What a command says next is its own posture talk, not report: `start`'s persistence
- * notes now follow them rather than precede them.
- */
+/** What `dev` and `start` say about the directory they just opened, in the order they say it. */
 export async function reportAssembly(a, extras = {}) {
     reportLine("agent", a.agentDir);
     reportLine("workspace", a.workspace);
-    reportWorkspaceHint(workspaceHint(a));
     for (const [label, value] of extras.beforeModel ?? [])
         reportLine(label, value);
     reportLine("model", `${a.modelSpec}${a.config.thinkingLevel ? ` (thinking: ${a.config.thinkingLevel})` : ""}`);
-    await reportAuth(a.agentDir, a.modelSpec, a.authPath);
+    await reportAuth(a.agentDir, a.modelSpec, a.auth);
     reportLine("context", a.definition.contextFiles.map((f) => f.path).join(", ") || "(none)");
     if (a.definition.persona)
         reportLine("persona", "persona.md");
-    reportLine("skills", a.definition.skills.map((s) => s.name).join(", ") || "(none)");
+    // What this agent HAS — the definition's skills and the ones its machine lends (machine.ts).
+    const skills = withMachine(a.definition.skills, (await readMachine(a.workspace)).skills);
+    reportLine("skills", skills.map((s) => s.name).join(", ") || "(none)");
     reportLine("codingTools", CODING_TOOL_NAMES.join(", "));
     if (a.toolNames.length > 0)
         reportLine("tools", a.toolNames.join(", "));
@@ -91,7 +51,6 @@ export async function reportAssembly(a, extras = {}) {
         reportLine("deferred", `${a.deferredToolNames.join(", ")} (activated via search_tools)`);
     }
     reportToolCollisions(a.toolCollisions);
-    reportModuleLoadFailures(a.toolFailures);
     for (const [label, value] of extras.afterTools ?? [])
         reportLine(label, value);
     reportFindingsIfChanged(a.definition.dir, a.definition);
@@ -100,12 +59,7 @@ export async function reportAssembly(a, extras = {}) {
 export function isInteractive() {
     return Boolean(process.stdin.isTTY && process.stdout.isTTY);
 }
-/**
- * Parse + range-check a port string (CLI flag or env). Empty/whitespace is "not set" → undefined, so
- * the `??` chain falls through instead of binding port 0 (`Number("")` is 0). The exit code follows
- * RESPONSIBILITY, not the layer that discovers the problem: a bad `--port` is a usage error (2), a
- * bad `PORT` env is broken runtime configuration (1).
- */
+/** Parse + range-check a port string (CLI flag or env). */
 export function parsePort(value, source, from) {
     if (value === undefined)
         return undefined;
@@ -121,9 +75,8 @@ export function parsePort(value, source, from) {
     return Number(trimmed);
 }
 /**
- * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to
- * config, then all interfaces). An unbindable string is a USAGE error (2) — caught here rather than as
- * a node bind failure, or worse, as a "the interface you bound" diagnostic downstream.
+ * Parse a `--bind` address: empty/whitespace is "not set" → undefined (the `??` chain falls through to config, then
+ * all interfaces).
  */
 export function parseBind(value) {
     const trimmed = value?.trim();
@@ -133,36 +86,33 @@ export function parseBind(value) {
         failUsage(`invalid --bind "${value}": must be an IP address or "localhost"`);
     return bindAddress(trimmed); // a name never travels past this point — see bind.ts
 }
-/** Report which source provides the model's credentials, surfacing a remediation hint at startup. Non-blocking.
- *  Probes through the AGENT's model surface (`agentDir` carries its models.json), so a custom endpoint is
- *  reported like any built-in rather than as an unknown provider. */
-export async function reportAuth(agentDir, modelSpec, authPath) {
+/** Report which source provides the model's credentials, surfacing a remediation hint at startup. */
+export async function reportAuth(agentDir, modelSpec, auth) {
     const provider = providerOf(modelSpec);
-    const models = await createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
+    const { path: authPath, fallback: fallbackAuthPath } = auth;
+    const models = await createPiModelRuntime({ agentDir, auth }).catch(failStartup);
     const source = await probeAuthSource(models, modelSpec);
-    // Only when nothing satisfies auth do we read the store (refresh-FREE) to tell "nothing stored" from
-    // "stored but unusable" — see formatAuthReport for why. store.read warns on a corrupt file itself.
-    const stored = source === undefined
-        ? await fastagentCredentialStore(authPath)
-            .read(provider)
-            .catch(() => undefined)
-        : undefined;
-    const report = formatAuthReport(provider, authPath, source, stored);
+    // One refresh-FREE read per layer, serving both questions below. A read failure is already warned about by the
+    // store itself; this line degrades to "nothing stored" rather than taking down the startup report.
+    const readFrom = (path) => fastagentCredentialStore(path)
+        .read(provider)
+        .catch(() => undefined);
+    const inPrimary = await readFrom(authPath);
+    const inFallback = inPrimary || fallbackAuthPath === undefined ? undefined : await readFrom(fallbackAuthPath);
+    // Name the layer the credential actually came from: "which file do I edit" is the question this line answers, and
+    // a global credential lives in a file the agent dir does not contain. With NEITHER layer holding it, the answer is
+    // the primary — that is the file the `fastagent login` this report recommends writes.
+    const found = fallbackAuthPath !== undefined && inFallback ? fallbackAuthPath : authPath;
+    // Only when nothing satisfies auth does the stored credential matter: it tells "nothing stored" from "stored but
+    // unusable".
+    const stored = source === undefined ? (inPrimary ?? inFallback) : undefined;
+    const report = formatAuthReport(provider, found, source, stored);
     log.info(`[fastagent] ${report.line}`);
     if (report.warn)
         log.warn(`[fastagent] ${report.warn}`);
 }
 /**
- * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE
- * funnel, no dead ends. When no model is set (flag/env/config) and we're on a TTY, show the FULL
- * catalog annotated per provider — ready (with the credential source, so which account pays is
- * visible at the decision point) or login-required — and, when the choice needs auth, run the login
- * flow INLINE instead of exiting with "run `fastagent login` and come back". A no-op when a model is
- * already set; on a non-TTY (CI, a piped stdin), with `--no-input`, on cancel, or on a failed login
- * it stays quiet and lets the caller raise its own clear error (`missing model`, or deploy's
- * model-travel gate). The pick is exported to FASTAGENT_MODEL so a spawned `dev` worker inherits it,
- * and best-effort written back to the config so the next run is quiet. `agentDir` is the resolved
- * AGENT DIR (resolvePlacement().agentDir) — config and auth both live there.
+ * First-run model resolution for every assembly command (dev/start/invoke/fire/chat/deploy): ONE funnel, no dead ends.
  */
 async function resolveFirstRunModel(agentDir, options = {}) {
     const { config, path: configPath } = await loadConfig(agentDir).catch(failStartup);
@@ -172,31 +122,24 @@ async function resolveFirstRunModel(agentDir, options = {}) {
         return; // --no-input: never prompt (clig) — the opener raises the clear error
     if (!isInteractive())
         return; // CI/deploy: the opener throws the actionable missing-model error
-    const authPath = resolveAuthPath(agentDir, options.authPath);
-    // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a
-    // self-hosted endpoint is pickable on first run instead of being invisible until hand-set.
-    const models = await createPiModelRuntime({ agentDir, authPath }).catch(failStartup);
-    const chosen = await pickWithCredentials(models, authPath);
+    const auth = resolveAuthLayers(agentDir);
+    // The picker lists the AGENT's surface: built-ins plus whatever its models.json declares, so a self-hosted endpoint
+    // is pickable on first run instead of being invisible until hand-set.
+    const models = await createPiModelRuntime({ agentDir, auth }).catch(failStartup);
+    const chosen = await pickWithCredentials(models, auth.path, agentDir);
     if (chosen === undefined)
         return; // cancelled (or auth probe failed): the caller raises its clear missing-model error
     process.env.FASTAGENT_MODEL = chosen; // this process + any spawned dev worker inherits it
     await persistModelChoice(agentDir, configPath, chosen);
 }
-/**
- * The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy —
- * remedy warnings for providers no login flow can fix (the choice is KEPT: model validity is
- * independent of credentials), or the inline login for the rest. Returns the chosen spec, or
- * undefined when the pick should be discarded (picker cancel, login cancel, a failed auth probe).
- */
-async function pickWithCredentials(models, authPath) {
+/** The credential-aware pick: full catalog annotated per provider, then the post-pick auth policy. */
+async function pickWithCredentials(models, authPath, agentDir) {
     let statuses;
     try {
         statuses = await providerAuthStatuses(models);
     }
     catch (error) {
-        // Per-provider auth throws are captured as `broken` INSIDE providerAuthStatuses; reaching here
-        // means the enumeration itself failed (getProviders / a provider with no probe-able surface) — a
-        // system fault. Surface it; the opener then still raises the clear missing-model error.
+        // Per-provider auth throws are captured as `broken` INSIDE providerAuthStatuses.
         log.warn(`[fastagent] could not probe provider auth: ${error.message}`);
         return undefined;
     }
@@ -212,9 +155,7 @@ async function pickWithCredentials(models, authPath) {
     if (status?.state === "ready")
         return chosen; // usable now — nothing to fix
     if (status && status.login === "none") {
-        // No login flow exists for this provider — KEEP the choice and name the remedy. The remedy depends
-        // on WHY it is not ready: a BROKEN stored credential still owns the provider (env is consulted
-        // only when nothing is stored — createPiModels), so "set the env var" would not help there.
+        // No login flow exists for this provider — KEEP the choice and name the remedy.
         if (status.state === "broken") {
             log.warn(`[fastagent] stored auth for "${provider}" is unusable: ${status.message} — fix or remove it in ${authPath}; invokes fail until then`);
         }
@@ -224,84 +165,21 @@ async function pickWithCredentials(models, authPath) {
         return chosen;
     }
     try {
-        // Verified against the CHOSEN model — the exact request the agent is about to make; a rejected
-        // key re-prompts inside the loop, so reaching here means a usable (or at worst unverifiable) key.
-        await loginWithKeyCheck(provider, authPath, chosen);
+        // Verified on this agent's registry, against the chosen model: the request the agent is about to make.
+        await loginFlow(terminalLoginIO(), { provider, authPath, agentDir, verifyWith: chosen });
         console.error(`[fastagent] logged in to ${provider} — saved to ${authPath}`);
     }
     catch (error) {
         if (error instanceof LoginCancelled)
             return undefined; // user backed out — discard the choice, like a picker cancel
-        // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy,
-        // and a later `fastagent login` fixes auth without re-picking the model.
+        // A FAILED login keeps the choice: the pick persists, the startup auth report names the remedy, and a later
+        // `fastagent login` fixes auth without re-picking the model.
         log.warn(`[fastagent] login for "${provider}" failed: ${error.message} — model saved; run \`fastagent login\` to fix auth`);
     }
     return chosen;
 }
-/**
- * Interactive login with the api_key quick-fail probe closed into a LOOP: a definitively rejected key
- * (HTTP 401) deletes the bad credential and RE-PROMPTS immediately — the user's hands are on the
- * keyboard NOW; parking the failure for a later `fastagent login` would waste that. The loop exits on
- * a verified/unverifiable key (kept), an OAuth login (completing the flow already proved the
- * credential), or cancel (LoginCancelled propagates to the caller's cancel policy). Used by both the
- * `login` command and the first-run picker's inline login.
- */
-export async function loginWithKeyCheck(provider, authPath, spec, 
-// Test seams: this loop DESTROYS credential state on `rejected`, so its policy (rejected → delete →
-// re-ask ONLY the key) is pinned by a test through fake flow/verify; production callers omit both.
-seams = {}) {
-    const flow = seams.flow ?? loginFlow;
-    const verify = seams.verify ?? verifyApiKeyLogin;
-    const io = terminalLoginIO();
-    let method;
-    for (;;) {
-        const result = await flow(io, { provider, authPath, method });
-        if (result.method !== "api_key")
-            return result;
-        const verdict = await verify(result.provider, authPath, spec);
-        if (verdict !== "rejected")
-            return result;
-        // Retry re-asks ONLY the key: the provider/method choices weren't the mistake, the keystrokes were.
-        provider = result.provider;
-        method = "api_key";
-    }
-}
-/**
- * Quick-fail check after an api_key login (OAuth needs none — completing the flow already proved the
- * credential): probe the stored key with one minimal request against `spec`, or the provider's first
- * model. Policy over {@link probeApiKey}'s verdict: `rejected` (definitive HTTP 401) DELETES the
- * just-stored credential — a mistyped key must not persist as plausible state — and the caller
- * ({@link loginWithKeyCheck}) re-prompts; `unknown` (network, quota, permissions) keeps it and prints
- * the provider's message: the key may still be right, and wrongly destroying a good credential costs
- * more than keeping a doubtful one.
- */
-async function verifyApiKeyLogin(provider, authPath, spec) {
-    // Built-ins only: `login` itself offers built-in providers (login.ts), and a models.json endpoint
-    // authenticates from its own `apiKey` (env/command), so there is no stored credential to verify here.
-    const models = createPiModels({ authPath });
-    const model = spec ? resolveModel(models, spec) : models.getProvider(provider)?.getModels()[0];
-    if (!model) {
-        console.error(`[fastagent] cannot verify the key: provider "${provider}" lists no models — kept as stored`);
-        return "unknown";
-    }
-    const label = `${model.provider}/${model.id}`;
-    console.error(`[fastagent] verifying the key with ${label}…`);
-    const probe = await probeApiKey(models, model);
-    if (probe.state === "ok") {
-        console.error(`[fastagent] key verified — ${label} responded`);
-    }
-    else if (probe.state === "rejected") {
-        await fastagentCredentialStore(authPath).delete(provider);
-        console.error(`[fastagent] ${provider} rejected the API key (HTTP 401): ${probe.message} — enter it again (or cancel)`);
-    }
-    else {
-        console.error(`[fastagent] could not verify the key with ${label}: ${probe.message} — kept; invokes surface the provider's error`);
-    }
-    return probe.state;
-}
-/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. Shared
- *  by the `login` command and the first-run picker's inline login. */
-function terminalLoginIO() {
+/** Login terminal IO via @clack/prompts: a searchable list once long, a hidden prompt for keys. */
+export function terminalLoginIO() {
     return {
         async select(message, options) {
             const r = await (options.length > 7 ? autocomplete : select)({ message, options });
@@ -317,15 +195,11 @@ function terminalLoginIO() {
         openUrl: openExternalUrl,
     };
 }
-/**
- * Best-effort persist the picked model so the next run does not prompt. Rewrites the commented
- * `model:` placeholder the scaffold writes / an existing `model:` line, or re-inserts the line into a
- * scaffold-shaped config (the hand-deleted-to-reset case); anything else (a hand-shaped config) is
- * left untouched with a printed hint. Never throws — persistence is a convenience.
- */
+/** Best-effort persist the picked model so the next run does not prompt. */
 async function persistModelChoice(agentDir, configPath, spec) {
     const hint = () => console.error(
-    // No "using it for this run" promise: deploy's model-travel gate rightly ignores the un-persisted pick.
+    // The pick lives in THIS process's environment only, so it serves this run and nothing that outlives it: a
+    // deployment resolves in the environment being deployed, where this machine's variables do not exist.
     `[fastagent] picked ${spec} — set \`model: ${JSON.stringify(spec)}\` in your config to persist`);
     if (!configPath)
         return hint();

package/dist/cli.js

@@ -1,12 +1,5 @@
 #!/usr/bin/env node
-/**
- * fastagent CLI — the thin entry. Everything (parsing, help, dispatch, exit-code policy) lives in
- * cli/program.ts and is loaded lazily, so `fastagent <cmd>` pays only for the module graph that
- * command actually uses (the command registry lazy-imports each implementation in turn).
- *
- * Process side effects (proxy dispatcher, .env loading, log posture, explicit exits) belong to the
- * command modules under cli/commands/ — this file must stay import-free.
- */
+/** fastagent CLI — the thin entry. */
 const { runCli } = await import("./cli/program.js");
 await runCli(process.argv);
 export {};

package/dist/collect.d.ts

@@ -19,6 +19,12 @@ import type { AgentEvent, Json } from "./agent.ts";
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
  *
+ * NOT `Stream.toAsyncIterable`. Its `return()` does interrupt the in-flight pull and close the scope,
+ * but a pull that has ALREADY resolved still hands its value back from the same `next()` — the entry
+ * guard only catches later calls. A consumer that cancels while a buffered terminal is in flight would
+ * therefore receive that terminal, which is the one thing MUST 3 forbids. The re-check after the await
+ * below is what makes the silence deterministic instead of a race.
+ *
  * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
  * generator parked in an await can still reach a `yield` on its way out (an error path that
  * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal

package/dist/collect.js

@@ -7,6 +7,12 @@
  * generator's own catch/finally already surfaced the outcome). `throw()` tears down identically
  * and rethrows the caller's error deterministically instead of poking a completed generator.
  *
+ * NOT `Stream.toAsyncIterable`. Its `return()` does interrupt the in-flight pull and close the scope,
+ * but a pull that has ALREADY resolved still hands its value back from the same `next()` — the entry
+ * guard only catches later calls. A consumer that cancels while a buffered terminal is in flight would
+ * therefore receive that terminal, which is the one thing MUST 3 forbids. The re-check after the await
+ * below is what makes the silence deterministic instead of a race.
+ *
  * Cancellation also SILENCES the stream, and that belongs here rather than in each producer: a
  * generator parked in an await can still reach a `yield` on its way out (an error path that
  * yields a terminal, say), and that yield satisfies the pending `next()` — handing a terminal

package/dist/core.d.ts

@@ -1,4 +1,5 @@
 export type { Agent, AgentEvent, ImageRef, Json, Prompt, Scope } from "./agent.ts";
+export { ABORTED_CODE, SESSION_BUSY_CODE } from "./agent.ts";
 export { collect, AgentFailure, type CollectResult } from "./collect.ts";
 export type { ModuleLoadFailure } from "./loader.ts";
 export { createInvokeHandler } from "./channels/http.ts";
@@ -7,4 +8,6 @@ export { ControlRequestError, connectAgent, connectSessionControl, type RemoteEn
 export { readBodyCapped } from "./channels/body.ts";
 export { text, textHeaders } from "./channels/respond.ts";
 export type { ChannelContext, ChannelHandler, ChannelModule, LongConnection, LongConnectionChannelModule, Routes, } from "./channel.ts";
-export { defineSchedule, type LoadedSchedule, type Schedule } from "./schedule/schedule.ts";
+export { defineRoutine, type DefineRoutineOptions, type LoadedRoutine, type Routine } from "./schedule/routine.ts";
+export { defineChannel, type DefineChannelOptions } from "./channels/define-channel.ts";
+export type { DeclaredSecret } from "./declared-secrets.ts";

package/dist/core.js

@@ -1,12 +1,14 @@
+// VALUES, not types: each caller does something DIFFERENT with these two codes (retry with backoff, skip the
+// occurrence, steer the live run instead of failing), which is why they are named at all. Without an export an
+// embedder copies the literal, and the copy is how the first-event rule goes silently wrong.
+export { ABORTED_CODE, SESSION_BUSY_CODE } from "./agent.js";
 export { collect, AgentFailure } from "./collect.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";
-// 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";
+// Mounting only.
+export { defineRoutine } from "./schedule/routine.js";
+// What a `channels/*.ts` file is written against when it needs credentials: declaring them is what
+// lets `deploy` carry them and the serve refuse to start without them.
+export { defineChannel } from "./channels/define-channel.js";

package/dist/declared-secrets.d.ts

@@ -0,0 +1,55 @@
+/**
+ * WHICH ENV VARS THIS AGENT'S CODE NEEDS, in ONE shape, wherever it was declared: `defineTool`, `defineChannel` and
+ * `defineRoutine({ secrets })`, each next to the code that reads the value.
+ *
+ * One list, two consequences:
+ *  - a serving path ASSERTS the values before it runs, so a missing one is a startup failure naming the file, not a
+ *    401 three days later;
+ *  - `deploy --run` refuses a value file that does not supply one.
+ *
+ * Agent code does not read `process.env`: each authoring surface hands back exactly the values it declared, so the
+ * declaration cannot drift from the read, and a typo is a type error. The values still travel through the process env
+ * (a provider SDK reads its own variable), and `deploy` carries the whole value file (deploy/secrets.ts) — a
+ * declaration makes a value REQUIRED, it does not decide what travels.
+ */
+/** One env var some part of the definition declared, and where that declaration is. */
+export interface DeclaredSecret {
+    /** The env-var name. */
+    name: string;
+    /** Where it was declared: "tools/x-post.ts", "routines/daily-digest.ts", "config.tools" — printed in
+     *  runbooks and failures, so it must name a place the author can open. */
+    source: string;
+}
+/**
+ * THE READ: what a code-input module declared, attributed to its file — the one implementation for
+ * `tools/`, `routines/` and `channels/`.
+ *
+ * One function, so every code input gets the same shape check: a `secrets: "FOO"` is that file's load
+ * failure, wherever it is. What a caller DOES with a bad declaration differs (push a failure and skip, or throw
+ * inside its own per-file try), so the verdict travels back as data rather than as an exception.
+ */
+export declare function readSecretDeclaration(moduleDefault: unknown, label: string): {
+    secrets: DeclaredSecret[];
+    error?: undefined;
+} | {
+    secrets?: undefined;
+    error: string;
+};
+/** Every owner's declarations as one list — what a path that runs ALL of them (a serve, a deploy)
+ *  asserts or carries. A path that runs ONE reads that owner's entry instead. */
+export declare function allSecrets(byOwner: ReadonlyMap<string, readonly DeclaredSecret[]>): DeclaredSecret[];
+/** Declared names as a stable list, first declaration winning — the form a carrier iterates. */
+export declare function dedupeSecrets(declared: readonly DeclaredSecret[]): DeclaredSecret[];
+/**
+ * The values for a declared list, as the authoring surfaces hand them to author code. A name with no
+ * value reads as `""` rather than throwing: the deploy pre-flight IMPORTS these modules on a machine
+ * that legitimately holds no secrets, and a throwing accessor would make the channel whose secrets we
+ * came to collect unloadable. Presence is guaranteed by the gate (src/secrets-gate.ts) on the paths
+ * that run the code, which is the one place that can tell "not set" from "not needed here".
+ */
+export declare function secretValues<const S extends readonly string[]>(names: S | undefined, env?: NodeJS.ProcessEnv): Record<S[number], string>;
+/** Declared names with no value in `env` — empty string counts as missing (an unset `.env` line). */
+export declare function missingSecrets(declared: readonly DeclaredSecret[], env?: NodeJS.ProcessEnv): DeclaredSecret[];
+/** "X_API_KEY, X_API_SECRET (tools/x-post.ts); SLACK_TOKEN (routines/digest.ts)" — grouped by the
+ *  file to open, since that is the unit the author fixes. */
+export declare function describeSecrets(declared: readonly DeclaredSecret[]): string;

package/dist/declared-secrets.js

@@ -0,0 +1,88 @@
+/**
+ * WHICH ENV VARS THIS AGENT'S CODE NEEDS, in ONE shape, wherever it was declared: `defineTool`, `defineChannel` and
+ * `defineRoutine({ secrets })`, each next to the code that reads the value.
+ *
+ * One list, two consequences:
+ *  - a serving path ASSERTS the values before it runs, so a missing one is a startup failure naming the file, not a
+ *    401 three days later;
+ *  - `deploy --run` refuses a value file that does not supply one.
+ *
+ * Agent code does not read `process.env`: each authoring surface hands back exactly the values it declared, so the
+ * declaration cannot drift from the read, and a typo is a type error. The values still travel through the process env
+ * (a provider SDK reads its own variable), and `deploy` carries the whole value file (deploy/secrets.ts) — a
+ * declaration makes a value REQUIRED, it does not decide what travels.
+ */
+/**
+ * What an env-var NAME may look like. Checked at the declaration, not left to the host: these names
+ * are written verbatim into a Compose file, a Fly/Railway runbook and a CloudFormation parameter, so
+ * a typo (`"X_API_KEY "`, `"my key"`) or a quote/newline produces a broken or wrong artifact whose
+ * error surfaces in someone's cloud CLI, pointing at nothing. Case is not dictated — `http_proxy` is
+ * a real variable — only the shape a shell and every artifact format agree on.
+ */
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Why an authored `secrets:` is unusable, or undefined when it is fine. A `.js` tool or a wrong type
+ *  never met TypeScript, and a malformed declaration must fail as a load error rather than be
+ *  silently dropped — the whole value of the field is that its absence is meaningful. */
+function secretNamesProblem(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        return "secrets must be an array of env-var names";
+    for (const name of value) {
+        if (typeof name !== "string" || !ENV_NAME.test(name)) {
+            return `secrets must be an array of env-var names — ${JSON.stringify(name)} is not one`;
+        }
+    }
+    return undefined;
+}
+/**
+ * THE READ: what a code-input module declared, attributed to its file — the one implementation for
+ * `tools/`, `routines/` and `channels/`.
+ *
+ * One function, so every code input gets the same shape check: a `secrets: "FOO"` is that file's load
+ * failure, wherever it is. What a caller DOES with a bad declaration differs (push a failure and skip, or throw
+ * inside its own per-file try), so the verdict travels back as data rather than as an exception.
+ */
+export function readSecretDeclaration(moduleDefault, label) {
+    const declared = moduleDefault?.secrets;
+    const problem = secretNamesProblem(declared);
+    if (problem !== undefined)
+        return { error: `${label}: ${problem}` };
+    return { secrets: (declared ?? []).map((name) => ({ name, source: label })) };
+}
+/** Every owner's declarations as one list — what a path that runs ALL of them (a serve, a deploy)
+ *  asserts or carries. A path that runs ONE reads that owner's entry instead. */
+export function allSecrets(byOwner) {
+    return [...byOwner.values()].flat();
+}
+/** Declared names as a stable list, first declaration winning — the form a carrier iterates. */
+export function dedupeSecrets(declared) {
+    const seen = new Set();
+    return declared.filter((s) => !seen.has(s.name) && seen.add(s.name));
+}
+/**
+ * The values for a declared list, as the authoring surfaces hand them to author code. A name with no
+ * value reads as `""` rather than throwing: the deploy pre-flight IMPORTS these modules on a machine
+ * that legitimately holds no secrets, and a throwing accessor would make the channel whose secrets we
+ * came to collect unloadable. Presence is guaranteed by the gate (src/secrets-gate.ts) on the paths
+ * that run the code, which is the one place that can tell "not set" from "not needed here".
+ */
+export function secretValues(names, env = process.env) {
+    const values = {};
+    for (const name of names ?? [])
+        values[name] = env[name] ?? "";
+    return values;
+}
+/** Declared names with no value in `env` — empty string counts as missing (an unset `.env` line). */
+export function missingSecrets(declared, env = process.env) {
+    return dedupeSecrets(declared).filter((s) => !env[s.name]);
+}
+/** "X_API_KEY, X_API_SECRET (tools/x-post.ts); SLACK_TOKEN (routines/digest.ts)" — grouped by the
+ *  file to open, since that is the unit the author fixes. */
+export function describeSecrets(declared) {
+    const bySource = new Map();
+    for (const { name, source } of dedupeSecrets(declared)) {
+        bySource.set(source, [...(bySource.get(source) ?? []), name]);
+    }
+    return [...bySource].map(([source, names]) => `${names.join(", ")} (${source})`).join("; ");
+}