aec-agent 1.0.1 → 1.0.4

package/dist/components/group-hub/group-turns.js

@@ -0,0 +1,834 @@
+import { randomUUID } from "node:crypto";
+import { GroupError } from "../../kernel/errors/group-error.js";
+import { SDKEventType } from "../event-handler/events.js";
+import { safeError } from "../multi-agent-orchestration/agent/subagent-manager/brief.js";
+import { buildMemberPrompt } from "./member-prompt.js";
+import { resolveRecipients } from "./recipients.js";
+import { GROUP_TEXT_LIMITS, resolveGroupLimits, } from "./types.js";
+const ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+const SPAWN_TOOL = "spawn_subagent";
+/**
+ * Group turns (A-109, A-112, A-115) — runs one user message through a group:
+ *  - one member answers alone; or several answer side by side as one round and the lead
+ *    sums up; or the lead answers and hands parts to members through spawn_subagent (A-105,
+ *    under a spawn scope: the members see the thread, work in their own member sessions,
+ *    stream into the thread, and need no extra approval), then sums up;
+ *  - guard rails: members per round, a token budget and a deadline for the whole turn, a
+ *    deadline per member; hand-off depth is A-105's (a member cannot delegate further);
+ *  - stop the whole turn or one member; one member failing does not fail the round, and the
+ *    summary says what is missing; retry one member's answer.
+ * One group turn runs per group session at a time.
+ */
+export class GroupTurns {
+    deps;
+    active = new Map();
+    /** Lead session → its spawn scope while it leads a turn. */
+    scopes = new Map();
+    /** `${groupSessionId}\0${agentId}` → the member's session id. */
+    memberSessions = new Map();
+    /** Hand-off answers by child run id, until the run's end settles them. */
+    handoffWriters = new Map();
+    unsubscribes = [];
+    constructor(deps) {
+        this.deps = deps;
+        const bus = deps.eventBus;
+        // The turn's budget counts every model response in its member sessions.
+        this.unsubscribes.push(bus.on(SDKEventType.ModelResponded, (e) => {
+            if (!e.payload.usage)
+                return;
+            for (const turn of this.active.values()) {
+                if (!turn.memberSessions.has(e.sessionId))
+                    continue;
+                turn.usage = addUsage(turn.usage, e.payload.usage);
+                const used = turn.usage.inputTokens + turn.usage.outputTokens;
+                if (used > turn.limits.maxTokensPerTurn) {
+                    this.limit(turn, `Stopped: this turn used its ${turn.limits.maxTokensPerTurn.toLocaleString("en-US")} tokens (maxTokensPerTurn).`);
+                }
+            }
+        }));
+    }
+    /** SubagentScopes: a lead session's spawn scope while it leads a group turn. */
+    get(sessionId) {
+        return this.scopes.get(sessionId);
+    }
+    isBusy(sessionId) {
+        return this.active.has(sessionId);
+    }
+    /** The running turns, for "busy" marks: group session → who is doing what. */
+    running() {
+        return [...this.active.values()].map((t) => ({ groupId: t.group.id, sessionId: t.sessionId, turnId: t.id, presence: [...t.presence.values()] }));
+    }
+    /** What each member of a running turn is doing now (empty when idle). */
+    presenceOf(sessionId) {
+        return [...(this.active.get(sessionId)?.presence.values() ?? [])];
+    }
+    /** Run one user message through the group. Throws GroupError before anything runs. */
+    async send(group, session, request, options = {}) {
+        const text = typeof request.text === "string" ? request.text.trim() : "";
+        if (!text)
+            throw new GroupError("the message is empty", "invalid_argument");
+        if (text.length > GROUP_TEXT_LIMITS.message) {
+            throw new GroupError(`the message is ${text.length} characters; keep it under ${GROUP_TEXT_LIMITS.message}`, "invalid_argument");
+        }
+        const host = this.requireReady(group);
+        const turn = this.begin(group, session.id, options.signal);
+        try {
+            const members = group.members.filter((id) => host.get(id)).map((id) => ({ id, name: host.get(id).profile.name }));
+            const { addressed, plan } = resolveRecipients({ text, to: request.to, members, leadId: group.leadId, replyMode: group.replyMode, muted: group.muted });
+            const user = await this.deps.thread.append({ sessionId: session.id, groupId: group.id, kind: "user", text, to: addressed });
+            turn.added.push(user.id);
+            await this.titleFrom(session, text);
+            this.deps.eventBus.emit({ type: SDKEventType.GroupTurnStarted, sessionId: session.id, payload: { groupId: group.id, turnId: turn.id, plan: plan.kind } });
+            await this.runPlan(turn, plan);
+            return await this.end(turn, plan);
+        }
+        catch (err) {
+            await this.end(turn, { kind: "none", reason: "failed" }).catch(() => undefined);
+            throw err;
+        }
+    }
+    /** Run a member's answer again, in place. Throws GroupError before anything runs. */
+    async retry(group, session, message, options = {}) {
+        if (message.kind !== "agent" || !message.agentId)
+            throw new GroupError("only a member's answer can be retried", "invalid_argument");
+        if (message.status === "running")
+            throw new GroupError("that answer is still being written", "busy");
+        const host = this.requireReady(group);
+        if (!host.get(message.agentId) || !group.members.includes(message.agentId)) {
+            throw new GroupError(`"${message.agentId}" is not a running member of this group`, "unknown_agent");
+        }
+        const turn = this.begin(group, session.id, options.signal);
+        const plan = { kind: "single", agentId: message.agentId };
+        try {
+            this.deps.eventBus.emit({ type: SDKEventType.GroupTurnStarted, sessionId: session.id, payload: { groupId: group.id, turnId: turn.id, plan: plan.kind } });
+            await this.memberTurn(turn, message.agentId, {
+                role: message.summary ? "summary" : "retry",
+                retry: message,
+                ...(message.roundId ? { roundId: message.roundId } : {}),
+            });
+            return await this.end(turn, plan);
+        }
+        catch (err) {
+            await this.end(turn, plan).catch(() => undefined);
+            throw err;
+        }
+    }
+    /** Stop the session's running turn, or (with `agentId`) one member of it. False when nothing ran. */
+    stop(sessionId, agentId) {
+        const turn = this.active.get(sessionId);
+        if (!turn)
+            return false;
+        if (!agentId) {
+            turn.reason ??= "stopped";
+            turn.controller.abort();
+            return true;
+        }
+        const direct = turn.direct.get(agentId);
+        if (direct) {
+            direct.reason ??= "cancelled";
+            direct.controller.abort();
+            return true;
+        }
+        const child = turn.spawned.get(agentId);
+        if (child)
+            return this.deps.getAgents()?.get(child.leadId)?.subagents.stop(child.runId) ?? false;
+        return false;
+    }
+    /** Resolves once the session's running turn (if any) has ended. */
+    async idle(sessionId) {
+        await this.active.get(sessionId)?.done;
+    }
+    /** Stop every running turn and stop listening. */
+    dispose() {
+        for (const turn of this.active.values()) {
+            turn.reason ??= "stopped";
+            turn.controller.abort();
+        }
+        for (const off of this.unsubscribes)
+            off();
+        this.unsubscribes = [];
+    }
+    /** Forget a deleted group session (its member sessions are deleted by the hub). */
+    forgetSession(sessionId) {
+        for (const key of [...this.memberSessions.keys()])
+            if (key.startsWith(`${sessionId}\0`))
+                this.memberSessions.delete(key);
+    }
+    /** The member's private session in a group session, created on first use. */
+    memberSession(group, groupSessionId, agentId) {
+        const key = `${groupSessionId}\0${agentId}`;
+        let found = this.memberSessions.get(key);
+        if (!found) {
+            found = (async () => {
+                const sessions = this.deps.getSessions();
+                const existing = await sessions.list({ metadata: { source: "group-member", groupSessionId, agentId } });
+                if (existing[0])
+                    return existing[0].id;
+                const metadata = { agentId, source: "group-member", groupId: group.id, groupSessionId, title: `Group: ${group.name}` };
+                return (await sessions.create({ ...metadata })).id;
+            })();
+            this.memberSessions.set(key, found);
+            found.catch(() => this.memberSessions.delete(key));
+        }
+        return found;
+    }
+    // ---------------------------------------------------------------------------
+    // A turn's life
+    // ---------------------------------------------------------------------------
+    requireReady(group) {
+        const host = this.deps.getAgents();
+        if (!host)
+            throw new GroupError("no agents are running in this host", "unknown_agent");
+        const running = group.members.filter((id) => host.get(id));
+        if (running.length < 2)
+            throw new GroupError("the group needs at least 2 running members", "invalid_argument");
+        if (!host.get(group.leadId))
+            throw new GroupError(`the lead "${group.leadId}" is not running`, "unknown_agent");
+        return host;
+    }
+    begin(group, sessionId, signal) {
+        if (this.active.has(sessionId))
+            throw new GroupError("a group turn is already running in this session; wait for it or stop it", "busy");
+        const limits = resolveGroupLimits(group.limits);
+        const turn = {
+            id: randomUUID(),
+            group,
+            sessionId,
+            limits,
+            controller: new AbortController(),
+            direct: new Map(),
+            spawned: new Map(),
+            memberSessions: new Set(),
+            usage: { ...ZERO_USAGE },
+            added: [],
+            presence: new Map(),
+            settling: new Set(),
+            cleanup: () => undefined,
+            done: Promise.resolve(),
+            finished: () => undefined,
+        };
+        turn.done = new Promise((resolve) => (turn.finished = resolve));
+        this.active.set(sessionId, turn);
+        const onAbort = () => {
+            turn.reason ??= "stopped";
+            turn.controller.abort();
+        };
+        if (signal?.aborted)
+            onAbort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        const timer = setTimeout(() => this.limit(turn, `Stopped: this turn ran for ${Math.round(limits.maxElapsedMsPerTurn / 60_000)} minutes (maxElapsedMsPerTurn).`), limits.maxElapsedMsPerTurn);
+        turn.controller.signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+        turn.cleanup = () => {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+        };
+        return turn;
+    }
+    /** A guard rail ended the turn: stop everyone, note why once. */
+    limit(turn, note) {
+        if (turn.reason)
+            return;
+        turn.reason = "limited";
+        turn.limitNote = note;
+        turn.controller.abort();
+    }
+    async end(turn, plan) {
+        turn.cleanup();
+        for (const agentId of [...turn.presence.keys()])
+            this.setPresence(turn, agentId, "idle");
+        try {
+            await Promise.all([...turn.settling]);
+            if (turn.limitNote)
+                turn.added.push((await this.deps.thread.note(turn.group.id, turn.sessionId, turn.limitNote)).id);
+            await this.deps.thread.settle(turn.sessionId);
+        }
+        finally {
+            this.active.delete(turn.sessionId);
+            turn.finished();
+        }
+        const status = turn.reason === "stopped" ? "stopped" : turn.reason === "limited" ? "limited" : plan.kind === "none" ? "no_reply" : "completed";
+        this.deps.eventBus.emit({
+            type: SDKEventType.GroupTurnFinished,
+            sessionId: turn.sessionId,
+            payload: { groupId: turn.group.id, turnId: turn.id, status, usage: { ...turn.usage } },
+        });
+        const byId = new Map((await this.deps.thread.list(turn.sessionId)).map((m) => [m.id, m]));
+        return {
+            turnId: turn.id,
+            status,
+            plan,
+            messages: turn.added.map((id) => byId.get(id)).filter((m) => !!m),
+            usage: { ...turn.usage },
+        };
+    }
+    async runPlan(turn, plan) {
+        switch (plan.kind) {
+            case "none":
+                turn.added.push((await this.deps.thread.note(turn.group.id, turn.sessionId, plan.reason)).id);
+                return;
+            case "single":
+                await this.memberTurn(turn, plan.agentId, { role: "member" });
+                return;
+            case "round":
+                await this.round(turn, plan.agentIds, plan.summarize);
+                return;
+            case "lead":
+                await this.leadTurn(turn, plan.helpers);
+                return;
+        }
+    }
+    /** Several members side by side; then the lead sums up. */
+    async round(turn, agentIds, summarize) {
+        const max = turn.limits.maxMembersPerRound;
+        const ids = agentIds.slice(0, max);
+        if (agentIds.length > max) {
+            const left = agentIds.slice(max).map((id) => this.nameOf(id)).join(", ");
+            turn.added.push((await this.deps.thread.note(turn.group.id, turn.sessionId, `${left} left out: at most ${max} members answer in one round.`)).id);
+        }
+        const roundId = randomUUID();
+        const prepared = [];
+        for (const id of ids)
+            prepared.push(await this.prepareMember(turn, id, { role: "member", roundId }));
+        const answers = await Promise.all(prepared.map((p) => (p ? this.runMember(turn, p) : null)));
+        if (!summarize || ids.length < 2 || turn.controller.signal.aborted)
+            return;
+        const missing = answers
+            .map((m, i) => ({ agentId: ids[i], message: m }))
+            .filter((a) => !a.message || (a.message.status !== "completed" && a.message.status !== "partial"))
+            .map((a) => ({ agentId: a.agentId, reason: a.message?.error ?? a.message?.status?.replace("_", " ") ?? "no answer" }));
+        await this.memberTurn(turn, turn.group.leadId, { role: "summary", missing });
+    }
+    // ---------------------------------------------------------------------------
+    // One member's turn
+    // ---------------------------------------------------------------------------
+    /** One member answers in its own session; returns its answer (null when it could not run). */
+    async memberTurn(turn, agentId, options) {
+        const prepared = await this.prepareMember(turn, agentId, options);
+        return prepared ? this.runMember(turn, prepared) : null;
+    }
+    /**
+     * What a member is told, and its answer opened in the thread ("running"). A round opens
+     * every answer first, in plan order, so the thread's order does not depend on who starts first.
+     */
+    async prepareMember(turn, agentId, options) {
+        const agent = this.deps.getAgents()?.get(agentId);
+        if (!agent || turn.controller.signal.aborted)
+            return null;
+        const { group, sessionId: groupSessionId } = turn;
+        const memberSession = await this.memberSession(group, groupSessionId, agentId);
+        turn.memberSessions.add(memberSession);
+        const { messages, cursor } = await this.deps.thread.unseen(groupSessionId, agentId);
+        const prompt = buildMemberPrompt({
+            group,
+            names: this.names(group),
+            self: agentId,
+            role: options.role,
+            messages,
+            view: group.memberView,
+            ...(options.missing?.length ? { missing: options.missing } : {}),
+            ...(options.retry ? { retryOf: { status: options.retry.status ?? "failed" } } : {}),
+        });
+        await this.deps.thread.markSeen(groupSessionId, { [agentId]: cursor });
+        const writer = new AnswerWriter(this.deps.thread, {
+            sessionId: groupSessionId,
+            groupId: group.id,
+            agentId,
+            ...(options.roundId ? { roundId: options.roundId } : {}),
+            ...(options.role === "summary" ? { summary: true } : {}),
+        });
+        turn.added.push((await writer.open(options.retry)).id);
+        return { agentId, agent, memberSession, prompt, writer, options };
+    }
+    async runMember(turn, prepared) {
+        const { agentId, agent, memberSession, prompt, writer, options } = prepared;
+        const { group, sessionId: groupSessionId } = turn;
+        const own = { controller: new AbortController(), reason: undefined };
+        turn.direct.set(agentId, own);
+        const onTurnAbort = () => own.controller.abort();
+        if (turn.controller.signal.aborted)
+            onTurnAbort();
+        turn.controller.signal.addEventListener("abort", onTurnAbort, { once: true });
+        const timer = setTimeout(() => {
+            own.reason ??= "timeout";
+            own.controller.abort();
+        }, turn.limits.memberTimeoutMs);
+        this.setPresence(turn, agentId, "thinking", undefined, options.roundId);
+        let result;
+        let failure;
+        try {
+            const traceAttributes = this.traceAttributes(turn, agentId, options.role, options.roundId);
+            const context = {
+                groupId: group.id,
+                groupSessionId,
+                agentId,
+                sessionId: memberSession,
+                role: options.role,
+                ...(options.roundId ? { roundId: options.roundId } : {}),
+                prompt,
+                signal: own.controller.signal,
+                traceAttributes,
+                execute: (signal) => this.stream(turn, agent, memberSession, prompt, signal, traceAttributes, (chunk) => writer.chunk(chunk, (state, tool) => this.setPresence(turn, agentId, state, tool, options.roundId))),
+            };
+            result = await (this.deps.getRunner() ?? defaultRunner)(context);
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            clearTimeout(timer);
+            turn.controller.signal.removeEventListener("abort", onTurnAbort);
+            turn.direct.delete(agentId);
+            this.setPresence(turn, agentId, "idle", undefined, options.roundId);
+        }
+        const status = statusOf(result, failure, own.reason, turn.reason, writer);
+        return writer.finish(status, result?.usage, errorFor(status, failure, writer.streamError, turn.limits.memberTimeoutMs));
+    }
+    /** The lead answers and may hand parts to `helpers`; their answers stream in as one round. */
+    async leadTurn(turn, helpers) {
+        const { group, sessionId: groupSessionId } = turn;
+        const leadId = group.leadId;
+        const lead = this.deps.getAgents()?.get(leadId);
+        if (!lead)
+            return;
+        const leadSession = await this.memberSession(group, groupSessionId, leadId);
+        turn.memberSessions.add(leadSession);
+        const roundId = randomUUID();
+        const { messages, cursor } = await this.deps.thread.unseen(groupSessionId, leadId);
+        const prompt = buildMemberPrompt({ group, names: this.names(group), self: leadId, role: "lead", messages, view: group.memberView, helpers });
+        await this.deps.thread.markSeen(groupSessionId, { [leadId]: cursor });
+        // The lead's text goes into segments: what it says before handing off, then (after the
+        // hand-offs) its summary. A segment is opened by its first text or tool call.
+        let segment = null;
+        let handedOff = false;
+        /** The lead's stream ended on an error chunk (its turn limit, a provider error). */
+        let leadError;
+        const segments = [];
+        const openSegment = async () => {
+            if (segment)
+                return segment;
+            segment = new AnswerWriter(this.deps.thread, { sessionId: groupSessionId, groupId: group.id, agentId: leadId, ...(handedOff ? { summary: true } : {}) });
+            segments.push(segment);
+            turn.added.push((await segment.open()).id);
+            return segment;
+        };
+        const closeSegment = async () => {
+            const open = segment;
+            segment = null;
+            if (open && !open.finished)
+                await open.finish("completed");
+        };
+        const presence = (state, tool) => this.setPresence(turn, leadId, state, tool);
+        const scope = {
+            allow: helpers.map((agentId) => ({ agentId, access: hasOwnSandbox(this.deps.getAgents()?.get(agentId)?.profile) ? "write" : "read-only" })),
+            limits: {
+                maxConcurrent: Math.max(1, Math.min(helpers.length, turn.limits.maxMembersPerRound)),
+                maxRunsPerTurn: turn.limits.maxMembersPerRound,
+                maxTokensPerTurn: turn.limits.maxTokensPerTurn,
+                maxElapsedMsPerTurn: turn.limits.maxElapsedMsPerTurn,
+                childTimeoutMs: turn.limits.memberTimeoutMs,
+            },
+            preApproved: true,
+            grantSpawnTool: true,
+            indexIntro: "These are the other members of your group chat. They see the group thread, so a short, specific task is enough; " +
+                "each answer is shown in the thread and comes back to you.",
+            childSession: async (agentId) => {
+                const id = await this.memberSession(group, groupSessionId, agentId);
+                turn.memberSessions.add(id);
+                return id;
+            },
+            brief: async (request, target) => {
+                handedOff = true;
+                await closeSegment();
+                const row = await this.deps.thread.append({
+                    sessionId: groupSessionId,
+                    groupId: group.id,
+                    kind: "handoff",
+                    agentId: leadId,
+                    toAgentId: target.agentId,
+                    text: request.task,
+                    status: "running",
+                    subagentRunId: target.runId,
+                });
+                turn.added.push(row.id);
+                turn.spawned.set(target.agentId, { runId: target.runId, leadId });
+                const seen = await this.deps.thread.unseen(groupSessionId, target.agentId);
+                await this.deps.thread.markSeen(groupSessionId, { [target.agentId]: seen.cursor });
+                const ask = request.context ? `${request.task}\n\n${JSON.stringify(request.context, null, 2)}` : request.task;
+                return buildMemberPrompt({ group, names: this.names(group), self: target.agentId, role: "handoff", messages: seen.messages, view: group.memberView, ask });
+            },
+            runner: (child) => this.handoffTurn(turn, child, roundId),
+        };
+        // Hand-off rows and answers take the child run's final status (A-105 decides it).
+        const onFinished = (e) => {
+            if (e.sessionId !== leadSession)
+                return;
+            const settling = this.settleHandoff(turn, e.payload.runId, e.payload.status, e.payload.error).catch((err) => {
+                console.warn(`[group] could not record the end of hand-off ${e.payload.runId}:`, errorMessage(err));
+            });
+            turn.settling.add(settling);
+            void settling.finally(() => turn.settling.delete(settling));
+        };
+        const offs = [
+            this.deps.eventBus.on(SDKEventType.SubagentCompleted, onFinished),
+            this.deps.eventBus.on(SDKEventType.SubagentFailed, onFinished),
+            this.deps.eventBus.on(SDKEventType.SubagentCancelled, onFinished),
+        ];
+        this.scopes.set(leadSession, scope);
+        const own = { controller: new AbortController(), reason: undefined };
+        turn.direct.set(leadId, own);
+        const onTurnAbort = () => own.controller.abort();
+        if (turn.controller.signal.aborted)
+            onTurnAbort();
+        turn.controller.signal.addEventListener("abort", onTurnAbort, { once: true });
+        presence("thinking");
+        let result;
+        let failure;
+        try {
+            const traceAttributes = this.traceAttributes(turn, leadId, "lead");
+            result = await (this.deps.getRunner() ?? defaultRunner)({
+                groupId: group.id,
+                groupSessionId,
+                agentId: leadId,
+                sessionId: leadSession,
+                role: "lead",
+                prompt,
+                signal: own.controller.signal,
+                traceAttributes,
+                execute: (signal) => this.stream(turn, lead, leadSession, prompt, signal, traceAttributes, async (chunk) => {
+                    if (chunk.type === "tool_call" && chunk.toolCall?.name === SPAWN_TOOL) {
+                        await closeSegment();
+                        presence("tool", SPAWN_TOOL);
+                        return;
+                    }
+                    if (chunk.type === "error") {
+                        leadError = chunk.error ?? "the model's reply failed";
+                        if (segment)
+                            segment.streamError = leadError;
+                        return;
+                    }
+                    if (chunk.type === "tool_result" && segments.every((s) => !s.hasTool(chunk.toolResult?.toolCallId)))
+                        return;
+                    // An empty text chunk (some providers send content: "") opens no segment.
+                    if (chunk.type === "text" && !chunk.content)
+                        return;
+                    if (chunk.type === "text" || chunk.type === "tool_call" || chunk.type === "tool_result")
+                        await (await openSegment()).chunk(chunk, presence);
+                }),
+            });
+        }
+        catch (err) {
+            failure = err;
+        }
+        finally {
+            this.scopes.delete(leadSession);
+            for (const off of offs)
+                off();
+            turn.controller.signal.removeEventListener("abort", onTurnAbort);
+            turn.direct.delete(leadId);
+            presence("idle");
+        }
+        const last = segment;
+        const status = statusOf(result, failure, own.reason, turn.reason, last ?? (leadError ? { streamError: leadError, hasText: false } : null));
+        if (last && !last.finished)
+            await last.finish(status, result?.usage, errorFor(status, failure, last.streamError, turn.limits.memberTimeoutMs));
+        else if (!segments.length && status !== "completed") {
+            // The lead never wrote anything: still show that it did not answer.
+            const empty = new AnswerWriter(this.deps.thread, { sessionId: groupSessionId, groupId: group.id, agentId: leadId });
+            turn.added.push((await empty.open()).id);
+            await empty.finish(status, result?.usage, errorFor(status, failure, undefined, turn.limits.memberTimeoutMs));
+        }
+        // The lead learned every hand-off result in its own turn.
+        await this.deps.thread.markSeen(groupSessionId, { [leadId]: await this.deps.thread.lastSeq(groupSessionId) });
+    }
+    /** A member's turn for a hand-off: its answer streams into the thread as part of the round. */
+    async handoffTurn(turn, child, roundId) {
+        const agent = this.deps.getAgents()?.get(child.agentId);
+        if (!agent)
+            throw new Error(`"${child.agentId}" is not running`);
+        const writer = new AnswerWriter(this.deps.thread, {
+            sessionId: turn.sessionId,
+            groupId: turn.group.id,
+            agentId: child.agentId,
+            roundId,
+            subagentRunId: child.parent.subagentRunId,
+        });
+        turn.added.push((await writer.open()).id);
+        this.handoffWriters.set(child.parent.subagentRunId, writer);
+        this.setPresence(turn, child.agentId, "thinking", undefined, roundId);
+        try {
+            const result = await (this.deps.getRunner() ?? defaultRunner)({
+                groupId: turn.group.id,
+                groupSessionId: turn.sessionId,
+                agentId: child.agentId,
+                sessionId: child.sessionId,
+                role: "handoff",
+                roundId,
+                prompt: child.prompt,
+                signal: child.signal,
+                traceAttributes: { ...child.traceAttributes, ...this.traceAttributes(turn, child.agentId, "handoff", roundId) },
+                execute: (signal) => this.stream(turn, agent, child.sessionId, child.prompt, signal, child.traceAttributes, (chunk) => writer.chunk(chunk, (state, tool) => this.setPresence(turn, child.agentId, state, tool, roundId))),
+            });
+            // The answer's text is the report; its final status comes with the run's end (settleHandoff).
+            return {
+                output: writer.text || result.output,
+                usage: result.usage,
+                ...(result.aborted ? { aborted: true } : {}),
+                ...(result.stopReason ? { stopReason: result.stopReason } : writer.streamError ? { stopReason: writer.hasText ? "max_tokens" : "error" } : {}),
+            };
+        }
+        finally {
+            this.setPresence(turn, child.agentId, "idle", undefined, roundId);
+        }
+    }
+    /** A hand-off's child run ended: its row and its answer take the run's status. */
+    async settleHandoff(turn, runId, status, error) {
+        for (const [agentId, child] of turn.spawned)
+            if (child.runId === runId)
+                turn.spawned.delete(agentId);
+        const thread = await this.deps.thread.list(turn.sessionId);
+        const row = thread.find((m) => m.kind === "handoff" && m.subagentRunId === runId);
+        if (row)
+            await this.deps.thread.update({ ...row, status, ...(error ? { error } : {}) });
+        const writer = this.handoffWriters.get(runId);
+        this.handoffWriters.delete(runId);
+        if (writer && !writer.finished)
+            await writer.finish(status, undefined, error);
+        else if (!writer) {
+            const answer = thread.find((m) => m.kind === "agent" && m.subagentRunId === runId);
+            if (answer && answer.status !== status)
+                await this.deps.thread.update({ ...answer, status, ...(error ? { error } : {}) });
+        }
+    }
+    /** Runs a member's streamed turn, handing each chunk to `onChunk`. */
+    async stream(turn, agent, sessionId, prompt, signal, traceAttributes, onChunk) {
+        turn.memberSessions.add(sessionId);
+        let usage = { ...ZERO_USAGE };
+        let aborted = false;
+        let stopReason;
+        for await (const chunk of agent.chatStream(prompt, undefined, { signal, sessionId, traceAttributes })) {
+            if (chunk.type === "done") {
+                if (chunk.usage)
+                    usage = { ...chunk.usage };
+                aborted = chunk.aborted === true;
+                if (chunk.stopReason === "max_tokens" || chunk.stopReason === "error")
+                    stopReason = chunk.stopReason;
+            }
+            await onChunk(chunk);
+        }
+        return { output: "", usage, ...(aborted ? { aborted: true } : {}), ...(stopReason ? { stopReason } : {}) };
+    }
+    // ---------------------------------------------------------------------------
+    // Helpers
+    // ---------------------------------------------------------------------------
+    setPresence(turn, agentId, state, tool, roundId) {
+        const prev = turn.presence.get(agentId);
+        if (prev && prev.state === state && prev.tool === tool)
+            return;
+        if (!prev && state === "idle")
+            return;
+        const payload = { groupId: turn.group.id, agentId, state, ...(tool ? { tool } : {}), ...(roundId ? { roundId } : {}) };
+        if (state === "idle")
+            turn.presence.delete(agentId);
+        else
+            turn.presence.set(agentId, payload);
+        this.deps.thread.presence(turn.sessionId, payload);
+    }
+    traceAttributes(turn, agentId, role, roundId) {
+        return {
+            source: "group",
+            groupId: turn.group.id,
+            groupSessionId: turn.sessionId,
+            groupTurnId: turn.id,
+            groupRole: role,
+            memberId: agentId,
+            ...(roundId ? { groupRoundId: roundId } : {}),
+        };
+    }
+    names(group) {
+        const host = this.deps.getAgents();
+        return new Map(group.members.map((id) => [id, host?.get(id)?.profile.name ?? id]));
+    }
+    nameOf(agentId) {
+        return this.deps.getAgents()?.get(agentId)?.profile.name ?? agentId;
+    }
+    /** A new session takes its first message as its title. */
+    async titleFrom(session, text) {
+        if (typeof session.metadata["title"] === "string" && session.metadata["title"])
+            return;
+        const line = text.split("\n").map((l) => l.trim()).find(Boolean) ?? "";
+        const title = line.length > 80 ? `${line.slice(0, 80)}…` : line;
+        await this.deps.thread.updateMetadata(session.id, (meta) => (meta.title ? meta : { ...meta, title }));
+        session.metadata["title"] = title;
+    }
+}
+/**
+ * Writes one member answer into the thread: opens it ("running"), adds streamed text (as
+ * deltas) and tool steps, then stores how it ended.
+ */
+class AnswerWriter {
+    thread;
+    base;
+    message = null;
+    toolStarts = new Map();
+    /** A tool step came after the last text: the next text starts a new paragraph. */
+    gap = false;
+    writing = false;
+    finished = false;
+    streamError;
+    constructor(thread, base) {
+        this.thread = thread;
+        this.base = base;
+    }
+    get text() {
+        return this.message?.text ?? "";
+    }
+    get hasText() {
+        return this.text.trim() !== "";
+    }
+    hasTool(toolCallId) {
+        return !!toolCallId && !!this.message?.tools?.some((t) => t.id === toolCallId);
+    }
+    /** Append the answer (or reset `existing` for a retry). */
+    async open(existing) {
+        if (existing) {
+            const { error: _e, usage: _u, tools: _t, ...rest } = existing;
+            this.message = await this.thread.update({ ...rest, text: "", status: "running" });
+        }
+        else {
+            this.message = await this.thread.append({ ...this.base, kind: "agent", text: "", status: "running" });
+        }
+        return this.message;
+    }
+    async chunk(chunk, presence) {
+        const message = this.message;
+        if (!message || this.finished)
+            return;
+        switch (chunk.type) {
+            case "text": {
+                if (!chunk.content)
+                    return;
+                const piece = this.gap && message.text ? `\n\n${chunk.content}` : chunk.content;
+                this.gap = false;
+                message.text += piece;
+                this.thread.delta(message, piece);
+                if (!this.writing) {
+                    this.writing = true;
+                    presence("writing");
+                }
+                return;
+            }
+            case "tool_call":
+                if (chunk.toolCall)
+                    await this.toolCall(chunk.toolCall);
+                this.writing = false;
+                if (chunk.toolCall)
+                    presence("tool", chunk.toolCall.name);
+                return;
+            case "tool_result":
+                if (chunk.toolResult)
+                    await this.toolResult(chunk.toolResult);
+                presence("thinking");
+                return;
+            case "error":
+                this.streamError = chunk.error;
+                return;
+            default:
+                return;
+        }
+    }
+    async finish(status, usage, error) {
+        const message = this.message;
+        if (!message || this.finished)
+            return message;
+        this.finished = true;
+        const tools = message.tools?.map((t) => (t.status === "running" ? { ...t, status: "error" } : t));
+        const { error: _old, ...rest } = message;
+        this.message = await this.thread.update({
+            ...rest,
+            status,
+            ...(tools ? { tools } : {}),
+            ...(usage && usage.inputTokens + usage.outputTokens > 0 ? { usage } : {}),
+            ...(error ? { error } : {}),
+        });
+        return this.message;
+    }
+    async toolCall(call) {
+        const message = this.message;
+        this.gap = true;
+        this.toolStarts.set(call.id, Date.now());
+        const step = { id: call.id, name: call.name, status: "running", arguments: call.arguments };
+        message.tools = [...(message.tools ?? []), step];
+        this.message = await this.thread.update(message);
+    }
+    async toolResult(result) {
+        const message = this.message;
+        const started = this.toolStarts.get(result.toolCallId);
+        message.tools = (message.tools ?? []).map((t) => t.id === result.toolCallId
+            ? {
+                ...t,
+                status: result.isError ? "error" : "done",
+                resultPreview: result.content.slice(0, 300),
+                ...(started ? { durationMs: Date.now() - started } : {}),
+            }
+            : t);
+        this.message = await this.thread.update(message);
+    }
+}
+const defaultRunner = (context) => context.execute(context.signal);
+/**
+ * How a member's own turn ended. A turn that ended on its own keeps its outcome even when a
+ * stop came in as it finished. The stream's error chunk (the turn limit) is a partial
+ * answer when some text was written, a failure otherwise.
+ */
+function statusOf(result, failure, memberStop, turnStop, writer) {
+    const endedOnItsOwn = failure === undefined && result !== undefined && !result.aborted;
+    if (!endedOnItsOwn) {
+        if (memberStop === "timeout")
+            return "timed_out";
+        if (turnStop === "limited")
+            return "budget_exhausted";
+        if (memberStop === "cancelled" || turnStop === "stopped" || result?.aborted)
+            return "cancelled";
+        return "failed";
+    }
+    if (result.stopReason === "error")
+        return "failed";
+    if (result.stopReason === "max_tokens")
+        return "partial";
+    if (writer?.streamError)
+        return writer.hasText ? "partial" : "failed";
+    return "completed";
+}
+function errorFor(status, failure, streamError, memberTimeoutMs) {
+    switch (status) {
+        case "completed":
+            return undefined;
+        case "failed":
+            return safeError(failure !== undefined ? errorMessage(failure) : (streamError ?? "the model stopped the reply (refusal or content filter)"));
+        case "partial":
+            return "the reply hit the output token limit";
+        case "timed_out":
+            return `did not finish within ${Math.round(memberTimeoutMs / 1000)}s`;
+        case "budget_exhausted":
+            return "the turn's budget ran out";
+        case "cancelled":
+            return "stopped";
+        default:
+            return undefined;
+    }
+}
+function addUsage(a, b) {
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        ...(a.cacheReadTokens || b.cacheReadTokens ? { cacheReadTokens: (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0) } : {}),
+        ...(a.cacheWriteTokens || b.cacheWriteTokens ? { cacheWriteTokens: (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0) } : {}),
+    };
+}
+function hasOwnSandbox(profile) {
+    return !!profile && typeof profile.sandbox === "object" && profile.sandbox !== null && "own" in profile.sandbox;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=group-turns.js.map