@theokit/sdk 1.6.2 → 1.8.0

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

@@ -0,0 +1,233 @@
+---
+user-invocable: false
+description: Dependency injection container, decorators, scopes, and modules for @theokit/di.
+paths:
+  - "**/*container*"
+  - "**/*inject*"
+  - "**/*provider*"
+  - "**/*module*"
+---
+
+# TheoKit DI -- Dependency Injection
+
+Quick reference for `@theokit/di` -- a TypeScript DI container with decorator metadata.
+
+## Installation
+
+```bash
+pnpm add @theokit/di reflect-metadata
+```
+
+Requires `reflect-metadata` polyfill imported once at app entry and `experimentalDecorators` + `emitDecoratorMetadata` in `tsconfig.json`.
+
+## Core decorators
+
+### @Injectable
+
+```typescript
+import { Injectable, Scope } from "@theokit/di";
+
+@Injectable()
+class UserRepository {
+  findById(id: string) { /* ... */ }
+}
+
+// With options:
+@Injectable({ scope: Scope.REQUEST })
+class RequestScopedService { /* ... */ }
+```
+
+`InjectableOptions`:
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `scope` | `Scope` | `Scope.SINGLETON` | Lifecycle scope. |
+
+### @Inject
+
+```typescript
+import { Inject } from "@theokit/di";
+
+@Injectable()
+class OrderService {
+  constructor(
+    @Inject("DATABASE_URL") private readonly dbUrl: string,
+    private readonly repo: UserRepository, // auto-resolved by type
+  ) {}
+}
+```
+
+Use `@Inject(token)` for string/symbol tokens. Constructor parameter types are auto-resolved via `reflect-metadata` when the parameter is a class.
+
+### @Optional
+
+```typescript
+import { Optional } from "@theokit/di";
+
+@Injectable()
+class NotificationService {
+  constructor(
+    @Optional() private readonly sms?: SmsGateway,
+  ) {}
+}
+```
+
+Resolves to `undefined` instead of throwing `TokenNotFoundError` when the dependency is not registered.
+
+### @Qualifier
+
+```typescript
+import { Qualifier } from "@theokit/di";
+
+@Injectable()
+class PaymentService {
+  constructor(
+    @Qualifier("stripe") private readonly gateway: PaymentGateway,
+  ) {}
+}
+```
+
+Disambiguates between multiple providers registered under the same interface token.
+
+### @Primary
+
+```typescript
+import { Primary, Injectable } from "@theokit/di";
+
+@Injectable()
+@Primary()
+class StripeGateway implements PaymentGateway { /* ... */ }
+```
+
+Marks a provider as the default when multiple are registered for the same token. Wins over non-primary providers unless `@Qualifier` is used.
+
+### @PostConstruct / @PreDestroy
+
+```typescript
+import { PostConstruct, PreDestroy, Injectable } from "@theokit/di";
+
+@Injectable()
+class DatabasePool {
+  @PostConstruct()
+  async init() { /* called after construction */ }
+
+  @PreDestroy()
+  async shutdown() { /* called on container.dispose() */ }
+}
+```
+
+## Container
+
+```typescript
+import { Container } from "@theokit/di";
+
+const container = new Container();
+
+// Register classes
+container.register(UserRepository);
+container.register(OrderService);
+
+// Register value providers
+container.register("DATABASE_URL", { useValue: "postgres://..." });
+
+// Register factory providers
+container.register("Logger", {
+  useFactory: (ctx) => new Logger(ctx.resolve("DATABASE_URL")),
+});
+
+// Register existing (alias)
+container.register("PrimaryRepo", { useExisting: UserRepository });
+
+// Resolve
+const service = container.resolve(OrderService);
+const asyncService = await container.resolveAsync(OrderService);
+
+// Dispose (calls @PreDestroy hooks)
+await container.dispose();
+```
+
+### ContainerOptions
+
+```typescript
+interface ContainerOptions {
+  parent?: Container;    // hierarchical containers
+  autoRegister?: boolean; // default false
+}
+```
+
+### Provider types
+
+```typescript
+type Provider =
+  | ClassProvider      // { useClass: Constructor, scope? }
+  | ValueProvider      // { useValue: any }
+  | FactoryProvider    // { useFactory: (ctx) => any, scope? }
+  | ExistingProvider;  // { useExisting: Token }
+```
+
+## Scopes
+
+```typescript
+import { Scope } from "@theokit/di";
+```
+
+| Scope | Behavior |
+|---|---|
+| `Scope.SINGLETON` | One instance per container (default). |
+| `Scope.TRANSIENT` | New instance on every resolve. |
+| `Scope.REQUEST` | One instance per request scope (via `container.createScope()`). |
+
+Request scope example:
+
+```typescript
+const requestContainer = container.createScope();
+const handler = requestContainer.resolve(RequestHandler);
+// All REQUEST-scoped deps share the same instance within this scope
+```
+
+## @Module
+
+```typescript
+import { Module } from "@theokit/di";
+
+@Module({
+  providers: [UserRepository, OrderService],
+  imports: [DatabaseModule],
+  exports: [UserRepository],
+})
+class UserModule {}
+
+// Load module into container
+container.loadModule(UserModule);
+```
+
+`ModuleMetadata`:
+
+| Field | Type | Description |
+|---|---|---|
+| `providers` | `Provider[]` | Classes/providers registered in this module. |
+| `imports` | `Module[]` | Other modules whose exports become available. |
+| `exports` | `Token[]` | Tokens visible to importing modules. |
+
+## Errors
+
+| Error | Cause |
+|---|---|
+| `TokenNotFoundError` | Token not registered and not `@Optional`. |
+| `CyclicDependencyError` | Circular dependency detected in resolution graph. |
+| `MissingInjectableError` | Class used as dependency without `@Injectable`. |
+| `ScopeViolationError` | Singleton depends on transient/request-scoped dep. |
+| `ContainerDisposedError` | Resolve called after `container.dispose()`. |
+| `ContainerFrozenError` | Register called after container is frozen. |
+| `AsyncProviderInSyncResolveError` | Async factory used with `resolve()` instead of `resolveAsync()`. |
+| `ReflectMetadataMissingError` | `reflect-metadata` polyfill not imported. |
+| `CyclicModuleImportError` | Circular module imports detected. |
+| `InvalidModuleError` | Module class missing `@Module` decorator. |
+| `InvalidExportError` | Module exports a token not in its providers. |
+
+## Graph analysis
+
+```typescript
+const graph: DependencyGraph = container.analyzeGraph();
+// Useful for debugging dependency chains and detecting issues
+```

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
+  }
+}
+```