@fitchmultz/pi-subagents 0.46.2 → 0.48.0

package/src/pi-intercom/native-control.ts

@@ -0,0 +1,160 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { IntercomLifecycle } from "./lifecycle.ts";
+import type { IntercomConnection } from "./connection.ts";
+import type { Message, SessionInfo } from "./types.ts";
+import { authorizedControlPeer } from "./native-control-auth.ts";
+import {
+  CONTROL_FALLBACK,
+  CONTROL_SCHEMA,
+  isControlRequest,
+  type NativeControlRequest,
+  type NativeControlResult,
+} from "./native-control-protocol.ts";
+import { readLiveTranscript, transcriptOptions } from "./transcript.ts";
+
+export class NativeControls {
+  private readonly lifecycle: Readonly<Pick<IntercomLifecycle, "live" | "generation">>;
+  private readonly connection: Readonly<Pick<IntercomConnection, "active">>;
+  constructor(lifecycle: NativeControls["lifecycle"], connection: NativeControls["connection"]) {
+    this.lifecycle = lifecycle;
+    this.connection = connection;
+  }
+  private result(ctx: ExtensionContext, request: NativeControlRequest): NativeControlResult {
+    const base = {
+      schema: CONTROL_SCHEMA,
+      kind: "result",
+      verb: request.verb,
+      mode: ctx.mode,
+      idle: ctx.isIdle(),
+      pendingInput: ctx.hasPendingMessages(),
+      queueCleared: false,
+      processExited: false,
+    } satisfies Partial<NativeControlResult>;
+    if (request.verb !== "transcript" && request.options !== undefined) {
+      throw new Error("Only transcript accepts options.");
+    }
+    const stopSupport = stopCapability(ctx);
+    switch (request.verb) {
+      case "capabilities":
+        return {
+          ...base,
+          status: "ok",
+          stopSupport,
+          verbs: ["capabilities", "cancel", "stop", "transcript"],
+        };
+      case "transcript":
+        return {
+          ...base,
+          status: "ok",
+          transcript: readLiveTranscript(ctx.sessionManager, transcriptOptions(request.options)),
+        };
+      case "cancel":
+        return {
+          ...base,
+          status: "cancel_requested",
+          reason: "Native current-operation abort; accepted queued input is not cleared.",
+        };
+      case "stop":
+        return {
+          ...base,
+          status:
+            ctx.mode === "print" || ctx.mode === "json" ? "unsupported" : "shutdown_requested",
+          stopSupport,
+          reason:
+            "Native shutdown/current-operation abort requested, not process exit. Idle RPC is deferred until a native command/settlement; print/JSON/SDK have no guaranteed shutdown binding.",
+        };
+    }
+  }
+  async receive(ctx: ExtensionContext, from: SessionInfo, message: Message): Promise<boolean> {
+    if (!Object.hasOwn(message, "control")) {
+      return false;
+    }
+    // Even malformed/response envelopes never enter conversation journaling or inference.
+    const request = message.control;
+    if (
+      !isControlRequest(request) ||
+      message.replyTo !== undefined ||
+      message.delivery !== "passive" ||
+      message.expectsReply === true
+    ) {
+      return true;
+    }
+    const generation = this.lifecycle.generation;
+    const active = this.connection.active;
+    if (!active || !this.lifecycle.live(ctx, generation)) {
+      return true;
+    }
+    const result = this.admit(ctx, from.id, request);
+    // Receipt is acknowledged before shutdown can retire this socket/context.
+    await active.send(from.id, {
+      text: CONTROL_FALLBACK,
+      delivery: "passive",
+      replyTo: message.id,
+      control: result,
+    });
+    this.apply(ctx, generation, { active, peer: from.id, request, result });
+    return true;
+  }
+  private apply(
+    ctx: ExtensionContext,
+    generation: number,
+    state: {
+      readonly active: NonNullable<IntercomConnection["active"]>;
+      readonly peer: string;
+      readonly request: NativeControlRequest;
+      readonly result: NativeControlResult;
+    },
+  ): void {
+    const { active, peer, request, result } = state;
+    if (
+      !this.lifecycle.live(ctx, generation) ||
+      this.connection.active !== active ||
+      !authorizedControlPeer(peer, request.certificate)
+    ) {
+      return;
+    }
+    if (
+      result.status === "shutdown_requested" ||
+      (result.status === "unsupported" && request.verb === "stop")
+    ) {
+      ctx.shutdown();
+      if (this.lifecycle.live(ctx, generation)) {
+        ctx.abort();
+      }
+    } else if (result.status === "cancel_requested") {
+      ctx.abort();
+    }
+  }
+  private admit(
+    ctx: ExtensionContext,
+    peer: string,
+    request: NativeControlRequest,
+  ): NativeControlResult {
+    if (!authorizedControlPeer(peer, request.certificate)) {
+      return {
+        schema: CONTROL_SCHEMA,
+        kind: "result",
+        verb: request.verb,
+        status: "denied",
+        reason: "Sender certificate is not currently authorized by private bridge configuration.",
+      };
+    }
+    try {
+      return this.result(ctx, request);
+    } catch {
+      return {
+        schema: CONTROL_SCHEMA,
+        kind: "result",
+        verb: request.verb,
+        status: "failed",
+        reason: "Native control input/state is unavailable.",
+      };
+    }
+  }
+}
+function stopCapability(ctx: ExtensionContext): NativeControlResult["stopSupport"] {
+  if (ctx.mode === "tui") {
+    return "native_shutdown";
+  }
+  return ctx.mode === "rpc" ? "requires_activity" : "host_dependent";
+}

