@signalridge/pi-sessions 0.0.0-stage → 1.2.0

package/src/ownership.ts

@@ -0,0 +1,133 @@
+import { createHash } from "node:crypto";
+import type { ExtensionCommandContext, ExtensionContext, SessionShutdownEvent } from "@earendil-works/pi-coding-agent";
+
+export class Retired extends Error {
+  constructor() {
+    super("Session interaction retired");
+  }
+}
+
+export function branchFingerprint(ctx: ExtensionContext): string {
+  // All native data, not just a leaf ID or the model-visible messages. This also catches
+  // context edits and same-leaf in-place changes before a delayed lifecycle event arrives.
+  return createHash("sha256").update(JSON.stringify(ctx.sessionManager.getBranch())).digest("hex");
+}
+
+export function modelIdentity(ctx: Pick<ExtensionContext, "model">): string {
+  return ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : "";
+}
+
+function selectedModelFingerprint(ctx: Pick<ExtensionContext, "model">): string {
+  return createHash("sha256")
+    .update(JSON.stringify(ctx.model ?? null))
+    .digest("hex");
+}
+
+export class Owner<Context extends ExtensionContext = ExtensionCommandContext> {
+  readonly controller = new AbortController();
+  readonly manager;
+  readonly id: string;
+  readonly file: string | undefined;
+  readonly fingerprint: string;
+  readonly model: string;
+  private readonly modelData: string;
+  readonly draft: string | undefined;
+  readonly editorFactory;
+  committing: "new" | "resume" | undefined;
+  // One delivered preflight belongs to our initiated replacement. Keep the
+  // committing marker separately: shutdown must retain recovery after revocation.
+  expectedSwitch = false;
+  target: string | undefined;
+  replacementStarted = false;
+  replacementApproved = false;
+  private retired = false;
+  private timer: ReturnType<typeof setInterval>;
+
+  constructor(
+    readonly ctx: Context,
+    readonly requireModel: boolean,
+  ) {
+    this.manager = ctx.sessionManager;
+    this.id = this.manager.getSessionId();
+    this.file = this.manager.getSessionFile();
+    this.fingerprint = branchFingerprint(ctx);
+    this.model = modelIdentity(ctx);
+    this.modelData = selectedModelFingerprint(ctx);
+    this.draft = ctx.mode === "tui" ? ctx.ui.getEditorText() : undefined;
+    this.editorFactory = ctx.mode === "tui" ? ctx.ui.getEditorComponent() : undefined;
+    this.timer = setInterval(() => this.current(), 75);
+    this.timer.unref();
+  }
+
+  get signal(): AbortSignal {
+    return this.controller.signal;
+  }
+
+  current(): boolean {
+    if (this.retired) return false;
+    try {
+      if (
+        this.ctx.sessionManager !== this.manager ||
+        this.manager.getSessionId() !== this.id ||
+        this.manager.getSessionFile() !== this.file ||
+        branchFingerprint(this.ctx) !== this.fingerprint ||
+        (this.requireModel &&
+          (modelIdentity(this.ctx) !== this.model || selectedModelFingerprint(this.ctx) !== this.modelData)) ||
+        (this.draft !== undefined &&
+          (this.ctx.ui.getEditorText() !== this.draft || this.ctx.ui.getEditorComponent() !== this.editorFactory))
+      ) {
+        this.retire();
+      }
+    } catch {
+      this.retire();
+    }
+    return !this.retired;
+  }
+
+  check(): void {
+    if (!this.current()) throw new Retired();
+  }
+
+  retire(): void {
+    if (this.retired) return;
+    this.retired = true;
+    clearInterval(this.timer);
+    this.controller.abort();
+  }
+
+  shutdown(event: SessionShutdownEvent): void {
+    // Retain recovery data once native replacement begins, even when approval
+    // was revoked during a later asynchronous before-switch handler. Only a
+    // still-current owner may carry prefill approval across normal teardown.
+    if (this.committing && event.reason === this.committing) {
+      this.replacementStarted = true;
+      this.replacementApproved = this.current();
+    }
+    this.retire();
+  }
+
+  finish(): void {
+    this.retire();
+  }
+
+  /** Stop waiting promptly even if a provider or RPC editor ignores cancellation.
+   * Late results are consumed, never allowed to mutate the retired owner. */
+  async wait<T>(work: Promise<T>): Promise<T> {
+    if (!this.current()) {
+      void work.catch(() => {});
+      throw new Retired();
+    }
+    let abort!: () => void;
+    const cancellation = new Promise<never>((_resolve, reject) => {
+      abort = () => reject(new Retired());
+      this.signal.addEventListener("abort", abort, { once: true });
+    });
+    try {
+      const value = await Promise.race([work, cancellation]);
+      this.check();
+      return value;
+    } finally {
+      this.signal.removeEventListener("abort", abort);
+    }
+  }
+}

