pim-agent 0.13.0 → 0.14.0

package/packages/core/src/shared/FuzzyMatcher.ts

@@ -43,27 +43,26 @@ function prepare<T>(candidates: readonly FuzzyCandidate<T>[]): FuzzyIndex<T> {
   return {
     find: (query, options = {}) => {
       const trimmed = query.trim();
-      const limit = options.limit ?? Infinity;
       if (trimmed.length === 0) {
-        if (emptyHits === undefined) {
-          emptyHits = [...candidates]
-            .sort((a, b) =>
-              (a.haystacks[0] ?? "").localeCompare(b.haystacks[0] ?? "")
-            )
-            .map((candidate) => ({
-              item: candidate.item,
-              score: 0,
-              positions: new Set<number>(),
-            }));
-        }
-        return limit === Infinity ? emptyHits : emptyHits.slice(0, limit);
+        emptyHits ??= [...candidates]
+          .sort((a, b) =>
+            (a.haystacks[0] ?? "").localeCompare(b.haystacks[0] ?? "")
+          )
+          .map((candidate) => ({
+            item: candidate.item,
+            score: 0,
+            positions: new Set<number>(),
+          }));
+        return emptyHits.slice(0, options.limit);
       }
-      const hits = fzf.find(trimmed).map((result) => ({
-        item: result.item.item,
-        score: result.score,
-        positions: result.positions,
-      }));
-      return limit === Infinity ? hits : hits.slice(0, limit);
+      return fzf
+        .find(trimmed)
+        .slice(0, options.limit)
+        .map((result) => ({
+          item: result.item.item,
+          score: result.score,
+          positions: result.positions,
+        }));
     },
   };
 }

package/packages/core/src/shared/Git.ts

@@ -6,32 +6,26 @@ import { Proc, type ProcOptions, type ProcResult } from "./Proc";
 
 export type GitState = {
   readonly branch: string | null;
-  /** Paths `git status` lists as changed; zero is a clean tree. */
   readonly dirtyCount: number;
   readonly ahead: number;
   readonly behind: number;
-  /**
-   * Changes whenever the repository's content does: the commit at head, every
-   * path git calls changed, and what each of those paths now holds. A count
-   * cannot see an edit to a file already dirty; this can.
-   */
+  /** Hash of HEAD, the changed paths and their stats; also moves when an already-dirty file is edited again. */
   readonly revision: string;
 };
 
-/** One local branch, as `listBranches` ranks and labels it. */
 export type GitBranch = {
   readonly name: string;
   readonly current: boolean;
-  /** The branch `origin/HEAD` points at, or the first of `main`/`master`/`trunk` that exists. */
+  /** `origin/HEAD`'s target, else the first of `main`/`master`/`trunk` that exists. */
   readonly isDefault: boolean;
-  /** Its last commit, in epoch seconds. */
+  /** Last commit time, epoch seconds. */
   readonly updatedAt: number;
   readonly ahead: number;
   readonly behind: number;
-  /** It tracked a remote branch that has since been deleted, so its work has usually landed. */
+  /** Its upstream branch was deleted. */
   readonly gone: boolean;
   readonly merged: boolean;
-  /** Checked out in another worktree, where git will refuse to take it from. */
+  /** Checked out in another worktree. */
   readonly worktree: boolean;
 };
 
@@ -41,7 +35,7 @@ export type GitOutcome =
 
 export type CommitRequest = {
   readonly message: string;
-  /** Exactly what is committed; a rename contributes both of its names. */
+  /** Exactly what is committed; a rename lists both names. */
   readonly paths: readonly string[];
 };
 
@@ -81,7 +75,7 @@ const COMMIT_TIMEOUT_MS = 120_000;
 
 const ERROR_LIMIT = 400;
 
