@fastagent-sh/fastagent 0.20.0 → 0.21.1

package/dist/deploy/fly/run.js

@@ -18,15 +18,70 @@
  * never land in argv/process listings.
  */
 import { registerWebhooks } from "../channel-ingress.js";
-/** Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept both). */
-function listHasName(stdout, name) {
+/** The `Type` values that put an app on `https://<app>.fly.dev`, BY FAMILY — one entry per allocate
+ *  command, because that is the granularity the answer is acted on at. The rest of flyctl's
+ *  vocabulary — `private_v6` (Flycast), `egress_v4`, `egress_v6`, `egress_pair` — is internal or
+ *  outbound. */
+const INGRESS_TYPES = { v4: ["v4", "shared_v4"], v6: ["v6"] };
+/**
+ * Which PUBLIC ingress families `fly ips list --json` shows — asked per family, because "has an
+ * ingress address" is not the question the two allocate commands answer. An app holding only a `v6`
+ * passes the coarse test and still resolves `<app>.fly.dev` to an AAAA record alone, so an IPv4-only
+ * webhook sender (Telegram, GitHub) reproduces #425 against it.
+ *
+ * The list is EVERY assignment the app holds, and a Flycast or egress address carries a non-empty
+ * `Address` too — reading one as routable pre-empts flyctl's own first-deploy fallback, which returns
+ * early once any assignment exists.
+ *
+ * Output that is not a JSON array THROWS rather than reading as "no address": the caller turns that
+ * into a gate, because a list we cannot read is not a state we can act on.
+ */
+export function ingressAddresses(stdout) {
+    const entries = JSON.parse(stdout);
+    if (!Array.isArray(entries))
+        throw new Error(`expected a JSON array, got ${typeof entries}`);
+    const has = (types) => entries.some((entry) => typeof entry?.Address === "string" && entry.Address !== "" && types.includes(entry.Type));
+    return { v4: has(INGRESS_TYPES.v4), v6: has(INGRESS_TYPES.v6) };
+}
+/**
+ * Whether a `fly … list --json` array contains an object named `name` (Fly capitalizes `Name`; accept
+ * both). Exported for the same reason railway's parsers are: what it encodes is an assumption about
+ * another tool's output, and the live probe checks that assumption against the real `flyctl`.
+ *
+ * THROWS on output that is not a JSON array, for the same reason {@link ingressAddresses} does —
+ * `false` here means "the host does not have it", and answering that for a list nobody could read
+ * creates a SECOND volume, or in teardown destroys nothing at all.
+ */
+export function listHasName(stdout, name) {
+    const entries = JSON.parse(stdout);
+    if (!Array.isArray(entries))
+        throw new Error(`expected a JSON array, got ${typeof entries}`);
+    return entries.some((o) => o.Name === name || o.name === name);
+}
+/**
+ * A read-only `fly … list --json`, reduced to the question the next step asks of it — or the gate for
+ * a list we cannot act on. THE place the three answers stay three: the command failed, the output was
+ * unreadable, or the host gave a verdict. Collapsing the middle one into `false` is what shipped #425
+ * and what would have skipped a teardown.
+ */
+async function readList(fly, args, read) {
+    // The command as RUN, not a restatement of it: a gate that tells the operator to run it themselves
+    // has to name one that works from their cwd, and `fly ips list --json` without `-a <app>` does not
+    // (fly.toml lives under the agent prefix, so flyctl finds no app).
+    const cmd = `fly ${args.join(" ")}`;
+    const result = await fly(args, { capture: true });
+    if (result.code !== 0)
+        return { gate: `\`${cmd}\` failed — see the flyctl output above; fix and re-run` };
     try {
-        const arr = JSON.parse(stdout);
-        return (Array.isArray(arr) &&
-            arr.some((o) => o.Name === name || o.name === name));
+        return { value: read(result.stdout) };
     }
-    catch {
-        return false;
+    catch (error) {
+        // The one place a parse failure is allowed to stop being an exception: this IS the boundary that
+        // turns it into the operator's gate (printed + non-zero exit), never a default answer.
+        return {
+            gate: `\`${cmd}\` was unreadable (${error instanceof Error ? error.message : String(error)}) — ` +
+                `run it yourself and check the flyctl version; fix and re-run`,
+        };
     }
 }
 /**
@@ -46,12 +101,13 @@ export async function deployFlyRun(plan, fly, log, registrars) {
     if (plan.missingSecrets.length > 0) {
         return gate(`no local value for: ${plan.missingSecrets.join(", ")} — set them in .env (or the environment) and re-run`);
     }
-    // 3. App — idempotent (create only if absent; a taken global name is a gate). A FAILED list is its own
-    //    gate: inferring "absent" from an errored query would then misreport the create as a name clash.
-    const appsList = await fly(["apps", "list", "--json"], { capture: true });
-    if (appsList.code !== 0)
-        return gate("`fly apps list` failed — see the flyctl output above; fix and re-run");
-    if (listHasName(appsList.stdout, plan.appName)) {
+    // 3. App — idempotent (create only if absent; a taken global name is a gate). An unusable list is its
+    //    own gate ({@link readList}): inferring "absent" from a query nobody could read would then
+    //    misreport the create as a name clash.
+    const appExists = await readList(fly, ["apps", "list", "--json"], (out) => listHasName(out, plan.appName));
+    if ("gate" in appExists)
+        return gate(appExists.gate);
+    if (appExists.value) {
         log(`app ${plan.appName} exists — skipping create`);
     }
     else {
@@ -63,10 +119,10 @@ export async function deployFlyRun(plan, fly, log, registrars) {
     }
     // 4. Volume — idempotent; region comes from fly.toml (must match the machine's region). A failed list
     //    gates for the same reason as the app list above.
-    const volList = await fly(["volumes", "list", "-a", plan.appName, "--json"], { capture: true });
-    if (volList.code !== 0)
-        return gate("`fly volumes list` failed — see the flyctl output above; fix and re-run");
-    if (listHasName(volList.stdout, "data")) {
+    const volumeExists = await readList(fly, ["volumes", "list", "-a", plan.appName, "--json"], (out) => listHasName(out, "data"));
+    if ("gate" in volumeExists)
+        return gate(volumeExists.gate);
+    if (volumeExists.value) {
         log(`volume data exists — skipping create`);
     }
     else {
@@ -76,7 +132,33 @@ export async function deployFlyRun(plan, fly, log, registrars) {
             return gate("`fly volumes create` failed — see the flyctl output above");
         }
     }
-    // 5. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
+    // 5. Ingress address — `[http_service]` in fly.toml DECLARES a service; it does not create an address
+    //    to reach it on. `fly launch` allocates one as part of its flow, and this driver does not use it,
+    //    so without this step the deploy succeeds, the machine serves, and `https://<app>.fly.dev` has no
+    //    DNS record at all — reported as a healthy deploy, and handed to the webhook registrars as a URL
+    //    they then fail to reach.
+    const addresses = await readList(fly, ["ips", "list", "-a", plan.appName, "--json"], ingressAddresses);
+    if ("gate" in addresses)
+        return gate(addresses.gate);
+    // Check-then-act PER FAMILY: an app that already holds one must still be given the other, or the
+    // gate between the two allocations below heals into a permanent half-state — the re-run the gate
+    // asks for sees the v4 it just made, skips, and reports success on an app with no v6 (and, the way
+    // that matters, no v4). v4 SHARED and v6 are both free; a dedicated v4 is billed, so it stays an
+    // operator decision — `fly ips allocate-v4 -a <app>` after the fact, which this step reads as v4.
+    for (const [family, allocate] of [
+        ["v4", ["ips", "allocate-v4", "--shared", "-a", plan.appName]],
+        ["v6", ["ips", "allocate-v6", "-a", plan.appName]],
+    ]) {
+        if (addresses.value[family]) {
+            log(`public ${family} address exists — skipping allocate`);
+            continue;
+        }
+        log(`allocating a public ${family} address…`);
+        if ((await fly([...allocate])).code !== 0) {
+            return gate(`\`fly ${allocate.join(" ")}\` failed — see the flyctl output above`);
+        }
+    }
+    // 6. Secrets — staged (no deploy yet; we deploy with fly.toml next). Values over stdin, not argv.
     const keys = Object.keys(plan.secrets);
     if (keys.length > 0) {
         log(`setting ${keys.length} secret(s): ${keys.join(", ")}`);
@@ -85,7 +167,7 @@ export async function deployFlyRun(plan, fly, log, registrars) {
             return gate("`fly secrets import` failed — see the flyctl output above");
         }
     }
-    // 6. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
+    // 7. Deploy — remote builder (no local Docker), one machine. Context + Dockerfile are passed
     //    explicitly (the workspace root is the context; the Dockerfile lives under fastagent/).
     log("deploying (remote build)…");
     const deployArgs = [
@@ -104,7 +186,7 @@ export async function deployFlyRun(plan, fly, log, registrars) {
     if ((await fly(deployArgs)).code !== 0) {
         return gate("`fly deploy` failed — see the flyctl output above; fix and re-run");
     }
-    // 7. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
+    // 8. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
     //    kernel's; Fly contributes its deterministic URL and how to retry.
     const registrationGateMsg = await registerWebhooks({
         baseUrl: `https://${plan.appName}.fly.dev`,

package/dist/deploy/hosts.d.ts

@@ -0,0 +1,5 @@
+/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ *  time without pulling a command module. */
+export declare const DEPLOY_HOSTS: readonly ["docker", "fly", "railway", "agentcore"];
+export type DeployHost = (typeof DEPLOY_HOSTS)[number];

package/dist/deploy/hosts.js

@@ -0,0 +1,4 @@
+/** The deploy targets, as a value: the CLI's `<host>` choices and the host-only-flag table's
+ *  exhaustiveness check both read it. Dependency-free, so `cli/program.ts` can import it at load
+ *  time without pulling a command module. */
+export const DEPLOY_HOSTS = ["docker", "fly", "railway", "agentcore"];

package/dist/deploy/preflight.js

@@ -14,7 +14,7 @@ import { basename, isAbsolute, join, relative, sep } from "node:path";
 import ignore from "ignore";
 import { classifyBind } from "../bind.js";
 import { resolveAuthPath } from "../engines/pi/config.js";
-import { resolveSecretsDir, resolveStateRoot, exists } from "../paths.js";
+import { resolveSecretsDir, resolveStateRoot, exists, readTextIfExists } from "../paths.js";
 import { inspectChannels } from "../channels/discover.js";
 import { discoverScheduleFiles } from "../schedule/discover.js";
 import { createPiModelRuntime, modelCredentialCarry, probeAuthSource } from "../engines/pi/models.js";
@@ -86,7 +86,7 @@ export async function preflightDeploy(input) {
                 `same value to callers: attach --url <public-url> --token …. Unset, the box mints its own per boot — ` +
                 `readable only by shelling in (\`docker compose exec\`/\`fly ssh console\`: <stateRoot>/control.json, whose ` +
                 `url field is container-loopback) and replaced on every restart. Front the endpoint with real auth for ` +
-                `anything wider (design §14)`,
+                `anything wider (docs/design/session-control.md §14)`,
         });
     }
     // Known channel kinds only — a custom channel's secrets/webhook are unknown to us; note and let the
