@akanjs/devkit 3.0.0-beta.9 → 3.0.0

package/codeAgent/agent/CodeAgentStreamPrinter.ts

@@ -0,0 +1,86 @@
+import { type CodeAgentEvent, codeAgentEventLabel } from "akanjs/common";
+import chalk from "chalk";
+
+export interface CodeAgentStreamPrinterOptions {
+  /** One JSON object per line instead of prose, for a pipe that parses. */
+  json?: boolean;
+  thinking?: boolean;
+  write?: (text: string) => void;
+}
+
+export class CodeAgentStreamPrinter {
+  readonly #options: CodeAgentStreamPrinterOptions;
+  readonly #write: (text: string) => void;
+  #streaming = false;
+
+  constructor(options: CodeAgentStreamPrinterOptions = {}) {
+    this.#options = options;
+    this.#write = options.write ?? ((text) => process.stdout.write(text));
+  }
+
+  print(event: CodeAgentEvent) {
+    if (this.#options.json) return this.#write(`${JSON.stringify(event)}\n`);
+    switch (event.type) {
+      case "text_delta":
+        this.#streaming = true;
+        return this.#write(event.text);
+      case "thinking_delta":
+        if (!this.#options.thinking) return;
+        this.#streaming = true;
+        return this.#write(chalk.dim(event.text));
+      case "tool_start":
+        return this.#line(chalk.cyan(`→ ${event.tool.title}`));
+      case "tool_end":
+        return this.#line(CodeAgentStreamPrinter.#toolEnd(event));
+      case "session":
+        return this.#line(chalk.dim(codeAgentEventLabel(event)));
+      case "turn_end":
+        // Only `truncated` is said: a cut answer looks exactly like a finished one.
+        if (event.stopReason === "truncated") return this.#line(chalk.yellow(codeAgentEventLabel(event)));
+        return;
+      case "message":
+      case "tool_progress":
+      case "turn_start":
+      case "idle":
+      case "queue":
+      case "context":
+      // A stream has no rail to redraw; the pool already reports a child's start and cost as notices.
+      case "subagent":
+        return;
+      case "question":
+        return this.#line(chalk.yellow(`? ${event.question.prompt}`));
+      case "approval":
+        return this.#line(chalk.yellow(`approve? ${event.request.summary}`));
+      case "notice":
+        return this.#line(CodeAgentStreamPrinter.#notice(event.level, event.message));
+      case "error":
+        return this.#line(chalk.red(`error: ${event.message}`));
+      default:
+        return this.#line(chalk.dim(codeAgentEventLabel(event)));
+    }
+  }
+
+  /** Closes a half-written streamed line so the exit code and the shell prompt do not land mid-sentence. */
+  finish() {
+    if (this.#streaming) this.#write("\n");
+    this.#streaming = false;
+  }
+
+  #line(text: string) {
+    if (this.#streaming) this.#write("\n");
+    this.#streaming = false;
+    this.#write(`${text}\n`);
+  }
+
+  static #toolEnd(event: Extract<CodeAgentEvent, { type: "tool_end" }>) {
+    if (event.outcome === "ok") return chalk.green(`✓ ${event.tool.title}`);
+    if (event.outcome === "blocked") return chalk.yellow(`⦸ ${event.tool.title} — ${event.output}`);
+    return chalk.red(`✗ ${event.tool.title} — ${event.output.split("\n")[0] ?? ""}`);
+  }
+
+  static #notice(level: "info" | "warning" | "error", message: string) {
+    if (level === "error") return chalk.red(message);
+    if (level === "warning") return chalk.yellow(message);
+    return chalk.dim(message);
+  }
+}

package/codeAgent/agent/CodeAgentSuspended.ts

@@ -0,0 +1,85 @@
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import type { CodeAgentApprovalRequest, CodeAgentQuestion } from "akanjs/common";
+
+interface SuspendedState {
+  question?: CodeAgentQuestion;
+  approvals: CodeAgentApprovalRequest[];
+}
+
+// Taking an ask removes it, which makes an answer idempotent: a second tab or a retried frame finds nothing.
+export class CodeAgentSuspended {
+  readonly #file: string | null;
+  #state: SuspendedState;
+
+  constructor(file: string | null) {
+    this.#file = file;
+    this.#state = CodeAgentSuspended.#read(file);
+  }
+
+  static fileOf(sessionDir: string | undefined, sessionId: string) {
+    return sessionDir ? path.join(sessionDir, `${sessionId}.suspended.json`) : null;
+  }
+
+  get question() {
+    return this.#state.question;
+  }
+
+  get approvals(): readonly CodeAgentApprovalRequest[] {
+    return this.#state.approvals;
+  }
+
+  //* A new question replaces the old one: asking ends the turn, so the earlier question has nobody left to answer it.
+  setQuestion(question: CodeAgentQuestion) {
+    this.#state = { ...this.#state, question };
+    this.#save();
+  }
+
+  addApproval(request: CodeAgentApprovalRequest) {
+    this.#state = { ...this.#state, approvals: [...this.#state.approvals, request] };
+    this.#save();
+  }
+
+  takeQuestion(questionId: string) {
+    const question = this.#state.question;
+    if (question?.questionId !== questionId) return undefined;
+    this.#state = { approvals: this.#state.approvals };
+    this.#save();
+    return question;
+  }
+
+  takeApproval(approvalId: string) {
+    const request = this.#state.approvals.find((approval) => approval.approvalId === approvalId);
+    if (!request) return undefined;
+    this.#state = { ...this.#state, approvals: this.#state.approvals.filter((approval) => approval !== request) };
+    this.#save();
+    return request;
+  }
+
+  //* A prompt the user typed instead of answering moves the conversation on; the parked asks belong to a turn it replaced.
+  clear() {
+    if (!this.#state.question && !this.#state.approvals.length) return;
+    this.#state = { approvals: [] };
+    this.#save();
+  }
+
+  #save() {
+    if (!this.#file) return;
+    if (!this.#state.question && !this.#state.approvals.length) {
+      rmSync(this.#file, { force: true });
+      return;
+    }
+    mkdirSync(path.dirname(this.#file), { recursive: true });
+    writeFileSync(this.#file, `${JSON.stringify(this.#state)}\n`);
+  }
+
+  static #read(file: string | null): SuspendedState {
+    if (!file || !existsSync(file)) return { approvals: [] };
+    try {
+      const parsed = JSON.parse(readFileSync(file, "utf8")) as Partial<SuspendedState>;
+      return { ...(parsed.question ? { question: parsed.question } : {}), approvals: parsed.approvals ?? [] };
+    } catch {
+      return { approvals: [] };
+    }
+  }
+}

package/codeAgent/agent/CodeAgentUi.ts

@@ -0,0 +1,47 @@
+import type { ExtensionUIContext } from "@earendil-works/pi-coding-agent";
+
+export interface CodeAgentUiHandlers {
+  ask(prompt: string, kind: "text" | "select" | "confirm", choices?: string[]): Promise<string | undefined>;
+  notify(level: "info" | "warning" | "error", message: string): void;
+}
+
+// Only the dialogs and `notify` mean anything off the engine's TUI; the rest are no-ops, not throws, so an
+// extension that sets a status line does not take the turn down with it.
+export class CodeAgentUi {
+  readonly #handlers: CodeAgentUiHandlers;
+
+  constructor(handlers: CodeAgentUiHandlers) {
+    this.#handlers = handlers;
+  }
+
+  context(): ExtensionUIContext {
+    const noop = () => {};
+    const ui = {
+      select: async (title: string, options: string[]) => await this.#handlers.ask(title, "select", options),
+      confirm: async (title: string, message: string) => {
+        const answer = await this.#handlers.ask(message ? `${title}: ${message}` : title, "confirm");
+        return answer === "yes" || answer === "true";
+      },
+      input: async (title: string) => await this.#handlers.ask(title, "text"),
+      notify: (message: string, type: "info" | "warning" | "error" = "info") => this.#handlers.notify(type, message),
+      editor: async (title: string, prefill?: string) => (await this.#handlers.ask(title, "text")) ?? prefill,
+      onTerminalInput: () => noop,
+      setStatus: noop,
+      setWorkingMessage: noop,
+      setWorkingVisible: noop,
+      setWorkingIndicator: noop,
+      setHiddenThinkingLabel: noop,
+      setWidget: noop,
+      setFooter: noop,
+      setHeader: noop,
+      setTitle: noop,
+      custom: async () => undefined,
+      pasteToEditor: noop,
+      setEditorText: noop,
+      getEditorText: () => "",
+      addAutocompleteProvider: noop,
+      setCustomEditorComponent: noop,
+    };
+    return ui as unknown as ExtensionUIContext;
+  }
+}

package/codeAgent/agent/CodeMailbox.ts

@@ -0,0 +1,148 @@
+import {
+  appendFileSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import path from "node:path";
+import { parseJsonLine, readJsonLines } from "./jsonLines";
+
+export interface CodePeer {
+  id: string;
+  name: string;
+  cwd: string;
+  pid: number;
+  /** When the session last said it was alive. */
+  at: number;
+}
+
+export interface CodeMail {
+  at: number;
+  from: string;
+  fromName: string;
+  text: string;
+}
+
+// A directory, not a socket or daemon: it survives either end restarting and needs nothing listening.
+// Presence is a heartbeat file, not a registration, so a session that died silently goes stale on its own.
+export class CodeMailbox {
+  static readonly staleMs = 20_000;
+  static readonly beatMs = 5_000;
+  static readonly pollMs = 1_500;
+  /** How many messages one session may send in a minute, so two agents answering each other cannot run away. */
+  static readonly sendsPerMinute = 20;
+
+  readonly #dir: string;
+  readonly #id: string;
+  #name: string;
+  #read = 0;
+  #sent: number[] = [];
+  #beat: ReturnType<typeof setInterval> | null = null;
+  #poll: ReturnType<typeof setInterval> | null = null;
+
+  constructor(dir: string, id: string, name: string) {
+    this.#dir = dir;
+    this.#id = id;
+    this.#name = name;
+  }
+
+  get inbox() {
+    return path.join(this.#dir, "inbox", `${this.#id}.jsonl`);
+  }
+
+  /** Announces this session and starts delivering what arrives for it. */
+  open(cwd: string, onMail: (mail: CodeMail) => void) {
+    mkdirSync(path.join(this.#dir, "live"), { recursive: true });
+    mkdirSync(path.join(this.#dir, "inbox"), { recursive: true });
+    // What is already in the inbox belongs to an earlier run; delivering it would replay a past conversation.
+    this.#read = readJsonLines(this.inbox).length;
+    this.beat(cwd);
+    this.#beat = setInterval(() => this.beat(cwd), CodeMailbox.beatMs);
+    this.#poll = setInterval(() => {
+      for (const mail of this.#drain()) onMail(mail);
+    }, CodeMailbox.pollMs);
+  }
+
+  close() {
+    if (this.#beat) clearInterval(this.#beat);
+    if (this.#poll) clearInterval(this.#poll);
+    this.#beat = null;
+    this.#poll = null;
+    try {
+      rmSync(path.join(this.#dir, "live", `${this.#id}.json`), { force: true });
+    } catch {
+      // A leftover presence file goes stale on its own; failing to remove it is not worth an error.
+    }
+  }
+
+  rename(name: string, cwd: string) {
+    this.#name = name;
+    this.beat(cwd);
+  }
+
+  beat(cwd: string) {
+    const peer: CodePeer = { id: this.#id, name: this.#name, cwd, pid: process.pid, at: Date.now() };
+    try {
+      writeFileSync(path.join(this.#dir, "live", `${this.#id}.json`), JSON.stringify(peer));
+    } catch {
+      // A read-only or missing directory means no presence; messaging then simply finds nobody.
+    }
+  }
+
+  /** The live sessions of this workspace, this one excluded — it is not a peer of itself. */
+  peers(): CodePeer[] {
+    const dir = path.join(this.#dir, "live");
+    if (!existsSync(dir)) return [];
+    const now = Date.now();
+    return readdirSync(dir)
+      .filter((entry) => entry.endsWith(".json"))
+      .map((entry) => CodeMailbox.#peer(path.join(dir, entry)))
+      .filter((peer): peer is CodePeer => !!peer && peer.id !== this.#id && now - peer.at < CodeMailbox.staleMs)
+      .sort((left, right) => right.at - left.at);
+  }
+
+  /** Resolves what a person typed — a name, or the front of an id — to exactly one peer. */
+  find(target: string) {
+    const needle = target.trim().toLowerCase();
+    const peers = this.peers();
+    const byName = peers.filter((peer) => peer.name.toLowerCase() === needle);
+    if (byName.length === 1) return byName[0];
+    const byPrefix = peers.filter((peer) => peer.id.startsWith(needle) || peer.name.toLowerCase().startsWith(needle));
+    return byPrefix.length === 1 ? byPrefix[0] : undefined;
+  }
+
+  send(to: string, text: string) {
+    const now = Date.now();
+    this.#sent = this.#sent.filter((at) => now - at < 60_000);
+    if (this.#sent.length >= CodeMailbox.sendsPerMinute)
+      throw new Error(`Too many messages: ${CodeMailbox.sendsPerMinute} a minute is the ceiling.`);
+    this.#sent.push(now);
+    const mail: CodeMail = { at: now, from: this.#id, fromName: this.#name, text };
+    mkdirSync(path.join(this.#dir, "inbox"), { recursive: true });
+    // Append, never rewrite: two senders may be writing at the same moment, and one line is one write.
+    appendFileSync(path.join(this.#dir, "inbox", `${to}.jsonl`), `${JSON.stringify(mail)}\n`);
+  }
+
+  #drain(): CodeMail[] {
+    const lines = readJsonLines(this.inbox);
+    if (lines.length <= this.#read) return [];
+    const fresh = lines.slice(this.#read);
+    this.#read = lines.length;
+    return fresh
+      .map((line) => parseJsonLine<CodeMail>(line))
+      .filter((mail): mail is CodeMail => !!mail?.text && typeof mail.from === "string");
+  }
+
+  static #peer(file: string) {
+    try {
+      const peer = JSON.parse(readFileSync(file, "utf8")) as CodePeer;
+      return typeof peer.id === "string" ? { ...peer, at: peer.at || statSync(file).mtimeMs } : undefined;
+    } catch {
+      return undefined;
+    }
+  }
+}

package/codeAgent/agent/CodeSessionFork.ts

@@ -0,0 +1,56 @@
+import { randomBytes } from "node:crypto";
+import { readFileSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { codeAgentSessionName } from "akanjs/common";
+import { CodeSessionIndex } from "./CodeSessionIndex";
+import { parseJsonLine } from "./jsonLines";
+
+interface CodeSessionRecord {
+  [key: string]: unknown;
+  type?: string;
+  id?: string;
+}
+
+// Only the `session` record's id is rewritten: a shared id would give two agents one inbox and one resume target.
+export class CodeSessionFork {
+  static fork(dir: string, id: string, name?: string) {
+    const source = CodeSessionIndex.fileOf(dir, id);
+    if (!source) throw new Error(`No stored session ${id} in ${dir}`);
+    const lines = readFileSync(source, "utf8")
+      .split("\n")
+      .filter((line) => !!line.trim());
+    if (!lines.length) throw new Error(`Session ${id} has nothing in it to fork`);
+    const at = new Date();
+    const forked = Bun.randomUUIDv7();
+    const records = lines
+      .map((line) => parseJsonLine<CodeSessionRecord>(line))
+      .filter((record): record is CodeSessionRecord => !!record);
+    const first = records.find((record) => record.type === "session");
+    if (!first) throw new Error(`Session ${id} carries no session record`);
+    first.id = forked;
+    first.timestamp = at.toISOString();
+    records.push(CodeSessionFork.#named(records, name ?? CodeSessionFork.#nameOf(records), at));
+    // The engine's own file-name shape, which `CodeSessionIndex.fileOf` matches a resume against.
+    const file = path.join(dir, `${at.toISOString().replace(/[:.]/g, "-")}_${forked}.jsonl`);
+    writeFileSync(file, `${records.map((record) => JSON.stringify(record)).join("\n")}\n`);
+    return { id: forked, file };
+  }
+
+  /** A rename is an appended record, so the fork is named by adding one rather than by editing the original. */
+  static #named(records: CodeSessionRecord[], name: string, at: Date) {
+    const parent = records.at(-1)?.id;
+    return {
+      type: "session_info",
+      id: randomBytes(4).toString("hex"),
+      parentId: typeof parent === "string" ? parent : null,
+      timestamp: at.toISOString(),
+      name,
+    };
+  }
+
+  static #nameOf(records: CodeSessionRecord[]) {
+    const named = records.filter((record) => record.type === "session_info").at(-1);
+    const current = typeof named?.name === "string" ? named.name : "";
+    return codeAgentSessionName(current ? `${current} fork` : "fork");
+  }
+}

package/codeAgent/agent/CodeSessionIndex.ts

@@ -0,0 +1,78 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { parseJsonLine, readJsonLines } from "./jsonLines";
+
+export interface CodeSessionEntry {
+  id: string;
+  file: string;
+  /** What the session calls itself, when it was named. */
+  name: string | undefined;
+  /** The first thing the person asked, which is what a list of sessions is actually scanned for. */
+  opening: string;
+  updatedAt: number;
+  turns: number;
+}
+
+// Read as files: the engine's session manager has nothing that enumerates the directory.
+export class CodeSessionIndex {
+  static readonly readLimit = 512 * 1024;
+
+  static list(dir: string, limit = 30): CodeSessionEntry[] {
+    if (!existsSync(dir)) return [];
+    const files = readdirSync(dir)
+      .filter((entry) => entry.endsWith(".jsonl"))
+      .map((entry) => path.join(dir, entry))
+      .map((file) => ({ file, updatedAt: CodeSessionIndex.#mtime(file) }))
+      .sort((left, right) => right.updatedAt - left.updatedAt)
+      .slice(0, limit);
+    return files
+      .map((entry) => CodeSessionIndex.#read(entry.file, entry.updatedAt))
+      .filter((entry): entry is CodeSessionEntry => !!entry);
+  }
+
+  static fileOf(dir: string, id: string) {
+    if (!existsSync(dir)) return undefined;
+    // The file name carries the id after its timestamp, so the directory is searched without reading anything.
+    const match = readdirSync(dir).find((entry) => entry.endsWith(`${id}.jsonl`) || entry === `${id}.jsonl`);
+    return match ? path.join(dir, match) : undefined;
+  }
+
+  static #mtime(file: string) {
+    try {
+      return statSync(file).mtimeMs;
+    } catch {
+      return 0;
+    }
+  }
+
+  static #read(file: string, updatedAt: number): CodeSessionEntry | undefined {
+    const lines = readJsonLines(file, CodeSessionIndex.readLimit);
+    if (!lines.length) return undefined;
+    const entry: CodeSessionEntry = { id: "", file, name: undefined, opening: "", updatedAt, turns: 0 };
+    for (const line of lines) {
+      const record = parseJsonLine<{ [key: string]: unknown; type?: string }>(line);
+      if (!record) continue;
+      if (record.type === "session" && typeof record.id === "string") entry.id = record.id;
+      // A rename appends a second entry rather than editing the first, so the last one on the file wins.
+      if (record.type === "session_info" && typeof record.name === "string") entry.name = record.name;
+      if (record.type !== "message") continue;
+      const message = record.message as { role?: string; content?: unknown } | undefined;
+      if (message?.role !== "user") continue;
+      entry.turns += 1;
+      if (!entry.opening) entry.opening = CodeSessionIndex.#text(message.content);
+    }
+    return entry.id ? entry : undefined;
+  }
+
+  static #text(content: unknown) {
+    const text =
+      typeof content === "string"
+        ? content
+        : Array.isArray(content)
+          ? content
+              .map((part) => (typeof part === "object" && part && "text" in part ? String(part.text) : ""))
+              .join(" ")
+          : "";
+    return text.replace(/\s+/g, " ").trim();
+  }
+}