@theokit/sdk 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 2.1.0
+
+### Minor Changes
+
+- 7d53632: Custom LLM providers via the public Plugin protocol (plan `dev-friendly-custom-provider`).
+
+  - **Added** `defineProvider(profile, opts?)` — canonical factory (mirrors `defineTool`/`definePlugin`, Inviolable Rule 9) that wraps a data-only `ProviderProfile` into a `kind: "model-provider"` `Plugin`. Register any OpenAI-/Anthropic-compatible endpoint (Groq, Together, Fireworks, DeepInfra, a private gateway) with `Agent.create({ model: { id: "myprov/model" }, plugins: [defineProvider(profile)] })`, routed via the `provider/model` id prefix. Exported from `@theokit/sdk`.
+  - **Fixed** half-wired `kind: "model-provider"` plugin path: `PluginManager` aggregated provider profiles but nothing registered them, so `getProviderProfile`/`resolveProviderChain` never saw a plugin-contributed provider — a programmatic `model-provider` plugin was silently dropped. The local-agent run now registers plugin-contributed profiles before provider-chain resolution, so custom providers actually route.
+  - **Docs** new "Custom providers (`defineProvider`)" section in `docs.md` (field reference + `apiMode` table) and a worked `examples/custom-provider/`.
+
+- 872c89e: M0 Foundation — expose already-existing internal primitives as public surfaces (plan `m0-foundation-expose-primitives`), so agent/code-assistant builders reuse battle-tested plumbing instead of re-implementing it.
+
+  - `isTransientError(err)` — public retryability predicate delegating to `TheokitAgentError.isRetryable` (T1.1).
+  - `safeFilenameForId(id, { maxLen })` — total id→filename helper via `@theokit/sdk/path-safety` (passthrough when safe, deterministic sha256 token otherwise); `sanitizeRunId` migrated to it (T2.1).
+  - `@theokit/sdk/concurrency` — public `createSemaphore` + new ordered, fail-fast `mapWithConcurrency`; two internal pooling clones deduplicated onto it (T3.1).
+  - `@theokit/sdk/retry` — generic `withRetry(fn, options)` (exponential backoff + full jitter, injectable sleep/rng, default `isRetryable = isTransientError`) (T4.1).
+  - `openSqliteResilient` (`@theokit/sdk/internal/persistence`, semver-exempt) — shared driver-load + WAL + corruption-recovery; both memory `index-db` copies deduplicated onto it (T5.1).
+
+## 2.0.1
+
+### Patch Changes
+
+- aac62bc: Internal architecture cleanup (arch-review Groups A–D) — no public API or behavior change.
+
+  - **Group A:** widen the internal `agent-factory-registry` inversion seam from `create()` to a full `AgentFacadePort` (`create`/`prompt`/`get`/`resume`/`batch`); route `internal/{eval,scorers,cron}` through `getAgentFacade()` instead of importing the public `Agent` facade upward. A `internal-must-not-import-facade` dependency-cruiser rule now enforces the boundary. `cron.ts`/`eval.ts` gained an `import "./agent.js"` bootstrap (kept out of tree-shaking via the `sideEffects` allowlist) so the `@theokit/sdk/cron` and `@theokit/sdk/eval` sub-path entries still register the facade at load time.
+  - **Group B:** relocated the 17 loose `internal/runtime/*.ts` modules into cohesive sub-folders (`lifecycle/`, `validation/`, `concurrency/`, `tools/`, `config/`, plus folding `system-prompt.ts`/`yaml-frontmatter.ts` into existing dirs); removed the dead `internal/runtime/mcp-tools.ts`.
+  - **Group C:** removed the cargo-cult `TheoKitContainer` (was `@public` but never exported; `run()` discarded registered tools/workflows); the `multi-agent` template now uses `Agent.create()`.
+  - **Group D:** renamed `internal/errors/` → `internal/error-mappers/` (the directory holds only provider error-mappers, no error classes).
+
+  All changes are internal-only and behavior-preserving (full suite GREEN, `madge --circular` unchanged, depcruise clean). Consumers see no API or behavior difference.
+
 ## 2.0.0
 
 ### Major Changes
@@ -32,10 +63,15 @@
 
 ### Fixed
 
+- The Agent-facade bootstrap added in Group A (`import "./agent.js"` in `cron.ts`/`eval.ts`) was tree-shaken out of the built `cron.js`/`eval.js` bundles under `package.json "sideEffects": false` + tsup `treeshake: true`. SDK-source tests passed but real **dist** consumers (e.g. `@theokit/cli` via `@theokit/sdk/eval`) hit `internal: Agent facade not registered` at runtime. Declared `agent.{ts,js,cjs}` in the `sideEffects` allowlist so the bootstrap survives bundling while the rest of the package stays tree-shakeable. Bundle size unchanged from the pre-Group-A baseline. (arch-review Group A follow-up; caught by `pnpm validate`)
 - `Agent.batch` now validates its inputs at the boundary (fail-fast). Invalid `concurrency` (not a positive integer) throws `ConfigurationError(code: "invalid_concurrency")` with a user-facing message, and an empty/non-string prompt item throws `ConfigurationError(code: "invalid_batch_item")` — both BEFORE any credential pool is built or Task is registered. Previously invalid `concurrency` surfaced only deep inside the semaphore with a leaky "permits" message AND after task registration (a dangling Task could be registered with `task: true`), and empty-string prompts flowed silently to `agent.send`. New `validateBatchInput` pre-flight; whitespace-only prompts are intentionally still accepted (non-empty strings; the validator does not judge content). (arch-review cross-validation Gap 3)
 
 ### Changed
 
