pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,85 @@
+import type { Api as ModelApi, Model } from "@earendil-works/pi-ai";
+import {
+  getAgentDir,
+  ModelRegistry,
+  ModelRuntime,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { join } from "node:path";
+
+/** One model a session can be switched to, named the way `setModel` takes it. */
+export type ModelChoice = {
+  readonly id: string;
+  readonly label: string;
+  /** Who serves it, for a client that groups or tags the catalogue. */
+  readonly provider: string;
+};
+
+/**
+ * Pi's installation as one process sees it: a single `ModelRuntime` over a
+ * single `auth.json`, and one `SettingsManager` per cwd. Every surface in a
+ * process shares one of these — two runtimes over one auth file race each
+ * other's token refresh.
+ */
+export class AgentRuntime {
+  public readonly agentDir: string;
+  private readonly settingsManagers = new Map<string, SettingsManager>();
+  private runtime: ModelRuntime | undefined;
+  private registry: ModelRegistry | undefined;
+  private booting: Promise<void> | undefined;
+
+  public constructor(agentDir?: string) {
+    this.agentDir = agentDir ?? getAgentDir();
+  }
+
+  /** Idempotent, and shared by every caller: the second surface to ask waits on the first. */
+  public init(): Promise<void> {
+    this.booting ??= this.bootstrap().catch((err: unknown) => {
+      this.booting = undefined;
+      throw err;
+    });
+    return this.booting;
+  }
+
+  public get modelRuntime(): ModelRuntime {
+    return this.required(this.runtime);
+  }
+
+  public get modelRegistry(): ModelRegistry {
+    return this.required(this.registry);
+  }
+
+  /** Every model this machine has credentials for, qualified as `setModel` takes them. */
+  public models(): readonly ModelChoice[] {
+    return this.modelRegistry.getAvailable().map((model: Model<ModelApi>) => ({
+      id: `${model.provider}/${model.id}`,
+      label: model.name,
+      provider: model.provider,
+    }));
+  }
+
+  public settingsManagerFor(cwd: string): SettingsManager {
+    const existing = this.settingsManagers.get(cwd);
+    if (existing) {
+      return existing;
+    }
+    const settingsManager = SettingsManager.create(cwd, this.agentDir);
+    this.settingsManagers.set(cwd, settingsManager);
+    return settingsManager;
+  }
+
+  private async bootstrap(): Promise<void> {
+    this.runtime = await ModelRuntime.create({
+      authPath: join(this.agentDir, "auth.json"),
+      modelsPath: join(this.agentDir, "models.json"),
+    });
+    this.registry = new ModelRegistry(this.runtime);
+  }
+
+  private required<T>(value: T | undefined): T {
+    if (value === undefined) {
+      throw new Error("AgentRuntime.init() must complete before use");
+    }
+    return value;
+  }
+}

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

@@ -0,0 +1,213 @@
+import type { BunFile } from "bun";
+
+import type { FileEntry, SessionHeader } from "@earendil-works/pi-coding-agent";
+import { parseSessionEntries } from "@earendil-works/pi-coding-agent";
+
+import { Attachments } from "../attachments/Attachments";
+import { MessageText } from "./MessageText";
+
+async function ifPresent<T>(read: () => Promise<T>, absent: T): Promise<T> {
+  try {
+    return await read();
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return absent;
+    }
+    throw err;
+  }
+}
+
+/** One durable line of a session file; the header is line 1, so entries start at `seq` 2. */
+export type LoggedEntry = {
+  readonly seq: number;
+  readonly entry: FileEntry;
+};
+
+type Cursor = {
+  readonly offset: number;
+  readonly seq: number;
+};
+
+const PROBE_LINES = 16;
+
+const PROBE_LIMIT = 16 * 1024 * 1024;
+
+const PROBE_CHUNK = 8 * 1024;
+const PROBE_CHUNK_MAX = 256 * 1024;
+
+const EMPTY = new Uint8Array();
+
+const TAIL_BYTES = 64 * 1024;
+const TAIL_LINES = 10;
+
+const TITLE_LIMIT = 120;
+
+/** What the session catalogue shows for one file without opening a session. */
+export type SessionDigest = {
+  /** The first user message, trimmed; absent when the session has none yet. */
+  readonly title?: string;
+  /** When the agent last wrote; it moves with an in-flight turn, so read it before starting one. */
+  readonly settledAt?: number;
+};
+
+function isHeader(entry: FileEntry): entry is SessionHeader {
+  return entry.type === "session";
+}
+
+/** A reader over one pi session file: append-only JSONL, so a line's `seq` never changes. */
+export class EventLog {
+  public readonly path: string;
+  private cursor: Cursor = { offset: 0, seq: 0 };
+
+  public constructor(path: string) {
+    this.path = path;
+  }
+
+  /** Durable entries with `seq > afterSeq`, oldest first. */
+  public async read(afterSeq = 0): Promise<readonly LoggedEntry[]> {
+    const start =
+      this.cursor.seq <= afterSeq ? this.cursor : { offset: 0, seq: 0 };
+    const file = Bun.file(this.path);
+    const text = await ifPresent(() => file.slice(start.offset).text(), "");
+
+    // A trailing fragment is a write in progress: stop short of it or reads lose entries.
+    const lastBreak = text.lastIndexOf("\n");
+    if (lastBreak === -1) {
+      return [];
+    }
+    const complete = text.slice(0, lastBreak + 1);
+    const lines = complete.split("\n");
+    lines.pop();
+
+    const entries: LoggedEntry[] = [];
+    for (const [index, line] of lines.entries()) {
+      const seq = start.seq + index + 1;
+      if (seq <= afterSeq) {
+        continue;
+      }
+      const parsed = parseSessionEntries(line)[0];
+      if (parsed) {
+        entries.push({ seq, entry: parsed });
+      }
+    }
+
+    this.cursor = {
+      offset: start.offset + Buffer.byteLength(complete, "utf8"),
+      seq: start.seq + lines.length,
+    };
+    return entries;
+  }
+
+  public async header(): Promise<SessionHeader | undefined> {
+    for await (const line of headLines(Bun.file(this.path), 1)) {
+      const entry = parseSessionEntries(line)[0];
+      return entry && isHeader(entry) ? entry : undefined;
+    }
+    return undefined;
+  }
+
+  /** The `seq` of the last complete line, without parsing any of them. */
+  public async head(): Promise<number> {
+    await this.read(Number.MAX_SAFE_INTEGER);
+    return this.cursor.seq;
+  }
+
+  /** Title and settle time for the catalogue, read from the two ends of the file. */
+  public async digest(): Promise<SessionDigest> {
+    const file = Bun.file(this.path);
+    const [title, settledAt] = await Promise.all([
+      firstUserMessage(file),
+      settleTime(file),
+    ]);
+    return {
+      ...(title === undefined ? {} : { title }),
+      ...(settledAt === undefined ? {} : { settledAt }),
+    };
+  }
+}
+
+async function* headLines(
+  file: BunFile,
+  count: number
+): AsyncGenerator<string> {
+  // Decode with `stream: true`: a chunk boundary can split a character.
+  const decoder = new TextDecoder();
+  let pending = "";
+  let yielded = 0;
+  let offset = 0;
+  let ask = PROBE_CHUNK;
+  while (offset < PROBE_LIMIT) {
+    const chunk = await ifPresent(
+      () => file.slice(offset, offset + ask).bytes(),
+      EMPTY
+    );
+    if (chunk.length === 0) {
+      return;
+    }
+    offset += chunk.length;
+    ask = Math.min(ask * 2, PROBE_CHUNK_MAX);
+    pending += decoder.decode(chunk, { stream: true });
+    const lines = pending.split("\n");
+    pending = lines.pop() ?? "";
+    for (const line of lines) {
+      yield line;
+      if (++yielded >= count) {
+        return;
+      }
+    }
+  }
+}
+
+async function settleTime(file: BunFile): Promise<number | undefined> {
+  const near = Math.max(0, file.size - TAIL_BYTES);
+  const lines = await tailLines(file, near);
+  const found = lastAgentTime(lines);
+  if (found !== undefined || near === 0 || lines.length >= TAIL_LINES) {
+    return found;
+  }
+  return lastAgentTime(await tailLines(file, 0));
+}
+
+async function tailLines(file: BunFile, from: number): Promise<string[]> {
+  const text = await ifPresent(() => file.slice(from).text(), "");
+  const lines = text.split("\n");
+  lines.pop();
+  if (from > 0) {
+    lines.shift();
+  }
+  return lines.slice(-TAIL_LINES).reverse();
+}
+
+function lastAgentTime(lines: readonly string[]): number | undefined {
+  for (const line of lines) {
+    const entry = parseSessionEntries(line)[0];
+    if (entry?.type !== "message") {
+      continue;
+    }
+    const role = entry.message.role;
+    if (role === "assistant" || role === "toolResult") {
+      const at = Date.parse(entry.timestamp);
+      return Number.isNaN(at) ? undefined : at;
+    }
+  }
+  return undefined;
+}
+
+async function firstUserMessage(file: BunFile): Promise<string | undefined> {
+  for await (const line of headLines(file, PROBE_LINES)) {
+    const entry = parseSessionEntries(line)[0];
+    if (entry?.type !== "message" || entry.message.role !== "user") {
+      continue;
+    }
+    const said = Attachments.parse(MessageText.textOf(entry.message.content));
+    const text =
+      said.text.trim() ||
+      said.files.map((file) => Attachments.nameOf(file.path)).join(", ");
+    if (text !== "") {
+      return text.length > TITLE_LIMIT
+        ? `${text.slice(0, TITLE_LIMIT).trimEnd()}…`
+        : text;
+    }
+  }
+  return undefined;
+}

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

