@arnilo/prism 0.0.8 → 0.0.11

package/docs/provider-conformance.md

@@ -45,7 +45,7 @@ Helpers accept normal `AIProvider`, `ProviderRequest`, `ProviderEvent`, `Usage`,
 - `collectProviderEvents()` returns provider events in stream order.
 - `assertProviderStreamConforms()` returns collected events after verifying the stream ends with `done` or `error`, terminal events are last, and optional text/usage expectations match.
 - `assertAbortIsObserved()` passes an already-aborted signal and expects provider generation to reject. This is the supported timeout primitive; use a host abort controller or `RunOptions.signal` rather than deprecated provider-level `timeoutMs`.
-- `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments. The runtime uses the same reconstruction behavior before tool execution when a provider streams deltas.
+- `assertToolCallDeltasReconstruct()` rebuilds streamed `tool_call_delta` fragments into tool calls and validates expected id/name/arguments. Malformed JSON with id+name present yields `argumentsError` (no throw); missing id/name throws typed `incomplete_delta`. The runtime uses the same reconstruction before tool execution when a provider streams deltas.
 - `assertUsageAccounting()` finds `usage` or `done.usage` and checks selected token fields including `cacheReadTokens` and `cacheWriteTokens`. This is the provider-neutral check for normalized cache read/write token extraction; every first-party provider package exercises it against server-specific fields (`cached_tokens`, `cache_read_input_tokens`, etc.).
 - `assertSerializedRequestCoversContent()` scans a serialized provider request body for primitive canaries from each Prism content block and fails if any supported block type is silently dropped. Provider-valid transcripts place assistant `tool_call` messages before matching role `tool` `tool_result` messages; runtime, cache-aware input layout, and observational-memory worker loops preserve that order before serialization.
 - `assertProviderOwnedHeadersWin()` compares captured request headers against the provider's authoritative owned header values and a caller-supplied header bag; it fails if any owned header (`authorization`, `content-type`, session/security headers) was overridden by caller headers, and also fails if a non-owned caller header was dropped. This is the provider-neutral check that caller `ProviderRequest.options.headers` cannot hijack provider credentials or sessions; every first-party provider package exercises it.

package/docs/provider-packages.md

@@ -67,7 +67,7 @@ Phase 6 also adds optional [`@arnilo/prism-provider-ai-sdk`](providers/ai-sdk.md
 
 Provider live tests are real smoke tests gated by `PRISM_LIVE_PROVIDER_TESTS=1` plus the provider-specific API key (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, `KIMI_API_KEY`, `ZAI_API_KEY`, `NEURALWATT_API_KEY`, or `OPENCODE_API_KEY`). They cover text generation, tool-call loop behavior, abort/error paths where supported, and no-secret-leak assertions; they skip by default and never run in release verification.
 
-These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation.
+These workspaces still follow the same rule as external packages: no provider SDK dependency, catalog fetch, env scan, keychain/file credential lookup, shell auth command, OAuth login, or live provider call runs by default. `@arnilo/prism-provider-openai` now registers OpenAI Responses and OpenAI Codex providers from caller-supplied credentials only, with optional `models`/`codexModels` overrides and an opt-in `listOpenAIModels()` helper for official `GET /models` discovery. `@arnilo/prism-provider-opencode-go` now registers docs-verified OpenCode Go open coding models with dual OpenAI/Anthropic routes (`compat.route`), official default base `https://opencode.ai/zen/go/v1`, `reasoning_content`/thinking preserve, and an opt-in `listOpenCodeGoModels()` helper for official `GET /zen/go/v1/models`. `@arnilo/prism-provider-openrouter` now registers an app-controlled OpenRouter catalog with routing/`reasoning`/cache passthrough, assistant `reasoning` replay, optional top-level automatic `cache_control`, and an opt-in `listOpenRouterModels()` helper for official `GET /api/v1/models` (setup still never fetches). `@arnilo/prism-provider-zai` now registers featured GLM-5.x/4.x metadata with official `thinking`/`reasoning_effort`/`tool_stream`/`clear_thinking` mapping, Preserved Thinking `reasoning_content` replay, implicit context caching, and an opt-in `listZaiModels()` helper for OpenAI-compatible `GET /models`. `@arnilo/prism-provider-kimi` now registers Kimi Coding Anthropic-compatible behavior by default, optional callable Moonshot Open Platform Chat Completions when `includeMoonshotModels` is requested, official Coding/Open Platform featured ids, thinking/`reasoning_effort` compat mapping, and an opt-in `listKimiModels()` helper for Moonshot `GET /v1/models`. `@arnilo/prism-provider-neuralwatt` now registers static featured model metadata with NeuralWatt reasoning_effort/thinking_token_budget/chat_template_kwargs request mapping, SSE comment tolerance, an opt-in `listNeuralWattModels()` helper for explicit `/v1/models` discovery, `getNeuralWattQuota()` for on-demand account balance/usage/energy, `neuralWattEventsWithTelemetry()`/`mapNeuralWattTelemetry()` for `: energy`/`: cost` telemetry, and `classifyNeuralWattError()` for retry classification. None of these helpers run during package setup or generation. `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity deferred). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md). `@arnilo/prism-provider-anthropic` registers native Anthropic Messages (`createAnthropicProviderPackage` / `listAnthropicModels`). `@arnilo/prism-provider-google` registers native Gemini `generateContent` streaming (`createGoogleProviderPackage` / `listGoogleModels`; Vertex identity deferred). Both follow the same zero-setup-network / host-owned credential / provider-owned-header rules; see [`docs/providers/anthropic.md`](providers/anthropic.md) and [`docs/providers/google.md`](providers/google.md).
 
 ### First-party cache behavior
 

