@fastagent-sh/fastagent 0.12.0

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

@@ -0,0 +1,20 @@
+import type { AgentTool } from "@earendil-works/pi-agent-core";
+/**
+ * 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.
+ */
+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: AgentTool[], stateRoot: string, enabled: boolean): AgentTool[];
+/** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
+export declare function makeWakeTool(stateRoot: string, now?: () => Date): AgentTool;
+/** 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. */
+export declare function makeUnwakeTool(stateRoot: string): AgentTool;

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

@@ -0,0 +1,110 @@
+/**
+ * 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.session, set around the harness 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.
+ */
+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.
+ */
+export function parseDelayMs(input) {
+    if (typeof input === "number")
+        return Number.isFinite(input) && input > 0 ? input * 1000 : undefined;
+    const m = input.trim().match(/^(\d+(?:\.\d+)?)\s*(s|m|h|d)$/i); // unit REQUIRED on a string
+    if (!m)
+        return undefined;
+    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)];
+}
+/** Build the `wake` tool bound to `stateRoot` (where wake-ups persist). */
+export function makeWakeTool(stateRoot, now = () => new Date()) {
+    return defineTool({
+        name: "wake",
+        description: "Schedule yourself to wake up later and continue in THIS conversation. ONE-SHOT: pass `in` — a " +
+            'duration string with a unit ("30m", "2h", "1d") or a number of seconds — to resume a task after a ' +
+            "delay. RECURRING: pass `cron` (5-field, optional `tz`) to wake repeatedly — use sparingly, and " +
+            "`unwake` with the returned id when the job is done. Exactly one of `in`/`cron`. When the time " +
+            "comes, a new turn runs in this same session with `prompt` as its instruction (tagged with the wake-up's " +
+            "id so you can tell it from a user message) — you keep the full context of this conversation. IMPORTANT: the woken turn's plain reply is NOT delivered to anyone — " +
+            "to reach the user it must call a delivery tool (e.g. a channel's send tool), exactly as a scheduled " +
+            "job would.",
+        input: z.object({
+            in: z
+                .union([z.string(), z.number()])
+                .optional()
+                .describe('one-shot delay: a duration string with a unit ("30m" / "2h" / "1d"), or a number of seconds'),
+            cron: z.string().optional().describe('recurring: a 5-field cron expression (e.g. "0 9 * * *")'),
+            tz: z.string().optional().describe('IANA timezone for `cron` (default "UTC")'),
+            prompt: z.string().min(1).describe("the instruction for the woken turn (runs in this same conversation)"),
+        }),
+        execute(input, ctx) {
+            if (!ctx.session)
+                return "wake is only available inside a conversation (there is no session to resume).";
+            if ((input.in === undefined) === (input.cron === undefined)) {
+                return "pass exactly one of `in` (one-shot) or `cron` (recurring).";
+            }
+            if (input.cron !== undefined) {
+                // addWakeup validates the cron and DERIVES the first instant itself — one computation, one truth.
+                const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, cron: input.cron, tz: input.tz }, now());
+                if (!r.ok)
+                    return r.error; // guardrail message the model can act on
+                return `OK — recurring wake ${r.id} (cron "${input.cron}"${input.tz ? ` ${input.tz}` : ""}), first at ${r.fireAt}: ${input.prompt}. Use unwake({ id: "${r.id}" }) to stop it.`;
+            }
+            const ms = parseDelayMs(input.in);
+            if (ms === undefined) {
+                return `couldn't parse "in" (${JSON.stringify(input.in)}) — use a unit like "30m" / "2h" / "1d", or a number of seconds (a bare number as text like "120" is rejected).`;
+            }
+            const at = new Date(now().getTime() + ms);
+            const r = addWakeup(stateRoot, { session: ctx.session, prompt: input.prompt, fireAt: at }, now());
+            if (!r.ok)
+                return r.error; // guardrail message the model can act on
+            return `OK — I'll wake up at ${r.fireAt} (id ${r.id}) to: ${input.prompt}. Use unwake({ id: "${r.id}" }) if it becomes unnecessary.`;
+        },
+    });
+}
+/** 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. */
+export function makeUnwakeTool(stateRoot) {
+    return defineTool({
+        name: "unwake",
+        description: "Cancel one of YOUR pending wake-ups (one-shot or recurring) by the id `wake` returned. Use it when " +
+            "a scheduled follow-up is no longer needed — especially to stop a recurring wake once its job is done.",
+        input: z.object({ id: z.string().min(1).describe("the wake-up id (returned by `wake`)") }),
+        execute(input, ctx) {
+            if (!ctx.session)
+                return "unwake is only available inside a conversation.";
+            return removeWakeup(stateRoot, input.id, ctx.session)
+                ? `OK — wake-up ${input.id} cancelled.`
+                : `no pending wake-up ${input.id} in this conversation (already fired, or not yours).`;
+        },
+    });
+}

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

