@theokit/sdk 4.53.1 → 4.55.0

package/claude-template/dot-claude/skills/theokit-errors/SKILL.md

@@ -1,172 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*error*"
-  - "**/*Error*"
-  - "**/*exception*"
-description: TheoKit SDK error hierarchy — TheokitAgentError, error codes, retry patterns
----
-
-# TheoKit Error Handling
-
-All SDK errors extend `TheokitAgentError`. Use `isRetryable` to drive
-retry/backoff logic without coupling to specific subclasses.
-
-## Error hierarchy
-
-```
-Error
-+-- TheokitAgentError
-|   +-- AuthenticationError
-|   +-- RateLimitError
-|   +-- ConfigurationError
-|   |   +-- IntegrationNotConnectedError
-|   +-- NetworkError
-|   +-- UnknownAgentError
-|
-+-- UnsupportedRunOperationError   (separate hierarchy)
-+-- AgentRunError                  (thrown by Agent.prompt with throwOnError)
-```
-
-## Error reference
-
-| Error | When | `isRetryable` |
-|---|---|---|
-| `AuthenticationError` | Invalid API key, not logged in, insufficient permissions | `false` |
-| `RateLimitError` | Too many requests or usage limits exceeded | `true` |
-| `ConfigurationError` | Invalid model, bad request parameters, malformed options | `false` |
-| `IntegrationNotConnectedError` | Cloud agent for a repo whose SCM is not connected | `false` |
-| `NetworkError` | Service unavailable, timeout, transport failure | `true` |
-| `UnknownAgentError` | Catch-all for unclassified errors | `false` |
-| `UnsupportedRunOperationError` | Runtime does not support a `Run` operation | n/a |
-| `AgentRunError` | Run finished with error status (only with `throwOnError: true`) | n/a |
-
-## `TheokitAgentError` properties
-
-```typescript
-class TheokitAgentError extends Error {
-  readonly isRetryable: boolean;
-  readonly code?: string;
-  readonly protoErrorCode?: string;
-  readonly cause?: unknown;
-  readonly metadata?: ErrorMetadata;  // v1.3+ provider HTTP errors
-}
-```
-
-## `ErrorMetadata` (v1.3+)
-
-When an error originates from a provider HTTP call:
-
-```typescript
-interface ErrorMetadata {
-  provider: string;          // "anthropic" | "openai" | "openrouter" | ...
-  endpoint: string;          // "/v1/messages" | "/v1/chat/completions"
-  code: ErrorCode;
-  statusCode?: number;
-  retryAfter?: number;       // seconds
-  raw?: unknown;             // raw response body (truncated ~2KB)
-}
-
-type ErrorCode =
-  | "rate_limit" | "auth_failed" | "invalid_request"
-  | "timeout" | "server_error" | "context_too_long"
-  | "content_filtered" | "model_unavailable"
-  | "network" | "unknown";
-```
-
-## Retry pattern
-
-```typescript
-import { TheokitAgentError, type Run } from "@theokit/sdk";
-
-async function withRetry(send: () => Promise<Run>, attempts = 3): Promise<Run> {
-  let lastError: unknown;
-  for (let i = 0; i < attempts; i++) {
-    try {
-      return await send();
-    } catch (err) {
-      lastError = err;
-      if (err instanceof TheokitAgentError && err.isRetryable) {
-        await new Promise((r) => setTimeout(r, 2 ** i * 1000));
-        continue;
-      }
-      throw err;
-    }
-  }
-  throw lastError;
-}
-```
-
-## Using metadata for programmatic handling
-
-```typescript
-try {
-  await agent.send("...");
-} catch (err) {
-  if (err instanceof TheokitAgentError && err.metadata) {
-    switch (err.metadata.code) {
-      case "rate_limit":
-        await wait(err.metadata.retryAfter ?? 60);
-        return retry();
-      case "auth_failed":
-        throw new Error(`Check API key for ${err.metadata.provider}`);
-      case "context_too_long":
-        // trigger prompt compression
-        break;
-    }
-  }
-  throw err;
-}
-```
-
-## `IntegrationNotConnectedError`
-
-```typescript
-import { IntegrationNotConnectedError } from "@theokit/sdk/errors";
-
-try {
-  await Agent.create({ /* cloud with disconnected repo */ });
-} catch (err) {
-  if (err instanceof IntegrationNotConnectedError) {
-    console.error(`Connect ${err.provider} at ${err.helpUrl}`);
-  }
-}
-```
-
-## `UnsupportedRunOperationError`
-
-Check before calling runtime-dependent operations:
-
-```typescript
-if (run.supports("conversation")) {
-  const turns = await run.conversation();
-} else {
-  console.log(run.unsupportedReason("conversation"));
-}
-```
-
-## Tree-shaking
-
-Import error classes from the `/errors` subpath to avoid pulling the full SDK:
-
-```typescript
-import { TheokitAgentError, RateLimitError } from "@theokit/sdk/errors";
-```
-
-## `throwOnError` on `Agent.prompt`
-
-```typescript
-import { Agent, AgentRunError } from "@theokit/sdk";
-
-try {
-  const result = await Agent.prompt("hi", {
-    apiKey: process.env.ANTHROPIC_API_KEY!,
-    model: { id: "claude-sonnet-4-5-20250929" },
-    throwOnError: true,
-  });
-} catch (err) {
-  if (err instanceof AgentRunError && err.code === "auth_failed") {
-    // bad API key
-  }
-}
-```

