@godspeedai/cognate-ag-ui 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @godspeedai/cognate-ag-ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+AG-UI 1.0.0 interoperability adapter (spec §24, §31.8, §32; ADR-0008). An
+optional boundary, not the internal event model: native Cognate execution
+and UI work unchanged if this package is removed (spec §40.H).
+
+- `createProjector` folds a run's durable event stream into schema-valid
+  AG-UI events (bracketed text messages, tool calls, state snapshots/deltas,
+  continuation CUSTOM events, RUN_FINISHED/RUN_ERROR).
+- `createAgUiHandler` is an HTTP endpoint: POST `RunAgentInput` → SSE stream.
+  Actions (start, resolve a continuation, cancel) go through
+  `RuntimeService` with the transport-authenticated caller. A valid
+  `forwardedProps.cognate.cursor` resumes with `STATE_SNAPSHOT` + newer
+  events; an unknown/expired cursor triggers a full resync
+  (`RUN_STARTED`, `MESSAGES_SNAPSHOT`, `STATE_SNAPSHOT`, …). Disconnecting
+  never cancels the durable run.
+
+## Compatibility matrix (`matrix`, `ignoredFrameworkEvents`)
+
+All 31 AG-UI 1.0.0 `EventType` values are covered, one row each:
+
+- **Supported (outbound):** `RUN_STARTED`, `RUN_FINISHED`, `RUN_ERROR`,
+  `TEXT_MESSAGE_*` (not `_CHUNK`), `TOOL_CALL_*` (not `_CHUNK`),
+  `STATE_SNAPSHOT`, `STATE_DELTA`, `MESSAGES_SNAPSHOT`, `CUSTOM`.
+- **Unsupported (none):** the `_CHUNK` shorthands, `ACTIVITY_*`, `RAW`,
+  `STEP_*`, `REASONING_*`, `SUBAGENT_*` — Cognate has no matching concept
+  yet; each row's `note` says why.
+- `TOOL_CALL_ARGS` carries the recorded invocation input (`run.invocation`
+  payload `input`; `{}` after that payload is erased).
+
+`ignoredFrameworkEvents` lists Cognate event types deliberately not
+projected: `run.step.completed`, `run.resumed`, `run.wait.closed`,
+`run.recall` (replay/determinism bookkeeping). Artifacts are projected as
+`CUSTOM` `cognate.artifact` events (AG-UI 1.0.0 has no artifact event).
+
+## Continuation mapping
+
+A `frontend_capability` continuation (or `type: "frontend:<capability>"`,
+runtime-api's convention) becomes `TOOL_CALL_START/ARGS/END` with
+`toolCallId` = the continuation id. A `human_approval` continuation becomes
+`CUSTOM "cognate.continuation"`. Any other kind (e.g. `oauth_callback`) has
+no faithful AG-UI representation and becomes
+`CUSTOM "cognate.unsupported_interaction"`, and the run's `RUN_FINISHED`
+reports `status: "waiting_unsupported"` instead of `"waiting"`.

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@godspeedai/cognate-ag-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "AG-UI projection and interoperability adapter: outbound event mapping, inbound actions through native authorization, SSE endpoint with reconnect (spec §24). Internal events are never AG-UI aliases.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GodSpeedAI/Cognate.git",
+    "directory": "packages/ag-ui"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@ag-ui/core": "1.0.0",
+    "@ag-ui/encoder": "1.0.0",
+    "@godspeedai/cognate-client": "^0.1.1",
+    "@godspeedai/cognate-events": "^0.1.1",
+    "@godspeedai/cognate-runtime-api": "^0.1.1"
+  },
+  "devDependencies": {
+    "@ag-ui/client": "1.0.0",
+    "@godspeedai/cognate-runtime-bun": "workspace:*"
+  }
+}

package/src/index.ts

