@warmdrift/kgauto-compiler 2.0.0-alpha.32 → 2.0.0-alpha.34

package/dist/{ir-De2AQtlr.d.mts → ir-BAAHLfFL.d.mts}

@@ -564,6 +564,86 @@ interface CompileResult {
          * treat as 'parallel' equivalent for back-compat.
          */
         toolOrchestration?: 'parallel' | 'sequential' | 'either';
+        /**
+         * alpha.33. Zero-based index into the resolved (post-compression) history
+         * array at which Anthropic prompt-cache marker should land — i.e., the
+         * last message that belongs to the stable cacheable prefix. Consumers
+         * using AI-SDK's `streamText({ messages: convertToModelMessages(...) })`
+         * lose the per-message `providerOptions.anthropic.cacheControl` markers
+         * the compiler emits on `result.request.messages`, because
+         * `convertToModelMessages` reads raw input not the lowered output.
+         * This index gives the consumer a single deterministic position to
+         * attach `cacheControl: { type: 'ephemeral' }` after their own conversion.
+         *
+         * Computation:
+         *   - `historyCachePolicy.strategy === 'all-but-latest'`: history.length - 1
+         *     (or undefined if history is empty)
+         *   - `historyCachePolicy.strategy === 'fixed-suffix'` with `suffix: N`:
+         *     history.length - 1 - N (undefined if N exceeds history length)
+         *   - `historyCachePolicy.strategy === 'none'` or omitted: undefined
+         *
+         * The companion helper `attachCacheControlToStreamTextInput()` reads
+         * this field + the consumer's converted messages to perform the per-
+         * attempt mutation correctly. Filed by IC + tt-intel cross-consumer
+         * pattern 2026-05-20 (`streamText-cache-marker-propagation-gap`).
+         */
+        historyCacheMarkIndex?: number;
+        /**
+         * alpha.33. Zero-based index into the structured `systemMessages` array
+         * (see top-level `systemMessages` field) at which the cacheable system
+         * prefix ends. Useful when the consumer is building a multi-block
+         * system parameter for Anthropic streamText — they can attach
+         * `providerOptions.anthropic.cacheControl` to `systemMessages[index]`.
+         *
+         * Undefined when no section had `cacheable: true` OR `systemMessages` is
+         * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
+         */
+        systemCacheMarkIndex?: number;
+    };
+    /**
+     * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
+     * consumers. When the consumer's lowered request has cacheable section
+     * markers, the flat `system: string` form loses the marker assignment
+     * (every `streamText({ system: '<string>' })` call silently strips
+     * providerOptions). Pass `systemMessages` instead to `streamText({
+     * system: result.systemMessages })` so the cacheable prefix is structurally
+     * preserved.
+     *
+     * Each entry is a `SystemModelMessage`-shaped object:
+     *   { role: 'system', content: string, providerOptions?: { anthropic?:
+     *     { cacheControl: { type: 'ephemeral' } } } }
+     *
+     * Provider-agnostic on emit: only Anthropic actually consumes the
+     * cacheControl block; Gemini / OpenAI / DeepSeek receive the same
+     * shape but ignore the marker (matching their implicit-caching semantics).
+     *
+     * Empty array when the IR carried zero sections (rare; usually means the
+     * compiler dropped everything for the chosen intent). Consumers can fall
+     * back to `result.systemMessages.length === 0 ? '' : result.systemMessages`
+     * or use the helper `attachCacheControlToStreamTextInput()` which handles
+     * both shapes.
+     */
+    systemMessages: SystemModelMessage[];
+}
+/**
+ * alpha.33. AI-SDK-compatible system-message shape carried on
+ * `CompileResult.systemMessages`. Matches the AI-SDK `streamText({ system })`
+ * structured form — consumers can pass these directly without conversion.
+ *
+ * The `providerOptions` field is set ONLY for entries that came from a
+ * section with `cacheable: true` AND the chosen provider is Anthropic AND
+ * the compiler computed a non-zero `cacheableTokens`. Other providers see
+ * `providerOptions: undefined` (or omitted entirely).
+ */
+interface SystemModelMessage {
+    role: 'system';
+    content: string;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl: {
+                type: 'ephemeral';
+            };
+        };
     };
 }
 /**
@@ -653,6 +733,43 @@ interface CallOptions {
      * for hermetic test runs.
      */
     noAutoFilter?: boolean;
