@unofficialbox/box-open-elements 0.19.0 → 0.21.0

package/dist/patterns/agent-chat/agent-chat.js

@@ -1,8 +1,14 @@
 import { AgentChatController } from "./controller.js";
 import { isSafeHref } from "../internal/safe-href.js";
 import { BaseElement } from "../../core/index.js";
+import { announce } from "../../foundations/a11y/index.js";
 import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
 import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+import { ScrollPinController, boeEntranceKeyframes, boeReducedMotionPolicy } from "../../foundations/motion/index.js";
+import { boeStatusGlyph, boeStatusStyles } from "../../foundations/status/index.js";
+import { ResultBlocks, resultDocumentIds } from "../../components/collections/result-blocks.js";
+import { RunSummary } from "../run/run-summary.js";
+let chatInstance = 0;
 const DEFAULT_TAG_NAME = "box-agent-chat";
 const escapeHtml = (value) => value
     .replaceAll("&", "&")
@@ -237,7 +243,7 @@ const elementStyles = `
           gap: 0.4rem;
         }
 
-        [part="proposal-action"] {
+        [part="proposal-action"], [part="option"], [part="retry"] {
           appearance: none;
           font: inherit;
           font-size: 0.78rem;
@@ -251,7 +257,9 @@ const elementStyles = `
           transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
         }
 
-        [part="proposal-action"]:hover {
+        [part="option"], [part="retry"] { justify-self: start; min-height: 32px; text-align: left; }
+
+        [part="proposal-action"]:hover, [part="option"]:hover, [part="retry"]:hover {
           background: var(--boe-token-surface-surface-hover, #f4f4f4);
         }
 
@@ -265,7 +273,7 @@ const elementStyles = `
           color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 74%, black 26%);
         }
 
-        [part="proposal-action"]:focus-visible {
+        [part="proposal-action"]:focus-visible, [part="option"]:focus-visible, [part="retry"]:focus-visible {
           outline: none;
           box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
         }
@@ -365,9 +373,22 @@ const elementStyles = `
 export class AgentChat extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["agent-name", "heading", "placeholder", "token"];
+        return ["agent-name", "heading", "placeholder", "token", "hidden", "hide-citations"];
     }
     controller = null;
+    scope = `boe-chat-${++chatInstance}`;
+    composing = false;
+    scrollPin;
+    resizeObserver;
+    messageCount = 0;
+    jumpEl;
+    focusComposer() { this.inputEl?.focus({ preventScroll: true }); }
+    proposalAnchor(messageId, proposalId) { return `${this.scope}-${encodeURIComponent(messageId)}-${encodeURIComponent(proposalId)}`; }
+    focusProposal(messageId, proposalId) {
+        const card = this.shadowRoot?.getElementById(this.proposalAnchor(messageId, proposalId));
+        card?.scrollIntoView({ block: "nearest" });
+        card?.focus({ preventScroll: true });
+    }
     ownsController = false;
     pendingStart = false;
     unsubscribeFns = [];
@@ -425,6 +446,8 @@ export class AgentChat extends BaseElement {
         this.adoptController(value);
     }
     attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "hidden" && newValue === null && this.isRendered)
+            this.focusComposer();
         if (name === "token") {
             this.scheduleStart();
         }
