@tangle-network/agent-app 0.60.198 → 0.60.200

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

@@ -55,6 +55,7 @@ import { type InteractionAnswerRoute, type InteractionAnswerRouteOptions } from
 import { type PersistedChatMessageForTurn, type TurnEventStore } from '../stream/index';
 import type { ModelFailoverAttempt } from '../model-resolution/failover';
 import { type ModelPolicy } from '../policy-filters/index';
+import { type TurnSpanAttrs, type TurnTrace, type TurnTraceSink, type TurnTraceSummary } from '../turn-trace/recorder';
 import { type TurnRoutePhase } from './turn-progress';
 import { type ChatTurnPartInput, type ChatTurnRequestPayload } from './wire';
 /** Usage receipt persisted onto the assistant message (the flattened
@@ -261,6 +262,14 @@ export interface ChatTurnProduceArgs<TContext> {
     intentLine?: Promise<string | null>;
     /** Server-authenticated limits for this turn. Never copied from the body. */
     executionLimits?: ChatTurnExecutionLimits;
+    /**
+     * The turn's trace (`@tangle-network/agent-app/turn-trace`), bound to this turn's execution id. Pass it to the
+     * Router engine (`trace`), `streamSandboxPrompt` and `ensureWorkspaceSandbox` so the turn's model calls, tool
+     * calls and box claim are recorded under it; its `traceId` is what those calls send as `x-tangle-trace-id`.
+     * The route records admission and persistence itself. Optional for source compatibility with synthetic
+     * producers; every `createChatTurnRoutes` invocation supplies it.
+     */
+    trace?: TurnTrace;
     /** 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
@@ -367,6 +376,8 @@ interface ChatTurnLifecycleBase<TContext> {
 /** When the turn's first visible word streamed, measured from `onTurnStart`. Absent when no word streamed. */
 interface ChatTurnLifecycleTiming {
     firstTextMs?: number;
+    /** Where the turn's wall time went: its share inside named spans and the time per kind of span. */
+    trace?: TurnTraceSummary;
 }
 /** Define lifecycle start event with context and timestamp for a chat turn */
 export interface ChatTurnLifecycleStart<TContext> extends ChatTurnLifecycleBase<TContext> {
@@ -453,6 +464,16 @@ export interface ChatTurnCompleteInput<TContext> {
      *  same id as `DetachedTurnResult.messageId`. */
     assistantMessageId: string | null;
 }
+/** Where a finished turn's trace goes, and the host's labels for its root span. Metadata only: never content. */
+export interface ChatTurnTraceOptions<TContext> {
+    sink?: TurnTraceSink;
+    /** Labels for the root span, e.g. the workspace id. Called once per exported turn. */
+    labels?(info: {
+        identity: ChatTurnIdentity;
+        executionId: string;
+        context: TContext;
+    }): TurnSpanAttrs;
+}
 /** Define options to configure chat turn routes including authorization, storage, and event buffering */
 export interface CreateChatTurnRoutesOptions<TContext = void> {
     /** Names the product in `deriveExecutionId` so retries land on the same
@@ -606,6 +627,13 @@ export interface CreateChatTurnRoutesOptions<TContext = void> {
     }, context: TContext): void | Promise<void>;
     /** Trace flush handed to `waitUntil` (OTLP export). */
     traceFlush?(context: TContext): Promise<void>;
+    /**
+     * Where each finished turn's trace goes (`createIntelligenceTurnTraceSink`). The route always records the
+     * turn's trace (`ChatTurnProduceArgs.trace`) and reports its summary to `lifecycle`; this sends the spans on.
+     * The sink runs under `waitUntil` after the lifecycle hooks, and its failure never fails a turn. A turn handed
+     * to a durable owner (`handoffCompletion`) is exported by that owner, not here.
+     */
+    turnTrace?: ChatTurnTraceOptions<TContext>;
     /** Compose the interaction-answer endpoints (`/interactions`). Omit when the
      *  product has no sidecar ask channel. */
     interactions?: InteractionAnswerRouteOptions;

package/dist/{chunk-XJEIGVMQ.js → chunk-2OWT3TNV.js}

@@ -1,6 +1,6 @@
 import {
   runRouterTurn
-} from "./chunk-FPOOBGRG.js";
+} from "./chunk-T4BLISYH.js";
 
 // src/runtime/protected-model.ts
 import {
@@ -219,4 +219,4 @@ export {
   createRouterProtectedModelPort,
   runProtectedRouterTurn
 };
-//# sourceMappingURL=chunk-XJEIGVMQ.js.map
+//# sourceMappingURL=chunk-2OWT3TNV.js.map

package/dist/{chunk-XP77DJEF.js → chunk-6XXKFYIM.js}

@@ -34,6 +34,9 @@ import {
 import {
   checkModelPolicy
 } from "./chunk-XELWWXJJ.js";
+import {
+  createTurnTrace
+} from "./chunk-BKPJFES3.js";
 
 // src/chat-routes/draft-persistence.ts
 var CONTENT_EVENT_TYPES = /* @__PURE__ */ new Set([
@@ -378,12 +381,13 @@ function createChatTurnRoutes(options) {
     return Promise.race([generated, deadline]).finally(() => clearTimeout(timer));
   }
   async function turn(request, ctx) {
-    const admitted = await admitTurn(request);
+    const admitted = await admitTurn(request, createTurnTrace());
     if (!admitted.ok) return admitted.response;
     if (request.headers.get(TURN_PROGRESS_HEADER) !== TURN_PROGRESS_FIRST) return runTurn(request, ctx, admitted);
     return progressFirstTurn(request, ctx, admitted);
   }
-  async function admitTurn(request) {
+  async function admitTurn(request, trace) {
+    const parse = trace.start("admission.parse", "admission");
     const [rawBody, badBody] = await parseJsonObjectBody(request);
     if (badBody) return { ok: false, response: badBody };
     let parsed;
@@ -393,21 +397,23 @@ function createChatTurnRoutes(options) {
       if (err instanceof ChatTurnInputError) return { ok: false, response: errorResponse(err) };
       throw err;
     }
-    const auth = await options.authorize({ request, intent: "turn", body: parsed.payload });
+    parse.end();
+    const auth = await trace.measure("admission.authorize", "admission", () => options.authorize({ request, intent: "turn", body: parsed.payload }));
     if (!auth.ok) return { ok: false, response: auth.response };
     const namedModel = typeof parsed.payload.model === "string" ? parsed.payload.model.trim() : "";
-    if (options.modelPolicy && namedModel) {
-      const decision = await checkModelPolicy(
+    const policy = options.modelPolicy;
+    if (policy && namedModel) {
+      const decision = await trace.measure("admission.model_policy", "admission", () => checkModelPolicy(
         namedModel,
-        options.modelPolicy.catalog,
-        options.modelPolicy.filter,
-        options.modelPolicy.context
-      );
+        policy.catalog,
+        policy.filter,
+        policy.context
+      ));
       if (!decision.allowed) {
         return { ok: false, response: Response.json({ code: "model_policy_denied", error: decision.reason }, { status: 403 }) };
       }
     }
-    return { ok: true, parsed, auth };
+    return { ok: true, parsed, auth, trace };
   }
   function progressFirstTurn(request, ctx, admitted) {
     const receivedAt = Date.now();
@@ -490,7 +496,7 @@ function createChatTurnRoutes(options) {
     });
   }
   async function runTurn(request, ctx, admitted, progress, startedIntent) {
-    const { parsed, auth } = admitted;
+    const { parsed, auth, trace } = admitted;
     const intentLine = startedIntent ?? startIntentLine(admitted);
     const { payload, content, fileParts, mentions, turnId } = parsed;
     const { tenantId, userId, context } = auth;
@@ -503,8 +509,9 @@ function createChatTurnRoutes(options) {
         log("[chat-routes] turnLock.warm failed", { error: err instanceof Error ? err.message : String(err) });
       }
     }
-    if (options.prepareTurn) {
-      const prepared = await options.prepareTurn({
+    const prepareTurn = options.prepareTurn;
+    if (prepareTurn) {
+      const prepared = await trace.measure("admission.prepare", "admission", () => prepareTurn({
         request,
         body: payload,
         tenantId,
@@ -512,7 +519,7 @@ function createChatTurnRoutes(options) {
         threadId: payload.threadId,
         context,
         progress: (phase, message) => progress?.(phase, message)
-      });
+      }));
       if (!prepared.ok) return prepared.response;
     }
     const readHistory = async () => (await options.store.listMessages(payload.threadId)).map((m) => ({
@@ -521,6 +528,7 @@ function createChatTurnRoutes(options) {
       content: m.content,
       parts: m.parts ?? null
     }));
+    const historySpan = trace.start("admission.history", "admission");
     const existingMessages = await readHistory();
     const historyBeforeLock = options.turnLock ? JSON.stringify(existingMessages) : void 0;
     let hasRunningTurn = false;
@@ -534,6 +542,7 @@ function createChatTurnRoutes(options) {
         });
       }
     }
+    historySpan.end();
     const chatTurn = resolveChatTurn({ existingMessages, userContent: content, turnId, hasRunningTurn });
     const identity = {
       tenantId,
@@ -548,6 +557,7 @@ function createChatTurnRoutes(options) {
     });
     const executionId = payload.retryAttemptId ? `${turnExecutionId}:retry:${payload.retryAttemptId}` : turnExecutionId;
     if (executionId.length > 256) return errorResponse(new ChatTurnInputError("Retry execution id exceeds 256 bytes"));
+    trace.bind(executionId);
     const turnStreamId = crypto.randomUUID();
     const prompt = fileParts.length === 0 ? content : content ? [{ type: "text", text: content }, ...fileParts] : [...fileParts];
     let draft;
@@ -581,6 +591,7 @@ function createChatTurnRoutes(options) {
       turnStreamId,
       priorMessages: chatTurn.priorMessages,
       handoffCompletion,
+      trace,
       ...intentLine ? { intentLine } : {},
       ...ctx?.executionLimits ? { executionLimits: ctx.executionLimits } : {}
     };
@@ -599,8 +610,9 @@ function createChatTurnRoutes(options) {
         });
       }
     };
-    if (options.turnLock) {
-      const acquired = await options.turnLock.acquire(produceArgs);
+    const turnLock = options.turnLock;
+    if (turnLock) {
+      const acquired = await trace.measure("admission.lock", "admission", () => turnLock.acquire(produceArgs));
       if (!acquired.acquired) return acquired.response;
       lockAcquired = true;
       lockHandle = acquired.handle;
@@ -619,12 +631,17 @@ function createChatTurnRoutes(options) {
     const fireTerminalLifecycle = async (failed, terminalError) => {
       if (lifecycleSettled) return;
       lifecycleSettled = true;
+      const failureCode = failed ? failureCodeOf(lastFailureData) ?? (terminalError instanceof Error ? terminalError.name : "turn_failed") : void 0;
+      const snapshot = trace.finish(failureCode === void 0 ? {} : { error: failureCode });
       const lifecycle = options.lifecycle;
-      if (!lifecycle) return;
       const durationMs = Date.now() - turnStartedAtMs;
-      const timing = firstTextAtMs === void 0 ? {} : { firstTextMs: firstTextAtMs - turnStartedAtMs };
+      const timing = {
+        ...firstTextAtMs === void 0 ? {} : { firstTextMs: firstTextAtMs - turnStartedAtMs },
+        trace: snapshot.summary
+      };
       try {
-        if (failed) {
+        if (!lifecycle) {
+        } else if (failed) {
           await lifecycle.onTurnError?.({
             identity,
             executionId,
@@ -662,9 +679,28 @@ function createChatTurnRoutes(options) {
           error: err instanceof Error ? err.message : String(err)
         });
       }
+      const traceOptions = options.turnTrace;
+      if (traceOptions?.sink) {
+        try {
+          await traceOptions.sink(snapshot, {
+            "tangle.sessionId": identity.sessionId,
+            "tangle.userId": identity.userId,
+            "tangle.tenantId": identity.tenantId,
+            "tangle.turn.failed": failed,
+            ...gatedTurn ? { "tangle.turn.gated": true } : {},
+            ...failureCode ? { "tangle.turn.failure_code": failureCode } : {},
+            ...traceOptions.labels?.({ identity, executionId, context }) ?? {}
+          });
+        } catch (err) {
+          log("[chat-routes] turn trace sink failed", {
+            turnId: turnStreamId,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        }
+      }
     };
     try {
-      if (lockAcquired && JSON.stringify(await readHistory()) !== historyBeforeLock) {
+      if (lockAcquired && JSON.stringify(await trace.measure("admission.history_recheck", "admission", readHistory)) !== historyBeforeLock) {
         await releaseLock();
         return Response.json({
           code: "chat_history_changed",
@@ -675,17 +711,18 @@ function createChatTurnRoutes(options) {
       let userMessageId = chatTurn.reusedUserMessageId ?? null;
       if (insertUserMessage) {
         userMessageId = rowIdOf(
-          await options.store.appendMessage({
+          await trace.measure("admission.persist_user", "admission", () => 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);
+      const contextGate = options.contextGate;
+      if (contextGate) {
+        const gate = await trace.measure("admission.gate", "admission", () => contextGate(produceArgs));
         if (gate.proceed === "handoff") {
           await releaseLock();
           return gate.response;
@@ -715,10 +752,12 @@ function createChatTurnRoutes(options) {
           return gate.response;
         }
       }
-      if (options.beforeTurn) {
-        const patch = await options.beforeTurn(produceArgs);
+      const beforeTurn = options.beforeTurn;
+      if (beforeTurn) {
+        const patch = await trace.measure("admission.before_turn", "admission", () => beforeTurn(produceArgs));
         if (patch) produceArgs = { ...produceArgs, ...patch };
       }
+      const streamSetup = trace.start("admission.stream_setup", "admission");
       tap = createBufferedTurnTap({
         store: options.turnStore,
         turnId: turnStreamId,
@@ -766,6 +805,7 @@ function createChatTurnRoutes(options) {
           });
         }
       }
+      streamSetup.end();
       const result = handleChatTurn({
         identity,
         waitUntil: ctx?.waitUntil,
@@ -775,7 +815,7 @@ function createChatTurnRoutes(options) {
           // defer it into the generator's first pull.
           produce: () => ({
             stream: (async function* () {
-              producer = await options.produce(produceArgs);
+              producer = await trace.measure("admission.produce", "admission", () => options.produce(produceArgs));
               let source = producer.stream;
               if (ctx?.cancelOnDisconnect) {
                 source = abortOnSignal(source, request.signal);
@@ -801,7 +841,7 @@ function createChatTurnRoutes(options) {
             if (options.onEvent) await options.onEvent(event, context);
           },
           ...options.transformFinalText ? { transformFinalText: options.transformFinalText } : {},
-          persistAssistantMessage: async ({ finalText }) => {
+          persistAssistantMessage: ({ finalText }) => trace.measure("persist.assistant", "persist", async () => {
             if (completionHandoff) return;
             if (ctx?.cancelOnDisconnect && request.signal.aborted) {
               await draft?.discard();
@@ -849,7 +889,7 @@ function createChatTurnRoutes(options) {
                 ...values
               })
             );
-          },
+          }),
           ...options.onTurnComplete ? {
             // Wired into the engine's completion hook, which fires only when
             // the stream ended without throwing. A terminal error EVENT
@@ -901,6 +941,7 @@ function createChatTurnRoutes(options) {
           await tap.detach();
           return;
         }
+        const finalize = trace.start("persist.finalize", "persist");
         if (ctx?.cancelOnDisconnect && request.signal.aborted) {
           await draft?.discard();
         } else {
@@ -914,6 +955,7 @@ function createChatTurnRoutes(options) {
             error: err instanceof Error ? err.message : String(err)
           });
         }
+        finalize.end();
         await fireTerminalLifecycle(failed, drainError);
         await releaseLock();
       })();
@@ -1285,4 +1327,4 @@ export {
   createChatTurnRoutes,
   streamChatRouteAsSandboxEvents
 };
-//# sourceMappingURL=chunk-XP77DJEF.js.map
+//# sourceMappingURL=chunk-6XXKFYIM.js.map