@fastagent-sh/fastagent 0.18.0 → 0.20.0

package/dist/deploy/runner.js

@@ -4,6 +4,7 @@
  * binary and the command sequence differ. Tests inject a fake recorder; production spawns the real CLI.
  */
 import { spawn } from "node:child_process";
+import { log } from "../log.js";
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the
  * agent). stderr is always inherited to the terminal; stdout is inherited unless `capture`. A spawn
@@ -22,11 +23,30 @@ export function spawnRunner(bin, cwd) {
         });
         let out = "";
         let err = "";
+        let stdinError;
         child.stdout?.on("data", (d) => (out += String(d)));
         child.stderr?.on("data", (d) => (err += String(d)));
-        if (opts?.input)
+        if (opts?.input) {
+            // A host CLI that rejects before reading (bad auth, a refused command) closes stdin under us:
+            // the write then emits `error` on a stream with no listener, which Node turns into an uncaught
+            // exception — crashing the deploy and losing the gate message the exit code was about to carry.
+            // HELD, not dropped: the exit code says it only when the CLI exits non-zero (see below).
+            child.stdin?.on("error", (error) => (stdinError ??= error));
             child.stdin?.end(opts.input);
-        child.on("close", (code) => res({ code: code ?? 1, stdout: out, stderr: opts?.captureStderr ? err : undefined }));
+        }
+        child.on("close", (code) => {
+            // A CLI that exits 0 having refused part of its stdin took TRUNCATED input — an auth seed runs
+            // well past the 64KB pipe buffer, so "success" here would deploy a half-written secret and say
+            // nothing. The exit code is what callers read, so the failure has to reach them as one.
+            const truncated = stdinError !== undefined && (code ?? 1) === 0;
+            if (truncated) {
+                // `error`, not `warn`: this line is the ONLY evidence of the failure — the caller's gate says
+                // "see the output above", and above it the host CLI printed success. A log level that mutes
+                // it (CI often sets `error`) leaves a stopped deploy with no diagnosable cause.
+                log.error(`[fastagent] ${bin} exited 0 without reading all of its input — ${stdinError?.message}`);
+            }
+            res({ code: truncated ? 1 : (code ?? 1), stdout: out, stderr: opts?.captureStderr ? err : undefined });
+        });
         child.on("error", () => res({ code: 127, stdout: "", stderr: opts?.captureStderr ? "" : undefined })); // ENOENT
     });
 }

package/dist/deploy/secrets.d.ts

@@ -1,9 +1,4 @@
-/**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. Required values
- * gate every target; optional channel values travel only when configured. Only the SET command differs
- * (`fly secrets import` vs `railway variables set`). The runbooks list both classes; `--run` reads local values.
- */
-import { type ChannelKind } from "../scaffold/add-channel.ts";
+import type { DeclaredChannel } from "../channels/discover.ts";
 /**
  * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
  * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
@@ -17,7 +12,7 @@ export declare function isEnvKey(source: string | undefined): source is string;
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[], longConnectionChannels?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: readonly DeclaredChannel[], extraSecrets?: string[]): {
     name: string;
     hint: string;
     required: boolean;
@@ -42,8 +37,7 @@ export declare function assembleSecrets(input: {
      *  no value to carry and no gate to raise — see {@link modelCredentialCarry}. */
     modelKeyInDefinition?: boolean;
     authFile: Buffer | undefined;
-    channels: ChannelKind[];
-    longConnectionChannels?: string[];
+    channels: readonly DeclaredChannel[];
     /** Extra secret env-var names from `fastagent.config` deploy.secrets — carried like channel secrets. */
     extraSecrets?: string[];
     env: NodeJS.ProcessEnv;