@@ -0,0 +1,53 @@
+import type { Agent } from "../../agent.ts";
+import { type FastagentConfig } from "./config.ts";
+import type { ModuleLoadFailure } from "../../loader.ts";
+import { type LoadedDefinition } from "./definition.ts";
+import type { ToolCollision } from "./tool.ts";
+export interface CreatePiAgentFromWorkspaceOptions {
+    /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
+    model?: string;
+    /**
+     * Session store directory. Default `<dir>/.fastagent/sessions` (gitignored machine state). `start`
+     * overrides it (--sessions-dir / FASTAGENT_SESSIONS_DIR / a mounted volume) so production continuity
+     * survives redeploys.
+     */
+    sessionsDir?: string;
+    /**
+     * Credentials file override. Default `<dir>/.fastagent/auth.json` (project-level, gitignored under
+     * the same `*`-ignored `.fastagent`). Override via --auth-path / FASTAGENT_AUTH_PATH; point it at
+     * `~/.fastagent/auth.json` to share one credential across projects.
+     */
+    authPath?: string;
+    /**
+     * This is a long-running SERVE (`dev`/`start`), where the scheduler poller runs — so a self-scheduled
+     * wake-up is actually honored. One-shot entries (`invoke`/`fire`) leave it off (they exit after the turn
+     * and never poll). The built-in `wake` tool mounts only when this is set AND `config.selfSchedule` is on.
+     */
+    serving?: boolean;
+}
+/**
+ * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
+ * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
+ * to report what it assembled.
+ */
+export declare function createPiAgentFromWorkspace(dir: string, options?: CreatePiAgentFromWorkspaceOptions): Promise<{
+    agent: Agent;
+    definition: LoadedDefinition;
+    config: FastagentConfig;
+    configPath?: string;
+    /** The resolved "provider/modelId" spec actually in use. */
+    modelSpec: string;
+    /** Absolute agent-definition dir in use (config.agentDir resolved against dir; = dir when unset). Channels/tools/persona come from here. */
+    agentDir: string;
+    /** Absolute state root in use (FASTAGENT_STATE_DIR > <dir>/.fastagent) — the ChannelContext's stateRoot. */
+    stateRoot: string;
+    /** Absolute session store directory in use (for the startup report). */
+    sessionsDir: string;
+    /** Absolute credentials file in use (for the startup report). */
+    authPath: string;
+    /** Non-default tool names in effect: config.tools + discovered tools/. */
+    toolNames: string[];
+    toolCollisions: ToolCollision[];
+    /** `tools/` files that failed to import — skipped, reported by the caller, never fatal. */
+    toolFailures: ModuleLoadFailure[];
+}>;

package/dist/engines/pi/workspace.js

