@superblocksteam/vite-plugin-file-sync 2.0.137-next.0 → 2.0.138-next.0

package/dist/ai-service/knowledge/knowledge-metrics-emitters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-metrics-emitters.d.ts","sourceRoot":"","sources":["../../../src/ai-service/knowledge/knowledge-metrics-emitters.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,wBAAwB,CAAC;AA+BhC;;GAEG;AACH,wBAAgB,8BAA8B,CAAC,KAAK,EAAE;IACpD,UAAU,CAAC,EAAE;QACX,sBAAsB,EAAE,MAAM,EAAE,CAAC;QACjC,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,QAAQ,EAAE,WAAW,CAAC;CACvB,GAAG,IAAI,CA+BP;AAED,wBAAgB,2BAA2B,CAAC,KAAK,EAAE;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,IAAI,CAMP;AAED,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAElE;AAED,wBAAgB,kCAAkC,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQzE"}

package/dist/ai-service/knowledge/knowledge-metrics-emitters.js

@@ -0,0 +1,77 @@
+import { FactAccessType } from "@superblocksteam/shared";
+import { recordKnowledgeIndexFacts, recordKnowledgeRead, resetKnowledgeReadTrackerForTurn, } from "./knowledge-metrics.js";
+function countOnDemandFacts(facts) {
+    return facts.filter((fact) => fact.accessType === FactAccessType.ON_DEMAND)
+        .length;
+}
+/** Matches `generateOnDemandFactsSkillIndex`: integration entries include all facts. */
+function countIntegrationIndexFacts(facts) {
+    return Object.values(facts.integrations).reduce((total, integrationFacts) => total + integrationFacts.length, 0);
+}
+function recordAlwaysInjectReads(layer, facts) {
+    for (const fact of facts) {
+        if (fact.accessType !== FactAccessType.ALWAYS_INJECT) {
+            continue;
+        }
+        recordKnowledgeRead({
+            accessType: "always_inject",
+            dedupeKey: fact.id,
+            layer,
+        });
+    }
+}
+/**
+ * Emit read and index metrics at the start of an LLM turn after facts are loaded.
+ */
+export function recordKnowledgeTurnLoadMetrics(input) {
+    resetKnowledgeReadTrackerForTurn();
+    recordAlwaysInjectReads("org", input.rpcFacts.org);
+    recordAlwaysInjectReads("user", input.rpcFacts.user);
+    for (const integrationFacts of Object.values(input.rpcFacts.integrations)) {
+        recordAlwaysInjectReads("integration", integrationFacts);
+    }
+    const indexCounts = {
+        integration: countIntegrationIndexFacts(input.rpcFacts),
+        org: countOnDemandFacts(input.rpcFacts.org),
+        user: countOnDemandFacts(input.rpcFacts.user),
+    };
+    if (input.appMetrics) {
+        for (const dedupeKey of input.appMetrics.alwaysInjectDedupeKeys) {
+            recordKnowledgeRead({
+                accessType: "always_inject",
+                dedupeKey,
+                layer: "app",
+            });
+        }
+        indexCounts.app = input.appMetrics.onDemandIndexCount;
+    }
+    else {
+        // Explicit zero so a failed load does not leave a stale app count from a
+        // prior turn (ObservableGauge only overwrites layers present in payload).
+        indexCounts.app = 0;
+    }
+    recordKnowledgeIndexFacts({ counts: indexCounts });
+}
+export function recordKnowledgeOnDemandRead(input) {
+    recordKnowledgeRead({
+        accessType: "on_demand",
+        dedupeKey: input.dedupeKey,
+        layer: input.layer,
+    });
+}
+export function isAppKnowledgeReadPath(filePath) {
+    return filePath.startsWith("skills/app/") && filePath.endsWith(".md");
+}
+export function appKnowledgeReadDedupeKey(filePath) {
+    return filePath;
+}
+export function recordAppKnowledgeReadIfApplicable(filePath) {
+    if (!isAppKnowledgeReadPath(filePath)) {
+        return;
+    }
+    recordKnowledgeOnDemandRead({
+        dedupeKey: appKnowledgeReadDedupeKey(filePath),
+        layer: "app",
+    });
+}
+//# sourceMappingURL=knowledge-metrics-emitters.js.map

