@fastagent-sh/fastagent 0.18.0 → 0.20.0

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

@@ -4,7 +4,7 @@
  * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
-import type { SessionTreeEntry } from "@earendil-works/pi-agent-core";
+import type { SessionEntry as PiSessionEntry, AgentSession } from "@earendil-works/pi-coding-agent";
 /** FastAgent's read-only port over the current conversation manager. Serving and chat adapt their
  * different concrete session implementations to this one tool-runtime contract. */
 export interface ReadonlySessionManager {
@@ -13,13 +13,22 @@ export interface ReadonlySessionManager {
         id: string;
         timestamp: string;
     }>;
-    getBranch(): Promise<SessionTreeEntry[]>;
+    getBranch(): Promise<PiSessionEntry[]>;
 }
 /**
- * The turn's tool-activation bridge — narrow closures over the CURRENT harness (invoke.ts builds it
- * per turn), so a loader tool can activate deferred tools mid-turn without tool.ts importing the
- * harness. pi records the change in the session (`active_tools_change`) and the per-invoke restore
- * (harness.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
+ * pi's AgentSession as the port above — the SAME adapter for both of its consumers: chat's resident
+ * session (session-builder.ts) and serving's per-invoke one (agent-session-factory.ts).
+ *
+ * `sessionId` is the CALLER's, not pi's. A tool correlates its own state by the id the channel
+ * minted; pi's is that id encoded into a filename-safe record name, and leaking the encoding here
+ * would hand a telegram tool `s-1001234567890` for a room it knows as `-1001234567890`.
+ */
+export declare function agentSessionManager(session: AgentSession, sessionId: string): ReadonlySessionManager;
+/**
+ * The turn's tool-activation bridge — narrow closures over the CURRENT session (bound per turn), so
+ * a loader tool can activate deferred tools mid-turn without tool.ts importing the engine. pi records
+ * the change in the session (`active_tools_change`) and the per-invoke restore
+ * (agent-session-factory.ts) carries it into later turns; defineTool's wrapper stamps the newly-activated names on
  * the tool result (`addedToolNames`) — the load point native deferred-loading providers preserve the
  * prompt-cache prefix with.
  */
@@ -32,21 +41,35 @@ export interface ToolActivation {
         description: string;
     }>;
     /** ADDITIVE activation. Unknown names are filtered out before reaching pi (whose `setActiveTools`
-     *  THROWS on them); resolves the names actually newly activated (already-active names don't repeat). */
-    activate(names: string[]): Promise<string[]>;
+     *  THROWS on them); answers the names actually newly activated (already-active names don't repeat).
+     *
+     *  SYNCHRONOUS, and that is the contract, not an implementation detail: read-modify-write against
+     *  pi's active set cannot be interleaved as long as no caller can await inside it. An async
+     *  signature would need a lock to say the same thing, and the lock is what a previous version had
+     *  — one rebuilt per tool call, so the parallel batch it existed for never met on it. If pi's
+     *  setters ever become async, this signature is where that breaks, loudly. */
+    activate(names: string[]): string[];
 }
+/**
+ * The activation bridge over a live pi session — the ONE implementation, for both consumers.
+ *
+ * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
+ * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
+ * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
+ * what a served session uses to record the delta that carries the discovery into its next turn,
+ * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
+ *
+ * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
+ */
+export declare function sessionToolActivation(session: AgentSession, onActivated?: (added: string[]) => void): ToolActivation;
 export interface TurnContext {
     /** Working directory for this execution. Falls back to process.cwd() only for an unbound direct call. */
     cwd?: string;
     /** Current conversation manager. Absent outside a FastAgent-managed agent turn. */
     sessionManager?: ReadonlySessionManager;
     /** Tool activation for the current turn. Two producers, one consumer surface: invoke.ts bridges the
-     *  serving harness; chat.ts bridges pi's AgentSession (chat emulates deferral — same loader, same
+     *  served session; chat.ts bridges the resident one (chat emulates deferral — same loader, same
      *  semantics). Absent only outside any turn (a bare `fastagent tool` run). */
     tools?: ToolActivation;
 }
 export declare const turnContext: AsyncLocalStorage<TurnContext>;