+    /**
+     * alpha.34. When provided AND the chosen provider supports streaming
+     * (`profile.streaming === true`) AND `noStream` is not set, kgauto
+     * enables provider-native SSE streaming at the wire layer and invokes
+     * `onChunk(delta)` once per provider stream event. `delta` is the text
+     * since the previous `onChunk` call (NOT cumulative) — provider
+     * stream-shape headache normalized in kgauto's lowering layer.
+     *
+     * `CallResult.response.text` is still populated with the full assembled
+     * response — kgauto buffers internally regardless of the callback.
+     * Consumers can use either the streaming side-effect OR the final
+     * `response.text`, doesn't matter.
+     *
+     * Tool calls + finish reason + usage are collected from stream events
+     * and returned in the final `CallResult` exactly as the non-streaming
+     * path would shape them. Brain telemetry latency = time-to-stream-end.
+     *
+     * Chain-walk semantics: if the streaming target fails mid-stream
+     * (network error, retryable provider error), kgauto walks to the next
+     * fallback target and restarts streaming from its first chunk —
+     * `onChunk` fires fresh from the new target. Consumer detects via the
+     * post-call `CallResult.fellOverFrom`. To opt out of fallback for
+     * streaming, set `noFallback: true` alongside `onChunk`.
+     *
+     * Filed by playbacksam s42 (2026-05-22) as `streaming-output-callback-
+     * on-callresult` for ComposeDrawer SSE; perceived-latency UX win
+     * during 10-30s draft assembly.
+     */
+    onChunk?: (chunk: string) => void;
+    /**
+     * alpha.34. Explicit opt-out of streaming even when `onChunk` is
+     * provided. Default: false (streaming enabled when `onChunk` is set).
+     * Use when the consumer wants to pass `onChunk` conditionally without
+     * branching the call site (e.g., capture chunks for instrumentation
+     * without engaging streaming wire format).
+     */
+    noStream?: boolean;
 }
 interface CallAttempt {
     model: string;
@@ -1028,4 +1145,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SectionRewrite as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type SectionKind as u, type ToolDefinition as v };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainWithGrounding as o, type Constraints as p, type MutationApplied as q, type NormalizedTokens as r, type OutcomeKind as s, type PerAxisMetricsByModel as t, type PromptSection as u, type SectionKind as v, type ToolDefinition as w };

package/dist/{ir-BIAT9gJk.d.ts → ir-B_ygNURd.d.ts}