@@ -0,0 +1,623 @@
+// CG-AGUI (spec §24, §31.8, §32; ADR-0008): AG-UI 1.0.0 interoperability adapter.
+// Outbound: durable Cognate events -> schema-valid AG-UI events (never the reverse: AG-UI never becomes
+// the internal event model). Inbound: AG-UI actions pass through RuntimeService with the transport's
+// authenticated caller, never trusting the wire body for identity (spec §32).
+import { EventType } from "@ag-ui/core";
+import { RunAgentInputSchema } from "@ag-ui/core/schemas";
+import { EventEncoder } from "@ag-ui/encoder";
+import type { Json, StoredEvent } from "@godspeedai/cognate-events";
+import { FRONTEND_CAPABILITY } from "@godspeedai/cognate-runtime-api";
+import type { Caller, ContinuationView, RuntimeService } from "@godspeedai/cognate-runtime-api";
+import { ServiceError } from "@godspeedai/cognate-runtime-api";
+
+/** One row per AG-UI 1.0.0 EventType (all 31): how Cognate produces or handles it (spec §24 compatibility matrix). */
+export interface MatrixRow {
+  readonly agUiType: string;
+  readonly direction: "outbound" | "inbound" | "none";
+  readonly supported: boolean;
+  /** Framework source (e.g. `run.started`, `message.delta`) or the reason it is unsupported. */
+  readonly note: string;
+}
+
+const row = (agUiType: string, direction: MatrixRow["direction"], supported: boolean, note: string): MatrixRow => ({ agUiType, direction, supported, note });
+
+export const matrix: readonly MatrixRow[] = [
+  row(EventType.RUN_STARTED, "outbound", true, "run.started"),
+  row(EventType.RUN_FINISHED, "outbound", true, "run.completed, or run.waiting once the run stabilizes (result.status: completed | waiting | waiting_unsupported)"),
+  row(EventType.RUN_ERROR, "outbound", true, "run.failed, run.cancelled (code: cancelled), or a ServiceError from an inbound action (code: the ServiceErrorCode)"),
+  row(EventType.TEXT_MESSAGE_START, "outbound", true, "message.delta (opens a streamed assistant message; emitted once per open message)"),
+  row(EventType.TEXT_MESSAGE_CONTENT, "outbound", true, "message.delta"),
+  row(EventType.TEXT_MESSAGE_END, "outbound", true, "message.delta (closed before any non-delta projection)"),
+  row(EventType.TEXT_MESSAGE_CHUNK, "none", false, "Cognate always emits explicit start/content/end; the chunk shorthand is unused"),
+  row(EventType.TOOL_CALL_START, "outbound", true, "run.invocation, model invocation progress, or a frontend capability continuation"),
+  row(EventType.TOOL_CALL_ARGS, "outbound", true, "run.invocation input, streamed model arguments, or continuation payload"),
+  row(EventType.TOOL_CALL_END, "outbound", true, "run.invocation, model invocation progress, or frontend capability continuation"),
+  row(EventType.TOOL_CALL_CHUNK, "none", false, "the chunk shorthand is unused"),
+  row(EventType.TOOL_CALL_RESULT, "outbound", true, "run.invocation result or failure, JSON-stringified"),
+  row(EventType.STATE_SNAPSHOT, "outbound", true, "state.changed{snapshot}, or a folded snapshot synthesized on reconnect/resync"),
+  row(EventType.STATE_DELTA, "outbound", true, "state.changed{patch} (RFC 6902 patch passed through verbatim)"),
+  row(EventType.MESSAGES_SNAPSHOT, "outbound", true, "synthesized on a full resync (unknown/expired cursor) from folded message.delta history"),
+  row(EventType.ACTIVITY_SNAPSHOT, "none", false, "Cognate has no activity-log concept distinct from state and messages"),
+  row(EventType.ACTIVITY_DELTA, "none", false, "Cognate has no activity-log concept distinct from state and messages"),
+  row(EventType.RAW, "none", false, "the adapter does not pass through foreign wire events verbatim"),
+  row(EventType.CUSTOM, "outbound", true, "human continuations (cognate.continuation), artifacts (cognate.artifact), and continuation kinds with no faithful AG-UI representation (cognate.unsupported_interaction)"),
+  row(EventType.STEP_STARTED, "none", false, "ctx.step is internal replay-determinism bookkeeping (run.step.completed), not a user-facing span"),
+  row(EventType.STEP_FINISHED, "none", false, "ctx.step is internal replay-determinism bookkeeping, not a user-facing span"),
+  row(EventType.REASONING_START, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_MESSAGE_START, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_MESSAGE_CONTENT, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_MESSAGE_END, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_MESSAGE_CHUNK, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_END, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.REASONING_ENCRYPTED_VALUE, "none", false, "Cognate has no reasoning/thinking channel distinct from message.delta"),
+  row(EventType.SUBAGENT_STARTED, "none", false, "Cognate runs are flat; no nested subagent invocation is surfaced yet"),
+  row(EventType.SUBAGENT_FINISHED, "none", false, "Cognate runs are flat; no nested subagent invocation is surfaced yet"),
+  row(EventType.SUBAGENT_ERROR, "none", false, "Cognate runs are flat; no nested subagent invocation is surfaced yet"),
+];
+
+/** Framework event types deliberately not projected to AG-UI (explicitly ignored, never reinterpreted). */
+export const ignoredFrameworkEvents: readonly string[] = [
+  "run.step.completed",
+  "run.resumed",
+  "run.wait.closed",
+  "run.recall",
+  "run.remote_offers",
+];
+
+/** AG-UI event as a plain object; `rawEvent.cognate` carries `{ eventId, position, runId }` of the durable source. */
+export type AgUiEvent = { readonly type: string; readonly [key: string]: unknown };
+
+const SUPPORTED_CONTINUATION_KINDS = new Set<string>(["human_approval", FRONTEND_CAPABILITY]);
+
+function conditionKindOf(view: ContinuationView | undefined): string | undefined {
+  const c = view?.condition;
+  if (c && typeof c === "object" && !Array.isArray(c) && typeof (c as { kind?: unknown }).kind === "string") return (c as { kind: string }).kind;
+  return undefined;
+}
+
+function payloadField<T>(event: StoredEvent, key: string): T | undefined {
+  const p = event.payload;
+  return p && typeof p === "object" && !Array.isArray(p) && key in p ? ((p as { [k: string]: Json })[key] as unknown as T) : undefined;
+}
+
+function metaField<T>(event: StoredEvent, key: string): T | undefined {
+  const m = event.metadata;
+  return m && key in m ? ((m as { [k: string]: Json })[key] as unknown as T) : undefined;
+}
+
+// ── JSON Patch (RFC 6902), minimal subset needed to fold state.changed history into a snapshot ─────────
+
+type PatchOp = { readonly op: string; readonly path: string; readonly value?: Json; readonly from?: string };
+
+function pointer(path: string): readonly string[] {
+  if (path === "") return [];
+  return path
+    .slice(1)
+    .split("/")
+    .map((s) => s.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+function clone(v: Json): Json {
+  return v === null ? null : (JSON.parse(JSON.stringify(v)) as Json);
+}
+
+function setAt(doc: Json, path: readonly string[], value: Json, mode: "add" | "replace" | "remove"): Json {
+  if (path.length === 0) return mode === "remove" ? null : value;
+  const result = clone(doc ?? {});
+  let cursor: Json = result;
+  for (let i = 0; i < path.length - 1; i++) {
+    const seg = path[i]!;
+    if (Array.isArray(cursor)) cursor = cursor[seg === "-" ? cursor.length - 1 : Number(seg)]!;
+    else if (cursor && typeof cursor === "object") cursor = (cursor as { [k: string]: Json })[seg]!;
+  }
+  const last = path[path.length - 1]!;
+  if (Array.isArray(cursor)) {
+    const index = last === "-" ? cursor.length : Number(last);
+    if (mode === "remove") cursor.splice(index, 1);
+    else if (mode === "add") cursor.splice(index, 0, value);
+    else cursor[index] = value;
+  } else if (cursor && typeof cursor === "object") {
+    const record = cursor as { [k: string]: Json };
+    if (mode === "remove") delete record[last];
+    else record[last] = value;
+  }
+  return result;
+}
+
+function applyPatch(doc: Json, ops: readonly PatchOp[]): Json {
+  let result = doc;
+  for (const op of ops) {
+    if (op.op === "add") result = setAt(result, pointer(op.path), op.value ?? null, "add");
+    else if (op.op === "replace") result = setAt(result, pointer(op.path), op.value ?? null, "replace");
+    else if (op.op === "remove") result = setAt(result, pointer(op.path), null, "remove");
+    else if (op.op === "move" && op.from) {
+      result = setAt(result, pointer(op.path), null, "remove");
+    }
+  }
+  return result;
+}
+
+/**
+ * Stateful per-run projector: feed durable events in order, get schema-valid AG-UI events.
+ * Text deltas are bracketed by TEXT_MESSAGE_START/END; invocations become TOOL_CALL_*; state becomes
+ * STATE_SNAPSHOT / STATE_DELTA; frontend-capability continuations become client tool calls.
+ */
+export function createProjector(options: { readonly threadId: string; readonly runId: string; readonly continuation?: (id: string) => ContinuationView | undefined }): {
+  push(event: StoredEvent): readonly AgUiEvent[];
+  /** Yields MESSAGES_SNAPSHOT + STATE_SNAPSHOT from everything folded via `push` so far. */
+  snapshot(): readonly AgUiEvent[];
+  /** Yields only STATE_SNAPSHOT from the current fold (used to anchor a cursor-resumed stream). */
+  stateOnly(): readonly AgUiEvent[];
+} {
+  let openMessageId: string | undefined;
+  const openToolCalls = new Set<string>();
+  const knownToolCalls = new Set<string>();
+  let text = "";
+  let state: Json = null;
+
+  const cognateOf = (e: StoredEvent) => ({ eventId: e.eventId, position: e.position, runId: e.runId });
+
+  function closeText(out: AgUiEvent[], cognate: unknown): void {
+    if (openMessageId) {
+      out.push({ type: "TEXT_MESSAGE_END", messageId: openMessageId, rawEvent: { cognate } });
+      openMessageId = undefined;
+    }
+  }
+
+  function updateFold(event: StoredEvent): void {
+    if (event.eventType === "message.delta" || (event.eventType === "run.invocation.progress" && metaField<string>(event, "capability") === "model.generate" && payloadField<string>(event, "type") === "text")) {
+      const t = payloadField<string>(event, "text");
+      if (typeof t === "string") text += t;
+    } else if (event.eventType === "state.changed") {
+      const snapshot = payloadField<Json>(event, "snapshot");
+      if (snapshot !== undefined) state = snapshot;
+      else {
+        const patch = payloadField<readonly PatchOp[]>(event, "patch");
+        if (patch) state = applyPatch(state, patch);
+      }
+    }
+  }
+
+  function project(event: StoredEvent): AgUiEvent[] {
+    const out: AgUiEvent[] = [];
+    const cognate = cognateOf(event);
+    switch (event.eventType) {
+      case "run.started":
+        out.push({ type: "RUN_STARTED", threadId: options.threadId, runId: options.runId, rawEvent: { cognate } });
+        break;
+      case "message.delta": {
+        const t = payloadField<string>(event, "text");
+        if (typeof t !== "string") break;
+        if (!openMessageId) {
+          openMessageId = event.eventId;
+          out.push({ type: "TEXT_MESSAGE_START", messageId: openMessageId, role: "assistant", rawEvent: { cognate } });
+        }
+        out.push({ type: "TEXT_MESSAGE_CONTENT", messageId: openMessageId, delta: t, rawEvent: { cognate } });
+        break;
+      }
+      case "state.changed": {
+        closeText(out, cognate);
+        const snapshot = payloadField<Json>(event, "snapshot");
+        if (snapshot !== undefined) out.push({ type: "STATE_SNAPSHOT", snapshot, rawEvent: { cognate } });
+        else {
+          const patch = payloadField<readonly PatchOp[]>(event, "patch");
+          if (patch) out.push({ type: "STATE_DELTA", delta: patch, rawEvent: { cognate } });
+        }
+        break;
+      }
+      case "run.artifact": {
+        // AG-UI 1.0.0 has no artifact event; project explicitly as CUSTOM rather than dropping it.
+        closeText(out, cognate);
+        out.push({ type: "CUSTOM", name: "cognate.artifact", value: { artifactId: metaField<string>(event, "artifactId") ?? payloadField<string>(event, "artifactId") ?? null }, rawEvent: { cognate } });
+        break;
+      }
+      case "run.invocation.progress": {
+        if (metaField<string>(event, "capability") !== "model.generate") break;
+        const kind = payloadField<string>(event, "type");
+        if (kind === "text") {
+          const delta = payloadField<string>(event, "text");
+          if (typeof delta !== "string") break;
+          if (!openMessageId) {
+            openMessageId = event.eventId;
+            out.push({ type: "TEXT_MESSAGE_START", messageId: openMessageId, role: "assistant", rawEvent: { cognate } });
+          }
+          out.push({ type: "TEXT_MESSAGE_CONTENT", messageId: openMessageId, delta, rawEvent: { cognate } });
+          break;
+        }
+        const callId = payloadField<string>(event, "callId");
+        if (!callId) break;
+        if (kind === "tool_call_start") {
+          const name = payloadField<string>(event, "name");
+          if (!name) break;
+          closeText(out, cognate);
+          openToolCalls.add(callId);
+          knownToolCalls.add(callId);
+          out.push({ type: "TOOL_CALL_START", toolCallId: callId, toolCallName: name, rawEvent: { cognate } });
+        } else if (kind === "tool_call_args" && openToolCalls.has(callId)) {
+          const delta = payloadField<string>(event, "delta");
+          if (typeof delta === "string") out.push({ type: "TOOL_CALL_ARGS", toolCallId: callId, delta, rawEvent: { cognate } });
+        } else if (kind === "tool_call_end" && openToolCalls.delete(callId)) {
+          out.push({ type: "TOOL_CALL_END", toolCallId: callId, rawEvent: { cognate } });
+        }
+        break;
+      }
+      case "run.invocation": {
+        if (metaField<string>(event, "capability") === "model.generate") break;
+        closeText(out, cognate);
+        const stepId = metaField<string>(event, "stepId") ?? event.eventId;
+        const capability = metaField<string>(event, "capability") ?? "capability";
+        const ok = metaField<boolean>(event, "ok") === true;
+        out.push({ type: "TOOL_CALL_START", toolCallId: stepId, toolCallName: capability, rawEvent: { cognate } });
+        out.push({ type: "TOOL_CALL_ARGS", toolCallId: stepId, delta: JSON.stringify(payloadField<Json>(event, "input") ?? {}), rawEvent: { cognate } });
+        out.push({ type: "TOOL_CALL_END", toolCallId: stepId, rawEvent: { cognate } });
+        const content = JSON.stringify(ok ? (payloadField<Json>(event, "result") ?? null) : (payloadField<Json>(event, "failure") ?? null));
+        out.push({ type: "TOOL_CALL_RESULT", messageId: `${stepId}:result`, toolCallId: stepId, content, role: "tool", rawEvent: { cognate } });
+        break;
+      }
+      case "run.waiting": {
+        closeText(out, cognate);
+        const continuationId = metaField<string>(event, "continuationId") ?? "";
+        const waitType = payloadField<string>(event, "type") ?? "";
+        const view = options.continuation?.(continuationId);
+        if (waitType.startsWith("frontend:") || waitType.startsWith("remote:")) {
+          const remoteId = metaField<string>(event, "stepId")?.match(/^wait:remote:(.+)$/)?.[1];
+          const toolCallId = remoteId ?? continuationId;
+          const capability = waitType.slice(waitType.indexOf(":") + 1);
+          if (!knownToolCalls.has(toolCallId)) {
+            out.push({ type: "TOOL_CALL_START", toolCallId, toolCallName: capability, rawEvent: { cognate } });
+            out.push({ type: "TOOL_CALL_ARGS", toolCallId, delta: JSON.stringify(view?.payload ?? {}), rawEvent: { cognate } });
+            out.push({ type: "TOOL_CALL_END", toolCallId, rawEvent: { cognate } });
+          } else if (openToolCalls.delete(toolCallId)) {
+            out.push({ type: "TOOL_CALL_END", toolCallId, rawEvent: { cognate } });
+          }
+        } else {
+          const kind = conditionKindOf(view);
+          const supported = kind !== undefined && SUPPORTED_CONTINUATION_KINDS.has(kind);
+          // AG-UI 1.0.0 has no interrupt event, so run-level waits surface as CUSTOM. The value is
+          // self-sufficient: a generic client can act on it (forwardedProps.cognate.resolve/cancel)
+          // without parsing rawEvent, using the ids carried here.
+          out.push({
+            type: "CUSTOM",
+            name: supported ? "cognate.continuation" : "cognate.unsupported_interaction",
+            value: { id: continuationId, type: waitType, kind: kind ?? "unknown", payload: view?.payload ?? null, runId: options.runId, threadId: options.threadId },
+            rawEvent: { cognate },
+          });
+        }
+        break;
+      }
+      case "run.resumed": {
+        const stepId = metaField<string>(event, "stepId");
+        const callId = stepId?.match(/^wait:remote:(.+)$/)?.[1];
+        if (!callId) break;
+        const resolution = payloadField<Json>(event, "input") ?? null;
+        const result = resolution && typeof resolution === "object" && !Array.isArray(resolution) && resolution.ok === true ? (resolution.value ?? null) : resolution;
+        out.push({ type: "TOOL_CALL_RESULT", messageId: `${callId}:result`, toolCallId: callId, content: JSON.stringify(result), role: "tool", rawEvent: { cognate } });
+        break;
+      }
+      case "run.completed": {
+        closeText(out, cognate);
+        out.push({ type: "RUN_FINISHED", threadId: options.threadId, runId: options.runId, result: { status: "completed", output: payloadField<Json>(event, "output") ?? null }, rawEvent: { cognate } });
+        break;
+      }
+      case "run.failed": {
+        closeText(out, cognate);
+        out.push({ type: "RUN_ERROR", message: payloadField<string>(event, "error") ?? "run failed", code: "failed", rawEvent: { cognate } });
+        break;
+      }
+      case "run.cancelled": {
+        closeText(out, cognate);
+        out.push({ type: "RUN_ERROR", message: payloadField<string>(event, "reason") ?? "cancelled", code: "cancelled", rawEvent: { cognate } });
+        break;
+      }
+      default:
+        break; // ignoredFrameworkEvents and anything unrecognized project to nothing
+    }
+    return out;
+  }
+
+  return {
+    push(event: StoredEvent): readonly AgUiEvent[] {
+      updateFold(event);
+      return project(event);
+    },
+    snapshot(): readonly AgUiEvent[] {
+      const messages = text ? [{ id: `${options.runId}:assistant`, role: "assistant", content: text }] : [];
+      return [
+        { type: "MESSAGES_SNAPSHOT", messages },
+        { type: "STATE_SNAPSHOT", snapshot: state },
+      ];
+    },
+    stateOnly(): readonly AgUiEvent[] {
+      return [{ type: "STATE_SNAPSHOT", snapshot: state }];
+    },
+  };
+}
+
+/** Correlation id grouping the Cognate runs started for one AG-UI thread (mirrors the Harness `session:<id>`). */
+export function threadCorrelationId(threadId: string): string {
+  return `agui-thread:${threadId}`;
+}
+
+export interface EndpointOptions {
+  readonly service: RuntimeService;
+  readonly authenticate: (headers: Headers) => Caller | undefined | Promise<Caller | undefined>;
+  /** Agent to start for new user messages when `forwardedProps.cognate.agent` is absent. */
+  readonly defaultAgent: string;
+}
+
+type Message = { readonly id: string; readonly role: string; readonly content?: unknown; readonly toolCallId?: string };
+type RunAgentInput = { readonly threadId: string; readonly runId: string; readonly messages: readonly Message[]; readonly context?: readonly { readonly description: string; readonly value: string }[]; readonly forwardedProps?: Record<string, unknown>; readonly state?: Record<string, unknown> };
+type CognateProps = { readonly agent?: string; readonly cancel?: { readonly reason?: string }; readonly resolve?: { readonly continuationId: string; readonly action: "resume" | "cancel"; readonly input?: Json; readonly expectedVersion?: number }; readonly cursor?: number };
+
+function cognateProps(input: RunAgentInput): CognateProps {
+  const raw = (input.forwardedProps as { cognate?: CognateProps } | undefined)?.cognate;
+  return raw ?? {};
+}
+
+const encoder = new EventEncoder();
+
+function sseResponse(events: readonly AgUiEvent[]): Response {
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const bytes = new TextEncoder();
+      for (const event of events) {
+        try {
+          controller.enqueue(bytes.encode(encoder.encodeSSE(event as never)));
+        } catch {
+          break;
+        }
+      }
+      try {
+        controller.close();
+      } catch {
+        // already closed by a disconnect
+      }
+    },
+  });
+  return new Response(body, { status: 200, headers: { "content-type": encoder.getContentType() } });
+}
+
+/**
+ * Project a durable event cursor as SSE. Cancelling the HTTP body only aborts this
+ * projection: it never cancels the run whose committed history remains resumable.
+ */
+function liveSseResponse(produce: (emit: (event: AgUiEvent) => boolean, signal: AbortSignal) => Promise<void>): Response {
+  const aborted = new AbortController();
+  const body = new ReadableStream<Uint8Array>({
+    start(controller) {
+      const bytes = new TextEncoder();
+      const emit = (event: AgUiEvent): boolean => {
+        if (aborted.signal.aborted) return false;
+        try {
+          controller.enqueue(bytes.encode(encoder.encodeSSE(event as never)));
+          return true;
+        } catch {
+          aborted.abort();
+          return false;
+        }
+      };
+      void produce(emit, aborted.signal)
+        .catch((error: unknown) => {
+          if (!aborted.signal.aborted) controller.error(error);
+        })
+        .finally(() => {
+          if (!aborted.signal.aborted) {
+            try {
+              controller.close();
+            } catch {
+              // The consumer may have already cancelled the body.
+            }
+          }
+        });
+    },
+    cancel() {
+      aborted.abort();
+    },
+  });
+  return new Response(body, { status: 200, headers: { "content-type": encoder.getContentType() } });
+}
+
+/**
+ * HTTP endpoint for AG-UI clients: POST RunAgentInput → SSE stream of AG-UI events. Inbound actions (user message,
+ * tool results for frontend capabilities, continuation responses, cancellation) go through RuntimeService with the
+ * authenticated caller. `forwardedProps.cognate.cursor` resumes from a durable position; an invalid cursor yields
+ * a full resync. Disconnecting never cancels the durable run.
+ */
+export function createAgUiHandler(options: EndpointOptions): (request: Request) => Promise<Response> {
+  const { service } = options;
+
+  return async function handle(request: Request): Promise<Response> {
+    let body: unknown;
+    try {
+      body = await request.json();
+    } catch {
+      return new Response(JSON.stringify({ error: "invalid JSON body" }), { status: 400, headers: { "content-type": "application/json" } });
+    }
+    const parsed = RunAgentInputSchema.safeParse(body);
+    if (!parsed.success) return new Response(JSON.stringify({ error: "invalid RunAgentInput", issues: parsed.error.issues }), { status: 400, headers: { "content-type": "application/json" } });
+    const input = parsed.data as unknown as RunAgentInput;
+
+    const caller = await options.authenticate(request.headers);
+    if (!caller) return new Response(null, { status: 401 });
+
+    const props = cognateProps(input);
+    const threadCorrelation = threadCorrelationId(input.threadId);
+    const belongsToRunOrThreadState = (event: StoredEvent, runId: string): boolean =>
+      event.runId === runId || (event.eventType === "state.changed" && event.metadata?.scope === "thread" && event.correlationId === threadCorrelation);
+
+    // Thread -> run mapping is served by the runtime's run index (DEBT-019), maintained atomically with
+    // run.started, not by scanning the event log: runs started for a thread carry its correlation id, so a
+    // restarted server (or another process) routes resolve/cancel/reconnect to the thread's most recent run.
+    // `listRuns` is tenant-scoped, so another tenant's thread never matches.
+    const resolveRunId = async (): Promise<string> => {
+      const runs = await service.listRuns(caller, { correlationId: threadCorrelation });
+      const latest = runs.at(-1);
+      if (latest) return latest.runId;
+      throw new ServiceError("not_found", `no Cognate run is known for thread ${input.threadId}`);
+    };
+    const positionBeforeAction = async (runId: string): Promise<number> => {
+      let position = 0;
+      for await (const event of service.events(caller, { runId, afterPosition: 0 })) position = event.position;
+      return position;
+    };
+
+    let cognateRunId: string;
+    let mode: "full" | "reconnect";
+    let afterInboundAction = 0;
+    try {
+      if (props.cancel) {
+        cognateRunId = await resolveRunId();
+        afterInboundAction = await positionBeforeAction(cognateRunId);
+        await service.cancelRun(caller, { runId: cognateRunId, reason: props.cancel.reason ?? "cancelled", idempotencyKey: `agui:${input.threadId}:${input.runId}:cancel` });
+        mode = "full";
+      } else if (props.resolve) {
+        cognateRunId = await resolveRunId();
+        afterInboundAction = await positionBeforeAction(cognateRunId);
+        await service.resolveContinuation(caller, {
+          continuationId: props.resolve.continuationId,
+          action: props.resolve.action,
+          input: props.resolve.input ?? null,
+          idempotencyKey: `agui:resolve:${props.resolve.continuationId}:${props.resolve.action}`,
+          ...(props.resolve.expectedVersion !== undefined ? { expectedVersion: props.resolve.expectedVersion } : {}),
+        });
+        mode = "full";
+      } else if (input.messages.some((m) => m.role === "tool")) {
+        const toolMessage = [...input.messages].reverse().find((m) => m.role === "tool")!;
+        let value: Json;
+        try {
+          value = JSON.parse(String(toolMessage.content ?? "null"));
+        } catch {
+          value = String(toolMessage.content ?? "");
+        }
+        cognateRunId = await resolveRunId();
+        afterInboundAction = await positionBeforeAction(cognateRunId);
+        // Frontend waits project the full continuation id as the wire toolCallId; remote-offer waits
+        // project the bare remote id (the continuation id is `<runId>.wait.remote:<remoteId>`). A
+        // generic AG-UI client echoes whichever id it received, so accept both shapes: a bare id is
+        // addressed to the thread's current run's remote wait. An unknown id still fails closed
+        // (not_found) through the service's own continuation lookup.
+        const continuationId = toolMessage.toolCallId!.includes(".wait.")
+          ? toolMessage.toolCallId!
+          : `${cognateRunId}.wait.remote:${toolMessage.toolCallId!}`;
+        await service.resolveContinuation(caller, { continuationId, action: "resume", input: { ok: true, value }, idempotencyKey: `agui:resolve:${continuationId}:tool` });
+        mode = "full";
+      } else if (input.messages.some((m) => m.role === "user")) {
+        const userMessage = [...input.messages].reverse().find((m) => m.role === "user")!;
+        const text = typeof userMessage.content === "string" ? userMessage.content : "";
+        // AG-UI clients send `state: {}` by default; only a non-empty object is a real seed (spec §29.1).
+        const seedState = input.state && typeof input.state === "object" && Object.keys(input.state).length > 0 ? (input.state as Json) : undefined;
+        const view = await service.startRun(caller, {
+          agent: props.agent ?? options.defaultAgent,
+          // Context is a read-only observation captured at run start. It is distinct from the
+          // caller/agent writable `state.changed` stream and remains immutable on replay.
+          input: { message: text, context: (input.context ?? []).map(({ description, value }) => ({ description, value })) },
+          idempotencyKey: `agui:${input.threadId}:${input.runId}`,
+          correlationId: threadCorrelation,
+          ...(seedState !== undefined ? { state: seedState } : {}),
+        });
+        cognateRunId = view.runId;
+        mode = "full";
+      } else {
+        cognateRunId = await resolveRunId();
+        mode = "reconnect";
+      }
+    } catch (error) {
+      if (error instanceof ServiceError) return sseResponse([{ type: "RUN_ERROR", message: error.message, code: error.code }]);
+      throw error;
+    }
+
+    // The runtime cursor is the source of both catch-up and live delivery. It subscribes before reading
+    // history, so a commit between those phases is neither lost nor duplicated. Do not wait for settlement:
+    // an SSE consumer must see each committed projection while the run is still executing.
+    const readHistory = async (): Promise<StoredEvent[]> => {
+      const events: StoredEvent[] = [];
+      for await (const event of service.events(caller, { correlationId: threadCorrelation, afterPosition: 0 })) {
+        if (belongsToRunOrThreadState(event, cognateRunId)) events.push(event);
+      }
+      return events;
+    };
+    return liveSseResponse(async (emit, signal) => {
+      let continuationViews: ContinuationView[] = [];
+      const byId = new Map<string, ContinuationView>();
+      const projector = createProjector({ threadId: input.threadId, runId: input.runId, continuation: (id) => byId.get(id) });
+      let settled = false;
+
+      const refreshContinuations = async (): Promise<void> => {
+        continuationViews = await service.listContinuations(caller, { runId: cognateRunId });
+        byId.clear();
+        for (const continuation of continuationViews) byId.set(continuation.id, continuation);
+      };
+      const finishWaiting = (): void => {
+        const open = continuationViews.filter((v) => v.status === "OPEN");
+        const supported = open.every((v) => {
+          const kind = conditionKindOf(v);
+          return kind !== undefined && SUPPORTED_CONTINUATION_KINDS.has(kind);
+        });
+        emit({ type: "RUN_FINISHED", threadId: input.threadId, runId: input.runId, result: { status: supported ? "waiting" : "waiting_unsupported", continuations: open.map((v) => ({ id: v.id, type: v.type, version: v.version })) } });
+        settled = true;
+      };
+      const project = async (event: StoredEvent, finishOnWait = true): Promise<void> => {
+        if (event.eventType === "run.waiting") await refreshContinuations();
+        for (const projected of projector.push(event)) if (!emit(projected)) return;
+        if (event.eventType === "run.waiting" && finishOnWait) finishWaiting();
+        else if (event.eventType === "run.completed" || event.eventType === "run.failed" || event.eventType === "run.cancelled") settled = true;
+      };
+
+      let afterPosition = afterInboundAction;
+      let emitSeededThreadState = false;
+      if (mode === "full" && afterInboundAction === 0) {
+        const history = await readHistory();
+        const started = history.find((event) => event.eventType === "run.started" && event.runId === cognateRunId);
+        if (started) {
+          for (const event of history) {
+            if (event.position >= started.position) break;
+            if (event.eventType === "state.changed" && event.metadata?.scope === "thread") {
+              projector.push(event);
+              emitSeededThreadState = true;
+            }
+          }
+          afterPosition = started.position - 1;
+        }
+      }
+      if (mode === "reconnect") {
+        const history = await readHistory();
+        const cursor = props.cursor;
+        const maxPosition = history.at(-1)?.position ?? 0;
+        const validCursor = typeof cursor === "number" && cursor >= 0 && cursor <= maxPosition;
+        if (validCursor) {
+          for (const event of history) if (event.position <= cursor) projector.push(event);
+          for (const event of projector.stateOnly()) if (!emit(event)) return;
+          afterPosition = cursor;
+        } else {
+          const started = history.find((event) => event.eventType === "run.started" && event.runId === cognateRunId);
+          if (!emit({ type: "RUN_STARTED", threadId: input.threadId, runId: input.runId, rawEvent: started ? { cognate: { eventId: started.eventId, position: started.position, runId: started.runId } } : undefined })) return;
+          for (const event of history) if (event.eventType === "message.delta" || event.eventType === "state.changed" || (event.eventType === "run.invocation.progress" && payloadField<string>(event, "type") === "text")) projector.push(event);
+          for (const event of projector.snapshot()) if (!emit(event)) return;
+          for (const event of history) {
+            if (event.eventType === "run.started" || event.eventType === "message.delta" || event.eventType === "state.changed" || (event.eventType === "run.invocation.progress" && payloadField<string>(event, "type") === "text")) continue;
+            await project(event, false);
+            if (settled || signal.aborted) return;
+          }
+          afterPosition = maxPosition;
+          // Historical waits are interaction episodes, not terminal history. Only the run's
+          // current waiting status should end a resync; an earlier wait may have been resumed.
+          if ((await service.getRun(caller, { runId: cognateRunId })).status === "waiting") {
+            await refreshContinuations();
+            finishWaiting();
+            return;
+          }
+        }
+      }
+
+      for await (const event of service.events(caller, { correlationId: threadCorrelation, afterPosition, follow: true, signal })) {
+        if (!belongsToRunOrThreadState(event, cognateRunId)) continue;
+        await project(event);
+        if (event.eventType === "run.started" && emitSeededThreadState) {
+          for (const snapshot of projector.stateOnly()) if (!emit(snapshot)) return;
+          emitSeededThreadState = false;
+        }
+        if (settled || signal.aborted) return;
+      }
+    });
+  };
+}