+- Renamed `src/internal/errors/` → `src/internal/error-mappers/`, collapsing the redundant `mappers/` nesting (arch-review Group D). The directory held only provider error-mapper implementations (anthropic, bedrock, ollama, openai-compatible, vertex, shared) and zero error classes — those live in `src/errors.ts` — so `errors/` was a misnomer. Pure rename + import-path fixups across importers, tests (moved to `tests/internal/error-mappers/`), and `docs/error-codes.md`; no API/behavior change.
+- Removed the cargo-cult `TheoKitContainer` (`src/theokit-container.ts`, arch-review Group C). It was `@public`-annotated but never exported from `index.ts` — no consumer could import it, so removal has zero real breaking impact — and its `run()` rebuilt a fresh `Agent.create` from only `model`/`apiKey`/`systemPrompt`, silently discarding the registered `tools`/`workflows` (dead, misleading surface that contradicts ADR D431's "factory functions are canonical; no in-SDK IoC container"). The `multi-agent` template + README now coordinate specialists via `Agent.create()`. The container's e2e error-propagation test was re-expressed as genuine coverage of the REAL `AgentDisposedError` thrown by `local-agent-send.ts` (the container had faked it with a string) — a net coverage gain. Deleted `tests/theokit-container.test.ts` + `tests/e2e/container-multi-agent.e2e.test.ts` (pure container bookkeeping, no Agent-level coverage).
+- Completed the `internal/runtime/` root cleanup (arch-review Group B). The flat root previously held 18 loose modules (down from 62 after M4); relocated the remaining 17 into cohesive sub-folders — `lifecycle/` (run-until, fork-agent, post-run-lifecycle, spawn-collect, auto-summarize), `validation/` (validate-agent-options, validate-response), `concurrency/` (async-local-storage, async-semaphore, abort-utils), `tools/` (shell-tool, hitl-middleware), `config/` (default-model, workspace-dir, providers-manager) — plus folding `system-prompt.ts` into the existing `system-prompt/` dir and `yaml-frontmatter.ts` into `context/`. `internal/runtime/` root now holds zero loose `.ts`. Removed the dead `internal/runtime/mcp-tools.ts` (`buildToolList` had zero callers; survived prior gates because orphan detection excludes `internal/`). Pure `git mv` + import-path fixups (39 importer files), one dead-code deletion; no API/behavior change. Full suite GREEN (2616 pass); `madge --circular` unchanged (1 type-only cycle); depcruise clean.
+- Closed the last 3 wrong-direction imports where `internal/{eval,scorers,cron}` imported the public `Agent` facade directly (arch-review Group A). The `agent-factory-registry` inversion seam was widened from a single `create()` to a full `AgentFacadePort` (`create`/`prompt`/`get`/`resume`/`batch`); `eval/runner` (batch), `scorers/llm-judge` (prompt), and `cron/run-job` (get/resume/create) now resolve the facade via `getAgentFacade()` instead of inverting the public-api → internal dependency direction. A new `internal-must-not-import-facade` dependency-cruiser rule permanently enforces the boundary. The `cron.ts`/`eval.ts` facades gained an explicit `import "./agent.js"` bootstrap so the `@theokit/sdk/cron` and `@theokit/sdk/eval` sub-path entries still register the facade at load time (preserving the side effect the removed direct imports used to provide). Fully internal — no API/behavior change; full suite GREEN, `madge --circular` unchanged (1 intentional type-only cycle), depcruise clean.
 - Reorganized the flat 62-file `src/internal/runtime/` god folder into sub-concern folders (arch-review M4): `local-agent/` (15), `cloud/` (6), `compression/` (6), `hooks/` (4), `budget/` (3), `memory/` (4), `session/` (3), `skills/` (3) — alongside the pre-existing `registry/`, `system-prompt/`, `context/`, `fixtures/`, `plugins/`. 18 cross-cutting singletons (abort-utils, async-_, default-model, fork-agent, run-until, system-prompt, validate-_, etc.) remain at the `runtime/` root (down from 62). Pure file moves + import-path updates (44 files moved, ~100 import sites rewritten incl. 2 lint-allowlist path updates); `internal/runtime` is not an exported subpath and has no tsup entry, so the change is fully internal — no API/behavior change. Full SDK suite GREEN (2629 tests); `madge --circular` unchanged (1 intentional type-only `memory/memory-provider` cycle).
 - Broke 2 of 3 type-only dependency cycles in the public type barrel (arch-review ADR 0001). `ForkOptions`/`ForkResult` moved to a leaf `types/fork.ts`, so `types/agent.ts` no longer imports the `internal/runtime/fork-agent.ts` implementation (`fork-agent.ts` re-exports them for back-compat). Eliminates the `types/agent.ts → fork-agent.ts → {plugins/types,(self)}` cycles. No behavior/API change; `madge --circular` drops from 3 to 1 (the remaining `memory-provider` cycle is a genuine bidirectional type relationship, runtime-safe, left intentionally).