opencode-effect-enforcer 0.2.8 → 0.4.0

package/skills/effect-ai-language-model/SKILL.md

@@ -7,16 +7,23 @@ description: Master the Effect AI LanguageModel service for text generation, str
 
 Pattern guide for working with the LanguageModel service from Effect AI for type-safe LLM interactions with Effect's functional patterns.
 
+Baseline: `effect@4.0.0`. Inspect that tag in the Effect source reference, not
+unreleased main. Keep Effect-family packages on the same version. `effect/ai`
+APIs carry `@stability unstable` and may change incompatibly in minor releases.
+
+For System One classification, rating, and probability calls through
+`DecisionModel`, use `effect-ai-decision-model`.
+
 ## Import Patterns
 
 **CRITICAL**: Always use namespace imports:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
-import * as Toolkit from 'effect/unstable/ai/Toolkit';
-import * as Tool from 'effect/unstable/ai/Tool';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
+import * as Toolkit from 'effect/ai/Toolkit';
+import * as Tool from 'effect/ai/Tool';
 import * as Effect from 'effect/Effect';
 import * as Stream from 'effect/Stream';
 import * as Schema from 'effect/Schema';
@@ -56,7 +63,7 @@ LanguageModel ∈ R → Effect.gen(function*() {
 Basic text generation with optional tool calling:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Effect from 'effect/Effect';
 
 // Simple text generation
@@ -104,6 +111,12 @@ For `Schema.NumberFromString`, manual calls contain `{ count: '3' }`.
 
 Pass those encoded params directly to `toolkit.handle(name, params, toolCallId)` when resolving manually. `Toolkit.handle` now accepts `Tool.ParametersEncoded<T>` and performs the decode before the handler receives `Tool.Parameters<T>`.
 
+Provide `Tool.HandlerServices<T>` to both the outer `handle` Effect and the
+returned Stream; parameter decoding can need services before streaming starts.
+The outer Effect can fail with `AiError`, and the Stream can fail with
+`Tool.HandlerError<T> | AiError`, including in `failureMode: 'return'` when
+result encoding fails.
+
 ### Response Accessors
 
 ```typescript
@@ -129,7 +142,7 @@ When converting `response.content` back into history, `Prompt.fromResponseParts`
 Force schema-validated output from the model:
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Schema from 'effect/Schema';
 import * as Effect from 'effect/Effect';
 
@@ -178,8 +191,9 @@ const extractEvent = LanguageModel.generateObject({
 
 Real-time streaming text generation:
 
+<!-- typecheck -->
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Stream from 'effect/Stream';
 import * as Effect from 'effect/Effect';
 import * as Console from 'effect/Console';
@@ -196,7 +210,7 @@ const program = streamStory.pipe(
 			return Console.log(part.delta);
 		}
 		if (part.type === 'tool-params-delta') {
-			return Console.log('Tool params:', part.paramsDelta);
+			return Console.log('Tool params:', part.delta);
 		}
 		return Effect.void;
 	})
@@ -214,7 +228,7 @@ Common StreamPart shapes include (non-exhaustive):
   | { type: "reasoning-delta", id, delta }
   | { type: "reasoning-end", id }
   | { type: "tool-params-start", id, name }
-  | { type: "tool-params-delta", id, paramsDelta }
+  | { type: "tool-params-delta", id, delta }
   | { type: "tool-params-end", id }
   | { type: "tool-call", id, name, params }
   | { type: "tool-result", id, name, result, isFailure, preliminary? }
@@ -289,7 +303,7 @@ toolChoice: {
 ## Error Handling
 
 ```typescript
-import * as AiError from 'effect/unstable/ai/AiError';
+import * as AiError from 'effect/ai/AiError';
 
 const robust = LanguageModel.generateText({
 	prompt: 'Analyze this...'
@@ -311,10 +325,22 @@ remain explicit and provider/validation failures use `AiError`. Classification
 requires at least two labels, rating requires at least two distinct ordered
 levels, and a definition requires at least one decision.
 
+`Decision.probability({ instructions })` estimates the probability of `true`.
+Its `criteria` is optional; when supplied it must describe both `false` and
+`true`. Guard `decision.criteria` before reading outcome descriptions.
+
+Custom adapters can set `DecisionModel.make({ decide, probabilityPrecision })`
+to accept rounding drift in classification/rating distributions. At precision
+`p`, the allowed sum drift is half a unit of the last decimal place per label
+(plus the core numerical tolerance); accepted drift is rescaled to sum to one.
+Zero sums, invalid probabilities, and larger drift still fail with
+`InvalidOutputError`. Omit the option for strict sum validation. OpenRouter and
+TypeSafe adapters use precision `2`.
+
 <!-- typecheck -->
 ```ts
 import * as Schema from 'effect/Schema';
-import { Decision, DecisionModel } from 'effect/unstable/ai';
+import { Decision, DecisionModel } from 'effect/ai';
 
 class Ticket extends Schema.Class<Ticket>('Ticket')({ body: Schema.String }) {}
 const triage = Decision.make({
@@ -323,7 +349,8 @@ const triage = Decision.make({
 		team: Decision.classify({
 			instructions: 'Choose the team responsible for this request',
 			criteria: { billing: 'Payments and invoices', support: 'Product support' }
-		})
+		}),
+		urgent: Decision.probability({ instructions: 'The ticket needs immediate attention' })
 	}
 });
 const result = DecisionModel.decide(triage, { input: new Ticket({ body: 'Invoice question' }) });
@@ -332,7 +359,7 @@ const result = DecisionModel.decide(triage, { input: new Ticket({ body: 'Invoice
 ## Type Extraction Utilities
 
 ```typescript
-import type * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import type * as LanguageModel from 'effect/ai/LanguageModel';
 
 // Extract error types from options
 type MyError = LanguageModel.ExtractError<typeof options>;
@@ -360,9 +387,14 @@ make :: ConstructorParams → Effect Service
 
 When implementing a custom LanguageModel provider, return encoded parts: `Array<Response.PartEncoded>` for `generateText` and `Stream<Response.StreamPartEncoded>` for `streamText`. If you emit `response-metadata`, encode timestamps as ISO strings. Providers that support provider-side conversations should honor `ProviderOptions.previousResponseId` and `ProviderOptions.incrementalPrompt`; providers that cannot should intentionally ignore them.
 
+`ProviderOptions.incrementalFallback` is `true` when the core retries a rejected
+incremental request with the full prompt. The fallback clears
+`previousResponseId` and `incrementalPrompt`; use that signal to reset adapter
+turn state without unnecessarily closing a healthy connection.
+
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Response from 'effect/unstable/ai/Response';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Response from 'effect/ai/Response';
 
 const makeCustomProvider = Effect.gen(function* () {
 	const service = yield* LanguageModel.make({
@@ -655,7 +687,7 @@ const generated = LanguageModel.generateText({ prompt: '...' }).pipe(
 Inside an effect that runs with a language model provider, you can retrieve the current provider name:
 
 ```typescript
-import * as Model from 'effect/unstable/ai/Model';
+import * as Model from 'effect/ai/Model';
 
 const program = Effect.gen(function* () {
 	const providerName = yield* Model.ProviderName;
@@ -672,7 +704,7 @@ const program = Effect.gen(function* () {
 
 ## References
 
-- Source: `packages/effect/src/unstable/ai/LanguageModel.ts`
-- Chat integration: `packages/effect/src/unstable/ai/Chat.ts`
-- Response types: `effect/unstable/ai/Response`
-- Tool system: `effect/unstable/ai/Tool`, `effect/unstable/ai/Toolkit`
+- Source: `packages/effect/src/ai/LanguageModel.ts`
+- Chat integration: `packages/effect/src/ai/Chat.ts`
+- Response types: `effect/ai/Response`
+- Tool system: `effect/ai/Tool`, `effect/ai/Toolkit`

package/skills/effect-ai-prompt/SKILL.md

@@ -7,13 +7,17 @@ description: Build prompts for Effect AI using messages, parts, and composition
 
 Master the Effect AI Prompt API for building type-safe conversations with language models.
 
+Baseline: `effect@4.0.0`; inspect that tag in the Effect source reference.
+`effect/ai` APIs remain `@stability unstable` and can break in minor releases.
+Keep provider packages on the same version as `effect`.
+
 ## Import Patterns
 
 **CRITICAL**: Always use namespace imports:
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
 import { pipe } from 'effect';
 ```
 
@@ -54,12 +58,13 @@ The Effect v4 module also exports runtime schemas for every part and each role-s
 
 ## Message Types
 
-Each message has `role` and `content`. Content is an array of `Part` objects.
+Each message has `role` and `content`. System content is a string; other roles
+contain arrays of the parts allowed for that role.
 
 ### System Messages
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Prompt from 'effect/ai/Prompt';
 
 // String content only
 const system = Prompt.makeMessage('system', {
@@ -368,7 +373,7 @@ const appended = pipe(prompt, Prompt.appendSystem(' Be concise.'));
 ### Convert AI Response to Prompt
 
 ```typescript
-import * as Response from 'effect/unstable/ai/Response';
+import * as Response from 'effect/ai/Response';
 
 const responseParts: ReadonlyArray<Response.AnyPart> = [
 	Response.makePart('text-start', { id: 'text_1' }),
@@ -400,7 +405,13 @@ const responseParts: ReadonlyArray<Response.AnyPart> = [
 const historyPrompt = Prompt.fromResponseParts(responseParts);
 ```
 
-`Prompt.fromResponseParts` folds streaming text/reasoning only when the matching start/delta/end parts are present in the same input, places tool calls and approval requests in assistant messages, and skips preliminary tool results. For final tool results it always uses `encodedResult`: framework-executed results (`providerExecuted: false`) become tool messages, while provider-executed results (`providerExecuted: true`) remain in the assistant message with that flag preserved.
+`Prompt.fromResponseParts` folds streaming text/reasoning by matching IDs and
+emits the accumulated part on its end marker. Pass complete start/delta/end
+sequences rather than isolated deltas. It places tool calls and approval requests
+in assistant messages and skips preliminary tool results. For final tool results
+it always uses `encodedResult`: framework-executed results
+(`providerExecuted: false`) become tool messages, while provider-executed results
+(`providerExecuted: true`) remain in the assistant message with that flag preserved.
 
 This distinction matters for hosted tools such as provider web search or code execution. Moving their results into a tool message changes the conversation shape expected by the provider.
 
@@ -426,7 +437,7 @@ This keeps prompt assembly inside the Effect graph instead of forcing Promise is
 ```typescript
 import { Effect } from 'effect';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 
 const chat = Effect.gen(function* () {
 	const history = yield* SubscriptionRef.make(Prompt.empty);
@@ -456,7 +467,7 @@ const chat = Effect.gen(function* () {
 ### Generate Text
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect } from 'effect';
 
 const program = Effect.gen(function* () {
@@ -474,7 +485,7 @@ const program = Effect.gen(function* () {
 ### Stream Text
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect, Stream } from 'effect';
 
 const program = Effect.gen(function* () {
@@ -493,7 +504,7 @@ const program = Effect.gen(function* () {
 ### Generate Object
 
 ```typescript
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import { Effect, Schema } from 'effect';
 
 const Contact = Schema.Struct({
@@ -525,8 +536,8 @@ may reject it. Provider config uses snake_case; Prompt metadata uses camelCase.
 ```typescript
 import { OpenAiLanguageModel } from '@effect/ai-openai';
 import { Effect } from 'effect';
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
 
 const program = LanguageModel.generateText({
 	prompt: Prompt.make([
@@ -552,7 +563,7 @@ OpenAI client layer at the runtime boundary (see `effect-ai-provider`).
 
 ```typescript
 // Augment options interfaces via module augmentation
-declare module 'effect/unstable/ai/Prompt' {
+declare module 'effect/ai/Prompt' {
 	interface TextPartOptions {
 		readonly anthropic?: {
 			readonly cache_control?: {
@@ -703,7 +714,7 @@ const toolInteraction = Prompt.make([
 ## Type Guards
 
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
+import * as Prompt from 'effect/ai/Prompt';
 
 declare const value: unknown;
 

package/skills/effect-ai-provider/SKILL.md

@@ -7,6 +7,14 @@ description: Configure and compose AI provider layers using @effect/ai packages.
 
 Configure AI provider layers for language model integration using Effect's AI ecosystem.
 
+Baseline: `effect@4.0.0`; inspect the matching tag in the Effect source reference.
+Keep `effect` and every `@effect/*` package on the same version. Core AI APIs and
+provider clients, models, and generated schemas carry `@stability unstable`:
+minor releases may include breaking changes, even with `effect/ai` import paths.
+
+For TypeSafe/Jev and OpenRouter **decision-model** layers, use
+`effect-ai-decision-model`; its provider contracts differ from language models.
+
 ## When to Use This Skill
 
 Use this skill when:
@@ -34,7 +42,7 @@ import {
 	Stream
 } from 'effect';
 
-// From "effect/unstable/ai" — namespace imports
+// From "effect/ai" — namespace imports
 import {
 	AiError,
 	Chat,
@@ -43,13 +51,13 @@ import {
 	Prompt,
 	Tool,
 	Toolkit
-} from 'effect/unstable/ai';
+} from 'effect/ai';
 // Or individually:
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
-import * as Chat from 'effect/unstable/ai/Chat';
-import * as Model from 'effect/unstable/ai/Model';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as AiError from 'effect/unstable/ai/AiError';
+import * as LanguageModel from 'effect/ai/LanguageModel';
+import * as Chat from 'effect/ai/Chat';
+import * as Model from 'effect/ai/Model';
+import * as Prompt from 'effect/ai/Prompt';
+import * as AiError from 'effect/ai/AiError';
 
 // Anthropic
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
@@ -70,7 +78,7 @@ import {
 } from '@effect/ai-openrouter';
 
 // HTTP client (required by all providers)
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 ```
 
 ## Provider Layer Pattern
@@ -96,7 +104,7 @@ ProviderClient.layerConfig :: { apiKey } → Layer Client HttpClient
 ```typescript
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 // Client layer (reusable across models)
 const AnthropicClientLayer = AnthropicClient.layerConfig({
@@ -115,6 +123,12 @@ const AnthropicLive = AnthropicLanguageModel.layer({
 
 Anthropic capability detection preserves the lower output limits and structured-output support of known legacy Claude models. Unknown and newly released model identifiers default to modern capabilities: native structured outputs and `128_000` output tokens. Override capability detection with `structuredOutputs: false` (or `true`) when a model or compatible endpoint differs from that default; set `max_tokens` separately when the provider's output limit differs.
 
+Anthropic-compatible gateways may omit `usage.inference_geo`. Malformed gateway
+4xx error bodies are classified by HTTP status (including 429 retry delays), not
+as `InvalidOutputError`. Direct `client.betaMessagesPost` calls expose
+`HttpClientError` for those responses; the language-model adapter maps them to
+`AiError` reasons.
+
 ```typescript
 const compatibleClaude = AnthropicLanguageModel.model('future-claude-model', {
 	structuredOutputs: false,
@@ -127,7 +141,7 @@ const compatibleClaude = AnthropicLanguageModel.model('future-claude-model', {
 ```typescript
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 const OpenAiClientLayer = OpenAiClient.layerConfig({
 	apiKey: Config.Redacted('OPENAI_API_KEY')
@@ -151,6 +165,10 @@ Public OpenAI modules:
 
 `OpenAiSchema.ResponseStreamEvent` accepts both flat OpenAI error events and compatible-provider events with details nested under `error`, normalizing both to the same decoded error event shape.
 
+For WebSocket turns, `previous_response_not_found` triggers a retry with the full
+prompt. An open socket is retained; custom adapters can inspect
+`ProviderOptions.incrementalFallback` to recognize the full-prompt retry.
+
 ```typescript
 const client = yield* OpenAiClient.OpenAiClient;
 const [body] = yield* client.createResponse({
@@ -176,14 +194,21 @@ const NativeTools = Toolkit.make(
 
 Available hosted/provider tools include `WebSearch`, `CodeInterpreter`, `FileSearch`, `ImageGeneration`, and `Mcp` (`customName: "OpenAiMcp"`). MCP tool approval requests/results use this canonical `OpenAiMcp` name and the normal Effect AI approval request/response parts. Handler-required local tools such as `Shell`, `LocalShell`, and `ApplyPatch` run in your environment; provide handlers only behind explicit sandboxing, authorization, and audit policy.
 
+Web-search calls may omit `action`. Narrow that optional field before reading
+action details; incomplete calls are preserved as failed tool results.
+
 ## OpenAI-Compatible Providers
 
-Use `apiUrl` with `@effect/ai-openai` for OpenAI-compatible APIs (Azure OpenAI, local models, etc.):
+Use `apiUrl` with `@effect/ai-openai` for APIs compatible with OpenAI Responses.
+For Chat Completions-compatible endpoints use `@effect/ai-openai-compat`
+(`OpenAiClient`, `OpenAiLanguageModel`), which preserves non-null text/tool
+argument fragments when other streamed delta fields are null. Both adapters
+preserve raw JSON Schema dynamic-tool arguments.
 
 ```typescript
 import { OpenAiClient, OpenAiConfig } from '@effect/ai-openai';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/unstable/http';
+import { FetchHttpClient, HttpClient, HttpClientRequest } from 'effect/http';
 
 const CompatibleClientLayer = OpenAiClient.layerConfig({
 	apiKey: Config.Redacted('OPENAI_COMPAT_API_KEY'),
@@ -208,7 +233,7 @@ import {
 	OpenRouterLanguageModel
 } from '@effect/ai-openrouter';
 import { Config, Layer } from 'effect';
-import { FetchHttpClient } from 'effect/unstable/http';
+import { FetchHttpClient } from 'effect/http';
 
 const OpenRouterClientLayer = OpenRouterClient.layerConfig({
 	apiKey: Config.Redacted('OPENROUTER_API_KEY')
@@ -226,13 +251,13 @@ const routerModel = OpenRouterLanguageModel.model('anthropic/claude-sonnet-4');
 import { AnthropicClient, AnthropicLanguageModel } from '@effect/ai-anthropic';
 import { OpenAiClient, OpenAiLanguageModel } from '@effect/ai-openai';
 import { Effect, ExecutionPlan, Layer } from 'effect';
-import { LanguageModel } from 'effect/unstable/ai';
+import { LanguageModel } from 'effect/ai';
 
 // Try cheaper model first, fall back to more expensive one
 const DraftPlan = ExecutionPlan.make(
 	{
 		provide: OpenAiLanguageModel.model('gpt-5.2'),
-		attempts: 3 // retry up to 3 times before falling back
+		attempts: 3 // up to 3 total attempts before falling back
 	},
 	{
 		provide: AnthropicLanguageModel.model('claude-opus-4-6'),
@@ -278,7 +303,7 @@ Maintain conversation history with automatic context management:
 
 ```typescript
 import { Effect, Ref } from 'effect';
-import { Chat, Prompt } from 'effect/unstable/ai';
+import { Chat, Prompt } from 'effect/ai';
 
 // Create with system prompt
 const session =
@@ -361,7 +386,7 @@ OpenAI error classification distinguishes temporary rate limits from exhausted a
 Wrap provider layers with metadata. Takes 3 positional arguments: `(providerName, modelId, layer)`:
 
 ```typescript
-import { Model } from 'effect/unstable/ai';
+import { Model } from 'effect/ai';
 
 // This is what ProviderLanguageModel.model() calls internally:
 const Claude = Model.make(
@@ -437,7 +462,7 @@ Wrap `AiError` into domain-specific tagged errors:
 
 ```typescript
 import { Schema } from 'effect';
-import { AiError } from 'effect/unstable/ai';
+import { AiError } from 'effect/ai';
 
 export class MyAiError extends Schema.TaggedError<MyAiError>()(
 	'MyAiError',
@@ -459,7 +484,7 @@ export class MyAiError extends Schema.TaggedError<MyAiError>()(
 | ----------------------- | ------------- | ----------------------------------------------- |
 | `@effect/ai-anthropic`  | Anthropic     | Claude Opus 4, Claude Sonnet 4, etc.            |
 | `@effect/ai-openai`     | OpenAI        | GPT-5, GPT-4.1, o-series, etc.                  |
-| `@effect/ai-openai`     | OpenAI-Compat | Any OpenAI-compatible API via `apiUrl`          |
+| `@effect/ai-openai-compat` | OpenAI-Compat | Chat Completions-compatible APIs via `apiUrl` |
 | `@effect/ai-openrouter` | OpenRouter    | Multi-provider proxy (any model ID)             |
 
 **Note**: There are no `@effect/ai-google` or `@effect/ai-amazon-bedrock` packages. Use OpenRouter to access Google/Bedrock models.
@@ -488,8 +513,8 @@ import {
 	Model,
 	Prompt,
 	type Response
-} from 'effect/unstable/ai';
-import { FetchHttpClient } from 'effect/unstable/http';
+} from 'effect/ai';
+import { FetchHttpClient } from 'effect/http';
 
 // ---------------------------------------------------------------------------
 // Provider client layers
@@ -675,10 +700,16 @@ import { BedrockClient } from '@effect/ai-amazon-bedrock'; // Does NOT exist
 ## References
 
 Provider-neutral structured decisions use `Decision` / `DecisionModel` from
-`effect/unstable/ai`. `OpenRouterDecisionModel` targets OpenRouter's alpha Decisions
+`effect/ai`. `OpenRouterDecisionModel` targets OpenRouter's alpha Decisions
 API; `@effect/ai-typesafe` supplies a provider for TypeSafe System One. Custom
 OpenRouter client implementations include `createDecisions`.
 
+`OpenRouterDecisionModel` and the TypeSafe decision model configure
+`probabilityPrecision: 2`: rounded distributions such as `0.02 / 0.93 / 0.04`
+are accepted and rescaled. Custom `DecisionModel.make` adapters retain strict sum
+validation unless they opt in. `Decision.probability` allows omitted `criteria`;
+when present it must describe both boolean outcomes (see `effect-ai-language-model`).
+
 Use each branded service's same-name type (`LanguageModel.LanguageModel`,
 `EmbeddingModel.EmbeddingModel`, `Chat.Chat`) and its exported TypeId for custom
 implementations. Prefer provided constructors; do not hard-code marker strings.

package/skills/effect-ai-streaming/SKILL.md

@@ -5,6 +5,10 @@ description: Master Effect AI streaming response patterns including start/delta/
 
 # Effect AI Streaming
 
+Baseline: `effect@4.0.0`; inspect that tag in the Effect source reference.
+The `effect/ai` APIs remain `@stability unstable` despite their shorter import
+paths and may break in minor releases. Align provider package versions with `effect`.
+
 ## When to Use This Skill
 
 - Real-time streaming responses from language models
@@ -24,7 +28,7 @@ import * as Effect from 'effect/Effect';
 import * as Channel from 'effect/Channel';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
 import * as Match from 'effect/Match';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Response from 'effect/ai/Response';
 ```
 
 ## StreamPart Protocol
@@ -80,8 +84,8 @@ Accumulate stream parts incrementally using mutable state for efficiency:
 ```typescript
 import * as Stream from 'effect/Stream';
 import * as Effect from 'effect/Effect';
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
 import * as SubscriptionRef from 'effect/SubscriptionRef';
 
 const streamWithHistory = Stream.suspend(() => {
@@ -214,14 +218,20 @@ Why checkpoint-based merging:
 - `Prompt.fromResponseParts` routes framework-executed final results into a tool message, but keeps provider-executed final results in the assistant message. It preserves `providerExecuted` and uses `encodedResult` in both cases.
 - Tools requiring approval emit `tool-approval-request`. Append a matching `Prompt.toolApprovalResponsePart` in a tool message and call the model again; approved/denied responses are pre-resolved into final tool results before the next provider call.
 - In OpenAI-specific SSE code, unknown future events decode through `OpenAiSchema.ResponseStreamEvent` and are ignored by `OpenAiLanguageModel`; malformed known events still fail decoding.
+- OpenAI-compatible Chat Completions providers can send null delta fields. The
+  adapter preserves text and tool arguments from the remaining fields; custom
+  adapters should skip null fragments rather than discard the whole chunk.
+- Manual `Toolkit.handle` execution requires handler services on both the outer
+  Effect and its returned Stream. Even return-mode streams can fail with
+  `AiError` during result encoding; keep that error channel when composing streams.
 
 ## Complete Example
 
 <!-- typecheck -->
 ```typescript
-import * as Prompt from 'effect/unstable/ai/Prompt';
-import * as Response from 'effect/unstable/ai/Response';
-import * as LanguageModel from 'effect/unstable/ai/LanguageModel';
+import * as Prompt from 'effect/ai/Prompt';
+import * as Response from 'effect/ai/Response';
+import * as LanguageModel from 'effect/ai/LanguageModel';
 import * as Stream from 'effect/Stream';
 import * as Channel from 'effect/Channel';
 import * as Effect from 'effect/Effect';
@@ -327,16 +337,21 @@ Stream.mapArrayEffect(Effect.fnUntraced(function* (chunk) {
 ### Source Parts
 
 ```typescript
-{ type: "document-source", id: string, title?: string }
-{ type: "url-source", url: string, title?: string }
+{ type: "source", sourceType: "document", id: string, mediaType: string, title: string }
+{ type: "source", sourceType: "url", id: string, url: URL, title: string }
 ```
 
+The encoded URL source uses a string URL.
+
 ### Metadata Parts
 
 ```typescript
-{ type: "response-metadata", id: string, modelId: string, timestamp: Date }
+{ type: "response-metadata", id?: string, modelId?: string, timestamp?: DateTime.Utc }
 ```
 
+The encoded provider form uses an ISO string for `timestamp`; the decoded part
+uses `DateTime.Utc`.
+
 ### Error Parts
 
 ```typescript
@@ -383,9 +398,9 @@ StreamPart types:
 
 Key modules:
 
-- `effect/unstable/ai/Response` - Response part schemas and constructors
-- `effect/unstable/ai/Prompt` - Prompt construction and merging
-- `effect/Stream` - Stream combinators (`mapChunksEffect`, `runForEach`, `runDrain`)
+- `effect/ai/Response` - Response part schemas and constructors
+- `effect/ai/Prompt` - Prompt construction and merging
+- `effect/Stream` - Stream combinators (`mapArrayEffect`, `runForEach`, `runDrain`)
 - `effect/Channel` - Low-level resource management (`acquireUseRelease`)
 - `effect/SubscriptionRef` - Reactive shared state
 - `effect/Match` - Pattern matching (use `Match.when({ type: ... })` for stream parts)