package/src/session-payload.ts

@@ -0,0 +1,189 @@
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+function record(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function content(value: unknown): boolean {
+  return (
+    typeof value === "string" ||
+    (Array.isArray(value) &&
+      value.every((part: unknown) => {
+        if (!record(part)) return false;
+        switch (part.type) {
+          case "text":
+            return typeof part.text === "string";
+          case "image":
+            return typeof part.data === "string" && typeof part.mimeType === "string";
+          case "thinking":
+            return typeof part.thinking === "string";
+          case "toolCall":
+            return typeof part.id === "string" && typeof part.name === "string" && record(part.arguments);
+          default:
+            return false;
+        }
+      }))
+  );
+}
+function arrayContent(value: unknown, kinds: readonly string[]): boolean {
+  return (
+    Array.isArray(value) &&
+    content(value) &&
+    value.every((part: unknown) => record(part) && typeof part.type === "string" && kinds.includes(part.type))
+  );
+}
+function optionalBoolean(value: unknown): boolean {
+  return value === undefined || typeof value === "boolean";
+}
+function optionalString(value: unknown): boolean {
+  return value === undefined || typeof value === "string";
+}
+function numericFields(value: Record<string, unknown>, fields: readonly string[]): boolean {
+  return fields.every((field) => typeof value[field] === "number" && Number.isFinite(value[field]));
+}
+function usage(value: unknown): boolean {
+  return (
+    record(value) &&
+    numericFields(value, ["input", "output", "cacheRead", "cacheWrite", "totalTokens"]) &&
+    record(value.cost) &&
+    numericFields(value.cost, ["input", "output", "cacheRead", "cacheWrite", "total"]) &&
+    ["cacheWrite1h", "reasoning"].every((field) => value[field] === undefined || numericFields(value, [field]))
+  );
+}
+function systemContent(value: unknown): boolean {
+  return (
+    typeof value === "string" ||
+    (Array.isArray(value) &&
+      value.every((part: unknown) => record(part) && part.type === "text" && typeof part.text === "string"))
+  );
+}
+
+function systemMessage(value: unknown): boolean {
+  return (
+    record(value) &&
+    value.role === "system" &&
+    numericFields(value, ["timestamp"]) &&
+    systemContent(value.content) &&
+    (value.sections === undefined ||
+      (record(value.sections) &&
+        Object.values(value.sections).every((section) => section === null || typeof section === "string"))) &&
+    (value.toolsAdded === undefined ||
+      (Array.isArray(value.toolsAdded) &&
+        value.toolsAdded.every(
+          (tool: unknown) =>
+            record(tool) &&
+            typeof tool.name === "string" &&
+            typeof tool.description === "string" &&
+            record(tool.parameters),
+        ))) &&
+    (value.toolsRemoved === undefined ||
+      (Array.isArray(value.toolsRemoved) &&
+        value.toolsRemoved.every((tool: unknown) => record(tool) && typeof tool.name === "string")))
+  );
+}
+
+/** Validate fields consumed by native restoration before disposing the source.
+ * Arbitrary custom data/details remain opaque; this is not a provider schema. */
+export function validateEntryPayload(value: Record<string, unknown>, byId: ReadonlyMap<string, SessionEntry>): void {
+  let valid = false;
+  switch (value.type) {
+    case "message": {
+      const message = value.message;
+      if (!record(message) || !numericFields(message, ["timestamp"])) break;
+      switch (message.role) {
+        case "assistant":
+          valid =
+            arrayContent(message.content, ["text", "thinking", "toolCall"]) &&
+            usage(message.usage) &&
+            optionalString(message.errorMessage);
+          break;
+        case "toolResult":
+          valid =
+            arrayContent(message.content, ["text", "image"]) && (message.usage === undefined || usage(message.usage));
+          break;
+        case "user":
+          valid = typeof message.content === "string" || arrayContent(message.content, ["text", "image"]);
+          break;
+        case "system":
+          valid = systemMessage(message);
+          break;
+        case "custom":
+          valid =
+            typeof message.customType === "string" &&
+            typeof message.display === "boolean" &&
+            (typeof message.content === "string" || arrayContent(message.content, ["text", "image"]));
+          break;
+        case "bashExecution":
+          valid =
+            typeof message.command === "string" &&
+            typeof message.output === "string" &&
+            typeof message.cancelled === "boolean" &&
+            typeof message.truncated === "boolean" &&
+            optionalString(message.fullOutputPath) &&
+            optionalBoolean(message.excludeFromContext) &&
+            (message.exitCode === undefined ||
+              (typeof message.exitCode === "number" && Number.isSafeInteger(message.exitCode)));
+          break;
+        case "branchSummary":
+          valid =
+            typeof message.summary === "string" && (message.fromId === null || typeof message.fromId === "string");
+          break;
+        case "compactionSummary":
+          valid = typeof message.summary === "string" && numericFields(message, ["tokensBefore"]);
+          break;
+      }
+      break;
+    }
+    case "context_edit": {
+      const target = typeof value.targetId === "string" ? byId.get(value.targetId) : undefined;
+      const editable =
+        target?.type === "custom_message" ||
+        (target?.type === "message" && ["user", "assistant", "toolResult"].includes(target.message.role));
+      valid =
+        editable && (value.replacement === null || (record(value.replacement) && content(value.replacement.content)));
+      break;
+    }
+    case "model_change":
+      valid = typeof value.provider === "string" && typeof value.modelId === "string";
+      break;
+    case "thinking_level_change":
+      valid = typeof value.thinkingLevel === "string";
+      break;
+    case "usage":
+      valid =
+        typeof value.kind === "string" &&
+        typeof value.provider === "string" &&
+        typeof value.model === "string" &&
+        usage(value.usage) &&
+        optionalString(value.note);
+      break;
+    case "compaction":
+      valid =
+        typeof value.summary === "string" &&
+        typeof value.firstKeptEntryId === "string" &&
+        typeof value.tokensBefore === "number" &&
+        Number.isFinite(value.tokensBefore) &&
+        value.tokensBefore >= 0 &&
+        (value.usage === undefined || usage(value.usage)) &&
+        (value.systemMessage === undefined || systemMessage(value.systemMessage));
+      break;
+    case "branch_summary":
+      valid =
+        typeof value.summary === "string" &&
+        typeof value.fromId === "string" &&
+        (value.usage === undefined || usage(value.usage));
+      break;
+    case "custom":
+      valid = typeof value.customType === "string";
+      break;
+    case "custom_message":
+      valid = typeof value.customType === "string" && content(value.content) && typeof value.display === "boolean";
+      break;
+    case "label":
+      valid = typeof value.targetId === "string" && optionalString(value.label);
+      break;
+    case "session_info":
+      valid = optionalString(value.name);
+      break;
+  }
+  if (!valid) throw new Error("Malformed native session payload");
+}

package/src/storage.ts

@@ -0,0 +1,213 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { type FileHandle, open, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { getCurrentSystemMessage } from "@earendil-works/pi-ai";
+import {
+  buildSessionProjection,
+  CURRENT_SESSION_VERSION,
+  estimateTokens,
+  migrateSessionEntries,
+  type SessionEntry,
+  type SessionHeader,
+  type SessionManager,
+} from "@earendil-works/pi-coding-agent";
+import { validateEntryPayload } from "./session-payload.js";
+import { bounded, messageText, PREVIEW_BYTES } from "./text.js";
+
+const FILE_BYTES = 32 * 1024 * 1024;
+const LINE_BYTES = 4 * 1024 * 1024;
+const ENTRY_TYPES = new Set([
+  "message",
+  "model_change",
+  "thinking_level_change",
+  "usage",
+  "compaction",
+  "branch_summary",
+  "custom",
+  "label",
+  "custom_message",
+  "context_edit",
+  "session_info",
+]);
+export interface Candidate {
+  path: string;
+  header: SessionHeader;
+  digest: string;
+  preview: string;
+  entries: readonly SessionEntry[];
+}
+
+/** Read through a fixed byte budget, even if an external writer grows the file.
+ * The extra byte is only an oversize probe; check cancellation between chunks. */
+async function readBounded(handle: FileHandle, signal: AbortSignal): Promise<string> {
+  const chunks: Buffer[] = [];
+  let total = 0;
+  while (total <= FILE_BYTES) {
+    signal.throwIfAborted();
+    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, FILE_BYTES + 1 - total));
+    const { bytesRead } = await handle.read({ buffer, offset: 0, length: buffer.length, position: total });
+    signal.throwIfAborted();
+    if (!bytesRead) break;
+    total += bytesRead;
+    if (total > FILE_BYTES) throw new Error("Oversized session");
+    chunks.push(buffer.subarray(0, bytesRead));
+  }
+  const bytes = Buffer.concat(chunks, total);
+  const text = bytes.toString("utf8");
+  if (!Buffer.from(text).equals(bytes)) throw new Error("Invalid UTF-8 session");
+  return text;
+}
+
+/** Vet without opening a SessionManager (which can initialize/rewrite malformed files).
+ * Limits apply to our validation/preview, not to the SDK's list implementation. */
+export async function vetSession(path: string, expectedId: string, signal: AbortSignal): Promise<Candidate> {
+  signal.throwIfAborted();
+  if (!isAbsolute(path)) throw new Error("Session path must be absolute");
+  const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = await handle.stat();
+    if (!before.isFile() || !before.size || before.size > FILE_BYTES)
+      throw new Error("Unreadable or oversized session");
+    const body = await readBounded(handle, signal);
+    signal.throwIfAborted();
+    const after = await handle.stat();
+    if (before.size !== after.size || before.mtimeMs !== after.mtimeMs)
+      throw new Error("Session changed while reading");
+    const lines = body.trimEnd().split("\n");
+    let header: SessionHeader | undefined;
+    const recent: string[] = [];
+    const ids = new Set<string>();
+    const entries: SessionEntry[] = [];
+    const byId = new Map<string, SessionEntry>();
+    for (let index = 0; index < lines.length; index++) {
+      const line = lines[index];
+      if (Buffer.byteLength(line) > LINE_BYTES) throw new Error("Oversized session entry");
+      const value: unknown = JSON.parse(line);
+      if (!value || typeof value !== "object" || Array.isArray(value) || !("type" in value))
+        throw new Error("Malformed session entry");
+      if (index === 0) {
+        if (
+          value.type !== "session" ||
+          !("id" in value) ||
+          value.id !== expectedId ||
+          !("cwd" in value) ||
+          typeof value.cwd !== "string" ||
+          !isAbsolute(value.cwd) ||
+          !("timestamp" in value) ||
+          typeof value.timestamp !== "string" ||
+          !Number.isFinite(Date.parse(value.timestamp)) ||
+          !("version" in value) ||
+          (value.version !== 2 && value.version !== CURRENT_SESSION_VERSION)
+        ) {
+          throw new Error("Session identity/header no longer matches");
+        }
+        header = value as SessionHeader;
+      } else {
+        if (
+          typeof value.type !== "string" ||
+          !ENTRY_TYPES.has(value.type) ||
+          !("id" in value) ||
+          typeof value.id !== "string" ||
+          !value.id ||
+          ids.has(value.id) ||
+          !("parentId" in value) ||
+          (value.parentId !== null && (typeof value.parentId !== "string" || !ids.has(value.parentId))) ||
+          !("timestamp" in value) ||
+          typeof value.timestamp !== "string" ||
+          !Number.isFinite(Date.parse(value.timestamp))
+        )
+          throw new Error("Malformed session tree");
+        entries.push(value as SessionEntry);
+        ids.add(value.id);
+      }
+    }
+    if (!header) throw new Error("Missing session header");
+    // Migrations mutate their argument. Keep raw header/bytes for identity and
+    // digest, and normalize only a clone before native payload validation.
+    const normalized = structuredClone([header, ...entries]);
+    migrateSessionEntries(normalized);
+    const migrated = normalized.slice(1) as SessionEntry[];
+    for (const entry of migrated) {
+      validateEntryPayload(entry as unknown as Record<string, unknown>, byId);
+      byId.set(entry.id, entry);
+      const text = messageText(entry);
+      if (text) {
+        recent.push(text);
+        if (recent.length > 6) recent.shift();
+      }
+    }
+    // Public pure replay and estimation exercise the footer's consumed shape,
+    // not just projection. Never open/repair a manager during preflight.
+    const projection = buildSessionProjection(migrated, undefined, byId);
+    const system = getCurrentSystemMessage(projection.messages);
+    if (system) estimateTokens(system);
+    for (const message of projection.messages) if (message.role !== "system") estimateTokens(message);
+    if (!(await stat(header.cwd)).isDirectory()) throw new Error("Session workspace unavailable");
+    signal.throwIfAborted();
+    return {
+      path: resolve(path),
+      header,
+      digest: createHash("sha256").update(body).digest("hex"),
+      preview: bounded(recent.join("\n\n"), PREVIEW_BYTES),
+      entries: migrated,
+    };
+  } finally {
+    await handle.close();
+  }
+}
+
+export interface Snapshot {
+  path: string;
+  id: string;
+  cleanup(): void;
+}
+export function snapshotBranch(cwd: string, branch: readonly SessionEntry[], parentSession?: string): Snapshot {
+  const directory = mkdtempSync(join(tmpdir(), "pi-sessions-parent-"));
+  const cleanup = () => rmSync(directory, { recursive: true, force: true });
+  try {
+    const id = randomUUID();
+    const path = join(directory, `${id}.jsonl`);
+    const header: SessionHeader = {
+      type: "session",
+      version: CURRENT_SESSION_VERSION,
+      id,
+      cwd,
+      timestamp: new Date().toISOString(),
+      ...(parentSession ? { parentSession } : {}),
+    };
+    writeFileSync(path, `${[header, ...structuredClone(branch)].map((entry) => JSON.stringify(entry)).join("\n")}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    return { path, id, cleanup };
+  } catch (error) {
+    cleanup();
+    throw error;
+  }
+}
+
+/** Pi 1.0.4 defers custom-only sessions until the first human turn. Materialize
+ * exactly the public native header/entries, then re-open through the public API
+ * to keep subsequent append persistence coherent. No synthetic model message. */
+export function persistHandoff(manager: SessionManager): string {
+  let path = manager.getSessionFile();
+  if (!path) {
+    const directory = mkdtempSync(join(tmpdir(), "pi-sessions-handoff-"));
+    path = join(directory, `${manager.getSessionId()}.jsonl`);
+  }
+  const header = manager.getHeader();
+  if (!header) throw new Error("Missing destination header");
+  const entries = manager.getEntries();
+  // Never remove a file after native replacement: it may already be the only
+  // recovery record. Exclusive creation cannot overwrite pre-existing history.
+  writeFileSync(path, `${[header, ...entries].map((entry) => JSON.stringify(entry)).join("\n")}\n`, {
+    encoding: "utf8",
+    flag: "wx",
+    mode: 0o600,
+  });
+  manager.setSessionFile(path);
+  return path;
+}

package/src/text.ts

@@ -0,0 +1,80 @@
+import { stripVTControlCharacters } from "node:util";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const SUMMARY_BYTES = 16 * 1024;
+export const PREVIEW_BYTES = 6 * 1024;
+export const SHARE_BYTES = 16 * 1024;
+export const ROW_LIMIT = 200;
+export const PAGE_ROWS = 12;
+
+/** Remove terminal instructions, bidi/format controls and unpaired surrogates; keep CJK and newlines. */
+export function plain(text: string): string {
+  return stripVTControlCharacters(text.replace(/\p{Surrogate}/gu, "")).replace(/[\p{Cc}\p{Cf}]/gu, (c) =>
+    c === "\n" ? "\n" : c === "\t" ? " " : "",
+  );
+}
+
+/** UTF-8 prefix, never a broken code point. Only used for unapproved previews/input context. */
+export function bounded(text: string, bytes: number): string {
+  let result = "";
+  let used = 0;
+  for (const c of text) {
+    const size = Buffer.byteLength(c);
+    if (used + size > bytes) break;
+    result += c;
+    used += size;
+  }
+  return result;
+}
+
+export function label(text: string, bytes = 180): string {
+  return bounded(plain(text).replace(/\s+/gu, " ").trim(), bytes);
+}
+
+/** Conservative defaults, not a promise to identify every secret in prose. Human review is required. */
+export function redact(text: string): string {
+  return text
+    .replace(/-----BEGIN [^-]*PRIVATE KEY-----[\s\S]*?(?:-----END [^-]*PRIVATE KEY-----|$)/gu, "[private key omitted]")
+    .replace(/\b(?:sk-[\w-]{12,}|gh[pousr]_[\w]{16,}|AKIA[A-Z0-9]{16})\b/gu, "[credential omitted]")
+    .replace(
+      /(\b(?:authorization|api[_-]?key|access[_-]?token|password|secret)\s*[:=]\s*)(?:Bearer\s+)?[^\s,;]+/giu,
+      "$1[omitted]",
+    );
+}
+
+export function messageText(entry: unknown): string | undefined {
+  if (!entry || typeof entry !== "object" || !("type" in entry) || entry.type !== "message") return;
+  if (!("message" in entry) || !entry.message || typeof entry.message !== "object") return;
+  const message = entry.message;
+  if (!("role" in message) || (message.role !== "user" && message.role !== "assistant")) return;
+  if (!("content" in message)) return;
+  const content = message.content;
+  let text = typeof content === "string" ? bounded(content, 8192) : "";
+  if (Array.isArray(content)) {
+    for (const block of content) {
+      if (block && typeof block === "object" && block.type === "text" && typeof block.text === "string") {
+        text = bounded(`${text}${text ? "\n" : ""}${bounded(block.text, 2048)}`, 8192);
+        if (Buffer.byteLength(text) >= 8192) break;
+      }
+    }
+  }
+  return `${message.role}: ${bounded(redact(plain(bounded(text, 8192))), 2048)}`;
+}
+
+export function recentText(branch: readonly SessionEntry[], maxBytes = SHARE_BYTES): string {
+  const parts: string[] = [];
+  let remaining = maxBytes;
+  for (let index = branch.length - 1; index >= 0 && parts.length < 12 && remaining > 2; index--) {
+    const text = messageText(branch[index]);
+    if (text) {
+      const selected = bounded(text, remaining - (parts.length ? 2 : 0));
+      remaining -= Buffer.byteLength(selected) + (parts.length ? 2 : 0);
+      parts.unshift(selected);
+    }
+  }
+  return parts.join("\n\n");
+}
+
+export function validSummary(text: string): boolean {
+  return !!text.trim() && Buffer.byteLength(text) <= SUMMARY_BYTES && plain(text) === text;
+}