@@ -0,0 +1,21 @@
+import type { AssistantMessage, UserMessage } from "@earendil-works/pi-ai";
+
+function textOf(
+  content: UserMessage["content"] | AssistantMessage["content"],
+  kind: "text" | "thinking" = "text"
+): string {
+  if (typeof content === "string") {
+    return kind === "text" ? content : "";
+  }
+  let out = "";
+  for (const part of content) {
+    if (kind === "text" && part.type === "text") {
+      out += part.text;
+    } else if (kind === "thinking" && part.type === "thinking") {
+      out += part.thinking;
+    }
+  }
+  return out;
+}
+
+export const MessageText = { textOf };

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

@@ -0,0 +1,94 @@
+import { join } from "node:path";
+
+import { Fs } from "../shared/Fs";
+import { Paths } from "../shared/Paths";
+
+type Stored = {
+  readonly baseline: number;
+  readonly sessions: Record<string, number>;
+};
+
+/** When each session was last read, shared by every client of a machine. */
+export class ReadCursors {
+  private readonly file: string;
+  private readonly ready: Promise<void>;
+  private readonly cursors = new Map<string, number>();
+  private baseline = 0;
+  private readonly writes = Fs.serialised();
+
+  /** Defaults to `~/.pim/read.json`. */
+  public constructor(path?: string) {
+    this.file = path ?? join(Paths.pimHomeDir(), "read.json");
+    this.ready = this.load();
+  }
+
+  /** Whether a session has been answered since anything last read it. */
+  public async isUnread(
+    sessionId: string,
+    answeredAt: number | undefined
+  ): Promise<boolean> {
+    await this.ready;
+    return (
+      answeredAt !== undefined &&
+      answeredAt > (this.cursors.get(sessionId) ?? this.baseline)
+    );
+  }
+
+  /** Moves a session's cursor forward; the write behind it is not waited on. */
+  public async mark(sessionId: string, at: number = Date.now()): Promise<void> {
+    await this.ready;
+    if ((this.cursors.get(sessionId) ?? this.baseline) >= at) {
+      return;
+    }
+    this.cursors.set(sessionId, at);
+    this.persist();
+  }
+
+  public async prune(alive: ReadonlySet<string>): Promise<void> {
+    await this.ready;
+    let dropped = false;
+    for (const sessionId of this.cursors.keys()) {
+      if (!alive.has(sessionId)) {
+        this.cursors.delete(sessionId);
+        dropped = true;
+      }
+    }
+    if (dropped) {
+      this.persist();
+    }
+  }
+
+  /** Settles the writes behind the marks taken so far, for a clean stop. */
+  public async flush(): Promise<void> {
+    await this.ready;
+    await this.writes.run(async () => undefined);
+  }
+
+  private async load(): Promise<void> {
+    const stored = (await Bun.file(this.file)
+      .json()
+      .catch(() => undefined)) as Partial<Stored> | undefined;
+    if (typeof stored?.baseline !== "number") {
+      // Persist the baseline now: recomputing it on each start clears every unread session.
+      this.baseline = Date.now();
+      this.persist();
+      return;
+    }
+    this.baseline = stored.baseline;
+    for (const [sessionId, at] of Object.entries(stored.sessions ?? {})) {
+      if (typeof at === "number") {
+        this.cursors.set(sessionId, at);
+      }
+    }
+  }
+
+  private persist(): void {
+    void this.writes.run(async () => {
+      const stored: Stored = {
+        baseline: this.baseline,
+        sessions: Object.fromEntries(this.cursors),
+      };
+      await Fs.writeJson(this.file, stored).catch(() => undefined);
+    });
+  }
+}

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

