refactor(ai): rename llm package

packages/ai/src/protocols/utils/bedrock-auth.ts

@@ -0,0 +1,70 @@
+import { AwsV4Signer } from "aws4fetch"
+import { Effect } from "effect"
+import { Headers } from "effect/unstable/http"
+import { Auth, type AuthInput } from "../../route/auth"
+import { ProviderShared } from "../shared"
+
+/**
+ * AWS credentials for SigV4 signing. Bedrock also supports Bearer API key auth,
+ * which provider facades configure as route auth instead of SigV4. STS-vended
+ * credentials should be refreshed by the consumer (rebuild the model) before
+ * they expire; the route does not refresh.
+ */
+export interface Credentials {
+  readonly region: string
+  readonly accessKeyId: string
+  readonly secretAccessKey: string
+  readonly sessionToken?: string
+}
+
+const signRequest = (input: {
+  readonly url: string
+  readonly body: string
+  readonly headers: Headers.Headers
+  readonly credentials: Credentials
+}) =>
+  Effect.tryPromise({
+    try: async () => {
+      const signed = await new AwsV4Signer({
+        url: input.url,
+        method: "POST",
+        headers: Object.entries(input.headers),
+        body: input.body,
+        region: input.credentials.region,
+        accessKeyId: input.credentials.accessKeyId,
+        secretAccessKey: input.credentials.secretAccessKey,
+        sessionToken: input.credentials.sessionToken,
+        service: "bedrock",
+      }).sign()
+      return Object.fromEntries(signed.headers.entries())
+    },
+    catch: (error) =>
+      ProviderShared.invalidRequest(
+        `Bedrock Converse SigV4 signing failed: ${error instanceof Error ? error.message : String(error)}`,
+      ),
+  })
+
+/** Sign the exact JSON bytes with SigV4 using credentials configured on the route. */
+export const sigV4 = (credentials: Credentials | undefined) =>
+  Auth.custom((input: AuthInput) => {
+    return Effect.gen(function* () {
+      if (!credentials) {
+        return yield* ProviderShared.invalidRequest(
+          "Bedrock Converse requires either route bearer auth or AWS credentials configured on the route",
+        )
+      }
+      const headersForSigning = Headers.set(input.headers, "content-type", "application/json")
+      const signed = yield* signRequest({
+        url: input.url,
+        body: input.body,
+        headers: headersForSigning,
+        credentials,
+      })
+      return Headers.setAll(headersForSigning, signed)
+    })
+  })
+
+/** Bedrock route auth defaults to SigV4 and expects credentials from route configuration. */
+export const auth = sigV4(undefined)
+
+export * as BedrockAuth from "./bedrock-auth"

packages/ai/src/protocols/utils/bedrock-cache.ts

@@ -0,0 +1,37 @@
+import { Schema } from "effect"
+import type { CacheHint } from "../../schema"
+import { newBreakpoints, ttlBucket, type Breakpoints } from "./cache"
+
+// Bedrock cache markers are positional: emit a `cachePoint` block immediately
+// after the content the caller wants treated as a cacheable prefix. Bedrock
+// accepts optional `ttl: "5m" | "1h"` on cachePoint, mirroring Anthropic.
+export const CachePointBlock = Schema.Struct({
+  cachePoint: Schema.Struct({
+    type: Schema.tag("default"),
+    ttl: Schema.optional(Schema.Literals(["5m", "1h"])),
+  }),
+})
+export type CachePointBlock = Schema.Schema.Type<typeof CachePointBlock>
+
+// Bedrock-Claude enforces the same 4-breakpoint cap as the Anthropic Messages
+// API. Callers pass a shared counter through every `block()` call site so the
+// budget is respected across `system`, `messages`, and `tools`.
+export const BEDROCK_BREAKPOINT_CAP = 4
+
+export type { Breakpoints } from "./cache"
+export const breakpoints = () => newBreakpoints(BEDROCK_BREAKPOINT_CAP)
+
+const DEFAULT_5M: CachePointBlock = { cachePoint: { type: "default" } }
+const DEFAULT_1H: CachePointBlock = { cachePoint: { type: "default", ttl: "1h" } }
+
+export const block = (breakpoints: Breakpoints, cache: CacheHint | undefined): CachePointBlock | undefined => {
+  if (cache?.type !== "ephemeral" && cache?.type !== "persistent") return undefined
+  if (breakpoints.remaining <= 0) {
+    breakpoints.dropped += 1
+    return undefined
+  }
+  breakpoints.remaining -= 1
+  return ttlBucket(cache.ttlSeconds) === "1h" ? DEFAULT_1H : DEFAULT_5M
+}
+
+export * as BedrockCache from "./bedrock-cache"

