@theokit/sdk 1.6.2 → 1.8.0

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

@@ -0,0 +1,209 @@
+---
+user-invocable: false
+description: Agent lifecycle, sending messages, streaming, and disposal patterns for @theokit/sdk.
+paths:
+  - "**/*agent*"
+  - "**/*Agent*"
+  - "**/sdk.*"
+---
+
+# TheoKit SDK -- Agent Core
+
+Quick reference for Agent lifecycle, Run streaming, and disposal.
+
+## Agent.create
+
+```typescript
+import { Agent } from "@theokit/sdk";
+
+const agent = await Agent.create({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+```
+
+Returns an `SDKAgent`. Local agents get `agent-<uuid>` IDs; cloud agents get `bc-<uuid>`.
+
+### AgentOptions (key fields)
+
+| Property | Type | Notes |
+|---|---|---|
+| `model` | `ModelSelection` | Required for local; `{ id, params? }`. |
+| `apiKey` | `string` | Falls back to `THEOKIT_API_KEY` env. |
+| `local` | `{ cwd, settingSources?, sandboxOptions? }` | Local runtime config. |
+| `cloud` | `CloudOptions` | Cloud runtime config (repos, autoCreatePR, envVars). |
+| `systemPrompt` | `string \| (ctx: SystemPromptContext) => string` | Static string or async resolver. |
+| `mcpServers` | `Record<string, McpServerConfig>` | Inline MCP server definitions. |
+| `agents` | `Record<string, AgentDefinition>` | Subagent definitions. |
+| `tools` | `CustomTool[]` | Inline custom tools (local only). |
+| `memory` | `MemoryOptions` | Durable memory config. |
+| `handoffs` | `Array<SDKAgent \| Handoff>` | Peer-to-peer agent handoffs. |
+| `conversationStorage` | `ConversationStorageAdapter` | Pluggable persistence. |
+
+## Agent.prompt (one-shot)
+
+```typescript
+const result = await Agent.prompt("What does the auth middleware do?", {
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+// result: { id, status, result?, model?, durationMs?, git? }
+```
+
+Pass `throwOnError: true` to reject with `AgentRunError` instead of resolving with `status: 'error'`.
+
+## agent.send and Run
+
+```typescript
+const run = await agent.send("Find the bug in src/auth.ts");
+```
+
+### Run interface
+
+| Member | Type | Description |
+|---|---|---|
+| `id` | `string` | Run identifier. |
+| `status` | `RunStatus` | `"running" \| "finished" \| "error" \| "cancelled"` |
+| `stream()` | `AsyncGenerator<SDKMessage>` | Normalized event stream. |
+| `wait()` | `Promise<RunResult>` | Block until finished. |
+| `cancel()` | `Promise<void>` | Cancel the run. |
+| `conversation()` | `Promise<ConversationTurn[]>` | Structured turn history. |
+| `onDidChangeStatus(fn)` | `() => void` | Status change listener; returns unsubscribe. |
+
+### Streaming SDKMessage types
+
+```typescript
+for await (const event of run.stream()) {
+  switch (event.type) {
+    case "assistant": /* event.message.content: (TextBlock | ToolUseBlock)[] */ break;
+    case "thinking":  /* event.text, event.thinking_duration_ms? */ break;
+    case "tool_call": /* event.name, event.status, event.args?, event.result? */ break;
+    case "status":    /* event.status: cloud lifecycle transitions */ break;
+    case "task":      /* event.text: task milestones */ break;
+    case "request":   /* event.request_id: awaiting user input */ break;
+  }
+}
+```
+
+### Per-send options
+
+```typescript
+await agent.send("Plan the refactor", {
+  model: { id: "claude-sonnet-4-6", params: [{ id: "thinking", value: "high" }] },
+  systemPrompt: "Focus on performance.",
+  signal: abortController.signal,
+  onDelta: ({ update }) => { /* InteractionUpdate */ },
+  onStep: ({ step }) => { /* ConversationStep */ },
+});
+```
+
+## Agent.resume
+
+```typescript
+const agent = await Agent.resume("bc-abc123", {
+  apiKey: process.env.THEOKIT_API_KEY!,
+});
+```
+
+Runtime auto-detected from ID prefix. Inline `mcpServers` and `tools` are NOT persisted -- re-pass on resume.
+
+## Agent.getOrCreate
+
+```typescript
+const agent = await Agent.getOrCreate(`tg-user-${userId}`, {
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "claude-sonnet-4-6" },
+  local: { cwd: process.cwd() },
+});
+```
+
+Tries resume first; on `UnknownAgentError` falls through to create.
+
+## Agent.get / Agent.list / Agent.listRuns
+
+```typescript
+const info = await Agent.get(agentId);
+const { items, nextCursor } = await Agent.list({ runtime: "local", cwd: process.cwd() });
+const { items: runs } = await Agent.listRuns(agentId);
+```
+
+## createAgentFactory
+
+```typescript
+import { createAgentFactory } from "@theokit/sdk";
+
+const factory = createAgentFactory({
+  apiKey: process.env.THEOKIT_API_KEY!,
+  model: { id: "claude-sonnet-4-6" },
+  local: { cwd: process.cwd() },
+  systemPrompt: "You are a helpful assistant.",
+});
+const agent = await factory.getOrCreate(`user-${userId}`);
+```
+
+## Agent.builder (fluent API)
+
+```typescript
+const agent = await Agent.builder()
+  .apiKey(process.env.THEOKIT_API_KEY!)
+  .model({ id: "claude-sonnet-4-6" })
+  .local({ cwd: process.cwd() })
+  .tools([myTool])
+  .getOrCreate(`user-${userId}`);
+```
+
+## Agent.generateObject / Agent.streamObject
+
+```typescript
+import { z } from "zod";
+
+const { object } = await Agent.generateObject({
+  schema: z.object({ title: z.string(), year: z.number().nullable() }),
+  prompt: "Fact card about jazz.",
+  model: { id: "google/gemini-2.0-flash-001" },
+  local: { cwd: process.cwd() },
+});
+
+for await (const evt of Agent.streamObject({ schema, prompt, model, local })) {
+  if (evt.type === "partial") render(evt.partial);
+  if (evt.type === "complete") finalize(evt.object);
+}
+```
+
+## Disposal patterns
+
+```typescript
+// Preferred: await using (auto-dispose on block exit)
+await using agent = await Agent.create({ /* ... */ });
+
+// Explicit dispose
+await agent[Symbol.asyncDispose]();
+
+// Fire-and-forget close
+agent.close();
+
+// Reload config without disposing
+await agent.reload();
+```
+
+## Agent.registry (production)
+
+```typescript
+Agent.registry.configure({ maxAgents: 1000, idleTimeoutMs: 15 * 60 * 1000 });
+Agent.registry.size();
+Agent.registry.evict("agent-42");
+await Agent.registry.evictAll(); // graceful shutdown
+```
+
+## Cancellation
+
+```typescript
+const run = await agent.send(message, { signal: request.signal });
+// On abort: AgentRunError with code "aborted"
+
+// Compose with timeout:
+const composed = AbortSignal.any([request.signal, AbortSignal.timeout(30_000)]);
+await agent.send(message, { signal: composed });
+```

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