@theokit/sdk 4.53.1 → 4.55.0

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

@@ -1,102 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*auth*"
-  - "**/*Auth*"
-  - "**/*envelope*"
-description: TheoKit SDK server auth — Auth.create orchestrator, validateReturnTo, and the cross-layer error envelope
----
-
-# TheoKit Server Auth
-
-Server-side auth orchestrator and the cross-layer error envelope. These live
-under the `@theokit/sdk/server/*` sub-paths (not the main barrel). Concrete
-OAuth/email providers ship in opt-in `@theokit/auth-*` packages — the SDK only
-defines the orchestrator contract.
-
-## `Auth.create` — session + provider orchestrator
-
-```typescript
-import {
-  Auth,
-  validateReturnTo,
-  AuthConfigError,
-  AuthProviderNotFoundError,
-  AuthCallbackError,
-  AuthCancelledError,
-  AuthSecretTooShortError,
-} from "@theokit/sdk/server/auth";
-import type {
-  AuthProvider,
-  SessionManager,
-  AuthOrchestrator,
-} from "@theokit/sdk/server/auth";
-```
-
-`Auth.create(opts)` returns an `AuthOrchestrator<TSession>` with 5 methods.
-`providers` is optional — an empty list is the manual-`signIn`-only escape hatch.
-
-```typescript
-const auth: AuthOrchestrator<Session> = Auth.create<Session>({
-  session,                 // your SessionManager<Session> implementation
-  providers: [githubProvider], // AuthProvider<Profile>[] from a @theokit/auth-* package
-  onSignIn: async ({ profile, provider }) => {
-    return toSession(profile, provider); // returns the TSession to persist
-  },
-  onSignOut: async (session) => {
-    /* revoke, audit, etc. */
-  },
-});
-
-// OAuth flow (node:http req/res):
-const redirect = await auth.startSignIn("github", req, { returnTo: "/dashboard" });
-const { session, returnTo } = await auth.finishSignIn("github", req, res); // rotates session id (OWASP A07)
-const current = await auth.getSession(req);
-await auth.signOut(res);
-
-// Escape hatch — persist a session directly, skipping the OAuth flow:
-const s = await auth.signIn(externalProfile, "github", req, res);
-```
-
-## `validateReturnTo` — open-redirect guard (OWASP A01)
-
-Returns a safe same-origin path. Cross-origin, protocol-relative (`//evil.com`),
-empty, and defensive cases all collapse to `"/"`.
-
-```typescript
-const safe = validateReturnTo(returnTo, new URL("https://app.example.com"));
-// "/dashboard" -> kept; "https://evil.com" -> "/"; undefined -> "/"
-```
-
-Typed errors: `AuthConfigError`, `AuthProviderNotFoundError`, `AuthCallbackError`,
-`AuthCancelledError`, `AuthSecretTooShortError`.
-
-## Error envelope — cross-layer boundary translation
-
-```typescript
-import {
-  toEnvelope,
-  fromEnvelope,
-  MemoryAdapterError,
-} from "@theokit/sdk/server/errors-envelope";
-import type {
-  TheokitErrorEnvelope,
-  TheokitErrorCode,
-} from "@theokit/sdk/server/errors-envelope";
-```
-
-`toEnvelope` translates any SDK error (or arbitrary thrown value) into the wire
-envelope at egress; `fromEnvelope` reconstructs SDK class identity at ingress so
-`instanceof` checks keep working across an IPC/serialization boundary.
-
-```typescript
-try {
-  await agent.send(prompt);
-} catch (err) {
-  const envelope: TheokitErrorEnvelope = toEnvelope(err); // { code, message, meta?, ext? }
-  send(envelope); // code is a TheokitErrorCode, e.g. "RATE_LIMITED"
-}
-
-// Inbound edge (e.g. worker receiving the envelope):
-const restored = fromEnvelope(envelope); // a TheokitAgentError subclass
-```

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

@@ -1,176 +0,0 @@
----
-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-client/SKILL.md