-/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
- *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
- *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
-export declare function additiveActivation(registered: string[], current: string[], names: string[]): string[];

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

@@ -4,11 +4,58 @@
  * closures. Deploy-time ambients a tool closes over at build time do NOT belong here.
  */
 import { AsyncLocalStorage } from "node:async_hooks";
+/**
+ * pi's AgentSession as the port above — the SAME adapter for both of its consumers: chat's resident
+ * session (session-builder.ts) and serving's per-invoke one (agent-session-factory.ts).
+ *
+ * `sessionId` is the CALLER's, not pi's. A tool correlates its own state by the id the channel
+ * minted; pi's is that id encoded into a filename-safe record name, and leaking the encoding here
+ * would hand a telegram tool `s-1001234567890` for a room it knows as `-1001234567890`.
+ */
+export function agentSessionManager(session, sessionId) {
+    return {
+        getSessionId: () => sessionId,
+        async getHeader() {
+            const header = session.sessionManager.getHeader();
+            if (!header)
+                throw new Error("session has no metadata header");
+            return { id: sessionId, timestamp: header.timestamp };
+        },
+        async getBranch() {
+            return session.sessionManager.getBranch();
+        },
+    };
+}
+/**
+ * The activation bridge over a live pi session — the ONE implementation, for both consumers.
+ *
+ * Serving (`agent-session-factory.ts`) and chat (`session-builder.ts`) had a copy each, identical
+ * but for the persistence line; the neighbouring `definitionResourceLoaderOptions` exists because
+ * that exact duplication drifted once before. The difference is a PARAMETER now: `onActivated` is
+ * what a served session uses to record the delta that carries the discovery into its next turn,
+ * and chat has nowhere to put one (pi's SessionContext has no active-tool set).
+ *
+ * Bind it to the SESSION, never to a tool call: the next call has to see what this one activated.
+ */
+export function sessionToolActivation(session, onActivated) {
+    return {
+        active: () => session.getActiveToolNames(),
+        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const current = session.getActiveToolNames();
+            const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
+            if (added.length === 0)
+                return added;
+            session.setActiveToolsByName([...current, ...added]);
+            onActivated?.(added);
+            return added;
+        },
+    };
+}
 export const turnContext = new AsyncLocalStorage();
