@fastagent-sh/fastagent 0.17.1 → 0.19.0

package/dist/deploy/preflight.js

@@ -15,14 +15,15 @@ import ignore from "ignore";
 import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
 import { resolveSecretsDir, resolveStateRoot } from "../paths.js";
-import { inspectChannels } from "../engines/pi/channel.js";
+import { inspectChannels } from "../channels/discover.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
-import { createPiModels, probeAuthSource } from "../engines/pi/models.js";
+import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
 import { CHANNEL_KINDS } from "../scaffold/add-channel.js";
 import { exists } from "../paths.js";
 import { detectRuntime, readPackageJson } from "../runtime.js";
 import { fastagentVersion } from "../version.js";
 import { isGeneratedDockerfile, isGeneratedDockerignore } from "./container.js";
+import { isEnvKey } from "./secrets.js";
 /**
  * "Would docker's packer drop this path?" — built from a `.dockerignore`'s text via the `ignore`
  * matcher (the same library the workspace ignore files use), so `!` negation and last-match-wins are
@@ -126,9 +127,25 @@ export async function preflightDeploy(input) {
         });
     }
     // Probe auth from the SAME project-level file the opener/login use — not the global default, which would
-    // miss a `fastagent login` credential and falsely report "none configured".
+    // miss a `fastagent login` credential and falsely report "none configured". Through the AGENT's model
+    // surface too (its models.json travels into the image), so a custom endpoint is not read as an unknown
+    // provider — this probe feeds the gate that decides whether `--run` may proceed.
     const authPath = resolveAuthPath(agentDir, authPathFlag);
-    const modelAuth = modelSpec ? await probeAuthSource(createPiModels({ authPath }), modelSpec) : undefined;
+    const models = await createPiModelRuntime({ agentDir, authPath });
+    let modelAuth = modelSpec ? await probeAuthSource(models, modelSpec) : undefined;
+    let modelKeyInDefinition = false;
+    // probeAuthSource answers "is it authenticated here", which is not the deploy question ("how does the
+    // credential REACH the host"). It reports every models.json endpoint as "configured API key" — not an
+    // env-var name — so without this the gate below sees no credential and stops the deploy with two
+    // remedies that are both wrong for such an agent: `fastagent login` cannot serve a custom provider,
+    // and the key is already in the environment.
+    if (modelSpec && !isEnvKey(modelAuth)) {
+        const carry = modelCredentialCarry(models, modelSpec);
+        if (carry.envVar)
+            modelAuth = carry.envVar;
+        else
+            modelKeyInDefinition = carry.inDefinition;
+    }
     // Container facts (shared by every host) + the warnings that follow. The facts describe the AGENT —
     // its package.json/runtime/lockfile drive the image's install step — never the workspace's (the bake
     // ships the whole tree, but the workspace's own manifest belongs to its own deploy).
@@ -410,6 +427,7 @@ export async function preflightDeploy(input) {
         longConnectionChannels,
         hasTimeTriggers,
         modelAuth,
+        modelKeyInDefinition,
         authPath,
         container,
         port,

package/dist/deploy/secrets.d.ts

@@ -38,6 +38,9 @@ export declare function deploymentSecrets(modelAuth: string | undefined, channel
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;
+    /** The definition carries the model key itself (a models.json literal `apiKey` / `!command`): there is
+     *  no value to carry and no gate to raise — see {@link modelCredentialCarry}. */
+    modelKeyInDefinition?: boolean;
     authFile: Buffer | undefined;
     channels: ChannelKind[];
     longConnectionChannels?: string[];

package/dist/deploy/secrets.js

