pim-agent 0.0.1 → 0.10.0

package/packages/core/src/session/SessionRegistry.ts

@@ -0,0 +1,244 @@
+import {
+  SessionManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+
+import { Directories } from "../shared/Directories";
+import { Pool } from "../shared/Pool";
+import type { Surface } from "../shared/Surface";
+import { AgentRuntime, type ModelChoice } from "./AgentRuntime";
+import { EventLog } from "./EventLog";
+import { SessionCache } from "./SessionCache";
+import {
+  SessionHost,
+  type CustomToolContext,
+  type HostSettings,
+} from "./SessionHost";
+import { SessionLease } from "./SessionLease";
+import { SessionName } from "./SessionName";
+
+/** A session as pi stores it: one JSONL file under a cwd-encoded directory. */
+export type SessionSummary = {
+  readonly sessionId: string;
+  readonly cwd: string;
+  readonly path: string;
+  readonly createdAt: number;
+  readonly modifiedAt: number;
+};
+
+export type SessionRegistryDeps = {
+  readonly defaults: { readonly cwd: string; readonly model?: string };
+  /** The process-wide pi installation; one is built here when a caller has none to share. */
+  readonly runtime?: AgentRuntime;
+  /** Where auth, models, settings and sessions live; must agree with pi's own `getAgentDir()`. */
+  readonly agentDir?: string;
+  readonly capacity?: number;
+  readonly customTools?: (
+    context: CustomToolContext
+  ) => readonly ToolDefinition[];
+  /** Appended to every session's system prompt. */
+  readonly systemInstruction?: () => Promise<string | undefined>;
+  /** Where this frontend's human is reading. */
+  readonly surface?: Surface;
+};
+
+export type SessionCreateOptions = {
+  readonly cwd?: string;
+  /** Open the new session like this one: model, chosen thinking level, and cwd when none is given. */
+  readonly like?: SessionHost;
+};
+
+/** A session tree is thousands of files and each header is one open; fanning out over all of them at once is how a listing runs the process out of descriptors. */
+const HEADER_READS = 32;
+
+/** Live sessions keyed on pi's session UUID; the catalogue is pi's sessions directory, read on demand. */
+export class SessionRegistry {
+  private readonly deps: SessionRegistryDeps;
+  private readonly runtime: AgentRuntime;
+  private readonly hosts: SessionCache<SessionHost>;
+
+  public constructor(deps: SessionRegistryDeps) {
+    this.deps = deps;
+    this.runtime = deps.runtime ?? new AgentRuntime(deps.agentDir);
+    this.hosts = new SessionCache(deps.capacity);
+  }
+
+  public get sessionsRoot(): string {
+    return join(this.runtime.agentDir, "sessions");
+  }
+
+  public async init(): Promise<void> {
+    await this.runtime.init();
+  }
+
+  /** Sessions on disk, newest first; reads only each file's header line. */
+  public async list(cwd?: string): Promise<readonly SessionSummary[]> {
+    const summaries = (
+      await Pool.mapPooled(
+        await this.paths("*/*.jsonl"),
+        HEADER_READS,
+        readSummary
+      )
+    ).filter(
+      (summary): summary is SessionSummary =>
+        summary !== undefined && (cwd === undefined || summary.cwd === cwd)
+    );
+    return summaries.sort((a, b) => b.modifiedAt - a.modifiedAt);
+  }
+
+  /** The live host for `sessionId`, if one is currently loaded. */
+  public peek(sessionId: string): SessionHost | undefined {
+    return this.hosts.peek(sessionId);
+  }
+
+  /**
+   * Rename a session through pi's own session name, so its `/resume` picker shows
+   * it too; `null` clears it. A live session is renamed by its agent, a closed one
+   * by appending to its file under the turn lease. Answers with the name pi kept.
+   */
+  public async setName(
+    sessionId: string,
+    name: string | null
+  ): Promise<string | undefined> {
+    const host = this.peek(sessionId);
+    if (host?.agentSession) {
+      return await host.setName(name);
+    }
+    const summary = await this.find(sessionId);
+    if (summary === undefined) {
+      throw new Error(`unknown session: ${sessionId}`);
+    }
+    const next = SessionName.normalise(name);
+    // Reopening is a plain read today, but a pi that migrates the file rewrites it.
+    // The lease is only ever held for a whole turn, so a rename refuses rather than queues.
+    return await SessionLease.hold(
+      summary.path,
+      "daemon",
+      async () => {
+        const manager = SessionManager.open(summary.path);
+        manager.appendSessionInfo(next);
+        return manager.getSessionName();
+      },
+      { timeoutMs: 0 }
+    );
+  }
+
+  /** Every model this machine has credentials for, qualified as `SessionHost.setModel` takes them. */
+  public models(): readonly ModelChoice[] {
+    return this.runtime.models();
+  }
+
+  public async open(sessionId: string): Promise<SessionHost> {
+    const cached = this.hosts.touch(sessionId);
+    if (cached) {
+      return cached;
+    }
+    const summary = await this.find(sessionId);
+    if (!summary) {
+      throw new Error(`unknown session: ${sessionId}`);
+    }
+    return this.hosts.adopt(
+      sessionId,
+      this.buildHost(sessionId, {
+        cwd: summary.cwd,
+        sessionPath: summary.path,
+      })
+    );
+  }
+
+  /** Start a new session; the agent is built eagerly because pi assigns the UUID and file. */
+  public async create(
+    options: SessionCreateOptions = {}
+  ): Promise<SessionHost> {
+    const like = options.like;
+    const cwd = options.cwd ?? like?.cwd ?? this.deps.defaults.cwd;
+    const reason = await Directories.check(cwd);
+    if (reason !== undefined) {
+      throw new Error(reason);
+    }
+    const model = like?.currentModelId;
+    const thinkingLevel = like?.chosenThinkingLevel;
+    const host = this.buildHost("pending", {
+      cwd,
+      ...(model === undefined ? {} : { model }),
+      ...(thinkingLevel === undefined ? {} : { thinkingLevel }),
+    });
+    const agent = await host.ensureAgent();
+    return this.hosts.adopt(agent.sessionId, host);
+  }
+
+  public async disposeAll(): Promise<void> {
+    await this.hosts.disposeAll();
+  }
+
+  /**
+   * One session by id. Pi names a file for the id it carries, so the usual
+   * answer is one glob and one header; resolving it by listing would read the
+   * header of every session on disk to throw all but one away.
+   */
+  private async find(sessionId: string): Promise<SessionSummary | undefined> {
+    for (const path of await this.paths(`*/*${sessionId}.jsonl`)) {
+      const summary = await readSummary(path);
+      if (summary?.sessionId === sessionId) {
+        return summary;
+      }
+    }
+    // A file named something else entirely: the id is the header's, not the name's.
+    return (await this.list()).find(
+      (summary) => summary.sessionId === sessionId
+    );
+  }
+
+  private async paths(pattern: string): Promise<readonly string[]> {
+    const root = this.sessionsRoot;
+    if (!(await stat(root).catch(() => undefined))?.isDirectory()) {
+      return [];
+    }
+    const found: string[] = [];
+    for await (const relative of new Bun.Glob(pattern).scan({
+      cwd: root,
+      onlyFiles: true,
+    })) {
+      found.push(join(root, relative));
+    }
+    return found;
+  }
+
+  private buildHost(label: string, settings: HostSettings): SessionHost {
+    return new SessionHost({
+      label: `session ${label}`,
+      settings,
+      defaults: this.deps.defaults,
+      agentDir: this.runtime.agentDir,
+      modelRuntime: this.runtime.modelRuntime,
+      modelRegistry: this.runtime.modelRegistry,
+      settingsManagerFor: (cwd) => this.runtime.settingsManagerFor(cwd),
+      persistSettings: async () => {},
+      // The terminal can hold the same file open, so every mutation goes through the turn lease.
+      lease: "daemon",
+      customTools: this.deps.customTools,
+      ...(this.deps.systemInstruction === undefined
+        ? {}
+        : { systemInstruction: this.deps.systemInstruction }),
+      ...(this.deps.surface === undefined
+        ? {}
+        : { surface: this.deps.surface }),
+    });
+  }
+}
+
+async function readSummary(path: string): Promise<SessionSummary | undefined> {
+  const header = await new EventLog(path).header();
+  if (!header) {
+    return undefined;
+  }
+  return {
+    sessionId: header.id,
+    cwd: header.cwd,
+    path,
+    createdAt: Date.parse(header.timestamp),
+    modifiedAt: Math.floor((await Bun.file(path).stat()).mtimeMs),
+  };
+}

package/packages/core/src/session/WriteMark.ts

@@ -0,0 +1,51 @@
+import type { EventLog } from "./EventLog";
+
+/** How much of a session file one process can account for: durable lines, and pi's own entries. */
+export type WriteMark = {
+  readonly head: number;
+  readonly entries: number;
+};
+
+/** Pi's in-memory entry list: an `AgentSession`'s `sessionManager`, or one held directly. */
+type EntrySource = {
+  getEntries(): readonly unknown[];
+};
+
+/** Nothing accounted for yet, which `foreignSince` reads as "the file is pi's to write". */
+const UNREAD: WriteMark = { head: 0, entries: 0 };
+
+/** Head first: an append between the two reads must under-count the file, never over. */
+async function of(log: EventLog, source: EntrySource): Promise<WriteMark> {
+  return { head: await log.head(), entries: source.getEntries().length };
+}
+
+/**
+ * Whether the file gained lines beyond the ones pi appended from memory. A turn, a
+ * model change, a compaction, a `/name` and an idle `!bash` all move both counts
+ * together, so only a writer that is not this process makes the difference positive.
+ *
+ * pi names a session file before it writes one, buffering entries until the first
+ * assistant reply, so a mark taken before the file exists is answered by the whole of
+ * it: header plus every entry pi was holding.
+ */
+function foreignSince(mark: WriteMark, next: WriteMark): boolean {
+  const base = mark.head === 0 ? { head: 1, entries: 0 } : mark;
+  return next.head - base.head - (next.entries - base.entries) > 0;
+}
+
+/**
+ * Whether every line the file gained since `mark` is one no reader has to replay.
+ * A rename appends `session_info` and moves no history, so a surface that absorbs
+ * it stays on the session it is already holding. Only ask between turns: a window
+ * that also holds our own appends is not benign, and a running turn's is.
+ */
+async function benignSince(log: EventLog, mark: WriteMark): Promise<boolean> {
+  const added = await log.read(mark.head);
+  return (
+    added.length > 0 &&
+    added.every(({ entry }) => entry.type === "session_info")
+  );
+}
+
+/** Write accounting over one session file: whose lines are these? */
+export const WriteMark = { UNREAD, of, foreignSince, benignSince };

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

@@ -0,0 +1,25 @@
+// Never throw on an unknown flag or positional: the same argv reaches every mode.
+function scan(
+  args: ReadonlyArray<string>,
+  visit: (key: string, take: () => string | undefined) => void
+): void {
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (!arg.startsWith("--")) {
+      continue;
+    }
+    const eqIdx = arg.indexOf("=");
+    const key = eqIdx >= 0 ? arg.slice(0, eqIdx) : arg;
+    const inline = eqIdx >= 0 ? arg.slice(eqIdx + 1) : undefined;
+
+    visit(key, () => {
+      if (inline !== undefined) {
+        return inline;
+      }
+      i += 1;
+      return args[i];
+    });
+  }
+}
+
+export const Cli = { scan };

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

