@alvin0/ai-agent-sdk-decision-adapter 0.0.0-stage → 0.1.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 alvin0 (chaulamdinhai) <chaulamdinhai@gmail.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,289 @@
-# Temporary Holding Version
+# Decision adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime: **Universal** (Node, browser, and Web-standard workers).
+
+```sh
+pnpm add @alvin0/ai-agent-sdk-core @alvin0/ai-agent-sdk-decision-adapter
+```
+
+Provider-neutral typed decisions, independently of chat generation and embeddings.
+Use `choiceQuestion`, `scoreQuestion`, and `booleanQuestion` to define a closed
+answer space. The return type preserves question IDs and literal choice options.
+
+See [Use cases and setup](./USE_CASES.md) for routing, triage, guardrails, RAG
+reranking, extraction, and staged workflows, including their tradeoffs.
+
+```ts
+import {
+  createDecisionRuntime, choiceQuestion,
+} from '@alvin0/ai-agent-sdk-decision-adapter'
+import { typesafePlugin } from '@alvin0/ai-agent-sdk-provider-typesafe'
+
+const runtime = createDecisionRuntime({
+  providers: [typesafePlugin({ apiKey: 'your-server-side-key' })],
+})
+try {
+  const model = runtime.decisionModel({ provider: 'typesafe', model: 'jev-latest' })
+  const result = await model.evaluate({
+    state: { message: 'Please refund my invoice' },
+    questions: {
+      department: choiceQuestion('Which department should handle this?', {
+        billing: 'Invoices and refunds', support: 'Technical issues',
+      }),
+    },
+  })
+  // Typed as 'billing' | 'support'.
+  console.log(result.answers.department.choice)
+} finally {
+  await runtime.close()
+}
+```
+
+## Contract
+
+- `choice`: selected option; optional full probability distribution.
+- `score`: expected zero-based ordinal level; fractional scores are valid.
+- `boolean`: boolean value; optional probability of true. The TypeSafe provider
+  uses `probabilityTrue >= 0.5` for `value`; application thresholds can use the raw
+  probability instead.
+- Evidence carries `probabilitySource`: `provider`, `token-logprobs`, or
+  `model-generated`. The tag identifies provenance, not a calibration guarantee.
+  Missing evidence/usage stays absent. Confidence is not inferred.
+- JSON is detached and frozen before async preparation. Results are checked for
+  IDs, types, allowed choices, probability bounds/sums, and score consistency.
+  JSON is bounded to 2 MiB, 100,000 nodes and depth 64.
+- Model catalogs are advisory. Unknown model IDs remain callable.
+
+## OpenAI, Anthropic and Gemini decisions
+
+`llmDecisionAdapter({ adapter })` wraps an existing SDK `ModelAdapter`.
+`llmDecisionPlugin({ id, routes, adapter })` installs that bridge into the companion
+runtime. Install only the provider packages you use; the decision package adds no
+dependency on concrete providers. Their existing credentials, gateways, injected
+fetch, request logging and provider-attempt accounting remain in use.
+
+OpenAI project examples and live calls use `gpt-6-luna` as the minimum model.
+Select it or a newer model explicitly; do not fall back to older OpenAI models.
+
+```ts
+import { createDecisionRuntime, createDecisionTask, choiceQuestion, llmDecisionPlugin }
+  from '@alvin0/ai-agent-sdk-decision-adapter'
+import { openAiAdapter } from '@alvin0/ai-agent-sdk-provider-openai'
+import { anthropicAdapter } from '@alvin0/ai-agent-sdk-provider-anthropic'
+import { geminiAdapter } from '@alvin0/ai-agent-sdk-provider-gemini'
+import { envCredential } from '@alvin0/ai-agent-sdk-auth-node/env'
+
+const runtime = createDecisionRuntime({ providers: [
+  llmDecisionPlugin({ id: 'openai-decisions', routes: ['openai'],
+    adapter: openAiAdapter({ apiKey: envCredential('OPENAI_API_KEY') }) }),
+  llmDecisionPlugin({ id: 'anthropic-decisions', routes: ['anthropic'],
+    adapter: anthropicAdapter({ apiKey: envCredential('ANTHROPIC_API_KEY') }) }),
+  llmDecisionPlugin({ id: 'gemini-decisions', routes: ['gemini'],
+    adapter: geminiAdapter({ apiKey: envCredential('GEMINI_API_KEY') }) }),
+] })
+try {
+  const task = createDecisionTask(runtime.decisionModel({
+    provider: 'openai', model: 'gpt-6-luna',
+  }), { questions: {
+    route: choiceQuestion('Which team should handle this?', {
+      billing: 'Invoices and refunds', support: 'Technical issues', other: 'Neither',
+    }),
+  } })
+  const result = await task.evaluate('Please refund my duplicate invoice')
+  console.log(result.answers.route.choice)
+  // Select provider: 'anthropic' or 'gemini' with that provider's model ID
+  // to use the same question/task contract. evaluateBatch works identically.
+} finally { await runtime.close() }
+```
+
+The default `outputMode: 'json-schema'` sends a closed JSON Schema through the
+provider's existing structured-output protocol. OpenAI Responses and Chat
+Completions, Anthropic Messages and Gemini Interactions are covered by HTTP fixture
+tests. Choose a model/endpoint supporting that feature. Unsupported options fail
+explicitly; the bridge does not silently switch formats or providers.
+
+For endpoints using function calling instead, configure `outputMode: 'tool'`.
+The bridge asks for exactly one `submit_decisions` call and consumes its arguments
+as data. No host tool or agent loop executes. The model must support forced tool
+selection; some models/reasoning configurations reject it. Additional/wrong tool
+calls, truncated responses, invalid JSON, unknown fields/options, and inconsistent
+scores/distributions fail validation. Numeric constraints are checked locally to
+keep the schema portable across provider subsets.
+
+`evidence: 'none'` is the default: only choice/score/boolean values are requested.
+Missing probabilities/confidence remain absent. With `evidence: 'model-generated'`,
+Choice/Score request full probability distributions and confidence, and Boolean
+requests `probabilityTrue`. These are model estimates, not native probabilities or
+token logprobs. They are always tagged `model-generated`, cannot spoof provenance,
+and require explicit `allowedSources: ['model-generated']` in a gate. Structured
+output constrains shape; it does not calibrate those estimates.
+
+Options also accept `generation: { maxTokens, temperature, topP, reasoningEffort }`
+and `maxResponseBytes` (default 2 MiB, maximum 16 MiB), including reasoning and
+arguments. Sampling/effort support remains model-specific; omission adds no sampling
+defaults. Pass a raw single-attempt adapter, not a retry-wrapped registry/agent
+handle. The decision runtime owns retry/deadline policy and reuses one prepared
+generation across attempts. Direct bridge calls are also deadline-bounded.
+For score questions in evidence mode, the wire schema requests only the
+distribution and confidence. The SDK derives the public fractional score from
+that validated distribution; it does not ask the model to duplicate the arithmetic.
+Extra score fields and malformed distributions are rejected rather than repaired.
+
+The SDK generation stream does not expose an authoritative response model ID or
+request ID as public fields. The bridge therefore returns the requested model ID
+and omits `providerRequestId`; provider-attempt telemetry remains with the wrapped
+adapter. Pin model IDs when evaluation reproducibility matters. TypeSafe's native
+adapter continues to preserve its actual response model ID and native evidence.
+
+Protocol references: [OpenAI function calling](https://developers.openai.com/api/docs/guides/function-calling),
+[Anthropic tool definitions](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools),
+[Gemini Interactions](https://ai.google.dev/gemini-api/docs/interactions-overview).
+
+## Providers and lifecycle
+
+Extend `DecisionAdapter`; only `evaluate()` is abstract. One invocation performs
+one physical attempt. Override `resolveModel()` to declare question types and
+provider-specific bounds. Mutable connection configurations must override
+`prepareDecisionCall()` to bind metadata and dispatch to the same generation.
+Its optional fourth argument is the invocation context: forward it during
+connection/credential preparation as well as dispatch. A prepared call belongs to
+one logical request; reuse that request for retries, prepare again for a new input.
+Adapters must honor the request's `signal` and may report physical attempts using
+the supplied SDK `ModelInvocationContext`.
+
+`defineDecisionProviderPlugin()` declares versioned route ownership. Register
+multiple plugins with `createDecisionRuntime({ providers })`, or register adapters
+directly with `runtime.registerAdapter(routes, adapter)`. A route cannot have two
+decision adapters; registration is atomic and returns an idempotent disposer.
+
+This package supplies a **companion runtime**, not an `AgentRuntime` plugin. Keep
+the decision runtime next to the agent runtime and call its model handles from
+host workflow code or a tool. Pass `ModelInvocationContext` as the second argument
+to `evaluate()` to join existing provider-attempt accounting; this runtime does
+not create an independent observation exporter or fabricate attempt telemetry.
+
+The default logical deadline is 30 seconds, including preparation, attempts and
+backoff. Override with runtime `timeoutMs` or per-call `timeoutMs`. SDK retry policy
+and backoff helpers are reused; the adapter's route retry policy takes precedence
+over the runtime default when explicitly configured (TypeSafe inherits the runtime
+policy when its `retryPolicy` is omitted). A single prepared call is reused across
+retries. The runtime owns the overall deadline; the LLM bridge does not add an
+independent 30-second deadline inside a runtime call. Direct LLM calls retain a
+30-second default. Transport request limits may still bound a physical attempt.
+`close()` aborts active work, runs plugin cleanup, and rejects subsequent calls.
+Noncooperative extension promises are detached after cancellation; their late
+rejections are observed, but external side effects cannot be undone.
+
+### Connecting to a core agent
+
+The current `AgentRuntime.providers` accepts generation and embedding plugins,
+not decision plugins, and `AgentRuntime` has no `decisionModel()` method. A decision
+task can nevertheless run inside a core tool through the public API:
+
+```ts
+import { defineTool } from '@alvin0/ai-agent-sdk-core'
+
+// `task` is a configured decision task with a `route` choice question.
+const classifyTicket = defineTool<{ message: string }>({
+  name: 'classify_ticket', description: 'Classify a support ticket',
+  parameters: {
+    type: 'object', properties: { message: { type: 'string' } },
+    required: ['message'], additionalProperties: false,
+  },
+  parse(raw) {
+    if (raw === null || typeof raw !== 'object' || !('message' in raw)
+      || typeof raw.message !== 'string') throw new Error('message required')
+    return { message: raw.message }
+  },
+  async execute(args, ctx) {
+    const result = await task.evaluate({ message: args.message },
+      { signal: ctx.signal }, { ...(ctx.logger ? { logger: ctx.logger } : {}) })
+    return { route: result.answers.route.choice, model: result.model }
+  },
+})
+// Pass tools: [classifyTicket] when binding a core agent/session.
+```
+
+Return the selected JSON fields to the agent, and always forward `ctx.signal`.
+Closing core aborts a decision called by an active tool when that signal is
+forwarded. Core does not close the independently-created decision runtime; the
+host must close both owners, including decisions called outside agent runs.
+Tool signals are scoped to one invocation and are aborted during cleanup, so do
+not keep them for later background work.
+
+`ToolRunContext` exposes cancellation, logging and run position; it does not
+expose a complete `ModelInvocationContext` or provider-attempt accounting handle.
+Forwarding its logger alone does not merge nested decision usage into the core
+agent's token totals, budgets or model-call reports. A host-owned invocation
+context can be passed explicitly; full core-managed admission, lifecycle,
+catalogs and accounting would require a native decision capability in core.
+
+The public integration tests cover tool output reaching the next agent step,
+core-close cancellation, independent companion lifecycle, and rejection of
+decision plugins in the core provider list.
+
+Run `pnpm --filter @alvin0/ai-agent-sdk-decision-adapter test` for offline contract
+tests and `test:pack` for installed-tarball verification.
+For live acceptance with workspace `.env` keys, run `pnpm human:decision:all` after
+building. It covers TypeSafe and OpenAI JSON Schema/tool mode, English/Vietnamese,
+batches, model-generated evidence and a core agent tool. Unconfigured providers
+are skipped. OpenAI defaults to `gpt-6-luna`. `OPENAI_DECISION_MODEL` (or
+`OPENAI_MODEL`) may select it or a newer model; `TYPESAFE_MODEL` pins the TypeSafe
+model. The runner emits safe status/usage/latency diagnostics without keys or raw
+errors.
+
+## Reusable tasks and batches
+
+`createDecisionTask(model, { questions, timeoutMs, context })` binds a detached,
+frozen rubric to a model handle. `task.evaluate(state, { signal, timeoutMs }, context)`
+overrides call options without repeating questions or connection configuration.
+SDK-created immutable snapshots are reused; arbitrary frozen caller inputs still
+undergo validation. Task batches share the captured rubric across queued states.
+The LLM bridge and TypeSafe compile each rubric once per adapter/rubric identity,
+and reuse the captured request through retries. No result cache or cross-call
+credential/connection cache is introduced. Prepared calls reject requests targeting
+a different provider/model before dispatch. Direct LLM prepared evaluations also
+honor `timeoutMs` (30 seconds by default) and close stalled iterators without
+waiting for their teardown. JSON arrays must contain only their own enumerable
+indexed data properties; getters, custom iterators, symbols and auxiliary
+properties are rejected without running caller hooks. LLM prompts put the fixed questions
+before changing state; evidence instructions appear only in evidence mode.
+Use a separate task per model/rubric combination; changing providers requires no
+change to the task's question contract.
+
+`task.evaluateBatch(states, { concurrency, signal, timeoutMs, context })` evaluates
+independent states with the same rubric. `evaluateDecisionBatch(model, inputs, options)`
+also accepts a different question set per input. Both preserve input order and
+return `{ status: 'fulfilled', value }` or `{ status: 'rejected', reason }` per item.
+They use at most four concurrent logical calls by default (configurable 1–256).
+This is client-side scheduling, not a provider batch endpoint. Retries occupy the
+same concurrency slot. A batch accepts at most 1,024 inputs, snapshots queued
+payloads before dispatch, and does not automatically chunk or truncate data.
+
+The batch deadline defaults to 30 seconds and includes queue time. Batch `timeoutMs`
+sets that overall deadline; task `timeoutMs` or input `timeoutMs` still governs each
+dispatched call, including custom handles that ignore deadlines. Item deadlines
+start on dispatch, independently of the overall deadline that includes queue time.
+Batch cancellation preserves caller `ModelError` reasons (including `TIMEOUT`)
+and signal composition supports high concurrency without accumulating listeners
+on the shared runtime/batch signal. Batch cancellation/deadline rejects the operation and stops queued
+dispatches; individual item failures/cancellation remain partial results. Invalid
+input/configuration rejects the batch before dispatch. Empty batches return `[]`.
+For large datasets, submit application-managed chunks with explicit deadlines.
+Concurrency limits active logical calls, not the memory used by queued snapshots;
+choose chunk sizes based on payload size as well as item count.
+
+## Evidence gates
+
+`gateChoice(answer, { minConfidence, minProbability, minMargin, allowedSources })`
+requires at least one explicit threshold and accepts only when every configured
+threshold passes. `minMargin` compares the selected probability to the runner-up.
+`gateBoolean(answer, { falseMax, trueMin, allowedSources })` accepts false below or
+at `falseMax`, true above or at `trueMin`, and abstains between them. Both return
+`{ status: 'accepted', value }` or `{ status: 'abstained', reason }`.
+
+Gates consume validated answers and default to `allowedSources: ['provider']`.
+Missing required evidence or disallowed provenance causes abstention. These pure
+helpers do not call a fallback model, run tools, derive confidence, or authorize
+actions. Calibrate thresholds against labeled examples for each model, question
+and domain. A provider confidence statistic is not an empirical accuracy estimate.

package/USE_CASES.md

@@ -0,0 +1,217 @@
+# Use cases and setup
+
+The kit separates three concerns: the provider handles transport and model
+capabilities; a task binds a model to reusable questions; application code owns
+thresholds, branches, ranking and actions. A decision model selects from a closed
+answer space. Generated prose, open-ended tool arguments and arbitrary extraction
+remain generation tasks.
+
+## Choosing the decision shape
+
+| Use case | Question setup | Host workflow | Main pitfall |
+| --- | --- | --- | --- |
+| Intent, tool or model routing | Choice over known routes, including `other` | Gate the selected route; select a handler/model | A forced winner is not proof the request fits any route |
+| Support triage / semantic features | Choice + independent booleans + ordinal scores in one request | Combine relevant answers in code | Questions do not consume each other's answers |
+| Input/output/tool verification | One boolean per failure mode, with concrete true/false criteria | Block, review or continue using a three-way gate | An uncertain negative does not prove safety |
+| RAG reranking / entity matching | Same relevance/match question on each query-candidate pair | Bounded batch, then filter and sort successful candidates | Choice probabilities are relative to the candidate set |
+| Severity / lead prioritization | Ordered score rubric, or several independent indicators | Apply application weights and thresholds | A fractional expected score is not an integer label or a calibrated business value |
+| Known-value extraction | Choice among parser-generated candidates plus `none` | Return the selected candidate's original value | A decision primitive cannot invent a missing address/date/argument |
+| Hierarchical classification / cascades | Choice at each branch or a verification task after selection | Separate calls with explicit updated state and a depth/budget limit | A greedy early mistake propagates; multiplying evidence does not guarantee a calibrated path probability |
+
+These patterns follow TypeSafe's [use-case map](https://docs.typesafe.ai/concepts/use-case-map),
+[fan-out](https://docs.typesafe.ai/patterns/fan-out),
+[reranking](https://docs.typesafe.ai/cookbooks/rerank_typesafe), and
+[hierarchical classification](https://docs.typesafe.ai/cookbooks/hierarchical_classification)
+examples. They are workflow patterns rather than provider-specific task types.
+
+## Setup once, reuse across consumers
+
+For a service, create one runtime during startup, inject task handles into request
+handlers/tools, and close the runtime during shutdown. For a CLI/job, use
+`try/finally`. Connection configuration is separate from the rubric so consumers
+do not receive credentials. Pass request-scoped invocation context explicitly
+instead of storing it on a singleton task.
+
+```ts
+import {
+  createDecisionRuntime, createDecisionTask, choiceQuestion, booleanQuestion,
+  scoreQuestion, gateChoice, gateBoolean,
+} from '@alvin0/ai-agent-sdk-decision-adapter'
+import { typesafePlugin } from '@alvin0/ai-agent-sdk-provider-typesafe'
+import { envCredential } from '@alvin0/ai-agent-sdk-auth-node/env'
+
+const runtime = createDecisionRuntime({
+  providers: [typesafePlugin({ apiKey: envCredential('TYPESAFE_API_KEY') })],
+  timeoutMs: 5_000,
+  retryPolicy: { mode: 'normal', maxRetries: 1 },
+})
+const model = runtime.decisionModel({ provider: 'typesafe', model: 'jev-1.13.0' })
+const triage = createDecisionTask(model, {
+  timeoutMs: 3_000,
+  questions: {
+    route: choiceQuestion('Which team should handle this ticket?', {
+      billing: 'Invoices, charges and refunds',
+      support: 'Product failures and technical issues',
+      other: 'Outside the listed categories or insufficient information',
+    }),
+    severity: scoreQuestion('Impact of the technical issue, if present', [
+      'Cosmetic', 'Degraded with a workaround', 'Blocked without a workaround',
+    ]),
+    refund: booleanQuestion('Is a refund explicitly requested?', {
+      true: 'An explicit request for money back or a credit',
+      false: 'No explicit refund request, including merely asking about prices',
+    }),
+  },
+})
+```
+
+Pin a tested model version for stable evaluation/calibration. An alias such as
+`jev-latest` is convenient for exploration; keep `result.model` in evaluation
+records so an alias change is visible. Models need no catalog allowlist. Other
+providers can bind the same questions through their own decision plugins, subject
+to their declared capabilities. Do not assume identical limits or probability
+semantics across providers.
+
+### Routing and triage
+
+```ts
+const result = await triage.evaluate({ message: 'I was charged twice; please refund.' })
+const route = gateChoice(result.answers.route, {
+  minProbability: 0.85, minMargin: 0.2,
+})
+const refund = gateBoolean(result.answers.refund, { falseMax: 0.2, trueMin: 0.8 })
+// Example thresholds only; measure them against your own labeled tickets.
+if (route.status === 'abstained') {
+  // Queue for review or ask a separate model; retain the original result.
+} else if (route.value === 'billing') {
+  // Attach refund.status/value to the billing queue, rather than issuing a refund.
+} else if (route.value === 'support') {
+  // Read severity here; the billing path can ignore that speculative answer.
+}
+```
+
+Multiple questions in one request all see the same state. This supports multi-label
+tagging through independent booleans; a single Choice returns one mutually exclusive
+winner. Questions whose rubric actually depends on an earlier answer require a
+second call with that answer included in the next state.
+
+### Guardrails and verification
+
+Use a reusable boolean task for each input/output/tool check, passing the artifact,
+relevant policy and evidence in the state. Name the question so the polarity is
+clear, for example `violatesPolicy`, rather than an ambiguous `safe`.
+
+```ts
+const verify = createDecisionTask(model, { questions: {
+  violatesPolicy: booleanQuestion('Does the proposed response violate the supplied policy?', {
+    true: 'At least one concrete policy violation is supported by the response',
+    false: 'The proposed response complies with every applicable supplied rule',
+  }),
+} })
+const check = await verify.evaluate({ policy: 'Do not disclose internal access tokens.', response: 'Hello!' })
+const verdict = gateBoolean(check.answers.violatesPolicy, { falseMax: 0.1, trueMin: 0.8 })
+// accepted false: continue; accepted true: block; abstained: review/fallback.
+```
+
+Transport/auth failures throw; they do not become a semantic negative. The host
+sets failure behavior. Decision checks supplement deterministic permission and
+schema checks; the gate itself executes no action. For citations, supply both the
+claim and source passage. For tool selection, validate tool arguments separately.
+
+### Rerank a shortlist or match entities
+
+For a runnable example combining access/date filtering, per-facet document
+selection and OpenAI answers with exact source quotes, see the
+[document-selection sample](../../samples/decision-document-selection/README.md).
+It also handles historical policies and abstains when evidence is incomplete.
+
+Use one state per candidate so relevance scores do not depend on which other
+candidates happen to share a request. Keep candidate IDs in the host array.
+
+```ts
+const relevance = createDecisionTask(model, { questions: {
+  relevant: booleanQuestion('Does this passage directly answer the query?', {
+    true: 'Contains information sufficient to answer the query',
+    false: 'Only shares a topic or lacks the needed information',
+  }),
+} })
+const candidates = [
+  { id: 'a', text: 'Refunds are processed in five business days.' },
+  { id: 'b', text: 'Our logo is blue.' },
+]
+const rows = await relevance.evaluateBatch(candidates.map(candidate => ({
+  query: 'When will my refund arrive?', passage: candidate.text,
+})), { concurrency: 4, timeoutMs: 15_000 })
+const ranked = rows.flatMap((row, index) => {
+  if (row.status !== 'fulfilled') return [] // Record failures separately; do not score them as zero.
+  const answer = row.value.answers.relevant
+  if (answer.probabilitySource !== 'provider' || answer.probabilityTrue === undefined) return []
+  return [{ candidate: candidates[index]!, score: answer.probabilityTrue, result: row.value }]
+}).sort((a, b) => b.score - a.score)
+```
+
+Retrieval produces the shortlist first; reranking cannot recover missing candidates.
+Use this pattern for record linkage by supplying two candidate records and a fixed
+match rubric. Prefer a labeled evaluation set to interpreting a raw probability
+as a guaranteed match rate. The batch preserves order, partial failures and actual
+model IDs. Configure its overall deadline for the entire queue, not just one call.
+
+### Staged decisions and model fallback
+
+The host can first call a routing task, gate its evidence, then call a specialized
+task with `{ originalState, selectedRoute }`. For an uncertain result, explicitly
+invoke another configured decision handle or an existing generation model. Treat
+semantic abstention separately from network failure. Never silently relabel an
+auth/configuration failure as uncertainty. Keep each stage's result for audit.
+
+For a taxonomy, bound depth, model calls and time; optional beam search explores
+several probable branches rather than only the first winner. For candidate
+extraction, let deterministic parsing produce candidates, select among their IDs,
+and verify the chosen value in a second stage. Include `none`/`other` where absence
+is valid. Split independent work into batches; keep dependencies sequential.
+
+## Provider and environment choices
+
+| Consumer | Setup |
+| --- | --- |
+| Node service / agent tool | Lazy `envCredential`, shared runtime/tasks, per-request signal/context |
+| Browser app | Server endpoint holding the key; inject a server-side task behind it |
+| Worker / edge runtime | Inject a key from the host's secret binding or a `CredentialSource`; use Web fetch |
+| Local/self-hosted API | Adapter with `baseUrl`, injected transport, explicit HTTP opt-in for local development |
+| Multiple accounts/endpoints | Multiple TypeSafe plugins with distinct `id` and `routes`; bind a task to each route |
+| Unit tests / offline execution | Register a deterministic `DecisionAdapter` or inject mocked fetch; keep the same task/gate code |
+
+Credential resolution follows the underlying adapter: TypeSafe resolves per physical
+attempt; prepared LLM adapters may capture credentials once per logical call.
+An explicitly configured provider retry policy overrides the runtime default;
+TypeSafe inherits the runtime policy when omitted. Choose one retry owner to avoid compounded attempts. Cancellation
+bounds scheduling and waiting; it does not undo provider processing or host actions.
+No batch cache, automatic fallback, model-specific calibration, business side effects,
+or streaming dataset ingestion is implied by this package.
+
+See TypeSafe's [confidence explanation](https://docs.typesafe.ai/confidence) for
+the distribution statistic behind Choice/Score confidence. A Boolean's probability
+near 0.5 is uncertain; it has no native separate confidence. The kit preserves raw
+evidence and requires explicit gates rather than fabricating a shared metric.
+
+## Use an LLM for the same tasks
+
+Wrap `openAiAdapter`, `anthropicAdapter`, `geminiAdapter` or another SDK model
+adapter in `llmDecisionPlugin`. The [LLM setup example](./README.md#openai-anthropic-and-gemini-decisions)
+registers all three. Keep the rubric and batch/workflow code; change the target
+provider/model to select the implementation. Different providers can coexist with
+TypeSafe in the same decision runtime.
+
+Use JSON Schema by default, or select the tool mode for a compatible endpoint.
+Generation must finish successfully before its answer is accepted; a partially
+valid answer cut off by the token limit is rejected. No format repair or automatic
+fallback is hidden in the adapter. Host cascades can explicitly catch failures or
+handle abstention and invoke a different configured task.
+
+LLM decisions default to values without confidence. For a routing policy that
+needs raw evidence, prefer a provider that supplies it, or explicitly opt into
+`evidence: 'model-generated'` and validate its behavior on your dataset. Existing
+gates abstain on absent evidence and disallow these self-reported estimates by
+default. Configuring structured output does not turn an LLM into a calibrated
+native decision model. A batch may span an alias update; pinned IDs and per-stage
+records help evaluation, while response model IDs are unavailable on this bridge.

package/dist/async-BPqlUFnU.js

@@ -0,0 +1,53 @@
+import { MODEL_ERROR_CODES, ModelError } from "@alvin0/ai-agent-sdk-core";
+
+//#region src/async.ts
+function throwIfAborted(signal) {
+	if (signal.aborted) throw signal.reason instanceof ModelError ? signal.reason : new ModelError("Decision call aborted", MODEL_ERROR_CODES.ABORTED);
+}
+/** Settles promptly even if an extension ignores cancellation; observes its late rejection. */
+function abortable(work, signal) {
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			cleanup();
+			try {
+				throwIfAborted(signal);
+			} catch (error) {
+				reject(error);
+			}
+		};
+		const cleanup = () => signal.removeEventListener("abort", abort);
+		work.then((value) => {
+			cleanup();
+			resolve(value);
+		}, (error) => {
+			cleanup();
+			reject(error);
+		});
+		signal.addEventListener("abort", abort, { once: true });
+		if (signal.aborted) abort();
+	});
+}
+function waitDecisionDelay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		const abort = () => {
+			clearTimeout(timer);
+			cleanup();
+			try {
+				throwIfAborted(signal);
+			} catch (error) {
+				reject(error);
+			}
+		};
+		const cleanup = () => signal.removeEventListener("abort", abort);
+		const timer = setTimeout(() => {
+			cleanup();
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", abort, { once: true });
+		if (signal.aborted) abort();
+	});
+}
+
+//#endregion
+export { throwIfAborted as n, waitDecisionDelay as r, abortable as t };
+//# sourceMappingURL=async-BPqlUFnU.js.map

package/dist/async-BPqlUFnU.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-BPqlUFnU.js","names":[],"sources":["../src/async.ts"],"sourcesContent":["import { ModelError, MODEL_ERROR_CODES } from '@alvin0/ai-agent-sdk-core'\n\nexport function throwIfAborted(signal: AbortSignal): void {\n  if (signal.aborted) throw signal.reason instanceof ModelError ? signal.reason : new ModelError('Decision call aborted', MODEL_ERROR_CODES.ABORTED)\n}\n/** Settles promptly even if an extension ignores cancellation; observes its late rejection. */\nexport function abortable<T>(work: Promise<T>, signal: AbortSignal): Promise<T> {\n  return new Promise<T>((resolve, reject) => {\n    const abort = () => { cleanup(); try { throwIfAborted(signal) } catch (error) { reject(error) } }\n    const cleanup = () => signal.removeEventListener('abort', abort)\n    work.then(value => { cleanup(); resolve(value) }, error => { cleanup(); reject(error) })\n    signal.addEventListener('abort', abort, { once: true })\n    if (signal.aborted) abort()\n  })\n}\nexport function waitDecisionDelay(ms: number, signal: AbortSignal): Promise<void> {\n  return new Promise((resolve, reject) => {\n    const abort = () => { clearTimeout(timer); cleanup(); try { throwIfAborted(signal) } catch (error) { reject(error) } }\n    const cleanup = () => signal.removeEventListener('abort', abort)\n    const timer = setTimeout(() => { cleanup(); resolve() }, ms)\n    signal.addEventListener('abort', abort, { once: true })\n    if (signal.aborted) abort()\n  })\n}\n"],"mappings":";;;AAEA,SAAgB,eAAe,QAA2B;CACxD,IAAI,OAAO,SAAS,MAAM,OAAO,kBAAkB,aAAa,OAAO,SAAS,IAAI,WAAW,yBAAyB,kBAAkB,OAAO;AACnJ;;AAEA,SAAgB,UAAa,MAAkB,QAAiC;CAC9E,OAAO,IAAI,SAAY,SAAS,WAAW;EACzC,MAAM,cAAc;GAAE,QAAQ;GAAG,IAAI;IAAE,eAAe,MAAM;GAAE,SAAS,OAAO;IAAE,OAAO,KAAK;GAAE;EAAE;EAChG,MAAM,gBAAgB,OAAO,oBAAoB,SAAS,KAAK;EAC/D,KAAK,MAAK,UAAS;GAAE,QAAQ;GAAG,QAAQ,KAAK;EAAE,IAAG,UAAS;GAAE,QAAQ;GAAG,OAAO,KAAK;EAAE,CAAC;EACvF,OAAO,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;EACtD,IAAI,OAAO,SAAS,MAAM;CAC5B,CAAC;AACH;AACA,SAAgB,kBAAkB,IAAY,QAAoC;CAChF,OAAO,IAAI,SAAS,SAAS,WAAW;EACtC,MAAM,cAAc;GAAE,aAAa,KAAK;GAAG,QAAQ;GAAG,IAAI;IAAE,eAAe,MAAM;GAAE,SAAS,OAAO;IAAE,OAAO,KAAK;GAAE;EAAE;EACrH,MAAM,gBAAgB,OAAO,oBAAoB,SAAS,KAAK;EAC/D,MAAM,QAAQ,iBAAiB;GAAE,QAAQ;GAAG,QAAQ;EAAE,GAAG,EAAE;EAC3D,OAAO,iBAAiB,SAAS,OAAO,EAAE,MAAM,KAAK,CAAC;EACtD,IAAI,OAAO,SAAS,MAAM;CAC5B,CAAC;AACH"}