@@ -65,6 +65,12 @@ export function assembleSecrets(input) {
     else if (input.authFile) {
         secrets.FASTAGENT_AUTH_SEED = input.authFile.toString("base64");
     }
+    else if (input.modelKeyInDefinition) {
+        // The definition authenticates itself (models.json literal key, or a command run on the host), so it
+        // travels in the image with everything else. Gating here would be the worst kind of wrong: both
+        // remedies we print are impossible for such an agent — `fastagent login` has no flow for a custom
+        // provider, and there is no provider env key to set.
+    }
     else {
         needsModelCredential = true; // no env key, no auth.json — `fastagent login` remediation
     }

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, resolveStateRoot } from "./paths.js";
-import { isUnderDir } from "./engines/pi/definition.js";
+import { AGENT_CONFIG_NAMES, AGENT_MODELS_FILE, resolveStateRoot } from "./paths.js";
+import { 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 { 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.*, .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;
@@ -49,8 +55,14 @@ export function devWatchIgnored(root, envFile) {
             return false;
         if (rel === "package.json")
             return false;
+        // models.json is read ONCE per worker (the model hub is built during assembly), so an edit needs a
+        // restart like any other code input. It is also the one input whose breakage KILLS the worker — a
+        // malformed file fails assembly — so leaving it unwatched would strand the author: the fix that
+        // repairs it would not be the edit that restarts.
+        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)

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,314 @@
+/**
+ * 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 { additiveActivation, agentSessionManager, 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();
+/**
+ * The turn's {@link ToolActivation} over a live session — the same bridge chat uses, so one
+ * built-in `search_tools` serves both.
+ *
+ * Activations are PERSISTED as deltas, so a tool discovered in one turn stays callable in the next.
+ * pi's own chat session does not do this (it has no place to put the record); a served session does,
+ * because the alternative is an agent that re-discovers the same capability every single turn.
+ */
+function sessionToolActivation(session) {
+    // Serialize activations: the read-modify-write below is only race-free while nothing awaits
+    // between read and write, and parallel tool calls in one batch would otherwise double-stamp.
+    let chain = Promise.resolve([]);
+    return {
+        active: () => session.getActiveToolNames(),
+        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
+        activate(names) {
+            const run = async () => {
+                const current = session.getActiveToolNames();
+                const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
+                if (added.length > 0) {
+                    session.setActiveToolsByName([...current, ...added]);
+                    session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
+                }
+                return added;
+            };
+            const result = chain.then(run, run);
+            chain = result.catch(() => []);
+            return result;
+        },
+    };
+}
+/**
+ * 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.
+ */
+function toolDefinitions(tools, cwd, env, sessionId, 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 session = bound.session;
+            if (!session)
+                throw new Error("tool executed before its session was bound (lifecycle invariant broken)");
+            return turnContext.run({ cwd, sessionManager: agentSessionManager(session, sessionId), tools: sessionToolActivation(session) }, 
+            // 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, cwd, env, sessionId, bound),
+        });
+        bound.session = session;
+        // 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,
+        };
+    });
+}

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

@@ -1,7 +1,7 @@
 import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
 import type { FastagentTool } from "./tool.ts";
 import type { Models } from "@earendil-works/pi-ai";
-import type { AnyModel } from "./harness.ts";
+import type { AnyModel } from "./models.ts";
 export interface FastagentConfig {
     /** "provider/modelId". Precedence: CLI --model > FASTAGENT_MODEL > config. */
     model?: string;
@@ -9,8 +9,8 @@ export interface FastagentConfig {
      *  "xhigh" | "max"). Unset = pi's default. Authors tune thinking in the pi TUI while vibing — this
      *  is the serving-side counterpart (fidelity). Levels a model doesn't support are clamped by pi. */
     thinkingLevel?: ThinkingLevel;
-    /** Extra custom tools, appended after pi defaults — never replaces them. `FastagentTool` = AgentTool
-     *  plus the optional `deferred` marker (see defineTool). */
+    /** Extra custom tools, appended after the pi coding tools — never replaces them. `FastagentTool`
+     *  = AgentTool plus the optional `deferred` marker (see defineTool). */
     tools?: FastagentTool[];
     /** `host` is the bind address: unset (or `0.0.0.0`) binds all interfaces — what containers need;
      *  `127.0.0.1` keeps the serve (including `/control/*`) off the LAN. Precedence: `--bind` > this. */
@@ -60,7 +60,7 @@ export declare function loadConfig(dir: string): Promise<LoadedConfig>;
  *  lookups then miss visibly (an unknown-provider error / a login-required hint), never a mangled id
  *  (`slice(0, indexOf("/"))` silently drops the last char when "/" is absent). */
 export declare function providerOf(spec: string): string;
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export declare function resolveModel(models: Models, spec: string): AnyModel;
 /** All registered "provider/modelId" specs in `models`, sorted — the list behind `fastagent models`. */
 export declare function listModels(models: Models): string[];

package/dist/engines/pi/config.js

@@ -151,7 +151,7 @@ export function providerOf(spec) {
     const slash = spec.indexOf("/");
     return slash > 0 ? spec.slice(0, slash) : spec;
 }
-/** Resolve "provider/modelId" → a pi Model from `models`, so the harness resolves auth from the same collection. */
+/** Resolve "provider/modelId" → a pi Model from `models`, so auth resolves from the same collection. */
 export function resolveModel(models, spec) {
     const slash = spec.indexOf("/");
     if (slash < 1 || slash === spec.length - 1) {