pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,279 @@
+import { readFileSync, unlinkSync } from "node:fs";
+import { mkdir, open, stat, unlink, utimes } from "node:fs/promises";
+import { hostname } from "node:os";
+import { dirname } from "node:path";
+
+import { FileWatch } from "../shared/FileWatch";
+import { FsErrors } from "../shared/FsErrors";
+import { Fs } from "../shared/Fs";
+import { Json } from "../shared/Json";
+
+export type LeaseFrontend = "tui" | "daemon";
+
+/** What one holder wrote into `<sessionPath>.lease`. */
+export type LeaseRecord = {
+  readonly pid: number;
+  readonly hostname: string;
+  readonly frontend: LeaseFrontend;
+  readonly startedAt: number;
+};
+
+export type LeaseHandle = {
+  release(): Promise<void>;
+};
+
+export type AcquireResult =
+  | { readonly ok: true; readonly handle: LeaseHandle }
+  /** Absent when the holder's file is torn or vanished mid-read. */
+  | { readonly ok: false; readonly holder?: LeaseRecord };
+
+export type LeaseOptions = {
+  readonly heartbeatMs?: number;
+  readonly pollMs?: number;
+  readonly timeoutMs?: number;
+  /** Called with the current holder each time an acquire is denied and another poll follows. */
+  readonly onBlocked?: (holder: LeaseRecord | undefined) => void;
+};
+
+const HEARTBEAT_MS = 5_000;
+const STALE_MS = 30_000;
+const POLL_MS = 250;
+const TIMEOUT_MS = 5 * 60_000;
+const STEAL_ATTEMPTS = 3;
+const STEAL_BACKOFF_MS = 50;
+
+const HOST = hostname();
+
+const held = new Set<string>();
+let exitHooked = false;
+
+function pathFor(sessionPath: string): string {
+  return `${sessionPath}.lease`;
+}
+
+function toRecord(value: unknown): LeaseRecord | undefined {
+  const raw = Json.asRecord(value);
+  if (
+    typeof raw?.pid !== "number" ||
+    typeof raw.hostname !== "string" ||
+    typeof raw.startedAt !== "number" ||
+    (raw.frontend !== "tui" && raw.frontend !== "daemon")
+  ) {
+    return undefined;
+  }
+  return {
+    pid: raw.pid,
+    hostname: raw.hostname,
+    frontend: raw.frontend,
+    startedAt: raw.startedAt,
+  };
+}
+
+async function recordAt(path: string): Promise<LeaseRecord | undefined> {
+  return toRecord(await Fs.readJsonOr<unknown>(path, undefined));
+}
+
+/** The current holder, or undefined when the file is absent, torn, or half-written. */
+async function read(sessionPath: string): Promise<LeaseRecord | undefined> {
+  return await recordAt(pathFor(sessionPath));
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    // EPERM is someone else's live process.
+    return FsErrors.code(err) !== "ESRCH";
+  }
+}
+
+/** A holder is stale once its pid is gone, or once it stops heartbeating; never across hosts. */
+function isStale(
+  record: LeaseRecord,
+  mtimeMs: number,
+  now = Date.now()
+): boolean {
+  if (record.hostname !== HOST) {
+    return false;
+  }
+  return !isAlive(record.pid) || now - mtimeMs > STALE_MS;
+}
+
+/** Whether this very process wrote that record — the one holder allowed to release it. */
+function isOurs(record: LeaseRecord | undefined): boolean {
+  return record?.pid === process.pid && record.hostname === HOST;
+}
+
+async function stealable(
+  path: string,
+  record: LeaseRecord | undefined
+): Promise<boolean> {
+  const mtimeMs = await stat(path).then(
+    (stats) => stats.mtimeMs,
+    () => undefined
+  );
+  if (mtimeMs === undefined) {
+    return true;
+  }
+  // A torn file is a holder mid-write until it stops being refreshed.
+  return record === undefined
+    ? Date.now() - mtimeMs > STALE_MS
+    : isStale(record, mtimeMs);
+}
+
+async function claim(
+  path: string,
+  frontend: LeaseFrontend
+): Promise<LeaseRecord | undefined> {
+  const record: LeaseRecord = {
+    pid: process.pid,
+    hostname: HOST,
+    frontend,
+    startedAt: Date.now(),
+  };
+  const file = await open(path, "wx").catch((err: unknown) => {
+    if (FsErrors.code(err) === "EEXIST") {
+      return undefined;
+    }
+    // The session's directory is pi's to create, and a lease can precede the file it guards.
+    if (FsErrors.code(err) === "ENOENT") {
+      return mkdir(dirname(path), { recursive: true }).then(() =>
+        open(path, "wx")
+      );
+    }
+    throw err;
+  });
+  if (file === undefined) {
+    return undefined;
+  }
+  try {
+    await file.writeFile(`${JSON.stringify(record)}\n`);
+  } finally {
+    await file.close();
+  }
+  return record;
+}
+
+function hookExit(): void {
+  if (exitHooked) {
+    return;
+  }
+  exitHooked = true;
+  process.on("exit", () => {
+    for (const path of held) {
+      try {
+        if (isOurs(toRecord(Json.tryParseJson(readFileSync(path, "utf8"))))) {
+          unlinkSync(path);
+        }
+      } catch {}
+    }
+  });
+}
+
+function handleFor(path: string, options: LeaseOptions): LeaseHandle {
+  held.add(path);
+  hookExit();
+  // Bump mtime rather than rewrite: a rename would clobber whoever holds the file next.
+  const beat = setInterval(() => {
+    const now = new Date();
+    void utimes(path, now, now).catch(() => undefined);
+  }, options.heartbeatMs ?? HEARTBEAT_MS);
+  beat.unref?.();
+
+  let released = false;
+  return {
+    release: async (): Promise<void> => {
+      if (released) {
+        return;
+      }
+      released = true;
+      clearInterval(beat);
+      held.delete(path);
+      if (isOurs(await recordAt(path))) {
+        await unlink(path).catch(() => undefined);
+      }
+    },
+  };
+}
+
+/** Create-exclusive, stealing only a lease whose holder is provably gone. */
+async function acquire(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  options: LeaseOptions = {}
+): Promise<AcquireResult> {
+  const path = pathFor(sessionPath);
+  for (let attempt = 0; ; attempt++) {
+    if (await claim(path, frontend)) {
+      return { ok: true, handle: handleFor(path, options) };
+    }
+    const holder = await recordAt(path);
+    if (attempt >= STEAL_ATTEMPTS || !(await stealable(path, holder))) {
+      return holder === undefined ? { ok: false } : { ok: false, holder };
+    }
+    await unlink(path).catch(() => undefined);
+    await Bun.sleep(STEAL_BACKOFF_MS);
+  }
+}
+
+/** Polls until the lease is free, the deadline passes, or the holder is stealable. */
+async function waitFor(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  options: LeaseOptions = {}
+): Promise<AcquireResult> {
+  const deadline = Date.now() + (options.timeoutMs ?? TIMEOUT_MS);
+  while (true) {
+    const result = await acquire(sessionPath, frontend, options);
+    if (result.ok || Date.now() >= deadline) {
+      return result;
+    }
+    options.onBlocked?.(result.holder);
+    await Bun.sleep(options.pollMs ?? POLL_MS);
+  }
+}
+
+function denial(result: { readonly holder?: LeaseRecord }): string {
+  const holder = result.holder;
+  const who =
+    holder === undefined
+      ? "another process"
+      : `${holder.frontend} (pid ${holder.pid})`;
+  return `Session is busy: ${who} still holds its turn lease.`;
+}
+
+/** The only safe way to take a lease: waits for it, and always gives it back. */
+async function hold<T>(
+  sessionPath: string,
+  frontend: LeaseFrontend,
+  work: () => Promise<T>,
+  options: LeaseOptions = {}
+): Promise<T> {
+  const result = await waitFor(sessionPath, frontend, options);
+  if (!result.ok) {
+    throw new Error(denial(result));
+  }
+  try {
+    return await work();
+  } finally {
+    await result.handle.release();
+  }
+}
+
+/** Fires whenever the lease appears, changes hands, or is released. */
+function watch(sessionPath: string, onChange: () => void): () => void {
+  return FileWatch.file(pathFor(sessionPath), onChange);
+}
+
+/** A turn lease over one session file, held as a sibling `<sessionPath>.lease`. */
+export const SessionLease = {
+  pathFor,
+  read,
+  acquire,
+  hold,
+  waitFor,
+  watch,
+  isStale,
+  isOurs,
+};

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

@@ -0,0 +1,169 @@
+import { 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 { AgentRuntime, type ModelChoice } from "./AgentRuntime";
+import { EventLog } from "./EventLog";
+import { SessionCache } from "./SessionCache";
+import {
+  SessionHost,
+  type CustomToolContext,
+  type HostSettings,
+} from "./SessionHost";
+
+/** 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>;
+};
+
+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;
+};
+
+/** 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 root = this.sessionsRoot;
+    if (!(await stat(root).catch(() => undefined))?.isDirectory()) {
+      return [];
+    }
+    const paths: string[] = [];
+    for await (const relative of new Bun.Glob("*/*.jsonl").scan({
+      cwd: root,
+      onlyFiles: true,
+    })) {
+      paths.push(join(root, relative));
+    }
+    const summaries = (await Promise.all(paths.map(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);
+  }
+
+  /** 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.list()).find((s) => s.sessionId === 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();
+  }
+
+  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 }),
+    });
+  }
+}
+
+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,37 @@
+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;
+}
+
+/** Write accounting over one session file: whose lines are these? */
+export const WriteMark = { UNREAD, of, foreignSince };

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" },
+];