@theokit/sdk 1.7.0 → 1.8.1

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

@@ -0,0 +1,176 @@
+---
+user-invocable: false
+paths:
+  - "**/*budget*"
+  - "**/*Budget*"
+  - "**/*cost*"
+  - "**/*token*"
+description: TheoKit SDK Budget API reference — cost tracking, token budget enforcement, usage reporting
+---
+
+# TheoKit Budget
+
+Token cost enforcement primitive. Track, warn, and block LLM spend at the
+process level with stacked USD limits and configurable enforcement modes.
+
+## Quick start
+
+```typescript
+import { Budget } from "@theokit/sdk";
+
+const handle = Budget.create({
+  name: "my-bot",
+  scope: "process",
+  mode: "warn",
+  limits: [
+    { window: "1h", limitUsd: 5.0 },
+    { window: "1d", limitUsd: 50.0 },
+  ],
+  onThreshold: (event) => {
+    console.warn(`Budget ${event.budgetName}: ${event.threshold * 100}% of ${event.window} limit`);
+  },
+  onExceed: (event) => {
+    console.error(`Budget ${event.budgetName}: exceeded ${event.window} limit`);
+  },
+});
+```
+
+## Enforcement modes
+
+| Mode | Behavior |
+|---|---|
+| `"audit"` | Log only. Never throws, never blocks. |
+| `"warn"` | Callbacks fire at 80%, 95%, and 100% thresholds. No throw. Default. |
+| `"block"` | Preflight throw (`BudgetExceededError`) BEFORE the LLM call when would-exceed. |
+
+## Stacked limits
+
+Pass multiple limits. ANY exceeded limit triggers enforcement:
+
+```typescript
+Budget.create({
+  name: "emergency-stop",
+  scope: "process",
+  mode: "block",
+  limits: [
+    { window: "1h", limitUsd: 2.0 },
+    { window: "1d", limitUsd: 10.0 },
+    { window: "30d", limitUsd: 100.0 },
+  ],
+});
+```
+
+Empty `limits[]` is valid: pure tracking with no threshold/exceed callbacks.
+
+## Time windows
+
+| Window | Alignment |
+|---|---|
+| `"1h"` | Relative (last 60 minutes) |
+| `"1d"` | UTC midnight boundary |
+| `"1w"` | Monday 00:00 UTC |
+| `"30d"` | 1st of month 00:00 UTC |
+| `"365d"` | Jan 1 00:00 UTC |
+
+## Managing budgets
+
+```typescript
+// Retrieve a budget handle
+const handle = Budget.get("my-bot");
+
+// Check spend and remaining
+handle?.spentIn("1d");       // USD spent in current day window
+handle?.remainingIn("1d");   // USD remaining before limit
+
+// List all active budgets
+const budgets = Budget.list();
+
+// Snapshot all windows for all budgets
+const snapshots = Budget.snapshot();
+// [{ name, window, spentUsd, limitUsd, ratio }, ...]
+
+// Delete a budget
+Budget.delete("my-bot");
+```
+
+## Type reference
+
+```typescript
+type BudgetScope = "agent" | "call" | "process";
+type BudgetWindow = "1h" | "1d" | "1w" | "30d" | "365d";
+type BudgetMode = "audit" | "warn" | "block";
+
+interface BudgetLimit {
+  readonly window: BudgetWindow;
+  readonly limitUsd: number;
+}
+
+interface BudgetOptions {
+  readonly name: string;          // must match ^[a-z0-9][a-z0-9_-]*$
+  readonly scope: BudgetScope;
+  readonly limits: ReadonlyArray<BudgetLimit>;
+  readonly mode?: BudgetMode;     // default "warn"
+  readonly onThreshold?: (event: BudgetThresholdEvent) => void | Promise<void>;
+  readonly onExceed?: (event: BudgetExceedEvent) => void | Promise<void>;
+}
+
+interface BudgetHandle {
+  readonly name: string;
+  readonly mode: BudgetMode;
+  readonly scope: BudgetScope;
+  readonly limits: ReadonlyArray<BudgetLimit>;
+  spentIn(window: BudgetWindow): number;
+  remainingIn(window: BudgetWindow): number;
+}
+
+interface BudgetSnapshot {
+  readonly name: string;
+  readonly window: BudgetWindow;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+  readonly ratio: number;
+}
+
+interface BudgetThresholdEvent {
+  readonly budgetName: string;
+  readonly window: BudgetWindow;
+  readonly threshold: 0.8 | 0.95;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+}
+
+interface BudgetExceedEvent {
+  readonly budgetName: string;
+  readonly window: BudgetWindow;
+  readonly spentUsd: number;
+  readonly limitUsd: number;
+  readonly mode: BudgetMode;
+}
+```
+
+## Wiring with agents
+
+Budget enforcement integrates with `agent.send()`. When a budget is active
+and mode is `"block"`, a preflight check runs before the LLM call. If the
+estimated cost would exceed a limit, `BudgetExceededError` is thrown.
+
+The `turn-ended` InteractionUpdate carries token usage that feeds the budget
+ledger automatically:
+
+```typescript
+{ inputTokens, outputTokens, cacheReadTokens, cacheWriteTokens }
+```
+
+## Errors
+
+| Error | When |
+|---|---|
+| `ConfigurationError` | Invalid `name` (grammar violation) or duplicate `name` |
+| `BudgetExceededError` | `mode: "block"` and spend would exceed a limit |
+
+## Known limitations
+
+- v1 supports `scope: "process"` only. `"agent"` and `"call"` scopes are
+  reserved for future multi-tenant scenarios.
+- In-flight `agent.send` calls referencing a deleted budget treat subsequent
+  charges as a silent no-op with a stderr warning.

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