@@ -0,0 +1,68 @@
+/** What a cache entry has to offer: a recency stamp and a way to let go. */
+export type CachedSession = {
+  lastUsed: number;
+  dispose(): Promise<void>;
+};
+
+const CAPACITY = 16;
+
+/** Live sessions, keyed however the frontend keys them, capped by least-recently-used. */
+export class SessionCache<T extends CachedSession> {
+  private readonly capacity: number;
+  private readonly entries = new Map<string, T>();
+
+  public constructor(capacity: number = CAPACITY) {
+    this.capacity = capacity;
+  }
+
+  public get size(): number {
+    return this.entries.size;
+  }
+
+  /** The live entry, if there is one, without counting as a use. */
+  public peek(key: string): T | undefined {
+    return this.entries.get(key);
+  }
+
+  /** The live entry, marked used now so eviction passes over it. */
+  public touch(key: string): T | undefined {
+    const entry = this.entries.get(key);
+    if (entry) {
+      entry.lastUsed = Date.now();
+    }
+    return entry;
+  }
+
+  /** Store `value`, disposing the least recently used entry first when full. */
+  public adopt(key: string, value: T): T {
+    this.evictIfNeeded();
+    this.entries.set(key, value);
+    return value;
+  }
+
+  public async disposeAll(): Promise<void> {
+    const live = [...this.entries.values()];
+    this.entries.clear();
+    await Promise.all(live.map((entry) => entry.dispose()));
+  }
+
+  private evictIfNeeded(): void {
+    if (this.entries.size < this.capacity) {
+      return;
+    }
+    let oldestKey: string | undefined;
+    let oldest = Infinity;
+    for (const [key, entry] of this.entries) {
+      if (entry.lastUsed < oldest) {
+        oldest = entry.lastUsed;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey === undefined) {
+      return;
+    }
+    const evicted = this.entries.get(oldestKey)!;
+    this.entries.delete(oldestKey);
+    void evicted.dispose();
+  }
+}