@theokit/sdk 1.6.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "1.6.2",
+  "version": "1.8.0",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheo/theokit-sdk#readme",
@@ -48,16 +48,6 @@
         "default": "./dist/errors.cjs"
       }
     },
-    "./tools": {
-      "import": {
-        "types": "./dist/tools/index.d.ts",
-        "default": "./dist/tools.js"
-      },
-      "require": {
-        "types": "./dist/tools/index.d.cts",
-        "default": "./dist/tools.cjs"
-      }
-    },
     "./path-safety": {
       "import": {
         "types": "./dist/path-safety.d.ts",
@@ -108,32 +98,147 @@
         "default": "./dist/server/auth/index.cjs"
       }
     },
+    "./server/errors-envelope": {
+      "import": {
+        "types": "./dist/server/errors-envelope.d.ts",
+        "default": "./dist/server/errors-envelope.js"
+      },
+      "require": {
+        "types": "./dist/server/errors-envelope.d.cts",
+        "default": "./dist/server/errors-envelope.cjs"
+      }
+    },
+    "./subscription": {
+      "import": {
+        "types": "./dist/subscription/index.d.ts",
+        "default": "./dist/subscription/index.js"
+      },
+      "require": {
+        "types": "./dist/subscription/index.d.cts",
+        "default": "./dist/subscription/index.cjs"
+      }
+    },
+    "./internal/persistence": {
+      "import": {
+        "types": "./dist/internal/persistence/index.d.ts",
+        "default": "./dist/internal/persistence/index.js"
+      },
+      "require": {
+        "types": "./dist/internal/persistence/index.d.cts",
+        "default": "./dist/internal/persistence/index.cjs"
+      }
+    },
+    "./internal/plugins": {
+      "import": {
+        "types": "./dist/internal/plugins/index.d.ts",
+        "default": "./dist/internal/plugins/index.js"
+      },
+      "require": {
+        "types": "./dist/internal/plugins/index.d.cts",
+        "default": "./dist/internal/plugins/index.cjs"
+      }
+    },
+    "./internal/observability": {
+      "import": {
+        "types": "./dist/internal/observability/index.d.ts",
+        "default": "./dist/internal/observability/index.js"
+      },
+      "require": {
+        "types": "./dist/internal/observability/index.d.cts",
+        "default": "./dist/internal/observability/index.cjs"
+      }
+    },
+    "./internal/security": {
+      "import": {
+        "types": "./dist/internal/security/index.d.ts",
+        "default": "./dist/internal/security/index.js"
+      },
+      "require": {
+        "types": "./dist/internal/security/index.d.cts",
+        "default": "./dist/internal/security/index.cjs"
+      }
+    },
+    "./rag": {
+      "import": {
+        "types": "./dist/rag/index.d.ts",
+        "default": "./dist/rag/index.js"
+      },
+      "require": {
+        "types": "./dist/rag/index.d.cts",
+        "default": "./dist/rag/index.cjs"
+      }
+    },
+    "./a2a": {
+      "import": {
+        "types": "./dist/a2a/index.d.ts",
+        "default": "./dist/a2a/index.js"
+      },
+      "require": {
+        "types": "./dist/a2a/index.d.cts",
+        "default": "./dist/a2a/index.cjs"
+      }
+    },
+    "./client": {
+      "import": {
+        "types": "./dist/client/index.d.ts",
+        "default": "./dist/client/index.js"
+      },
+      "require": {
+        "types": "./dist/client/index.d.cts",
+        "default": "./dist/client/index.cjs"
+      }
+    },
+    "./sandbox": {
+      "import": {
+        "types": "./dist/sandbox/index.d.ts",
+        "default": "./dist/sandbox/index.js"
+      },
+      "require": {
+        "types": "./dist/sandbox/index.d.cts",
+        "default": "./dist/sandbox/index.cjs"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
     "bin",
+    "claude-template",
     "README.md",
     "CHANGELOG.md",
     "LICENSE"
   ],
   "bin": {
+    "theokit-init-claude": "./bin/init-claude.mjs",
     "theokit-migrate-config": "./bin/theokit-migrate-config.mjs",
     "theokit-migrate-memory": "./bin/theokit-migrate-memory.mjs"
   },
   "sideEffects": false,
+  "scripts": {
+    "build": "tsup && cp src/internal/providers/provider-catalog.json dist/provider-catalog.json",
+    "test": "vitest run --no-file-parallelism",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist",
+    "docs:json": "typedoc --options typedoc.json",
+    "docs:drift": "tsx scripts/check-docs-drift.ts"
+  },
   "peerDependencies": {
     "@lancedb/lancedb": "^0.30.0",
+    "@types/ws": ">=8.0.0",
     "better-sqlite3": "^12.0.0",
     "proper-lockfile": "^4.1.2",
     "sqlite-vec": "^0.1.0",
-    "zod": "^3.25.0 || ^4.0.0",
-    "zod-to-json-schema": "^3.24.0"
+    "ws": ">=8.0.0",
+    "zod": "^4.0.0"
   },
   "peerDependenciesMeta": {
     "@lancedb/lancedb": {
       "optional": true
     },
+    "@types/ws": {
+      "optional": true
+    },
     "better-sqlite3": {
       "optional": true
     },
@@ -143,7 +248,7 @@
     "sqlite-vec": {
       "optional": true
     },
-    "zod-to-json-schema": {
+    "ws": {
       "optional": true
     },
     "zod": {
@@ -151,7 +256,8 @@
     }
   },
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "keywords": [
     "agent",
@@ -172,22 +278,19 @@
     "croner": "^9.0.0"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/sdk-trace-base": "^1.30.1",
+    "@theokit/sdk-handoff": "workspace:*",
+    "@theokit/sdk-memory": "workspace:*",
     "@types/better-sqlite3": "^7.6.13",
     "@types/proper-lockfile": "^4.1.4",
+    "@types/ws": "^8.18.0",
     "better-sqlite3": "^12.10.0",
     "fast-check": "^4.8.0",
     "proper-lockfile": "^4.1.2",
     "sqlite-vec": "^0.1.9",
     "typedoc": "^0.28.19",
+    "ws": "^8.18.0",
     "zod": "^4.0.0"
-  },
-  "scripts": {
-    "build": "tsup",
-    "test": "vitest run --no-file-parallelism",
-    "test:watch": "vitest",
-    "typecheck": "tsc --noEmit",
-    "clean": "rm -rf dist",
-    "docs:json": "typedoc --options typedoc.json",
-    "docs:drift": "tsx scripts/check-docs-drift.ts"
   }
-}
+}

