@theokit/sdk 5.2.1 → 5.3.1

package/CHANGELOG.md

@@ -1,5 +1,126 @@
 # Changelog
 
+## 5.3.1
+
+### Patch Changes
+
+- [#614](https://github.com/usetheokit/theokit-sdk/pull/614) [`20794ef`](https://github.com/usetheokit/theokit-sdk/commit/20794efffa012edf200a3409abc53b988960e7af) Thanks [@usetheodev](https://github.com/usetheodev)! - `Agent.delete` removes the entry from the persisted registry ([#612](https://github.com/usetheokit/theokit-sdk/issues/612))
+  
+  It did not. The method was a no-op against `registry.json` whenever the agent was not already in the
+  calling process's memory — which is every agent in a freshly started process, so every CLI
+  invocation:
+  
+  ```ts
+  static async delete(agentId: string, _options: AgentOperationOptions = {}): Promise<void> {
+    removeRegisteredAgent(agentId);   // Map is empty → returns false → no save scheduled
+    await flushRegistrySaves();       // flushes an empty queue
+  }
+  ```
+  
+  `Agent.delete` returns `Promise<void>` and throws nothing when it removed nothing, so a caller had no
+  way to notice. Measured downstream as a `sessions delete` that reported success and exited 0 while
+  the session stayed in the listing — the transcript really was removed, leaving a registry entry
+  pointing at a file that no longer existed.
+  
+  **What makes this an omission rather than a design:** every neighbouring mutator already hydrates.
+  `Agent.rename` and `Agent.archive` reach `getRegisteredAgentOrThrow`, which loads from disk on a
+  miss; `delete` was the only one that never did.
+  
+  `options.cwd` is now read instead of being defaulted away — it is declared on
+  `AgentOperationOptions` and the parameter was `_options`. Hydrating `process.cwd()` unconditionally
+  would repeat B-115 (a documented option that compiles and does nothing) on the one path whose job is
+  to remove data.
+  
+  **Deliberately unchanged:** deleting an unknown id still resolves rather than throwing. Matching
+  `rename`'s `UnknownAgentError` is defensible, but it is a breaking change for callers that delete
+  idempotently, and an entry and its transcript can legitimately outlive one another in both
+  directions. A persistence fix should not smuggle in an API break.
+  
+  Consumers that already called `Agent.delete` and observed the entry surviving will now see it
+  removed. Nothing that behaved correctly before changes.
+
+- [#614](https://github.com/usetheokit/theokit-sdk/pull/614) [`52d31d9`](https://github.com/usetheokit/theokit-sdk/commit/52d31d903fa5ddd3236db7f628f943e7e8ceae58) Thanks [@usetheodev](https://github.com/usetheodev)! - A local agent's public `summary` is a runtime label, not a fixture name ([#611](https://github.com/usetheokit/theokit-sdk/issues/611))
+  
+  `SDKAgentInfo.summary` is `@public` and required, returned by `Agent.list()` and `Agent.get()`.
+  `registerLocalAgent` assigned it unconditionally:
+  
+  ```ts
+  summary: "Local contract fixture",
+  ```
+  
+  So that string was the **only** value the field could hold for a local agent, and `AgentOptions`
+  exposes no `summary` for a consumer to override it. It was found on a real user's session record on
+  disk, written through a consumer by a real turn — nothing about the run was a fixture.
+  
+  The cloud sibling faces the same requirement and guards it, which is what makes this an omission
+  rather than a decision:
+  
+  ```ts
+  summary: this.isFixtureMode() ? "Cloud contract fixture" : "Cloud agent",
+  ```
+  
+  `isFixtureMode()` keys off a `theo_test_*` key with no configured base URL — it describes whether
+  the *remote* is stubbed, so there is no local equivalent to port. The local branch therefore takes
+  the cloud branch's non-fixture value: **`"Local agent"`**.
+  
+  The `toLocalAgentInfo` / `toCloudAgentInfo` **fallbacks** carried the same two literals and move
+  with it. That pair is the reason this was worth fixing carefully rather than quickly: while the
+  registration wrote a fixture name unconditionally, the fallback could never be observed, so fixing
+  only the reachable site would have left the string ready to reappear for any record that arrives
+  without a summary.
+  
+  Consumers rendering `summary` will see `Local agent` where they previously saw
+  `Local contract fixture`. Nothing reads the value programmatically in this package; a consumer that
+  matched on the old string was matching on a placeholder.
+
+## 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

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

@@ -1,4 +1,4 @@
-export { Agent } from './chunk-43H4EBS2.js';
+export { Agent } from './chunk-ZFEOAC52.js';
 import './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
@@ -54,5 +54,5 @@ import './chunk-V22DZIXO.js';
 import './chunk-NJWYQWDL.js';
 import './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';
-//# sourceMappingURL=agent-VUNM33WJ.js.map
-//# sourceMappingURL=agent-VUNM33WJ.js.map
+//# sourceMappingURL=agent-G4OFQYLE.js.map
+//# sourceMappingURL=agent-G4OFQYLE.js.map

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

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

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

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkDEJCKB65_cjs = require('./chunk-DEJCKB65.cjs');
+var chunk5XNRWMMD_cjs = require('./chunk-5XNRWMMD.cjs');
 require('./chunk-KVSAY6NZ.cjs');
 require('./chunk-Y2KYR2ED.cjs');
 require('./chunk-BUUUWQMB.cjs');
@@ -61,7 +61,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkDEJCKB65_cjs.Agent; }
+  get: function () { return chunk5XNRWMMD_cjs.Agent; }
 });
