pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,14 @@
+import { type Static, Type } from "typebox";
+
+export const writeSchema = Type.Object({
+  path: Type.String({
+    description:
+      "Absolute or relative path to file (resolved against cwd). Parent directories are created if missing.",
+  }),
+  content: Type.String({
+    description:
+      "UTF-8 text written verbatim. Include a trailing newline if needed.",
+  }),
+});
+
+export type WriteInput = Static<typeof writeSchema>;

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

@@ -0,0 +1,87 @@
+import { DiffLines, type ToolDiff } from "../../shared/DiffLines";
+import { Fs } from "../../shared/Fs";
+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.
+const MAX_DIFF_BYTES = 2 * 1024 * 1024;
+
+export type WriteOutcome = {
+  readonly bytesWritten: number;
+  readonly created: boolean;
+  readonly diff?: ToolDiff;
+  readonly diffSkipped?: {
+    readonly reason: "size";
+    readonly thresholdBytes: number;
+    readonly comparedBytes: number;
+  };
+  readonly trailingNewlineChange?: "added" | "removed";
+};
+
+export async function writeContent(
+  absolutePath: string,
+  content: string
+): Promise<WriteOutcome> {
+  const prior = await readPriorContent(absolutePath);
+  const bytesWritten = Buffer.byteLength(content, "utf8");
+
+  if (prior === content) {
+    return { bytesWritten, created: false };
+  }
+
+  await Fs.writeAtomic(absolutePath, content);
+
+  const created = prior === undefined;
+  const priorBytes = prior === undefined ? 0 : Buffer.byteLength(prior, "utf8");
+  const comparedBytes = Math.max(priorBytes, bytesWritten);
+  const priorNewline = prior?.endsWith("\n") ?? false;
+  const contentNewline = content.endsWith("\n");
+  const trailingNewlineChange =
+    created || priorNewline === contentNewline
+      ? undefined
+      : contentNewline
+        ? "added"
+        : "removed";
+
+  if (comparedBytes > MAX_DIFF_BYTES) {
+    return {
+      bytesWritten,
+      created,
+      diffSkipped: {
+        reason: "size",
+        thresholdBytes: MAX_DIFF_BYTES,
+        comparedBytes,
+      },
+      ...(trailingNewlineChange === undefined ? {} : { trailingNewlineChange }),
+    };
+  }
+
+  const diff = DiffLines.buildToolDiff(
+    absolutePath,
+    prior === undefined ? DiffLines.emptySide : DiffLines.fromText(prior),
+    DiffLines.fromText(content),
+    CONTEXT_LINES
+  );
+
+  return {
+    bytesWritten,
+    created,
+    ...(diff === undefined ? {} : { diff }),
+    ...(trailingNewlineChange === undefined ? {} : { trailingNewlineChange }),
+  };
+}
+
+async function readPriorContent(
+  absolutePath: string
+): Promise<string | undefined> {
+  try {
+    return await Bun.file(absolutePath).text();
+  } catch (error) {
+    if (FsErrors.code(error) === "ENOENT") {
+      return undefined;
+    }
+
+    throw error;
+  }
+}

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

@@ -0,0 +1,14 @@
+import type { PickerItem } from "./PickerItem";
+
+export type RankFilePickerOptions = {
+  readonly limit?: number;
+  readonly signal?: AbortSignal;
+};
+
+export type FilePickerSuggestionEngine = {
+  readonly refreshRelative: () => Promise<void>;
+  readonly rank: (
+    query: string,
+    options: RankFilePickerOptions
+  ) => Promise<readonly PickerItem[] | undefined>;
+};

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

@@ -0,0 +1,52 @@
+import type { PickerItem } from "./PickerItem";
+import type { FileCandidate } from "./catalog";
+import type {
+  FilePickerSuggestionEngine,
+  RankFilePickerOptions,
+} from "./FilePickerSuggestionEngine";
+import { rank } from "./ranker";
+
+export type InProcessFilePickerSuggestionEngineOptions = {
+  readonly loadRelativeCatalog: () => Promise<readonly FileCandidate[]>;
+};
+
+export class InProcessFilePickerSuggestionEngine implements FilePickerSuggestionEngine {
+  private cachedRelative: readonly FileCandidate[] | undefined;
+  private refresh: Promise<void> | undefined;
+
+  public constructor(
+    private readonly options: InProcessFilePickerSuggestionEngineOptions
+  ) {}
+
+  public refreshRelative(): Promise<void> {
+    this.refresh ??= this.options
+      .loadRelativeCatalog()
+      .then((catalog) => {
+        this.cachedRelative = catalog;
+      })
+      .catch(() => {
+        if (this.cachedRelative === undefined) {
+          this.cachedRelative = [];
+        }
+      })
+      .finally(() => {
+        this.refresh = undefined;
+      });
+
+    return this.refresh;
+  }
+
+  public async rank(
+    query: string,
+    options: RankFilePickerOptions
+  ): Promise<readonly PickerItem[] | undefined> {
+    if (options.signal?.aborted === true) {
+      return [];
+    }
+
+    return rank(query, {
+      cachedRelative: this.cachedRelative,
+      limit: options.limit,
+    });
+  }
+}

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

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

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

