nolo-cli 0.1.29 → 0.1.31

package/server/handlers/agentRun/index.ts

@@ -28,13 +28,41 @@
 
 import { createHash } from "node:crypto";
 import { ulid } from "ulid";
+import { userActor } from "../../../auth/actor";
 import { authenticateRequest } from "../../../auth/utils";
 import { WEB_AUTH_TOKEN_COOKIE } from "../../../auth/tokenCookie";
 import { getUser } from "../../../auth/server/getUser";
 import { checkBasicBalance } from "../../../auth/billing";
+import {
+    GPT_PRO_REQUIRED_BALANCE,
+    hasGptProTierAccess,
+    isGptProModel,
+} from "../../../auth/server/gptProAccess";
 import { chargeTokenUsageWithLedger } from "../../../auth/server/tokenUsageBilling";
 import { writeServerTokenRecord } from "../../../ai/token/serverTokenWriter";
-import serverDb, { ensureServerDbOpen } from "../../../database/server/db";
+import {
+    createProviderCallCompletedEvent,
+    createProviderCallPendingEvent,
+    type ProviderCallEvent,
+} from "../../../ai/token/providerCall";
+import { writeProviderCallEvent } from "../../../ai/token/providerCallWriter";
+import {
+    createProviderBillableEvent,
+    type ProviderBillableEvent,
+} from "../../../ai/token/providerBillableEvent";
+import { writeProviderBillableEvent } from "../../../ai/token/providerBillableEventWriter";
+import { createRatingResult, type RatingResult } from "../../../ai/token/ratingResult";
+import { writeRatingResult } from "../../../ai/token/ratingResultWriter";
+import type { Usage } from "../../../ai/token/calculatePrice";
+import {
+    createBillingAnomaly,
+    type BillingAnomaly,
+    type BillingAnomalyKind,
+    type BillingAnomalySeverity,
+    type BillingAnomalyStage,
+} from "../../../ai/token/billingAnomaly";
+import { writeBillingAnomaly } from "../../../ai/token/billingAnomalyWriter";
+import { ensureServerDbOpen, getServerAuthorityStore } from "../../../database/server/db";
 import { runAgentLoop, buildSseStream } from "./loop";
 import { incActiveStream, decActiveStream } from "../../serverDrain";
 import { saveRunAsDialog, createPendingDialog, finalizeDialog, appendToExistingDialog } from "./saveDialog";