-//# sourceMappingURL=agent-GACKKINM.cjs.map
-//# sourceMappingURL=agent-GACKKINM.cjs.map
+//# sourceMappingURL=agent-UXU5AIOJ.cjs.map
+//# sourceMappingURL=agent-UXU5AIOJ.cjs.map

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

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

package/dist/agent.d.ts

@@ -268,9 +268,27 @@ export declare class Agent {
      */
     static describe(agentId: string): Promise<AgentDescription>;
     /**
-     * Permanently delete a cloud agent.
+     * Permanently delete a registered agent — local or cloud.
+     *
+     * #612 — this HYDRATES before removing, and until it did the method was a no-op against the
+     * persisted registry whenever the agent was not already in this process's memory. Which is every
+     * agent in a freshly started process: `removeRegisteredAgent` only schedules a save when the entry
+     * was in the Map, so `agents.delete()` returned `false`, nothing was scheduled, and
+     * `flushRegistrySaves()` flushed an empty queue. The entry survived and this returned normally.
+     *
+     * Every neighbouring mutator already did this — `rename` and `archive` reach
+     * `getRegisteredAgentOrThrow`, which hydrates on a miss. `delete` was the only one that did not.
+     *
+     * `options.cwd` is read rather than defaulted away: it is declared on `AgentOperationOptions`, and
+     * hydrating `process.cwd()` unconditionally is the B-115 defect — an option that compiles and does
+     * nothing — on the one path that is supposed to remove data.
+     *
+     * Deleting an unknown id still resolves rather than throwing, deliberately. `rename` throws
+     * `UnknownAgentError` and matching it here is defensible, but it is a breaking change for callers
+     * that delete idempotently, and an entry and its transcript can legitimately outlive one another
+     * in both directions. That decision belongs to its own change, not to a persistence fix.
      *
      * @public
      */
-    static delete(agentId: string, _options?: AgentOperationOptions): Promise<void>;
+    static delete(agentId: string, options?: AgentOperationOptions): Promise<void>;
 }

package/dist/{chunk-DEJCKB65.cjs → chunk-5XNRWMMD.cjs}