package/dist/ai-service/knowledge/knowledge-metrics-emitters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-metrics-emitters.js","sourceRoot":"","sources":["../../../src/ai-service/knowledge/knowledge-metrics-emitters.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/knowledge/knowledge-metrics.d.ts

@@ -0,0 +1,43 @@
+export declare const KNOWLEDGE_LAYERS: readonly ["app", "integration", "org", "user"];
+export type KnowledgeLayer = (typeof KNOWLEDGE_LAYERS)[number];
+export declare const KNOWLEDGE_ACCESS_TYPES: readonly ["always_inject", "on_demand"];
+export type KnowledgeAccessType = (typeof KNOWLEDGE_ACCESS_TYPES)[number];
+export declare const KNOWLEDGE_SUGGESTION_SOURCES: readonly ["remember_knowledge"];
+export type KnowledgeSuggestionSource = (typeof KNOWLEDGE_SUGGESTION_SOURCES)[number];
+export declare const KNOWLEDGE_APPROVAL_PROMPT_TYPES: readonly ["confirm", "multi_choice", "remember_knowledge_draft"];
+export type KnowledgeApprovalPromptType = (typeof KNOWLEDGE_APPROVAL_PROMPT_TYPES)[number];
+export declare const KNOWLEDGE_APPROVAL_OUTCOMES: readonly ["approved", "denied"];
+export type KnowledgeApprovalOutcome = (typeof KNOWLEDGE_APPROVAL_OUTCOMES)[number];
+export declare const KNOWLEDGE_WRITE_SCOPES: readonly ["app", "integration", "org", "user"];
+export type KnowledgeWriteScope = (typeof KNOWLEDGE_WRITE_SCOPES)[number];
+export declare const KNOWLEDGE_WRITE_ACTIONS: readonly ["create", "delete", "update"];
+export type KnowledgeWriteAction = (typeof KNOWLEDGE_WRITE_ACTIONS)[number];
+export declare const KNOWLEDGE_WRITE_STATUSES: readonly ["created", "created_remote", "deleted", "failed", "skipped_not_found", "updated"];
+export type KnowledgeWriteStatus = (typeof KNOWLEDGE_WRITE_STATUSES)[number];
+export declare function resetKnowledgeReadTrackerForTurn(): void;
+export declare function recordKnowledgeRead(input: {
+    accessType: KnowledgeAccessType;
+    dedupeKey: string;
+    layer: KnowledgeLayer;
+}): void;
+export declare function recordKnowledgeIndexFacts(input: {
+    counts: Partial<Record<KnowledgeLayer, number>>;
+}): void;
+export declare function recordKnowledgeSuggestion(input: {
+    candidateCount: number;
+    source: KnowledgeSuggestionSource;
+}): void;
+export declare function recordKnowledgeDuplicateHint(): void;
+export declare function recordKnowledgeApprovalPrompt(input: {
+    promptType: KnowledgeApprovalPromptType;
+}): void;
+export declare function recordKnowledgeApprovalResponse(input: {
+    outcome: KnowledgeApprovalOutcome;
+}): void;
+export declare function recordKnowledgeWrite(input: {
+    action: KnowledgeWriteAction;
+    scope: KnowledgeWriteScope;
+    status: KnowledgeWriteStatus;
+}): void;
+export declare function _resetClarkKnowledgeMetricsForTesting(): void;
+//# sourceMappingURL=knowledge-metrics.d.ts.map