package/dist/budget.d.ts

@@ -1,48 +0,0 @@
-/**
- * `Budget` — token cost enforcement primitive (Adoption Roadmap #1
- * post-Tasks, ADRs D375-D388).
- *
- * Static facade delegating to the in-process registry + ledger.
- * 3 modes: `audit` (log-only), `warn` (callbacks + log), `block`
- * (preflight throw before LLM call).
- *
- * @public
- */
-import { computeCost } from "./internal/budget/compute-cost.js";
-import { chargeAndCheckThresholds, preflightCheck } from "./internal/budget/enforcement.js";
-import { inferApiMode, normalizeUsage } from "./internal/budget/normalize-usage.js";
-import { getPricingEntry } from "./internal/budget/pricing-registry.js";
-import { UsageAccumulator } from "./internal/budget/usage-accumulator.js";
-import type { BudgetHandle, BudgetOptions, BudgetSnapshot } from "./types/budget.js";
-export { chargeAndCheckThresholds, computeCost, getPricingEntry, inferApiMode, normalizeUsage, preflightCheck, UsageAccumulator, };
-export declare class Budget {
-    private constructor();
-    /**
-     * Create a budget. `name` must match `^[a-z0-9][a-z0-9_-]*$` (EC-7).
-     * Throws `ConfigurationError` if name is invalid OR already exists
-     * (EC-16: duplicate surface caller bug).
-     *
-     * `limits` is stacked (D384) — ANY exceeded triggers enforcement.
-     * Empty `limits[]` is valid: pure tracking, no thresholds/exceed
-     * callbacks fire (EC-19).
-     *
-     * Default `mode` is `"warn"` (D383). For emergency stop, use
-     * `mode: "block", limits: [{ window: "1d", limitUsd: 0 }]` (EC-18).
-     */
-    static create(options: BudgetOptions): BudgetHandle;
-    /** Returns the handle for an active budget, or `undefined`. */
-    static get(name: string): BudgetHandle | undefined;
-    /** Returns all active budgets. */
-    static list(): readonly BudgetHandle[];
-    /**
-     * Deletes a budget from the registry. Returns `true` if it existed.
-     * In-flight `agent.send` calls referencing the name treat the
-     * subsequent charge as a silent no-op + stderr warn (EC-20).
-     */
-    static delete(name: string): boolean;
-    /**
-     * Returns per-window spend snapshot for all active budgets. Each
-     * entry has `{ name, window, spentUsd, limitUsd, ratio }`.
-     */
-    static snapshot(): readonly BudgetSnapshot[];
-}

package/dist/cache.d.ts

