@tangle-network/agent-app 0.43.71 → 0.43.72

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. */
@@ -360,6 +369,20 @@ 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. */
@@ -434,6 +457,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 +479,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
@@ -534,20 +587,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 +1557,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 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,