@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/dist/agent/observation.js

@@ -0,0 +1,346 @@
+import * as fs from "node:fs";
+import * as net from "node:net";
+import { once } from "node:events";
+import { timingSafeEqual } from "node:crypto";
+import { createMessageReader } from "../pi-intercom/broker/framing.js";
+import { agentObservationSocketPath, preparePrivateSocketPath, } from "../pi-intercom/broker/paths.js";
+import { errorMessage, isRecord } from "../shared/unknown.js";
+import { LiveState } from "./observation-state.js";
+import { Viewer } from "./observation-view.js";
+const CONTENT_MS = 250;
+const ACTIVITY_MS = 1000;
+const HELLO_MS = 2000;
+const HELLO_BYTES = 4096;
+const LIMITS = { detail: 4, activity: 8 };
+function sameSecret(actual, expected) {
+    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 {
+    state;
+    viewers = new Set();
+    greeting = new Set();
+    server;
+    socketPath;
+    inode;
+    unsubscribe;
+    timer;
+    closed = false;
+    /** The actor's run is in progress, including native work before and after the agent loop. */
+    running = false;
+    lastContent = -Infinity;
+    lastActivity = -Infinity;
+    dueAt = 0;
+    stats = {
+        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,
+    };
+    session;
+    identity;
+    constructor(session, identity) {
+        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, identity) {
+        const observation = new ActorObservation(session, identity);
+        try {
+            await observation.listen();
+        }
+        catch (error) {
+            observation.fail(error);
+        }
+        return observation;
+    }
+    async listen() {
+        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. */
+    native(apply) {
+        if (this.closed) {
+            return;
+        }
+        const started = performance.now();
+        try {
+            apply();
+            this.schedule();
+        }
+        catch (error) {
+            this.fail(error);
+        }
+        this.stats.listenerMs += performance.now() - started;
+    }
+    listener = (event) => {
+        this.native(() => this.state.apply(event));
+    };
+    /** Sparse tool lifecycle hook, registered by the actor's own extension. */
+    tool(event) {
+        this.native(() => this.state.tool(event));
+    }
+    /** Run lifecycle from the actor: compact activity is sampled from native state meanwhile. */
+    working(running) {
+        this.native(() => {
+            this.running = running;
+            this.state.activityVersion++;
+        });
+    }
+    busy() {
+        const { session } = this;
+        return this.running || session.isStreaming || session.isCompacting || session.isRetrying;
+    }
+    details() {
+        return [...this.viewers].filter((viewer) => viewer.level === "detail").length;
+    }
+    /** Token-rate native events are subscribed only while a validated detail viewer reads them. */
+    observe(on) {
+        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);
+        }
+    }
+    accept = (socket) => {
+        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;
+        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();
+            }
+        });
+    };
+    hello(socket, message) {
+        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;
+    }
+    helloLevel(message) {
+        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. */
+    snapshot(viewer) {
+        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);
+    }
+    contentWork() {
+        return [...this.viewers].some((viewer) => viewer.wants(this.state));
+    }
+    /** Sampled once a second while native work runs; otherwise only after a sparse change. */
+    activityWork() {
+        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. */
+    schedule() {
+        // 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();
+        }
+    }
+    flush = () => {
+        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);
+        }
+    };
+    broadcastContent() {
+        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);
+            }
+        }
+    }
+    broadcastActivity() {
+        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);
+            }
+        }
+    }
+    send(viewer, json) {
+        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;
+    }
+    fail(error) {
+        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. */
+    release() {
+        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() {
+        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/dist/agent/observe-card.js

@@ -0,0 +1,243 @@
+import { isRecord } from "../shared/unknown.js";
+import { AssistantMessageComponent, Container, Text, ToolExecutionComponent, createBashToolDefinition, createEditToolDefinition, createFindToolDefinition, createGrepToolDefinition, createLsToolDefinition, createPowerShellToolDefinition, createReadToolDefinition, createWriteToolDefinition, } from "./observe-layout.js";
+const renderers = Object.entries({
+    bash: createBashToolDefinition,
+    edit: createEditToolDefinition,
+    find: createFindToolDefinition,
+    grep: createGrepToolDefinition,
+    ls: createLsToolDefinition,
+    powershell: createPowerShellToolDefinition,
+    read: createReadToolDefinition,
+    write: createWriteToolDefinition,
+});
+function nativeTool(name, id, args, options) {
+    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) {
+    if (typeof value === "string") {
+        return [{ type: "text", text: value }];
+    }
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value.flatMap((part) => {
+        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) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    return "json" in value ? value.json : undefined;
+}
+export function assistant(content, streaming) {
+    // 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) => {
+            if (block.type === "thinking") {
+                return [{ type: "thinking", thinking: block.text ?? "" }];
+            }
+            return block.type === "text" ? [{ type: "text", text: block.text ?? "" }] : [];
+        }),
+    };
+}
+export class Card {
+    id;
+    content = new Container();
+    footer = new Container();
+    assistant;
+    status;
+    blocks;
+    ended;
+    value;
+    tool;
+    selected = false;
+    expanded = false;
+    ready = false;
+    page = 0;
+    pages = 1;
+    cache;
+    arguments;
+    phase = "";
+    constructor(id) {
+        this.id = id;
+    }
+    publish(page, args, options) {
+        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));
+        }
+    }
+    publishTool(message, args, options) {
+        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));
+    }
+    configureTool(value, options) {
+        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, options, preparing) {
+        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();
+        }
+    }
+    preview(value, isError, partial) {
+        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, hideThinking) {
+        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() {
+        this.cache = undefined;
+        this.content.invalidate();
+        this.footer.invalidate();
+    }
+    render(width) {
+        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;
+    }
+    matches(content, ended) {
+        return (this.ended === ended &&
+            this.blocks?.length === content.length &&
+            content.every((block, index) => this.blocks?.[index] === block));
+    }
+    toggle() {
+        if (this.tool) {
+            this.expanded = !this.expanded;
+            this.tool.setExpanded(this.expanded);
+            this.cache = undefined;
+        }
+    }
+    handleMouse(event) {
+        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;
+    }
+}

