@agent-native/core 0.129.2 → 0.130.0

package/src/agent/run-manager.ts

@@ -395,6 +395,20 @@ export interface StartRunOptions {
    * callers use it to describe who owns continuation at hosted chunk boundaries.
    */
   dispatchMode?: "foreground" | "foreground-self-chain" | "background";
+  /**
+   * Optional context forwarded onto the terminal-outcome analytics event
+   * (see `emitRunTerminalTrackingEvent`) so run cutoffs can be broken down
+   * by model/engine/user. Run-manager has no way to know these on its own —
+   * the caller (production-agent.ts) knows them but does not thread them
+   * through yet; omitted fields are simply left off the event rather than
+   * defaulted to a placeholder.
+   */
+  model?: string;
+  engineName?: string;
+  userId?: string;
+  /** Continuation/redispatch attempt number for this logical turn, if the
+   *  caller is tracking one. */
+  attemptCount?: number;
 }
 
 export interface ResolveRunSoftTimeoutOptions {
@@ -535,6 +549,80 @@ function terminalReasonForRun(
   return "done";
 }
 
+const MAX_RUN_ERROR_DETAIL_LENGTH = 500;
+
+/**
+ * Emit one analytics event per terminal run — the seam that makes cutoffs
+ * (`run_budget_exhausted`, `loop_limit`, aborts, `truncated` continuation
+ * boundaries) queryable in the same pipeline as `$ai_generation`
+ * (see observability/traces.ts). Same mechanism: dynamic import of
+ * `track()` with every failure swallowed, so a missing/broken tracking
+ * provider can never affect the run or its persisted status. Must be called
+ * AFTER the atomic-complete SQL writes in the `.finally()` boundary above —
+ * never before, and never awaited by it.
+ *
+ * Operational metadata only: no message content, no prompt/response text,
+ * no user email. `errorDetail` carries engine/gateway error strings (e.g.
+ * "context_length_exceeded"), not user-authored text.
+ */
+function emitRunTerminalTrackingEvent(args: {
+  runId: string;
+  threadId: string;
+  turnId: string;
+  status: "completed" | "errored" | "aborted" | "truncated";
+  terminalReason: string;
+  errorCode?: string;
+  errorDetail?: string;
+  dispatchMode?: string;
+  abortReason?: string;
+  durationMs: number;
+  model?: string;
+  engineName?: string;
+  userId?: string;
+  attemptCount?: number;
+}): void {
+  const properties: Record<string, unknown> = {
+    source: "agent_run_manager",
+    run_id: args.runId,
+    thread_id: args.threadId,
+    turn_id: args.turnId,
+    status: args.status,
+    terminal_reason: args.terminalReason,
+    error_code: args.errorCode,
+    error_detail: args.errorDetail
+      ? args.errorDetail.length > MAX_RUN_ERROR_DETAIL_LENGTH
+        ? `${args.errorDetail.slice(0, MAX_RUN_ERROR_DETAIL_LENGTH)}…`
+        : args.errorDetail
+      : undefined,
+    dispatch_mode: args.dispatchMode ?? "foreground",
+    abort_reason: args.abortReason,
+    duration_ms: args.durationMs,
+    model: args.model,
+    engine: args.engineName,
+    attempt_count: args.attemptCount,
+  };
+  for (const key of Object.keys(properties)) {
+    if (properties[key] === undefined) delete properties[key];
+  }
+
+  try {
+    void Promise.all([
+      import("../tracking/registry.js"),
+      import("../observability/tracking-identity.js"),
+    ])
+      .then(([{ track }, { trackingIdentityProperties }]) => {
+        track(
+          "agent_run_terminal",
+          { ...properties, ...trackingIdentityProperties() },
+          { userId: args.userId },
+        );
+      })
+      .catch(() => {});
+  } catch {
+    // Tracking must never affect the agent run or its persisted status.
+  }
+}
+
 function abortInMemoryRun(run: ActiveRun, reason: string = "user") {
   run.abortReason = reason;
   run.status = "aborted";
@@ -1101,6 +1189,11 @@ export function startRun(
       //    /runs/active check while we wait for SQL writes to land.
       let completionError: unknown = null;
       let terminalPersistenceError: unknown = null;
+      // Populated in step 5b for errored runs; read by the terminal tracking
+      // emission below so it doesn't have to re-walk diagnosticEvents.
+      let runTerminalErrorCode: string | undefined;
+      let runTerminalErrorDetail: string | undefined;
+      let terminalPersistenceEstablished = false;
       const resolveTerminalEventForCompletion = () => {
         const continuationTerminalEvent = run.continuationTerminalEvent
           ? {
@@ -1278,9 +1371,11 @@ export function startRun(
             statusUpdated = false;
           }
           if (statusUpdated) {
+            terminalPersistenceEstablished = true;
             await setRunTerminalReason(runId, terminalReason);
           } else {
-            await reconcileTerminalRunFromEvents(runId).catch(() => false);
+            terminalPersistenceEstablished =
+              await reconcileTerminalRunFromEvents(runId).catch(() => false);
           }
         }
       } catch {
@@ -1324,6 +1419,8 @@ export function startRun(
               ? completionError.message
               : String(completionError));
         }
+        runTerminalErrorCode = errorCode ?? "unknown";
+        runTerminalErrorDetail = errorDetail;
         await setRunError(runId, errorCode ?? "unknown", errorDetail);
       }
 
@@ -1332,6 +1429,34 @@ export function startRun(
           () => false,
         );
         if (!reconciled) throw terminalPersistenceError;
+        terminalPersistenceEstablished = true;
+      }
+
+      // 5c. Emit a terminal-outcome analytics event, reusing the same
+      // best-effort tracking seam as $ai_generation (dynamic import + a
+      // swallowed catch so a broken/absent provider can never affect the
+      // run). Fired AFTER the atomic-complete SQL writes above so it never
+      // races the thread_data-before-status invariant those steps exist to
+      // protect. `persistedStatus` (not `finalStatus`) is used so a
+      // continuation boundary reports as "truncated" rather than a false
+      // "completed" — that distinction is the whole point of this event.
+      if (terminalPersistenceEstablished) {
+        emitRunTerminalTrackingEvent({
+          runId,
+          threadId,
+          turnId: run.turnId,
+          status: persistedStatus,
+          terminalReason,
+          errorCode: runTerminalErrorCode,
+          errorDetail: runTerminalErrorDetail,
+          dispatchMode: options?.dispatchMode,
+          abortReason: run.abortReason,
+          durationMs: Date.now() - run.startedAt,
+          model: options?.model,
+          engineName: options?.engineName,
+          userId: options?.userId,
+          attemptCount: options?.attemptCount,
+        });
       }
 
       // 6. Schedule in-memory cleanup + opportunistic old-run pruning.

package/src/agent/thread-data-builder.ts

@@ -944,6 +944,45 @@ export interface MergeThreadDataOptions {
   preserveExistingTopLevelKeys?: boolean;
 }
 
+const CLAIMED_QUEUED_MESSAGE_IDS_KEY = "_claimedQueuedMessageIds";
+const MAX_CLAIMED_QUEUED_MESSAGE_IDS = 200;
+
+function claimedQueuedMessageIds(repo: any): string[] {
+  const value = repo?.[CLAIMED_QUEUED_MESSAGE_IDS_KEY];
+  if (!Array.isArray(value)) return [];
+  return value.filter(
+    (id): id is string => typeof id === "string" && id.length > 0,
+  );
+}
+
+export function hasClaimedQueuedMessage(repo: any, messageId: string): boolean {
+  return claimedQueuedMessageIds(repo).includes(messageId);
+}
+
+export function claimQueuedMessage(repo: any, messageId: string): any {
+  const normalized = repo && typeof repo === "object" ? { ...repo } : {};
+  const claimed = claimedQueuedMessageIds(normalized).filter(
+    (id) => id !== messageId,
+  );
+  normalized[CLAIMED_QUEUED_MESSAGE_IDS_KEY] = [...claimed, messageId].slice(
+    -MAX_CLAIMED_QUEUED_MESSAGE_IDS,
+  );
+  return pruneClaimedQueuedMessages(normalized);
+}
+
+function pruneClaimedQueuedMessages(repo: any): any {
+  if (!Array.isArray(repo?.queuedMessages)) return repo;
+  const claimed = new Set(claimedQueuedMessageIds(repo));
+  if (claimed.size === 0) return repo;
+  return {
+    ...repo,
+    queuedMessages: repo.queuedMessages.filter(
+      (message: any) =>
+        typeof message?.id !== "string" || !claimed.has(message.id),
+    ),
+  };
+}
+
 export function mergeThreadDataForClientSave(
   existingRepo: any,
   incomingRepo: any,
@@ -989,7 +1028,9 @@ export function mergeThreadDataForClientSave(
   const incomingMessages = Array.isArray(merged.messages)
     ? merged.messages
     : null;
-  if (!existingMessages || !incomingMessages) return merged;
+  if (!existingMessages || !incomingMessages) {
+    return pruneClaimedQueuedMessages(merged);
+  }
 
   const incomingKeySets: Set<string>[] = incomingMessages.map(
     (entry: unknown) => new Set(messageIdentityKeys(getStoredMessage(entry))),
@@ -1044,7 +1085,7 @@ export function mergeThreadDataForClientSave(
   merged.messages = nextMessages.map((entry) =>
     rewriteEntryParentId(entry, idRewrites),
   );
-  return normalizeThreadRepository(merged);
+  return normalizeThreadRepository(pruneClaimedQueuedMessages(merged));
 }
 
 function escapeAttachmentAttribute(value: string): string {
@@ -1189,6 +1230,7 @@ export function buildUserMessage(opts: {
   text: string;
   attachments?: AgentChatAttachment[];
   runId?: string;
+  queuedMessageId?: string;
   createdAt?: Date;
 }): {
   id: string;
@@ -1208,6 +1250,9 @@ export function buildUserMessage(opts: {
     metadata: {
       custom: {
         submittedRunId: opts.runId,
+        ...(opts.queuedMessageId
+          ? { agentNativeQueuedMessageId: opts.queuedMessageId }
+          : {}),
       },
     },
   };

package/src/agent/types.ts

@@ -135,6 +135,8 @@ export interface AgentChatScope {
 
 export interface AgentChatRequest {
   message: string;
+  /** Stable identity of a durable queued message, used to reject replayed delivery. */
+  queuedMessageId?: string;
   /**
    * User-visible text to persist in chat history. `message` may be normalized
    * for the model (for example mention markup or internal continuation text).

package/src/chat-threads/store.ts

@@ -1056,11 +1056,10 @@ export async function setThreadQueuedMessages(
     try {
       data = JSON.parse(thread.threadData);
     } catch {}
-    if (queuedMessages.length === 0) {
-      delete data.queuedMessages;
-    } else {
-      data.queuedMessages = queuedMessages;
-    }
+    // Keep an explicit empty tombstone. Other mounted chat surfaces only
+    // reconcile queue state when this field is present; deleting it lets a
+    // stale local queue survive the clear and submit the same prompt again.
+    data.queuedMessages = queuedMessages;
     await updateThreadData(
       threadId,
       JSON.stringify(data),