package/src/pi-intercom/saved-transcript.ts

@@ -0,0 +1,175 @@
+import { constants, openSync, closeSync, fstatSync } from "node:fs";
+import type * as NativeSession from "@earendil-works/pi-coding-agent";
+import { loadNativeSession } from "../shared/native-session-loader.ts";
+import { scanJournal, type Projection } from "../shared/journal-reader.ts";
+import { Fault } from "./bridge-protocol.ts";
+import { readLiveTranscript, type TranscriptOptions, type TranscriptPage } from "./transcript.ts";
+
+const FILE_BYTES = 64 * 1024 * 1024;
+const ENTRY_COUNT = 50000;
+const TEXT_LIMIT = 131072;
+const fields = new Set([
+  "type",
+  "id",
+  "parentId",
+  "timestamp",
+  "version",
+  "cwd",
+  "customType",
+  "display",
+  "content",
+]);
+/** Only branch structure and public textual content are hydrated, never image/provider/custom data. */
+const transcriptProjection: Projection = (path) => {
+  if (path.length === 0) {
+    return true;
+  }
+  if (path[0] === "message") {
+    return messageField(path.slice(1));
+  }
+  if (path[0] === "content") {
+    return contentField(path.slice(1));
+  }
+  return path.length === 1 && fields.has(String(path[0])) ? 4096 : false;
+};
+function messageField(path: readonly (string | number)[]): boolean | number {
+  if (path.length === 0) {
+    return true;
+  }
+  if (path[0] === "content") {
+    return contentField(path.slice(1));
+  }
+  return path.length === 1 && ["role", "output", "display", "truncated"].includes(String(path[0]))
+    ? TEXT_LIMIT
+    : false;
+}
+function contentField(path: readonly (string | number)[]): boolean | number {
+  return path.length < 2 || (path.length === 2 && ["type", "text"].includes(String(path[1])))
+    ? TEXT_LIMIT
+    : false;
+}
+function textField(path: readonly (string | number)[]): boolean {
+  if (path[0] === "message") {
+    return (
+      (path.length === 2 && ["content", "output"].includes(String(path[1]))) ||
+      (path.length === 4 && path[1] === "content" && path[3] === "text")
+    );
+  }
+  return path[0] === "content" && (path.length === 1 || (path.length === 3 && path[2] === "text"));
+}
+function savedLines(
+  fd: number,
+  size: number,
+): { readonly lines: readonly string[]; readonly cut: ReadonlySet<number> } {
+  const lines: string[] = [];
+  const cut = new Set<number>();
+  const lengths = new Map<string, number>();
+  scanJournal(
+    fd,
+    transcriptProjection,
+    ({ value }) => {
+      if (lines.length >= ENTRY_COUNT) {
+        throw new Fault(
+          413,
+          "transcript_too_large",
+          "Saved journal exceeds the 50000-entry budget.",
+        );
+      }
+      lines.push(JSON.stringify(value));
+      lengths.clear();
+    },
+    {
+      policy: "inspect",
+      requireNewline: true,
+      end: size,
+      limits: { depth: 64, nodes: 16384, arrayLength: 4096, keyLength: 512 },
+      malformed: (_start, _end, error) => {
+        if (error instanceof RangeError) {
+          throw new Fault(413, "transcript_too_large", "Saved record exceeds projection limits.");
+        }
+        lengths.clear();
+        cut.delete(lines.length);
+      },
+      stringChunk: (path, chunk) => {
+        if (textField(path)) {
+          const key = JSON.stringify(path);
+          const count = (lengths.get(key) ?? 0) + chunk.length;
+          lengths.set(key, count);
+          if (count > TEXT_LIMIT) {
+            cut.add(lines.length);
+          }
+        }
+      },
+    },
+  );
+  return { lines, cut };
+}
+/** Internal hook: caller MUST resolve a catalog-approved saved ID/name, never accept an HTTP filepath. */
+export async function readSavedTranscript(
+  packageRoot: string,
+  approvedFile: string,
+  options: TranscriptOptions = {},
+): Promise<TranscriptPage> {
+  const sdk = await loadNativeSession(packageRoot);
+  const fd = openSync(approvedFile, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    const before = fstatSync(fd);
+    if (!before.isFile() || before.size > FILE_BYTES) {
+      throw new Fault(413, "transcript_too_large", "Saved journal exceeds the 64 MiB read budget.");
+    }
+    const { lines, cut } = savedLines(fd, before.size);
+    const after = fstatSync(fd);
+    if (
+      after.size !== before.size ||
+      after.mtimeMs !== before.mtimeMs ||
+      after.ctimeMs !== before.ctimeMs
+    ) {
+      throw new Fault(
+        409,
+        "session_changed",
+        "Saved journal changed during reading; refresh the catalog.",
+      );
+    }
+    const entries = sdk.parseSessionEntries(lines.join("\n"));
+    return savedPage(entries, cut, options, sdk);
+  } finally {
+    closeSync(fd);
+  }
+}
+function savedPage(
+  entries: ReturnType<typeof NativeSession.parseSessionEntries>,
+  cut: ReadonlySet<number>,
+  options: TranscriptOptions,
+  sdk: typeof NativeSession,
+): TranscriptPage {
+  const header = entries.find((entry) => entry.type === "session");
+  if (header === undefined) {
+    throw new Fault(409, "invalid_session", "Saved journal has no native session header.");
+  }
+  const legacy = (header.version ?? 1) < 2;
+  if (legacy && options.cursor !== undefined) {
+    throw new Fault(
+      409,
+      "cursor_unavailable",
+      "Legacy journals have no stable entry IDs; request a fresh bounded recent transcript.",
+    );
+  }
+  // Native inMemory reconstructs branch state/migrations without ever opening or writing the file.
+  const manager = sdk.SessionManager.inMemory(header.cwd, undefined, entries);
+  const page = readLiveTranscript(manager, options);
+  const cutIds = new Set(
+    entries.flatMap((entry, index) =>
+      entry.type !== "session" && cut.has(index) ? [entry.id] : [],
+    ),
+  );
+  const records = page.records.map((entry) =>
+    cutIds.has(entry.id) ? { ...entry, truncated: true } : entry,
+  );
+  return {
+    ...page,
+    // ponytail: v1 has no persisted entry IDs; use catalog snapshot cursors if legacy pagination is needed.
+    cursor: legacy ? undefined : page.cursor,
+    records,
+    truncated: page.truncated || records.some((entry) => entry.truncated),
+  };
+}

