@superblocksteam/vite-plugin-file-sync 1.99.99-next.2 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/llm/client.js

@@ -0,0 +1,992 @@
+import { asSchema, safeParseJSON, safeValidateTypes, } from "@ai-sdk/provider-utils";
+import { safeJsonStringify } from "../../util/log-sanitizer.js";
+import { getLogger, getPrefixedLogger, getErrorMeta, } from "../../util/logger.js";
+import { LLMObsTracer } from "../llmobs/tracer.js";
+import { scanContentForSecrets, SecretRedactor, classifyPromptSafety, createBlockedUserMessage, FAIL_CLOSED_RESULT, } from "../security/index.js";
+import { catchBackgroundPeerDisconnect } from "../state-machine/helpers/stable-peer.js";
+import { isExtendedThinkingModel, upstreamStallTimeoutMsFor, } from "../util/llm-config-utils.js";
+import { SERVER_COMPACTION_INTERRUPTED_SUMMARY } from "./context-v2/compaction/server-side.js";
+import { ContextV2Adapter } from "./context-v2/index.js";
+import { estimateValueTokens } from "./context-v2/token-tracker.js";
+import { createVercelProvider } from "./interaction/adapters/vercel.js";
+import { StreamOrchestrator, StreamConfig, DEFAULT_COMPACTION_SUMMARY_TIMEOUT_MS, DEFAULT_FIRST_TOKEN_TIMEOUT_MS, LoggingObserver, LLMObsObserver, ContextObserver, RetryNotificationObserver, wrapToolsForObservability, } from "./stream/index.js";
+import { StepTokenUsageObserver, } from "./stream/observers/step-token-usage.js";
+import { createWorkflowUsageObserver, } from "./stream/observers/workflow-usage.js";
+import { logToolContextIntegrityIssues } from "./tool-context-integrity.js";
+/** Context setups slower than this get a warning log (pre-network hang risk). */
+const SLOW_CONTEXT_SETUP_WARN_MS = 5_000;
+/**
+ * Size the tool definitions the provider will be charged for on this request.
+ *
+ * The oversize gate lives in `ContextV2`, which only sees the message array,
+ * but the provider bills the tool schemas too and they are frequently the
+ * largest part of a request that the message array cannot see. Sized here
+ * because this is the layer that holds the tools, and handed over as a plain
+ * token count so `context-v2` gains no dependency on the agent tool types.
+ *
+ * `asSchema().jsonSchema` rather than the raw tool objects: `inputSchema` is a
+ * Zod schema, and serializing that measures Zod's internals instead of the JSON
+ * Schema actually sent.
+ *
+ * Never throws, and failures are isolated PER TOOL. One unconvertible schema
+ * must not zero the whole count: tools measured 24,284 of a 39,615-token
+ * estimate on a real Clark turn, so swallowing all of them silently reopens
+ * most of the gap this sizing exists to close. A tool that cannot be sized
+ * contributes 0 and is named in the log so on-call does not bisect the
+ * registry by hand.
+ */
+function estimateToolSchemaTokens(tools) {
+    if (!tools)
+        return 0;
+    let tokens = 0;
+    for (const [name, definition] of Object.entries(tools)) {
+        try {
+            tokens += estimateValueTokens({
+                name,
+                description: definition.description,
+                inputSchema: asSchema(definition.inputSchema).jsonSchema,
+            });
+        }
+        catch (err) {
+            getLogger().warn(`[llm-client] could not size the schema for tool '${name}'; ` +
+                `excluding it from the oversize check`, getErrorMeta(err));
+        }
+    }
+    return tokens;
+}
+/**
+ * Merge `protectedTools` into the `excludeTools` field of the request's
+ * `clear_tool_uses_20250919` edit (if present), returning a new
+ * `providerOptions` object. Returns the input unchanged when there is no
+ * Anthropic context-management config, no `clear_tool_uses` edit, or no
+ * protected tools to add.
+ *
+ * Exposed for testing — the live call site is `LLMClient.streamText`.
+ */
+export function mergeProtectedToolsIntoExcludeTools(providerOptions, protectedTools) {
+    if (protectedTools.length === 0 ||
+        !providerOptions ||
+        !providerOptions.anthropic) {
+        return { providerOptions, changed: false, mergedCount: 0 };
+    }
+    const anthropicOpts = providerOptions.anthropic;
+    const edits = anthropicOpts.contextManagement?.edits;
+    const clearEditIndex = edits?.findIndex((e) => e.type === "clear_tool_uses_20250919") ?? -1;
+    if (!edits || clearEditIndex < 0) {
+        return { providerOptions, changed: false, mergedCount: 0 };
+    }
+    const clearEdit = edits[clearEditIndex];
+    const merged = Array.from(new Set([...(clearEdit.excludeTools ?? []), ...protectedTools]));
+    const newEdits = edits.slice();
+    newEdits[clearEditIndex] = { ...clearEdit, excludeTools: merged };
+    const next = {
+        ...providerOptions,
+        anthropic: {
+            ...anthropicOpts,
+            contextManagement: {
+                ...anthropicOpts.contextManagement,
+                edits: newEdits,
+            },
+        },
+    };
+    return { providerOptions: next, changed: true, mergedCount: merged.length };
+}
+/**
+ * Extracts text content from a user message.
+ *
+ * @param user - The user message to extract text from
+ * @param scope - Which text parts to extract: "all" (default) or "last" (user prompt only)
+ * @returns Extracted text content
+ */
+export function extractTextFromMessage(message, scope = "all") {
+    if (typeof message.content === "string") {
+        return message.content;
+    }
+    const textParts = message.content.filter((part) => part.type === "text");
+    if (scope === "last") {
+        const lastPart = textParts[textParts.length - 1];
+        if (lastPart) {
+            return lastPart.text;
+        }
+    }
+    return textParts.map((part) => part.text).join("\n");
+}
+/**
+ * Creates a new user message with text content redacted.
+ */
+function redactUserMessage(user, redactor) {
+    if (!redactor.hasFindings()) {
+        return user;
+    }
+    if (typeof user.content === "string") {
+        return {
+            ...user,
+            content: redactor.redact(user.content),
+        };
+    }
+    // Content is an array - redact text parts
+    return {
+        ...user,
+        content: user.content.map((part) => {
+            if (part.type === "text") {
+                return { ...part, text: redactor.redact(part.text) };
+            }
+            return part;
+        }),
+    };
+}
+export class LLMClient {
+    contextManagerV2;
+    appShell;
+    baseProvider;
+    retryOptions;
+    unifiedProviderEnabled;
+    organizationId;
+    applicationId;
+    getJwt;
+    onUsageRecorded;
+    stepTokenUsageLabels;
+    logger = getPrefixedLogger("[llm-client]");
+    constructor(params) {
+        this.contextManagerV2 = params.contextManagerV2;
+        this.appShell = params.appShell;
+        this.baseProvider = params.baseProvider ?? createVercelProvider();
+        this.retryOptions = params.retryOptions;
+        this.unifiedProviderEnabled = params.unifiedProviderEnabled ?? false;
+        this.organizationId = params.organizationId;
+        this.applicationId = params.applicationId;
+        this.getJwt = params.getJwt;
+        this.onUsageRecorded = params.onUsageRecorded;
+        this.stepTokenUsageLabels = params.stepTokenUsageLabels;
+    }
+    /**
+     * Applies safety classification to a user message.
+     *
+     * @param user - The user message to classify
+     * @param userText - The extracted text to classify
+     * @param config - Safety classification configuration
+     * @returns Object containing the processed message and classification result
+     */
+    async applySafetyClassification(user, userText, config, fallbackProviderConfig) {
+        const failOpen = config.failOpen ?? true;
+        if (!config.model) {
+            this.logger.warn("[safety-classifier] No model configured, skipping classification");
+            return {
+                message: user,
+                classification: {
+                    safe: true,
+                    justification: "No model configured, skipped classification",
+                },
+            };
+        }
+        try {
+            this.logger.info("[safety-classifier] Running safety classification");
+            const classification = await classifyPromptSafety(userText, {
+                model: config.model,
+                providerConfig: config.providerConfig ?? fallbackProviderConfig,
+                // Route through this same client so the classification call inherits
+                // retry/observability. The classifier disables its own safety pass to
+                // avoid recursion (see classifyPromptSafety).
+                llmClient: this,
+                timeout: config.timeout ?? 5000,
+            });
+            if (!classification.safe) {
+                this.logger.warn("[safety-classifier] Prompt classified as unsafe", {
+                    justification: classification.justification,
+                    categories: classification.categories,
+                });
+                return {
+                    message: createBlockedUserMessage(user, classification),
+                    classification: {
+                        safe: false,
+                        justification: classification.justification,
+                        categories: classification.categories,
+                    },
+                };
+            }
+            this.logger.info("[safety-classifier] Prompt classified as safe");
+            return {
+                message: user,
+                classification: {
+                    safe: true,
+                    justification: classification.justification,
+                },
+            };
+        }
+        catch (error) {
+            this.logger.error("[safety-classifier] Classification failed", getErrorMeta(error));
+            if (failOpen) {
+                this.logger.info("[safety-classifier] Failing open, allowing request to proceed");
+                return {
+                    message: user,
+                    classification: {
+                        safe: true,
+                        justification: "Classification error, failed open",
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+            else {
+                this.logger.warn("[safety-classifier] Failing closed, blocking request");
+                return {
+                    message: createBlockedUserMessage(user, FAIL_CLOSED_RESULT),
+                    classification: {
+                        safe: false,
+                        justification: FAIL_CLOSED_RESULT.justification,
+                        categories: FAIL_CLOSED_RESULT.categories,
+                        error: error instanceof Error ? error.message : String(error),
+                    },
+                };
+            }
+        }
+    }
+    async streamText(options, logger = getLogger(), tracer = LLMObsTracer.instance) {
+        const { model, user, system, context: contextConfig, logging: loggingConfig, recordObsContent, retry: retryConfig, providerConfig, thinking: thinkingConfig, enableFallback, fallbackStrategy, peer, chatSessionStore, observers: customObservers, degradationKey, prepareStep, onStepFinish, onFinish, onChunk, onError, onContextReady, safety: safetyConfig, ...streamOptions } = options;
+        if (!user) {
+            throw new Error("user message is required");
+        }
+        let safeUser = user;
+        let safetySpan;
+        // Apply safety features if configured and at least one is enabled
+        const secretRedactionLevel = safetyConfig?.secretRedaction?.level ?? "full";
+        const hasSecretRedaction = secretRedactionLevel !== "off";
+        const hasClassification = safetyConfig?.classification?.enabled === true;
+        if (safetyConfig && (hasSecretRedaction || hasClassification)) {
+            safetySpan = tracer.startActiveSpan({
+                name: "llmclient.safety",
+                kind: "task",
+            });
+            const scope = safetyConfig.scope ?? "all";
+            const userText = extractTextFromMessage(user, scope);
+            let classificationInput = safetyConfig.classification?.input ?? userText;
+            // Secret redaction (if enabled)
+            if (hasSecretRedaction) {
+                await tracer.trace({
+                    name: "llmclient.safety.secretRedaction",
+                    kind: "task",
+                }, async () => {
+                    try {
+                        const scanResult = await scanContentForSecrets(userText, {
+                            consumer: "prompt",
+                        });
+                        // Check if scan completed successfully
+                        if (!scanResult.success) {
+                            // The scanner service owns failure reporting. Preserve fail-open behavior.
+                            return;
+                        }
+                        const secretRedactor = new SecretRedactor(scanResult.findings);
+                        if (scanResult.hasSecrets) {
+                            this.logger.warn(`[secret-scan] Found ${scanResult.findings.length} potential secret(s)`, {
+                                findingCount: scanResult.findings.length,
+                                hasVerified: scanResult.hasVerifiedSecrets,
+                                detectorTypes: scanResult.findings.map((f) => f.detectorType),
+                            });
+                        }
+                        safeUser = redactUserMessage(safeUser, secretRedactor);
+                        classificationInput = secretRedactor.redact(classificationInput);
+                    }
+                    catch (error) {
+                        this.logger.error("[secret-scan] Secret scanning threw an exception, proceeding without redaction", getErrorMeta(error));
+                        // Fail-open: Continue with unredacted message rather than blocking
+                    }
+                });
+            }
+            // Safety classification (if enabled)
+            if (hasClassification && safetyConfig.classification) {
+                const config = safetyConfig.classification;
+                if (!config.model) {
+                    this.logger.warn("[safety-classifier] No model configured, skipping classification");
+                }
+                else {
+                    await tracer.trace({
+                        name: "llmclient.safety.classification",
+                        kind: "task",
+                    }, async () => {
+                        const result = await this.applySafetyClassification(safeUser, classificationInput, config, providerConfig);
+                        safeUser = result.message;
+                        // Annotate classification span with results
+                        tracer.annotate({
+                            tags: {
+                                "safety.classification.safe": result.classification.safe,
+                                "safety.classification.blocked": !result.classification.safe,
+                            },
+                            metadata: {
+                                classification: {
+                                    safe: result.classification.safe,
+                                    justification: result.classification.justification,
+                                    ...(result.classification.categories && {
+                                        categories: result.classification.categories,
+                                    }),
+                                    ...(result.classification.error && {
+                                        error: result.classification.error,
+                                    }),
+                                },
+                            },
+                        });
+                    });
+                }
+            }
+            safetySpan?.finish();
+        }
+        if (!providerConfig?.provider || !providerConfig?.model) {
+            throw new Error("providerConfig with provider and model is required. " +
+                "This should be populated from llmConfig sent by the UI.");
+        }
+        const usesManagedContext = contextConfig?.mode !== "stateless";
+        const managedContextConfig = usesManagedContext ? contextConfig : undefined;
+        const contextId = managedContextConfig?.contextId;
+        // Stateless calls are internal one-shots with no conversation to log to, so
+        // they must not write `.superblocks/generations` transcript artifacts.
+        // Default logging OFF for stateless unless a caller explicitly passes a
+        // logging config (explicit opt-in still wins). This makes `stateless` the
+        // canonical "internal, no-artifact" signal and removes the per-call-site
+        // `logging: false` footgun for future internal callers.
+        const effectiveLoggingConfig = loggingConfig === undefined && !usesManagedContext
+            ? false
+            : loggingConfig;
+        const contextManagement = managedContextConfig?.contextManagement?.type === "client"
+            ? {
+                ...managedContextConfig.contextManagement,
+                summarizeLLM: this.summarizeViaClient,
+            }
+            : managedContextConfig?.contextManagement;
+        const contextSetupStartedAt = performance.now();
+        const managedContext = usesManagedContext
+            ? await this.createContext(contextId, managedContextConfig?.contextOptionsV2, tracer, contextManagement, peer)
+            : undefined;
+        const contextHandle = managedContext?.contextHandle;
+        const ctx = managedContext?.ctx;
+        if (ctx) {
+            if (managedContextConfig?.messages?.length) {
+                await ctx.initializeWith(managedContextConfig.messages);
+            }
+            if (system) {
+                ctx.setSystemPrompt({ role: "system", content: system });
+            }
+            // Warn when an ephemeral context (no persistent contextId) ends up without
+            // a system prompt. This was the root cause of APPS-3387: exitPlanMode
+            // created an ephemeral context whose initializeWith silently dropped the
+            // system message, causing the LLM to reason but produce no text output.
+            if (!contextId && !system) {
+                const hasSystemInMessages = managedContextConfig?.messages?.some((m) => m.role === "system");
+                if (!hasSystemInMessages) {
+                    logger.warn("[llm-client] Ephemeral context created without a system prompt. " +
+                        "This may cause the LLM to produce empty text output.");
+                }
+            }
+            await ctx.startTurn(safeUser);
+            // A restored history can already exceed the model's input limit, in which
+            // case the provider rejects the request before reporting any usage. Since
+            // `afterResponse` is the only compaction trigger and it needs
+            // provider-reported usage, compaction can never fire again and the app is
+            // wedged permanently (ENG-5282).
+            //
+            // Here, rather than at restore: the system prompt is set and this turn is
+            // appended, so the check sizes the payload that is actually going out; the
+            // peer's compaction callbacks are already attached, so the user sees the
+            // summarization instead of a silent two-minute wait; and the turn is
+            // already in flight, so blocking costs nothing extra. No-op for payloads
+            // that fit.
+            //
+            // Tool schemas are sized here and passed in because the provider charges
+            // for them on every request and they never appear in the message array.
+            // Against the five captured production sessions the messages-only
+            // estimate reads 0.19x to 1.23x of provider-reported usage, and under-
+            // reading is the direction that matters for a gate: a payload genuinely
+            // over the limit estimates as fitting and no pass fires. Passed as a
+            // thunk so the sizing (schema conversion and serialization of every tool)
+            // only runs when the context is actually going to look at it; with the
+            // kill switch off this call is a no-op.
+            await ctx.compactIfOversized(() => estimateToolSchemaTokens(streamOptions.tools));
+            onContextReady?.(ctx);
+        }
+        const messagesForModel = ctx
+            ? await ctx.getMessages()
+            : [safeUser];
+        if (usesManagedContext) {
+            logToolContextIntegrityIssues(this.logger, "ctx.initial", messagesForModel);
+        }
+        // Context setup (create + history replay + start turn) runs before any
+        // network call; if it is slow the user sees a silent "generating" hang
+        // with nothing in APM (APPS-4690). Log timing so stalls here are visible.
+        const contextSetupMs = Math.round(performance.now() - contextSetupStartedAt);
+        if (contextSetupMs > SLOW_CONTEXT_SETUP_WARN_MS) {
+            // contextId identifies which context was loading (correlate with the
+            // manager's "Loading context ... from storage" breadcrumb); persistent
+            // restores show replayedMessages=0 because their history comes from
+            // storage, not from contextConfig.messages.
+            logger.warn(`[llm-client] slow context setup: ${contextSetupMs}ms ` +
+                `(contextId=${contextId?.name ?? "ephemeral"} replayedMessages=${managedContextConfig?.messages?.length ?? 0})`);
+        }
+        try {
+            const fallbackEnabled = this.unifiedProviderEnabled && (enableFallback ?? false);
+            logger.info(`[llm-client] provider=${providerConfig.provider} model=${providerConfig.model} ` +
+                `unifiedProvider=${this.unifiedProviderEnabled} fallback=${fallbackEnabled}` +
+                ` retry=${safeJsonStringify(retryConfig)}` +
+                ` contextSetupMs=${contextSetupMs}`);
+            // Resolve the idle / first-token / max-time budgets for a GIVEN model.
+            // Fallback can downgrade the model mid-stream (e.g. opus -> sonnet), and
+            // each model needs to be monitored against its OWN budget rather than the
+            // initial model's frozen one — otherwise a fast model inherits opus's 180s
+            // idle budget (masks real stalls) or opus inherits sonnet's 90s budget
+            // (kills legitimate long reasoning). The orchestrator's IdleMonitor and
+            // the RetryEngine max-time guard call this with the CURRENT attempt's
+            // model. See APPS-4775.
+            const budgetForModel = (model) => {
+                // Opus models can take long enough between chunks during high-effort
+                // reasoning to trip the default idle watchdog. Give these sessions
+                // longer idle/total timeouts; the first-token watchdog below still
+                // catches streams that produce no text or reasoning delta.
+                const extendedThinking = isExtendedThinkingModel(model);
+                // Caps total token-silent wall-clock. These streams were effectively
+                // unbounded before (keep-alives reset the clock), so a real token-based
+                // cap here is strictly tighter than prior behavior. Kept above the proxy's
+                // UPSTREAM_STALL_TIMEOUT_MS (extended 900s / standard 450s) so a single
+                // proxy stall still leaves room for a same-provider retry. Reaching a
+                // FALLBACK provider does not depend on this margin: RetryEngine advances an
+                // available fallback before applying this max-time guard (APPS-4641).
+                const defaultMaxTotalTimeMs = extendedThinking
+                    ? 30 * 60 * 1000
+                    : 15 * 60 * 1000;
+                const defaultIdleTimeoutMs = extendedThinking ? 180_000 : 90_000;
+                const flaggedBudgets = retryConfig?.streamTimeoutBudgets ??
+                    this.retryOptions?.streamTimeoutBudgets;
+                const flaggedIdleTimeoutMs = extendedThinking
+                    ? flaggedBudgets?.extendedIdleMs
+                    : flaggedBudgets?.standardIdleMs;
+                const flaggedContentSilenceTimeoutMs = extendedThinking
+                    ? flaggedBudgets?.extendedContentSilenceMs
+                    : flaggedBudgets?.standardContentSilenceMs;
+                const idleTimeoutMs = retryConfig?.idleTimeoutMs ??
+                    this.retryOptions?.idleTimeoutMs ??
+                    flaggedIdleTimeoutMs ??
+                    defaultIdleTimeoutMs;
+                const defaultFirstTokenTimeoutMs = Math.min(idleTimeoutMs, DEFAULT_FIRST_TOKEN_TIMEOUT_MS);
+                const firstTokenTimeoutMs = retryConfig?.firstTokenTimeoutMs ??
+                    this.retryOptions?.firstTokenTimeoutMs ??
+                    flaggedBudgets?.firstTokenMs ??
+                    defaultFirstTokenTimeoutMs;
+                const contentSilenceTimeoutMs = retryConfig?.contentSilenceTimeoutMs ??
+                    this.retryOptions?.contentSilenceTimeoutMs ??
+                    flaggedContentSilenceTimeoutMs ??
+                    idleTimeoutMs;
+                const compactionSummaryTimeoutMs = retryConfig?.compactionSummaryTimeoutMs ??
+                    this.retryOptions?.compactionSummaryTimeoutMs ??
+                    DEFAULT_COMPACTION_SUMMARY_TIMEOUT_MS;
+                const timeoutSource = retryConfig?.timeoutSource ??
+                    this.retryOptions?.timeoutSource ??
+                    (flaggedBudgets ? "feature-flag" : "default");
+                // Hard floor at the proxy's upstream stall bound so the budget can never
+                // expire before the proxy emits its retryable stall frame — even under a
+                // caller override below that bound (without the floor the client would tear
+                // the request down as a plain timeout and never see the retryable error).
+                // Shares `@superblocksteam/clark`'s `upstreamStallTimeoutMsFor` with the
+                // proxy so the two layers cannot drift.
+                const proxyStallTimeoutMs = upstreamStallTimeoutMsFor(model);
+                const maxTotalTimeMs = Math.max(retryConfig?.maxTotalTimeMs ??
+                    this.retryOptions?.maxTotalTimeMs ??
+                    defaultMaxTotalTimeMs, proxyStallTimeoutMs);
+                return {
+                    idleTimeoutMs,
+                    firstTokenTimeoutMs,
+                    contentSilenceTimeoutMs,
+                    compactionSummaryTimeoutMs,
+                    maxTotalTimeMs,
+                    timeoutSource,
+                };
+            };
+            // Flat fields reflect the INITIAL model so observers/logs/tests reading
+            // them are unchanged; budgetForModel re-resolves per attempt.
+            const initialBudget = budgetForModel(providerConfig.model);
+            // Surface the resolved per-model budget so on-call can verify from session
+            // logs what idle/first-token/max-total limits a session was armed with
+            // (e.g. confirm an opus session got opus's longer budgets).
+            logger.debug("[llm-client] Resolved per-model stream budget", {
+                model: providerConfig.model,
+                idleTimeoutMs: initialBudget.idleTimeoutMs,
+                firstTokenTimeoutMs: initialBudget.firstTokenTimeoutMs,
+                contentSilenceTimeoutMs: initialBudget.contentSilenceTimeoutMs,
+                compactionSummaryTimeoutMs: initialBudget.compactionSummaryTimeoutMs,
+                maxTotalTimeMs: initialBudget.maxTotalTimeMs,
+                timeoutSource: initialBudget.timeoutSource,
+            });
+            const config = StreamConfig.create({
+                retry: {
+                    ...this.retryOptions,
+                    ...retryConfig,
+                    maxTotalTimeMs: initialBudget.maxTotalTimeMs,
+                    idleTimeoutMs: initialBudget.idleTimeoutMs,
+                    firstTokenTimeoutMs: initialBudget.firstTokenTimeoutMs,
+                    contentSilenceTimeoutMs: initialBudget.contentSilenceTimeoutMs,
+                    compactionSummaryTimeoutMs: initialBudget.compactionSummaryTimeoutMs,
+                    timeoutSource: initialBudget.timeoutSource,
+                    budgetForModel,
+                },
+                provider: providerConfig.provider,
+                model: providerConfig.model,
+                fallback: {
+                    enabled: fallbackEnabled,
+                    strategy: fallbackStrategy,
+                },
+                thinking: thinkingConfig,
+                logging: effectiveLoggingConfig !== false
+                    ? {
+                        enabled: true,
+                        conversationId: effectiveLoggingConfig?.conversationId,
+                        saveArtifact: this.appShell.saveGeneratedArtifact.bind(this.appShell),
+                        metadata: effectiveLoggingConfig?.metadata,
+                    }
+                    : { enabled: false },
+            });
+            const observers = [];
+            if (effectiveLoggingConfig !== false) {
+                // Determine if this is a cloud-prem deployment
+                const isCloudPrem = process.env.SUPERBLOCKS_DEPLOYMENT_TYPE === "cloud-prem";
+                observers.push(new LoggingObserver({
+                    logRef: effectiveLoggingConfig?.logRef,
+                    policy: {
+                        // Full mode re-enables logging observer secret scanning.
+                        // Initial-prompt/off skip observer scanning for lower latency.
+                        secretRedactionEnabled: safetyConfig != null && secretRedactionLevel === "full",
+                        // Disable artifact saving for cloud-prem by default
+                        artifactSavingEnabled: !isCloudPrem,
+                    },
+                }));
+            }
+            observers.push(new LLMObsObserver({ tracer, logger, recordContent: recordObsContent }));
+            if (contextHandle) {
+                observers.push(new ContextObserver({
+                    contextHandle,
+                }));
+            }
+            observers.push(new RetryNotificationObserver({ peer, chatSessionStore }));
+            // Workflow metrics tracking
+            if (this.onUsageRecorded) {
+                observers.push(createWorkflowUsageObserver(this.onUsageRecorded));
+            }
+            if (this.stepTokenUsageLabels) {
+                observers.push(new StepTokenUsageObserver(this.stepTokenUsageLabels));
+            }
+            if (customObservers) {
+                observers.push(...customObservers);
+            }
+            const orchestrator = new StreamOrchestrator({
+                provider: this.baseProvider,
+                config,
+                observers,
+                logger: this.logger,
+                organizationId: this.organizationId,
+                applicationId: this.applicationId,
+                getJwt: this.getJwt,
+                degradationKey,
+            });
+            const { tools, ...restStreamOptions } = streamOptions;
+            const tracedTools = tools
+                ? wrapToolsForObservability(tools, tracer, recordObsContent ?? true)
+                : undefined;
+            // Augment contextManagement with protected tool names from context history.
+            // Protected tools (e.g., system skill reads) are excluded from clear_tool_uses
+            // so their results survive context compaction. See helper for details.
+            if (contextHandle) {
+                const protectedTools = contextHandle.context.getProtectedToolNames();
+                const augmented = mergeProtectedToolsIntoExcludeTools(restStreamOptions.providerOptions, protectedTools);
+                if (augmented.changed) {
+                    restStreamOptions.providerOptions =
+                        augmented.providerOptions;
+                    this.logger.info(`[llm-client] Added ${protectedTools.length} protected tool(s) to excludeTools (total ${augmented.mergedCount})`);
+                }
+            }
+            const result = await orchestrator.execute({
+                ...restStreamOptions,
+                tools: tracedTools,
+                model,
+                messages: messagesForModel,
+                system: usesManagedContext ? undefined : system,
+                prepareStep: ctx
+                    ? async (step) => {
+                        this.logger.debug("prepareStep");
+                        ctx.startStep();
+                        const messages = await ctx.getMessages();
+                        logToolContextIntegrityIssues(this.logger, "ctx.prepareStep", messages);
+                        step = { ...step, messages };
+                        return prepareStep?.(step) ?? step;
+                    }
+                    : prepareStep,
+                onStepFinish,
+                onFinish,
+                onChunk,
+            });
+            if (onError) {
+                void result.response?.catch((error) => {
+                    const normalizedError = error instanceof Error ? error : new Error(String(error));
+                    void onError(normalizedError);
+                });
+            }
+            return result;
+        }
+        catch (error) {
+            contextHandle?.release();
+            throw error;
+        }
+    }
+    /**
+     * Runs the Phase-2 context-compaction summarization call through this client
+     * so it inherits retry, idle-monitor stall handling, and the standardized
+     * observer pipeline instead of calling the AI SDK's `streamText`
+     * directly. Injected into the client-side compaction strategy via
+     * `contextManagement.summarizeLLM`.
+     *
+     * - Runs `stateless`: summarization is a one-shot with no
+     *   conversation to attach to, so it skips the managed-context machinery
+     *   (ephemeral context, turn tracking, context observer) and — because
+     *   stateless defaults logging off — persists no `.superblocks/generations`
+     *   artifacts without a per-call-site `logging: false`.
+     * - No `safety` object (reads as `safety: undefined`, like every other
+     *   non-user-prompt turn — subagent, judge, plan mode): the compaction prompt
+     *   is internally generated, not user content, so the migration adds only
+     *   retry/observability, never classification or redaction. The client skips
+     *   the safety pipeline whenever no safety feature is enabled.
+     * - `recordObsContent: false` — the LLMObsObserver is always attached, and the
+     *   compaction input is the serialized prior session (which can carry secrets
+     *   and tool output). With redaction off, recording content would annotate the
+     *   span with that raw conversation, so redact it on the span (model, usage,
+     *   timing, and span structure are still recorded). Mirrors how the safety
+     *   classifier keeps its prompt content off LLMObs.
+     * - `providerConfig` is threaded in via `args` from
+     *   `modelForTask("summarizeMessages")` (the `{ model, providerConfig }` pair
+     *   the other migrated call sites pass, see #20263), so it reflects the org's real
+     *   provider/core model instead of a hardcode. It only sets the retry-budget
+     *   profile + initial telemetry label; the real per-call model/provider are
+     *   recorded from the response headers on the obs span.
+     *
+     * Drains `fullStream` (not `textStream`) so the managed-stream wrapper fires
+     * session finalization, and captures usage/finishReason from the terminal
+     * `finish` part — emitted on the stream we already drain, so it is in-order
+     * with the loop (unlike `onFinish`, which is the AI SDK's callback on the
+     * inner provider stream and can fire *after* this loop exits, leaving the
+     * counts undefined and silently zeroing the summary message's tokenCount).
+     */
+    summarizeViaClient = async (args) => {
+        const user = args.messages[args.messages.length - 1];
+        if (!args.providerConfig) {
+            // Production always threads this from `modelForTask("summarizeMessages")`
+            // through the compaction DI chain; a missing value means the wiring is
+            // broken, not a case to paper over with a default.
+            throw new Error("summarizeViaClient requires a providerConfig threaded from the " +
+                "compaction strategy (modelForTask). None was supplied.");
+        }
+        const result = await this.streamText({
+            // The summarization model always resolves to a LanguageModelV3 (from
+            // `modelForTask`), never a bare string, in the compaction path.
+            model: args.model,
+            user,
+            system: args.system,
+            maxOutputTokens: args.maxOutputTokens,
+            abortSignal: args.abortSignal,
+            providerConfig: args.providerConfig,
+            context: { mode: "stateless" },
+            recordObsContent: false,
+        });
+        let text = "";
+        let usage;
+        let finishReason;
+        for await (const part of result.fullStream) {
+            if (part.type === "text-delta") {
+                text += part.text;
+            }
+            else if (part.type === "finish") {
+                usage = part.totalUsage;
+                finishReason = part.finishReason;
+            }
+        }
+        return { text, usage, finishReason };
+    };
+    async createContext(contextId, contextOptionsV2, tracer, contextManagement, peer) {
+        const context = await this.contextManagerV2.getOrCreateContext(contextId, contextOptionsV2, tracer, contextManagement, {
+            ...((this.applicationId ?? contextId?.appId)
+                ? { applicationId: this.applicationId ?? contextId?.appId }
+                : {}),
+            ...(this.organizationId ? { organizationId: this.organizationId } : {}),
+        });
+        const adapter = ContextV2Adapter.fromContext(context);
+        adapter.setCompactionCallbacks(undefined);
+        // Surface compaction as `context-compaction-phase2` control messages on
+        // the peer. Client-side callbacks fire around local summarization; the
+        // server-side strategy fires them when the provider reports that a managed
+        // compact edit ran.
+        if (contextManagement && peer) {
+            adapter.setCompactionCallbacks({
+                onCompactionStart: (phase, messageId) => {
+                    if (phase === "phase1")
+                        return;
+                    catchBackgroundPeerDisconnect(peer.call.aiPushMessage({
+                        id: messageId,
+                        role: "system",
+                        type: "control",
+                        group: `context-compaction-${phase}`,
+                        content: "Summarizing conversation",
+                        status: "pending",
+                    }), "compaction start push");
+                },
+                onCompactionCancel: (phase, messageId) => {
+                    if (phase === "phase1")
+                        return;
+                    catchBackgroundPeerDisconnect(peer.call.aiPushMessage({
+                        id: messageId,
+                        role: "system",
+                        type: "control",
+                        group: `context-compaction-${phase}`,
+                        content: "Summarizing conversation",
+                        status: "cancelled",
+                    }), "compaction cancel push");
+                },
+                onCompactionComplete: (phase, messageId, summary) => {
+                    if (phase === "phase1")
+                        return;
+                    const isInterrupted = summary === SERVER_COMPACTION_INTERRUPTED_SUMMARY;
+                    catchBackgroundPeerDisconnect(peer.call.aiPushMessage({
+                        id: messageId,
+                        role: "system",
+                        type: "control",
+                        group: `context-compaction-${phase}`,
+                        content: isInterrupted
+                            ? "Compaction interrupted"
+                            : "Summarized past conversation",
+                        status: "validated",
+                        summary,
+                    }), "compaction complete push");
+                },
+            });
+        }
+        this.logger.info(`[llm-client] context (${contextId?.name ?? "ephemeral"}, persistent=${!!this.contextManagerV2 && !!contextId})`);
+        return {
+            contextHandle: {
+                context: adapter,
+                release: () => { },
+            },
+            ctx: adapter,
+        };
+    }
+    /**
+     * Generates text from the LLM without exposing a stream to the caller.
+     *
+     * Convenience wrapper around {@link streamText} that drains the result and
+     * returns the joined text. Routing through `streamText` inherits the same
+     * context management, safety classification, retry, and observability.
+     *
+     * `observers` is intentionally omitted from the options: callers cannot
+     * inject their own stream observers here, but the internal `streamText` path
+     * still creates the logging/LLMObs observers, so observability fires as
+     * usual. `experimental_output` is also omitted — passing it would silently
+     * put the model in JSON mode while this method still returns a raw text
+     * string; use {@link generateObject} for structured output.
+     *
+     * @param options - Same options as `streamText`, minus `observers` and
+     *   `experimental_output`.
+     * @returns The concatenated `text-delta` content.
+     *
+     * @example
+     * ```typescript
+     * const text = await client.generateText({
+     *   model,
+     *   user: { role: "user", content: "Summarize this..." },
+     *   providerConfig: { provider: "vertex", model: "claude-sonnet-4-5" },
+     * });
+     * ```
+     */
+    async generateText(options, logger = getLogger(), tracer = LLMObsTracer.instance) {
+        const result = await this.streamText(options, logger, tracer);
+        return this.drainTextChunks(result, "generateText", logger);
+    }
+    /**
+     * Drain a managed `fullStream`, returning the concatenated `text-delta`
+     * content. `fullStream` (not `textStream`) is drained because the managed-
+     * stream wrapper on it fires session finalization, which observers rely on to
+     * flush obs spans and persist logs. On a mid-stream failure it logs and
+     * rethrows a "<caller> failed during stream consumption" error, preserving
+     * the original cause.
+     */
+    async drainTextChunks(result, callerName, logger) {
+        const chunks = [];
+        try {
+            for await (const part of result.fullStream) {
+                if (part.type === "text-delta") {
+                    chunks.push(part.text);
+                }
+            }
+        }
+        catch (error) {
+            const errorMeta = getErrorMeta(error);
+            logger.error(`[llm-client] ${callerName} stream consumption failed after ${chunks.length} chunks`, errorMeta);
+            throw new Error(`${callerName} failed during stream consumption after ${chunks.length} chunks: ${errorMeta.error.message}`, { cause: error });
+        }
+        return chunks.join("");
+    }
+    /**
+     * Drains a structured-output (`generateObject`) stream, capturing the result
+     * from whichever channel the provider used.
+     *
+     * The adapter's `Output.object` sets the JSON response format, but providers
+     * deliver the answer differently:
+     *  - some stream the JSON as plain text (`text-delta`);
+     *  - direct `@ai-sdk/anthropic` realizes structured output as a forced `json`
+     *    tool call, so the object arrives as the tool-call input and NO
+     *    `text-delta` is emitted. Draining only text there yields an empty string
+     *    and a spurious "empty response" error (APPS-1213).
+     *  - the Clark proxy (`@superblocksteam/clark`, used for bedrock/vertex)
+     *    streams the result as a Clark `object` chunk; if that chunk carries no
+     *    `id`, the Clark model forwards it as a `raw` part (its
+     *    `forwardAsActivity`), so the object reaches neither the text nor the
+     *    tool-call channel. We recover it from the raw `object` chunk (APPS-1213).
+     *
+     * `generateObject` disables user tools (`tools: undefined, maxSteps: 1`), so
+     * any tool call in the stream is the injected structured-output tool. We
+     * capture its already-parsed `input`; if only input deltas stream without a
+     * terminal `tool-call` part, we recover the object from the accumulated JSON.
+     * The full `fullStream` is still drained, which is what triggers session
+     * finalization for observability.
+     */
+    async drainObjectStream(result, logger) {
+        const chunks = [];
+        let toolObject;
+        let toolInputJson = "";
+        try {
+            for await (const part of result.fullStream) {
+                if (part.type === "text-delta") {
+                    chunks.push(part.text);
+                }
+                else if (part.type === "tool-call") {
+                    toolObject = part.input;
+                }
+                else if (part.type === "tool-input-delta") {
+                    toolInputJson += part.delta ?? "";
+                }
+                else if (part.type === "raw") {
+                    // Clark proxy channel (vertex/bedrock via @superblocksteam/clark):
+                    // a JSON-`responseFormat` result is streamed as a Clark `object`
+                    // chunk. When that chunk has no `id`, the Clark model can't turn it
+                    // into a `text-delta` and forwards it verbatim as a `raw` part (its
+                    // `forwardAsActivity`). The object then reaches neither the text nor
+                    // the tool-call channel, so draining only those read it as empty even
+                    // though the model produced the full object (APPS-1213). Recover it
+                    // from the raw `object` chunk's `object` field.
+                    const rawValue = part.rawValue;
+                    if (rawValue !== null &&
+                        typeof rawValue === "object" &&
+                        rawValue.type === "object" &&
+                        rawValue.object !== undefined) {
+                        toolObject = rawValue.object;
+                    }
+                }
+            }
+        }
+        catch (error) {
+            const errorMeta = getErrorMeta(error);
+            logger.error(`[llm-client] generateObject stream consumption failed after ${chunks.length} text chunks`, errorMeta);
+            throw new Error(`generateObject failed during stream consumption after ${chunks.length} chunks: ${errorMeta.error.message}`, { cause: error });
+        }
+        // The raw `toolInputJson` is returned unparsed so the caller can tell a
+        // genuinely-empty response apart from malformed/truncated tool input: if
+        // the model emitted tool-input bytes that fail to parse, that is a parse
+        // error to surface, not an "empty response".
+        return { text: chunks.join(""), toolObject, toolInputJson };
+    }
+    /**
+     * Generates structured output validated against a Zod (or flexible) schema.
+     *
+     * Passes the schema through to the adapter's `Output.object` (which sets the
+     * JSON response format), routes through {@link streamText} with tools
+     * disabled and a single step, then resolves the object from whichever channel
+     * the provider used — the drained text, or the structured-output tool call
+     * (Anthropic/Clark realize `Output.object` as a forced `json` tool, so the
+     * object arrives as the tool-call input with no text emitted; see
+     * {@link drainObjectStream}) — and schema-validates it. Like
+     * {@link generateText}, draining `fullStream` is what triggers session
+     * finalization for observability.
+     *
+     * Snowflake Cortex constraint: Cortex rejects `generateObject` calls whose
+     * schema emits certain JSON Schema keywords, so avoid Zod refinements like
+     * `.min()` / `.max()` / `.email()` / `.url()` / `.uuid()` etc. in the
+     * `schema` — use the JSON-Schema-keyword forms (`minLength` / `maxLength` /
+     * `minimum` / `maximum` / `format`, ...) instead. See the "Snowflake Cortex
+     * generateObject schema constraints" section in the repo AGENTS.md for the
+     * full keyword list.
+     *
+     * @param options - Stream options plus the required `schema`.
+     * @returns The parsed, schema-validated object.
+     *
+     * @example
+     * ```typescript
+     * const result = await client.generateObject({
+     *   model,
+     *   user: { role: "user", content: "Classify this prompt" },
+     *   schema: z.object({ safe: z.boolean(), justification: z.string() }),
+     *   providerConfig: { provider: "vertex", model: "claude-sonnet-4-5" },
+     * });
+     * ```
+     */
+    async generateObject(options, logger = getLogger(), tracer = LLMObsTracer.instance) {
+        const { schema, ...streamOptions } = options;
+        const result = await this.streamText({
+            ...streamOptions,
+            // Structured output is single-step and tool-free.
+            tools: undefined,
+            maxSteps: 1,
+            // Pass the schema straight through; the adapter wraps it in the SDK's
+            // Output.object (which accepts a Zod/flexible schema directly) to set
+            // the JSON response format. We still own the final parse/validate
+            // below so error shapes stay consistent and tied to fullStream drain.
+            experimental_output: schema,
+        }, logger, tracer);
+        const { text: fullText, toolObject, toolInputJson, } = await this.drainObjectStream(result, logger);
+        // Only a stream with no text, no resolved tool-call object, and no tool
+        // input bytes is genuinely empty. A non-empty `toolInputJson` that fails to
+        // parse is malformed output (handled in the parse path below), not empty.
+        if (!fullText && toolObject === undefined && !toolInputJson) {
+            logger.error("[llm-client] generateObject received an empty response");
+            throw new Error("generateObject failed: received an empty response from the model.");
+        }
+        // Final JSON-parse + schema-validation is the most likely failure mode in
+        // production, so log it (with the offending text length) before it
+        // propagates — otherwise the failure is a silent blind spot.
+        try {
+            let value;
+            if (fullText) {
+                const parseResult = await safeParseJSON({ text: fullText });
+                if (!parseResult.success) {
+                    throw new Error(`Failed to parse JSON response: ${parseResult.error.message}`);
+                }
+                value = parseResult.value;
+            }
+            else if (toolObject !== undefined) {
+                // Structured-output tool-call channel: input is already a parsed object.
+                value = toolObject;
+            }
+            else {
+                // Tool input streamed as deltas without a terminal tool-call part: parse
+                // the accumulated JSON. A failure here is truncated/corrupt output, so
+                // surface it as a parse error rather than letting it read as "empty".
+                const parseResult = await safeParseJSON({ text: toolInputJson });
+                if (!parseResult.success) {
+                    throw new Error(`Failed to parse JSON response: ${parseResult.error.message}`);
+                }
+                value = parseResult.value;
+            }
+            const validationResult = await safeValidateTypes({
+                value,
+                schema: asSchema(schema),
+            });
+            if (!validationResult.success) {
+                throw new Error(`Response did not match schema: ${validationResult.error.message}`);
+            }
+            return validationResult.value;
+        }
+        catch (error) {
+            const errorMeta = getErrorMeta(error);
+            logger.error(`[llm-client] generateObject failed to parse/validate output ` +
+                `(textLen=${fullText.length}, viaToolCall=${!fullText})`, errorMeta);
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=client.js.map