pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,128 @@
+import { join } from "node:path";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { Fs } from "./Fs";
+import { Paths } from "./Paths";
+
+const Schema = Type.Object({
+  extensions: Type.Object(
+    {
+      toggles: Type.Record(Type.String(), Type.Boolean(), { default: {} }),
+    },
+    { default: { toggles: {} } }
+  ),
+  exa: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  jina: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  firecrawl: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  read: Type.Object(
+    {
+      dedupImages: Type.Boolean({ default: true }),
+    },
+    { default: { dedupImages: true } }
+  ),
+});
+
+type Settings = Static<typeof Schema>;
+
+let loaded: Promise<Settings> | undefined;
+let loadedPath: string | undefined;
+const writes = Fs.serialised();
+
+function path(): string {
+  return join(Paths.pimHomeDir(), "settings.json");
+}
+
+function load(): Promise<Settings> {
+  const settingsPath = path();
+  if (loadedPath !== settingsPath) {
+    loaded = undefined;
+    loadedPath = settingsPath;
+  }
+  loaded ??= (async () => {
+    const raw = await Fs.readJsonOr<unknown>(settingsPath, {});
+    const filled = Value.Default(Schema, raw);
+    return Value.Check(Schema, filled) ? filled : Value.Create(Schema);
+  })();
+  return loaded;
+}
+
+async function getExaApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["EXA_API_KEY"]) ??
+    normalize((await get("exa")).apiKey)
+  );
+}
+
+async function getJinaApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["JINA_API_KEY"]) ??
+    normalize((await get("jina")).apiKey)
+  );
+}
+
+async function getFirecrawlApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["FIRECRAWL_API_KEY"]) ??
+    normalize((await get("firecrawl")).apiKey)
+  );
+}
+
+function normalize(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+async function get<K extends keyof Settings>(key: K): Promise<Settings[K]> {
+  return (await load())[key];
+}
+
+function set<K extends keyof Settings>(
+  key: K,
+  value: Settings[K]
+): Promise<void> {
+  return update(key, () => value);
+}
+
+function update<K extends keyof Settings>(
+  key: K,
+  mutate: (current: Settings[K]) => Settings[K]
+): Promise<void> {
+  return writes.run(async () => {
+    const current = await load();
+    const next: Settings = { ...current, [key]: mutate(current[key]) };
+    if (!Value.Check(Schema, next)) {
+      throw new Error(`Invalid value for pim setting "${String(key)}"`);
+    }
+    const settingsPath = path();
+    loaded = Promise.resolve(next);
+    loadedPath = settingsPath;
+    await Paths.ensurePimHome();
+    await Fs.writeJson(settingsPath, next);
+  });
+}
+
+export const PimSettings = {
+  path,
+  getExaApiKey,
+  getJinaApiKey,
+  getFirecrawlApiKey,
+  get,
+  set,
+  update,
+};

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

@@ -0,0 +1,93 @@
+import { Fs } from "./Fs";
+import { createKy } from "./Http";
+
+const REGISTRY = "https://registry.npmjs.org";
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+type Manifest = {
+  readonly name: string;
+  readonly version: string;
+};
+
+type LatestOptions = {
+  readonly fetch?: typeof fetch;
+  readonly timeoutMs?: number;
+};
+
+async function read(url: URL): Promise<Manifest> {
+  const pkg = await Fs.readJsonOr<Partial<Manifest> | null>(url, null);
+  return {
+    name: typeof pkg?.name === "string" ? pkg.name : "?",
+    version: typeof pkg?.version === "string" ? pkg.version : "?",
+  };
+}
+
+function self(): Promise<Manifest> {
+  return read(new URL("../../../../package.json", import.meta.url));
+}
+
+async function current(): Promise<string> {
+  return (await self()).version;
+}
+
+/** The npm package this pim was published as. */
+async function name(): Promise<string> {
+  return (await self()).name;
+}
+
+/** The pi that ships inside pim's install tree. */
+async function pi(): Promise<string> {
+  return (
+    await read(
+      new URL(
+        import.meta.resolve("@earendil-works/pi-coding-agent/package.json")
+      )
+    )
+  ).version;
+}
+
+async function latest(
+  options: LatestOptions = {}
+): Promise<string | undefined> {
+  const pkg = await self();
+  const client = createKy(options.fetch);
+  try {
+    const release = await client(
+      `${REGISTRY}/${pkg.name.replace("/", "%2f")}/latest`,
+      {
+        timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        headers: { accept: "application/json" },
+      }
+    ).json<{ readonly version?: unknown }>();
+    return typeof release.version === "string" && release.version.trim()
+      ? release.version.trim()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function core(version: string): readonly number[] | undefined {
+  const parts = version.trim().split(/[-+]/)[0]!.split(".");
+  const numbers = parts.map(Number);
+  return parts.length === 3 &&
+    numbers.every((part) => Number.isInteger(part) && part >= 0)
+    ? numbers
+    : undefined;
+}
+
+function isNewer(candidate: string, installed: string): boolean {
+  const left = core(candidate);
+  const right = core(installed);
+  if (!left || !right) {
+    return candidate.trim() !== installed.trim();
+  }
+  for (const [index, part] of left.entries()) {
+    if (part !== right[index]) {
+      return part > right[index]!;
+    }
+  }
+  return installed.includes("-") && !candidate.includes("-");
+}
+
+export const PimVersion = { current, name, pi, latest, isNewer };

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

@@ -0,0 +1,26 @@
+async function mapPooled<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = Array.from({ length: items.length });
+  let next = 0;
+
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      results[index] = await fn(items[index] as T, index);
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, worker)
+  );
+
+  return results;
+}
+
+export const Pool = {
+  mapPooled,
+};

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