@@ -1,58 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*client*"
-  - "**/*Client*"
-description: TheoKit SDK low-level HTTP client — TheoKitClient (DEPRECATED; prefer the Agent façade)
----
-
-# TheoKit Client
-
-`TheoKitClient` is a browser-safe, zero-Node-dependency HTTP client (native
-`fetch` + manual SSE parsing) for a legacy server-adapter contract.
-
-> DEPRECATED since 2.x — the `@theokit/sdk/client` sub-path consumes a legacy
-> server-adapter HTTP contract (`POST /agent/send`, `GET /agent/stream`) that the
-> ecosystem no longer produces, and will be removed in the next major. For
-> in-process runs use the `Agent` façade (`@theokit/sdk`); for HTTP, use the
-> framework's typed `POST /api/agents/<name>` client. Reach for this only when
-> maintaining an existing integration against the old contract.
-
-```ts
-import { TheoKitClient } from "@theokit/sdk/client";
-import type { ClientOptions, SendResponse, StreamEvent } from "@theokit/sdk/client";
-```
-
-## Construct
-
-The constructor takes `ClientOptions` — `baseUrl` (required), optional `basePath`
-and `headers`.
-
-```ts
-const client = new TheoKitClient({
-  baseUrl: "https://adapter.example.com",
-  basePath: "/agent",                      // optional
-  headers: { authorization: "Bearer …" },  // optional
-});
-```
-
-## Send (one-shot)
-
-`send(input)` POSTs and resolves a `SendResponse` (`{ status, output?, error? }`).
-
-```ts
-const res: SendResponse = await client.send("summarize the repo");
-if (res.error) throw new Error(res.error);
-console.log(res.status, res.output);
-```
-
-## Stream (SSE)
-
-`stream(input)` returns an `AsyncGenerator<StreamEvent>`; each `StreamEvent` has a
-`type` and an optional `text` (plus arbitrary extra fields).
-
-```ts
-for await (const event of client.stream("build the changelog")) {
-  if (event.type === "text" && event.text) process.stdout.write(event.text);
-}
-```

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

@@ -1,102 +0,0 @@
----
-user-invocable: false
-paths:
-  - "**/*compact*"
-  - "**/*Compact*"
-description: TheoKit SDK compaction reference — compactTranscript, shouldCompact, checkpoints, context-overflow
----
-
-# TheoKit Compaction
-
-Public context-management helpers. Every function is pure and never mutates its
-input. A `CompressibleMessage` is `{ role: "user" | "assistant" | "system"; content: string }`.
-
-```typescript
-import {
-  compactTranscript,
-  shouldCompact,
-  estimateTokens,
-  buildCheckpoint,
-  filterFromLatestCheckpoint,
-  isContextOverflowError,
-  CHECKPOINT_MARKER,
-  SUMMARY_TEMPLATE,
-  type CompactTranscriptOptions,
-  type ShouldCompactInput,
-  type CompressibleMessage,
-} from "@theokit/sdk/compaction";
-```
-
-## Pre-call gate — `estimateTokens` + `shouldCompact`
-
-`estimateTokens` is a tokenizer-free `ceil(text.length / 4)` heuristic — a cheap
-gate, NOT exact tokenization. `shouldCompact` is pure: the caller supplies the
-model's window.
-
-```typescript
-const estimated = estimateTokens(transcript.map((m) => m.content).join("\n"));
-
-const input: ShouldCompactInput = {
-  estimated,
-  contextWindow: 200_000,
-  buffer: 8_000,     // headroom to reserve (output + safety margin)
-  maxOutput: 4_000,  // optional; separate response reservation (default 0)
-};
-
-if (shouldCompact(input)) {
-  // compact before sending — see below
-}
-```
-
-## `compactTranscript` — summarize the older window
-
-Default `keepRecent` mode keeps the last N turns verbatim (default 6) and
-preserves leading system prompts. The older window is summarized via the
-caller-supplied `summarize` callback (or dropped if omitted). With `failSafe`, a
-thrown summarizer returns the ORIGINAL transcript instead of propagating.
-
-```typescript
-const opts: CompactTranscriptOptions = {
-  keepRecent: 6,        // OR keepTokens: 40_000 (token-budget mode, takes precedence)
-  failSafe: true,
-  summarize: async (older: CompressibleMessage[], template: string) => {
-    // template is SUMMARY_TEMPLATE unless overridden via summaryTemplate
-    const summary = await callYourModel(template, older);
-    return { role: "system", content: summary };
-  },
-};
-
-const compacted = await compactTranscript(transcript, opts);
-```
-
-## Checkpoints — mark and filter
-
-`buildCheckpoint` produces a `system` turn whose content starts with
-`CHECKPOINT_MARKER`. `filterFromLatestCheckpoint` returns turns relative to the
-most recent marker (`include: "after"` excludes it — the default; `"from"`
-includes it).
-
-```typescript
-const marked = [...transcript, buildCheckpoint("milestone: tests green")];
-
-const recent = filterFromLatestCheckpoint(marked);              // after (exclusive)
-const withHead = filterFromLatestCheckpoint(marked, { include: "from" });
-```
-
-## Context-overflow detection
-
-`isContextOverflowError` is `true` only for a `TheokitAgentError` reporting the
-typed `context_too_long` code — never a brittle message regex.
-
-```typescript
-try {
-  await agent.send(prompt);
-} catch (err) {
-  if (isContextOverflowError(err)) {
-    const compacted = await compactTranscript(transcript, { keepRecent: 4 });
-    // retry with the compacted transcript
-  } else {
-    throw err;
-  }
-}
-```

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

