@fastagent-sh/fastagent 0.23.0 → 0.24.1

package/dist/engines/pi/turn-kit.js

@@ -1,3 +1,6 @@
+/** The turn mechanism's ENGINE-agnostic half: the parts that describe a turn rather than pi. */
+import { stripVTControlCharacters } from "node:util";
+import { contentText } from "@earendil-works/pi-ai";
 import { ABORTED_CODE } from "../../agent.js";
 import { log } from "../../log.js";
 export function inProcessLease() {
@@ -71,19 +74,38 @@ function messageSignal(message) {
     return {};
 }
 /**
- * Terminal mapping, decided by the resolved message's stopReason: pi's `prompt()` RESOLVES a message with stopReason
+ * How an answer ended, read off the stopReason pi records on the message. The ONE reading: `message_finished`,
+ * the `assistant` entry `entries()` publishes, and the invoke terminal all derive from it, so the live outcome and
+ * the recorded one cannot disagree.
+ */
+export function answerOutcome(message) {
+    const error = message.errorMessage ? { error: { message: message.errorMessage } } : {};
+    switch (message.stopReason) {
+        case "error":
+            return { status: "failed", ...error };
+        case "aborted":
+            return { status: "aborted", ...error };
+        case "length":
+            return { status: "truncated" };
+        default:
+            return undefined;
+    }
+}
+/**
+ * Terminal mapping, decided by the resolved message's outcome: pi's `prompt()` RESOLVES a message with stopReason
  * "error"/"aborted" rather than throwing, so relying on catch alone would miss that whole failure class and violate
- * SPEC MUST 1.
+ * SPEC MUST 1. A truncated final answer still completes the run.
  */
 export function toTerminal(message) {
-    if (message.stopReason === "aborted") {
+    const outcome = answerOutcome(message);
+    if (outcome?.status === "aborted") {
         // A deliberate stop (a control-plane or consumer abort), not an error — see {@link ABORTED_CODE} for the consumer
         // contract (design §6).
-        const details = message.errorMessage ?? "run aborted";
+        const details = outcome.error?.message ?? "run aborted";
         return { type: "failed", details, retryable: false, code: ABORTED_CODE };
     }
-    if (message.stopReason === "error") {
-        const details = message.errorMessage ?? `model stopped: ${message.stopReason}`;
+    if (outcome?.status === "failed") {
+        const details = outcome.error?.message ?? "model stopped: error";
         return { type: "failed", details, retryable: classifyRetryable(details, messageSignal(message)) };
     }
     return { type: "completed" };
@@ -119,27 +141,82 @@ export async function toPiPromptOptions(prompt, delivery) {
     }));
     return { images };
 }
-/** The SPEC projection of the rich stream. */
-export function projectAgentEvent(se) {
-    switch (se.type) {
-        case "message_delta": {
-            const d = se.data;
-            return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
-        }
-        case "tool_started": {
-            const d = se.data;
-            return { type: "tool_started", id: d.id, name: d.name, args: d.args };
-        }
-        case "tool_finished": {
-            const d = se.data;
-            return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
-        }
-        case "retry_scheduled": {
-            // `operation` (compaction | branch_summary) stays session-plane vocabulary.
-            const d = se.data;
-            return { type: "retrying", attempt: d.attempt, maxAttempts: d.maxAttempts, delayMs: d.delayMs, reason: d.error };
-        }
-        default:
+/**
+ * The SPEC projection of ONE run's rich stream. Stateful only for `tool_progress`, the one event that is a status
+ * rather than a fact: an outer call's status line is sent when it changes, and a call that call makes, at any depth,
+ * is its status. Nested calls are otherwise the observation plane's alone.
+ */
+export function agentEventProjection() {
+    /** Each nested call's outer call, the one the stream announced with `tool_started`. */
+    const outerOf = new Map();
+    /** The status line each outer call last reported. */
+    const shown = new Map();
+    const progress = (id, text) => {
+        if (text === undefined || shown.get(id) === text)
             return null;
+        shown.set(id, text);
+        return { type: "tool_progress", id, text };
+    };
+    return (se) => {
+        switch (se.type) {
+            case "message_delta": {
+                const d = se.data;
+                return d.channel === "text" ? { type: "text", delta: d.delta } : { type: "thinking", delta: d.delta };
+            }
+            case "tool_started": {
+                const d = se.data;
+                if (!d.parentToolCallId)
+                    return { type: "tool_started", id: d.id, name: d.name, args: d.args };
+                const outer = outerOf.get(d.parentToolCallId) ?? d.parentToolCallId;
+                outerOf.set(d.id, outer);
+                return progress(outer, callLine(d.name, d.args));
+            }
+            case "tool_progress": {
+                const d = se.data;
+                // A nested call's own output is not its caller's status; the nested call starting is (above).
+                if (d.parentToolCallId || !Array.isArray(d.partialResult.content))
+                    return null;
+                return progress(d.id, lastLine(contentText(d.partialResult.content, "\n")));
+            }
+            case "tool_finished": {
+                const d = se.data;
+                if (d.parentToolCallId)
+                    return null;
+                return { type: "tool_ended", id: d.id, isError: d.isError, content: d.content };
+            }
+            case "retry_scheduled": {
+                // `operation` (compaction | branch_summary) stays session-plane vocabulary.
+                const d = se.data;
+                return {
+                    type: "retrying",
+                    attempt: d.attempt,
+                    maxAttempts: d.maxAttempts,
+                    delayMs: d.delayMs,
+                    reason: d.error,
+                };
+            }
+            default:
+                return null;
+        }
+    };
+}
+/**
+ * The line a terminal shows last: control sequences removed, and a bare `\r`, a progress bar redrawing in place, ends a
+ * line like `\n` does. Undefined when there is no visible text yet (a shell that has printed nothing).
+ */
+function lastLine(text) {
+    const lines = stripVTControlCharacters(text).split(/\r\n|\r|\n/);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i]?.trim();
+        if (line)
+            return line;
     }
+    return undefined;
+}
+/** A nested call as its caller's status: the tool and its first plain argument, on one line (`weather London`). */
+function callLine(name, args) {
+    const first = args !== null && typeof args === "object" && !Array.isArray(args)
+        ? Object.values(args).find((value) => typeof value === "string" || typeof value === "number")
+        : undefined;
+    return first === undefined ? name : `${name} ${String(first).replace(/\s+/g, " ").trim()}`.trim();
 }

package/dist/pi.d.ts

@@ -5,7 +5,7 @@ export { z } from "zod";
 export type { AgentTool, ExecutionEnv, Skill, SkillDiagnostic } from "@earendil-works/pi-agent-core";
 /** A conversation record, as the tool runtime and the control plane hold it. */
 export type { SessionManager, SessionEntry as PiSessionEntry } from "@earendil-works/pi-coding-agent";
-export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshModelCatalog, } from "./engines/pi/open.ts";
+export { availableModelsFromDir, createPiAgentFromDir, type CreatePiAgentFromDirOptions, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.ts";
 export type { LoadedDefinition, SkillCollision } from "./engines/pi/definition.ts";
 export { defineConfig, listModels, resolveModel, type FastagentConfig, } from "./engines/pi/config.ts";
 export type { SessionObserver } from "./engines/pi/turn-kit.ts";

package/dist/pi.js

@@ -2,7 +2,7 @@
 export { createPiAgent, createPiAgentFromDefinition, } from "./engines/pi/create.js";
 export { defineTool, } from "./engines/pi/tool.js";
 export { z } from "zod";
-export { availableModelsFromDir, createPiAgentFromDir, refreshModelCatalog, } from "./engines/pi/open.js";
+export { availableModelsFromDir, createPiAgentFromDir, refreshMachineModelCatalog, refreshModelCatalog, } from "./engines/pi/open.js";
 export { defineConfig, listModels, resolveModel, } from "./engines/pi/config.js";
 export { inProcessLease } from "./engines/pi/turn-kit.js";
 export { createPiSessionControl, } from "./engines/pi/session-control.js";

package/dist/session.d.ts

@@ -54,14 +54,22 @@ export interface Session {
      */
     image(ref: string): Promise<ImageRef | undefined>;
     events(): SessionEventStream;
-    /** Set durable session properties. */
+    /**
+     * Set durable session properties, applied by the session's next turn. An id with no record (nothing has written it
+     * yet) takes them too: the write creates its record, and the session's first turn runs on them. Refused there:
+     * `leafEntryId` (no entries to point at) and an id no client could address ({@link isAddressableSession}).
+     */
     update(patch: SessionUpdate): Promise<SessionResult>;
     /**
      * Join the active run: delivered after the current turn's tool calls, before the next model call. `prompt.text`
-     * must not be empty (`invalid_command`): a queued prompt is reported by its text ({@link PendingPrompts}).
+     * must not be empty (`invalid_command`): a queued prompt is reported by its text ({@link PendingPrompts}). An
+     * accepted result carries its {@link PromptDisposition}.
      */
     steer(prompt: Prompt): Promise<SessionResult>;
-    /** Queue for the active run, FIFO, delivered when it is otherwise idle. Same non-empty `text` rule as `steer`. */
+    /**
+     * Queue for the active run, FIFO, delivered when it is otherwise idle. Same non-empty `text` rule and
+     * {@link PromptDisposition} as `steer`.
+     */
     followUp(prompt: Prompt): Promise<SessionResult>;
     /** Stop the active run — its queues, its retry delay, its cancellable tool work. */
     abort(): Promise<SessionResult>;
@@ -121,11 +129,22 @@ export interface SessionCapabilities {
     delete: boolean;
     /** Which {@link SessionUpdate} fields this deployment accepts. */
     updatable: SessionUpdateField[];
-    /** The specs `update({ model })` accepts — present iff `model` is updatable. */
-    allowedModels?: string[];
+    /** The models `update({ model })` accepts, by `spec` — present iff `model` is updatable. */
+    allowedModels?: ModelDescriptor[];
     toolProgress: boolean;
     usage: boolean;
 }
+/**
+ * A model as a picker shows it, before any session runs on it. `thinkingLevels` is what `update({ thinkingLevel })`
+ * accepts for a session on this model; `name` and `contextWindow` are absent when the model does not declare them.
+ */
+export interface ModelDescriptor {
+    /** What `update({ model })` takes. */
+    spec: string;
+    name?: string;
+    thinkingLevels: string[];
+    contextWindow?: number;
+}
 /** One name a client can offer the user. */
 export interface AgentCommand {
     name: string;
@@ -144,7 +163,11 @@ export declare const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
 export declare const NO_ACTIVE_RUN_CODE = "no_active_run";
 /** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime. */
 export declare const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a write against a session that does not exist. */
+/**
+ * Stable `SessionResult.error.code` for a write that needs a record (fork's source, compact, delete) against an id
+ * that has none, because nothing has written it yet. `update()` creates the record instead, and answers this code only
+ * when a concurrent `delete()` removes the record between its read and its write.
+ */
 export declare const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable landed. */
 export declare const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";
@@ -180,6 +203,7 @@ export declare const PARTIAL_UPDATE_CODE = "partial_update";
 export type SessionResult = {
     ok: true;
     runId?: string;
+    disposition?: PromptDisposition;
 } | {
     ok: false;
     error: {
@@ -188,6 +212,13 @@ export type SessionResult = {
         retryable: boolean;
     };
 };
+/**
+ * What became of an accepted `steer`/`followUp` prompt — present on exactly those results. `queued`: it waits in
+ * {@link PendingPrompts} until the run takes it in. `handled`: the engine consumed it before the queue (in pi, a
+ * definition extension's `input` handler), so it never enters the conversation, and no `queue_changed` or
+ * `user_message` reports it.
+ */
+export type PromptDisposition = "queued" | "handled";
 /** One session in {@link SessionControl.sessions} — a conversation-list row, not a session's contents. */
 export interface SessionSummary {
     session: string;
@@ -205,7 +236,10 @@ export interface SessionState {
     /** `compacting` refers to MANUAL compaction (`compact`) at a session boundary. */
     status: "idle" | "running" | "compacting";
     activeRunId?: string;
-    /** What this session will RUN with, not what was recorded. */
+    /**
+     * What this session will RUN with, not what was recorded. An id with no record reports what its first turn would run
+     * on: the defaults, the level clamped to the model.
+     */
     model?: string;
     thinkingLevel?: string;
     /** What `update({ thinkingLevel })` accepts for THIS session — re-read after a model change. */
@@ -319,13 +353,29 @@ export type MessageDeltaEvent = SessionEvent<"message_delta", {
 }> & {
     runId: string;
 };
-export type MessageFinishedEvent = SessionEvent<"message_finished", Record<never, never>> & {
+/**
+ * How an answer ended, when it did not end normally: absent on an answer that did. One value, carried live by its
+ * `message_finished` and durably by its `assistant` entry, so a reopened conversation reads what a watcher saw.
+ * `truncated` is an answer cut off at the output limit — a property of the answer, not of its run, which may still
+ * complete. An answer whose entry a `context_edit { omitted }` targets (`failed` or `truncated`) is an attempt the
+ * engine abandoned; a retry usually, but not always, follows it.
+ */
+export type AnswerOutcome = {
+    status: "failed" | "aborted" | "truncated";
+    error?: {
+        message: string;
+    };
+};
+export type MessageFinishedEvent = SessionEvent<"message_finished", {
+    outcome?: AnswerOutcome;
+}> & {
     runId: string;
 };
 export type ToolStartedEvent = SessionEvent<"tool_started", {
     id: string;
     name: string;
     args: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
@@ -334,6 +384,7 @@ export type ToolProgressEvent = SessionEvent<"tool_progress", {
     id: string;
     name: string;
     partialResult: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };
@@ -341,6 +392,7 @@ export type ToolFinishedEvent = SessionEvent<"tool_finished", {
     id: string;
     isError: boolean;
     content: Json;
+    parentToolCallId?: string;
 }> & {
     runId: string;
 };

package/dist/session.js

@@ -28,7 +28,11 @@ export const UNSUPPORTED_CAPABILITY_CODE = "unsupported_capability";
 export const NO_ACTIVE_RUN_CODE = "no_active_run";
 /** Stable `SessionResult.error.code` for a PAYLOAD that is invalid for this runtime. */
 export const INVALID_COMMAND_CODE = "invalid_command";
-/** Stable `SessionResult.error.code` for a write against a session that does not exist. */
+/**
+ * Stable `SessionResult.error.code` for a write that needs a record (fork's source, compact, delete) against an id
+ * that has none, because nothing has written it yet. `update()` creates the record instead, and answers this code only
+ * when a concurrent `delete()` removes the record between its read and its write.
+ */
 export const NO_SUCH_SESSION_CODE = "no_such_session";
 /** Stable `SessionResult.error.code` for a write rejected BEFORE acceptance with nothing durable landed. */
 export const BOUNDARY_COMMAND_FAILED_CODE = "boundary_command_failed";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fastagent-sh/fastagent",
-  "version": "0.23.0",
+  "version": "0.24.1",
   "description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on Telegram, Slack, Feishu, or behind any channel.",
   "keywords": [
     "agent",
@@ -101,16 +101,16 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.6.0",
-    "@earendil-works/pi-agent-core": "^0.87.1",
-    "@earendil-works/pi-ai": "^0.87.1",
-    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@earendil-works/pi-agent-core": "^0.99.2",
+    "@earendil-works/pi-ai": "^0.99.2",
+    "@earendil-works/pi-coding-agent": "^0.99.2",
     "@hono/node-server": "^2.1.1",
     "@larksuiteoapi/node-sdk": "^1.71.1",
     "@smithy/signature-v4": "^5.7.4",
     "chokidar": "^5.0.0",
     "commander": "^15.0.0",
     "croner": "^10.0.1",
-    "effect": "4.0.0-rc.117",
+    "effect": "4.0.0-rc.118",
     "giget": "^3.3.0",
     "ignore": "^7.0.5",
     "proper-lockfile": "^4.1.2",

package/dist/engines/pi/search-tools.d.ts

@@ -1,4 +0,0 @@
-import { type MountedTool } from "./tool.ts";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
-export declare function withSearchTool(tools: MountedTool[]): MountedTool[];
-export declare function makeSearchToolsTool(): MountedTool;

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

@@ -1,109 +0,0 @@
-/** The built-in `search_tools` loader — the discovery surface for deferred tools (defineTool `deferred: true`). */
-import { z } from "zod";
-import { log } from "../../log.js";
-import { defineTool, isDeferredTool, stripDeferredMarker } from "./tool.js";
-/** Mount the built-in loader iff any mounted tool is deferred and the author didn't define their own. */
-export function withSearchTool(tools) {
-    if (!tools.some(isDeferredTool))
-        return tools;
-    const authored = tools.find((t) => t.name === "search_tools");
-    if (!authored)
-        return [...tools, makeSearchToolsTool()];
-    let fixed = authored;
-    if (isDeferredTool(fixed)) {
-        // A deferred LOADER is a contradiction — it is the only entry point to the deferred tools, so nothing could ever
-        // activate it (or, through it, them).
-        log.warn("[fastagent] search_tools is marked deferred — ignoring the marker: the loader must stay active, or no deferred tool could ever be activated");
-        fixed = stripDeferredMarker(fixed);
-    }
-    return fixed === authored ? tools : tools.map((t) => (t === authored ? fixed : t));
-}
-/** Activation cap per search: activation is additive, session-persisted, and has NO deactivate path. */
-const MAX_ACTIVATIONS_PER_SEARCH = 5;
-/** Miss-path listing cap — same rationale as the activation cap. */
-const MAX_MISS_LISTING = 10;
-export function makeSearchToolsTool() {
-    return defineTool({
-        name: "search_tools",
-        description: 
-        // First line short on purpose: the base prompt's tools list truncates at the first newline, and the discovery
-        // guidance below would otherwise flood it (and duplicate its deferred note).
-        "Discover and activate additional tools.\n" +
-            "Part of this agent's toolset is inactive until needed: search by keywords (e.g. what you are " +
-            "trying to do), and matching inactive tools are activated and become callable from that point on " +
-            "(if too many match, you get the candidates back — narrow the query, or query an exact tool " +
-            "name). ALWAYS search here before concluding a capability is missing.",
-        input: z.object({
-            query: z.string().min(1).describe("keywords describing the capability you need (e.g. 'weather forecast')"),
-        }),
-        async execute(input, ctx) {
-            if (!ctx.tools)
-                return "tool activation is unavailable outside a conversation turn.";
-            // Search the WHOLE registered catalog: the loader is the only discovery surface, and in a long conversation the
-            // model does not remember what it activated.
-            // ponytail: naive keyword match (any query token as a case-insensitive substring of name+description) under a
-            // hard per-search activation cap — the two ceilings are relevance and irreversibility; swap in
-            // scoring/embeddings if catalogs outgrow this.
-            const tokens = input.query
-                .toLowerCase()
-                .split(/[^a-z0-9]+/)
-                .filter(Boolean);
-            // AND semantics: EVERY token must hit — "adding a word narrows" must actually hold, or the over-cap "narrow the
-            // query" instruction sends the model in circles (OR would widen with each word, and a shared prefix like
-            // "fetch" could make a whole tool family permanently over-cap).
-            const matchesQuery = (t) => {
-                const haystack = `${t.name} ${t.description}`.toLowerCase();
-                return tokens.every((token) => haystack.includes(token));
-            };
-            const describe = (t) => `${t.name} — ${t.description.split("\n")[0]}`;
-            const active = new Set(ctx.tools.active());
-            const registered = ctx.tools.registered();
-            // A query with no searchable tokens (all punctuation/symbols) must not match.
-            if (tokens.length === 0)
-                return `"${input.query}" contains no searchable keywords — describe the capability you need.`;
-            // Exact-name shortcut: the guaranteed escape hatch from the cap — a query that IS an INACTIVE registered tool's
-            // name addresses that one tool, no keyword scoring in the way.
-            const exact = registered.find((t) => t.name.toLowerCase() === input.query.trim().toLowerCase());
-            const activeMatches = registered.filter((t) => active.has(t.name) && (t === exact || matchesQuery(t)));
-            const inactiveMatches = exact && !active.has(exact.name) ? [exact] : registered.filter((t) => !active.has(t.name) && matchesQuery(t));
-            // Same listing cap as every other branch — a wide token can match most of the ACTIVE set too (in chat that
-            // includes pi's default tools), and no answer may pour a catalog into the context.
-            const listedActive = activeMatches.slice(0, MAX_MISS_LISTING);
-            const moreActive = activeMatches.length - listedActive.length;
-            const activeNote = activeMatches.length > 0
-                ? `Already active (call directly): ${listedActive.map(describe).join("; ")}${moreActive > 0 ? ` … and ${moreActive} more` : ""}.`
-                : "";
-            if (inactiveMatches.length === 0) {
-                if (activeNote)
-                    return activeNote;
-                const inactive = registered.filter((t) => !active.has(t.name));
-                if (inactive.length === 0)
-                    return "All tools are already active — nothing to discover.";
-                // Cap the miss listing like the activation cap — both guard the same semantic (don't pour the catalog back
-                // into the context the deferral exists to protect).
-                const listed = inactive.slice(0, MAX_MISS_LISTING);
-                const more = inactive.length - listed.length;
-                return `No tools matched "${input.query}". Inactive tools: ${listed.map(describe).join("; ")}${more > 0 ? ` … and ${more} more — search with different keywords.` : ""}`;
-            }
-            if (inactiveMatches.length > MAX_ACTIVATIONS_PER_SEARCH) {
-                // Same listing cap as the miss path — an over-cap answer must not pour the catalog into the context either.
-                const listed = inactiveMatches.slice(0, MAX_MISS_LISTING);
-                const more = inactiveMatches.length - listed.length;
-                return `${inactiveMatches.length} inactive tools matched "${input.query}" — too many to activate at once (activation is permanent for this conversation). Narrow the query (or query an exact name). Matches: ${listed
-                    .map((t) => t.name)
-                    .join(", ")}${more > 0 ? ` … and ${more} more` : ""}.${activeNote ? ` ${activeNote}` : ""}`;
-            }
-            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.
-            if (activated.length === 0) {
-                return `Matched ${inactiveMatches.map((t) => t.name).join(", ")} — already active (possibly activated by a concurrent call). Call them directly.${activeNote ? ` ${activeNote}` : ""}`;
-            }
-            const raced = inactiveMatches.filter((t) => !activated.includes(t.name));
-            return `Activated: ${inactiveMatches
-                .filter((t) => activated.includes(t.name))
-                .map(describe)
-                .join("; ")}.${raced.length > 0 ? ` Already active: ${raced.map((t) => t.name).join(", ")}.` : ""}${activeNote ? ` ${activeNote}` : ""} These tools are callable now.`;
-        },
-    });
-}