@fastagent-sh/fastagent 0.12.1 → 0.14.0

package/dist/deploy/railway/run.js

@@ -1,3 +1,4 @@
+import { registrationGate } from "../registration-gate.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
@@ -61,10 +62,12 @@ export function parseHasVolume(stdout, mountPath) {
     return jsonStrings(stdout).includes(mountPath);
 }
 /**
- * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` performs the
- * post-deploy webhook step (the CLI passes its telegram registrar). Every gate is fail-visible.
+ * Run the deploy through `railway`. `log` reports progress; `registerTelegram(baseUrl)` /
+ * `registerFeishu(baseUrl, kind)` perform the post-deploy webhook steps (the CLI passes its canonical
+ * Feishu registrar, which also serves the Lark compatibility profile). Absent, the manual console
+ * instruction is printed. Every gate is fail-visible.
  */
-export async function deployRailwayRun(plan, railway, log, registerTelegram) {
+export async function deployRailwayRun(plan, railway, log, registerTelegram, registerFeishu) {
     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
@@ -165,12 +168,31 @@ export async function deployRailwayRun(plan, railway, log, registerTelegram) {
     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…");
-        await registerTelegram(url);
+        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
+    }
+    for (const kind of ["feishu", "lark"]) {
+        if (!plan.channels.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();
+    if (registrationGateMsg)
+        return gate(registrationGateMsg);
     return { ok: true, url };
 }

package/dist/deploy/registration-gate.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Host-NEUTRAL step-7 gate policy, shared by the host runners: the registrars report facts
+ * ({@link RegistrationOutcome}), this module owns what to do about them.
+ *
+ * - "failed" gates — exit 0 would tell a coding agent "done" while the deployed agent cannot receive
+ *   messages, and the runners' earlier steps are idempotent so a re-run just retries registration.
+ * - "manual" does NOT gate — re-running can never change it (an unclearable gate would spin a coding
+ *   agent forever) — but is re-surfaced after all registrar output (and before any gate message) so
+ *   the operator cannot miss it under the registrar's earlier log lines.
+ *
+ * The runners attempt ALL channels first (one failure doesn't skip the rest), then apply this policy
+ * once. Only the retry remediation differs per host (`retryHint`).
+ */
+import type { RegistrationOutcome } from "../channels/registration.ts";
+export declare function registrationGate(log: (msg: string) => void, retryHint: string): {
+    track: (kind: string, outcome: RegistrationOutcome) => void;
+    /** Logs the manual notices; returns the gate message (composes with cli.ts's "deploy stopped:"
+     *  prefix — it leads with the failure, not "the deploy succeeded"), or undefined for no gate. */
+    gate: () => string | undefined;
+};

package/dist/deploy/registration-gate.js

@@ -0,0 +1,20 @@
+export function registrationGate(log, retryHint) {
+    const unregistered = [];
+    const manual = [];
+    return {
+        track(kind, outcome) {
+            if (outcome === "failed")
+                unregistered.push(kind);
+            if (outcome === "manual")
+                manual.push(kind);
+        },
+        gate() {
+            for (const kind of manual) {
+                log(`${kind}: webhook registration needs a one-time manual step — see the instructions above`);
+            }
+            if (unregistered.length === 0)
+                return undefined;
+            return `webhook registration failed for: ${unregistered.join(", ")} — the app itself deployed; fix the error above, then ${retryHint}`;
+        },
+    };
+}

package/dist/deploy/runner.d.ts

@@ -5,10 +5,13 @@ export interface RunResult {
     stdout: string;
 }
 /** Run `bin args`: `capture` collects stdout (for `--json` queries), else the command streams to the
- *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv). */
+ *  terminal (create/deploy) and stdout is empty; `input` is fed to stdin (secrets over stdin, never argv).
+ *  `env` adds child-only environment values — Docker Compose interpolates secrets from it without putting
+ *  values in argv or mutating the long-lived CLI process. */
 export type CliRunner = (args: string[], opts?: {
     capture?: boolean;
     input?: string;
+    env?: NodeJS.ProcessEnv;
 }) => Promise<RunResult>;
 /**
  * Production {@link CliRunner}: spawn `bin` in `cwd` (the workspace, so a build/upload context is the

package/dist/deploy/runner.js

@@ -13,6 +13,7 @@ export function spawnRunner(bin, cwd) {
     return (args, opts) => new Promise((res) => {
         const child = spawn(bin, args, {
             cwd,
+            env: opts?.env ? { ...process.env, ...opts.env } : process.env,
             stdio: [opts?.input ? "pipe" : "inherit", opts?.capture ? "pipe" : "inherit", "inherit"],
         });
         let out = "";

package/dist/deploy/secrets.d.ts

@@ -1,8 +1,7 @@
 /**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
- * required (the model key when local auth is an env key + every discovered channel's secrets) is the
- * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
- * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ * 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";
 /**
@@ -13,13 +12,15 @@ import { type ChannelKind } from "../scaffold/add-channel.ts";
  */
 export declare function isEnvKey(source: string | undefined): source is string;
 /**
- * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
- * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
+ * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
+ * 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 requiredSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
+export declare function deploymentSecrets(modelAuth: string | undefined, channels: ChannelKind[], extraSecrets?: string[]): {
     name: string;
     hint: string;
+    required: boolean;
 }[];
 /**
  * Assemble the secret VALUES a `--run` deploy sets on the host, from the local credential + channels —
@@ -32,8 +33,8 @@ export declare function requiredSecrets(modelAuth: string | undefined, channels:
  *
  * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
  * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
- * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
+ * required value enters `missingSecrets`; an absent optional value is simply omitted.
  */
 export declare function assembleSecrets(input: {
     modelAuth: string | undefined;

package/dist/deploy/secrets.js

@@ -1,8 +1,7 @@
 /**
- * The secret set a deployed agent needs, computed from the definition — host-neutral. WHAT secrets are
- * required (the model key when local auth is an env key + every discovered channel's secrets) is the
- * same on every target; only the SET command differs (`fly secrets import` vs `railway variables set`).
- * The runbooks list these NAMES; `--run` (per host) reads their VALUES from the local env.
+ * 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 { channelSetup } from "../scaffold/add-channel.js";
 /**
@@ -15,22 +14,23 @@ export function isEnvKey(source) {
     return source !== undefined && /^[A-Z][A-Z0-9_]*$/.test(source);
 }
 /**
- * The required secret NAMES + hints for a runbook: the model key (when local auth is an env key) plus
- * every discovered channel's secrets. An OAuth/stored login has no env key here — it carries as
+ * Secret NAMES + hints for a runbook: the model key (when local auth is an env key), discovered channel
+ * secrets, and config extras. Channel metadata keeps optional values visible without presenting them as
+ * 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 requiredSecrets(modelAuth, channels, extraSecrets = []) {
+export function deploymentSecrets(modelAuth, channels, extraSecrets = []) {
     const secrets = [];
     if (isEnvKey(modelAuth))
-        secrets.push({ name: modelAuth, hint: "your model provider key" });
+        secrets.push({ name: modelAuth, hint: "your model provider key", required: true });
     for (const kind of channels) {
         for (const e of channelSetup(kind).env)
-            secrets.push({ name: e.name, hint: e.hint });
+            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" });
+            secrets.push({ name, hint: "declared in fastagent.config deploy.secrets", required: true });
         }
     }
     return secrets;
@@ -46,8 +46,8 @@ export function requiredSecrets(modelAuth, channels, extraSecrets = []) {
  *
  * Channel secrets come from the local env only — NEVER minted. A random mint would be wrong for a
  * human-shared secret (github's webhook secret must match the value the operator enters in the repo,
- * which a silent mint never surfaces) and would rotate every run (breaking idempotency). Absent →
- * `missingSecrets`, same as the plain runbook's operator-filled placeholders.
+ * which a silent mint never surfaces) and would rotate every run (breaking idempotency). An absent
+ * required value enters `missingSecrets`; an absent optional value is simply omitted.
  */
 export function assembleSecrets(input) {
     const secrets = {};
@@ -70,9 +70,10 @@ export function assembleSecrets(input) {
         for (const e of channelSetup(kind).env) {
             const v = input.env[e.name];
             if (v)
-                secrets[e.name] = v;
-            else
+                secrets[e.name] = v; // optional channel values travel when configured
+            else if (e.required) {
                 missingSecrets.push(e.name); // operator-provided (in .env); a human-shared secret can't be minted
+            }
         }
     }
     for (const name of input.extraSecrets ?? []) {

package/dist/dev-supervisor.js

@@ -16,6 +16,7 @@ import { watch as watchTree } from "chokidar";
 import { loadConfig, resolveAgentDir } from "./engines/pi/config.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 (workspace-relative): the process-bound code inputs only. */
 export const WATCHED_HINT = "tools/, channels/, package.json (agent dir), fastagent.config.*, .env (run root)";
@@ -99,7 +100,7 @@ export async function runDevSupervisor(dir, options = {}) {
                 void startCloudflareTunnel(m.port).then((t) => {
                     if (t) {
                         tunnel = t;
-                        void announceWebhooks(agentDir, t.url);
+                        void announceWebhooks(agentDir, t.url, { openUrl: openExternalUrl });
                     }
                 });
             }

package/dist/engines/pi/auth.js

@@ -12,22 +12,24 @@
  * token and persisting the new one elsewhere leaves global stale for every other consumer.
  *
  * Sharing is still SAFE the right way: point everything at ONE file (`FASTAGENT_AUTH_PATH` → the
- * global path). One file means one refresh lifecycle under `FileAuthStorageBackend`'s cross-process
- * lock (refresh re-reads the latest token under the lock) — the documented same-machine pattern.
+ * global path). One file means one refresh lifecycle under the store's cross-process write lock
+ * (refresh re-reads the latest token under the lock), the documented same-machine pattern.
  * fastagent's store stays SEPARATE from the pi CLI's `~/.pi/agent/auth.json` for the same single-
  * lifecycle reason: two uncoordinated files over one grant would each rotate and break the other.
  *
- * Persistence + locking reuse pi's `FileAuthStorageBackend` (a cross-process file lock) on the WRITE
- * path only. `read` is pi-ai's per-request hot path, so it stays UNLOCKED; the backend's in-place
- * write opens only a sub-millisecond torn-read window, which `read` absorbs by re-reading. The write
- * path refuses to overwrite a corrupt file (never clobbering other providers' credentials).
+ * Locking is vendored here on `proper-lockfile`, with the same parameters pi's file backend used
+ * before pi 0.80.8 stopped exporting it (upstream's stated migration path for SDK consumers is a
+ * custom pi-ai `CredentialStore`, which this file is). The lock guards the WRITE path only. `read`
+ * is pi-ai's per-request hot path, so it stays UNLOCKED; the in-place locked write opens only a
+ * sub-millisecond torn-read window, which `read` absorbs by re-reading. The write path refuses to
+ * overwrite a corrupt file (never clobbering other providers' credentials).
  */
-import { existsSync, readFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { log } from "../../log.js";
 import { setTimeout as sleep } from "node:timers/promises";
-import { FileAuthStorageBackend } from "@earendil-works/pi-coding-agent";
+import lockfile from "proper-lockfile";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`). The project-level default is
  * `<dir>/.fastagent/auth.json` (computed by the opener and by `fastagent login`); this is only the
@@ -42,57 +44,169 @@ function pick(creds, providerId) {
     const cred = creds[providerId];
     return cred && (cred.type === "oauth" || cred.type === "api_key") ? cred : undefined;
 }
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
 /**
- * Parse the credentials JSON for a WRITE: a corrupt file must THROW — serializing `{}` over it would
- * wipe every other provider's credentials. The throw aborts the locked write, leaving the file intact.
+ * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
+ * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
+ * Ensures the file exists first (0700 dir, 0600 file, EXCLUSIVE create: a concurrent first write
+ * must never be clobbered by the init) because `proper-lockfile` locks an existing path. A
+ * compromised lock aborts before the write rather than clobbering a concurrent writer, and a
+ * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
  */
-function parseForWrite(raw, where) {
-    if (!raw)
-        return {};
+async function withLockedAuthFile(authPath, fn) {
+    const dir = dirname(authPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    if (!existsSync(authPath)) {
+        try {
+            writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
+            chmodSync(authPath, 0o600);
+        }
+        catch (error) {
+            // EEXIST: another process created the file between the existence check and this exclusive
+            // create; its content (possibly already-written credentials) must not be clobbered.
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    let compromised;
+    const throwIfCompromised = () => {
+        if (compromised)
+            throw compromised;
+    };
+    const release = await lockfile.lock(authPath, {
+        retries: { retries: 10, factor: 2, minTimeout: 100, maxTimeout: 10_000, randomize: true },
+        stale: 30_000,
+        onCompromised: (error) => {
+            compromised = error;
+        },
+    });
+    let result;
+    try {
+        throwIfCompromised();
+        const current = existsSync(authPath) ? readFileSync(authPath, "utf8") : undefined;
+        const out = await fn(current);
+        throwIfCompromised();
+        if (out.next !== undefined) {
+            writeFileSync(authPath, out.next, AUTH_FILE_WRITE_OPTIONS);
+            chmodSync(authPath, 0o600);
+        }
+        throwIfCompromised();
+        result = out.result;
+    }
+    catch (error) {
+        // The primary failure stays the signal; unlock noise must not mask it.
+        try {
+            await release();
+        }
+        catch {
+            // Secondary: a compromised or stale-reclaimed lock often cannot release cleanly.
+        }
+        throw error;
+    }
+    // Success path: a failed release is a real cleanup failure (the leftover auth.json.lock stalls
+    // the next writer for the staleness window with zero diagnostics), so it surfaces instead of
+    // resolving a silently degraded operation. A compromise detected after the last in-band check
+    // surfaces here too.
+    try {
+        await release();
+    }
+    catch (releaseError) {
+        if (compromised === undefined)
+            throw releaseError;
+    }
+    throwIfCompromised();
+    return result;
+}
+/**
+ * Decode the credentials JSON, shared by the read and write paths. The root must be a plain
+ * non-null, non-array object: `[]`, `null`, and scalar roots pass JSON.parse but break the record
+ * semantics (an array root even swallows writes, since JSON.stringify drops string keys on arrays).
+ * Structurally invalid = corrupt, exactly like unparsable text.
+ */
+function decodeCreds(raw) {
+    let parsed;
     try {
-        return JSON.parse(raw);
+        parsed = JSON.parse(raw);
     }
     catch {
-        throw new Error(`refusing to overwrite corrupt auth file ${where} — fix or remove it`);
+        return undefined;
     }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return undefined;
+    return parsed;
+}
+/**
+ * Tolerant UNLOCKED read of the whole credentials file, shared by `read` and `list`. The only race
+ * is a sub-millisecond in-place write during an OAuth rotation, which can yield an empty/partial
+ * file; re-read a few times before concluding it is corrupt. A missing file reads as undefined
+ * silently (normal not-configured); a valid file returns immediately, so the common case costs one
+ * read.
+ */
+async function readCreds(authPath, warn) {
+    for (let attempt = 0; attempt < 3; attempt++) {
+        let raw;
+        try {
+            raw = readFileSync(authPath, "utf8");
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined; // missing/deleted
+            warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
+            return undefined;
+        }
+        if (raw !== "") {
+            const creds = decodeCreds(raw);
+            if (creds !== undefined)
+                return creds;
+            // A partial read mid-write parses as garbage; fall through and retry. A structurally invalid
+            // root lands here too and is reported as corrupt below.
+        }
+        if (attempt < 2)
+            await sleep(2);
+    }
+    warn(`[fastagent] corrupt auth file ${authPath}: fix or remove it`);
+    return undefined;
+}
+/**
+ * Parse the credentials JSON for a WRITE: a corrupt file must THROW, because serializing `{}` over
+ * it would wipe every other provider's credentials. The throw aborts the locked write, leaving the
+ * file intact.
+ */
+function parseForWrite(raw, where) {
+    if (!raw)
+        return {};
+    const creds = decodeCreds(raw);
+    if (creds === undefined) {
+        throw new Error(`refusing to overwrite corrupt auth file ${where}: fix or remove it`);
+    }
+    return creds;
 }
 /** A read-write `CredentialStore` backed by the given credentials file (default {@link GLOBAL_AUTH_PATH};
  *  the directory opener passes the project-level `<dir>/.fastagent/auth.json`). */
 export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options = {}) {
     const warn = options.warn ?? ((message) => log.warn(message));
-    const backend = new FileAuthStorageBackend(authPath);
     return {
         async read(providerId) {
-            // UNLOCKED hot path: the only race is a sub-millisecond in-place write during an OAuth rotation,
-            // which can yield an empty/partial file. Re-read a few times before concluding it is corrupt;
-            // a valid `{}` (provider absent) returns immediately, so a not-configured read costs nothing.
-            for (let attempt = 0; attempt < 3; attempt++) {
-                let raw;
-                try {
-                    raw = readFileSync(authPath, "utf8");
-                }
-                catch (error) {
-                    if (error.code === "ENOENT")
-                        return undefined; // missing/deleted
-                    warn(`[fastagent] cannot read ${authPath}: ${error.message}`);
-                    return undefined;
-                }
-                if (raw !== "") {
-                    try {
-                        return pick(JSON.parse(raw), providerId);
-                    }
-                    catch {
-                        // A partial read mid-write parses as garbage — fall through and retry.
-                    }
+            const creds = await readCreds(authPath, warn);
+            return creds ? pick(creds, providerId) : undefined;
+        },
+        async list() {
+            // Metadata only, never secrets (the pi-ai `list` contract). Foreign/old entries are filtered
+            // with the same validation as `read`, so both surfaces agree on what "configured" means.
+            const creds = await readCreds(authPath, warn);
+            if (!creds)
+                return [];
+            const infos = [];
+            for (const [providerId, cred] of Object.entries(creds)) {
+                if (cred && (cred.type === "oauth" || cred.type === "api_key")) {
+                    infos.push({ providerId, type: cred.type });
                 }
-                if (attempt < 2)
-                    await sleep(2);
             }
-            warn(`[fastagent] corrupt auth file ${authPath} — fix or remove it`);
-            return undefined;
+            return infos;
         },
         modify(providerId, fn) {
-            return backend.withLockAsync(async (current) => {
+            return withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath); // corrupt → throw → no clobber
                 const next = await fn(pick(creds, providerId));
                 if (next === undefined)
@@ -102,11 +216,11 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
             });
         },
         async delete(providerId) {
-            // No-op when nothing is stored: do NOT take the lock (which would create the file via the
-            // backend's ensureFileExists) on a machine that never stored this provider.
+            // No-op when nothing is stored: do NOT take the lock (which would create the file) on a
+            // machine that never stored this provider.
             if (!existsSync(authPath))
                 return;
-            await backend.withLockAsync(async (current) => {
+            await withLockedAuthFile(authPath, async (current) => {
                 const creds = parseForWrite(current, authPath);
                 if (!(providerId in creds))
                     return { result: undefined }; // absent: no write

package/dist/engines/pi/chat.js

@@ -7,7 +7,7 @@
  * AGENTS.md up to the repo root and discover skills from pi's own global dirs). So fastagent's
  * assembly is INJECTED into pi's session:
  *   - prompt  → systemPromptOverride = base + instructions ONLY; pi appends the skill section and env
- *               (date/cwd) itself (including them here would duplicate both).
+ *               (cwd) itself (including it here would duplicate it).
  *   - skills  → skillsOverride (fastagent's skills, for the section + invocation).
  *   - tools   → default coding tools by NAME (pi rebuilds them cwd-bound for rich rendering) +
  *               fastagent's custom tools via pi's customTools path (so they survive /new, /resume, fork).
@@ -28,7 +28,9 @@ import { loadConfig, resolveAgentDir, resolveModel, resolveModelSpec } from "./c
 import { assembleSystemPrompt, piBasePrompt, piDefaultTools, resolveTools } from "./create.js";
 import { createPiModels } from "./models.js";
 import { canonicalPath, loadAgentDefinition } from "./definition.js";
-import { loadTools, mergeDiscoveredTools } from "./tool.js";
+import { isDeferredTool, loadTools, mergeDiscoveredTools } from "./tool.js";
+import { withSearchTool } from "./search-tools.js";
+import { additiveActivation, turnContext } from "./tool-context.js";
 import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollisions } from "./report.js";
 /**
  * Build pi's interactive runtime driven by fastagent's assembled agent (model, prompt, tools,
@@ -38,6 +40,34 @@ import { reportDefinitionWarnings, reportModuleLoadFailures, reportToolCollision
 export async function buildChatRuntime(dir, options = {}, 
 /** Session backend. Defaults to pi's project-scoped store; tests inject SessionManager.inMemory(). */
 sessionManager) {
+    /** The turn's {@link ToolActivation} over pi's AgentSession — the chat counterpart of invoke.ts's
+     *  harness bridge, so the SAME builtin search_tools serves both paths. Additive; unknown names
+     *  filtered (`setActiveToolsByName` is authoritative on the session and rebuilds its prompt — our
+     *  static override keeps the prompt identical to serving). */
+    function chatToolActivation(session) {
+        // Same serialization as invoke.ts's bridge (there per turn; here per session — chat turns are
+        // interactive, so per-session is equivalent): the read-modify-write below is only race-free while
+        // nothing awaits between read and write, and pi's session setters happening to be synchronous today
+        // is not a contract worth betting parallel tool batches on. Built ONCE per session (createRuntime),
+        // so parallel calls actually share the chain.
+        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]);
+                    return added;
+                };
+                const result = chain.then(run, run); // run after the predecessor settles, success or failure
+                chain = result.catch(() => []); // the caller sees a rejection on `result`; the chain stays usable
+                return result;
+            },
+        };
+    }
     async function resolveAssembly(cwd) {
         const { config } = await loadConfig(cwd);
         const modelSpec = resolveModelSpec(options.model, config);
@@ -55,21 +85,42 @@ sessionManager) {
         // Same tool resolution as the dev opener, then split: defaults go to pi by NAME (rebuilt cwd-bound
         // for rich rendering); customs go through pi's `customTools` path so they survive /new, /resume, fork.
         const discovered = await loadTools(agentDir);
-        const { tools, collisions: crossCollisions } = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+        const merged = mergeDiscoveredTools(resolveTools(config, cwd), discovered.tools);
+        // Chat EMULATES deferral, like serving (what you iterate is what you serve): the builtin loader
+        // mounts when a deferred tool exists, the initial active set excludes deferred tools (applied on
+        // the session in createRuntime below — pi's TUI session starts all-active), and the activation
+        // bridge below rides the same turn context the serving path uses, so the SAME search_tools works
+        // against pi's AgentSession instead of fastagent's harness.
+        const tools = withSearchTool(merged.tools);
+        const crossCollisions = merged.collisions;
         reportToolCollisions([...discovered.collisions, ...crossCollisions]);
         reportModuleLoadFailures(discovered.failures);
         const defaultNames = piDefaultTools(cwd).map((t) => t.name);
         const customTools = tools.filter((t) => !defaultNames.includes(t.name));
-        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts it).
+        // Adapt fastagent's AgentTool to pi's ToolDefinition (`parameters` is plain JSON-Schema; pi accepts
+        // it). Each execute runs inside the turn context with the CURRENT session's activation bridge — the
+        // assembly is memoized across /new//resume/fork rebuilds while the session changes, so the bridge
+        // resolves through sessionRef at call time, exactly like the serving path resolves its harness.
         const customToolDefs = customTools.map((t) => ({
             name: t.name,
             label: t.name,
             description: t.description ?? "",
             parameters: t.parameters,
-            execute: (id, params, signal) => t.execute(id, params, signal),
+            // Propagate the execution mode — an activating tool (the builtin loader) declares "sequential"
+            // so pi serializes its batch; without this, pi's outer active-set diff double-stamps parallels.
+            executionMode: t.executionMode,
+            execute: (id, params, signal) => {
+                const bound = sessionRef.current;
+                // Unreachable by construction (createRuntime sets sessionRef before any turn can run a tool).
+                // Throw rather than silently run outside the turn context — that would disguise a broken
+                // session-lifecycle invariant as a normal out-of-turn call (fail visibly).
+                if (!bound)
+                    throw new Error("chat tool executed before its session was built (lifecycle invariant broken)");
+                return turnContext.run({ session: bound.session.sessionId, tools: bound.activation }, () => t.execute(id, params, signal));
+            },
         }));
-        // base + instructions ONLY — pi appends the skill section and env (date/cwd) itself (including
-        // them here would duplicate both).
+        // base + instructions ONLY — pi appends the skill section and env (cwd) itself (including
+        // them here would duplicate them).
         const systemPrompt = assembleSystemPrompt({
             base: piBasePrompt({ tools, persona: definition.persona }),
             contextFiles: definition.contextFiles,
@@ -82,6 +133,13 @@ sessionManager) {
     // edits. And keep it workspace-scoped — `.env` is process-global, so a switch to another cwd would
     // leak env or require mutating global env at runtime.
     const rootCwd = canonicalPath(dir);
+    // The CURRENT pi session + its activation bridge, BOUND TOGETHER — rebuilt on /new//resume/fork
+    // while the memoized assembly (and its tool execute closures) stays. The bridge must share the
+    // session's lifetime, NOT be rebuilt per tool call (a per-call chain serializes nothing). Note on
+    // parallel batches: pi wraps SDK customTools in its own before/after active-set diff, so an
+    // activating tool must carry `executionMode: "sequential"` (the builtin loader does) — pi then runs
+    // the whole batch serially and the outer diff sees correct snapshots.
+    const sessionRef = {};
     let assembly;
     const assemblyFor = (cwd) => {
         // Canonical paths: pi's process.cwd() fallback is a realpath, so a symlinked workspace would
@@ -135,6 +193,21 @@ sessionManager) {
             tools: [...defaultNames, ...customTools.map((t) => t.name)],
             customTools: customToolDefs,
         });
+        sessionRef.current = { session: result.session, activation: chatToolActivation(result.session) };
+        // Deferral emulation: pi's TUI session starts with everything active — narrow it by SUBTRACTING
+        // the deferred names from whatever is active (robust to pi mounting tools of its own; an
+        // exact-set-equality gate would silently stop narrowing the day pi adds one). Applied on EVERY
+        // build including /resume: pi's chat session does not record activations (its SessionContext has
+        // no activeToolNames), so "restore prior activations" is not implementable here — deferral stays
+        // consistently ON and a resumed conversation re-discovers via search_tools (documented divergence
+        // from serving, where activations persist in the session).
+        const deferredNames = customTools.filter(isDeferredTool).map((t) => t.name);
+        if (deferredNames.length > 0) {
+            const active = result.session.getActiveToolNames();
+            if (deferredNames.some((n) => active.includes(n))) {
+                result.session.setActiveToolsByName(active.filter((n) => !deferredNames.includes(n)));
+            }
+        }
         return { ...result, services, diagnostics: services.diagnostics };
     };
     const runtime = await createAgentSessionRuntime(createRuntime, {