@fastagent-sh/fastagent 0.21.0 → 0.22.0

package/dist/engines/pi/turn-kit.js

@@ -59,13 +59,7 @@ function errorSignal(error) {
     const causeCode = e.cause && typeof e.cause === "object" ? e.cause.code : undefined;
     return { status, code: e.code ?? causeCode };
 }
-/**
- * Pull the structured error `code` pi records on a failed message's diagnostics. `diagnostics`
- * accumulates across attempts (`appendAssistantMessageDiagnostic`), so the terminal cause is the LAST
- * code-bearing entry — `findLast`, not `find`: an earlier attempt's transient 503 must not classify a
- * terminal 400/auth failure as retryable. (Reverse scan rather than `findLast` — the tsconfig lib is
- * ES2022.)
- */
+/** Pull the structured error `code` pi records on a failed message's diagnostics. */
 function messageSignal(message) {
     const diagnostics = message.diagnostics ?? [];
     for (let i = diagnostics.length - 1; i >= 0; i--) {
@@ -76,14 +70,14 @@ function messageSignal(message) {
     return {};
 }
 /**
- * Terminal mapping, decided by the resolved message's stopReason: pi's prompt() resolves a message
- * with stopReason "error"/"aborted" rather than throwing, so relying on catch alone would miss this
- * entire failure class (violating SPEC MUST 1).
+ * Terminal mapping, decided by the resolved message's stopReason: pi's `prompt()` RESOLVES a message with stopReason
+ * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
+ * SPEC MUST 1.
  */
 export function toTerminal(message) {
     if (message.stopReason === "aborted") {
-        // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE}
-        // for the consumer contract (design §6).
+        // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE} for the consumer
+        // contract (design §6).
         const details = message.errorMessage ?? "run aborted";
         return { type: "failed", details, retryable: false, code: ABORTED_CODE };
     }
@@ -98,30 +92,28 @@ export function errorToTerminal(error) {
     return { type: "failed", details, retryable: classifyRetryable(details, errorSignal(error)) };
 }
 /**
- * Map prompt images to pi ImageContent, resizing each to model-friendly dimensions/size with pi's
- * Photon resizer (reused from pi-coding-agent, lazy-imported so the common no-image headless path never
- * loads the TUI module graph). A null resize (unresizable / Photon unavailable) keeps the original
- * bytes — the provider then applies its own limit.
+ * Map prompt images to pi ImageContent. `prompt()` normalizes its images itself, with the bound model's resize
+ * profile (`inputLimits.images.resize`) and format conversion, so a `"prompt"` delivery hands them over as-is.
+ * `steer`/`followUp` do not, so a `"queued"` delivery resizes here with pi's default profile: the model is not known
+ * yet when a queued message is prepared. pi's resizer is lazy-imported so the no-image path never loads its module
+ * graph.
  */
-export async function toPiPromptOptions(prompt) {
+export async function toPiPromptOptions(prompt, delivery) {
     if (!prompt.images || prompt.images.length === 0)
         return undefined;
+    if (delivery === "prompt") {
+        return { images: prompt.images.map((img) => ({ type: "image", data: img.data, mimeType: img.mimeType })) };
+    }
     const { resizeImage } = await import("@earendil-works/pi-coding-agent");
     const images = await Promise.all(prompt.images.map(async (img) => {
-        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType, {
-            maxWidth: 1568,
-            maxHeight: 1568,
-            maxBytes: 5 * 1024 * 1024,
-        }).catch(() => null);
+        const resized = await resizeImage(Buffer.from(img.data, "base64"), img.mimeType).catch(() => null);
         return resized
             ? { type: "image", data: resized.data, mimeType: resized.mimeType }
             : { type: "image", data: img.data, mimeType: img.mimeType };
     }));
     return { images };
 }
-/** The SPEC projection of the rich stream. Events with no `AgentEvent` counterpart (progress,
- *  message boundaries, run boundaries) project to null — the invoke terminal is produced from the
- *  resolved message ({@link toTerminal}), not from `run_settled`. */
+/** The SPEC projection of the rich stream. */
 export function projectAgentEvent(se) {
     switch (se.type) {
         case "message_delta": {
@@ -137,8 +129,7 @@ export function projectAgentEvent(se) {
             return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
         }
         case "retry_scheduled": {
-            // `operation` (compaction | branch_summary) stays session-plane vocabulary — a turn renderer
-            // only needs "transient failure, retrying"; the engine detail lives in the control plane.
+            // `operation` (compaction | branch_summary) stays session-plane vocabulary.
             const d = se.data;
             return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
         }
@@ -146,43 +137,3 @@ export function projectAgentEvent(se) {
             return null;
     }
 }
-// ── EventQueue: push→pull plumbing for a two-port engine ────────────────────
-//
-// Single-consumer async queue; single-threaded JS means no await interleaves between push and
-// drain, so no locking. Engines that are natively async-iterable would not need it.
-export class EventQueue {
-    buffer = [];
-    wake;
-    push(item) {
-        this.buffer.push(item);
-        const wake = this.wake;
-        this.wake = undefined;
-        wake?.();
-    }
-    /**
-     * Yield pushed events in order until `done` settles AND the buffer is drained. The terminal is
-     * produced separately (toTerminal); rejections of `done` are swallowed here (the caller awaits
-     * `run` itself) to avoid unhandled rejections.
-     */
-    async *drainUntil(done) {
-        let settled = false;
-        const onSettle = () => {
-            settled = true;
-            const wake = this.wake;
-            this.wake = undefined;
-            wake?.();
-        };
-        const finished = done.then(onSettle, onSettle);
-        while (true) {
-            while (this.buffer.length > 0) {
-                yield this.buffer.shift();
-            }
-            if (settled)
-                break;
-            await new Promise((resolve) => {
-                this.wake = resolve;
-            });
-        }
-        await finished;
-    }
-}

package/dist/engines/pi/wake-tool.d.ts

@@ -1,17 +1,9 @@
 import { type MountedTool } from "./tool.ts";
 /**
- * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"`
- * ("30m", "2h", "1d"). Undefined for anything else, INCLUDING a bare numeric string like "120": one
- * encoding, one scale. Deliberate — an LLM freely emits a number OR a numeral-string, so letting a
- * unitless string alias to a different unit than a number (120s vs 120min, 60x apart) is a silent
- * footgun the guardrail (min 60s) would mask. A rejected value comes back to the model to fix.
+ * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
+ * "1d").
  */
 export declare function parseDelayMs(input: string | number): number | undefined;
-/**
- * Append the built-in `wake` tool to `tools` — but only when `enabled` (the serving path, where the
- * scheduler poller honors a wake-up) and only when the workspace hasn't defined its own `wake` (that
- * wins, like any tool collision). The single place the mount decision + collision rule run.
- */
 export declare function withWakeTool(tools: MountedTool[], stateRoot: string, enabled: boolean): MountedTool[];
 /** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
 export declare function makeWakeTool(stateRoot: string, now?: () => Date): MountedTool;

package/dist/engines/pi/wake-tool.js

@@ -1,25 +1,10 @@
-/**
- * The built-in `wake` tool: the agent's self-scheduling surface. Calling it records a one-shot wake-up
- * (wakeups.ts); the scheduler fires it back into the SAME session, so the agent resumes THIS
- * conversation after a delay ("check the deploy in 10 minutes"). The session comes from the turn
- * context (ToolContext.sessionManager, set around the turn); the state root is closed over at build
- * time (where it is known — the workspace opener), never read from the turn.
- *
- * Mounted by the opener ONLY when `config.selfSchedule` is on AND on the serving path (`dev`/`start`, where
- * the scheduler poller honors a wake-up) — never on the one-shot `invoke`/`fire` (they exit and never poll).
- * To opt OUT: leave `selfSchedule` off (the default), or override the built-in by defining your own
- * `tools/wake.ts` (a same-name collision wins — see {@link withWakeTool}). There is no name-based tool
- * exclusion config today.
- */
+/** The built-in `wake` tool: the agent's self-scheduling surface. */
 import { z } from "zod";
 import { addWakeup, removeWakeup } from "../../schedule/wakeups.js";
 import { defineTool } from "./tool.js";
 /**
- * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"`
- * ("30m", "2h", "1d"). Undefined for anything else, INCLUDING a bare numeric string like "120": one
- * encoding, one scale. Deliberate — an LLM freely emits a number OR a numeral-string, so letting a
- * unitless string alias to a different unit than a number (120s vs 120min, 60x apart) is a silent
- * footgun the guardrail (min 60s) would mask. A rejected value comes back to the model to fix.
+ * Parse a delay to milliseconds: a number is SECONDS; a string MUST carry a unit — `"<n><s|m|h|d>"` ("30m", "2h",
+ * "1d").
  */
 export function parseDelayMs(input) {
     if (typeof input === "number")
@@ -30,17 +15,10 @@ export function parseDelayMs(input) {
     const mult = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[m[2].toLowerCase()];
     return Number(m[1]) * mult;
 }
-/**
- * Append the built-in `wake` tool to `tools` — but only when `enabled` (the serving path, where the
- * scheduler poller honors a wake-up) and only when the workspace hasn't defined its own `wake` (that
- * wins, like any tool collision). The single place the mount decision + collision rule run.
- */
 export function withWakeTool(tools, stateRoot, enabled) {
     if (!enabled)
         return tools;
     // wake/unwake are a PAIR over one store: if the workspace defines EITHER name, mount NEITHER built-in.
-    // Mixing halves would mislead — an author's wake doesn't write our wakeups store, so our unwake could
-    // never cancel what it returns ("not yours" forever); the author owns the whole concept or none of it.
     if (tools.some((t) => t.name === "wake" || t.name === "unwake"))
         return tools;
     return [...tools, makeWakeTool(stateRoot), makeUnwakeTool(stateRoot)];
@@ -92,8 +70,10 @@ export function makeWakeTool(stateRoot, now = () => new Date()) {
         },
     });
 }
-/** Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring
- *  that is no longer needed). Session-scoped — a conversation can never cancel another's. */
+/**
+ * Build the `unwake` tool: cancel one of THIS conversation's pending wake-ups by id (a wake/recurring that is no
+ * longer needed).
+ */
 function makeUnwakeTool(stateRoot) {
     return defineTool({
         name: "unwake",

package/dist/env.d.ts

@@ -1,36 +1,35 @@
 /**
- * Load a `.env` file into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence
- * on BOTH axes (verified against Node): a real env var wins over the file (an already-set key is kept),
- * and within the file a repeated key takes the LAST occurrence. Portable across Node and Bun: Bun has no
- * `process.loadEnvFile`, so we parse the file ourselves rather than depend on a Node-only entry point.
- *
- * Two phases keep the two rules distinct: parse into a map (later line overrides earlier = last-wins),
- * then apply only the keys `process.env` doesn't already have (env-wins). Minimal parser — `KEY=VALUE`
- * per line, `#` comments and blank lines skipped, surrounding matched single/double quotes stripped:
- * enough for the flat secret files fastagent reads (tokens, keys), not a full dotenv dialect (no
- * multiline, no `export`, no interpolation). A missing file throws ENOENT for the caller to treat as
- * "no .env"; any other read error propagates.
+ * Write parsed values into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence on BOTH
+ * axes (verified against Node in test/env.test.ts): a real env var wins over the file, and within the file the last
+ * occurrence wins ({@link parseEnvContent}).
  */
-export declare function loadEnvFile(file: string): void;
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). THE parser —
- *  anything else reading/deciding on .env content (e.g. `add`'s secret pre-fill) must use this, never a
- *  private re-implementation: two parsers of one dialect diverge silently. */
+export declare function applyEnvValues(values: ReadonlyMap<string, string>): void;
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
 export declare function parseEnvContent(content: string): Map<string, string>;
-/** The agent's `.env` file: `<resolved secrets dir>/.env` — default `<agentDir>/.secrets/.env`,
- *  moved together with auth.json by `FASTAGENT_SECRETS_DIR` ({@link resolveSecretsDir} in the neutral
- *  paths.ts). THE path every reader/writer of the agent's .env must use, so "where do secrets
- *  live" cannot diverge across commands. The file's OWN location resolves from the REAL environment:
- *  commands locate + load `.env` first, so a `FASTAGENT_SECRETS_DIR` set INSIDE it still relocates
- *  auth.json but cannot move the file it is read from. */
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export declare function loadEnvValues(file: string): Map<string, string>;
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
 export declare function dotEnvPath(agentDir: string, env?: NodeJS.ProcessEnv): string;
-/** The committable template: `<agentDir>/.secrets/.env.example` — deliberately NOT moved by
- *  `FASTAGENT_SECRETS_DIR`: it is authored agent surface that travels with the directory (the
- *  scaffolded `.secrets/.gitignore` un-ignores exactly it), while the real values follow the override. */
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
 export declare function envExamplePath(agentDir: string): string;
 /**
- * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link loadEnvFile}), treating a
- * MISSING file as normal (no .env) — the agent-facing entry every command + the tunnel use. `agentDir`
- * is the AGENT DIR (resolvePlacement().agentDir). Only ENOENT is swallowed; any other read error (a
- * corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
+ * follows whatever proxy that (or the ambient environment) declares.
+ *
+ * ONE function because the two steps are one fact in a fixed order — the proxy can be declared in the `.env`, so it
+ * has to be read first, and `installProxyFetch` reads the environment at construction. A command that did only half
+ * would send an authored tool, a channel's app-creation flow, or a skill download DIRECT on a machine that has no
+ * direct route. Whether a given request then uses the proxy is the dispatcher's decision, not the
+ * caller's — see {@link installProxyFetch} on loopback.
+ */
+export declare function enterAgentEnv(agentDir: string): void;
+/**
+ * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link applyEnvValues}), treating a MISSING file as
+ * normal (no .env). Commands want {@link enterAgentEnv}, which is this plus the proxy that `.env` may declare.
  */
 export declare function loadDotEnv(agentDir: string): void;

package/dist/env.js

@@ -1,30 +1,19 @@
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { log } from "./log.js";
+import { installProxyFetch } from "./proxy.js";
 import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
 /**
- * Load a `.env` file into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence
- * on BOTH axes (verified against Node): a real env var wins over the file (an already-set key is kept),
- * and within the file a repeated key takes the LAST occurrence. Portable across Node and Bun: Bun has no
- * `process.loadEnvFile`, so we parse the file ourselves rather than depend on a Node-only entry point.
- *
- * Two phases keep the two rules distinct: parse into a map (later line overrides earlier = last-wins),
- * then apply only the keys `process.env` doesn't already have (env-wins). Minimal parser — `KEY=VALUE`
- * per line, `#` comments and blank lines skipped, surrounding matched single/double quotes stripped:
- * enough for the flat secret files fastagent reads (tokens, keys), not a full dotenv dialect (no
- * multiline, no `export`, no interpolation). A missing file throws ENOENT for the caller to treat as
- * "no .env"; any other read error propagates.
+ * Write parsed values into `process.env`, matching Node's `--env-file` / `process.loadEnvFile` precedence on BOTH
+ * axes (verified against Node in test/env.test.ts): a real env var wins over the file, and within the file the last
+ * occurrence wins ({@link parseEnvContent}).
  */
-export function loadEnvFile(file) {
-    const parsed = parseEnvContent(readFileSync(file, "utf8"));
-    for (const [key, value] of parsed) {
+export function applyEnvValues(values) {
+    for (const [key, value] of values)
         if (!(key in process.env))
-            process.env[key] = value; // env-vs-file: a real env var wins
-    }
+            process.env[key] = value;
 }
-/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). THE parser —
- *  anything else reading/deciding on .env content (e.g. `add`'s secret pre-fill) must use this, never a
- *  private re-implementation: two parsers of one dialect diverge silently. */
+/** Parse .env content into key → value (the dialect above; last occurrence of a key wins). */
 export function parseEnvContent(content) {
     const parsed = new Map();
     for (const raw of content.split("\n")) {
@@ -43,50 +32,56 @@ export function parseEnvContent(content) {
     }
     return parsed;
 }
-/** The agent's `.env` file: `<resolved secrets dir>/.env` — default `<agentDir>/.secrets/.env`,
- *  moved together with auth.json by `FASTAGENT_SECRETS_DIR` ({@link resolveSecretsDir} in the neutral
- *  paths.ts). THE path every reader/writer of the agent's .env must use, so "where do secrets
- *  live" cannot diverge across commands. The file's OWN location resolves from the REAL environment:
- *  commands locate + load `.env` first, so a `FASTAGENT_SECRETS_DIR` set INSIDE it still relocates
- *  auth.json but cannot move the file it is read from. */
+/**
+ * READ a value file without entering it: the values as data, never `process.env`. This is how code reasons about an
+ * environment OTHER than its own — `deploy` resolves configuration in the environment being deployed, which this
+ * file declares, and merging it into the running process would put the two environments in one bag. A missing file
+ * is no values, which is normal.
+ */
+export function loadEnvValues(file) {
+    try {
+        return parseEnvContent(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return new Map();
+        throw error;
+    }
+}
+/** The agent's `.env` file: `<resolved secrets dir>/.env`. */
 export function dotEnvPath(agentDir, env = process.env) {
     return join(resolveSecretsDir(agentDir, env), ".env");
 }
-/** The committable template: `<agentDir>/.secrets/.env.example` — deliberately NOT moved by
- *  `FASTAGENT_SECRETS_DIR`: it is authored agent surface that travels with the directory (the
- *  scaffolded `.secrets/.gitignore` un-ignores exactly it), while the real values follow the override. */
+/** The committable template: `<agentDir>/.secrets/.env.example`. */
 export function envExamplePath(agentDir) {
     return join(agentDir, SECRETS_DIRNAME, ".env.example");
 }
 /**
- * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link loadEnvFile}), treating a
- * MISSING file as normal (no .env) — the agent-facing entry every command + the tunnel use. `agentDir`
- * is the AGENT DIR (resolvePlacement().agentDir). Only ENOENT is swallowed; any other read error (a
- * corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ * ENTER an agent directory's runtime environment: its `.env` becomes `process.env`, and this process's outbound fetch
+ * follows whatever proxy that (or the ambient environment) declares.
+ *
+ * ONE function because the two steps are one fact in a fixed order — the proxy can be declared in the `.env`, so it
+ * has to be read first, and `installProxyFetch` reads the environment at construction. A command that did only half
+ * would send an authored tool, a channel's app-creation flow, or a skill download DIRECT on a machine that has no
+ * direct route. Whether a given request then uses the proxy is the dispatcher's decision, not the
+ * caller's — see {@link installProxyFetch} on loopback.
+ */
+export function enterAgentEnv(agentDir) {
+    loadDotEnv(agentDir);
+    installProxyFetch();
+}
+/**
+ * Load the agent's `.env` ({@link dotEnvPath}) into `process.env` ({@link applyEnvValues}), treating a MISSING file as
+ * normal (no .env). Commands want {@link enterAgentEnv}, which is this plus the proxy that `.env` may declare.
  */
 export function loadDotEnv(agentDir) {
     const path = dotEnvPath(agentDir);
-    try {
-        loadEnvFile(path);
-    }
-    catch (error) {
-        if (error.code !== "ENOENT")
-            throw error;
-    }
-    // A `.env` at the agent's root is the file habit puts there, and nothing reads it. Left silent, the
-    // symptom is a setting that appears configured and is not.
-    //
-    // Scoped to keys FASTAGENT itself reads, because that is the only case we can be sure about: an agent
-    // directory can be the author's repository too (the shape `--agent-dir .` exists for), where a root
-    // `.env` is their APPLICATION's — and "move the values" would break it. Nothing here can tell those
-    // apart, so the broader guess (warn whenever the agent has no env of its own) was a warning on every
-    // boot, with destructive advice, aimed at the population that never had the problem. Channel
-    // credentials are deliberately out of scope: a channel that cannot find its token reports that itself,
-    // and it is the one that knows the name.
+    applyEnvValues(loadEnvValues(path)); // ONE definition of "a missing value file is normal" (loadEnvValues)
+    // A `.env` at the agent's root is the file habit puts there, and nothing reads it.
     const stray = join(agentDir, ".env");
     if (stray === path || !existsSync(stray))
         return;
-    const misplaced = [...parseEnvContent(readFileSync(stray, "utf8")).keys()].filter((k) => k.startsWith("FASTAGENT_"));
+    const misplaced = [...parseEnvContent(readFileSync(stray, "utf8")).keys()];
     if (misplaced.length > 0) {
         log.warn(`[fastagent] ${stray} is NOT read — it sets ${misplaced.join(", ")}, and this agent's env lives at ` +
             `${path}; move those values there`);

package/dist/index.js

@@ -1,6 +1,4 @@
 // Convenience entry: the engine-neutral core plus the pi reference implementation.
-// Contract/channel-only consumers should prefer `@fastagent-sh/fastagent/core`; pi-specific consumers
-// may use `@fastagent-sh/fastagent/pi`. The root remains the supported all-in-one surface.
 export * from "./core.js";
 export * from "./node.js";
 export * from "./session.js";

package/dist/lark.d.ts

@@ -1,4 +1,3 @@
-/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
- *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
 export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, type LarkChannelOptions, type LarkWebSocketChannelOptions, type LarkMessageEvent, type LarkMessage, type LarkRoute, type LarkFailure, } from "./channels/lark/lark.ts";
 export { larkTransport, type FeishuTransport as LarkTransport } from "./channels/feishu/shared-api.ts";

package/dist/lark.js

@@ -1,4 +1,3 @@
-/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical
- *  Feishu engine. Feishu tenants use `@fastagent-sh/fastagent/feishu`. */
+/** `@fastagent-sh/fastagent/lark` — the Lark-international compatibility surface over the canonical Feishu engine. */
 export { larkChannel, larkWebSocketChannel, defaultLarkRoute, larkEnvelope, } from "./channels/lark/lark.js";
 export { larkTransport } from "./channels/feishu/shared-api.js";

package/dist/loader.d.ts

@@ -1,48 +1,3 @@
-/** One module file a directory declares. `name` is what the domain knows it by; nothing is imported
- *  to produce this. */
-export interface InventoryEntry {
-    /** Basename without extension — the authoritative name for tools/channels/schedules. */
-    name: string;
-    /** "tools/foo.ts"-style label for errors and collisions. */
-    label: string;
-    file: string;
-}
-/**
- * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
- * without importing any of them.
- *
- * It exists because four consumers need that answer and only one of them may import: the loader
- * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
- * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
- * what counts as a module file, on how to strip the extension, on which errno means "no such
- * directory" — and a fix had to be applied in four places, which is why the fourth kept being
- * missed. There is one reading now; what to DO with a failure stays with the caller, because that
- * genuinely differs (the loader throws, the tunnel cannot).
- *
- * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
- * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
- * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
- * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
- * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
- *
- * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
- * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
- * inside it, so following a link would import from anywhere on the box past the very check meant to
- * prevent it. Do not "fix" this by following them — report them, which this does.
- *
- * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
- * consumers and only one of them imports — a listing that reports the name it cannot load reads as
- * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
- * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
- * agentcore` does) says it twice — both readings are true, and remembering what was already said
- * would mean a restart stops mentioning a skip that is still there.
- *
- * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
- * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
- * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
- * skips, return them beside the entries — do not reconstruct them from stderr.
- */
-export declare function moduleInventory(subDir: string): Promise<InventoryEntry[]>;
 export interface DiscoveredModule {
     /** Basename without extension — the authoritative name for tools/channels. */
     name: string;
@@ -53,9 +8,7 @@ export interface DiscoveredModule {
         default?: unknown;
     };
 }
-/** An agent module that failed to load, surfaced as data so its caller can report the exact file.
- *  `loadModuleDir` fills it for import failures; domain loaders add validation failures. The caller owns
- *  policy: tools/schedules may skip one bad file, while serving treats a broken declared channel as fatal. */
+/** An agent module that failed to load, surfaced as data so its caller can report the exact file. */
 export interface ModuleLoadFailure {
     /** "tools/foo.ts"-style label. */
     label: string;
@@ -63,20 +16,26 @@ export interface ModuleLoadFailure {
     /** The failure message (an import error carries {@link moduleLoadHint}). */
     message: string;
 }
-/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+/** A module the loader skipped, said once, the same way for tools, channels and routines. */
 export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;
 /**
- * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
- * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
- * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
+ * THE REFUSAL every path that is about to RUN the agent shares: an enabled file under `tools/`, `channels/` or
+ * `routines/` is a declaration, so one that cannot load means the agent is missing something its author said it
+ * has. Starting anyway announces a ready service over an absent capability — a schedule that never fires, a tool the
+ * model simply never gets — with nothing but one warning to find it by. Every failure is reported before this
+ * throws, so a boot fixes all of them at once rather than one per restart.
+ *
+ * Inspecting a definition (`info`, `fastagent tool`) is NOT this path: it must survive a broken file in order to
+ * report it.
  */
+export declare function refuseBrokenDeclarations(failures: readonly ModuleLoadFailure[]): void;
+/** Import every module the directory declares ({@link moduleInventory}). */
 export declare function loadModuleDir(subDir: string): Promise<{
     modules: DiscoveredModule[];
     failures: ModuleLoadFailure[];
 }>;
 /**
- * A hint for the two common dynamic-import failures — an uninstalled dependency or a non-ESM
- * package — and empty otherwise, so an unrelated error is reported on its own.
+ * A hint for the two common dynamic-import failures — an uninstalled dependency or a non-ESM package — and empty
+ * otherwise, so an unrelated error is reported on its own.
  */
 export declare function moduleLoadHint(error: NodeJS.ErrnoException): string;

package/dist/loader.js

@@ -20,41 +20,10 @@ function moduleName(fileName) {
     return basename(fileName, extname(fileName));
 }
 /**
- * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules",
- * without importing any of them.
- *
- * It exists because four consumers need that answer and only one of them may import: the loader
- * below, `fastagent info`'s channel listing, `--tunnel`'s webhook registration, and the deploy
- * pre-flight's schedule probe. When they each read the directory themselves they disagreed — on
- * what counts as a module file, on how to strip the extension, on which errno means "no such
- * directory" — and a fix had to be applied in four places, which is why the fourth kept being
- * missed. There is one reading now; what to DO with a failure stays with the caller, because that
- * genuinely differs (the loader throws, the tunnel cannot).
- *
- * A missing directory is an empty inventory. Everything else throws, ENOTDIR included: `channels`
- * and `schedules` are named directories, so the path existing as a FILE is a mistake in the agent
- * rather than an agent without one (`service.test.ts` pins that for `schedules`). `paths.ts` folds
- * ENOTDIR into its empty scan for the opposite reason — it asks which children HAPPEN to be agent
- * dirs, where a file simply is not one. `not_found` is a non-Node runtime's ENOENT.
- *
- * SYMLINKS ARE SKIPPED, and that is a boundary rather than an oversight: `assertInsideAgentDir`
- * guards the code-input DIRECTORY against escaping the definition, and nothing guards the entries
- * inside it, so following a link would import from anywhere on the box past the very check meant to
- * prevent it. Do not "fix" this by following them — report them, which this does.
- *
- * The skip is WARNED HERE, not handed back, because "this file is not loadable" holds for all four
- * consumers and only one of them imports — a listing that reports the name it cannot load reads as
- * "I never created it". What to do about a load FAILURE does differ per caller, so that travels as
- * data. One warning per READ, so a command that both lists and loads the same directory (`deploy
- * agentcore` does) says it twice — both readings are true, and remembering what was already said
- * would mean a restart stops mentioning a skip that is still there.
- *
- * A skip is therefore a warning ONLY, unlike a {@link ModuleLoadFailure}: it is absent from `info
- * --json` and `deploy` does not gate on it. That is the deliberate cost of one report for four
- * consumers, three of which list names and have nowhere to put data. To give a machine consumer the
- * skips, return them beside the entries — do not reconstruct them from stderr.
+ * WHAT A CODE-INPUT DIRECTORY DECLARES — the single answer to "which files here are modules", without importing any of
+ * them. Internal: the loading functions below are its only consumers.
  */
-export async function moduleInventory(subDir) {
+async function moduleInventory(subDir) {
     let dirents;
     try {
         dirents = await readdir(subDir, { withFileTypes: true });
@@ -68,8 +37,6 @@ export async function moduleInventory(subDir) {
     const sub = basename(subDir);
     const entries = [];
     // Sorted by the NAME a consumer sees, so none of them re-sorts and none can disagree about order.
-    // Filename breaks a tie: `foo.js` and `foo.ts` both read as `foo`, and the domain loaders document
-    // that the FIRST wins — deciding that here keeps it from depending on readdir's order.
     const byName = (a, b) => moduleName(a.name).localeCompare(moduleName(b.name)) || a.name.localeCompare(b.name);
     for (const dirent of dirents.sort(byName)) {
         if (!isModuleFile(dirent.name))
@@ -90,17 +57,31 @@ export async function moduleInventory(subDir) {
     }
     return entries;
 }
-/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+/** A module the loader skipped, said once, the same way for tools, channels and routines. */
 export function reportModuleLoadFailures(failures) {
     for (const f of failures)
         log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
 }
 /**
- * Import every module the directory declares ({@link moduleInventory}). A file that fails to IMPORT
- * is collected into `failures` (with {@link moduleLoadHint}) rather than thrown, so the caller can
- * report every bad file and apply domain policy; `loadTools`/`loadChannels` add validation failures
- * the same way. Entries the inventory SKIPPED are already reported by it, for every consumer.
+ * THE REFUSAL every path that is about to RUN the agent shares: an enabled file under `tools/`, `channels/` or
+ * `routines/` is a declaration, so one that cannot load means the agent is missing something its author said it
+ * has. Starting anyway announces a ready service over an absent capability — a schedule that never fires, a tool the
+ * model simply never gets — with nothing but one warning to find it by. Every failure is reported before this
+ * throws, so a boot fixes all of them at once rather than one per restart.
+ *
+ * Inspecting a definition (`info`, `fastagent tool`) is NOT this path: it must survive a broken file in order to
+ * report it.
  */
+export function refuseBrokenDeclarations(failures) {
+    if (failures.length === 0)
+        return;
+    reportModuleLoadFailures(failures);
+    // The reasons are repeated from the warnings above because this message is all an embedder catching the rejection
+    // has, and all a deployment running at FASTAGENT_LOG_LEVEL=error sees.
+    throw new Error(`failed to load: ${failures.map((f) => `${f.label} (${f.message})`).join("; ")} — fix it, or rename an ` +
+        `intentionally disabled file to *.disabled`);
+}
+/** Import every module the directory declares ({@link moduleInventory}). */
 export async function loadModuleDir(subDir) {
     const entries = await moduleInventory(subDir);
     const modules = [];
@@ -121,8 +102,8 @@ export async function loadModuleDir(subDir) {
     return { modules, failures };
 }
 /**
- * A hint for the two common dynamic-import failures — an uninstalled dependency or a non-ESM
- * package — and empty otherwise, so an unrelated error is reported on its own.
+ * A hint for the two common dynamic-import failures — an uninstalled dependency or a non-ESM package — and empty
+ * otherwise, so an unrelated error is reported on its own.
  */
 export function moduleLoadHint(error) {
     if (error.code === "ERR_MODULE_NOT_FOUND" || /Cannot find (package|module)/.test(error.message)) {