@@ -0,0 +1,70 @@
+/**
+ * Open a definition directory into an agent — the single workspace opener BOTH `fastagent dev` and
+ * `fastagent start` drive.
+ *
+ * A thin command-posture composition over L2 `createPiAgentFromDefinition`: open the directory →
+ * resolve model (flag > env > config) and tools (append-after-defaults) → pick session storage →
+ * call L2. dev and start share the SAME assembly here (what you iterate is what you serve); they
+ * differ only at the CLI — dev watches and uses the in-tree sessions default, start runs without
+ * watch and can point sessions at a mounted volume.
+ */
+import { mkdir } from "node:fs/promises";
+import { defaultAuthPath, defaultSessionsDir, loadConfig, resolveAgentDir, resolveModelSpec, resolveStateRoot, } from "./config.js";
+import { createPiAgentFromDefinition, resolveWorkspaceTools } from "./create.js";
+import { withWakeTool } from "./wake-tool.js";
+import { ensureStateRootSelfIgnored } from "./definition.js";
+import { jsonlSessionStore } from "./sessions.js";
+/**
+ * "Point at a workspace → agent": load the config, resolve model and tools, then L2. Throws a clear
+ * error when no model source is set (fail visibly at startup). Returns everything an entry point needs
+ * to report what it assembled.
+ */
+export async function createPiAgentFromWorkspace(dir, options = {}) {
+    const { config, path: configPath } = await loadConfig(dir);
+    const modelSpec = resolveModelSpec(options.model, config);
+    if (!modelSpec) {
+        throw new Error(`missing model: set --model, "model" in fastagent.config.ts, or FASTAGENT_MODEL (e.g. "openai-codex/gpt-5.5")`);
+    }
+    // The run root is `dir` (cwd — where config lives, whose AGENTS.md is ② context); the agent's own
+    // surface (persona/skills/tools/channels) lives in `agentDir` (config.agentDir, or `dir` when flat).
+    const agentDir = resolveAgentDir(dir, config);
+    const { tools, toolNames, toolCollisions, toolFailures } = await resolveWorkspaceTools(config, agentDir, dir);
+    // The state root: auth/sessions/channel state all derive from it, so FASTAGENT_STATE_DIR moves the
+    // whole machine-state home in one knob (a container mounts one volume); the finer overrides below
+    // still win for their specific path.
+    const stateRoot = resolveStateRoot(dir);
+    // Mount the built-in `wake` tool only when BOTH: this is a long-running serve (the poller honors it) AND
+    // the author opted into self-scheduling (config.selfSchedule). The workspace's own `wake` wins if defined.
+    const mountedTools = withWakeTool(tools, stateRoot, !!options.serving && !!config.selfSchedule);
+    const sessionsDir = options.sessionsDir ?? defaultSessionsDir(stateRoot);
+    await mkdir(sessionsDir, { recursive: true });
+    // The credentials file: project-level by default (under the self-ignored state root); only READ here,
+    // so no mkdir (a missing file reads as not-configured — `fastagent login` creates it).
+    const authPath = options.authPath ?? defaultAuthPath(stateRoot);
+    // Self-ignore the state root iff it lands in-tree — which covers everything under it (sessions, auth,
+    // every channel's `channels/<kind>` home), including a custom in-tree `FASTAGENT_STATE_DIR`. A
+    // per-path override to an external volume is out-of-tree and correctly left alone.
+    await ensureStateRootSelfIgnored(dir, stateRoot);
+    const { agent, definition } = await createPiAgentFromDefinition(agentDir, {
+        model: modelSpec,
+        cwd: dir,
+        tools: mountedTools,
+        authPath,
+        // Skills are definition-only (the agent is its directory), so dev mirrors deployment exactly.
+        sessions: jsonlSessionStore({ dir: sessionsDir, cwd: dir }),
+    });
+    return {
+        agent,
+        definition,
+        agentDir,
+        config,
+        configPath,
+        modelSpec,
+        stateRoot,
+        sessionsDir,
+        authPath,
+        toolNames,
+        toolCollisions,
+        toolFailures,
+    };
+}

package/dist/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+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 parseEnvContent(content: string): Map<string, string>;
+/**
+ * Load `<dir>/.env` into `process.env` ({@link loadEnvFile}), treating a MISSING file as normal (no .env)
+ * — the workspace-facing entry every command + the tunnel use. Only ENOENT is swallowed; any other read
+ * error (a corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ */
+export declare function loadDotEnv(dir: string): void;

