@tangle-network/agent-app 0.44.54 → 0.44.55

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

@@ -9,13 +9,13 @@ import { T as TurnEventStore } from '../turn-buffer-COMQUwO2.js';
 import { M as ModelFailoverAttempt } from '../failover-D-3UXXTb.js';
 export { D as DEFAULT_STALE_TURN_LOCK_GRACE_MS, a as DEFAULT_TERMINAL_TURN_LOCK_GRACE_MS, R as ReconcileStaleTurnLockOptions, b as ReconcileStaleTurnLockResult, S as StaleTurnLockSandboxProbeResult, c as StaleTurnLockSessionProbeResult, r as reconcileStaleTurnLock } from '../stale-turn-lock-DucQzvXu.js';
 import { J as JsonRecord } from '../stream-normalizer-CnPnMaTp.js';
+import { SandboxInstance } from '@tangle-network/sandbox';
 import { SandboxExecChannel, PromptInputPart } from '../sandbox/index.js';
 import '@tangle-network/agent-interface';
 import '../contract-CQNvv5th.js';
 import '../types-CCeYywdS.js';
 import '../plans/index.js';
 import '@tangle-network/sandbox/core';
-import '@tangle-network/sandbox';
 import '../auth-DJs6lfAs.js';
 import '../types-DbU-oO5h.js';
 import '../harness/index.js';
@@ -1086,9 +1086,10 @@ type DetachedTurnParts = Array<Record<string, unknown>>;
 interface DetachedTurnFinal {
     text?: string;
     usage?: ChatTurnUsage;
-    /** The structured parts to persist when this receipt IS the result (the
-     *  cached / finished-server-side path). Omitted when the record only carries
-     *  a usage receipt. */
+    /** The structured parts to persist when this receipt is more complete than
+     *  the live stream (cached, finished server-side, or a fast stream that
+     *  delivered scalar text before its message-part events). Omitted when the
+     *  record only carries a usage receipt. */
     parts?: DetachedTurnParts;
 }
 /** Define options for managing and projecting a detached turn event stream in a session */