package/dist/ai-service/knowledge/knowledge-metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-metrics.d.ts","sourceRoot":"","sources":["../../../src/ai-service/knowledge/knowledge-metrics.ts"],"names":[],"mappings":"AAoCA,eAAO,MAAM,gBAAgB,gDAAiD,CAAC;AAC/E,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/D,eAAO,MAAM,sBAAsB,yCAA0C,CAAC;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,eAAO,MAAM,4BAA4B,iCAAkC,CAAC;AAC5E,MAAM,MAAM,yBAAyB,GACnC,CAAC,OAAO,4BAA4B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhD,eAAO,MAAM,+BAA+B,kEAIlC,CAAC;AACX,MAAM,MAAM,2BAA2B,GACrC,CAAC,OAAO,+BAA+B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,2BAA2B,iCAAkC,CAAC;AAC3E,MAAM,MAAM,wBAAwB,GAClC,CAAC,OAAO,2BAA2B,CAAC,CAAC,MAAM,CAAC,CAAC;AAE/C,eAAO,MAAM,sBAAsB,gDAKzB,CAAC;AACX,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE1E,eAAO,MAAM,uBAAuB,yCAA0C,CAAC;AAC/E,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5E,eAAO,MAAM,wBAAwB,6FAO3B,CAAC;AACX,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAyM7E,wBAAgB,gCAAgC,IAAI,IAAI,CAEvD;AAED,wBAAgB,mBAAmB,CAAC,KAAK,EAAE;IACzC,UAAU,EAAE,mBAAmB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,cAAc,CAAC;CACvB,GAAG,IAAI,CAEP;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD,GAAG,IAAI,CAEP;AAED,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,yBAAyB,CAAC;CACnC,GAAG,IAAI,CAEP;AAED,wBAAgB,4BAA4B,IAAI,IAAI,CAEnD;AAED,wBAAgB,6BAA6B,CAAC,KAAK,EAAE;IACnD,UAAU,EAAE,2BAA2B,CAAC;CACzC,GAAG,IAAI,CAEP;AAED,wBAAgB,+BAA+B,CAAC,KAAK,EAAE;IACrD,OAAO,EAAE,wBAAwB,CAAC;CACnC,GAAG,IAAI,CAEP;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,MAAM,EAAE,oBAAoB,CAAC;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,MAAM,EAAE,oBAAoB,CAAC;CAC9B,GAAG,IAAI,CAEP;AAED,wBAAgB,qCAAqC,IAAI,IAAI,CAE5D"}

package/dist/ai-service/knowledge/knowledge-metrics.js