@@ -0,0 +1,30 @@
+export type ProcOptions = {
+  readonly cwd?: string | undefined;
+  readonly stdout?: "pipe" | "inherit";
+};
+
+export type ProcResult = {
+  readonly code: number;
+  readonly stdout: string;
+  readonly stderr: string;
+};
+
+async function run(
+  cmd: ReadonlyArray<string>,
+  options: ProcOptions = {}
+): Promise<ProcResult> {
+  const proc = Bun.spawn([...cmd], {
+    cwd: options.cwd,
+    stdout: options.stdout ?? "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr] = await Promise.all([
+    proc.stdout instanceof ReadableStream
+      ? new Response(proc.stdout).text()
+      : "",
+    new Response(proc.stderr).text(),
+  ]);
+  return { code: await proc.exited, stdout, stderr };
+}
+
+export const Proc = { run };

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

@@ -0,0 +1,50 @@
+export type RateLimiterOptions = {
+  readonly maxRequests: number;
+  readonly windowMs: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+};
+
+export class RateLimiter {
+  private readonly maxRequests: number;
+  private readonly windowMs: number;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly timestamps: number[] = [];
+  private tail: Promise<void> = Promise.resolve();
+
+  public constructor(options: RateLimiterOptions) {
+    this.maxRequests = Math.max(1, options.maxRequests);
+    this.windowMs = options.windowMs;
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? ((ms) => Bun.sleep(ms));
+  }
+
+  public acquire(): Promise<void> {
+    const reserved = this.tail.then(() => this.reserve());
+    this.tail = reserved.catch(() => {});
+
+    return reserved;
+  }
+
+  private async reserve(): Promise<void> {
+    while (true) {
+      const now = this.now();
+      const threshold = now - this.windowMs;
+
+      while (this.timestamps.length > 0 && this.timestamps[0]! <= threshold) {
+        this.timestamps.shift();
+      }
+
+      if (this.timestamps.length < this.maxRequests) {
+        this.timestamps.push(now);
+
+        return;
+      }
+
+      const waitMs = this.timestamps[0]! + this.windowMs - now;
+
+      await this.sleep(Math.max(0, waitMs));
+    }
+  }
+}

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