@@ -0,0 +1,13 @@
+import type { Unit } from "./Supervisor";
+
+/** The single unit every pim surface runs inside; `--surfaces` picks which of them come up. */
+export const DaemonUnit = {
+  mode: "daemon",
+  description: "Pim daemon",
+} satisfies Unit;
+
+/** One unit per surface, which is how pim shipped until the surfaces shared a process. */
+export const SupersededUnits: ReadonlyArray<Unit> = [
+  { mode: "web", description: "Pim web daemon" },
+  { mode: "telegram", description: "Pim Telegram daemon" },
+];

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

@@ -0,0 +1,304 @@
+import * as Diff from "diff";
+
+export type ToolDiffLineKind = "context" | "added" | "removed";
+
+export type IntraLineRange = {
+  readonly start: number;
+  readonly end: number;
+};
+
+export type ToolDiffLine = {
+  readonly kind: ToolDiffLineKind;
+  readonly oldLine?: number;
+  readonly newLine?: number;
+  readonly text: string;
+  readonly emphasis?: readonly IntraLineRange[];
+};
+
+export type ToolDiffHunk = {
+  readonly oldStart: number;
+  readonly oldLines: number;
+  readonly newStart: number;
+  readonly newLines: number;
+  readonly lines: readonly ToolDiffLine[];
+};
+
+export type ToolDiff = {
+  readonly path: string;
+  readonly hunks: readonly ToolDiffHunk[];
+};
+
+// Keep the EOF-newline flag out of `lines`, or `joinComparable` emits a phantom blank line.
+export type ToolDiffSide = {
+  readonly lines: readonly string[];
+  readonly hasTrailingNewline: boolean;
+};
+
+function buildToolDiff(
+  path: string,
+  oldSide: ToolDiffSide,
+  newSide: ToolDiffSide,
+  contextSize: number
+): ToolDiff | undefined {
+  if (contextSize < 0 || !Number.isFinite(contextSize)) {
+    throw new Error(
+      `contextSize must be a non-negative finite number, got ${contextSize}.`
+    );
+  }
+
+  const lines = build(oldSide.lines, newSide.lines);
+
+  if (!lines.some((line) => line.kind !== "context")) {
+    return undefined;
+  }
+
+  const emphasized = attachEmphasis(lines);
+
+  return {
+    path,
+    hunks: buildHunks(emphasized, contextSize),
+  };
+}
+
+function fromText(text: string): ToolDiffSide {
+  if (text.length === 0) {
+    return emptySide;
+  }
+
+  const hasTrailingNewline = text.endsWith("\n");
+  const parts = text.split("\n");
+
+  if (hasTrailingNewline) {
+    parts.pop();
+  }
+
+  return { lines: parts, hasTrailingNewline };
+}
+
+function attachEmphasis(
+  lines: readonly ToolDiffLine[]
+): readonly ToolDiffLine[] {
+  const result: ToolDiffLine[] = [...lines];
+  let i = 0;
+
+  while (i < result.length) {
+    if (result[i]?.kind !== "removed") {
+      i += 1;
+      continue;
+    }
+
+    let removedEnd = i;
+    while (
+      removedEnd < result.length &&
+      result[removedEnd]?.kind === "removed"
+    ) {
+      removedEnd += 1;
+    }
+
+    let addedEnd = removedEnd;
+    while (addedEnd < result.length && result[addedEnd]?.kind === "added") {
+      addedEnd += 1;
+    }
+
+    const removedCount = removedEnd - i;
+    const addedCount = addedEnd - removedEnd;
+
+    if (removedCount > 0 && removedCount === addedCount) {
+      for (let k = 0; k < removedCount; k += 1) {
+        const removed = result[i + k];
+        const added = result[removedEnd + k];
+
+        if (removed === undefined || added === undefined) {
+          continue;
+        }
+
+        const ranges = computeIntraLineRanges(removed.text, added.text);
+
+        if (ranges === undefined) {
+          continue;
+        }
+
+        result[i + k] = { ...removed, emphasis: ranges.removed };
+        result[removedEnd + k] = { ...added, emphasis: ranges.added };
+      }
+    }
+
+    i = addedEnd > i ? addedEnd : i + 1;
+  }
+
+  return result;
+}
+
+function computeIntraLineRanges(
+  oldText: string,
+  newText: string
+):
+  | {
+      readonly removed: readonly IntraLineRange[];
+      readonly added: readonly IntraLineRange[];
+    }
+  | undefined {
+  const parts = Diff.diffWords(oldText, newText);
+  const removedRanges: IntraLineRange[] = [];
+  const addedRanges: IntraLineRange[] = [];
+  let oldPos = 0;
+  let newPos = 0;
+  let sharedLen = 0;
+  let firstRemoved = true;
+  let firstAdded = true;
+
+  for (const part of parts) {
+    const len = part.value.length;
+
+    if (part.added === true) {
+      const leading = firstAdded ? leadingWsLen(part.value) : 0;
+      firstAdded = false;
+      if (len - leading > 0) {
+        addedRanges.push({ start: newPos + leading, end: newPos + len });
+      }
+      newPos += len;
+      continue;
+    }
+
+    if (part.removed === true) {
+      const leading = firstRemoved ? leadingWsLen(part.value) : 0;
+      firstRemoved = false;
+      if (len - leading > 0) {
+        removedRanges.push({ start: oldPos + leading, end: oldPos + len });
+      }
+      oldPos += len;
+      continue;
+    }
+
+    sharedLen += len;
+    oldPos += len;
+    newPos += len;
+  }
+
+  if (sharedLen === 0) {
+    return undefined;
+  }
+
+  return { removed: removedRanges, added: addedRanges };
+}
+
+function build(
+  oldLines: readonly string[],
+  newLines: readonly string[]
+): readonly ToolDiffLine[] {
+  const parts = Diff.diffLines(
+    joinComparable(oldLines),
+    joinComparable(newLines)
+  );
+  const lines: ToolDiffLine[] = [];
+  let oldLine = 1;
+  let newLine = 1;
+
+  for (const part of parts) {
+    const values = partLines(part.value);
+
+    for (const text of values) {
+      if (part.added === true) {
+        lines.push({ kind: "added", newLine, text });
+        newLine += 1;
+        continue;
+      }
+
+      if (part.removed === true) {
+        lines.push({ kind: "removed", oldLine, text });
+        oldLine += 1;
+        continue;
+      }
+
+      lines.push({ kind: "context", oldLine, newLine, text });
+      oldLine += 1;
+      newLine += 1;
+    }
+  }
+
+  return lines;
+}
+
+function buildHunks(
+  lines: readonly ToolDiffLine[],
+  contextSize: number
+): readonly ToolDiffHunk[] {
+  const changeIndexes = lines
+    .map((line, index) => (line.kind === "context" ? -1 : index))
+    .filter((index) => index >= 0);
+  const hunks: ToolDiffHunk[] = [];
+  let firstChange = changeIndexes[0];
+  let lastChange = changeIndexes[0];
+
+  if (firstChange === undefined || lastChange === undefined) {
+    return hunks;
+  }
+
+  const pushHunk = (startChange: number, endChange: number): void => {
+    const hunkLines = lines.slice(
+      Math.max(0, startChange - contextSize),
+      Math.min(lines.length, endChange + contextSize + 1)
+    );
+    const oldNumbers = hunkLines.flatMap((line) =>
+      line.oldLine === undefined ? [] : [line.oldLine]
+    );
+    const newNumbers = hunkLines.flatMap((line) =>
+      line.newLine === undefined ? [] : [line.newLine]
+    );
+    const oldStart =
+      oldNumbers.length === 0
+        ? Math.max(0, (newNumbers[0] ?? 1) - 1)
+        : Math.min(...oldNumbers);
+    const newStart =
+      newNumbers.length === 0
+        ? Math.max(0, (oldNumbers[0] ?? 1) - 1)
+        : Math.min(...newNumbers);
+
+    hunks.push({
+      oldStart,
+      oldLines:
+        oldNumbers.length === 0 ? 0 : Math.max(...oldNumbers) - oldStart + 1,
+      newStart,
+      newLines:
+        newNumbers.length === 0 ? 0 : Math.max(...newNumbers) - newStart + 1,
+      lines: hunkLines,
+    });
+  };
+
+  for (const changeIndex of changeIndexes.slice(1)) {
+    if (changeIndex - lastChange <= contextSize * 2 + 1) {
+      lastChange = changeIndex;
+      continue;
+    }
+
+    pushHunk(firstChange, lastChange);
+    firstChange = changeIndex;
+    lastChange = changeIndex;
+  }
+
+  pushHunk(firstChange, lastChange);
+
+  return hunks;
+}
+
+function leadingWsLen(value: string): number {
+  return value.match(/^\s*/)?.[0].length ?? 0;
+}
+
+function joinComparable(lines: readonly string[]): string {
+  return lines.length === 0 ? "" : `${lines.join("\n")}\n`;
+}
+
+function partLines(value: string): readonly string[] {
+  const lines = value.split("\n");
+
+  if (lines.at(-1) === "") {
+    lines.pop();
+  }
+
+  return lines;
+}
+
+const emptySide: ToolDiffSide = { lines: [], hasTrailingNewline: false };
+
+export const DiffLines = { buildToolDiff, fromText, emptySide, attachEmphasis };

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

