@oddkin/ai 0.0.0-stage → 1.0.0-beta.0

package/dist/prod/controllers/conversation.js

@@ -0,0 +1,919 @@
+import { signal } from "@oddkin/core/reactive";
+import { can, intersectCapabilities, normalizeApproval, normalizeArtifact, normalizeMessage, normalizePart, normalizeSnapshot, toPublicError } from "../contracts/normalize.js";
+import { createId } from "../internal/ids.js";
+import { APPROVAL_TRANSITIONS, ATTEMPT_TRANSITIONS, TOOL_TRANSITIONS, applyStopOutcome, canTransition, isActive, isTerminal, stopAfterTerminal } from "./transitions.js";
+const SEND_FAILED = {
+  code: "ai.send.failed",
+  message: "The message could not be sent.",
+  retryable: !0
+}, DECISION_FAILED = {
+  code: "ai.approval.failed",
+  message: "The decision could not be submitted.",
+  retryable: !0
+}, STREAM_FAILED = {
+  code: "ai.stream.failed",
+  message: "The response failed.",
+  retryable: !0
+}, MAX_EVENT_IDS = 4096, AFTER_TERMINAL = /* @__PURE__ */ new Set(["snapshot", "usage", "metadata", "approval-resolved", "artifact"]);
+class Sink {
+  target;
+  owner;
+  generation;
+  #open = !0;
+  constructor(target, owner, generation) {
+    this.target = target, this.owner = owner, this.generation = generation;
+  }
+  get active() {
+    return this.#open && this.owner._accepts(this);
+  }
+  /** @internal */
+  get _generation() {
+    return this.generation;
+  }
+  push(event) {
+    this.owner._ingest(this, event);
+  }
+  close() {
+    this.#open && (this.owner._closed(this), this.#open = !1);
+  }
+  /** @internal Called when the controller replaces or disconnects this sink. */
+  _invalidate() {
+    this.#open = !1;
+  }
+}
+class ConversationController {
+  #transport;
+  #id;
+  #diagnose;
+  #state;
+  /** The current immutable snapshot as an Oddkin readable. */
+  state;
+  #policy;
+  #generation = 0;
+  #messages = /* @__PURE__ */ new Map();
+  #children = /* @__PURE__ */ new Map();
+  #preferred = /* @__PURE__ */ new Map();
+  #leaf;
+  #sinks = /* @__PURE__ */ new Map();
+  #replay = /* @__PURE__ */ new Map();
+  #stepStart = /* @__PURE__ */ new Map();
+  #pendingDecisions = /* @__PURE__ */ new Set();
+  #pendingStops = /* @__PURE__ */ new Map();
+  #disposed = !1;
+  constructor(options) {
+    this.#transport = options.transport, this.#id = options.createId ?? createId, this.#diagnose = options.onDiagnostic, this.#policy = options.capabilities, this.#state = signal({
+      ...this.#empty(options.conversationId ?? this.#id("conversation")),
+      capabilities: this.#capabilities()
+    }), this.state = this.#state;
+  }
+  // ---- ExternalSource ----
+  getSnapshot() {
+    return this.#state.peek();
+  }
+  subscribe(listener) {
+    let last = this.#state.peek(), active = !0;
+    const check = () => {
+      if (!active)
+        return;
+      const next = this.#state.peek();
+      next !== last && (last = next, listener());
+    };
+    return this.#listeners.add(check), () => {
+      active = !1, this.#listeners.delete(check);
+    };
+  }
+  #listeners = /* @__PURE__ */ new Set();
+  // ---- Loading ----
+  /**
+   * Replace the conversation with a validated snapshot. A different conversation id isolates
+   * every in-flight stream, stop, and decision of the previous one.
+   */
+  load(raw) {
+    const result = normalizeSnapshot(raw);
+    for (const d of result.diagnostics)
+      this.#report(d);
+    if (!result.ok || !result.value)
+      return result;
+    const snapshot = result.value;
+    this.#isolate(), this.#messages = new Map(snapshot.messages.map((msg) => [msg.id, msg])), this.#rebuildChildren(), this.#leaf = snapshot.activeLeafId && this.#messages.has(snapshot.activeLeafId) ? snapshot.activeLeafId : this.#deepest(void 0);
+    const base = this.#empty(snapshot.conversationId);
+    return this.#commit({
+      ...base,
+      tools: Object.fromEntries((snapshot.tools ?? []).map((t) => [t.toolCallId, t])),
+      approvals: Object.fromEntries((snapshot.approvals ?? []).map((a) => [a.approvalId, a])),
+      artifacts: Object.fromEntries((snapshot.artifacts ?? []).map((a) => [a.artifactId, a])),
+      hasMoreHistory: snapshot.hasMoreHistory ?? !1,
+      history: snapshot.hasMoreHistory ? "idle" : "complete"
+    }), result;
+  }
+  /** Start an empty conversation, isolating the previous one. */
+  reset(conversationId = this.#id("conversation")) {
+    this.#isolate(), this.#messages = /* @__PURE__ */ new Map(), this.#children = /* @__PURE__ */ new Map(), this.#leaf = void 0, this.#commit(this.#empty(conversationId));
+  }
+  /** Replace the application capability policy (narrowing only). */
+  setCapabilities(capabilities) {
+    this.#policy = capabilities, this.#capabilityCache = void 0, this.#commit({ ...this.#state.peek() });
+  }
+  // ---- Sending ----
+  /**
+   * Send a user message and start a new attempt. Resolves when the backend accepted or rejected
+   * the request. A rejected (never accepted) request removes the optimistic messages so the
+   * composer's preserved draft stays the single copy of the content.
+   */
+  async send(input) {
+    const state = this.#state.peek();
+    if (!can(state.capabilities, "send"))
+      return { ok: !1, reason: "unavailable" };
+    if (!input.text.trim() && !input.files?.length)
+      return { ok: !1, reason: "invalid" };
+    if (state.activeAttemptId && isActive(state.attempts[state.activeAttemptId]?.status ?? "completed"))
+      return { ok: !1, reason: "busy" };
+    const prompt = {
+      id: this.#id("msg"),
+      role: "user",
+      ...this.#leaf ? { parentId: this.#leaf } : {},
+      parts: [
+        ...input.files ?? [],
+        ...input.text ? [
+          {
+            type: "text",
+            id: this.#id("part"),
+            text: input.text,
+            state: "done"
+          }
+        ] : []
+      ]
+    };
+    return this.#start(prompt, "new", void 0, !0);
+  }
+  /** Retry a failed, interrupted, or cancelled attempt as a new linked attempt. */
+  retry(attemptId) {
+    return this.#again(attemptId, "retry");
+  }
+  /** Generate an alternative answer; the previous one stays reachable as a branch. */
+  regenerate(messageId) {
+    const message = this.#messages.get(messageId), attemptId = message?.attemptId;
+    return !message || message.role !== "assistant" || !attemptId ? Promise.resolve({ ok: !1, reason: "invalid" }) : this.#again(attemptId, "regenerate");
+  }
+  /** Edit a user message: a new sibling branch and a new attempt; the original is preserved. */
+  async edit(messageId, text) {
+    const state = this.#state.peek(), original = this.#messages.get(messageId);
+    if (!original || original.role !== "user")
+      return { ok: !1, reason: "invalid" };
+    if (!can(state.capabilities, "edit"))
+      return { ok: !1, reason: "unavailable" };
+    if (state.activeAttemptId && isActive(state.attempts[state.activeAttemptId]?.status ?? "completed"))
+      return { ok: !1, reason: "busy" };
+    const prompt = {
+      id: this.#id("msg"),
+      role: "user",
+      ...original.parentId ? { parentId: original.parentId } : {},
+      parts: [
+        ...original.parts.filter((p) => p.type === "file"),
+        { type: "text", id: this.#id("part"), text, state: "done" }
+      ]
+    };
+    return this.#start(prompt, "edit", void 0, !1);
+  }
+  async #again(attemptId, relation) {
+    const state = this.#state.peek(), previous = state.attempts[attemptId];
+    if (!previous)
+      return { ok: !1, reason: "invalid" };
+    if (!can(state.capabilities, relation))
+      return { ok: !1, reason: "unavailable" };
+    if (isActive(previous.status))
+      return { ok: !1, reason: "busy" };
+    const prompt = this.#messages.get(previous.promptId);
+    return prompt ? this.#start(prompt, relation, previous.attemptId, !1) : { ok: !1, reason: "invalid" };
+  }
+  async #start(prompt, relation, parentAttemptId, optimistic) {
+    const state = this.#state.peek(), runId = relation === "new" || relation === "edit" ? this.#id("run") : state.attempts[parentAttemptId ?? ""]?.runId ?? this.#id("run"), attemptId = this.#id("attempt"), messageId = this.#id("msg"), target = { conversationId: state.conversationId, runId, attemptId }, history = this.#path(prompt.parentId), isNewPrompt = !this.#messages.has(prompt.id);
+    isNewPrompt && this.#addMessage(prompt), this.#addMessage({
+      id: messageId,
+      role: "assistant",
+      parentId: prompt.id,
+      parts: [],
+      attemptId
+    }), this.#select(messageId);
+    const attempt = {
+      attemptId,
+      runId,
+      conversationId: state.conversationId,
+      messageId,
+      promptId: prompt.id,
+      relation,
+      ...parentAttemptId ? { parentAttemptId } : {},
+      status: "submitted",
+      connection: "connecting",
+      stop: "none"
+    };
+    this.#commit({
+      ...this.#state.peek(),
+      attempts: { ...this.#state.peek().attempts, [attemptId]: attempt },
+      activeAttemptId: attemptId
+    });
+    const sink = new Sink(target, this, this.#generation);
+    this.#sinks.set(attemptId, sink), this.#replay.set(attemptId, { seq: -1 / 0, ids: /* @__PURE__ */ new Set(), order: [] });
+    const generation = this.#generation;
+    try {
+      return await this.#transport.send({ ...target, relation, parentAttemptId, prompt, messageId, history }, sink), generation !== this.#generation ? { ok: !1, reason: "stale" } : (this.#updateAttempt(attemptId, (a) => a.status === "submitted" ? { ...a, status: "accepted" } : a), { ok: !0, attemptId });
+    } catch (error) {
+      if (generation !== this.#generation)
+        return { ok: !1, reason: "stale" };
+      const publicError = toPublicError(error, SEND_FAILED), current = this.#state.peek().attempts[attemptId];
+      if (sink._invalidate(), current?.status === "submitted" && optimistic && isNewPrompt) {
+        this.#removeMessage(messageId), this.#removeMessage(prompt.id);
+        const { [attemptId]: _removed, ...attempts } = this.#state.peek().attempts;
+        this.#commit({ ...this.#state.peek(), attempts, activeAttemptId: void 0 });
+      } else
+        this.#updateAttempt(attemptId, (a) => ({
+          ...a,
+          status: isTerminal(a.status) ? a.status : "failed",
+          connection: "closed",
+          error: publicError
+        }));
+      return { ok: !1, reason: "rejected", error: publicError };
+    }
+  }
+  // ---- Stop, disconnect, resume ----
+  /**
+   * Request cancellation of the underlying work for one attempt. The attempt stays
+   * `stop: requested` until the backend answers; partial output is kept. A response for an
+   * older request (or another conversation) is ignored.
+   */
+  async stop(attemptId = this.#state.peek().activeAttemptId) {
+    const state = this.#state.peek(), attempt = attemptId ? state.attempts[attemptId] : void 0;
+    if (!attempt || !attemptId)
+      return { ok: !1, reason: "invalid" };
+    if (!can(state.capabilities, "stop") || !this.#transport.stop)
+      return { ok: !1, reason: "unavailable" };
+    if (attempt.stop === "requested")
+      return { ok: !1, reason: "duplicate" };
+    if (!isActive(attempt.status) && attempt.status !== "interrupted")
+      return { ok: !1, reason: "invalid" };
+    const request = (this.#pendingStops.get(attemptId) ?? 0) + 1;
+    this.#pendingStops.set(attemptId, request);
+    const generation = this.#generation;
+    this.#updateAttempt(attemptId, (a) => ({ ...a, stop: "requested" }));
+    const target = { conversationId: attempt.conversationId, runId: attempt.runId, attemptId };
+    let outcome;
+    try {
+      outcome = await this.#transport.stop(target);
+    } catch {
+      outcome = "rejected";
+    }
+    return generation !== this.#generation || this.#pendingStops.get(attemptId) !== request ? (this.#report({
+      code: "ai.stop.stale",
+      path: "",
+      message: "Ignored a stop response for an older request.",
+      attemptId
+    }), { ok: !1, reason: "stale" }) : (this.#pendingStops.delete(attemptId), this.#updateAttempt(attemptId, (a) => {
+      if (a.stop !== "requested")
+        return a;
+      const next = applyStopOutcome(a.status, outcome);
+      return { ...a, ...next };
+    }), outcome === "cancelled" && this.#sinks.get(attemptId)?._invalidate(), outcome === "rejected" ? { ok: !1, reason: "rejected" } : { ok: !0, attemptId });
+  }
+  /**
+   * Close the client stream for an attempt without cancelling the work (unmount, navigation).
+   * The attempt keeps its status; `resume()` can reattach when supported.
+   */
+  disconnect(attemptId = this.#state.peek().activeAttemptId) {
+    const attempt = attemptId ? this.#state.peek().attempts[attemptId] : void 0;
+    return !attempt || !attemptId ? { ok: !1, reason: "invalid" } : (this.#sinks.get(attemptId)?._invalidate(), this.#sinks.delete(attemptId), this.#transport.disconnect?.(this.#target(attempt)), this.#updateAttempt(attemptId, (a) => a.connection === "closed" ? a : { ...a, connection: "disconnected" }), { ok: !0, attemptId });
+  }
+  /** Reattach to an existing attempt. Never starts new work or a new attempt. */
+  async resume(attemptId = this.#state.peek().activeAttemptId) {
+    const state = this.#state.peek(), attempt = attemptId ? state.attempts[attemptId] : void 0;
+    if (!attempt || !attemptId)
+      return { ok: !1, reason: "invalid" };
+    if (!can(state.capabilities, "resume") || !this.#transport.resume)
+      return { ok: !1, reason: "unavailable" };
+    if (isTerminal(attempt.status))
+      return { ok: !1, reason: "invalid" };
+    if (attempt.connection === "open" || attempt.connection === "reconnecting")
+      return { ok: !1, reason: "duplicate" };
+    this.#sinks.get(attemptId)?._invalidate();
+    const sink = new Sink(this.#target(attempt), this, this.#generation);
+    this.#sinks.set(attemptId, sink), this.#updateAttempt(attemptId, (a) => ({ ...a, connection: "reconnecting" }));
+    const generation = this.#generation;
+    try {
+      return await this.#transport.resume(this.#target(attempt), sink), { ok: !0, attemptId };
+    } catch (error) {
+      return generation === this.#generation && this.#sinks.get(attemptId) === sink && (sink._invalidate(), this.#updateAttempt(attemptId, (a) => ({
+        ...a,
+        connection: "closed",
+        status: isTerminal(a.status) ? a.status : "interrupted",
+        error: toPublicError(error, STREAM_FAILED)
+      }))), { ok: !1, reason: "rejected" };
+    }
+  }
+  // ---- Approvals ----
+  /**
+   * Submit a decision for one approval revision. Repeated activation, stale revisions, and
+   * expired proposals are refused without a request. The approval stays `decision-pending`
+   * until the backend acknowledges it; acknowledgment does not mean the action succeeded.
+   */
+  async decide(approvalId, revision, decision, reason) {
+    const state = this.#state.peek(), approval = state.approvals[approvalId];
+    if (!approval)
+      return { ok: !1, reason: "invalid" };
+    if (!can(state.capabilities, "respondToApproval") || !this.#transport.decide)
+      return { ok: !1, reason: "unavailable" };
+    if (approval.revision !== revision)
+      return { ok: !1, reason: "stale" };
+    const key = `${approvalId}:${revision}`;
+    if (this.#pendingDecisions.has(key))
+      return { ok: !1, reason: "duplicate" };
+    if (approval.status !== "requested" && approval.status !== "decision-failed")
+      return {
+        ok: !1,
+        reason: approval.status === "expired" || approval.status === "superseded" ? "stale" : "duplicate"
+      };
+    if (approval.expiresAt && Date.parse(approval.expiresAt) <= Date.now())
+      return this.#setApproval(approvalId, revision, "expired"), { ok: !1, reason: "stale" };
+    this.#pendingDecisions.add(key);
+    const generation = this.#generation;
+    this.#updateApproval(approvalId, (a) => {
+      const { error: _error, ...rest } = a;
+      return { ...rest, status: "decision-pending", decision, ...reason ? { reason } : {} };
+    });
+    const attempt = approval.attemptId ? state.attempts[approval.attemptId] : void 0;
+    try {
+      const outcome = await this.#transport.decide({
+        conversationId: state.conversationId,
+        runId: attempt?.runId ?? "",
+        attemptId: approval.attemptId ?? "",
+        approvalId,
+        toolCallId: approval.toolCallId,
+        revision,
+        decision,
+        reason
+      });
+      if (generation !== this.#generation)
+        return { ok: !1, reason: "stale" };
+      const status = outcome === "accepted" ? decision === "approve" ? "approved" : "rejected" : outcome === "expired" ? "expired" : "superseded";
+      return this.#setApproval(approvalId, revision, status), outcome === "accepted" ? { ok: !0 } : { ok: !1, reason: "stale" };
+    } catch (error) {
+      if (generation !== this.#generation)
+        return { ok: !1, reason: "stale" };
+      const current = this.#state.peek().approvals[approvalId];
+      return current?.revision === revision && current.status === "decision-pending" && this.#updateApproval(approvalId, (a) => ({
+        ...a,
+        status: "decision-failed",
+        error: toPublicError(error, DECISION_FAILED)
+      })), { ok: !1, reason: "rejected", error: toPublicError(error, DECISION_FAILED) };
+    } finally {
+      this.#pendingDecisions.delete(key);
+    }
+  }
+  // ---- Branches and history ----
+  /** Show the branch containing `messageId` (following its most recently selected leaf). */
+  switchBranch(messageId) {
+    return this.#messages.has(messageId) ? can(this.#state.peek().capabilities, "switchBranch") ? (this.#select(messageId), this.#leaf = this.#deepest(messageId), this.#commit({ ...this.#state.peek() }), { ok: !0 }) : { ok: !1, reason: "unavailable" } : { ok: !1, reason: "invalid" };
+  }
+  /** Load earlier messages. Prepended messages never move the active branch. */
+  async loadHistory() {
+    const state = this.#state.peek();
+    if (!can(state.capabilities, "history") || !this.#transport.loadHistory)
+      return { ok: !1, reason: "unavailable" };
+    if (state.history === "loading")
+      return { ok: !1, reason: "duplicate" };
+    if (!state.hasMoreHistory)
+      return { ok: !1, reason: "invalid" };
+    const generation = this.#generation;
+    this.#commit({ ...state, history: "loading" });
+    try {
+      const raw = await this.#transport.loadHistory(state.conversationId, state.messages[0]?.id);
+      if (generation !== this.#generation)
+        return { ok: !1, reason: "stale" };
+      const result = normalizeSnapshot(raw);
+      for (const d of result.diagnostics)
+        this.#report(d);
+      if (!result.ok || !result.value || result.value.conversationId !== state.conversationId)
+        return this.#commit({ ...this.#state.peek(), history: "error" }), { ok: !1, reason: "invalid" };
+      for (const message of result.value.messages)
+        this.#messages.has(message.id) || this.#messages.set(message.id, message);
+      this.#rebuildChildren();
+      const more = result.value.hasMoreHistory ?? !1;
+      return this.#commit({
+        ...this.#state.peek(),
+        history: more ? "idle" : "complete",
+        hasMoreHistory: more
+      }), { ok: !0 };
+    } catch {
+      return generation === this.#generation && this.#commit({ ...this.#state.peek(), history: "error" }), { ok: !1, reason: "rejected" };
+    }
+  }
+  // ---- Feedback ----
+  async submitFeedback(feedback) {
+    const state = this.#state.peek();
+    if (!can(state.capabilities, "feedback") || !this.#transport.submitFeedback)
+      return { ok: !1, reason: "unavailable" };
+    if (state.feedback[feedback.messageId]?.status === "pending")
+      return { ok: !1, reason: "duplicate" };
+    const generation = this.#generation, pending = { ...feedback, status: "pending" };
+    this.#commit({ ...state, feedback: { ...state.feedback, [feedback.messageId]: pending } });
+    let next;
+    try {
+      await this.#transport.submitFeedback(pending), next = { ...feedback, status: "submitted" };
+    } catch (error) {
+      next = {
+        ...feedback,
+        status: "failed",
+        error: toPublicError(error, {
+          code: "ai.feedback.failed",
+          message: "Feedback was not sent."
+        })
+      };
+    }
+    if (generation !== this.#generation)
+      return { ok: !1, reason: "stale" };
+    const now = this.#state.peek();
+    return this.#commit({ ...now, feedback: { ...now.feedback, [feedback.messageId]: next } }), next.status === "submitted" ? { ok: !0 } : { ok: !1, reason: "rejected" };
+  }
+  /** Release client-side work: disconnect open streams (never cancels remote work). */
+  dispose() {
+    if (!this.#disposed) {
+      for (const [attemptId, sink] of this.#sinks) {
+        sink._invalidate();
+        const attempt = this.#state.peek().attempts[attemptId];
+        attempt && !isTerminal(attempt.status) && this.#transport.disconnect?.(this.#target(attempt));
+      }
+      this.#sinks.clear(), this.#listeners.clear(), this.#generation++, this.#disposed = !0;
+    }
+  }
+  // ---- Event ingestion (called by sinks) ----
+  /** @internal */
+  _accepts(sink) {
+    return !this.#disposed && sink._generation === this.#generation && this.#sinks.get(sink.target.attemptId) === sink;
+  }
+  /** @internal */
+  _closed(sink) {
+    if (!this._accepts(sink))
+      return;
+    const attemptId = sink.target.attemptId;
+    this.#sinks.delete(attemptId), this.#updateAttempt(attemptId, (a) => ({
+      ...a,
+      connection: "closed",
+      // A closed connection is not completion: without a terminal event the outcome is unknown.
+      status: a.status === "awaiting-input" || isTerminal(a.status) ? a.status : "interrupted"
+    }));
+  }
+  /** @internal */
+  _ingest(sink, event) {
+    const attemptId = sink.target.attemptId;
+    if (!this._accepts(sink)) {
+      this.#report({
+        code: "ai.event.stale",
+        path: "",
+        message: `Dropped a late "${event?.type}" event.`,
+        attemptId
+      });
+      return;
+    }
+    if (typeof event != "object" || event === null || typeof event.type != "string") {
+      this.#report({
+        code: "ai.event.invalid",
+        path: "",
+        message: "Dropped a malformed event.",
+        attemptId
+      });
+      return;
+    }
+    if (this.#isDuplicate(attemptId, event)) {
+      this.#report({
+        code: "ai.event.duplicate",
+        path: "",
+        message: `Dropped a replayed "${event.type}" event.`,
+        attemptId
+      });
+      return;
+    }
+    const attempt = this.#state.peek().attempts[attemptId];
+    if (attempt) {
+      if (isTerminal(attempt.status) && !AFTER_TERMINAL.has(event.type)) {
+        this.#report({
+          code: "ai.event.afterTerminal",
+          path: "",
+          message: `Dropped "${event.type}" after the attempt ended.`,
+          attemptId
+        });
+        return;
+      }
+      this.#applyEvent(attempt, event);
+    }
+  }
+  #isDuplicate(attemptId, event) {
+    const replay = this.#replay.get(attemptId);
+    if (!replay)
+      return !1;
+    if (typeof event.seq == "number") {
+      if (event.seq <= replay.seq)
+        return !0;
+      replay.seq = event.seq;
+    }
+    if (typeof event.eventId == "string") {
+      if (replay.ids.has(event.eventId))
+        return !0;
+      replay.ids.add(event.eventId), replay.order.push(event.eventId), replay.order.length > MAX_EVENT_IDS && replay.ids.delete(replay.order.shift());
+    }
+    return !1;
+  }
+  #applyEvent(attempt, event) {
+    const id = attempt.attemptId;
+    switch (event.type !== "metadata" && event.type !== "attempt-accepted" && this.#markStreaming(id), event.type) {
+      case "attempt-accepted":
+        this.#updateAttempt(id, (a) => a.status === "submitted" ? { ...a, status: "accepted" } : a);
+        return;
+      case "message-start":
+        return;
+      case "message-reset":
+        this.#stepStart.delete(id), this.#updateMessage(attempt.messageId, (msg) => ({ ...msg, parts: [] }));
+        return;
+      case "step-start":
+        this.#stepStart.set(id, this.#messages.get(attempt.messageId)?.parts.length ?? 0);
+        return;
+      case "step-reset": {
+        const start = this.#stepStart.get(id) ?? 0;
+        this.#updateMessage(attempt.messageId, (msg) => ({
+          ...msg,
+          parts: msg.parts.slice(0, start)
+        }));
+        return;
+      }
+      case "text-start":
+        this.#upsertPart(attempt.messageId, event.partId, () => ({
+          type: event.kind ?? "text",
+          id: event.partId,
+          text: "",
+          state: "streaming"
+        }));
+        return;
+      case "text-delta":
+        this.#upsertPart(attempt.messageId, event.partId, () => ({ type: "text", id: event.partId, text: "", state: "streaming" }), (part) => part.type === "text" || part.type === "reasoning" ? { ...part, text: part.text + event.delta } : part);
+        return;
+      case "text-end":
+        this.#updatePart(attempt.messageId, event.partId, (part) => part.type === "text" || part.type === "reasoning" ? { ...part, state: "done" } : part);
+        return;
+      case "part": {
+        const { part, diagnostics } = normalizePart(event.part, `/${attempt.messageId}`);
+        for (const d of diagnostics)
+          this.#report({ ...d, attemptId: id });
+        this.#upsertPart(attempt.messageId, part.id, () => part, () => part);
+        return;
+      }
+      case "tool-input-start":
+        this.#upsertTool(event.toolCallId, () => ({
+          toolCallId: event.toolCallId,
+          attemptId: id,
+          toolName: event.toolName,
+          ...event.title ? { title: event.title } : {},
+          status: "input-streaming",
+          inputText: ""
+        })), this.#upsertPart(attempt.messageId, `tool-${event.toolCallId}`, () => ({
+          type: "tool-call",
+          id: `tool-${event.toolCallId}`,
+          toolCallId: event.toolCallId
+        }));
+        return;
+      case "tool-input-delta":
+        this.#updateTool(event.toolCallId, (t) => t.status === "input-streaming" ? { ...t, inputText: (t.inputText ?? "") + event.delta } : t);
+        return;
+      case "tool-input-available":
+        this.#ensureTool(attempt, event.toolCallId), this.#moveTool(event.toolCallId, "input-available", (t) => ({ ...t, input: event.input }));
+        return;
+      case "tool-executing":
+        this.#moveTool(event.toolCallId, "executing");
+        return;
+      case "tool-output":
+        this.#moveTool(event.toolCallId, "output-available", (t) => ({
+          ...t,
+          output: event.output
+        }));
+        return;
+      case "tool-error":
+        this.#moveTool(event.toolCallId, "output-error", (t) => ({ ...t, error: event.error }));
+        return;
+      case "tool-denied":
+        this.#moveTool(event.toolCallId, "denied");
+        return;
+      case "approval-request":
+        this.#requestApproval(attempt, event.approval);
+        return;
+      case "approval-resolved":
+        this.#setApproval(event.approvalId, event.revision, event.status);
+        return;
+      case "artifact": {
+        const result = normalizeArtifact(event.artifact);
+        for (const d of result.diagnostics)
+          this.#report({ ...d, attemptId: id });
+        if (!result.value)
+          return;
+        const artifact = result.value, now = this.#state.peek();
+        this.#commit({ ...now, artifacts: { ...now.artifacts, [artifact.artifactId]: artifact } }), this.#upsertPart(attempt.messageId, `artifact-${artifact.artifactId}`, () => ({
+          type: "artifact",
+          id: `artifact-${artifact.artifactId}`,
+          artifactId: artifact.artifactId,
+          revisionId: artifact.currentRevisionId
+        }), (part) => part.type === "artifact" ? { ...part, revisionId: artifact.currentRevisionId } : part);
+        return;
+      }
+      case "usage":
+        this.#updateAttempt(id, (a) => ({ ...a, usage: event.usage }));
+        return;
+      case "snapshot": {
+        const result = normalizeMessage(event.message);
+        for (const d of result.diagnostics)
+          this.#report({ ...d, attemptId: id });
+        if (!result.value || result.value.id !== attempt.messageId) {
+          this.#report({
+            code: "ai.snapshot.scope",
+            path: "",
+            message: "Ignored a snapshot for another message.",
+            attemptId: id
+          });
+          return;
+        }
+        const replacement = result.value;
+        this.#updateMessage(attempt.messageId, (msg) => ({
+          ...replacement,
+          ...msg.parentId ? { parentId: msg.parentId } : {},
+          attemptId: id
+        }));
+        return;
+      }
+      case "finish":
+        this.#terminate(id, event.status ?? "completed");
+        return;
+      case "abort":
+        this.#terminate(id, "cancelled");
+        return;
+      case "error":
+        this.#terminate(id, "failed", event.error);
+        return;
+      case "metadata":
+        this.#report({
+          code: "ai.event.metadata",
+          path: "",
+          message: "Provider metadata (not rendered).",
+          attemptId: id
+        });
+        return;
+      default:
+        this.#report({
+          code: "ai.event.unknown",
+          path: "",
+          message: `Ignored unknown event "${event.type}".`,
+          attemptId: id
+        });
+    }
+  }
+  #markStreaming(attemptId) {
+    this.#updateAttempt(attemptId, (a) => {
+      const connection = a.connection === "connecting" || a.connection === "reconnecting" ? "open" : a.connection, status = a.status === "submitted" || a.status === "accepted" || a.status === "interrupted" ? "streaming" : a.status;
+      return connection === a.connection && status === a.status ? a : { ...a, connection, status };
+    });
+  }
+  #terminate(attemptId, status, error) {
+    this.#updateAttempt(attemptId, (a) => isTerminal(a.status) || !canTransition(ATTEMPT_TRANSITIONS, a.status, status) ? a : {
+      ...a,
+      status,
+      stop: isTerminal(status) ? stopAfterTerminal(a.stop, status) : a.stop,
+      ...error ? { error } : {}
+    });
+    const attempt = this.#state.peek().attempts[attemptId];
+    if (attempt && (this.#updateMessage(attempt.messageId, (msg) => msg.parts.some((p) => (p.type === "text" || p.type === "reasoning") && p.state === "streaming") ? {
+      ...msg,
+      parts: msg.parts.map((p) => (p.type === "text" || p.type === "reasoning") && p.state === "streaming" ? { ...p, state: "done" } : p)
+    } : msg), status === "cancelled" || status === "failed")) {
+      const now = this.#state.peek();
+      let changed = !1;
+      const tools = { ...now.tools };
+      for (const tool of Object.values(now.tools))
+        tool.attemptId === attemptId && (tool.status === "input-streaming" || tool.status === "executing") && (tools[tool.toolCallId] = { ...tool, status: "cancelled" }, changed = !0);
+      changed && this.#commit({ ...now, tools });
+    }
+  }
+  #requestApproval(attempt, raw) {
+    const result = normalizeApproval({ ...raw, attemptId: raw.attemptId ?? attempt.attemptId });
+    for (const d of result.diagnostics)
+      this.#report({ ...d, attemptId: attempt.attemptId });
+    if (!result.value)
+      return;
+    const incoming = result.value, now = this.#state.peek(), existing = now.approvals[incoming.approvalId];
+    if (existing && existing.revision >= incoming.revision) {
+      this.#report({
+        code: "ai.approval.stale",
+        path: "",
+        message: "Ignored an older approval revision.",
+        attemptId: attempt.attemptId
+      });
+      return;
+    }
+    const record = { ...incoming, status: "requested" };
+    this.#commit({ ...now, approvals: { ...now.approvals, [record.approvalId]: record } }), record.toolCallId ? (this.#ensureTool(attempt, record.toolCallId), this.#moveTool(record.toolCallId, "awaiting-approval", (t) => ({
+      ...t,
+      approvalId: record.approvalId
+    }))) : this.#upsertPart(attempt.messageId, `approval-${record.approvalId}`, () => ({
+      type: "approval",
+      id: `approval-${record.approvalId}`,
+      approvalId: record.approvalId
+    }));
+  }
+  // ---- Record helpers ----
+  #ensureTool(attempt, toolCallId) {
+    this.#state.peek().tools[toolCallId] || (this.#upsertTool(toolCallId, () => ({
+      toolCallId,
+      attemptId: attempt.attemptId,
+      toolName: "tool",
+      status: "input-available"
+    })), this.#upsertPart(attempt.messageId, `tool-${toolCallId}`, () => ({
+      type: "tool-call",
+      id: `tool-${toolCallId}`,
+      toolCallId
+    })));
+  }
+  #upsertTool(toolCallId, create) {
+    const now = this.#state.peek();
+    now.tools[toolCallId] || this.#commit({ ...now, tools: { ...now.tools, [toolCallId]: create() } });
+  }
+  #updateTool(toolCallId, update) {
+    const now = this.#state.peek(), tool = now.tools[toolCallId];
+    if (!tool)
+      return;
+    const next = update(tool);
+    next !== tool && this.#commit({ ...now, tools: { ...now.tools, [toolCallId]: next } });
+  }
+  #moveTool(toolCallId, status, update) {
+    this.#updateTool(toolCallId, (t) => canTransition(TOOL_TRANSITIONS, t.status, status) ? { ...update ? update(t) : t, status } : (this.#report({
+      code: "ai.tool.transition",
+      path: "",
+      message: `Ignored ${t.status} \u2192 ${status} for ${toolCallId}.`
+    }), t));
+  }
+  #updateApproval(approvalId, update) {
+    const now = this.#state.peek(), approval = now.approvals[approvalId];
+    approval && this.#commit({ ...now, approvals: { ...now.approvals, [approvalId]: update(approval) } });
+  }
+  #setApproval(approvalId, revision, status) {
+    this.#updateApproval(approvalId, (a) => a.revision !== revision || !canTransition(APPROVAL_TRANSITIONS, a.status, status) ? a : { ...a, status });
+  }
+  #updateAttempt(attemptId, update) {
+    const now = this.#state.peek(), attempt = now.attempts[attemptId];
+    if (!attempt)
+      return;
+    const next = update(attempt);
+    next !== attempt && this.#commit({ ...now, attempts: { ...now.attempts, [attemptId]: next } });
+  }
+  #updateMessage(messageId, update) {
+    const message = this.#messages.get(messageId);
+    if (!message)
+      return;
+    const next = update(message);
+    next !== message && (this.#messages.set(messageId, next), this.#commit({ ...this.#state.peek() }));
+  }
+  #upsertPart(messageId, partId, create, update) {
+    this.#updateMessage(messageId, (msg) => {
+      const index = msg.parts.findIndex((p) => p.id === partId);
+      if (index === -1)
+        return { ...msg, parts: [...msg.parts, update ? update(create()) : create()] };
+      if (!update)
+        return msg;
+      const current = msg.parts[index], next = update(current);
+      if (next === current)
+        return msg;
+      const parts = msg.parts.slice();
+      return parts[index] = next, { ...msg, parts };
+    });
+  }
+  #updatePart(messageId, partId, update) {
+    this.#updateMessage(messageId, (msg) => {
+      const index = msg.parts.findIndex((p) => p.id === partId);
+      if (index === -1)
+        return msg;
+      const parts = msg.parts.slice();
+      return parts[index] = update(msg.parts[index]), { ...msg, parts };
+    });
+  }
+  #addMessage(message) {
+    this.#messages.set(message.id, message);
+    const key = this.#parentKey(message);
+    this.#children.set(key, [...this.#children.get(key) ?? [], message.id]);
+  }
+  /** Parent key in the branch tree; a parent that is not loaded yet (older history) is the root. */
+  #parentKey(message) {
+    return message.parentId && this.#messages.has(message.parentId) ? message.parentId : "";
+  }
+  #removeMessage(messageId) {
+    const message = this.#messages.get(messageId);
+    if (!message)
+      return;
+    this.#messages.delete(messageId);
+    const key = this.#parentKey(message);
+    this.#children.set(key, (this.#children.get(key) ?? []).filter((id) => id !== messageId)), this.#preferred.get(key) === messageId && this.#preferred.delete(key), this.#leaf === messageId && (this.#leaf = message.parentId);
+  }
+  #rebuildChildren() {
+    this.#children = /* @__PURE__ */ new Map();
+    for (const message of this.#messages.values()) {
+      const key = this.#parentKey(message);
+      this.#children.set(key, [...this.#children.get(key) ?? [], message.id]);
+    }
+  }
+  /** Remember `messageId` as the selected child of its parent, up to the root. */
+  #select(messageId) {
+    let current = this.#messages.get(messageId);
+    for (; current; )
+      this.#preferred.set(this.#parentKey(current), current.id), current = current.parentId ? this.#messages.get(current.parentId) : void 0;
+    this.#leaf = messageId;
+  }
+  /** Deepest descendant following preferred (else latest) children. */
+  #deepest(from) {
+    let current = from;
+    for (; ; ) {
+      const children = this.#children.get(current ?? "") ?? [];
+      if (!children.length)
+        return current;
+      current = this.#preferred.get(current ?? "") ?? children[children.length - 1];
+    }
+  }
+  #path(leaf) {
+    const path = [];
+    let current = leaf ? this.#messages.get(leaf) : void 0;
+    for (; current; )
+      path.push(current), current = current.parentId ? this.#messages.get(current.parentId) : void 0;
+    return path.reverse();
+  }
+  #branches(path) {
+    const out = {};
+    for (const message of path) {
+      const siblings = (this.#children.get(this.#parentKey(message)) ?? []).filter((id) => this.#messages.get(id)?.role === message.role);
+      if (siblings.length < 2)
+        continue;
+      const index = siblings.indexOf(message.id);
+      out[message.id] = {
+        index: index + 1,
+        count: siblings.length,
+        previousId: siblings[index - 1],
+        nextId: siblings[index + 1]
+      };
+    }
+    return out;
+  }
+  #target(attempt) {
+    return {
+      conversationId: attempt.conversationId,
+      runId: attempt.runId,
+      attemptId: attempt.attemptId
+    };
+  }
+  #isolate() {
+    this.#generation++;
+    for (const sink of this.#sinks.values())
+      sink._invalidate();
+    this.#sinks.clear(), this.#replay.clear(), this.#stepStart.clear(), this.#pendingDecisions.clear(), this.#pendingStops.clear(), this.#preferred.clear();
+  }
+  #empty(conversationId) {
+    return {
+      conversationId,
+      revision: 0,
+      messages: [],
+      tools: {},
+      approvals: {},
+      artifacts: {},
+      attempts: {},
+      branches: {},
+      activeAttemptId: void 0,
+      capabilities: {},
+      history: "complete",
+      hasMoreHistory: !1,
+      feedback: {}
+    };
+  }
+  #capabilities() {
+    if (!this.#capabilityCache) {
+      const supported = this.#transport.capabilities;
+      this.#capabilityCache = this.#policy ? intersectCapabilities(supported, this.#policy) : supported;
+    }
+    return this.#capabilityCache;
+  }
+  #capabilityCache;
+  #commit(next) {
+    const previous = this.#state.peek(), messages = this.#path(this.#leaf);
+    this.#state.value = {
+      ...next,
+      revision: previous.revision + 1,
+      messages,
+      branches: this.#branches(messages),
+      capabilities: this.#capabilities()
+    };
+    for (const listener of [...this.#listeners])
+      listener();
+  }
+  #report(diagnostic) {
+    this.#diagnose?.(diagnostic);
+  }
+}
+export {
+  ConversationController
+};