@@ -3440,7 +3440,7 @@ var HISTOGRAM_NAMES = {
 };
 function safeRequire(moduleName) {
   try {
-    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-DEJCKB65.cjs', document.baseURI).href)));
+    const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-5XNRWMMD.cjs', document.baseURI).href)));
     return r(moduleName);
   } catch {
     return void 0;
@@ -3683,7 +3683,7 @@ var cachedOtel;
 function loadOtel() {
   if (cachedOtel === void 0) {
     try {
-      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-DEJCKB65.cjs', document.baseURI).href)));
+      const r = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('chunk-5XNRWMMD.cjs', document.baseURI).href)));
       const mod = r("@opentelemetry/api");
       cachedOtel = mod;
     } catch {
@@ -4456,7 +4456,13 @@ function registerLocalAgent(args) {
     agentId: args.agentId,
     runtime: "local",
     name: args.options.name,
-    summary: "Local contract fixture",
+    // #611 — a runtime label, not a fixture name. `SDKAgentInfo.summary` is `@public` and required,
+    // `AgentOptions` has no `summary` for a consumer to override, and this line was unconditional —
+    // so "Local contract fixture" was the only value the field could hold for a local agent, and it
+    // was measured reaching a user's session record on disk. The cloud sibling already guards its
+    // own fixture string behind `isFixtureMode()`; there is no local equivalent to port, so the
+    // local branch simply takes the non-fixture value.
+    summary: "Local agent",
     model: args.model,
     createdAt: Date.now(),
     lastModified: Date.now(),
@@ -10424,14 +10430,17 @@ function commonAgentInfo(agent, fallbackSummary) {
 }
 function toLocalAgentInfo(agent) {
   return {
-    ...commonAgentInfo(agent, "Local contract fixture"),
+    ...commonAgentInfo(agent, "Local agent"),
     runtime: "local",
     ...agent.cwd !== void 0 ? { cwd: agent.cwd } : {}
   };
 }
 function toCloudAgentInfo(agent) {
   return {
-    ...commonAgentInfo(agent, "Cloud contract fixture"),
+    // Same fallback, same reason (#611). The cloud REGISTRATION already guards its fixture string
+    // behind `isFixtureMode()`, so this line only answers for a record that carries no summary —
+    // and a fixture name is the wrong answer for that record whichever runtime it came from.
+    ...commonAgentInfo(agent, "Cloud agent"),
     archived: agent.archived,
     runtime: "cloud",
     env: { type: "cloud" },
@@ -10923,11 +10932,30 @@ var Agent = class _Agent {
     };
   }
   /**
-   * Permanently delete a cloud agent.
+   * Permanently delete a registered agent — local or cloud.
+   *
+   * #612 — this HYDRATES before removing, and until it did the method was a no-op against the
+   * persisted registry whenever the agent was not already in this process's memory. Which is every
+   * agent in a freshly started process: `removeRegisteredAgent` only schedules a save when the entry
+   * was in the Map, so `agents.delete()` returned `false`, nothing was scheduled, and
+   * `flushRegistrySaves()` flushed an empty queue. The entry survived and this returned normally.
+   *
+   * Every neighbouring mutator already did this — `rename` and `archive` reach
+   * `getRegisteredAgentOrThrow`, which hydrates on a miss. `delete` was the only one that did not.
+   *
+   * `options.cwd` is read rather than defaulted away: it is declared on `AgentOperationOptions`, and
+   * hydrating `process.cwd()` unconditionally is the B-115 defect — an option that compiles and does
+   * nothing — on the one path that is supposed to remove data.
+   *
+   * Deleting an unknown id still resolves rather than throwing, deliberately. `rename` throws
+   * `UnknownAgentError` and matching it here is defensible, but it is a breaking change for callers
+   * that delete idempotently, and an entry and its transcript can legitimately outlive one another
+   * in both directions. That decision belongs to its own change, not to a persistence fix.
    *
    * @public
    */
-  static async delete(agentId, _options = {}) {
+  static async delete(agentId, options = {}) {
+    await hydrateRegistryFromDisk(options.cwd ?? process.cwd());
     removeRegisteredAgent(agentId);
     await flushRegistrySaves();
   }
@@ -10991,5 +11019,5 @@ exports.generateCronId = generateCronId;
 exports.getPricingEntry = getPricingEntry;
 exports.openRouterMemoryEmbeddingProviderAdapter = openRouterMemoryEmbeddingProviderAdapter;
 exports.resolveSessionDir = resolveSessionDir;
-//# sourceMappingURL=chunk-DEJCKB65.cjs.map
-//# sourceMappingURL=chunk-DEJCKB65.cjs.map
+//# sourceMappingURL=chunk-5XNRWMMD.cjs.map
+//# sourceMappingURL=chunk-5XNRWMMD.cjs.map