@theokit/sdk 5.3.0 → 5.3.2

package/dist/index.d.ts

@@ -2,15 +2,15 @@ import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01n
 export { a as ErrorCode } from './errors-base-B5g01neU.js';
 import { F as RunEvent, j as CostBreakdown, at as TokenUsage, R as RunResult, M as ModelSelection, C as CustomTool, a as McpServerConfig, T as ToolResultContentBlock, b as Run, P as Processor, c as PermissionMode, d as RunEventSink$1, S as SDKMessage } from './run-CTAdRU3U.js';
 export { A as AgentConversationTurn, e as AssistantMessage, f as CompletionCheck, g as CompletionCheckResult, h as ConversationStep, i as ConversationTurn, j as CostBreakdown, k as CostSource, l as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, m as GenerateRunResult, I as ImageBlock, n as InputProcessorContext, o as InteractionUpdate, p as McpAuthConfig, q as McpHttpServerConfig, r as McpOAuthConfig, s as McpStdioServerConfig, t as MessageOrigin, u as ModelParameterValue, O as OutputProcessorContext, v as PartialToolCallUpdate, w as ProcessorControls, x as ProcessorTripwire, y as ProcessorViolation, z as RunCompactBoundaryEvent, B as RunCompletionCheckEvent, E as RunErrorDetail, F as RunEvent, H as RunGitInfo, J as RunMemoryDegradedEvent, K as RunOperation, L as RunPermissionDeniedEvent, N as RunRateLimitEvent, Q as RunStatus, U as RunTaskCompletedEvent, V as RunTaskStartedEvent, W as RunTaskUpdatedEvent, X as RunTimelineEvent, Y as RunToCompletionOptions, Z as RunToCompletionResult, _ as RunToolProgressEvent, $ as RunTripwireEvent, a0 as SDKAssistantMessage, a1 as SDKImage, a2 as SDKImageDimension, a3 as SDKObjectDelta, a4 as SDKRequestMessage, a5 as SDKStatusMessage, a6 as SDKSystemMessage, a7 as SDKTaskMessage, a8 as SDKThinkingMessage, a9 as SDKToolUseMessage, aa as SDKUserMessage, ab as SDKUserMessageEvent, ac as SendOptions, ad as ShellCommand, ae as ShellConversationTurn, af as ShellOutput, ag as ShellOutputDeltaUpdate, ah as StepCompletedUpdate, ai as StepStartedUpdate, aj as StreamToCompletionResult, ak as SummaryCompletedUpdate, al as SummaryStartedUpdate, am as SummaryUpdate, an as TextBlock, ao as TextDeltaUpdate, ap as ThinkingCompletedUpdate, aq as ThinkingDeltaUpdate, ar as ThinkingMessage, as as TokenDeltaUpdate, at as TokenUsage, au as ToolCall, av as ToolCallCompletedUpdate, aw as ToolCallStartedUpdate, ax as ToolContextMessage, ay as ToolResult, az as ToolResultGuardOptions, aA as ToolUseBlock, aB as TurnEndedUpdate, aC as UserMessage, aD as UserMessageAppendedUpdate } from './run-CTAdRU3U.js';