@@ -71,7 +99,6 @@ import {
 } from "./builtinAgents";
 import { resolveAgentRunAgentConfig } from "./agentLookup";
 import {
-    resolveAgentRunDelegation,
     resolveMachineBindingPreflight,
 } from "./runtimeRouting";
 import {
@@ -83,7 +110,7 @@ import {
 } from "./requestContext";
 import { buildAgentRunDebugContext } from "./debugContext";
 import { resolveAgentRunBilledUsage } from "./runBilling";
-import { buildInheritedDialogPromptBlock } from "./inheritedDialogPrompt";
+import { buildConversationReferenceBlock } from "./conversationReference";
 import { completeSyncAgentRunDialog } from "./syncRunDialog";
 import {
     AGENT_RUN_CORS_HEADERS as CORS,
@@ -94,6 +121,7 @@ import {
 import { machineRegistry } from "../machines/machineRegistry";
 import {
     ConnectorOfflineError,
+    InvalidBoundMachineConfigError,
     type MachineConnectorRunProgress,
     resolveAgentRuntimeMachineId,
     runViaMachineConnector,
@@ -112,6 +140,9 @@ type AgentRunBillingInput = Parameters<typeof resolveAgentRunBilledUsage>[0] & {
 const DEFAULT_BACKGROUND_RUN_TIMEOUT_MS = 10 * 60_000;
 const DEFAULT_RUNTIME_PROMPT_PAGE_THRESHOLD_BYTES = 32_000;
 
+const getAgentRunStore = () => getServerAuthorityStore();
+const serverDb = getAgentRunStore();
+
 function byteLength(value: string) {
     return Buffer.byteLength(value, "utf8");
 }
@@ -209,7 +240,11 @@ async function withBackgroundRunTimeout<T>(
     }
 }
 
-async function chargeAgentRunTokenCost(userId: string, tokenWrite: AgentRunTokenWrite) {
+async function chargeAgentRunTokenCost(
+    userId: string,
+    tokenWrite: AgentRunTokenWrite,
+    ledgerIdempotencyKey: string,
+) {
     return chargeTokenUsageWithLedger({
         store: serverDb,
         userId,
@@ -217,9 +252,193 @@ async function chargeAgentRunTokenCost(userId: string, tokenWrite: AgentRunToken
         tokenRecord: tokenWrite.tokenRecord,
         reason: "agent_run",
         txId: `token-${tokenWrite.recordKey}`,
+        ledgerIdempotencyKey,
+        allowBuyerNegative: true,
     });
 }
 
+function buildAggregateProviderCallLedgerIdempotencyKey(providerCallIds: string[]) {
+    const stableSource = [...new Set(providerCallIds)].sort().join("|");
+    const sourceHash = createHash("sha256").update(stableSource).digest("hex").slice(0, 16);
+    return `provider-call-group:sha256-${sourceHash}:charge:v1`;
+}
+
+async function writeProviderCallEventSafely(event: ProviderCallEvent) {
+    try {
+        await writeProviderCallEvent({ store: serverDb, event });
+    } catch (error) {
+        console.warn("[billing] Provider-call evidence write failed", {
+            providerCallId: event.providerCallId,
+            eventId: event.eventId,
+            status: event.status,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        await writeBillingAnomalySafely(createAgentRunBillingAnomaly({
+            kind: "provider_call_write_failed",
+            severity: "high",
+            stage: "provider_call",
+            userId: event.userId,
+            dialogId: event.dialogId,
+            agentId: event.agentId,
+            provider: event.provider,
+            model: event.model,
+            providerCallId: event.providerCallId,
+            message: "Provider-call evidence write failed",
+            evidence: {
+                eventId: event.eventId,
+                eventStatus: event.status,
+                error: error instanceof Error ? error.message : String(error),
+            },
+        }));
+    }
+}
+
+async function writeBillingAnomalySafely(anomaly: BillingAnomaly) {
+    try {
+        await writeBillingAnomaly({ store: serverDb, anomaly });
+    } catch (error) {
+        console.warn("[billing] Billing anomaly write failed", {
+            anomalyId: anomaly.id,
+            kind: anomaly.kind,
+            providerCallId: anomaly.providerCallId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}
+
+function createAgentRunBillingAnomaly(args: {
+    kind: BillingAnomalyKind;
+    severity: BillingAnomalySeverity;
+    stage: BillingAnomalyStage;
+    userId: string;
+    dialogId?: string;
+    agentId?: string;
+    provider: string;
+    model: string;
+    providerCallId?: string;
+    billableEventId?: string;
+    ratingResultId?: string;
+    riskPlatformCredits?: number;
+    message: string;
+    evidence: Record<string, unknown>;
+}) {
+    return createBillingAnomaly({
+        anomalyId: `anom_${ulid()}`,
+        kind: args.kind,
+        severity: args.severity,
+        stage: args.stage,
+        userId: args.userId,
+        dialogId: args.dialogId,
+        agentId: args.agentId,
+        provider: args.provider,
+        model: args.model,
+        providerCallId: args.providerCallId,
+        billableEventId: args.billableEventId,
+        ratingResultId: args.ratingResultId,
+        riskPlatformCredits: args.riskPlatformCredits,
+        message: args.message,
+        evidence: args.evidence,
+        createdAt: new Date().toISOString(),
+    });
+}
+
+async function writeProviderBillableEventSafely(event: ProviderBillableEvent) {
+    try {
+        await writeProviderBillableEvent({ store: serverDb, event });
+    } catch (error) {
+        console.warn("[billing] Provider billable event write failed", {
+            billableEventId: event.id,
+            sourceProviderCallIds: event.sourceProviderCallIds,
+            provider: event.provider,
+            model: event.model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        await writeBillingAnomalySafely(createAgentRunBillingAnomaly({
+            kind: "billable_event_write_failed",
+            severity: "high",
+            stage: "billable_event",
+            userId: event.userId,
+            dialogId: event.dialogId,
+            agentId: event.agentId,
+            provider: event.provider,
+            model: event.model,
+            providerCallId: event.sourceProviderCallIds[0],
+            billableEventId: event.id,
+            message: "Provider billable event write failed",
+            evidence: {
+                sourceProviderCallIds: event.sourceProviderCallIds,
+                error: error instanceof Error ? error.message : String(error),
+            },
+        }));
+    }
+}
+
+async function writeRatingResultSafely(
+    rating: RatingResult,
+    context: {
+        userId: string;
+        dialogId?: string;
+        agentId?: string;
+        providerCallId?: string;
+    },
+) {
+    try {
+        await writeRatingResult({ store: serverDb, rating });
+    } catch (error) {
+        console.warn("[billing] Rating result write failed", {
+            ratingId: rating.id,
+            billableEventId: rating.billableEventId,
+            provider: rating.provider,
+            model: rating.model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        await writeBillingAnomalySafely(createAgentRunBillingAnomaly({
+            kind: "rating_failed",
+            severity: "high",
+            stage: "rating",
+            userId: context.userId,
+            dialogId: context.dialogId,
+            agentId: context.agentId,
+            provider: rating.provider,
+            model: rating.model,
+            providerCallId: context.providerCallId,
+            billableEventId: rating.billableEventId,
+            ratingResultId: rating.id,
+            riskPlatformCredits: rating.platformCredits,
+            message: "Rating result write failed",
+            evidence: {
+                error: error instanceof Error ? error.message : String(error),
+                snapshot: rating.snapshot,
+            },
+        }));
+    }
+}
+
+function numberOrZero(value: unknown) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
+function normalizeAgentRunBillingUsage(rawUsage: Record<string, any>): Usage {
+    return {
+        input_tokens: numberOrZero(rawUsage.input_tokens ?? rawUsage.prompt_tokens),
+        output_tokens: numberOrZero(rawUsage.output_tokens ?? rawUsage.completion_tokens),
+        cache_creation_input_tokens: numberOrZero(rawUsage.cache_creation_input_tokens),
+        cache_read_input_tokens: numberOrZero(rawUsage.cache_read_input_tokens),
+        ...(typeof rawUsage.cost === "number" ? { cost: rawUsage.cost } : {}),
+        ...(typeof rawUsage.billing_service_tier === "string"
+            ? { billing_service_tier: rawUsage.billing_service_tier }
+            : {}),
+        ...(typeof rawUsage.image_generation_count === "number"
+            ? { image_generation_count: rawUsage.image_generation_count }
+            : {}),
+    };
+}
+
+function resolveEstimateReason(rawUsage: Record<string, any>) {
+    const reason = rawUsage.billing_estimate_reason ?? rawUsage.estimateReason ?? rawUsage.estimate_reason;
+    return typeof reason === "string" && reason.trim() ? reason.trim() : undefined;
+}
+
 async function projectBackgroundDialogActivity(args: {
     dialogId: string;
     dialogKey: string;
@@ -384,6 +603,43 @@ async function writeAgentRunBillingIfNeeded(args: AgentRunBillingInput) {
         });
         if (!args.userId || !billedUsage) return;
 
+        const rawUsage = billedUsage as any;
+        const physicalProviderCallIds = Array.isArray(args.result.providerCallIds)
+            ? args.result.providerCallIds.filter((id): id is string => typeof id === "string" && id.trim().startsWith("call_"))
+            : [];
+        const hasAggregatePhysicalUsage = physicalProviderCallIds.length > 1;
+        const providerCallId = physicalProviderCallIds[physicalProviderCallIds.length - 1] ?? `call_${ulid()}`;
+        const providerCallStartedAt = new Date().toISOString();
+        const billingProvider =
+            rawUsage.billing_provider ??
+            billingAgentConfig.provider ??
+            args.result.provider ??
+            "unknown";
+        const billingModel =
+            rawUsage.billing_model ??
+            billingAgentConfig.model ??
+            args.result.model ??
+            "unknown";
+        const billingServiceTier =
+            rawUsage.billing_service_tier ??
+            billingAgentConfig.billingServiceTier ??
+            billingAgentConfig.serviceTier;
+
+        if (physicalProviderCallIds.length === 0) {
+            await writeProviderCallEventSafely(createProviderCallPendingEvent({
+                providerCallId,
+                eventId: `evt_${ulid()}`,
+                userId: args.userId,
+                dialogId: args.dialogId,
+                agentId: args.agentKey,
+                provider: billingProvider,
+                model: billingModel,
+                endpoint: "agentRun",
+                ...(billingServiceTier ? { serviceTier: String(billingServiceTier) } : {}),
+                startedAt: providerCallStartedAt,
+            }));
+        }
+
         const tokenWrite = await writeServerTokenRecord({
             userId: args.userId,
             agentKey: args.agentKey,
@@ -391,7 +647,120 @@ async function writeAgentRunBillingIfNeeded(args: AgentRunBillingInput) {
             runId: args.dialogId,
             rawUsage: billedUsage as any,
         });
-        if (tokenWrite.cost > 0) await chargeAgentRunTokenCost(args.userId, tokenWrite);
+        const normalizedBillingUsage = normalizeAgentRunBillingUsage(rawUsage);
+        if (!hasAggregatePhysicalUsage) {
+            await writeProviderCallEventSafely(createProviderCallCompletedEvent({
+                providerCallId,
+                eventId: `evt_${ulid()}`,
+                userId: args.userId,
+                dialogId: args.dialogId,
+                agentId: args.agentKey,
+                provider: billingProvider,
+                model: billingModel,
+                endpoint: "agentRun",
+                ...(billingServiceTier ? { serviceTier: String(billingServiceTier) } : {}),
+                startedAt: providerCallStartedAt,
+                completedAt: new Date().toISOString(),
+                inputTokens: normalizedBillingUsage.input_tokens,
+                outputTokens: normalizedBillingUsage.output_tokens,
+                cacheCreationInputTokens: normalizedBillingUsage.cache_creation_input_tokens,
+                cacheReadInputTokens: normalizedBillingUsage.cache_read_input_tokens,
+                platformCredits: tokenWrite.cost,
+                pricingVersion: "model-registry-current",
+                billingStatus: tokenWrite.cost > 0 ? "pending_ledger" : "zero_policy",
+            }));
+        }
+        const billableEventId = `billable_${ulid()}`;
+        const ledgerIdempotencyKey = hasAggregatePhysicalUsage
+            ? buildAggregateProviderCallLedgerIdempotencyKey(physicalProviderCallIds)
+            : `provider-call:${providerCallId}:charge:v1`;
+        const billableEvent = createProviderBillableEvent({
+            eventId: billableEventId,
+            operationId: args.dialogId,
+            sourceProviderCallIds: physicalProviderCallIds.length > 0
+                ? [...physicalProviderCallIds]
+                : [providerCallId],
+            userId: args.userId,
+            dialogId: args.dialogId,
+            agentId: args.agentKey,
+            provider: billingProvider,
+            model: billingModel,
+            endpoint: "agentRun",
+            kind: "llm_tokens",
+            usage: {
+                inputTokens: normalizedBillingUsage.input_tokens,
+                outputTokens: normalizedBillingUsage.output_tokens,
+                cacheCreationInputTokens: normalizedBillingUsage.cache_creation_input_tokens,
+                cacheReadInputTokens: normalizedBillingUsage.cache_read_input_tokens,
+            },
+            estimated: rawUsage.billing_estimated === true,
+            estimateReason: resolveEstimateReason(rawUsage),
+            needsReconciliation: hasAggregatePhysicalUsage,
+            createdAt: new Date().toISOString(),
+        });
+        await writeProviderBillableEventSafely(billableEvent);
+        if (hasAggregatePhysicalUsage) {
+            await writeBillingAnomalySafely(createAgentRunBillingAnomaly({
+                kind: "aggregate_usage_unallocated",
+                severity: "medium",
+                stage: "usage",
+                userId: args.userId,
+                dialogId: args.dialogId,
+                agentId: args.agentKey,
+                provider: billingProvider,
+                model: billingModel,
+                providerCallId,
+                billableEventId,
+                riskPlatformCredits: tokenWrite.cost,
+                message: "Aggregate agent-run usage spans multiple physical provider calls and needs per-call allocation",
+                evidence: {
+                    sourceProviderCallIds: physicalProviderCallIds,
+                    ledgerIdempotencyKey,
+                    usage: normalizedBillingUsage,
+                    tokenKey: tokenWrite.recordKey,
+                },
+            }));
+        }
+        await writeRatingResultSafely(createRatingResult({
+            ratingId: `rating_${ulid()}`,
+            billableEventId,
+            provider: billingProvider,
+            model: billingModel,
+            ...(billingServiceTier ? { serviceTier: String(billingServiceTier) } : {}),
+            usage: normalizedBillingUsage,
+            createdAt: new Date().toISOString(),
+        }), {
+            userId: args.userId,
+            dialogId: args.dialogId,
+            agentId: args.agentKey,
+            providerCallId,
+        });
+        if (tokenWrite.cost > 0) {
+            const ledgerResult = await chargeAgentRunTokenCost(args.userId, tokenWrite, ledgerIdempotencyKey);
+            if (!ledgerResult.success) {
+                await writeBillingAnomalySafely(createAgentRunBillingAnomaly({
+                    kind: "ledger_failed",
+                    severity: "critical",
+                    stage: "ledger",
+                    userId: args.userId,
+                    dialogId: args.dialogId,
+                    agentId: args.agentKey,
+                    provider: billingProvider,
+                    model: billingModel,
+                    providerCallId,
+                    billableEventId,
+                    riskPlatformCredits: tokenWrite.cost,
+                    message: "Provider-call ledger charge failed",
+                    evidence: {
+                        ledgerStatus: ledgerResult.status,
+                        error: ledgerResult.error,
+                        tokenKey: tokenWrite.recordKey,
+                        txId: ledgerResult.txId,
+                        ledgerIdempotencyKey,
+                    },
+                }));
+            }
+        }
     } catch (error) {
         console.warn("[billing] Agent run billing write failed; preserving dialog result", {
             dialogId: args.dialogId,
@@ -455,16 +824,11 @@ const extractAgentRunUserText = (userInput: AgentRunRequest["userInput"]): strin
 const buildAgentRunUserMessageContent = (
     userInput: AgentRunRequest["userInput"],
     turnInstruction?: string | null,
-    prelude?: string | null,
 ): ChatMessage["content"] => {
     const normalizedTurnInstruction =
         typeof turnInstruction === "string" && turnInstruction.trim()
             ? turnInstruction.trim()
             : "";
-    const normalizedPrelude =
-        typeof prelude === "string" && prelude.trim()
-            ? prelude.trim()
-            : "";
     const normalizedParts = normalizeAgentRunUserParts(userInput);
     if (normalizedParts.length > 0) {
         // Inject URL hints so the model uses original HTTPS URLs in tool calls
@@ -484,9 +848,6 @@ const buildAgentRunUserMessageContent = (
                 : null;
 
         return [
-            ...(normalizedPrelude
-                ? [{ type: "text" as const, text: `${normalizedPrelude}\n\n--- User task ---` }]
-                : []),
             ...(normalizedTurnInstruction
                 ? [{ type: "text" as const, text: `${normalizedTurnInstruction}\n\n--- User task ---` }]
                 : []),
@@ -503,14 +864,13 @@ const buildAgentRunUserMessageContent = (
     }
 
     const userText = extractAgentRunUserText(userInput);
-    const prefix = [normalizedPrelude, normalizedTurnInstruction].filter(Boolean).join("\n\n");
-    if (!prefix) {
+    if (!normalizedTurnInstruction) {
         return userText;
     }
     if (!userText) {
-        return prefix;
+        return normalizedTurnInstruction;
     }
-    return [prefix, "--- User task ---", userText].join("\n\n");
+    return [normalizedTurnInstruction, "--- User task ---", userText].join("\n\n");
 };
 
 function resolveDirectSpecialistAgentKey(args: {
@@ -655,6 +1015,7 @@ function buildBillableForegroundSseStream(
             let lastInputPrice = context.agentConfig.inputPrice;
             let lastOutputPrice = context.agentConfig.outputPrice;
             let lastArtifacts: unknown;
+            let lastProviderCallIds: string[] | undefined;
             let toolCallCount = 0;
             let sawDone = false;
             const trace: ChatMessage[] = [];
@@ -711,6 +1072,11 @@ function buildBillableForegroundSseStream(
                             ? payload.outputPrice
                             : lastOutputPrice;
                     lastArtifacts = payload.artifacts ?? lastArtifacts;
+                    if (Array.isArray(payload.providerCallIds)) {
+                        lastProviderCallIds = payload.providerCallIds.filter(
+                            (id: unknown): id is string => typeof id === "string" && id.trim()
+                        );
+                    }
                     if (assistantText) {
                         trace.push({ role: "assistant", content: assistantText });
                     }
@@ -750,6 +1116,7 @@ function buildBillableForegroundSseStream(
                         inputPrice: lastInputPrice,
                         outputPrice: lastOutputPrice,
                         usage: lastUsage,
+                        ...(lastProviderCallIds?.length ? { providerCallIds: lastProviderCallIds } : {}),
                         ...(lastArtifacts ? { artifacts: lastArtifacts } : {}),
                         trace,
                         runtimeToolNames: [],
@@ -850,6 +1217,13 @@ function shouldBypassBalanceForLocalSmokeAgent(
 }
 
 function resolveConnectorFailureResponse(error: any, agentConfig: any): Response | null {
+    if (error instanceof InvalidBoundMachineConfigError) {
+        return agentRunJson({
+            error: "Invalid runtime binding",
+            reason: error.reason,
+            message: error.message,
+        }, error.status);
+    }
     if (error instanceof ConnectorOfflineError) {
         return agentRunJson({
             error: "Connector offline",
@@ -925,7 +1299,7 @@ export async function handleAgentRun(req: Request): Promise<Response> {
     const {
         requestedAgentKey,
         userInput,
-        history,
+        requestHistory,
         stream,
         runtimeContext,
         effectiveMaxRounds,
@@ -978,32 +1352,18 @@ export async function handleAgentRun(req: Request): Promise<Response> {
     try { await ensureServerDbOpen(); } catch (e: any) { return agentRunError(e.message, 500); }
     const agentLookup = await resolveAgentRunAgentConfig({
         agentKey,
-        getAgentRecord: (key) => serverDb.get(key),
+        getAgentRecord: (key) => getAgentRunStore().get(key),
     });
     if (!agentLookup.ok) {
         return agentRunError(agentLookup.message, agentLookup.status);
     }
-    let agentConfig: any = agentLookup.agentConfig;
-    agentConfig = {
-        ...agentConfig,
-        dbKey: agentConfig.dbKey ?? agentKey,
+    const storedAgentConfig = {
+        ...agentLookup.agentConfig,
+        dbKey: agentLookup.agentConfig.dbKey ?? agentKey,
     };
 
-    const runtimeDelegation = resolveAgentRunDelegation({ agentConfig, serverBase });
-    if (!runtimeDelegation.ok) {
-        return agentRunError(runtimeDelegation.message, runtimeDelegation.status);
-    }
-    if (runtimeDelegation.route === "remote") {
-        return proxyAgentRunToRemote({
-            targetBase: runtimeDelegation.targetBase,
-            body,
-            authToken,
-            stream,
-        });
-    }
-
     const machineBinding = resolveMachineBindingPreflight({
-        agentConfig,
+        agentConfig: storedAgentConfig,
         userId,
         listMachines: (ownerUserId) => machineRegistry.listMachines(ownerUserId),
     });
@@ -1016,47 +1376,83 @@ export async function handleAgentRun(req: Request): Promise<Response> {
         authToken,
     });
     const taskRunPreflightPrompt = taskRunPreflight.prompt;
-    agentConfig = await prepareAgentRunRuntimeConfig({
-        agentConfig,
+    const currentUserActor = userActor(userId);
+    const fetchAuthorizedDialogMessages = (args: { dialogId: string; limit: number }) =>
+        fetchConvMsgs(args, {
+            userId,
+            actor: currentUserActor,
+        });
+    if (continueDialogId && (body.inheritedFromDialogKey || body.parentDialogId)) {
+        console.info("[agentRun] continue-history-overrides-inherited-reference", {
+            continueDialogId,
+            inheritedFromDialogKey: body.inheritedFromDialogKey ?? null,
+            parentDialogId: body.parentDialogId ?? null,
+        });
+    }
+    const preparedRuntimeConfig = await prepareAgentRunRuntimeConfig({
+        agentConfig: storedAgentConfig,
         runtimeContext,
         taskRunPreflightPrompt,
         runtimeOptions,
         parentDialogId,
         inheritedFromDialogKey,
+        includeConversationReference: !continueDialogId,
         resolveReferenceRuntime: (references) =>
             resolveServerReferenceRuntime({
                 references,
                 loadPage: async (identifier: string) => {
                     try {
-                        return await serverDb.get(identifier);
+                        return await getAgentRunStore().get(identifier);
                     } catch {
                         return null;
                     }
                 },
             }),
-        buildInheritedDialogPromptBlock: (args) =>
-            buildInheritedDialogPromptBlock({
+        buildConversationReferenceBlock: (args) =>
+            buildConversationReferenceBlock({
                 ...args,
                 getDialogRecord: async (dialogKey) => {
                     try {
-                        return await serverDb.get(dialogKey);
+                        return await getAgentRunStore().get(dialogKey);
                     } catch {
                         return null;
                     }
                 },
-                fetchConversationMessages: fetchConvMsgs,
+                fetchConversationMessages: fetchAuthorizedDialogMessages,
             }),
     });
+    const {
+        runtimeEntrypointBlock,
+        taskRunPreflightBlock,
+        referenceRuntimeBlock,
+        conversationReferenceBlock,
+        editingContextBlock,
+        ...preparedAgentConfig
+    } = preparedRuntimeConfig;
+    const runtimePreparedAgentConfig = preparedAgentConfig;
     const runtimeToolPolicySnapshot = resolveEffectiveRuntimeToolPolicy({
-        agentConfig,
-        taskRunControl: taskRunPreflight.control,
-        host: "web",
+        agentConfig: runtimePreparedAgentConfig,
     });
 
     // 余额检查（仅 JWT 登录用户）
-    const bypassBalanceCheck = shouldBypassBalanceForLocalSmokeAgent(agentKey, agentConfig, serverBase);
+    const bypassBalanceCheck = shouldBypassBalanceForLocalSmokeAgent(
+        agentKey,
+        runtimePreparedAgentConfig,
+        serverBase,
+    );
     if (userId && !bypassBalanceCheck) {
         const user = await getUser(userId);
+        if (isGptProModel(runtimePreparedAgentConfig.provider, runtimePreparedAgentConfig.model)) {
+            const gptProAccess = hasGptProTierAccess({ userData: user });
+            if (!gptProAccess.allowed) {
+                return agentRunJson({
+                    error: "GPT Pro requires 199 current balance",
+                    reason: "gpt_pro_tier_required",
+                    requiredBalance: GPT_PRO_REQUIRED_BALANCE,
+                    message: `GPT Pro 系列需要当前余额大于等于 ${GPT_PRO_REQUIRED_BALANCE}。`,
+                }, 402);
+            }
+        }
         const balanceCheck = checkBasicBalance(user?.balance ?? 0);
         if (!balanceCheck.allowed) {
             return agentRunJson({ error: balanceCheck.error }, 402);
@@ -1070,15 +1466,15 @@ export async function handleAgentRun(req: Request): Promise<Response> {
         continueDialogUserId,
     } = await resolveContinueDialogContext({
         continueDialogId,
-        history,
+        requestHistoryFallback: requestHistory,
         userId,
         resolveExistingDialogRef,
-        fetchConvMsgs,
+        fetchConvMsgs: fetchAuthorizedDialogMessages,
         summarizeMessagesForDebug,
     });
 
     const executionContext = await prepareAgentRunExecutionContext({
-        agentConfig,
+        agentConfig: runtimePreparedAgentConfig,
         agentKey,
         userId,
         userInput,
@@ -1087,9 +1483,13 @@ export async function handleAgentRun(req: Request): Promise<Response> {
         spaceId,
         runtimeProfile,
         existingDialogRecord,
-        taskRunPreflightPrompt,
+        runtimeEntrypointBlock,
+        taskRunPreflightBlock,
+        referenceRuntimeBlock,
+        conversationReferenceBlock,
+        editingContextBlock,
         loadUserSettings: (settingsUserId) =>
-            serverDb.get(createUserKey.settings(settingsUserId)),
+            getAgentRunStore().get(createUserKey.settings(settingsUserId)),
         resolveRuntimePolicy,
         buildUserPolicyContext,
         resolveMemoryRuntime,
@@ -1099,16 +1499,125 @@ export async function handleAgentRun(req: Request): Promise<Response> {
         canonicalizeToolNames,
         prioritizeToolNames,
     });
-    agentConfig = executionContext.agentConfig;
-    const runtimePolicy = executionContext.runtimePolicy;
+    const executionAgentConfig = executionContext.agentConfig;
+    const executionRuntimePolicy = executionContext.runtimePolicy;
     const effectiveRuntimeProfile = executionContext.effectiveRuntimeProfile;
-    const memoryRuntime = executionContext.memoryRuntime;
-    const autonomousRuntime = executionContext.autonomousRuntime;
+    const executionMemoryRuntime = executionContext.memoryRuntime;
     const runtimeSystemMessageContext = executionContext.runtimeSystemMessageContext;
-    const messages = executionContext.messages;
+    const executionMessages = executionContext.messages;
+    const executionMachineId = resolveAgentRuntimeMachineId(executionAgentConfig);
+    const buildExecutionWorkspaceLease = (
+        connectorResult: ConnectorAgentRunResult | null | undefined,
+    ) =>
+        buildWorkspaceLeaseFromConnectorResult({
+            result: connectorResult,
+            agentKey,
+            machineId: executionMachineId,
+            runtimeToolPolicySnapshot,
+        });
+    const runExecutionConnector = async (args: {
+        userId: string;
+        requestTimeoutMs?: number;
+        runtimePromptPage?: Record<string, unknown> | null;
+        onProgress?: (progress: MachineConnectorRunProgress) => Promise<void>;
+    }) =>
+        runViaMachineConnector({
+            agentConfig: executionAgentConfig,
+            agentKey,
+            authToken,
+            category,
+            continueDialogId: continueDialogId ?? undefined,
+            messages: executionMessages,
+            runtimeContext,
+            spaceId,
+            userId: args.userId,
+            userInput: userInputText,
+            requestTimeoutMs: args.requestTimeoutMs,
+            runtimeToolPolicySnapshot,
+            ...(args.runtimePromptPage ? { runtimePromptPage: args.runtimePromptPage } : {}),
+            ...(args.onProgress ? { onProgress: args.onProgress } : {}),
+        });
+    const runExecutionLoop = (args: {
+        userId: string;
+        dialogId?: string;
+        spaceId?: string | null;
+    }) =>
+        runAgentLoopImpl(
+            executionAgentConfig,
+            executionMessages,
+            effectiveMaxRounds,
+            serverBase,
+            authToken,
+            executionRuntimePolicy,
+            args.userId,
+            args.dialogId,
+            args.spaceId,
+            userInputText,
+            runtimeContext,
+            serverDb,
+        );
+    const runExecutionResult = async (args: {
+        userId: string;
+        dialogId?: string;
+        spaceId?: string | null;
+        requestTimeoutMs?: number;
+        runtimePromptPage?: Record<string, unknown> | null;
+        onProgress?: (progress: MachineConnectorRunProgress) => Promise<void>;
+    }) => {
+        const connectorResult = await runExecutionConnector({
+            userId: args.userId,
+            requestTimeoutMs: args.requestTimeoutMs,
+            runtimePromptPage: args.runtimePromptPage,
+            onProgress: args.onProgress,
+        });
+        return {
+            connectorResult,
+            workspaceLease: buildExecutionWorkspaceLease(connectorResult),
+            result: (connectorResult ?? await runExecutionLoop({
+                userId: args.userId,
+                dialogId: args.dialogId,
+                spaceId: args.spaceId,
+            })) as LoopResult,
+        };
+    };
+    const buildExecutionSourceStream = (args: {
+        userId: string;
+        dialogId: string;
+        spaceId?: string | null;
+    }) =>
+        buildSseStreamImpl(
+            executionAgentConfig,
+            executionMessages,
+            effectiveMaxRounds,
+            serverBase,
+            authToken,
+            executionRuntimePolicy,
+            args.userId,
+            args.dialogId,
+            args.spaceId,
+            userInputText,
+            runtimeContext,
+            serverDb,
+        );
+    const dialogLifecyclePersistenceContext = {
+        userId,
+        callerType,
+        userInput: userInputText,
+        spaceId,
+        category,
+        inheritedFromDialogKey,
+        parentDialogId,
+        runtimeProfile: effectiveRuntimeProfile,
+        runtimeContext,
+        runtimeToolPolicySnapshot,
+    };
+    const buildPendingDialogInput = (pendingAgentKey: string) => ({
+        agentKey: pendingAgentKey,
+        ...dialogLifecyclePersistenceContext,
+    });
 
     try {
-        await ensureLocalModelRuntimeIfNeeded(agentConfig);
+        await ensureLocalModelRuntimeIfNeeded(executionAgentConfig);
     } catch (e: any) {
         if (isLocalRuntimeUnavailableError(e)) {
             return agentRunJson({
@@ -1139,112 +1648,81 @@ export async function handleAgentRun(req: Request): Promise<Response> {
             continueDialogUserId,
             fallbackSpaceId: spaceId,
             createPendingDialog,
-            pendingDialogInput: {
-                agentKey: dialogAgentKey,
-                userId,
-                callerType,
-                userInput: userInputText,
-                spaceId,
-                category,
-                inheritedFromDialogKey,
-                parentDialogId,
-                runtimeProfile: effectiveRuntimeProfile,
-                runtimeContext,
-                runtimeToolPolicySnapshot,
-            },
+            pendingDialogInput: buildPendingDialogInput(dialogAgentKey),
         });
         return {
             ...prepared,
             persistDialog: true,
         };
     };
+    const buildForegroundStreamLifecycleContext = (args: {
+        streamDialog: Awaited<ReturnType<typeof prepareCurrentForegroundStreamDialog>>;
+        startedAt: number;
+        workspaceLease?: Record<string, unknown>;
+    }) => ({
+        agentConfig: executionAgentConfig,
+        agentKey,
+        dialogAgentKey,
+        traceAgentKey,
+        userId: args.streamDialog.effectiveUserId,
+        dialogId: args.streamDialog.dialogId,
+        dialogKey: args.streamDialog.dialogKey,
+        userInputText,
+        startedAt: args.startedAt,
+        isContinue: Boolean(continueDialogId),
+        spaceId: args.streamDialog.effectiveSpaceId,
+        runtimeProfile: effectiveRuntimeProfile,
+        runtimeToolPolicySnapshot,
+        persistDialog: args.streamDialog.persistDialog,
+        ...(args.workspaceLease ? { workspaceLease: args.workspaceLease } : {}),
+    });
 
     if (stream) {
-        try {
-            const connectorResult = await runViaMachineConnector({
-                agentConfig,
-                agentKey,
-                category,
-                continueDialogId: continueDialogId ?? undefined,
-                messages,
-                runtimeContext,
-                spaceId,
-                userId,
-                userInput: userInputText,
-                requestTimeoutMs: effectiveAgentRunTimeoutMs,
-                runtimeToolPolicySnapshot,
-            });
-            if (connectorResult) {
-                const workspaceLease = buildWorkspaceLeaseFromConnectorResult({
-                    result: connectorResult,
-                    agentKey,
-                    machineId: resolveAgentRuntimeMachineId(agentConfig),
-                    runtimeToolPolicySnapshot,
+        const dispatchForegroundStreamExecution = async () => {
+            try {
+                const connectorResult = await runExecutionConnector({
+                    userId,
+                    requestTimeoutMs: effectiveAgentRunTimeoutMs,
                 });
-                const streamDialog = await prepareCurrentForegroundStreamDialog();
-                const startedAt = Date.now();
-                return agentRunSse(buildBillableForegroundSseStream(
-                    buildMachineConnectorSseStream(connectorResult),
-                    {
-                        agentConfig,
-                        agentKey,
-                        dialogAgentKey,
-                        traceAgentKey,
-                        userId: streamDialog.effectiveUserId,
-                        dialogId: streamDialog.dialogId,
-                        dialogKey: streamDialog.dialogKey,
-                        userInputText,
-                        startedAt,
-                        isContinue: Boolean(continueDialogId),
-                        spaceId: streamDialog.effectiveSpaceId,
-                        runtimeProfile: effectiveRuntimeProfile,
-                        runtimeToolPolicySnapshot,
-                        workspaceLease,
-                        persistDialog: streamDialog.persistDialog,
-                    }
-                ));
+                if (connectorResult) {
+                    const workspaceLease = buildExecutionWorkspaceLease(connectorResult);
+                    const streamDialog = await prepareCurrentForegroundStreamDialog();
+                    const startedAt = Date.now();
+                    return agentRunSse(buildBillableForegroundSseStream(
+                        buildMachineConnectorSseStream(connectorResult),
+                        buildForegroundStreamLifecycleContext({
+                            streamDialog,
+                            startedAt,
+                            workspaceLease,
+                        })
+                    ));
+                }
+            } catch (e: any) {
+                const connectorFailureResponse = resolveConnectorFailureResponse(e, executionAgentConfig);
+                if (connectorFailureResponse) return connectorFailureResponse;
+                throw e;
             }
-        } catch (e: any) {
-            const connectorFailureResponse = resolveConnectorFailureResponse(e, agentConfig);
-            if (connectorFailureResponse) return connectorFailureResponse;
-            throw e;
-        }
-        let streamDialog: Awaited<ReturnType<typeof prepareForegroundStreamDialog>>;
-        try {
-            streamDialog = await prepareCurrentForegroundStreamDialog();
-        } catch (e: any) {
-            return agentRunError(e.message ?? "Failed to create dialog", e.status ?? 500);
-        }
-        const startedAt = Date.now();
-        const sourceStream = buildSseStreamImpl(
-            agentConfig,
-            messages,
-            effectiveMaxRounds,
-            serverBase,
-            authToken,
-            runtimePolicy,
-            streamDialog.effectiveUserId,
-            streamDialog.dialogId,
-            streamDialog.effectiveSpaceId,
-            userInputText,
-            runtimeContext,
-        );
-        return agentRunSse(buildBillableForegroundSseStream(sourceStream, {
-            agentConfig,
-            agentKey,
-            dialogAgentKey,
-            traceAgentKey,
-            userId: streamDialog.effectiveUserId,
-            dialogId: streamDialog.dialogId,
-            dialogKey: streamDialog.dialogKey,
-            userInputText,
-            startedAt,
-            isContinue: Boolean(continueDialogId),
-            spaceId: streamDialog.effectiveSpaceId,
-            runtimeProfile: effectiveRuntimeProfile,
-            runtimeToolPolicySnapshot,
-            persistDialog: streamDialog.persistDialog,
-        }));
+            let streamDialog: Awaited<ReturnType<typeof prepareForegroundStreamDialog>>;
+            try {
+                streamDialog = await prepareCurrentForegroundStreamDialog();
+            } catch (e: any) {
+                return agentRunError(e.message ?? "Failed to create dialog", e.status ?? 500);
+            }
+            const startedAt = Date.now();
+            const sourceStream = buildExecutionSourceStream({
+                userId: streamDialog.effectiveUserId,
+                dialogId: streamDialog.dialogId,
+                spaceId: streamDialog.effectiveSpaceId,
+            });
+            return agentRunSse(buildBillableForegroundSseStream(
+                sourceStream,
+                buildForegroundStreamLifecycleContext({
+                    streamDialog,
+                    startedAt,
+                }),
+            ));
+        };
+        return await dispatchForegroundStreamExecution();
     }
 
     // ── background 模式：立即返回 dialogId，后台执行 ───────────────────────────
@@ -1256,19 +1734,7 @@ export async function handleAgentRun(req: Request): Promise<Response> {
             continueDialogUserId,
             fallbackSpaceId: spaceId,
             createPendingDialog,
-            pendingDialogInput: {
-                agentKey,
-                userId,
-                callerType,
-                userInput: userInputText,
-                spaceId,
-                category,
-                inheritedFromDialogKey,
-                parentDialogId,
-                runtimeProfile: effectiveRuntimeProfile,
-                runtimeContext,
-                runtimeToolPolicySnapshot,
-            },
+            pendingDialogInput: buildPendingDialogInput(agentKey),
         });
         if (isBackgroundRunDialogError(backgroundDialog)) {
             return agentRunError(backgroundDialog.error, backgroundDialog.status);
@@ -1279,150 +1745,112 @@ export async function handleAgentRun(req: Request): Promise<Response> {
             effectiveUserId: effectiveBackgroundUserId,
             effectiveSpaceId: effectiveBackgroundSpaceId,
         } = backgroundDialog;
+        const backgroundDialogPersistenceContext = {
+            dialogId,
+            dialogKey,
+            agentKey,
+            parentDialogId,
+            runtimeContext,
+            spaceId: effectiveBackgroundSpaceId,
+        };
         const startedAt = Date.now();
+        const persistBackgroundDialogRecord = async (args: {
+            status: "running" | "failed";
+            updatedAt: number;
+            extraFields?: Record<string, unknown>;
+            buildRuntimeCheckpoint: (existingDialog: any) => unknown;
+            failureLogLabel: string;
+        }) => {
+            try {
+                const store = getAgentRunStore();
+                const existingDialog = await store.get(dialogKey);
+                await store.put(dialogKey, {
+                    ...existingDialog,
+                    status: args.status,
+                    updatedAt: new Date(args.updatedAt).toISOString(),
+                    ...(args.extraFields ?? {}),
+                    runtimeCheckpoint: args.buildRuntimeCheckpoint(existingDialog),
+                });
+                return true;
+            } catch (persistError) {
+                console.error(
+                    `[background] dialog=${dialogId} ${args.failureLogLabel} persist failed:`,
+                    persistError,
+                );
+                return false;
+            }
+        };
+        const publishBackgroundDialogTransition = async (args: {
+            status: "running" | "done" | "failed";
+            projectActivity?: boolean;
+            progress?: MachineConnectorRunProgress;
+            content?: string;
+            usage?: LoopResult["usage"];
+            error?: string;
+        }) => {
+            if (args.projectActivity !== false) {
+                await projectBackgroundDialogActivity({
+                    ...backgroundDialogPersistenceContext,
+                    status: args.status,
+                });
+            }
+            if (args.progress) {
+                pushEvent(`dialog-${dialogId}`, {
+                    type: "runtime.progress",
+                    progress: args.progress,
+                });
+                return;
+            }
+            if (args.status === "running") {
+                pushEvent(`dialog-${dialogId}`, { type: "status", status: "running" });
+                return;
+            }
+            if (args.status === "done") {
+                pushEvent(`dialog-${dialogId}`, {
+                    type: "done",
+                    content: args.content,
+                    usage: args.usage,
+                });
+                if (effectiveBackgroundSpaceId) {
+                    pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.done", dialogId });
+                }
+                return;
+            }
+            pushEvent(`dialog-${dialogId}`, {
+                type: "failed",
+                error: args.error,
+            });
+            if (effectiveBackgroundSpaceId) {
+                pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.failed", dialogId });
+            }
+        };
 
         // 更新 status=running
-        try {
-            const existingDialog = await serverDb.get(dialogKey);
-            const runningAt = Date.now();
-            await serverDb.put(dialogKey, {
-                ...existingDialog,
-                status: "running",
-                startedAt,
-                updatedAt: new Date(runningAt).toISOString(),
-                runtimeCheckpoint: buildRunningRuntimeCheckpoint({
-                    dialogId,
-                    userInputText,
-                    updatedAt: runningAt,
-                    runtimeBinding: existingDialog?.runtimeBinding,
-                }),
-            });
-            await projectBackgroundDialogActivity({
+        const runningAt = Date.now();
+        const persistedRunning = await persistBackgroundDialogRecord({
+            status: "running",
+            updatedAt: runningAt,
+            extraFields: { startedAt },
+            buildRuntimeCheckpoint: (existingDialog: any) => buildRunningRuntimeCheckpoint({
                 dialogId,
-                dialogKey,
-                agentKey,
-                parentDialogId,
-                runtimeContext,
-                status: "running",
-            });
-        } catch (e) {
-            console.error(`[background] dialog=${dialogId} status update failed:`, e);
-        }
-        pushEvent(`dialog-${dialogId}`, { type: "status", status: "running" });
+                userInputText,
+                updatedAt: runningAt,
+                runtimeBinding: existingDialog?.runtimeBinding,
+            }),
+            failureLogLabel: "status update",
+        });
+        await publishBackgroundDialogTransition({
+            status: "running",
+            projectActivity: persistedRunning,
+        });
 
         // 后台执行（不阻塞响应）
         incActiveStream();
-        (async () => {
-            try {
-                const backgroundTimeoutMs =
-                    effectiveAgentRunTimeoutMs ?? DEFAULT_BACKGROUND_RUN_TIMEOUT_MS;
-                let workspaceLease: Record<string, unknown> | undefined;
-                const persistConnectorProgress = async (progress: MachineConnectorRunProgress) => {
-                    const progressAt = Date.now();
-                    try {
-                        const existingDialog = await serverDb.get(dialogKey);
-                        await serverDb.put(dialogKey, {
-                            ...existingDialog,
-                            status: "running",
-                            updatedAt: new Date(progressAt).toISOString(),
-                            runtimeCheckpoint: buildProgressRuntimeCheckpoint({
-                                existingDialog,
-                                dialogId,
-                                userInputText,
-                                progress,
-                                updatedAt: progressAt,
-                            }),
-                        });
-                        await projectBackgroundDialogActivity({
-                            dialogId,
-                            dialogKey,
-                            agentKey,
-                            parentDialogId,
-                            runtimeContext,
-                            status: "running",
-                        });
-                        pushEvent(`dialog-${dialogId}`, {
-                            type: "runtime.progress",
-                            progress,
-                        });
-                    } catch (progressError) {
-                        console.error(`[background] dialog=${dialogId} progress persist failed:`, progressError);
-                    }
-                };
-                const runtimePromptPage = await createRuntimePromptPageIfLarge({
-                    agentConfig,
-                    agentKey,
-                    dialogId,
-                    runtimeContext,
-                    spaceId: effectiveBackgroundSpaceId,
-                    userId: effectiveBackgroundUserId,
-                    userInputText,
-                }).catch((error) => {
-                    console.warn("[agentRun.background] runtime prompt page create failed", {
-                        dialogId,
-                        agentKey,
-                        error: error instanceof Error ? error.message : String(error),
-                    });
-                    return null;
-                });
-                if (runtimePromptPage) {
-                    await persistConnectorProgress({
-                        message: "runtime-prompt-page-created",
-                        promptPageKey: runtimePromptPage.dbKey,
-                        promptPageHash: runtimePromptPage.promptHash,
-                        promptBytes: runtimePromptPage.contentBytes,
-                        updatedAt: Date.now(),
-                    });
-                }
-                const result = await withBackgroundRunTimeout((async () => {
-                    console.log("[agentRun.background] dispatch", {
-                        dialogId,
-                        agentKey,
-                        backgroundTimeoutMs,
-                        userInputBytes: byteLength(userInputText),
-                        runtimePromptPageKey: runtimePromptPage?.dbKey,
-                    });
-                    const connectorResult = await runViaMachineConnector({
-                        agentConfig,
-                        agentKey,
-                        category,
-                        continueDialogId: continueDialogId ?? undefined,
-                        messages,
-                        runtimeContext,
-                        spaceId,
-                        userId: effectiveBackgroundUserId,
-                        userInput: userInputText,
-                        requestTimeoutMs: backgroundTimeoutMs,
-                        runtimeToolPolicySnapshot,
-                        runtimePromptPage,
-                        onProgress: persistConnectorProgress,
-                    });
-                    console.log("[agentRun.background] connector-result", {
-                        dialogId,
-                        agentKey,
-                        usedMachineConnector: Boolean(connectorResult),
-                        contentBytes: byteLength(String(connectorResult?.content ?? "")),
-                    });
-                    workspaceLease = buildWorkspaceLeaseFromConnectorResult({
-                        result: connectorResult,
-                        agentKey,
-                        machineId: resolveAgentRuntimeMachineId(agentConfig),
-                        runtimeToolPolicySnapshot,
-                    });
-                    return (connectorResult ?? await runAgentLoopImpl(
-                        agentConfig,
-                        messages,
-                        effectiveMaxRounds,
-                        serverBase,
-                        authToken,
-                        runtimePolicy,
-                        effectiveBackgroundUserId,
-                        dialogId,
-                        effectiveBackgroundSpaceId,
-                        userInputText,
-                        runtimeContext,
-                    )) as LoopResult;
-                })(), backgroundTimeoutMs);
+        const dispatchBackgroundExecution = async () => {
+            const settleBackgroundExecutionSuccess = async (args: {
+                result: LoopResult;
+                workspaceLease?: Record<string, unknown>;
+            }) => {
                 if (continueDialogId) {
                     await appendToExistingDialog({
                         dialogId,
@@ -1430,20 +1858,20 @@ export async function handleAgentRun(req: Request): Promise<Response> {
                         agentKey,
                         userId: effectiveBackgroundUserId,
                         userInput: userInputText,
-                        result,
+                        result: args.result,
                         durationMs: Date.now() - startedAt,
                         spaceId: effectiveBackgroundSpaceId,
                         runtimeProfile: effectiveRuntimeProfile,
                         runtimeContext,
                         runtimeToolPolicySnapshot,
-                        workspaceLease,
+                        workspaceLease: args.workspaceLease,
                     });
                 } else {
                     await finalizeDialog({
                         dialogId,
                         dialogKey,
                         agentKey,
-                        result,
+                        result: args.result,
                         startedAt,
                         status: "done",
                         userInput: userInputText,
@@ -1451,131 +1879,169 @@ export async function handleAgentRun(req: Request): Promise<Response> {
                         spaceId,
                         runtimeContext,
                         runtimeToolPolicySnapshot,
-                        workspaceLease,
+                        workspaceLease: args.workspaceLease,
                     });
                 }
-                await projectBackgroundDialogActivity({
-                    dialogId,
-                    dialogKey,
-                    agentKey,
-                    parentDialogId,
-                    runtimeContext,
+                await publishBackgroundDialogTransition({
                     status: "done",
+                    content: args.result.content,
+                    usage: args.result.usage,
                 });
-                pushEvent(`dialog-${dialogId}`, {
-                    type: "done",
-                    content: result.content,
-                    usage: result.usage,
-                });
-                if (effectiveBackgroundSpaceId) {
-                    pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.done", dialogId });
-                }
                 await writeAgentRunBillingIfNeeded({
-                    agentConfig,
+                    agentConfig: executionAgentConfig,
                     agentKey,
-                    result,
+                    result: args.result,
                     dialogId,
                     mode: "background",
                     userId: effectiveBackgroundUserId,
                 });
-            } catch (e) {
-                console.error(`[background] dialog=${dialogId} failed:`, e);
+            };
+            const settleBackgroundExecutionFailure = async (args: {
+                error: unknown;
+            }) => {
                 const failedAt = Date.now();
-                const errorMessage = e instanceof Error ? e.message : String(e);
-                await serverDb.get(dialogKey).then((d: any) =>
-                    serverDb.put(dialogKey, {
-                        ...d,
-                        status: "failed",
-                        updatedAt: new Date(failedAt).toISOString(),
+                const errorMessage =
+                    args.error instanceof Error ? args.error.message : String(args.error);
+                await persistBackgroundDialogRecord({
+                    status: "failed",
+                    updatedAt: failedAt,
+                    extraFields: {
                         finishedAt: failedAt,
                         durationMs: Math.max(0, failedAt - startedAt),
-                        runtimeCheckpoint: {
-                            ...buildFailedRuntimeCheckpoint({
-                                existingDialog: d,
-                                dialogId,
-                                userInputText,
-                                updatedAt: failedAt,
-                                errorMessage,
-                            }),
-                            errorMessage,
-                        },
                         errorMessage,
-                    })
-                ).catch((putErr) => { console.error(`[background] dialog=${dialogId} status persist failed:`, putErr); });
-                await projectBackgroundDialogActivity({
-                    dialogId,
-                    dialogKey,
-                    agentKey,
-                    parentDialogId,
-                    runtimeContext,
-                    status: "failed",
+                    },
+                    buildRuntimeCheckpoint: (existingDialog: any) => buildFailedRuntimeCheckpoint({
+                        existingDialog,
+                        dialogId,
+                        userInputText,
+                        updatedAt: failedAt,
+                        errorMessage,
+                    }),
+                    failureLogLabel: "status",
                 });
-                pushEvent(`dialog-${dialogId}`, {
-                    type: "failed",
+                await publishBackgroundDialogTransition({
+                    status: "failed",
                     error: errorMessage,
                 });
-                if (effectiveBackgroundSpaceId) {
-                    pushEvent(`space-${effectiveBackgroundSpaceId}`, { type: "dialog.failed", dialogId });
-                }
                 const dialogTitle =
                     existingDialogRecord?.title ??
                     buildDialogFallbackTitleFromUserInput(userInputText);
                 await emitDialogStatusNotification({
                     userId: effectiveBackgroundUserId,
-                    dialogId,
-                    dialogKey,
+                    ...backgroundDialogPersistenceContext,
                     dialogTitle,
-                    spaceId: effectiveBackgroundSpaceId,
                     status: "failed",
                     createdAt: failedAt,
                     errorMessage,
                 });
+            };
+            try {
+                const backgroundTimeoutMs =
+                    effectiveAgentRunTimeoutMs ?? DEFAULT_BACKGROUND_RUN_TIMEOUT_MS;
+                let workspaceLease: Record<string, unknown> | undefined;
+                const prepareBackgroundProgressPhase = async () => {
+                    const persistConnectorProgress = async (progress: MachineConnectorRunProgress) => {
+                        const progressAt = Date.now();
+                        const persistedProgress = await persistBackgroundDialogRecord({
+                            status: "running",
+                            updatedAt: progressAt,
+                            buildRuntimeCheckpoint: (existingDialog: any) => buildProgressRuntimeCheckpoint({
+                                existingDialog,
+                                dialogId,
+                                userInputText,
+                                progress,
+                                updatedAt: progressAt,
+                            }),
+                            failureLogLabel: "progress",
+                        });
+                        if (persistedProgress) {
+                            await publishBackgroundDialogTransition({
+                                status: "running",
+                                progress,
+                            });
+                        }
+                    };
+                    const maybeRuntimePromptPage = await createRuntimePromptPageIfLarge({
+                        agentConfig: executionAgentConfig,
+                        agentKey,
+                        dialogId,
+                        runtimeContext,
+                        spaceId: effectiveBackgroundSpaceId,
+                        userId: effectiveBackgroundUserId,
+                        userInputText,
+                    }).catch((error) => {
+                        console.warn("[agentRun.background] runtime prompt page create failed", {
+                            dialogId,
+                            agentKey,
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        return null;
+                    });
+                    if (maybeRuntimePromptPage) {
+                        await persistConnectorProgress({
+                            message: "runtime-prompt-page-created",
+                            promptPageKey: maybeRuntimePromptPage.dbKey,
+                            promptPageHash: maybeRuntimePromptPage.promptHash,
+                            promptBytes: maybeRuntimePromptPage.contentBytes,
+                            updatedAt: Date.now(),
+                        });
+                    }
+                    return {
+                        persistConnectorProgress,
+                        runtimePromptPage: maybeRuntimePromptPage,
+                    };
+                };
+                const { persistConnectorProgress, runtimePromptPage } = await prepareBackgroundProgressPhase();
+                const { result, workspaceLease: resolvedWorkspaceLease } = await withBackgroundRunTimeout((async () => {
+                    console.log("[agentRun.background] dispatch", {
+                        dialogId,
+                        agentKey,
+                        backgroundTimeoutMs,
+                        userInputBytes: byteLength(userInputText),
+                        runtimePromptPageKey: runtimePromptPage?.dbKey,
+                    });
+                    const executionRun = await runExecutionResult({
+                        userId: effectiveBackgroundUserId,
+                        dialogId,
+                        spaceId: effectiveBackgroundSpaceId,
+                        requestTimeoutMs: backgroundTimeoutMs,
+                        runtimePromptPage,
+                        onProgress: persistConnectorProgress,
+                    });
+                    console.log("[agentRun.background] connector-result", {
+                        dialogId,
+                        agentKey,
+                        usedMachineConnector: Boolean(executionRun.connectorResult),
+                        contentBytes: byteLength(String(executionRun.connectorResult?.content ?? "")),
+                    });
+                    return executionRun;
+                })(), backgroundTimeoutMs);
+                workspaceLease = resolvedWorkspaceLease;
+                await settleBackgroundExecutionSuccess({ result, workspaceLease });
+            } catch (e) {
+                console.error(`[background] dialog=${dialogId} failed:`, e);
+                await settleBackgroundExecutionFailure({ error: e });
             } finally {
                 decActiveStream();
             }
-        })().catch((e) => { console.error(`[background] unhandled rejection dialog=${dialogId}:`, e); });
+        };
+        dispatchBackgroundExecution().catch((e) => { console.error(`[background] unhandled rejection dialog=${dialogId}:`, e); });
 
         return agentRunJson({ dialogId, status: "pending" }, 202);
     }
 
     // ── 前台同步模式 ───────────────────────────────────────────────────────────
-    try {
+    const dispatchSyncExecution = async () => {
         const startTime = Date.now();
         // 注意：sync 新建 dialog 的首轮执行在 saveRunAsDialog 之前，runAgentLoop 此时还拿不到最终 dialogId。
         // 这意味着首轮 server-side external tool charge 还无法稳定投影进 dialog.totalCost；
         // continue/background 场景已有 dialogId，可正常回写。后续若要补齐这里，需要先拿稳定 dialogId 再执行工具链。
-        const connectorResult = await runViaMachineConnector({
-            agentConfig,
-            agentKey,
-            category,
-            continueDialogId: continueDialogId ?? undefined,
-            messages,
-            runtimeContext,
-            spaceId,
+        const { result, workspaceLease } = await runExecutionResult({
             userId,
-            userInput: userInputText,
             requestTimeoutMs: effectiveAgentRunTimeoutMs,
-            runtimeToolPolicySnapshot,
-        });
-        const workspaceLease = buildWorkspaceLeaseFromConnectorResult({
-            result: connectorResult,
-            agentKey,
-            machineId: resolveAgentRuntimeMachineId(agentConfig),
-            runtimeToolPolicySnapshot,
-        });
-        const result = (connectorResult ?? await runAgentLoopImpl(
-            agentConfig,
-            messages,
-            effectiveMaxRounds,
-            serverBase,
-            authToken,
-            runtimePolicy,
-            userId,
-            continueDialogId ?? undefined,
+            dialogId: continueDialogId ?? undefined,
             spaceId,
-            userInputText,
-            runtimeContext,
-        )) as LoopResult;
+        });
         const durationMs = Date.now() - startTime;
 
         const { dialogId, dialogKey } = await completeSyncAgentRunDialog({
@@ -1583,26 +2049,17 @@ export async function handleAgentRun(req: Request): Promise<Response> {
             existingDialogKey,
             dialogAgentKey,
             traceAgentKey,
-            userId,
             continueDialogUserId,
-            callerType,
-            userInput: userInputText,
             result,
             durationMs,
-            spaceId,
-            category,
-            inheritedFromDialogKey,
-            parentDialogId,
-            runtimeProfile: effectiveRuntimeProfile,
-            runtimeContext,
-            runtimeToolPolicySnapshot,
             workspaceLease,
             appendToExistingDialog,
             saveRunAsDialog,
             summarizeMessagesForDebug,
+            ...dialogLifecyclePersistenceContext,
         });
         await writeAgentRunBillingIfNeeded({
-            agentConfig,
+            agentConfig: executionAgentConfig,
             agentKey,
             result,
             dialogId,
@@ -1613,7 +2070,7 @@ export async function handleAgentRun(req: Request): Promise<Response> {
         const debugContext = buildAgentRunDebugContext({
             enabled: debugContextLayers,
             runtimeSystemMessageContext,
-            selectedMemoryItems: memoryRuntime.selectedItems,
+            selectedMemoryItems: executionMemoryRuntime.selectedItems,
         });
 
         return agentRunJson({
@@ -1622,8 +2079,11 @@ export async function handleAgentRun(req: Request): Promise<Response> {
             dialogKey,
             ...(debugContext ? { debug: debugContext } : {}),
         });
+    };
+    try {
+        return await dispatchSyncExecution();
     } catch (e: any) {
-        const connectorFailureResponse = resolveConnectorFailureResponse(e, agentConfig);
+        const connectorFailureResponse = resolveConnectorFailureResponse(e, executionAgentConfig);
         if (connectorFailureResponse) return connectorFailureResponse;
         return agentRunError(e.message ?? "Internal server error", 500);
     }