@@ -299,7 +299,7 @@ export async function preflightDeploy(input) {
     // `docker build` (so it is the file that actually decides `deploy docker`). Checking only the root one
     // left the credential gate not covering the path it was written for.
     for (const rel of [".dockerignore", `${agentPrefix}Dockerfile.dockerignore`]) {
-        const kept = await readFile(join(workspace, rel), "utf8").catch(() => undefined);
+        const kept = await readTextIfExists(join(workspace, rel));
         if (kept === undefined)
             continue;
         // One WE generated is regenerated by this very run under --force, so checking the stale content on

package/dist/deploy/railway/plan.d.ts

@@ -50,6 +50,11 @@ export interface RailwayPlan {
  *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
  *  convention); two mechanisms, two documented spellings, one fact each. */
 export declare const dockerfilePathVar: (prefix: string) => string;
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
+ *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
+ *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
+ *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+export declare function toRailwayName(basename: string): string;
 /** Did fastagent generate this `railway.json`? Unparseable or unmarked reads as the author's. */
 export declare function isGeneratedRailwayJson(content: string): boolean;
 /** Compute the Railway deploy plan from the resolved definition. */

package/dist/deploy/railway/plan.js

@@ -8,6 +8,13 @@ const MOUNT = "/data";
  *  config file's `dockerfilePath` spells it WITHOUT the slash (the config-as-code schema's own
  *  convention); two mechanisms, two documented spellings, one fact each. */
 export const dockerfilePathVar = (prefix) => `/${prefix}Dockerfile`;
+/** The name this tool gives BOTH the project and the service, derived from the workspace directory.
+ *  Railway names are project-scoped (not globally unique like a Fly app), so this only has to survive
+ *  the command — slug anything that would break `railway add --service <name>`, and name the fallback
+ *  rather than emitting an empty argument. Shared so the live probe tears down what the CLI creates. */
+export function toRailwayName(basename) {
+    return basename.replace(/[^a-zA-Z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "agent";
+}
 /** railway.json is JSON, so its ownership marker is a KEY rather than a comment line. Railway ignores
  *  unknown keys; the predicate below is what lets `--force` reset OUR file and keep a hand-written one. */
 const GENERATED_RAILWAY_KEY = "x-generated-by";

package/dist/deploy/railway/run.d.ts

@@ -21,7 +21,8 @@
  *
  * Secrets go in one-per-`variable set --stdin` (value on stdin, never argv/process listing — Railway has
  * no bulk stdin import like Fly's `secrets import`). Auth needs an ACCOUNT credential (login or
- * `RAILWAY_API_KEY`), not a project token: `init` creates a project that a project token can't predate.
+ * `RAILWAY_API_TOKEN`), not the project-scoped `RAILWAY_TOKEN`: `init` creates a project that a project
+ * token can't predate.
  */
 import { type Registrars } from "../channel-ingress.ts";
 import type { DeclaredChannel } from "../../channels/discover.ts";

package/dist/deploy/railway/run.js

@@ -21,7 +21,8 @@
  *
  * Secrets go in one-per-`variable set --stdin` (value on stdin, never argv/process listing — Railway has
  * no bulk stdin import like Fly's `secrets import`). Auth needs an ACCOUNT credential (login or
- * `RAILWAY_API_KEY`), not a project token: `init` creates a project that a project token can't predate.
+ * `RAILWAY_API_TOKEN`), not the project-scoped `RAILWAY_TOKEN`: `init` creates a project that a project
+ * token can't predate.
  */
 import { registerWebhooks } from "../channel-ingress.js";
 /**
@@ -100,10 +101,10 @@ export async function deployRailwayRun(plan, railway, log, registrars) {
     // and it's ordered before the volume (which has no --service), so the mismatch fails visibly with no
     // side effect. (Pre-checking the name means walking status's nested multi-service shape — not worth it.)
     const svc = ["--service", plan.name];
-    // 1. Auth needs an ACCOUNT credential (browser login or RAILWAY_API_KEY) — a project token can't
-    //    predate the project `init` creates. `whoami` succeeds with either.
+    // 1. Auth needs an ACCOUNT credential (browser login or RAILWAY_API_TOKEN) — the project-scoped
+    //    RAILWAY_TOKEN can't predate the project `init` creates. `whoami` succeeds with either.
     if ((await railway(["whoami"], { capture: true })).code !== 0) {
-        return gate("not logged in to Railway — run `railway login`, or set RAILWAY_API_KEY (an account token), then re-run");
+        return gate("not logged in to Railway — run `railway login`, or set RAILWAY_API_TOKEN (an account token), then re-run");
     }
     // 2. Gate missing required secret VALUES before any side effect (no half-created infra).
     if (plan.missingSecrets.length > 0) {

package/dist/deploy/secrets.js

@@ -106,23 +106,6 @@ 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.some((channel) => channel.name === "slack")) {
-        const rotation = [
-            "SLACK_BOT_REFRESH_TOKEN",
-            "SLACK_BOT_TOKEN_EXPIRES_AT",
-            "SLACK_CLIENT_ID",
-            "SLACK_CLIENT_SECRET",
-        ];
-        if (rotation.some((name) => !!input.env[name])) {
-            for (const name of rotation) {
-                if (!input.env[name] && !missingSecrets.includes(name))
-                    missingSecrets.push(name);
-            }
-        }
-    }
     for (const name of input.extraSecrets ?? []) {
         if (name in secrets || missingSecrets.includes(name))
             continue; // already covered by model/channel — no dup

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

@@ -1,11 +1,13 @@
-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 { Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type AgentSessionServices, type CreateAgentSessionServicesOptions, type ModelRuntime, type SessionManager, createAgentSessionFromServices } 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>;
+import { type AnyModel } from "./models.ts";
+interface PiSessionDefinition {
+    systemPrompt?: string;
+    skills: Skill[];
+}
 export interface PiAgentSessionFactoryOptions {
     /** Where conversations live. Continuity = same store + same session id. */
     sessions: PiSessionRecordStore;
@@ -23,16 +25,8 @@ export interface PiAgentSessionFactoryOptions {
     }>;
     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[];
-    }>;
+    /** Read once per binding; prompt and skills come from the same definition read. */
+    readDefinition: () => PiSessionDefinition | Promise<PiSessionDefinition>;
     /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
     cwd: string;
     /**
@@ -66,9 +60,35 @@ export interface PiAgentSessionFactoryOptions {
     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;
 }
+export interface BindPiSessionOptions {
+    services: AgentSessionServices;
+    sessionManager: SessionManager;
+    /** Chat only: pi's runtime hands the resumed/new session its start event. */
+    sessionStartEvent?: Parameters<typeof createAgentSessionFromServices>[0]["sessionStartEvent"];
+    model: AnyModel;
+    thinkingLevel: ThinkingLevel | undefined;
+    tools: MountedTool[];
+    /** The agent's working directory — what fastagent-defined tools see as `cwd`. */
+    cwd: string;
+    /** Built-ins omitted by an explicit lower-level tool list. */
+    excludedToolNames?: readonly string[];
+    /** The CALLER's session id — what a tool asking which conversation it is in hears. Defaults to
+     *  pi's own id, which is right where the caller has none (chat). */
+    sessionId?: string;
+    /** Record each discovered activation on the session, so the next bind restores it. Off for chat:
+     *  pi's own session has nowhere to put one, so a resumed chat re-discovers. */
+    recordActivations: boolean;
+}
+/**
+ * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context,
+ * pi's own tool copies kept off, and deferral applied. The per-invoke factory and the resident chat
+ * runtime both bind here — they differ in what they hand in (a shared vs a per-session `services`,
+ * record-resolved vs configured settings) and in whether a discovered activation has a record to
+ * land in, and in nothing else. Two copies of this drifted once (the tool adapter and the deferral
+ * narrowing each existed twice, identical but for those parameters).
+ */
+export declare function bindPiSession(options: BindPiSessionOptions): ReturnType<typeof createAgentSessionFromServices>;
 /**
  * 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.

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

@@ -54,31 +54,102 @@ const warnedDroppedActivations = new Set();
  * 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) {
+function toolDefinitions(tools, bound, sessionId) {
     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)
+        ...tool,
+        label: tool.label || tool.name,
+        execute: (id, params, signal, onUpdate, ctx) => {
+            const binding = bound.current;
+            if (!binding)
                 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 }));
+            const { session, context } = binding;
+            // Expose the caller's id rather than Pi's filename encoding.
+            const sessionManager = Object.create(ctx.sessionManager, {
+                getSessionId: { value: () => sessionId },
+                getHeader: {
+                    value: () => {
+                        const header = ctx.sessionManager.getHeader();
+                        return header ? { ...header, id: sessionId } : header;
+                    },
+                },
+            });
+            // Pi's thinking getter uses a shared runtime; a restored cwd may be a symlink spelling.
+            const scoped = Object.create(ctx, {
+                sessionManager: { value: sessionManager },
+                cwd: { value: context.cwd },
+                thinkingLevel: { get: () => session.thinkingLevel },
+            });
+            return turnContext.run(context, () => tool.execute(id, params, signal, onUpdate, scoped));
         },
     }));
 }
+/**
+ * Bind ONE pi session to a record: the definition's tools as pi definitions over one turn context,
+ * pi's own tool copies kept off, and deferral applied. The per-invoke factory and the resident chat
+ * runtime both bind here — they differ in what they hand in (a shared vs a per-session `services`,
+ * record-resolved vs configured settings) and in whether a discovered activation has a record to
+ * land in, and in nothing else. Two copies of this drifted once (the tool adapter and the deferral
+ * narrowing each existed twice, identical but for those parameters).
+ */
+export async function bindPiSession(options) {
+    const { services, sessionManager, model, thinkingLevel, tools, cwd, recordActivations } = options;
+    const excludedToolNames = options.excludedToolNames ?? [];
+    const deferred = tools.filter(isDeferredTool).map((t) => t.name);
+    const bound = {};
+    const sessionId = options.sessionId ?? sessionManager.getSessionId();
+    const result = await createAgentSessionFromServices({
+        services,
+        sessionManager,
+        ...(options.sessionStartEvent ? { sessionStartEvent: options.sessionStartEvent } : {}),
+        model,
+        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. And
+        // NO `tools` allowlist: it would freeze the set at bind time, while pi lets an extension register
+        // from `session_start` — `noTools: "builtin"` gives the guarantee the allowlist was there for.
+        noTools: "builtin",
+        ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
+        customTools: toolDefinitions(tools, bound, sessionId),
+    });
+    const { session } = result;
+    // 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.current = {
+        session,
+        context: {
+            cwd,
+            sessionManager: agentSessionManager(session, sessionId),
+            // Persist each discovery so a served session can restore it on its next turn.
+            tools: sessionToolActivation(session, recordActivations
+                ? (added) => session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added })
+                : undefined),
+        },
+    };
+    // 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 = recordActivations ? 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 result;
+}
 /**
  * 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.
@@ -121,7 +192,7 @@ export function definitionResourceLoaderOptions(source) {
         // 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() ?? " ",
+        systemPromptOverride: () => source.systemPrompt() || " ",
         appendSystemPromptOverride: () => [],
         skillsOverride: (base) => ({
             skills: toPiSkills(source.skills()),
@@ -131,7 +202,7 @@ export function definitionResourceLoaderOptions(source) {
 }
 /** 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 { sessions, thinkingLevel, cwd } = options;
     const extensionPaths = options.extensionPaths ?? [];
     const excludedToolNames = options.excludedToolNames ?? [];
     if (extensionPaths.length > 0) {
@@ -140,10 +211,8 @@ export function piAgentSessionFactory(options) {
             "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 definition;
     let services;
     let engine;
     const buildServices = async (modelRuntime) => createAgentSessionServices({
@@ -155,23 +224,16 @@ export function piAgentSessionFactory(options) {
         // 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,
+            systemPrompt: () => definition.systemPrompt,
+            skills: () => definition.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;
+        const next = await options.readDefinition();
         engine ??= options.engine();
         const { modelRuntime, model } = await engine;
         if (services === undefined) {
-            prompt = nextPrompt;
-            skills = nextSkills;
+            definition = next;
             services = buildServices(modelRuntime); // assigned before any await: concurrent turns share it
         }
         else {
@@ -196,10 +258,10 @@ export function piAgentSessionFactory(options) {
             // 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);
+            const definitionChanged = loader.getSystemPrompt() !== (next.systemPrompt || " ") ||
+                skillSet(loader.getSkills().skills) !== skillSet(next.skills);
             if (definitionChanged) {
-                prompt = nextPrompt;
-                skills = nextSkills;
+                definition = next;
                 await loader.reload();
             }
         }
@@ -215,63 +277,25 @@ export function piAgentSessionFactory(options) {
             model,
             thinkingLevel: thinkingLevel ?? DEFAULT_THINKING_LEVEL,
         });
-        const bound = {};
-        const { session } = await createAgentSessionFromServices({
+        const { session } = await bindPiSession({
             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 = {
+            tools,
             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);
-            }
-        }
+            excludedToolNames,
+            sessionId,
+            recordActivations: true,
+        });
         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");
+    return skills
+        .map((s) => `${s.name}\u0000${s.filePath ?? ""}\u0000${s.description}\u0000${s.disableModelInvocation ?? false}`)
+        .join("\u0001");
 }
 /** fastagent's Skill (content inline) as pi's (read from filePath at invocation time). */
 function toPiSkills(skills) {