Multiplayer agent harness for work.
import { postCallText, postResultOk } from "./surface-post.ts";
import type { PendingApproval, ToolActivity, WorkBlock } from "./core-bridge.ts";
export interface ToolPayload {
sessionId?: string;
title?: string;
task?: string;
target?: string;
delivered?: string;
interrupt?: boolean;
status?: string;
children?: number;
tool?: string;
command?: string;
background?: boolean;
purpose?: string;
path?: string;
bytes?: number;
name?: string;
url?: string;
query?: string;
seq?: number;
count?: number;
found?: boolean;
blocked?: string;
denied?: boolean;
error?: string;
reason?: string;
code?: number;
timedOut?: boolean;
isError?: boolean;
result?: string;
quarantined?: boolean;
action?: string;
process_id?: string;
sandbox_id?: string | null;
monitor_id?: string;
added?: number;
}
export interface ToolRowModel {
call: ToolActivity | null;
result: ToolActivity | null;
approval?: ToolActivity;
attempts?: number;
pending?: PendingApproval;
}
export type TimelineItem =
| { kind: "steer"; activity: ToolActivity }
| { kind: "thinking"; activity: ToolActivity }
| { kind: "text"; activity: ToolActivity }
| { kind: "tool"; row: ToolRowModel }
| { kind: "approval"; approval: PendingApproval };
export function workTimelineSegments(items: TimelineItem[]): TimelineItem[][] {
const segments: TimelineItem[][] = [[]];
for (const item of items) {
if (item.kind === "steer") segments.push([item], []);
else segments.at(-1)!.push(item);
}
return segments;
}
function isTerminalWorkStatus(status: WorkBlock["status"]): boolean {
return status === "complete" || status === "failed";
}
export type ToolRowKind = "running" | "ok" | "failed" | "attempted" | "approval";
export function toolCategory(payload: ToolPayload): string {
if (payload.tool === "execute" && payload.background === true) return "background";
if (payload.tool === "files") {
if (payload.action === "read" || payload.action === "write") return payload.action;
return "share";
}
if (payload.tool === "skills") return payload.action === "read" ? "skill" : "share";
if (payload.tool === "apps") return payload.action === "publish" ? "publish" : "share";
if (payload.tool === "sessions" || payload.tool === "subagents") return "session";
if (payload.tool !== "sandbox") return payload.tool ?? "unknown";
if (payload.action === "exec") return "execute";
if (
[
"start_process",
"read_process",
"write_stdin",
"signal_process",
"list_processes",
"watch_process",
"unwatch_process",
].includes(payload.action ?? "")
)
return "background";
return "sandbox";
}
export function toolExecutionOutput(result: ToolPayload): string | null {
return typeof result.code === "number" && typeof result.result === "string" ? result.result : null;
}
export function toolRowKind(row: ToolRowModel, status: WorkBlock["status"]): ToolRowKind {
const result = (row.result?.payload ?? {}) as ToolPayload;
if (result.blocked === "needs_approval") return "approval";
if (!row.result) {
if (!isTerminalWorkStatus(status)) return "running";
return status === "failed" ? "failed" : "attempted";
}
const completedNonzeroExecution =
toolCategory({ ...result, ...((row.call?.payload ?? {}) as ToolPayload) }) === "execute" &&
typeof result.code === "number" &&
Number.isFinite(result.code) &&
result.code !== 0 &&
result.timedOut === false &&
toolExecutionOutput(result) !== null;
const failed =
(result.isError === true && !completedNonzeroExecution) ||
!!result.error ||
result.denied === true ||
result.timedOut === true ||
result.quarantined === true;
return failed ? "failed" : "ok";
}
function callIdOf(a: ToolActivity): string | undefined {
const id = (a.payload as { callId?: unknown } | null)?.callId;
return typeof id === "string" && id ? id : undefined;
}
export function postSpeechText(row: ToolRowModel, allowInFlight = false): string | null {
const text = postCallText(row.call?.payload);
if (!text?.trim()) return null;
if (row.result) return postResultOk(row.result.payload) ? text : null;
return allowInFlight && !row.approval && !row.pending ? text : null;
}
function orphanCallSignature(row: ToolRowModel): string | null {
if (!row.call || row.result || row.approval) return null;
const p = (row.call.payload ?? {}) as ToolPayload;
return [
p.tool ?? "unknown",
p.action ?? "",
p.sandbox_id ?? "",
p.process_id ?? "",
p.monitor_id ?? "",
p.command ?? "",
p.path ?? "",
p.name ?? "",
p.url ?? "",
p.query ?? "",
p.seq !== undefined ? String(p.seq) : "",
].join("");
}
const timelineMemo = new WeakMap<
WorkBlock,
{
activity: WorkBlock["activity"];
reasoning: WorkBlock["reasoning"];
status: WorkBlock["status"];
approvals: WorkBlock["pendingApprovals"];
items: TimelineItem[];
}
>();
export function buildTimeline(work: WorkBlock): TimelineItem[] {
const hit = timelineMemo.get(work);
if (
hit &&
hit.activity === work.activity &&
hit.reasoning === work.reasoning &&
hit.status === work.status &&
hit.approvals === work.pendingApprovals
) {
return hit.items;
}
const items = buildTimelineUncached(work);
timelineMemo.set(work, {
activity: work.activity,
reasoning: work.reasoning,
status: work.status,
approvals: work.pendingApprovals,
items,
});
return items;
}
function buildTimelineUncached(work: WorkBlock): TimelineItem[] {
const pendingByCmd = new Map<string, PendingApproval[]>();
for (const a of work.pendingApprovals ?? []) {
const list = pendingByCmd.get(a.command);
if (list) list.push(a);
else pendingByCmd.set(a.command, [a]);
}
const items: TimelineItem[] = [];
const rowByCallId = new Map<string, ToolRowModel>();
let open: ToolRowModel | null = null;
for (const a of work.activity) {
if (a.type === "text_start") continue;
if (a.type === "user") {
if (
(a.payload as { steered?: boolean; hidden?: boolean } | null)?.steered &&
!(a.payload as { hidden?: boolean } | null)?.hidden
)
items.push({ kind: "steer", activity: a });
open = null;
} else if (a.type === "thinking") {
items.push({ kind: "thinking", activity: a });
open = null;
} else if (a.type === "text") {
items.push({ kind: "text", activity: a });
open = null;
} else if (a.type === "approval_resolved") {
open = null;
} else if (a.type === "tool_call") {
const row: ToolRowModel = { call: a, result: null };
const cid = callIdOf(a);
if (cid) rowByCallId.set(cid, row);
open = row;
items.push({ kind: "tool", row });
} else if (a.type === "tool_result") {
const cid = callIdOf(a);
const matched = cid ? rowByCallId.get(cid) : undefined;
if (matched && !matched.result) matched.result = a;
else if (!cid && open && !open.result) open.result = a;
else items.push({ kind: "tool", row: { call: null, result: a } });
} else {
items.push({ kind: "tool", row: { call: null, result: null, approval: a } });
open = null;
}
}
if (!isTerminalWorkStatus(work.status)) {
liveReasoning(work).forEach((block, i) =>
items.push({
kind: "thinking",
activity: {
seq: -1 - i,
parentSeq: null,
type: "thinking",
payload: { thinking: block.text, step: { id: block.step, index: block.index } },
createdAt: 0,
},
}),
);
}
const collapsed = collapseToolItems(items, work.status);
for (const item of collapsed) {
if (item.kind !== "tool") continue;
const cmd = (item.row.call?.payload as ToolPayload | undefined)?.command;
const blocked = (item.row.result?.payload as ToolPayload | undefined)?.blocked === "needs_approval";
if (!cmd || !blocked) continue;
const queue = pendingByCmd.get(cmd);
if (queue?.length) item.row.pending = queue.shift();
}
for (const queue of pendingByCmd.values()) for (const a of queue) collapsed.push({ kind: "approval", approval: a });
return collapsed;
}
export function thinkingStepKey(payload: unknown): string | null {
const step = (payload as { step?: { id?: unknown; index?: unknown } } | null)?.step;
return step ? `${String(step.id)}:${String(step.index)}` : null;
}
function liveReasoning(work: WorkBlock): NonNullable<WorkBlock["reasoning"]> {
const persisted = new Set(work.activity.map((a) => (a.type === "thinking" ? thinkingStepKey(a.payload) : null)));
return (work.reasoning ?? []).filter((b) => b.text.trim() && !persisted.has(`${b.step}:${b.index}`));
}
function collapseToolItems(items: TimelineItem[], status: WorkBlock["status"]): TimelineItem[] {
if (!isTerminalWorkStatus(status)) return items;
const out: TimelineItem[] = [];
for (const item of items) {
if (item.kind !== "tool") {
out.push(item);
continue;
}
const prev = out[out.length - 1];
const sig = orphanCallSignature(item.row);
if (sig && prev?.kind === "tool" && orphanCallSignature(prev.row) === sig) {
prev.row.attempts = (prev.row.attempts ?? 1) + (item.row.attempts ?? 1);
continue;
}
out.push({ kind: "tool", row: { ...item.row, attempts: item.row.attempts ?? 1 } });
}
return out;
}
export function sessionToolView(
call: ToolPayload,
result: ToolPayload,
sessions: readonly { id: string; title?: string | null }[],
): { action: string; chipTitle?: string; sessionId?: string; detail: string } {
const action = call.interrupt === true ? "interrupt" : (call.action ?? result.action ?? "");
const target = result.sessionId ?? call.target;
const session =
sessions.find((row) => row.id === target || row.title === target) ??
sessions.find((row) => result.result?.includes(`(sessionId ${row.id})`));
const sessionId = session?.id ?? result.sessionId;
let chipTitle = session?.title || result.title || call.name || "Subagent";
let detail = "";
if (action === "wait") return { action, detail: "for agent messages" };
if (action === "read" && !target && result.children === undefined) return { action, detail: "subagents" };
if (action === "read" && result.children !== undefined) {
return { action, detail: `${result.children} subagent${result.children === 1 ? "" : "s"}` };
}
if (action === "open" && !session?.title && !result.title && !call.name && call.task) {
chipTitle = call.task.split("\n")[0].slice(0, 48);
}
if (action === "write" || action === "send_message" || action === "followup_task") {
const verbs: Record<string, string> = {
steered: "steered",
queued_turn: "queued a turn",
queued_message: "",
interrupted: "interrupted",
};
detail = result.delivered ? (verbs[result.delivered] ?? result.delivered) : "";
} else if (action === "read") detail = result.status ?? "";
return { action, chipTitle, ...(sessionId ? { sessionId } : {}), detail };
}
export function currentTextPhase(work: WorkBlock): {
phase: "commentary" | "final_answer" | undefined;
streamOffset: number;
startedAt: number;
} | null {
const entry = work.activity.findLast((activity) => activity.type === "text_start");
if (!entry) return null;
const payload = entry.payload as { phase?: unknown; streamOffset?: unknown } | null;
if (
(payload?.phase !== undefined && payload.phase !== "commentary" && payload.phase !== "final_answer") ||
typeof payload?.streamOffset !== "number" ||
!Number.isSafeInteger(payload.streamOffset) ||
payload.streamOffset < 0
)
return null;
return { phase: payload.phase, streamOffset: payload.streamOffset, startedAt: entry.createdAt };
}
export function streamedAnswer(text: string, work: WorkBlock): string {
const phase = currentTextPhase(work);
if (phase) {
const lastText = work.activity.findLast((entry) => entry.type === "text_start" || entry.type === "text");
if (phase.phase !== "final_answer" && lastText?.type === "text") return "";
return streamTextFrom(text, phase.streamOffset, work.streamStartOffset ?? 0);
}
return work.streamStartOffset
? streamTextFrom(text, 0, work.streamStartOffset)
: streamingTextTail(text, work.activity);
}
function streamTextFrom(text: string, offset: number, startOffset: number): string {
if (offset >= startOffset) return text.slice(offset - startOffset);
let boundary = 0;
while (boundary < text.length && text[boundary]!.trim()) boundary++;
return "…earlier output omitted\n\n" + text.slice(boundary).trimStart();
}
export function streamingTextTail(text: string, activity: ToolActivity[]): string {
let tail = text;
for (const entry of activity) {
if (entry.type !== "text") continue;
const spoken = ((entry.payload as { text?: string } | null)?.text ?? "").trim();
if (!spoken) continue;
const candidate = tail.trimStart();
if (candidate.startsWith(spoken)) tail = candidate.slice(spoken.length).replace(/^\s*?\n\n/, "");
else if (spoken.startsWith(candidate)) return "";
else break;
}
return tail;
}
export function messageWorkTimeline(work: WorkBlock, finalText: string): TimelineItem[] {
const timeline = buildTimeline(work);
const lastText = finalText.trim() ? timeline.findLastIndex((item) => item.kind === "text") : -1;
return timeline.filter((item, index) => {
if (item.kind === "thinking") {
const payload = item.activity.payload as { thinking?: string; redacted?: boolean } | null;
return !payload?.redacted && Boolean(payload?.thinking?.trim());
}
if (item.kind !== "text") return true;
const payload = item.activity.payload as { text?: string; demoted?: boolean; phase?: string } | null;
return (
!payload?.demoted &&
Boolean(payload?.text?.trim()) &&
!(index === lastText && payload?.phase !== "commentary" && payload?.text?.trim() === finalText.trim())
);
});
}