@fastagent-sh/fastagent 0.19.0 → 0.20.0

package/dist/deploy/secrets.js

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

package/dist/dev-supervisor.js

@@ -13,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.js

@@ -18,7 +18,7 @@ import { log } from "../../log.js";
 import { isDeferredTool } from "./tool.js";
 import { activePath, resolveSessionSettings } from "./session-settings.js";
 import { DEFAULT_THINKING_LEVEL } from "./models.js";
-import { additiveActivation, agentSessionManager, turnContext } from "./tool-context.js";
+import { agentSessionManager, sessionToolActivation, turnContext } from "./tool-context.js";
 /**
  * The session custom-entry type recording ONE activation delta: `{ names }` — exactly the deferred
  * tools a loader activated in that call.
@@ -47,37 +47,6 @@ function recordedActivations(session) {
 /** Warned once per session+missing set: a fresh session is built per invoke and channel sessions run
  *  for weeks, so an un-deduped warn would repeat every turn and dilute its own signal. */
 const warnedDroppedActivations = new Set();
-/**
- * The turn's {@link ToolActivation} over a live session — the same bridge chat uses, so one
- * built-in `search_tools` serves both.
- *
- * Activations are PERSISTED as deltas, so a tool discovered in one turn stays callable in the next.
- * pi's own chat session does not do this (it has no place to put the record); a served session does,
- * because the alternative is an agent that re-discovers the same capability every single turn.
- */
-function sessionToolActivation(session) {
-    // Serialize activations: the read-modify-write below is only race-free while nothing awaits
-    // between read and write, and parallel tool calls in one batch would otherwise double-stamp.
-    let chain = Promise.resolve([]);
-    return {
-        active: () => session.getActiveToolNames(),
-        registered: () => session.getAllTools().map((t) => ({ name: t.name, description: t.description ?? "" })),
-        activate(names) {
-            const run = async () => {
-                const current = session.getActiveToolNames();
-                const added = additiveActivation(session.getAllTools().map((t) => t.name), current, names);
-                if (added.length > 0) {
-                    session.setActiveToolsByName([...current, ...added]);
-                    session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added });
-                }
-                return added;
-            };
-            const result = chain.then(run, run);
-            chain = result.catch(() => []);
-            return result;
-        },
-    };
-}
 /**
  * fastagent's tools as pi tool definitions, bound to ONE session.
  *
@@ -85,8 +54,12 @@ function sessionToolActivation(session) {
  * 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, cwd, env, sessionId, bound) {
+function toolDefinitions(tools, env, bound) {
     return tools.map((tool) => ({
         name: tool.name,
         label: tool.name,
@@ -96,10 +69,10 @@ function toolDefinitions(tools, cwd, env, sessionId, bound) {
         // without it pi's outer active-set diff double-stamps parallel calls.
         executionMode: tool.executionMode,
         execute: (id, params, signal) => {
-            const session = bound.session;
-            if (!session)
-                throw new Error("tool executed before its session was bound (lifecycle invariant broken)");
-            return turnContext.run({ cwd, sessionManager: agentSessionManager(session, sessionId), tools: sessionToolActivation(session) }, 
+            const context = bound.context;
+            if (!context)
+                throw new Error("tool executed before its turn context was bound (lifecycle invariant broken)");
+            return turnContext.run(context, 
             // Lower-level MountedTools may consume the fifth-argument env. Directory coding tools are
             // cwd-bound and ignore it; authored tools read FastAgent's turnContext instead.
             () => tool.execute(id, params, signal, undefined, { env }));
@@ -252,9 +225,17 @@ export function piAgentSessionFactory(options) {
             // Lower-level callers with an explicit list also rely on omitted built-ins staying omitted.
             noTools: "builtin",
             ...(excludedToolNames.length > 0 ? { excludeTools: [...excludedToolNames] } : {}),
-            customTools: toolDefinitions(tools, cwd, env, sessionId, bound),
+            customTools: toolDefinitions(tools, env, bound),
         });
-        bound.session = session;
+        // One context for the whole session: it describes the SESSION, not the call. The activation
+        // bridge above all — a tool call has to see what the previous one activated.
+        bound.context = {
+            cwd,
+            sessionManager: agentSessionManager(session, sessionId),
+            // A served session HAS somewhere to record the discovery, so it does: the delta is what makes
+            // the tool still callable next turn (see {@link TOOL_ACTIVATION_ENTRY}).
+            tools: sessionToolActivation(session, (added) => session.sessionManager.appendCustomEntry(TOOL_ACTIVATION_ENTRY, { names: added })),
+        };
         // An extension handler that throws is otherwise dropped: pi fans errors out to registered
         // listeners and has none by default, which on a server means a broken extension looks like an
         // extension that simply did nothing.

package/dist/engines/pi/auth.js

@@ -20,16 +20,20 @@
  * 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).
+ * is pi-ai's per-request hot path, so it stays UNLOCKED — safe because every write that carries a
+ * CREDENTIAL publishes by rename ({@link writeFileAtomic}): a reader sees one whole version of the
+ * file or another, never a partial one, so a rotation has no torn-read window for an unlocked read
+ * to absorb. The one in-place write left is the `{}` bootstrap below, whose window an unlocked read
+ * observes as an empty file — reported as corrupt, which for a zero-byte auth.json is the right
+ * answer either way. The write path refuses to overwrite a corrupt file (never clobbering other
+ * providers' credentials).
  */
