pim-agent 0.13.0 → 0.14.1

package/packages/core/src/extensions/read/schema.ts

@@ -27,7 +27,7 @@ export type ReadRange = {
   readonly end?: number;
 };
 
-export type ReadTextDetails = {
+type ReadTextDetails = {
   readonly kind: "text";
   readonly absolutePath: string;
   readonly totalLines: number;
@@ -42,7 +42,7 @@ export type ReadTextDetails = {
 export type ReadImageDetails = ImageDetails & {
   readonly kind: "image";
   readonly absolutePath: string;
-  /** Sent earlier in this conversation and unchanged since, so only the note went to the model. */
+  /** Only a note was sent; the image went out earlier. */
   readonly deduped?: boolean;
 };
 

package/packages/core/src/extensions/subagent/render.ts

@@ -28,7 +28,7 @@ export function formatCallTitle(prompt: string | undefined): string {
   return (prompt ?? "...").split(/\r?\n/u)[0]?.trim() || "...";
 }
 
-/** The status line the parent model reads while the call streams: the summary flattened. */
+/** The summary as plain text, for streaming updates. */
 export function formatTopLine(details: SubagentDetails): string {
   return summarySpans(details, details.stopReason === undefined)
     .map((span) => span.text)
@@ -57,7 +57,7 @@ function summarySpans(
   details: SubagentDetails,
   isPartial: boolean
 ): readonly Span[] {
-  // `details` is typed whole but may not be: pi empties it on failure, and old sessions lack usage.
+  // pi empties `details` on failure, and old sessions lack usage.
   if (details.usage === undefined) {
     return [];
   }

package/packages/core/src/extensions/subagent/subagent.ts

@@ -20,9 +20,8 @@ import { MessageText } from "../../session/MessageText";
 import { CoreExtensions } from "../CoreExtensions";
 import { formatTopLine } from "./render";
 
-export const PER_TASK_OUTPUT_CAP = 32 * 1024;
-export const SUBAGENT_TOOL_NAME = "subagent";
-
+const PER_TASK_OUTPUT_CAP = 32 * 1024;
+const SUBAGENT_TOOL_NAME = "subagent";
 export const UPDATE_INTERVAL_MS = 100;
 
 const inSubagent = new AsyncLocalStorage<true>();
@@ -38,7 +37,6 @@ export type SubagentUsage = {
 };
 
 export type SubagentSnapshot = {
-  /** The child's session id, for a log reader; a transcript is found from the call id, not this. */
   readonly sessionId: string | undefined;
   readonly usage: SubagentUsage;
   readonly stopReason: string | undefined;
@@ -47,7 +45,7 @@ export type SubagentSnapshot = {
   readonly contextWindow: number | undefined;
 };
 
-/** `returnedOutput` is the capped answer for the parent model; `fullOutput` is every word written. */
+/** `returnedOutput` is the capped last message; `fullOutput` is every message. */
 export type SubagentDetails = SubagentSnapshot & {
   readonly returnedOutput: string;
   readonly fullOutput: string;
@@ -67,9 +65,9 @@ export type SubagentSession = {
 
 export type SubagentSessionSpec = {
   readonly activeToolNames?: readonly string[];
-  /** The parent's live level; left unset, pi falls back to settings, not to the parent. */
+  /** Unset falls back to pi's settings, not the parent's level. */
   readonly thinkingLevel?: ThinkingLevel;
-  /** The parent's tool call id, which names the child's log on disk. */
+  /** Names the child's log file. */
   readonly callId?: string;
 };
 
@@ -90,7 +88,7 @@ export function childToolNames(
   return activeToolNames.filter((name) => name !== SUBAGENT_TOOL_NAME);
 }
 
-// The child inherits no registrations: without this roster its `tools` allowlist loses every pim tool.
+// The child inherits no registrations; without these its `tools` allowlist drops every pim tool.
 export function childLoaderOptions(cwd: string): {
   readonly cwd: string;
   readonly agentDir: string;
@@ -103,7 +101,7 @@ export function childLoaderOptions(cwd: string): {
   };
 }
 
-export async function createSdkSubagentSession(
+async function createSdkSubagentSession(
   parentCtx: ExtensionContext,
   spec: SubagentSessionSpec = {}
 ): Promise<SubagentSession> {
@@ -125,7 +123,7 @@ export async function createSdkSubagentSession(
   return session;
 }
 
-// `open`, not `create`: the log path must be derivable from the parent session id and call id.
+// `open`, not `create`, so the log path is derived from the parent session id and call id.
 async function childSessionManager(
   parentCtx: ExtensionContext,
   callId: string | undefined
@@ -279,7 +277,6 @@ export class SubagentEventCapture {
     this.emitUpdate();
   }
 
-  /** Drops a throttled update still in flight once the run is over. */
   public dispose(): void {
     this.cancelPending();
   }
@@ -295,7 +292,7 @@ export class SubagentEventCapture {
     };
   }
 
-  /** Everything the child wrote, one paragraph per assistant message, including a streaming one. */
+  /** All assistant messages so far, including one still streaming. */
   public narration(): string {
     const said =
       this.pendingText === ""
@@ -358,15 +355,7 @@ export class SubagentEventCapture {
   }
 }
 
-type MutableUsage = {
-  input: number;
-  output: number;
-  cacheRead: number;
-  cacheWrite: number;
-  cost: number;
-  turns: number;
-  contextTokens: number | undefined;
-};
+type MutableUsage = { -readonly [K in keyof SubagentUsage]: SubagentUsage[K] };
 
 export type OutputCapResult = {
   readonly text: string;

package/packages/core/src/extensions/system-prompt/index.ts

@@ -15,8 +15,7 @@ const DATETIME_MESSAGE_TYPE = "pim-datetime";
 
 export default function (surface?: Surface): ExtensionFactory {
   return (pi: ExtensionAPI): void => {
-    // On submit rather than in `before_agent_start`, which can only append
-    // behind the user's message.
+    // `before_agent_start` could only append after the user's message.
     pi.on("input", () => {
       pi.sendMessage(
         {

package/packages/core/src/extensions/system-prompt/prompt.ts

@@ -78,7 +78,7 @@ export function buildEnvironment(opts: EnvironmentOptions): string {
   ].join("\n");
 }
 
-/** What the surface renders beyond plain text; empty, so pi omits the section, where that is nothing. */
+/** Empty makes pi omit the section. */
 export function buildFormatting(surface: Surface | undefined): string {
   return surface === undefined ? "" : FORMATTING[surface];
 }
@@ -110,8 +110,6 @@ function computeOs(options: OsDescriptionOptions): string {
         return undefined;
       }
     });
-  const unixName = (): string | undefined => runCommand(["uname", "-sr"]);
-
   if (platform === "linux") {
     const osRelease = runCommand(["cat", "/etc/os-release"]);
     if (osRelease) {
@@ -147,7 +145,7 @@ function computeOs(options: OsDescriptionOptions): string {
     return ver?.replace(/\s+/g, " ").trim() || platform;
   }
 
-  return unixName() ?? platform;
+  return runCommand(["uname", "-sr"]) ?? platform;
 }
 
 type FieldParser = (line: string) => readonly [string, string] | undefined;

package/packages/core/src/extensions/todo/render.ts

@@ -47,10 +47,7 @@ function inProgressSection(items: readonly TodoItem[]): readonly ViewBlock[] {
   ];
 }
 
-export function formatWidgetTitle(
-  items: readonly TodoItem[],
-  theme: Theme
-): string {
+function formatWidgetTitle(items: readonly TodoItem[], theme: Theme): string {
   const total = theme.bold(Format.count(items.length, "todo"));
   const summary = formatStatusSummary(items);
   return summary ? `${total} (${summary})` : total;

package/packages/core/src/extensions/todo/todo.ts

@@ -14,7 +14,6 @@ export type FormatChecklistOptions = {
   readonly activeOnly?: boolean;
 };
 
-/** Identity key for the per-session state slot. */
 export type TodoSessionKey = ExtensionContext["sessionManager"];
 
 const itemsBySession = new WeakMap<TodoSessionKey, TodoItem[]>();
@@ -67,7 +66,7 @@ export function hasActiveItems(items: readonly TodoItem[]): boolean {
   return items.some(isActive);
 }
 
-export function summarizeItems(items: readonly TodoItem[]): TodoSummary {
+function summarizeItems(items: readonly TodoItem[]): TodoSummary {
   const summary: TodoSummary = {
     pending: 0,
     in_progress: 0,
@@ -129,32 +128,26 @@ function findLatestTodoItems(branch: readonly unknown[]): TodoItem[] {
 }
 
 function extractTodoItems(entry: unknown): TodoItem[] | undefined {
+  const holder = todoHolder(entry);
+  return isRecord(holder) && Array.isArray(holder.todos)
+    ? normalizeUnknownItems(holder.todos)
+    : undefined;
+}
+
+/** The todo tool result's details, or a compaction checkpoint's data. */
+function todoHolder(entry: unknown): unknown {
   if (!isRecord(entry)) {
     return undefined;
   }
-  if (entry.type === "message") {
-    const message = entry.message;
-    if (
-      !isRecord(message) ||
-      message.role !== "toolResult" ||
-      message.toolName !== "todo"
-    ) {
-      return undefined;
-    }
-    const details = message.details;
-    if (!isRecord(details) || !Array.isArray(details.todos)) {
-      return undefined;
-    }
-    return normalizeUnknownItems(details.todos);
-  }
   if (entry.type === "custom" && entry.customType === TODO_STATE_CUSTOM_TYPE) {
-    const data = entry.data;
-    if (!isRecord(data) || !Array.isArray(data.todos)) {
-      return undefined;
-    }
-    return normalizeUnknownItems(data.todos);
+    return entry.data;
   }
-  return undefined;
+  const message = entry.type === "message" ? entry.message : undefined;
+  return isRecord(message) &&
+    message.role === "toolResult" &&
+    message.toolName === "todo"
+    ? message.details
+    : undefined;
 }
 
 function normalizeUnknownItems(items: readonly unknown[]): TodoItem[] {

package/packages/core/src/extensions/web-fetch/JinaReaderClient.ts

@@ -155,17 +155,9 @@ function requiredString(value: unknown, name: string): string {
 }
 
 function optionalString(value: unknown, name: string): string | undefined {
-  if (value === undefined || value === null) {
-    return undefined;
-  }
-
-  if (typeof value !== "string") {
-    throw new JinaReaderClientError(
-      `Response contained invalid payload: expected string ${name}.`
-    );
-  }
-
-  return value;
+  return value === undefined || value === null
+    ? undefined
+    : requiredString(value, name);
 }
 
 function stringifyErrorData(data: unknown): string {

package/packages/core/src/extensions/web-fetch/WebViewFetchClient.ts

@@ -171,9 +171,7 @@ function readSnapshot(value: unknown): WebViewSnapshot {
 function safeClose(view: WebViewLike): void {
   try {
     view.close();
-  } catch {
-    // close() throws if already closed.
-  }
+  } catch {}
 }
 
 function defaultFactory(): WebViewLike {

package/packages/core/src/extensions/web-fetch/fetch.ts

@@ -9,7 +9,7 @@ import type { JinaReaderClient } from "./JinaReaderClient";
 import {
   WEB_FETCH_INLINE_BYTES,
   type WebFetchFormat,
-  type WebFetchResolvedFormat,
+  type WebFetchPageDetails,
 } from "./schema";
 import type { WebViewFetchClient } from "./WebViewFetchClient";
 
@@ -19,16 +19,8 @@ export type WebFetchPage = {
   readonly content: string;
 };
 
-export type WebFetchPageOutcome = {
-  readonly kind: "page";
+export type WebFetchPageOutcome = WebFetchPageDetails & {
   readonly text: string;
-  readonly title: string;
-  readonly url: string;
-  readonly format: WebFetchResolvedFormat;
-  readonly returnedBytes: number;
-  readonly totalBytes: number;
-  readonly truncated: boolean;
-  readonly path: string | null;
 };
 
 export type WebFetchOutcome = WebFetchPageOutcome | WebFetchImageOutcome;
@@ -73,7 +65,7 @@ export function validatePublicUrl(value: string): string {
 
 export async function formatOutcome(
   page: WebFetchPage,
-  format: WebFetchResolvedFormat
+  format: WebFetchFormat
 ): Promise<WebFetchPageOutcome> {
   const { body, returnedBytes, totalBytes, truncated } =
     OutputBudget.truncateUtf8(page.content, WEB_FETCH_INLINE_BYTES);
@@ -120,7 +112,7 @@ export type ExecuteFetchInput = {
   readonly url: string;
   readonly format: WebFetchFormat;
   readonly signal?: AbortSignal;
-  /** Only the image probe takes it; the readers own their own transports. */
+  /** Used only by the image probe. */
   readonly fetch?: HttpFetch;
 };
 

package/packages/core/src/extensions/web-fetch/image.ts

@@ -20,7 +20,7 @@ const TIMEOUT_MS = 20_000;
 
 const IMAGE_CONTENT_TYPE = /^image\//iu;
 
-/** The picture the URL really serves, or null for anything the page path should handle. */
+/** Null when the URL does not serve an image. */
 export async function fetchImage(
   input: ImageFetchInput
 ): Promise<NormalisedImage | null> {
@@ -49,7 +49,6 @@ export function imageContent(
   return [...Images.contentOf(image, Images.noteOf(image)), ...footer];
 }
 
-/** The fetch succeeded and the intent was ambiguous, so the model is told what it got, not refused. */
 export function noVisionNote(url: string, image: NormalisedImage): string {
   const saved = image.cachePath === null ? "" : `, saved to ${image.cachePath}`;
   return Images.noVisionNote(
@@ -72,7 +71,7 @@ export function imageDetails(
   };
 }
 
-/** A response whose own headers claim a picture; the bytes still have to agree. */
+/** A response whose headers claim an image; the bytes are sniffed later. */
 async function declaredImage(input: ImageFetchInput): Promise<Response | null> {
   let response: Response;
 
@@ -105,7 +104,7 @@ async function declaredImage(input: ImageFetchInput): Promise<Response | null> {
   return response;
 }
 
-/** Stops at the cap and at the first chunk that is not a picture, so neither is ever buffered whole. */
+/** Stops early on oversize or on bytes that don't sniff as an image. */
 async function readCapped(
   response: Response,
   url: string

package/packages/core/src/extensions/web-fetch/index.ts

@@ -64,19 +64,8 @@ export default function (pi: ExtensionAPI): void {
         };
       }
 
-      return {
-        content: [{ type: "text", text: outcome.text }],
-        details: {
-          kind: "page",
-          url: outcome.url,
-          title: outcome.title,
-          format: outcome.format,
-          returnedBytes: outcome.returnedBytes,
-          totalBytes: outcome.totalBytes,
-          truncated: outcome.truncated,
-          path: outcome.path,
-        },
-      };
+      const { text, ...details } = outcome;
+      return { content: [{ type: "text", text }], details };
     },
     toViewModel: webFetchView,
   });

package/packages/core/src/extensions/web-fetch/render.ts

@@ -9,14 +9,13 @@ import type {
   WebFetchFormat,
   WebFetchImageDetails,
   WebFetchInput,
-  WebFetchResolvedFormat,
   webFetchSchema,
 } from "./schema";
 
 type WebFetchViewInput = ToolViewInput<typeof webFetchSchema, WebFetchDetails>;
 
 type TitleOutcome = {
-  readonly format: WebFetchResolvedFormat;
+  readonly format: WebFetchFormat;
   readonly totalBytes: number;
 };
 
@@ -41,7 +40,7 @@ export function webFetchView({ args, result }: WebFetchViewInput): ToolView {
   };
 }
 
-/** Legacy sessions predate the tag, so anything untagged reads as a page. */
+/** Untagged (legacy) details are pages. */
 function imageDetailsOf(
   details: WebFetchDetails | undefined
 ): WebFetchImageDetails | undefined {
@@ -95,6 +94,6 @@ function formatDetail(
     : `${Format.bytesCompact(outcome.totalBytes)} ${label}`;
 }
 
-function formatLabel(format: WebFetchResolvedFormat): string {
+function formatLabel(format: WebFetchFormat): string {
   return format === "html" ? "HTML" : "Markdown";
 }

package/packages/core/src/extensions/web-fetch/schema.ts

@@ -6,7 +6,6 @@ export const WEB_FETCH_INLINE_BYTES = 32 * 1024;
 
 export const FETCH_FORMATS = ["markdown", "html"] as const;
 export type WebFetchFormat = (typeof FETCH_FORMATS)[number];
-export type WebFetchResolvedFormat = WebFetchFormat;
 
 export const webFetchSchema = Type.Object({
   url: Type.String({
@@ -27,7 +26,7 @@ export type WebFetchPageDetails = {
   readonly kind: "page";
   readonly url: string;
   readonly title: string;
-  readonly format: WebFetchResolvedFormat;
+  readonly format: WebFetchFormat;
   readonly returnedBytes: number;
   readonly totalBytes: number;
   readonly truncated: boolean;
@@ -37,9 +36,9 @@ export type WebFetchPageDetails = {
 export type WebFetchImageDetails = ImageDetails & {
   readonly kind: "image";
   readonly url: string;
-  /** `~/.pim/cache/img-<sha256>.<ext>`, or null when the cache write failed. */
+  /** Null when the cache write failed. */
   readonly path: string | null;
-  /** Cached and shown here, but never sent: the current model has no vision input. */
+  /** Not sent because the model has no vision input. */
   readonly withheld: boolean;
 };
 

package/packages/core/src/extensions/web-search/ExaMcpClient.ts

@@ -19,6 +19,8 @@ type ExaSearchInput = {
   readonly signal?: AbortSignal;
 };
 
+type ResultObject = Readonly<Record<string, unknown>>;
+
 class ExaSearchError extends Error {
   public constructor(message: string) {
     super(message);
@@ -28,7 +30,7 @@ class ExaSearchError extends Error {
 
 const defaultEndpoint = "https://mcp.exa.ai/mcp";
 const toolName = "web_search_exa";
-// Stay under the keyless endpoint's 2 req/s window, or a 429 no longer means the daily cap.
+// Stay under the keyless 2 req/s limit so a 429 means the daily cap.
 const maxRequestsPerWindow = 2;
 const windowMs = 1100;
 
@@ -40,7 +42,7 @@ export class ExaMcpClient {
       options.apiKey === undefined || options.apiKey.length === 0
         ? undefined
         : options.apiKey;
-    // Throttle only on the free tier; an API key lifts the rate limit.
+    // An API key lifts the rate limit.
     const rateLimiter =
       apiKey !== undefined
         ? undefined
@@ -181,37 +183,30 @@ function readPlainTextSnippet(lines: readonly string[]): string {
 
 function findFirstObjectArray(
   values: readonly unknown[]
-): readonly Readonly<Record<string, unknown>>[] | undefined {
+): readonly ResultObject[] | undefined {
   for (const value of values) {
-    if (
-      Array.isArray(value) &&
-      value.every((item) => Json.asRecord(item) !== undefined)
-    ) {
-      return value as readonly Readonly<Record<string, unknown>>[];
-    }
-
-    const record = Json.asRecord(value);
-
-    if (record === undefined) {
-      continue;
+    if (isObjectArray(value)) {
+      return value;
     }
-
-    for (const nestedValue of Object.values(record)) {
-      if (
-        Array.isArray(nestedValue) &&
-        nestedValue.every((item) => Json.asRecord(item) !== undefined)
-      ) {
-        return nestedValue as readonly Readonly<Record<string, unknown>>[];
-      }
+    const nested = Object.values(Json.asRecord(value) ?? {}).find(
+      isObjectArray
+    );
+    if (nested !== undefined) {
+      return nested;
     }
   }
 
   return undefined;
 }
 
-function projectResult(
-  result: Readonly<Record<string, unknown>>
-): SearchResult {
+function isObjectArray(value: unknown): value is readonly ResultObject[] {
+  return (
+    Array.isArray(value) &&
+    value.every((item) => Json.asRecord(item) !== undefined)
+  );
+}
+
+function projectResult(result: ResultObject): SearchResult {
   return {
     title: readResultString(result, "title"),
     url: readResultString(result, "url"),
@@ -219,7 +214,7 @@ function projectResult(
   };
 }
 
-function readSnippet(result: Readonly<Record<string, unknown>>): string {
+function readSnippet(result: ResultObject): string {
   return (
     readOptionalResultString(result, "snippet") ??
     readOptionalResultString(result, "text") ??
@@ -228,10 +223,7 @@ function readSnippet(result: Readonly<Record<string, unknown>>): string {
   );
 }
 
-function readResultString(
-  result: Readonly<Record<string, unknown>>,
-  name: string
-): string {
+function readResultString(result: ResultObject, name: string): string {
   const value = readOptionalResultString(result, name);
 
   if (value === undefined) {
@@ -242,7 +234,7 @@ function readResultString(
 }
 
 function readOptionalResultString(
-  result: Readonly<Record<string, unknown>>,
+  result: ResultObject,
   name: string
 ): string | undefined {
   const value = result[name];

package/packages/core/src/extensions/web-search/SearchBreaker.ts

@@ -27,7 +27,7 @@ const DAY_MS = 86_400_000;
 
 const defaultProbeIntervalMs = 1_800_000;
 
-/** Which providers are quota-exhausted, on disk; quota is per-IP-per-day, so trips expire at UTC midnight. */
+/** Persists quota-exhausted providers. Trips expire at UTC midnight unless a retry-after is given. */
 export class SearchBreaker {
   private readonly filePath: string;
   private readonly now: () => number;

package/packages/core/src/extensions/web-search/SearchChain.ts

@@ -18,7 +18,7 @@ export type SearchChainOptions = {
   readonly breaker: SearchBreaker;
 };
 
-/** Tries providers in order until one answers; an empty result set is an answer and ends the chain. */
+/** Tries providers in order; the first answer wins, even an empty one. */
 export class SearchChain {
   private readonly providers: readonly SearchProvider[];
   private readonly breaker: SearchBreaker;
@@ -30,7 +30,6 @@ export class SearchChain {
 
   public async search(input: ProviderSearchInput): Promise<ChainSearchOutcome> {
     const failures: string[] = [];
-    let attempted = false;
 
     for (const provider of this.providers) {
       if (await this.breaker.isOpen(provider.name)) {
@@ -46,14 +45,16 @@ export class SearchChain {
         const results = await provider.search(input);
         await this.breaker.reset(provider.name);
 
-        return { provider: provider.name, results, fellBack: attempted };
+        return {
+          provider: provider.name,
+          results,
+          fellBack: failures.length > 0,
+        };
       } catch (error) {
         if (input.signal?.aborted || Errors.isAbort(error)) {
           throw error;
         }
 
-        attempted = true;
-
         if (error instanceof ProviderQuotaError) {
           await this.breaker.trip({
             provider: provider.name,

package/packages/core/src/extensions/web-search/providers/DuckDuckGoProvider.ts

@@ -25,7 +25,7 @@ const defaultReaderEndpoint = "https://r.jina.ai";
 const defaultSearchEndpoint = "https://lite.duckduckgo.com/lite/";
 const defaultTimeoutMs = 30_000;
 
-/** Reads the Lite SERP through Jina: DuckDuckGo answers direct API calls with a 202 anti-bot challenge. */
+/** Reads the Lite SERP through Jina; direct requests get a 202 anti-bot challenge. */
 export class DuckDuckGoProvider implements SearchProvider {
   public readonly name = "duckduckgo";
 
@@ -43,7 +43,7 @@ export class DuckDuckGoProvider implements SearchProvider {
     this.timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
     this.headers = {
       Accept: "application/json",
-      // The reader caches aggressively and would serve a stale SERP.
+      // Otherwise the reader may serve a stale SERP.
       "x-no-cache": "true",
       ...(options.apiKey === undefined || options.apiKey.length === 0
         ? {}

package/packages/core/src/extensions/web-search/providers/FirecrawlProvider.ts

@@ -20,7 +20,6 @@ export type FirecrawlProviderOptions = {
 const defaultEndpoint = "https://api.firecrawl.dev/v2/search";
 const defaultTimeoutMs = 20_000;
 
-/** Firecrawl search; omitting `Authorization` is the keyless tier, whose exhaustion shows only as a 429. */
 export class FirecrawlProvider implements SearchProvider {
   public readonly name = "firecrawl";
 
@@ -73,7 +72,7 @@ export class FirecrawlProvider implements SearchProvider {
       quotaStatuses: [429],
       quotaMessage:
         "Firecrawl rejected the request: keyless daily limit reached.",
-      // Firecrawl meters a rolling 24h window and reports the remainder in the body, not Retry-After.
+      // Firecrawl reports the wait in the body, not Retry-After.
       readRetryAfterMs,
     });
   }