@fitchmultz/pi-subagents 0.49.1 → 0.51.0

package/dist/agent/observation-state.js

@@ -0,0 +1,246 @@
+import { boundedJson } from "../shared/bounded-json.js";
+const VALUE_BUDGET = { bytes: 64 * 1024, nodes: 4096, depth: 32 };
+/** Longer native identifiers are left to the journal rather than keyed live. */
+export const NAME_CHARS = 1024;
+const RETAINED = { settlements: 128, tools: 256 };
+const WRITING = { text: "writing", thinking: "thinking", toolCall: "calling" };
+export class LiveTool {
+    partial;
+    rev = 0;
+    ended;
+    id;
+    name;
+    args;
+    argsJson;
+    partialJson;
+    resultJson;
+    constructor(id, name, args) {
+        this.id = id;
+        this.name = name;
+        this.args = args;
+    }
+    /** Replaceable progress: only the latest reference is projected at the next flush. */
+    progress(value) {
+        this.partial = value;
+        this.rev++;
+    }
+    projectedArgs(project) {
+        this.argsJson ??= project(this.args);
+        return this.argsJson;
+    }
+    projectedPartial(project) {
+        if (this.partialJson?.rev !== this.rev) {
+            this.partialJson = { rev: this.rev, json: project(this.partial) };
+        }
+        return this.partialJson.json;
+    }
+    projectedResult(project) {
+        this.resultJson ??= project(this.ended?.result);
+        return this.resultJson;
+    }
+}
+/**
+ * Single-writer actor state. Sparse tool hooks always keep the tool table, because native state
+ * retains neither progress, unpublished parallel results nor nested calls. Token-rate message
+ * events arrive only while a detail viewer observes; attaching seeds from public native state.
+ */
+export class LiveState {
+    version = 0;
+    activityVersion = 0;
+    message;
+    tools = new Map();
+    settlements = [];
+    settled = 0;
+    /** Live items dropped by a retention bound or a branch change; viewers resynchronize. */
+    evicted = 0;
+    events = 0;
+    toolEvents = 0;
+    progressUpdates = 0;
+    projections = 0;
+    unavailable = 0;
+    observing = false;
+    nextKey = 0;
+    queued = false;
+    closed = false;
+    watermark;
+    session;
+    changed;
+    failed;
+    constructor(session, changed, failed) {
+        this.session = session;
+        this.changed = changed;
+        this.failed = failed;
+        this.watermark = session.sessionManager.getLeafId();
+    }
+    /** Start or stop the transient message view; tools persist across viewers. */
+    observe(on) {
+        this.resolve();
+        this.observing = on;
+        this.message = undefined;
+        this.settlements.length = 0;
+        if (on) {
+            const streaming = this.session.state.streamingMessage;
+            if (streaming?.role === "assistant") {
+                this.assistant("message_start", streaming);
+            }
+        }
+        this.version++;
+        this.activityVersion++;
+    }
+    apply(event) {
+        this.events++;
+        if (event.type === "message_start" ||
+            event.type === "message_update" ||
+            event.type === "message_end") {
+            this.messageEvent(event);
+        }
+    }
+    messageEvent(event) {
+        if (event.message.role === "assistant") {
+            this.assistant(event.type, event.message);
+        }
+        if (event.type === "message_end" && !this.queued) {
+            this.queued = true;
+            // Native message_end listeners run just before the same job appends the entry.
+            queueMicrotask(this.settle);
+        }
+    }
+    assistant(type, message) {
+        let live = this.message;
+        if (type === "message_start" || live === undefined) {
+            // A previous message still here was never found in the session tree.
+            this.evicted += live === undefined ? 0 : 1;
+            live = { key: ++this.nextKey, message, ended: false };
+            this.message = live;
+        }
+        live.message = message;
+        live.ended = type === "message_end";
+        this.version++;
+    }
+    tool(event) {
+        this.toolEvents++;
+        this.version++;
+        if (event.type === "tool_execution_start") {
+            this.resolve();
+            this.startTool(event.toolCallId, event.toolName, event.args);
+            return;
+        }
+        const tool = this.tools.get(event.toolCallId);
+        if (event.type === "tool_execution_update") {
+            tool?.progress(event.partialResult);
+            this.progressUpdates++;
+        }
+        else if (tool) {
+            tool.ended = { isError: event.isError, result: event.result };
+            this.activityVersion++;
+        }
+    }
+    startTool(id, name, args) {
+        if (id.length > NAME_CHARS) {
+            this.unavailable++;
+            return;
+        }
+        const oldest = this.tools.size >= RETAINED.tools ? this.tools.keys().next() : undefined;
+        if (oldest?.done === false) {
+            this.tools.delete(oldest.value);
+            this.evicted++;
+        }
+        this.tools.set(id, new LiveTool(id, name, args));
+        this.activityVersion++;
+    }
+    settle = () => {
+        this.queued = false;
+        try {
+            if (!this.closed && this.resolve()) {
+                this.changed();
+            }
+        }
+        catch (error) {
+            this.failed(error);
+        }
+    };
+    /**
+     * Hand native messages appended since the last walk over to their session entries. A live
+     * message without an entry is unresolved publication and stays live. Returns whether anything
+     * changed.
+     */
+    resolve() {
+        const { appended, departed } = this.appended();
+        this.evicted += departed && this.observing ? 1 : 0;
+        for (const entry of appended) {
+            this.publish(entry, !departed && this.observing);
+        }
+        this.settlements.splice(0, Math.max(0, this.settlements.length - RETAINED.settlements));
+        const changed = appended.length > 0;
+        this.version += changed ? 1 : 0;
+        this.activityVersion += changed ? 1 : 0;
+        return changed;
+    }
+    /** Message entries since the previous walk, in journal order; each append is visited once. */
+    appended() {
+        const manager = this.session.sessionManager;
+        const appended = [];
+        let entry = manager.getLeafEntry();
+        const leaf = entry?.id ?? null;
+        while (entry !== undefined && entry.id !== this.watermark) {
+            if (entry.type === "message") {
+                appended.push(entry);
+            }
+            entry = entry.parentId === null ? undefined : manager.getEntry(entry.parentId);
+        }
+        // A leaf off the previous branch walked to the root once; its entries are not new.
+        const departed = entry === undefined && this.watermark !== null;
+        this.watermark = leaf;
+        return { appended: appended.reverse(), departed };
+    }
+    publish({ id, message }, settle) {
+        const call = message.role === "toolResult" ? message.toolCallId : "";
+        const tool = call.length > 0 && call.length <= NAME_CHARS ? call : null;
+        // A published result also retires the calls it made through ctx.executeTool().
+        const retired = (key) => tool !== null && (key === tool || key.startsWith(`${tool}/`));
+        for (const live of [...this.tools.keys()].filter(retired)) {
+            this.tools.delete(live);
+        }
+        const key = this.message?.message === message ? this.message.key : null;
+        this.message = key === null ? this.message : undefined;
+        if (settle) {
+            const seq = ++this.settled;
+            this.settlements.push({ seq, json: JSON.stringify([seq, id, key, tool]) });
+        }
+    }
+    dispose() {
+        this.closed = true;
+    }
+    project = (value) => {
+        this.projections++;
+        const result = boundedJson(value, VALUE_BUDGET);
+        if ("json" in result) {
+            return `{"json":${result.json}}`;
+        }
+        this.unavailable++;
+        return `{"unavailable":"${result.unavailable}"}`;
+    };
+    /** Sampled from public native state, so compact peers never need token-rate events. */
+    activity(busy) {
+        const { session } = this;
+        const running = [...this.tools.values()].filter((tool) => tool.ended === undefined);
+        const streaming = session.state.streamingMessage;
+        const content = streaming?.role === "assistant" ? streaming.content : undefined;
+        const last = content?.at(-1)?.type;
+        const phases = [
+            [running.length > 0, "tool"],
+            [content !== undefined, last === undefined ? "responding" : WRITING[last]],
+            [session.isCompacting, "compacting"],
+            [session.isRetrying, "retrying"],
+            [busy || session.isStreaming, "working"],
+        ];
+        const phase = phases.find(([active]) => active)?.[1] ?? "idle";
+        return JSON.stringify({
+            phase,
+            tools: running.slice(0, 3).map((tool) => tool.name.slice(0, 64)),
+            running: running.length,
+            model: this.session.model?.id,
+            thinking: this.session.thinkingLevel,
+        });
+    }
+}

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;
+    }
+}