package/docs/provider-primitives.md

@@ -110,7 +110,7 @@ export interface SseEvent {
 }
 
 export class ProviderTransportError extends Error {
-  readonly code: "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted";
+  readonly code: "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta";
   readonly limitBytes?: number;
 }
 
@@ -131,6 +131,12 @@ export function parseJsonObjectArguments(
   text: string,
   options?: { toolName?: string; maxBytes?: number },
 ): JsonObject;
+
+/** Non-throwing variant for recoverable tool-call recovery; prefer with \`toolCallFromArgumentsText\`. */
+export function tryParseJsonObjectArguments(
+  text: string,
+  options?: { toolName?: string; maxBytes?: number },
+): { ok: true; value: JsonObject } | { ok: false; error: ProviderTransportError };
 ```
 
 **Performance:** Single pass over chunks; retained memory is `O(min(buffer, maxBufferBytes))`, not `O(stream)`. No full-stream accumulation.

package/docs/providers/anthropic.md

@@ -0,0 +1,92 @@
+# Anthropic provider package
+
+## What it does
+
+`@arnilo/prism-provider-anthropic` is the first-party Anthropic Messages provider for Prism (`POST /v1/messages`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Wire format is package-local (OpenCode Go / Kimi Anthropic routes are pattern-only, not a shared core serializer).
+
+## When to use it
+
+Use for native Claude Messages (tools, `cache_control`, thinking/reasoning, media, usage, abort). Prefer this over the AI SDK escape hatch when Anthropic is a primary coding host.
+
+Do **not** use for OpenCode Go Anthropic *route* hosting (`@arnilo/prism-provider-opencode-go`) or automatic credential discovery.
+
+## Inputs / request
+
+```ts
+import {
+  createAnthropicProviderPackage,
+  createAnthropicMessagesProvider,
+  listAnthropicModels,
+  defineAnthropicModel,
+} from "@arnilo/prism-provider-anthropic";
+
+createAnthropicProviderPackage(options?: AnthropicProviderPackageOptions): ProviderPackage
+createAnthropicMessagesProvider(options?): AIProvider
+listAnthropicModels(options?: ListAnthropicModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Host-owned Anthropic API key (late-bound). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Override default `https://api.anthropic.com`. |
+| `id` | `string` | Provider id (default `anthropic`). |
+| `userAgent` | `string` | Optional User-Agent. |
+| `models` | `readonly ModelConfig[]` | Override featured offline models. |
+
+Featured offline aliases: `claude-opus-4-8`, `claude-sonnet-5`, `claude-haiku-4-5`, `claude-fable-5`. Caller-gated discovery: `listAnthropicModels()` — never during setup.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text, thinking deltas, tool-call delta/final, usage (incl. cache read/create when present), `done`, redacted `error`. |
+| Cache | Featured models use `cache.kind: "cache_control"`; markers on selected breakpoints (`long` → `ttl: "1h"`). |
+| Thinking | Model-family aware (`adaptive` vs `enabled`+`budget_tokens`); helpers `anthropicThinking` / `anthropicEffort` / `anthropicPreserveThinking`. |
+| Auth | `api_key` for provider id; provider-owned `content-type`, `x-api-key`, `anthropic-version` win over caller headers. |
+
+## Request/response example
+
+```json
+{
+  "model": "claude-sonnet-5",
+  "messages": [{ "role": "user", "content": [{ "type": "text", "text": "Hello" }] }],
+  "stream": true,
+  "max_tokens": 1024
+}
+```
+
+## Implementation example
+
+```ts
+import { createProviderRegistry, createModelRegistry } from "@arnilo/prism";
+import { createAnthropicProviderPackage, listAnthropicModels } from "@arnilo/prism-provider-anthropic";
+
+const api = /* ExtensionAPI or host registries */;
+api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey }));
+
+// Optional: caller-gated catalog refresh
+const models = await listAnthropicModels({ apiKey: hostKey });
+api.registerProviderPackage(createAnthropicProviderPackage({ apiKey: hostKey, models }));
+```
+
+## Extension and configuration notes
+
+- Register via `defineProviderPackage` / host registries; no package auto-discovery.
+- AI SDK (`@arnilo/prism-provider-ai-sdk`) remains an escape hatch, not the primary Anthropic path.
+- Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `ANTHROPIC_API_KEY`.
+
+## Security and performance notes
+
+- No network during import/setup/default tests; credentials host-owned and late-bound.
+- Provider-owned auth headers cannot be overridden by caller headers.
+- Media/SSRF bounds reuse `@arnilo/prism/providers/media` / transport helpers.
+- Offline conformance: `@arnilo/prism/testing/provider-conformance`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): package setup + discovery contract.
+- [Provider caching](../provider-caching.md): `cache_control` breakpoints.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
+- [Provider conformance](../provider-conformance.md): network-free assertions.
+- Package README: [`packages/provider-anthropic/README.md`](../../packages/provider-anthropic/README.md)