package/src/pi-intercom/session-targets.ts

@@ -14,6 +14,10 @@ export interface ProjectSessionIdentity extends TargetIdentity {
 
 export const MIN_SESSION_TARGET_PREFIX_LENGTH = 8;
 
+export function nativePeerId(sessionId: string): string {
+  return `pi-${createHash("sha256").update(sessionId).digest("hex").slice(0, 32)}`;
+}
+
 export interface TargetResolution<T extends TargetIdentity> {
   readonly status: "none" | "found" | "ambiguous" | "prefix_too_short";
   readonly target?: T;

package/src/pi-intercom/transcript.ts

@@ -0,0 +1,226 @@
+import type { ExtensionContext, SessionEntry } from "@earendil-works/pi-coding-agent";
+type ReadonlySessionManager = ExtensionContext["sessionManager"];
+type BoundedOptions = TranscriptOptions & { readonly limit: number; readonly maxBytes: number };
+import { isRecord, isUnknownArray } from "../shared/unknown.ts";
+import { Fault, label, object } from "./bridge-protocol.ts";
+
+export interface TranscriptOptions {
+  readonly limit?: number;
+  readonly maxBytes?: number;
+  readonly cursor?: string;
+}
+export interface TranscriptRecord {
+  readonly id: string;
+  readonly timestamp: string;
+  readonly role: string;
+  readonly text: string;
+  readonly truncated: boolean;
+}
+export interface TranscriptPage {
+  readonly sessionId: string;
+  readonly leafId: string | null;
+  readonly records: readonly TranscriptRecord[];
+  readonly bytes: number;
+  readonly truncated: boolean;
+  readonly cursor?: string;
+  readonly scanLimitReached: boolean;
+  readonly finalizedOnly: true;
+  readonly streaming: "unavailable";
+}
+const SCAN_LIMIT = 1024;
+export function transcriptOptions(value: unknown = {}): BoundedOptions {
+  const input = object(value, ["limit", "maxBytes", "cursor"]);
+  const limit = integer(input.limit, 50, 1, 100);
+  const maxBytes = integer(input.maxBytes, 65536, 256, 131072);
+  const cursor = input.cursor === undefined ? undefined : label(input.cursor, "cursor", 512);
+  return { limit, maxBytes, cursor };
+}
+function integer(value: unknown, fallback: number, min: number, max: number): number {
+  const result = value === undefined ? fallback : value;
+  if (typeof result !== "number" || !Number.isInteger(result) || result < min || result > max) {
+    throw new Fault(
+      400,
+      "invalid_input",
+      `Transcript limit must be an integer from ${min} to ${max}.`,
+    );
+  }
+  return result;
+}
+interface TextOutput {
+  readonly text: string;
+  readonly truncated: boolean;
+}
+function textualContent(content: unknown): TextOutput {
+  if (typeof content === "string") {
+    return { text: content, truncated: false };
+  }
+  if (!isUnknownArray(content)) {
+    return { text: "", truncated: false };
+  }
+  const pieces: string[] = [];
+  let remaining = 131073;
+  let truncated = content.length > 4096;
+  for (const part of content.slice(0, 4096)) {
+    if (remaining <= 0) {
+      truncated = true;
+      break;
+    }
+    if (isRecord(part) && part.type === "text" && typeof part.text === "string") {
+      const text = part.text.slice(0, remaining);
+      pieces.push(text);
+      truncated ||= text.length < part.text.length;
+      remaining -= text.length + 1;
+    }
+  }
+  return { text: pieces.join("\n"), truncated };
+}
+function visible(entry: SessionEntry): (TextOutput & { readonly role: string }) | undefined {
+  if (entry.type === "custom_message") {
+    return entry.display ? { role: "custom", ...textualContent(entry.content) } : undefined;
+  }
+  if (entry.type !== "message") {
+    return undefined;
+  }
+  const message = entry.message;
+  if (message.role === "bashExecution") {
+    return {
+      role: "toolResult",
+      text: message.output,
+      truncated: nativeTruncation(message.truncated),
+    };
+  }
+  if (!["user", "assistant", "toolResult", "custom"].includes(message.role)) {
+    return undefined;
+  }
+  if (message.role === "custom" && !message.display) {
+    return undefined;
+  }
+  return "content" in message
+    ? { role: message.role, ...textualContent(message.content) }
+    : undefined;
+}
+function nativeTruncation(value: unknown): boolean {
+  // Older saved bash entries may predate the native boolean field.
+  return value === true;
+}
+function boundedText(text: string, budget: number): string {
+  // Slice before UTF-8 encoding to avoid copying arbitrarily large live tool output.
+  const bytes = Buffer.from(text.slice(0, budget));
+  if (bytes.length <= budget) {
+    return bytes.toString();
+  }
+  let end = budget;
+  while (end > 0 && (bytes[end] & 0xc0) === 0x80) {
+    end -= 1;
+  }
+  return bytes.subarray(0, end).toString();
+}
+function startId(
+  manager: ReadonlySessionManager,
+  leaf: string | null,
+  cursor?: string,
+): { readonly id: string | null; readonly scanned: number } {
+  if (cursor === undefined) {
+    return { id: leaf, scanned: 0 };
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+  } catch {
+    throw new Fault(400, "invalid_cursor", "Invalid transcript cursor.");
+  }
+  const data = object(raw, ["leaf", "before"]);
+  if (data.leaf !== leaf) {
+    throw new Fault(409, "branch_changed", "Active branch changed; request a new transcript page.");
+  }
+  const before = label(data.before, "cursor entry", 128);
+  let id = leaf;
+  for (let scanned = 0; id !== null && scanned < SCAN_LIMIT; scanned += 1) {
+    if (id === before) {
+      return { id, scanned };
+    }
+    id = manager.getEntry(id)?.parentId ?? null;
+  }
+  throw new Fault(400, "invalid_cursor", "Cursor is outside the bounded active branch.");
+}
+/** Finalized textual output on the selected branch; never builds full history/context. */
+export function readLiveTranscript(
+  manager: ReadonlySessionManager,
+  input: TranscriptOptions = {},
+): TranscriptPage {
+  const options = transcriptOptions(input);
+  const leaf = manager.getLeafId();
+  const start = startId(manager, leaf, options.cursor);
+  let id = start.id;
+  let scanned = start.scanned;
+  const records: TranscriptRecord[] = [];
+  let bytes = 0;
+  let textTruncated = false;
+  while (id !== null && scanned < SCAN_LIMIT) {
+    scanned += 1;
+    const entry = manager.getEntry(id);
+    if (!entry) {
+      textTruncated = true;
+      id = null;
+      break;
+    }
+    const record = transcriptRecord(entry, options.maxBytes - bytes);
+    if (record !== undefined) {
+      records.push(record);
+      bytes += Buffer.byteLength(record.text);
+      textTruncated ||= record.truncated;
+    }
+    id = entry.parentId;
+    if (records.length >= options.limit || bytes >= options.maxBytes) {
+      break;
+    }
+  }
+  return transcriptPage(manager, {
+    leaf,
+    records,
+    bytes,
+    textTruncated,
+    id,
+    scanLimitReached: scanned >= SCAN_LIMIT && id !== null,
+  });
+}
+function transcriptRecord(entry: SessionEntry, budget: number): TranscriptRecord | undefined {
+  const output = visible(entry);
+  if (output === undefined || output.text.length === 0) {
+    return undefined;
+  }
+  const text = boundedText(output.text, budget);
+  return {
+    id: entry.id,
+    timestamp: entry.timestamp,
+    role: output.role,
+    text,
+    truncated: text !== output.text || output.truncated,
+  };
+}
+function transcriptPage(
+  manager: ReadonlySessionManager,
+  state: {
+    readonly leaf: string | null;
+    readonly records: TranscriptRecord[];
+    readonly bytes: number;
+    readonly textTruncated: boolean;
+    readonly id: string | null;
+    readonly scanLimitReached: boolean;
+  },
+): TranscriptPage {
+  const { leaf, records, bytes, textTruncated, id, scanLimitReached } = state;
+  return {
+    sessionId: manager.getSessionId(),
+    leafId: leaf,
+    records: records.reverse(),
+    bytes,
+    truncated: id !== null || textTruncated,
+    scanLimitReached,
+    ...(id !== null && !scanLimitReached
+      ? { cursor: Buffer.from(JSON.stringify({ leaf, before: id })).toString("base64url") }
+      : {}),
+    finalizedOnly: true,
+    streaming: "unavailable",
+  };
+}

package/src/pi-intercom/types.ts

@@ -8,6 +8,7 @@ import {
   safeLabel,
   safeText,
 } from "./validation.ts";
+import type { NativeControlEnvelope } from "./native-control-protocol.ts";
 
 export interface SessionInfo {
   readonly id: string;
@@ -106,6 +107,7 @@ export interface Message {
   readonly timestamp: number;
   readonly replyTo?: string;
   readonly expectsReply?: boolean;
+  readonly control?: NativeControlEnvelope;
   /** Recipients verify parent ownership before elevating human origin. */
   readonly human?: HumanMessageOrigin;
   readonly topic?: TopicUpdate;