packages/ai/src/protocols/utils/bedrock-media.ts

@@ -0,0 +1,90 @@
+import { Effect, Schema } from "effect"
+import type { MediaPart } from "../../schema"
+import { ProviderShared } from "../shared"
+
+// Bedrock Converse accepts image `format` as the file extension and
+// `source.bytes` as base64 in the JSON wire format.
+export const ImageFormat = Schema.Literals(["png", "jpeg", "gif", "webp"])
+export type ImageFormat = Schema.Schema.Type<typeof ImageFormat>
+
+export const ImageBlock = Schema.Struct({
+  image: Schema.Struct({
+    format: ImageFormat,
+    source: Schema.Struct({ bytes: Schema.String }),
+  }),
+})
+export type ImageBlock = Schema.Schema.Type<typeof ImageBlock>
+
+// Bedrock document blocks require a user-facing name so the model can refer to
+// the uploaded document.
+export const DocumentFormat = Schema.Literals(["pdf", "csv", "doc", "docx", "xls", "xlsx", "html", "txt", "md"])
+export type DocumentFormat = Schema.Schema.Type<typeof DocumentFormat>
+
+export const DocumentBlock = Schema.Struct({
+  document: Schema.Struct({
+    format: DocumentFormat,
+    name: Schema.String,
+    source: Schema.Struct({ bytes: Schema.String }),
+  }),
+})
+export type DocumentBlock = Schema.Schema.Type<typeof DocumentBlock>
+
+const IMAGE_FORMATS = {
+  "image/png": "png",
+  "image/jpeg": "jpeg",
+  "image/jpg": "jpeg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+} as const satisfies Record<string, ImageFormat>
+
+const DOCUMENT_FORMATS = {
+  "application/pdf": "pdf",
+  "text/csv": "csv",
+  "application/msword": "doc",
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": "docx",
+  "application/vnd.ms-excel": "xls",
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": "xlsx",
+  "text/html": "html",
+  "text/plain": "txt",
+  "text/markdown": "md",
+} as const satisfies Record<string, DocumentFormat>
+
+const documentBlock = (part: MediaPart, format: DocumentFormat, bytes: string): DocumentBlock => ({
+  document: {
+    format,
+    name: part.filename ?? `document.${format}`,
+    source: { bytes },
+  },
+})
+
+// Route by MIME. Known image/document formats lower into a typed block; anything
+// else fails with a clear error instead of silently degrading to a malformed
+// document block. Image MIME types not in `IMAGE_FORMATS` (e.g. `image/svg+xml`)
+// get an image-specific error so the caller knows it's a format-support issue,
+// not a kind-detection issue.
+export const lower = Effect.fn("BedrockMedia.lower")(function* (part: MediaPart) {
+  const mime = part.mediaType.toLowerCase()
+  const imageFormat = IMAGE_FORMATS[mime as keyof typeof IMAGE_FORMATS]
+  if (imageFormat) {
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(IMAGE_FORMATS)),
+    )
+    return { image: { format: imageFormat, source: { bytes: media.base64 } } } satisfies ImageBlock
+  }
+  if (mime.startsWith("image/"))
+    return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support image media type ${part.mediaType}`)
+  const documentFormat = DOCUMENT_FORMATS[mime as keyof typeof DOCUMENT_FORMATS]
+  if (documentFormat) {
+    const media = yield* ProviderShared.validateMedia(
+      "Bedrock Converse",
+      part,
+      new Set<string>(Object.keys(DOCUMENT_FORMATS)),
+    )
+    return documentBlock(part, documentFormat, media.base64)
+  }
+  return yield* ProviderShared.invalidRequest(`Bedrock Converse does not support media type ${part.mediaType}`)
+})
+
+export * as BedrockMedia from "./bedrock-media"

packages/ai/src/protocols/utils/cache.ts

@@ -0,0 +1,16 @@
+// Shared helpers for provider cache-marker lowering. Anthropic and Bedrock
+// both enforce a 4-breakpoint cap per request and accept the same `5m`/`1h`
+// TTL buckets, so the counter and TTL mapping live here.
+
+export interface Breakpoints {
+  remaining: number
+  dropped: number
+}
+
+export const newBreakpoints = (cap: number): Breakpoints => ({ remaining: cap, dropped: 0 })
+
+// Returns `"1h"` for any `ttlSeconds >= 3600`, otherwise `undefined` (the
+// provider default 5m). Anthropic & Bedrock both treat anything shorter than
+// an hour as 5m.
+export const ttlBucket = (ttlSeconds: number | undefined): "1h" | undefined =>
+  ttlSeconds !== undefined && ttlSeconds >= 3600 ? "1h" : undefined

packages/ai/src/protocols/utils/gemini-tool-schema.ts

@@ -0,0 +1,99 @@
+import { isRecord } from "../../utils/record"
+
+// Gemini accepts a JSON Schema-like dialect for tool parameters, but rejects a
+// handful of common JSON Schema shapes. Keep this projection isolated so the
+// Gemini protocol file still reads like the other protocol modules.
+const SCHEMA_INTENT_KEYS = [
+  "type",
+  "properties",
+  "items",
+  "prefixItems",
+  "enum",
+  "const",
+  "$ref",
+  "additionalProperties",
+  "patternProperties",
+  "required",
+  "not",
+  "if",
+  "then",
+  "else",
+]
+
+const hasCombiner = (schema: unknown) =>
+  isRecord(schema) && (Array.isArray(schema.anyOf) || Array.isArray(schema.oneOf) || Array.isArray(schema.allOf))
+
+const hasSchemaIntent = (schema: unknown) =>
+  isRecord(schema) && (hasCombiner(schema) || SCHEMA_INTENT_KEYS.some((key) => key in schema))
+
+const sanitizeNode = (schema: unknown): unknown => {
+  if (!isRecord(schema)) return Array.isArray(schema) ? schema.map(sanitizeNode) : schema
+
+  const result: Record<string, unknown> = Object.fromEntries(
+    Object.entries(schema).map(([key, value]) => [
+      key,
+      key === "enum" && Array.isArray(value) ? value.map(String) : sanitizeNode(value),
+    ]),
+  )
+
+  if (Array.isArray(result.enum) && (result.type === "integer" || result.type === "number")) result.type = "string"
+
+  const properties = result.properties
+  if (result.type === "object" && isRecord(properties) && Array.isArray(result.required)) {
+    result.required = result.required.filter((field) => typeof field === "string" && field in properties)
+  }
+
+  if (result.type === "array" && !hasCombiner(result)) {
+    result.items = result.items ?? {}
+    if (isRecord(result.items) && !hasSchemaIntent(result.items)) result.items = { ...result.items, type: "string" }
+  }
+
+  if (typeof result.type === "string" && result.type !== "object" && !hasCombiner(result)) {
+    delete result.properties
+    delete result.required
+  }
+
+  return result
+}
+
+const emptyObjectSchema = (schema: Record<string, unknown>) =>
+  schema.type === "object" &&
+  (!isRecord(schema.properties) || Object.keys(schema.properties).length === 0) &&
+  !schema.additionalProperties
+
+const projectNode = (schema: unknown): Record<string, unknown> | undefined => {
+  if (!isRecord(schema)) return undefined
+  if (emptyObjectSchema(schema)) return undefined
+  return Object.fromEntries(
+    [
+      ["description", schema.description],
+      ["required", schema.required],
+      ["format", schema.format],
+      ["type", Array.isArray(schema.type) ? schema.type.filter((type) => type !== "null")[0] : schema.type],
+      ["nullable", Array.isArray(schema.type) && schema.type.includes("null") ? true : undefined],
+      ["enum", schema.const !== undefined ? [schema.const] : schema.enum],
+      [
+        "properties",
+        isRecord(schema.properties)
+          ? Object.fromEntries(Object.entries(schema.properties).map(([key, value]) => [key, projectNode(value)]))
+          : undefined,
+      ],
+      [
+        "items",
+        Array.isArray(schema.items)
+          ? schema.items.map(projectNode)
+          : schema.items === undefined
+            ? undefined
+            : projectNode(schema.items),
+      ],
+      ["allOf", Array.isArray(schema.allOf) ? schema.allOf.map(projectNode) : undefined],
+      ["anyOf", Array.isArray(schema.anyOf) ? schema.anyOf.map(projectNode) : undefined],
+      ["oneOf", Array.isArray(schema.oneOf) ? schema.oneOf.map(projectNode) : undefined],
+      ["minLength", schema.minLength],
+    ].filter((entry) => entry[1] !== undefined),
+  )
+}
+
+export const convert = (schema: unknown) => projectNode(sanitizeNode(schema))
+
+export * as GeminiToolSchema from "./gemini-tool-schema"

packages/ai/src/protocols/utils/lifecycle.ts

@@ -0,0 +1,102 @@
+import { LLMEvent, type FinishReason, type ProviderMetadata, type Usage } from "../../schema"
+
+export interface State {
+  readonly stepStarted: boolean
+  readonly text: ReadonlySet<string>
+  readonly reasoning: ReadonlySet<string>
+}
+
+export const initial = (): State => ({ stepStarted: false, text: new Set(), reasoning: new Set() })
+
+export const stepStart = (state: State, events: LLMEvent[]): State => {
+  if (state.stepStarted) return state
+  events.push(LLMEvent.stepStart({ index: 0 }))
+  return { ...state, stepStarted: true }
+}
+
+export const textDelta = (state: State, events: LLMEvent[], id: string, text: string): State => {
+  const stepped = stepStart(state, events)
+  if (stepped.text.has(id)) {
+    events.push(LLMEvent.textDelta({ id, text }))
+    return stepped
+  }
+  events.push(LLMEvent.textStart({ id }), LLMEvent.textDelta({ id, text }))
+  return { ...stepped, text: new Set([...stepped.text, id]) }
+}
+
+export const reasoningStart = (
+  state: State,
+  events: LLMEvent[],
+  id: string,
+  providerMetadata?: ProviderMetadata,
+): State => {
+  if (state.reasoning.has(id)) return state
+  const stepped = stepStart(state, events)
+  events.push(LLMEvent.reasoningStart({ id, providerMetadata }))
+  return { ...stepped, reasoning: new Set([...stepped.reasoning, id]) }
+}
+
+export const reasoningDelta = (
+  state: State,
+  events: LLMEvent[],
+  id: string,
+  text: string,
+  providerMetadata?: ProviderMetadata,
+): State => {
+  const started = reasoningStart(state, events, id, providerMetadata)
+  events.push(LLMEvent.reasoningDelta({ id, text }))
+  return started
+}
+
+export const reasoningEnd = (
+  state: State,
+  events: LLMEvent[],
+  id: string,
+  providerMetadata?: ProviderMetadata,
+): State => {
+  if (!state.reasoning.has(id)) return state
+  const stepped = stepStart(state, events)
+  events.push(LLMEvent.reasoningEnd({ id, providerMetadata }))
+  const reasoning = new Set(stepped.reasoning)
+  reasoning.delete(id)
+  return { ...stepped, reasoning }
+}
+
+export const textEnd = (state: State, events: LLMEvent[], id: string, providerMetadata?: ProviderMetadata): State => {
+  if (!state.text.has(id)) return state
+  const stepped = stepStart(state, events)
+  events.push(LLMEvent.textEnd({ id, providerMetadata }))
+  const text = new Set(stepped.text)
+  text.delete(id)
+  return { ...stepped, text }
+}
+
+const closeOpenBlocks = (state: State, events: LLMEvent[]): State => {
+  for (const id of state.reasoning) events.push(LLMEvent.reasoningEnd({ id }))
+  for (const id of state.text) events.push(LLMEvent.textEnd({ id }))
+  return { ...state, text: new Set(), reasoning: new Set() }
+}
+
+export const finish = (
+  state: State,
+  events: LLMEvent[],
+  input: {
+    readonly reason: FinishReason
+    readonly usage?: Usage
+    readonly providerMetadata?: ProviderMetadata
+  },
+): State => {
+  const stepped = closeOpenBlocks(stepStart(state, events), events)
+  events.push(
+    LLMEvent.stepFinish({
+      index: 0,
+      reason: input.reason,
+      usage: input.usage,
+      providerMetadata: input.providerMetadata,
+    }),
+    LLMEvent.finish(input),
+  )
+  return { ...stepped, stepStarted: false }
+}
+
+export * as Lifecycle from "./lifecycle"

packages/ai/src/protocols/utils/openai-options.ts

@@ -0,0 +1,85 @@
+import { Schema } from "effect"
+import type { LLMRequest, TextVerbosity as TextVerbosityValue } from "../../schema"
+import { ReasoningEfforts, TextVerbosity } from "../../schema"
+
+export const OpenAIReasoningEfforts = ReasoningEfforts
+export type OpenAIReasoningEffort = string
+
+// Mirrors OpenAI's `ResponseIncludable` union from the official SDK. Keep this
+// in lockstep with `openai-node/src/resources/responses/responses.ts`.
+export const OpenAIResponseIncludables = [
+  "file_search_call.results",
+  "web_search_call.results",
+  "web_search_call.action.sources",
+  "message.input_image.image_url",
+  "computer_call_output.output.image_url",
+  "code_interpreter_call.outputs",
+  "reasoning.encrypted_content",
+  "message.output_text.logprobs",
+] as const
+export type OpenAIResponseIncludable = (typeof OpenAIResponseIncludables)[number]
+export const OpenAIServiceTiers = ["auto", "default", "flex", "priority"] as const
+export type OpenAIServiceTier = (typeof OpenAIServiceTiers)[number]
+
+const TEXT_VERBOSITY = new Set<string>(["low", "medium", "high"])
+const INCLUDABLES = new Set<string>(OpenAIResponseIncludables)
+const SERVICE_TIERS = new Set<string>(OpenAIServiceTiers)
+
+export const OpenAIReasoningEffort = Schema.String
+export const OpenAITextVerbosity = TextVerbosity
+export const OpenAIResponseIncludable = Schema.Literals(OpenAIResponseIncludables)
+export const OpenAIServiceTier = Schema.Literals(OpenAIServiceTiers)
+
+export const isReasoningEffort = (effort: unknown): effort is OpenAIReasoningEffort => typeof effort === "string"
+
+const isTextVerbosity = (value: unknown): value is TextVerbosityValue =>
+  typeof value === "string" && TEXT_VERBOSITY.has(value)
+
+const options = (request: LLMRequest) => request.providerOptions?.openai
+
+export const store = (request: LLMRequest): boolean | undefined => {
+  const value = options(request)?.store
+  return typeof value === "boolean" ? value : undefined
+}
+
+export const reasoningEffort = (request: LLMRequest): string | undefined => {
+  const value = options(request)?.reasoningEffort
+  return typeof value === "string" ? value : undefined
+}
+
+export const reasoningSummary = (request: LLMRequest): "auto" | undefined =>
+  options(request)?.reasoningSummary === "auto" ? "auto" : undefined
+
+// Resolve the OpenAI Responses `include` field. Filters out unknown
+// includable values defensively so a typo in upstream config drops the
+// invalid entry instead of poisoning the wire body. An empty array (either
+// passed directly or produced by filtering) is treated as "no include" and
+// returns undefined so the request body omits the field entirely.
+export const include = (request: LLMRequest): ReadonlyArray<OpenAIResponseIncludable> | undefined => {
+  const value = options(request)?.include
+  if (!Array.isArray(value)) return undefined
+  const filtered = value.filter((entry): entry is OpenAIResponseIncludable => INCLUDABLES.has(entry))
+  return filtered.length > 0 ? filtered : undefined
+}
+
+export const promptCacheKey = (request: LLMRequest) => {
+  const value = options(request)?.promptCacheKey
+  return typeof value === "string" ? value : undefined
+}
+
+export const textVerbosity = (request: LLMRequest) => {
+  const value = options(request)?.textVerbosity
+  return isTextVerbosity(value) ? value : undefined
+}
+
+export const serviceTier = (request: LLMRequest) => {
+  const value = options(request)?.serviceTier
+  return typeof value === "string" && SERVICE_TIERS.has(value) ? (value as OpenAIServiceTier) : undefined
+}
+
+export const instructions = (request: LLMRequest) => {
+  const value = options(request)?.instructions
+  return typeof value === "string" ? value : undefined
+}
+
+export * as OpenAIOptions from "./openai-options"

packages/ai/src/protocols/utils/tool-schema.ts

@@ -0,0 +1,86 @@
+import type { JsonSchema, ModelToolSchemaCompatibility } from "../../schema"
+import { isRecord } from "../../utils/record"
+import { GeminiToolSchema } from "./gemini-tool-schema"
+
+const removeNullSchemas = (value: unknown): unknown => {
+  if (Array.isArray(value)) return value.map(removeNullSchemas)
+  if (!isRecord(value)) return value
+  const fields = Object.fromEntries(
+    Object.entries(value)
+      .filter(([key]) => key !== "anyOf")
+      .map(([key, field]) => [key, removeNullSchemas(field)]),
+  )
+  if (!Array.isArray(value.anyOf)) return fields
+  const variants = value.anyOf.filter((variant) => !isRecord(variant) || variant.type !== "null").map(removeNullSchemas)
+  if (variants.length === 1 && isRecord(variants[0])) return { ...fields, ...variants[0] }
+  return { ...fields, anyOf: variants }
+}
+
+const tupleItemsSchema = (items: ReadonlyArray<unknown>) => {
+  const projected = items.map(moonshotNode)
+  if (projected.length === 0) return {}
+  if (projected.length === 1) return projected[0]
+  return { anyOf: projected }
+}
+
+const moonshotNode = (schema: unknown): unknown => {
+  if (Array.isArray(schema)) return schema.map(moonshotNode)
+  if (!isRecord(schema)) return schema
+  if (typeof schema.$ref === "string") return { $ref: schema.$ref }
+  return Object.fromEntries(
+    Object.entries(schema).flatMap(([key, value]) => {
+      if (key === "items" && Array.isArray(value)) return [[key, tupleItemsSchema(value)]]
+      if (key === "prefixItems") {
+        if ("items" in schema) return []
+        return [["items", tupleItemsSchema(Array.isArray(value) ? value : [])]]
+      }
+      if (key === "unevaluatedItems") return []
+      return [[key, moonshotNode(value)]]
+    }),
+  )
+}
+
+const moonshot = (schema: JsonSchema): JsonSchema => {
+  const projected = moonshotNode(schema)
+  return isRecord(projected) ? projected : {}
+}
+
+const openAI = (schema: JsonSchema): JsonSchema => {
+  const variants = Array.isArray(schema.anyOf) ? schema.anyOf.filter(isRecord) : []
+  const flattened =
+    variants.length === 0
+      ? { ...schema, type: "object" }
+      : {
+          ...Object.fromEntries(Object.entries(schema).filter(([key]) => key !== "anyOf")),
+          type: "object",
+          properties: variants.reduce(
+            (properties, variant) => ({ ...(isRecord(variant.properties) ? variant.properties : {}), ...properties }),
+            {},
+          ),
+          additionalProperties: false,
+        }
+  const normalized = removeNullSchemas(flattened)
+  return isRecord(normalized) ? normalized : { type: "object" }
+}
+
+const gemini = (schema: JsonSchema): JsonSchema => GeminiToolSchema.convert(schema) ?? {}
+
+const modelCompatibility = (
+  schema: JsonSchema,
+  compatibility: ModelToolSchemaCompatibility | undefined,
+): JsonSchema => {
+  if (compatibility === undefined) return schema
+  switch (compatibility) {
+    case "gemini":
+      return gemini(schema)
+    case "moonshot":
+      return moonshot(schema)
+  }
+}
+
+export const ToolSchemaProjection = {
+  gemini,
+  modelCompatibility,
+  moonshot,
+  openAI,
+} as const

packages/ai/src/protocols/utils/tool-stream.ts

@@ -0,0 +1,218 @@
+import { Effect } from "effect"
+import { LLMError, LLMEvent, type ProviderMetadata, type ToolCall } from "../../schema"
+import { eventError, parseToolInput, type ToolAccumulator } from "../shared"
+
+type StreamKey = string | number
+
+/**
+ * One pending streamed tool call. Providers emit the tool identity and JSON
+ * argument text across separate chunks; `input` is the raw JSON string collected
+ * so far, not the parsed object.
+ */
+export interface PendingTool extends ToolAccumulator {
+  readonly providerExecuted?: boolean
+  readonly providerMetadata?: ProviderMetadata
+}
+
+/**
+ * Sparse parser state keyed by the provider's stream-local tool identifier.
+ *
+ * This key is not the final tool-call id (`call_...`). It is the id/index the
+ * provider uses while streaming a partial call: OpenAI Chat / Anthropic /
+ * Bedrock use numeric content indexes, while OpenAI Responses uses string
+ * `item_id`s. The generic keeps each protocol internally consistent.
+ */
+export type State<K extends StreamKey> = Partial<Record<K, PendingTool>>
+
+/**
+ * Result of adding argument text to one pending tool call. It returns both the
+ * next `tools` state and the updated `tool` because parsers often need the
+ * current id/name immediately. `events` contains lifecycle and delta events
+ * produced by the append; metadata-only deltas update identity without output.
+ */
+export interface AppendOutcome<K extends StreamKey> {
+  readonly tools: State<K>
+  readonly tool: PendingTool
+  readonly events: ReadonlyArray<LLMEvent>
+}
+
+/** Create empty accumulator state for one provider stream. */
+export const empty = <K extends StreamKey>(): State<K> => ({})
+
+const withTool = <K extends StreamKey>(tools: State<K>, key: K, tool: PendingTool): State<K> => {
+  return { ...tools, [key]: tool }
+}
+
+const withoutTool = <K extends StreamKey>(tools: State<K>, key: K): State<K> => {
+  const next = { ...tools }
+  delete next[key]
+  return next
+}
+
+const inputStart = (tool: PendingTool) =>
+  LLMEvent.toolInputStart({
+    id: tool.id,
+    name: tool.name,
+    providerMetadata: tool.providerMetadata,
+  })
+
+const inputDelta = (tool: PendingTool, text: string) =>
+  LLMEvent.toolInputDelta({
+    id: tool.id,
+    name: tool.name,
+    text,
+  })
+
+const toolCall = (route: string, tool: PendingTool, inputOverride?: string) =>
+  parseToolInput(route, tool.name, inputOverride ?? tool.input).pipe(
+    Effect.map(
+      (input): ToolCall =>
+        LLMEvent.toolCall({
+          id: tool.id,
+          name: tool.name,
+          input,
+          providerExecuted: tool.providerExecuted ? true : undefined,
+          providerMetadata: tool.providerMetadata,
+        }),
+    ),
+  )
+
+/** Store the updated tool and produce the optional public delta event. */
+const appendTool = <K extends StreamKey>(
+  tools: State<K>,
+  key: K,
+  tool: PendingTool,
+  text: string,
+): AppendOutcome<K> => {
+  const events: LLMEvent[] = []
+  if (!tools[key]) events.push(inputStart(tool))
+  if (text.length > 0) events.push(inputDelta(tool, text))
+  return {
+    tools: withTool(tools, key, tool),
+    tool,
+    events,
+  }
+}
+
+export const isError = <K extends StreamKey>(result: AppendOutcome<K> | LLMError): result is LLMError =>
+  result instanceof LLMError
+
+/**
+ * Register a tool call whose start event arrived before any argument deltas.
+ * Used by Anthropic `content_block_start`, Bedrock `contentBlockStart`, and
+ * OpenAI Responses `response.output_item.added`.
+ */
+export const start = <K extends StreamKey>(
+  tools: State<K>,
+  key: K,
+  tool: Omit<PendingTool, "input"> & { readonly input?: string },
+) => withTool(tools, key, { ...tool, input: tool.input ?? "" })
+
+/**
+ * Append a streamed argument delta, starting the tool if this provider encodes
+ * identity on the first delta instead of a separate start event. OpenAI Chat has
+ * this shape: `tool_calls[].index` is the stream key, and `id` / `name` may only
+ * appear on the first delta for that index.
+ */
+export const appendOrStart = <K extends StreamKey>(
+  route: string,
+  tools: State<K>,
+  key: K,
+  delta: { readonly id?: string; readonly name?: string; readonly text: string },
+  missingToolMessage: string,
+): AppendOutcome<K> | LLMError => {
+  const current = tools[key]
+  const id = delta.id ?? current?.id
+  const name = delta.name ?? current?.name
+  if (!id || !name) return eventError(route, missingToolMessage)
+
+  const tool = {
+    id,
+    name,
+    input: `${current?.input ?? ""}${delta.text}`,
+    providerExecuted: current?.providerExecuted,
+    providerMetadata: current?.providerMetadata,
+  }
+  if (current && delta.text.length === 0 && current.id === id && current.name === name)
+    return { tools, tool: current, events: [] }
+  return appendTool(tools, key, tool, delta.text)
+}
+
+/**
+ * Append argument text to a tool that must already have been started. This keeps
+ * protocols honest when their stream grammar promises a start event before any
+ * argument delta.
+ */
+export const appendExisting = <K extends StreamKey>(
+  route: string,
+  tools: State<K>,
+  key: K,
+  text: string,
+  missingToolMessage: string,
+): AppendOutcome<K> | LLMError => {
+  const current = tools[key]
+  if (!current) return eventError(route, missingToolMessage)
+  if (text.length === 0) return { tools, tool: current, events: [] }
+  return appendTool(tools, key, { ...current, input: `${current.input}${text}` }, text)
+}
+
+/**
+ * Finalize one pending tool call: parse the accumulated raw JSON, remove it
+ * from state, and return the optional public `tool-call` event. Missing keys are
+ * a no-op because some providers emit stop events for non-tool content blocks.
+ */
+export const finish = <K extends StreamKey>(route: string, tools: State<K>, key: K) =>
+  Effect.gen(function* () {
+    const tool = tools[key]
+    if (!tool) return { tools }
+    return {
+      tools: withoutTool(tools, key),
+      events: [
+        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+        yield* toolCall(route, tool),
+      ],
+    }
+  })
+
+/**
+ * Finalize one pending tool call with an authoritative final input string.
+ * OpenAI Responses can send accumulated deltas and then repeat the completed
+ * arguments on `response.output_item.done`; the final value wins.
+ */
+export const finishWithInput = <K extends StreamKey>(route: string, tools: State<K>, key: K, input: string) =>
+  Effect.gen(function* () {
+    const tool = tools[key]
+    if (!tool) return { tools }
+    return {
+      tools: withoutTool(tools, key),
+      events: [
+        LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+        yield* toolCall(route, tool, input),
+      ],
+    }
+  })
+
+/**
+ * Finalize every pending tool call at once. OpenAI Chat has this shape: it does
+ * not emit per-tool stop events, so all accumulated calls finish when the choice
+ * receives a terminal `finish_reason`.
+ */
+export const finishAll = <K extends StreamKey>(route: string, tools: State<K>) =>
+  Effect.gen(function* () {
+    const pending = Object.values<PendingTool | undefined>(tools).filter(
+      (tool): tool is PendingTool => tool !== undefined,
+    )
+    return {
+      tools: empty<K>(),
+      events: yield* Effect.forEach(pending, (tool) =>
+        toolCall(route, tool).pipe(
+          Effect.map((call) => [
+            LLMEvent.toolInputEnd({ id: tool.id, name: tool.name, providerMetadata: tool.providerMetadata }),
+            call,
+          ]),
+        ),
+      ).pipe(Effect.map((events) => events.flat())),
+    }
+  })
+
+export * as ToolStream from "./tool-stream"