@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/src/agent/observation-view.ts

@@ -0,0 +1,267 @@
+import type { Socket } from "node:net";
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import { writeFrame } from "../pi-intercom/broker/framing.ts";
+import { NAME_CHARS, type LiveState, type LiveTool } from "./observation-state.ts";
+
+export const FRAME_BYTES = 256 * 1024 - 4;
+const MAX_BUFFERED = 1024 * 1024;
+const ENVELOPE_BYTES = 192;
+/** Blocks past this index stay journal-only; `count` still reports the native length. */
+const BLOCKS = 256;
+type Block = AssistantMessage["content"][number];
+export type Level = "detail" | "activity";
+
+function short(value: string): string {
+  return JSON.stringify(value.length > NAME_CHARS ? value.slice(0, NAME_CHARS) : value);
+}
+
+/** Pre-serialized pieces keep arbitrary values bounded before the frame exists. */
+class Frame {
+  readonly settled: string[] = [];
+  readonly tools: string[] = [];
+  readonly blocks: string[] = [];
+  full = false;
+  private bytes = ENVELOPE_BYTES;
+  room(): number {
+    return FRAME_BYTES - this.bytes;
+  }
+  take(json: string, bytes = Buffer.byteLength(json)): boolean {
+    if (this.bytes + bytes + 1 > FRAME_BYTES) {
+      this.full = true;
+      return false;
+    }
+    this.bytes += bytes + 1;
+    return true;
+  }
+  stop(): void {
+    this.full = true;
+  }
+}
+
+/** One viewer's position in one native content block. Text is sent as offset-addressed appends. */
+class BlockCursor {
+  readonly ref: Block;
+  private type: Block["type"];
+  private sent = 0;
+  private announced = false;
+  private args?: unknown;
+  constructor(block: Block) {
+    this.ref = block;
+    this.type = block.type;
+  }
+  next(index: number, frame: Frame, state: LiveState): string | undefined {
+    const block = this.ref;
+    if (block.type !== this.type) {
+      // An in-place type replacement restarts the block from offset zero.
+      this.type = block.type;
+      this.sent = 0;
+      this.announced = false;
+    }
+    if (block.type === "toolCall") {
+      if (this.announced && this.args === block.arguments) {
+        return undefined;
+      }
+      const item = `[${index},"toolCall",${short(block.id)},${short(block.name)},${state.project(block.arguments)}]`;
+      this.announced = frame.take(item);
+      this.args = block.arguments;
+      return this.announced ? item : undefined;
+    }
+    const text = block.type === "text" ? block.text : block.thinking;
+    return this.text(`[${index},"${block.type}",`, text, frame);
+  }
+  private text(head: string, text: string, frame: Frame): string | undefined {
+    if (text.length < this.sent) {
+      this.sent = 0;
+      this.announced = false;
+    }
+    if (this.announced && text.length === this.sent) {
+      return undefined;
+    }
+    const prefix = `${head}${this.sent},`;
+    const budget = frame.room() - prefix.length - 2;
+    let end = Math.min(text.length, this.sent + Math.max(0, budget));
+    while (end >= this.sent) {
+      const json = JSON.stringify(text.slice(this.sent, end));
+      const bytes = Buffer.byteLength(json);
+      if (bytes <= budget) {
+        frame.take(json, prefix.length + bytes + 1);
+        if (end < text.length) {
+          // The rest of this block needs another frame; keep this viewer dirty.
+          frame.stop();
+        }
+        this.sent = end;
+        this.announced = true;
+        return `${prefix}${json}]`;
+      }
+      // Escapes and multibyte text exceed one byte per code unit; shrink proportionally.
+      end = this.sent + Math.floor(((end - this.sent) * budget) / bytes) - 8;
+    }
+    frame.stop();
+    return undefined;
+  }
+}
+
+/** Per-viewer cursors. Each accepted frame advances them exactly once; nothing is resent. */
+export class Viewer {
+  blocked = false;
+  readonly socket: Socket;
+  readonly level: Level;
+  activitySeen = -1;
+  private activity = "";
+  private seen = -1;
+  private key = 0;
+  private count = 0;
+  private ended = false;
+  private blocks: BlockCursor[] = [];
+  private readonly tools = new Map<string, { readonly rev: number; readonly ended: boolean }>();
+  private settled = 0;
+  private evicted = 0;
+  constructor(socket: Socket, level: Level) {
+    this.socket = socket;
+    this.level = level;
+  }
+  /** A baseline: the journal through `head`'s leaf plus every current live item, resent. */
+  snapshot(state: LiveState, head: string, activity: string): string {
+    this.settled = state.settled;
+    this.evicted = state.evicted;
+    this.seen = -1;
+    this.key = 0;
+    this.blocks = [];
+    this.tools.clear();
+    this.activity = activity;
+    this.activitySeen = state.activityVersion;
+    return `${head},"activity":${this.activity},"seq":${state.settled}}`;
+  }
+  /** Missed settlements or evicted live items can only be recovered from a new baseline. */
+  stale(state: LiveState): boolean {
+    const oldest = state.settlements[0]?.seq ?? state.settled + 1;
+    return this.evicted !== state.evicted || this.settled + 1 < oldest;
+  }
+  wants(state: LiveState): boolean {
+    return this.level === "detail" && !this.blocked && this.seen !== state.version;
+  }
+  delta(state: LiveState): string | undefined {
+    const frame = new Frame();
+    this.settle(frame, state);
+    for (const tool of state.tools.values()) {
+      this.tool(tool, frame, state);
+    }
+    for (const id of this.tools.keys()) {
+      if (!state.tools.has(id)) {
+        this.tools.delete(id);
+      }
+    }
+    const message = this.message(frame, state);
+    if (!frame.full) {
+      this.seen = state.version;
+    }
+    if (frame.settled.length + frame.tools.length === 0 && message === undefined) {
+      return undefined;
+    }
+    const fields = [
+      `"t":"delta"`,
+      `"settled":[${frame.settled.join(",")}]`,
+      `"tools":[${frame.tools.join(",")}]`,
+    ];
+    return `{${[...fields, ...(message === undefined ? [] : [`"message":${message}`])].join(",")}}`;
+  }
+  private settle(frame: Frame, state: LiveState): void {
+    for (const settlement of state.settlements) {
+      if (settlement.seq <= this.settled) {
+        continue;
+      }
+      // Settlements stay in order: one that does not fit holds back every later one.
+      if (!frame.take(settlement.json)) {
+        return;
+      }
+      frame.settled.push(settlement.json);
+      this.settled = settlement.seq;
+    }
+  }
+  private tool(tool: LiveTool, frame: Frame, state: LiveState): void {
+    if (frame.full) {
+      return;
+    }
+    const fields = this.toolFields(tool, state);
+    const item = `{"id":${JSON.stringify(tool.id)},${fields.join(",")}}`;
+    if (fields.length > 0 && frame.take(item)) {
+      frame.tools.push(item);
+      this.tools.set(tool.id, { rev: tool.rev, ended: tool.ended !== undefined });
+    }
+  }
+  private toolFields(tool: LiveTool, state: LiveState): string[] {
+    const cursor = this.tools.get(tool.id);
+    const fields: string[] = [];
+    if (cursor === undefined) {
+      fields.push(`"name":${short(tool.name)}`, `"args":${tool.projectedArgs(state.project)}`);
+    }
+    if (tool.rev > (cursor?.rev ?? 0)) {
+      fields.push(`"partial":{"rev":${tool.rev},"value":${tool.projectedPartial(state.project)}}`);
+    }
+    if (tool.ended !== undefined && cursor?.ended !== true) {
+      const result = tool.projectedResult(state.project);
+      fields.push(`"end":{"isError":${tool.ended.isError},"result":${result}}`);
+    }
+    return fields;
+  }
+  private message(frame: Frame, state: LiveState): string | undefined {
+    const live = state.message;
+    if (live === undefined) {
+      return undefined;
+    }
+    const reset = this.key !== live.key;
+    if (reset) {
+      this.key = live.key;
+      this.blocks = [];
+      this.count = 0;
+      this.ended = false;
+    }
+    const content = live.message.content;
+    const changed = reset || content.length !== this.count || live.ended !== this.ended;
+    this.count = content.length;
+    this.ended = live.ended;
+    const limit = Math.min(content.length, BLOCKS);
+    this.blocks.length = Math.min(this.blocks.length, limit);
+    for (let index = 0; index < limit && !frame.full; index++) {
+      const item = this.cursor(index, content[index]).next(index, frame, state);
+      if (item !== undefined) {
+        frame.blocks.push(item);
+      }
+    }
+    if (!changed && frame.blocks.length === 0) {
+      return undefined;
+    }
+    // An ended message stays live until its session entry is found and handed over.
+    return `{"key":${live.key},"reset":${reset},"ended":${live.ended},"count":${content.length},"blocks":[${frame.blocks.join(",")}]}`;
+  }
+  private cursor(index: number, block: Block): BlockCursor {
+    const existing = this.blocks.at(index);
+    if (existing?.ref === block) {
+      return existing;
+    }
+    // A replaced native block is resent from offset zero.
+    const cursor = new BlockCursor(block);
+    this.blocks[index] = cursor;
+    return cursor;
+  }
+  activityFrame(state: LiveState, activity: string): string | undefined {
+    if (this.blocked) {
+      return undefined;
+    }
+    this.activitySeen = state.activityVersion;
+    if (this.activity === activity) {
+      return undefined;
+    }
+    this.activity = activity;
+    return `{"t":"activity","activity":${activity}}`;
+  }
+  /** `false` from Node means accepted but buffered: wait for drain, never resend. */
+  write(json: string): number {
+    this.blocked = !writeFrame(this.socket, json, FRAME_BYTES);
+    const buffered = this.socket.writableLength;
+    if (buffered > MAX_BUFFERED) {
+      this.socket.destroy();
+    }
+    return buffered;
+  }
+}