@@ -564,6 +564,86 @@ interface CompileResult {
          * treat as 'parallel' equivalent for back-compat.
          */
         toolOrchestration?: 'parallel' | 'sequential' | 'either';
+        /**
+         * alpha.33. Zero-based index into the resolved (post-compression) history
+         * array at which Anthropic prompt-cache marker should land — i.e., the
+         * last message that belongs to the stable cacheable prefix. Consumers
+         * using AI-SDK's `streamText({ messages: convertToModelMessages(...) })`
+         * lose the per-message `providerOptions.anthropic.cacheControl` markers
+         * the compiler emits on `result.request.messages`, because
+         * `convertToModelMessages` reads raw input not the lowered output.
+         * This index gives the consumer a single deterministic position to
+         * attach `cacheControl: { type: 'ephemeral' }` after their own conversion.
+         *
+         * Computation:
+         *   - `historyCachePolicy.strategy === 'all-but-latest'`: history.length - 1
+         *     (or undefined if history is empty)
+         *   - `historyCachePolicy.strategy === 'fixed-suffix'` with `suffix: N`:
+         *     history.length - 1 - N (undefined if N exceeds history length)
+         *   - `historyCachePolicy.strategy === 'none'` or omitted: undefined
+         *
+         * The companion helper `attachCacheControlToStreamTextInput()` reads
+         * this field + the consumer's converted messages to perform the per-
+         * attempt mutation correctly. Filed by IC + tt-intel cross-consumer
+         * pattern 2026-05-20 (`streamText-cache-marker-propagation-gap`).
+         */
+        historyCacheMarkIndex?: number;
+        /**
+         * alpha.33. Zero-based index into the structured `systemMessages` array
+         * (see top-level `systemMessages` field) at which the cacheable system
+         * prefix ends. Useful when the consumer is building a multi-block
+         * system parameter for Anthropic streamText — they can attach
+         * `providerOptions.anthropic.cacheControl` to `systemMessages[index]`.
+         *
+         * Undefined when no section had `cacheable: true` OR `systemMessages` is
+         * empty. Matches `historyCacheMarkIndex` semantics on the history axis.
+         */
+        systemCacheMarkIndex?: number;
+    };
+    /**
+     * alpha.33. Structured `system` for AI-SDK `streamText({ system })`
+     * consumers. When the consumer's lowered request has cacheable section
+     * markers, the flat `system: string` form loses the marker assignment
+     * (every `streamText({ system: '<string>' })` call silently strips
+     * providerOptions). Pass `systemMessages` instead to `streamText({
+     * system: result.systemMessages })` so the cacheable prefix is structurally
+     * preserved.
+     *
+     * Each entry is a `SystemModelMessage`-shaped object:
+     *   { role: 'system', content: string, providerOptions?: { anthropic?:
+     *     { cacheControl: { type: 'ephemeral' } } } }
+     *
+     * Provider-agnostic on emit: only Anthropic actually consumes the
+     * cacheControl block; Gemini / OpenAI / DeepSeek receive the same
+     * shape but ignore the marker (matching their implicit-caching semantics).
+     *
+     * Empty array when the IR carried zero sections (rare; usually means the
+     * compiler dropped everything for the chosen intent). Consumers can fall
+     * back to `result.systemMessages.length === 0 ? '' : result.systemMessages`
+     * or use the helper `attachCacheControlToStreamTextInput()` which handles
+     * both shapes.
+     */
+    systemMessages: SystemModelMessage[];
+}
+/**
+ * alpha.33. AI-SDK-compatible system-message shape carried on
+ * `CompileResult.systemMessages`. Matches the AI-SDK `streamText({ system })`
+ * structured form — consumers can pass these directly without conversion.
+ *
+ * The `providerOptions` field is set ONLY for entries that came from a
+ * section with `cacheable: true` AND the chosen provider is Anthropic AND
+ * the compiler computed a non-zero `cacheableTokens`. Other providers see
+ * `providerOptions: undefined` (or omitted entirely).
+ */
+interface SystemModelMessage {
+    role: 'system';
+    content: string;
+    providerOptions?: {
+        anthropic?: {
+            cacheControl: {
+                type: 'ephemeral';
+            };
+        };
     };
 }
 /**
@@ -653,6 +733,43 @@ interface CallOptions {
      * for hermetic test runs.
      */
     noAutoFilter?: boolean;
