@fastagent-sh/fastagent 0.19.0 → 0.21.0

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

@@ -21,10 +21,11 @@
  *
  * 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 { RegistrationOutcome } from "../../channels/registration.ts";
-import type { ChannelKind } from "../../scaffold/add-channel.ts";
+import { type Registrars } from "../channel-ingress.ts";
+import type { DeclaredChannel } from "../../channels/discover.ts";
 import type { CliRunner } from "../runner.ts";
 export interface RailwayRunPlan {
     /** Names both the project (`railway init --name`) and the service (`railway add --service`). Railway
@@ -38,8 +39,8 @@ export interface RailwayRunPlan {
     secrets: Record<string, string>;
     /** Required secret names with NO local value — the run gates on these before any side effect. */
     missingSecrets: string[];
-    channels: ChannelKind[];
-    longConnectionChannels?: string[];
+    /** Every declared channel and its ingress — the driver asks which of them have a webhook. */
+    channels: readonly DeclaredChannel[];
     /** Opt-in (CLI `--into-linked`) to provision INTO the project this directory is already linked to. Off
      *  by default so `--run` only creates on an unlinked dir and never deploys into a pre-existing (possibly
      *  unrelated/production) project; the flag is the operator's explicit "yes, this project". */
@@ -84,9 +85,9 @@ export declare function parseDomainUrl(stdout: string): string | undefined;
  */
 export declare function parseHasVolume(stdout: string, mountPath: string): boolean;
 /**
- * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
- * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
- * never travels to the host). Absent, the manual console
- * instruction is printed. Every gate is fail-visible.
+ * Run the deploy through `railway`. `log` reports progress; the injected {@link Registrars} perform
+ * the post-deploy webhook steps from the builder machine (Slack's control credential never travels to
+ * the host). A registrar the caller did not wire becomes the printed manual step. Every gate is
+ * fail-visible.
  */
-export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registerTelegram: (baseUrl: string) => Promise<RegistrationOutcome>, registerFeishu?: (baseUrl: string, kind: "feishu" | "lark") => Promise<RegistrationOutcome>, registerSlack?: (baseUrl: string) => Promise<RegistrationOutcome>): Promise<RailwayRunOutcome>;
+export declare function deployRailwayRun(plan: RailwayRunPlan, railway: CliRunner, log: (msg: string) => void, registrars: Registrars): Promise<RailwayRunOutcome>;

package/dist/deploy/railway/run.js

@@ -1,4 +1,30 @@
-import { registrationGate } from "../registration-gate.js";
+/**
+ * `fastagent deploy railway --run` — drive the Railway CLI to completion. The middle of the deploy the
+ * plain runbook hands to the operator; `--run` executes it so a coding agent runs ONE command.
+ *
+ * Railway's model forces differences from the Fly runner (fly/run.ts), all validated against CLI 5.15.0:
+ *
+ *  - **`--run` PROVISIONS a project and only runs on an UNLINKED directory** — so it can never deploy
+ *    into a project it didn't create. `railway init` isn't check-then-act (it ALWAYS makes a new project)
+ *    and `railway status` exits 0 even when unlinked (linkedness is read from stdout: JSON when linked,
+ *    empty when not). We do NOT track ownership: a pre-existing link is refused (Railway has no globally
+ *    unique name to give free identity like Fly's app name, and synthesizing one — a machine-local marker
+ *    — was a large, bug-prone premature optimization). The only "yes, this project" signal is the operator's
+ *    explicit `--into-linked`, which provisions INTO the linked project; a routine redeploy is just
+ *    `railway up`. The volume is check-then-act, so `--into-linked` (or a create that failed at volume-add) still gets it.
+ *  - **Every command needs `--service` explicitly** to stay non-interactive (a bare command prompts to
+ *    pick a service). `railway volume add` is the exception — it has NO `--service` flag and rides the
+ *    linked service, so the service must be created (and thus linked) first.
+ *  - **The public URL is minted, not deterministic** — bare `railway domain --json` returns the service
+ *    domain (minting one if absent), read for the webhook. We avoid the newer `domain list` subcommand:
+ *    on a CLI without it, `railway domain list` registers a bogus custom domain named "list" (destructive).
+ *
+ * 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_TOKEN`), not the project-scoped `RAILWAY_TOKEN`: `init` creates a project that a project
+ * token can't predate.
+ */
+import { registerWebhooks } from "../channel-ingress.js";
 /**
  * Whether `railway status --json` shows a linked project: non-empty stdout. Unlinked prints its message
  * to stderr and leaves stdout EMPTY (the exit code is 0 either way, so it can't be the signal). ANY
@@ -62,12 +88,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `log` reports progress; the injected Telegram/Feishu/Slack
- * registrars perform post-deploy webhook steps from the builder machine (Slack's control credential
- * never travels to the host). Absent, the manual console
- * instruction is printed. Every gate is fail-visible.
+ * Run the deploy through `railway`. `log` reports progress; the injected {@link Registrars} perform
+ * the post-deploy webhook steps from the builder machine (Slack's control credential never travels to
+ * the host). A registrar the caller did not wire becomes the printed manual step. Every gate is
+ * fail-visible.
  */
