pim-agent 0.0.1 → 0.10.0

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

@@ -0,0 +1,221 @@
+import { join } from "node:path";
+
+import { FileWatch } from "./FileWatch";
+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.
+ */
+export type GitRun<T = never> = GitOutcome & { readonly value?: T };
+
+export type GitMonitorDeps = {
+  /** How long a fetch stands before another is worth its round trip. */
+  readonly fetchTtlMs?: number;
+  /** How often a watched repository is read for the edits `.git` never hears about. */
+  readonly pollMs?: number;
+  readonly status?: (cwd: string) => Promise<GitState>;
+  readonly fetch?: (cwd: string) => Promise<GitOutcome>;
+};
+
+type Entry = {
+  readonly cwd: string;
+  readonly listeners: Set<GitListener>;
+  state: GitState;
+  stop: (() => void) | undefined;
+  inFlight: Promise<GitState> | undefined;
+  pending: boolean;
+  fetchedAt: number;
+  locked: boolean;
+  /** How long the last read took, and when it ended: what the poll paces itself by. */
+  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. */
+const BACKOFF = 4;
+
+function same(a: GitState, b: GitState): boolean {
+  return (
+    a.branch === b.branch &&
+    a.dirtyCount === b.dirtyCount &&
+    a.ahead === b.ahead &&
+    a.behind === b.behind &&
+    a.revision === b.revision
+  );
+}
+
+/**
+ * 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.
+ */
+export class GitMonitor {
+  private readonly entries = new Map<string, Entry>();
+  private readonly deps: GitMonitorDeps;
+
+  public constructor(deps: GitMonitorDeps = {}) {
+    this.deps = deps;
+  }
+
+  /** Follows `cwd` until the returned stop is called; the listener hears only changes, after a read of its own. */
+  public watch(cwd: string, listener: GitListener): () => void {
+    const entry = this.entryOf(cwd);
+    entry.listeners.add(listener);
+    entry.stop ??= this.follow(entry);
+    void this.read(entry, false);
+    return () => {
+      entry.listeners.delete(listener);
+      if (entry.listeners.size === 0) {
+        entry.stop?.();
+        entry.stop = undefined;
+      }
+    };
+  }
+
+  /** The last state read, without waiting: a caller painting a frame takes what is known now. */
+  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. */
+  public async refresh(
+    cwd: string,
+    options: { readonly fetch?: boolean } = {}
+  ): Promise<GitState> {
+    const entry = this.entryOf(cwd);
+    const ttl = this.deps.fetchTtlMs ?? FETCH_TTL_MS;
+    if (
+      options.fetch === true &&
+      !entry.locked &&
+      Date.now() - entry.fetchedAt > ttl
+    ) {
+      entry.fetchedAt = Date.now();
+      await (this.deps.fetch ?? Git.fetch)(cwd).catch(() => undefined);
+    }
+    return await this.read(entry);
+  }
+
+  /** Runs one writing operation over `cwd`, refusing a second while it lasts and re-reading once it ends. */
+  public async run<T = never>(
+    cwd: string,
+    operation: () => Promise<GitRun<T>>
+  ): Promise<GitRun<T>> {
+    const entry = this.entryOf(cwd);
+    if (entry.locked) {
+      return {
+        ok: false,
+        error: "another git operation is already running in this directory",
+      };
+    }
+    entry.locked = true;
+    try {
+      return await operation();
+    } finally {
+      entry.locked = false;
+      await this.read(entry);
+    }
+  }
+
+  public dispose(): void {
+    for (const entry of this.entries.values()) {
+      entry.stop?.();
+    }
+    this.entries.clear();
+  }
+
+  private entryOf(cwd: string): Entry {
+    const found = this.entries.get(cwd);
+    if (found) {
+      return found;
+    }
+    const entry: Entry = {
+      cwd,
+      listeners: new Set(),
+      state: Git.EMPTY,
+      stop: undefined,
+      inFlight: undefined,
+      pending: false,
+      fetchedAt: 0,
+      locked: false,
+      readMs: 0,
+      readAt: 0,
+    };
+    this.entries.set(cwd, entry);
+    return entry;
+  }
+
+  private follow(entry: Entry): () => void {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const stop = FileWatch.directory(join(entry.cwd, ".git"), () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        void this.read(entry);
+      }, 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.
+    const poll = setInterval(() => {
+      if (Date.now() - entry.readAt < entry.readMs * BACKOFF) {
+        return;
+      }
+      void this.read(entry, false);
+    }, this.deps.pollMs ?? POLL_MS);
+    poll.unref?.();
+    return () => {
+      clearTimeout(timer);
+      clearInterval(poll);
+      stop();
+    };
+  }
+
+  /** `restart` re-reads behind a read already running: a change cannot be answered by a read that predates it, a new subscriber can. */
+  private read(entry: Entry, restart = true): Promise<GitState> {
+    if (entry.inFlight) {
+      entry.pending ||= restart;
+      return entry.inFlight;
+    }
+    const run = (async (): Promise<GitState> => {
+      const started = Date.now();
+      try {
+        let next = entry.state;
+        do {
+          entry.pending = false;
+          next = await (this.deps.status ?? Git.fetchStatus)(entry.cwd);
+        } while (entry.pending);
+        this.settle(entry, next);
+        return next;
+      } catch {
+        return entry.state;
+      } finally {
+        entry.inFlight = undefined;
+        entry.readAt = Date.now();
+        entry.readMs = entry.readAt - started;
+      }
+    })();
+    entry.inFlight = run;
+    return run;
+  }
+
+  private settle(entry: Entry, next: GitState): void {
+    if (same(entry.state, next)) {
+      return;
+    }
+    entry.state = next;
+    for (const listener of entry.listeners) {
+      listener(next);
+    }
+  }
+}

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

@@ -0,0 +1,13 @@
+function compile(exclude: readonly string[] | undefined): readonly Bun.Glob[] {
+  return (exclude ?? []).map((pattern) => new Bun.Glob(pattern));
+}
+
+function ignores(globs: readonly Bun.Glob[], relativePath: string): boolean {
+  if (globs.length === 0) {
+    return false;
+  }
+
+  return globs.some((glob) => glob.match(relativePath));
+}
+
+export const GlobExclusions = { compile, ignores };

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

@@ -0,0 +1,14 @@
+import ky, { type KyInstance } from "ky";
+
+export type HttpFetch = (
+  input: Parameters<typeof fetch>[0],
+  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. */
+export function createKy(custom?: HttpFetch): KyInstance {
+  return ky.create({
+    retry: 0,
+    ...(custom === undefined ? {} : { fetch: custom as typeof fetch }),
+  });
+}

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

@@ -0,0 +1,36 @@
+/** The formats every provider we target accepts. */
+export type ImageMimeType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif"
+  | "image/webp";
+
+const EXTENSIONS = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+} satisfies Record<ImageMimeType, string>;
+
+/** Both spellings of every format, so `.jpeg` names a picture as surely as `.jpg`. */
+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];
+}
+
+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. */
+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. */
+export const ImageMime = { extensionOf, isSupported, namesExtension };

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