@@ -0,0 +1,110 @@
+import { type AgentSession, loadSkills } from "@earendil-works/pi-coding-agent";
+
+import { loadRelative } from "./catalog";
+import { rankCommands } from "./commandRanker";
+import { InProcessFilePickerSuggestionEngine } from "./InProcessFilePickerSuggestionEngine";
+import type { PickerItem } from "./PickerItem";
+
+export type PickerServiceDeps = {
+  /** Read per query: a session's cwd can move between turns. */
+  readonly cwd: () => string;
+  readonly agentDir: string;
+  /** Extension-registered commands, available only while an agent is built. */
+  readonly agent?: () => AgentSession | undefined;
+};
+
+const DEFAULT_LIMIT = 50;
+
+/** Answers one session's picker queries against the machine the agent runs on. */
+export class PickerService {
+  private readonly deps: PickerServiceDeps;
+  private fileCache:
+    | {
+        readonly cwd: string;
+        readonly engine: InProcessFilePickerSuggestionEngine;
+        loaded: boolean;
+      }
+    | undefined;
+  private commandCache:
+    | { readonly cwd: string; readonly items: readonly PickerItem[] }
+    | undefined;
+
+  public constructor(deps: PickerServiceDeps) {
+    this.deps = deps;
+  }
+
+  public async files(
+    query: string,
+    limit = DEFAULT_LIMIT
+  ): Promise<readonly PickerItem[]> {
+    const cache = this.fileEngine();
+    if (!cache.loaded) {
+      await cache.engine.refreshRelative();
+      cache.loaded = true;
+    }
+    return (await cache.engine.rank(query, { limit })) ?? [];
+  }
+
+  public commands(query: string, limit = DEFAULT_LIMIT): readonly PickerItem[] {
+    return rankCommands(query, this.commandItems(), { limit });
+  }
+
+  public invalidate(): void {
+    this.fileCache = undefined;
+    this.commandCache = undefined;
+  }
+
+  private fileEngine(): NonNullable<PickerService["fileCache"]> {
+    const cwd = this.deps.cwd();
+    if (this.fileCache?.cwd !== cwd) {
+      this.fileCache = {
+        cwd,
+        engine: new InProcessFilePickerSuggestionEngine({
+          loadRelativeCatalog: () => loadRelative({ root: cwd }),
+        }),
+        loaded: false,
+      };
+    }
+    return this.fileCache;
+  }
+
+  private commandItems(): readonly PickerItem[] {
+    const cwd = this.deps.cwd();
+    if (this.commandCache?.cwd !== cwd) {
+      this.commandCache = { cwd, items: this.loadSkillItems(cwd) };
+    }
+    return [...this.commandCache.items, ...this.extensionItems()];
+  }
+
+  private loadSkillItems(cwd: string): readonly PickerItem[] {
+    try {
+      const { skills } = loadSkills({
+        cwd,
+        agentDir: this.deps.agentDir,
+        skillPaths: [],
+        includeDefaults: true,
+      });
+      return skills.map((skill) => ({
+        value: `/skill:${skill.name}`,
+        label: `/skill:${skill.name}`,
+        description: skill.description,
+      }));
+    } catch {
+      return [];
+    }
+  }
+
+  private extensionItems(): readonly PickerItem[] {
+    const agent = this.deps.agent?.();
+    if (!agent) {
+      return [];
+    }
+    return agent.extensionRunner.getRegisteredCommands().map((command) => ({
+      value: `/${command.invocationName}`,
+      label: `/${command.invocationName}`,
+      ...(command.description === undefined
+        ? {}
+        : { description: command.description }),
+    }));
+  }
+}

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