package/docs/providers/google.md

@@ -0,0 +1,87 @@
+# Google provider package
+
+## What it does
+
+`@arnilo/prism-provider-google` is the first-party Gemini `generateContent` / `streamGenerateContent` provider for Prism (`POST /v1beta/models/{model}:streamGenerateContent?alt=sse`). Setup is side-effect-free: no network, env scan, or keychain lookup during import/setup. Uses native `fetch` + SSE — no `@google/genai` runtime dependency.
+
+## When to use it
+
+Use for first-party Gemini Developer API coding-host semantics (function calling, multimodal `inlineData`, thinking, usage, abort). Prefer this over the AI SDK escape hatch when Gemini is a primary host.
+
+Do **not** use for Vertex enterprise identity (deferred to 0.0.13+) or as a substitute for Anthropic Messages.
+
+## Inputs / request
+
+```ts
+import {
+  createGoogleProviderPackage,
+  createGoogleGenerateContentProvider,
+  listGoogleModels,
+  defineGoogleModel,
+} from "@arnilo/prism-provider-google";
+
+createGoogleProviderPackage(options?: GoogleProviderPackageOptions): ProviderPackage
+createGoogleGenerateContentProvider(options?): AIProvider
+listGoogleModels(options?: ListGoogleModelsOptions): Promise<ModelConfig[]>
+```
+
+| Field | Type | Purpose |
+| --- | --- | --- |
+| `apiKey` | `CredentialValueSource` | Host-owned Google/Gemini API key (late-bound). |
+| `fetch` | `typeof fetch` | Optional fetch for tests/hosts. |
+| `baseUrl` | `string` | Override default Gemini REST base. |
+| `id` | `string` | Provider id (default `google`). |
+| `userAgent` | `string` | Optional User-Agent. |
+| `models` | `readonly ModelConfig[]` | Override featured offline models. |
+
+Featured offline aliases include `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.5-flash-lite`, and `gemini-3.5-flash` (see package README for the live curated list). Caller-gated discovery: `listGoogleModels()` — never during setup. Model ids may arrive prefixed with `models/`; Prism strips the prefix.
+
+## Outputs / response / events
+
+| Surface | Behavior |
+| --- | --- |
+| Stream | Prism text, thinking when present, **complete** `tool_call` events (Gemini does not stream argument deltas), usage, `done`, redacted `error`. |
+| Cache | No Anthropic-style `cache_control`; Gemini implicit caching is not exposed as Prism breakpoints in 0.0.11. |
+| Multimodal | `inlineData` parts with MIME + base64; capability checks fail closed for unsupported modalities. |
+| Auth | `api_key`; provider-owned `content-type` + `x-goog-api-key` win over caller headers. |
+
+## Request/response example
+
+```json
+{
+  "contents": [{ "role": "user", "parts": [{ "text": "Hello" }] }],
+  "tools": [{ "functionDeclarations": [{ "name": "lookup", "parameters": { "type": "object" } }] }]
+}
+```
+
+## Implementation example
+
+```ts
+import { createGoogleProviderPackage, listGoogleModels } from "@arnilo/prism-provider-google";
+
+api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey }));
+
+const models = await listGoogleModels({ apiKey: hostKey });
+api.registerProviderPackage(createGoogleProviderPackage({ apiKey: hostKey, models }));
+```
+
+## Extension and configuration notes
+
+- Register via `defineProviderPackage` / host registries; no package auto-discovery.
+- AI SDK remains an escape hatch, not the primary Google path.
+- Live smoke: `PRISM_LIVE_PROVIDER_TESTS=1` + `GOOGLE_API_KEY` or `GEMINI_API_KEY`.
+- Vertex / enterprise identity stays out of 0.0.11.
+
+## Security and performance notes
+
+- No network during import/setup/default tests; credentials host-owned and late-bound.
+- Provider-owned auth headers cannot be overridden by caller headers.
+- Media bounds reuse shared provider media helpers; tool args arrive complete per chunk (no partial JSON reconstruction required).
+- Offline conformance: `@arnilo/prism/testing/provider-conformance`.
+
+## Related APIs
+
+- [Provider packages](../provider-packages.md): package setup + discovery contract.
+- [Thinking and reasoning](../thinking-and-reasoning.md): portable thinking helpers.
+- [Provider conformance](../provider-conformance.md): network-free assertions.
+- Package README: [`packages/provider-google/README.md`](../../packages/provider-google/README.md)