@@ -0,0 +1,357 @@
+import {
+  type AgentToolResult,
+  resizeImage,
+} from "@earendil-works/pi-coding-agent";
+import { extname } from "node:path";
+import { Format } from "./Format";
+import { ImageMime, type ImageMimeType } from "./ImageMime";
+import { Lines } from "./Lines";
+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. */
+  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. */
+  readonly originalMimeType: ImageMimeType;
+  readonly resized: boolean;
+  /** Frames in the source container, 1 for a still: the encoded copy holds 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. */
+export type ImageDetails = {
+  readonly sha256: string;
+  readonly mimeType: ImageMimeType;
+  readonly width: number;
+  readonly height: number;
+  readonly bytes: number;
+  readonly resized: boolean;
+  readonly frames: number;
+};
+
+type ToolContent = AgentToolResult<unknown>["content"];
+
+/** Never decode past this: a mislabelled video is rejected on its size alone. */
+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. */
+const SNIFF_BYTES = 12;
+
+const CACHE_PREFIX = "img-";
+
+const PNG = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+const JPEG = [0xff, 0xd8, 0xff];
+const GIF = [0x47, 0x49, 0x46, 0x38];
+const RIFF = [0x52, 0x49, 0x46, 0x46];
+const WEBP = [0x57, 0x45, 0x42, 0x50];
+const ZIP = [0x50, 0x4b, 0x03, 0x04];
+const PDF = [0x25, 0x50, 0x44, 0x46, 0x2d];
+const ANMF = [0x41, 0x4e, 0x4d, 0x46];
+const ACTL = [0x61, 0x63, 0x54, 0x4c];
+const IDAT = [0x49, 0x44, 0x41, 0x54];
+
+const GIF_EXTENSION = 0x21;
+const GIF_IMAGE_DESCRIPTOR = 0x2c;
+
+function startsWith(
+  bytes: Uint8Array,
+  signature: readonly number[],
+  offset = 0
+): boolean {
+  return signature.every((byte, index) => bytes[offset + index] === byte);
+}
+
+/** Magic bytes only: an extension is a claim, not evidence. */
+function sniff(bytes: Uint8Array): ImageMimeType | null {
+  if (startsWith(bytes, PNG)) {
+    return "image/png";
+  }
+  if (startsWith(bytes, JPEG)) {
+    return "image/jpeg";
+  }
+  if (startsWith(bytes, GIF)) {
+    return "image/gif";
+  }
+  if (startsWith(bytes, RIFF) && startsWith(bytes, WEBP, 8)) {
+    return "image/webp";
+  }
+  return null;
+}
+
+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. */
+function webpFrames(bytes: Uint8Array): number {
+  const reader = view(bytes);
+  let count = 0;
+  let at = 12;
+  while (at + 8 <= bytes.byteLength) {
+    const size = reader.getUint32(at + 4, true);
+    if (startsWith(bytes, ANMF, at)) {
+      count += 1;
+    }
+    at += 8 + size + (size % 2);
+  }
+  return count;
+}
+
+/** `acTL` carries the count outright, and must appear before the first `IDAT`. */
+function apngFrames(bytes: Uint8Array): number {
+  const reader = view(bytes);
+  let at = 8;
+  while (at + 12 <= bytes.byteLength) {
+    if (startsWith(bytes, ACTL, at + 4)) {
+      return reader.getUint32(at + 8);
+    }
+    if (startsWith(bytes, IDAT, at + 4)) {
+      return 1;
+    }
+    at += 12 + reader.getUint32(at);
+  }
+  return 1;
+}
+
+function gifFrames(bytes: Uint8Array): number {
+  let at = 13 + colourTableBytes(bytes[10] ?? 0);
+  let count = 0;
+  while (at < bytes.byteLength) {
+    if (bytes[at] === GIF_IMAGE_DESCRIPTOR) {
+      count += 1;
+      at = subBlocksEnd(bytes, at + 11 + colourTableBytes(bytes[at + 9] ?? 0));
+    } else if (bytes[at] === GIF_EXTENSION) {
+      at = subBlocksEnd(bytes, at + 2);
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+function colourTableBytes(packed: number): number {
+  return (packed & 0x80) === 0 ? 0 : 3 * 2 ** ((packed & 0x07) + 1);
+}
+
+function subBlocksEnd(bytes: Uint8Array, from: number): number {
+  let at = from;
+  while (at < bytes.byteLength) {
+    const size = bytes[at] ?? 0;
+    if (size === 0) {
+      return at + 1;
+    }
+    at += 1 + size;
+  }
+  return bytes.byteLength;
+}
+
+const FRAME_READERS: Partial<
+  Record<ImageMimeType, (bytes: Uint8Array) => number>
+> = {
+  "image/webp": webpFrames,
+  "image/png": apngFrames,
+  "image/gif": gifFrames,
+};
+
+/** Headers only: the count has to be read before the resize, which keeps frame 1 alone. */
+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. */
+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. */
+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. */
+function assertWithinSourceCap(byteLength: number, path: string): void {
+  if (byteLength > MAX_SOURCE_BYTES) {
+    throw new Error(
+      `Image is ${Format.bytes(byteLength)}, over the ${Format.bytes(MAX_SOURCE_BYTES)} read cap. Shrink it first: magick ${path} -resize ${MAX_EDGE}x${MAX_EDGE} /tmp/small.png`
+    );
+  }
+}
+
+async function normalise(
+  bytes: Uint8Array,
+  path: string
+): Promise<NormalisedImage> {
+  assertWithinSourceCap(bytes.byteLength, path);
+
+  const sniffed = sniff(bytes);
+  if (sniffed === null) {
+    throw new Error(
+      `File has an image extension but its content is not a valid PNG/JPEG/GIF/WebP. Detected: ${describe(bytes)}. This usually means a download saved an error page instead of the image. Use bash: file ${path}`
+    );
+  }
+
+  const resized = await resizeImage(bytes, sniffed, {
+    maxWidth: MAX_EDGE,
+    maxHeight: MAX_EDGE,
+    maxBytes: MAX_ENCODED_BYTES,
+  });
+  if (resized === null) {
+    throw new Error(
+      `Could not shrink ${path} (${Format.bytes(bytes.byteLength)}) under the ${Format.bytes(MAX_ENCODED_BYTES)} provider limit. Re-save it smaller: magick ${path} -resize ${MAX_EDGE}x${MAX_EDGE} -quality 80 /tmp/small.jpg`
+    );
+  }
+
+  // An unresized encode is the input re-spelled: decoding it back would copy the bytes twice.
+  const data = resized.wasResized ? Buffer.from(resized.data, "base64") : bytes;
+  const mimeType = ImageMime.isSupported(resized.mimeType)
+    ? resized.mimeType
+    : sniffed;
+  const sha256 = Bun.SHA256.hash(data, "hex");
+
+  return {
+    base64: resized.data,
+    mimeType,
+    width: resized.width,
+    height: resized.height,
+    bytes: data.byteLength,
+    originalWidth: resized.originalWidth,
+    originalHeight: resized.originalHeight,
+    originalMimeType: sniffed,
+    resized:
+      resized.width !== resized.originalWidth ||
+      resized.height !== resized.originalHeight,
+    frames: frames(bytes, sniffed),
+    sha256,
+    cachePath: await SpillCache.writeNamed(cacheName(sha256, mimeType), data),
+  };
+}
+
+/** The record of the picture a tool hands its view, off the picture itself. */
+function detailsOf(image: NormalisedImage): ImageDetails {
+  return {
+    sha256: image.sha256,
+    mimeType: image.mimeType,
+    width: image.width,
+    height: image.height,
+    bytes: image.bytes,
+    resized: image.resized,
+    frames: image.frames,
+  };
+}
+
+/** Text first, the way pi's own read orders it. */
+function contentOf(image: NormalisedImage, note?: string): ToolContent {
+  const picture = {
+    type: "image" as const,
+    data: image.base64,
+    mimeType: image.mimeType,
+  };
+  return note === undefined
+    ? [picture]
+    : [{ 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;
+  }
+  const scale = (image.originalWidth / image.width).toFixed(2);
+  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.
+ */
+function animationNote(image: NormalisedImage): string | undefined {
+  if (image.frames < 2) {
+    return 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
+  );
+  return notes.length === 0 ? undefined : notes.join(" ");
+}
+
+/** What the bytes are instead, in the words a person would use to go find them. */
+function describe(bytes: Uint8Array): string {
+  if (bytes.length === 0) {
+    return "an empty file";
+  }
+  if (startsWith(bytes, PDF)) {
+    return "PDF document";
+  }
+  if (startsWith(bytes, ZIP)) {
+    return "ZIP archive (.pptx/.docx/.xlsx are ZIPs)";
+  }
+
+  const head = new TextDecoder().decode(bytes.subarray(0, 512)).trimStart();
+  if (/^<(?:!doctype html|html|head|body)\b/i.test(head)) {
+    return "HTML document";
+  }
+  if (!Lines.isBinaryBytes(bytes)) {
+    return "JSON or text";
+  }
+  return `unrecognized bytes (hex: ${hex(bytes)})`;
+}
+
+function hex(bytes: Uint8Array): string {
+  return Array.from(bytes.subarray(0, 8), (byte) =>
+    byte.toString(16).padStart(2, "0")
+  ).join(" ");
+}
+
+export const Images = {
+  MAX_SOURCE_BYTES,
+  SNIFF_BYTES,
+  CACHE_PREFIX,
+  sniff,
+  frames,
+  isSupported: ImageMime.isSupported,
+  canSee,
+  noVisionNote,
+  extensionOf: ImageMime.extensionOf,
+  looksLikeImageName,
+  assertWithinSourceCap,
+  normalise,
+  detailsOf,
+  contentOf,
+  noteOf,
+  cacheName,
+};

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

@@ -0,0 +1,19 @@
+function asRecord(
+  value: unknown
+): Readonly<Record<string, unknown>> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return undefined;
+  }
+
+  return value as Readonly<Record<string, unknown>>;
+}
+
+function tryParseJson(text: string): unknown | undefined {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+export const Json = { asRecord, tryParseJson };