@yolk-sdk/agent 0.1.0-canary.95 → 0.1.0-canary.97

package/README.md

@@ -1,57 +1,66 @@
 # @yolk-sdk/agent
 
-Domain-free agent protocol, loop, runtime, Effect-native client, compaction, tools, React, providers, OAuth, skillset, and voice primitives.
+Domain-free agent protocol, loop, runtime, Effect-native client, compaction, classifier models, tools, React, providers, OAuth, skillset, and voice primitives.
 
 Root export is intentionally empty. Import feature APIs from explicit subpaths.
 
 ## Install
 
 ```bash
-pnpm add @yolk-sdk/agent@canary effect@4.0.0-rc.115
+pnpm add @yolk-sdk/agent@canary effect@4.0.0
 ```
 
 Add `react` if you use `@yolk-sdk/agent/react` or `@yolk-sdk/agent/voice/react`.
 
+Running the experimental `@yolk-sdk/agent/providers/*/conformance` cases? Also add `@yolk-sdk/conformance@canary` (usually as a dev dependency); the cases run through `@yolk-sdk/conformance/runner`.
+
 Canary APIs are unstable. Keep all `@yolk-sdk/*` packages on the same version.
-Use the SDK's matching Effect version (`4.0.0-rc.115`) in host code.
+Use the SDK's matching Effect version (`4.0.0`) in host code.
 Published package metadata requires Node.js 22+.
 
 ## Subpaths
 
