@tangle-network/agent-app 0.43.71 → 0.43.73

package/dist/chat-routes/index.d.ts

@@ -186,6 +186,15 @@ declare function createAssistantDraftWriter(options: AssistantDraftWriterOptions
  *  `updateMessage` a draft row could never be patched, so the caller keeps
  *  today's exact single-write behavior. */
 declare function storeSupportsDraftPersistence(store: AssistantDraftStore): boolean;
+/** The row id an `appendMessage` actually returned, or `null` when the store
+ *  returned nothing usable. `ChatTurnMessageStore.appendMessage` is typed
+ *  `Promise<unknown>` so a product adapter is free to resolve `void`; every
+ *  caller that wants to NAME the row it just wrote has to read defensively.
+ *
+ *  Deliberately no fallback to a caller-assigned id — see `writeOnce`, which
+ *  adds its own. A caller that let the store mint the id has nothing to fall
+ *  back TO, and guessing one would report a row that may not exist. */
+declare function rowIdOf(inserted: unknown): string | null;
 /** The default deterministic assistant-row id for a turn. Readable on purpose
  *  (an operator grepping a transcript row id finds the run), and stable across
  *  re-entries because every input already is. */
@@ -213,24 +222,31 @@ declare function assistantRowIdForTurn(turnKey: string): string;
  * no router import. Auth/access is one injected `authorize` seam, composable
  * with `/app-auth` guards but not coupled to them.
  *
- * Six optional product seams let a complex turn-orchestrator compose the
- * vertical instead of hand-rolling a generator — each omittable to the exact
- * behavior above: `turnLock` (single-flight acquire/release around the turn),
+ * Optional product seams let a complex turn-orchestrator compose the vertical
+ * instead of hand-rolling a generator — each omittable to the exact behavior
+ * above: `turnLock` (single-flight acquire/release around the turn),
  * `contextGate` (pre-producer domain-readiness short-circuit), `beforeTurn`
  * (observe + augment the producer input), `lifecycle` (deterministic
  * start/complete/error telemetry), `heartbeat` (keepalive during silent
- * producer waits), plus `onRawEvent` (the raw producer events, for telemetry).
- * `handleChatTurn` stays the engine — the seams only wrap its input, its
- * producer stream, and its settle.
+ * producer waits), and `onRawEvent` (the raw producer events, for telemetry) —
+ * plus the `authorize` result's `insertUserMessage` flag (suppress the user row
+ * for a product-dispatched turn). `handleChatTurn` stays the engine — the seams
+ * only wrap its input, its producer stream, and its settle.
+ *
+ * Seam stability: all of the above are STABLE and safe to depend on. They
+ * graduated in #227 against the bar this package holds itself to — a seam is
+ * provisional until two INDEPENDENT consumers exercise it, because one
+ * consumer's shape is indistinguishable from that consumer's assumptions.
+ * `turnLock` cleared it with `/turn-stream`'s shared DO adapter (#221);
+ * `contextGate`, `beforeTurn`, `onRawEvent` and `insertUserMessage` each
+ * cleared it with two product verticals reading them differently — and the
+ * review found no leaked assumptions to fix, only `ChatRouteEvent` to export.
  *