+    /**
+     * alpha.34. When provided AND the chosen provider supports streaming
+     * (`profile.streaming === true`) AND `noStream` is not set, kgauto
+     * enables provider-native SSE streaming at the wire layer and invokes
+     * `onChunk(delta)` once per provider stream event. `delta` is the text
+     * since the previous `onChunk` call (NOT cumulative) — provider
+     * stream-shape headache normalized in kgauto's lowering layer.
+     *
+     * `CallResult.response.text` is still populated with the full assembled
+     * response — kgauto buffers internally regardless of the callback.
+     * Consumers can use either the streaming side-effect OR the final
+     * `response.text`, doesn't matter.
+     *
+     * Tool calls + finish reason + usage are collected from stream events
+     * and returned in the final `CallResult` exactly as the non-streaming
+     * path would shape them. Brain telemetry latency = time-to-stream-end.
+     *
+     * Chain-walk semantics: if the streaming target fails mid-stream
+     * (network error, retryable provider error), kgauto walks to the next
+     * fallback target and restarts streaming from its first chunk —
+     * `onChunk` fires fresh from the new target. Consumer detects via the
+     * post-call `CallResult.fellOverFrom`. To opt out of fallback for
+     * streaming, set `noFallback: true` alongside `onChunk`.
+     *
+     * Filed by playbacksam s42 (2026-05-22) as `streaming-output-callback-
+     * on-callresult` for ComposeDrawer SSE; perceived-latency UX win
+     * during 10-30s draft assembly.
+     */
+    onChunk?: (chunk: string) => void;
+    /**
+     * alpha.34. Explicit opt-out of streaming even when `onChunk` is
+     * provided. Default: false (streaming enabled when `onChunk` is set).
+     * Use when the consumer wants to pass `onChunk` conditionally without
+     * branching the call site (e.g., capture chunks for instrumentation
+     * without engaging streaming wire format).
+     */
+    noStream?: boolean;
 }
 interface CallAttempt {
     model: string;
@@ -1028,4 +1145,4 @@ interface PerAxisMetrics {
 /** Per-axis metrics keyed by model — used for chain-comparison views. */
 type PerAxisMetricsByModel = Record<string, PerAxisMetrics>;
 
-export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SectionRewrite as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type RecordOutcomeInput as e, type OracleScore as f, type CompileResult as g, type Adapter as h, type PerAxisMetrics as i, type Provider as j, type ChainEntry as k, type CallAttempt as l, CallError as m, type ChainWithGrounding as n, type Constraints as o, type MutationApplied as p, type NormalizedTokens as q, type OutcomeKind as r, type PerAxisMetricsByModel as s, type PromptSection as t, type SectionKind as u, type ToolDefinition as v };
+export { type ApiKeys as A, type BestPracticeAdvisory as B, type CompilePolicy as C, type FallbackReason as F, type Grounding as G, type HistoryCachePolicy as H, type IntentDeclaration as I, type Message as M, type NormalizedResponse as N, type OutcomeResult as O, type ProviderOverrides as P, type RecordInput as R, type SystemModelMessage as S, type ToolCall as T, type CompiledRequest as a, type PromptIR as b, type CallOptions as c, type CallResult as d, type CompileResult as e, type SectionRewrite as f, type RecordOutcomeInput as g, type OracleScore as h, type Adapter as i, type PerAxisMetrics as j, type Provider as k, type ChainEntry as l, type CallAttempt as m, CallError as n, type ChainWithGrounding as o, type Constraints as p, type MutationApplied as q, type NormalizedTokens as r, type OutcomeKind as s, type PerAxisMetricsByModel as t, type PromptSection as u, type SectionKind as v, type ToolDefinition as w };

package/dist/profiles.d.mts

@@ -1,4 +1,4 @@
-import { j as Provider } from './ir-De2AQtlr.mjs';
+import { k as Provider } from './ir-BAAHLfFL.mjs';
 import { IntentArchetypeName } from './dialect.mjs';
 
 /**

package/dist/profiles.d.ts

@@ -1,4 +1,4 @@
-import { j as Provider } from './ir-BIAT9gJk.js';
+import { k as Provider } from './ir-B_ygNURd.js';
 import { IntentArchetypeName } from './dialect.js';
 
 /**

package/dist/{types-BjrIFPGe.d.mts → types-BoqPXoUb.d.mts}

@@ -1,4 +1,4 @@
-import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-De2AQtlr.mjs';
+import { q as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-BAAHLfFL.mjs';
 
 /**
  * Glass-Box observability types (alpha.17).

package/dist/{types-D_JAhCv4.d.ts → types-CXyKj6-K.d.ts}

@@ -1,4 +1,4 @@
-import { p as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, l as CallAttempt } from './ir-BIAT9gJk.js';
+import { q as MutationApplied, B as BestPracticeAdvisory, F as FallbackReason, m as CallAttempt } from './ir-B_ygNURd.js';
 
 /**
  * Glass-Box observability types (alpha.17).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@warmdrift/kgauto-compiler",
-  "version": "2.0.0-alpha.32",
+  "version": "2.0.0-alpha.34",
   "description": "Prompt compiler + central learning brain for multi-model AI apps. Swap models without rewriting prompts.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",