@theokit/sdk 1.7.0 → 1.8.0

package/claude-template/dot-claude/skills/theokit-di-agent/SKILL.md

@@ -0,0 +1,294 @@
+---
+user-invocable: false
+description: All 15 agentic decorators from @theokit/di-agent for tools, workflows, evals, cron, and more.
+paths:
+  - "**/*decorator*"
+  - "**/*Decorator*"
+  - "**/di-agent*"
+---
+
+# TheoKit DI-Agent -- Agentic Decorators
+
+Quick reference for `@theokit/di-agent` -- 15 decorators that wire agentic capabilities into DI-managed classes.
+
+## Installation
+
+```bash
+pnpm add @theokit/di-agent @theokit/di @theokit/sdk
+```
+
+Requires `reflect-metadata` and TypeScript decorator support (see `@theokit/di` docs).
+
+## createAgentProvider
+
+Bridges `@theokit/di` container with `@theokit/sdk` Agent. Reads decorator metadata from all registered classes and wires tools, workflows, evals, cron jobs, etc.
+
+```typescript
+import { Container } from "@theokit/di";
+import { createAgentProvider } from "@theokit/di-agent";
+
+const container = new Container();
+container.register(MyToolService);
+container.register(MyWorkflowService);
+
+const { agent, dispose } = await createAgentProvider(container, {
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+```
+
+## @Tool
+
+Registers a method as a custom tool exposed to the LLM.
+
+```typescript
+import { Injectable } from "@theokit/di";
+import { Tool } from "@theokit/di-agent";
+import { z } from "zod";
+
+@Injectable()
+class MathService {
+  @Tool({
+    name: "calculate",
+    description: "Evaluate a math expression.",
+    inputSchema: z.object({ expression: z.string() }),
+  })
+  calculate(input: { expression: string }): string {
+    return String(eval(input.expression));
+  }
+}
+```
+
+## @Workflow
+
+Marks a method as a workflow step definition.
+
+```typescript
+import { Workflow } from "@theokit/di-agent";
+
+@Injectable()
+class PipelineService {
+  @Workflow({ name: "data-pipeline", description: "ETL workflow." })
+  async run(input: { source: string }) {
+    // workflow implementation
+  }
+}
+```
+
+## @EvalDecorator
+
+Registers an eval suite on a method.
+
+```typescript
+import { EvalDecorator } from "@theokit/di-agent";
+
+@Injectable()
+class QAService {
+  @EvalDecorator({
+    name: "qa-smoke",
+    dataset: [{ input: "Say ok.", expected: "ok" }],
+  })
+  async evaluate() { /* ... */ }
+}
+```
+
+## @Cron
+
+Registers a cron-scheduled agent task.
+
+```typescript
+import { Cron } from "@theokit/di-agent";
+
+@Injectable()
+class ReportService {
+  @Cron({
+    expression: "0 9 * * *",
+    timezone: "America/Sao_Paulo",
+    message: "Summarize yesterday's commits.",
+  })
+  async dailyReport() { /* ... */ }
+}
+```
+
+## @Subscription
+
+Marks a method as a real-time subscription handler.
+
+```typescript
+import { Subscription } from "@theokit/di-agent";
+
+@Injectable()
+class EventService {
+  @Subscription({ topic: "orders.created", description: "Handle new orders." })
+  async onOrder(event: unknown) { /* ... */ }
+}
+```
+
+## @Auth
+
+Registers authentication/authorization logic for agent operations.
+
+```typescript
+import { Auth } from "@theokit/di-agent";
+
+@Injectable()
+class SecurityService {
+  @Auth({ strategy: "bearer", description: "JWT validation." })
+  async validate(token: string): Promise<boolean> { /* ... */ }
+}
+```
+
+## @Retriever
+
+Registers a retrieval method for RAG pipelines.
+
+```typescript
+import { Retriever } from "@theokit/di-agent";
+
+@Injectable()
+class SearchService {
+  @Retriever({ name: "docs-search", description: "Search documentation." })
+  async search(query: string) { /* ... */ }
+}
+```
+
+## @Reranker
+
+Registers a reranking method for RAG pipelines.
+
+```typescript
+import { Reranker } from "@theokit/di-agent";
+
+@Injectable()
+class RankService {
+  @Reranker({ name: "cohere-reranker", model: "rerank-v3.5" })
+  async rerank(query: string, docs: unknown[]) { /* ... */ }
+}
+```
+
+## @TextSplitter
+
+Registers a text splitting strategy.
+
+```typescript
+import { TextSplitter } from "@theokit/di-agent";
+
+@Injectable()
+class SplitterService {
+  @TextSplitter({ strategy: "recursive", chunkSize: 1000, overlap: 100 })
+  split(text: string) { /* ... */ }
+}
+```
+
+## @UseSandbox
+
+Marks a class or method for sandboxed execution.
+
+```typescript
+import { UseSandbox } from "@theokit/di-agent";
+
+@Injectable()
+class CodeRunner {
+  @UseSandbox({ enabled: true })
+  async execute(code: string) { /* ... */ }
+}
+```
+
+## @SubAgent
+
+Declares a subagent definition on a method.
+
+```typescript
+import { SubAgent } from "@theokit/di-agent";
+
+@Injectable()
+class AgentOrchestrator {
+  @SubAgent({
+    name: "code-reviewer",
+    description: "Expert code reviewer.",
+    prompt: "Review for bugs and security issues.",
+  })
+  async review() { /* ... */ }
+}
+```
+
+## @Hitl (Human-in-the-Loop)
+
+Marks a method as requiring human approval before proceeding.
+
+```typescript
+import { Hitl } from "@theokit/di-agent";
+
+@Injectable()
+class ApprovalService {
+  @Hitl({ description: "Requires manager approval.", timeout: 3600_000 })
+  async approve(request: unknown) { /* ... */ }
+}
+```
+
+## @AutoSummarize
+
+Enables automatic conversation summarization.
+
+```typescript
+import { AutoSummarize } from "@theokit/di-agent";
+
+@Injectable()
+class ChatService {
+  @AutoSummarize({ maxTurns: 20, strategy: "rolling" })
+  async chat() { /* ... */ }
+}
+```
+
+## @InjectAgent
+
+Injects the current `SDKAgent` instance into a class.
+
+```typescript
+import { Injectable } from "@theokit/di";
+import { InjectAgent } from "@theokit/di-agent";
+import type { SDKAgent } from "@theokit/sdk";
+
+@Injectable()
+class AgentAwareService {
+  constructor(@InjectAgent() private readonly agent: SDKAgent) {}
+
+  async doWork() {
+    const run = await this.agent.send("Do something");
+    await run.wait();
+  }
+}
+```
+
+## @MemoryScopeDecorator
+
+Configures memory scope for a class.
+
+```typescript
+import { MemoryScopeDecorator } from "@theokit/di-agent";
+
+@Injectable()
+@MemoryScopeDecorator({ namespace: "billing", scope: "user" })
+class BillingService { /* ... */ }
+```
+
+## Reading metadata (for framework authors)
+
+Each decorator has a companion reader function:
+
+```typescript
+import { readToolMetadata } from "@theokit/di-agent";
+import { readWorkflowMetadata } from "@theokit/di-agent";
+import { readCronMetadata } from "@theokit/di-agent";
+// ... readEvalDecoratorMetadata, readRetrieverMetadata, etc.
+
+const tools = readToolMetadata(MyToolService);
+```
+
+## AGENT_TOKEN
+
+```typescript
+import { AGENT_TOKEN } from "@theokit/di-agent";
+// Symbol token for agent injection in the DI container
+```

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

@@ -0,0 +1,172 @@
+---
+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

@@ -0,0 +1,144 @@
+---
+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` |
+
+### 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.
+
+## 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 |
+| `ConfigurationError` | Invalid concurrency, missing required fields |