pim-agent 0.12.1 → 0.14.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,
     });
   }

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

@@ -18,7 +18,7 @@ export type SearchProvider = {
   search(input: ProviderSearchInput): Promise<readonly SearchResult[]>;
 };
 
-/** Quota or rate limit exhausted; only this error opens the breaker and sidelines a provider. */
+/** The only error that trips the breaker. */
 export class ProviderQuotaError extends Error {
   public readonly provider: string;
   public readonly retryAfterMs: number | undefined;
@@ -43,7 +43,7 @@ export class ProviderSearchError extends Error {
 
 const MAX_SNIPPET_LENGTH = 500;
 
-/** Caps a provider snippet; Firecrawl returns whole scraped pages where others return two lines. */
+/** Collapses whitespace and caps length; Firecrawl can return whole pages. */
 export function normalizeSnippet(value: string | undefined): string {
   const collapsed = (value ?? "").replaceAll(/\s+/gu, " ").trim();
 
@@ -52,7 +52,7 @@ export function normalizeSnippet(value: string | undefined): string {
     : collapsed;
 }
 
-export function parseRetryAfterMs(value: string | null): number | undefined {
+function parseRetryAfterMs(value: string | null): number | undefined {
   if (value === null) {
     return undefined;
   }

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

@@ -4,7 +4,7 @@ import { FsErrors } from "../../shared/FsErrors";
 
 const CONTEXT_LINES = 3;
 
-// Diff.diffLines is O(n*d): above this only the diff is skipped, never the write.
+// Diffing is O(n*d); above this the diff is skipped, not the write.
 const MAX_DIFF_BYTES = 2 * 1024 * 1024;
 
 export type WriteOutcome = {

package/packages/core/src/picker/InProcessFilePickerSuggestionEngine.ts

@@ -25,9 +25,7 @@ export class InProcessFilePickerSuggestionEngine implements FilePickerSuggestion
         this.cachedRelative = catalog;
       })
       .catch(() => {
-        if (this.cachedRelative === undefined) {
-          this.cachedRelative = [];
-        }
+        this.cachedRelative ??= [];
       })
       .finally(() => {
         this.refresh = undefined;

package/packages/core/src/picker/PickerItem.ts

@@ -1,4 +1,4 @@
-/** One completion row, structurally identical to pi-tui's `AutocompleteItem`. */
+/** Structurally identical to pi-tui's `AutocompleteItem`. */
 export type PickerItem = {
   readonly value: string;
   readonly label: string;

package/packages/core/src/picker/PickerService.ts

@@ -9,19 +9,16 @@ import { InProcessFilePickerSuggestionEngine } from "./InProcessFilePickerSugges
 import type { PickerItem } from "./PickerItem";
 
 export type PickerServiceDeps = {
-  /** Read per query: a session's cwd can move between turns. */
+  /** Read per query; the cwd can change between turns. */
   readonly cwd: () => string;
   readonly agentDir: string;
-  /** Extension-registered commands, available only while an agent is built. */
+  /** Source of extension commands; undefined until an agent is built. */
   readonly agent?: () => AgentSession | undefined;
 };
 
 const DEFAULT_LIMIT = 50;
 
-/**
- * The `.agents/skills` roots pi reads and `loadSkills` does not: every one from
- * the cwd up to the repository root, plus the user's own.
- */
+/** `.agents/skills` dirs from cwd up to the repo root, plus `~/.agents/skills`; `loadSkills` skips these. */
 function agentsSkillDirs(cwd: string): string[] {
   const dirs: string[] = [];
   let dir = resolve(cwd);
@@ -37,7 +34,6 @@ function agentsSkillDirs(cwd: string): string[] {
   return dirs;
 }
 
-/** Answers one session's picker queries against the machine the agent runs on. */
 export class PickerService {
   private readonly deps: PickerServiceDeps;
   private fileCache:

package/packages/core/src/picker/RemoteFilePickerSuggestionEngine.ts

@@ -13,7 +13,7 @@ const DEBOUNCE_MS = 30;
 
 const CACHE_LIMIT = 100;
 
-/** The client half of the `@` picker: the TUI's engine contract, answered by the server. Browser-safe APIs only. */
+/** Browser-safe: asks the server for `@` picker rows. */
 export class RemoteFilePickerSuggestionEngine implements FilePickerSuggestionEngine {
   private readonly cache = new Map<string, readonly PickerItem[]>();
   private generation = 0;
@@ -23,7 +23,6 @@ export class RemoteFilePickerSuggestionEngine implements FilePickerSuggestionEng
     private readonly debounceMs: number = DEBOUNCE_MS
   ) {}
 
-  /** The invalidation hook: `picker_invalidate` from the server lands here. */
   public refreshRelative(): Promise<void> {
     this.cache.clear();
     return Promise.resolve();

package/packages/core/src/picker/catalog.ts

@@ -122,14 +122,13 @@ async function runLoadRelative(
   options: LoadRelativeOptions
 ): Promise<readonly FileCandidate[]> {
   const spawner = options.gitSpawner ?? defaultGitSpawner;
-
-  const fastPath = await tryGitListFiles(root, spawner);
-  if (fastPath !== undefined) {
-    return finalizeRelative(fastPath);
-  }
-
-  const fallback = await scanWithGlob(root);
-  return finalizeRelative(fallback);
+  const paths =
+    (await tryGitListFiles(root, spawner)) ??
+    (await FileEnumerator.enumerate(root, {
+      includeDotfiles: false,
+      includeIgnored: false,
+    }));
+  return finalizeRelative(paths);
 }
 
 async function tryGitListFiles(
@@ -148,13 +147,6 @@ async function tryGitListFiles(
   return result.stdout.split("\n").filter((line) => line.length > 0);
 }
 
-async function scanWithGlob(root: string): Promise<readonly string[]> {
-  return FileEnumerator.enumerate(root, {
-    includeDotfiles: false,
-    includeIgnored: false,
-  });
-}
-
 function finalizeRelative(paths: readonly string[]): readonly FileCandidate[] {
   const normalized = paths.map(Paths.toForwardSlashes);
 

package/packages/core/src/picker/filePickerWorker.ts

@@ -18,9 +18,7 @@ const refreshRelative = async (id: number, root: string): Promise<void> => {
       ok: true,
     } satisfies FilePickerWorkerResponse);
   } catch (error) {
-    if (cachedRelative === undefined) {
-      cachedRelative = [];
-    }
+    cachedRelative ??= [];
     self.postMessage({
       id,
       type: "refreshRelative",

package/packages/core/src/picker/ranker.ts

@@ -164,7 +164,7 @@ class RelativeRankingIndex {
         substringHits.push(candidate);
       }
 
-      // Only prefix hits may end the scan early: a late prefix must not lose to an earlier substring.
+      // Only prefix hits end the scan, so a late prefix hit still beats substrings.
       if (prefixHits.length >= limitSize) {
         break;
       }

package/packages/core/src/picker/token.ts

@@ -1,15 +1,14 @@
-/** Which picker the caret is sitting in, if any. */
 export type PickerToken = {
   readonly kind: "file" | "command";
   readonly query: string;
-  /** Offset of the sigil itself, so a completion replaces it too. */
+  /** Offset of the sigil. */
   readonly start: number;
 };
 
 export const AT_PREFIX = /(?:^|\s)@(\S*)$/;
 export const SLASH_PREFIX = /(?:^|\s)\/(\S*)$/;
 
-/** Offset of the sigil in a match that also swallows the whitespace before it. */
+/** Skips the leading whitespace the prefix regexes may match. */
 export function sigilOffset(match: RegExpMatchArray): number {
   const matched = match[0] ?? "";
   return (match.index ?? 0) + (/^\s/.test(matched) ? 1 : 0);
@@ -53,7 +52,7 @@ export function tokenKey(token: PickerToken | undefined): string {
 export type Completion = {
   readonly text: string;
   readonly caret: number;
-  /** A directory keeps the picker open so the next segment can be drilled into. */
+  /** True for a directory, so the next segment can be picked. */
   readonly keepOpen: boolean;
 };
 

package/packages/core/src/session/AgentRuntime.ts

@@ -7,19 +7,16 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { join } from "node:path";
 
-/** One model a session can be switched to, named the way `setModel` takes it. */
 export type ModelChoice = {
+  /** `provider/id`, as `setModel` takes it. */
   readonly id: string;
   readonly label: string;
-  /** Who serves it, for a client that groups or tags the catalogue. */
   readonly provider: string;
 };
 
 /**
- * Pi's installation as one process sees it: a single `ModelRuntime` over a
- * single `auth.json`, and one `SettingsManager` per cwd. Every surface in a
- * process shares one of these — two runtimes over one auth file race each
- * other's token refresh.
+ * One `ModelRuntime` per process, shared by every surface: two runtimes over
+ * one `auth.json` race each other's token refresh.
  */
 export class AgentRuntime {
   public readonly agentDir: string;
@@ -32,7 +29,7 @@ export class AgentRuntime {
     this.agentDir = agentDir ?? getAgentDir();
   }
 
-  /** Idempotent, and shared by every caller: the second surface to ask waits on the first. */
+  /** Idempotent; concurrent callers share one boot. A failed boot can be retried. */
   public init(): Promise<void> {
     this.booting ??= this.bootstrap().catch((err: unknown) => {
       this.booting = undefined;
@@ -49,7 +46,7 @@ export class AgentRuntime {
     return this.required(this.registry);
   }
 
-  /** Every model this machine has credentials for, qualified as `setModel` takes them. */
+  /** Models with credentials available. */
   public models(): readonly ModelChoice[] {
     return this.modelRegistry.getAvailable().map((model: Model<ModelApi>) => ({
       id: `${model.provider}/${model.id}`,

package/packages/core/src/session/EventLog.ts

@@ -18,7 +18,7 @@ async function ifPresent<T>(read: () => Promise<T>, absent: T): Promise<T> {
   }
 }
 
-/** One durable line of a session file; the header is line 1, so entries start at `seq` 2. */
+/** `seq` is the 1-based line number; the header is line 1. */
 export type LoggedEntry = {
   readonly seq: number;
   readonly entry: FileEntry;
@@ -40,7 +40,7 @@ function isHeader(entry: FileEntry): entry is SessionHeader {
   return entry.type === "session";
 }
 
-/** A reader over one pi session file: append-only JSONL, so a line's `seq` never changes. */
+/** Reader over one append-only pi session file. */
 export class EventLog {
   public readonly path: string;
   private cursor: Cursor = { offset: 0, seq: 0 };
@@ -56,7 +56,7 @@ export class EventLog {
     const file = Bun.file(this.path);
     const text = await ifPresent(() => file.slice(start.offset).text(), "");
 
-    // A trailing fragment is a write in progress: stop short of it or reads lose entries.
+    // Skip a trailing partial line; it is still being written.
     const lastBreak = text.lastIndexOf("\n");
     if (lastBreak === -1) {
       return [];
@@ -92,24 +92,18 @@ export class EventLog {
     return undefined;
   }
 
-  /** The `seq` of the last complete line, without parsing any of them. */
+  /** The `seq` of the last complete line. */
   public async head(): Promise<number> {
     await this.read(Number.MAX_SAFE_INTEGER);
     return this.cursor.seq;
   }
 
-  /**
-   * The name pi's own `/name` writes: the last `session_info` entry wins, and an
-   * empty one clears it. Appended rather than replaced, so it is found by reading
-   * the whole file — the one unbounded read the catalogue makes, and the only
-   * reason `SessionDigest` takes a whole file rather than a bounded head and tail.
-   */
+  /** The last `session_info` name; an empty one clears it. Reads the whole file. */
   public async name(): Promise<string | undefined> {
     const body = await durableBytes(Bun.file(this.path));
     return body === undefined ? undefined : SessionDigest.nameOf(body);
   }
 
-  /** Title and settle time for the catalogue, without opening a session. */
   public async digest(): Promise<SessionDigest> {
     const body = await durableBytes(Bun.file(this.path));
     return body === undefined
@@ -122,7 +116,7 @@ async function* headLines(
   file: BunFile,
   count: number
 ): AsyncGenerator<string> {
-  // Decode with `stream: true`: a chunk boundary can split a character.
+  // `stream: true`: a chunk boundary can split a character.
   const decoder = new TextDecoder();
   let pending = "";
   let yielded = 0;

package/packages/core/src/session/ReadCursors.ts

@@ -22,7 +22,6 @@ export class ReadCursors {
     this.ready = this.load();
   }
 
-  /** Whether a session has been answered since anything last read it. */
   public async isUnread(
     sessionId: string,
     answeredAt: number | undefined
@@ -34,7 +33,7 @@ export class ReadCursors {
     );
   }
 
-  /** Moves a session's cursor forward; the write behind it is not waited on. */
+  /** Only moves forward. Does not wait for the write. */
   public async mark(sessionId: string, at: number = Date.now()): Promise<void> {
     await this.ready;
     if ((this.cursors.get(sessionId) ?? this.baseline) >= at) {
@@ -58,7 +57,7 @@ export class ReadCursors {
     }
   }
 
-  /** Settles the writes behind the marks taken so far, for a clean stop. */
+  /** Waits for pending writes. */
   public async flush(): Promise<void> {
     await this.ready;
     await this.writes.run(async () => undefined);
@@ -69,7 +68,7 @@ export class ReadCursors {
       .json()
       .catch(() => undefined)) as Partial<Stored> | undefined;
     if (typeof stored?.baseline !== "number") {
-      // Persist the baseline now: recomputing it on each start clears every unread session.
+      // Persist it, or every restart would mark everything read.
       this.baseline = Date.now();
       this.persist();
       return;