package/dist/env.js

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * 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.
+ */
+export function loadEnvFile(file) {
+    const parsed = parseEnvContent(readFileSync(file, "utf8"));
+    for (const [key, value] of parsed) {
+        if (!(key in process.env))
+            process.env[key] = value; // env-vs-file: a real env var wins
+    }
+}
+/** 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 function parseEnvContent(content) {
+    const parsed = new Map();
+    for (const raw of content.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq < 1)
+            continue; // no `=`, or an empty key
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        const quote = value[0];
+        if ((quote === '"' || quote === "'") && value.at(-1) === quote)
+            value = value.slice(1, -1);
+        parsed.set(key, value); // in-file: last occurrence wins (Map overwrite)
+    }
+    return parsed;
+}
+/**
+ * Load `<dir>/.env` into `process.env` ({@link loadEnvFile}), treating a MISSING file as normal (no .env)
+ * — the workspace-facing entry every command + the tunnel use. Only ENOENT is swallowed; any other read
+ * error (a corrupt/unreadable file) propagates, so a real problem surfaces instead of silently skipping.
+ */
+export function loadDotEnv(dir) {
+    try {
+        loadEnvFile(join(dir, ".env"));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}

package/dist/github.d.ts

@@ -0,0 +1,3 @@
+/** `@fastagent-sh/fastagent/github` — the GitHub channel subpath export, kept off the root surface. */
+export { githubChannel, type GithubChannelOptions, type GithubEvent, type Intent, } from "./channels/github/github.ts";
+export type { Schema } from "@octokit/webhooks-types";

package/dist/github.js

@@ -0,0 +1,2 @@
+/** `@fastagent-sh/fastagent/github` — the GitHub channel subpath export, kept off the root surface. */
+export { githubChannel, } from "./channels/github/github.js";

package/dist/host/node.d.ts

@@ -0,0 +1,41 @@
+import type { Agent } from "../agent.ts";
+/** A mounted request handler (a channel's fetch, or a plain route like health). */
+export type ChannelHandler = (req: Request) => Response | Promise<Response>;
+/** This deployment's HTTP surface: route key → handler. Key is `"/path"` or `"METHOD /path"`. */
+export type Routes = Record<string, ChannelHandler>;
+/**
+ * What the framework hands a channel at mount time: the assembled agent plus the resolved state ROOT
+ * (absolute; `FASTAGENT_STATE_DIR` > `<dir>/.fastagent`). Channels derive their OWN durable home from
+ * it (`<stateRoot>/channels/<kind>/`) — they never anchor on `process.cwd()`. env is the OPERATOR
+ * input plane; this context is how the resolved result reaches code (embedders without the workspace
+ * opener construct it explicitly).
+ */
+export interface ChannelContext {
+    agent: Agent;
+    stateRoot: string;
+}
+/** A `channels/<name>.ts` default export: receives the mount context, returns the routes it mounts.
+ *  Adapters (`telegramChannel(opts)`, `githubChannel(opts)`) RETURN one of these, so user glue holds
+ *  only policy — the framework pipes `agent`/`stateRoot` to the adapter without transiting user code. */
+export type ChannelModule = (ctx: ChannelContext) => Routes;
+/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
+export declare function parseRouteKey(key: string): {
+    method?: string;
+    path: string;
+};
+/**
+ * Compose a {@link Routes} table into one handler: exact pathname match (optionally method-qualified),
+ * 405 when the path exists under another method, 404 otherwise. No params/wildcards.
+ */
+export declare function router(routes: Routes): ChannelHandler;
+/**
+ * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
+ * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
+ * for port 0) or rejects on a bind error.
+ */
+export declare function serveNode(handler: ChannelHandler, options: {
+    port: number;
+}): {
+    listening: Promise<number>;
+    close: () => Promise<void>;
+};

package/dist/host/node.js

@@ -0,0 +1,50 @@
+/**
+ * Node host (K-axis): mount a route table of Fetch handlers on a node:http server. Post-ACK work
+ * (e.g. a webhook channel's fire-and-forget turns) runs on this process's event loop and is lost on
+ * shutdown (the accepted tradeoff until durable execution exists).
+ */
+import { createServer } from "node:http";
+import { nodeListener } from "../channels/http.js";
+import { text } from "../channels/respond.js";
+/** Parse a route key: `"METHOD /path"` → `{ method, path }`, or `"/path"` → `{ path }` (any method). */
+export function parseRouteKey(key) {
+    const sp = key.indexOf(" ");
+    return sp === -1 ? { path: key } : { method: key.slice(0, sp).toUpperCase(), path: key.slice(sp + 1) };
+}
+/**
+ * Compose a {@link Routes} table into one handler: exact pathname match (optionally method-qualified),
+ * 405 when the path exists under another method, 404 otherwise. No params/wildcards.
+ */
+export function router(routes) {
+    const entries = Object.entries(routes).map(([key, handler]) => ({
+        ...parseRouteKey(key),
+        handler,
+    }));
+    return (req) => {
+        const { pathname } = new URL(req.url);
+        const onPath = entries.filter((e) => e.path === pathname);
+        if (onPath.length === 0)
+            return text("not found\n", 404);
+        const match = onPath.find((e) => e.method === undefined || e.method === req.method);
+        if (!match)
+            return text("method not allowed\n", 405);
+        return match.handler(req);
+    };
+}
+/**
+ * Serve `handler` on a Node HTTP server. Thin mechanism: bind, report the port, let the caller close
+ * it — no logging/signals/exit (the CLI owns those). `listening` resolves with the bound port (useful
+ * for port 0) or rejects on a bind error.
+ */
+export function serveNode(handler, options) {
+    const server = createServer(nodeListener(async (req) => handler(req)));
+    const listening = new Promise((resolve, reject) => {
+        server.once("error", reject); // a bind failure surfaces here, before "listening"
+        server.listen(options.port, () => {
+            server.off("error", reject);
+            resolve(server.address().port);
+        });
+    });
+    const close = () => new Promise((resolve, reject) => server.close((e) => (e ? reject(e) : resolve())));
+    return { listening, close };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./core.ts";
+export * from "./pi.ts";

package/dist/index.js

@@ -0,0 +1,5 @@
+// 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 "./pi.js";

package/dist/invoke-stream.d.ts

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

package/dist/invoke-stream.js

@@ -0,0 +1,26 @@
+export async function runInvokeStream(events, out, err) {
+    const toolName = new Map(); // tool_ended carries no name — remember it from tool_started
+    let exitCode = 0;
+    for await (const event of events) {
+        switch (event.type) {
+            case "text":
+                out(event.delta);
+                break;
+            case "tool_started":
+                toolName.set(event.id, event.name);
+                err(`[tool] ${event.name}`);
+                break;
+            case "tool_ended":
+                if (event.isError)
+                    err(`[tool] ${toolName.get(event.id) ?? event.id} failed`);
+                break;
+            case "failed":
+                err(`[fastagent] failed: ${event.details}${event.retryable ? " (retryable)" : ""}`);
+                exitCode = 1;
+                break;
+            case "completed":
+                break; // terminal success — nothing to render (structured data, if any, is not a CLI concern)
+        }
+    }
+    return exitCode;
+}

package/dist/loader.d.ts

@@ -0,0 +1,38 @@
+/** Whether `name` is an importable workspace module (a discovery candidate, not a type declaration). */
+export declare function isModuleFile(name: string): boolean;
+export interface DiscoveredModule {
+    /** Basename without extension — the authoritative name for tools/channels. */
+    name: string;
+    /** "tools/foo.ts"-style label for errors and collisions. */
+    label: string;
+    file: string;
+    mod: {
+        default?: unknown;
+    };
+}
+/** A workspace 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. */
+export interface ModuleLoadFailure {
+    /** "tools/foo.ts"-style label. */
+    label: string;
+    file: string;
+    /** The failure message (an import error carries {@link moduleLoadHint}). */
+    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.)
+ */
+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.
+ */
+export declare function moduleLoadHint(error: NodeJS.ErrnoException): string;

package/dist/loader.js

@@ -0,0 +1,69 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { readdir } from "node:fs/promises";
+import { basename, extname, join } from "node:path";
+import { pathToFileURL } from "node:url";
+const MODULE_EXTS = new Set([".ts", ".js", ".mjs"]);
+/** Whether `name` is an importable workspace module (a discovery candidate, not a type declaration). */
+export function isModuleFile(name) {
+    return MODULE_EXTS.has(extname(name)) && !name.endsWith(".d.ts");
+}
+/**
+ * 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.)
+ */
+export async function loadModuleDir(subDir) {
+    let entries;
+    try {
+        entries = await readdir(subDir, { withFileTypes: true });
+    }
+    catch (error) {
+        const e = error;
+        if (e.code === "ENOENT" || e.code === "not_found")
+            return { modules: [], failures: [] };
+        throw new Error(`cannot read ${subDir}: ${error.message}`);
+    }
+    const sub = basename(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}`;
+        try {
+            const mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+            modules.push({ name: basename(entry.name, extname(entry.name)), label, file, mod });
+        }
+        catch (error) {
+            failures.push({
+                label,
+                file,
+                message: `${error.message}${moduleLoadHint(error)}`,
+            });
+        }
+    }
+    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.
+ */
+export function moduleLoadHint(error) {
+    if (error.code === "ERR_MODULE_NOT_FOUND" || /Cannot find (package|module)/.test(error.message)) {
+        return "\n  (a dependency is not installed — run `npm install` in the workspace)";
+    }
+    if (/import statement outside a module|Unexpected token 'export'|ERR_REQUIRE_ESM/.test(error.message)) {
+        return '\n  (this workspace must be ESM — set "type": "module" in package.json)';
+    }
+    return "";
+}

package/dist/log.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Leveled logging. Runtime logs (lifecycle, warnings, errors, the debug turn trace) flow through ONE
+ * process-level logger, gated by a single level. It is a module singleton — not an injected dependency —
+ * because most runtime logs originate inside author-constructed channels (`channels/*.ts` call the
+ * channel factory themselves) and deep engine code, which the CLI cannot thread a logger into. The CLI
+ * sets the level by posture (dev → debug, start → info); `FASTAGENT_LOG_LEVEL` overrides it.
+ *
+ * This is NOT the CLI's user-facing output (help text, command results): that is the program talking to
+ * its operator and stays on plain `console`. Everything here is operational logging to stderr.
+ */
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface Logger {
+    debug(msg: string): void;
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+/** A standalone logger over an explicit sink — used in tests to assert level gating without the singleton. */
+export declare function createLogger(opts: {
+    level: LogLevel;
+    sink?: (line: string) => void;
+}): Logger;
+/** 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. */
+export declare const log: Logger;