@agent-native/core 0.159.5 → 0.160.1

package/dist/agent/production-agent.js

@@ -14,7 +14,7 @@ import { isMcpToolAllowedForRequest } from "../mcp-client/visibility.js";
 import { shouldInferSentimentForTurn } from "../observability/sentiment.js";
 import { completeRun as completeProgressRun, startRun as startProgressRun, updateRunProgress, } from "../progress/registry.js";
 import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "../server/agent-chat/skill-frontmatter.js";
-import { canUseDeployCredentialFallbackForRequest, getProviderCredentialAuthFailure, readDeployCredentialEnv, } from "../server/credential-provider.js";
+import { canUseDeployCredentialFallbackForRequest, getProviderCredentialAuthFailure, isBuilderGatewayDeployConfigured, readDeployCredentialEnv, } from "../server/credential-provider.js";
 import { readBody } from "../server/h3-helpers.js";
 import { resolveHostedHarnessPolicy } from "../server/hosted-harness-policy.js";
 import { assertRequestActionSurfaceIsolation, getRequestRunContext, ensureRequestRunContext, getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
@@ -27,8 +27,8 @@ import { buildSystemManifestSections, readContextXraySystemSections, } from "./c
 import { AGENT_CHAT_BACKGROUND_RUN_FIELD, AGENT_CHAT_PROCESS_RUN_PATH, backgroundRuntimeDiagnosticDetail, dispatchPathTargetsNetlifyBackgroundFunction, isAgentChatDurableBackgroundEnabled, isAgentChatForegroundSelfChainEnabled, isInBackgroundFunctionRuntime, resolveAgentChatProcessRunDispatchPath, shouldUseBackgroundFunctionTimeoutForWorker, } from "./durable-background.js";
 import { applyContextXrayTransformForIteration } from "./engine/context-directives-transform.js";
 import { attemptContinuationDispatch } from "./engine/continuation-dispatch-retry.js";
-import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
-import { isProviderConnectionErrorMessage } from "./engine/error-detail.js";
+import { formatLlmCredentialErrorMessage, LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
+import { isContextOverflowCode, isContextOverflowMessage, isProviderConnectionErrorMessage, } from "./engine/error-detail.js";
 import { resolveEngine, explicitEngineName, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
 import { resolveEmptyResponseRetryMaxOutputTokens, resolveMainChatMaxOutputTokens, resolveMaxOutputTokensForEngine, } from "./engine/output-tokens.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
@@ -840,20 +840,17 @@ function toolInputActivityLabel(toolName) {
 export function isContextTooLongError(err) {
     if (!(err instanceof Error))
         return false;
-    const msg = err.message.toLowerCase();
-    if (msg.includes("context_length_exceeded") ||
-        msg.includes("input_too_long") ||
-        msg.includes("too many tokens") ||
-        msg.includes("prompt is too long") ||
-        msg.includes("reduce the length") ||
-        // Gemini phrasing
-        msg.includes("input token count exceeds") ||
-        msg.includes("request too large"))
+    // The engine's structural verdict comes first: it was read off the provider's
+    // own reply, which is not always the message delivered here — a
+    // Builder-credits deployment answers every gateway rejection with one visitor
+    // line, and the gateway reports an overflow as a plain `invalid_request_error`
+    // whose prose was the only signal.
+    if (err instanceof EngineError && err.contextOverflow === true)
+        return true;
+    if (isContextOverflowMessage(err.message))
+        return true;
+    if (err instanceof EngineError && isContextOverflowCode(err.errorCode)) {
         return true;
-    if (err instanceof EngineError) {
-        const code = (err.errorCode ?? "").toLowerCase();
-        if (code.includes("context_length") || code.includes("input_too_long"))
-            return true;
     }
     return false;
 }
@@ -1425,8 +1422,10 @@ export async function callConnectedAgentReference(input) {
             orgSecret: callerAuth.orgSecret,
             onUpdate: relay.observePollUpdate,
         });
-        const responseText = userFacingLlmCredentialError(response, { agentName: input.agent }) ??
-            response;
+        const responseText = userFacingLlmCredentialError(response, {
+            agentName: input.agent,
+            visitorFacing: isBuilderGatewayDeployConfigured(),
+        }) ?? response;
         relay.emitResponseText(responseText);
         relay.finish("done");
         return responseText;
@@ -1564,6 +1563,11 @@ export function isResumableEngineError(err) {
     const code = err instanceof EngineError ? (err.errorCode ?? "").toLowerCase() : "";
     if (code === "builder_gateway_timeout" ||
         code === "builder_gateway_network_error" ||
+        // A gateway stream that stopped mid-turn. It reached here as
+        // `builder_gateway_network_error` until the engine named it, and a
+        // continuation is precisely its recovery: the partial turn is preserved and
+        // the agent is nudged to finish it, where an in-call retry would `clear` it.
+        code === "builder_gateway_stream_ended" ||
         code === "provider_network_error") {
         return true;
     }
@@ -1626,6 +1630,13 @@ export function continuationReasonForResumableError(err) {
     const code = err instanceof EngineError ? (err.errorCode ?? "").toLowerCase() : "";
     if (code === "builder_gateway_timeout")
         return "gateway_timeout";
+    // A gateway/proxy timeout status, read structurally. The prose below says the
+    // same thing on most lanes, but not on a Builder-credits deployment, where the
+    // message is one visitor line.
+    if (err instanceof EngineError &&
+        (err.statusCode === 408 || err.statusCode === 504)) {
+        return "gateway_timeout";
+    }
     const text = err instanceof Error ? err.message.toLowerCase() : "";
     if (text.includes("gateway timeout") ||
         text.includes("upstream timeout") ||
@@ -3737,6 +3748,7 @@ export async function runAgentLoop(opts) {
                                     upgradeUrl: event.upgradeUrl,
                                     statusCode: event.statusCode,
                                     providerRetryable: event.providerRetryable,
+                                    contextOverflow: event.contextOverflow,
                                 });
                             }
                         }
@@ -5132,7 +5144,8 @@ function backgroundChatProgressRunId(turnId) {
         .slice(0, 160);
     return `agent-chat-${normalized || "turn"}`;
 }
-function isRecoverableContinuationError(event) {
+/** @internal exported for unit tests only */
+export function isRecoverableContinuationError(event) {
     const code = String(event.errorCode ?? "").toLowerCase();
     const message = event.error.toLowerCase();
     if (code === "builder_gateway_error")
@@ -5147,12 +5160,26 @@ function isRecoverableContinuationError(event) {
     return (event.recoverable === true ||
         code === "builder_gateway_timeout" ||
         code === "builder_gateway_network_error" ||
+        // Server-driven background continuation for a truncated stream. The message
+        // used to carry this ("stream ended without a stop event", classified into
+        // `builder_gateway_network_error` above); the code carries it now, and on a
+        // Builder-credits deployment the code is all that is left.
+        code === "builder_gateway_stream_ended" ||
         code === "provider_network_error" ||
         code === "stale_run" ||
         code === "timeout" ||
         code === "timeout_error" ||
         code === "http_408" ||
         code === "http_429" ||
+        // The 5xx family the message clauses below used to reach by prose alone
+        // ("temporarily unavailable", "gateway timeout"). The client's own
+        // continuation list (sse-event-processor) has always carried these codes;
+        // the server read the sentence instead, which a Builder-credits deployment
+        // replaces with one visitor line.
+        code === "http_500" ||
+        code === "http_502" ||
+        code === "http_503" ||
+        code === "http_504" ||
         code === "http_529" ||
         code === "run_timeout" ||
         message.includes("timeout") ||
@@ -6514,11 +6541,20 @@ export function createProductionAgentHandler(options) {
             setResponseHeader(event, "Cache-Control", "no-cache");
             setResponseHeader(event, "Connection", "keep-alive");
             const encoder = new TextEncoder();
+            // A Builder-credits deployment serves this chat to visitors with no
+            // account, so the owner-facing "connect a provider" copy is unactionable
+            // for them. It is also what they see most of the time once a gateway auth
+            // failure arms the 15-minute marker: the credits lane stops resolving,
+            // engine selection falls back to the anthropic default, and this branch —
+            // not the engine's own error — is what answers the turn.
+            const missingCredentialsError = formatLlmCredentialErrorMessage({
+                visitorFacing: isBuilderGatewayDeployConfigured(),
+            });
             return new ReadableStream({
                 start(controller) {
                     controller.enqueue(encoder.encode(`data: ${JSON.stringify({
                         type: "error",
-                        error: LLM_MISSING_CREDENTIALS_MESSAGE,
+                        error: missingCredentialsError,
                         errorCode: LLM_MISSING_CREDENTIALS_ERROR_CODE,
                     })}\n\n`));
                     controller.close();
@@ -6887,6 +6923,11 @@ export function createProductionAgentHandler(options) {
                 .filter((key) => typeof key === "string")
                 .slice(0, 200)
             : undefined;
+        // The durable approval row is the authorization boundary. Do not require
+        // the client to reproduce the original structured history exactly: the UI
+        // may truncate tool arguments and intentionally assigns fresh replay ids.
+        // The loop still consumes only a matching server-created grant for the
+        // current owner/org/thread/turn/tool/input tuple.
         const exactApprovedToolCall = findApprovedStructuredToolCall(structuredHistory, requestedApprovedToolCalls);
         const firstRequestPayloadDetail = buildFirstRequestPayloadDetail({
             isFirstRequest: history.length === 0,
@@ -6965,14 +7006,7 @@ export function createProductionAgentHandler(options) {
                 return consumeAgentToolApproval(approvalStoreBinding(binding));
             },
         };
-        const exactApprovedToolEntry = exactApprovedToolCall
-            ? requestActions[exactApprovedToolCall.name]
-            : undefined;
-        const approvedToolCallsForExecution = exactApprovedToolCall && exactApprovedToolEntry?.needsApproval
-            ? [
-                toolCallCacheKey(exactApprovedToolCall.name, exactApprovedToolCall.input),
-            ]
-            : undefined;
+        const approvedToolCallsForExecution = requestedApprovedToolCalls;
         if (isBackgroundWorker &&
             (await isTurnAborted(effectiveThreadId, effectiveTurnId))) {
             await markRunAborted(runId, "user").catch(() => { });
@@ -7630,6 +7664,7 @@ export function createProductionAgentHandler(options) {
                         });
                         const message = userFacingLlmCredentialError(err, {
                             agentName: ref.name,
+                            visitorFacing: isBuilderGatewayDeployConfigured(),
                         }) ?? `Failed to run ${ref.name}: ${err?.message}`;
                         return `<agent-response name="${ref.name}" id="${ref.refId}" type="custom-agent" error="true">\n${message}\n</agent-response>`;
                     }
@@ -7670,6 +7705,7 @@ export function createProductionAgentHandler(options) {
                     catch (err) {
                         const message = userFacingLlmCredentialError(err, {
                             agentName: ref.name,
+                            visitorFacing: isBuilderGatewayDeployConfigured(),
                         }) ?? `Failed to reach ${ref.name}: ${err?.message}`;
                         return `<agent-response name="${ref.name}" id="${ref.refId}" error="true">\n${message}\n</agent-response>`;
                     }
@@ -7750,9 +7786,10 @@ export function createProductionAgentHandler(options) {
                 ...(threadId
                     ? { threadId: effectiveThreadId, turnId: effectiveTurnId }
                     : {}),
-                // Human-in-the-loop approval grants for this turn (sanitized — the
-                // request is untrusted; only the exact structured call is passed to
-                // the loop, where the durable grant is consumed atomically.
+                // Human-in-the-loop approval grants for this turn. The request is
+                // untrusted; the durable approval consumer below validates every key
+                // against the authenticated owner/org/thread/turn and consumes it
+                // atomically for the exact tool/input tuple.
                 ...(approvedToolCallsForExecution
                     ? { approvedToolCalls: approvedToolCallsForExecution }
                     : {}),

package/dist/agent/run-manager.js

@@ -323,6 +323,10 @@ function shouldCaptureRunError(err) {
     const normalizedCode = errorCode.toLowerCase();
     return (!normalizedCode.startsWith("credits-limit") &&
         normalizedCode !== "builder_gateway_network_error" &&
+        // A truncated gateway stream, which the client continues. It arrived here as
+        // `builder_gateway_network_error` until the engine gave it its own code, so
+        // omitting it would turn a routine recovered interruption into Sentry noise.
+        normalizedCode !== "builder_gateway_stream_ended" &&
         normalizedCode !== PROVIDER_NETWORK_ERROR_CODE &&
         normalizedCode !== "provider_rate_limited" &&
         normalizedCode !== "rate_limit_exceeded");
@@ -1173,6 +1177,32 @@ export function startRun(runId, threadId, runFn, onComplete, options) {
             ...(err instanceof EngineError && err.upgradeUrl
                 ? { upgradeUrl: err.upgradeUrl }
                 : {}),
+            // The engine's own retry verdict, carried structurally. The client
+            // decides auto-continue from this, `recoverable` and the error code, and
+            // a deployment whose visitor copy replaces the message (Builder credits)
+            // leaves it nothing else to read: without this a provider throttle the
+            // engine marked retryable ends the turn on those sites only.
+            //
+            // NOT `recoverable`. That field is the server's own "this run stopped at
+            // an internal continuation boundary" signal, read by
+            // `isInternalContinuationError` (thread-data-builder) to drop the error
+            // from the persisted turn and by `isRecoverableContinuationError`
+            // (production-agent) to self-chain the next background chunk. Neither
+            // lists `rate_limited` or `too_many_concurrent_requests` today, so
+            // feeding them from the engine verdict would newly chain up to
+            // MAX_BACKGROUND_RUN_CONTINUATIONS invocations into a live throttle — on
+            // every lane, not just Builder credits.
+            ...(err instanceof EngineError && err.providerRetryable === true
+                ? { providerRetryable: true }
+                : {}),
+            // Same reasoning as `providerRetryable`: on the credits lane the message
+            // is the visitor line and the code is `invalid_request_error`, so this
+            // flag is the only thing left that says "trim and retry once". Dropping
+            // it here turns a recoverable overflow into a terminal failure on exactly
+            // the sites that cannot read the real reason.
+            ...(err instanceof EngineError && err.contextOverflow === true
+                ? { contextOverflow: true }
+                : {}),
         });
     })
         .finally(async () => {

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

@@ -10,6 +10,10 @@ function isInternalContinuationError(event) {
         return false;
     return (event.recoverable === true ||
         code === "builder_gateway_timeout" ||
+        // Carries what `msg.includes("stream ended")` below used to: a
+        // Builder-credits deployment replaces that sentence with one visitor line,
+        // and the code is the only thing left that says the turn was truncated.
+        code === "builder_gateway_stream_ended" ||
         code === "stale_run" ||
         code === "timeout" ||
         code === "timeout_error" ||

package/dist/agent/tool-approval-migrations.d.ts

@@ -33,6 +33,7 @@ export declare const AGENT_TOOL_APPROVAL_TABLE_SQL: {
 )`;
 };
 export declare const AGENT_TOOL_APPROVAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_binding\n  ON agent_tool_approvals(owner_email, org_id, thread_id, tool_name, call_id, status)";
+export declare const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_logical\n  ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)";
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.

package/dist/agent/tool-approval-migrations.js

@@ -33,6 +33,8 @@ export const AGENT_TOOL_APPROVAL_TABLE_SQL = {
 };
 export const AGENT_TOOL_APPROVAL_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_binding
   ON agent_tool_approvals(owner_email, org_id, thread_id, tool_name, call_id, status)`;
+export const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_logical
+  ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)`;
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.
@@ -48,4 +50,12 @@ ${AGENT_TOOL_APPROVAL_INDEX_SQL}`,
 ${AGENT_TOOL_APPROVAL_INDEX_SQL}`,
         },
     },
+    {
+        version: 2,
+        name: "agent-tool-approvals-logical-binding-index",
+        sql: {
+            postgres: AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL,
+            sqlite: AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL,
+        },
+    },
 ];

package/dist/agent/tool-approval-store.d.ts

@@ -11,8 +11,10 @@ export interface AgentToolApprovalBinding {
 export declare function hashAgentToolApprovalKey(approvalKey: string): string;
 export declare function createAgentToolApproval(binding: AgentToolApprovalBinding): Promise<void>;
 /**
- * Atomically consume the server-created approval for one exact tool call.
- * Client history and approval keys are only lookup input; the pending row is
- * the authorization boundary and cannot be manufactured by the client.
+ * Atomically consume the server-created approval for one logical tool call.
+ * The model's call id is transport metadata and can change when Dispatch
+ * reconstructs a paused turn, so it is deliberately not part of authorization.
+ * The pending row remains the boundary: client history and approval keys alone
+ * cannot manufacture a grant.
  */
 export declare function consumeAgentToolApproval(binding: AgentToolApprovalBinding): Promise<boolean>;

package/dist/agent/tool-approval-store.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { getDbExec, isPostgres, retryOnDdlRace } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
-import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
+import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
 const APPROVAL_TTL_MS = 15 * 60_000;
 const APPROVAL_CLEANUP_AGE_MS = 24 * 60 * 60_000;
 let initPromise;
@@ -12,11 +12,13 @@ async function ensureAgentToolApprovalTable() {
             if (isPostgres()) {
                 await ensureTableExists("agent_tool_approvals", createSql);
                 await ensureIndexExists("idx_agent_tool_approvals_binding", AGENT_TOOL_APPROVAL_INDEX_SQL);
+                await ensureIndexExists("idx_agent_tool_approvals_logical", AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL);
                 return;
             }
             const client = getDbExec();
             await retryOnDdlRace(() => client.execute(createSql));
             await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_INDEX_SQL));
+            await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL));
         })().catch((error) => {
             initPromise = undefined;
             throw error;
@@ -65,9 +67,11 @@ export async function createAgentToolApproval(binding) {
     }
 }
 /**
- * Atomically consume the server-created approval for one exact tool call.
- * Client history and approval keys are only lookup input; the pending row is
- * the authorization boundary and cannot be manufactured by the client.
+ * Atomically consume the server-created approval for one logical tool call.
+ * The model's call id is transport metadata and can change when Dispatch
+ * reconstructs a paused turn, so it is deliberately not part of authorization.
+ * The pending row remains the boundary: client history and approval keys alone
+ * cannot manufacture a grant.
  */
 export async function consumeAgentToolApproval(binding) {
     await ensureAgentToolApprovalTable();
@@ -80,8 +84,8 @@ export async function consumeAgentToolApproval(binding) {
         WHERE owner_email = ?
           AND ((org_id IS NULL AND CAST(? AS TEXT) IS NULL) OR org_id = ?)
           AND ((thread_id IS NULL AND CAST(? AS TEXT) IS NULL) OR thread_id = ?)
+          AND ((turn_id IS NULL AND CAST(? AS TEXT) IS NULL) OR turn_id = ?)
           AND tool_name = ?
-          AND call_id = ?
           AND approval_key_hash = ?
           AND status = 'pending'
           AND expires_at > ?
@@ -97,8 +101,9 @@ export async function consumeAgentToolApproval(binding) {
             binding.orgId ?? null,
             binding.threadId ?? null,
             binding.threadId ?? null,
+            binding.turnId ?? null,
+            binding.turnId ?? null,
             binding.toolName,
-            binding.callId,
             hashAgentToolApprovalKey(binding.approvalKey),
             now,
         ],

package/dist/agent/types.d.ts

@@ -375,6 +375,15 @@ export type AgentChatEvent = {
     details?: string;
     /** True when the user can reasonably continue/retry from partial work. */
     recoverable?: boolean;
+    /**
+     * The engine's own verdict that another attempt at the same request may
+     * succeed (`EngineError.providerRetryable`). Distinct from `recoverable`,
+     * which the server's continuation classifiers read as "this run ended at
+     * an internal boundary, fold it and chain the next chunk". A provider
+     * throttle is retryable without being a boundary — conflating them makes
+     * a rate limit self-chain background continuations.
+     */
+    providerRetryable?: boolean;
 }
 /**
  * Legacy SSE terminal event. New streams emit

package/dist/cli/code-agent-connector.js

@@ -6,6 +6,7 @@ import { assertValidComputerCommandEnvelope } from "../integrations/computer-sup
 import { serializeBoundedRemoteJson } from "../integrations/remote-json-safety.js";
 import { executeDenyCodeAgentApproval, executePendingCodeAgentApproval, } from "./code-agent-executor.js";
 import { appendCodeAgentTranscriptEvent, codeAgentRunTranscriptPath, codeAgentStoreRoot, createCodeAgentRunRecord, getCodeAgentRunRecord, listCodeAgentRunRecords, normalizeCodeAgentPermissionMode, queueCodeAgentFollowUp, updateCodeAgentRunRecord, } from "./code-agent-runs.js";
+import { appendPortalTransferTranscript, parsePortalTransferContext, } from "./portal-transfer.js";
 import { loadPortalEnvironment, preparePortalWorkspace, parsePortalHandoff, } from "./portal-workspace.js";
 const DEVICE_PATH_ENV = "AGENT_NATIVE_REMOTE_DEVICE_PATH";
 const COMPUTER_BRIDGE_URL_ENV = "AGENT_NATIVE_COMPUTER_BRIDGE_URL";
@@ -203,6 +204,16 @@ class RemoteCodeAgentConnector {
         const metadata = isObject(command.params.metadata)
             ? command.params.metadata
             : {};
+        let portalTransfer = null;
+        try {
+            portalTransfer = parsePortalTransferContext(metadata.portalTransfer);
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
         let cwd = resolveCommandCwd(command.params.cwd ?? this.config.workspacePath);
         let portalWorkspace;
         let portalEnvironment;
@@ -226,6 +237,12 @@ class RemoteCodeAgentConnector {
         if (portalWorkspace && requestedRunId && !isSafeRunId(requestedRunId)) {
             return { ok: false, error: "Portal run id is invalid." };
         }
+        if (portalTransfer && (!portalWorkspace || !requestedRunId)) {
+            return {
+                ok: false,
+                error: "Portal transfer context requires a Portal run id and workspace.",
+            };
+        }
         if (portalWorkspace && requestedRunId) {
             const existing = getCodeAgentRunRecord(requestedRunId);
             const existingRemote = isObject(existing?.metadata?.remote)
@@ -240,12 +257,28 @@ class RemoteCodeAgentConnector {
                 }
                 return { ok: true, runId: existing.id, run: existing, resumed: true };
             }
+            const existingTransfer = isObject(existing?.metadata?.portalTransfer)
+                ? existing.metadata.portalTransfer
+                : undefined;
+            if (portalTransfer &&
+                existing &&
+                firstStringValue(existingTransfer?.sourceRunId) ===
+                    portalTransfer.sourceRunId) {
+                this.remoteRunIds.add(existing.id);
+                this.transcriptCursors.set(existing.id, { offset: 0, seq: 0 });
+                if (!activeRunners.has(existing.id)) {
+                    this.spawnRunner(existing.id, existing.cwd, existing.permissionMode, portalEnvironment?.values);
+                }
+                return { ok: true, runId: existing.id, run: existing, resumed: true };
+            }
         }
         const permissionMode = normalizeCodeAgentPermissionMode(command.params.permissionMode) ??
             "full-auto";
         const engine = firstStringValue(command.params.engine);
         const model = firstStringValue(command.params.model);
         const effort = firstStringValue(command.params.effort, command.params.reasoningEffort);
+        const metadataWithoutTransfer = { ...metadata };
+        delete metadataWithoutTransfer.portalTransfer;
         const run = createCodeAgentRunRecord({
             ...(portalWorkspace && requestedRunId ? { id: requestedRunId } : {}),
             goalId,
@@ -267,6 +300,14 @@ class RemoteCodeAgentConnector {
                 { label: "Prompt", value: truncateForDisplay(prompt, 160) },
                 { label: "Agent", value: "Remote connector" },
                 { label: "Mode", value: permissionMode },
+                ...(portalTransfer
+                    ? [
+                        {
+                            label: "Context",
+                            value: `Imported ${portalTransfer.events.length} transcript events`,
+                        },
+                    ]
+                    : []),
                 ...(portalWorkspace
                     ? [
                         {
@@ -283,7 +324,7 @@ class RemoteCodeAgentConnector {
                     : []),
             ],
             metadata: {
-                ...metadata,
+                ...metadataWithoutTransfer,
                 prompt,
                 source: "remote-connector",
                 engine,
@@ -313,14 +354,45 @@ class RemoteCodeAgentConnector {
                         },
                     }
                     : {}),
+                ...(portalTransfer
+                    ? {
+                        portalTransfer: {
+                            schemaVersion: 1,
+                            sourceRunId: portalTransfer.sourceRunId,
+                            ...(portalTransfer.sourceStatus
+                                ? { sourceStatus: portalTransfer.sourceStatus }
+                                : {}),
+                            ...(portalTransfer.sourcePhase
+                                ? { sourcePhase: portalTransfer.sourcePhase }
+                                : {}),
+                            eventCount: portalTransfer.events.length,
+                            transferredAt: new Date().toISOString(),
+                        },
+                    }
+                    : {}),
             },
         });
-        appendCodeAgentTranscriptEvent({
-            runId: run.id,
-            kind: "user",
-            message: prompt,
-            metadata: { source: "remote-initial-prompt", commandId: command.id },
-        });
+        if (portalTransfer) {
+            appendPortalTransferTranscript(portalTransfer, run.id);
+            appendCodeAgentTranscriptEvent({
+                runId: run.id,
+                kind: "user",
+                message: prompt,
+                metadata: {
+                    source: "portal-transfer-continuation",
+                    commandId: command.id,
+                    sourceRunId: portalTransfer.sourceRunId,
+                },
+            });
+        }
+        else {
+            appendCodeAgentTranscriptEvent({
+                runId: run.id,
+                kind: "user",
+                message: prompt,
+                metadata: { source: "remote-initial-prompt", commandId: command.id },
+            });
+        }
         appendCodeAgentTranscriptEvent({
             runId: run.id,
             kind: "status",

package/dist/cli/portal-transfer.d.ts

@@ -0,0 +1,43 @@
+export declare const PORTAL_TRANSFER_SCHEMA_VERSION: 1;
+export declare const PORTAL_TRANSFER_MAX_CONTEXT_BYTES = 900000;
+export type PortalTransferEventKind = "user" | "system" | "note" | "artifact" | "status";
+export interface PortalTransferTranscriptEvent {
+    schemaVersion: 1;
+    id: string;
+    kind: PortalTransferEventKind;
+    message: string;
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+    signal?: "credential-gap";
+}
+export interface PortalTransferContext {
+    schemaVersion: 1;
+    sourceRunId: string;
+    sourceStatus?: string;
+    sourcePhase?: string;
+    events: PortalTransferTranscriptEvent[];
+}
+export interface PortalTransferSourceEvent {
+    id?: unknown;
+    runId?: unknown;
+    kind?: unknown;
+    type?: unknown;
+    message?: unknown;
+    text?: unknown;
+    createdAt?: unknown;
+    metadata?: unknown;
+    signal?: unknown;
+}
+export declare function createPortalTransferContext(input: {
+    sourceRunId: string;
+    sourceStatus?: string;
+    sourcePhase?: string;
+    events: readonly PortalTransferSourceEvent[];
+}): PortalTransferContext;
+export declare function parsePortalTransferContext(value: unknown): PortalTransferContext | null;
+export declare function appendPortalTransferTranscript(context: PortalTransferContext, runId: string): number;
+export declare function portalTransferContinuationPrompt(input: {
+    hostLabel: string;
+    handoffId: string;
+    eventCount: number;
+}): string;