@gnldev/chat-adapter 0.1.0

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 2026 Karaca Yılmaz (https://gnl.dev)
+
+   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

@@ -0,0 +1,181 @@
+# @gnldev/chat-adapter
+
+Compatibility with the Vercel AI SDK's UI layer: run a durable agent on the server, render it with
+`useChat` on the client.
+
+## Install
+
+> Install: `pnpm add @gnldev/chat-adapter` — or use it from a [repo clone](https://github.com/Karaca7/gnldev): `pnpm install && pnpm -r build`.
+
+```bash
+npm i @gnldev/chat-adapter
+```
+
+## Chat route
+
+```ts
+import { createChatRoute } from '@gnldev/chat-adapter';
+
+app.route('/api', createChatRoute({ gnl }));
+// POST /api/agents/:name/chat — useChat({ api: '/api/agents/pay/chat' }) works unchanged.
+```
+
+The route streams back in the AI SDK's UI-message format, so an existing `useChat` frontend works
+unchanged — while the run behind it is journaled, replayable, and its side effects are
+[at-most-once](../durable/README.md#what-never-charged-twice-actually-means).
+
+You normally do NOT need `resolveRunId`: the default derivation `${body.id}:${lastMessage.id}` gives
+one durable run PER TURN (a network retry of the same turn replays; a new turn runs fresh).
+Anti-pattern to avoid: `resolveRunId: (_c, body) => body.id` — useChat's `body.id` is stable for the
+WHOLE conversation, so every later turn would replay turn 1 from the journal forever. What that
+derived string *is* — a name the engine hashes into an id, or the id itself — depends on whether the
+route can name the user; see [the idempotency contract](#the-idempotency-contract).
+
+## Who is this request for? (`identity` / `resolveResourceId`)
+
+This route ships with **no auth of its own** — deliberately, and the same posture as `@gnldev/agui`.
+What that leaves you responsible for is one thing: naming the end user each run acts for.
+
+**Why it is not optional.** GNL has no end-user identity of its own. An end user is a *subject* a
+trusted application names, not a principal GNL authenticates. The engine treats a few reserved
+context keys as "the server established this" — and an early version of this route forwarded
+`body.context` verbatim, so the reserved key arrived from whoever sent the request. Measured against
+a running app: a plain POST carrying `{"context":{"__gnl_resourceId":"VICTIM"}}` produced a run owned
+by that name, and the ownership stamp followed it.
+
+The route now **always seals** the context, so that specific forgery is closed whether or not you
+pass a resolver. What a resolver decides is the other half: whether the run has an owner at all.
+
+```ts
+import { createChatRoute } from '@gnldev/chat-adapter';
+
+const chat = createChatRoute({ gnl }, {
+  // ONE hook for both fields. The same signature @gnldev/agui's route takes.
+  identity: (req) => {
+    const session = db.sessions.get(req.headers.get('cookie'));   // YOUR session store
+    return session ? { resourceId: session.userId, threadId: session.conversationId } : undefined;
+  },
+});
+```
+
+`identity` receives the **web `Request`**, not the Hono context, so a host bridging this route from
+Express or Fastify can use it. It is called once per request and may return `undefined`.
+
+**Read it from something the server trusts** — a session cookie, a verified JWT,
+`principalOf(req)?.id` — and **never from the request body**. A body-supplied subject is the caller
+naming whoever they like, which is the hole the context seal exists to close.
+
+**If you give none.** Nothing is asserted and nothing is forged: runs are born **ownerless**. That is
+safe against impersonation and weak in the other direction — an ownership gate with no owner to
+compare against refuses nobody, so the protection reads as present and is not. Memory also has
+nothing to scope on, so per-user recall and `listThreads` have no subject to key by. In
+`NODE_ENV=production` the route says so once, at construction, with a `console.warn` — it never
+throws, because a deployment whose boundary genuinely lives in front of this route is not broken.
+
+**Precedence**, field by field:
+
+| Field | Order |
+|---|---|
+| `resourceId` | `resolveResourceId(c, body)` → `identity(req).resourceId` → *(none)* |
+| `threadId` | `resolveThreadId(c, body)` → `identity(req).threadId` → `body.threadId` → `body.id` → the runId |
+
+`resolveResourceId` / `resolveThreadId` still win: they are the existing contract, and a newer
+convenience must not quietly take a working deployment's answer away. `identity` outranks the body,
+because it is server-derived and the body is not.
+
+**Honest bound.** A resolver reading an *unauthenticated* request asserts a subject nobody verified.
+Put auth in front of this route — or compose `@gnldev/server`'s `createRestApi` auth middleware
+around it — or the subject is only as trustworthy as the caller.
+
+## The idempotency contract
+
+**Two regimes, decided by whether the route can name a subject.** The per-turn key
+(`${body.id}:${lastMessage.id}`, or an `Idempotency-Key` header when a gateway sends one) is this
+route's name for *the work this turn is*. When `identity` / `resolveResourceId` gives that turn an
+owner, the key is promoted to a **`workKey`**: the engine derives the run's id from it
+(`run1_<digest>`) and the string you sent stops being a journal key. When there is nobody to name —
+the anonymous quickstart, no auth, no session store — the same string stays the raw runId it has
+always been, byte for byte. Deriving an id from a name needs an *address* to make it unique within,
+and a route with no subject has none; refusing those requests would replace a working first five
+minutes with an error message. Your retry contract is identical in both: the same message ids
+produce the same key, and the same key lands on the same run.
+
+One migration note, because the regime is decided by the resolver: **adopting this version — or
+wiring `identity` into a deployment that ran without it — changes which id an in-flight turn's retry
+lands on** (raw key on the old pods, `run1_` on the new). During that window a retried turn can run
+once more. Close the window by draining in-flight requests over the deploy rather than rolling
+through it.
+
+- **`X-Gnl-Run-Id` on every response** (success and error): the opaque id of the run this call
+  landed on — a **correlation handle** for logs, traces and Studio. It is **not your retry key**: to
+  retry, send the same turn again (the same conversation id and the same last-message id). Explicit
+  `body.runId` and `resolveRunId` still win, and both stay raw — they name an *id*, and a host
+  holding one has already decided the addressing. The `Idempotency-Key` header is read AFTER them (a
+  gateway-stamped header must not silently override an application decision).
+- **A per-run lock is ON by default** (`lock: { ttlMs: 300_000 }`): two concurrent requests with the
+  same runId (double-click, two tabs, a retry racing the original) no longer both execute — the
+  loser gets a typed `409 { code: 'run_busy', resumable: true }` + `Retry-After`, and retrying the
+  same runId lands on the journal replay. `lock: false` restores the old behavior. Scope note: this
+  serializes CONCURRENT duplicates; serial retries were already deduped by the runId derivation.
+- **`X-Gnl-Idempotency-Status` on success responses**: `new` on a fresh run, `replay` when this
+  runId had prior journaled input (a retry/resume landing on journal state) — an observability
+  contract for client-side reconciliation, not a byte-identity guarantee.
+- **Typed errors instead of a flat 400**: `run_thread_mismatch` / `run_input_mismatch` /
+  `run_actor_mismatch` / `run_swept` → 409 without `resumable` (fix the id, not the request);
+  `run_busy` → 409 + `Retry-After`; `retry_limit_exceeded` → 422; upstream provider failures →
+  429/502/504. Malformed `messages` stays a 400 — with the header contract intact.
+
+## Approvals round-trip (`approve` / `approvalPayload`)
+
+When a tool suspends (a guard's `require-approval`, the `confirm` field, a duplicate/semantic
+question), the stream carries a `data-gnl-interrupt` chunk whose entries include the **suspended
+run's `runId`** — the approval's ADDRESS. A naive client that just re-POSTs its messages derives a
+FRESH runId from the new last-message id: the approval lands on a brand-new run and the suspended
+one waits forever. Use the helpers:
+
+```ts
+import { approvalPayload, approve } from '@gnldev/chat-adapter';
+
+// useChat-style: merge the payload into YOUR next request body (same conversation id, same messages)
+sendMessage(undefined, { body: approvalPayload(interrupt) });      // { runId, approvals: { [toolCallId]: true } }
+
+// headless/manual: a convenience fetch that re-POSTs and returns the streaming Response
+await approve('/api/agents/pay/chat', { interrupt, chatId, messages });
+```
+
+`approvalPayload` THROWS on an interrupt without `runId` rather than silently targeting a fresh run.
+Product rules, stated plainly: approval is a BUTTON — the route reads decisions only from
+`body.approvals`; a user typing "yes, do it" starts a fresh turn, it approves nothing. And
+"regenerate" with the same runId gets the journal REPLAY (the safe default); genuinely re-running a
+side effect goes through the approval ladder, never a silent re-execution.
+
+## Rebuilding history from the journal
+
+```ts
+import { toUIMessages } from '@gnldev/chat-adapter';
+
+const messages = toUIMessages(await journal.list(runId));
+```
+
+The journal is the source of truth, so a reconnecting client can rebuild the conversation without
+the server holding session state.
+
+## Exports
+
+| Export | What it is |
+|---|---|
+| `createChatRoute` | A handler that runs an agent and streams UI messages |
+| `toUIMessageStream` / `toUIMessageStreamResponse` | Converts a durable stream into the UI-message wire format, masking the internal sentinels |
+| `toUIMessages` | Journal records → `UIMessage[]` for history reconstruction |
+| `approvalPayload` / `approve` | The approval round-trip helpers — land the decision on the SUSPENDED run (see above) |
+| `maskSentinelOutput` | The shared sentinel-masking primitive (used by both live streaming and history) |
+
+## A note on history
+
+`useChat` posts the entire client-side history on every turn. When the agent has memory and a
+`threadId`, the server owns the history instead — the client's copy is a view, not the record. That
+contract is enforced in the core, not here.
+
+## License
+
+Apache-2.0 — see [LICENSE](./LICENSE).

package/dist/approve.d.ts

@@ -0,0 +1,32 @@
+/** The minimum an approval needs from a `data-gnl-interrupt` entry (see GnlInterruptData). */
+export interface ApprovableInterrupt {
+    toolCallId: string;
+    /** The suspended run's id — REQUIRED to route the approval (older servers that don't stamp it
+     *  Can't be addressed reliably; see `approvalPayload`'s throw). */
+    runId?: string;
+}
+/**
+ * The body fields that turn a chat POST into an approval of `interrupt`. Merge into the SAME request
+ * shape you normally send (same conversation `id`, same `messages`) — runId precedence in the route
+ * guarantees these fields win over derivation.
+ */
+export declare function approvalPayload(interrupt: ApprovableInterrupt, approved?: boolean): {
+    runId: string;
+    approvals: Record<string, boolean>;
+};
+export interface ApproveOptions {
+    interrupt: ApprovableInterrupt;
+    /** The SAME UIMessage history the original turn sent — the journal's frozen input wins on replay,
+     *  But the route still converts these (and the thread guard needs the same conversation). */
+    messages: unknown[];
+    /** UseChat's stable conversation id (`body.id`) — REQUIRED when the original turn had one: threadId
+     *  Defaults to it, and a mismatched thread is refused with 409 run_thread_mismatch. */
+    chatId?: string;
+    threadId?: string;
+    approved?: boolean;
+    headers?: Record<string, string>;
+    /** Override for non-global-fetch environments/tests. */
+    fetchImpl?: typeof fetch;
+}
+/** Re-POSTs the approval to the chat endpoint and returns the raw streaming Response. */
+export declare function approve(endpoint: string, opts: ApproveOptions): Promise<Response>;

package/dist/approve.js

@@ -0,0 +1,46 @@
+// FAZ-2 — the approval round-trip, fixed at the CLIENT edge. The failure this closes (heyet kararı
+// 1.8): a suspended tool emits a `data-gnl-interrupt`; the user clicks "approve"; a naive client
+// re-POSTs its messages and the route derives a FRESH runId from the new last-message id — the
+// approval lands on a brand-new run, the suspended run stays suspended forever (retention keeps
+// suspended runs deliberately → unbounded accumulation), and the tool never fires. The fix is
+// addressing: an approval must travel with the SUSPENDED run's id (`interrupt.runId`, stamped by
+// ui-stream.ts) and the SAME conversation identity (`body.id`/threadId — a different thread 409s on
+// the frozen-input guard).
+//
+// Two surfaces, by integration style:
+//  `approvalPayload(interrupt)`  — pure: the body fields to merge into YOUR request (useChat's
+//    `sendMessage(..., { body })`, a custom fetch, a proxy). No I/O, no deps.
+//  `approve(endpoint, {...})`    — convenience fetch for headless/manual flows: re-POSTs the SAME
+//    Messages + the payload and returns the raw streaming Response (the caller renders/drains it).
+//
+// Approval is a BUTTON, not prose: the route reads decisions ONLY from `body.approvals`
+// (chat-route.ts) — a user typing "yes, do it" into the chat input does NOT approve anything, it
+// starts a fresh turn. Likewise "regenerate" on a completed turn re-POSTs the same runId and gets the
+// journal REPLAY (safe default); genuinely re-running a side effect goes through this approval
+// ladder, never through a silent re-execution.
+/**
+ * The body fields that turn a chat POST into an approval of `interrupt`. Merge into the SAME request
+ * shape you normally send (same conversation `id`, same `messages`) — runId precedence in the route
+ * guarantees these fields win over derivation.
+ */
+export function approvalPayload(interrupt, approved = true) {
+    if (!interrupt.runId) {
+        throw new Error('@gnldev/chat-adapter: approvalPayload needs interrupt.runId — this server did not stamp runId onto the interrupt (upgrade the route/ui-stream), and approving by a DERIVED id would target a fresh run instead of the suspended one.');
+    }
+    return { runId: interrupt.runId, approvals: { [interrupt.toolCallId]: approved } };
+}
+/** Re-POSTs the approval to the chat endpoint and returns the raw streaming Response. */
+export async function approve(endpoint, opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    return doFetch(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', ...(opts.headers ?? {}) },
+        body: JSON.stringify({
+            ...(opts.chatId !== undefined ? { id: opts.chatId } : {}),
+            ...(opts.threadId !== undefined ? { threadId: opts.threadId } : {}),
+            messages: opts.messages,
+            ...approvalPayload(opts.interrupt, opts.approved ?? true),
+        }),
+    });
+}
+//# sourceMappingURL=approve.js.map

package/dist/approve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approve.js","sourceRoot":"","sources":["../src/approve.ts"],"names":[],"mappings":"AAAA,mGAAmG;AACnG,iGAAiG;AACjG,+FAA+F;AAC/F,gGAAgG;AAChG,8FAA8F;AAC9F,iGAAiG;AACjG,oGAAoG;AACpG,2BAA2B;AAC3B,EAAE;AACF,sCAAsC;AACtC,+FAA+F;AAC/F,8EAA8E;AAC9E,kGAAkG;AAClG,mGAAmG;AACnG,EAAE;AACF,wFAAwF;AACxF,iGAAiG;AACjG,sGAAsG;AACtG,+FAA+F;AAC/F,+CAA+C;AAU/C;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAC7B,SAA8B,EAC9B,QAAQ,GAAG,IAAI;IAEf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,sOAAsO,CACvO,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC;AACrF,CAAC;AAiBD,yFAAyF;AACzF,MAAM,CAAC,KAAK,UAAU,OAAO,CAAC,QAAgB,EAAE,IAAoB;IAClE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,IAAI,KAAK,CAAC;IACxC,OAAO,OAAO,CAAC,QAAQ,EAAE;QACvB,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE;QACxE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,GAAG,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACzD,GAAG,CAAC,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACnE,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,GAAG,eAAe,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,QAAQ,IAAI,IAAI,CAAC;SAC1D,CAAC;KACH,CAAC,CAAC;AACL,CAAC","sourcesContent":["// FAZ-2 — the approval round-trip, fixed at the CLIENT edge. The failure this closes (heyet kararı\n// 1.8): a suspended tool emits a `data-gnl-interrupt`; the user clicks \"approve\"; a naive client\n// re-POSTs its messages and the route derives a FRESH runId from the new last-message id — the\n// approval lands on a brand-new run, the suspended run stays suspended forever (retention keeps\n// suspended runs deliberately → unbounded accumulation), and the tool never fires. The fix is\n// addressing: an approval must travel with the SUSPENDED run's id (`interrupt.runId`, stamped by\n// ui-stream.ts) and the SAME conversation identity (`body.id`/threadId — a different thread 409s on\n// the frozen-input guard).\n//\n// Two surfaces, by integration style:\n//  `approvalPayload(interrupt)`  — pure: the body fields to merge into YOUR request (useChat's\n//    `sendMessage(..., { body })`, a custom fetch, a proxy). No I/O, no deps.\n//  `approve(endpoint, {...})`    — convenience fetch for headless/manual flows: re-POSTs the SAME\n//    Messages + the payload and returns the raw streaming Response (the caller renders/drains it).\n//\n// Approval is a BUTTON, not prose: the route reads decisions ONLY from `body.approvals`\n// (chat-route.ts) — a user typing \"yes, do it\" into the chat input does NOT approve anything, it\n// starts a fresh turn. Likewise \"regenerate\" on a completed turn re-POSTs the same runId and gets the\n// journal REPLAY (safe default); genuinely re-running a side effect goes through this approval\n// ladder, never through a silent re-execution.\n\n/** The minimum an approval needs from a `data-gnl-interrupt` entry (see GnlInterruptData). */\nexport interface ApprovableInterrupt {\n  toolCallId: string;\n  /** The suspended run's id — REQUIRED to route the approval (older servers that don't stamp it\n   *  Can't be addressed reliably; see `approvalPayload`'s throw). */\n  runId?: string;\n}\n\n/**\n * The body fields that turn a chat POST into an approval of `interrupt`. Merge into the SAME request\n * shape you normally send (same conversation `id`, same `messages`) — runId precedence in the route\n * guarantees these fields win over derivation.\n */\nexport function approvalPayload(\n  interrupt: ApprovableInterrupt,\n  approved = true,\n): { runId: string; approvals: Record<string, boolean> } {\n  if (!interrupt.runId) {\n    throw new Error(\n      '@gnldev/chat-adapter: approvalPayload needs interrupt.runId — this server did not stamp runId onto the interrupt (upgrade the route/ui-stream), and approving by a DERIVED id would target a fresh run instead of the suspended one.',\n    );\n  }\n  return { runId: interrupt.runId, approvals: { [interrupt.toolCallId]: approved } };\n}\n\nexport interface ApproveOptions {\n  interrupt: ApprovableInterrupt;\n  /** The SAME UIMessage history the original turn sent — the journal's frozen input wins on replay,\n   *  But the route still converts these (and the thread guard needs the same conversation). */\n  messages: unknown[];\n  /** UseChat's stable conversation id (`body.id`) — REQUIRED when the original turn had one: threadId\n   *  Defaults to it, and a mismatched thread is refused with 409 run_thread_mismatch. */\n  chatId?: string;\n  threadId?: string;\n  approved?: boolean;\n  headers?: Record<string, string>;\n  /** Override for non-global-fetch environments/tests. */\n  fetchImpl?: typeof fetch;\n}\n\n/** Re-POSTs the approval to the chat endpoint and returns the raw streaming Response. */\nexport async function approve(endpoint: string, opts: ApproveOptions): Promise<Response> {\n  const doFetch = opts.fetchImpl ?? fetch;\n  return doFetch(endpoint, {\n    method: 'POST',\n    headers: { 'content-type': 'application/json', ...(opts.headers ?? {}) },\n    body: JSON.stringify({\n      ...(opts.chatId !== undefined ? { id: opts.chatId } : {}),\n      ...(opts.threadId !== undefined ? { threadId: opts.threadId } : {}),\n      messages: opts.messages,\n      ...approvalPayload(opts.interrupt, opts.approved ?? true),\n    }),\n  });\n}\n"]}

package/dist/chat-route.d.ts

@@ -0,0 +1,107 @@
+import type { Context } from 'hono';
+import { Hono } from 'hono';
+import { createGnl } from '@gnldev/durable';
+import type { CreateGnlConfig, GnlIdentity } from '@gnldev/durable';
+export interface CreateChatRouteOptions {
+    /** Resolve the durable `runId` (exactly-once key for THIS request) from the request/body. */
+    resolveRunId?: (c: Context, body: any) => string | undefined;
+    /** Resolve the conversation `threadId` (memory continuity across requests) from the request/body. */
+    resolveThreadId?: (c: Context, body: any) => string | undefined;
+    /**
+     * WHO this request acts for — the end user's `resourceId`, read from something the SERVER trusts
+     * (a session cookie, a verified JWT, `principalOf(c.req.raw)?.id`) and NEVER from the body.
+     *
+     * WHY IT EXISTS. GNL has no end-user identity: an end user is a SUBJECT that a trusted application
+     * names, not a principal GNL authenticates (`resolveResourceId` in @gnldev/server states this).
+     * The engine treats the reserved context keys as "the server established this", and this route used
+     * to forward `body.context` verbatim — so the reserved key arrived from whoever sent the request.
+     * MEASURED against a running app: a plain POST carrying
+     * `{"context":{"__gnl_resourceId":"KURBAN-KULLANICI"}}` produced a run owned by that name, and the
+     * ownership stamp followed it. The seal that exists precisely to prevent this (registry.ts's
+     * `sealRequestContext`, whose own comment names the attack) was never applied on this path.
+     *
+     * The route now ALWAYS seals. With no resolver the seal carries no identity, which STRIPS the
+     * reserved keys: a forged subject cannot get through, and none is asserted either.
+     *
+     * HONEST BOUND — it decides what every ownership guarantee downstream is worth: this route ships
+     * with NO auth of its own (see the createChatRoute JSDoc). A resolver reading an unauthenticated
+     * request asserts a subject nobody verified. Put auth in front of this route, or the subject is
+     * only as trustworthy as the caller.
+     */
+    resolveResourceId?: (c: Context, body: any) => string | undefined;
+    /**
+     * WHO and WHICH CONVERSATION, in one hook — the same signature @gnldev/agui's route takes, so the
+     * function a host writes once works on both.
+     *
+     * It exists because the two hooks above are two hooks. A host wiring identity had to write
+     * `resolveResourceId` AND `resolveThreadId`, and on the sibling adapter the second one had a
+     * different shape and, for a while, no effect at all (see agui's route.ts note on the dead
+     * `threadId` line). Answering "who is this request for" twice is how one of the answers ends up
+     * missing.
+     *
+     * Takes the web `Request`, not the Hono `Context` — the precedent is @gnldev/server's
+     * `OrgOptions.resolve`, and the reason is the same: a host binding this route from Express or
+     * Fastify has a Request and no Context.
+     *
+     * PRECEDENCE: `resolveResourceId` / `resolveThreadId` still WIN, field by field. They are the
+     * existing contract and a new convenience must not silently take a working deployment's answer
+     * away. This fills whichever of the two the host did not supply.
+     *
+     * Called ONCE per request, for the reason already written below about `subject`: a resolver that
+     * reads the request may answer differently the second time.
+     *
+     * HONEST BOUND — unchanged from `resolveResourceId`: this route ships with no auth of its own. A
+     * resolver reading an unauthenticated request asserts a subject nobody verified.
+     */
+    identity?: GnlIdentity;
+    /**
+     * FAZ-2 — per-run concurrency lock, ON by default (`{ ttlMs: 300_000 }`). Two CONCURRENT requests
+     * with the same runId (double-click, two tabs, a retry racing the original) used to BOTH execute;
+     * Now the loser gets the typed `409 run_busy` (+ Retry-After) and the winner's journal replay
+     * answers the retry. `lock: false` restores the old behavior. The streamed lock SELF-RENEWS on a
+     * ttl/2 heartbeat (engine parity with run()), so ttlMs is the crash-takeover window — the generous
+     * 5-minute default simply keeps takeover conservative.
+     */
+    lock?: {
+        ttlMs?: number;
+    } | false;
+}
+/**
+ * Produces a single-endpoint Hono router from a createGnl config (or an already-built `gnl` instance)
+ * that a `useChat({ api: '.../agents/:name/chat' })` client can talk to:
+ * POST /agents/:name/chat   { id?, messages: UIMessage[], runId?, threadId?, approvals? }  → UI message stream
+ * Deliberately kept small — SAME posture as @gnldev/agui's `createAguiRoute`: NO auth/org/budget gates (if
+ * needed, wrap this route, or compose @gnldev/server's createRestApi's auth middleware around it — see README).
+ *
+ * IDENTITY precedence: `body.runId` > `opts.resolveRunId(...)` > the TURN'S NAME
+ * (`Idempotency-Key` header, else DERIVED `${body.id}:${lastMessage.id}`) > a generated id. The
+ * derivation is the load-bearing default: `body.id` is useChat's STABLE per-conversation id — using
+ * it ALONE would make every later turn replay turn 1 from the journal (withDurableModel replays
+ * `runId:model:0` and the model never runs again). Combining it with the LAST message's id (useChat
+ * stamps a fresh id per message) gives one exactly-once run PER TURN, and makes a network retry of
+ * the SAME turn land on the same run (deduped replay — free idempotency) while a NEW turn runs fresh.
+ * `threadId` defaults to `body.id` (the conversation), NOT the per-turn key — conversation memory
+ * must span turns.
+ *
+ * TWO REGIMES, decided by whether the route can name a SUBJECT (package #5, §7). With one, the
+ * turn's name is a `workKey` and the engine derives an opaque `run1_` id from it; without one it
+ * stays the raw id it has always been, because deriving needs an address (§6) and this route's
+ * quickstart names nobody. The retry contract is identical either way: the same message ids produce
+ * the same key, and the same key lands on the same run.
+ *
+ * SCOPE of that idempotency (FAZ-2): serial retries dedupe via journal replay, and CONCURRENT
+ * duplicates are now serialized by the default per-run lock (`CreateChatRouteOptions.lock`) — the
+ * loser gets the typed 409 `run_busy` + Retry-After instead of a second execution. The effective
+ * RunId is echoed on every response as `X-Gnl-Run-Id` and stamped onto interrupt chunks — a
+ * CORRELATION handle, not the retry key: to retry, send the same turn again. One exception, agui's
+ * too: a pre-run identity refusal (unknown agent, unaddressable scope) carries no header, because
+ * the header names a run and none exists yet on that path.
+ *
+ * Body `workKey` is deliberately NOT read here (the REST, agui and workflow doors all take it):
+ * this route speaks the useChat wire format, where the turn IS the work — the per-turn key above,
+ * or a gateway's `Idempotency-Key`, is what gets promoted. A field the UI library never sends would
+ * be dead surface with a live failure mode (a stale key silently pinning every turn to one run).
+ */
+export declare function createChatRoute(config: CreateGnlConfig | {
+    gnl: ReturnType<typeof createGnl>;
+}, opts?: CreateChatRouteOptions): Hono;