@fitchmultz/pi-subagents 0.50.0 → 0.52.0

package/dist/agent/observation-view.js

@@ -0,0 +1,258 @@
+import { writeFrame } from "../pi-intercom/broker/framing.js";
+import { NAME_CHARS } from "./observation-state.js";
+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;
+function short(value) {
+    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 {
+    settled = [];
+    tools = [];
+    blocks = [];
+    full = false;
+    bytes = ENVELOPE_BYTES;
+    room() {
+        return FRAME_BYTES - this.bytes;
+    }
+    take(json, bytes = Buffer.byteLength(json)) {
+        if (this.bytes + bytes + 1 > FRAME_BYTES) {
+            this.full = true;
+            return false;
+        }
+        this.bytes += bytes + 1;
+        return true;
+    }
+    stop() {
+        this.full = true;
+    }
+}
+/** One viewer's position in one native content block. Text is sent as offset-addressed appends. */
+class BlockCursor {
+    ref;
+    type;
+    sent = 0;
+    announced = false;
+    args;
+    constructor(block) {
+        this.ref = block;
+        this.type = block.type;
+    }
+    next(index, frame, state) {
+        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);
+    }
+    text(head, text, frame) {
+        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;
+    socket;
+    level;
+    activitySeen = -1;
+    activity = "";
+    seen = -1;
+    key = 0;
+    count = 0;
+    ended = false;
+    blocks = [];
+    tools = new Map();
+    settled = 0;
+    evicted = 0;
+    constructor(socket, level) {
+        this.socket = socket;
+        this.level = level;
+    }
+    /** A baseline: the journal through `head`'s leaf plus every current live item, resent. */
+    snapshot(state, head, activity) {
+        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) {
+        const oldest = state.settlements[0]?.seq ?? state.settled + 1;
+        return this.evicted !== state.evicted || this.settled + 1 < oldest;
+    }
+    wants(state) {
+        return this.level === "detail" && !this.blocked && this.seen !== state.version;
+    }
+    delta(state) {
+        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(",")}}`;
+    }
+    settle(frame, state) {
+        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;
+        }
+    }
+    tool(tool, frame, state) {
+        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 });
+        }
+    }
+    toolFields(tool, state) {
+        const cursor = this.tools.get(tool.id);
+        const fields = [];
+        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;
+    }
+    message(frame, state) {
+        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(",")}]}`;
+    }
+    cursor(index, block) {
+        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, activity) {
+        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) {
+        this.blocked = !writeFrame(this.socket, json, FRAME_BYTES);
+        const buffered = this.socket.writableLength;
+        if (buffered > MAX_BUFFERED) {
+            this.socket.destroy();
+        }
+        return buffered;
+    }
+}

package/dist/agent/observation.js

@@ -0,0 +1,350 @@
+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;
+    }
+    /** A live viewer keeps its actor resident; parking would end the native stream it reads. */
+    get watched() {
+        return this.viewers.size + this.greeting.size > 0;
+    }
+    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 };
+    }
+}