@agent-native/core 0.176.1 → 0.176.2-nightly-20260831185956

package/dist/agent/production-agent.js

@@ -23,6 +23,7 @@ import { assertRequestActionSurfaceIsolation, getRequestRunContext, ensureReques
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { ANALYTICS_CLIENT_PLATFORM_BODY_FIELD } from "../shared/analytics-platform.js";
 import { isReasoningEffort, normalizeReasoningEffortForRequest, stepDownReasoningEffort, } from "../shared/reasoning-effort.js";
+import { SYNTHETIC_TRAFFIC_BETA_E2E, SYNTHETIC_TRAFFIC_HEADER, } from "../shared/test-traffic.js";
 import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
 import { drainAgentWarnings, formatAgentWarningsForToolResult, } from "./action-warnings.js";
 import { buildSystemManifestSections, readContextXraySystemSections, } from "./context-xray/manifest.js";
@@ -41,7 +42,7 @@ import { filterHostedHarnessToolNames, normalizeHostedHarnessRuntime, } from "./
 import { getDefaultMaxIterations, getDefaultMaxRunInputTokens, MAX_AGENT_MAX_ITERATIONS, MIN_AGENT_MAX_ITERATIONS, normalizeMaxIterations, normalizeMaxRunInputTokens, readAgentLoopSettings, } from "./loop-settings.js";
 import { maybeCompactThread, buildObservationalContext, hasObservationalMemory, serializeObservationalMemoryBlock, } from "./observational-memory/index.js";
 import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js";
-import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnDurably, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterCompletedToolWithoutAssistantFinal, } from "./run-manager.js";
+import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnDurably, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterCompletedToolWithoutAssistantFinal, endsDuringActionPreparation, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, turnRunLedgerExhausted, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
 import { consumeAgentToolApproval, createAgentToolApproval, isAgentToolAlwaysAllowed, resolveAgentToolApprovalTurnId, } from "./tool-approval-store.js";
@@ -230,6 +231,18 @@ function normalizeBrowserTabId(value) {
     const trimmed = value.trim();
     return SAFE_BROWSER_TAB_ID_RE.test(trimmed) ? trimmed : undefined;
 }