@@ -1142,8 +1143,10 @@ interface DetachedTurnOptions {
     /** Authoritative final receipt, consulted whenever a re-invoke finds a prior
      *  buffer: (a) an already-`complete` turn returns it as the cached result,
      *  (b) a `running` turn (crash mid-run) uses it to detect a run that finished
-     *  server-side, and (c) a clean run whose stream carried no usage/text falls
-     *  back to it. Typically `() => box.findCompletedTurn(turnId)`. */
+     *  server-side, and (c) a clean run whose stream carried no usage or only
+     *  scalar text falls back to it. For Sandbox runs, use
+     *  `readCompletedSandboxTurn` so the exact completed session message
+     *  restores tool/file parts as well as text. */
     completedResult?: () => Promise<DetachedTurnFinal | null | undefined>;
     /** Clear the prior partial buffer for `turnId` before a genuine re-stream.
      *  A crash mid-run leaves buffered rows at seqs 1..N with status `running`;
@@ -1236,6 +1239,31 @@ interface DetachedTurnResult {
  */
 declare function runDetachedTurn(opts: DetachedTurnOptions): Promise<DetachedTurnResult>;
 
+/**
+ * Recover a detached Sandbox turn from its durable completed records.
+ *
+ * A fast detached run can finish before the live event subscriber receives
+ * every message-part event. The Sandbox still retains two exact records: a
+ * turn-id keyed result cache and the completed assistant message on the
+ * session. This adapter joins them without guessing across turns, then returns
+ * the same `DetachedTurnFinal` shape `runDetachedTurn` already consumes.
+ */
+
+/** The official Sandbox methods needed for completed-turn recovery. */
+type CompletedSandboxTurnSource = Pick<SandboxInstance, 'findCompletedTurn' | 'session'>;
+/** Options for resolving one exact detached turn. */
+interface ReadCompletedSandboxTurnOptions {
+    turnId: string;
+    sessionId: string;
+    log?: (message: string, meta?: Record<string, unknown>) => void;
+}
+/**
+ * Read the exact completed turn. The session-level result is consulted only
+ * when the matching completed assistant message is still the latest message;
+ * otherwise that result could belong to a newer turn on the same session.
+ */
+declare function readCompletedSandboxTurn(box: CompletedSandboxTurnSource, options: ReadCompletedSandboxTurnOptions): Promise<DetachedTurnFinal | null>;
+
 /** Resolve chat route events and materialize their durable state records */
 interface ChatRouteDurableProjection {
     observe(event: unknown): void | Promise<void>;
@@ -1755,4 +1783,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 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 ChatTurnModelAttribution, 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 EmptyTurnRetryInfo, type FilePartPromotionOutcome, MAX_EMPTY_TURN_RETRIES, 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, normalizeChatPromptForSandbox, promoteAgentFilePart, resolveChatAttachments, resolveEmptyTurnRetries, rowIdOf, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, summarizeFailoverReason, 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 ChatTurnModelAttribution, type ChatTurnModelFailover, ChatTurnPartInput, type ChatTurnProduceArgs, ChatTurnRequestPayload, type ChatTurnRouteProducer, type ChatTurnRoutes, type ChatTurnUsage, type CompletedSandboxTurnSource, type CreateAttachmentUploadRouteOptions, type CreateChatTurnRoutesOptions, type CreateUploadRouteOptions, type DetachedTurnFinal, type DetachedTurnOptions, type DetachedTurnParts, type DetachedTurnResult, type DispatchPartsOutcome, type DraftPersistenceTuning, type DraftStoredMessage, type EmptyTurnRetryInfo, type FilePartPromotionOutcome, MAX_EMPTY_TURN_RETRIES, type ModelFailoverStreamHandle, type ModelFailoverStreamOptions, type ModelFallbackInfo, type OpenModelStream, PROMOTE_MAX_FILE_BYTES, type PromoteAgentFilePartOptions, type PromoteFilePartResult, PromptInputPart, type RawAgentFilePart, type ReadAttachmentFn, type ReadCompletedSandboxTurnOptions, 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, normalizeChatPromptForSandbox, promoteAgentFilePart, readCompletedSandboxTurn, resolveChatAttachments, resolveEmptyTurnRetries, rowIdOf, runDetachedTurn, sanitizeUploadFilename, sniffMimeFromName, storeSupportsDraftPersistence, streamWithModelFailover, summarizeFailoverReason, withDurableChatProjection };

package/dist/chat-routes/index.js

@@ -66,6 +66,7 @@ import {
 import {
   asRecord,
   asString,
+  collapseRedundantTextParts,
   draftAssistantParts,
   finalizeAssistantParts,
   finalizePendingInteractionParts,
@@ -1027,6 +1028,28 @@ function streamWithModelFailover(options) {
   };
 }
 
+// src/chat-routes/sandbox-turn-usage.ts
+function addStepFinishUsage(part, usage) {
+  const tokens = asRecord(part.tokens);
+  if (tokens) {
+    const cache = asRecord(tokens.cache);
+    const add = (current, value) => {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return current;
+      return (current ?? 0) + n;
+    };
+    usage.inputTokens = add(usage.inputTokens, tokens.input);
+    usage.outputTokens = add(usage.outputTokens, tokens.output);
+    usage.reasoningTokens = add(usage.reasoningTokens, tokens.reasoning);
+    if (cache) {
+      usage.cacheReadTokens = add(usage.cacheReadTokens, cache.read);
+      usage.cacheWriteTokens = add(usage.cacheWriteTokens, cache.write);
+    }
+  }
+  const cost = Number(part.cost);
+  if (Number.isFinite(cost)) usage.costUsd = (usage.costUsd ?? 0) + cost;
+}
+
 // src/chat-routes/sandbox-producer.ts
 function textDelta(tracker, key, part, rawDelta) {
   const explicit = typeof rawDelta === "string" ? rawDelta : void 0;
@@ -1058,26 +1081,6 @@ function parseEffectiveBackend(data) {
     ...source ? { servedSource: source } : {}
   };
 }
-function usageFromStepFinish(part, usage) {
-  const tokens = asRecord(part.tokens);
-  if (tokens) {
-    const cache = asRecord(tokens.cache);
-    const add = (current, value) => {
-      const n = Number(value);
-      if (!Number.isFinite(n)) return current;
-      return (current ?? 0) + n;
-    };
-    usage.inputTokens = add(usage.inputTokens, tokens.input);
-    usage.outputTokens = add(usage.outputTokens, tokens.output);
-    usage.reasoningTokens = add(usage.reasoningTokens, tokens.reasoning);
-    if (cache) {
-      usage.cacheReadTokens = add(usage.cacheReadTokens, cache.read);
-      usage.cacheWriteTokens = add(usage.cacheWriteTokens, cache.write);
-    }
-  }
-  const cost = Number(part.cost);
-  if (Number.isFinite(cost)) usage.costUsd = (usage.costUsd ?? 0) + cost;
-}
 function toFiniteNumber(value) {
   if (typeof value === "number") return Number.isFinite(value) ? value : null;
   if (typeof value === "string" && value.trim() !== "") {
@@ -1316,7 +1319,7 @@ function createSandboxChatProducer(options) {
             continue;
           }
           if (partType === "step-finish") {
-            usageFromStepFinish(part, usage);
+            addStepFinishUsage(part, usage);
             recordPersistedPart(part, void 0, `step-finish:#${stepCounter++}`);
             const promptTokens = usage.inputTokens ?? 0;
             const completionTokens = usage.outputTokens ?? 0;
@@ -1558,11 +1561,11 @@ function errorMessageOf(ev) {
 function hasUsage(usage) {
   return typeof usage.inputTokens === "number" && usage.inputTokens > 0;
 }
-function cachedResultFrom(final) {
+function cachedResultFrom(final, persisted) {
   return {
     state: "completed",
-    text: final?.text ?? "",
-    parts: final?.parts ?? [],
+    text: final?.text ?? persisted?.content ?? "",
+    parts: final?.parts ?? persisted?.parts ?? [],
     usage: final?.usage ?? {},
     cached: true
   };
@@ -1571,6 +1574,12 @@ async function runDetachedTurn(opts) {
   const { store, turnId, scopeId } = opts;
   let producer;
   const servingModel = () => producer?.model ?? opts.model;
+  const persistedRow = async () => {
+    if (!opts.persist) return void 0;
+    return (await opts.persist.store.listMessages(opts.persist.threadId)).find(
+      (message) => message.id === (opts.persist?.messageId ?? assistantRowIdForTurn(turnId))
+    );
+  };
   let draft;
   if (opts.persist) {
     const { store: persistStore, threadId, messageId, transformText, ...tuning } = opts.persist;
@@ -1594,10 +1603,8 @@ async function runDetachedTurn(opts) {
       ...opts.log ? { log: opts.log } : {}
     });
   }
-  const settleRow = async (base) => {
-    const persisted = !producer && opts.persist ? (await opts.persist.store.listMessages(opts.persist.threadId)).find(
-      (message) => message.id === (opts.persist?.messageId ?? assistantRowIdForTurn(turnId))
-    ) : void 0;
+  const settleRow = async (base, cachedPersisted) => {
+    const persisted = cachedPersisted ?? (!producer ? await persistedRow() : void 0);
     const info = producer?.modelFailover?.();
     const attribution = producer?.modelAttribution?.();
     const model = producer?.model ?? persisted?.model ?? opts.model;
@@ -1660,14 +1667,21 @@ async function runDetachedTurn(opts) {
   } catch (err) {
     opts.log?.("[chat-routes] runDetachedTurn getStatus failed; treating as no prior", { turnId, err: String(err) });
   }
-  if (prior === "complete") return await settleRow(cachedResultFrom(await completed()));
+  if (prior === "complete") {
+    const persisted = await persistedRow();
+    return await settleRow(
+      cachedResultFrom(await completed(), persisted),
+      persisted
+    );
+  }
   if (prior === "running") {
     const final = await completed();
     if (final) {
       await store.setStatus(turnId, "complete", scopeId).catch((err) => {
         opts.log?.("[chat-routes] runDetachedTurn failed to settle a completed running turn", { turnId, err: String(err) });
       });
-      return await settleRow(cachedResultFrom(final));
+      const persisted = await persistedRow();
+      return await settleRow(cachedResultFrom(final, persisted), persisted);
     }
     if (opts.resetBuffer) {
       await opts.resetBuffer(turnId).catch((err) => {
@@ -1714,17 +1728,171 @@ async function runDetachedTurn(opts) {
   const text = producer.finalText?.() ?? "";
   const parts = producer.assistantParts?.() ?? [];
   let usage = producer.usage?.() ?? {};
-  if (!runError && !hasUsage(usage)) {
+  const onlyTextParts = parts.every(
+    (part) => String(part.type ?? "") === "text"
+  );
+  if (!runError && (!hasUsage(usage) || !text || onlyTextParts)) {
     const final = await completed();
     if (final?.usage) usage = { ...usage, ...final.usage };
-    if (!text && final?.text) {
-      return await settleRow({ state: "completed", text: final.text, parts: final.parts ?? parts, usage, cached: false });
-    }
+    return await settleRow({
+      state: "completed",
+      text: final?.text ?? text,
+      parts: final?.parts?.length ? final.parts : parts,
+      usage,
+      cached: false
+    });
   }
   if (runError) return await settleRow({ state: "failed", text, parts, usage, error: runError, cached: false });
   return await settleRow({ state: "completed", text, parts, usage, cached: false });
 }
 
+// src/chat-routes/completed-sandbox-turn.ts
+function finiteNumber(value) {
+  if (typeof value === "number") return Number.isFinite(value) ? value : void 0;
+  if (typeof value !== "string" || !value.trim()) return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function firstNumber(record, keys) {
+  for (const key of keys) {
+    const value = finiteNumber(record?.[key]);
+    if (value !== void 0) return value;
+  }
+  return void 0;
+}
+function usageFromResult(result) {
+  const raw = asRecord(result?.usage) ?? asRecord(result?.tokenUsage);
+  const inputTokens = firstNumber(raw, ["inputTokens", "promptTokens", "input"]);
+  const outputTokens = firstNumber(raw, ["outputTokens", "completionTokens", "output"]);
+  const reasoningTokens = firstNumber(raw, ["reasoningTokens", "reasoning"]);
+  const cacheReadTokens = firstNumber(raw, [
+    "cacheReadTokens",
+    "cacheReadInputTokens",
+    "cacheRead"
+  ]);
+  const cacheWriteTokens = firstNumber(raw, [
+    "cacheWriteTokens",
+    "cacheCreationInputTokens",
+    "cacheWrite"
+  ]);
+  const costUsd = firstNumber(result, ["costUsd", "totalCostUsd", "cost"]) ?? firstNumber(raw, ["costUsd", "cost"]);
+  return {
+    ...inputTokens !== void 0 ? { inputTokens } : {},
+    ...outputTokens !== void 0 ? { outputTokens } : {},
+    ...reasoningTokens !== void 0 ? { reasoningTokens } : {},
+    ...cacheReadTokens !== void 0 ? { cacheReadTokens } : {},
+    ...cacheWriteTokens !== void 0 ? { cacheWriteTokens } : {},
+    ...costUsd !== void 0 ? { costUsd } : {}
+  };
+}
+function textFromResult(result) {
+  return asString(result?.response) ?? asString(result?.finalText) ?? asString(result?.text) ?? asString(result?.output);
+}
+function completedMessagesForTurn(messages, turnId) {
+  return messages.filter(
+    (message) => message.role === "assistant" && message.metadata?.turnId === turnId && message.metadata?.interrupted !== true && (message.metadata?.completed === true || message.metadata?.status === "completed")
+  );
+}
+function normalizedMessageParts(message) {
+  const normalized = [];
+  const usage = {};
+  for (const raw of message.parts) {
+    const record = asRecord(raw);
+    if (!record) continue;
+    const part = normalizePersistedPart(record);
+    if (!part) continue;
+    normalized.push(part);
+    if (part.type === "step-finish") addStepFinishUsage(part, usage);
+  }
+  const collapsed = collapseRedundantTextParts(normalized);
+  const derivedText = collapsed.filter((part) => part.type === "text").map((part) => String(part.text ?? "")).join("");
+  return { parts: normalized, usage, derivedText };
+}
+function projectMessageParts(parts, finalText) {
+  const order = [];
+  const map = /* @__PURE__ */ new Map();
+  for (let index = 0; index < parts.length; index += 1) {
+    const part = parts[index];
+    const type = String(part.type ?? "");
+    const key = type === "step-start" || type === "step-finish" ? `${type}:#${index}` : getPartKey(part);
+    if (!map.has(key)) order.push(key);
+    map.set(key, mergePersistedPart(map.get(key), part));
+  }
+  return finalizeAssistantParts(order, map, finalText);
+}
+function hasUsage2(usage) {
+  return Object.values(usage).some(
+    (value) => typeof value === "number" && Number.isFinite(value)
+  );
+}
+async function readCompletedSandboxTurn(box, options) {
+  const { turnId, sessionId, log } = options;
+  const session = box.session(sessionId);
+  const [cacheOutcome, messagesOutcome] = await Promise.allSettled([
+    box.findCompletedTurn(turnId, { sessionId }),
+    session.messages({ limit: 1e3 })
+  ]);
+  if (cacheOutcome.status === "rejected") {
+    log?.("[chat-routes] completed Sandbox turn cache lookup failed", {
+      turnId,
+      sessionId,
+      error: String(cacheOutcome.reason)
+    });
+  }
+  if (messagesOutcome.status === "rejected") {
+    log?.("[chat-routes] completed Sandbox session message lookup failed", {
+      turnId,
+      sessionId,
+      error: String(messagesOutcome.reason)
+    });
+  }
+  const rawCached = cacheOutcome.status === "fulfilled" ? cacheOutcome.value : null;
+  const cached = rawCached && rawCached.turnId === turnId && rawCached.sessionId === sessionId ? rawCached : null;
+  if (rawCached && !cached) {
+    log?.("[chat-routes] ignored mismatched completed Sandbox turn cache record", {
+      turnId,
+      sessionId
+    });
+  }
+  const messages = messagesOutcome.status === "fulfilled" ? messagesOutcome.value : [];
+  const matchingMessages = completedMessagesForTurn(messages, turnId);
+  const matchingCount = matchingMessages.length;
+  const message = matchingCount === 1 ? matchingMessages[0] : null;
+  if (matchingCount > 1) {
+    log?.("[chat-routes] ignored ambiguous completed Sandbox session messages", {
+      turnId,
+      sessionId,
+      matchingCount
+    });
+  }
+  if (!cached && !message) return null;
+  let result = cached ? asRecord(cached.result) : void 0;
+  const latestConversationMessage = messages.filter((candidate) => candidate.role === "user" || candidate.role === "assistant").at(-1);
+  if (!result && message && latestConversationMessage === message) {
+    try {
+      result = asRecord(await session.result());
+    } catch (error) {
+      log?.("[chat-routes] completed Sandbox session result lookup failed", {
+        turnId,
+        sessionId,
+        error: String(error)
+      });
+    }
+  }
+  const recovered = message ? normalizedMessageParts(message) : null;
+  const text = textFromResult(result) ?? recovered?.derivedText;
+  const resultUsage = usageFromResult(result);
+  const usage = { ...recovered?.usage ?? {}, ...resultUsage };
+  const resultParts = Array.isArray(result?.parts) ? result.parts.map((part) => asRecord(part)).filter((part) => Boolean(part)).map((part) => normalizePersistedPart(part)).filter((part) => Boolean(part)) : null;
+  const sourceParts = recovered?.parts ?? resultParts;
+  const parts = sourceParts ? projectMessageParts(sourceParts, text ?? recovered?.derivedText ?? "") : void 0;
+  return {
+    ...text !== void 0 ? { text } : {},
+    ...hasUsage2(usage) ? { usage } : {},
+    ...parts ? { parts } : {}
+  };
+}
+
 // src/chat-routes/durable-projection.ts
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -2537,6 +2705,7 @@ export {
   parseFileMentions,
   promoteAgentFilePart,
   promptPartsByteSize,
+  readCompletedSandboxTurn,
   reconcileStaleTurnLock,
   resolveChatAttachments,
   resolveEmptyTurnRetries,