-/** No surface behind a daemon can answer a credential prompt, so every network call must fail instead of waiting on one. */
+/** Fail instead of waiting on a credential prompt nobody can answer. */
 const NETWORK_ENV: Readonly<Record<string, string | undefined>> = {
   GIT_TERMINAL_PROMPT: "0",
   GIT_ASKPASS: undefined,
@@ -90,7 +84,7 @@ const NETWORK_ENV: Readonly<Record<string, string | undefined>> = {
   GIT_SSH_COMMAND: process.env.GIT_SSH_COMMAND ?? "ssh -o BatchMode=yes",
 };
 
-/** A commit runs hooks and may sign, neither of which may open an editor on a machine nobody is sitting at. */
+/** Hooks and signing must never open an editor. */
 const COMMIT_OPTIONS: ProcOptions = {
   env: { GIT_EDITOR: "true" },
   timeoutMs: COMMIT_TIMEOUT_MS,
@@ -109,17 +103,13 @@ function git(
 }
 
 function network(cwd: string, args: readonly string[]): Promise<ProcResult> {
-  return Proc.run(["git", ...args], {
-    cwd,
-    env: NETWORK_ENV,
-    timeoutMs: NETWORK_TIMEOUT_MS,
-  });
+  return git(cwd, args, { env: NETWORK_ENV, timeoutMs: NETWORK_TIMEOUT_MS });
 }
 
-/** Which field of a porcelain-v2 entry holds the path it is about. */
+/** Index of the path field in each porcelain-v2 entry type. */
 const PATH_FIELD: Readonly<Record<string, number>> = { "1": 8, "2": 9, u: 10 };
 
-/** Beyond this many changed paths the count alone stands for the worktree. */
+/** Only the first this-many changed paths are stat'd into the revision. */
 const SAMPLE_LIMIT = 500;
 
 function pathOf(line: string): string {
@@ -135,7 +125,6 @@ function pathOf(line: string): string {
   return line.split(" ").slice(field).join(" ").split("\t")[0] ?? "";
 }
 
-/** What a changed path holds now, cheaply enough to read on every poll. */
 function worktreeSample(cwd: string): (path: string) => string {
   return (path) => {
     const stats = statSync(join(cwd, path), { throwIfNoEntry: false });
@@ -205,7 +194,6 @@ function parseTrack(text: string): {
   };
 }
 
-/** What one `for-each-ref` line says; `rank` adds the two facts that need the whole list. */
 type Ref = Omit<GitBranch, "isDefault" | "merged">;
 
 function parseRefs(text: string): readonly Ref[] {
@@ -228,7 +216,7 @@ function parseRefs(text: string): readonly Ref[] {
 
 const MOVING = "checkout: moving from ";
 
-/** When each branch was last checked out, newest first, so a branch worked on without committing still ranks. */
+/** Last checkout time per branch, from the reflog. */
 function parseVisits(text: string): ReadonlyMap<string, number> {
   const visits = new Map<string, number>();
   for (const line of Lines.split(text)) {
@@ -285,7 +273,7 @@ async function remoteOf(cwd: string): Promise<string | undefined> {
   return remotes.length === 1 ? remotes[0] : undefined;
 }
 
-/** What the remote calls its trunk; absent when no remote names one. */
+/** The remote's default branch, if it names one. */
 async function remoteHead(cwd: string): Promise<string | undefined> {
   const remote = await remoteOf(cwd);
   if (remote === undefined) {
@@ -315,7 +303,7 @@ async function mergedInto(
   return new Set(code === 0 ? Lines.split(stdout) : []);
 }
 
-/** Every local branch, trunk first and the rest by the last time they were committed to or checked out. */
+/** Local branches: default first, then by last commit or checkout. */
 async function listBranches(cwd: string): Promise<readonly GitBranch[]> {
   const [refs, log, remote] = await Promise.all([
     git(cwd, ["for-each-ref", "--format", BRANCH_FORMAT, "refs/heads/"]),
@@ -337,10 +325,7 @@ async function listBranches(cwd: string): Promise<readonly GitBranch[]> {
   );
 }
 
-/**
- * What a failed `git` said, in one line: its own words where it had any, the
- * caller's fallback where it had none, and the timeout where it never answered.
- */
+/** git's own error text, else `fallback`, or `timeout` when it timed out. */
 function failure(
   result: ProcResult,
   fallback: string,
@@ -369,16 +354,12 @@ async function checkout(cwd: string, branch: string): Promise<GitOutcome> {
   );
 }
 
-/** A path git is allowed to be pointed at: inside the repository, and named relative to it. */
+/** True for an empty, absolute or `..` path. */
 function escapes(path: string): boolean {
   return path === "" || isAbsolute(path) || path.split(/[/\\]/).includes("..");
 }
 
-/**
- * Commits exactly `paths` and nothing else: everything else changed stays
- * dirty, and an unrelated path someone had staged stays staged. Untracked
- * paths are added first, or a path-limited commit of one finds no such file.
- */
+/** Commits exactly `paths`; other changes, staged or not, are left alone. */
 async function commit(
   cwd: string,
   request: CommitRequest
@@ -397,13 +378,8 @@ async function commit(
       error: `${outside === "" ? "an empty path" : outside} is not a path inside this repository`,
     };
   }
-  /**
-   * `git add` refuses a pathspec that matches nothing on disk, and a staged
-   * rename's old name matches nothing: it is gone from both the worktree and
-   * the index. A deletion is the same. `git commit -- <paths>` reads those two
-   * off HEAD and the index by itself, so only the paths still on disk are
-   * worth adding, and a pick made entirely of them needs no `add` at all.
-   */
+  // Add only paths on disk: `git add` rejects deleted paths and a rename's old
+  // name, and `git commit -- <paths>` handles those itself.
   const onDisk = await Promise.all(
     request.paths.map((path) => Bun.file(join(cwd, path)).exists())
   );
@@ -457,7 +433,7 @@ async function pull(cwd: string): Promise<GitOutcome> {
   );
 }
 
-/** The remote branch HEAD tracks, or undefined when the branch is local-only or HEAD is detached. */
+/** Undefined when the branch has no upstream or HEAD is detached. */
 async function upstreamOf(cwd: string): Promise<string | undefined> {
   const { code, stdout } = await git(cwd, [
     "rev-parse",
@@ -469,7 +445,7 @@ async function upstreamOf(cwd: string): Promise<string | undefined> {
   return code === 0 && name !== "" ? name : undefined;
 }
 
-/** Publishes the branch, adopting the remote as its upstream the first time it is pushed. */
+/** Sets the upstream on the first push. */
 async function push(cwd: string): Promise<GitOutcome> {
   const [head, upstream] = await Promise.all([
     git(cwd, ["symbolic-ref", "--quiet", "--short", "HEAD"]),
@@ -500,7 +476,7 @@ async function push(cwd: string): Promise<GitOutcome> {
 async function fetchStatus(cwd: string): Promise<GitState> {
   try {
     const { code, stdout } = await git(cwd, [
-      // Or the chip's own read takes `index.lock` and fails the checkout beside it.
+      // Avoids taking `index.lock`, which would fail a concurrent checkout.
       "--no-optional-locks",
       "status",
       "--porcelain=v2",
@@ -512,7 +488,6 @@ async function fetchStatus(cwd: string): Promise<GitState> {
   }
 }
 
-/** The cwd's git state, for the TUI footer and the web's branch menu. */
 export const Git = {
   EMPTY,
   parseStatus,

package/packages/core/src/shared/GitMonitor.ts

@@ -5,16 +5,13 @@ import { Git, type GitOutcome, type GitState } from "./Git";
 
 export type GitListener = (state: GitState) => void;
 
-/**
- * What one operation under the lock says, and what it made where it made
- * anything: a commit has a sha to hand back, a checkout has only its outcome.
- */
+/** `value` carries an operation's result, e.g. a commit's sha. */
 export type GitRun<T = never> = GitOutcome & { readonly value?: T };
 
 export type GitMonitorDeps = {
-  /** How long a fetch stands before another is worth its round trip. */
+  /** Minimum gap between fetches. Defaults to 30s. */
   readonly fetchTtlMs?: number;
-  /** How often a watched repository is read for the edits `.git` never hears about. */
+  /** Poll for worktree edits, which `.git` never sees. Defaults to 2s. */
   readonly pollMs?: number;
   readonly status?: (cwd: string) => Promise<GitState>;
   readonly fetch?: (cwd: string) => Promise<GitOutcome>;
@@ -29,20 +26,18 @@ type Entry = {
   pending: boolean;
   fetchedAt: number;
   locked: boolean;
-  /** How long the last read took, and when it ended: what the poll paces itself by. */
+  /** Duration and end time of the last read; the poll backs off by these. */
   readMs: number;
   readAt: number;
 };
 
-/** A checkout writes half the repository; one read has to stand for the burst. */
 const DEBOUNCE_MS = 200;
 
 const FETCH_TTL_MS = 30_000;
 
-/** A worktree edit touches nothing under `.git`, so the watch alone would never see it. */
 const POLL_MS = 2_000;
 
-/** A repository too big to read in a tick is read this many times its own cost apart. */
+/** A slow repository is polled at most once per this many read durations. */
 const BACKOFF = 4;
 
 function same(a: GitState, b: GitState): boolean {
@@ -55,12 +50,7 @@ function same(a: GitState, b: GitState): boolean {
   );
 }
 
-/**
- * One reader of one repository, however many sessions share it: it watches
- * `.git` so a commit anywhere reaches every surface, coalesces the burst a
- * checkout makes into a single read, and serialises the operations that write,
- * which cannot run two at a time over one index.
- */
+/** One shared reader per repository: watches `.git`, debounces reads, and allows one writing operation at a time. */
 export class GitMonitor {
   private readonly entries = new Map<string, Entry>();
   private readonly deps: GitMonitorDeps;
@@ -69,7 +59,7 @@ export class GitMonitor {
     this.deps = deps;
   }
 
-  /** Follows `cwd` until the returned stop is called; the listener hears only changes, after a read of its own. */
+  /** The listener hears only changes. */
   public watch(cwd: string, listener: GitListener): () => void {
     const entry = this.entryOf(cwd);
     entry.listeners.add(listener);
@@ -84,12 +74,12 @@ export class GitMonitor {
     };
   }
 
-  /** The last state read, without waiting: a caller painting a frame takes what is known now. */
+  /** The last state read; never waits. */
   public stateOf(cwd: string): GitState {
     return this.entries.get(cwd)?.state ?? Git.EMPTY;
   }
 
-  /** Re-reads now; `fetch` also asks the remote, which is what ahead and behind are counted against. */
+  /** `fetch` also fetches the remote first, at most once per TTL. */
   public async refresh(
     cwd: string,
     options: { readonly fetch?: boolean } = {}
@@ -107,7 +97,7 @@ export class GitMonitor {
     return await this.read(entry);
   }
 
-  /** Runs one writing operation over `cwd`, refusing a second while it lasts and re-reading once it ends. */
+  /** Refuses while another operation runs on `cwd`; re-reads after. */
   public async run<T = never>(
     cwd: string,
     operation: () => Promise<GitRun<T>>
@@ -165,8 +155,7 @@ export class GitMonitor {
       }, DEBOUNCE_MS);
       timer.unref?.();
     });
-    // `false`: a read already running is fresh enough for a tick, and a slow
-    // status must never queue another behind itself.
+    // `false`: a tick must not queue a read behind a slow one.
     const poll = setInterval(() => {
       if (Date.now() - entry.readAt < entry.readMs * BACKOFF) {
         return;
@@ -181,7 +170,7 @@ export class GitMonitor {
     };
   }
 
-  /** `restart` re-reads behind a read already running: a change cannot be answered by a read that predates it, a new subscriber can. */
+  /** `restart` re-reads after an in-flight read, which may predate the change. */
   private read(entry: Entry, restart = true): Promise<GitState> {
     if (entry.inFlight) {
       entry.pending ||= restart;

package/packages/core/src/shared/GlobExclusions.ts

@@ -3,10 +3,6 @@ function compile(exclude: readonly string[] | undefined): readonly Bun.Glob[] {
 }
 
 function ignores(globs: readonly Bun.Glob[], relativePath: string): boolean {
-  if (globs.length === 0) {
-    return false;
-  }
-
   return globs.some((glob) => glob.match(relativePath));
 }
 

package/packages/core/src/shared/Http.ts

@@ -5,7 +5,7 @@ export type HttpFetch = (
   init?: Parameters<typeof fetch>[1]
 ) => ReturnType<typeof fetch>;
 
-/** Ky with retries off: its defaults retry GETs twice and honour `Retry-After` uncapped, stalling a tool for hours. */
+/** Retries off: ky's default honours `Retry-After` uncapped and can stall a tool for hours. */
 export function createKy(custom?: HttpFetch): KyInstance {
   return ky.create({
     retry: 0,

package/packages/core/src/shared/ImageMime.ts

@@ -1,4 +1,3 @@
-/** The formats every provider we target accepts. */
 export type ImageMimeType =
   | "image/png"
   | "image/jpeg"
@@ -12,13 +11,12 @@ const EXTENSIONS = {
   "image/webp": "webp",
 } satisfies Record<ImageMimeType, string>;
 
-/** Both spellings of every format, so `.jpeg` names a picture as surely as `.jpg`. */
+/** Includes both `jpg` and `jpeg`. */
 const NAME_EXTENSIONS = new Set([
   ...Object.values(EXTENSIONS),
   ...Object.keys(EXTENSIONS).map((mimeType) => mimeType.slice("image/".length)),
 ]);
 
-/** The format as a word, in the one spelling the notes, the UI and the cache filename all use. */
 function extensionOf(mimeType: ImageMimeType): string {
   return EXTENSIONS[mimeType];
 }
@@ -27,10 +25,10 @@ function isSupported(mimeType: string): mimeType is ImageMimeType {
   return Object.hasOwn(EXTENSIONS, mimeType);
 }
 
-/** Whether a bare, lowercased extension is one of the spellings a picture goes by. */
+/** Takes a bare, lowercased extension. */
 function namesExtension(extension: string): boolean {
   return NAME_EXTENSIONS.has(extension);
 }
 
-/** The format table alone, free of Node so the browser can name a picture too. */
+/** Browser-safe: no Node imports. */
 export const ImageMime = { extensionOf, isSupported, namesExtension };

package/packages/core/src/shared/Images.ts

@@ -10,33 +10,31 @@ import { SpillCache } from "./SpillCache";
 
 export type { ImageMimeType };
 
-/** What a tool needs off `ctx.model` to know whether a picture can be sent. */
 export type VisionModel = {
   readonly id: string;
   readonly input: readonly string[];
 };
 
-/** An image the providers will take: within their formats, dimensions and byte budget. */
 export type NormalisedImage = {
   readonly base64: string;
   readonly mimeType: ImageMimeType;
   readonly width: number;
   readonly height: number;
-  /** Encoded size after the resize, which is what the cache holds. */
+  /** Encoded size after the resize. */
   readonly bytes: number;
   readonly originalWidth: number;
   readonly originalHeight: number;
-  /** The container the frames were counted in: a resize is free to re-encode as another. */
+  /** May differ from `mimeType`: a resize can re-encode. */
   readonly originalMimeType: ImageMimeType;
   readonly resized: boolean;
-  /** Frames in the source container, 1 for a still: the encoded copy holds only the first. */
+  /** Frames in the source; the encoded copy keeps only the first. */
   readonly frames: number;
   readonly sha256: string;
   /** `~/.pim/cache/img-<sha256>.<ext>`, or null when the cache write failed. */
   readonly cachePath: string | null;
 };
 
-/** What every tool records about a picture it showed: the picture itself never rides here, `sha256` addresses it in the spill cache. */
+/** No pixel data: `sha256` addresses the picture in the spill cache. */
 export type ImageDetails = {
   readonly sha256: string;
   readonly mimeType: ImageMimeType;
@@ -49,12 +47,12 @@ export type ImageDetails = {
 
 type ToolContent = AgentToolResult<unknown>["content"];
 
-/** Never decode past this: a mislabelled video is rejected on its size alone. */
+/** Larger sources are rejected before decoding. */
 const MAX_SOURCE_BYTES = 25 * 1024 * 1024;
 const MAX_EDGE = 2000;
 const MAX_ENCODED_BYTES = 3_932_160;
 
-/** Enough for every magic-byte signature, WebP's `RIFF….WEBP` included. */
+/** Long enough for every signature, including WebP's `RIFF….WEBP`. */
 const SNIFF_BYTES = 12;
 
 const CACHE_PREFIX = "img-";
@@ -81,7 +79,7 @@ function startsWith(
   return signature.every((byte, index) => bytes[offset + index] === byte);
 }
 
-/** Magic bytes only: an extension is a claim, not evidence. */
+/** By magic bytes, never by extension. */
 function sniff(bytes: Uint8Array): ImageMimeType | null {
   if (startsWith(bytes, PNG)) {
     return "image/png";
@@ -102,7 +100,7 @@ function view(bytes: Uint8Array): DataView {
   return new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
 }
 
-/** RIFF chunks are padded to an even length, so an odd body carries one trailing byte. */
+/** RIFF chunks are padded to an even length. */
 function webpFrames(bytes: Uint8Array): number {
   const reader = view(bytes);
   let count = 0;
@@ -117,7 +115,7 @@ function webpFrames(bytes: Uint8Array): number {
   return count;
 }
 
-/** `acTL` carries the count outright, and must appear before the first `IDAT`. */
+/** `acTL` holds the count and must come before the first `IDAT`. */
 function apngFrames(bytes: Uint8Array): number {
   const reader = view(bytes);
   let at = 8;
@@ -173,32 +171,30 @@ const FRAME_READERS: Partial<
   "image/gif": gifFrames,
 };
 
-/** Headers only: the count has to be read before the resize, which keeps frame 1 alone. */
+/** Read from the source, since the resize keeps only frame 1. */
 function frames(bytes: Uint8Array, mimeType: ImageMimeType): number {
   return Math.max(1, FRAME_READERS[mimeType]?.(bytes) ?? 1);
 }
 
-/** An unknown model is not a blind one: only a model that names its inputs can rule the picture out. */
+/** An unknown model is assumed to see. */
 function canSee(model: VisionModel | undefined): boolean {
   return model === undefined || model.input.includes("image");
 }
 
-/** What a model without eyes is told in place of the picture it cannot be sent. */
 function noVisionNote(tool: string, subject: string): string {
   return `[${tool} tool: ${subject}; the current model has no vision input.]`;
 }
 
-/** A name that claims a picture — a claim the bytes still have to back. */
 function looksLikeImageName(path: string): boolean {
   return ImageMime.namesExtension(extname(path).slice(1).toLowerCase());
 }
 
-/** What the spill cache holds the picture under; the resize picks the extension, never the source path. */
+/** The extension follows the encoded type, not the source path. */
 function cacheName(sha256: string, mimeType: ImageMimeType): string {
   return `${CACHE_PREFIX}${sha256}.${ImageMime.extensionOf(mimeType)}`;
 }
 
-/** Refuse on the stat alone, so a mislabelled video is never pulled into memory. */
+/** Meant for the stat size, so an oversized file is never read. */
 function assertWithinSourceCap(byteLength: number, path: string): void {
   if (byteLength > MAX_SOURCE_BYTES) {
     throw new Error(
@@ -231,7 +227,7 @@ async function normalise(
     );
   }
 
-  // An unresized encode is the input re-spelled: decoding it back would copy the bytes twice.
+  // Unresized output is the input, so skip decoding the base64 back.
   const data = resized.wasResized ? Buffer.from(resized.data, "base64") : bytes;
   const mimeType = ImageMime.isSupported(resized.mimeType)
     ? resized.mimeType
@@ -256,7 +252,6 @@ async function normalise(
   };
 }
 
-/** The record of the picture a tool hands its view, off the picture itself. */
 function detailsOf(image: NormalisedImage): ImageDetails {
   return {
     sha256: image.sha256,
@@ -269,7 +264,7 @@ function detailsOf(image: NormalisedImage): ImageDetails {
   };
 }
 
-/** Text first, the way pi's own read orders it. */
+/** Text first, matching pi's read tool. */
 function contentOf(image: NormalisedImage, note?: string): ToolContent {
   const picture = {
     type: "image" as const,
@@ -281,7 +276,6 @@ function contentOf(image: NormalisedImage, note?: string): ToolContent {
     : [{ type: "text", text: note }, picture];
 }
 
-/** How the model maps coordinates it reads off the picture back onto the file. */
 function resizeNote(image: NormalisedImage): string | undefined {
   if (!image.resized) {
     return undefined;
@@ -290,10 +284,7 @@ function resizeNote(image: NormalisedImage): string | undefined {
   return `image resized from ${image.originalWidth}x${image.originalHeight} to ${image.width}x${image.height}; multiply coordinates by ${scale} to map to the original.`;
 }
 
-/**
- * What the picture leaves out, which a still under every cap says nothing about:
- * providers see one frame, so an unmentioned animation reads as an empty screen.
- */
+/** Providers see only one frame, so say the image is animated. */
 function animationNote(image: NormalisedImage): string | undefined {
   if (image.frames < 2) {
     return undefined;
@@ -301,7 +292,6 @@ function animationNote(image: NormalisedImage): string | undefined {
   return `animated ${ImageMime.extensionOf(image.originalMimeType)}: ${image.frames} frames, ${image.originalWidth}x${image.originalHeight}; frame 1 shown.`;
 }
 
-/** Everything true of the picture that is not in the picture. */
 function noteOf(image: NormalisedImage): string | undefined {
   const notes = [resizeNote(image), animationNote(image)].filter(
     (note) => note !== undefined
@@ -309,7 +299,7 @@ function noteOf(image: NormalisedImage): string | undefined {
   return notes.length === 0 ? undefined : notes.join(" ");
 }
 
-/** What the bytes are instead, in the words a person would use to go find them. */
+/** A human description of non-image bytes. */
 function describe(bytes: Uint8Array): string {
   if (bytes.length === 0) {
     return "an empty file";

package/packages/core/src/shared/Languages.ts

@@ -1,4 +1,4 @@
-// Values are highlight.js language ids; keep this module import-free, the web bundle needs it.
+// Values are highlight.js language ids. Keep import-free: the web bundle uses it.
 
 const ALIASES: Readonly<Record<string, string>> = {
   ts: "typescript",
@@ -77,7 +77,7 @@ const ALIASES: Readonly<Record<string, string>> = {
 
 const CANONICAL: ReadonlySet<string> = new Set(Object.values(ALIASES));
 
-// Never guess a language: auto-detection paints ordinary prose as keywords.
+// Unknown names stay undefined: auto-detection paints prose as code.
 function resolve(name: string | undefined): string | undefined {
   if (name === undefined) {
     return undefined;

package/packages/core/src/shared/Levenshtein.ts

@@ -27,12 +27,7 @@ function distance(left: string, right: string): number {
   return previous[right.length] ?? 0;
 }
 
-/**
- * Damerau–Levenshtein, where a transposition is one edit rather than two, and
- * a pair that cannot reach `max` answers `max + 1` without finishing the
- * matrix — the shape a vocabulary scan wants, since almost every term it asks
- * about is nowhere near.
- */
+/** Damerau–Levenshtein (a transposition is one edit). Returns `max + 1` early once over `max`. */
 function damerau(left: string, right: string, max: number): number {
   const over = max + 1;
   if (left === right) {

package/packages/core/src/shared/Lines.ts

@@ -1,7 +1,7 @@
 const utf8Bom = "\uFEFF";
 const utf8BomBytes = new Uint8Array([0xef, 0xbb, 0xbf]);
 
-/** How far in a NUL is still evidence of a binary file rather than text. */
+/** A NUL within this many leading bytes marks a file as binary. */
 const binarySniffBytes = 8192;
 
 function normalize(content: string): string {

package/packages/core/src/shared/McpClient.ts

@@ -201,9 +201,9 @@ export class McpClient {
 
   private async sendCancellation(
     sessionId: string | undefined,
-    requestId: number | undefined
+    requestId: number
   ): Promise<void> {
-    if (sessionId === undefined || requestId === undefined) {
+    if (sessionId === undefined) {
       return;
     }
 

package/packages/core/src/shared/PatchSummary.ts

@@ -36,5 +36,5 @@ export function cleanPath(raw: string): string {
   return path;
 }
 
-/** Fault-tolerant scan of V4A patch text for renderers; unrecognized lines are ignored. */
+/** Lenient scan of V4A patch text for renderers; unknown lines are ignored. */
 export const PatchSummary = { firstPath };