@@ -0,0 +1,139 @@
+---
+user-invocable: false
+paths:
+  - "**/.theokit/**"
+  - "**/config.*"
+  - "**/theo.config.*"
+description: TheoKit SDK configuration reference — .theokit/ structure, mcp.json, hooks, env vars, config discovery
+---
+
+# TheoKit Configuration
+
+## Directory structure
+
+```
+.theokit/
++-- hooks/                          # one .md per hook
+|   +-- shell-policy.md
++-- context/                        # one .md per context source
+|   +-- bot-readme.md
++-- skills/<name>/SKILL.md          # named capability packs
++-- plugins/<name>/PLUGIN.md        # plugin definitions
++-- cron/
+|   +-- jobs.json                   # local cron state (auto-created)
++-- agents/*.md                     # subagent definitions (name + description frontmatter)
++-- memory/                         # local memory storage
+```
+
+User-level config lives at `~/.theokit/` with the same structure.
+
+## Config file format (v1.5+)
+
+Markdown + YAML frontmatter. One file per entity.
+
+### Hook example
+
+```markdown
+---
+event: preToolUse
+matcher: ^shell$
+command: node .theokit/policy.js
+---
+
+# Shell tool policy gate
+
+Vets shell tool invocations before spawn.
+```
+
+### Disabling an entry
+
+Rename `<name>.md` to `<name>.md.disabled` — the loader silently skips it.
+
+## Setting sources
+
+`local.settingSources` controls which config layers a local agent loads:
+
+| Value | Source |
+|---|---|
+| `"project"` | `.theokit/` in the workspace |
+| `"user"` | `~/.theokit/` |
+| `"team"` | Team settings synced from the dashboard |
+| `"mdm"` | MDM-managed enterprise settings |
+| `"plugins"` | Plugin-provided settings |
+| `"all"` | All of the above |
+
+Cloud agents always load project / team / plugins and ignore this field.
+
+```typescript
+const agent = await Agent.create({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd(), settingSources: ["project", "user"] },
+});
+```
+
+## Environment variables
+
+| Env var | Purpose |
+|---|---|
+| `THEOKIT_API_KEY` | Default API key (user or service account) |
+| `THEOKIT_REDACT_SECRETS` | Set `false` to disable secret redaction (default: `true`) |
+| `OLLAMA_HOST` | Ollama server URL (default: `http://localhost:11434`) |
+| `OLLAMA_API_KEY` | Bearer token for Ollama Cloud or proxy |
+| `OPENROUTER_API_KEY` | OpenRouter provider key |
+| `ANTHROPIC_API_KEY` | Anthropic provider key |
+| `OPENAI_API_KEY` | OpenAI provider key |
+
+## MCP server discovery
+
+Servers are loaded with first-match-wins precedence:
+
+1. `mcpServers` on `agent.send()` — fully replaces creation-time servers
+2. `mcpServers` on `Agent.create()` — used when no per-send override
+3. Plugin servers (if settingSources includes `"plugins"`)
+4. Project servers from `.theokit/mcp.json` (if settingSources includes `"project"`)
+5. User servers from `~/.theokit/mcp.json` (if settingSources includes `"user"`)
+
+## Context manager config
+
+```typescript
+const agent = await Agent.create({
+  context: {
+    manager: "file",     // reads .theokit/context/<name>.md
+    maxTokens: 1200,
+  },
+  local: { cwd: process.cwd(), settingSources: ["project"] },
+});
+```
+
+`manager: "inline"` uses `sources` passed directly in `Agent.create()`.
+
+## Skills config
+
+```typescript
+const agent = await Agent.create({
+  skills: {
+    enabled: ["code-review", "test-architect"],
+  },
+  local: { cwd: process.cwd(), settingSources: ["project"] },
+});
+```
+
+Skills live at `.theokit/skills/<name>/SKILL.md` with strict YAML frontmatter
+(`name`, `description` required).
+
+## Migration from legacy JSON
+
+```bash
+npx theokit-migrate-config --apply
+```
+
+Dry-run by default; `--apply` writes. Backs up originals to
+`<file>.json.<unix-ts>.bak`. Legacy JSON still works in v1.x with a
+deprecation warning. JSON support removed in v2.0.
+
+## `agent.reload()`
+
+Re-reads filesystem config (context, skills, hooks, project MCP, subagents)
+without disposing the agent or losing conversation state. Invalid files
+raise `ConfigurationError`.

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