@@ -52,3 +46,18 @@ export declare function assembleSecrets(input: {
     missingSecrets: string[];
     needsModelCredential: boolean;
 };
+/**
+ * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
+ * FASTAGENT_AUTH_SEED materialization (the read side of {@link assembleSecrets}'s carry). ABSENT-ONLY
+ * by design: a present file (a refreshed volume copy) is never overwritten by the stale seed, so a box
+ * that ran its own OAuth refresh is not rolled back.
+ */
+export declare function authSeedBytes(seed: string | undefined, fileExists: boolean): Buffer | undefined;
+/**
+ * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
+ * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
+ * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
+ * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
+ * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ */
+export declare function collectAuthSeed(env: NodeJS.ProcessEnv): string | undefined;

package/dist/deploy/secrets.js

@@ -2,8 +2,20 @@
  * The secret set a deployed agent needs, computed from the definition — host-neutral. Required values
  * gate every target; optional channel values travel only when configured. Only the SET command differs
  * (`fly secrets import` vs `railway variables set`). The runbooks list both classes; `--run` reads local values.
+ *
+ * Both DIRECTIONS of the credential carry live here: the deploy-time assembly below, and the boot-time
+ * seed read at the bottom. They were split across a host driver (`fly/run.ts`), which left `start`
+ * — a serving path that deploys nothing, on Fly or anywhere — importing from it to boot a container.
  */
-import { channelSetup } from "../scaffold/add-channel.js";
+import { CONTROL_TOKEN_ENV } from "../channels/control.js";
+import { CHANNEL_KINDS, channelSetup } from "../scaffold/add-channel.js";
+/** The declared channels this tool has setup metadata for. A custom channel carries its own secrets;
+ *  nothing here can name them, and guessing would print a runbook line no one can act on. */
+function firstPartyChannels(channels) {
+    return channels.flatMap((channel) => CHANNEL_KINDS.includes(channel.name)
+        ? [{ kind: channel.name, ingress: channel.ingress }]
+        : []);
+}
 /**
  * Is this local auth source an env-var API key (→ becomes a deploy secret) vs OAuth / stored / none?
  * Positive match on the UPPER_SNAKE env-var naming shape, NOT a negative exclude of today's sentinel
@@ -19,20 +31,30 @@ export function isEnvKey(source) {
  * deployment prerequisites. An OAuth/stored login has no env key here — it carries as
  * `FASTAGENT_AUTH_SEED` on the `--run` path (see each host's run module), not as a named runbook secret.
  */
-export function deploymentSecrets(modelAuth, channels, extraSecrets = [], longConnectionChannels = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
         secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
-    for (const kind of channels) {
-        const setupMode = longConnectionChannels.includes(kind) ? "websocket" : "webhook";
-        for (const e of channelSetup(kind, setupMode).env) {
+    for (const { kind, ingress } of firstPartyChannels(channels)) {
+        for (const e of channelSetup(kind, ingress === "long-connection" ? "websocket" : "webhook").env) {
             secrets.push({ name: e.name, hint: e.hint, required: e.required });
         }
     }
     // Dedup: a name already covered by the model key / a channel secret must not appear twice in the runbook.
     for (const name of extraSecrets) {
         if (!secrets.some((s) => s.name === name)) {
-            secrets.push({ name, hint: "declared in fastagent.config deploy.secrets", required: true });
+            const control = name === CONTROL_TOKEN_ENV;
+            secrets.push({
+                name,
+                hint: control
+                    ? "the /control/* bearer token — mint one (uuidgen) and give the same value to callers"
+                    : "declared in fastagent.config deploy.secrets",
+                // OPTIONAL, unlike every other extra: unset, the box mints a per-boot token and still serves,
+                // and every host with a shell can read it back out of control.json. Gating would stop deploys
+                // that work today to enforce a convenience — the pre-flight warning is where that argument
+                // belongs.
+                required: !control,
+            });
         }
     }
     return secrets;
@@ -74,9 +96,8 @@ export function assembleSecrets(input) {
     else {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }
-    for (const kind of input.channels) {
-        const setupMode = input.longConnectionChannels?.includes(kind) ? "websocket" : "webhook";
-        for (const e of channelSetup(kind, setupMode).env) {
+    for (const { kind, ingress } of firstPartyChannels(input.channels)) {
+        for (const e of channelSetup(kind, ingress === "long-connection" ? "websocket" : "webhook").env) {
             const v = input.env[e.name];
             if (v)
                 secrets[e.name] = v; // optional channel values travel when configured
@@ -88,7 +109,7 @@ export function assembleSecrets(input) {
     // Slack bot-token rotation is an all-or-nothing credential bundle. Its fields remain optional so a
     // manually configured long-lived token works, but a partial bundle must gate before the container
     // reaches slackChannel construction.
-    if (input.channels.includes("slack")) {
+    if (input.channels.some((channel) => channel.name === "slack")) {
         const rotation = [
             "SLACK_BOT_REFRESH_TOKEN",
             "SLACK_BOT_TOKEN_EXPIRES_AT",
@@ -108,8 +129,39 @@ export function assembleSecrets(input) {
         const v = input.env[name];
         if (v)
             secrets[name] = v;
-        else
-            missingSecrets.push(name); // declared in config but no local value — same .env remediation
+        // The control token is CARRIED, never gated — see {@link deploymentSecrets}: unset, the box mints
+        // one and serves; every other extra is declared as needed, so its absence is a stop.
+        else if (name !== CONTROL_TOKEN_ENV)
+            missingSecrets.push(name);
     }
     return { secrets, missingSecrets, needsModelCredential };
 }
+/**
+ * The bytes to seed to the auth file, or undefined to leave it alone — the pure core of `start`'s
+ * FASTAGENT_AUTH_SEED materialization (the read side of {@link assembleSecrets}'s carry). ABSENT-ONLY
+ * by design: a present file (a refreshed volume copy) is never overwritten by the stale seed, so a box
+ * that ran its own OAuth refresh is not rolled back.
+ */
+export function authSeedBytes(seed, fileExists) {
+    return !seed || fileExists ? undefined : Buffer.from(seed, "base64");
+}
+/**
+ * Collect the (possibly CHUNKED) auth seed from the environment: `FASTAGENT_AUTH_SEED` plus numbered
+ * continuations (`_2`, `_3`, …) concatenated in order. Hosts whose env values carry a small max
+ * length (AgentCore: 2048 chars — a real OAuth auth.json's base64 exceeds it) split the seed across
+ * them at deploy time; single-var hosts (Fly/Railway) never set a continuation and are unchanged.
+ * Collection stops at the first absent/empty continuation — the writer fills them contiguously.
+ */
+export function collectAuthSeed(env) {
+    const first = env.FASTAGENT_AUTH_SEED;
+    if (!first)
+        return undefined;
+    let seed = first;
+    for (let i = 2;; i++) {
+        const part = env[`FASTAGENT_AUTH_SEED_${i}`];
+        if (!part)
+            break;
+        seed += part;
+    }
+    return seed;
+}

package/dist/dev-supervisor.js

@@ -13,15 +13,21 @@
 import { spawn } from "node:child_process";
 import { relative, sep } from "node:path";
 import { watch as watchTree } from "chokidar";
-import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot } from "./paths.js";
-import { isUnderDir } from "./engines/pi/definition.js";
+import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot, isUnderDir, } from "./paths.js";
 import { dotEnvPath } from "./env.js";
 import { log } from "./log.js";
 import { installProxyFetch } from "./proxy.js";
 import { openExternalUrl } from "./open-url.js";
+import { declaredChannels } from "./channels/discover.js";
 import { announceWebhooks, startCloudflareTunnel } from "./tunnel.js";
 /** What the dev watcher restarts on (agent-dir-relative): the process-bound code inputs only. */
-const WATCHED_HINT = "tools/, channels/, schedules/, package.json, fastagent.config.*, models.json, .secrets/.env";
+/**
+ * The agent-dir directories loaded ONCE per worker: a restart is their only re-read. One list, so
+ * the watcher and the line printed at startup cannot disagree — a directory watched but unannounced
+ * looks broken, and one announced but unwatched silently strands the author mid-edit.
+ */
+const CODE_INPUT_DIRS = ["tools", "channels", "schedules", "extensions"];
+const WATCHED_HINT = `${CODE_INPUT_DIRS.map((dir) => `${dir}/`).join(", ")}, package.json, fastagent.config.*, models.json, .secrets/.env`;
 /**
  * chokidar `ignored` matcher for the narrow watch scope (true = ignore), rooted at the AGENT DIR. When
  * the agent sits INSIDE the workspace that means the surrounding tree never triggers a restart at all;
@@ -56,7 +62,7 @@ export function devWatchIgnored(root, envFile) {
         if (rel === AGENT_MODELS_FILE)
             return false;
         const segments = rel.split(sep);
-        if (segments[0] === "tools" || segments[0] === "channels" || segments[0] === "schedules")
+        if (CODE_INPUT_DIRS.includes(segments[0]))
             return false;
         // The `.env` restarts too (credentials are process-bound). Keep it AND its ancestor directories
         // un-pruned so chokidar can descend to it; every sibling inside them (auth.json, .env.example)
@@ -102,9 +108,8 @@ export async function runDevSupervisor(placement, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(placement.agentDir, t.url, {
+                        void announceWebhooks(placement.agentDir, t.url, declaredChannels(m.routeChannels ?? []), {
                             openUrl: openExternalUrl,
-                            routeChannels: m.routeChannels,
                             stateRoot: resolveStateRoot(placement.agentDir),
                         });
                     }

package/dist/engines/pi/agent-session-factory.d.ts

@@ -0,0 +1,104 @@
+import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import type { Model } from "@earendil-works/pi-ai";
+import { type AgentSessionServices, type CreateAgentSessionServicesOptions, type ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { PiAgentSessionFactory } from "./invoke-session.ts";
+import type { PiSessionRecordStore } from "./session-store.ts";
+import { type MountedTool } from "./tool.ts";
+/** pi's Model with the API-shape generic erased; fastagent only passes models through. */
+type AnyModel = Model<any>;
+export interface PiAgentSessionFactoryOptions {
+    /** Where conversations live. Continuity = same store + same session id. */
+    sessions: PiSessionRecordStore;
+    /**
+     * The model to run and the hub that authenticates it, resolved on FIRST USE and kept.
+     *
+     * A thunk because building a `ModelRuntime` is async while assembling an agent is not: the L1
+     * surface hands back an `Agent` synchronously, so the credential read that a runtime performs
+     * belongs on the first turn rather than in the caller's constructor. The two travel together
+     * because a model must be resolved against the runtime that holds its provider's auth.
+     */
+    engine: () => Promise<{
+        modelRuntime: ModelRuntime;
+        model: AnyModel;
+    }>;
+    thinkingLevel?: ThinkingLevel;
+    tools?: MountedTool[];
+    /** Final assembled prompt, or a factory re-evaluated per turn. */
+    systemPrompt?: string | (() => string);
+    skills?: Skill[];
+    /** Per-turn source for the prompt+skills PAIR; supersedes the two above. This is what keeps
+     *  "the directory is the agent, LIVE" true on a shared `services`: the ResourceLoader is built
+     *  once, but what it serves is re-read here. */
+    live?: () => Promise<{
+        systemPrompt?: string;
+        skills?: Skill[];
+    }>;
+    /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
+    cwd: string;
+    /**
+     * Where pi looks for ITS settings (retry budget, compaction thresholds, default thinking level).
+     *
+     * Deliberately NOT pi's machine-global `~/.pi/agent`: a served agent must behave the same on the
+     * author's laptop and in a container, and reading the operator's personal pi configuration is the
+     * artifact losing to the machine. Point it at a definition-scoped path; a missing directory simply
+     * means pi's own defaults, which is the intended baseline.
+     */
+    agentDir?: string;
+    /**
+     * The definition's own extension entry points, for ANNOUNCING that serving does not run them.
+     *
+     * pi's extension machinery is built for one process serving one session: `bindCore()` copies the
+     * session's actions into a runtime the pi source itself calls "the shared runtime", extension
+     * modules are cached per assembly, and `session_start`/`session_shutdown` are a matched pair.
+     * Serving breaks every one of those assumptions — concurrent turns for unrelated conversations —
+     * and the failure is silent cross-talk: with two turns in flight, an extension calling
+     * `pi.sendMessage()` can deliver into the other conversation.
+     *
+     * Loading them anyway would be a correctness bug dressed as a feature, so serving does not, and
+     * warns when a definition ships some. `chat` runs them fully: one session, one runtime, which is
+     * exactly the shape pi is built for.
+     *
+     * Isolating them per session is mechanically possible — pi's uncached loader path builds a fresh
+     * module (jiti with `moduleCache: false`) and takes the runtime as an argument — but that function
+     * is not exported and the deep path is blocked by the package's `exports`. Reopening this needs
+     * that entry point upstream, not a workaround here.
+     */
+    extensionPaths?: string[];
+    /** Built-ins omitted by an explicit lower-level tool list. */
+    excludedToolNames?: readonly string[];
+    /** Filesystem/process environment: definition loading, and the turn context for tools that read one. */
+    env: ExecutionEnv;
+}
+/**
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
+ * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
+ * A definition running without the extension it ships is exactly the "quietly missing" failure this
+ * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
+ * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ */
+export declare function reportExtensionErrors(services: AgentSessionServices): void;
+/** What pi is allowed to discover, minus the parts each assembly fills in itself. */
+type DefinitionLoaderOptions = NonNullable<CreateAgentSessionServicesOptions["resourceLoaderOptions"]>;
+/**
+ * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
+ * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
+ * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
+ * everything comes from the definition, nothing from the machine that happens to be running it.
+ *
+ * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
+ * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
+ * worked when served and vanished in chat. A difference between the two has to be visible AS a
+ * difference, which is what the parameters are for: serving reads a prompt and skills that change
+ * per turn and passes NO extension paths (it does not run them — see
+ * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
+ * own. Both are arguments now, rather than two files that happen to disagree.
+ */
+export declare function definitionResourceLoaderOptions(source: {
+    systemPrompt: () => string | undefined;
+    skills: () => Skill[];
+    /** Omitted by serving, which does not run them. */
+    extensionPaths?: readonly string[];
+}): DefinitionLoaderOptions;
+/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+export declare function piAgentSessionFactory(options: PiAgentSessionFactoryOptions): PiAgentSessionFactory;
+export {};

package/dist/engines/pi/agent-session-factory.js

@@ -0,0 +1,295 @@
+/**
+ * The AgentSession L0's engine binding: fastagent's assembled agent — model, prompt, skills, tools —
+ * bound to one durable record, per invoke.
+ *
+ * The chat path builds the same pi class from the same assembly (session-builder.ts) but keeps ONE
+ * resident session. What is specific here is the posture: many sessions, one turn each, nothing in
+ * memory between turns.
+ *
+ * Shared once, rebuilt per turn:
+ * - `services` (ResourceLoader, settings, model runtime) is built lazily and reused — it is the
+ *   expensive half, and it holds nothing session-specific;
+ * - the `AgentSession` and its tool bindings are per turn, because a tool's `execute` closes over the
+ *   session it runs in and this posture has several in flight at once.
+ */
+import { dirname, join } from "node:path";
+import { createAgentSessionFromServices, createAgentSessionServices, } from "@earendil-works/pi-coding-agent";
+import { log } from "../../log.js";
+import { isDeferredTool } from "./tool.js";
+import { activePath, resolveSessionSettings } from "./session-settings.js";
+import { DEFAULT_THINKING_LEVEL } from "./models.js";
+import { agentSessionManager, sessionToolActivation, turnContext } from "./tool-context.js";
+/**
+ * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
+ * tools a loader activated in that call.
+ *
+ * A DEDICATED record, not pi's own `active_tools_change`: that one is a full SNAPSHOT of everything
+ * active at the moment, so replaying it would keep a tool active in old sessions after the author
+ * flips it to `deferred` — the session never discovered it. A delta carries only what was actually
+ * found, and is layered onto whatever the workspace mounts TODAY.
+ */
+const TOOL_ACTIVATION_ENTRY = "fastagent:tool-activation";
+/** Every deferred tool this session has ever discovered, oldest first. */
+function recordedActivations(session) {
+    const names = [];
+    for (const entry of session.sessionManager.getBranch()) {
+        const record = entry;
+        if (record.type !== "custom" || record.customType !== TOOL_ACTIVATION_ENTRY)
+            continue;
+        if (Array.isArray(record.data?.names)) {
+            for (const name of record.data.names)
+                if (typeof name === "string")
+                    names.push(name);
+        }
+    }
+    return names;
+}
+/** Warned once per session+missing set: a fresh session is built per invoke and channel sessions run
+ *  for weeks, so an un-deduped warn would repeat every turn and dilute its own signal. */
+const warnedDroppedActivations = new Set();
+/**
+ * fastagent's tools as pi tool definitions, bound to ONE session.
+ *
+ * `bound` is filled after the session exists — pi needs the definitions to build the session, and a
+ * tool needs the session to reach the turn context. A tool that somehow runs before that binding
+ * throws rather than executing outside the turn: a broken lifecycle must not look like a normal
+ * out-of-turn call.
+ *
+ * It carries the whole turn CONTEXT, not just the session: the activation bridge holds the lock that
+ * orders concurrent activations, so it has to live as long as the session the activations mutate.
+ * Building it here, per call, would hand each parallel tool its own.
+ */
+function toolDefinitions(tools, env, bound) {
+    return tools.map((tool) => ({
+        name: tool.name,
+        label: tool.name,
+        description: tool.description ?? "",
+        parameters: tool.parameters,
+        // An activating tool (the built-in loader) declares "sequential" so pi serializes its batch;
+        // without it pi's outer active-set diff double-stamps parallel calls.
+        executionMode: tool.executionMode,
+        execute: (id, params, signal) => {
+            const context = bound.context;
+            if (!context)
+                throw new Error("tool executed before its turn context was bound (lifecycle invariant broken)");
+            return turnContext.run(context, 
+            // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
+            // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
+            () => tool.execute(id, params, signal, undefined, { env }));
+        },
+    }));
+}
+/**
+ * Announce extensions pi failed to load. pi collects them into `LoadExtensionsResult.errors` and
+ * carries on with the rest — sound for a TUI that shows them, silent for a server that never looks.
+ * A definition running without the extension it ships is exactly the "quietly missing" failure this
+ * exists to remove. CHAT calls it, once per built services — serving does not load extensions at
+ * all, and announces that instead (see PiAgentSessionFactoryOptions.extensionPaths).
+ */
+export function reportExtensionErrors(services) {
+    for (const { path, error } of services.resourceLoader.getExtensions().errors) {
+        log.warn(`[fastagent] extension ${path} failed to load: ${error}`);
+    }
+}
+/**
+ * The resource posture a fastagent definition asks pi for — ONE definition of it, for both
+ * assemblies. Serving (`piAgentSessionFactory`) and chat (`buildAgentSessionRuntime`) build
+ * different sessions on top, but what pi is allowed to DISCOVER is not one of the differences:
+ * everything comes from the definition, nothing from the machine that happens to be running it.
+ *
+ * Two copies of this drifted once already: `additionalExtensionPaths` was added to both, and only
+ * one of them also passed the resulting tool names through pi's `tools` allowlist — so extensions
+ * worked when served and vanished in chat. A difference between the two has to be visible AS a
+ * difference, which is what the parameters are for: serving reads a prompt and skills that change
+ * per turn and passes NO extension paths (it does not run them — see
+ * {@link PiAgentSessionFactoryOptions.extensionPaths}); chat reads a fixed assembly and passes its
+ * own. Both are arguments now, rather than two files that happen to disagree.
+ */
+export function definitionResourceLoaderOptions(source) {
+    return {
+        // Definition-only, like dev/start: pi's machine-global discovery (the operator's own ~/.pi
+        // extensions, slash commands, global AGENTS.md, APPEND_SYSTEM.md) stays out, so the agent that
+        // runs is the artifact, not the artifact plus whoever's laptop it is.
+        noExtensions: true,
+        // ...except the definition's OWN extensions/: pi honours additionalExtensionPaths even under
+        // noExtensions, which is exactly the split wanted here — the artifact travels with its
+        // extensions, the machine's stay out.
+        ...(source.extensionPaths?.length ? { additionalExtensionPaths: [...source.extensionPaths] } : {}),
+        noPromptTemplates: true,
+        noContextFiles: true,
+        // A SPACE, not "", when the assembly has no prompt: pi treats an empty custom prompt as absent
+        // and substitutes its own coding-assistant identity, which an L1 agent
+        // (`createPiAgent({ model, tools })`) never asked for. pi appends its own working-directory line
+        // either way — that is engine behaviour this binding does not fight.
+        systemPromptOverride: () => source.systemPrompt() ?? " ",
+        appendSystemPromptOverride: () => [],
+        skillsOverride: (base) => ({
+            skills: toPiSkills(source.skills()),
+            diagnostics: base.diagnostics,
+        }),
+    };
+}
+/** Open-or-create the record, then bind a fresh session to it. One call per invoke. */
+export function piAgentSessionFactory(options) {
+    const { sessions, thinkingLevel, cwd, env } = options;
+    const extensionPaths = options.extensionPaths ?? [];
+    const excludedToolNames = options.excludedToolNames ?? [];
+    if (extensionPaths.length > 0) {
+        log.warn(`[fastagent] ${extensionPaths.length} extension(s) in the definition are NOT loaded when serving ` +
+            "(they run in `fastagent chat`): pi's extension runtime is shared across sessions, and serving " +
+            "runs concurrent turns for different conversations. See docs/configuration.md#extensions.");
+    }
+    const tools = options.tools ?? [];
+    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
+    // What the shared ResourceLoader serves, refreshed per turn before the session is built.
+    let prompt = typeof options.systemPrompt === "function" ? options.systemPrompt() : options.systemPrompt;
+    let skills = options.skills ?? [];
+    let services;
+    let engine;
+    const buildServices = async (modelRuntime) => createAgentSessionServices({
+        cwd,
+        agentDir: options.agentDir ?? join(cwd, ".fastagent", "pi"),
+        modelRuntime,
+        // No extensionPaths: serving does not run them (see PiAgentSessionFactoryOptions), which is
+        // the one resource question the two assemblies answer differently. The accessors read the
+        // CURRENT prompt/skills — serving refreshes both per turn, so a snapshot taken here would
+        // serve a stale definition after the first edit.
+        resourceLoaderOptions: definitionResourceLoaderOptions({
+            systemPrompt: () => prompt,
+            skills: () => skills,
+        }),
+    });
+    return async (sessionId, inherit) => {
+        const fresh = options.live ? await options.live() : undefined;
+        const nextPrompt = fresh
+            ? fresh.systemPrompt
+            : typeof options.systemPrompt === "function"
+                ? options.systemPrompt()
+                : prompt;
+        const nextSkills = fresh ? (fresh.skills ?? []) : skills;
+        engine ??= options.engine();
+        const { modelRuntime, model } = await engine;
+        if (services === undefined) {
+            prompt = nextPrompt;
+            skills = nextSkills;
+            services = buildServices(modelRuntime); // assigned before any await: concurrent turns share it
+        }
+        else {
+            // The ResourceLoader reads the overrides once and caches, so a re-read of the definition only
+            // reaches the model after a reload. Reload only when the definition ACTUALLY changed — an
+            // author edits persona.md far less often than the agent takes a turn, and a reload costs ~5ms
+            // against ~0.6ms to bind a session.
+            //
+            // "Changed" is measured against the LOADER, not against what this factory last wrote. Serving
+            // is concurrent across sessions, and a shared variable makes the check lie: one turn writes
+            // its new prompt, awaits before reloading, and the next turn sees that value already present,
+            // concludes nothing changed, and skips the reload — so the edit reaches neither the loader nor
+            // any error. Asking the loader what it is actually serving cannot go stale that way. The cost
+            // of losing the race is one redundant reload, not a swallowed edit.
+            //
+            // Skill CONTENT is not part of this — pi reads a skill from its file at invocation time, so
+            // only the declared set matters.
+            //
+            // What this deliberately does NOT provide is a per-turn snapshot. The definition is an AGENT
+            // property, not a session one: two turns running either side of an edit each get a definition
+            // that genuinely existed, and the product promise — an edit is live on the next turn — holds
+            // for both. Pinning a snapshot per turn would cost either a loader per turn or a queue in
+            // front of every bind, to buy a guarantee nothing asks for.
+            const loader = (await services).resourceLoader;
+            const definitionChanged = loader.getSystemPrompt() !== nextPrompt || loadedSkillSet(loader.getSkills().skills) !== skillSet(nextSkills);
+            if (definitionChanged) {
+                prompt = nextPrompt;
+                skills = nextSkills;
+                await loader.reload();
+            }
+        }
+        const sessionManager = await sessions.openOrCreate(sessionId, inherit);
+        // What the session RUNS on: the boundary plane records model/thinking overrides as entries, and
+        // pi does not read them back — a binding that ignored them would silently run every turn on the
+        // assembly default, and `state()` would report a setting no turn uses.
+        // The SAME read the control plane performs, including its integrity check: a record whose chain
+        // is broken must not run on assembly defaults while `state()` rejects it — one of the two planes
+        // would be lying. A throw here becomes this turn's `failed` event, which is where the fault has
+        // a channel to be reported through.
+        const settings = resolveSessionSettings(activePath(sessionManager), modelRuntime, {
+            model,
+            thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
+        });
+        const bound = {};
+        const { session } = await createAgentSessionFromServices({
+            services: await services,
+            sessionManager,
+            model: settings.model,
+            thinkingLevel: settings.thinkingLevel,
+            // pi would otherwise mount its built-ins on top of fastagent's copies, offering duplicate names.
+            // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted.
+            noTools: "builtin",
+            ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
+            customTools: toolDefinitions(tools, env, bound),
+        });
+        // One context for the whole session: it describes the SESSION, not the call. The activation
+        // bridge above all — a tool call has to see what the previous one activated.
+        bound.context = {
+            cwd,
+            sessionManager: agentSessionManager(session, sessionId),
+            // A served session HAS somewhere to record the discovery, so it does: the delta is what makes
+            // the tool still callable next turn (see {@link TOOL_ACTIVATION_ENTRY}).
+            tools: sessionToolActivation(session, (added) => session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added })),
+        };
+        // An extension handler that throws is otherwise dropped: pi fans errors out to registered
+        // listeners and has none by default, which on a server means a broken extension looks like an
+        // extension that simply did nothing.
+        //
+        // Deferral, then restoration: pi starts every mounted tool active, so narrow by SUBTRACTING the
+        // deferred names (robust to pi mounting tools of its own, unlike an exact-set replacement), then
+        // add back what THIS session has already discovered.
+        if (deferred.length > 0) {
+            const active = session.getActiveToolNames();
+            const mounted = new Set(session.getAllTools().map((tool) => tool.name));
+            const recorded = recordedActivations(session);
+            // A recorded name that is no longer mounted is dropped rather than replayed: pi's setter
+            // THROWS on an unknown name, so replaying one would brick every future turn of this session.
+            const restored = recorded.filter((name) => mounted.has(name));
+            const dropped = recorded.filter((name) => !mounted.has(name));
+            if (dropped.length > 0) {
+                const key = `${sessionId}\u0000${[...new Set(dropped)].sort().join(",")}`;
+                const emit = warnedDroppedActivations.has(key) ? log.debug : log.warn;
+                warnedDroppedActivations.add(key);
+                emit(`[fastagent] session ${sessionId}: dropping recorded activation(s) no longer mounted: ${[...new Set(dropped)].join(", ")}`);
+            }
+            const next = [...new Set([...active.filter((name) => !deferred.includes(name)), ...restored])];
+            if (next.length !== active.length || next.some((name) => !active.includes(name))) {
+                session.setActiveToolsByName(next);
+            }
+        }
+        return session;
+    };
+}
+/** What a reload has to notice: the declared set, not the files behind it. */
+function skillSet(skills) {
+    return skills.map((s) => `${s.name}\u0000${s.filePath}\u0000${s.description}`).join("\u0001");
+}
+/** The same signature, read back off the loader. */
+function loadedSkillSet(skills) {
+    return skills.map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}`).join("\u0001");
+}
+/** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
+function toPiSkills(skills) {
+    return skills.map((skill) => {
+        const baseDir = dirname(skill.filePath);
+        return {
+            name: skill.name,
+            description: skill.description,
+            filePath: skill.filePath,
+            baseDir,
+            sourceInfo: {
+                path: skill.filePath,
+                source: "fastagent",
+                scope: "project",
+                origin: "top-level",
+                baseDir,
+            },
+            disableModelInvocation: skill.disableModelInvocation ?? false,
+        };
+    });
+}