package/dist/agent/observe-chrome.js

@@ -0,0 +1,85 @@
+import { actionHints, actionText } from "../shared/tui-action.js";
+import { Container, HStack, rawKeyHint, ScrollView, Text, TruncatedText, } from "./observe-layout.js";
+import { plainText } from "./journal-tail.js";
+export class Details extends ScrollView {
+    constructor(launch) {
+        super(new Text(`${launch.context === "fork" ? "Fork context: includes inherited parent activity.\n" : ""}${launch.id}\nAssignment preview: ${plainText(launch.prompt, 160)}\n${launch.sessionFile}`, 0, 0), { primary: false, scrollbar: "always" });
+    }
+}
+export class ChildList extends ScrollView {
+    list;
+    open;
+    constructor(open) {
+        const list = new Container();
+        super(list, { primary: false, scrollbar: "always" });
+        this.list = list;
+        this.open = open;
+    }
+    update(rows, selected, checking) {
+        this.list.clear();
+        if (rows.length === 0) {
+            this.list.addChild(new Text(checking
+                ? "Checking saved child runs…"
+                : "No child runs to show. Completed runs are hidden.", 0, 0));
+        }
+        for (const row of rows) {
+            this.list.addChild(actionText(`${row.id === selected ? ">" : " "} ${row.status} · ${row.name}`, () => this.open(row.id)));
+        }
+    }
+    reveal(index) {
+        this.scrollTo(Math.max(0, index - Math.floor(this.viewportHeight / 2)));
+    }
+}
+/** Header activity label: a live connection wins over the last known row status. */
+export function activityLabel(options) {
+    const { row, client } = options;
+    if (row?.live !== true) {
+        return row?.status ?? "checking";
+    }
+    if (client?.connected === true) {
+        return client.activity;
+    }
+    if (client) {
+        return "Reconnecting";
+    }
+    return options.connecting ? "Connecting" : (row.activity ?? row.status);
+}
+/** Footer key hints press the same actions as the keyboard table. */
+export function appendHints(target, options) {
+    const hints = options.actions
+        .filter(([, label]) => label.length > 0)
+        .map(([key, label, action]) => ({
+        text: rawKeyHint(options.keys.getKeys(key)[0] ?? "", label),
+        action: () => options.perform(action),
+    }));
+    target.addChild(actionHints(hints), { basis: 1 });
+}
+/** Conversation body: persistent child strip beside the transcript, plus the follow footer. */
+export function appendConversation(target, options) {
+    target.addChild(new HStack([
+        {
+            component: options.list,
+            basis: 27,
+            visible: (viewport) => viewport.width >= 100,
+        },
+        { component: options.reading.scroll, basis: 0, grow: 1, minSize: 1 },
+    ], { gap: 1 }), { basis: 0, grow: 1, minSize: 1 });
+    const { following, pending } = options.reading;
+    let follow = pending
+        ? "New activity below · End to follow live"
+        : "Reading earlier · End to follow live";
+    if (following) {
+        follow = "Following live";
+    }
+    target.addChild(actionText(follow, options.follow), { basis: 1 });
+}
+export function appendHeader(target, options) {
+    const { launch } = options;
+    target.addChild(actionText(`${plainText(launch.name ?? "Child", 32)} · ${options.activity} · Details`, options.toggle), { basis: 1 });
+    target.addChild(new TruncatedText(`${options.model} · Thinking ${options.thinking}`, 0, 0), {
+        basis: 1,
+    });
+    if (options.details) {
+        target.addChild(options.details, { maxSize: 5 });
+    }
+}