-export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu, registerSlack) {
+export async function deployRailwayRun(plan, railway, log, registrars) {
     const gate = (g) => ({ ok: false, gate: g });
     // Every --service below targets plan.name — the name this tool gives BOTH the project and the service
     // (`init --name` + `add --service`). On a fresh create they match; on `--into-linked` into a hand-made
@@ -75,10 +101,10 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
     // 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) {
@@ -173,40 +199,15 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram, reg
     if (!url) {
         return gate("couldn't read a domain from `railway domain` — run `railway domain` manually, then set any webhook");
     }
-    // 7. Post-deploy webhook — gate policy is the shared registration-gate kernel (registrars report
-    //    facts, it owns the policy); all channels are attempted first.
-    const reg = registrationGate(log, "re-run with --into-linked to retry registration");
-    if (plan.channels.includes("telegram")) {
-        log("registering telegram webhook…");
-        reg.track("telegram", await registerTelegram(url));
-    }
-    if (plan.channels.includes("github")) {
-        log(`github: set the webhook in the repo (Settings → Webhooks) → ${url}/webhook`);
-        reg.track("github", "manual"); // always a human step — re-surface it after the registrar output
-    }
-    if (plan.channels.includes("slack")) {
-        if (registerSlack) {
-            log("registering slack event URL…");
-            reg.track("slack", await registerSlack(url));
-        }
-        else {
-            log(`slack: set Event Subscriptions → Request URL → ${url}/slack`);
-            reg.track("slack", "manual");
-        }
-    }
-    for (const kind of ["feishu", "lark"]) {
-        if (!plan.channels.includes(kind) || plan.longConnectionChannels?.includes(kind))
-            continue;
-        if (registerFeishu) {
-            log(`registering ${kind} event URL…`);
-            reg.track(kind, await registerFeishu(url, kind));
-        }
-        else {
-            log(`${kind}: set the event Request URL in the developer console (Events & Callbacks) → ${url}/${kind} (the service must be running when you save)`);
-            reg.track(kind, "manual"); // no registrar wired — the console step above is the operator's
-        }
-    }
-    const registrationGateMsg = reg.gate();
+    // 7. Post-deploy webhook — which channels, in what words, and the gate policy are all the shared
+    //    kernel's; Railway contributes the minted URL and how to retry.
+    const registrationGateMsg = await registerWebhooks({
+        baseUrl: url,
+        channels: plan.channels,
+        registrars,
+        log,
+        retryHint: "re-run with --into-linked to retry registration",
+    });
     if (registrationGateMsg)
         return gate(registrationGateMsg);
     return { ok: true, url };

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
@@ -85,31 +106,45 @@ 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")) {
-        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
         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,12 +13,12 @@
 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 "./paths.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. */
 /**
@@ -108,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

@@ -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.