@fastagent-sh/fastagent 0.23.0 → 0.24.0

package/dist/engines/pi/create.js

@@ -7,11 +7,12 @@ import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
 import { resolveModel } from "./config.js";
 import { isAgentcoreRuntime, isDeployedWorkspace } from "../../paths.js";
-import { loadAgentDefinition, loadExtensionPaths } from "./definition.js";
+import { loadAgentDefinition } from "./definition.js";
 import { reportFindingsIfChanged } from "./report.js";
-import { isDeferredTool, loadTools, mergeDiscoveredTools, } from "./tool.js";
+import { log } from "../../log.js";
+import { BUILTIN_EXTENSIONS, DISCOVERY, readMachine } from "./machine.js";
+import { loadTools, mergeDiscoveredTools } from "./tool.js";
 import { readSecretDeclaration } from "../../declared-secrets.js";
-import { withSearchTool } from "./search-tools.js";
 import { createPiAgentFromSession } from "./invoke-session.js";
 import { piAgentSessionFactory } from "./agent-session-factory.js";
 import { DEFAULT_THINKING_LEVEL } from "./models.js";
@@ -57,6 +58,32 @@ function omittedBuiltinNames(mounted, cwd) {
     const mountedNames = new Set(mounted.map((tool) => tool.name));
     return [...new Set(piRegisteredToolNames(cwd))].filter((name) => !mountedNames.has(name));
 }