-import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-CvmTR9uf.js';
-export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-CvmTR9uf.js';
+import { A as AgentOptions, L as LocalOptions, S as SystemPromptResolver, C as CloudOptions, M as MemorySettings, a as AgentDefinition, b as SkillsSettings, c as ListAgentsOptions, d as ListResult, e as SDKAgentInfo, G as GetAgentOptions, f as ListRunsOptions, g as GetRunOptions, h as AgentOperationOptions, i as AgentDescription, P as Plugin$1, j as ProviderProfile, I as InlineSkill, B as BudgetTracker, k as MemoryProvider, l as PreToolCallDecision } from './agent-CTbU0O1R.js';
+export { m as ActiveMemoryPassArgs, n as ActiveMemoryPassResult, o as AgentSubagentDescription, p as AgentToolDescription, q as BudgetCheck, r as BudgetTotal, s as BudgetUsageEvent, t as BuiltinToolName, u as CloudEnv, v as CloudRepo, w as CompatSource, x as CompatSourceAdapter, y as CompatSurface, z as CreateSkillSpec, H as HookName, D as MemoryProviderAgentRef, E as MemoryProviderFactory, F as MemoryProviderHandle, J as MemoryProviderInitOptions, K as PluginContext, N as PluginHookDisposer, O as PostAssistantReplyContext, Q as PostToolCallContext, R as PreToolCallContext, T as PreUserSendContext, U as PreUserSendResult, V as ProviderTransform, W as ProviderTransformContext, X as RecordSessionSummaryArgs, Y as SessionLifecycleContext, Z as SessionRecord, _ as SessionStore, $ as SettingSource, a0 as Skill, a1 as SkillsResolver, a2 as SkillsResolverContext, a3 as SystemPromptContext, a4 as SystemPromptMemoryFact, a5 as TelemetrySettings, a6 as ToolCallSummary, a7 as ToolResultTransformContext, a8 as TransformContext } from './agent-CTbU0O1R.js';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
 import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-CLOAyuiv.js';
 export { A as AgentDisposedError, c as AgentRunError, d as AgentRunErrorCode, e as AuthenticationError, f as BudgetExceedEvent, g as BudgetExceededError, h as BudgetLimit, i as BudgetMode, j as BudgetScope, k as BudgetThresholdEvent, l as BudgetWindow, C as ConfigurationError, I as IntegrationNotConnectedError, m as InvalidTaskIdError, M as MemoryAdapterError, n as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, T as TaskNotFoundError, U as UnknownAgentError, o as UnsupportedBudgetOperationError, p as UnsupportedRunOperationError, q as UnsupportedTaskOperationError, r as isTransientError } from './errors-CLOAyuiv.js';
 import { P as ProviderRoutingSettings, S as SDKAgent, C as ContextSettings, a as PluginsSettings, J as JudgeResult, G as GoalOptions, b as GoalEvent, c as GoalResult, M as MemoryId, d as SDKProvider } from './sdk-agent-D4a_BR_6.js';
 export { A as AgentMemory, e as AgentOperation, f as ContextBudget, g as ContextManagerKind, h as ContextSnapshot, i as ContextSource, j as ContextSourceStatus, I as InvalidateCacheOptions, k as MemoryAdapter, l as MemoryAdapterCapabilities, m as MemoryContext, n as MemoryFact, o as MemoryRevision, p as MemoryToolSchema, q as MemoryTurnMessage, r as PersonalityPreset, s as ProviderCapability, t as ProviderRoute, R as ResolvedProviderRoute, u as RunUntilIterator, v as SDKAgentPlugins, w as SDKAgentSkillDetail, x as SDKAgentSkills, y as SDKArtifact, z as SDKContextManager, B as SDKPluginMetadata, D as SDKProvidersManager, E as SystemPromptSkillRef, V as Verdict } from './sdk-agent-D4a_BR_6.js';
-export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-crfMMdAw.js';
+export { C as Cron, a as CronCreateOptions, b as CronGetOptions, c as CronJob, d as CronJobStatus, e as CronListOptions, f as CronOperationOptions, g as CronRunOptions, h as CronRuntime, i as CronSchedulerStatus, j as CronStartOptions } from './cron-Cl8FrK3D.js';
 import { StepResult } from './workflow.js';
 export { Workflow, agentStep, fn } from './workflow.js';
 
@@ -871,11 +871,29 @@ 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/index.js

@@ -8,15 +8,15 @@ import { Workflow, agentStep } from './chunk-HFEJE7AC.js';
 export { Workflow, agentStep, fn } from './chunk-HFEJE7AC.js';
 import './chunk-GBCVPKHE.js';
 import './chunk-HY66GLM6.js';
