pim-agent 0.0.1 → 0.9.0

package/packages/core/src/view/MarkdownPainter.ts

@@ -0,0 +1,314 @@
+import { basename } from "node:path";
+import { Painting, type PainterMap } from "./Painting";
+import type {
+  BlockOf,
+  DiffHunk,
+  NoticeSeverity,
+  Span,
+  Tone,
+  ToolIcon,
+  ToolView,
+  ViewBlock,
+} from "./ViewBlock";
+
+type Mode = "inline" | "block";
+
+/** How a block sits in a body; `embed` payloads must never be re-wrapped. */
+export type MarkdownFrame = "flow" | "embed" | "heading";
+
+export type MarkdownGroup = {
+  readonly frame: MarkdownFrame;
+  readonly lines: readonly string[];
+};
+
+export type PaintedTool = {
+  readonly icon: string;
+  readonly lines: readonly string[];
+};
+
+const INLINE_LIMIT = 180;
+
+const ENTITIES: Readonly<Record<string, string>> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+};
+
+function escape(text: string): string {
+  return text.replace(/[&<>"]/g, (char) => ENTITIES[char] ?? char);
+}
+
+function paint(blocks: readonly ViewBlock[]): string[] {
+  return blocks.flatMap((block) => paintBlock(block, "block"));
+}
+
+function paintInline(blocks: readonly ViewBlock[]): string {
+  return blocks
+    .flatMap((block) => paintBlock(block, "inline"))
+    .filter((line) => line !== "")
+    .join(" ");
+}
+
+function paintBody(blocks: readonly ViewBlock[]): MarkdownGroup[] {
+  return Painting.groupByFrame(blocks, Painting.FRAMES).map((group) => ({
+    frame: group.frame,
+    lines: group.blocks.flatMap((block) => paintBlock(block, "block")),
+  }));
+}
+
+function icon(toolIcon: ToolIcon | undefined): string {
+  return toolIcon === undefined ? DEFAULT_ICON : ICONS[toolIcon];
+}
+
+function paintTool(view: ToolView): PaintedTool {
+  const head = [view.title, view.summary ?? []]
+    .map((blocks) => paintInline(blocks))
+    .filter((text) => text !== "")
+    .join(" ");
+  const outline = outlined(view.body ?? []).flatMap((block) =>
+    paintBlock(block, "block")
+  );
+
+  return {
+    icon: icon(view.icon),
+    lines: [head, ...outline].filter((line) => line !== ""),
+  };
+}
+
+/** A chat row carries a body's headings and any payload that fits a line; an embedded one needs a screen. */
+function outlined(blocks: readonly ViewBlock[]): readonly ViewBlock[] {
+  return blocks.filter((block) => {
+    const frame = Painting.FRAMES[block.kind];
+    return (
+      frame === "heading" ||
+      (frame === "flow" && Painting.WEIGHT[block.kind] === "payload")
+    );
+  });
+}
+
+const ICONS = {
+  file: "📄",
+  edit: "✏️",
+  trash: "🗑️",
+  terminal: "⚡️",
+  search: "🔎",
+  checklist: "📋",
+  globe: "🌐",
+  upload: "📤",
+  clock: "⏰",
+  robot: "🤖",
+} as const satisfies Record<ToolIcon, string>;
+
+const DEFAULT_ICON = "⚙️";
+
+const TONE_WRAPPERS = {
+  default: identity,
+  muted: identity,
+  dim: identity,
+  error: bold,
+  warning: identity,
+  accent: identity,
+  added: identity,
+  removed: identity,
+  title: identity,
+} as const satisfies Record<Tone, (text: string) => string>;
+
+const NOTICE_PREFIXES = {
+  info: "",
+  warn: "⚠️ ",
+  error: "❌ ",
+} as const satisfies Record<NoticeSeverity, string>;
+
+function identity(text: string): string {
+  return text;
+}
+
+function bold(text: string): string {
+  return `<b>${text}</b>`;
+}
+
+function paintBlock(block: ViewBlock, mode: Mode): readonly string[] {
+  return Painting.dispatch(PAINTERS, block, mode);
+}
+
+function oneLine(text: string): string {
+  const index = text.indexOf("\n");
+  const first = index < 0 ? text : `${text.slice(0, index).trimEnd()} …`;
+  return first.length <= INLINE_LIMIT
+    ? first
+    : `${first.slice(0, INLINE_LIMIT - 1)}…`;
+}
+
+function escapeIn(text: string, mode: Mode): string {
+  return escape(mode === "inline" ? oneLine(text) : text);
+}
+
+function lines(text: string, mode: Mode): readonly string[] {
+  return mode === "inline"
+    ? [escapeIn(text, mode)]
+    : text.split("\n").map((line) => escape(line));
+}
+
+function paintText(block: BlockOf<"text">, mode: Mode): readonly string[] {
+  const wrap = TONE_WRAPPERS[block.tone ?? "default"];
+  return lines(block.text, mode).map(wrap);
+}
+
+function paintSpans(block: BlockOf<"spans">, mode: Mode): readonly string[] {
+  return [spansText(block.spans, mode)];
+}
+
+function spansText(spans: readonly Span[], mode: Mode): string {
+  return spans
+    .filter((span) => span.text !== "")
+    .map((span) => {
+      let text = escapeIn(span.text, mode);
+      if (span.code === true) {
+        text = `<code>${text}</code>`;
+      }
+      if (span.strike === true) {
+        text = `<s>${text}</s>`;
+      }
+      if (span.strong === true) {
+        text = bold(text);
+      }
+      return TONE_WRAPPERS[span.tone ?? "default"](text);
+    })
+    .join("");
+}
+
+function paintSection(block: BlockOf<"section">): readonly string[] {
+  const lead =
+    block.icon === undefined ? bold(escape(block.label)) : icon(block.icon);
+  const content = paintInline(block.content);
+  return [content === "" ? lead : `${lead} ${content}`];
+}
+
+function paintCode(block: BlockOf<"code">, mode: Mode): readonly string[] {
+  if (mode === "inline") {
+    return [`<code>${escapeIn(block.text, mode)}</code>`];
+  }
+  const start = block.startLine;
+  const body = numbered(block.text.split("\n"), start)
+    .map((line) => escape(line))
+    .join("\n");
+  return [preformatted(body, block.lang)];
+}
+
+function numbered(
+  source: readonly string[],
+  start: number | undefined
+): readonly string[] {
+  if (start === undefined) {
+    return source;
+  }
+  const width = Painting.lineNumberWidth(start, source.length);
+  return source.map(
+    (line, index) => `${String(start + index).padStart(width)} ${line}`
+  );
+}
+
+function preformatted(body: string, lang?: string): string {
+  return lang === undefined || lang === ""
+    ? `<pre>${body}</pre>`
+    : `<pre><code class="language-${escape(lang)}">${body}</code></pre>`;
+}
+
+function paintDiff(block: BlockOf<"diff">, mode: Mode): readonly string[] {
+  const body = block.hunks.flatMap((hunk) => diffLines(hunk));
+  if (body.length === 0) {
+    return [];
+  }
+  if (mode === "inline") {
+    return [`<code>${escapeIn(body[0] ?? "", mode)}</code>`];
+  }
+  return [preformatted(body.map((line) => escape(line)).join("\n"), "diff")];
+}
+
+function diffLines(hunk: DiffHunk): readonly string[] {
+  const header = `@@ -${hunk.oldStart},${hunk.oldLines} +${hunk.newStart},${hunk.newLines} @@`;
+  return [
+    header,
+    ...hunk.lines.map((line) => `${DIFF_MARKERS[line.kind]}${line.text}`),
+  ];
+}
+
+const DIFF_MARKERS = {
+  context: " ",
+  added: "+",
+  removed: "-",
+} as const;
+
+function paintFile(block: BlockOf<"file">, mode: Mode): readonly string[] {
+  const path = mode === "inline" ? basename(block.path) : block.path;
+  const { range, truncated } = Painting.fileSuffix(block);
+  return [`<code>${escape(oneLine(path) + range)}</code>${truncated}`];
+}
+
+function paintList(block: BlockOf<"list">, mode: Mode): readonly string[] {
+  return Painting.hangingList(block.items, block.ordered === true, (item) =>
+    paintBlock(item, mode)
+  );
+}
+
+function paintKv(block: BlockOf<"kv">, mode: Mode): readonly string[] {
+  return block.pairs.map(
+    ([key, value]) =>
+      `${bold(`${escapeIn(key, mode)}:`)} ${escapeIn(value, mode)}`
+  );
+}
+
+function paintLink(block: BlockOf<"link">, mode: Mode): readonly string[] {
+  const label = Painting.linkLabel(block);
+  return [`<a href="${escape(block.href)}">${escapeIn(label, mode)}</a>`];
+}
+
+function paintAttachment(
+  block: BlockOf<"attachment">,
+  mode: Mode
+): readonly string[] {
+  return [escapeIn(block.name, mode)];
+}
+
+function paintImage(block: BlockOf<"image">, mode: Mode): readonly string[] {
+  return [escapeIn(Painting.imageSummary(block), mode)];
+}
+
+function paintMarkdown(
+  block: BlockOf<"markdown">,
+  mode: Mode
+): readonly string[] {
+  return lines(block.text, mode);
+}
+
+function paintNotice(block: BlockOf<"notice">, mode: Mode): readonly string[] {
+  const prefix = NOTICE_PREFIXES[block.severity];
+  return lines(block.text, mode).map((line) => `${prefix}${line}`);
+}
+
+const PAINTERS: PainterMap<readonly string[], [Mode]> = {
+  text: paintText,
+  markdown: paintMarkdown,
+  spans: paintSpans,
+  section: paintSection,
+  code: paintCode,
+  diff: paintDiff,
+  file: paintFile,
+  list: paintList,
+  kv: paintKv,
+  link: paintLink,
+  attachment: paintAttachment,
+  image: paintImage,
+  notice: paintNotice,
+};
+
+/** Paints a `ViewBlock` tree to Telegram-flavoured HTML; the caller joins lines. */
+export const MarkdownPainter = {
+  escape,
+  paint,
+  paintInline,
+  paintBody,
+  icon,
+  paintTool,
+};

package/packages/core/src/view/Painting.ts

@@ -0,0 +1,182 @@
+import { Format } from "../shared/Format";
+import { ImageMime } from "../shared/ImageMime";
+import type { ImageDetails } from "../shared/Images";
+import type { BlockOf, KvPair, ViewBlock } from "./ViewBlock";
+
+export type PainterMap<TOut, TArgs extends readonly unknown[] = []> = {
+  readonly [TKind in ViewBlock["kind"]]: (
+    block: BlockOf<TKind>,
+    ...args: TArgs
+  ) => TOut;
+};
+
+function dispatch<TOut, TArgs extends readonly unknown[]>(
+  painters: PainterMap<TOut, TArgs>,
+  block: ViewBlock,
+  ...args: TArgs
+): TOut {
+  const painter = painters[block.kind] as (
+    block: ViewBlock,
+    ...args: TArgs
+  ) => TOut;
+  return painter(block, ...args);
+}
+
+/** How a block sits in its container: `embed` must not be restyled or re-wrapped, `tight` paints its own leading column. */
+export type BlockFrame = "flow" | "embed" | "tight" | "heading";
+
+const FRAMES = {
+  text: "flow",
+  markdown: "embed",
+  spans: "flow",
+  section: "heading",
+  code: "embed",
+  diff: "embed",
+  file: "flow",
+  list: "flow",
+  kv: "flow",
+  link: "flow",
+  attachment: "flow",
+  image: "flow",
+  notice: "flow",
+} as const satisfies Record<ViewBlock["kind"], BlockFrame>;
+
+/** What a block is to the tool that emitted it: its result, or the chrome around one. */
+export type BlockWeight = "payload" | "chrome";
+
+const WEIGHT = {
+  text: "chrome",
+  markdown: "payload",
+  spans: "chrome",
+  section: "chrome",
+  code: "chrome",
+  diff: "payload",
+  file: "chrome",
+  list: "chrome",
+  kv: "chrome",
+  link: "chrome",
+  attachment: "chrome",
+  image: "payload",
+  notice: "chrome",
+} as const satisfies Record<ViewBlock["kind"], BlockWeight>;
+
+export type FrameGroup<TFrame> = {
+  readonly frame: TFrame;
+  readonly blocks: readonly ViewBlock[];
+};
+
+function groupByFrame<TFrame>(
+  blocks: readonly ViewBlock[],
+  frames: Readonly<Record<ViewBlock["kind"], TFrame>>,
+  mergeable: (frame: TFrame) => boolean = () => true
+): FrameGroup<TFrame>[] {
+  const groups: Array<{ frame: TFrame; blocks: ViewBlock[] }> = [];
+  for (const block of blocks) {
+    const frame = frames[block.kind];
+    const open = groups.at(-1);
+    if (open?.frame === frame && mergeable(frame)) {
+      open.blocks.push(block);
+    } else {
+      groups.push({ frame, blocks: [block] });
+    }
+  }
+  return groups;
+}
+
+function formatRange(range: readonly [number, number | undefined]): string {
+  const [start, end] = range;
+  return end === undefined ? `:${start}` : `:${start}-${end}`;
+}
+
+function fileSuffix(block: {
+  readonly range?: readonly [number, number | undefined];
+  readonly truncated?: boolean;
+}): { readonly range: string; readonly truncated: string } {
+  return {
+    range: block.range ? formatRange(block.range) : "",
+    truncated: block.truncated === true ? " (truncated)" : "",
+  };
+}
+
+function linkLabel(block: {
+  readonly label: string;
+  readonly href: string;
+}): string {
+  return block.label === "" || block.label === block.href
+    ? block.href
+    : block.label;
+}
+
+/** What a painter that cannot draw the picture says instead: `[image 1200×800 png · 240 KB]`. */
+function imageSummary(block: BlockOf<"image">): string {
+  return `[image ${block.width}×${block.height} ${ImageMime.extensionOf(block.mimeType)} · ${Format.bytes(block.bytes)}]`;
+}
+
+/** The picture plus what it cannot show about itself; `extra` is whatever only the calling tool knows. */
+function imageBlocks(
+  details: ImageDetails,
+  alt: string,
+  extra: readonly KvPair[] = []
+): readonly ViewBlock[] {
+  return [
+    {
+      kind: "image",
+      sha256: details.sha256,
+      mimeType: details.mimeType,
+      width: details.width,
+      height: details.height,
+      bytes: details.bytes,
+      alt,
+    },
+    {
+      kind: "kv",
+      pairs: [
+        [
+          "dimensions",
+          `${details.width}x${details.height}${details.resized ? " (downscaled)" : ""}`,
+        ],
+        ...(details.frames >= 2
+          ? [["frames", `${details.frames} (frame 1 shown)`] as KvPair]
+          : []),
+        ["size", Format.bytes(details.bytes)],
+        ...extra,
+      ],
+    },
+  ];
+}
+
+function lineNumberWidth(start: number, count: number): number {
+  return String(start + Math.max(0, count - 1)).length;
+}
+
+function hangingList(
+  items: readonly ViewBlock[],
+  ordered: boolean,
+  paintItem: (item: ViewBlock) => readonly string[],
+  styleMarker: (marker: string) => string = (marker) => marker
+): string[] {
+  const markers = items.map((_, index) => (ordered ? `${index + 1}.` : "•"));
+  const width = Math.max(0, ...markers.map((marker) => marker.length)) + 1;
+  const indent = " ".repeat(width);
+
+  return items.flatMap((item, index) => {
+    const marker = styleMarker((markers[index] ?? "•").padEnd(width));
+    return paintItem(item).map((line, lineIndex) =>
+      lineIndex === 0 ? marker + line : indent + line
+    );
+  });
+}
+
+export const Painting = {
+  FRAMES,
+  WEIGHT,
+  dispatch,
+  groupByFrame,
+  formatRange,
+  fileSuffix,
+  linkLabel,
+  imageSummary,
+  imageBlocks,
+  lineNumberWidth,
+  hangingList,
+};

package/packages/core/src/view/ViewBlock.ts

@@ -0,0 +1,124 @@
+import type { ToolDiffHunk } from "../shared/DiffLines";
+import type { ImageMimeType } from "../shared/Images";
+
+export type DiffHunk = ToolDiffHunk;
+
+/** Semantic inline styling roles; every painter must map the whole set. */
+export type Tone =
+  | "default"
+  | "muted"
+  | "dim"
+  | "error"
+  | "warning"
+  | "accent"
+  | "added"
+  | "removed"
+  | "title";
+
+export type ToolIcon =
+  | "file"
+  | "edit"
+  | "trash"
+  | "terminal"
+  | "search"
+  | "checklist"
+  | "globe"
+  | "upload"
+  | "clock"
+  | "robot";
+
+export type Span = {
+  readonly text: string;
+  readonly tone?: Tone;
+  readonly strike?: boolean;
+  readonly strong?: boolean;
+  readonly code?: boolean;
+};
+
+export type NoticeSeverity = "info" | "warn" | "error";
+
+export type KvPair = readonly [string, string];
+
+export type ViewBlock =
+  | { readonly kind: "text"; readonly text: string; readonly tone?: Tone }
+  /** Markdown source; framed as an embed and never re-coloured or re-wrapped. */
+  | { readonly kind: "markdown"; readonly text: string }
+  /** One line of mixed-tone text, e.g. a `+5`/`-2` diff stat or a rename. */
+  | { readonly kind: "spans"; readonly spans: readonly Span[] }
+  /** Introduces a sub-item inside a body; painters draw it as a separated heading. */
+  | {
+      readonly kind: "section";
+      readonly label: string;
+      readonly icon?: ToolIcon;
+      readonly content: readonly ViewBlock[];
+    }
+  | {
+      readonly kind: "code";
+      readonly lang: string;
+      readonly text: string;
+      readonly startLine?: number;
+    }
+  | {
+      readonly kind: "diff";
+      readonly path: string;
+      readonly hunks: readonly DiffHunk[];
+    }
+  | {
+      readonly kind: "file";
+      readonly path: string;
+      /** An undefined end is an open-ended range (`:40`), not a missing one. */
+      readonly range?: readonly [number, number | undefined];
+      readonly truncated?: boolean;
+    }
+  | {
+      readonly kind: "list";
+      readonly items: readonly ViewBlock[];
+      readonly ordered?: boolean;
+    }
+  | {
+      readonly kind: "kv";
+      readonly pairs: readonly KvPair[];
+    }
+  | { readonly kind: "link"; readonly href: string; readonly label: string }
+  /** A file delivered to the reader, not a path on the agent's machine; `url` is server-relative. */
+  | {
+      readonly kind: "attachment";
+      /** What to call it on screen; never a path. */
+      readonly name: string;
+      readonly url: string;
+      readonly isImage: boolean;
+    }
+  /** A picture the model was shown, addressed by digest; the bytes never ride the wire, and the client that fetches them builds the URL. */
+  | {
+      readonly kind: "image";
+      readonly sha256: string;
+      readonly mimeType: ImageMimeType;
+      readonly width: number;
+      readonly height: number;
+      readonly bytes: number;
+      readonly alt: string;
+    }
+  | {
+      readonly kind: "notice";
+      readonly text: string;
+      readonly severity: NoticeSeverity;
+    };
+
+export type BlockOf<TKind extends ViewBlock["kind"]> = Extract<
+  ViewBlock,
+  { kind: TKind }
+>;
+
+export type ToolView = {
+  /** Display label for the title row, e.g. `"Read"`; defaults to the definition's label. */
+  readonly label?: string;
+  /** Tints the label; defaults to the title colour. */
+  readonly labelTone?: Tone;
+  readonly icon?: ToolIcon;
+  /** Painted as one line; a lone `markdown` block is handed over unpainted instead. */
+  readonly title: readonly ViewBlock[];
+  /** Status content rendered in every state: streaming, collapsed and expanded. */
+  readonly summary?: readonly ViewBlock[];
+  /** Rendered only once the row is expanded, and never while streaming. */
+  readonly body?: readonly ViewBlock[];
+};

package/packages/daemon/src/Daemon.ts

@@ -0,0 +1,63 @@
+import type { SurfaceName } from "./Surfaces";
+
+/** A running surface, and the only thing the daemon asks of one. */
+export type SurfaceHandle = {
+  readonly stop: () => Promise<void>;
+};
+
+export type Surface = {
+  readonly name: SurfaceName;
+  /** Brings the surface up, resolving once it is serving rather than when it stops. */
+  readonly start: () => Promise<SurfaceHandle>;
+};
+
+/**
+ * Every surface in one process, and none of them able to take another down: a
+ * bot that cannot reach Telegram leaves the browser served, and a port already
+ * bound leaves the bot polling.
+ */
+export class Daemon {
+  private readonly surfaces: ReadonlyArray<Surface>;
+  private readonly live = new Map<SurfaceName, SurfaceHandle>();
+
+  public constructor(surfaces: ReadonlyArray<Surface>) {
+    this.surfaces = surfaces;
+  }
+
+  public get running(): ReadonlyArray<SurfaceName> {
+    return [...this.live.keys()];
+  }
+
+  /** Starts every surface; throws only when none of them came up. */
+  public async start(): Promise<ReadonlyArray<SurfaceName>> {
+    await Promise.all(
+      this.surfaces.map(async (surface) => {
+        try {
+          this.live.set(surface.name, await surface.start());
+        } catch (err) {
+          console.error(`[daemon] the ${surface.name} surface failed:`, err);
+        }
+      })
+    );
+    if (this.live.size === 0) {
+      throw new Error(
+        `no surface started: ${this.surfaces.map((surface) => surface.name).join(", ")}`
+      );
+    }
+    return this.running;
+  }
+
+  public async stop(): Promise<void> {
+    const live = [...this.live];
+    this.live.clear();
+    await Promise.all(
+      live.map(async ([name, handle]) => {
+        try {
+          await handle.stop();
+        } catch (err) {
+          console.error(`[daemon] the ${name} surface failed to stop:`, err);
+        }
+      })
+    );
+  }
+}