@@ -0,0 +1,217 @@
+/**
+ * Clark knowledge lifecycle metrics (APPS-5064).
+ *
+ * Production counters/histograms/gauges for knowledge reads, the suggest→approve
+ * funnel, and writes. Complements retrieval spans from APPS-4708
+ * (`knowledge.facts`, `app_skills.load`).
+ *
+ * Wiring follows `ClarkContextMetrics` (APPS-4708): lazy meter resolution from
+ * the OTel global, instruments re-bound when the MeterProvider changes.
+ *
+ * Metrics:
+ *
+ *   - `superblocks.clark.knowledge.reads_total`              counter {layer, access_type}
+ *   - `superblocks.clark.knowledge.read_duplicates_total`    counter {layer}
+ *   - `superblocks.clark.knowledge.index_facts`              gauge     {layer}
+ *   - `superblocks.clark.knowledge.suggestions_total`        counter {source}
+ *   - `superblocks.clark.knowledge.suggestion_candidates`      histogram
+ *   - `superblocks.clark.knowledge.duplicate_hints_total`    counter
+ *   - `superblocks.clark.knowledge.approval_prompts_total`   counter {prompt_type}
+ *   - `superblocks.clark.knowledge.approval_responses_total` counter {outcome}
+ *   - `superblocks.clark.knowledge.writes_total`             counter {scope, action, status}
+ *
+ * Base cardinality budget (documented contract — growing an enum must be a
+ * deliberate, reviewed change; the regression test pins these counts):
+ *
+ *   reads(4×2) + read_duplicates(4) + index_facts(4) + suggestions(1) +
+ *   suggestion_candidates(1) + duplicate_hints(1) + approval_prompts(3) +
+ *   approval_responses(2) + writes(4×3×6) = 96 worst-case series.
+ */
+import { metrics, } from "@opentelemetry/api";
+export const KNOWLEDGE_LAYERS = ["app", "integration", "org", "user"];
+export const KNOWLEDGE_ACCESS_TYPES = ["always_inject", "on_demand"];
+export const KNOWLEDGE_SUGGESTION_SOURCES = ["remember_knowledge"];
+export const KNOWLEDGE_APPROVAL_PROMPT_TYPES = [
+    "confirm",
+    "multi_choice",
+    "remember_knowledge_draft",
+];
+export const KNOWLEDGE_APPROVAL_OUTCOMES = ["approved", "denied"];
+export const KNOWLEDGE_WRITE_SCOPES = [
+    "app",
+    "integration",
+    "org",
+    "user",
+];
+export const KNOWLEDGE_WRITE_ACTIONS = ["create", "delete", "update"];
+export const KNOWLEDGE_WRITE_STATUSES = [
+    "created",
+    "created_remote",
+    "deleted",
+    "failed",
+    "skipped_not_found",
+    "updated",
+];
+const METER_NAME = "superblocks.clark.knowledge";
+const METRIC_READS = "superblocks.clark.knowledge.reads_total";
+const METRIC_READ_DUPLICATES = "superblocks.clark.knowledge.read_duplicates_total";
+const METRIC_INDEX_FACTS = "superblocks.clark.knowledge.index_facts";
+const METRIC_SUGGESTIONS = "superblocks.clark.knowledge.suggestions_total";
+const METRIC_SUGGESTION_CANDIDATES = "superblocks.clark.knowledge.suggestion_candidates";
+const METRIC_DUPLICATE_HINTS = "superblocks.clark.knowledge.duplicate_hints_total";
+const METRIC_APPROVAL_PROMPTS = "superblocks.clark.knowledge.approval_prompts_total";
+const METRIC_APPROVAL_RESPONSES = "superblocks.clark.knowledge.approval_responses_total";
+const METRIC_WRITES = "superblocks.clark.knowledge.writes_total";
+const SUGGESTION_CANDIDATE_BUCKETS = [1, 2, 3, 5, 10, 20];
+class ClarkKnowledgeMetrics {
+    cachedInstruments;
+    cachedMeter;
+    indexFactCounts = new Map();
+    readKeysThisTurn = new Set();
+    observeIndexFacts = (result) => {
+        for (const [layer, value] of this.indexFactCounts.entries()) {
+            result.observe(value, { layer });
+        }
+    };
+    getInstruments() {
+        const meter = metrics.getMeter(METER_NAME);
+        if (meter === this.cachedMeter && this.cachedInstruments) {
+            return this.cachedInstruments;
+        }
+        this.cachedInstruments?.indexFactsGauge.removeCallback(this.observeIndexFacts);
+        this.cachedMeter = meter;
+        const indexFactsGauge = meter.createObservableGauge(METRIC_INDEX_FACTS, {
+            description: "Knowledge facts listed in the skill index at the last observed turn per layer (values persist until the next update for that layer). Org/user count on-demand entries only; integration counts all indexed integration facts.",
+            unit: "{fact}",
+        });
+        indexFactsGauge.addCallback(this.observeIndexFacts);
+        this.cachedInstruments = {
+            approvalPromptsCounter: meter.createCounter(METRIC_APPROVAL_PROMPTS, {
+                description: "Knowledge approval prompts shown to the user.",
+                unit: "{prompt}",
+            }),
+            approvalResponsesCounter: meter.createCounter(METRIC_APPROVAL_RESPONSES, {
+                description: "User responses to knowledge approval prompts.",
+                unit: "{response}",
+            }),
+            duplicateHintsCounter: meter.createCounter(METRIC_DUPLICATE_HINTS, {
+                description: "rememberKnowledge calls where recentlySavedMatches was non-empty.",
+                unit: "{hint}",
+            }),
+            indexFactsGauge,
+            readDuplicatesCounter: meter.createCounter(METRIC_READ_DUPLICATES, {
+                description: "Repeated reads of the same knowledge fact/path within one turn.",
+                unit: "{read}",
+            }),
+            readsCounter: meter.createCounter(METRIC_READS, {
+                description: "Knowledge surfaced into context via auto-inject or on-demand read.",
+                unit: "{read}",
+            }),
+            suggestionCandidatesHistogram: meter.createHistogram(METRIC_SUGGESTION_CANDIDATES, {
+                advice: { explicitBucketBoundaries: SUGGESTION_CANDIDATE_BUCKETS },
+                description: "Candidate count per rememberKnowledge call with valid candidates.",
+                unit: "{candidate}",
+            }),
+            suggestionsCounter: meter.createCounter(METRIC_SUGGESTIONS, {
+                description: "Valid knowledge suggestions from rememberKnowledge.",
+                unit: "{suggestion}",
+            }),
+            writesCounter: meter.createCounter(METRIC_WRITES, {
+                description: "Knowledge persistence attempts from saveKnowledgeAndNotify.",
+                unit: "{write}",
+            }),
+        };
+        return this.cachedInstruments;
+    }
+    resetReadTrackerForTurn() {
+        this.readKeysThisTurn.clear();
+    }
+    recordRead(input) {
+        const instruments = this.getInstruments();
+        const attributes = {
+            access_type: input.accessType,
+            layer: input.layer,
+        };
+        instruments.readsCounter.add(1, attributes);
+        const dedupeKey = `${input.layer}:${input.dedupeKey}`;
+        if (this.readKeysThisTurn.has(dedupeKey)) {
+            instruments.readDuplicatesCounter.add(1, { layer: input.layer });
+        }
+        else {
+            this.readKeysThisTurn.add(dedupeKey);
+        }
+    }
+    recordIndexFacts(input) {
+        this.getInstruments();
+        for (const layer of KNOWLEDGE_LAYERS) {
+            const count = input.counts[layer];
+            if (count === undefined) {
+                continue;
+            }
+            this.indexFactCounts.set(layer, Math.max(0, count));
+        }
+    }
+    recordSuggestion(input) {
+        const instruments = this.getInstruments();
+        instruments.suggestionsCounter.add(1, { source: input.source });
+        if (input.candidateCount > 0) {
+            instruments.suggestionCandidatesHistogram.record(input.candidateCount);
+        }
+    }
+    recordDuplicateHint() {
+        this.getInstruments().duplicateHintsCounter.add(1);
+    }
+    recordApprovalPrompt(input) {
+        this.getInstruments().approvalPromptsCounter.add(1, {
+            prompt_type: input.promptType,
+        });
+    }
+    recordApprovalResponse(input) {
+        this.getInstruments().approvalResponsesCounter.add(1, {
+            outcome: input.outcome,
+        });
+    }
+    recordWrite(input) {
+        this.getInstruments().writesCounter.add(1, {
+            action: input.action,
+            scope: input.scope,
+            status: input.status,
+        });
+    }
+    _resetForTesting() {
+        this.cachedInstruments?.indexFactsGauge.removeCallback(this.observeIndexFacts);
+        this.cachedMeter = undefined;
+        this.cachedInstruments = undefined;
+        this.indexFactCounts.clear();
+        this.readKeysThisTurn.clear();
+    }
+}
+const clarkKnowledgeMetrics = new ClarkKnowledgeMetrics();
+export function resetKnowledgeReadTrackerForTurn() {
+    clarkKnowledgeMetrics.resetReadTrackerForTurn();
+}
+export function recordKnowledgeRead(input) {
+    clarkKnowledgeMetrics.recordRead(input);
+}
+export function recordKnowledgeIndexFacts(input) {
+    clarkKnowledgeMetrics.recordIndexFacts(input);
+}
+export function recordKnowledgeSuggestion(input) {
+    clarkKnowledgeMetrics.recordSuggestion(input);
+}
+export function recordKnowledgeDuplicateHint() {
+    clarkKnowledgeMetrics.recordDuplicateHint();
+}
+export function recordKnowledgeApprovalPrompt(input) {
+    clarkKnowledgeMetrics.recordApprovalPrompt(input);
+}
+export function recordKnowledgeApprovalResponse(input) {
+    clarkKnowledgeMetrics.recordApprovalResponse(input);
+}
+export function recordKnowledgeWrite(input) {
+    clarkKnowledgeMetrics.recordWrite(input);
+}
+export function _resetClarkKnowledgeMetricsForTesting() {
+    clarkKnowledgeMetrics._resetForTesting();
+}
+//# sourceMappingURL=knowledge-metrics.js.map

