@theokit/sdk 5.3.0 → 5.3.2

package/CHANGELOG.md

@@ -1,5 +1,108 @@
 # Changelog
 
+## 5.3.2
+
+### Patch Changes
+
+- [#619](https://github.com/usetheokit/theokit-sdk/pull/619) [`3f80bba`](https://github.com/usetheokit/theokit-sdk/commit/3f80bbaf0e7b1a6e7cd81a08f63aba243e1a0f18) Thanks [@usetheodev](https://github.com/usetheodev)! - A wrongly-shaped `hooks` block is refused with the shape that would work
+  
+  `hooks: expected an object at "hooks" in <path>` named the validator's expectation and nothing an operator could act on. It now carries the accepted shape:
+  
+  ```
+  hooks: expected an object at "hooks" in <path> — hooks are keyed by event,
+  e.g. { "hooks": { "PreToolUse": [ { "hooks": [ { "type": "command", "command": "…" } ] } ] } }
+  ```
+  
+  Measured on a consumer in 2026-09. A flat `hooks` array in a `.theokit/settings.json` made this loader throw on **every turn** — and the file parsed perfectly for the product that had written it. `.theokit/` is this package's filebase, so what failed was an independent read of a path another product had started using, and the collision was one of **shape**, not of location. With only the diagnosis to go on, the operator looked in the wrong file.
+  
+  Two tests ship with it: the refusal names the shape, and a control proves the shape it names is accepted. Without the control, "the error mentions `keyed by event`" would say nothing about whether that advice is correct.
+
+- [#619](https://github.com/usetheokit/theokit-sdk/pull/619) [`a75059c`](https://github.com/usetheokit/theokit-sdk/commit/a75059cb496e4655e571a703c937e4e71ff670d8) Thanks [@usetheodev](https://github.com/usetheodev)! - Document that `on_session_start` / `on_session_end` fire once per **run** ([#613](https://github.com/usetheokit/theokit-sdk/issues/613) follow-up)
+  
+  Docs and a test only; no behaviour change.
+  
+  `SessionLifecycleContext` is named for a session and carries a `runId` that changes on every firing. The hooks fire once per pass through the agent loop — which is per-message for any application that builds its agent per turn. Nothing a consumer could read said so: the only accurate sentence was an internal comment at the firing site (`loop.ts`, *"fires once per run"*).
+  
+  That gap was measured. In 2026-09 it cost two sessions several hours and produced a defect filed against this package for behaviour that is correct; the real answer turned out to be an architectural mismatch in a consumer that constructs an agent per turn, where "once per run" is not what a `SessionStart` handler assumes.
+  
+  Two changes:
+  
+  - The cadence is now stated on `SessionLifecycleContext` and in the `HookName` docblock, where a consumer meets the hook.
+  - `test_on_session_start_fires_once_per_run_and_again_on_the_next_run` pins it across two runs. The existing integration case could not: it collects into a `Set`, so a hook firing twice and a hook firing once are indistinguishable there by construction.
+
+## 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

package/dist/{agent-CvmTR9uf.d.ts → agent-CTbU0O1R.d.ts}

@@ -689,6 +689,8 @@ interface ProviderProfile {
  *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
  *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
  *   `post_tool_call` and it quietly degrades to observation.
+ * - `on_session_start` / `on_session_end` fire once per **run**, not once per agent lifetime — see
+ *   {@link SessionLifecycleContext}. Build an agent per turn and they fire on every message.
  *
  * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
  * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
@@ -750,7 +752,24 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
-/** #65 — context for the `on_session_start` / `on_session_end` hooks. @public */
+/**
+ * #65 — context for the `on_session_start` / `on_session_end` hooks.
+ *
+ * **These fire once per RUN, not once per agent lifetime**, and the `runId` on this very context is
+ * the tell: it changes every time they fire. "Session" here means one pass through the agent loop.
+ *
+ * The distinction is invisible to an application that creates an agent once and sends many messages
+ * — there, per-run and per-session coincide. It is decisive for one that builds an agent **per
+ * turn**: `on_session_start` then fires on every message, which is the opposite of what a handler
+ * named for a session start usually assumes.
+ *
+ * Stated here because it was not stated anywhere a consumer could read it. The only accurate
+ * sentence lived in an internal comment at the firing site, and in 2026-09 that cost two people
+ * hours and produced a defect report filed against this package for behaviour that is correct.
+ * `test_on_session_start_fires_once_per_run_and_again_on_the_next_run` now pins it.
+ *
+ * @public
+ */
 interface SessionLifecycleContext {
     agentId: string;
     runId: string;

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

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkDEJCKB65_cjs = require('./chunk-DEJCKB65.cjs');
+var chunkY46VI73J_cjs = require('./chunk-Y46VI73J.cjs');
 require('./chunk-KVSAY6NZ.cjs');
 require('./chunk-Y2KYR2ED.cjs');
 require('./chunk-BUUUWQMB.cjs');
 require('./chunk-Z2JFX372.cjs');
-require('./chunk-SSIRPWWD.cjs');
+require('./chunk-65UMH5V3.cjs');
 require('./chunk-BV2MWEMV.cjs');
 require('./chunk-D6POWE7E.cjs');
 require('./chunk-GHX4P3V2.cjs');
@@ -61,7 +61,7 @@ require('./chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "Agent", {
   enumerable: true,
-  get: function () { return chunkDEJCKB65_cjs.Agent; }
+  get: function () { return chunkY46VI73J_cjs.Agent; }
 });
-//# sourceMappingURL=agent-GACKKINM.cjs.map
-//# sourceMappingURL=agent-GACKKINM.cjs.map
+//# sourceMappingURL=agent-KJLAWKZB.cjs.map
+//# sourceMappingURL=agent-KJLAWKZB.cjs.map

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

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

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

@@ -1,9 +1,9 @@
-export { Agent } from './chunk-43H4EBS2.js';
+export { Agent } from './chunk-363RBGIR.js';
 import './chunk-K2VMFZQ5.js';
 import './chunk-AWINL3ZC.js';
 import './chunk-K2BQQ445.js';
 import './chunk-7SZAV6QG.js';
-import './chunk-AI4MXACC.js';
+import './chunk-7L3MIW2F.js';
 import './chunk-2SFBB54R.js';
 import './chunk-55GB6JYQ.js';
 import './chunk-H73MEMQB.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-PNYJ5S2Y.js.map
+//# sourceMappingURL=agent-PNYJ5S2Y.js.map

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

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

package/dist/{agent-C3KO5LKm.d.cts → agent-QLwxhXY3.d.cts}

@@ -689,6 +689,8 @@ interface ProviderProfile {
  *   `on_session_end`, `post_assistant_reply`) is fire-and-forget: the return value is DISCARDED. A
  *   policy that needs to change a tool result belongs on `transform_tool_result` — put it on
  *   `post_tool_call` and it quietly degrades to observation.
+ * - `on_session_start` / `on_session_end` fire once per **run**, not once per agent lifetime — see
+ *   {@link SessionLifecycleContext}. Build an agent per turn and they fire on every message.
  *
  * Failure is asymmetric too. A fire-and-forget or transform handler that throws is caught, logged to
  * stderr, and the run continues. A `pre_tool_call` handler that throws is NOT caught by the hook
@@ -750,7 +752,24 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
-/** #65 — context for the `on_session_start` / `on_session_end` hooks. @public */
+/**
+ * #65 — context for the `on_session_start` / `on_session_end` hooks.
+ *
+ * **These fire once per RUN, not once per agent lifetime**, and the `runId` on this very context is
+ * the tell: it changes every time they fire. "Session" here means one pass through the agent loop.
+ *
+ * The distinction is invisible to an application that creates an agent once and sends many messages
+ * — there, per-run and per-session coincide. It is decisive for one that builds an agent **per
+ * turn**: `on_session_start` then fires on every message, which is the opposite of what a handler
+ * named for a session start usually assumes.
+ *
+ * Stated here because it was not stated anywhere a consumer could read it. The only accurate
+ * sentence lived in an internal comment at the firing site, and in 2026-09 that cost two people
+ * hours and produced a defect report filed against this package for behaviour that is correct.
+ * `test_on_session_start_fires_once_per_run_and_again_on_the_next_run` now pins it.
+ *
+ * @public
+ */
 interface SessionLifecycleContext {
     agentId: string;
     runId: string;

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-43H4EBS2.js → chunk-363RBGIR.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-AI4MXACC.js';
+import { loadHookConfig, warnOnce, currentPersonalityContext, warnPersonalitySwitchInsideFork } from './chunk-7L3MIW2F.js';
 import { extractCodePlugins } from './chunk-2SFBB54R.js';
 import { createOpenAiCompatibleRuntime } from './chunk-55GB6JYQ.js';
 import { persistActiveMemoryTranscript } from './chunk-OR6XIWLB.js';
@@ -4453,7 +4453,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(),
@@ -9116,7 +9122,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-XNREEC7M.js');
+  const { withPersonalityContext } = await import('./context-BUIE52VH.js');
   const create = getAgentFacade().create;
   return withPersonalityContext(
     { slug: parent.personalitySlugSnapshot, isFork: true },
@@ -10421,14 +10427,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" },
@@ -10920,11 +10929,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();
   }
@@ -10977,5 +11005,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-43H4EBS2.js.map
-//# sourceMappingURL=chunk-43H4EBS2.js.map
+//# sourceMappingURL=chunk-363RBGIR.js.map
+//# sourceMappingURL=chunk-363RBGIR.js.map