-| Subpath                                                | Purpose                                                        |
-| ------------------------------------------------------ | -------------------------------------------------------------- |
-| `@yolk-sdk/agent/protocol`                             | Wire messages, events, content, usage, tool schemas            |
-| `@yolk-sdk/agent/loop`                                 | Stateless LLM/tool loop                                        |
-| `@yolk-sdk/agent/loop/testing`                         | Faux provider and tool executor test helpers                   |
-| `@yolk-sdk/agent/runtime`                              | Transcript or append-backed runtime orchestration              |
-| `@yolk-sdk/agent/client`                               | HTTP/NDJSON transport, HITL resume, retry/error state helpers  |
-| `@yolk-sdk/agent/compaction`                           | Host-owned compaction budgets, checkpoints, formatting, retry  |
-| `@yolk-sdk/agent/tools`                                | Tool registry, typed inputs, interactions, subagents/questions |
-| `@yolk-sdk/agent/react`                                | Headless React chat hook, reducer, selectors, and render model |
-| `@yolk-sdk/agent/oauth`                                | Provider-neutral OAuth token and broker contracts              |
-| `@yolk-sdk/agent/providers/openai`                     | OpenAI/Codex OAuth and broker helpers                          |
-| `@yolk-sdk/agent/providers/openai/codex`               | OpenAI Codex request and auth helpers                          |
-| `@yolk-sdk/agent/providers/openai/codex-usage`         | Codex subscription-allowance snapshots                         |
-| `@yolk-sdk/agent/providers/openai/codex-provider`      | Codex LLM provider factory                                     |
-| `@yolk-sdk/agent/providers/openai/provider`            | OpenAI-compatible LLM provider factory                         |
-| `@yolk-sdk/agent/providers/openai/realtime`            | OpenAI Realtime session config and event codecs                |
-| `@yolk-sdk/agent/providers/openai/speech`              | OpenAI text-to-speech and transcription adapters               |
-| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider` | Vercel AI Gateway Chat Completions provider factory            |
-| `@yolk-sdk/agent/providers/opencode/go-provider`       | OpenCode Go Chat Completions, Messages, and Responses provider |
-| `@yolk-sdk/agent/providers/opencode/usage`             | OpenCode Go subscription-allowance snapshots                   |
-| `@yolk-sdk/agent/providers/anthropic`                  | Anthropic/Claude OAuth and broker helpers                      |
-| `@yolk-sdk/agent/providers/anthropic/claude`           | Claude request and auth helpers                                |
-| `@yolk-sdk/agent/providers/anthropic/usage`            | Claude subscription-allowance snapshots                        |
-| `@yolk-sdk/agent/providers/anthropic/claude-provider`  | Claude LLM provider factory                                    |
-| `@yolk-sdk/agent/providers/xai`                        | Grok subscription OAuth and token broker helpers               |
-| `@yolk-sdk/agent/providers/xai/grok`                   | Grok subscription request and auth helpers                     |
-| `@yolk-sdk/agent/providers/xai/grok-provider`          | Grok subscription LLM provider factory                         |
-| `@yolk-sdk/agent/providers/xai/usage`                  | Grok subscription-allowance snapshots                          |
-| `@yolk-sdk/agent/providers/subscription-usage`         | Shared allowance snapshot and safe error schemas               |
-| `@yolk-sdk/agent/skillset`                             | Portable skill and slash-command parsing/catalogs              |
-| `@yolk-sdk/agent/voice`                                | Voice protocol, controller, tool handler, projection, speech   |
-| `@yolk-sdk/agent/voice/browser`                        | Browser WebRTC voice transport                                 |
-| `@yolk-sdk/agent/voice/react`                          | Headless browser voice React hook                              |
+| Subpath                                                  | Purpose                                                                                       |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `@yolk-sdk/agent/protocol`                               | Wire messages, events, content, usage, tool schemas                                           |
+| `@yolk-sdk/agent/loop`                                   | Stateless LLM/tool loop                                                                       |
+| `@yolk-sdk/agent/loop/testing`                           | Faux provider and tool executor test helpers                                                  |
+| `@yolk-sdk/agent/runtime`                                | Transcript or append-backed runtime orchestration                                             |
+| `@yolk-sdk/agent/client`                                 | HTTP/NDJSON transport, HITL resume, retry/error state helpers                                 |
+| `@yolk-sdk/agent/compaction`                             | Host-owned compaction budgets, checkpoints, formatting, retry                                 |
+| `@yolk-sdk/agent/classification`                         | Classifier model contract: typed questions, answers, usage, errors                            |
+| `@yolk-sdk/agent/tools`                                  | Tool registry, typed inputs, interactions, subagents/questions                                |
+| `@yolk-sdk/agent/react`                                  | Headless React chat hook, reducer, selectors, and render model                                |
+| `@yolk-sdk/agent/oauth`                                  | Provider-neutral OAuth token and broker contracts                                             |
+| `@yolk-sdk/agent/providers/openai`                       | OpenAI/Codex OAuth and broker helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex`                 | OpenAI Codex request and auth helpers                                                         |
+| `@yolk-sdk/agent/providers/openai/codex-usage`           | Codex subscription-allowance snapshots                                                        |
+| `@yolk-sdk/agent/providers/openai/codex-provider`        | Codex LLM provider factory                                                                    |
+| `@yolk-sdk/agent/providers/openai/provider`              | OpenAI-compatible LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/openai/conformance`           | Synthetic OpenAI chat, Codex Responses, and Codex usage fixtures and conformance cases        |
+| `@yolk-sdk/agent/providers/openai/realtime`              | OpenAI Realtime session config and event codecs                                               |
+| `@yolk-sdk/agent/providers/openai/speech`                | OpenAI text-to-speech and transcription adapters                                              |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-provider`   | Vercel AI Gateway Chat Completions provider factory                                           |
+| `@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` | Vercel AI Gateway classifier (`POST /v1/evaluate`) layer                                      |
+| `@yolk-sdk/agent/providers/vercel/conformance`           | Verified Gateway chat fixtures, synthetic classifier fixtures, and conformance cases          |
+| `@yolk-sdk/agent/providers/opencode/go-provider`         | OpenCode Go Chat Completions, Messages, and Responses provider                                |
+| `@yolk-sdk/agent/providers/opencode/usage`               | OpenCode Go subscription-allowance snapshots                                                  |
+| `@yolk-sdk/agent/providers/opencode/conformance`         | Synthetic OpenCode Go (per protocol, commentary replay, usage) fixtures and conformance cases |
+| `@yolk-sdk/agent/providers/anthropic`                    | Anthropic/Claude OAuth and broker helpers                                                     |
+| `@yolk-sdk/agent/providers/anthropic/claude`             | Claude request and auth helpers                                                               |
+| `@yolk-sdk/agent/providers/anthropic/usage`              | Claude subscription-allowance snapshots                                                       |
+| `@yolk-sdk/agent/providers/anthropic/claude-provider`    | Claude LLM provider factory                                                                   |
+| `@yolk-sdk/agent/providers/anthropic/conformance`        | Synthetic Anthropic Messages and Claude usage fixtures and conformance cases                  |
+| `@yolk-sdk/agent/providers/xai`                          | Grok subscription OAuth and token broker helpers                                              |
+| `@yolk-sdk/agent/providers/xai/grok`                     | Grok subscription request and auth helpers                                                    |
+| `@yolk-sdk/agent/providers/xai/grok-provider`            | Grok subscription LLM provider factory                                                        |
+| `@yolk-sdk/agent/providers/xai/usage`                    | Grok subscription-allowance snapshots                                                         |
+| `@yolk-sdk/agent/providers/xai/conformance`              | Synthetic Grok Responses and Grok usage fixtures and conformance cases                        |
+| `@yolk-sdk/agent/providers/subscription-usage`           | Shared allowance snapshot and safe error schemas                                              |
+| `@yolk-sdk/agent/skillset`                               | Portable skill and slash-command parsing/catalogs                                             |
+| `@yolk-sdk/agent/voice`                                  | Voice protocol, controller, tool handler, projection, speech                                  |
+| `@yolk-sdk/agent/voice/browser`                          | Browser WebRTC voice transport                                                                |
+| `@yolk-sdk/agent/voice/react`                            | Headless browser voice React hook                                                             |
 
 ## Imports
 