package/claude-template/dot-claude/skills/theokit-eval/SKILL.md

@@ -1,179 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*eval*"
-  - "**/*Eval*"
-  - "**/*scorer*"
-description: TheoKit SDK Eval suite API reference — Eval.create, scorers, datasets, EvalRun
----
-
-# TheoKit Eval Suite
-
-Eval-as-code primitive for production deploy gates. Run evals against real LLM
-providers to measure quality, latency, and cost before shipping.
-
-## Quick start
-
-```typescript
-import { Eval, Scorers } from "@theokit/sdk";
-
-const run = await Eval.create({
-  name: "qa-smoke",
-  dataset: [
-    { input: "Reply with the word: ok.", expected: "ok" },
-    { input: "Say jazz in one word.", expected: "jazz" },
-  ],
-  scorers: [
-    Scorers.containsExpected({ caseSensitive: false }),
-    Scorers.regex(/[a-zA-Z]/),
-  ],
-  agent: {
-    apiKey: process.env.OPENROUTER_API_KEY,
-    model: { id: "openai/gpt-4o-mini" },
-    local: { cwd: process.cwd(), sandboxOptions: { enabled: false } },
-  },
-  concurrency: 4,
-}).run();
-
-console.log(run.aggregate.meanScore);     // 0.95
-console.log(run.aggregate.passRatio);     // 1.0
-console.log(run.aggregate.tokensInTotal); // 142
-console.log(run.aggregate.durationMsP95); // 1830
-```
-
-## Built-in scorers (`Scorers`)
-
-| Scorer | What it checks |
-|---|---|
-| `Scorers.exactMatch({ caseSensitive? })` | `output.trim() === expected.trim()` — refuses empty `expected` |
-| `Scorers.containsExpected({ caseSensitive? })` | `output.includes(expected)` — refuses empty `expected` |
-| `Scorers.regex(pattern)` | `pattern.test(output)` — test patterns against adversarial output to avoid ReDoS |
-| `Scorers.jsonShape(zodSchema, { strict? })` | `JSON.parse(output)` + Zod validation — caps output at 1 MB before parse |
-| `Scorers.llmJudge({ model, apiKey, criteria, rubric? })` | Second LLM scores against criteria — requires SEPARATE `apiKey` |
-| `Scorers.levenshtein({ threshold?, caseSensitive? })` | Normalized edit-distance similarity `1 - dist/max(len)` — deterministic (no LLM); `threshold` binarizes |
-| `Scorers.numericDiff({ tolerance? })` | Relative numeric closeness `1 - |o-e|/max(|o|,|e|)` — deterministic; `tolerance` binarizes |
-| `Scorers.embeddingSimilarity({ apiKey?, model?, threshold?, embed? })` | Cosine of output vs expected embeddings (OpenRouter by default; inject `embed` for another provider). One embeddings call per row |
-| `Scorers.verifyGate({ sandbox?, repoDir, failToPass, passToPass, command })` | Runs the project's tests in a sandbox; scores 1 iff exit 0 (SWE-bench style) |
-
-### Custom scorer
-
-A scorer is an async function returning a number between 0 and 1:
-
-```typescript
-const myScorer = async (row: { input: string; output: string; expected?: string }) => {
-  return row.output.length < 100 ? 1.0 : 0.5;
-};
-```
-
-## Dataset
-
-The `dataset` field accepts an array of objects with `input` and optional `expected`:
-
-```typescript
-interface EvalDatasetRow {
-  input: string;
-  expected?: string;
-}
-```
-
-Recommended ceiling: ~10k rows (v1 materializes in memory). For larger evals,
-partition into multiple `Eval.create` calls.
-
-## `EvalRun` shape
-
-```typescript
-interface EvalRun {
-  id: string;
-  name: string;
-  startedAt: number;
-  endedAt: number;
-  durationMs: number;
-  aggregate: EvalAggregate;
-  rows: ReadonlyArray<EvalRowResult>;
-  metadata?: Record<string, unknown>;
-}
-
-interface EvalAggregate {
-  meanScore: number;
-  medianScore: number;
-  passRatio: number;          // rows where meanScore >= 0.5
-  perScorer: Record<string, { mean; median; min; max }>;
-  totalRows: number;
-  errorRows: number;
-  durationMsP50: number;
-  durationMsP95: number;
-  tokensInTotal: number;
-  tokensOutTotal: number;
-}
-```
-
-`EvalRun` is plain JSON — `JSON.stringify(run)` works directly.
-
-## CI gate — `assertEval`
-
-Turn a run into a pass/fail gate. `assertEval` reads only `run.aggregate`,
-collects EVERY unmet threshold, and throws `EvalThresholdError` (with a
-`.failures` list) when any is missed — otherwise returns `void`. Drop it into a
-Vitest `it(...)` or a standalone script whose non-zero exit fails the CI job.
-
-```typescript
-import { Eval, Scorers, assertEval, EvalThresholdError } from "@theokit/sdk/eval";
-
-const run = await Eval.create({ name: "qa", dataset, scorers, agent }).run();
-
-assertEval(run, {
-  minMeanScore: 0.8,     // aggregate.meanScore >= 0.8
-  minPassRatio: 0.9,     // aggregate.passRatio  >= 0.9
-  maxErrorRatio: 0,      // errorRows / totalRows <= 0
-  perScorer: { "contains-expected": 0.7 }, // per-scorer mean floor (absent scorer = failure)
-});
-```
-
-## Trials (smooth non-determinism)
-
-`trials: N` runs each dataset row N times and collapses to ONE row whose
-per-scorer score is the mean over the trials (an errored trial contributes 0).
-`EvalRowResult.trialCount` records the collapse. Range `[1, 100]`.
-
-```typescript
-const run = await Eval.create({ name: "qa", dataset, scorers, agent, trials: 3 }).run();
-```
-
-## Concurrency
-
-`concurrency` defaults to 4. Allowed range: `[1, 64]` (integer). 0 and
-Infinity are rejected at `Eval.create` time.
-
-## Concurrent runs
-
-Per-process single-flight per `name`. Two `Eval.run` calls with the same
-`name` running simultaneously throw `EvalAlreadyRunningError`. Include model
-id in the name for matrix runs.
-
-## CLI integration
-
-The `theokit eval` CLI invokes `Eval.run` internally. User-authored
-`eval.config.{ts,mjs}` files are forward-compatible.
-
-## Telemetry
-
-When `agent.telemetry.enabled === true`, `Eval.run` emits a parent `eval.run`
-OTel span; `agent.send` / `llm.call` spans nest under it.
-
-## Cost forecasting
-
-```
-aggregate.tokensInTotal  x provider_input_price
-+ aggregate.tokensOutTotal x provider_output_price
-```
-
-With `llmJudge`, add ~1 judge call per row. 1000 rows with `gpt-4o-mini`
-costs roughly $3.00 total (base + judge).
-
-## Errors
-
-| Error | When |
-|---|---|
-| `EvalAlreadyRunningError` | Same `name` already running in this process |
-| `EvalThresholdError` | `assertEval` found one or more unmet thresholds (see `.failures`) |
-| `ConfigurationError` | Invalid concurrency, missing required fields |