@@ -0,0 +1,56 @@
+import type {
+  FilePickerSuggestionEngine,
+  RankFilePickerOptions,
+} from "./FilePickerSuggestionEngine";
+import type { PickerItem } from "./PickerItem";
+
+export type RemotePickerQuery = (
+  query: string,
+  limit: number | undefined
+) => Promise<readonly PickerItem[]>;
+
+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. */
+export class RemoteFilePickerSuggestionEngine implements FilePickerSuggestionEngine {
+  private readonly cache = new Map<string, readonly PickerItem[]>();
+  private generation = 0;
+
+  public constructor(
+    private readonly query: RemotePickerQuery,
+    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();
+  }
+
+  public async rank(
+    query: string,
+    options: RankFilePickerOptions
+  ): Promise<readonly PickerItem[] | undefined> {
+    const key = `${options.limit ?? ""}\u0000${query}`;
+    const cached = this.cache.get(key);
+    if (cached) {
+      return cached;
+    }
+    const mine = ++this.generation;
+    await new Promise((resolve) => setTimeout(resolve, this.debounceMs));
+    if (mine !== this.generation || options.signal?.aborted === true) {
+      return [];
+    }
+    const items = await this.query(query, options.limit);
+    this.cache.set(key, items);
+    if (this.cache.size > CACHE_LIMIT) {
+      const oldest = this.cache.keys().next().value;
+      if (oldest !== undefined) {
+        this.cache.delete(oldest);
+      }
+    }
+    return mine === this.generation ? items : [];
+  }
+}

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