@@ -0,0 +1,148 @@
+---
+user-invocable: false
+paths:
+  - "**/*cron*"
+  - "**/*Cron*"
+  - "**/*job*"
+  - "**/*schedule*"
+description: TheoKit SDK Cron jobs API reference — Cron.create, schedule syntax, job lifecycle
+---
+
+# TheoKit Cron Jobs
+
+Schedule Theo agent runs on a cron expression. Two runtimes mirror the agent
+split: local (in-process scheduler) and cloud (Theo PaaS, pre-release).
+
+## Creating a job
+
+```typescript
+import { Cron } from "@theokit/sdk";
+
+const job = await Cron.create({
+  cron: "0 9 * * *",                 // every day at 09:00
+  timezone: "America/Sao_Paulo",
+  message: "Summarize yesterday's commits and post to #engineering",
+  agent: {
+    apiKey: process.env.THEOKIT_API_KEY!,
+    model: { id: "google/gemini-2.0-flash-001" },
+    local: { cwd: process.cwd() },
+  },
+});
+
+await Cron.start();  // required for local jobs to fire
+```
+
+## Agent binding
+
+Pass exactly one of:
+
+- **`agent`** (full `AgentOptions`) — a fresh agent is created on every fire.
+  Use for independent runs.
+- **`agentId`** (string) — reuses an existing agent's conversation context
+  across fires. Use for continuity (e.g., weekly review building on past notes).
+
+Setting both raises `ConfigurationError`.
+
+## Cron expressions
+
+| Format | Example | Meaning |
+|---|---|---|
+| 5-field POSIX | `0 9 * * *` | Minute, hour, day-of-month, month, day-of-week |
+| `@hourly` | `@hourly` | Every hour at minute 0 |
+| `@daily` | `@daily` | Every day at midnight |
+| `@weekly` | `@weekly` | Every Sunday at midnight |
+| `@monthly` | `@monthly` | First day of month at midnight |
+| `@yearly` | `@yearly` | January 1 at midnight |
+
+`timezone` accepts any IANA identifier (default: `"UTC"`). Invalid expressions
+throw `ConfigurationError` synchronously at create time.
+
+## Managing jobs
+
+```typescript
+const { items } = await Cron.list({ runtime: "local", cwd: process.cwd() });
+const job = await Cron.get(jobId);
+
+await Cron.disable(jobId);   // pause without deleting
+await Cron.enable(jobId);    // resume
+await Cron.delete(jobId);    // permanent removal
+```
+
+## Manual fire (off-schedule)
+
+```typescript
+const run = await Cron.run(jobId);
+
+for await (const event of run.stream()) {
+  // same SDKMessage events as any other run
+}
+```
+
+Manual fires do not update `lastRunAt` — only scheduled fires do.
+
+## Local scheduler lifecycle
+
+```typescript
+await Cron.start({ cwd: process.cwd() });  // reads .theokit/cron/jobs.json
+const status = await Cron.status();
+// { running: true, jobCount: 3, nextFireAt: 1747... }
+await Cron.stop();  // halts scheduling; does NOT delete jobs
+```
+
+Local jobs only fire while the host process is alive. Run as `pm2` / `systemd`
+service for 24/7 local scheduling.
+
+## Persistence
+
+Local cron state lives in `.theokit/cron/jobs.json`. Created automatically by
+`Cron.create()`. Commit it if jobs should travel with the repo; add to
+`.gitignore` if environment-specific.
+
+## Type reference
+
+```typescript
+interface CronJob {
+  id: string;
+  name?: string;
+  cron: string;
+  timezone?: string;
+  message: string | SDKUserMessage;
+  agent?: AgentOptions;              // mutually exclusive with agentId
+  agentId?: string;
+  enabled: boolean;
+  status: "scheduled" | "running" | "paused" | "errored";
+  runtime: "local" | "cloud";
+  lastRunAt?: number;
+  nextRunAt?: number;
+  createdAt: number;
+}
+
+interface CronCreateOptions {
+  cron: string;
+  message: string | SDKUserMessage;
+  agent?: AgentOptions;
+  agentId?: string;
+  name?: string;
+  timezone?: string;
+  enabled?: boolean;                 // defaults to true
+  apiKey?: string;
+}
+
+interface CronSchedulerStatus {
+  running: boolean;
+  jobCount: number;
+  nextFireAt?: number;
+  lastError?: { jobId: string; message: string; at: number };
+}
+```
+
+## Cloud jobs (pre-release)
+
+Cloud jobs use Theo PaaS and do not need `Cron.start()`. Pass `agent.cloud`
+to create a cloud-scheduled job. Pre-release — not yet GA.
+
+## Known limitations
+
+- Local jobs only fire while the host process is alive.
+- In-flight fires are not resumed if the host process crashes mid-run.
+- `Cron.run()` (manual fire) does not update `lastRunAt`.

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