@theokit/sdk 5.1.0 → 5.2.1

package/CHANGELOG.md

@@ -1,5 +1,127 @@
 # Changelog
 
+## 5.2.1
+
+### Patch Changes
+
+- [#594](https://github.com/usetheokit/theokit-sdk/pull/594) [`9dc8cf5`](https://github.com/usetheokit/theokit-sdk/commit/9dc8cf52bee690bfb9cf55bee63bcda71d3132b3) Thanks [@usetheodev](https://github.com/usetheodev)! - `effectiveToolNames` refuses a created tool instead of answering confidently about it ([#583](https://github.com/usetheokit/theokit-sdk/issues/583) follow-up)
+  
+  Every field on `AgentOptions` is optional, so the `CustomTool` that `SubAgent.create()` returns —
+  `{ name, description, inputSchema, handler }` — satisfies the type **by vacuity, with no cast**.
+  Measured: a `@ts-expect-error` on that call is reported unused (`TS2578`), so the compiler genuinely
+  does not refuse it.
+  
+  What came back was worse than a wrong number:
+  
+  ```ts
+  effectiveToolNames(SubAgent.create({ name: "analyst", … }))
+  // { names: ["shell"], unresolved: [] }
+  ```
+  
+  The empty `unresolved` claims **completeness** about an object the function never understood. A
+  caller reads that as *"this subagent still announces a shell"* and either disbelieves a fix that
+  worked, or "fixes" something on the strength of it. That is the defect [#583](https://github.com/usetheokit/theokit-sdk/issues/583) exists to eliminate, one
+  function further on — and the same argument that made this return `{ names, unresolved }` rather than
+  a bare array forbids it.
+  
+  It now throws a `ConfigurationError` naming what to pass instead. The detection is exact rather than
+  heuristic: `AgentOptions` declares neither `handler` nor `inputSchema`, so an object carrying **both**
+  is a tool and not options.
+  
+  **The workaround is still needed, and the 5.2.0 notes should not have implied otherwise.**
+  `SubAgent.create()` closes its spec inside the handler, so the spec cannot be recovered from the
+  returned tool — keep it in a variable, or extract it into a function a test can call, and pass that.
+  
+  Reported by the `theocode` session, against advice of mine that was wrong.
+
+## 5.2.0
+
+### Minor Changes
+
+- [#585](https://github.com/usetheokit/theokit-sdk/pull/585) [`86bf6c1`](https://github.com/usetheokit/theokit-sdk/commit/86bf6c1ab90438835df5bb0d4a791596c58004ba) Thanks [@usetheodev](https://github.com/usetheodev)! - `effectiveToolNames` — ask what tools an agent will actually have ([#583](https://github.com/usetheokit/theokit-sdk/issues/583))
+  
+  `Agent.describe()` was the only reflection surface, and it builds its catalog as
+  `(options.tools ?? [])` — literally the array the caller passed. The SDK's own builtins were never in
+  it, so the two states that matter most were indistinguishable:
+  
+  ```
+  Agent.create({ tools: [] })                    describe().tools = []   ← holds a shell
+  the same + withheldBuiltinTools: ["shell"]     describe().tools = []   ← holds nothing
+  ```
+  
+  A consumer confirming that a role declared read-only really is one had no instrument. What they did
+  instead, measured in a real session: ask the agent to enumerate its own catalog — needs a credential,
+  needs the network, and returns the list the *model* decided to write. That same session recorded a
+  subagent answering *"I can't run shell commands in this environment"* while its catalog listed
+  `shell`. An attempt measures the model's disposition; the catalog measures its authority.
+  
+  ```ts
+  import { effectiveToolNames } from "@theokit/sdk";
+  
+  const { names, unresolved } = effectiveToolNames({ tools: [], withheldBuiltinTools: ["shell"] });
+  // names: []          — the shell is genuinely gone
+  // unresolved: []     — nothing else could contribute, so [] is the whole catalog
+  ```
+  
+  **Options in, not an agent id** — synchronous, credential-free, answerable *before* the agent runs,
+  so a test can compare what it declared against what the runtime will declare. `describe()` needs a
+  registered agent and answers too late for that.
+  
+  **Not a bare array**, deliberately. MCP tools need a live connection; plugin tools and the reasoning
+  `think` tool are assembled per run. Returning `string[]` would rebuild the original defect one
+  function over. `unresolved` names the sources that are configured and could not be enumerated, and is
+  empty when none are — which is the only condition under which `names` may be read as complete.
+  
+  Requested, with this exact shape and rationale, by the `theocode` session after it had to work around
+  the gap by extracting a subagent spec into a separate function just to assert on it.
+
+### Patch Changes
+
+- Correct a version number in the 5.1.0 release notes
+  
+  The 5.1.0 entry *"Snapshot versions now sort ABOVE the release they are cut from"* illustrates the
+  result as `5.0.2-compat-580-…`. **That digit was invented rather than derived.** The pending
+  changesets included a `minor`, so the calculated base was `5.1.0`, and the first cut after the change
+  printed:
+  
+  ```
+  5.1.0-compat-581-20260905211819
+  ```
+  
+  A correction was written before the release and did not reach it: it lived in a pull request that had
+  not merged when `changeset version` consumed the changeset, so the uncorrected text shipped.
+  
+  Recorded as a new entry rather than by editing the published one, per this project's changelog
+  discipline — a released entry is a record of what was said at the time, and rewriting it hides that
+  the correction happened.
+  
+  **Why a wrong digit was worth two entries:** the property that mattered — sorting above `5.0.0` —
+  held with either number. An invented value that does not change the conclusion is the kind that stays
+  uncorrected forever, and a reader comparing the changelog against what they installed would have
+  found an unexplained discrepancy and rightly concluded one of the two was lying.
+
+- [#585](https://github.com/usetheokit/theokit-sdk/pull/585) [`86bf6c1`](https://github.com/usetheokit/theokit-sdk/commit/86bf6c1ab90438835df5bb0d4a791596c58004ba) Thanks [@usetheodev](https://github.com/usetheodev)! - `CompatSurface` is declared once ([#586](https://github.com/usetheokit/theokit-sdk/issues/586))
+  
+  It was declared twice, independently — `types/agent.ts` (public, typing
+  `AgentOptions.local.compatSources`) and `internal/runtime/compat/foreign-config-sources.ts` (typing
+  the admission logic and `persistence/paths.ts`). Neither imported the other.
+  
+  Measured: adding a member to one alone produced **zero** type errors. Structurally identical unions
+  compare equal, so the two halves of one public contract could stop agreeing about which surfaces
+  exist, silently. Widen the public type and a caller declares a surface the admission logic ignores;
+  widen the internal one and the loader admits a surface no public caller can name. Both produce a
+  declaration that reads as honoured and is not.
+  
+  `types/` is a leaf by design, so the public declaration stays and the internal module imports it.
+  
+  The runtime list `COMPAT_SURFACES` cannot be derived from a type, so it remains a second copy of the
+  members — and a compile-time exhaustiveness check now pairs the two, in both directions.
+  
+  **The first version of that check was decorative and this is worth recording:** annotating the list
+  `readonly CompatSurface[]` widens each entry back to `CompatSurface`, so the check compared a type
+  against itself and passed on any drift. It was caught by testing the guard rather than trusting it —
+  a member added to the public type produced zero errors. `as const satisfies` keeps the literals.
+
 ## 5.1.0
 
 ### Minor Changes

package/dist/{agent-ARLOD4JX.cjs → agent-GACKKINM.cjs}

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkD3CCY3A2_cjs = require('./chunk-D3CCY3A2.cjs');
+var chunkDEJCKB65_cjs = require('./chunk-DEJCKB65.cjs');
 require('./chunk-KVSAY6NZ.cjs');
 require('./chunk-Y2KYR2ED.cjs');
 require('./chunk-BUUUWQMB.cjs');
 require('./chunk-Z2JFX372.cjs');
-require('./chunk-KGANQYP7.cjs');
+require('./chunk-SSIRPWWD.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-D6POWE7E.cjs');
 require('./chunk-GHX4P3V2.cjs');
@@ -43,8 +43,8 @@ require('./chunk-BJUJT5ED.cjs');
 require('./chunk-ZF2LDKQQ.cjs');
 require('./chunk-HCT4HPCL.cjs');
 require('./chunk-JLRLCBJ4.cjs');
-require('./chunk-QYLZQ43D.cjs');
-require('./chunk-NYQ3IS7K.cjs');
+require('./chunk-IQBDR5YZ.cjs');
+require('./chunk-DWB3CN46.cjs');
 require('./chunk-HW7SEELD.cjs');
 require('./chunk-ATT276RD.cjs');
 require('./chunk-3EE6LVWT.cjs');
@@ -61,7 +61,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkD3CCY3A2_cjs.Agent; }
+  get: function () { return chunkDEJCKB65_cjs.Agent; }
 });
-//# sourceMappingURL=agent-ARLOD4JX.cjs.map
-//# sourceMappingURL=agent-ARLOD4JX.cjs.map
+//# sourceMappingURL=agent-GACKKINM.cjs.map
+//# sourceMappingURL=agent-GACKKINM.cjs.map

package/dist/{agent-ARLOD4JX.cjs.map → agent-GACKKINM.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-ARLOD4JX.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-GACKKINM.cjs"}

package/dist/{agent-N6WJ54ML.js → agent-VUNM33WJ.js}

@@ -1,9 +1,9 @@
-export { Agent } from './chunk-OYD3U3LY.js';
+export { Agent } from './chunk-43H4EBS2.js';
 import './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
 import './chunk-7SZAV6QG.js';
-import './chunk-AW6F6HZR.js';
+import './chunk-AI4MXACC.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.js';
@@ -41,8 +41,8 @@ import './chunk-TA3K7SBK.js';
 import './chunk-Q5EWJPRY.js';
 import './chunk-EIQFAOFD.js';
 import './chunk-3JHIFQ4I.js';
-import './chunk-OQRGVTQF.js';
-import './chunk-WMWEI3NS.js';
+import './chunk-DLFWMJE3.js';
+import './chunk-RP3VXJMA.js';
 import './chunk-JNAA4G4H.js';
 import './chunk-6M2OIS4Y.js';
 import './chunk-R7WIIPUR.js';
@@ -54,5 +54,5 @@ import './chunk-V22DZIXO.js';
 import './chunk-NJWYQWDL.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-N6WJ54ML.js.map
-//# sourceMappingURL=agent-N6WJ54ML.js.map
+//# sourceMappingURL=agent-VUNM33WJ.js.map
+//# sourceMappingURL=agent-VUNM33WJ.js.map

package/dist/{agent-N6WJ54ML.js.map → agent-VUNM33WJ.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-N6WJ54ML.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-VUNM33WJ.js"}

package/dist/{chunk-OYD3U3LY.js → chunk-43H4EBS2.js}

@@ -1,7 +1,7 @@
 import { submit, emitRunEvent } from './chunk-K2VMFZQ5.js';
 import { enqueueSessionWrite, hydrateSession, persistTurnToTranscript, flushSessionWrites, appendSessionMessage, getSessionMessages, discardSession, clearSession } from './chunk-AWINL3ZC.js';
 import { IndexManager } from './chunk-7SZAV6QG.js';
-import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-AW6F6HZR.js';
+import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-AI4MXACC.js';
 import { extractCodePlugins } from './chunk-2SFBB54R.js';
 import { createOpenAiCompatibleRuntime } from './chunk-55GB6JYQ.js';
 import { persistActiveMemoryTranscript } from './chunk-OR6XIWLB.js';
@@ -24,8 +24,8 @@ import { expandTilde, defaultBaseDir } from './chunk-JOFVLOFY.js';
 import { withFileLock } from './chunk-TA3K7SBK.js';
 import { withCwdMutex } from './chunk-Q5EWJPRY.js';
 import { sweepStaleAtomicTemps, atomicWriteJson } from './chunk-3JHIFQ4I.js';
-import { loadSubagents, pluginBundleDirs } from './chunk-OQRGVTQF.js';
-import { reportUndeclaredSources, theokitConfigRoot, undefinedVariablesIn, getTheokitHome, adapterForConfigPath, projectConfigRoots, pluginBundleRoots } from './chunk-WMWEI3NS.js';
+import { loadSubagents, pluginBundleDirs } from './chunk-DLFWMJE3.js';
+import { reportUndeclaredSources, theokitConfigRoot, undefinedVariablesIn, getTheokitHome, adapterForConfigPath, projectConfigRoots, pluginBundleRoots } from './chunk-RP3VXJMA.js';
 import { readWorkspaceDir, parseSimpleYaml } from './chunk-JNAA4G4H.js';
 import { resolveEffectiveContextWindow, CONTEXT_WINDOW_FLOOR, CONTEXT_WINDOW_MARGIN } from './chunk-6M2OIS4Y.js';
 import { parseModelId } from './chunk-R7WIIPUR.js';
@@ -9116,7 +9116,7 @@ async function* localAgentStreamToCompletion(agent, message, options) {
 async function localAgentFork(parent, options) {
   const { forkAgentImpl } = await import('./fork-agent-S2EPIML7.js');
   const { getAgentFacade } = await import('./agent-factory-registry-ZVTABLEY.js');
-  const { withPersonalityContext } = await import('./context-Z3CFTT3H.js');
+  const { withPersonalityContext } = await import('./context-XNREEC7M.js');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -10889,7 +10889,7 @@ var Agent = class _Agent {
    */
   static async describe(agentId) {
     const agent = await getRegisteredAgentOrThrow(agentId);
-    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-DOBTTICM.js');
+    const { loadSubagents: loadSubagents2 } = await import('./subagents-loader-PAZVOZHI.js');
     const settingSources = agent.options.local?.settingSources;
     const subagents = await loadSubagents2(
       agent.cwd ?? process.cwd(),
@@ -10977,5 +10977,5 @@ async function openLocalStore(reg) {
 }
 
 export { Agent, AgentBuilder, DEFAULT_AGENTIC_MODEL_ID, MEMORY_EMBEDDING_ADAPTERS, Tool, ToolError, UsageAccumulator, computeCost, generateCronId, getPricingEntry, openRouterMemoryEmbeddingProviderAdapter, resolveSessionDir };
-//# sourceMappingURL=chunk-OYD3U3LY.js.map
-//# sourceMappingURL=chunk-OYD3U3LY.js.map
+//# sourceMappingURL=chunk-43H4EBS2.js.map
+//# sourceMappingURL=chunk-43H4EBS2.js.map