@@ -1,68 +0,0 @@
----
-user-invocable: false
-description: Bound in-process parallelism with Semaphore.create and mapWithConcurrency from @theokit/sdk/concurrency.
-paths:
-  - "**/*concurren*"
-  - "**/*semaphore*"
-  - "**/*Semaphore*"
----
-
-# TheoKit SDK -- Concurrency
-
-In-house concurrency helpers (no `p-limit`/`p-map` dependency). `Semaphore.create(permits)` builds an N-permit async counting gate; `mapWithConcurrency` runs an async mapper over items with bounded parallelism while preserving input order.
-
-## Import
-
-```typescript
-import { Semaphore, mapWithConcurrency } from "@theokit/sdk/concurrency";
-import type { AsyncSemaphore } from "@theokit/sdk/concurrency";
-```
-
-## Signatures
-
-```typescript
-class Semaphore {
-  static create(permits: number): AsyncSemaphore; // canonical factory (ADR 0015)
-}
-
-interface AsyncSemaphore {
-  acquire(): Promise<() => void>; // returns a release fn; call it exactly once
-  inFlight(): number;             // permits currently held
-  pending(): number;              // in-flight + queued waiters
-}
-
-function mapWithConcurrency<T, R>(
-  items: ReadonlyArray<T>,
-  concurrency: number,                                     // positive integer; validated
-  fn: (item: T, index: number, signal: AbortSignal) => Promise<R>,
-  options?: { signal?: AbortSignal },
-): Promise<R[]>; // ordered; fail-fast; throws ConfigurationError on bad concurrency
-```
-
-## Semaphore -- release in a finally
-
-```typescript
-const sem = Semaphore.create(4); // at most 4 in flight
-
-async function guarded<T>(task: () => Promise<T>): Promise<T> {
-  const release = await sem.acquire();
-  try {
-    return await task();
-  } finally {
-    release(); // release exactly once (idempotent, but leaking it consumes a permit)
-  }
-}
-```
-
-## mapWithConcurrency -- ordered bounded map
-
-```typescript
-const controller = new AbortController();
-const results = await mapWithConcurrency(
-  ["a", "b", "c"],
-  2, // max 2 concurrent fetches
-  async (url, _index, signal) => (await fetch(url, { signal })).json(),
-  { signal: controller.signal },
-);
-// results align with input order; rejects on the first task error
-```

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

@@ -1,139 +0,0 @@
----
-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`.