package/src/agent/observation.ts

@@ -0,0 +1,409 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import { once } from "node:events";
+import { timingSafeEqual } from "node:crypto";
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import { createMessageReader } from "../pi-intercom/broker/framing.ts";
+import {
+  agentObservationSocketPath,
+  preparePrivateSocketPath,
+} from "../pi-intercom/broker/paths.ts";
+import { errorMessage, isRecord } from "../shared/unknown.ts";
+import { LiveState, type ToolEvent } from "./observation-state.ts";
+import { Viewer, type Level } from "./observation-view.ts";
+
+const CONTENT_MS = 250;
+const ACTIVITY_MS = 1000;
+const HELLO_MS = 2000;
+const HELLO_BYTES = 4096;
+const LIMITS: Readonly<Record<Level, number>> = { detail: 4, activity: 8 };
+
+export interface ObservationIdentity {
+  readonly token: string;
+  readonly rootId: string;
+  readonly sessionId: string;
+}
+export interface ObservationStats {
+  error?: string;
+  viewers: number;
+  refused: number;
+  frames: number;
+  bytes: number;
+  largestFrame: number;
+  largestBuffered: number;
+  backpressured: number;
+  drains: number;
+  resyncs: number;
+  flushes: number;
+  flushMs: number;
+  slowestFlushMs: number;
+  listenerMs: number;
+  subscriptions: number;
+  events: number;
+  toolEvents: number;
+  progressUpdates: number;
+  projections: number;
+  unavailable: number;
+  settled: number;
+  evicted: number;
+}
+
+function sameSecret(actual: unknown, expected: string): boolean {
+  const left = Buffer.from(typeof actual === "string" ? actual : "");
+  const right = Buffer.from(expected);
+  return left.length === right.length && timingSafeEqual(left, right);
+}
+
+/**
+ * Actor-owned, read-only, push-only live view of the native child session. The actor is the sole
+ * publisher; viewers can only connect, say hello once and read. The journal stays authoritative.
+ */
+export class ActorObservation {
+  private readonly state: LiveState;
+  private readonly viewers = new Set<Viewer>();
+  private readonly greeting = new Set<net.Socket>();
+  private server?: net.Server;
+  private socketPath?: string;
+  private inode?: number;
+  private unsubscribe?: () => void;
+  private timer?: NodeJS.Timeout;
+  private closed = false;
+  /** The actor's run is in progress, including native work before and after the agent loop. */
+  private running = false;
+  private lastContent = -Infinity;
+  private lastActivity = -Infinity;
+  private dueAt = 0;
+  private readonly stats: Omit<
+    ObservationStats,
+    | "events"
+    | "toolEvents"
+    | "progressUpdates"
+    | "projections"
+    | "unavailable"
+    | "settled"
+    | "evicted"
+  > = {
+    viewers: 0,
+    refused: 0,
+    frames: 0,
+    bytes: 0,
+    largestFrame: 0,
+    largestBuffered: 0,
+    backpressured: 0,
+    drains: 0,
+    resyncs: 0,
+    flushes: 0,
+    flushMs: 0,
+    slowestFlushMs: 0,
+    listenerMs: 0,
+    subscriptions: 0,
+  };
+  private readonly session: AgentSession;
+  private readonly identity: ObservationIdentity;
+  private constructor(session: AgentSession, identity: ObservationIdentity) {
+    this.session = session;
+    this.identity = identity;
+    this.state = new LiveState(
+      session,
+      () => this.schedule(),
+      (error) => this.fail(error),
+    );
+  }
+  /** Never rejects: observation faults disable observation, not native execution. */
+  static async open(
+    session: AgentSession,
+    identity: ObservationIdentity,
+  ): Promise<ActorObservation> {
+    const observation = new ActorObservation(session, identity);
+    try {
+      await observation.listen();
+    } catch (error) {
+      observation.fail(error);
+    }
+    return observation;
+  }
+  private async listen(): Promise<void> {
+    const socketPath = preparePrivateSocketPath(agentObservationSocketPath(this.identity.token));
+    if (fs.lstatSync(socketPath, { throwIfNoEntry: false }) !== undefined) {
+      throw new Error("Observation endpoint already exists; refusing to replace it.");
+    }
+    const server = net.createServer(this.accept);
+    this.server = server;
+    server.on("error", (error) => this.fail(error));
+    server.listen(socketPath);
+    await once(server, "listening");
+    this.socketPath = socketPath;
+    fs.chmodSync(socketPath, 0o600);
+    this.inode = fs.lstatSync(socketPath).ino;
+  }
+  /** Native callbacks run inline before persistence: assign references, never throw or await. */
+  private native(apply: () => void): void {
+    if (this.closed) {
+      return;
+    }
+    const started = performance.now();
+    try {
+      apply();
+      this.schedule();
+    } catch (error) {
+      this.fail(error);
+    }
+    this.stats.listenerMs += performance.now() - started;
+  }
+  private readonly listener = (event: AgentSessionEvent): void => {
+    this.native(() => this.state.apply(event));
+  };
+  /** Sparse tool lifecycle hook, registered by the actor's own extension. */
+  tool(event: ToolEvent): void {
+    this.native(() => this.state.tool(event));
+  }
+  /** Run lifecycle from the actor: compact activity is sampled from native state meanwhile. */
+  working(running: boolean): void {
+    this.native(() => {
+      this.running = running;
+      this.state.activityVersion++;
+    });
+  }
+  private busy(): boolean {
+    const { session } = this;
+    return this.running || session.isStreaming || session.isCompacting || session.isRetrying;
+  }
+  /** A live viewer keeps its actor resident; parking would end the native stream it reads. */
+  get watched(): boolean {
+    return this.viewers.size + this.greeting.size > 0;
+  }
+  private details(): number {
+    return [...this.viewers].filter((viewer) => viewer.level === "detail").length;
+  }
+  /** Token-rate native events are subscribed only while a validated detail viewer reads them. */
+  private observe(on: boolean): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    this.state.observe(on);
+    if (on) {
+      this.stats.subscriptions++;
+      this.unsubscribe = this.session.subscribe(this.listener);
+    }
+  }
+  private readonly accept = (socket: net.Socket): void => {
+    socket.on("error", () => {
+      socket.destroy();
+    });
+    if (this.closed || this.viewers.size + this.greeting.size >= LIMITS.detail + LIMITS.activity) {
+      this.stats.refused++;
+      socket.destroy();
+      return;
+    }
+    this.greeting.add(socket);
+    const timeout = setTimeout(() => {
+      socket.destroy();
+    }, HELLO_MS);
+    timeout.unref();
+    let viewer: Viewer | undefined;
+    let greeted = false;
+    const reader = createMessageReader(
+      (message) => {
+        clearTimeout(timeout);
+        // Observation is push-only: anything after the hello closes this viewer.
+        viewer = greeted ? viewer : this.hello(socket, message);
+        if (greeted || viewer === undefined) {
+          socket.destroy();
+        }
+        greeted = true;
+      },
+      () => {
+        socket.destroy();
+      },
+      HELLO_BYTES,
+    );
+    socket.on("data", reader);
+    socket.on("close", () => {
+      clearTimeout(timeout);
+      this.greeting.delete(socket);
+      const detail = viewer?.level === "detail";
+      if (viewer && this.viewers.delete(viewer) && detail && this.details() === 0 && !this.closed) {
+        this.observe(false);
+        this.schedule();
+      }
+    });
+  };
+  private hello(socket: net.Socket, message: unknown): Viewer | undefined {
+    this.greeting.delete(socket);
+    const level = this.helloLevel(message);
+    const count = [...this.viewers].filter((viewer) => viewer.level === level).length;
+    if (level === undefined || this.closed || count >= LIMITS[level]) {
+      this.stats.refused++;
+      return undefined;
+    }
+    const viewer = new Viewer(socket, level);
+    socket.on("drain", () => {
+      viewer.blocked = false;
+      this.stats.drains++;
+      this.schedule();
+    });
+    this.viewers.add(viewer);
+    this.stats.viewers++;
+    try {
+      if (level === "detail" && this.details() === 1) {
+        this.observe(true);
+      }
+      this.send(viewer, this.snapshot(viewer));
+      this.schedule();
+    } catch (error) {
+      this.fail(error);
+    }
+    return viewer;
+  }
+  private helloLevel(message: unknown): Level | undefined {
+    if (
+      !isRecord(message) ||
+      message.t !== "hello" ||
+      message.v !== 1 ||
+      !sameSecret(message.token, this.identity.token) ||
+      message.rootId !== this.identity.rootId ||
+      message.sessionId !== this.identity.sessionId
+    ) {
+      return undefined;
+    }
+    return message.level === "detail" || message.level === "activity" ? message.level : undefined;
+  }
+  /** Published entries are found first, so the leaf covers everything no longer live. */
+  private snapshot(viewer: Viewer): string {
+    this.state.resolve();
+    const { token, rootId, sessionId } = this.identity;
+    const head = JSON.stringify({ t: "snapshot", v: 1, generation: token, rootId, sessionId });
+    const leafId = JSON.stringify(this.session.sessionManager.getLeafId());
+    const activity = this.state.activity(this.running);
+    return viewer.snapshot(this.state, `${head.slice(0, -1)},"leafId":${leafId}`, activity);
+  }
+  private contentWork(): boolean {
+    return [...this.viewers].some((viewer) => viewer.wants(this.state));
+  }
+  /** Sampled once a second while native work runs; otherwise only after a sparse change. */
+  private activityWork(): boolean {
+    const version = this.state.activityVersion;
+    return (
+      this.busy() ||
+      [...this.viewers].some((viewer) => !viewer.blocked && viewer.activitySeen !== version)
+    );
+  }
+  /** One timer, armed only while a connected viewer has unsent changes or native work runs. */
+  private schedule(): void {
+    // An armed timer already covers anything due no earlier than the next content slot.
+    const armed = this.timer === undefined ? Infinity : this.dueAt;
+    if (armed <= this.lastContent + CONTENT_MS || this.closed || this.viewers.size === 0) {
+      return;
+    }
+    const content = this.contentWork() ? this.lastContent + CONTENT_MS : Infinity;
+    const activity = this.activityWork() ? this.lastActivity + ACTIVITY_MS : Infinity;
+    const due = Math.min(content, activity);
+    if (due < armed) {
+      clearTimeout(this.timer);
+      this.dueAt = due;
+      this.timer = setTimeout(this.flush, Math.max(0, due - performance.now()));
+      this.timer.unref();
+    }
+  }
+  private readonly flush = (): void => {
+    const started = performance.now();
+    // Node's cached loop clock can fire a timer just before performance.now() reaches it.
+    const now = Math.max(started, this.dueAt);
+    try {
+      // Retry unresolved publication without a timer of its own.
+      this.state.resolve();
+      if (now >= this.lastContent + CONTENT_MS && this.contentWork()) {
+        this.lastContent = now;
+        this.broadcastContent();
+      }
+      if (now >= this.lastActivity + ACTIVITY_MS && this.activityWork()) {
+        this.lastActivity = now;
+        this.broadcastActivity();
+      }
+      const elapsed = performance.now() - started;
+      this.stats.flushes++;
+      this.stats.flushMs += elapsed;
+      this.stats.slowestFlushMs = Math.max(this.stats.slowestFlushMs, elapsed);
+      this.timer = undefined;
+      this.schedule();
+    } catch (error) {
+      this.timer = undefined;
+      this.fail(error);
+    }
+  };
+  private broadcastContent(): void {
+    for (const viewer of this.viewers) {
+      if (viewer.wants(this.state) && viewer.stale(this.state)) {
+        this.stats.resyncs++;
+        this.send(viewer, this.snapshot(viewer));
+      }
+      const delta = viewer.wants(this.state) ? viewer.delta(this.state) : undefined;
+      if (delta !== undefined) {
+        this.send(viewer, delta);
+      }
+    }
+  }
+  private broadcastActivity(): void {
+    const activity = this.state.activity(this.running);
+    for (const viewer of this.viewers) {
+      const frame = viewer.activityFrame(this.state, activity);
+      if (frame !== undefined) {
+        this.send(viewer, frame);
+      }
+    }
+  }
+  private send(viewer: Viewer, json: string): void {
+    const bytes = Buffer.byteLength(json) + 4;
+    const buffered = viewer.write(json);
+    this.stats.frames++;
+    this.stats.bytes += bytes;
+    this.stats.largestFrame = Math.max(this.stats.largestFrame, bytes);
+    this.stats.largestBuffered = Math.max(this.stats.largestBuffered, buffered);
+    this.stats.backpressured += viewer.blocked ? 1 : 0;
+  }
+  private fail(error: unknown): void {
+    this.stats.error ??= errorMessage(error);
+    if (!this.closed) {
+      this.closed = true;
+      console.error(`Child observation disabled: ${this.stats.error}`);
+      // Teardown leaves the native callback that observed the fault.
+      setImmediate(() => this.release());
+    }
+  }
+  /** Observation-only teardown; its own failures are recorded, never thrown into the actor. */
+  private release(): void {
+    this.unsubscribe?.();
+    this.unsubscribe = undefined;
+    clearTimeout(this.timer);
+    this.timer = undefined;
+    this.state.dispose();
+    // The endpoint goes first: a disconnected viewer proves removal was already attempted.
+    const socketPath = this.socketPath;
+    this.socketPath = undefined;
+    try {
+      if (
+        socketPath !== undefined &&
+        fs.lstatSync(socketPath, { throwIfNoEntry: false })?.ino === this.inode
+      ) {
+        fs.unlinkSync(socketPath);
+      }
+    } catch (error) {
+      this.stats.error ??= `Observation endpoint removal failed: ${errorMessage(error)}`;
+    }
+    this.server?.close();
+    this.server = undefined;
+    for (const socket of [...this.greeting, ...[...this.viewers].map((viewer) => viewer.socket)]) {
+      socket.destroy();
+    }
+  }
+  /** Idempotent. Releases observation only; never stops or signals the actor's work. */
+  close(): ObservationStats {
+    this.closed = true;
+    this.release();
+    const { events, toolEvents, progressUpdates, projections, unavailable, settled, evicted } =
+      this.state;
+    const counts = { events, toolEvents, progressUpdates, projections, unavailable };
+    return { ...this.stats, ...counts, settled, evicted };
+  }
+}