@@ -0,0 +1,371 @@
+import type {
+  AgentToolResult,
+  Theme,
+  ThemeColor,
+  ToolRenderResultOptions,
+} from "@earendil-works/pi-coding-agent";
+import type { MarkdownTheme } from "@earendil-works/pi-tui";
+import {
+  type Component,
+  Container,
+  Markdown,
+  visibleWidth,
+  wrapTextWithAnsi,
+} from "@earendil-works/pi-tui";
+
+export type RenderContext = {
+  readonly lastComponent: Component | undefined;
+  readonly isPartial: boolean;
+  readonly isError: boolean;
+};
+
+export type MarkerStatus = "warning" | "error" | "success";
+
+export type PrefixSpec = {
+  readonly prefix: string;
+  readonly width: number;
+};
+
+const GAPPED_PREFIX: PrefixSpec = {
+  prefix: " │ ",
+  width: 3,
+};
+const TIGHT_PREFIX: PrefixSpec = {
+  prefix: " │",
+  width: 2,
+};
+
+class ToolTitle implements Component {
+  private text = "";
+  private theme: Theme | undefined;
+
+  public setText(text: string, theme: Theme): void {
+    this.text = text;
+    this.theme = theme;
+  }
+
+  public render(width: number): string[] {
+    if (!this.text || this.text.trim() === "") {
+      return [];
+    }
+
+    const theme = this.theme;
+    const normalized = this.text.replace(/\t/g, "   ");
+    const lines = wrapTextWithAnsi(normalized, Math.max(1, width));
+
+    if (lines.length <= 1 || theme === undefined) {
+      return lines.map((line) => padLine(line, width));
+    }
+
+    const inner = Math.max(1, width - GAPPED_PREFIX.width);
+    const out = [padLine(lines[0] ?? "", width)];
+
+    for (const logical of lines.slice(1)) {
+      for (const wrapped of wrapTextWithAnsi(logical, inner)) {
+        out.push(
+          padLine(theme.fg("toolOutput", GAPPED_PREFIX.prefix) + wrapped, width)
+        );
+      }
+    }
+
+    return out;
+  }
+
+  public invalidate(): void {}
+}
+
+class MarkdownTitle implements Component {
+  private prefix = "";
+  private title = "";
+  private theme: Theme | undefined;
+
+  public set(args: {
+    readonly prefix: string;
+    readonly title: string;
+    readonly theme: Theme;
+  }): void {
+    this.prefix = args.prefix;
+    this.title = args.title;
+    this.theme = args.theme;
+  }
+
+  public render(width: number): string[] {
+    const theme = this.theme;
+    if (!theme) {
+      return [];
+    }
+
+    const inner = Math.max(1, width - visibleWidth(this.prefix));
+    const titleLines = markdownLines({
+      text: this.title,
+      theme,
+      width: inner,
+    });
+    const lines = titleLines.length > 0 ? titleLines : [""];
+    const out = [padLine(this.prefix + (lines[0] ?? ""), width)];
+
+    for (const line of lines.slice(1)) {
+      out.push(
+        padLine(theme.fg("toolOutput", GAPPED_PREFIX.prefix) + line, width)
+      );
+    }
+
+    return out;
+  }
+
+  public invalidate(): void {}
+}
+
+function padLine(line: string, width: number): string {
+  return line + " ".repeat(Math.max(0, width - visibleWidth(line)));
+}
+
+function makeMarkdown(
+  text: string,
+  theme: Theme,
+  lineColor: ThemeColor | undefined
+): Markdown {
+  return new Markdown(
+    text,
+    0,
+    0,
+    markdownTheme(theme),
+    lineColor ? { color: (t: string) => theme.fg(lineColor, t) } : undefined
+  );
+}
+
+function markdownTheme(theme: Theme): MarkdownTheme {
+  return {
+    heading: (text: string) => theme.fg("mdHeading", text),
+    link: (text: string) => theme.fg("mdLink", text),
+    linkUrl: (text: string) => theme.fg("mdLinkUrl", text),
+    code: (text: string) => theme.fg("mdCode", text),
+    codeBlock: (text: string) => theme.fg("mdCodeBlock", text),
+    codeBlockBorder: (text: string) => theme.fg("mdCodeBlockBorder", text),
+    quote: (text: string) => theme.fg("mdQuote", text),
+    quoteBorder: (text: string) => theme.fg("mdQuoteBorder", text),
+    hr: (text: string) => theme.fg("mdHr", text),
+    listBullet: (text: string) => theme.fg("mdListBullet", text),
+    bold: (text: string) => theme.bold(text),
+    italic: (text: string) => theme.italic(text),
+    underline: (text: string) => theme.underline(text),
+    strikethrough: (text: string) => theme.strikethrough(text),
+  };
+}
+
+function markerColorFor(isPartial: boolean, isError: boolean): MarkerStatus {
+  if (isPartial) {
+    return "warning";
+  }
+  if (isError) {
+    return "error";
+  }
+  return "success";
+}
+
+function firstText(
+  result:
+    | {
+        readonly content?: ReadonlyArray<{
+          readonly type: string;
+          readonly text?: string;
+        }>;
+      }
+    | undefined
+): string {
+  const first = result?.content?.[0];
+  return first && "text" in first ? (first.text ?? "") : "";
+}
+
+function extractErrorText(
+  result: {
+    readonly content?: ReadonlyArray<{
+      readonly type: string;
+      readonly text?: string;
+    }>;
+  },
+  fallback: string
+): string {
+  const text = (result.content ?? [])
+    .filter((item) => item.type === "text")
+    .map((item) => item.text ?? "")
+    .join("\n")
+    .trim();
+
+  return text || fallback;
+}
+
+function toolTitleText(args: {
+  readonly label: string;
+  readonly title: string;
+  readonly theme: Theme;
+  readonly markerColor: MarkerStatus;
+  readonly labelColor?: ThemeColor;
+}): string {
+  return titleHead(args) + args.theme.fg("toolTitle", ": " + args.title);
+}
+
+function titleHead(args: {
+  readonly label: string;
+  readonly theme: Theme;
+  readonly markerColor: MarkerStatus;
+  readonly labelColor?: ThemeColor;
+}): string {
+  const { label, theme, markerColor, labelColor } = args;
+  return (
+    theme.fg(markerColor, " ▪") +
+    " " +
+    theme.fg(labelColor ?? "toolTitle", theme.bold(label))
+  );
+}
+
+function makeTitleBlock(args: {
+  readonly text: string;
+  readonly theme: Theme;
+  readonly lastComponent?: Component;
+}): Component {
+  const component =
+    args.lastComponent instanceof ToolTitle
+      ? args.lastComponent
+      : new ToolTitle();
+  component.setText(args.text, args.theme);
+  return component;
+}
+
+function renderToolCallTitle(args: {
+  readonly label: string;
+  readonly title: string;
+  readonly theme: Theme;
+  readonly context: RenderContext;
+  readonly labelColor?: ThemeColor;
+  readonly markdown?: boolean;
+}): Component {
+  const { theme, context } = args;
+  const markerColor = markerColorFor(
+    Boolean(context.isPartial),
+    Boolean(context.isError)
+  );
+
+  if (args.markdown === true) {
+    const component =
+      context.lastComponent instanceof MarkdownTitle
+        ? context.lastComponent
+        : new MarkdownTitle();
+    component.set({
+      prefix: titleHead({ ...args, markerColor }) + theme.fg("toolTitle", ": "),
+      title: args.title,
+      theme,
+    });
+    return component;
+  }
+
+  return makeTitleBlock({
+    text: toolTitleText({ ...args, markerColor }),
+    theme,
+    lastComponent: context.lastComponent,
+  });
+}
+
+function makePrefixedBlock(args: {
+  readonly lines: readonly string[];
+  readonly theme: Theme;
+  readonly prefix: PrefixSpec;
+  readonly lineColor?: ThemeColor;
+}): Component {
+  const { lines, theme, prefix, lineColor } = args;
+  return {
+    render(width: number): string[] {
+      const inner = Math.max(1, width - prefix.width);
+      const out: string[] = [];
+      for (const logical of lines) {
+        for (const w of wrapTextWithAnsi(logical, inner)) {
+          const body = lineColor ? theme.fg(lineColor, w) : w;
+          out.push(theme.fg("toolOutput", prefix.prefix) + body);
+        }
+      }
+      return out;
+    },
+    invalidate() {},
+  };
+}
+
+function markdownLines(args: {
+  readonly text: string;
+  readonly theme: Theme;
+  readonly width: number;
+  readonly lineColor?: ThemeColor;
+}): string[] {
+  return makeMarkdown(args.text, args.theme, args.lineColor)
+    .render(args.width)
+    .map((line) => line.trimEnd());
+}
+
+function makeMarkdownBlock(args: {
+  readonly text: string;
+  readonly theme: Theme;
+  readonly prefix: PrefixSpec;
+  readonly lineColor?: ThemeColor;
+}): Component {
+  const { text, theme, prefix, lineColor } = args;
+  const markdown = makeMarkdown(text, theme, lineColor);
+
+  return {
+    render(width: number): string[] {
+      const inner = Math.max(1, width - prefix.width);
+      return markdown
+        .render(inner)
+        .map((line) => theme.fg("toolOutput", prefix.prefix) + line.trimEnd());
+    },
+    invalidate(): void {
+      markdown.invalidate();
+    },
+  };
+}
+
+function renderErrorResult(args: {
+  readonly result: AgentToolResult<unknown>;
+  readonly options: ToolRenderResultOptions;
+  readonly theme: Theme;
+  readonly context: RenderContext;
+}): Container {
+  const { result, options, theme, context } = args;
+  const container =
+    (context.lastComponent as Container | undefined) ?? new Container();
+  container.clear();
+
+  if (options.isPartial || !options.expanded) {
+    return container;
+  }
+
+  const body = firstText(result);
+  if (!body) {
+    return container;
+  }
+
+  container.addChild(
+    makePrefixedBlock({
+      lines: body.split("\n"),
+      theme,
+      prefix: GAPPED_PREFIX,
+      lineColor: "error",
+    })
+  );
+
+  container.invalidate();
+  return container;
+}
+
+export const Renderer = {
+  GAPPED_PREFIX,
+  TIGHT_PREFIX,
+  markerColorFor,
+  firstText,
+  extractErrorText,
+  toolTitleText,
+  makeTitleBlock,
+  renderToolCallTitle,
+  makePrefixedBlock,
+  markdownLines,
+  makeMarkdownBlock,
+  renderErrorResult,
+};

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

@@ -0,0 +1,17 @@
+import { basename, resolve, sep } from "node:path";
+
+/** Reduces a client-supplied name to one harmless path segment. */
+function safeName(name: string): string {
+  return basename(name).replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+/** Resolves `child` under `parent`, refusing anything that escapes it. */
+function contain(parent: string, child: string): string {
+  const path = resolve(parent, child);
+  if (!path.startsWith(`${resolve(parent)}${sep}`)) {
+    throw new Error(`refusing path outside ${parent}: ${child}`);
+  }
+  return path;
+}
+
+export const SafePath = { safeName, contain };