-import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { GLOBAL_HOME_DIR, SECRETS_DIRNAME } from "../../paths.js";
+import { GLOBAL_HOME_DIR, SECRETS_DIRNAME, SECRET_FILE_MODE, ensureSecretsDir } from "../../paths.js";
+import { writeFileAtomic } from "../../atomic-write.js";
 import { log } from "../../log.js";
-import { setTimeout as sleep } from "node:timers/promises";
 import lockfile from "proper-lockfile";
 /**
  * The GLOBAL fastagent credentials file (distinct from pi's `~/.pi`), under the user-global machinery
@@ -46,7 +50,7 @@ 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 };
+const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
 /**
  * Serialized cross-process read-modify-write of the credentials file: exponential-backoff retries,
  * 30s staleness, and compromise detection (the parameters pi's `FileAuthStorageBackend` used).
@@ -56,13 +60,15 @@ const AUTH_FILE_WRITE_OPTIONS = { encoding: "utf8", mode: 0o600 };
  * failed unlock after a successful operation rejects instead of leaving a stale lock silently.
  */
 async function withLockedAuthFile(authPath, fn) {
-    const dir = dirname(authPath);
-    if (!existsSync(dir))
-        mkdirSync(dir, { recursive: true, mode: 0o700 });
+    // 0700 unconditionally, including on a directory an operator named with `--auth-path`: pointing a
+    // credential file somewhere is asking for that somewhere to hold a credential. Where the process
+    // cannot chmod (a mount it does not own), this raises — the write fails visibly instead of
+    // quietly leaving the directory readable, which is the trade this repo takes everywhere else.
+    await ensureSecretsDir(dirname(authPath));
     if (!existsSync(authPath)) {
         try {
             writeFileSync(authPath, "{}", { ...AUTH_FILE_WRITE_OPTIONS, flag: "wx" });
-            chmodSync(authPath, 0o600);
+            chmodSync(authPath, SECRET_FILE_MODE);
         }
         catch (error) {
             // EEXIST: another process created the file between the existence check and this exclusive
@@ -89,10 +95,12 @@ async function withLockedAuthFile(authPath, fn) {
         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);
-        }
+        // Rename, not an in-place rewrite: it is what lets `read` stay unlocked, and it is the only
+        // spelling that applies the mode before the content is reachable — `writeFileSync`'s `mode` is
+        // a no-op on an existing file, so a chmod after it leaves the new credential briefly readable
+        // at whatever mode the old file carried.
+        if (out.next !== undefined)
+            writeFileAtomic(authPath, out.next, SECRET_FILE_MODE);
         throwIfCompromised();
         result = out.result;
     }
@@ -139,34 +147,26 @@ function decodeCreds(raw) {
     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.
+ * UNLOCKED read of the whole credentials file, shared by `read` and `list`. ONE read: the write
+ * publishes by rename, so this observes one whole version or another and has nothing to absorb by
+ * re-reading. A missing file reads as undefined silently (normal not-configured); anything that
+ * does not decode is a real corruption — a hand-edit — and says so immediately, rather than after
+ * retrying a race that cannot happen.
  */
-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);
+function readCreds(authPath, warn) {
+    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;
     }
+    const creds = raw === "" ? undefined : decodeCreds(raw);
+    if (creds !== undefined)
+        return creds;
     warn(`[fastagent] corrupt auth file ${authPath}: fix or remove it`);
     return undefined;
 }