-/** The additive-activation contract, in ONE place for both bridges (invoke.ts over the harness,
- *  chat.ts over pi's AgentSession): dedupe → keep registered names only (pi's setters THROW on
- *  unknown) → exclude already-active → the names to actually add (empty = nothing to set). */
-export function additiveActivation(registered, current, names) {
+/** dedupe → keep registered names only (pi's setters THROW on unknown) → exclude already-active →
+ *  the names to actually add (empty = nothing to set). */
+function additiveActivation(registered, current, names) {
     const known = new Set(registered);
     const active = new Set(current);
     return [...new Set(names)].filter((name) => known.has(name) && !active.has(name));

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

@@ -11,7 +11,7 @@ export interface ToolContext {
     sessionManager?: ReadonlySessionManager;
     /** Tool activation for the current turn (a loader tool activates {@link DefineToolOptions.deferred}
      *  tools with it — the built-in `search_tools` is one consumer). Provided by both the serving path
-     *  (invoke.ts, over the harness) and chat (over pi's AgentSession); undefined only outside any turn
+     *  (agent-session-factory.ts) and chat (session-builder.ts); undefined only outside any turn
      *  (a bare `fastagent tool` run). */
     tools?: ToolActivation;
 }
@@ -35,9 +35,9 @@ export interface DefineToolOptions<I extends z.ZodType> {
     execute: (input: z.infer<I>, ctx: ToolContext) => unknown | Promise<unknown>;
 }
 /**
- * A tool as MOUNTED: what the harness actually runs. Wider than the authored {@link AgentTool} on
- * purpose — pi's default coding tools read the turn's tool context (its ExecutionEnv) as a fifth
- * `execute` parameter, while fastagent's own tools take four and are assignable to it unchanged.
+ * A tool as MOUNTED: what the engine actually runs. Wider than the authored {@link AgentTool} on
+ * purpose — a lower-level mounted tool may read an `ExecutionEnv` from the fifth `execute` parameter,
+ * while coding-agent's cwd-bound tools ignore it and fastagent's authored tools take four arguments.
  * Naming the wider type is what lets `defineTool` stay context-free for authors while both families
  * live in one array; every helper that only inspects or reorders tools is typed on THIS.
  */
@@ -73,7 +73,7 @@ export declare function loadTools(dir: string): Promise<{
     failures: ModuleLoadFailure[];
 }>;
 /**
- * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
 export declare function mergeDiscoveredTools(existing: MountedTool[], discovered: AgentTool[]): {

package/dist/engines/pi/tool.js

@@ -62,9 +62,9 @@ export function defineTool(options) {
             const tools = store?.tools
                 ? {
                     ...store.tools,
-                    activate: async (names) => {
+                    activate: (names) => {
                         // biome-ignore lint/style/noNonNullAssertion: guarded by the ternary above
-                        const activated = await store.tools.activate(names);
+                        const activated = store.tools.activate(names);
                         added.push(...activated);
                         return activated;
                     },
@@ -116,7 +116,7 @@ export async function loadTools(dir) {
     return { tools: [...byName.values()], collisions, failures };
 }
 /**
- * Merge resolved tools (pi defaults + `config.tools`) with discovered `tools/`, deduped by name.
+ * Merge resolved tools (pi coding tools + `config.tools`) with discovered `tools/`, deduped by name.
  * Existing tools win; dropped discovered tools surface as collisions.
  */
 export function mergeDiscoveredTools(existing, discovered) {

package/dist/engines/pi/turn-kit.d.ts

@@ -1,19 +1,22 @@
 /**
- * The turn mechanism's pi-CLASS-neutral half, shared by every pi L0. Not "engine-neutral" in this
- * repo's sense — that term is reserved for code with no engine import at all (src/agent.ts), and
- * everything here speaks pi's message and image types. What it is neutral about is which pi class
- * runs the turn.
+ * The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. Not
+ * "engine-neutral" in this repo's sense — that term is reserved for code with no engine import at
+ * all (src/agent.ts), and the terminals here read pi's message shape. What they do not touch is how
+ * a turn is driven, which is why they survived the engine change unaltered.
  *
  *   Lease       — single-writer concurrency floor (injectable port + in-process default)
  *   Terminals   — a settled pi message or a thrown error → the SPEC terminal, `retryable` included
  *   EventQueue  — push→pull plumbing for engines that emit events beside their result
  *   Prompt prep — SPEC images → pi's ImageContent
+ *   Projection  — the rich SessionEvent stream → the narrow SPEC one
+ *   Observation — the seam a control-plane hub attaches to (RunControls + SessionObserver)
  *
- * What is NOT neutral — the harness's event vocabulary and its observation plane — stays in
- * invoke.ts, and the AgentSession's in invoke-session.ts.
+ * What is NOT neutral — pi's event vocabulary and how a turn is driven — stays in invoke-session.ts,
+ * the L0 that owns it.
  */
 import type { AssistantMessage, ImageContent } from "@earendil-works/pi-ai";
 import { type AgentEvent, type Prompt } from "../../agent.ts";
+import type { SessionEvent } from "../../session.ts";
 export type Release = () => void;
 export interface Lease {
     /** Try to acquire exclusive write access for the session (fail-fast). Returns null if held. */
@@ -43,6 +46,29 @@ export declare function errorToTerminal(error: unknown): Extract<AgentEvent, {
 export declare function toPiPromptOptions(prompt: Prompt): Promise<{
     images?: ImageContent[];
 } | undefined>;
+/** Live modulation handles for one active run — what the control plane's `dispatch` routes to.
+ *  Built inside the turn (it owns the engine instance); registered with the observer at
+ *  run_started, gone after run_settled. RACE WINDOW (all three commands, symmetric): the run may
+ *  resolve between the settled-check and the engine call landing — an accepted `abort` can still
+ *  settle `completed`, and an accepted `steer`/`followUp` can settle without the prompt ever being
+ *  consumed. Acceptance is not outcome; the settlement is the truth. */
+export interface RunControls {
+    steer(prompt: Prompt): Promise<void>;
+    followUp(prompt: Prompt): Promise<void>;
+    abort(): Promise<void>;
+}
+/** The DATA-plane observation seam: every rich event of every run, pushed as it happens. `run`
+ *  carries the live {@link RunControls}, attached to the `run_started` event only. A hub
+ *  (session-control.ts) implements this to serve `events()`/`state()`/`dispatch`; absent = zero
+ *  overhead. Scope: RUN events only — the hub's own boundary-mutation events (`state_changed`,
+ *  `compaction_*`) originate in the hub and reach full-vocabulary taps via the hub's `tap` option,
+ *  not this seam. TRUST BOUNDARY: this seam hands every wired observer the run's modulation handles — it is the trusted hub seam, not a public fan-out point. Do not wire
+ *  untrusted taps here; give third parties the read-only `events()` stream instead. */
+export type SessionObserver = (session: string, event: SessionEvent, run?: RunControls) => void;
+/** 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`. */
+export declare function projectAgentEvent(se: SessionEvent): AgentEvent | null;
 export declare class EventQueue<T> {
     private buffer;
     private wake?;

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

@@ -82,7 +82,7 @@ function messageSignal(message) {
  */
 export function toTerminal(message) {
     if (message.stopReason === "aborted") {
-        // A deliberate stop (control-plane abort / harness abort), not an error — see {@link ABORTED_CODE}
+        // 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 };
@@ -119,6 +119,33 @@ export async function toPiPromptOptions(prompt) {
     }));
     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`. */
+export function projectAgentEvent(se) {
+    switch (se.type) {
+        case "message_delta": {
+            const d = se.data;
+            return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
+        }
+        case "tool_started": {
+            const d = se.data;
+            return { type: "tool_started", id: d.id, name: d.name, args: d.args };
+        }
+        case "tool_finished": {
+            const d = se.data;
+            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.
+            const d = se.data;
+            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
+        }
+        default:
+            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

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

@@ -2,7 +2,7 @@
  * 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 harness turn); the state root is closed over at build
+ * 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

package/dist/env.js

@@ -1,6 +1,5 @@
-import { readFileSync } from "node:fs";
+import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { existsSync } from "node:fs";
 import { log } from "./log.js";
 import { SECRETS_DIRNAME, resolveSecretsDir } from "./paths.js";
 /**

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./core.ts";
+export * from "./node.ts";
 export * from "./session.ts";
 export * from "./pi.ts";

package/dist/index.js

@@ -2,5 +2,6 @@
 // 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";
 export * from "./pi.js";

package/dist/loader.d.ts

@@ -1,5 +1,48 @@
-/** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export declare function isModuleFile(name: string): boolean;
+/** 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;
@@ -21,11 +64,10 @@ export interface ModuleLoadFailure {
     message: string;
 }
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. 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. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * 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.
  */
 export declare function loadModuleDir(subDir: string): Promise<{
     modules: DiscoveredModule[];

package/dist/loader.js

@@ -9,40 +9,101 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 import { readdir } from "node:fs/promises";
 import { basename, extname, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { log } from "./log.js";
 const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
 /** Whether `name` is an importable agent module (a discovery candidate, not a type declaration). */
-export function isModuleFile(name) {
+function isModuleFile(name) {
     return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
 }
+/** The name a module is known by: its basename without the extension. */
+function moduleName(fileName) {
+    return basename(fileName, extname(fileName));
+}
 /**
- * Import every module file in `subDir`, sorted by name. Missing dir returns none. 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. (A missing DIRECTORY still returns empty; an unreadable directory still throws
- * — that's not a per-file problem.)
+ * 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 async function loadModuleDir(subDir) {
-    let entries;
+export async function moduleInventory(subDir) {
+    let dirents;
     try {
-        entries = await readdir(subDir, { withFileTypes: true });
+        dirents = await readdir(subDir, { withFileTypes: true });
     }
     catch (error) {
-        const e = error;
-        if (e.code === "ENOENT" || e.code === "not_found")
-            return { modules: [], failures: [] };
+        const code = error.code;
+        if (code === "ENOENT" || code === "not_found")
+            return [];
         throw new Error(`cannot read ${subDir}: ${error.message}`);
     }
     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))
+            continue;
+        const label = `${sub}/${dirent.name}`;
+        if (dirent.isFile()) {
+            entries.push({ name: moduleName(dirent.name), label, file: join(subDir, dirent.name) });
+        }
+        else if (dirent.isSymbolicLink()) {
+            log.warn(`[fastagent] ${label} is a symlink — code inputs must be real files inside the agent dir — not loaded`);
+        }
+        else if (dirent.isDirectory()) {
+            log.warn(`[fastagent] ${label} is a directory, not a file — not loaded`);
+        }
+        else {
+            log.warn(`[fastagent] ${label} is not a regular file — not loaded`);
+        }
+    }
+    return entries;
+}
+/**
+ * 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.
+ */
+export async function loadModuleDir(subDir) {
+    const entries = await moduleInventory(subDir);
     const modules = [];
     const failures = [];
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !isModuleFile(entry.name))
-            continue;
-        const file = join(subDir, entry.name);
-        const label = `${sub}/${entry.name}`;
+    for (const { name, label, file } of entries) {
         try {
             const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
-            modules.push({ name: basename(entry.name, extname(entry.name)), label, file, mod });
+            modules.push({ name, label, file, mod });
         }
         catch (error) {
             failures.push({

package/dist/log.d.ts

@@ -23,4 +23,7 @@ export declare function createLogger(opts: {
 /** Set the posture default. A valid `FASTAGENT_LOG_LEVEL` override, if present, wins and is not changed. */
 export declare function setLogLevel(level: LogLevel): void;
 /** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
+import type { ModuleLoadFailure } from "./loader.ts";
 export declare const log: Logger;
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export declare function reportModuleLoadFailures(failures: readonly ModuleLoadFailure[]): void;

package/dist/log.js

@@ -47,5 +47,9 @@ const emit = (level) => (msg) => {
     if (ORDER[level] >= ORDER[currentLevel])
         console.error(format(level, msg));
 };
-/** The process logger. Runtime code imports this and calls `log.info(...)` etc. */
 export const log = { debug: emit("debug"), info: emit("info"), warn: emit("warn"), error: emit("error") };
+/** A module the loader skipped, said once, the same way for tools, channels and schedules. */
+export function reportModuleLoadFailures(failures) {
+    for (const f of failures)
+        log.warn(`[fastagent] ${f.label} failed to load, skipping it — ${f.message}`);
+}

package/dist/node.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Binding a Fetch handler to a Node HTTP server.
+ *
+ * Its own entry point because it is the one piece of the neutral surface that is RUNTIME-specific:
+ * `@hono/node-server` bridges `node:http` ↔ Fetch, and that package is the only third-party weight
+ * anywhere behind `/core`. Keeping it here lets a channel package or another engine import the
+ * contract without pulling a Node HTTP bridge it will never call — and lets a non-Node runtime
+ * (Workers, Deno, Bun's own server) consume `/core` unchanged.
+ *
+ * Engine-neutral is not the same as runtime-neutral, and the two properties give the surface its
+ * three layers: `/core` is both (contract, fetch-shaped kit), `/node` is engine-neutral only (this
+ * file: the assembly and the HTTP binding, which need a filesystem, a clock and an environment),
+ * `/pi` is neither (it names an engine).
+ */
+export { nodeListener, serveNode } from "./channels/serve.ts";
+export { mountAgentService, type AgentService, type MountableAgent, type MountAgentServiceOptions, } from "./service.ts";

package/dist/node.js

@@ -0,0 +1,20 @@
+/**
+ * Binding a Fetch handler to a Node HTTP server.
+ *
+ * Its own entry point because it is the one piece of the neutral surface that is RUNTIME-specific:
+ * `@hono/node-server` bridges `node:http` ↔ Fetch, and that package is the only third-party weight
+ * anywhere behind `/core`. Keeping it here lets a channel package or another engine import the
+ * contract without pulling a Node HTTP bridge it will never call — and lets a non-Node runtime
+ * (Workers, Deno, Bun's own server) consume `/core` unchanged.
+ *
+ * Engine-neutral is not the same as runtime-neutral, and the two properties give the surface its
+ * three layers: `/core` is both (contract, fetch-shaped kit), `/node` is engine-neutral only (this
+ * file: the assembly and the HTTP binding, which need a filesystem, a clock and an environment),
+ * `/pi` is neither (it names an engine).
+ */
+export { nodeListener, serveNode } from "./channels/serve.js";
+// The assembly: a MountableAgent becomes a mounted service. Engine-neutral — it reads the SPEC
+// contract plus three paths, so a second engine reuses it with its own opener — but NOT runtime
+// neutral: it reads a directory, a cron and an environment. That is what makes this its entry
+// rather than `/core`.
+export { mountAgentService, } from "./service.js";

package/dist/paths.d.ts

@@ -136,9 +136,35 @@ export declare function resolveStateRoot(dir: string, env?: NodeJS.ProcessEnv):
  * auth.json but cannot move the file it is read from (env.ts dotEnvPath).
  */
 export declare function resolveSecretsDir(dir: string, env?: NodeJS.ProcessEnv): string;
+/** What a file under {@link resolveSecretsDir} is written with (auth.json, .env). */
+export declare const SECRET_FILE_MODE = 384;
+/**
+ * Create the secrets directory with the mode its contents require — and REPAIR it when it already
+ * exists, which is the case that matters.
+ *
+ * The DIRECTORY is the boundary that actually protects a credential: without its `x` bit nothing
+ * below it is reachable, whatever a file's own mode says. And it is decided ONCE, by whichever
+ * writer gets there first — `mkdir`'s `mode` is ignored for a directory that already exists, so a
+ * later, more careful caller silently inherits the first one's answer. Four callers create this
+ * directory (`init`, `add <channel>`, the credential store, the deploy seed) and the ordinary order
+ * is init → add → login, so the careful one is LAST: the rule has to live where all of them can
+ * reach it, and it has to chmod rather than trust the create.
+ *
+ * A chmod the caller never asked for owes them its reason: the raw `EPERM ... chmod '/shared/creds'`
+ * reads as a bug in whatever they WERE doing (storing a credential), not as fastagent tightening a
+ * directory they pointed it at, and says nothing about the way out.
+ */
+export declare function ensureSecretsDir(dir: string): Promise<void>;
 /**
  * Guard that `<agentDir>/<name>` resolves INSIDE the agent dir — a symlink that escapes (or an
  * absolute target) is rejected, so discovery/scaffolding never reaches out of the definition directory.
  * A missing target is fine (nothing to guard yet).
  */
 export declare function assertInsideAgentDir(agentDir: string, name: string): Promise<void>;
+/**
+ * Whether `targetPath` lives inside `baseDir` (same path counts). Used to ask "did an override move
+ * this OUT of the agent?" — the startup report's redeploy notes, `add`'s printed `.env` label, and the
+ * dev watcher's "your .env is not watched" warning all turn on that fact. Reporting only: fastagent
+ * does not act on where a user's paths point.
+ */
+export declare function isUnderDir(targetPath: string, baseDir: string): boolean;