pim-agent 0.0.1 → 0.10.0

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);
+        }
+      })
+    );
+  }
+}

package/packages/daemon/src/DaemonInstall.ts

@@ -0,0 +1,115 @@
+import { join } from "node:path";
+
+import { DaemonUnit, SupersededUnits } from "#core/shared/DaemonUnit";
+import { Supervisor, type Unit } from "#core/shared/Supervisor";
+import { DEFAULT_CLIENT_DIR } from "#server/StaticClient";
+import { WebOptions } from "#server/WebOptions";
+import { Surfaces, type SurfaceName } from "./Surfaces";
+
+type FrozenUnit = Unit & { readonly args: ReadonlyArray<string> };
+
+/** What this machine serves today: the unit being replaced, or the ones it supersedes. */
+export type Installed = {
+  readonly surfaces: ReadonlyArray<SurfaceName>;
+  readonly args: ReadonlyArray<string>;
+};
+
+const NOTHING: Installed = { surfaces: [], args: [] };
+
+/**
+ * A supervisor starts the daemon with no argv: every flag it needs must be
+ * frozen in here. What is installed already is the base the new argv overrides
+ * flag by flag, so installing one surface keeps the other one — and its
+ * settings. Naming `--surfaces` outright is how a daemon is shrunk again.
+ */
+function unit(
+  argv: ReadonlyArray<string>,
+  installed: Installed = NOTHING
+): FrozenUnit {
+  const surfaces = Surfaces.named(argv)
+    ? Surfaces.parse(argv)
+    : Surfaces.union(installed.surfaces, Surfaces.parse(argv));
+  const merged = [...installed.args, ...argv];
+  return {
+    ...DaemonUnit,
+    description: `${DaemonUnit.description} (${surfaces.join(", ")})`,
+    args: [
+      "--surfaces",
+      Surfaces.format(surfaces),
+      ...(surfaces.includes("web")
+        ? WebOptions.freeze(WebOptions.parse(merged))
+        : []),
+    ],
+  };
+}
+
+/**
+ * The merged unit's own argv, or — before the cutover — whatever the per-surface
+ * units were installed with, so a tailnet hostname frozen months ago survives.
+ */
+async function installed(): Promise<Installed> {
+  const current = await Supervisor.installedArgs(DaemonUnit);
+  if (current.length > 0) {
+    return { surfaces: Surfaces.parse(current), args: carriedOver(current) };
+  }
+  const superseded = (
+    await Promise.all(
+      SupersededUnits.map((unit) => Supervisor.installedArgs(unit))
+    )
+  ).filter((args) => args.length > 0);
+  return {
+    surfaces: Surfaces.union(...superseded.map(Surfaces.parse)),
+    args: superseded.flatMap(carriedOver),
+  };
+}
+
+// `--web-cwd` becomes `--cwd` on the way in, or it would outrank a new `--cwd`.
+function carriedOver(args: ReadonlyArray<string>): ReadonlyArray<string> {
+  return args.map((arg) => (arg === "--web-cwd" ? "--cwd" : arg));
+}
+
+async function install(argv: ReadonlyArray<string>): Promise<void> {
+  const descriptor = unit(argv, await installed());
+  const surfaces = Surfaces.parse(descriptor.args);
+  if (surfaces.includes("web")) {
+    await buildClient();
+  }
+  const kept = surfaces.filter((name) => !Surfaces.parse(argv).includes(name));
+  if (kept.length > 0) {
+    console.log(
+      `[install] keeping the ${kept.join(", ")} surface this machine already serves; pass --surfaces to change that`
+    );
+  }
+  console.log(
+    `[install] unit starts: pim --mode ${descriptor.mode} ${descriptor.args.join(" ")}`
+  );
+  await Supervisor.install(descriptor, { replaces: SupersededUnits });
+}
+
+async function uninstall(): Promise<void> {
+  await Supervisor.uninstall(DaemonUnit);
+  await Supervisor.supersede(SupersededUnits);
+}
+
+async function buildClient(): Promise<void> {
+  const at = await Supervisor.detectInstall();
+  // Probe `index.html`, not the directory: a half-emptied `dist/client` is still a broken bundle.
+  const bundled = await Bun.file(
+    join(DEFAULT_CLIENT_DIR, "index.html")
+  ).exists();
+  if (at.kind !== "dev" || bundled) {
+    return;
+  }
+  console.log("[install] building the web client");
+  const proc = Bun.spawn(["bun", "run", "web:build"], {
+    cwd: at.packageRoot,
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    throw new Error(`bun run web:build exited ${code}`);
+  }
+}
+
+export const DaemonInstall = { unit, installed, install, uninstall };

package/packages/daemon/src/Surfaces.ts

@@ -0,0 +1,66 @@
+import { Cli as Argv } from "#core/shared/Cli";
+
+export const SURFACE_NAMES = ["web", "telegram"] as const;
+
+export type SurfaceName = (typeof SURFACE_NAMES)[number];
+
+function isSurfaceName(value: string | undefined): value is SurfaceName {
+  return SURFACE_NAMES.includes(value as SurfaceName);
+}
+
+/**
+ * Which surfaces this process should bring up. `--mode web` and `--mode
+ * telegram` are the single-surface spellings of `--surfaces`, so a Telegram-only
+ * install needs no port and a web-only one needs no token.
+ */
+function parse(args: ReadonlyArray<string>): ReadonlyArray<SurfaceName> {
+  let requested: string | undefined;
+  let mode: string | undefined;
+  Argv.scan(args, (key, take) => {
+    switch (key) {
+      case "--surfaces":
+        requested = take() ?? requested;
+        break;
+      case "--mode":
+        mode = take() ?? mode;
+        break;
+      default:
+        break;
+    }
+  });
+  if (requested === undefined) {
+    return isSurfaceName(mode) ? [mode] : SURFACE_NAMES;
+  }
+  const names = requested
+    .split(",")
+    .map((name) => name.trim())
+    .filter((name) => name.length > 0);
+  const unknown = names.filter((name) => !isSurfaceName(name));
+  if (names.length === 0 || unknown.length > 0) {
+    throw new Error(
+      `--surfaces takes a comma-separated list of ${SURFACE_NAMES.join(", ")}, got "${requested}"`
+    );
+  }
+  return SURFACE_NAMES.filter((name) => names.includes(name));
+}
+
+function format(names: ReadonlyArray<SurfaceName>): string {
+  return names.join(",");
+}
+
+/** Whether the caller named the surfaces outright, rather than implying them by mode. */
+function named(args: ReadonlyArray<string>): boolean {
+  return args.some(
+    (arg) => arg === "--surfaces" || arg.startsWith("--surfaces=")
+  );
+}
+
+function union(
+  ...groups: ReadonlyArray<ReadonlyArray<SurfaceName>>
+): ReadonlyArray<SurfaceName> {
+  return SURFACE_NAMES.filter((name) =>
+    groups.some((group) => group.includes(name))
+  );
+}
+
+export const Surfaces = { parse, format, named, union };

package/packages/daemon/src/TelegramSurface.ts

@@ -0,0 +1,30 @@
+import type { AgentRuntime } from "#core/session/AgentRuntime";
+import { Bot } from "#telegram/Bot";
+import { Config } from "#telegram/Config";
+import type { Surface } from "./Daemon";
+
+function create(args: ReadonlyArray<string>, runtime: AgentRuntime): Surface {
+  return {
+    name: "telegram",
+    start: async () => {
+      const config = await Config.load(Config.parseArgs(args));
+      const bot = new Bot(config, runtime);
+      await bot.start();
+      return { stop: () => bot.stop() };
+    },
+  };
+}
+
+/** `--print-config`, which resolves the bot's config the way a run would and stops there. */
+async function printConfig(args: ReadonlyArray<string>): Promise<void> {
+  const config = await Config.load(Config.parseArgs(args));
+  console.log(
+    JSON.stringify(
+      { ...config, token: config.token ? "***" : undefined },
+      null,
+      2
+    )
+  );
+}
+
+export const TelegramSurface = { create, printConfig };

package/packages/daemon/src/WebSurface.ts

@@ -0,0 +1,56 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+import { AttachmentStore } from "#core/attachments/AttachmentStore";
+import type { AgentRuntime } from "#core/session/AgentRuntime";
+import { SessionRegistry } from "#core/session/SessionRegistry";
+import { Tools } from "#core/shared/Tools";
+import { defaultAttachmentsRoot } from "#server/AttachmentEndpoint";
+import { SendFileTool } from "#server/SendFileTool";
+import { WebOptions } from "#server/WebOptions";
+import { WsGateway } from "#server/WsGateway";
+import type { Surface } from "./Daemon";
+
+function create(args: ReadonlyArray<string>, runtime: AgentRuntime): Surface {
+  return {
+    name: "web",
+    start: async () => {
+      const options = WebOptions.parse(args);
+      const attachmentsRoot = defaultAttachmentsRoot();
+      const store = new AttachmentStore(attachmentsRoot);
+      const registry = new SessionRegistry({
+        runtime,
+        defaults: { cwd: options.cwd },
+        customTools: ({ cwd, sessionId }) => [
+          Tools.wrap(
+            SendFileTool.build({ store, cwd, sessionId })
+          ) as ToolDefinition,
+        ],
+        surface: "web browser",
+      });
+      await registry.init();
+
+      const gateway = new WsGateway({
+        registry,
+        hostname: options.hostname,
+        port: WebOptions.port(options),
+        attachmentsRoot,
+        ...(options.clientDir === undefined
+          ? {}
+          : { clientDir: options.clientDir }),
+      });
+      gateway.start();
+      process.stderr.write(
+        `pim-server listening on ${gateway.url} (web UI: http://${options.hostname}:${gateway.port})\n`
+      );
+
+      return {
+        stop: async () => {
+          await gateway.stop();
+          await registry.disposeAll();
+        },
+      };
+    },
+  };
+}
+
+export const WebSurface = { create };

package/packages/daemon/src/index.ts

@@ -0,0 +1,37 @@
+import { AgentRuntime } from "#core/session/AgentRuntime";
+import { Daemon, type Surface } from "./Daemon";
+import { Surfaces } from "./Surfaces";
+import { TelegramSurface } from "./TelegramSurface";
+import { WebSurface } from "./WebSurface";
+
+/** Every surface in this process shares one pi installation, and so one `auth.json`. */
+export function build(args: ReadonlyArray<string>): ReadonlyArray<Surface> {
+  const runtime = new AgentRuntime();
+  return Surfaces.parse(args).map((name) =>
+    name === "web"
+      ? WebSurface.create(args, runtime)
+      : TelegramSurface.create(args, runtime)
+  );
+}
+
+export async function start(args: ReadonlyArray<string>): Promise<void> {
+  if (
+    Surfaces.parse(args).includes("telegram") &&
+    args.includes("--print-config")
+  ) {
+    await TelegramSurface.printConfig(args);
+    return;
+  }
+
+  const daemon = new Daemon(build(args));
+  const running = await daemon.start();
+  console.log(`[daemon] serving ${running.join(", ")}`);
+
+  await new Promise<void>((resolve) => {
+    for (const signal of ["SIGINT", "SIGTERM"] as const) {
+      process.once(signal, () => {
+        void daemon.stop().then(resolve);
+      });
+    }
+  });
+}