package/docs/public-contracts.md

@@ -151,6 +151,10 @@ Important request shapes:
 | `PersistenceQuery` | Common pagination controls: `cursor?`, `limit?`, `order?: "asc" \| "desc"`. |
 | `OwnershipScope` | Multi-tenant scope: `tenantId?`, `accountId?`, `userId?`. Included in records and queries. |
 | `SessionRecord` / `SessionQuery` | Stored session and query filters (parent, agent definition, retention policy, timestamps, ownership). |
+| `SessionIndex` / `SessionSearchQuery` / `SessionSearchHit` | Bounded optional session search seam (`search` / `SessionStore.searchSessions?`). Filters: workspace (`metadata.workspaceRoot`), time, provider/model, label/summary, optional FTS `query`, ownership. Hits return `sessionId` + optional `leafId` for resume; never credentials. Caps via `resolveSessionSearchQuery` / `DEFAULT_*` / `HARD_MAX_*` session-search constants. |
+| `contextBudget` / `getContextBudgetReport` / `ContextBudgetError` | Opt-in assembler budget on `AssembleProviderInputOptions`; deterministic eviction; omission report in `ProviderRequest.metadata` (kinds/ids/sizes only). |
+| `AgentSession.steer` / `SteerOptions` / pending-steer caps | Mid-run enqueue into active run; optional `softInterrupt`; default 8 msgs / 64 KiB UTF-8. |
+| `SessionSearchUnsupportedError` / `sessionSearchMode` | Memory opt-out + JSONL; typed throw (not empty success). |
 | `BranchRecord` / `BranchQuery` | Branch handle/leaf pointer and query filters (session, name, parent branch, leaf presence). |
 | `SessionEntryQuery` | Paginated entry filters: `sessionId`, `runId`, `parentId`, `leafId`, `kind`, timestamp range, ownership. |
 | `RunRecord` / `RunQuery` | Stored run and filters: session, branch, status, timestamps, ownership. |