@@ -0,0 +1,268 @@
+import type { PickerItem } from "./PickerItem";
+import type {
+  FilePickerSuggestionEngine,
+  RankFilePickerOptions,
+} from "./FilePickerSuggestionEngine";
+import type {
+  FilePickerWorkerRequest,
+  FilePickerWorkerResponse,
+} from "./filePickerWorkerMessages";
+
+type PendingRefresh = {
+  readonly resolve: () => void;
+};
+
+type RankRequest = {
+  readonly id: number;
+  readonly query: string;
+  readonly limit: number | undefined;
+  readonly resolve: (items: readonly PickerItem[] | undefined) => void;
+  readonly reject: (error: unknown) => void;
+  readonly signal: AbortSignal | undefined;
+  readonly abortListener: (() => void) | undefined;
+  settled: boolean;
+};
+
+export class WorkerFilePickerSuggestionEngine implements FilePickerSuggestionEngine {
+  private worker: Worker | undefined;
+  private nextRequestId = 0;
+  private refresh: Promise<void> | undefined;
+  private activeRank: RankRequest | undefined;
+  private queuedRank: RankRequest | undefined;
+  private readonly pendingRefreshes = new Map<number, PendingRefresh>();
+
+  public constructor(private readonly root: string) {}
+
+  public refreshRelative(): Promise<void> {
+    this.refresh ??= this.sendRefreshRelative().finally(() => {
+      this.refresh = undefined;
+    });
+    return this.refresh;
+  }
+
+  public rank(
+    query: string,
+    options: RankFilePickerOptions
+  ): Promise<readonly PickerItem[] | undefined> {
+    if (options.signal?.aborted === true) {
+      return Promise.resolve([]);
+    }
+
+    const id = this.nextRequestId++;
+    return new Promise((resolve, reject) => {
+      let request: RankRequest;
+      const abortListener = (): void => {
+        this.abortRank(request);
+      };
+      request = {
+        id,
+        query,
+        limit: options.limit,
+        resolve,
+        reject,
+        signal: options.signal,
+        abortListener: options.signal === undefined ? undefined : abortListener,
+        settled: false,
+      };
+
+      if (options.signal !== undefined) {
+        options.signal.addEventListener("abort", abortListener, { once: true });
+      }
+
+      this.enqueueRank(request);
+    });
+  }
+
+  public dispose(): void {
+    this.worker?.terminate();
+    this.worker = undefined;
+    this.failPending(new Error("file picker worker disposed"));
+  }
+
+  private enqueueRank(request: RankRequest): void {
+    if (this.activeRank === undefined) {
+      this.sendRank(request);
+      return;
+    }
+
+    this.resolveRank(this.activeRank, []);
+    if (this.queuedRank !== undefined) {
+      this.resolveRank(this.queuedRank, []);
+    }
+    this.queuedRank = request;
+  }
+
+  private sendRank(request: RankRequest): void {
+    this.activeRank = request;
+    try {
+      this.post({
+        id: request.id,
+        type: "rank",
+        query: request.query,
+        limit: request.limit,
+      });
+    } catch (error) {
+      if (this.activeRank === request) {
+        this.activeRank = undefined;
+      }
+      this.rejectRank(request, error);
+      this.sendQueuedRank();
+    }
+  }
+
+  private sendQueuedRank(): void {
+    const request = this.queuedRank;
+    if (request === undefined || this.activeRank !== undefined) {
+      return;
+    }
+
+    this.queuedRank = undefined;
+    if (request.settled) {
+      this.sendQueuedRank();
+      return;
+    }
+
+    this.sendRank(request);
+  }
+
+  private abortRank(request: RankRequest): void {
+    if (this.queuedRank === request) {
+      this.queuedRank = undefined;
+    }
+    this.resolveRank(request, []);
+  }
+
+  private resolveRank(
+    request: RankRequest,
+    items: readonly PickerItem[] | undefined
+  ): void {
+    if (request.settled) {
+      return;
+    }
+
+    request.settled = true;
+    this.removeAbortListener(request);
+    request.resolve(items);
+  }
+
+  private rejectRank(request: RankRequest, error: unknown): void {
+    if (request.settled) {
+      return;
+    }
+
+    request.settled = true;
+    this.removeAbortListener(request);
+    request.reject(error);
+  }
+
+  private sendRefreshRelative(): Promise<void> {
+    const id = this.nextRequestId++;
+    return new Promise((resolve) => {
+      this.pendingRefreshes.set(id, { resolve });
+      try {
+        this.post({
+          id,
+          type: "refreshRelative",
+          root: this.root,
+        });
+      } catch {
+        this.pendingRefreshes.delete(id);
+        resolve();
+      }
+    });
+  }
+
+  private post(message: FilePickerWorkerRequest): void {
+    this.currentWorker().postMessage(message);
+  }
+
+  private currentWorker(): Worker {
+    if (this.worker !== undefined) {
+      return this.worker;
+    }
+
+    const worker = new Worker(
+      new URL("./filePickerWorker.ts", import.meta.url),
+      {
+        type: "module",
+      }
+    );
+    worker.onmessage = (
+      event: MessageEvent<FilePickerWorkerResponse>
+    ): void => {
+      this.handleMessage(event.data);
+    };
+    worker.onerror = (event): void => {
+      this.worker = undefined;
+      worker.terminate();
+      this.failPending(new Error(event.message));
+    };
+    this.worker = worker;
+    return worker;
+  }
+
+  private handleMessage(message: FilePickerWorkerResponse): void {
+    switch (message.type) {
+      case "refreshRelative":
+        this.handleRefreshRelativeMessage(message);
+        break;
+      case "rank":
+        this.handleRankMessage(message);
+        break;
+    }
+  }
+
+  private handleRefreshRelativeMessage(
+    message: Extract<
+      FilePickerWorkerResponse,
+      { readonly type: "refreshRelative" }
+    >
+  ): void {
+    const pending = this.pendingRefreshes.get(message.id);
+    if (pending === undefined) {
+      return;
+    }
+
+    this.pendingRefreshes.delete(message.id);
+    pending.resolve();
+  }
+
+  private handleRankMessage(
+    message: Extract<FilePickerWorkerResponse, { readonly type: "rank" }>
+  ): void {
+    const request = this.activeRank;
+    if (request === undefined || request.id !== message.id) {
+      return;
+    }
+
+    this.activeRank = undefined;
+    if (message.ok) {
+      this.resolveRank(request, message.items);
+    } else {
+      this.rejectRank(request, new Error(message.error));
+    }
+    this.sendQueuedRank();
+  }
+
+  private failPending(error: unknown): void {
+    for (const [id, pending] of this.pendingRefreshes) {
+      this.pendingRefreshes.delete(id);
+      pending.resolve();
+    }
+
+    if (this.activeRank !== undefined) {
+      this.rejectRank(this.activeRank, error);
+      this.activeRank = undefined;
+    }
+    if (this.queuedRank !== undefined) {
+      this.rejectRank(this.queuedRank, error);
+      this.queuedRank = undefined;
+    }
+  }
+
+  private removeAbortListener(request: RankRequest): void {
+    if (request.signal !== undefined && request.abortListener !== undefined) {
+      request.signal.removeEventListener("abort", request.abortListener);
+    }
+  }
+}