+/**
+ * The usage label is caller-supplied (a template surface, an MCP host, an
+ * extension), and it lands in a usage row AND in a trace span name. Bound it
+ * and strip control characters here so a client cannot turn either into a
+ * payload channel.
+ */
+function normalizeUsageLabel(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.replace(/[\u0000-\u001f\u007f]/g, " ").trim();
+    return trimmed ? trimmed.slice(0, 120) : undefined;
+}
 function normalizeChatScope(value) {
     if (value == null)
         return null;
@@ -272,14 +285,15 @@ export async function getOwnerApiKey(provider, ownerEmail) {
     if (!ownerEmail)
         return undefined;
     const secretKey = PROVIDER_TO_ENV[provider] ?? `${provider.toUpperCase()}_API_KEY`;
+    const syntheticTraffic = getRequestContext()?.isSyntheticTraffic === true;
     try {
         const { readAppSecret } = await import("../secrets/storage.js");
         const refs = [{ scope: "user", scopeId: ownerEmail }];
         const orgId = getRequestOrgId();
-        if (orgId) {
+        if (orgId && !syntheticTraffic) {
             refs.push({ scope: "org", scopeId: orgId }, { scope: "workspace", scopeId: orgId });
         }
-        else {
+        else if (!syntheticTraffic) {
             refs.push({ scope: "workspace", scopeId: `solo:${ownerEmail}` });
         }
         for (const ref of refs) {
@@ -298,8 +312,13 @@ export async function getOwnerApiKey(provider, ownerEmail) {
         }
     }
     catch {
-        // app_secrets table not ready — fall through to legacy lookup.
+        // app_secrets table not ready — only non-synthetic traffic may fall through
+        // to legacy lookup. A synthetic run must never bill an alternate key.
+        if (syntheticTraffic)
+            return undefined;
     }
+    if (syntheticTraffic)
+        return undefined;
     try {
         const { getSetting } = await import("../settings/store.js");
         const stored = await getSetting(`user-api-key:${provider}:${ownerEmail}`);
@@ -827,6 +846,10 @@ const FOREGROUND_FIRST_MODEL_EVENT_TIMEOUT_MS = 25_000;
 // ceiling and steps effort down a tier) instead of re-issuing the
 // exact same doomed request twice.
 const EMPTY_FINAL_RESPONSE_RETRY_LIMIT = 2;
+// A `max_tokens` stop with tool-call parts present is a tool call cut off
+// mid-arguments. Same escalation shape as the empty-final retry: each attempt
+// raises the ceiling, so re-issuing is not re-issuing the same doomed request.
+const TRUNCATED_TOOL_CALL_RETRY_LIMIT = 2;
 const MAIN_CHAT_INTERNAL_CONTINUATION_LIMIT = 6;
 const RUN_BUDGET_EXHAUSTED_ERROR_CODE = "run_budget_exhausted";
 const RUN_BUDGET_EXHAUSTED_MESSAGE = "I ran out of time before finishing this step. " +
@@ -1523,6 +1546,13 @@ export async function callConnectedAgentReference(input) {
             userEmail: callerAuth.userEmail,
             orgDomain: callerAuth.orgDomain,
             orgSecret: callerAuth.orgSecret,
+            ...(getRequestContext()?.isSyntheticTraffic === true
+                ? {
+                    transportHeaders: {
+                        [SYNTHETIC_TRAFFIC_HEADER]: SYNTHETIC_TRAFFIC_BETA_E2E,
+                    },
+                }
+                : {}),
             onUpdate: relay.observePollUpdate,
         });
         const responseText = userFacingLlmCredentialError(response, {
@@ -2954,14 +2984,22 @@ function schemaErrorPropertyNames(error) {
  * actions have echoed the expected signature since `wrapWithValidation`; this
  * gives the raw path the same answer from the same helper.
  */
-function toolInputSchemaErrorResult(toolName, input, error, parameters) {
+function toolInputSchemaErrorResult(toolName, input, error, parameters, 
+/**
+ * The model response carrying this call stopped at the output-token cap, so
+ * the arguments are truncated rather than wrong. Telling the model to match
+ * the schema here is what makes it re-send the same oversized payload.
+ */
+outputCapTruncated = false) {
     const signature = describeToolParameterSignature(parameters, schemaErrorPropertyNames(error));
     return (`Invalid action parameters for ${toolName}: ${sanitizeToolErrorText(error)}. ` +
         `Received: ${stringifyToolInput(input)}. ` +
         (signature
             ? `Expected: ${signature} (where * = required, ? = optional). `
             : "") +
-        "The tool was not executed; retry with arguments that match the tool schema.");
+        (outputCapTruncated
+            ? "The tool was not executed: the response hit the model output-token cap before these arguments finished, so they are truncated, not wrong. Retry with a smaller payload — split the work across several calls, or shorten the longest field."
+            : "The tool was not executed; retry with arguments that match the tool schema."));
 }
 const rawToolInputAjv = new Ajv({
     strict: false,
@@ -3318,7 +3356,14 @@ export async function runAgentLoop(opts) {
             added.push(name);
         }
         if (added.length > 0) {
-            activeTools = (availableTools ?? tools).filter((tool) => activeToolNames.has(tool.name));
+            const expandedTools = (availableTools ?? tools).filter((tool) => activeToolNames.has(tool.name));
+            const prioritizedNames = new Set(names);
+            // Provider adapters cap the schema list; keep search results in the
+            // prefix so the next request can actually call what it discovered.
+            activeTools = [
+                ...expandedTools.filter((tool) => prioritizedNames.has(tool.name)),
+                ...expandedTools.filter((tool) => !prioritizedNames.has(tool.name)),
+            ];
         }
         if (!reportedExpandedToolSchemaBytes &&
             expandedToolSchemaBytes > EXPANDED_TOOL_SCHEMA_WARN_BYTES) {
@@ -3428,6 +3473,7 @@ export async function runAgentLoop(opts) {
     }
     let finalGuardRetries = 0;
     let emptyFinalResponseRetries = 0;
+    let truncatedToolCallRetries = 0;
     let iterations = 0;
     // `loop_limit` and `done` share one terminal-event slot in run-manager, so a
     // trailing `done` would overwrite the boundary the continuation logic reads.
@@ -4174,6 +4220,37 @@ export async function runAgentLoop(opts) {
         // permanently disabled for the rest of a long multi-step run.
         finalGuardRetries = 0;
         emptyFinalResponseRetries = 0;
+        // A `max_tokens` stop is only recognised as truncation in the
+        // `toolCallParts.length === 0` branch above. A tool call cut off
+        // mid-arguments still arrives AS a tool-call part, so without this the
+        // turn reads as a normal one: the partial arguments fail schema
+        // validation, the model is told to "retry with arguments that match the
+        // tool schema", and it re-issues the same oversized payload against the
+        // same ceiling until the identical-error stop fires. The tool never runs
+        // and nothing in the transcript says the response was truncated.
+        //
+        // The tool calls still execute — the assistant turn carrying them is
+        // already in `messages`, and every tool_use needs its tool_result — but
+        // the retry gets a raised ceiling and the error text below names the real
+        // cause.
+        const toolCallTruncatedByOutputCap = terminalStopReason === "max_tokens";
+        if (toolCallTruncatedByOutputCap) {
+            if (truncatedToolCallRetries < TRUNCATED_TOOL_CALL_RETRY_LIMIT) {
+                truncatedToolCallRetries += 1;
+                effectiveMaxOutputTokens =
+                    resolveEmptyResponseRetryMaxOutputTokens(model);
+            }
+            else {
+                // Retries spent. The raised ceiling was lent to those attempts, not to
+                // the rest of the run — leaving it in place kept every later request
+                // above the configured cap.
+                effectiveMaxOutputTokens = opts.maxOutputTokens;
+            }
+        }
+        else {
+            truncatedToolCallRetries = 0;
+            effectiveMaxOutputTokens = opts.maxOutputTokens;
+        }
         flushUnstreamedAssistantText();
         let requestedActionStop = null;
         // An `endsTurn` action ran and handed control to the user. Distinct from
@@ -4711,7 +4788,7 @@ export async function runAgentLoop(opts) {
             try {
                 const toolCallSchemaError = toolCallErrors.get(toolCall.id);
                 if (toolCallSchemaError && !toolInputNormalized) {
-                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCallSchemaError.input, toolCallSchemaError.error, actionEntry?.tool.parameters));
+                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCallSchemaError.input, toolCallSchemaError.error, actionEntry?.tool.parameters, toolCallTruncatedByOutputCap));
                     emitToolDone({
                         type: "tool_done",
                         id: toolCall.id,
@@ -4733,7 +4810,7 @@ export async function runAgentLoop(opts) {
                 }
                 const rawToolInputError = validateRawToolInput(actionEntry, toolCall.input);
                 if (rawToolInputError) {
-                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCall.input, rawToolInputError, actionEntry.tool.parameters));
+                    const result = finalizeToolErrorResult(toolInputSchemaErrorResult(toolCall.name, toolCall.input, rawToolInputError, actionEntry.tool.parameters, toolCallTruncatedByOutputCap));
                     emitToolDone({
                         type: "tool_done",
                         id: toolCall.id,
@@ -5508,7 +5585,8 @@ export function backgroundContinuationReasonForRun(run) {
     if (last?.type === "error" && isRecoverableContinuationError(last)) {
         return continuationReasonForResumableError(new EngineError(last.error, { errorCode: last.errorCode }));
     }
-    if (endsAfterCompletedToolWithoutAssistantFinal(run)) {
+    if (endsAfterCompletedToolWithoutAssistantFinal(run) ||
+        endsDuringActionPreparation(run)) {
         return "stream_ended";
     }
     return "run_timeout";
@@ -5613,7 +5691,8 @@ export async function runAgentLoopWithMainChatInternalContinuations(opts) {
 }
 function endsAtContinuationBoundary(run) {
     return (endsAtInternalContinuationBoundary(run) ||
-        endsAfterCompletedToolWithoutAssistantFinal(run));
+        endsAfterCompletedToolWithoutAssistantFinal(run) ||
+        endsDuringActionPreparation(run));
 }
 // Defined in `app-config/run-lifecycle-invariants.ts`, the neutral home for
 // lifecycle bounds that participate in a cross-module relationship: the durable
@@ -6513,7 +6592,12 @@ export function createProductionAgentHandler(options) {
                 return { error: "Invalid request body" };
             }
         }
-        const { message, history = [], structuredHistory, references = [], threadId, attachments, displayMessage, queuedMessageId, internalContinuation, turnId: requestTurnId, model: requestModel, engine: requestEngine, effort: requestEffort, browserTabId, scope, harness: requestHarness, trackInRunsTray, } = body;
+        const { message, history = [], structuredHistory, references = [], threadId, attachments, displayMessage, parentId, queuedMessageId, internalContinuation, turnId: requestTurnId, model: requestModel, engine: requestEngine, effort: requestEffort, browserTabId, scope, harness: requestHarness, trackInRunsTray, } = body;
+        const requestParentId = parentId === null
+            ? null
+            : typeof parentId === "string" && parentId.trim()
+                ? parentId.trim()
+                : undefined;
         setupMark("bodyParsed");
         // Durable-background marker. Present ONLY when this handler was re-entered
         // as the Netlify background worker via the `_process-run` self-dispatch
@@ -6859,6 +6943,7 @@ export function createProductionAgentHandler(options) {
         const model = normalizeModelForEngine(engine, modelCandidate);
         let effectiveModel = model;
         let modelSelectionSource = modelSelection.source;
+        const turnUsageLabel = normalizeUsageLabel(body.usageLabel);
         let experimentAssignments = [];
         // Database-backed experiments remain available to app operators.
         try {
@@ -8303,8 +8388,16 @@ export function createProductionAgentHandler(options) {
                             threadId: threadId ?? null,
                             userId: ownerEmail,
                             config: obsConfig,
+                            // A caller that named its turn (a template surface, an MCP
+                            // host, a background send) gets that name in the trace list;
+                            // a plain chat turn stays `agent_run` so the common case
+                            // still aggregates.
+                            spanName: turnUsageLabel && turnUsageLabel !== "chat"
+                                ? `agent_run:${turnUsageLabel}`
+                                : undefined,
                             metadata: {
                                 modelSelectionSource,
+                                ...(turnUsageLabel ? { label: turnUsageLabel } : {}),
                                 ...(experimentAssignments.length > 0
                                     ? { experimentAssignments }
                                     : {}),
@@ -8369,7 +8462,7 @@ export function createProductionAgentHandler(options) {
                             cacheReadTokens: turnUsage.cacheReadTokens,
                             cacheWriteTokens: turnUsage.cacheWriteTokens,
                             model: turnUsage.model,
-                            label: body.usageLabel || "chat",
+                            label: turnUsageLabel || "chat",
                             // token_usage has had run_id/thread_id/task_id since it was
                             // created and every row was NULL on all three, so no spend could
                             // be tied back to a run, thread, or outcome.
@@ -8410,6 +8503,7 @@ export function createProductionAgentHandler(options) {
             // assistant message. Falls back to the runId (turn == run) when the
             // client doesn't supply a turnId.
             turnId: effectiveTurnId,
+            parentId: requestParentId,
             waitUntil: getRequestRunContext()?.waitUntil,
             // A durable background worker reaches this same call site, so keying
             // only on the foreground self-chain flag stamped every worker run

package/dist/agent/run-manager.d.ts

@@ -3,6 +3,8 @@ import type { AgentChatEvent, RunEvent, RunStatus } from "./types.js";
 export interface ActiveRun {
     runId: string;
     threadId: string;
+    /** Parent message for the assistant-ui branch this run is answering. */
+    parentId?: string | null;
     /** Logical-turn identity (see StartRunOptions.turnId). Defaults to runId. */
     turnId: string;
     events: RunEvent[];
@@ -208,6 +210,8 @@ export interface StartRunOptions {
      * share one `turnId` so the durable assistant message can be folded across
      * them instead of dropped per-run. Defaults to the runId (turn == run). */
     turnId?: string;
+    /** Parent message for the assistant-ui branch this run is answering. */
+    parentId?: string | null;
     /**
      * Opt into the durable-background-function soft-timeout regime for THIS run
      * only. When true, `resolveRunSoftTimeoutMs` lifts the hosted ceiling from
@@ -361,6 +365,11 @@ export declare function resolveBackgroundAutomationSoftTimeoutMs(overrideMs?: nu
  * the same boundary evidence.
  */
 export declare function endsAfterCompletedToolWithoutAssistantFinal(run: ActiveRun): boolean;
+/**
+ * A model can emit a lead-in before it starts assembling an action input. If
+ * the run ends in that preparation phase, `done` is not a successful turn.
+ */
+export declare function endsDuringActionPreparation(run: ActiveRun): boolean;
 /**
  * Start a new agent run in the background.
  * `runFn` receives a `send` callback and an `AbortSignal`.

package/dist/agent/run-manager.js

@@ -484,6 +484,33 @@ export function endsAfterCompletedToolWithoutAssistantFinal(run) {
     }
     return completedToolAfterLastAssistantText;
 }
+/**
+ * A model can emit a lead-in before it starts assembling an action input. If
+ * the run ends in that preparation phase, `done` is not a successful turn.
+ */
+export function endsDuringActionPreparation(run) {
+    let preparingAction = false;
+    for (const { event } of run.events) {
+        if (isPreparingActionActivityEvent(event) ||
+            event.type === "tool_input_start" ||
+            event.type === "tool_input_delta") {
+            preparingAction = true;
+            continue;
+        }
+        if ((event.type === "text" && event.text.trim().length > 0) ||
+            event.type === "tool_start" ||
+            event.type === "tool_done" ||
+            event.type === "approval_required" ||
+            event.type === "clear" ||
+            event.type === "error" ||
+            event.type === "missing_api_key" ||
+            event.type === "auto_continue" ||
+            event.type === "loop_limit") {
+            preparingAction = false;
+        }
+    }
+    return preparingAction;
+}
 function terminalEventForcesErroredStatus(event) {
     return event?.type === "error" || event?.type === "missing_api_key";
 }
@@ -734,6 +761,7 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
     const run = {
         runId,
         threadId,
+        ...(options?.parentId !== undefined ? { parentId: options.parentId } : {}),
         turnId: options?.turnId ?? runId,
         events: [],
         status: "running",
@@ -1565,19 +1593,20 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
                 terminalEventForcesErroredStatus(terminalEvent)
                 ? "errored"
                 : "completed";
-        const shouldAutoContinueAfterCompletedTool = finalStatus === "completed" &&
-            endsAfterCompletedToolWithoutAssistantFinal(run) &&
+        const shouldAutoContinueAfterUnfinishedTurn = finalStatus === "completed" &&
+            (endsAfterCompletedToolWithoutAssistantFinal(run) ||
+                endsDuringActionPreparation(run)) &&
             (!terminalEventForCompletion ||
                 (terminalEventForCompletion.event.type === "done" &&
                     terminalEventForCompletion.event.reason !== "user"));
-        const completedToolContinuationEvent = shouldAutoContinueAfterCompletedTool
+        const unfinishedTurnContinuationEvent = shouldAutoContinueAfterUnfinishedTurn
             ? {
                 type: "auto_continue",
                 reason: "stream_ended",
             }
             : null;
-        if (completedToolContinuationEvent) {
-            terminalEvent = completedToolContinuationEvent;
+        if (unfinishedTurnContinuationEvent) {
+            terminalEvent = unfinishedTurnContinuationEvent;
         }
         const terminalReason = terminalReasonForRun(finalStatus, terminalEvent, run.abortReason, completionError);
         // A run that stopped at a continuation boundary did not finish, so it is
@@ -1607,7 +1636,7 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             // client would never see the terminal/continuation signal. We always
             // re-stamp the seq at emit time (max-seq+1) just below.
             const terminalEventToEmit = finalStatus === "completed"
-                ? (completedToolContinuationEvent ??
+                ? (unfinishedTurnContinuationEvent ??
                     terminalEventForCompletion?.event ?? { type: "done" })
                 : terminalEventForCompletion?.event.type === "error" ||
                     terminalEventForCompletion?.event.type === "missing_api_key"

package/dist/agent/thread-data-builder.d.ts

@@ -35,6 +35,10 @@ interface BuildAssistantMessageOptions {
      */
     turnId?: string;
     runDurationMs?: number;
+    scope?: {
+        type: string;
+        id: string;
+    } | null;
 }
 type AssistantMessage = NonNullable<ReturnType<typeof buildAssistantMessage>>;
 type UserMessage = ReturnType<typeof buildUserMessage>;
@@ -163,7 +167,7 @@ export declare function upsertUserMessage(repo: any, userMsg: UserMessage): any;
  * any assistant content as proof that the frontend already saved the final
  * turn.
  */
-export declare function upsertAssistantMessage(repo: any, assistantMsg: AssistantMessage): any;
+export declare function upsertAssistantMessage(repo: any, assistantMsg: AssistantMessage, parentId?: string | null): any;
 /**
  * Fold a continuation run's assistant message onto the single durable message
  * for its logical turn (identified by `turnId`), so a turn that spans several
@@ -183,6 +187,7 @@ export declare function upsertAssistantMessage(repo: any, assistantMsg: Assistan
 export declare function foldAssistantTurn(repo: any, assistantMsg: AssistantMessage, options: {
     turnId?: string;
     runId?: string;
+    parentId?: string | null;
 }): any;
 export declare function normalizeThreadTitle(value: unknown): string;
 /**

package/dist/agent/thread-data-builder.js

@@ -251,6 +251,12 @@ export function buildAssistantMessage(events, runId, options = {}) {
     const custom = {};
     if (options.turnId)
         custom.turnId = options.turnId;
+    if (options.scope?.type && options.scope.id) {
+        custom.chatScope = {
+            type: options.scope.type,
+            id: options.scope.id,
+        };
+    }
     if (runId)
         custom.foldedRunIds = [runId];
     if (typeof options.runDurationMs === "number" &&
@@ -443,20 +449,20 @@ function normalizeContentForFingerprint(content) {
         ? { ...part, toolCallId: undefined }
         : part);
 }
-function messageIdentityKeys(message) {
-    const keys = [];
+function messageIdentityKeySet(message) {
+    const strong = [];
     if (typeof message?.id === "string" && message.id) {
-        keys.push(`id:${message.id}`);
+        strong.push(`id:${message.id}`);
     }
     const runId = getMessageRunId(message);
     if (runId)
-        keys.push(`run:${runId}`);
+        strong.push(`run:${runId}`);
     // A logical turn is ONE durable assistant message even though it may span
     // several continuation runs, so two messages sharing a turnId (e.g. the
     // client export and the server fold of the same answer) must dedupe to one.
     const turnId = turnIdOf(message);
     if (turnId)
-        keys.push(`turn:${turnId}`);
+        strong.push(`turn:${turnId}`);
     // Normalize attachments through `normalizeAttachmentIdentity` so an
     // explicit empty `[]` (assistant-ui's default for messages with no
     // attachments) and an omitted/undefined `attachments` field hash to the
@@ -468,8 +474,9 @@ function messageIdentityKeys(message) {
     // `[]` vs `undefined`. (Repro on slides prod: every user turn produced
     // a `client_user → assistant → server_user` triple instead of a
     // `user → assistant` pair.)
+    const fingerprint = [];
     try {
-        keys.push(`fingerprint:${JSON.stringify({
+        fingerprint.push(`fingerprint:${JSON.stringify({
             role: message?.role,
             content: normalizeContentForFingerprint(message?.content),
             attachments: normalizeAttachmentIdentity(message?.attachments),
@@ -480,7 +487,7 @@ function messageIdentityKeys(message) {
     }
     if (message?.role === "user") {
         try {
-            keys.push(`user-fingerprint:${JSON.stringify({
+            fingerprint.push(`user-fingerprint:${JSON.stringify({
                 role: message.role,
                 content: normalizeContentForFingerprint(message.content),
                 attachments: normalizeAttachmentIdentity(message.attachments),
@@ -490,12 +497,52 @@ function messageIdentityKeys(message) {
             // Same best-effort behavior as the full fingerprint.
         }
     }
-    return keys;
+    return { strong, fingerprint };
+}
+function messageIdentityKeys(message) {
+    const { strong, fingerprint } = messageIdentityKeySet(message);
+    return [...strong, ...fingerprint];
 }
 function messagesMatch(a, b) {
     const bKeys = new Set(messageIdentityKeys(b));
     return messageIdentityKeys(a).some((key) => bKeys.has(key));
 }
+function keySetsOverlap(a, b) {
+    return a.some((key) => b.has(key));
+}
+/**
+ * Rank candidate incoming entries for one existing entry: a strong-key match
+ * (id/runId/turnId) always wins over a fingerprint-only match, since a
+ * fingerprint has no positional or temporal salt and different messages can
+ * collide on one. Within a tier, more than one candidate is genuinely
+ * ambiguous — nothing in the keys says which is "the same message" — so
+ * pick the candidate positioned closest to `existingIndex` instead of
+ * silently keeping array-scan order (the original defect: the first unused
+ * incoming entry sharing ANY key won, so a fingerprint match on an
+ * out-of-order entry could preempt the correct strong-key match and pair the
+ * wrong messages, rewriting parent links onto the wrong id).
+ */
+function findRankedIdentityMatch(existingKeys, incomingKeySets, usedIncoming, existingIndex) {
+    const strongCandidates = [];
+    const fingerprintCandidates = [];
+    for (let i = 0; i < incomingKeySets.length; i++) {
+        if (usedIncoming.has(i))
+            continue;
+        const keys = incomingKeySets[i];
+        if (keySetsOverlap(existingKeys.strong, new Set(keys.strong))) {
+            strongCandidates.push(i);
+        }
+        else if (keySetsOverlap(existingKeys.fingerprint, new Set(keys.fingerprint))) {
+            fingerprintCandidates.push(i);
+        }
+    }
+    const candidates = strongCandidates.length > 0 ? strongCandidates : fingerprintCandidates;
+    if (candidates.length === 0)
+        return -1;
+    return candidates.reduce((closest, index) => Math.abs(index - existingIndex) < Math.abs(closest - existingIndex)
+        ? index
+        : closest);
+}
 function preserveAssistantRunDuration(chosenEntry, otherEntry) {
     const chosen = getStoredMessage(chosenEntry);
     const other = getStoredMessage(otherEntry);
@@ -1106,18 +1153,19 @@ export function mergeThreadDataForClientSave(existingRepo, incomingRepo, options
     if (!existingMessages || !incomingMessages) {
         return pruneClaimedQueuedMessages(merged);
     }
-    const incomingKeySets = incomingMessages.map((entry) => new Set(messageIdentityKeys(getStoredMessage(entry))));
+    const incomingKeySets = incomingMessages.map((entry) => messageIdentityKeySet(getStoredMessage(entry)));
     const usedIncoming = new Set();
     const nextMessages = [];
     const idRewrites = new Map();
-    for (const existingEntry of existingMessages) {
+    for (let existingIndex = 0; existingIndex < existingMessages.length; existingIndex++) {
+        const existingEntry = existingMessages[existingIndex];
         const existingMessage = getStoredMessage(existingEntry);
         if (existingMessage?.role === "assistant" &&
             messageContentIsEmpty(existingMessage.content)) {
             continue;
         }
-        const existingKeys = messageIdentityKeys(existingMessage);
-        const incomingIndex = incomingKeySets.findIndex((keys, index) => !usedIncoming.has(index) && existingKeys.some((key) => keys.has(key)));
+        const existingKeys = messageIdentityKeySet(existingMessage);
+        const incomingIndex = findRankedIdentityMatch(existingKeys, incomingKeySets, usedIncoming, existingIndex);
         if (incomingIndex === -1) {
             nextMessages.push(existingEntry);
             continue;
@@ -1460,22 +1508,29 @@ function shouldReplaceLastAssistant(lastMessage, assistantMsg) {
  * any assistant content as proof that the frontend already saved the final
  * turn.
  */
-export function upsertAssistantMessage(repo, assistantMsg) {
+export function upsertAssistantMessage(repo, assistantMsg, parentId) {
     const nextRepo = normalizeThreadRepository(repo);
     const lastIndex = nextRepo.messages.length - 1;
     const lastEntry = lastIndex >= 0 ? nextRepo.messages[lastIndex] : undefined;
     const lastMsg = getStoredMessage(lastEntry);
     const lastRole = lastMsg?.role;
+    const lastParentId = lastEntry ? getStoredParentId(lastEntry) : undefined;
     if (lastRole === "assistant" &&
+        (parentId === undefined || lastParentId === parentId) &&
         shouldReplaceLastAssistant(lastMsg, assistantMsg)) {
         nextRepo.messages[lastIndex] = { ...lastEntry, message: assistantMsg };
         nextRepo.headId = assistantMsg.id;
         return nextRepo;
     }
-    const parentId = nextRepo.messages.length > 0
+    const fallbackParentId = nextRepo.messages.length > 0
         ? (messageId(getStoredMessage(nextRepo.messages[nextRepo.messages.length - 1])) ?? null)
         : null;
-    nextRepo.messages.push({ message: assistantMsg, parentId });
+    const resolvedParentId = parentId === null ||
+        (typeof parentId === "string" &&
+            nextRepo.messages.some((entry) => messageId(getStoredMessage(entry)) === parentId))
+        ? parentId
+        : fallbackParentId;
+    nextRepo.messages.push({ message: assistantMsg, parentId: resolvedParentId });
     nextRepo.headId = assistantMsg.id;
     return nextRepo;
 }
@@ -1555,12 +1610,14 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
     const turnId = options.turnId;
     const runId = options.runId;
     if (!turnId)
-        return upsertAssistantMessage(repo, assistantMsg);
+        return upsertAssistantMessage(repo, assistantMsg, options.parentId);
     const nextRepo = normalizeThreadRepository(repo);
     const lastIndex = nextRepo.messages.length - 1;
     const lastEntry = lastIndex >= 0 ? nextRepo.messages[lastIndex] : undefined;
     const lastMsg = getStoredMessage(lastEntry);
     const sameTurn = lastMsg?.role === "assistant" &&
+        (options.parentId === undefined ||
+            getStoredParentId(lastEntry) === options.parentId) &&
         (turnIdOf(lastMsg) === turnId ||
             // A message the client wrote for one of this turn's runs before it
             // carried a turnId stamp.
@@ -1569,7 +1626,7 @@ export function foldAssistantTurn(repo, assistantMsg, options) {
         // First chunk of this turn (or the previous assistant belongs to an
         // earlier turn) — append as a fresh message; buildAssistantMessage already
         // stamped turnId + foldedRunIds onto it.
-        return upsertAssistantMessage(repo, assistantMsg);
+        return upsertAssistantMessage(repo, assistantMsg, options.parentId);
     }
     const existingContent = Array.isArray(lastMsg.content) ? lastMsg.content : [];
     const incomingContent = Array.isArray(assistantMsg.content)

package/dist/agent/types.d.ts

@@ -174,6 +174,8 @@ export interface AgentChatRequest {
     structuredHistory?: AgentChatStructuredMessage[];
     references?: AgentChatReference[];
     threadId?: string;
+    /** Parent message for assistant-ui sends and regenerations. */
+    parentId?: string | null;
     attachments?: AgentChatAttachment[];
     /** Internal retry/continuation requests should not create visible user turns. */
     internalContinuation?: boolean;

package/dist/app-config/agent.d.ts

@@ -11,8 +11,12 @@ export declare const agentConfig: z.ZodObject<{
     engine: z.ZodOptional<z.ZodString>;
     model: z.ZodOptional<z.ZodString>;
     builtInEngines: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    buildEnginePackages: z.ZodOptional<z.ZodString>;
     mode: z.ZodOptional<z.ZodString>;
     preferBringYourOwnKey: z.ZodDefault<z.ZodBoolean>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+    mainChatMaxOutputTokens: z.ZodDefault<z.ZodNumber>;
+    emptyResponseRetryMaxOutputTokens: z.ZodDefault<z.ZodNumber>;
     sourceSweepToolCallThreshold: z.ZodDefault<z.ZodNumber>;
     runSoftTimeoutMs: z.ZodOptional<z.ZodNumber>;
     completedRunRetentionMs: z.ZodOptional<z.ZodNumber>;