@theokit/sdk 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## 5.3.0
+
+### Minor Changes
+
+- [#607](https://github.com/usetheokit/theokit-sdk/pull/607) [`a7ed8e0`](https://github.com/usetheokit/theokit-sdk/commit/a7ed8e0c37105375e439ef567a51c7643ffc7754) Thanks [@usetheodev](https://github.com/usetheodev)! - `listSessions` — enumerate sessions, and say where each id came from ([#598](https://github.com/usetheokit/theokit-sdk/issues/598))
+  
+  Every transcript helper this package published mapped **forward** — `sessionUuidFor`,
+  `transcriptPath`, `legacyTranscriptPath`, `encodeProjectDir`, `transcriptRoot`. **None enumerated.**
+  So a consumer that needed the list rebuilt it, and two independent ones did, in opposite directions,
+  and both derived the session id from the **filename**:
+  
+  | consumer | direction | what broke |
+  |---|---|---|
+  | `@theokit/agents` | file → id | `sessionIdOf` returned the file stem |
+  | a downstream agent runtime | id → file | compared session ids against filenames |
+  
+  The second was measured against `5.0.1`: the protected set never matched, so **neither the registered
+  sessions nor the live one were protected and everything classified as an orphan** — a garbage
+  collector that would delete the session in use.
+  
+  ```ts
+  import { listSessions } from "@theokit/sdk/persistence";
+  
+  for (const s of await listSessions(process.cwd())) {
+    if (s.idSource === "unavailable") continue;   // do not guess, and do not delete
+    …
+  }
+  ```
+  
+  **Documentation was not the fix, and that is the argument for the primitive.** The rename was
+  documented thoroughly. One of those two consumers had *read* it and broke anyway; the other had not
+  and broke identically. Two samples, one informed and one not, the same defect — so the cause is the
+  shape of the surface rather than the reader. Nor can it be closed with an inverse: the filename is a
+  UUIDv8 over SHA-256, which has none.
+  
+  **Every entry carries `idSource`, and an unreadable id is `undefined` rather than guessed.** An
+  `id: string` that is sometimes read from the transcript and sometimes inferred is the same defect one
+  layer up — a value that reads as authoritative and occasionally is not, which is exactly what
+  produced the garbage-collector failure. A caller deciding what to *delete* needs to tell "not
+  registered" from "I could not read this file"; in a plain list those look identical and mean opposite
+  things.
+  
+  Reading is capped (64KB by default, `idScanBytes`) because the id lives in the first record and a
+  transcript grows without bound: bounded work with a declared outcome beats an unbounded read.
+  
+  Evidence gathered by the `theocode` session, which measured its own failure and obtained the
+  sibling's `file:line` rather than paraphrasing it.
+
+## 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

package/dist/index.cjs

@@ -919,8 +919,17 @@ var NoopMemoryProvider = class {
 var ALWAYS_REGISTERED = ["shell"];
 var MEMORY_BUILTINS = ["memory_search", "memory_get"];
 function effectiveToolNames(options) {
+  refuseCreatedTool(options);
   return { names: resolvableNames(options), unresolved: unresolvableSources(options) };
 }
+function refuseCreatedTool(options) {
+  const candidate = options;
+  if (candidate.handler === void 0 || candidate.inputSchema === void 0) return;
+  throw new chunkJ7J7J2GN_cjs.ConfigurationError(
+    `effectiveToolNames received a created tool${typeof candidate.name === "string" ? ` ("${candidate.name}")` : ""}, not AgentOptions. \`SubAgent.create()\` returns a CustomTool and closes its spec inside the handler, so the spec cannot be recovered from it. Pass the spec you built it from \u2014 keep it in a variable, or extract it into a function the test can call.`,
+    { code: "effective_tools_expected_options" }
+  );
+}
 function resolvableNames(options) {
   const withheld = new Set(options.withheldBuiltinTools ?? []);
   const builtins = [