@@ -1,74 +0,0 @@
-/**
- * Public `Cache` class — semantic LLM response cache (Adoption Roadmap #6;
- * ADRs D249-D266).
- *
- * Usage:
- *
- *   import { Agent, Cache, definePlugin } from "@theokit/sdk";
- *
- *   const cache = Cache.semantic({
- *     embedder: myEmbedderRuntime,    // EmbeddingRuntime (D11)
- *     threshold: 0.85,
- *     ttl: { default: "1h", exclude: /weather|today|now/i },
- *     namespace: "my-app",
- *     modelId: "openai/gpt-4o-mini",
- *   });
- *
- *   const agent = await Agent.create({
- *     model: { id: "openai/gpt-4o-mini" },
- *     plugins: [cache.asPlugin()],
- *     // ...
- *   });
- *
- *   await agent.send("What is the capital of France?");   // miss → LLM
- *   await agent.send("Tell me the capital of France");    // semantic hit
- *
- * @public
- */
-import type { Plugin } from "./internal/plugins/types.js";
-import type { CacheSemanticOptions, CacheStats } from "./types/cache.js";
-export declare class Cache {
-    private readonly embedder;
-    private readonly threshold;
-    private readonly ttl;
-    private readonly namespace;
-    private readonly modelId;
-    private readonly store;
-    private _plugin?;
-    private constructor();
-    static semantic(options: CacheSemanticOptions): Cache;
-    /**
-     * EC-4 absorbed: memoized so repeated `asPlugin()` calls return the SAME
-     * plugin descriptor — no duplicate hook registration.
-     */
-    asPlugin(): Plugin;
-    /**
-     * Explicit cache lookup — callers that want true LLM short-circuit
-     * call this BEFORE `agent.send()`, then dispatch to the LLM only on miss.
-     *
-     * v1 plugin mode provides recall + context-inject (LLM still called).
-     * v1.x will add transparent short-circuit via an agent-loop refactor.
-     */
-    consult(prompt: string): Promise<{
-        hit: false;
-    } | {
-        hit: true;
-        response: string;
-        source: "kv" | "semantic";
-        distance?: number;
-    }>;
-    /**
-     * Explicit cache store — pair with `consult()` to manually feed the
-     * cache after dispatching the LLM call yourself.
-     */
-    remember(prompt: string, response: string, opts?: {
-        usedTools?: boolean;
-    }): Promise<void>;
-    /** Stats snapshot — primary observable for dogfood verification. */
-    stats(): CacheStats;
-    /** Clear all entries (and flush to disk if JSON backend). */
-    clear(): Promise<void>;
-    /** Force-evict expired entries. Returns count removed. */
-    evictExpired(now?: number): number;
-}
-export { CacheEmbedderError, CacheInvalidTtlError } from "./types/cache.js";

package/dist/cron-1yxL3K2S.d.cts

