@cyanheads/mcp-ts-core 0.1.0-beta.12

package/skills/api-context/SKILL.md

@@ -0,0 +1,321 @@
+---
+name: api-context
+description: >
+  Canonical reference for the unified `Context` object passed to every tool and resource handler in `@cyanheads/mcp-ts-core`. Covers the full interface, all sub-APIs (`ctx.log`, `ctx.state`, `ctx.elicit`, `ctx.sample`, `ctx.progress`), and when to use each.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Every tool and resource handler receives a single `Context` (`ctx`) argument. It provides request identity, structured logging, tenant-scoped storage, optional protocol capabilities (elicitation, sampling), cancellation, and task progress — all auto-correlated to the current request.
+
+**Rule:** Use `ctx.log` and `ctx.state` inside handlers. Use the global `logger` and `StorageService` directly only in lifecycle/background code (`setup()`, services).
+
+---
+
+## `Context` Interface
+
+```ts
+import type { Context } from '@cyanheads/mcp-ts-core/context';
+
+interface Context {
+  // Identity & tracing
+  readonly requestId: string;       // Unique per request, auto-generated
+  readonly timestamp: string;       // ISO 8601 request start time
+  readonly tenantId?: string;       // From JWT 'tid' claim; 'default' in stdio mode
+  readonly traceId?: string;        // OTEL trace ID (present when OTEL enabled)
+  readonly spanId?: string;         // OTEL span ID (present when OTEL enabled)
+  readonly auth?: AuthContext;      // Parsed auth claims (clientId, scopes, sub)
+
+  // Structured logging — auto-includes requestId, traceId, tenantId
+  readonly log: ContextLogger;
+
+  // Tenant-scoped key-value storage
+  readonly state: ContextState;
+
+  // Optional protocol capabilities (undefined when client doesn't support them)
+  readonly elicit?: (message: string, schema: z.ZodObject<any>) => Promise<ElicitResult>;
+  readonly sample?: (messages: SamplingMessage[], opts?: SamplingOpts) => Promise<CreateMessageResult>;
+
+  // Cancellation
+  readonly signal: AbortSignal;
+
+  // Task progress — present only when tool is defined with task: true
+  readonly progress?: ContextProgress;
+
+  // Raw URI — present only for resource handlers
+  readonly uri?: URL;
+}
+```
+
+### Identity fields
+
+| Field | Always present | Source |
+|:------|:--------------|:-------|
+| `requestId` | Yes | Auto-generated UUID per request |
+| `timestamp` | Yes | ISO 8601, request start |
+| `tenantId` | In stdio (as `'default'`); from JWT `tid` claim in HTTP | JWT / stdio default |
+| `traceId` | When OTEL enabled | OTEL trace context |
+| `spanId` | When OTEL enabled | OTEL trace context |
+| `auth` | When auth enabled | Parsed JWT claims |
+
+---
+
+## `ctx.log`
+
+Request-scoped structured logger. Every log line is automatically annotated with `requestId`, `traceId`, and `tenantId` — no manual spreading needed.
+
+### Methods
+
+| Method | Level |
+|:-------|:------|
+| `ctx.log.debug(msg, data?)` | Verbose debugging |
+| `ctx.log.info(msg, data?)` | Normal operational events |
+| `ctx.log.notice(msg, data?)` | Significant but non-error events |
+| `ctx.log.warning(msg, data?)` | Recoverable issues, unexpected states |
+| `ctx.log.error(msg, error?, data?)` | Errors (second arg is the Error object) |
+
+### Usage
+
+```ts
+// Basic
+ctx.log.info('Processing query', { query: input.query });
+
+// With error object (second arg)
+ctx.log.error('Failed to fetch upstream', error, { url, statusCode });
+
+// Debug detail
+ctx.log.debug('Cache miss', { key, ttl });
+```
+
+### `ctx.log` vs global `logger`
+
+| Use | Where |
+|:----|:------|
+| `ctx.log` | Inside tool/resource handlers — auto-correlated to the request |
+| `core.logger` / `logger` | In `setup()`, service constructors, background tasks — no request context available |
+
+The global `logger` is imported from `@cyanheads/mcp-ts-core/utils/logger`. In handlers, always prefer `ctx.log`.
+
+---
+
+## `ctx.state`
+
+Tenant-scoped key-value storage. Delegates to `StorageService` with automatic `tenantId` scoping — data written under tenant A is invisible to tenant B.
+
+### Interface
+
+```ts
+interface ContextState {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, opts?: { ttl?: number }): Promise<void>;
+  delete(key: string): Promise<void>;
+  list(prefix?: string, opts?: { cursor?: string; limit?: number }): Promise<{
+    items: Array<{ key: string; value: string }>;
+    cursor?: string;  // opaque base64url; omitted on last page
+  }>;
+}
+```
+
+### Usage
+
+```ts
+// Store (values are always strings — serialize JSON manually)
+await ctx.state.set('item:123', JSON.stringify(data));
+await ctx.state.set('session:xyz', token, { ttl: 3600 }); // TTL in seconds
+
+// Retrieve
+const raw = await ctx.state.get('item:123');
+const data = raw ? JSON.parse(raw) : null;
+
+// Delete
+await ctx.state.delete('item:123');
+
+// List with prefix + pagination
+const page = await ctx.state.list('item:', { cursor, limit: 20 });
+for (const { key, value } of page.items) { /* ... */ }
+if (page.cursor) { /* more pages available */ }
+```
+
+### Behavior notes
+
+- Throws `McpError(InvalidRequest)` if `tenantId` is missing (won't happen in stdio mode — defaults to `'default'`).
+- Keys are tenant-prefixed internally; handlers never need to namespace manually.
+- **Workers persistence:** The `in-memory` provider loses data on cold starts. Use `cloudflare-kv`, `cloudflare-r2`, or `cloudflare-d1` for durable storage in Workers.
+
+---
+
+## `ctx.elicit` / `ctx.sample`
+
+Both are optional — they are `undefined` when the connected client does not support the capability. Always check for presence before calling. No type guards are required; a simple truthiness check is sufficient.
+
+### `ctx.elicit` — ask the user for structured input
+
+Presents a form to the human user via the MCP elicitation protocol. The user fills in a Zod-validated schema and returns an action (`accept`, `decline`, or `cancel`).
+
+```ts
+if (ctx.elicit) {
+  const result = await ctx.elicit(
+    'Which output format do you want?',
+    z.object({
+      format: z.enum(['json', 'csv', 'markdown']).describe('Output format'),
+      includeHeaders: z.boolean().default(true).describe('Include column headers'),
+    }),
+  );
+
+  if (result.action === 'accept') {
+    // result.data is typed as { format: 'json' | 'csv' | 'markdown', includeHeaders: boolean }
+    await produceOutput(result.data.format, result.data.includeHeaders);
+  } else {
+    // 'decline' or 'cancel' — user opted out
+    throw new McpError(JsonRpcErrorCode.InvalidRequest, 'User declined input');
+  }
+}
+```
+
+`ElicitResult`:
+
+```ts
+type ElicitResult =
+  | { action: 'accept'; data: z.infer<typeof schema> }
+  | { action: 'decline' | 'cancel' };
+```
+
+**Convention:** Only call `ctx.elicit` from tool handlers, not from services.
+
+### `ctx.sample` — request an LLM completion from the client
+
+Requests the client's LLM to generate a completion (MCP sampling protocol). Useful for AI-assisted tool behavior without managing a separate LLM provider.
+
+```ts
+if (ctx.sample) {
+  const result = await ctx.sample(
+    [
+      { role: 'user', content: { type: 'text', text: `Summarize: ${data}` } },
+    ],
+    { maxTokens: 500 },
+  );
+  return { summary: result.content.text };
+}
+```
+
+`SamplingOpts`:
+
+```ts
+interface SamplingOpts {
+  includeContext?: 'none' | 'thisServer' | 'allServers';
+  maxTokens?: number;
+  modelPreferences?: Record<string, unknown>;
+  stopSequences?: string[];
+  temperature?: number;
+}
+```
+
+**Convention:** Only call `ctx.sample` from tool handlers, not from services.
+
+---
+
+## `ctx.signal`
+
+Standard `AbortSignal`. Present on every context. Set when the client cancels the request or when a task tool is cancelled.
+
+```ts
+// Check before expensive operations
+if (ctx.signal.aborted) return earlyResult;
+
+// Pass through to fetch / other async APIs
+const response = await fetch(url, { signal: ctx.signal });
+
+// Loop with cancellation check
+for (const item of items) {
+  if (ctx.signal.aborted) break;
+  await processItem(item);
+}
+```
+
+In task tools (`task: true`), the framework signals `ctx.signal` when the client sends a cancellation request.
+
+---
+
+## `ctx.progress`
+
+Present only when the tool definition includes `task: true`. Undefined for standard (non-task) tools and all resource handlers.
+
+### Methods
+
+| Method | Purpose |
+|:-------|:--------|
+| `ctx.progress.setTotal(n)` | Set the total number of steps (enables percentage calculation on client) |
+| `ctx.progress.increment(amount?)` | Advance progress by `amount` (default: 1) |
+| `ctx.progress.update(message)` | Send a descriptive status message without advancing the counter |
+
+### Usage
+
+```ts
+const asyncCountdown = tool('async_countdown', {
+  description: 'Count down from a number with progress updates.',
+  task: true,
+  input: z.object({
+    count: z.number().int().positive().describe('Number to count down from'),
+    delayMs: z.number().default(1000).describe('Delay between counts in ms'),
+  }),
+
+  async handler(input, ctx) {
+    await ctx.progress!.setTotal(input.count);
+
+    for (let i = input.count; i > 0; i--) {
+      if (ctx.signal.aborted) break;
+
+      await ctx.progress!.update(`Counting: ${i}`);
+      await new Promise(resolve => setTimeout(resolve, input.delayMs));
+      await ctx.progress!.increment();
+    }
+
+    return { finalCount: 0, message: 'Countdown complete' };
+  },
+});
+```
+
+**Note:** Use the non-null assertion (`ctx.progress!`) when accessing inside a `task: true` handler — the type is `ContextProgress | undefined` even though it's guaranteed present at runtime. TypeScript cannot narrow based on the `task` flag.
+
+---
+
+## `ctx.uri`
+
+Present only for resource handlers. The raw `URL` object for the matched resource URI.
+
+```ts
+export const myResource = resource('myscheme://{itemId}/data', {
+  async handler(params, ctx) {
+    ctx.log.debug('Resource accessed', { uri: ctx.uri?.toString() });
+    // params.itemId is extracted from the URI pattern — prefer params over ctx.uri
+    return fetchItem(params.itemId);
+  },
+});
+```
+
+Prefer `params` (the extracted URI template variables) over parsing `ctx.uri` manually. `ctx.uri` is available when the raw URL string is needed.
+
+---
+
+## Quick Reference
+
+| Property | Type | Present when |
+|:---------|:-----|:-------------|
+| `ctx.requestId` | `string` | Always |
+| `ctx.timestamp` | `string` | Always |
+| `ctx.tenantId` | `string \| undefined` | Always in stdio (`'default'`); HTTP with auth |
+| `ctx.traceId` | `string \| undefined` | OTEL enabled |
+| `ctx.spanId` | `string \| undefined` | OTEL enabled |
+| `ctx.auth` | `AuthContext \| undefined` | Auth enabled |
+| `ctx.log` | `ContextLogger` | Always |
+| `ctx.state` | `ContextState` | Always (throws if `tenantId` missing) |
+| `ctx.signal` | `AbortSignal` | Always |
+| `ctx.elicit` | `function \| undefined` | Client supports elicitation |
+| `ctx.sample` | `function \| undefined` | Client supports sampling |
+| `ctx.progress` | `ContextProgress \| undefined` | Tool defined with `task: true` |
+| `ctx.uri` | `URL \| undefined` | Resource handlers only |

package/skills/api-errors/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: api-errors
+description: >
+  McpError constructor, JsonRpcErrorCode reference, and error handling patterns for `@cyanheads/mcp-ts-core`. Use when looking up error codes, understanding where errors should be thrown vs. caught, or using ErrorHandler.tryCatch in services.
+metadata:
+  author: cyanheads
+  version: "1.0"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Error handling in `@cyanheads/mcp-ts-core` follows a strict layered pattern: tool and resource handlers throw `McpError` freely (no try/catch), the handler factory catches and normalizes all errors, and services use `ErrorHandler.tryCatch` for graceful recovery.
+
+**Imports:**
+
+```ts
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+import { ErrorHandler } from '@cyanheads/mcp-ts-core/utils/errorHandler';
+```
+
+---
+
+## McpError Constructor
+
+```ts
+throw new McpError(code, message?, data?, options?)
+```
+
+- `code` — a `JsonRpcErrorCode` enum value
+- `message` — optional human-readable description of the failure
+- `data` — optional structured context (plain object)
+- `options` — optional `{ cause?: unknown }` for error chaining
+
+**Example:**
+
+```ts
+import { McpError, JsonRpcErrorCode } from '@cyanheads/mcp-ts-core/errors';
+
+throw new McpError(JsonRpcErrorCode.InvalidParams, 'Missing required field: name', {
+  requestId: ctx.requestId,
+  field: 'name',
+});
+```
+
+---
+
+## Error Codes
+
+**Standard JSON-RPC 2.0 codes:**
+
+| Code | Value | When to Use |
+|:-----|------:|:------------|
+| `ParseError` | -32700 | Malformed JSON received |
+| `InvalidRequest` | -32600 | Unsupported operation, missing client capability |
+| `MethodNotFound` | -32601 | Requested method does not exist |
+| `InvalidParams` | -32602 | Bad input, missing required fields, schema validation failure |
+| `InternalError` | -32603 | Unexpected failure, catch-all for programmer errors |
+
+**Implementation-defined codes (-32000 to -32099):**
+
+| Code | Value | When to Use |
+|:-----|------:|:------------|
+| `ServiceUnavailable` | -32000 | External dependency down, upstream failure |
+| `NotFound` | -32001 | Resource, entity, or record doesn't exist |
+| `Conflict` | -32002 | Duplicate key, version mismatch, concurrent modification |
+| `RateLimited` | -32003 | Rate limit exceeded |
+| `Timeout` | -32004 | Operation exceeded time limit |
+| `Forbidden` | -32005 | Authenticated but insufficient scopes/permissions |
+| `Unauthorized` | -32006 | No auth, invalid token, expired credentials |
+| `ValidationError` | -32007 | Business rule violation (not schema — use `InvalidParams` for that) |
+| `ConfigurationError` | -32008 | Missing env var, invalid config |
+| `InitializationFailed` | -32009 | Server/component startup failure |
+| `DatabaseError` | -32010 | Storage/persistence layer failure |
+| `SerializationError` | -32070 | Data serialization/deserialization failed |
+| `UnknownError` | -32099 | Generic fallback when no other code fits |
+
+---
+
+## Where Errors Are Handled
+
+| Layer | Pattern |
+|:------|:--------|
+| Tool/resource handlers | Throw `McpError` — no try/catch |
+| Handler factory | Catches all errors, normalizes to `McpError`, sets `isError: true` |
+| Services/setup code | `ErrorHandler.tryCatch` for graceful recovery |
+
+**Handler — throw freely, no try/catch:**
+
+```ts
+export const myTool = tool('my_tool', {
+  input: z.object({ id: z.string().describe('Item ID') }),
+  async handler(input, ctx) {
+    const item = await db.find(input.id);
+    if (!item) {
+      throw new McpError(JsonRpcErrorCode.NotFound, `Item not found: ${input.id}`, {
+        id: input.id,
+      });
+    }
+    return item;
+  },
+});
+```
+
+---
+
+## ErrorHandler.tryCatch (Services)
+
+Use `ErrorHandler.tryCatch` in service code — not in tool handlers. It wraps arbitrary exceptions into `McpError` and supports structured logging context.
+
+```ts
+import { ErrorHandler } from '@cyanheads/mcp-ts-core/utils/errorHandler';
+
+// Works with both async and sync functions
+const result = await ErrorHandler.tryCatch(
+  () => externalApi.fetch(url),
+  {
+    operation: 'ExternalApi.fetch',
+    context: { url },
+    errorCode: JsonRpcErrorCode.ServiceUnavailable,
+  },
+);
+
+const parsed = await ErrorHandler.tryCatch(
+  () => JSON.parse(raw),
+  {
+    operation: 'parseConfig',
+    errorCode: JsonRpcErrorCode.ConfigurationError,
+  },
+);
+```
+
+`tryCatch` always logs and rethrows — it never swallows errors. The `fn` argument may be synchronous or return a `Promise`; both are handled via `Promise.resolve(fn())`.
+
+**Options** (`Omit<ErrorHandlerOptions, 'rethrow'>`):
+
+| Option | Type | Required | Purpose |
+|:-------|:-----|:--------:|:--------|
+| `operation` | `string` | Yes | Name logged with the error |
+| `context` | `ErrorContext` | No | Extra structured fields merged into the log record; `requestId` and `timestamp` receive special treatment |
+| `errorCode` | `JsonRpcErrorCode` | No | Code used if the caught error is not already an `McpError` |
+| `input` | `unknown` | No | Input value sanitized and logged alongside the error |
+| `critical` | `boolean` | No | Marks the error as critical in logs (default `false`) |
+| `includeStack` | `boolean` | No | Include stack trace in log output (default `true`) |
+| `errorMapper` | `(error: unknown) => Error` | No | Custom transform applied instead of default `McpError` wrapping |

package/skills/api-services/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: api-services
+description: >
+  API reference for built-in service providers (LLM, Speech, Graph). Use when looking up service interfaces, provider capabilities, or integration patterns.
+metadata:
+  author: cyanheads
+  version: "1.2"
+  audience: external
+  type: reference
+---
+
+## Overview
+
+Service interfaces are deferred from core's public exports — they remain in downstream servers until shared by 2+ servers. These are documented here for core contributors and servers that use the built-in providers.
+
+All services follow the **init/accessor pattern**: initialized in `setup()`, accessed at request time via lazy accessor. See the `add-service` skill for the full pattern.
+
+## References
+
+| Reference | Path | Description |
+|:----------|:-----|:------------|
+| LLM | `references/llm.md` | OpenRouter-based LLM provider (`ILlmProvider`, streaming, config) |
+| Speech | `references/speech.md` | TTS/STT providers (`SpeechService`, ElevenLabs, Whisper) |
+| Graph | `references/graph.md` | Relationship graph operations (`IGraphProvider`, traversal, pathfinding) |

package/skills/api-services/references/graph.md

@@ -0,0 +1,124 @@
+# Graph Service (`services/graph`)
+
+## `IGraphProvider` interface
+
+Relationship-oriented graph operations — not vertex-CRUD:
+
+| Method | Signature | Notes |
+|:-------|:----------|:------|
+| `relate` | `(from, edgeTable, to, context, options?) -> Promise<Edge>` | Create a directed relationship edge |
+| `unrelate` | `(edgeId, context) -> Promise<boolean>` | Delete an edge by ID. Returns `true` if found. |
+| `traverse` | `(startVertexId, context, options?) -> Promise<TraversalResult>` | Graph traversal from a starting vertex |
+| `shortestPath` | `(from, to, context, options?) -> Promise<GraphPath \| null>` | Find lowest-cost path between two vertices |
+| `getOutgoingEdges` | `(vertexId, context, edgeTypes?) -> Promise<Edge[]>` | All outgoing edges from a vertex |
+| `getIncomingEdges` | `(vertexId, context, edgeTypes?) -> Promise<Edge[]>` | All incoming edges to a vertex |
+| `pathExists` | `(from, to, context, maxDepth?) -> Promise<boolean>` | Reachability check (cheaper than `shortestPath`) |
+| `getStats` | `(context) -> Promise<GraphStats>` | Aggregate vertex/edge counts and type breakdowns |
+| `healthCheck` | `() -> Promise<boolean>` | Provider liveness check |
+
+All methods that take `context` expect `RequestContext`, not unified `Context`.
+
+## `GraphService` class
+
+Thin facade over `IGraphProvider` — delegates all calls to the injected provider with debug logging. Same method signatures as `IGraphProvider`, plus:
+
+| Method | Return |
+|:-------|:-------|
+| `getProvider()` | `IGraphProvider` — access the underlying provider |
+
+Not auto-constructed — initialize in `setup()` with a provider.
+
+## Types
+
+```ts
+interface Vertex {
+  id: string;       // e.g., 'user:alice'
+  table: string;    // e.g., 'user'
+  data: Record<string, unknown>;
+}
+
+interface Edge {
+  id: string;       // e.g., 'follows:1'
+  table: string;    // e.g., 'follows'
+  from: string;     // source vertex ID
+  to: string;       // target vertex ID
+  data: Record<string, unknown>;
+}
+
+type TraversalDirection = 'out' | 'in' | 'both';
+
+interface TraversalOptions {
+  direction?: TraversalDirection;  // default: 'out'
+  maxDepth?: number;               // default: 1
+  edgeTypes?: string[];            // filter by edge table
+  vertexTypes?: string[];          // filter by vertex table
+  where?: string;                  // provider-specific filter
+}
+
+interface TraversalResult {
+  start: Vertex;
+  paths: GraphPath[];
+}
+
+interface GraphPath {
+  vertices: Vertex[];
+  edges: Edge[];
+  weight?: number;
+}
+
+interface PathOptions {
+  algorithm?: 'dijkstra' | 'bfs' | 'dfs';  // default: 'bfs'
+  maxLength?: number;
+  weightFn?: (edge: Edge) => number;        // required for 'dijkstra'
+}
+
+interface RelateOptions {
+  allowDuplicates?: boolean;  // default: false
+  data?: Record<string, unknown>;
+}
+
+interface GraphStats {
+  vertexCount: number;
+  edgeCount: number;
+  avgDegree: number;
+  vertexTypes: Record<string, number>;
+  edgeTypes: Record<string, number>;
+}
+```
+
+## Usage
+
+```ts
+// Create a relationship
+const edge = await graphService.relate(
+  'user:alice', 'follows', 'user:bob', context,
+  { data: { since: '2025-01-01' } },
+);
+
+// Delete a relationship
+const deleted = await graphService.unrelate('follows:1', context);
+
+// Traverse the graph
+const result = await graphService.traverse('user:alice', context, {
+  maxDepth: 2,
+  edgeTypes: ['follows'],
+  direction: 'out',
+});
+
+// Find shortest path
+const path = await graphService.shortestPath('user:alice', 'user:charlie', context, {
+  algorithm: 'bfs',
+  maxLength: 4,
+});
+if (path) console.log(`${path.vertices.length} hops`);
+
+// Check reachability
+const connected = await graphService.pathExists('user:alice', 'user:charlie', context, 3);
+
+// Get edges
+const outgoing = await graphService.getOutgoingEdges('user:alice', context, ['follows']);
+const incoming = await graphService.getIncomingEdges('user:bob', context, ['follows']);
+
+// Stats
+const stats = await graphService.getStats(context);
+```

package/skills/api-services/references/llm.md

@@ -0,0 +1,46 @@
+# LLM Service (`services/llm`)
+
+| Export | API | Notes |
+|:-------|:----|:------|
+| `ILlmProvider` | `.chatCompletion(params, context) -> Promise<ChatCompletion \| Stream<ChatCompletionChunk>>` `.chatCompletionStream(params, context) -> Promise<AsyncIterable<ChatCompletionChunk>>` | OpenAI-compatible interface. `params.stream` discriminates return type on `chatCompletion`. Context is `RequestContext`, not unified `Context`. |
+| `OpenRouterProvider` | Implements `ILlmProvider` via OpenRouter API | Tier 3 peer: `openai`. Lazy-loaded. Rate-limited via `RateLimiter`. Retries on 429/5xx. |
+| `OpenRouterChatParams` | `ChatCompletionCreateParamsNonStreaming \| ChatCompletionCreateParamsStreaming` | OpenAI SDK types — OpenRouter is API-compatible. |
+
+## Configuration
+
+| Env Var | Purpose |
+|:--------|:--------|
+| `OPENROUTER_API_KEY` | API key (required to enable LLM service) |
+| `OPENROUTER_APP_URL` | App URL for OpenRouter rankings |
+| `OPENROUTER_APP_NAME` | App name for OpenRouter rankings |
+| `LLM_DEFAULT_MODEL` | Default model ID (e.g., `anthropic/claude-sonnet-4-20250514`) |
+| `LLM_DEFAULT_MAX_TOKENS` | Default max tokens |
+| `LLM_DEFAULT_TEMPERATURE` | Default temperature |
+
+## Usage
+
+```ts
+// In a tool handler — assumes LLM provider was initialized in setup()
+// Note: chatCompletion takes RequestContext, not the unified Context.
+// In services, pass the RequestContext directly. In tool handlers,
+// create one via requestContextService or pass through from the service layer.
+const completion = await llmProvider.chatCompletion({
+  model: 'anthropic/claude-sonnet-4-20250514',
+  messages: [{ role: 'user', content: 'Hello' }],
+  max_tokens: 500,
+}, requestContext);
+```
+
+Streaming variant:
+
+```ts
+const stream = await llmProvider.chatCompletionStream({
+  model: 'anthropic/claude-sonnet-4-20250514',
+  messages: [{ role: 'user', content: 'Hello' }],
+  max_tokens: 500,
+}, requestContext);
+
+for await (const chunk of stream) {
+  // chunk is ChatCompletionChunk
+}
+```