@@ -190,13 +190,13 @@ export function fastagentCredentialStore(authPath = GLOBAL_AUTH_PATH, options =
     const warn = options.warn ?? ((message) => log.warn(message));
     return {
         async read(providerId) {
-            const creds = await readCreds(authPath, warn);
+            const creds = 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);
+            const creds = readCreds(authPath, warn);
             if (!creds)
                 return [];
             const infos = [];

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

@@ -24,7 +24,7 @@ export interface FastagentConfig {
     selfSchedule?: boolean;
     /**
      * Serve the session control plane over HTTP (`/control/*`: state/entries/events + dispatch —
-     * steer/abort/compact/set_model…) for remote consumers: a Web panel, a desktop app, `fastagent
+     * steer/abort/compact + session properties and lifecycle) for remote consumers: a Web panel, a desktop app, `fastagent
      * attach`. Default off (it is a remote-control surface). When on, `dev`/`start` generate a
      * per-boot bearer token and write `<stateRoot>/control.json` for local discovery. The serve
      * binds all interfaces by default, so the routes are LAN-reachable with the token as the only

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

@@ -1,4 +1,17 @@
-import type { ExecutionEnv, Skill, ThinkingLevel } from "@earendil-works/pi-agent-core";
+/**
+ * Agent assembly (configuration-time): the engine assets (tools, prompt) plus the reusable ladder
+ * that puts a pi agent together.
+ *
+ *   L2  createPiAgentFromDefinition(dir, options)   — load a definition directory, assemble, then L1.
+ *   L1  createPiAgent(options)                       — assemble from typed parts (the canonical ctor).
+ *   L0  createPiAgentFromSession({ sessionFactory }) — in invoke-session.ts (the turn mechanism).
+ *
+ * Above L2 sits the agent opener createPiAgentFromDir (open.ts), which both `dev` and
+ * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
+ * they come from the definition; the openers own model/tools — from config resolution).
+ */
+import { type ExecutionEnv, type Skill, type ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type ModelRuntime } from "@earendil-works/pi-coding-agent";
 import type { Provider } from "@earendil-works/pi-ai";
 import type { Agent } from "../../agent.ts";
 import { type FastagentConfig } from "./config.ts";
@@ -7,7 +20,6 @@ import type { ModuleLoadFailure } from "../../loader.ts";
 import { type ToolCollision, type MountedTool } from "./tool.ts";
 import { type PiAgentSessionFactory } from "./invoke-session.ts";
 import { type AnyModel } from "./models.ts";
-import type { ModelRuntime } from "@earendil-works/pi-coding-agent";
 import { type PiSessionRecordStore } from "./session-store.ts";
 import { type Lease, type SessionObserver } from "./turn-kit.ts";
 /**

package/dist/engines/pi/create.js

@@ -10,9 +10,9 @@
  * `start` drive. Each rung calls the one below; options narrow as you go up (L2 owns systemPrompt/skills —
  * they come from the definition; the openers own model/tools — from config resolution).
  */
-import { formatSkillsForSystemPrompt } from "@earendil-works/pi-agent-core";
+import { formatSkillsForSystemPrompt, } from "@earendil-works/pi-agent-core";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
-import { createCodingTools, createPowerShellTool, createReadOnlyTools } from "@earendil-works/pi-coding-agent";
+import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
 import { defaultAuthPath, resolveModel } from "./config.js";
 import { resolveSecretsDir } from "../../paths.js";
 import { loadAgentDefinition, loadExtensionPaths } from "./definition.js";

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

@@ -1,4 +1,4 @@
-import type { ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
+import { type ExecutionEnv, type Skill, type SkillDiagnostic } from "@earendil-works/pi-agent-core";
 /** A same-name skill collision (the discarded side). Surfaced, never swallowed. */
 export interface SkillCollision {
     name: string;

package/dist/engines/pi/definition.js

@@ -131,11 +131,10 @@ export async function loadExtensionPaths(agentDir, options = {}) {
     return paths.sort();
 }
 /**
- * The first candidate that is a REAL file. `exists` would follow a symlink, which is how a
- * subdirectory's `index.ts` could otherwise point outside the definition and slip past the rule the
- * top-level entries already follow.
+ * The first candidate that is a REAL file, and whether one was found but REFUSED as a symlink.
+ * `exists` would follow the link, which is how a subdirectory's `index.ts` could otherwise point
+ * outside the definition and slip past the rule the top-level entries already follow.
  */
-/** The first real file among the candidates, and whether one was found but REFUSED as a symlink. */
 async function firstRealFile(e, candidates) {
     let refused = false;
     for (const candidate of candidates) {

package/dist/engines/pi/login.js

@@ -30,6 +30,18 @@ function authCallbacks(io, userSignal, doneSignal) {
         signal: userSignal ?? new AbortController().signal,
         prompt: async (p) => {
             if (p.type === "select") {
+                // This branch is UNCANCELLABLE: `LoginIO.select` takes no signal, so all three the line
+                // below composes — the provider's own, the caller's `loginFlow({ signal })`, and the
+                // pending-prompt backstop — are dropped here.
+                //
+                // It costs nothing against pi 0.84's providers, where every `select` is the FIRST call of
+                // `login()` (bedrock, vertex, openai-codex, radius — all of them asking which login method
+                // to use). Nothing is racing it: no callback server is up yet, and `doneSignal` fires when
+                // `auth.login()` RETURNS, which it cannot do while blocked on this await.
+                //
+                // That is a property of the providers, not a guarantee, and nothing here holds it. A
+                // provider that ever issues a `select` after starting its callback server shows up as the
+                // CLI parked on stdin — widen `LoginIO.select` with a signal then.
                 const v = await io.select(p.message, p.options.map((o) => ({ value: o.id, label: o.label, hint: o.description })));
                 if (v === undefined)
                     throw new LoginCancelled("cancelled");
@@ -94,9 +106,14 @@ async function selectProvider(io, providers, method, store) {
         return { value: p.id, label: auth?.name ?? p.name, hint: cred ? `configured (${cred.type})` : undefined };
     }));
     const id = await io.select("Select a provider", options);
-    if (!id)
+    // Answers the PROVIDER, not its id: the caller needs the object, and resolving it here means the
+    // one place that can fail to is the one that just offered the list. Cancel and an id that was
+    // never offered are the same answer — nothing was chosen — and `find` gives both, since a
+    // provider id is always a string and `undefined` matches none of them.
+    const chosen = candidates.find((p) => p.id === id);
+    if (!chosen)
         throw new LoginCancelled("no provider selected");
-    return id;
+    return chosen;
 }
 /**
  * Resolve method + provider (asking only what is not given), run the login flow, and persist. A no-op
@@ -106,26 +123,25 @@ export async function loginFlow(io, options = {}) {
     const store = options.store ?? fastagentCredentialStore(options.authPath ?? GLOBAL_AUTH_PATH);
     const providers = options.providers ?? builtinProviders();
     let method;
-    let providerId;
+    let provider;
     if (options.provider) {
-        providerId = options.provider;
-        const p = providers.find((x) => x.id === providerId);
-        if (!p)
-            throw new Error(`unknown provider "${providerId}"`);
-        method = options.method ?? (await methodForProvider(io, p));
+        const named = providers.find((x) => x.id === options.provider);
+        if (!named)
+            throw new Error(`unknown provider "${options.provider}"`);
+        provider = named;
+        method = options.method ?? (await methodForProvider(io, provider));
     }
     else {
         method = options.method ?? (await selectMethod(io));
-        providerId = await selectProvider(io, providers, method, store);
+        provider = await selectProvider(io, providers, method, store);
     }
     // Preflight: a no-op modify runs the refuse-corrupt / writability check BEFORE the flow.
-    await store.modify(providerId, async () => undefined);
-    const provider = providers.find((p) => p.id === providerId);
-    if (!provider)
-        throw new Error(`unknown provider "${providerId}"`);
+    await store.modify(provider.id, async () => undefined);
+    // Reachable even though both branches above resolved a provider: an explicit `method` bypasses
+    // methodForProvider, so `{ provider: "openai-codex", method: "api_key" }` arrives here.
     const auth = method === "oauth" ? provider.auth.oauth : provider.auth.apiKey;
     if (!auth?.login)
-        throw new Error(`provider "${providerId}" has no ${method} login`);
+        throw new Error(`provider "${provider.id}" has no ${method} login`);
     // `done` cancels any prompt left pending when login resolves (manual-code race backstop).
     const done = new AbortController();
     let credential;
@@ -135,6 +151,6 @@ export async function loginFlow(io, options = {}) {
     finally {
         done.abort();
     }
-    await store.modify(providerId, async () => credential);
-    return { provider: providerId, method };
+    await store.modify(provider.id, async () => credential);
+    return { provider: provider.id, method };
 }

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

@@ -5,8 +5,7 @@ import type { SessionObserver } from "./turn-kit.ts";
 import type { ModuleLoadFailure } from "../../loader.ts";
 import { type LoadedDefinition } from "./definition.ts";
 import { type PiSessionRecordStore } from "./session-store.ts";
-import type { ToolCollision } from "./tool.ts";
-import type { MountedTool } from "./tool.ts";
+import type { ToolCollision, MountedTool } from "./tool.ts";
 export interface CreatePiAgentFromDirOptions {
     /** Model spec override (e.g. the CLI --model flag). Precedence: this > FASTAGENT_MODEL > config.model. */
     model?: string;

package/dist/engines/pi/open.js

@@ -95,7 +95,7 @@ export async function createPiAgentFromDir(dir, options = {}) {
             },
             // The caller tap's boundary-event half: state_changed/compaction_* originate in the hub
             // and never cross the data plane's observer seam — without this, an audit tap wired here
-            // would miss exactly the mutations it most needs to see (set_model).
+            // would miss exactly the mutations it most needs to see (`update({ model })`).
             tap: caller ? (session, event) => caller(session, event) : undefined,
         })
         : undefined;

package/dist/engines/pi/search-tools.js

@@ -124,7 +124,7 @@ export function makeSearchToolsTool() {
                     .map((t) => t.name)
                     .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
             }
-            const activated = await ctx.tools.activate(inactiveMatches.map((t) => t.name));
+            const activated = ctx.tools.activate(inactiveMatches.map((t) => t.name));
             // Report what actually happened, not what was attempted: a parallel sibling call may have
             // activated the same matches first, leaving nothing new here — an empty "Activated:" would lie.
             if (activated.length === 0) {

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

@@ -6,7 +6,7 @@
  * pi-specific is opening a DIRECTORY into one, which is why this shortcut lives here and the
  * assembly does not. A second engine ships its own opener and reuses `mountAgentService` unchanged.
  */
-import type { AgentService, MountAgentServiceOptions } from "../../service.ts";
+import { type AgentService, type MountAgentServiceOptions } from "../../service.ts";
 export interface CreateAgentServiceOptions extends MountAgentServiceOptions {
     model?: string;
     authPath?: string;

package/dist/engines/pi/service.js

@@ -1,3 +1,11 @@
+/**
+ * `createAgentService` — the product as one call, with pi supplying the engine.
+ *
+ * The ASSEMBLY is engine-neutral and lives in `src/service.ts`: it takes a {@link MountableAgent}
+ * (the SPEC contract plus three paths) and knows nothing about how that agent was built. What is
+ * pi-specific is opening a DIRECTORY into one, which is why this shortcut lives here and the
+ * assembly does not. A second engine ships its own opener and reuses `mountAgentService` unchanged.
+ */
 import { mountAgentService } from "../../service.js";
 import { createPiAgentFromDir } from "./open.js";
 /**