@@ -442,10 +465,26 @@ export class AgentChat extends BaseElement {
     }
     connectedCallback() {
         super.connectedCallback();
+        if (this.controller && !this.ownsController && this.unsubscribeFns.length === 0)
+            this.subscribeToController(this.controller);
+        this.scrollPin?.connect();
+        if (typeof ResizeObserver !== "undefined") {
+            this.resizeObserver = new ResizeObserver(() => this.scrollPin?.contentChanged());
+            this.resizeObserver.observe(this.threadEl);
+            for (const child of Array.from(this.threadEl.children))
+                this.resizeObserver.observe(child);
+        }
         this.scheduleStart();
     }
     disconnectedCallback() {
-        this.teardownController();
+        this.scrollPin?.disconnect();
+        this.resizeObserver?.disconnect();
+        if (this.ownsController)
+            this.teardownController();
+        else {
+            this.unsubscribeFns.forEach(fn => fn());
+            this.unsubscribeFns = [];
+        }
     }
     /** Send the composer's contents (or an explicit body) as a user turn. */
     async send(body) {
@@ -455,11 +494,13 @@ export class AgentChat extends BaseElement {
         }
         // Clear only once the controller has accepted the turn, so a refused
         // send (no controller, or a disconnected session) never loses typing.
-        const sent = await this.controller?.send(text);
-        if (sent && body === undefined && this.inputEl) {
+        const accepted = this.controller?.getState().connected;
+        const sending = this.controller?.send(text);
+        if (accepted && body === undefined && this.inputEl) {
             this.inputEl.value = "";
             this.syncComposer();
         }
+        await sending;
     }
     /** Stop the in-flight generation; the partial reply is kept. */
     stop() {
@@ -525,6 +566,11 @@ export class AgentChat extends BaseElement {
             ["actionResolved", "action-resolved"],
         ];
         this.unsubscribeFns = events.map(([eventName, domEventName]) => controller.subscribe(eventName, payload => {
+            if (eventName === "actionResolved") {
+                const { proposal, decision } = payload;
+                const failed = proposal.outcome === "failed";
+                announce(`${proposal.title}: ${failed ? "Approved, but did not complete" : decision === "approved" ? "Approved" : "Rejected"}${proposal.note ? `. ${proposal.note}` : ""}`, failed ? "assertive" : "polite", this.ownerDocument);
+            }
             this.dispatchEvent(new CustomEvent(domEventName, {
                 bubbles: true,
                 composed: true,
@@ -558,6 +604,13 @@ export class AgentChat extends BaseElement {
         const canResolve = Boolean(this.controller?.config.transport.resolveAction);
         return message.proposals
             .map(proposal => {
+            if (proposal.decision) {
+                const failed = proposal.outcome === "failed";
+                return `<div part="proposal" aria-live="off" tabindex="-1" id="${this.proposalAnchor(message.id, proposal.id)}" data-proposal-id="${escapeHtml(proposal.id)}" data-decision="${escapeHtml(proposal.decision)}" ${failed ? 'role="alert"' : ""}>
+          <span part="decision">${boeStatusGlyph(failed ? "failed" : proposal.decision === "approved" ? "done" : "skipped")}${proposal.decision === "approved" ? failed ? "Approved · didn't complete" : "Approved" : "Rejected"} · <span part="proposal-title">${escapeHtml(proposal.title)}</span></span>
+          ${proposal.note ? `<p part="proposal-note">${escapeHtml(proposal.note)}</p>` : ""}
+          ${failed ? `<button part="retry" data-message-id="${escapeHtml(message.id)}">Try again</button>` : ""}</div>`;
+            }
             const params = (proposal.params ?? [])
                 .map(param => `
               <dt part="param-label">${escapeHtml(param.label)}</dt>
@@ -567,20 +620,22 @@ export class AgentChat extends BaseElement {
             const actions = canResolve && !proposal.decision
                 ? `
               <div part="proposal-actions">
-                <button type="button" part="proposal-action" data-action="approve" data-proposal-id="${escapeHtml(proposal.id)}">Approve</button>
-                <button type="button" part="proposal-action" data-action="reject" data-proposal-id="${escapeHtml(proposal.id)}">Reject</button>
-                <button type="button" part="proposal-action" data-action="modify" data-proposal-id="${escapeHtml(proposal.id)}">Modify</button>
+                <button type="button" part="proposal-action" data-action="approve" data-proposal-id="${escapeHtml(proposal.id)}" ${proposal.resolving ? "disabled" : ""} aria-busy="${proposal.resolving === "approved"}">${proposal.resolving === "approved" ? boeStatusGlyph("active") : ""}Approve</button>
+                <button type="button" part="proposal-action" data-action="reject" data-proposal-id="${escapeHtml(proposal.id)}" ${proposal.resolving ? "disabled" : ""} aria-busy="${proposal.resolving === "rejected"}">${proposal.resolving === "rejected" ? boeStatusGlyph("active") : ""}Reject</button>
+                <button type="button" part="proposal-action" data-action="modify" data-proposal-id="${escapeHtml(proposal.id)}" ${proposal.resolving ? "disabled" : ""}>Modify</button>
               </div>
             `
                 : "";
             return `
-          <div part="proposal" data-proposal-id="${escapeHtml(proposal.id)}"${proposal.decision ? ` data-decision="${escapeHtml(proposal.decision)}"` : ""}>
+          <div part="proposal" tabindex="-1" id="${this.proposalAnchor(message.id, proposal.id)}" data-proposal-id="${escapeHtml(proposal.id)}">
+            <span>${boeStatusGlyph("pending")} Needs your approval</span>
             <span part="proposal-title">${escapeHtml(proposal.title)}</span>
             ${proposal.summary ? `<p part="proposal-summary">${escapeHtml(proposal.summary)}</p>` : ""}
             ${params ? `<dl part="proposal-params">${params}</dl>` : ""}
             ${proposal.decision ? `<span part="decision">${proposal.decision === "approved" ? "Approved" : "Rejected"}</span>` : ""}
             ${proposal.note ? `<p part="proposal-note">${escapeHtml(proposal.note)}</p>` : ""}
             ${actions}
+            <p part="proposal-note">To change it, reply with the new values.</p>
           </div>
         `;
         })
@@ -589,7 +644,8 @@ export class AgentChat extends BaseElement {
     messageInnerHtml(message) {
         const name = message.role === "user" ? "You" : (message.actor?.name ?? this.agentName);
         const initials = message.actor?.initials ?? initialsOf(name);
-        const citations = message.citations
+        const documentIds = resultDocumentIds(message.blocks ?? []);
+        const citations = (this.hasAttribute("hide-citations") ? [] : message.citations.filter(c => !documentIds.includes(c.id)))
             .map(citation => this.citationHtml(message.id, citation))
             .join("");
         return `
@@ -597,10 +653,14 @@ export class AgentChat extends BaseElement {
         <span part="avatar" aria-hidden="true">${escapeHtml(initials)}</span>
         <span part="author">${escapeHtml(name)}</span>
       </div>
-      <p part="body">${escapeHtml(message.body)}${message.status === "streaming" ? `<span part="caret" aria-hidden="true"></span>` : ""}</p>
+      ${message.role === "agent" ? '<box-run-summary></box-run-summary>' : ""}
+      <p part="body">${escapeHtml(message.body)}${message.status === "streaming" && !message.blocks?.length ? `<span part="caret" aria-hidden="true"></span>` : ""}</p>
+      <box-result-blocks></box-result-blocks>
+      ${message.completeness?.status === "incomplete" ? '<p part="incomplete" role="status">This reply may be incomplete.</p>' : ""}
       ${message.status === "error" && message.errorMessage ? `<p part="error" role="alert">${escapeHtml(message.errorMessage)}</p>` : ""}
       ${citations ? `<div part="citations">${citations}</div>` : ""}
       ${this.proposalHtml(message)}
+      ${message.proposals.some(p => p.outcome === "failed") ? "" : (message.options ?? []).map((o, i) => `<button part="option" data-option="${i}">${escapeHtml(o.label)}</button>`).join("")}
     `;
     }
     /**
@@ -620,7 +680,12 @@ export class AgentChat extends BaseElement {
             },
             agentName: this.agentName,
             citations: message.citations.map(({ id, href, label }) => ({ id, href, label })),
-            proposals: message.proposals.map(({ id, title, summary, params, decision, note }) => ({
+            hideCitations: this.hasAttribute("hide-citations"),
+            blocks: message.blocks,
+            completeness: message.completeness?.status,
+            options: message.options,
+            proposals: message.proposals.map(({ id, title, summary, params, decision, note, outcome, resolving }) => ({
+                outcome, resolving,
                 id,
                 title,
                 summary,
@@ -656,21 +721,38 @@ export class AgentChat extends BaseElement {
         body.insertBefore(document.createTextNode(message.body), body.firstChild);
     }
     renderTemplate() {
+        ResultBlocks.register();
+        RunSummary.register();
         if (!this.shadowRoot) {
             return;
         }
         // The composer is part of the stable shell: a streaming reply patches
         // only [part="thread"], so typing is never interrupted.
         this.shadowRoot.innerHTML = `
-      <style>${elementStyles}</style>
+      <style>${elementStyles}
+      [part="message"][data-role="agent"]{border:0;background:transparent;padding-inline:0;max-width:75ch;min-width:0}
+      [part="message"][data-role="user"]{background:var(--boe-token-surface-surface-secondary,#f4f4f4)}
+      [part="proposal"]{border:1px solid var(--boe-token-stroke-stroke,#ddd);background:var(--boe-token-surface-surface,#fff);box-shadow:var(--boe-profile-shadow-overlay,0 3px 14px #0001)}
+      [part="proposal"][data-decision]{border:0;background:transparent;box-shadow:none;padding-inline:0}
+      [part="decision"]{background:none;border-radius:0;padding:0;gap:.4rem;font:inherit}
+      [part="proposal-action"][data-action="approve"],[part="proposal-action"][aria-busy="true"]{background:var(--boe-token-surface-surface-brand,#0061d5);color:var(--boe-token-text-text-on-brand,#fff);border-color:transparent}
+      [part="proposal-action"]:disabled:not([aria-busy="true"]){opacity:.5}
+      [part="composer"]{position:relative;border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:12px;padding:.4rem}
+      [part="input"]{border:0;resize:none;max-height:180px;padding-right:5rem;box-sizing:border-box}
+      [part="composer-actions"]{position:absolute;right:.5rem;bottom:.5rem}
+      [part="jump"]{justify-self:center;border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:999px;padding:.4rem .8rem;background:var(--boe-token-surface-surface,#fff);color:inherit;cursor:pointer}
+      .sr-only{position:absolute;width:1px;height:1px;overflow:hidden;clip-path:inset(50%)}
+      ${boeEntranceKeyframes}${boeStatusStyles}${boeReducedMotionPolicy}</style>
       <section part="panel">
         <div part="header">
           <h2 part="title"></h2>
           <span part="status" role="status" aria-live="polite"></span>
         </div>
-        <ol part="thread" role="log" aria-live="polite" aria-relevant="additions"></ol>
+        <ol part="thread" role="log" aria-live="polite" aria-relevant="additions" tabindex="0"></ol>
+        <button part="jump" hidden>Jump to latest</button>
         <div part="composer">
-          <textarea part="input" rows="2"></textarea>
+          <label class="sr-only" id="${this.scope}-label">Message</label>
+          <textarea part="input" rows="2" aria-labelledby="${this.scope}-label"></textarea>
           <div part="composer-actions">
             <button type="button" part="stop" hidden>Stop</button>
             <button type="button" part="send">Send</button>
@@ -685,6 +767,11 @@ export class AgentChat extends BaseElement {
         this.statusEl = this.shadowRoot.querySelector('[part="status"]');
     }
     setupListeners() {
+        this.jumpEl = this.shadowRoot.querySelector('[part="jump"]');
+        this.scrollPin = new ScrollPinController(this.threadEl, show => { this.jumpEl.hidden = !show; });
+        this.jumpEl.addEventListener("click", () => this.scrollPin?.jump());
+        this.inputEl.addEventListener("compositionstart", () => { this.composing = true; });
+        this.inputEl.addEventListener("compositionend", () => { this.composing = false; });
         this.sendEl.addEventListener("click", () => {
             void this.send();
         });
@@ -693,7 +780,7 @@ export class AgentChat extends BaseElement {
         });
         this.inputEl.addEventListener("keydown", event => {
             // Enter sends, Shift+Enter makes a newline — the conversational default.
-            if (event.key === "Enter" && !event.shiftKey) {
+            if (event.key === "Enter" && !event.shiftKey && !event.isComposing && !this.composing && event.keyCode !== 229) {
                 event.preventDefault();
                 void this.send();
             }
@@ -703,15 +790,31 @@ export class AgentChat extends BaseElement {
         });
         this.threadEl.addEventListener("click", event => {
             const target = event.target;
+            const messageId = target.closest('[part="message"]')?.getAttribute("data-message-id") ?? "";
+            const option = target.closest("[data-option]");
+            if (option) {
+                const prompt = this.controller?.getMessage(messageId)?.options?.[Number(option.dataset.option)]?.prompt;
+                if (prompt)
+                    void this.send(prompt);
+                return;
+            }
+            if (target.closest('[part="retry"]')) {
+                const messages = this.controller?.getState().messages ?? [];
+                const index = messages.findIndex(m => m.id === messageId);
+                const request = messages.slice(0, index).reverse().find(m => m.role === "user");
+                if (request)
+                    void this.send(request.body);
+                return;
+            }
             const proposalButton = target.closest('[part="proposal-action"]');
             if (proposalButton && this.threadEl.contains(proposalButton)) {
                 const proposalId = proposalButton.getAttribute("data-proposal-id") ?? "";
                 const action = proposalButton.getAttribute("data-action") ?? "";
                 if (action === "approve") {
-                    void this.controller?.resolveAction(proposalId, "approved");
+                    void this.controller?.resolveAction(proposalId, "approved", undefined, messageId);
                 }
                 else if (action === "reject") {
-                    void this.controller?.resolveAction(proposalId, "rejected");
+                    void this.controller?.resolveAction(proposalId, "rejected", undefined, messageId);
                 }
                 else if (action === "modify") {
                     // Modifying needs the host's own editor, so this surfaces intent.
@@ -744,6 +847,9 @@ export class AgentChat extends BaseElement {
         const streaming = this.controller?.getState().streaming ?? false;
         this.inputEl.placeholder = this.placeholder;
         this.sendEl.disabled = streaming || this.inputEl.value.trim().length === 0;
+        this.sendEl.hidden = streaming;
+        this.inputEl.style.height = "auto";
+        this.inputEl.style.height = `${Math.min(180, Math.max(56, this.inputEl.scrollHeight))}px`;
         this.stopEl.hidden = !streaming;
         this.statusEl.textContent = streaming ? "Agent is responding…" : "";
     }
@@ -762,7 +868,8 @@ export class AgentChat extends BaseElement {
             : null;
         const state = this.controller?.getState() ?? null;
         const messages = state?.messages ?? [];
-        const atBottom = this.threadEl.scrollHeight - this.threadEl.scrollTop - this.threadEl.clientHeight < 40;
+        const newMessage = messages.length > this.messageCount;
+        this.messageCount = messages.length;
         this.shadowRoot.querySelector('[part="title"]').textContent = this.heading;
         if (messages.length === 0) {
             if (!this.threadEl.querySelector('[part="empty"]')) {
@@ -793,7 +900,13 @@ export class AgentChat extends BaseElement {
                 else {
                     node.setAttribute("data-signature", signature);
                     node.setAttribute("data-status", message.status);
+                    const summary = node.querySelector("box-run-summary");
+                    const results = node.querySelector("box-result-blocks");
                     node.innerHTML = this.messageInnerHtml(message);
+                    if (summary)
+                        node.querySelector("box-run-summary")?.replaceWith(summary);
+                    if (results)
+                        node.querySelector("box-result-blocks")?.replaceWith(results);
                 }
             }
             else {
@@ -806,8 +919,19 @@ export class AgentChat extends BaseElement {
                 this.threadEl.insertBefore(node, anchor);
             }
             previous = node;
+            this.resizeObserver?.observe(node);
+            const blocks = node.querySelector("box-result-blocks");
+            if (blocks && blocks.blocks !== message.blocks)
+                blocks.blocks = message.blocks ?? [];
+            const summary = node.querySelector("box-run-summary");
+            if (summary) {
+                summary.toggleAttribute("failed", message.status === "error");
+                summary.turn = { steps: message.trace ?? [], todos: message.todos ?? [], startedAt: message.startedAt ?? 0,
+                    ...(message.endedAt !== undefined ? { endedAt: message.endedAt } : {}), incomplete: message.completeness?.status === "incomplete" };
+            }
         }
         for (const stale of existing.values()) {
+            this.resizeObserver?.unobserve(stale);
             stale.remove();
         }
         if (focusKey?.part) {
@@ -817,9 +941,7 @@ export class AgentChat extends BaseElement {
             target?.focus();
         }
         // Follow the stream only when the reader is already at the bottom.
-        if (atBottom) {
-            this.threadEl.scrollTop = this.threadEl.scrollHeight;
-        }
+        this.scrollPin?.contentChanged(newMessage);
         this.syncComposer();
     }
 }

package/dist/patterns/agent-chat/controller.d.ts

@@ -11,6 +11,8 @@ export declare class AgentChatController extends Controller<AgentChatState, Agen
     readonly config: AgentChatSessionConfig;
     private sendCounter;
     private activeAbortController;
+    private finishActive?;
+    private readonly resolving;
     constructor(config: AgentChatSessionConfig);
     connect(): void;
     disconnect(): void;
@@ -23,5 +25,5 @@ export declare class AgentChatController extends Controller<AgentChatState, Agen
      */
     send(body: string): Promise<AgentChatMessage | null>;
     /** Resolve a HITL proposal through the transport capability. */
-    resolveAction(proposalId: string, decision: AgentActionDecision, note?: string): Promise<AgentActionProposal | null>;
+    resolveAction(proposalId: string, decision: AgentActionDecision, note?: string, messageId?: string): Promise<AgentActionProposal | null>;
 }

package/dist/patterns/agent-chat/controller.js

@@ -16,6 +16,8 @@ export class AgentChatController extends Controller {
     config;
     sendCounter = 0;
     activeAbortController = null;
+    finishActive;
+    resolving = new Set();
     constructor(config) {
         super(createInitialState());
         this.config = config;
@@ -31,7 +33,7 @@ export class AgentChatController extends Controller {
         if (!this.state.connected) {
             return;
         }
-        this.activeAbortController?.abort();
+        this.stop();
         this.activeAbortController = null;
         this.setState(createInitialState());
         this.emit("disconnected", undefined);
@@ -42,6 +44,7 @@ export class AgentChatController extends Controller {
     /** Abort the in-flight generation; whatever already streamed is kept. */
     stop() {
         this.activeAbortController?.abort();
+        this.finishActive?.();
     }
     /**
      * Send a user turn and stream the agent's reply. One send at a time: a
@@ -52,7 +55,7 @@ export class AgentChatController extends Controller {
         if (!this.state.connected || trimmed.length === 0) {
             return null;
         }
-        this.activeAbortController?.abort();
+        this.stop();
         const abortController = typeof AbortController === "function" ? new AbortController() : null;
         this.activeAbortController = abortController;
         this.sendCounter += 1;
@@ -70,6 +73,9 @@ export class AgentChatController extends Controller {
             role: "agent",
             body: "",
             status: "streaming",
+            startedAt: Date.now(),
+            blocks: [], trace: [], todos: [], options: [],
+            completeness: { status: "streaming", missing: [] },
             ...(this.config.agentName ? { actor: { name: this.config.agentName } } : {}),
             citations: [],
             proposals: [],
@@ -89,37 +95,81 @@ export class AgentChatController extends Controller {
             });
             this.emit("messagesChanged", { messages: this.state.messages });
         };
+        const sequences = new Set();
+        let highSequence = 0;
+        let done;
+        const missing = () => Array.from({ length: highSequence }, (_, i) => i + 1).filter(i => !sequences.has(i));
+        const upsert = (items, item) => item.id && items.some(i => i.id === item.id)
+            ? items.map(i => i.id === item.id ? item : i) : [...items, item];
         const onEvent = (event) => {
             const current = this.getMessage(agentMessage.id);
-            if (!current || current.status !== "streaming") {
+            if (!current || current.status !== "streaming" || abortController?.signal.aborted || turn !== this.sendCounter || done) {
                 return;
             }
+            if (event.seq !== undefined) {
+                if (!Number.isSafeInteger(event.seq) || event.seq < 1 || event.seq > 100000)
+                    throw new Error("Invalid stream sequence");
+                if (sequences.has(event.seq))
+                    return;
+                sequences.add(event.seq);
+                highSequence = Math.max(highSequence, event.seq);
+            }
+            let patch = {};
             if (event.kind === "delta") {
-                patchAgentMessage({ body: current.body + event.text });
+                patch = { body: current.body + event.text };
             }
             else if (event.kind === "citation") {
-                patchAgentMessage({ citations: [...current.citations, event.citation] });
+                patch = { citations: upsert(current.citations, event.citation) };
             }
-            else {
-                patchAgentMessage({ proposals: [...current.proposals, event.proposal] });
+            else if (event.kind === "proposal") {
+                patch = { proposals: upsert(current.proposals, event.proposal) };
+            }
+            else if (event.kind === "block") {
+                patch = { blocks: upsert(current.blocks ?? [], event.block) };
+            }
+            else if (event.kind === "trace") {
+                patch = { trace: upsert(current.trace ?? [], event.step) };
+            }
+            else if (event.kind === "todos") {
+                patch = { todos: event.todos };
+            }
+            else if (event.kind === "options") {
+                patch = { options: event.options };
             }
+            else if (event.kind === "context") {
+                patch = { context: event.context };
+            }
+            else if (event.kind === "done") {
+                done = event.status;
+            }
+            patchAgentMessage({ ...patch, completeness: { status: "streaming", missing: missing() } });
         };
+        let finished = false;
         const finish = (patch) => {
-            patchAgentMessage(patch);
+            if (finished)
+                return;
+            finished = true;
+            const gaps = missing();
+            patchAgentMessage({ ...patch, endedAt: Date.now(), completeness: {
+                    status: patch.status === "error" ? "error" : !done || gaps.length ? "incomplete" : done,
+                    missing: gaps,
+                } });
             // A superseded send must not clear the newer send's streaming flag.
             if (turn === this.sendCounter) {
                 this.setState({ ...this.state, streaming: false });
                 this.emit("streamingChanged", { streaming: false });
             }
         };
+        this.finishActive = () => finish({ status: "complete" });
         try {
             await this.config.transport.sendMessage({
                 body: trimmed,
+                messageId: agentMessage.id,
                 token: this.config.token,
                 onEvent,
                 ...(abortController ? { signal: abortController.signal } : {}),
             });
-            finish({ status: "complete" });
+            finish({ status: done === "error" ? "error" : "complete" });
         }
         catch (error) {
             if (abortController?.signal.aborted) {
@@ -129,42 +179,58 @@ export class AgentChatController extends Controller {
             else {
                 const message = error instanceof Error ? error.message : "The agent reply failed";
                 finish({ status: "error", errorMessage: message });
-                this.setState({ ...this.state, error: message });
-                this.emit("sendFailed", { message });
+                if (turn === this.sendCounter) {
+                    this.setState({ ...this.state, error: message });
+                    this.emit("sendFailed", { message });
+                }
             }
         }
         finally {
             if (this.activeAbortController === abortController) {
                 this.activeAbortController = null;
+                this.finishActive = undefined;
             }
         }
         return this.getMessage(agentMessage.id) ?? null;
     }
     /** Resolve a HITL proposal through the transport capability. */
-    async resolveAction(proposalId, decision, note) {
+    async resolveAction(proposalId, decision, note, messageId) {
         const transport = this.config.transport;
         if (!transport.resolveAction) {
             throw new Error("Agent-chat transport does not support resolveAction");
         }
-        const holder = this.state.messages.find(message => message.proposals.some(proposal => proposal.id === proposalId));
+        const holder = this.state.messages.find(message => (!messageId || message.id === messageId) &&
+            message.proposals.some(proposal => proposal.id === proposalId));
         const pending = holder?.proposals.find(proposal => proposal.id === proposalId);
-        if (!this.state.connected || !holder || !pending || pending.decision) {
+        const key = `${holder?.id}:${proposalId}`;
+        if (!this.state.connected || !holder || !pending || pending.decision || this.resolving.has(key)) {
             return null;
         }
+        const patch = (value) => {
+            this.setState({ ...this.state, messages: this.state.messages.map(m => m.id === holder.id ? {
+                    ...m, proposals: m.proposals.map(p => p.id === proposalId ? { ...p, ...value } : p),
+                } : m) });
+            this.emit("messagesChanged", { messages: this.state.messages });
+        };
+        this.resolving.add(key);
+        patch({ resolving: decision });
         try {
             // Called on the transport so class-based implementations keep `this`.
-            const resolved = await transport.resolveAction({
+            const response = await transport.resolveAction({
                 proposalId,
+                messageId: holder.id,
                 decision,
                 ...(note !== undefined ? { note } : {}),
                 token: this.config.token,
             });
+            const resolved = { ...pending, ...response, decision };
+            delete resolved.resolving;
             this.setState({
                 ...this.state,
                 messages: this.state.messages.map(message => message.id === holder.id
                     ? {
                         ...message,
-                        proposals: message.proposals.map(proposal => proposal.id === proposalId ? { ...proposal, ...resolved } : proposal),
+                        proposals: message.proposals.map(proposal => proposal.id === proposalId ? { ...pending, ...resolved, decision } : proposal),
                     }
                     : message),
             });
@@ -178,5 +244,15 @@ export class AgentChatController extends Controller {
             this.emit("sendFailed", { message });
             return null;
         }
+        finally {
+            this.resolving.delete(key);
+            const current = this.getMessage(holder.id)?.proposals.find(p => p.id === proposalId);
+            if (current?.resolving) {
+                const clean = { ...current };
+                delete clean.resolving;
+                this.setState({ ...this.state, messages: this.state.messages.map(m => m.id === holder.id ? { ...m, proposals: m.proposals.map(p => p.id === proposalId ? clean : p) } : m) });
+                this.emit("messagesChanged", { messages: this.state.messages });
+            }
+        }
     }
 }

package/dist/patterns/agent-chat/index.d.ts

@@ -1,3 +1,4 @@
 export * from "./types.js";
 export * from "./controller.js";
 export * from "./agent-chat.js";
+export * from "./ndjson.js";

package/dist/patterns/agent-chat/index.js

@@ -4,3 +4,4 @@ export * from "./types.js";
 export * from "./controller.js";
 // Composed conversation surface
 export * from "./agent-chat.js";
+export * from "./ndjson.js";

package/dist/patterns/agent-chat/ndjson.d.ts

@@ -0,0 +1,5 @@
+/** Incremental UTF-8 decoding with a bounded line buffer and early-reader cleanup. */
+export declare function readNdjson<T = unknown>(stream: ReadableStream<Uint8Array>, options?: {
+    maxLineLength?: number;
+    signal?: AbortSignal;
+}): AsyncGenerator<T>;