@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/shared/native-journal.ts

@@ -1,7 +1,8 @@
 import * as fs from "node:fs";
-import { scanJournal, type JournalPolicy, type JournalRecord } from "./journal-frames.ts";
+import { JournalFrames, type JournalPolicy, type JournalRecord } from "./journal-frames.ts";
+import type { Projection, StringChunk } from "./json-projection.ts";
 import { nativeProjection } from "./journal-projections.ts";
-import { isRecord, recordAt, type UnknownRecord } from "./unknown.ts";
+import { isRecord, type UnknownRecord } from "./unknown.ts";
 
 /** A selected journal entry is not a complete SDK SessionEntry or Message. */
 export interface NativePreview extends UnknownRecord {
@@ -33,77 +34,169 @@ function preview(
   };
   return { value, start: record.start, end: record.end };
 }
-function configurationModel(value: NativePreview): string | undefined {
-  const message = recordAt(value, "message");
-  const provider = value.type === "model_change" ? value.provider : message?.provider;
-  const model = value.type === "model_change" ? value.modelId : message?.model;
-  return typeof provider === "string" && typeof model === "string"
-    ? `${provider}/${model}`
-    : undefined;
-}
 export class NativeJournal {
   readonly records: NativeRecord[] = [];
   readonly byId = new Map<string, NativeRecord>();
-  readonly stamp: string;
-  readonly end: number;
+  stamp: string;
+  end: number;
   readonly file: string;
-  constructor(file: string, policy: JournalPolicy = "inspect", requireNewline = policy === "live") {
+  private readonly identity: string;
+  private offset = 0;
+  private readonly frames: JournalFrames;
+  constructor(
+    file: string,
+    policy: JournalPolicy = "inspect",
+    requireNewline = policy === "live",
+    options: { readBytes?: number; select?: Projection } = {},
+  ) {
     this.file = file;
-    const fd = fs.openSync(file, "r");
+    let parent: string | null = null;
+    this.frames = new JournalFrames(
+      options.select ?? nativeProjection,
+      (raw) => {
+        const record = preview(raw, parent, this.records[0]?.value.version === 1);
+        if (!record) {
+          if (policy !== "inspect") {
+            throw new SyntaxError(`Native record at byte ${raw.start} requires a type`);
+          }
+          return;
+        }
+        if (record.value.type !== "session") {
+          parent = record.value.id;
+        }
+        this.records.push(record);
+        this.byId.set(record.value.id, record);
+      },
+      { policy, requireNewline },
+    );
+    const fd = fs.openSync(
+      file,
+      fs.constants.O_RDONLY | (policy === "live" ? fs.constants.O_NOFOLLOW : 0),
+    );
     try {
       const stat = fs.fstatSync(fd, { bigint: true });
       this.stamp = journalStamp(stat);
+      this.identity = `${stat.dev}:${stat.ino}`;
       this.end = Number(stat.size);
-      let parent: string | null = null;
-      scanJournal(
+      this.index(fd, Math.min(this.end, options.readBytes ?? Infinity));
+      this.checkInitial(stat, fs.fstatSync(fd, { bigint: true }), policy);
+    } finally {
+      fs.closeSync(fd);
+    }
+    if (this.records[0]?.value.type !== "session") {
+      throw new Error("Not a readable native Pi session.");
+    }
+  }
+  private checkInitial(before: fs.BigIntStats, after: fs.BigIntStats, policy: JournalPolicy): void {
+    if (
+      journalStamp(after) !== this.stamp &&
+      (policy !== "live" ||
+        after.size < before.size ||
+        `${after.dev}:${after.ino}` !== this.identity)
+    ) {
+      throw new Error("Journal changed while indexing; refresh history.");
+    }
+  }
+  private index(fd: number, end: number): void {
+    const buffer = Buffer.allocUnsafe(65536);
+    while (this.offset < end) {
+      const count = fs.readSync(
         fd,
-        nativeProjection,
-        (raw) => {
-          const record = preview(raw, parent, this.records[0]?.value.version === 1);
-          if (!record) {
-            if (policy !== "inspect") {
-              throw new SyntaxError(`Native record at byte ${raw.start} requires a type`);
-            }
-            return;
-          }
-          if (record.value.type !== "session") {
-            parent = record.value.id;
-          }
-          this.records.push(record);
-          this.byId.set(record.value.id, record);
-        },
-        { policy, requireNewline, end: this.end },
+        buffer,
+        0,
+        Math.min(buffer.length, end - this.offset),
+        this.offset,
       );
-      if (journalStamp(fs.fstatSync(fd, { bigint: true })) !== this.stamp) {
-        throw new Error("Journal changed while indexing; refresh history.");
+      if (count === 0) {
+        throw new Error("Journal truncated while reading");
+      }
+      this.frames.write(buffer.subarray(0, count));
+      this.offset += count;
+    }
+    this.frames.finish();
+  }
+  get indexed(): boolean {
+    return this.offset === this.end;
+  }
+  /** Incremental, LF-published indexing. Append work is budgeted independently of paint. */
+  refresh(bytes = 256 * 1024): boolean {
+    const fd = fs.openSync(this.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    try {
+      const stat = fs.fstatSync(fd, { bigint: true });
+      if (`${stat.dev}:${stat.ino}` !== this.identity || Number(stat.size) < this.offset) {
+        throw new Error("Native journal was replaced or truncated; reopen this conversation.");
+      }
+      if (journalStamp(stat) === this.stamp && this.indexed) {
+        return false;
       }
+      const previous = this.records.length;
+      this.end = Number(stat.size);
+      this.index(fd, Math.min(this.end, this.offset + bytes));
+      this.stamp = journalStamp(stat);
+      return previous !== this.records.length;
     } finally {
       fs.closeSync(fd);
     }
-    if (this.records[0]?.value.type !== "session") {
-      throw new Error("Not a readable native Pi session.");
+  }
+  /** Project one immutable, published record, including bounded slices of very large strings. */
+  async project(
+    record: NativeRecord,
+    select: Projection,
+    stringChunk?: StringChunk,
+    signal?: AbortSignal,
+  ): Promise<UnknownRecord> {
+    const fd = fs.openSync(this.file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+    let stream: fs.ReadStream | undefined;
+    try {
+      const stat = fs.fstatSync(fd, { bigint: true });
+      if (`${stat.dev}:${stat.ino}` !== this.identity || Number(stat.size) < record.end) {
+        throw new Error("Native journal was replaced or truncated.");
+      }
+      let value: UnknownRecord | undefined;
+      const frames = new JournalFrames(
+        select,
+        (entry) => {
+          value = entry.value;
+        },
+        { policy: "live", start: record.start, stringChunk },
+      );
+      stream = fs.createReadStream(this.file, {
+        fd,
+        start: record.start,
+        end: record.end - 1,
+        highWaterMark: 65536,
+        signal,
+      });
+      for await (const chunk of stream) {
+        if (!Buffer.isBuffer(chunk)) {
+          throw new TypeError("Native journal reads require bytes.");
+        }
+        frames.write(chunk);
+      }
+      frames.finish();
+      if (!value) {
+        throw new Error("Native entry is not published.");
+      }
+      return value;
+    } finally {
+      if (stream) {
+        stream.destroy();
+      } else {
+        fs.closeSync(fd);
+      }
     }
   }
-  branch(leaf?: string | null, endedAt?: number): NativeRecord[] {
+  branch(leaf?: string | null): NativeRecord[] {
     if (leaf === null) {
       return [];
     }
-    const eligible =
-      endedAt === undefined
-        ? this.records
-        : this.records.filter(
-            (record) =>
-              record.value.type === "session" ||
-              Date.parse(record.value.timestamp ?? "") <= endedAt,
-          );
     let current =
       leaf !== undefined && leaf !== ""
         ? this.byId.get(leaf)
-        : eligible.findLast((record) => record.value.type !== "session");
+        : this.records.findLast((record) => record.value.type !== "session");
     const path: NativeRecord[] = [];
     const seen = new Set<string>();
-    const allowed = new Set(eligible.map((record) => record.value.id));
-    while (current && current.value.type !== "session" && allowed.has(current.value.id)) {
+    while (current && current.value.type !== "session") {
       if (seen.has(current.value.id)) {
         throw new Error("Cyclic journal ancestry");
       }
@@ -139,33 +232,22 @@ export class NativeJournal {
       fs.closeSync(fd);
     }
   }
-  configuration(
-    endedAt?: number,
-    leaf?: string | null,
-  ): {
-    model?: string;
-    thinking?: string;
-    modelRecordedAt?: number;
-  } {
-    const result: ReturnType<NativeJournal["configuration"]> = {};
-    let model: NativePreview | undefined;
-    for (const { value } of this.branch(leaf, endedAt)) {
-      if (value.type === "thinking_level_change" && typeof value.thinkingLevel === "string") {
-        result.thinking = value.thinkingLevel;
-      }
-      if (
-        value.type === "model_change" ||
-        (value.type === "message" && recordAt(value, "message")?.role === "assistant")
-      ) {
-        model = value;
-      }
-    }
-    if (model) {
-      result.model = configurationModel(model);
-      result.modelRecordedAt = Date.parse(model.timestamp ?? "");
-    }
-    return result;
-  }
+}
+/** Native v3 writers append after attachment; loading older formats can rewrite in place.
+ * Outside prefix edits followed by same-inode growth are not an append-only operation.
+ */
+export function nativeAppend(
+  before: fs.BigIntStats,
+  after: fs.BigIntStats,
+  header: UnknownRecord | undefined,
+): boolean {
+  return (
+    header?.type === "session" &&
+    header.version === 3 &&
+    before.dev === after.dev &&
+    before.ino === after.ino &&
+    after.size > before.size
+  );
 }
 export function journalStamp(stat: fs.BigIntStats): string {
   return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;

package/src/shared/parking.ts

@@ -0,0 +1,22 @@
+import type { NativeHistory } from "../pi-intercom/last-message.ts";
+import { isRecord } from "./unknown.ts";
+
+/** A child actor asks its intercom to fence broker input before parking, or to release it. */
+export const PARK = "pi-subagents:park";
+export interface ParkRequest {
+  readonly park: boolean;
+  readonly reply: (parked: Promise<boolean>) => void;
+}
+/** A main intercom wakes or reads an exited parked child through the agent runtime. */
+export const WAKE = "pi-subagents:wake";
+export const PARKED_HISTORY = "pi-subagents:parked-history";
+export interface HistoryRequest {
+  readonly peer: string;
+  readonly reply: (history: Promise<NativeHistory | undefined>) => void;
+}
+export function isParkRequest(value: unknown): value is ParkRequest {
+  return isRecord(value) && typeof value.park === "boolean" && typeof value.reply === "function";
+}
+export function isHistoryRequest(value: unknown): value is HistoryRequest {
+  return isRecord(value) && typeof value.peer === "string" && typeof value.reply === "function";
+}

package/src/shared/post-exit-stdio-guard.ts

@@ -1,7 +1,10 @@
-import { execFileSync, type ChildProcess } from "node:child_process";
-import { readLinuxProcess } from "../pi-intercom/broker/pid.ts";
+import { execFile, execFileSync, type ChildProcess } from "node:child_process";
+import { readFileSync, readlinkSync } from "node:fs";
+import { isLinuxProcessReplaced, readLinuxProcess } from "../pi-intercom/broker/pid.ts";
 import { hasErrorCode } from "./unknown.ts";
 
+const BIRTH_FIELDS = ["lstart=", "pgid="];
+
 interface AgentProcessExit {
   readonly pid?: number;
   readonly code: number | null;
@@ -20,6 +23,31 @@ interface ChildWithKill {
   readonly kill: (signal?: NodeJS.Signals | number) => boolean;
 }
 
+interface ProcessClock {
+  readonly boot: string;
+  readonly namespace: string;
+  readonly at: string;
+}
+
+/** Capture only a real, cross-process clock context; unavailable context proves nothing. */
+export function readProcessClock(): ProcessClock | undefined {
+  if (process.platform !== "android") {
+    return undefined;
+  }
+  try {
+    const boot = readFileSync("/proc/sys/kernel/random/boot_id", "utf8").trim();
+    const namespace = readlinkSync("/proc/self/ns/time");
+    const at = process.hrtime.bigint();
+    return at > 0n &&
+      /^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/.test(boot) &&
+      /^time:\[\d+\]$/.test(namespace)
+      ? { boot, namespace, at: at.toString() }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** Capture the detached group leader's birth identity; Pi may replace its command-line title. */
 export function readChildProcessIdentity(pid: number): string | undefined {
   if (!Number.isSafeInteger(pid) || pid <= 0) {
@@ -28,21 +56,151 @@ export function readChildProcessIdentity(pid: number): string | undefined {
   if (process.platform === "linux") {
     return readLinuxProcess(pid)?.identity;
   }
+  return groupLeader(pid, readPsFields(pid, BIRTH_FIELDS));
+}
+
+function groupLeader(pid: number, birth: string | undefined): string | undefined {
+  return Number(birth?.split(" ").at(-1)) === pid ? birth : undefined;
+}
+
+// Always one PID: Darwin ps given several PIDs scans every process at many times the cost.
+function psArguments(pid: number, fields: readonly string[]): string[] {
+  return ["-p", String(pid), ...fields.flatMap((field) => ["-o", field])];
+}
+
+function psOptions(zone: string | undefined) {
+  const env = { ...process.env, LC_ALL: "C", ...(zone === undefined ? {} : { TZ: zone }) };
+  return { encoding: "utf8" as const, timeout: 1000, env };
+}
+
+function readPsFields(pid: number, fields: readonly string[], zone?: string): string | undefined {
   try {
-    const identity = execFileSync("ps", ["-p", String(pid), "-o", "lstart=", "-o", "pgid="], {
-      encoding: "utf8",
-      timeout: 1000,
+    return execFileSync("ps", psArguments(pid, fields), {
+      ...psOptions(zone),
       stdio: ["ignore", "pipe", "ignore"],
-      env: { ...process.env, LC_ALL: "C" },
     })
       .trim()
       .replace(/\s+/g, " ");
-    return Number(identity.split(" ").at(-1)) === pid ? identity : undefined;
   } catch {
     return undefined;
   }
 }
 
+/** Nonblocking `readPsFields`; a failed run likewise observes nothing. */
+function observePsFields(
+  pid: number,
+  fields: readonly string[],
+  zone?: string,
+): Promise<string | undefined> {
+  return new Promise((resolve) => {
+    execFile("ps", psArguments(pid, fields), psOptions(zone), (error, stdout) => {
+      resolve(error ? undefined : stdout.trim().replace(/\s+/g, " "));
+    });
+  });
+}
+
+// C-locale ps lstart (whole-second birth, in the reader's zone), then the process group.
+const PS_IDENTITY = /^[A-Z][a-z]{2} ([A-Z][a-z]{2}) (\d{1,2}) (\d{2}):(\d{2}):(\d{2}) (\d{4}) \d+$/;
+const MONTHS = "JanFebMarAprMayJunJulAugSepOctNovDec";
+
+/** Parses a birth observed with TZ=UTC0. */
+function utcBirth(birth: string | undefined): number {
+  const [, month = "", day, hours, minutes, seconds, year] = PS_IDENTITY.exec(birth ?? "") ?? [];
+  const index = MONTHS.indexOf(month);
+  // Unreadable or malformed observations yield NaN, which never proves a later birth.
+  return month.length === 3 && index % 3 === 0
+    ? Date.UTC(
+        Number(year),
+        index / 3,
+        Number(day),
+        Number(hours),
+        Number(minutes),
+        Number(seconds),
+      )
+    : Number.NaN;
+}
+
+function sameClock(left: ProcessClock, right: ProcessClock): boolean {
+  return left.boot === right.boot && left.namespace === right.namespace;
+}
+
+/** Android's elapsed age bounds birth in the saved monotonic clock, never wall time. */
+function clockBound(clock: ProcessClock | undefined) {
+  const before = readProcessClock();
+  return clock !== undefined && before !== undefined && sameClock(clock, before)
+    ? { clock, before }
+    : undefined;
+}
+
+/** `elapsed` is observed after the bound's `before` read; the closing clock read follows both. */
+function bornAfter(
+  { clock, before }: { clock: ProcessClock; before: ProcessClock },
+  elapsed = "",
+): boolean {
+  const after = readProcessClock();
+  if (after === undefined || !sameClock(before, after) || !/^\d+$/.test(elapsed)) {
+    return false;
+  }
+  // Include displayed-second and native tick uncertainty. BOOTTIME age includes suspend,
+  // unlike hrtime's MONOTONIC clock, so suspend only moves this lower bound earlier.
+  const birth = BigInt(before.at) - (BigInt(elapsed) + 2n) * 1_000_000_000n;
+  return BigInt(after.at) >= BigInt(before.at) && birth > BigInt(clock.at);
+}
+
+/**
+ * True only when a live PID provably names a different process than an owner-published record.
+ * Darwin identities are unzoned local times, so they are never compared across zones; only a
+ * UTC-observed birth strictly after the record's publication proves replacement. Android uses
+ * a conservative elapsed-age bound against its recorded boot-qualified monotonic clock.
+ */
+export function isChildProcessReplaced(
+  pid: number,
+  recorded: string,
+  published?: number,
+  clock?: ProcessClock,
+): boolean {
+  if (process.platform === "linux") {
+    return isLinuxProcessReplaced(pid, recorded);
+  }
+  if (!PS_IDENTITY.test(recorded)) {
+    return false;
+  }
+  if (process.platform === "android") {
+    const bound = clockBound(clock);
+    return bound !== undefined && bornAfter(bound, readPsFields(pid, ["etimes="]));
+  }
+  return published !== undefined && utcBirth(readPsFields(pid, BIRTH_FIELDS, "UTC0")) > published;
+}
+
+/**
+ * Nonblocking `readChildProcessIdentity(pid) !== recorded && isChildProcessReplaced(...)` for
+ * routine liveness. Signals still need the fresh synchronous proof.
+ */
+export async function observeChildProcessReplaced(
+  pid: number,
+  recorded: string,
+  published?: number,
+  clock?: ProcessClock,
+): Promise<boolean> {
+  if (process.platform === "linux") {
+    return readChildProcessIdentity(pid) !== recorded && isLinuxProcessReplaced(pid, recorded);
+  }
+  if (
+    !PS_IDENTITY.test(recorded) ||
+    groupLeader(pid, await observePsFields(pid, BIRTH_FIELDS)) === recorded
+  ) {
+    return false;
+  }
+  if (process.platform === "android") {
+    const bound = clockBound(clock);
+    return bound !== undefined && bornAfter(bound, await observePsFields(pid, ["etimes="]));
+  }
+  if (published === undefined) {
+    return false;
+  }
+  return utcBirth(await observePsFields(pid, BIRTH_FIELDS, "UTC0")) > published;
+}
+
 function trySignalChild(child: ChildWithKill, signal: NodeJS.Signals): boolean {
   try {
     return child.kill(signal);

package/src/shared/tui-action.ts

@@ -0,0 +1,39 @@
+import {
+  MouseRegion,
+  TruncatedText,
+  truncateToWidth,
+  visibleWidth,
+  type Component,
+} from "@earendil-works/pi-tui";
+
+export function actionText(text: string, action: (column: number) => void): Component {
+  const component = new TruncatedText(text, 0, 0);
+  return new MouseRegion(component, (event) => {
+    if (
+      (event.type !== "press" && event.type !== "click") ||
+      event.button !== "left" ||
+      event.x >= visibleWidth(truncateToWidth(text, event.width))
+    ) {
+      return;
+    }
+    if (event.type === "click") {
+      action(event.x);
+    }
+    return { handled: true, render: event.type === "click" };
+  });
+}
+
+/** Each visible hint dispatches the same action as its corresponding keyboard binding. */
+export function actionHints(hints: readonly { text: string; action: () => void }[]): Component {
+  return actionText(hints.map((hint) => hint.text).join(" · "), (column) => {
+    let start = 0;
+    for (const hint of hints) {
+      const end = start + visibleWidth(hint.text);
+      if (column >= start && column < end) {
+        hint.action();
+        return;
+      }
+      start = end + 3;
+    }
+  });
+}

package/tsconfig.client.json

@@ -0,0 +1,8 @@
+{
+  "extends": "./tsconfig.build.json",
+  "compilerOptions": {
+    "declaration": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src/intercom-client.ts"]
+}

package/tsconfig.json

@@ -4,6 +4,7 @@
     "lib": ["ES2025"],
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
+    "customConditions": ["development"],
     "allowImportingTsExtensions": true,
     "verbatimModuleSyntax": true,
     "erasableSyntaxOnly": true,

package/src/shared/stream-json.d.ts

@@ -1,10 +0,0 @@
-import type { Many, none } from "stream-chain/defs.js";
-import type { ParserOptions, Token } from "stream-json/core/parser.js";
-
-// stream-json 3.7.0 exports the synchronous tokenizer used by its default
-// generator adapter, but omits this export from parser.d.ts.
-declare module "stream-json/core/parser.js" {
-  export function jsonParser(
-    options?: Readonly<ParserOptions>,
-  ): (chunk: string | typeof none) => Many<Token> | typeof none;
-}