@@ -88,7 +97,9 @@ import {
   modelVisibleToolError,
   modelVisibleToolErrorStructuredContent,
   makeQuestionToolModule,
-  resolveTools
+  omitNullOptionalToolArguments,
+  resolveTools,
+  withToolArgumentsErrorHint
 } from '@yolk-sdk/agent/tools'
 import {
   AgentChatAction,
@@ -212,7 +223,7 @@ Server-side configuration fragment (the host supplies credentials and model poli
 
 ```ts
 import { Layer, Redacted } from 'effect'
-import { FetchHttpClient } from 'effect/unstable/http'
+import { FetchHttpClient } from 'effect/http'
 import { makeOpenCodeGoProviderLayer } from '@yolk-sdk/agent/providers/opencode/go-provider'
 
 const GoLayer = makeOpenCodeGoProviderLayer({
@@ -240,7 +251,7 @@ Read Go subscription allowance separately from per-request token usage (server-s
 
 ```ts
 import { Effect, Redacted } from 'effect'
-import { FetchHttpClient } from 'effect/unstable/http'
+import { FetchHttpClient } from 'effect/http'
 import { fetchOpenCodeGoSubscriptionUsage } from '@yolk-sdk/agent/providers/opencode/usage'
 
 const usageEffect = fetchOpenCodeGoSubscriptionUsage(Redacted.make(hostOpenCodeGoApiKey), {
@@ -248,7 +259,7 @@ const usageEffect = fetchOpenCodeGoSubscriptionUsage(Redacted.make(hostOpenCodeG
 }).pipe(Effect.provide(FetchHttpClient.layer))
 ```
 
-The fixed API-key endpoint returns used percentages/reset instants for `five-hour`, `seven-day`, and
+The API-key endpoint (default `openCodeGoSubscriptionUsageUrl`) returns used percentages/reset instants for `five-hour`, `seven-day`, and
 `monthly` windows. Monthly resets follow the subscription's anniversary, not the first of the month;
 the adapter preserves the provider's timestamp. Missing/invalid percentages are omitted, not treated
 as zero. Treat snapshots as best-effort; hosts own polling, stale-data policy, persistence, and UI.
@@ -293,7 +304,8 @@ for unions, refinements, and tuples. The Claude adapter therefore projects tool
 provider-compatible object schema without `anyOf`, `oneOf`, `allOf`, or tuple-only `prefixItems`.
 When a constraint cannot be represented faithfully, the projection widens the model-facing schema
 rather than excluding a valid call. Tool execution remains safe because `makeTool` validates the
-returned arguments against the original Effect Schema before invoking the executor.
+returned arguments against the original Effect Schema (through its JSON codec) before invoking the
+executor.
 
 Before projection, `toAnthropicClaudeRequestBody` and the Claude provider decode `ToolDef.parameters`
 and `ToolCall.params` as `Schema.Json`. Non-JSON values fail as non-retryable `LLMError` with
@@ -317,7 +329,28 @@ remain opaque. Background wrapping preserves boolean `true`/`false` as the argum
 reference/resource restrictions still apply at activation. `makeTool` may add root `type: "object"`
 to typeless `anyOf`/`oneOf` unions whose members are all object schemas, as required by strict
 OpenAI-compatible upstreams; primitives, unknown, and already-typed roots are unchanged, and call
-validation still uses the original Effect Schema.
+validation still decodes through the original Effect Schema's JSON codec. Effect 4.0.0 exports
+`Schema.isPattern` to JSON Schema only for `u`-flag regexes (optionally with `d`, `g`, or `y`);
+add `u` to keep model-visible `pattern` hints.
+
+### Tool arguments: `null` and unknown keys
+
+Tool arguments are accepted exactly as advertised: unambiguous `null`s are normalized, and keys
+that would be silently lost are rejected. `ToolDef.parameters` describes the schema's canonical JSON codec, so `Schema.optional(X)` is
+advertised as `X | null`. `makeTool` (validate and execute), `makeInputTool`/`makeInteractionTool`
+call params, and the loop `question` decode model arguments with `Schema.toCodecJson(parameters)`:
+`null` on `Schema.optional(X)` decodes as absent and `withDecodingDefault` still applies,
+`Schema.optional(Schema.NullOr(X))` keeps `null`, and required non-nullable fields still reject it.
+`undefined`-valued keys from in-process callers count as absent.
+Non-finite numbers (the codec's `"NaN"`/`"Infinity"` strings) are validation errors. Objects are
+advertised closed (`additionalProperties: false`), so unknown keys at any depth are model-visible
+validation errors instead of being stripped (also through closed-input declarations whose JSON codec
+bypasses their own parser). Their error message names each unknown key and lists the allowed keys at that path; this includes
+a `null` on another union member's field.
+`resolveTools` also drops `null` where the advertised schema declares a property optional without
+admitting `null` (for example `Schema.optionalKey(X)`, the subagent `model`, or raw MCP schemas)
+before any registration sees the call; `omitNullOptionalToolArguments` (`@yolk-sdk/agent/tools`) exposes that step for hosts
+that dispatch registrations themselves. User-submitted input/interaction responses are unchanged.
 
 ### OpenAI Chat Completions, Responses, and extraBody
 
@@ -410,7 +443,7 @@ Effect `HttpClient`:
 
 ```ts
 import { Effect } from 'effect'
-import { FetchHttpClient } from 'effect/unstable/http'
+import { FetchHttpClient } from 'effect/http'
 import { fetchOpenAiCodexSubscriptionUsage } from '@yolk-sdk/agent/providers/openai/codex-usage'
 
 const snapshot = await fetchOpenAiCodexSubscriptionUsage(hostOAuthAccessToken).pipe(
@@ -430,7 +463,8 @@ version.
 Provider adapters return an immutable Effect `Chunk` of semantic window ids, percentages, and
 optional reset/duration fields; hosts own labels, polling, persistence, stale-data policy, alert
 thresholds, billing interpretation, and UI. Configure `requestTimeoutMs` at the server integration
-boundary. Endpoint origins stay fixed, and `FetchHttpClient.layer` is configured for manual
+boundary. Each fetcher defaults to its exported URL constant; the optional `url` override is only
+for a trusted proxy or local emulator, because the credential is sent to it. `FetchHttpClient.layer` is configured for manual
 redirects. A custom `HttpClient` must not follow redirects for these credential-bearing requests.
 
 Subscription allowance snapshots are separate from protocol `AgentUsage`, which accounts for tokens
@@ -748,6 +782,47 @@ handler, approval HITL, transcript projection, and one-shot TTS/STT contracts.
   overflow such as `{"n":1e999}` takes the same mapper-specific fallbacks. Approval identifiers,
   gates, deny, and execution schema validation are unchanged.
 
+## Classifier models
+
+`@yolk-sdk/agent/classification` is a provider-neutral contract for classifier models such as
+TypeSafe's Jev: one `state` (a string, JSON object, or JSON array) and named `boolean`, `choice`
+(2-255 options), or `score` (2-10 levels, lowest first) questions, answered together with
+probabilities. `classify` types each answer from its question (a choice answer's `choice` is the
+union of its option keys) and checks every answer against its question. Probabilities are kept as
+returned, never renormalized. Failures are typed (`ClassificationRequestInvalid`,
+`ClassificationProviderError`, `ClassificationResponseInvalid`); a response that fails to decode
+keeps the billed `usage`. Classification is a read; authorization stays host policy.
+
+`@yolk-sdk/agent/providers/vercel/ai-gateway-classifier` calls AI Gateway `POST /v1/evaluate`
+(Gateway calls this evaluation) with `typesafe-ai/jev` by default and the same Gateway credential
+as the chat provider:
+
+```ts
+import { Effect, Redacted } from 'effect'
+import { FetchHttpClient } from 'effect/http'
+import { classify } from '@yolk-sdk/agent/classification'
+import { makeVercelAiGatewayClassifierLayer } from '@yolk-sdk/agent/providers/vercel/ai-gateway-classifier'
+
+const program = classify({
+  state: { subject: 'Invoice question', body: 'I was charged twice.' },
+  questions: {
+    route: {
+      type: 'choice',
+      instructions: 'Which team should handle this ticket?',
+      criteria: { billing: 'Payments and refunds.', bug: 'Product defects.' }
+    }
+  }
+}).pipe(
+  Effect.map(result => result.answers.route.choice), // 'billing' | 'bug'
+  Effect.provide(makeVercelAiGatewayClassifierLayer({ apiKey: Redacted.make(gatewayKey) })),
+  Effect.provide(FetchHttpClient.layer)
+)
+```
+
+`providerOptions` passes through unchanged (for example `{ gateway: { zeroDataRetention: true } }`).
+`providerMetadata.gateway.cost` becomes `usage.costUsd`, and `x-ai-gateway-evaluation-fallback-*`
+response headers are kept in `providerMetadata.evaluationFallbackHeaders`.
+
 ## Subagents
 
 `subagent` is the package-owned contract for child-agent delegation. The SDK provides schema,
@@ -838,6 +913,28 @@ Without a host, definitions, approval ids, and inline behavior are unchanged.
 - Hosts own authorization, status/wait tools, cancellation, terminal storage, usage, and delivery.
   Never append a second result for the original call.
 
+## Code mode tool contract
+
+These options are the tool contract that [`@yolk-sdk/codemode`](../codemode/README.md) builds on.
+This package declares them; it does not run scripts.
+
+- `makeTool({ output })` adds declaration-only `ToolDef.outputSchema`, lowered like `parameters`.
+- `callableBy: 'all' | 'model' | 'codemode'` (default `all`) decides who may call a tool. For
+  `codemode` only, `discovery: 'listed' | 'search'` (default `listed`) decides how scripts find it.
+  Codemode-only tools never reach providers. Approval, input, interaction, activated background,
+  `question`, `subagent`, and nested-access tools never run from code mode; `resolveTools` rejects
+  `callableBy: 'codemode'` on them.
+- `nestedToolAccess: true` gives a registration's `execute` a `nested` executor over the other
+  code-mode-callable tools of the same resolution and host context. Nested calls run through the
+  resolved execute path and fail closed with model-visible error results. Assign nested call ids as
+  `<parentToolCallId>/<seq>`.
+- `describe: ({ tools }) => string` on a nested-access registration computes its resolved
+  description from those nested tools; `def.description` stays the static fallback.
+- Report nested calls with protocol `recordNestedToolCall` and `nestedToolCallResultFields`. The
+  bounded `ToolResult.nestedCalls` record and summed `ToolResult.usage` never reach the model:
+  `toolResultMessageFromResult` drops both, and the loop does not add `ToolResult.usage` to run
+  usage. Capture them from the `ToolResult` or tool events when you need audit or billing records.
+
 ## Tool failures
 
 Use `modelVisibleToolError(...)` for expected tool-domain failures the model can recover
@@ -847,9 +944,10 @@ see the message and continue. The result includes structured content with `type`
 `reason`, `message`, and optional `details` for UI/runtime handling.
 
 Optional `makeTool({ invalidParamsMessage })` receives the `Schema.SchemaError` produced by
-`Schema.decodeUnknownEffect` on `parameters` (validate and execute). The decode error is passed
+decoding `parameters` through its JSON codec (validate and execute). The decode error is passed
 through unwrapped. Default text is `Invalid ${name} arguments: ${String(error)}`, which keeps the
-`SchemaError(...)` wrapper. In Effect rc.115, `SchemaError` extends native `Error`, but the
+`SchemaError(...)` wrapper, followed by one line per object (path and allowed-key set) naming its unknown keys and
+listing the allowed keys. Custom callbacks can append the same hint with `withToolArgumentsErrorHint(message, error)`. In Effect 4, `SchemaError` extends native `Error`, but the
 wrapper remains part of this tool-message contract; do not default to `.message`.
 Existing `(error: unknown) => string` callbacks remain assignable.
 
@@ -867,12 +965,16 @@ aborts, and implementation bugs outside typed tool execution.
 - Persist/return one `ToolResultMessage` for every host tool call, including `isError` failures.
 - Persist terminal provider failures and clear active run ids where applicable.
 - Provide tools, approval policy, auth, storage, and observability.
+- If you send `ToolDef`s to providers yourself (outside `run`/`runModelTurn`), filter them with
+  protocol `providerToolDefs`; codemode-only tools must never reach providers. Executor decorators
+  outside `ResolvedToolSet.execute` do not see nested code mode calls.
 - Compact context and decide memory/search policy.
 
 ## Boundaries
 
 - Core loop/protocol/runtime/tools have no React, Next.js, provider SDKs, auth, storage drivers, or app concepts.
 - `@yolk-sdk/agent/compaction` combines pure planning/formatting helpers with Effect-native transformer and retry adapters; hosts own thresholds, summaries, compaction payloads, and durable compactor policy.
+- `@yolk-sdk/agent/classification` is provider-neutral (no Node, React, or provider code); provider subpaths supply `ClassifierModel` layers.
 - `@yolk-sdk/agent/react` is headless and uses React as an optional peer.
 - Provider subpaths own vendor wire/auth mechanics only; hosts own token storage, refresh, routing, and policy.
 - `@yolk-sdk/agent/providers/openai/speech` is server integration requiring runtime

package/dist/classification/errors.d.mts

@@ -0,0 +1,57 @@
+import * as Schema from "effect/Schema";
+import { ProviderErrorInfo } from "@yolk-sdk/agent/protocol";
+
+//#region src/classification/errors.d.ts
+/**
+ * Why an answer does not fit its question:
+ *
+ * - `missing_answer`: a question has no answer.
+ * - `unexpected_answer`: an answer names no question that was asked.
+ * - `type_mismatch`: the answer's `type` is not the question's.
+ * - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.
+ * - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.
+ * - `invalid_choice`: a choice answer names no option of its question.
+ * - `invalid_score`: a score answer has no finite `score`.
+ * - `malformed_answer`: the answer is not an object.
+ */
+declare const ClassificationAnswerIssueReason: Schema.Literals<readonly ["missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+type ClassificationAnswerIssueReason = typeof ClassificationAnswerIssueReason.Type;
+/** `malformed_response`: the response body is not the provider's documented envelope. */
+declare const ClassificationResponseIssue: Schema.Literals<readonly ["malformed_response", "missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+type ClassificationResponseIssue = typeof ClassificationResponseIssue.Type;
+declare const ClassificationRequestInvalid_base: Schema.Class<ClassificationRequestInvalid, Schema.TaggedStruct<"ClassificationRequestInvalid", {
+  readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+/** The request does not satisfy the classification contract; nothing was sent. */
+declare class ClassificationRequestInvalid extends ClassificationRequestInvalid_base {}
+declare const ClassificationProviderError_base: Schema.Class<ClassificationProviderError, Schema.TaggedStruct<"ClassificationProviderError", {
+  readonly message: Schema.String;
+  readonly retryable: Schema.Boolean;
+  readonly provider: typeof ProviderErrorInfo;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The provider could not be reached or rejected the request. `message` is safe to show: it never
+ * carries provider bodies, headers, or credentials. `provider` classifies the failure (status,
+ * provider error code, retry delay).
+ */
+declare class ClassificationProviderError extends ClassificationProviderError_base {}
+declare const ClassificationResponseInvalid_base: Schema.Class<ClassificationResponseInvalid, Schema.TaggedStruct<"ClassificationResponseInvalid", {
+  readonly message: Schema.String; /** Provider id, when a provider (not the typed `classify` check) found the issue. */
+  readonly provider: Schema.optional<Schema.String>;
+  readonly reason: Schema.Literals<readonly ["malformed_response", "missing_answer", "unexpected_answer", "type_mismatch", "invalid_probability", "invalid_confidence", "invalid_choice", "invalid_score", "malformed_answer"]>;
+  readonly questionId: Schema.optional<Schema.String>;
+  readonly usage: Schema.optional<Schema.Struct<{
+    readonly inputTokens: Schema.Int;
+    readonly outputTokens: Schema.Int;
+    readonly costUsd: Schema.optionalKey<Schema.Finite>;
+  }>>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * The provider answered, but the response or one of its answers does not fit the request.
+ * `usage` is kept when the provider reported it, because the request was billed.
+ */
+declare class ClassificationResponseInvalid extends ClassificationResponseInvalid_base {}
+type ClassificationError = ClassificationRequestInvalid | ClassificationProviderError | ClassificationResponseInvalid;
+//#endregion
+export { ClassificationAnswerIssueReason, ClassificationError, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue };
+//# sourceMappingURL=errors.d.mts.map

package/dist/classification/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/classification/errors.ts"],"mappings":";;;;;;AAgBA;;;;AAA4C;AAW5C;;;;AAAyF;cAX5E,+BAAA,EAA+B,MAAA,CAAA,QAAA;AAAA,KAWhC,+BAAA,UAAyC,+BAAA,CAAgC,IAAI;;cAG5E,2BAAA,EAA2B,MAAA,CAAA,QAAA;AAAA,KAK5B,2BAAA,UAAqC,2BAAA,CAA4B,IAAI;AAAA,cAAA,iCAAA;;;;cAGpE,4BAAA,SAAqC,iCAKjD;AAAA,cAAG,gCAAA;;;;;;;;;;cAOS,2BAAA,SAAoC,gCAOhD;AAAA,cAAG,kCAAA;;;;;;;;;;;AAdA;;;;AAAA,cAoBS,6BAAA,SAAsC,kCAUlD;AAAA,KAEW,mBAAA,GACR,4BAAA,GACA,2BAAA,GACA,6BAAA"}

package/dist/classification/errors.mjs

@@ -0,0 +1,56 @@
+import { ClassificationUsage } from "./schema.mjs";
+import * as Schema from "effect/Schema";
+import { ProviderErrorInfo } from "@yolk-sdk/agent/protocol";
+//#region src/classification/errors.ts
+/**
+* Why an answer does not fit its question:
+*
+* - `missing_answer`: a question has no answer.
+* - `unexpected_answer`: an answer names no question that was asked.
+* - `type_mismatch`: the answer's `type` is not the question's.
+* - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.
+* - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.
+* - `invalid_choice`: a choice answer names no option of its question.
+* - `invalid_score`: a score answer has no finite `score`.
+* - `malformed_answer`: the answer is not an object.
+*/
+const ClassificationAnswerIssueReason = Schema.Literals([
+	"missing_answer",
+	"unexpected_answer",
+	"type_mismatch",
+	"invalid_probability",
+	"invalid_confidence",
+	"invalid_choice",
+	"invalid_score",
+	"malformed_answer"
+]);
+/** `malformed_response`: the response body is not the provider's documented envelope. */
+const ClassificationResponseIssue = Schema.Literals(["malformed_response", ...ClassificationAnswerIssueReason.literals]);
+/** The request does not satisfy the classification contract; nothing was sent. */
+var ClassificationRequestInvalid = class extends Schema.TaggedError()("ClassificationRequestInvalid", { message: Schema.String }) {};
+/**
+* The provider could not be reached or rejected the request. `message` is safe to show: it never
+* carries provider bodies, headers, or credentials. `provider` classifies the failure (status,
+* provider error code, retry delay).
+*/
+var ClassificationProviderError = class extends Schema.TaggedError()("ClassificationProviderError", {
+	message: Schema.String,
+	retryable: Schema.Boolean,
+	provider: ProviderErrorInfo
+}) {};
+/**
+* The provider answered, but the response or one of its answers does not fit the request.
+* `usage` is kept when the provider reported it, because the request was billed.
+*/
+var ClassificationResponseInvalid = class extends Schema.TaggedError()("ClassificationResponseInvalid", {
+	message: Schema.String,
+	/** Provider id, when a provider (not the typed `classify` check) found the issue. */
+	provider: Schema.optional(Schema.String),
+	reason: ClassificationResponseIssue,
+	questionId: Schema.optional(Schema.String),
+	usage: Schema.optional(ClassificationUsage)
+}) {};
+//#endregion
+export { ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/classification/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/classification/errors.ts"],"sourcesContent":["import * as Schema from 'effect/Schema'\nimport { ProviderErrorInfo } from '@yolk-sdk/agent/protocol'\nimport { ClassificationUsage } from './schema.ts'\n\n/**\n * Why an answer does not fit its question:\n *\n * - `missing_answer`: a question has no answer.\n * - `unexpected_answer`: an answer names no question that was asked.\n * - `type_mismatch`: the answer's `type` is not the question's.\n * - `invalid_probability`: a probability is missing, not a number, non-finite, or outside `[0, 1]`.\n * - `invalid_confidence`: a confidence is not a finite number in `[0, 1]`.\n * - `invalid_choice`: a choice answer names no option of its question.\n * - `invalid_score`: a score answer has no finite `score`.\n * - `malformed_answer`: the answer is not an object.\n */\nexport const ClassificationAnswerIssueReason = Schema.Literals([\n  'missing_answer',\n  'unexpected_answer',\n  'type_mismatch',\n  'invalid_probability',\n  'invalid_confidence',\n  'invalid_choice',\n  'invalid_score',\n  'malformed_answer'\n])\n\nexport type ClassificationAnswerIssueReason = typeof ClassificationAnswerIssueReason.Type\n\n/** `malformed_response`: the response body is not the provider's documented envelope. */\nexport const ClassificationResponseIssue = Schema.Literals([\n  'malformed_response',\n  ...ClassificationAnswerIssueReason.literals\n])\n\nexport type ClassificationResponseIssue = typeof ClassificationResponseIssue.Type\n\n/** The request does not satisfy the classification contract; nothing was sent. */\nexport class ClassificationRequestInvalid extends Schema.TaggedError<ClassificationRequestInvalid>()(\n  'ClassificationRequestInvalid',\n  {\n    message: Schema.String\n  }\n) {}\n\n/**\n * The provider could not be reached or rejected the request. `message` is safe to show: it never\n * carries provider bodies, headers, or credentials. `provider` classifies the failure (status,\n * provider error code, retry delay).\n */\nexport class ClassificationProviderError extends Schema.TaggedError<ClassificationProviderError>()(\n  'ClassificationProviderError',\n  {\n    message: Schema.String,\n    retryable: Schema.Boolean,\n    provider: ProviderErrorInfo\n  }\n) {}\n\n/**\n * The provider answered, but the response or one of its answers does not fit the request.\n * `usage` is kept when the provider reported it, because the request was billed.\n */\nexport class ClassificationResponseInvalid extends Schema.TaggedError<ClassificationResponseInvalid>()(\n  'ClassificationResponseInvalid',\n  {\n    message: Schema.String,\n    /** Provider id, when a provider (not the typed `classify` check) found the issue. */\n    provider: Schema.optional(Schema.String),\n    reason: ClassificationResponseIssue,\n    questionId: Schema.optional(Schema.String),\n    usage: Schema.optional(ClassificationUsage)\n  }\n) {}\n\nexport type ClassificationError =\n  | ClassificationRequestInvalid\n  | ClassificationProviderError\n  | ClassificationResponseInvalid\n"],"mappings":";;;;;;;;;;;;;;;;AAgBA,MAAa,kCAAkC,OAAO,SAAS;CAC7D;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAKD,MAAa,8BAA8B,OAAO,SAAS,CACzD,sBACA,GAAG,gCAAgC,QACrC,CAAC;;AAKD,IAAa,+BAAb,cAAkD,OAAO,YAA0C,EACjG,gCACA,EACE,SAAS,OAAO,OAClB,CACF,EAAE,CAAC;;;;;;AAOH,IAAa,8BAAb,cAAiD,OAAO,YAAyC,EAC/F,+BACA;CACE,SAAS,OAAO;CAChB,WAAW,OAAO;CAClB,UAAU;AACZ,CACF,EAAE,CAAC;;;;;AAMH,IAAa,gCAAb,cAAmD,OAAO,YAA2C,EACnG,iCACA;CACE,SAAS,OAAO;;CAEhB,UAAU,OAAO,SAAS,OAAO,MAAM;CACvC,QAAQ;CACR,YAAY,OAAO,SAAS,OAAO,MAAM;CACzC,OAAO,OAAO,SAAS,mBAAmB;AAC5C,CACF,EAAE,CAAC"}

package/dist/classification/index.d.mts

@@ -0,0 +1,4 @@
+import { ClassificationAnswerIssueReason, ClassificationError, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue } from "./errors.mjs";
+import { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationRequest, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestionType, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels } from "./schema.mjs";
+import { ClassificationAnswerIssue, ClassificationRequestFor, ClassificationResultFor, ClassifierAnswerFor, ClassifierAnswersFor, ClassifierModel, ClassifierQuestionsInput, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor } from "./model.mjs";
+export { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, type ClassificationAnswerIssue, ClassificationAnswerIssueReason, type ClassificationError, ClassificationProviderError, ClassificationRequest, type ClassificationRequestFor, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue, ClassificationResult, type ClassificationResultFor, ClassificationUsage, ClassifierAnswer, type ClassifierAnswerFor, type ClassifierAnswersFor, ClassifierCriterion, ClassifierModel, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, type ClassifierQuestionType, ClassifierQuestions, type ClassifierQuestionsInput, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels };

package/dist/classification/index.mjs

@@ -0,0 +1,4 @@
+import { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationRequest, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels } from "./schema.mjs";
+import { ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue } from "./errors.mjs";
+import { ClassifierModel, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor } from "./model.mjs";
+export { BooleanClassifierAnswer, BooleanClassifierQuestion, ChoiceClassifierAnswer, ChoiceClassifierQuestion, ClassificationAnswerIssueReason, ClassificationProviderError, ClassificationRequest, ClassificationRequestInvalid, ClassificationResponseInvalid, ClassificationResponseIssue, ClassificationResult, ClassificationUsage, ClassifierAnswer, ClassifierCriterion, ClassifierModel, ClassifierProbabilities, ClassifierProbability, ClassifierQuestion, ClassifierQuestions, ClassifierState, ScoreClassifierAnswer, ScoreClassifierQuestion, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor, maxClassifierChoiceOptions, maxClassifierScoreLevels, minClassifierChoiceOptions, minClassifierScoreLevels };

package/dist/classification/model.d.mts

@@ -0,0 +1,74 @@
+import { ClassificationAnswerIssueReason, ClassificationError, ClassificationRequestInvalid } from "./errors.mjs";
+import { BooleanClassifierAnswer, ChoiceClassifierAnswer, ClassificationRequest, ClassificationResult, ClassifierAnswer, ClassifierQuestion, ScoreClassifierAnswer } from "./schema.mjs";
+import { Context, Effect, Result } from "effect";
+
+//#region src/classification/model.d.ts
+declare const ClassifierModel_base: Context.ServiceClass<ClassifierModel, "@yolk-sdk/agent/classification/ClassifierModel", {
+  readonly classify: (request: ClassificationRequest) => Effect.Effect<ClassificationResult, ClassificationError>;
+}>;
+/**
+ * Answers typed questions about one state. Classification is a read: it has no side effects.
+ * Providers supply layers; `classify` is the typed entry point.
+ */
+declare class ClassifierModel extends ClassifierModel_base {}
+/** Named questions, typed for inference. */
+type ClassifierQuestionsInput = {
+  readonly [questionId: string]: ClassifierQuestion;
+};
+/** The answer type a question gets; a choice answer's `choice` is the union of its option keys. */
+type ClassifierAnswerFor<Q extends ClassifierQuestion> = Q extends {
+  readonly type: 'boolean';
+} ? BooleanClassifierAnswer : Q extends {
+  readonly type: 'choice';
+  readonly criteria: infer Criteria;
+} ? ChoiceClassifierAnswer & {
+  readonly choice: Extract<keyof Criteria, string>;
+} : ScoreClassifierAnswer;
+type ClassifierAnswersFor<Q extends ClassifierQuestionsInput> = { readonly [K in keyof Q]: ClassifierAnswerFor<Q[K]> };
+type ClassificationRequestFor<Q extends ClassifierQuestionsInput> = Omit<ClassificationRequest, 'questions'> & {
+  readonly questions: Q;
+};
+type ClassificationResultFor<Q extends ClassifierQuestionsInput> = ClassificationResult & {
+  readonly answers: ClassifierAnswersFor<Q>;
+};
+/** Where an answer leaves its question. */
+type ClassificationAnswerIssue = {
+  readonly reason: ClassificationAnswerIssueReason;
+  readonly questionId: string;
+};
+/**
+ * Decode one raw provider answer against the question it answers. The answer must be an object
+ * whose `type` is the question's; probabilities and confidence must be finite numbers in `[0, 1]`
+ * and are kept exactly as given (never renormalized); a choice must name one of the question's
+ * options; a score must be finite. Only the contract fields are kept.
+ */
+declare const decodeClassifierAnswer: (question: ClassifierQuestion, raw: unknown) => Result.Result<ClassifierAnswer, ClassificationAnswerIssueReason>;
+/**
+ * Decode raw provider answers (a JSON object keyed by question id) against the questions asked:
+ * every question needs exactly one answer of its type, and no answer may name a question that was
+ * not asked. Fails with the first issue, in question order (then unexpected answers); answers that
+ * are not an object fail as the first question's `malformed_answer`.
+ */
+declare const decodeClassifierAnswers: (questions: ClassifierQuestionsInput, raw: unknown) => Result.Result<Record<string, ClassifierAnswer>, ClassificationAnswerIssue>;
+/** The first way `answers` leaves `questions`, or undefined when every answer fits its question. */
+declare const classificationAnswersIssue: (questions: ClassifierQuestionsInput, answers: {
+  readonly [questionId: string]: ClassifierAnswer;
+}) => ClassificationAnswerIssue | undefined;
+/** Narrow a result to the answer types its questions infer, after checking every answer. */
+declare const isClassificationResultFor: <const Q extends ClassifierQuestionsInput>(questions: Q, result: ClassificationResult) => result is ClassificationResultFor<Q>;
+/**
+ * Validate a request against the classification contract before anything is sent. Fails with
+ * `ClassificationRequestInvalid` (for example a choice with more than 255 options, or a score with
+ * more than 10 levels).
+ */
+declare const decodeClassificationRequest: (request: unknown) => Effect.Effect<ClassificationRequest, ClassificationRequestInvalid>;
+/**
+ * Classify with the `ClassifierModel` in context, typing each answer from its question: a choice
+ * answer's `choice` is the union of that question's option keys. Every answer is checked against
+ * its question; a provider that returns a mismatching answer fails with
+ * `ClassificationResponseInvalid` (keeping usage).
+ */
+declare const classify: <const Q extends ClassifierQuestionsInput>(request: ClassificationRequestFor<Q>) => Effect.Effect<ClassificationResultFor<Q>, ClassificationError, ClassifierModel>;
+//#endregion
+export { ClassificationAnswerIssue, ClassificationRequestFor, ClassificationResultFor, ClassifierAnswerFor, ClassifierAnswersFor, ClassifierModel, ClassifierQuestionsInput, classificationAnswersIssue, classify, decodeClassificationRequest, decodeClassifierAnswer, decodeClassifierAnswers, isClassificationResultFor };
+//# sourceMappingURL=model.d.mts.map

package/dist/classification/model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.mts","names":[],"sources":["../../src/classification/model.ts"],"mappings":";;;;;cAiBoB,oBAAA;sBAUd,OAAA,EAAS,qBAAA,KACN,MAAA,CAAO,MAAA,CAAO,oBAAA,EAAsB,mBAAA;AAAA;;;;;cALhC,eAAA,SAAwB,oBAOgB;;KAGzC,wBAAA;EAAA,UAAuC,UAAA,WAAqB,kBAAkB;AAAA;;KAG9E,mBAAA,WAA8B,kBAAA,IAAsB,CAAA;EAAA,SACrD,IAAA;AAAA,IAEP,uBAAA,GACA,CAAA;EAAA,SAAqB,IAAA;EAAA,SAAyB,QAAA;AAAA,IAC5C,sBAAA;EAAA,SAAoC,MAAA,EAAQ,OAAA,OAAc,QAAA;AAAA,IAC1D,qBAAA;AAAA,KAEM,oBAAA,WAA+B,wBAAA,2BACpB,CAAA,GAAI,mBAAA,CAAoB,CAAA,CAAE,CAAA;AAAA,KAGrC,wBAAA,WAAmC,wBAAA,IAA4B,IAAA,CACzE,qBAAA;EAAA,SAEa,SAAA,EAAW,CAAA;AAAA;AAAA,KAEd,uBAAA,WAAkC,wBAAA,IAA4B,oBAAA;EAAA,SAC/D,OAAA,EAAS,oBAAA,CAAqB,CAAA;AAAA;;KAI7B,yBAAA;EAAA,SACD,MAAA,EAAQ,+BAA+B;EAAA,SACvC,UAAA;AAAA;;;;;;;cAuDE,sBAAA,GACX,QAAA,EAAU,kBAAA,EACV,GAAA,cACC,MAAA,CAAO,MAAA,CAAO,gBAAA,EAAkB,+BAAA;;;;;;;cAwDtB,uBAAA,GACX,SAAA,EAAW,wBAAA,EACX,GAAA,cACC,MAAA,CAAO,MAAA,CAAO,MAAA,SAAe,gBAAA,GAAmB,yBAAA;;cAkCtC,0BAAA,GACX,SAAA,EAAW,wBAAA,EACX,OAAA;EAAA,UAAqB,UAAA,WAAqB,gBAAA;AAAA,MACzC,yBAAA;;cAOU,yBAAA,mBAA6C,wBAAA,EACxD,SAAA,EAAW,CAAA,EACX,MAAA,EAAQ,oBAAA,KACP,MAAA,IAAU,uBAAA,CAAwB,CAAA;;;;;;cAQxB,2BAAA,GACX,OAAA,cACC,MAAA,CAAO,MAAA,CAAO,qBAAA,EAAuB,4BAAA;;AAhMb;AAE3B;;;;cA6Ma,QAAA,mBAA4B,wBAAA,EACvC,OAAA,EAAS,wBAAA,CAAyB,CAAA,MACjC,MAAA,CAAO,MAAA,CAAO,uBAAA,CAAwB,CAAA,GAAI,mBAAA,EAAqB,eAAA"}