- * Seam stability: `lifecycle`, `heartbeat`, and `turnLock` are generic and
- * stable (`turnLock` graduated with `/turn-stream`'s shared DO adapter, #221).
- * `contextGate`, `beforeTurn`, and `onRawEvent` are `@experimental` — proven
- * by a single consumer (gtm's chat vertical, #200) and may change once a
- * second consumer exercises them. They stay FLAT top-level options (not
- * grouped under a `hooks` object): that grouping would break the shipped
- * consumer's call for no mechanism gain, and this package's exports are
- * additive-only.
+ * They stay FLAT top-level options (not grouped under a `hooks` object): that
+ * grouping would break every shipped consumer's call for no mechanism gain, and
+ * this package's exports are additive-only. For the same reason `onRawEvent`
+ * keeps its two-argument `(event, context)` signature rather than being
+ * normalized to the single-args shape the other seams take.
  */
 
 /** Usage receipt persisted onto the assistant message (the flattened
@@ -329,7 +345,14 @@ type ChatTurnAuthorization<TContext> = {
      *  never overrides — the engine's retry-dedup: `authorize` runs before
      *  turn identity is resolved, so it cannot tell a retry from a fresh turn;
      *  a turn already deduped stays deduped. Omit / `true` → today's behavior.
-     *  @experimental Single-consumer; shape may change. */
+     *
+     *  Settled shape (#227). The validated case in both consumers is the same:
+     *  a durable plan-approval follow-up re-entering an execution the decision
+     *  route already enqueued — a decision, not a typed message, so it must
+     *  not surface a user bubble. Suppressing the insert also propagates:
+     *  `ChatTurnProduceArgs.userMessageId` is `null` for the rest of the turn
+     *  when there is no row to reuse, so a seam anchoring to the user row must
+     *  handle that arm rather than assume a string. */
     insertUserMessage?: boolean;
 } | {
     ok: false;
@@ -360,9 +383,28 @@ interface ChatTurnProduceArgs<TContext> {
     /** The turn-buffer id announced to the client for replay. */
     turnStreamId: string;
     priorMessages: PersistedChatMessageForTurn[];
+    /** The durable `role:'user'` row this turn is anchored to — the row the
+     *  factory just inserted, or the one retry-dedup REUSED. Products anchor
+     *  optimistic-bubble swaps, retry targeting, and stop-polling to it, and it
+     *  is the only way to name a REUSED row (which `priorMessages` excludes).
+     *
+     *  Three states, all meaningful:
+     *  - `undefined` — not resolved yet. `turnLock.acquire` is the one seam that
+     *    sees this: it runs before any side effect by contract, so the row does
+     *    not exist when it reads the args.
+     *  - `null` — resolved, no row: `authorize` returned `insertUserMessage:
+     *    false` on a turn with nothing to reuse, or the store's `appendMessage`
+     *    resolved without a usable id.
+     *  - a string — the row id, for `contextGate`, `beforeTurn`, and `produce`. */
+    userMessageId?: string | null;
 }
 /** One event as it crosses the route: the producer's own vocabulary, or an
- *  injected keepalive. Same shape the engine forwards verbatim. */
+ *  injected keepalive. Same shape the engine forwards verbatim.
+ *
+ *  Public because it IS the vocabulary of two seams — `onRawEvent`'s parameter
+ *  and `heartbeat.event`'s return. Exported so a product can declare a
+ *  standalone handler (`function onRawEvent(e: ChatRouteEvent, ctx: T)`) rather
+ *  than depending on contextual typing from an inline object literal. */
 type ChatRouteEvent = {
     type: string;
     data?: Record<string, unknown>;
@@ -434,6 +476,11 @@ interface ChatTurnLifecycleComplete<TContext> extends ChatTurnLifecycleBase<TCon
     /** Attribution for a downgrade: which models were tried and why each failed.
      *  `undefined` when the producer reports no failover support. */
     modelFailover?: ChatTurnModelFailover;
+    /** The durable `role:'assistant'` row this turn wrote, or `null` when it
+     *  wrote none (an empty turn leaves no row — a draft started mid-stream is
+     *  retracted). The detached lane surfaces the same id as
+     *  `DetachedTurnResult.messageId`; one contract, two lanes. */
+    assistantMessageId: string | null;
 }
 /** Represent an error occurring during a chat turn lifecycle with context and duration information */
 interface ChatTurnLifecycleError<TContext> extends ChatTurnLifecycleBase<TContext> {
@@ -451,6 +498,31 @@ interface ChatTurnLifecycle<TContext> {
     onTurnComplete?(info: ChatTurnLifecycleComplete<TContext>): void | Promise<void>;
     onTurnError?(info: ChatTurnLifecycleError<TContext>): void | Promise<void>;
 }
+/** What a settled turn reports to `onTurnComplete` — the product's
+ *  post-processing seam (billing, titles, audit). */
+interface ChatTurnCompleteInput<TContext> {
+    identity: ChatTurnIdentity;
+    finalText: string;
+    context: TContext;
+    failed: boolean;
+    failureReason?: string;
+    /** The model that SERVED this turn. With failover wired it may differ from
+     *  the requested one, so a product that bills or scores per model MUST read
+     *  it here rather than assuming the model it asked for. */
+    model?: string;
+    /** Present when the producer supports failover: the full attempt trail, and
+     *  `usedFallback` — the flag that makes a silent downgrade impossible. */
+    modelFailover?: ChatTurnModelFailover;
+    /** The durable `role:'assistant'` row this turn wrote, or `null` when it
+     *  wrote none (an empty turn leaves no row).
+     *
+     *  Populated even when `failed` is true — a terminal error event still
+     *  persists whatever partial answer arrived, and that pairing is exactly
+     *  what lets a product render an error row against a REAL message instead of
+     *  hunting for the newest row in the thread. The detached lane surfaces the
+     *  same id as `DetachedTurnResult.messageId`. */
+    assistantMessageId: string | null;
+}
 /** Define options to configure chat turn routes including authorization, storage, and event buffering */
 interface CreateChatTurnRoutesOptions<TContext = void> {
     /** Names the product in `deriveExecutionId` so retries land on the same
@@ -479,11 +551,34 @@ interface CreateChatTurnRoutesOptions<TContext = void> {
     /** Pre-turn readiness gate that can short-circuit with a product `Response`
      *  before the producer runs (the user row is already persisted). Runs after
      *  `turnLock.acquire`, before `beforeTurn`. Omit → always proceed.
-     *  @experimental Single-consumer (gtm, #200); shape may change. */
+     *
+     *  Settled shape (#227). What a consumer may depend on:
+     *  - `args.userMessageId` is RESOLVED here — a string, or `null` when the
+     *    insert was suppressed with nothing to reuse. (`turnLock.acquire` is the
+     *    only seam that sees it `undefined`.)
+     *  - `{proceed:false}` releases the lock and returns the product's `Response`
+     *    verbatim: `beforeTurn` and `produce` never run, no assistant row is
+     *    written, and the user row already inserted is KEPT — a real user turn
+     *    whose assistant side is the gate's own response.
+     *  - Always returning `{proceed:true}` is supported, not a misuse: the seam
+     *    doubles as the one place that runs after the user row exists and before
+     *    the producer, which is where per-turn analytics and readiness
+     *    precomputation belong. A gate that never gates is a valid consumer. */
     contextGate?(args: ChatTurnProduceArgs<TContext>): ChatTurnGateResult | Promise<ChatTurnGateResult>;
     /** Observe the assembled producer input and optionally augment it (rewrite
      *  the prompt / prior messages) before the producer runs. Omit → no change.
-     *  @experimental Single-consumer (gtm, #200); shape may change. */
+     *
+     *  Settled shape (#227). BOTH return arms are contract:
+     *  - a `ChatTurnInputPatch` shallow-merges over the route-assembled args, so
+     *    an omitted field keeps the route's value;
+     *  - `void` means "no patch" — and mutating `args.context` in place is the
+     *    supported way to thread request-scoped state forward to `produce` /
+     *    `lifecycle` / `onTurnComplete`, which all receive the same object.
+     *
+     *  A throw propagates (the turn fails with the lock released). It runs BEFORE
+     *  `lifecycle.onTurnStart`, so a throw here fires no terminal lifecycle hook —
+     *  the span never opened. Telemetry for a failure in this seam belongs in the
+     *  seam, not in `lifecycle`. */
     beforeTurn?(args: ChatTurnProduceArgs<TContext>): ChatTurnInputPatch | void | Promise<ChatTurnInputPatch | void>;
     /** Deterministic run telemetry (start / complete / error) with identity and
      *  timing. Omit → no telemetry. */
@@ -494,7 +589,18 @@ interface CreateChatTurnRoutesOptions<TContext = void> {
      *  before any heartbeat injection (the raw sidecar-producer events, for
      *  telemetry). Never alters the stream; errors are swallowed. Distinct from
      *  `onEvent`, which sees the engine-framed stream incl. lifecycle envelopes.
-     *  @experimental Single-consumer (gtm, #200); shape may change. */
+     *
+     *  Settled shape (#227). What a consumer may depend on:
+     *  - it sees EXACTLY the producer's own events — no engine lifecycle
+     *    envelopes, and no injected keepalives (`heartbeat` wraps the stream
+     *    downstream of this tap, so a synthetic event never reaches a trace);
+     *  - a throw is caught and logged, never surfaced: a broken telemetry sink
+     *    cannot fail a turn or truncate the client's stream;
+     *  - it is an OBSERVER — the return value is ignored, and the event object
+     *    continues downstream. Mutating it mutates the stream; don't.
+     *
+     *  Takes `(event, context)` rather than one args object, matching both
+     *  shipped consumers; see the module header on why it stays that way. */
     onRawEvent?(event: ChatRouteEvent, context: TContext): void | Promise<void>;
     /** Pre-persist transform of the final text (e.g. `/redact`'s `redactPII`).
      *  Live stream is never altered. */
@@ -534,20 +640,7 @@ interface CreateChatTurnRoutesOptions<TContext = void> {
      *  than billing an empty turn and marking it done. A turn that THROWS never
      *  reaches this hook (the engine skips it on a producer throw). Errors are
      *  swallowed by the engine — they never fail a streamed turn. */
-    onTurnComplete?(input: {
-        identity: ChatTurnIdentity;
-        finalText: string;
-        context: TContext;
-        failed: boolean;
-        failureReason?: string;
-        /** The model that SERVED this turn. With failover wired it may differ from
-         *  the requested one, so a product that bills or scores per model MUST read
-         *  it here rather than assuming the model it asked for. */
-        model?: string;
-        /** Present when the producer supports failover: the full attempt trail, and
-         *  `usedFallback` — the flag that makes a silent downgrade impossible. */
-        modelFailover?: ChatTurnModelFailover;
-    }): Promise<void>;
+    onTurnComplete?(input: ChatTurnCompleteInput<TContext>): Promise<void>;
     /** Per-event side channel (product broadcast). The turn-buffer tap is
      *  already wired; this runs in addition. */
     onEvent?(event: {
@@ -1517,4 +1610,4 @@ interface PromoteAgentFilePartOptions {
 /** Promote a part of an agent file with optional byte limits and MIME type detection */
 declare function promoteAgentFilePart(options: PromoteAgentFilePartOptions): Promise<PromoteFilePartResult>;
 
-export { type AssistantDraftSnapshot, type AssistantDraftStore, type AssistantDraftWriter, type AssistantDraftWriterOptions, type AssistantRowValues, type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentUploadAuthorization, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, type ChatTurnModelFailover, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnParts, type DetachedTurnResult, type DispatchPartsOutcome, type DraftPersistenceTuning, type DraftStoredMessage, type FilePartPromotionOutcome, type ModelFailoverStreamHandle, type ModelFailoverStreamOptions, type ModelFallbackInfo, type OpenModelStream, PROMOTE_MAX_FILE_BYTES, type PromoteAgentFilePartOptions, type PromoteFilePartResult, PromptInputPart, type RawAgentFilePart, type ReadAttachmentFn, type ReadSandboxMentionFn, type ResolveChatAttachmentsOptions, type ResolveChatAttachmentsResult, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, type WriteAttachmentFn, assistantRowIdForTurn, buildDispatchParts, bytesToBase64, classifyTerminalFailure, createAssistantDraftWriter, createAttachmentUploadRoute, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, isCommittingSandboxEvent, isDraftContentEvent, promoteAgentFilePart, resolveChatAttachments, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, withDurableChatProjection };
+export { type AssistantDraftSnapshot, type AssistantDraftStore, type AssistantDraftWriter, type AssistantDraftWriterOptions, type AssistantRowValues, type AttachmentPathArgs, type AttachmentPathCheck, type AttachmentReadResult, type AttachmentUploadAuthorization, type AttachmentWriteResult, type BuildDispatchPartsInput, ChatAttachmentKind, type ChatRouteDurableProjection, type ChatRouteDurableProjectionLogger, type ChatRouteEvent, type ChatTurnAuthorization, type ChatTurnAuthorizeArgs, type ChatTurnCompleteInput, ChatTurnFilePartInput, type ChatTurnGateResult, type ChatTurnHeartbeat, type ChatTurnInputPatch, type ChatTurnLifecycle, type ChatTurnLifecycleComplete, type ChatTurnLifecycleError, type ChatTurnLifecycleStart, type ChatTurnLock, type ChatTurnLockResult, type ChatTurnMessageStore, type ChatTurnModelFailover, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnParts, type DetachedTurnResult, type DispatchPartsOutcome, type DraftPersistenceTuning, type DraftStoredMessage, type FilePartPromotionOutcome, type ModelFailoverStreamHandle, type ModelFailoverStreamOptions, type ModelFallbackInfo, type OpenModelStream, PROMOTE_MAX_FILE_BYTES, type PromoteAgentFilePartOptions, type PromoteFilePartResult, PromptInputPart, type RawAgentFilePart, type ReadAttachmentFn, type ReadSandboxMentionFn, type ResolveChatAttachmentsOptions, type ResolveChatAttachmentsResult, type SandboxChatProducerOptions, type SandboxUploadSink, UPLOAD_INLINE_MAX_BYTES, UPLOAD_MAX_FILE_BYTES, type UploadAuthorization, type UploadedChatFile, type WriteAttachmentFn, assistantRowIdForTurn, buildDispatchParts, bytesToBase64, classifyTerminalFailure, createAssistantDraftWriter, createAttachmentUploadRoute, createChatTurnRoutes, createSandboxChatProducer, createUploadRoute, defaultValidateAttachmentPath, isCommittingSandboxEvent, isDraftContentEvent, promoteAgentFilePart, resolveChatAttachments, rowIdOf, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, withDurableChatProjection };

package/dist/chat-routes/index.js

@@ -31,7 +31,7 @@ import {
   normalizeClientTurnId,
   replayTurnEvents,
   resolveChatTurn
-} from "../chunk-YN7QR7MJ.js";
+} from "../chunk-RK2MKLBT.js";
 import {
   createInteractionAnswerRoute
 } from "../chunk-3JUTOVUH.js";
@@ -216,8 +216,7 @@ function createAssistantDraftWriter(options) {
       role: "assistant",
       ...values
     });
-    const insertedId = inserted?.id;
-    rowId = typeof insertedId === "string" && insertedId ? insertedId : options.messageId;
+    rowId = rowIdOf(inserted) ?? options.messageId;
     writes += 1;
   }
   function trigger() {
@@ -284,6 +283,10 @@ function createAssistantDraftWriter(options) {
 function storeSupportsDraftPersistence(store) {
   return typeof store.updateMessage === "function";
 }
+function rowIdOf(inserted) {
+  const id = inserted?.id;
+  return typeof id === "string" && id ? id : null;
+}
 function assistantRowIdForTurn(turnKey) {
   return `assistant:${turnKey}`;
 }
@@ -464,6 +467,8 @@ function createChatTurnRoutes(options) {
     }
     let producer;
     let draft;
+    let assistantMessageId;
+    const assistantRowId = () => assistantMessageId ?? draft?.rowId() ?? null;
     let runFailed = false;
     let lastFailureData;
     let turnStartedAtMs = 0;
@@ -495,6 +500,7 @@ function createChatTurnRoutes(options) {
             durationMs,
             finalText: producer?.finalText() ?? "",
             usage: producer?.usage?.() ?? {},
+            assistantMessageId: assistantRowId(),
             ...producer?.model ? { model: producer.model } : {},
             ...failoverInfo ? { modelFailover: failoverInfo } : {}
           });
@@ -508,14 +514,18 @@ function createChatTurnRoutes(options) {
     };
     try {
       const insertUserMessage = chatTurn.shouldInsertUserMessage && (auth.insertUserMessage ?? true);
+      let userMessageId = chatTurn.reusedUserMessageId ?? null;
       if (insertUserMessage) {
-        await options.store.appendMessage({
-          threadId: payload.threadId,
-          role: "user",
-          content,
-          parts: userPartsWithFiles(chatTurn.userParts, fileParts, mentions)
-        });
+        userMessageId = rowIdOf(
+          await options.store.appendMessage({
+            threadId: payload.threadId,
+            role: "user",
+            content,
+            parts: userPartsWithFiles(chatTurn.userParts, fileParts, mentions)
+          })
+        );
       }
+      produceArgs = { ...produceArgs, userMessageId };
       if (options.contextGate) {
         const gate = await options.contextGate(produceArgs);
         if (!gate.proceed) {
@@ -613,6 +623,7 @@ function createChatTurnRoutes(options) {
             const parts = projected ? toChatMessageParts(projected) : void 0;
             if (!finalText.trim() && (!parts || parts.length === 0)) {
               await draft?.discard();
+              assistantMessageId = draft?.rowId() ?? null;
               return;
             }
             const usage = producer?.usage?.() ?? {};
@@ -629,13 +640,16 @@ function createChatTurnRoutes(options) {
             };
             if (draft) {
               await draft.finalize(values);
+              assistantMessageId = draft.rowId() ?? null;
               return;
             }
-            await options.store.appendMessage({
-              threadId: payload.threadId,
-              role: "assistant",
-              ...values
-            });
+            assistantMessageId = rowIdOf(
+              await options.store.appendMessage({
+                threadId: payload.threadId,
+                role: "assistant",
+                ...values
+              })
+            );
           },
           ...options.onTurnComplete ? {
             // Wired into the engine's completion hook, which fires only when
@@ -650,6 +664,7 @@ function createChatTurnRoutes(options) {
                 finalText,
                 context,
                 failed: runFailed,
+                assistantMessageId: assistantRowId(),
                 ...runFailed ? { failureReason: failureReasonOf(lastFailureData) } : {},
                 ...producer?.model ? { model: producer.model } : {},
                 ...failoverInfo ? { modelFailover: failoverInfo } : {}
@@ -2288,6 +2303,7 @@ export {
   promptPartsByteSize,
   reconcileStaleTurnLock,
   resolveChatAttachments,
+  rowIdOf,
   runDetachedTurn,
   sanitizeAttachmentFileName,
   sanitizeUploadFilename,