@theokit/sdk 1.9.0 → 2.0.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 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
+
+- b9f30a6: Carve the non-Harness surface out of `@theokit/sdk` (plan `monorepo-cohesion-split`). The SDK now ships only the Agent-AI Harness.
+
+  BREAKING (no retro-compat, authorized):
+
+  - Removed the `@theokit/sdk/rag` sub-path export and the embedded `voice` module — they moved to standalone `@theokit/rag` / `@theokit/voice` packages (repos `theokit-rag` / `theokit-voice`). Import those packages instead.
+  - Decorator-first DX is no longer required of Harness features (ADR D431). `@theokit/di` / `@theokit/di-agent` / `@theokit/orm` moved to `theokit-backend-dx`, the gateway packages to `theokit-gateways`, `@theokit/react` to `theokit-react`, and `@theokit/skills-google-workspace` to the Skills pillar. Decorators remain available as an optional layer via the externally-published `@theokit/di`.
+
+  The surviving `@theokit/sdk-*` extension peer specifiers stay as semver ranges (`>=1.7.0`), satisfying the publish-readiness gate.
+
 ## 1.9.0
 
 ### Minor Changes
@@ -19,10 +45,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).
 
@@ -53,7 +84,7 @@
 
 - **Compression config resolution module (T2.2 step 2/N of plan `sdk-superiority-2026-06-07`, ADR D440)**: `resolveCompressionConfig(agentModel, config): ResolvedCompressionConfig` bridges the compression-model-registry (step 1) with the `Agent.create({compression})` override surface. Resolves: (a) compression model — registry default OR explicit `config.model` override; (b) API key — first-match chain: explicit `config.apiKey` → `THEOKIT_COMPRESSION_API_KEY` env var → undefined (signals aux-LLM client to use agent's main CredentialPool); (c) maxAttempts (default 3) + grace (default 1). Pure config resolution — no I/O. 11 new tests at `tests/internal/runtime/compression-config.test.ts`. Foundation for step 3 (aux-llm-client with OTel span) and step 4 (agent-loop wire).
 
-- **Model capabilities introspection registry (T3.10c step 1 of plan `sdk-superiority-2026-06-07`, DR3 #17)**: pre-T3.10c the SDK had no way to query a model's capability flags before sending a request — consumers who sent vision content to a text-only model or structured-output requests to a model without json_schema support got an opaque 400 from the provider. T3.10c step 1 adds the foundation pure-function registry `resolveModelCapabilities(modelId): ModelCapabilities` with typed per-model flags: `supportsVision`, `supportsStructuredOutput`, `supportsToolUse`, `supportsCacheControl`, `maxContextTokens`, `maxOutputTokens`. Resolution algorithm: strip routing prefixes (openrouter/, vertex/, bedrock/), exact-match against the vendor-model registry, then infer vendor from model name (claude-_ → anthropic/, gpt-_ → openai/, gemini-\* → google/) for routing-prefixed lookups. Unknown models return conservative defaults (all false, 4096/4096 token counts) — never optimistic assumptions. Initial registry covers OpenAI (gpt-4o/4o-mini/4-turbo/o1/o3) and Anthropic (claude-opus-4/sonnet-4/3-5-sonnet/3-haiku/3-opus) families. 9 new tests at `tests/internal/llm/model-capabilities.test.ts`. Foundation for step 2 (public `Theokit.models.capabilities()` API) and step 3 (Agent.create boundary gate + `CapabilityNotSupportedError`).
+- **Model capabilities introspection registry (T3.10c step 1 of plan `sdk-superiority-2026-06-07`, DR3 #17)**: pre-T3.10c the SDK had no way to query a model's capability flags before sending a request — consumers who sent vision content to a text-only model or structured-output requests to a model without json*schema support got an opaque 400 from the provider. T3.10c step 1 adds the foundation pure-function registry `resolveModelCapabilities(modelId): ModelCapabilities` with typed per-model flags: `supportsVision`, `supportsStructuredOutput`, `supportsToolUse`, `supportsCacheControl`, `maxContextTokens`, `maxOutputTokens`. Resolution algorithm: strip routing prefixes (openrouter/, vertex/, bedrock/), exact-match against the vendor-model registry, then infer vendor from model name (claude-* → anthropic/, gpt-\_ → openai/, gemini-\* → google/) for routing-prefixed lookups. Unknown models return conservative defaults (all false, 4096/4096 token counts) — never optimistic assumptions. Initial registry covers OpenAI (gpt-4o/4o-mini/4-turbo/o1/o3) and Anthropic (claude-opus-4/sonnet-4/3-5-sonnet/3-haiku/3-opus) families. 9 new tests at `tests/internal/llm/model-capabilities.test.ts`. Foundation for step 2 (public `Theokit.models.capabilities()` API) and step 3 (Agent.create boundary gate + `CapabilityNotSupportedError`).
 
 ### Fixed