@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/src/agent/observation.ts

@@ -0,0 +1,405 @@
+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;
+  }
+  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 };
+  }
+}

package/src/agent/observe-card.ts

@@ -0,0 +1,304 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { Component, TUI, TuiMouseEvent } from "@earendil-works/pi-tui";
+import { isRecord } from "../shared/unknown.ts";
+import type { ViewedBlock, ViewedTool } from "./observe-client.ts";
+import type { ConversationPage } from "./journal-tail.ts";
+import {
+  AssistantMessageComponent,
+  Container,
+  Text,
+  ToolExecutionComponent,
+  createBashToolDefinition,
+  createEditToolDefinition,
+  createFindToolDefinition,
+  createGrepToolDefinition,
+  createLsToolDefinition,
+  createPowerShellToolDefinition,
+  createReadToolDefinition,
+  createWriteToolDefinition,
+} from "./observe-layout.ts";
+
+export interface CardOptions {
+  tui: TUI;
+  cwd: string;
+  hideThinking: boolean;
+}
+const renderers = Object.entries({
+  bash: createBashToolDefinition,
+  edit: createEditToolDefinition,
+  find: createFindToolDefinition,
+  grep: createGrepToolDefinition,
+  ls: createLsToolDefinition,
+  powershell: createPowerShellToolDefinition,
+  read: createReadToolDefinition,
+  write: createWriteToolDefinition,
+});
+function nativeTool(
+  name: string,
+  id: string,
+  args: unknown,
+  options: CardOptions,
+): InstanceType<typeof ToolExecutionComponent> {
+  return new ToolExecutionComponent(
+    name,
+    id,
+    args,
+    { showImages: false, outputPad: 0 },
+    renderers.find(([key]) => key === name)?.[1](options.cwd) ?? {},
+    options.tui,
+    options.cwd,
+  );
+}
+
+export function blocks(value: unknown): ViewedBlock[] {
+  if (typeof value === "string") {
+    return [{ type: "text", text: value }];
+  }
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return (value as unknown[]).flatMap((part): ViewedBlock[] => {
+    if (!isRecord(part)) {
+      return [];
+    }
+    if (part.type === "text" && typeof part.text === "string") {
+      return [{ type: "text", text: part.text }];
+    }
+    if (part.type === "thinking" && typeof part.thinking === "string") {
+      return [{ type: "thinking", text: part.thinking }];
+    }
+    if (part.type === "toolCall" && typeof part.id === "string" && typeof part.name === "string") {
+      return [{ type: "toolCall", id: part.id, name: part.name, args: part.arguments }];
+    }
+    return [
+      {
+        type: "text",
+        text: `[${typeof part.type === "string" ? part.type : "non-text"} attachment]`,
+      },
+    ];
+  });
+}
+export function projected(value: unknown): unknown {
+  if (!isRecord(value)) {
+    return undefined;
+  }
+  return "json" in value ? value.json : undefined;
+}
+export function assistant(content: ViewedBlock[], streaming: boolean): AssistantMessage {
+  // Rendering only. Accounting and completion still use native journals and receipts.
+  return {
+    role: "assistant",
+    api: "observer",
+    provider: "observer",
+    model: "",
+    timestamp: 0,
+    stopReason: streaming ? "pending" : "stop",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      totalTokens: 0,
+      cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+    },
+    content: content.flatMap((block): AssistantMessage["content"] => {
+      if (block.type === "thinking") {
+        return [{ type: "thinking", thinking: block.text ?? "" }];
+      }
+      return block.type === "text" ? [{ type: "text", text: block.text ?? "" }] : [];
+    }),
+  };
+}
+
+export class Card implements Component {
+  id: string;
+  readonly content = new Container();
+  readonly footer = new Container();
+  assistant?: InstanceType<typeof AssistantMessageComponent>;
+  status?: InstanceType<typeof Text>;
+  blocks?: ViewedBlock[];
+  ended?: boolean;
+  value?: unknown;
+  tool?: InstanceType<typeof ToolExecutionComponent>;
+  selected = false;
+  expanded = false;
+  ready = false;
+  page = 0;
+  pages = 1;
+  private cache?: { width: number; lines: string[] };
+  private arguments?: unknown;
+  private phase = "";
+  constructor(id: string) {
+    this.id = id;
+  }
+  publish(page: ConversationPage, args: unknown, options: CardOptions): void {
+    this.content.clear();
+    this.footer.clear();
+    this.ready = true;
+    this.page = page.page;
+    this.pages = page.pages;
+    const { message } = page;
+    const content = blocks(message.content);
+    if (message.role === "assistant") {
+      this.content.addChild(
+        new AssistantMessageComponent(assistant(content, false), options.hideThinking),
+      );
+      if (typeof message.errorMessage === "string") {
+        this.content.addChild(new Text(message.errorMessage, 0, 0));
+      }
+    } else if (message.role === "toolResult") {
+      this.publishTool(message, args, options);
+    } else {
+      this.content.addChild(
+        new Text(
+          `${typeof message.role === "string" ? message.role : "message"}\n${content.map((part) => part.text ?? "").join("\n")}`,
+          0,
+          0,
+        ),
+      );
+    }
+  }
+  private publishTool(message: Record<string, unknown>, args: unknown, options: CardOptions): void {
+    this.tool ??= nativeTool(
+      typeof message.toolName === "string" ? message.toolName : "tool",
+      typeof message.toolCallId === "string" ? message.toolCallId : this.id,
+      args ?? {},
+      options,
+    );
+    this.tool.updateResult({
+      content: blocks(message.content)
+        .filter((part) => part.type === "text")
+        .map((part) => ({ type: "text", text: part.text })),
+      isError: message.isError === true,
+    });
+    this.tool.setExpanded(this.expanded);
+    this.content.addChild(this.tool);
+    this.footer.addChild(
+      new Text("Arguments are a bounded preview. Exact call in Details journal.", 0, 0),
+    );
+  }
+  private configureTool(value: ViewedTool, options: CardOptions): void {
+    if (!this.tool) {
+      this.tool = nativeTool(value.name, value.id, projected(value.args) ?? {}, options);
+      this.tool.setExpanded(this.expanded);
+      this.content.addChild(this.tool);
+      this.status = new Text("", 0, 0);
+      this.content.addChild(this.status);
+    }
+    if (this.arguments !== value.args) {
+      this.tool.updateArgs(projected(value.args) ?? {});
+      this.arguments = value.args;
+      this.invalidate();
+    }
+  }
+  updateTool(value: ViewedTool, options: CardOptions, preparing: boolean): void {
+    this.configureTool(value, options);
+    const ended = value.end !== undefined;
+    const source = value.end ?? { result: value.partial, isError: false };
+    let phase = preparing ? "Preparing tool call" : "Running";
+    if (ended) {
+      phase = "Awaiting journal publication";
+    }
+    if (this.value !== source.result || this.phase !== phase) {
+      if (source.result !== undefined) {
+        this.preview(source.result, source.isError, !ended);
+      }
+      this.status?.setText(phase);
+      this.phase = phase;
+      this.value = source.result;
+      this.ended = ended;
+      this.invalidate();
+    }
+  }
+  private preview(value: unknown, isError: boolean, partial: boolean): void {
+    const result = projected(value) ?? {
+      content: [
+        { type: "text", text: "Live preview unavailable; full result appears after publication." },
+      ],
+    };
+    if (isRecord(result)) {
+      this.tool?.updateResult(
+        {
+          content: blocks(result.content)
+            .filter((part) => part.type === "text")
+            .map((part) => ({ type: "text", text: part.text })),
+          isError,
+        },
+        partial,
+      );
+    }
+  }
+  stream(message: { blocks: ViewedBlock[]; ended: boolean }, hideThinking: boolean): void {
+    if (!this.assistant) {
+      this.assistant = new AssistantMessageComponent(undefined, hideThinking);
+      this.status = new Text("", 0, 0);
+      this.content.addChild(this.assistant);
+      this.content.addChild(this.status);
+    }
+    if (this.matches(message.blocks, message.ended)) {
+      return;
+    }
+    this.assistant.updateContent(
+      assistant(message.blocks.filter(Boolean), !message.ended),
+      !message.ended,
+    );
+    this.status?.setText(message.ended ? "Awaiting journal publication" : "In progress");
+    this.blocks = message.blocks.slice();
+    this.ended = message.ended;
+    this.invalidate();
+  }
+  invalidate(): void {
+    this.cache = undefined;
+    this.content.invalidate();
+    this.footer.invalidate();
+  }
+  render(width: number): string[] {
+    if (this.cache?.width !== width) {
+      const lines = [...this.content.render(width), ...this.footer.render(width)];
+      if (this.selected && this.tool && lines.length > 0) {
+        lines[0] = "> Selected tool".slice(0, width);
+      }
+      this.cache = { width, lines };
+    }
+    return this.cache.lines;
+  }
+  private matches(content: ViewedBlock[], ended: boolean): boolean {
+    return (
+      this.ended === ended &&
+      this.blocks?.length === content.length &&
+      content.every((block, index) => this.blocks?.[index] === block)
+    );
+  }
+  toggle(): void {
+    if (this.tool) {
+      this.expanded = !this.expanded;
+      this.tool.setExpanded(this.expanded);
+      this.cache = undefined;
+    }
+  }
+  handleMouse(event: TuiMouseEvent): ReturnType<NonNullable<Component["handleMouse"]>> {
+    const body = this.content.render(event.width).length;
+    if (event.y >= body) {
+      return this.footer.handleMouse({
+        ...event,
+        y: event.y - body,
+        height: Math.max(0, event.height - body),
+      });
+    }
+    if (
+      this.tool &&
+      event.button === "left" &&
+      (event.type === "press" || event.type === "click")
+    ) {
+      if (event.type === "click") {
+        this.toggle();
+      }
+      return { handled: true, render: event.type === "click" };
+    }
+    const result = this.content.handleMouse(event);
+    if (result?.handled) {
+      this.cache = undefined;
+    }
+    return result;
+  }
+}