package/claude-template/dot-claude/skills/theokit-filesystem/SKILL.md

@@ -1,74 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*filesystem*"
-  - "**/*Filesystem*"
-description: TheoKit SDK filesystem seam — FilesystemBackend, LocalFilesystem, boundary-enforced storage with read-before-write safety
----
-
-# TheoKit Filesystem
-
-A pluggable, boundary-enforced file *storage* provider for agent file tools —
-the storage-side twin of the sandbox seam. Ship a `FilesystemBackend` (default
-`LocalFilesystem`) with an optional `readOnly` flag and a per-request resolver.
-
-```ts
-import {
-  LocalFilesystem, FilesystemBackend, resolveFilesystem,
-} from "@theokit/sdk/filesystem";
-import type {
-  FilesystemProvider, FilesystemConfig, FileStat, WriteFileOptions,
-} from "@theokit/sdk/filesystem";
-import {
-  FileNotFoundError, FilesystemError,
-  FilesystemReadOnlyError, FilesystemSecurityError, StaleFileError,
-} from "@theokit/sdk/filesystem";
-```
-
-## LocalFilesystem
-
-Boundary-enforced over `node:fs/promises`. Every path resolves within `basePath`;
-traversal / symlink escapes are rejected with `FilesystemSecurityError`. NOT an
-isolation boundary — run untrusted code inside a container/VM.
-
-```ts
-const fs = new LocalFilesystem({ basePath: "/workspace", readOnly: false });
-
-const stat: FileStat = await fs.writeFile("notes.md", "# hello"); // returns FileStat
-const text = await fs.readFile("notes.md");
-const names = await fs.list(".");            // entry names, not recursive
-if (await fs.exists("notes.md")) { /* … */ }
-```
-
-## Read-before-write safety (SE32)
-
-`stat().mtimeMs` is the oracle. Pass `expectedMtime` so a concurrent change makes
-the write fail with `StaleFileError` instead of silently clobbering.
-
-```ts
-const before = await fs.stat("notes.md");
-try {
-  await fs.writeFile("notes.md", updated, { expectedMtime: before.mtimeMs });
-} catch (err) {
-  if (err instanceof StaleFileError) { /* someone changed it — re-read + merge */ }
-}
-```
-
-## Per-request provider (multi-tenant)
-
-A `FilesystemProvider` is a backend OR a resolver `(ctx) => backend` run at
-tool-execution time, giving each request its own root. `resolveFilesystem`
-collapses either form to a concrete backend.
-
-```ts
-const provider: FilesystemProvider<{ tenant: string }> = (ctx) =>
-  new LocalFilesystem({ basePath: `/data/${ctx.tenant}` });
-
-const backend = await resolveFilesystem(provider, { tenant: "acme" });
-```
-
-## Custom backend
-
-Extend `FilesystemBackend` and implement `readFile` / `writeFile` / `stat` /
-`list`; `exists()`, `readOnly`, and `basePath` derive on the base class. Map raw
-Node errors to the typed errors above (`FileNotFoundError`, `FilesystemError`).

