@fastagent-sh/fastagent 0.22.1 → 0.24.0

package/dist/engines/pi/create.js

@@ -5,16 +5,18 @@
 import { toUSVString } from "node:util";
 import { NodeExecutionEnv } from "@earendil-works/pi-agent-core/node";
 import { createCodingTools, createPowerShellTool, createReadOnlyTools, } from "@earendil-works/pi-coding-agent";
-import { resolveAuthLayers, resolveModel } from "./config.js";
+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, createPiModelRuntime } from "./models.js";
+import { DEFAULT_THINKING_LEVEL } from "./models.js";
+import { agentModels } from "./agent-models.js";
 import { piInMemorySessionRecordStore } from "./session-store.js";
 import { inProcessLease } from "./turn-kit.js";
 // ── §1 tools ─────────────────────────────────────────────────────────────────
@@ -56,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.
@@ -81,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
@@ -123,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.
@@ -137,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
@@ -187,38 +217,40 @@ 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.catalog();
+        return registry;
+    };
     let engine;
     const resolveEngine = () => {
-        engine ??= (async () => {
-            // The caller's registry when there is one — the directory rung builds it from the agent's own models.json, so a
-            // custom endpoint declared there is the one a turn resolves against.
-            const modelRuntime = opts.models ?? (await createPiModelRuntime({ auth: opts.auth }));
-            // 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 ?? [])
-                modelRuntime.registerNativeProvider(provider);
-            return { modelRuntime, model: resolveModel(modelRuntime, opts.model) };
-        })();
+        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 ?? [],
     };
 }
@@ -229,35 +261,28 @@ 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,
-        ...(options.authPath !== undefined ? { auth: { path: options.authPath } } : {}),
+        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,
     }), options.observer);
 }
 /**
- * THE model registry an agent directory runs on: pi's built-ins, the directory's own `models.json` (custom endpoints
- * are definition data and travel with the artifact) layered over the machine's `~/.fastagent/models.json` (environment,
- * which does not travel), and any injected Provider instance, over the given credentials.
- * The directory rung assembles from it and `availableModelsFromDir` lists from it, so a layer added here reaches both.
+ * L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. `models` is the directory's
+ * model environment when the caller already built it (the opener, whose report must describe what runs); otherwise it
+ * is built here from the credential options.
  */
-export function definitionModelRuntime(dir, options) {
-    return createPiModelRuntime({ agentDir: dir, ...options });
-}
-/** L2, as the value: load the directory (base + AGENTS.md + skills + env) and assemble. */
-export async function assemblePiFromDefinition(dir, 
-/** `auth` is the opener's already-resolved layers, which take the place of `authPath`. */
-options) {
+export async function assemblePiFromDefinition(dir, options) {
     // `dir` = the agent-definition dir (persona.md/skills/); `cwd` (default = dir) is the run root where tools operate
     // and whose ancestors are walked for ② context.
     const cwd = options.cwd ?? dir;
@@ -265,20 +290,27 @@ 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 auth = options.auth ?? (options.authPath === undefined ? resolveAuthLayers(dir) : { path: options.authPath });
+    const { providers } = options;
+    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: await definitionModelRuntime(dir, {
-            auth,
-            ...(options.providers ? { providers: options.providers } : {}),
-        }),
+        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 @@ 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 @@ 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/entry-images.d.ts

@@ -0,0 +1,14 @@
+import type { SessionManager } from "@earendil-works/pi-coding-agent";
+import type { ImageRef } from "../../agent.ts";
+import type { EntryImage } from "../../session.ts";
+type Message = {
+    role: string;
+    content?: unknown;
+};
+/** `data.images` of the entry `entryId` holding `message`, absent when it has none. */
+export declare function entryImages(entryId: string, message: Message): {
+    images?: EntryImage[];
+};
+/** The image `ref` names in `record`, or undefined when it names none there. The inverse of `entryImages`. */
+export declare function imageAt(record: SessionManager, ref: string): ImageRef | undefined;
+export {};

package/dist/engines/pi/entry-images.js

@@ -0,0 +1,23 @@
+/** A user prompt's and a tool result's images; no other message publishes any, so no ref can reach them. */
+function publishedImages(message) {
+    if (message.role !== "user" && message.role !== "toolResult")
+        return [];
+    const content = message.content;
+    return Array.isArray(content) ? content.filter((b) => b.type === "image") : [];
+}
+/** `data.images` of the entry `entryId` holding `message`, absent when it has none. */
+export function entryImages(entryId, message) {
+    const images = publishedImages(message).map((b, i) => ({ ref: `${entryId}:${i}`, mimeType: b.mimeType }));
+    return images.length > 0 ? { images } : {};
+}
+/** The image `ref` names in `record`, or undefined when it names none there. The inverse of `entryImages`. */
+export function imageAt(record, ref) {
+    const at = ref.lastIndexOf(":");
+    const index = ref.slice(at + 1);
+    // Canonical digits only, so one image has one ref (`:00` is not `:0`).
+    if (at <= 0 || !/^(0|[1-9]\d*)$/.test(index))
+        return undefined;
+    const entry = record.getEntry(ref.slice(0, at));
+    const image = entry?.type === "message" ? publishedImages(entry.message)[Number(index)] : undefined;
+    return image ? { data: image.data, mimeType: image.mimeType } : undefined;
+}

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

@@ -4,12 +4,18 @@ import * as Effect from "effect/Effect";
 import * as Fiber from "effect/Fiber";
 import * as Queue from "effect/Queue";
 import { ABORTED_CODE, SESSION_BUSY_CODE, } from "../../agent.js";
+import { entryImages } from "./entry-images.js";
 import { cancellableStream } from "../../collect.js";
 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) {
@@ -32,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 {
@@ -105,9 +128,10 @@ function reportUserMessages(session, report) {
     return Effect.acquireRelease(Effect.sync(() => {
         record.appendMessage = (message) => {
             const entryId = append.call(record, message);
-            // The same text `entries()` publishes for this entry (session-control.ts toSessionEntry).
-            if (message.role === "user")
-                report(entryId, contentText(message.content, ""));
+            // The same text and images `entries()` publishes for this entry (session-control.ts toSessionEntry).
+            if (message.role === "user") {
+                report({ entryId, text: contentText(message.content, ""), ...entryImages(entryId, message) });
+            }
             return entryId;
         };
     }), () => Effect.sync(() => {
@@ -123,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;
@@ -142,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(() => {
@@ -188,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)
@@ -198,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;
@@ -220,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) {
@@ -240,7 +305,7 @@ export function createPiAgentFromSession(options) {
                 if (OWED_BY_THE_RUN.has(error.event))
                     extensionFailure ??= `${error.event} failed (${error.extensionPath}): ${error.error}`;
             })), (unsubscribe) => Effect.sync(unsubscribe));
-            yield* reportUserMessages(session, (entryId, text) => observe({ type: "user_message", timestamp: Date.now(), runId, data: { entryId, text } }));
+            yield* reportUserMessages(session, (data) => observe({ type: "user_message", timestamp: Date.now(), runId, data }));
             const extensionTurns = trackExtensionTurns(session);
             // Completing the gate can run waiting controls synchronously; their queue events must be observed.
             yield* Deferred.succeed(bound, session);
@@ -316,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;
+}