package/dist/ai-service/knowledge/knowledge-metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge-metrics.js","sourceRoot":"","sources":["../../../src/ai-service/knowledge/knowledge-metrics.ts"],"names":[],"mappings":"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"}

package/dist/ai-service/llm/client.d.ts

@@ -1,4 +1,5 @@
 import type { LanguageModelV3 } from "@ai-sdk/provider";
+import { type FlexibleSchema } from "@ai-sdk/provider-utils";
 import type { ModelMessage } from "ai";
 import type { Tool } from "../agent/tools2/types.js";
 import type { AppShell } from "../app-interface/shell.js";
@@ -13,29 +14,43 @@ import type { ContextId } from "./context-v2/types.js";
 import type { StreamTextResult, StreamTextProvider } from "./interaction/provider.js";
 import type { StreamTextOptions } from "./interaction/provider.js";
 import { type ProviderType, type CoreModelType, type FallbackStrategy, type LogRef, type RetryConfigOptions, type StreamObserver } from "./stream/index.js";
-export interface LLMClientStreamTextOptions<TOOLS extends Record<string, Tool>> extends Omit<StreamTextOptions<TOOLS>, "messages"> {
-    context?: {
-        contextId?: ContextId;
-        messages?: ModelMessage[];
-        contextOptionsV2?: Partial<ContextOptionsV2>;
-        /**
-         * Optional compaction strategy selection. When omitted the context manager
-         * defaults to server-side compaction; passing `{ type: "client", ... }`
-         * routes through the legacy phase-1+phase-2 path (used as the runtime
-         * kill-switch when server-side context management misbehaves).
-         */
-        contextManagement?: ContextManagementOptions;
-    };
+type ManagedLLMContextConfig = {
+    mode?: "managed";
+    contextId?: ContextId;
+    messages?: ModelMessage[];
+    contextOptionsV2?: Partial<ContextOptionsV2>;
+    /**
+     * Optional compaction strategy selection. When omitted the context manager
+     * defaults to server-side compaction; passing `{ type: "client", ... }`
+     * routes through the legacy phase-1+phase-2 path (used as the runtime
+     * kill-switch when server-side context management misbehaves).
+     */
+    contextManagement?: ContextManagementOptions;
+};
+type StatelessLLMContextConfig = {
+    mode: "stateless";
+};
+export type LLMClientContextConfig = ManagedLLMContextConfig | StatelessLLMContextConfig;
+export interface LLMClientProviderConfig {
+    provider: ProviderType;
+    model: CoreModelType;
+}
+export interface LLMClientStreamTextOptions<TOOLS extends Record<string, Tool>, OUTPUT = unknown> extends Omit<StreamTextOptions<TOOLS, OUTPUT>, "messages"> {
+    context?: LLMClientContextConfig;
     logging?: {
         conversationId?: string;
         logRef?: LogRef;
         metadata?: Record<string, unknown>;
     } | false;
+    /**
+     * When false, LLM message input/output content is replaced with a redacted
+     * placeholder on the LLMObs span (the span, metrics, model, and timing are
+     * still recorded). Use for internal calls whose content may carry secrets.
+     * Defaults to true.
+     */
+    recordObsContent?: boolean;
     retry?: RetryConfigOptions;
-    providerConfig: {
-        provider: ProviderType;
-        model: CoreModelType;
-    };
+    providerConfig: LLMClientProviderConfig;
     /**
      * Thinking knobs for the model. When set, the orchestrator will rebuild
      * provider-specific thinking options per attempt based on the current
@@ -60,6 +75,7 @@ export interface LLMClientStreamTextOptions<TOOLS extends Record<string, Tool>>
         classification?: {
             enabled: boolean;
             model?: LanguageModelV3;
+            providerConfig?: LLMClientProviderConfig;
             timeout?: number;
             failOpen?: boolean;
         };
@@ -69,6 +85,18 @@ export interface LLMClientStreamTextOptions<TOOLS extends Record<string, Tool>>
         };
     };
 }
+/**
+ * Options for {@link LLMClient.generateObject}. Adds the required `schema`
+ * (used to build the JSON response format and to validate the final output)
+ * and drops `experimental_output`, which the method builds internally from the
+ * schema. `tools` and `maxSteps` are also dropped because `generateObject`
+ * unconditionally overrides them (structured output is single-step and
+ * tool-free) — accepting them would be a silently-ignored footgun.
+ */
+export interface LLMClientGenerateObjectOptions<TOOLS extends Record<string, Tool>, OUTPUT> extends Omit<LLMClientStreamTextOptions<TOOLS, OUTPUT>, "experimental_output" | "tools" | "maxSteps"> {
+    /** Zod (or other flexible) schema the output must match. */
+    schema: FlexibleSchema<OUTPUT>;
+}
 export interface LLMClientParameters {
     contextManagerV2: ContextManagerV2;
     appShell: AppShell;
@@ -145,7 +173,105 @@ export declare class LLMClient {
      * @returns Object containing the processed message and classification result
      */
     private applySafetyClassification;
-    streamText<TOOLS extends Record<string, Tool>>(options: LLMClientStreamTextOptions<TOOLS>, logger?: import("../../util/logger.js").Logger, tracer?: LLMObsTracer): Promise<StreamTextResult<TOOLS>>;
+    streamText<TOOLS extends Record<string, Tool>, OUTPUT = unknown>(options: LLMClientStreamTextOptions<TOOLS, OUTPUT>, logger?: import("../../util/logger.js").Logger, tracer?: LLMObsTracer): Promise<StreamTextResult<TOOLS>>;
     private createContext;
+    /**
+     * 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" },
+     * });
+     * ```
+     */
+    generateText<TOOLS extends Record<string, Tool> = Record<string, Tool>>(options: Omit<LLMClientStreamTextOptions<TOOLS>, "observers" | "experimental_output">, logger?: import("../../util/logger.js").Logger, tracer?: LLMObsTracer): Promise<string>;
+    /**
+     * 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.
+     */
+    private drainTextChunks;
+    /**
+     * 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.
+     */
+    private drainObjectStream;
+    /**
+     * 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" },
+     * });
+     * ```
+     */
+    generateObject<TOOLS extends Record<string, Tool> = Record<string, Tool>, OUTPUT = unknown>(options: LLMClientGenerateObjectOptions<TOOLS, OUTPUT>, logger?: import("../../util/logger.js").Logger, tracer?: LLMObsTracer): Promise<OUTPUT>;
 }
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/ai-service/llm/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/ai-service/llm/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/ai-service/llm/client.ts"],"names":[],"mappings":"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"}