package/claude-template/dot-claude/skills/theokit-gateways/SKILL.md

@@ -1,209 +0,0 @@
----
-user-invocable: false
-description: Gateway architecture and 10 platform adapters (Telegram, Slack, Discord, WhatsApp, Teams, Email, SMS, Mattermost, LINE, Matrix).
-paths:
-  - "**/*gateway*"
-  - "**/*Gateway*"
-  - "**/*telegram*"
-  - "**/*slack*"
-  - "**/*discord*"
-  - "**/*whatsapp*"
----
-
-# TheoKit SDK -- Gateways
-
-Quick reference for the gateway architecture and all 10 platform adapters.
-
-## Architecture
-
-The gateway system uses a base adapter pattern. Each platform adapter extends `BasePlatformAdapter` from `@theokit/gateway`. The core package defines:
-
-- `BasePlatformAdapter` -- abstract class with `connect`, `disconnect`, `sendMessage`, `onInbound`.
-- `GatewayMessageEvent` -- discriminated union of all platform inbound events (keyed by `platform`).
-- `OutboundMessage` -- what `sendMessage` accepts.
-- `SendResult` -- `{ ok, messageId?, error? }`.
-- Session router for multi-platform agent dispatch.
-
-## BasePlatformAdapter
-
-```typescript
-abstract class BasePlatformAdapter {
-  abstract readonly platform: PlatformName;
-  abstract connect(): Promise<boolean>;
-  abstract disconnect(): Promise<void>;
-  abstract sendMessage(out: OutboundMessage): Promise<SendResult>;
-  abstract onInbound(handler: (event: GatewayMessageEvent) => Promise<void>): () => void;
-  async startTyping(channelId: string): Promise<void> { /* noop */ }
-  async stopTyping(channelId: string): Promise<void> { /* noop */ }
-}
-```
-
-## GatewayMessageEvent (common fields)
-
-```typescript
-interface BaseMessageEvent {
-  id: string;
-  platform: PlatformName;
-  sender: { id: string; username?: string; displayName?: string };
-  channel: { id: string; type: "dm" | "group" | "thread"; topicId?: string };
-  text: string;
-  receivedAt: number;
-  replyTo?: string;
-}
-```
-
-## PlatformName
-
-```typescript
-type PlatformName =
-  | "telegram" | "discord" | "slack" | "whatsapp" | "teams"
-  | "email" | "sms" | "mattermost" | "line" | "matrix";
-```
-
-## Platform adapters
-
-### 1. Telegram (`@theokit/gateway-telegram`)
-
-```bash
-pnpm add @theokit/gateway-telegram @theokit/gateway grammy
-```
-
-```typescript
-import { TelegramAdapter } from "@theokit/gateway-telegram";
-
-const adapter = new TelegramAdapter({ botToken: process.env.TELEGRAM_BOT_TOKEN! });
-await adapter.connect();
-```
-
-Platform-specific: `event.telegram.chatId`, `event.telegram.messageId`, `event.telegram.threadId?`.
-
-### 2. Discord (`@theokit/gateway-discord`)
-
-```bash
-pnpm add @theokit/gateway-discord @theokit/gateway discord.js
-```
-
-```typescript
-import { DiscordAdapter } from "@theokit/gateway-discord";
-
-const adapter = new DiscordAdapter({ botToken: process.env.DISCORD_BOT_TOKEN! });
-await adapter.connect();
-```
-
-Platform-specific: `event.discord.guildId`, `event.discord.channelId`, `event.discord.messageId`.
-
-### 3. Slack (`@theokit/gateway-slack`)
-
-```bash
-pnpm add @theokit/gateway-slack @theokit/gateway @slack/bolt @slack/web-api
-```
-
-```typescript
-import { SlackAdapter } from "@theokit/gateway-slack";
-
-const adapter = new SlackAdapter({
-  botToken: process.env.SLACK_BOT_TOKEN!,
-  appToken: process.env.SLACK_APP_TOKEN!,
-  requireMention: true,  // default; public channels need @bot mention
-});
-await adapter.connect();
-```
-
-Platform-specific: `event.slack.teamId`, `event.slack.channelId`, `event.slack.ts`, `event.slack.threadTs?`.
-
-### 4. WhatsApp (`@theokit/gateway-whatsapp`)
-
-```bash
-pnpm add @theokit/gateway-whatsapp @theokit/gateway
-```
-
-Two backends: `"cloud"` (Meta Cloud API) and `"web"` (whatsapp-web.js bridge).
-
-Platform-specific: `event.whatsapp.wamid`, `event.whatsapp.backend`, `event.whatsapp.phoneNumberId?`.
-
-### 5. Teams (`@theokit/gateway-teams`)
-
-```bash
-pnpm add @theokit/gateway-teams @theokit/gateway botbuilder
-```
-
-Platform-specific: `event.teams.activityId`, `event.teams.conversationId`, `event.teams.conversationType`, `event.teams.tenantId?`.
-
-### 6. Email (`@theokit/gateway-email`)
-
-```bash
-pnpm add @theokit/gateway-email @theokit/gateway
-```
-
-Uses IMAP for inbound and SMTP for outbound.
-
-Platform-specific: `event.email.messageId`, `event.email.subject`, `event.email.fromAddress`, `event.email.recipients`.
-
-### 7. SMS (`@theokit/gateway-sms`)
-
-```bash
-pnpm add @theokit/gateway-sms @theokit/gateway
-```
-
-Backends: `"twilio"`, `"plivo"`, `"vonage"`. Inbound via webhook server.
-
-Platform-specific: `event.sms.backend`, `event.sms.from` (E.164), `event.sms.to` (E.164).
-
-### 8. Mattermost (`@theokit/gateway-mattermost`)
-
-```bash
-pnpm add @theokit/gateway-mattermost @theokit/gateway
-```
-
-Platform-specific: `event.mattermost.postId`, `event.mattermost.channelId`, `event.mattermost.rootId?`.
-
-### 9. LINE (`@theokit/gateway-line`)
-
-```bash
-pnpm add @theokit/gateway-line @theokit/gateway
-```
-
-Inbound via webhook with signature verification. Reply tokens are cached (one-shot, 60s TTL).
-
-Platform-specific: `event.line.sourceType`, `event.line.sourceId`, `event.line.messageId`.
-
-### 10. Matrix (`@theokit/gateway-matrix`)
-
-```bash
-pnpm add @theokit/gateway-matrix @theokit/gateway matrix-js-sdk
-```
-
-Platform-specific: `event.matrix.roomId`, `event.matrix.eventId`, `event.matrix.memberCount`.
-
-## Common usage pattern
-
-```typescript
-import { Agent } from "@theokit/sdk";
-
-const adapter = new TelegramAdapter({ botToken: process.env.TELEGRAM_BOT_TOKEN! });
-await adapter.connect();
-
-adapter.onInbound(async (event) => {
-  const agent = await Agent.getOrCreate(`${event.platform}-${event.sender.id}`, {
-    apiKey: process.env.THEOKIT_API_KEY!,
-    model: { id: "google/gemini-2.0-flash-001" },
-    local: { cwd: process.cwd() },
-    memory: { enabled: true, namespace: "bot", scope: "user", userId: event.sender.id },
-  });
-
-  await adapter.startTyping(event.channel.id);
-  const run = await agent.send(event.text);
-  const result = await run.wait();
-  await adapter.stopTyping(event.channel.id);
-
-  await adapter.sendMessage({
-    channel: event.channel,
-    text: result.result ?? "No response.",
-    replyTo: event.id,
-  });
-});
-```
-
-## Error mapping convention
-
-Each adapter maps platform errors to canonical `SendResult.error.code` values: `rate_limit`, `channel_not_found`, `no_permission`, `auth_error`, `message_too_long`, `platform_error`.