-export { Cron } from './chunk-WHTMFN4Q.js';
-import { MEMORY_EMBEDDING_ADAPTERS, resolveSessionDir, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-43H4EBS2.js';
-export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-43H4EBS2.js';
+export { Cron } from './chunk-ZITYGJOD.js';
+import { MEMORY_EMBEDDING_ADAPTERS, resolveSessionDir, DEFAULT_AGENTIC_MODEL_ID, Agent } from './chunk-363RBGIR.js';
+export { Agent, AgentBuilder, Tool, ToolError, UsageAccumulator, computeCost, getPricingEntry } from './chunk-363RBGIR.js';
 import { configure, submit, list, get, cancel, subscribe } from './chunk-K2VMFZQ5.js';
 export { emitRunEvent } from './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';
@@ -1792,7 +1792,7 @@ function isBuiltAgent(m) {
   return typeof m.send === "function";
 }
 async function materialize(def, index) {
-  const { Agent: Agent2 } = await import('./agent-VUNM33WJ.js');
+  const { Agent: Agent2 } = await import('./agent-PNYJ5S2Y.js');
   return Agent2.create({
     // `AgentDefinition.model` admits the sentinel `'inherit'`, which is not a model id. Inheriting
     // here means "declare nothing and let the default apply" — forwarding the literal would create

package/dist/subagents-loader.d.cts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-C3KO5LKm.cjs';
+import { a as AgentDefinition } from './agent-QLwxhXY3.cjs';
 import './sdk-agent-BOiKqOgL.cjs';
 import './run-CTAdRU3U.cjs';
 import 'zod';

package/dist/subagents-loader.d.ts

@@ -1,4 +1,4 @@
-import { a as AgentDefinition } from './agent-CvmTR9uf.js';
+import { a as AgentDefinition } from './agent-CTbU0O1R.js';
 import './sdk-agent-D4a_BR_6.js';
 import './run-CTAdRU3U.js';
 import 'zod';

package/dist/types/plugin.d.ts

@@ -41,6 +41,8 @@ import type { ProviderProfile } from "./provider-profile.js";
  *   `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
@@ -120,7 +122,24 @@ export interface LlmCallContext {
     /** Iteration index (0-based) of the current turn, when available. */
     iteration?: number;
 }
-/** #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
+ */
 export interface SessionLifecycleContext {
     agentId: string;
     runId: string;

package/docs/error-codes.md

@@ -79,10 +79,10 @@ Branch on `code`, never on the message: messages carry context (an id, a path, a
 | `handoff_target_required` | domain | ConfigurationError | `packages/sdk-handoff/src/handoff.ts:111` |
 | `hitl_timeout` | domain | HitlTimeoutError | `packages/sdk/src/internal/runtime/tools/hitl-middleware.ts:42` +1 |
 | `hook_denied` | domain | ConfigurationError | `packages/sdk/src/internal/local-agent/local-agent.ts:454` |
-| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:272` |
+| `hooks_invalid_command` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:295` |
 | `hooks_json_invalid` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:190` +2 |
 | `hooks_read_error` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:181` |
-| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:266` |
+| `hooks_unsupported_type` | domain | ConfigurationError | `packages/sdk/src/internal/runtime/hooks/hooks-source.ts:289` |
 | `interactive_unavailable` | domain | InteractiveUnavailableError | `packages/sdk/src/interactive/types.ts:28` +1 |
 | `INTERNAL_SERVER_ERROR` | domain | — | `packages/sdk/src/server/errors-envelope.ts:100` |
 | `invalid_argument` | domain | TheokitAgentError | `packages/sdk/src/compaction.ts:79` |

package/docs/harness-capability-map.md

@@ -357,7 +357,7 @@ A symbol listed under two specifiers is reachable from both, but that does NOT m
 | `Security` | class | Public security namespace (T2.1, ADR D68).  |
 | `SecurityFloorInput` | interface | The vocabulary, the layer names, and the values to resolve.  |
 | `SendOptions` | interface | Per-send overrides and callbacks.  |
-| `SessionLifecycleContext` | interface | #65 — context for the `on_session_start` / `on_session_end` hooks. |
+| `SessionLifecycleContext` | interface | #65 — context for the `on_session_start` / `on_session_end` hooks.  |
 | `SessionMessage` | interface | One turn of a session.  |
 | `SessionMessagePart` | type | One structured element of a {@link SessionMessage } .  |
 | `SessionRecord` | interface | One transcript record — a single line of the session JSONL file, and the unit the pluggable `SessionStore` seam reads and writes.  |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theokit/sdk",
-  "version": "5.3.0",
+  "version": "5.3.2",
   "description": "TypeScript SDK for the Theo agent harness — same surface, local or cloud.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/usetheokit/theokit-sdk#readme",