@@ -0,0 +1,70 @@
+import * as Diff from "diff";
+import {
+  DiffLines,
+  type ToolDiff,
+  type ToolDiffHunk,
+  type ToolDiffLine,
+  type ToolDiffLineKind,
+} from "./DiffLines";
+
+function fromUnified(path: string, patch: string): ToolDiff | undefined {
+  const hunks = Diff.parsePatch(patch)
+    .flatMap((file) => file.hunks)
+    .map(toHunk)
+    .filter((hunk) => hunk.lines.length > 0);
+
+  return hunks.length === 0 ? undefined : { path, hunks };
+}
+
+function toHunk(hunk: Diff.StructuredPatchHunk): ToolDiffHunk {
+  const lines: ToolDiffLine[] = [];
+  let oldLine = hunk.oldStart;
+  let newLine = hunk.newStart;
+
+  for (const raw of hunk.lines) {
+    if (raw.startsWith("\\")) {
+      continue;
+    }
+
+    const kind = kindOf(raw);
+    const text = raw.slice(1);
+
+    if (kind === "added") {
+      lines.push({ kind, newLine, text });
+      newLine += 1;
+      continue;
+    }
+
+    if (kind === "removed") {
+      lines.push({ kind, oldLine, text });
+      oldLine += 1;
+      continue;
+    }
+
+    lines.push({ kind, oldLine, newLine, text });
+    oldLine += 1;
+    newLine += 1;
+  }
+
+  return {
+    oldStart: hunk.oldStart,
+    oldLines: hunk.oldLines,
+    newStart: hunk.newStart,
+    newLines: hunk.newLines,
+    lines: DiffLines.attachEmphasis(lines),
+  };
+}
+
+function kindOf(line: string): ToolDiffLineKind {
+  if (line.startsWith("+")) {
+    return "added";
+  }
+
+  if (line.startsWith("-")) {
+    return "removed";
+  }
+
+  return "context";
+}
+
+export const DiffPatch = { fromUnified };