@@ -1,221 +0,0 @@
-import { aG as SDKUserMessage, A as AgentOptions, j as ListResult, m as Run } from './run-DkCD5DeO.cjs';
-
-/**
- * Runtime hosting a cron job. Mirrors the agent runtime split.
- *
- * - `local` — the in-process scheduler activated via `Cron.start()` fires the
- *   job while the host process is alive.
- * - `cloud` — Theo PaaS schedules the job server-side; fires independent of
- *   any SDK process.
- *
- * @public
- */
-type CronRuntime = "local" | "cloud";
-/**
- * Lifecycle state reported by `Cron.list()` / `Cron.get()`.
- *
- * @public
- */
-type CronJobStatus = "scheduled" | "running" | "paused" | "errored";
-/**
- * Persistent cron-scheduled invocation of the Theo agent.
- *
- * Exactly one of {@link CronJob.agent} (ephemeral agent created on each fire)
- * or {@link CronJob.agentId} (bound to an existing agent for context
- * continuity) is set.
- *
- * @public
- */
-interface CronJob {
-    id: string;
-    name?: string;
-    /** Standard 5-field POSIX cron expression or shorthand (`@hourly`, `@daily`, ...). */
-    cron: string;
-    /** IANA timezone identifier. Defaults to `"UTC"`. */
-    timezone?: string;
-    /** Message sent to the agent on each fire. */
-    message: string | SDKUserMessage;
-    /** Ephemeral agent options. Mutually exclusive with `agentId`. */
-    agent?: AgentOptions;
-    /** ID of an existing agent to reuse for context continuity. Mutually exclusive with `agent`. */
-    agentId?: string;
-    /** Whether the scheduler will fire this job on schedule. */
-    enabled: boolean;
-    /** Current status. */
-    status: CronJobStatus;
-    /** Runtime that hosts this job. Inferred from `agent`/`agentId` at create time. */
-    runtime: CronRuntime;
-    /** Unix ms of the last successful fire, if any. */
-    lastRunAt?: number;
-    /** Unix ms of the next scheduled fire, computed by the scheduler. */
-    nextRunAt?: number;
-    /** Unix ms when the job was created. */
-    createdAt: number;
-}
-/**
- * Options for `Cron.create()`.
- *
- * Pass `agent` for an ephemeral agent created fresh on each fire, OR
- * `agentId` to reuse an existing agent (preserves conversation context across
- * fires). Setting both is a `ConfigurationError`.
- *
- * @public
- */
-interface CronCreateOptions {
-    cron: string;
-    message: string | SDKUserMessage;
-    agent?: AgentOptions;
-    agentId?: string;
-    name?: string;
-    timezone?: string;
-    /** Defaults to `true`. */
-    enabled?: boolean;
-    /** Falls back to `THEOKIT_API_KEY`. */
-    apiKey?: string;
-}
-/**
- * Options for `Cron.list()`.
- *
- * @public
- */
-type CronListOptions = {
-    limit?: number;
-    cursor?: string;
-} & ({
-    runtime?: undefined;
-} | {
-    runtime: "local";
-    cwd?: string;
-} | {
-    runtime: "cloud";
-    apiKey?: string;
-});
-/**
- * Options for `Cron.get()`.
- *
- * @public
- */
-interface CronGetOptions {
-    cwd?: string;
-    apiKey?: string;
-}
-/**
- * Options for `Cron.delete()` / `Cron.enable()` / `Cron.disable()`.
- *
- * @public
- */
-interface CronOperationOptions {
-    cwd?: string;
-    apiKey?: string;
-}
-/**
- * Options for `Cron.run()` — manually trigger a job off-schedule.
- *
- * @public
- */
-interface CronRunOptions {
-    cwd?: string;
-    apiKey?: string;
-}
-/**
- * Options for `Cron.start()` — activates the in-process scheduler for local
- * jobs.
- *
- * @public
- */
-interface CronStartOptions {
-    /** Local workspace whose `.theokit/cron/jobs.json` to load. Defaults to `process.cwd()`. */
-    cwd?: string;
-    /** Override the env API key. */
-    apiKey?: string;
-}
-/**
- * Snapshot of the local scheduler returned by `Cron.status()`.
- *
- * @public
- */
-interface CronSchedulerStatus {
-    /** Whether the in-process scheduler is currently running. */
-    running: boolean;
-    /** Number of jobs loaded into the scheduler. */
-    jobCount: number;
-    /** Unix ms of the next scheduled fire across all jobs, if any. */
-    nextFireAt?: number;
-    /** Last error observed in the scheduler, if any. */
-    lastError?: {
-        jobId: string;
-        message: string;
-        at: number;
-    };
-}
-
-/**
- * Static façade for scheduling Theo agent runs on a cron expression.
- *
- * @public
- */
-declare class Cron {
-    private constructor();
-    /**
-     * Create and persist a cron job.
-     *
-     * @public
-     */
-    static create(options: CronCreateOptions): Promise<CronJob>;
-    /**
-     * List cron jobs (local, cloud, or both).
-     *
-     * @public
-     */
-    static list(options?: CronListOptions): Promise<ListResult<CronJob>>;
-    /**
-     * Get a single cron job by ID.
-     *
-     * @public
-     */
-    static get(jobId: string, _options?: CronGetOptions): Promise<CronJob>;
-    /**
-     * Delete a cron job permanently.
-     *
-     * @public
-     */
-    static delete(jobId: string, _options?: CronOperationOptions): Promise<void>;
-    /**
-     * Re-enable a paused cron job.
-     *
-     * @public
-     */
-    static enable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
-    /**
-     * Pause a cron job without deleting it.
-     *
-     * @public
-     */
-    static disable(jobId: string, _options?: CronOperationOptions): Promise<CronJob>;
-    /**
-     * Manually trigger a cron job off-schedule. Returns the resulting `Run`.
-     *
-     * @public
-     */
-    static run(jobId: string, _options?: CronRunOptions): Promise<Run>;
-    /**
-     * Activate the in-process scheduler for local cron jobs.
-     *
-     * @public
-     */
-    static start(options?: CronStartOptions): Promise<void>;
-    /**
-     * Stop the in-process scheduler. Jobs are preserved.
-     *
-     * @public
-     */
-    static stop(): Promise<void>;
-    /**
-     * Snapshot of the local scheduler.
-     *
-     * @public
-     */
-    static status(_options?: CronStartOptions): Promise<CronSchedulerStatus>;
-}
-
-export { Cron as C, type CronCreateOptions as a, type CronGetOptions as b, type CronJob as c, type CronJobStatus as d, type CronListOptions as e, type CronOperationOptions as f, type CronRunOptions as g, type CronRuntime as h, type CronSchedulerStatus as i, type CronStartOptions as j };