@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/core",
-  "version": "3.0.0-alpha.2",
+  "version": "3.0.0-alpha.21",
   "description": "Shared utilities, event types, and constants for Unipi extension suite",
   "type": "module",
   "license": "MIT",
@@ -17,8 +17,11 @@
   ],
   "files": [
     "*.ts",
+    "src/**/*.ts",
     "README.md",
-    "!*.test.ts"
+    "!*.test.ts",
+    "!src/**/__tests__/**",
+    "!src/**/*.test.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -41,6 +44,6 @@
     "themes": []
   },
   "scripts": {
-    "test": "npx tsx --test *.test.ts"
+    "test": "npx tsx --test *.test.ts src/*/__tests__/*.test.ts"
   }
 }

package/packages/core/src/attach/detect.ts

@@ -0,0 +1,163 @@
+/**
+ * @pi-unipi/core — attachments: path detection and tokens (pure + fs reads)
+ *
+ * A pasted / dropped / Ctrl+V'd file path in the editor becomes a token:
+ *   images    → [Image #N]  (sent as real image content on submit)
+ *   documents → [File #N]   (expanded back to "[File #N: <path>]" on submit)
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, extname } from "node:path";
+
+export const IMAGE_MIME: Record<string, string> = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+};
+
+const DOC_EXT = new Set([
+  ".pdf", ".txt", ".md", ".csv", ".tsv", ".json", ".yaml", ".yml", ".xml", ".html", ".log",
+  ".docx", ".xlsx", ".pptx", ".odt", ".ods", ".rtf", ".zip", ".svg", ".mp3", ".wav", ".mp4", ".mov",
+]);
+
+export type AttachmentKind = "image" | "file";
+
+export interface Attachment {
+  id: number;
+  kind: AttachmentKind;
+  path: string;
+  name: string;
+  bytes: number;
+  mimeType?: string;
+}
+
+export function tokenFor(a: Pick<Attachment, "kind" | "id">): string {
+  return a.kind === "image" ? `[Image #${a.id}]` : `[File #${a.id}]`;
+}
+
+export function kindOf(path: string): AttachmentKind | undefined {
+  const ext = extname(path).toLowerCase();
+  if (IMAGE_MIME[ext]) return "image";
+  if (DOC_EXT.has(ext)) return "file";
+  return undefined;
+}
+
+/** Candidate path spans: quoted, file:// URIs, and bare absolute or ~ paths (escaped spaces ok). */
+const CANDIDATE = /'(\/[^'\n]+|~\/[^'\n]+)'|"(\/[^"\n]+|~\/[^"\n]+)"|(file:\/\/\/[^\s'"]+)|((?:~|\/)(?:[^\s'"\\]|\\ )+)/g;
+
+function normalize(raw: string): string {
+  let p = raw;
+  if (p.startsWith("file://")) {
+    try {
+      p = decodeURIComponent(p.slice("file://".length));
+    } catch {
+      p = p.slice("file://".length);
+    }
+  }
+  p = p.replace(/\\ /g, " ");
+  if (p.startsWith("~/")) p = homedir() + p.slice(1);
+  return p;
+}
+
+export interface Found {
+  /** Exact text in the editor to replace. */
+  raw: string;
+  path: string;
+  kind: AttachmentKind;
+}
+
+/** Existing, attachable files mentioned in `text` (first occurrence each). */
+export function findPaths(text: string, exists: (p: string) => boolean = (p) => existsSync(p) && statSync(p).isFile()): Found[] {
+  const out: Found[] = [];
+  for (const m of text.matchAll(CANDIDATE)) {
+    const raw = m[0];
+    const path = normalize(m[1] ?? m[2] ?? m[3] ?? m[4] ?? "");
+    const kind = kindOf(path);
+    if (!kind || out.some((f) => f.path === path)) continue;
+    try {
+      if (!exists(path)) continue;
+    } catch {
+      continue;
+    }
+    out.push({ raw, path, kind });
+  }
+  return out;
+}
+
+/** Replace found paths with tokens; returns the new text and new attachments. */
+export function tokenize(
+  text: string,
+  existing: readonly Attachment[],
+  size: (p: string) => number = (p) => statSync(p).size,
+  exists?: (p: string) => boolean,
+): { text: string; added: Attachment[] } {
+  let next = text;
+  let id = existing.reduce((m, a) => Math.max(m, a.id), 0);
+  const added: Attachment[] = [];
+  for (const f of findPaths(text, exists)) {
+    const reuse = [...existing, ...added].find((a) => a.path === f.path);
+    const a: Attachment = reuse ?? {
+      id: ++id,
+      kind: f.kind,
+      path: f.path,
+      name: basename(f.path),
+      bytes: (() => {
+        try {
+          return size(f.path);
+        } catch {
+          return 0;
+        }
+      })(),
+      ...(f.kind === "image" ? { mimeType: IMAGE_MIME[extname(f.path).toLowerCase()] } : {}),
+    };
+    if (!reuse) added.push(a);
+    next = next.split(f.raw).join(tokenFor(a));
+  }
+  return { text: next, added };
+}
+
+/** Attachments whose token is still in the text. */
+export function stillReferenced(text: string, attachments: readonly Attachment[]): Attachment[] {
+  return attachments.filter((a) => text.includes(tokenFor(a)));
+}
+
+export interface ImagePart {
+  type: "image";
+  data: string;
+  mimeType: string;
+}
+
+/**
+ * Submit-time expansion: images become image content (in token order), file
+ * tokens become "[File #N: <path>]" so the model can read them.
+ */
+export function expandForSubmit(
+  text: string,
+  attachments: readonly Attachment[],
+  read: (p: string) => Buffer = (p) => readFileSync(p),
+): { text: string; images: ImagePart[] } {
+  const used = stillReferenced(text, attachments).sort((a, b) => text.indexOf(tokenFor(a)) - text.indexOf(tokenFor(b)));
+  const images: ImagePart[] = [];
+  let out = text;
+  for (const a of used) {
+    if (a.kind === "file") {
+      out = out.split(tokenFor(a)).join(`[File #${a.id}: ${a.path}]`);
+      continue;
+    }
+    try {
+      images.push({ type: "image", data: read(a.path).toString("base64"), mimeType: a.mimeType ?? "image/png" });
+    } catch {
+      out = out.split(tokenFor(a)).join(`[Image #${a.id}: ${a.path} (unreadable)]`);
+    }
+  }
+  return { text: out, images };
+}
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${Math.round(bytes / 1024)} KB`;
+  return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}

package/packages/core/src/child-agent/child-args.ts

@@ -0,0 +1,31 @@
+/**
+ * Extension-selection flags the sidekick child must inherit from the lead's
+ * argv — otherwise `pi --no-extensions -e <repo>` still lets the child pick
+ * up the globally installed suite. Pure: reads a plain argv array.
+ */
+
+export function leadExtensionArgs(argv: readonly string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--extension" || arg === "-e") {
+      const value = argv[i + 1];
+      if (value !== undefined) {
+        out.push("--extension", value);
+        i++;
+      }
+    } else if (arg === "--no-extensions" || arg === "-ne") {
+      out.push("--no-extensions");
+    } else if (arg === "--skill") {
+      const value = argv[i + 1];
+      if (value !== undefined) {
+        out.push("--skill", value);
+        i++;
+      }
+    }
+    // --no-skills is unconditional below: the child never needs skill
+    // discovery; the parent's --no-skills is preserved anyway.
+  }
+  out.push("--no-skills");
+  return out;
+}

package/packages/core/src/child-agent/delivery.ts

@@ -0,0 +1,41 @@
+/**
+ * Exactly-once completion delivery for handoffs nobody is waiting on.
+ *
+ * `attach`/`detach` bracket every waiting period. The completion is sent only
+ * if the report lands (or has already landed) while no waiter is attached, and
+ * only once per handoff id.
+ */
+export function createCompletionDelivery<TReport>(
+  send: (report: TReport) => void,
+): {
+  attach(id: string): void;
+  detach(id: string, done: Promise<TReport>): void;
+  consume(id: string): void;
+} {
+  const waiting = new Set<string>();
+  const armed = new Set<string>();
+  const delivered = new Set<string>();
+
+  return {
+    attach(id) {
+      waiting.add(id);
+    },
+    detach(id, done) {
+      waiting.delete(id);
+      // One continuation per handoff, however many times a waiter gives up.
+      if (armed.has(id)) return;
+      armed.add(id);
+      void done
+        .then((report) => {
+          if (waiting.has(id) || delivered.has(id)) return;
+          delivered.add(id);
+          send(report);
+        })
+        .catch(() => undefined);
+    },
+    consume(id) {
+      waiting.delete(id);
+      delivered.add(id);
+    },
+  };
+}

package/packages/core/src/child-agent/index.ts

@@ -0,0 +1,5 @@
+export * from "./pi-spawn.js";
+export * from "./child-args.js";
+export * from "./runtime.js";
+export * from "./readers.js";
+export * from "./delivery.js";

package/packages/core/src/child-agent/readers.ts

@@ -0,0 +1,203 @@
+/**
+ * Shared `read_subagent` registry: owners (fusion sidekick, subagents) register
+ * readers keyed by agent_id ownership. The tool itself is registered once by
+ * whichever package loads first, and dispatches to the owning reader.
+ *
+ * Demand: `setReadSubagentDemand(pi, owner, wanted)` — `read_subagent` stays in
+ * pi's active tool set iff at least one owner wants it; other tools untouched.
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export interface SubagentReadParams {
+  agent_id?: string;
+  block?: boolean;
+  timeout?: number;
+}
+
+export interface SubagentReader {
+  /** True when `agent_id` belongs to this owner (undefined = can't tell). */
+  owns(id: string, ctx?: ExtensionContext): boolean;
+  /** The owner's newest handoff/subagent (id + start time) or undefined. */
+  latest(ctx?: ExtensionContext): { id: string; startedAt: number } | undefined;
+  read(params: SubagentReadParams, signal: AbortSignal | undefined, onUpdate: ((u: unknown) => void) | undefined, ctx: ExtensionContext): Promise<unknown>;
+}
+
+export interface RegisteredReader extends SubagentReader {
+  owner: string;
+}
+
+const readers: RegisteredReader[] = [];
+const demand = new Map<string, boolean>();
+
+export function registerSubagentReader(owner: string, reader: SubagentReader): RegisteredReader {
+  const entry: RegisteredReader = { owner, ...reader };
+  const existing = readers.findIndex((r) => r.owner === owner);
+  if (existing >= 0) readers[existing] = entry;
+  else readers.push(entry);
+  return entry;
+}
+
+export function subagentReaders(): readonly RegisteredReader[] {
+  return readers;
+}
+
+export function readerFor(id: string | undefined, ctx?: ExtensionContext): RegisteredReader | undefined {
+  if (id !== undefined) return readers.find((r) => r.owns(id, ctx)) ?? readers.find((r) => r.latest(ctx)?.id === id);
+  let best: RegisteredReader | undefined;
+  let bestAt = -1;
+  for (const r of readers) {
+    const at = r.latest(ctx)?.startedAt ?? -1;
+    if (at > bestAt) { bestAt = at; best = r; }
+  }
+  return best;
+}
+
+/** Recompute and apply `read_subagent` presence in pi's active tool set. */
+export function setReadSubagentDemand(pi: Pick<ExtensionAPI, "getActiveTools" | "setActiveTools">, owner: string, wanted: boolean): void {
+  demand.set(owner, wanted);
+  const want = [...demand.values()].some(Boolean);
+  const current = pi.getActiveTools();
+  const has = current.includes("read_subagent");
+  if (has === want) return;
+  pi.setActiveTools(want ? [...current, "read_subagent"] : current.filter((t) => t !== "read_subagent"));
+}
+
+/** Test hook: clear all registrations (incl. the registered tool flag). */
+export function resetSubagentRegistry(): void {
+  readers.length = 0;
+  demand.clear();
+  toolOwner = undefined;
+}
+
+// ── The shared read_subagent tool (registered once, dispatches by owner) ────
+
+import { Box, Text, type Component } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { badge, leader, spinner, SPINNER_MS, STATE_BADGE, STATE_COLOR, type KitTheme, type RunState } from "../tui/kit.js";
+
+const ReadSubagentParams = Type.Object({
+  agent_id: Type.Optional(Type.String({ description: "Subagent or sidekick id; omit for the most recent" })),
+  block: Type.Optional(Type.Boolean({ description: "Wait for completion (default false)" })),
+  timeout: Type.Optional(Type.Number({ description: "Maximum wait in seconds (default 30, max 600)" })),
+});
+
+let toolOwner: ExtensionAPI | undefined;
+
+interface ReadDetails {
+  owner?: string;
+  title?: string;
+  profile?: string;
+  status?: string;
+  toolCalls?: number;
+}
+
+/** Shared state for one read_subagent row (call + result renderers). */
+interface ReadState {
+  owner?: string;
+  title?: string;
+  final?: boolean;
+  startedAt?: number;
+  timer?: ReturnType<typeof setInterval>;
+}
+
+interface ReadContext {
+  state: ReadState;
+  invalidate(): void;
+}
+
+const lines = (render: (w: number) => string[]): Component => ({ invalidate() {}, render });
+const secs = (ms: number) => `${String(Math.max(0, Math.floor(ms / 1000)))}s`;
+
+/**
+ * Subagent reads are background work → badge lines:
+ *   WAIT  Map auth flow ······················· ⢎⡱ 12s
+ *   GOT   Map auth flow ······················· completed · 5 tool calls
+ * The call line shows while waiting; the result line replaces it.
+ */
+/**
+ * Sidekick reads keep pi's tinted tool box (fusion's choice): the tool renders
+ * itself (renderShell "self") so subagent reads can go boxless, and this
+ * repaints the standard box for everyone else.
+ */
+function toolBox(theme: KitTheme, bg: "toolPendingBg" | "toolSuccessBg" | "toolErrorBg", text: string): Component {
+  const paint = (theme as KitTheme & { bg?: (c: string, s: string) => string }).bg;
+  // Call as a method: pi's Theme.bg reads this.bgColors, so a detached call crashes the TUI.
+  const box = new Box(1, 1, paint ? (s: string) => paint.call(theme, bg, s) : undefined);
+  box.addChild(new Text(text, 0, 0));
+  return box;
+}
+
+const noContext = (): ReadContext => ({ state: {}, invalidate() {} });
+
+function renderReadCall(args: SubagentReadParams, theme: KitTheme, context: ReadContext = noContext()): Component {
+  const st = context.state;
+  st.owner ??= readerFor(args.agent_id)?.owner;
+  st.startedAt ??= Date.now();
+  if (st.owner !== "subagents") {
+    if (st.final) return lines(() => []);
+    return toolBox(theme, "toolPendingBg", `${theme.fg("toolTitle", theme.bold("● read_subagent"))} ${theme.fg("dim", args.block === true ? "· waiting" : "· snapshot")}`);
+  }
+  if (args.block === true && !st.final && st.timer === undefined) {
+    st.timer = setInterval(() => context.invalidate(), SPINNER_MS);
+    st.timer.unref?.();
+  }
+  return lines((w) => {
+    if (st.final) return [];
+    const who = st.title ?? args.agent_id ?? "latest subagent";
+    const right = args.block === true ? `${spinner(theme)} ${theme.fg("dim", secs(Date.now() - (st.startedAt ?? Date.now())))}` : theme.fg("dim", "checking…");
+    return [leader(theme, `${badge(theme, "accent", args.block === true ? "WAIT" : "READ")} ${who}`, right, w)];
+  });
+}
+
+function renderReadResult(result: { details?: unknown; isError?: boolean }, opts: { isPartial?: boolean }, theme: KitTheme, context: ReadContext = noContext()): Component {
+  const d = result.details as ReadDetails | undefined;
+  const st = context.state;
+  if (d?.owner) st.owner = d.owner;
+  if (d?.title) st.title = d.title;
+  if (st.owner === "subagents") {
+    if (opts.isPartial) return lines(() => []);
+    if (st.timer) clearInterval(st.timer);
+    st.timer = undefined;
+    st.final = true;
+    const status = d?.status ?? (result.isError === true ? "failed" : "completed");
+    const state = (status in STATE_COLOR ? status : "failed") as RunState;
+    const label = state === "running" ? "READ" : state === "completed" ? "GOT " : STATE_BADGE[state];
+    const chip = badge(theme, STATE_COLOR[state], label);
+    const bits = [state === "running" ? "still running" : status, d?.toolCalls !== undefined ? `${String(d.toolCalls)} tool call${d.toolCalls === 1 ? "" : "s"}` : ""].filter(Boolean);
+    return lines((w) => [leader(theme, `${chip} ${d?.title ?? st.title ?? "subagent"}`, theme.fg("dim", bits.join(" · ")), w)]);
+  }
+  // Sidekick/fusion reads keep the compact ◆ status line in a tool box; the
+  // call box above is dropped once the result box replaces it.
+  if (!opts.isPartial) st.final = true;
+  const status = d?.status ?? "done";
+  const err = result.isError === true;
+  return toolBox(theme, opts.isPartial ? "toolPendingBg" : err ? "toolErrorBg" : "toolSuccessBg", `${theme.fg(err ? "error" : "accent", err ? "✗" : "◆")} ${theme.fg("toolTitle", theme.bold(`read_subagent ${status}`))}`);
+}
+
+/**
+ * Register the shared `read_subagent` tool (idempotent — the first loader
+ * wins). Owners must have registered a reader via `registerSubagentReader`.
+ */
+export function ensureReadSubagentTool(pi: ExtensionAPI): void {
+  if (toolOwner === pi) return;
+  toolOwner = pi;
+  pi.registerTool({
+    name: "read_subagent",
+    label: "Read Subagent",
+    description:
+      "Read a subagent's or the sidekick's result by agent_id (omit for the most recent). block:true waits for completion up to timeout seconds (default 30, max 600); block:false returns the current status immediately.",
+    parameters: ReadSubagentParams,
+    renderShell: "self",
+    renderCall: (args: SubagentReadParams, theme, context) => renderReadCall(args, theme, context as unknown as ReadContext),
+    renderResult: (result, options, theme, context) => renderReadResult(result as never, options, theme, context as unknown as ReadContext),
+    async execute(_toolCallId, params: SubagentReadParams, signal, onUpdate, ctx) {
+      const reader = readerFor(params.agent_id, ctx);
+      if (!reader) {
+        return { content: [{ type: "text" as const, text: params.agent_id !== undefined ? `No subagent found for ${params.agent_id}.` : "No subagent has run yet." }], details: {}, isError: true };
+      }
+      const timeoutSec = Math.min(600, params.timeout ?? 30);
+      return (await reader.read({ ...params, timeout: timeoutSec }, signal, onUpdate === undefined ? undefined : (u) => onUpdate(u as never), ctx)) as never;
+    },
+  });
+}