+function isDefaultActiveTool(tool) {
+    return ((!tool.exposure || tool.exposure === "direct" || tool.exposure === "model-only") && tool.defaultActive !== false);
+}
+/** The built-in extension a `codemode`/`deferred` tool is reached through ({@link DISCOVERY}). */
+function wayIn(tool) {
+    return tool.exposure === "codemode" || tool.exposure === "deferred" ? DISCOVERY[tool.exposure].extension : undefined;
+}
+/** Whether this machine leaves the tool's way in enabled (a tool that needs none always has one). */
+function hasWayIn(tool, builtinExtensions) {
+    const extension = wayIn(tool);
+    return extension === undefined || builtinExtensions.includes(extension);
+}
+function indirectReach(tool, builtinExtensions) {
+    if (isDefaultActiveTool(tool))
+        return undefined;
+    if (!hasWayIn(tool, builtinExtensions))
+        return "unreachable";
+    if (tool.exposure === "deferred")
+        return "tool_search";
+    if (tool.exposure === "codemode")
+        return "codemode";
+    if (tool.exposure === "hidden")
+        return "hidden";
+    // `defaultActive: false`: only an authored loader (`ToolContext.tools.activate`) brings it in.
+    return "inactive";
+}
 /**
  * The full directory-agent tool set: all pi coding tools + `config.tools` + discovered `tools/` (deduped, existing
  * win), plus the authored names and collisions to report.
@@ -82,24 +109,22 @@ export async function resolveAgentTools(config, agentDir, cwd) {
         mountedConfigTools.push(tool);
     }
     const merged = mergeDiscoveredTools(configured, discovered.tools);
-    // The built-in `search_tools` loader mounts here.
-    const tools = withSearchTool(merged.tools);
-    // Builtin = a search_tools that was ABSENT before withSearchTool (a reference compare would misfire on the
-    // deferred-authored-loader case, where withSearchTool returns a new array without adding one).
-    const builtinLoaderMounted = !merged.tools.some((t) => t.name === "search_tools") && tools.some((t) => t.name === "search_tools");
+    const tools = merged.tools;
     const toolCollisions = [...discovered.collisions, ...configuredCollisions, ...merged.collisions];
     // `toolNames` is the AUTHOR's active-by-default surface (config.tools + tools/).
     // The discovered tools that were DROPPED (a coding tool or config.tools already owns the name):
     // asking the mounted set instead would read the winner's name as proof the loser is mounted.
     const shadowed = new Set(merged.collisions.map((c) => c.name));
+    const { builtinExtensions } = await readMachine(cwd);
     const defaultNames = new Set(CODING_TOOL_NAMES);
-    const toolNames = tools
-        .filter((t) => !defaultNames.has(t.name) && !isDeferredTool(t) && !(builtinLoaderMounted && t.name === "search_tools"))
-        .map((t) => t.name);
+    const toolNames = tools.filter((t) => !defaultNames.has(t.name) && isDefaultActiveTool(t)).map((t) => t.name);
     return {
         tools,
         toolNames,
-        deferredToolNames: tools.filter(isDeferredTool).map((t) => t.name),
+        indirectTools: tools.flatMap((t) => {
+            const reach = defaultNames.has(t.name) ? undefined : indirectReach(t, builtinExtensions);
+            return reach ? [{ name: t.name, reach }] : [];
+        }),
         toolCollisions,
         toolFailures: discovered.failures,
         // Mounted only, and config.tools are FastagentTools too, so a programmatic tool declares the
@@ -124,10 +149,14 @@ export async function resolveAgentTools(config, agentDir, cwd) {
 /** The pi engine's base prompt (segment ①), mirroring pi-coding-agent's default path with two deviations. */
 export function piBasePrompt(options = {}) {
     const mounted = options.tools ?? [];
+    const builtinExtensions = options.builtinExtensions ?? BUILTIN_EXTENSIONS;
     // Deferred tools stay OUT of the list: their schemas are not in the request until activated, so naming them here
     // would invite calls to tools that don't exist yet.
-    const tools = mounted.filter((t) => !isDeferredTool(t));
-    const deferredCount = mounted.length - tools.length;
+    const tools = mounted.filter(isDefaultActiveTool);
+    // Only `deferred` tools are tool_search's to load (the session activates it for them); `codemode` ones are listed
+    // in codemode's own description, and an inactive direct tool is reached only through an authored activation.
+    // A disabled tool-search leaves them no way in, and naming tool_search would invite calls to a tool that is not there.
+    const deferredCount = mounted.filter((tool) => tool.exposure === "deferred" && hasWayIn(tool, builtinExtensions)).length;
     const toolsList = tools.length > 0 ? tools.map((t) => `- ${t.name}: ${(t.description ?? "").split("\n")[0]}`).join("\n") : "(none)";
     // Segment ① identity: an authored persona (persona.md) replaces the default engine identity line (core.md §2),
     // keeping the tools list + guidelines below.
@@ -138,7 +167,7 @@ export function piBasePrompt(options = {}) {
             ? "You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files."
             : "You are an AI assistant operating inside pi, an agent harness. Help users using only the tools and context available to you.");
     const deferredNote = deferredCount > 0
-        ? `\n\n${deferredCount} additional tool(s) are registered but inactive — use search_tools to discover and activate them before concluding a capability is missing.`
+        ? `\n\n${deferredCount} additional tool(s) are registered but not loaded — use tool_search to find and load them before concluding a capability is missing.`
         : "";
     // What takes effect when, and the agent's own path to a new capability, are the same on every host; only how long
     // the storage lives differs, below. The skill it writes lives in the definition directory, which the next
@@ -188,16 +217,10 @@ function assemblePi(opts) {
     // — boundary mutations must contend on it.
     const lease = opts.lease ?? inProcessLease();
     const sessions = opts.sessions ?? piInMemorySessionRecordStore({ cwd });
-    // The model and its runtime resolve on FIRST USE.
+    const createModelRuntime = opts.models;
     let registry;
     const modelRuntime = () => {
-        registry ??= opts.models().then((runtime) => {
-            // ModelRuntime registers providers by config record, so an injected Provider INSTANCE (a gateway, a self-hosted
-            // endpoint, a test fake) goes in through its native seam.
-            for (const provider of opts.providers ?? [])
-                runtime.registerNativeProvider(provider);
-            return runtime;
-        });
+        registry ??= opts.catalog();
         return registry;
     };
     let engine;
@@ -205,25 +228,28 @@ function assemblePi(opts) {
         engine ??= modelRuntime().then((runtime) => ({ modelRuntime: runtime, model: resolveModel(runtime, opts.model) }));
         return engine;
     };
+    // Deny omitted coding names so discovery cannot reintroduce tools a lower-level caller excluded.
+    const excludedToolNames = omittedBuiltinNames(opts.tools ?? [], cwd);
     const sessionFactory = piAgentSessionFactory({
         sessions,
-        engine: resolveEngine,
+        engine: async () => ({ modelRuntime: await createModelRuntime() }),
+        modelSpec: opts.model,
         thinkingLevel: opts.thinkingLevel,
         tools: opts.tools,
         readDefinition: opts.readDefinition,
         cwd,
         ...(opts.extensionPaths ? { extensionPaths: opts.extensionPaths } : {}),
-        // `noTools: "builtin"` leaves pi's built-ins in the registry; a lower-level replacement must also deny every
-        // omitted coding name so a loader cannot reactivate one later.
-        excludedToolNames: omittedBuiltinNames(opts.tools ?? [], cwd),
+        excludedToolNames,
     });
     return {
         lease,
         sessionFactory,
         modelRuntime,
+        createModelRuntime,
         engine: resolveEngine,
         thinkingLevel: opts.thinkingLevel ?? DEFAULT_THINKING_LEVEL,
         tools: opts.tools ?? [],
+        excludedToolNames,
         readDefinition: opts.readDefinition,
         extensionPaths: opts.extensionPaths ?? [],
     };
@@ -235,17 +261,17 @@ export function agentOf(assembly, observer) {
 /** L1: assemble from typed parts. */
 export function createPiAgent(options) {
     const { instructions, skills = [] } = options;
+    const models = agentModels(undefined, options, { providers: options.providers });
     return agentOf(assemblePi({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        providers: options.providers,
-        models: agentModels(undefined, options).runtime,
+        models: models.createRuntime,
+        catalog: models.runtime,
         readDefinition: () => ({
             systemPrompt: typeof instructions === "function" ? instructions() : instructions,
             skills,
         }),
-        // Deferred tools need their loader on every rung (idempotent; the caller's own search_tools wins).
-        tools: options.tools ? withSearchTool(options.tools) : options.tools,
+        tools: options.tools,
         sessions: options.sessions,
         env: options.env,
         lease: options.lease,
@@ -264,21 +290,27 @@ export async function assemblePiFromDefinition(dir, options) {
     // Boot-time load: fail-visibly at startup on a broken directory, and give callers the snapshot to report
     // (skills/diagnostics/collisions).
     const definition = await loadAgentDefinition(dir, { cwd, env });
-    // Deferred tools need their loader on every rung (idempotent — the workspace opener already applied it; a caller's
-    // own search_tools wins).
-    const tools = withSearchTool(options.tools ?? piAllCodingTools(cwd));
+    const tools = options.tools ?? piAllCodingTools(cwd);
     // Boot findings go through the SAME memoized reporter every later reader uses (report.ts, keyed by the resolved
     // dir).
     reportFindingsIfChanged(definition.dir, definition);
     const { providers } = options;
-    const models = options.models ?? agentModels(dir, options, providers ? { providers } : {});
+    const models = options.models ?? agentModels(dir, options, { cwd, env, ...(providers ? { providers } : {}) });
     // Built at boot, so a malformed models.json fails the assembly rather than its first turn. The directory's own
     // models.json is what a turn resolves against, layered over the machine's (models.ts).
     await models.runtime();
+    const { builtinExtensions } = await readMachine(cwd);
+    const unreachable = tools.filter((tool) => !hasWayIn(tool, builtinExtensions));
+    // Said once per assembly: the model cannot call these at all, while the tools themselves loaded fine.
+    for (const tool of unreachable) {
+        log.warn(`[fastagent] tool "${tool.name}" (exposure: ${tool.exposure}) cannot be reached: pi's settings disable ` +
+            `builtin:${wayIn(tool)}, its only way in`);
+    }
     const assembly = assemblePi({
         model: options.model,
         thinkingLevel: options.thinkingLevel,
-        models: models.runtime,
+        models: models.createRuntime,
+        catalog: models.runtime,
         // The directory is the agent, LIVE: re-read the definition on every invoke, so AGENTS.md/skills edits (the
         // author's, or the agent's own self-modification) take effect on the next turn with no process restart — restarts
         // are reserved for code (tools/channels/config, module cache).
@@ -289,7 +321,7 @@ export async function assemblePiFromDefinition(dir, options) {
                 systemPrompt: assembleSystemPrompt({
                     // Segment ①: an authored persona (persona.md, def.persona) overrides the engine identity, re-read per turn
                     // like AGENTS.md so edits go live.
-                    base: options.base ?? piBasePrompt({ tools, persona: def.persona }),
+                    base: options.base ?? piBasePrompt({ tools, persona: def.persona, builtinExtensions }),
                     // ② project context: AGENTS.md files (agentDir + cwd-ancestor walk) via loadProjectContextFiles.
                     contextFiles: def.contextFiles,
                 }),
@@ -298,7 +330,8 @@ export async function assemblePiFromDefinition(dir, options) {
         },
         tools,
         sessions: options.sessions,
-        extensionPaths: await loadExtensionPaths(dir, { cwd, env }),
+        // The catalog's own discovery: the models it registered and the extensions sessions load are one list.
+        extensionPaths: [...(await models.extensionPaths())],
         cwd,
         env,
         lease: options.lease,

package/dist/engines/pi/invoke-session.js

@@ -10,7 +10,12 @@ import { log } from "../../log.js";
 import { toRetryScheduledEvent } from "./retry-event.js";
 import { PortFailure, port, portAbort, portCleanup, portError } from "../../effect-port.js";
 import { SessionBusy, acquireSession, acquireSessionLease } from "./session-effects.js";
-import { errorToTerminal, inProcessLease, projectAgentEvent, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
+import { errorToTerminal, inProcessLease, agentEventProjection, answerOutcome, toPiPromptOptions, toTerminal, } from "./turn-kit.js";
+// Structured output is for scripts. Observation publishes Pi's display result, including bounded nested traces.
+function displayToolResult(result) {
+    const { structuredContent: _internal, ...display } = result;
+    return display;
+}
 function toSessionEvent(event, runId) {
     const at = Date.now();
     switch (event.type) {
@@ -33,30 +38,47 @@ function toSessionEvent(event, runId) {
             }
             return null;
         }
-        case "message_end":
+        case "message_end": {
             if (event.message.role !== "assistant")
                 return null;
-            return { type: "message_finished", timestamp: at, runId, data: {} };
+            const outcome = answerOutcome(event.message);
+            return { type: "message_finished", timestamp: at, runId, data: outcome ? { outcome } : {} };
+        }
         case "tool_execution_start":
             return {
                 type: "tool_started",
                 timestamp: at,
                 runId,
-                data: { id: event.toolCallId, name: event.toolName, args: event.args },
+                data: {
+                    id: event.toolCallId,
+                    name: event.toolName,
+                    args: event.args,
+                    ...(event.parentToolCallId ? { parentToolCallId: event.parentToolCallId } : {}),
+                },
             };
         case "tool_execution_update":
             return {
                 type: "tool_progress",
                 timestamp: at,
                 runId,
-                data: { id: event.toolCallId, name: event.toolName, partialResult: event.partialResult },
+                data: {
+                    id: event.toolCallId,
+                    name: event.toolName,
+                    partialResult: displayToolResult(event.partialResult),
+                    ...(event.parentToolCallId ? { parentToolCallId: event.parentToolCallId } : {}),
+                },
             };
         case "tool_execution_end":
             return {
                 type: "tool_finished",
                 timestamp: at,
                 runId,
-                data: { id: event.toolCallId, isError: event.isError, content: event.result },
+                data: {
+                    id: event.toolCallId,
+                    isError: event.isError,
+                    content: displayToolResult(event.result),
+                    ...(event.parentToolCallId ? { parentToolCallId: event.parentToolCallId } : {}),
+                },
             };
         case "queue_update":
             return {
@@ -125,10 +147,27 @@ export function createPiAgentFromSession(options) {
         const abort = new AbortController();
         onCancelReady(() => abort.abort());
         const runId = crypto.randomUUID();
+        const project = agentEventProjection();
+        /**
+         * Each call's `tool_progress` still waiting in the queue. A newer status replaces its text instead of queuing
+         * behind it, so the queue holds at most one per running call, and a consumer that falls behind (a slow `/invoke`
+         * client) gets the latest status, not every snapshot in between: pi's bash reports every 100 ms, and a single
+         * growing line is up to 50 KB each time. The replaced event keeps its place, which moves a status earlier, never
+         * past its own call's `tool_ended`: pi takes no progress from a call once it has returned.
+         */
+        const unreadProgress = new Map();
         let settled = false;
         let outcome;
         let abortsInFlight = 0;
         let abortSucceeded = false;
+        /**
+         * An abort is owed to every model request this invoke makes, including one not yet started. pi's `abort()` stops
+         * only an agent run or a compaction already in flight: one that lands while `prompt()` prepares (input handlers,
+         * the auth check, `before_agent_start`) finds nothing to stop, and `_runAgentPrompt` then clears pi's own flag.
+         * So the run remembers it and aborts each agent run and automatic compaction as it starts (`agent_start`,
+         * `compaction_start`: both emitted once pi's controller for it exists).
+         */
+        let abortRequested = false;
         const observe = (event, run) => {
             if (!event || !observer)
                 return;
@@ -144,25 +183,38 @@ export function createPiAgentFromSession(options) {
          * Every control command obeys one admission rule: wait for this run's binding, then refuse once it has settled.
          * Kept in one place so a fourth command cannot arrive with a fifth spelling of it.
          */
+        const alreadySettled = () => new PortFailure(new Error("run already settled; the command cannot take effect"));
         const command = (run) => Effect.runPromise(Effect.gen(function* () {
             const session = yield* ready;
             if (settled)
-                return yield* Effect.fail(new PortFailure(new Error("run already settled; the command cannot take effect")));
-            yield* run(session);
+                return yield* Effect.fail(alreadySettled());
+            return yield* run(session);
         }));
-        // Prompt preparation stays OUTSIDE admission. An await between the settled check and the enqueue would let the run
-        // end in between, and pi accepts a message for a finished run without complaint (`_steeringMessages.push`) — the
-        // command would be dropped and still reported as success. Image resizing is exactly such an await, hundreds of
-        // milliseconds of dynamic import and Photon work, and doing it here also keeps it overlapping session acquisition.
+        // Prompt preparation stays OUTSIDE admission: pi accepts a message for a finished run without complaint
+        // (`_steeringMessages.push`), so a run that ends between the settled check and the enqueue drops the command while
+        // it reports success. Image resizing would be such a gap, hundreds of milliseconds of dynamic import and Photon
+        // work, and doing it here also keeps it overlapping session acquisition. pi has a gap of its own: it awaits the
+        // definition's `input` handlers before it queues, so a `queued` answer is checked against settlement once more.
+        // A `handled` one stands either way: the handler took the prompt whatever became of the run.
         const enqueue = async (p, kind) => {
             const opts = await toPiPromptOptions(p, "queued");
-            return command((session) => port(() => session[kind](p.text, opts?.images)));
+            return command((session) => Effect.gen(function* () {
+                const disposition = yield* port(() => session[kind](p.text, opts?.images));
+                if (disposition === "queued" && settled) {
+                    // pi has queued it, and announced it (`queue_update`), on a run that takes nothing in any more. Emptying
+                    // the queue tells the observation plane so, which would otherwise report the refused prompt pending.
+                    session.clearQueue();
+                    return yield* Effect.fail(alreadySettled());
+                }
+                return disposition;
+            }));
         };
         const controls = {
             steer: (p) => enqueue(p, "steer"),
             followUp: (p) => enqueue(p, "followUp"),
             abort: () => command((session) => Effect.gen(function* () {
                 abortsInFlight++;
+                abortRequested = true;
                 yield* port(() => session.abort()).pipe(Effect.tap(() => Effect.sync(() => {
                     abortSucceeded = true;
                 })), Effect.ensuring(Effect.sync(() => {
@@ -190,9 +242,10 @@ export function createPiAgentFromSession(options) {
             let streamedAnswer = false;
             let retriedAfterAnswer;
             let eventFailure;
-            const stop = () => {
-                void Effect.runPromise(portCleanup("event-fault abort", () => session.abort()));
+            const abortWith = (operation) => {
+                void Effect.runPromise(portCleanup(operation, () => session.abort()));
             };
+            const stop = () => abortWith("event-fault abort");
             yield* Effect.acquireRelease(Effect.try({
                 try: () => session.subscribe((event) => {
                     if (retriedAfterAnswer !== undefined || eventFailure)
@@ -200,6 +253,8 @@ export function createPiAgentFromSession(options) {
                     try {
                         if (event.type === "agent_start")
                             runStarted = true;
+                        if ((event.type === "agent_start" || event.type === "compaction_start") && abortRequested)
+                            abortWith("requested abort");
                         // Compaction rewrites session history; the event's assistant message is the turn's fact.
                         if (event.type === "message_end" && event.message.role === "assistant") {
                             finalAssistant = event.message;
@@ -222,11 +277,19 @@ export function createPiAgentFromSession(options) {
                         observe(rich);
                         if (!rich)
                             return;
-                        const projected = projectAgentEvent(rich);
+                        const projected = project(rich);
                         if (!projected)
                             return;
                         if (projected.type === "text" || projected.type === "thinking")
                             streamedAnswer = true;
+                        if (projected.type === "tool_progress") {
+                            const unread = unreadProgress.get(projected.id);
+                            if (unread) {
+                                unread.text = projected.text;
+                                return;
+                            }
+                            unreadProgress.set(projected.id, projected);
+                        }
                         Queue.offerUnsafe(queue, projected);
                     }
                     catch (error) {
@@ -318,6 +381,9 @@ export function createPiAgentFromSession(options) {
                     }
                     else if (event.type === "completed")
                         outcome = { status: "completed" };
+                    // Handed over: the consumer owns it now, and the next status queues afresh.
+                    if (event.type === "tool_progress")
+                        unreadProgress.delete(event.id);
                     yield event;
                 }
             }

package/dist/engines/pi/locked-file.d.ts

@@ -0,0 +1,9 @@
+export interface LockResult<T> {
+    result: T;
+    /** New file content to persist under the lock; undefined = no write. */
+    next?: string;
+}
+/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
+export declare function withLockedFile<T>(path: string, fn: (current: string | undefined) => Promise<LockResult<T>>, options?: {
+    signal?: AbortSignal;
+}): Promise<T>;

package/dist/engines/pi/locked-file.js

@@ -0,0 +1,102 @@
+/**
+ * The one cross-process read-modify-write for a JSON file several processes share: fastagent's credentials file and a
+ * model catalog. It takes the lock pi takes for the same files (pi-coding-agent's `FileAuthStorageBackend`), so a
+ * fastagent writer and a pi writer queue behind each other, and it REPLACES the file rather than rewriting it in
+ * place, which is what lets every reader of these files read without the lock: a reader sees the old file or the new
+ * one, never one cut short.
+ */
+import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import lockfile from "proper-lockfile";
+import { writeFileAtomic } from "../../atomic-write.js";
+import { SECRET_FILE_MODE } from "../../paths.js";
+const WRITE_OPTIONS = { encoding: "utf8", mode: SECRET_FILE_MODE };
+/**
+ * The file a write must land IN, which is not always the path it is addressed BY. pi writes these files in place,
+ * so it follows a symlink to the target; an atomic rename would replace the link with a regular file instead, and
+ * from then on the two tools would be editing different files — the same split the shared lock exists to prevent,
+ * arriving one write later. A dangling link (a dotfile manager that has not checked the target out yet) still names
+ * where the content belongs, so it is followed too rather than overwritten.
+ */
+function writeTarget(path) {
+    if (existsSync(path))
+        return realpathSync(path);
+    const link = lstatSync(path, { throwIfNoEntry: false });
+    // ponytail: one hop. A chain of dangling links would have its second link replaced; resolve iteratively if that
+    // ever shows up in a real layout.
+    return link?.isSymbolicLink() ? resolve(dirname(path), readlinkSync(path)) : path;
+}
+/** Serialized cross-process read-modify-write of one file, replaced whole so its readers need no lock. */
+export async function withLockedFile(path, fn, options = {}) {
+    mkdirSync(dirname(path), { recursive: true });
+    if (!existsSync(path)) {
+        try {
+            // `wx` makes this an exclusive CREATE, which is the one case `writeFileSync` honours `mode` in — so no chmod
+            // after it (unlike writeFileAtomic, whose temp may already exist from a crashed writer).
+            writeFileSync(path, "{}", { ...WRITE_OPTIONS, flag: "wx" });
+        }
+        catch (error) {
+            // EEXIST: the path IS taken, by something `existsSync` does not see through — either another process created
+            // the file just now (its content must not be clobbered) or the path is a dangling symlink. Both are left
+            // alone: the write below resolves where they belong.
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+    }
+    let compromised;
+    const throwIfCompromised = () => {
+        if (compromised)
+            throw compromised;
+    };
+    const release = await lockfile.lock(path, {
+        // MUST match pi-coding-agent's `core/auth-storage.js`, which locks with `realpath: false`. When the file
+        // itself is a symlink (dotfile managers do this), the two settings name DIFFERENT lock files and both locks can
+        // be held at once — so `pi` and `fastagent` would refresh the same provider concurrently, and a rotated refresh
+        // token logs one of them out. Resolving the link would be the stronger rule, but only if BOTH sides did it, and
+        // we do not own the other side.
+        realpath: false,
+        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(path) ? readFileSync(path, "utf8") : undefined;
+        const out = await fn(current);
+        throwIfCompromised();
+        // The last moment a caller that gave up can keep its change off disk: waiting for the lock may have outlasted it
+        // (another process held the lock through the caller's timeout or cancel).
+        options.signal?.throwIfAborted();
+        // 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.
+        if (out.next !== undefined) {
+            writeFileAtomic(writeTarget(path), out.next, SECRET_FILE_MODE);
+        }
+        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 `<file>.lock` stalls the next writer for
+    // the staleness window with zero diagnostics), so it surfaces instead of resolving a silently degraded operation.
+    try {
+        await release();
+    }
+    catch (releaseError) {
+        if (compromised === undefined)
+            throw releaseError;
+    }
+    throwIfCompromised();
+    return result;
+}

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

@@ -31,6 +31,12 @@ export declare function loginOptions(credentials: string | CredentialStore): Pro
 /** {@link loginOptions} over pi's built-ins plus `providers` (a same id replaces one). Not public: a test seam. */
 export declare function loginOptionsOver(credentials: string | CredentialStore, providers?: readonly Provider[]): Promise<LoginOption[]>;
 export type LoginRequest = {
+    /**
+     * Stable installation identity (Sign in with ChatGPT requires one). With `authPath` it defaults to Pi settings
+     * beside that file (`settings.json`, written before the flow runs); over a caller's `credentialStore` there is no
+     * file to keep it beside, so a flow that needs one fails unless this supplies it.
+     */
+    getDeviceId?: () => string;
     provider: string;
     method: LoginMethod;
     /** pi-ai's own interaction: prompts (`text`, `secret`, `select`, `manual_code`) and events (`auth_url`, …). */
@@ -63,7 +69,7 @@ export interface LoginResult {
  * A provider an agent's models.json points elsewhere is not this call's: store that key with `fastagentCredentialStore`.
  *
  * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
- * writes nothing. Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
+ * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
  * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
  */
 export declare function login(request: LoginRequest): Promise<LoginResult>;

package/dist/engines/pi/login.js

@@ -5,6 +5,8 @@
  * one front end ({@link loginFlow}: terminal menus, then {@link login}); a GUI client is another.
  */
 import { InMemoryCredentialStore, } from "@earendil-works/pi-ai";
+import { dirname } from "node:path";
+import { SettingsManager } from "@earendil-works/pi-coding-agent";
 import { fastagentCredentialStore } from "./auth.js";
 import { createPiModelRuntime, interactiveAuth, loginProviders, piModelsOver, probeApiKey } from "./models.js";
 import { agentModels } from "./agent-models.js";
@@ -61,7 +63,7 @@ function anySignal(...signals) {
  * A provider an agent's models.json points elsewhere is not this call's: store that key with `fastagentCredentialStore`.
  *
  * Aborting `interaction.signal` at any point, the verification included, rejects with {@link LoginCancelled} and
- * writes nothing. Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
+ * writes no credential (an OAuth device ID, the installation's identity, is kept once created). Every prompt carries a signal that aborts on it, on the prompt's own signal (a callback server
  * beating a `manual_code` prompt), and when the flow settles with a prompt still pending.
  */
 export function login(request) {
@@ -80,6 +82,7 @@ export async function loginOver(request, internals = {}) {
     const auth = interactiveAuth(provider, method);
     if (!auth?.login)
         throw new Error(`provider "${provider.id}" has no interactive ${method} login`);
+    const flow = auth.login.bind(auth);
     // The key under test lives here, not in the file, until it passes.
     const trial = new InMemoryCredentialStore();
     // Only a key needs the registry, and building an agent's fails on a broken models.json: an OAuth sign-in must not.
@@ -97,8 +100,21 @@ export async function loginOver(request, internals = {}) {
     await store.modify(provider.id, async () => undefined);
     const signal = interaction.signal ?? new AbortController().signal;
     const notify = (event) => interaction.notify(event);
+    let getDeviceId = request.getDeviceId;
+    if (method === "oauth" && !getDeviceId && request.authPath !== undefined) {
+        // Only the settings file beside the credentials: no project's `.pi/settings.json` has a say in this write.
+        const settings = SettingsManager.create(dirname(request.authPath), dirname(request.authPath), {
+            projectTrusted: false,
+        });
+        const deviceId = settings.getOrCreateDeviceId();
+        await settings.flush();
+        const errors = settings.drainErrors();
+        if (errors.length)
+            throw new Error(`could not persist login device ID: ${errors.map(({ error }) => error.message).join("; ")}`);
+        getDeviceId = () => deviceId;
+    }
     for (;;) {
-        const credential = await runFlow(auth.login.bind(auth), interaction, signal);
+        const credential = await runFlow((io) => flow(io, { getDeviceId }), interaction, signal);
         let verified = "n/a";
         if (models) {
             await trial.modify(provider.id, async () => credential);
@@ -150,7 +166,7 @@ export const PI_DEFAULT_MODELS = {
     anthropic: "claude-opus-4-8",
     openai: "gpt-5.5",
     "azure-openai-responses": "gpt-5.4",
-    "openai-codex": "gpt-5.5",
+    "openai-codex": "gpt-6.1-sol",
     radius: "balanced",
     nvidia: "nvidia/nemotron-3-super-120b-a12b",
     deepseek: "deepseek-v4-pro",
@@ -170,11 +186,11 @@ export const PI_DEFAULT_MODELS = {
     moonshotai: "kimi-k2.6",
     "moonshotai-cn": "kimi-k2.6",
     huggingface: "moonshotai/Kimi-K2.6",
-    fireworks: "accounts/fireworks/models/kimi-k2p6",
-    together: "moonshotai/Kimi-K2.6",
+    fireworks: "accounts/fireworks/models/kimi-k3",
+    together: "moonshotai/Kimi-K3",
     baseten: "zai-org/GLM-5.2",
     opencode: "kimi-k2.6",
-    "opencode-go": "kimi-k2.6",
+    "opencode-go": "kimi-k3",
     "kimi-coding": "kimi-for-coding",
     meta: "muse-spark-1.3",
     "cloudflare-workers-ai": "@cf/moonshotai/kimi-k2.6",