@theokit/sdk 5.6.0 → 5.8.0

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # Changelog
 
+## 5.8.0
+
+### Minor Changes
+
+- [#683](https://github.com/usetheokit/theokit-sdk/pull/683) [`ccb7ede`](https://github.com/usetheokit/theokit-sdk/commit/ccb7edea41b63da1519971af95256bc828c88e10) Thanks [@usetheodev](https://github.com/usetheodev)! - Seventeen symbols marked `@public` were reachable from no entry in the export map. They are now.
+  
+  `@public` in a docblock is a promise that somebody outside the package is meant to name the symbol.
+  Nothing verified the promise, and the export map is exactly where it breaks quietly: a symbol can be
+  declared, documented, and compiled into a chunk while being importable from nowhere. A consumer
+  following the documentation got `has no exported member`.
+  
+  Three of the seventeen are worth naming, because their kind made the gap expensive:
+  
+  - **`CompressionFailedError`, `CompressionModelUnresolvedError`** — typed errors. `catch (e) { if (e
+    instanceof CompressionFailedError) }` did not compile for any consumer, which is the entire reason
+    a typed error exists rather than a message string.
+  - **`defineSubscription`** — a `define*` extension point, so the extension could not be written.
+  - **`withheldSpecs`** — names which instruction files a repository lost and which grant restores each
+    one. It shipped unreachable in 5.7.0: the capability worked and the accessor did not.
+  
+  Now importable: `AgentBuilderDeps`, `EnvPolicy`, `ForkOptions`, `ForkResult`, `HookApprovalGate`,
+  `HookApprovalRequest`, `LlmCallContext`, `ToolContext`, `createTokenLimiter`,
+  `createUnicodeNormalizer` (root); `admittedSpecs`, `withheldSpecs` (`/context`);
+  `CompressionFailedError`, `CompressionModelUnresolvedError`, `CompressionConfig` (`/compaction`);
+  `defineSubscription` (`/subscription`).
+  
+  **One went the other way.** `truncateWithMarker` lost its marker rather than gaining an export: it is
+  a pure truncation helper whose docblock describes implementation edge cases, not a contract, and an
+  export is a semver commitment somebody then has to keep.
+  
+  `withheldSpecs` also gained a named return type, `WithheldSpec`, and that is not style. The DTS
+  rollup only pulls a symbol into a chunk when a public type references it — with an anonymous return
+  type nothing referenced the function, the re-export dangled, and the build failed with TS2305 in
+  whichever file carried it. Naming the return value is what makes the function packable, and it gives
+  a consumer something to write in their own signature.
+  
+  **A gate now holds the promise.** `quality:public-surface` generates one probe per export-map entry
+  and lets `tsc` answer which names it cannot resolve.
+
+## 5.7.0
+
+### Minor Changes
+
+- [#675](https://github.com/usetheokit/theokit-sdk/pull/675) [`cbbed19`](https://github.com/usetheokit/theokit-sdk/commit/cbbed19abff45b58c10de1bf694524fbd246d6c2) Thanks [@usetheodev](https://github.com/usetheodev)! - A repo-root instruction file now requires a grant a consumer can write.
+  
+  `DEFAULT_DISCOVERY_SPECS` carries four repo-root instruction files whose bodies enter the system
+  prompt as if we had written them — `AGENTS.md`, `GEMINI.md`, `CLAUDE.md` and `.cursor/rules/*.mdc`.
+  Until now exactly ONE spec in that file carried a gate, and it was `.claude/rules/*.md`. A cloned
+  repository's `.claude/rules/*.md` needed a declaration; the `CLAUDE.md` one directory up did not,
+  while both carried the same risk.
+  
+  **The vocabulary landed before the gate, and the order is the whole point.** `CompatSource` went
+  from two literals to five:
+  
+  ```ts
+  compatSources: ["agents"]   // AGENTS.md is admitted; GEMINI.md is not
+  ```
+  
+  Gating the four against the OLD union would have gated three formats on a grant nobody could write
+  and made them permanently unreachable — worse than the gap. A test asserts the invariant in both
+  directions and fails the moment a spec is gated on a token the union does not carry.
+  
+  **Separate literals, not one `foreign` token**, so a consumer who wants `AGENTS.md` is not forced to
+  also admit `.cursor/rules/*.mdc`.
+  
+  **BREAKING for a consumer who declares nothing**: they went from four repo-root files in the prompt
+  to none. That is the intended behaviour and it is LOUD — `withheldSpecs` reports every withheld file
+  by path with the grant that restores it, and the runner warns once naming each one. A count would be
+  a diagnosis with no remedy: you cannot decide whether to grant a dialect without knowing which file
+  it brings.
+  
+  `undefined` and `[]` stay distinct: no gate configured admits everything, an empty declaration
+  withholds every gated spec. Collapsing them would restore the defect the first gate closed.
+
+- [#675](https://github.com/usetheokit/theokit-sdk/pull/675) [`de40d9f`](https://github.com/usetheokit/theokit-sdk/commit/de40d9f3d398f84d5b145cec8bc56a4c6ec85a25) Thanks [@usetheodev](https://github.com/usetheodev)! - The pre-compaction seam now reaches the compaction path a consumer actually calls.
+  
+  There are three compaction paths in this ecosystem. `withPreCompaction`, shipped in
+  `@theokit/agents@14.1.0`, covers one of them — the agents-layer strategy. The other two are
+  `autoCompactIfNeeded` and `Agent.compact(sessionId, { trigger })`, and **the second is the one a
+  person reaches**: `/compact` → `handleCompact` → `compactSession` → `Agent.compact`.
+  
+  ```ts
+  await Agent.compact(agentId, {
+    trigger: "manual",
+    onPreCompact: async ({ messages, trigger, signal }) => {
+      await archive(messages, { because: trigger })   // runs BEFORE the transcript is rewritten
+    },
+    onPreCompactError: (e) => report(e),              // compaction proceeds either way
+  })
+  ```
+  
+  **One seam covers both SDK paths** because they converge on `compactSessionTranscript`. A seam per
+  caller would need each one to choose, and a caller that chooses wrong reintroduces the gap.
+  
+  **`trigger` is received, not inferred.** It already existed in the options and already reached the
+  compaction boundary; the handler is simply told. Inferring it from the call site would be right today
+  and silently wrong the first time a third caller appears.
+  
+  **Failure never blocks compaction.** A handler that throws is reported; one that exceeds its bound is
+  abandoned with its `AbortSignal` aborted first, so it can stop rather than be left running. A hook
+  that could block would turn a consumer's bug into a runtime that cannot reclaim its context.
+  
+  **Nothing changes for a consumer who registers nothing** — the seam is not entered, asserted by a
+  test rather than left as an inference.
+
 ## 5.6.0
 
 ### Minor Changes

package/dist/a2a/index.cjs

@@ -1,8 +1,8 @@
 'use strict';
 
-var chunkNQTD6QOW_cjs = require('../chunk-NQTD6QOW.cjs');
+var chunkJW3GVLM6_cjs = require('../chunk-JW3GVLM6.cjs');
 require('../chunk-NINIJCHU.cjs');
-var chunkJ7J7J2GN_cjs = require('../chunk-J7J7J2GN.cjs');
+var chunkUNFBHV46_cjs = require('../chunk-UNFBHV46.cjs');
 var chunk6LHQPOMI_cjs = require('../chunk-6LHQPOMI.cjs');
 
 // src/a2a/agent-mailbox.ts
@@ -35,7 +35,7 @@ var AgentMailbox = class {
 };
 
 // src/a2a/message-bus.ts
-var A2APeerNotRegisteredError = class extends chunkJ7J7J2GN_cjs.TheokitAgentError {
+var A2APeerNotRegisteredError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
   constructor(to) {
     super(`Agent "${to}" not registered on MessageBus`, {
       code: "a2a_peer_not_registered",
@@ -47,7 +47,7 @@ var A2APeerNotRegisteredError = class extends chunkJ7J7J2GN_cjs.TheokitAgentErro
   name = "A2APeerNotRegisteredError";
   code = "a2a_peer_not_registered";
 };
-var A2ARequestTimeoutError = class extends chunkJ7J7J2GN_cjs.TheokitAgentError {
+var A2ARequestTimeoutError = class extends chunkUNFBHV46_cjs.TheokitAgentError {
   constructor(to, timeoutMs) {
     super(`A2A request timeout: ${to} did not respond within ${timeoutMs}ms`, {
       code: "a2a_request_timeout",
@@ -124,11 +124,11 @@ var MessageBus = class {
 
 Object.defineProperty(exports, "MaxDelegationDepthError", {
   enumerable: true,
-  get: function () { return chunkNQTD6QOW_cjs.MaxDelegationDepthError; }
+  get: function () { return chunkJW3GVLM6_cjs.MaxDelegationDepthError; }
 });
 Object.defineProperty(exports, "SubAgent", {
   enumerable: true,
-  get: function () { return chunkNQTD6QOW_cjs.SubAgent; }
+  get: function () { return chunkJW3GVLM6_cjs.SubAgent; }
 });
 exports.A2APeerNotRegisteredError = A2APeerNotRegisteredError;
 exports.A2ARequestTimeoutError = A2ARequestTimeoutError;

package/dist/a2a/index.js

@@ -1,6 +1,6 @@
-export { MaxDelegationDepthError, SubAgent } from '../chunk-CFE6QF2Q.js';
+export { MaxDelegationDepthError, SubAgent } from '../chunk-XCQ432OX.js';
 import '../chunk-6X6ID4MO.js';
-import { TheokitAgentError } from '../chunk-ALUN2B4W.js';
+import { TheokitAgentError } from '../chunk-B5MHRQJZ.js';
 import { diag } from '../chunk-CZJ6Q7CW.js';
 
 // src/a2a/agent-mailbox.ts

package/dist/{agent-82d_DrCL.d.cts → agent-3RcPVGMo.d.cts}

@@ -1,5 +1,5 @@
-import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-BOiKqOgL.cjs';
-import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.cjs';
+import { o as MemoryFact, l as MemoryAdapter, n as MemoryContext, H as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-dNwjwCt5.cjs';
+import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-DsA5Ip2i.cjs';
 
 /**
  * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
@@ -815,6 +815,17 @@ interface PreToolCallDecision {
     block: true;
     message: string;
 }
+/**
+ * #65 — a 2nd argument passed to a tool handler, carrying the run's cancellation
+ * signal (ties into #58) so a cooperative tool can stop when the run is
+ * cancelled. Optional and additive — existing single-arg handlers are unaffected.
+ * (requestConfirmation/requestCredential are a documented follow-up.)
+ *
+ * @public
+ */
+interface ToolContext {
+    signal?: AbortSignal;
+}
 /** #65 — context for the `post_tool_call` hook (fired after a tool runs). @public */
 interface PostToolCallContext {
     name: string;
@@ -827,6 +838,13 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
+/** #65 — context for the `pre_llm_call` / `post_llm_call` hooks. @public */
+interface LlmCallContext {
+    agentId: string;
+    runId: string;
+    /** Iteration index (0-based) of the current turn, when available. */
+    iteration?: number;
+}
 /**
  * #65 — context for the `on_session_start` / `on_session_end` hooks.
  *
@@ -1046,7 +1064,7 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
+type CompatSource = "claude-code" | "theokit" | "agents" | "gemini" | "cursor" | CompatSourceAdapter;
 /**
  * A surface a foreign configuration source may be admitted to.
  *
@@ -1989,4 +2007,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type SessionStore as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CreateSkillSpec as D, type MemoryProviderAgentRef as E, type MemoryProviderFactory as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type MemoryProviderHandle as J, type MemoryProviderInitOptions as K, type LocalOptions as L, type MemorySettings as M, type PluginContext as N, type PluginHookDisposer as O, type Plugin as P, type PostAssistantReplyContext as Q, type PostToolCallContext as R, type SystemPromptResolver as S, type PreToolCallContext as T, type PreUserSendContext as U, type PreUserSendResult as V, type ProviderTransform as W, type ProviderTransformContext as X, type RecordSessionSummaryArgs as Y, type SessionLifecycleContext as Z, type SessionRecord as _, type AgentDefinition as a, type SettingSource as a0, Skill as a1, type SkillsResolver as a2, type SkillsResolverContext as a3, type SystemPromptContext as a4, type SystemPromptMemoryFact as a5, type TelemetrySettings as a6, type ToolCallSummary as a7, type ToolResultTransformContext as a8, type TransformContext as a9, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type MemoryProvider as l, type PreToolCallDecision as m, type ActiveMemoryPassArgs as n, type ActiveMemoryPassResult as o, type AgentSubagentDescription as p, type AgentToolDescription as q, type BudgetCheck as r, type BudgetTotal as s, type BudgetUsageEvent as t, type BuiltinToolName as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };
+export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SessionRecord as a1, type SessionStore as a2, type SettingSource as a3, Skill as a4, type SkillsResolver as a5, type SkillsResolverContext as a6, type SystemPromptContext as a7, type SystemPromptMemoryFact as a8, type TelemetrySettings as a9, type ToolCallSummary as aa, type ToolContext as ab, type ToolResultTransformContext as ac, type TransformContext as ad, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type MemoryProvider as l, type PreToolCallDecision as m, type ActiveMemoryPassArgs as n, type ActiveMemoryPassResult as o, type AgentSubagentDescription as p, type AgentToolDescription as q, type BudgetCheck as r, type BudgetTotal as s, type BudgetUsageEvent as t, type BuiltinToolName as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };

package/dist/agent-7ERQNV66.js

@@ -0,0 +1,59 @@
+export { Agent } from './chunk-3CU5J7V3.js';
+import './chunk-XKMVJ443.js';
+import './chunk-5522X223.js';
+import './chunk-K2BQQ445.js';
+import './chunk-R2C3HXR3.js';
+import './chunk-PQCTDMUI.js';
+import './chunk-2SFBB54R.js';
+import './chunk-HOHR75KF.js';
+import './chunk-H73MEMQB.js';
+import './chunk-OR6XIWLB.js';
+import './chunk-TC4RWP3Y.js';
+import './chunk-UNZOJVVC.js';
+import './chunk-NOO6GZTZ.js';
+import './chunk-SUVCHX4L.js';
+import './chunk-2XC6KDJM.js';
+import './chunk-TE6XVTOA.js';
+import './chunk-24MGQDK3.js';
+import './chunk-2WXHA33T.js';
+import './chunk-HKCKOAIO.js';
+import './chunk-DDRX4LYS.js';
+import './chunk-7GDHFV2M.js';
+import './chunk-KVNWIAO4.js';
+import './chunk-SVQIW5RJ.js';
+import './chunk-FD2UT76F.js';
+import './chunk-7I5Z3UBJ.js';
+import './chunk-FJWQP6EE.js';
+import './chunk-NAF4L3T6.js';
+import './chunk-XCQ432OX.js';
+import './chunk-6X6ID4MO.js';
+import './chunk-7HUCU3KK.js';
+import './chunk-4QCJAJAG.js';
+import './chunk-SAGRF4IB.js';
+import './chunk-5DD4NJN3.js';
+import './chunk-UKMBRMGT.js';
+import './chunk-7JAKO3NM.js';
+import './chunk-ZWFTECOE.js';
+import './chunk-GTX6FEDP.js';
+import './chunk-JOFVLOFY.js';
+import './chunk-WE22OXQA.js';
+import './chunk-XZHJYSPB.js';
+import './chunk-BKMDRBJ7.js';
+import './chunk-Q5EWJPRY.js';
+import './chunk-GGRPAQ3B.js';
+import './chunk-3JHIFQ4I.js';
+import './chunk-W4VQMXBZ.js';
+import './chunk-X7EUUHXU.js';
+import './chunk-MQGSOKR3.js';
+import './chunk-GMRFAX4I.js';
+import './chunk-R7WIIPUR.js';
+import './chunk-53RDNK3H.js';
+import './chunk-MFZODA5Y.js';
+import './chunk-AGACYRJ2.js';
+import './chunk-EJROML3Q.js';
+import './chunk-5Q4RTLMP.js';
+import './chunk-H3CVJSFC.js';
+import './chunk-B5MHRQJZ.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=agent-7ERQNV66.js.map
+//# sourceMappingURL=agent-7ERQNV66.js.map

package/dist/{agent-JJZM2VIK.js.map → agent-7ERQNV66.js.map}

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

package/dist/agent-LNTR4QH5.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+var chunk2STSX2SY_cjs = require('./chunk-2STSX2SY.cjs');
+require('./chunk-J6GXS5A2.cjs');
+require('./chunk-PSLCVSCS.cjs');
+require('./chunk-BUUUWQMB.cjs');
+require('./chunk-TTBIQTO5.cjs');
+require('./chunk-J4SA2ZEJ.cjs');
+require('./chunk-BV2MWEMV.cjs');
+require('./chunk-MEUBLCM4.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-TMKTSYDS.cjs');
+require('./chunk-76PIKR4P.cjs');
+require('./chunk-B3XXQX6L.cjs');
+require('./chunk-ARMFXTY6.cjs');
+require('./chunk-CQYBJOB2.cjs');
+require('./chunk-YJNYDJ2T.cjs');
+require('./chunk-WPO3VCY4.cjs');
+require('./chunk-QOGNZMHD.cjs');
+require('./chunk-YIFFF23U.cjs');
+require('./chunk-2ZPEDVLM.cjs');
+require('./chunk-KTA7YTZQ.cjs');
+require('./chunk-OCEQ6DW2.cjs');
+require('./chunk-KRD3GQAA.cjs');
+require('./chunk-RQMCOFAI.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-YSTXFWQE.cjs');
+require('./chunk-FRITRLZQ.cjs');
+require('./chunk-JW3GVLM6.cjs');
+require('./chunk-NINIJCHU.cjs');
+require('./chunk-HG5LKFG7.cjs');
+require('./chunk-SWALPLFQ.cjs');
+require('./chunk-IJ7M6GOG.cjs');
+require('./chunk-GM54F4FE.cjs');
+require('./chunk-SA6K24NB.cjs');
+require('./chunk-IIYJMXYW.cjs');
+require('./chunk-NJSIAJEK.cjs');
+require('./chunk-NKIQTLFA.cjs');
+require('./chunk-GZV6AVRL.cjs');
+require('./chunk-A4RAL2ER.cjs');
+require('./chunk-P22BZE7G.cjs');
+require('./chunk-OF2CLCTH.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-GHHIJEFX.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-XW4POZ6V.cjs');
+require('./chunk-TY56BKSK.cjs');
+require('./chunk-MPR2ISL2.cjs');
+require('./chunk-J5623RIV.cjs');
+require('./chunk-3EE6LVWT.cjs');
+require('./chunk-R3ZQBPA5.cjs');
+require('./chunk-YRJA2POB.cjs');
+require('./chunk-NVXXWAU7.cjs');
+require('./chunk-RA7IE4NK.cjs');
+require('./chunk-NAGPKWOD.cjs');
+require('./chunk-OLSEWLK5.cjs');
+require('./chunk-UNFBHV46.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "Agent", {
+  enumerable: true,
+  get: function () { return chunk2STSX2SY_cjs.Agent; }
+});
+//# sourceMappingURL=agent-LNTR4QH5.cjs.map
+//# sourceMappingURL=agent-LNTR4QH5.cjs.map

package/dist/{agent-47NS6ZVL.cjs.map → agent-LNTR4QH5.cjs.map}

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

package/dist/{agent-G6g-uwcB.d.ts → agent-lS68mYIL.d.ts}

@@ -1,5 +1,5 @@
-import { n as MemoryFact, k as MemoryAdapter, m as MemoryContext, E as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-D4a_BR_6.js';
-import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-CTAdRU3U.js';
+import { o as MemoryFact, l as MemoryAdapter, n as MemoryContext, H as SystemPromptSkillRef, C as ContextSettings, P as ProviderRoutingSettings, a as PluginsSettings, S as SDKAgent } from './sdk-agent-wEOLXD3F.js';
+import { M as ModelSelection, C as CustomTool, c as PermissionMode, a as McpServerConfig, P as Processor } from './run-DsA5Ip2i.js';
 
 /**
  * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
@@ -815,6 +815,17 @@ interface PreToolCallDecision {
     block: true;
     message: string;
 }
+/**
+ * #65 — a 2nd argument passed to a tool handler, carrying the run's cancellation
+ * signal (ties into #58) so a cooperative tool can stop when the run is
+ * cancelled. Optional and additive — existing single-arg handlers are unaffected.
+ * (requestConfirmation/requestCredential are a documented follow-up.)
+ *
+ * @public
+ */
+interface ToolContext {
+    signal?: AbortSignal;
+}
 /** #65 — context for the `post_tool_call` hook (fired after a tool runs). @public */
 interface PostToolCallContext {
     name: string;
@@ -827,6 +838,13 @@ interface PostToolCallContext {
     agentId: string;
     runId: string;
 }
+/** #65 — context for the `pre_llm_call` / `post_llm_call` hooks. @public */
+interface LlmCallContext {
+    agentId: string;
+    runId: string;
+    /** Iteration index (0-based) of the current turn, when available. */
+    iteration?: number;
+}
 /**
  * #65 — context for the `on_session_start` / `on_session_end` hooks.
  *
@@ -1046,7 +1064,7 @@ type SettingSource = "project" | "user" | "team" | "mdm" | "plugins" | "all";
  *
  * @public
  */
-type CompatSource = "claude-code" | "theokit" | CompatSourceAdapter;
+type CompatSource = "claude-code" | "theokit" | "agents" | "gemini" | "cursor" | CompatSourceAdapter;
 /**
  * A surface a foreign configuration source may be admitted to.
  *
@@ -1989,4 +2007,4 @@ interface ListResult<T> {
     nextCursor?: string;
 }
 
-export { type SessionStore as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CreateSkillSpec as D, type MemoryProviderAgentRef as E, type MemoryProviderFactory as F, type GetAgentOptions as G, type HookName as H, type InlineSkill as I, type MemoryProviderHandle as J, type MemoryProviderInitOptions as K, type LocalOptions as L, type MemorySettings as M, type PluginContext as N, type PluginHookDisposer as O, type Plugin as P, type PostAssistantReplyContext as Q, type PostToolCallContext as R, type SystemPromptResolver as S, type PreToolCallContext as T, type PreUserSendContext as U, type PreUserSendResult as V, type ProviderTransform as W, type ProviderTransformContext as X, type RecordSessionSummaryArgs as Y, type SessionLifecycleContext as Z, type SessionRecord as _, type AgentDefinition as a, type SettingSource as a0, Skill as a1, type SkillsResolver as a2, type SkillsResolverContext as a3, type SystemPromptContext as a4, type SystemPromptMemoryFact as a5, type TelemetrySettings as a6, type ToolCallSummary as a7, type ToolResultTransformContext as a8, type TransformContext as a9, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type MemoryProvider as l, type PreToolCallDecision as m, type ActiveMemoryPassArgs as n, type ActiveMemoryPassResult as o, type AgentSubagentDescription as p, type AgentToolDescription as q, type BudgetCheck as r, type BudgetTotal as s, type BudgetUsageEvent as t, type BuiltinToolName as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };
+export { type RecordSessionSummaryArgs as $, type AgentOptions as A, type BudgetTracker as B, type CloudOptions as C, type CreateSkillSpec as D, type HookApprovalRequest as E, type HookName as F, type GetAgentOptions as G, type HookApprovalGate as H, type InlineSkill as I, type LlmCallContext as J, type MemoryProviderAgentRef as K, type LocalOptions as L, type MemorySettings as M, type MemoryProviderFactory as N, type MemoryProviderHandle as O, type Plugin as P, type MemoryProviderInitOptions as Q, type PluginContext as R, type SystemPromptResolver as S, type PluginHookDisposer as T, type PostAssistantReplyContext as U, type PostToolCallContext as V, type PreToolCallContext as W, type PreUserSendContext as X, type PreUserSendResult as Y, type ProviderTransform as Z, type ProviderTransformContext as _, type AgentDefinition as a, type SessionLifecycleContext as a0, type SessionRecord as a1, type SessionStore as a2, type SettingSource as a3, Skill as a4, type SkillsResolver as a5, type SkillsResolverContext as a6, type SystemPromptContext as a7, type SystemPromptMemoryFact as a8, type TelemetrySettings as a9, type ToolCallSummary as aa, type ToolContext as ab, type ToolResultTransformContext as ac, type TransformContext as ad, type SkillsSettings as b, type ListAgentsOptions as c, type ListResult as d, type SDKAgentInfo as e, type ListRunsOptions as f, type GetRunOptions as g, type AgentOperationOptions as h, type AgentDescription as i, type ProviderProfile as j, type Skill$1 as k, type MemoryProvider as l, type PreToolCallDecision as m, type ActiveMemoryPassArgs as n, type ActiveMemoryPassResult as o, type AgentSubagentDescription as p, type AgentToolDescription as q, type BudgetCheck as r, type BudgetTotal as s, type BudgetUsageEvent as t, type BuiltinToolName as u, type CloudEnv as v, type CloudRepo as w, type CompatSource as x, type CompatSourceAdapter as y, type CompatSurface as z };

package/dist/agent.d.ts

@@ -219,6 +219,17 @@ export declare class Agent {
     static compact(agentId: string, options?: {
         trigger?: "manual" | "auto";
         summarize?: (messages: readonly import("./compaction.js").CompressibleMessage[]) => Promise<string>;
+        /**
+         * B-082 — work to run before the transcript is rewritten, on THIS path.
+         *
+         * `/compact` reaches here, and before this option the seam existed only on the agents-layer
+         * strategy, which this path never touches. The handler is awaited, bounded, and its failure is
+         * reported without stopping compaction — the same contract `withPreCompaction` carries, not a
+         * second one.
+         */
+        onPreCompact?: import("./internal/session/compact-session.js").PreCompactHandler;
+        onPreCompactError?: (error: unknown) => void;
+        preCompactTimeoutMs?: number;
     }): Promise<import("./internal/session/compact-session.js").CompactResult>;
     /**
      * M51 — inject a SYNTHETIC user+assistant pair into a LOCAL session's persisted transcript WITHOUT

package/dist/auth/index.cjs

@@ -1,10 +1,10 @@
 'use strict';
 
 var chunkFRITRLZQ_cjs = require('../chunk-FRITRLZQ.cjs');
-var chunk4NLCWGH7_cjs = require('../chunk-4NLCWGH7.cjs');
-var chunkEXTRW7GW_cjs = require('../chunk-EXTRW7GW.cjs');
-var chunkHUFSABUZ_cjs = require('../chunk-HUFSABUZ.cjs');
-require('../chunk-J7J7J2GN.cjs');
+var chunkRA7IE4NK_cjs = require('../chunk-RA7IE4NK.cjs');
+var chunkNAGPKWOD_cjs = require('../chunk-NAGPKWOD.cjs');
+var chunkOLSEWLK5_cjs = require('../chunk-OLSEWLK5.cjs');
+require('../chunk-UNFBHV46.cjs');
 require('../chunk-6LHQPOMI.cjs');
 
 // src/internal/auth/oauth-device.ts
@@ -14,7 +14,7 @@ async function parseJsonOrFail(res, code, what) {
   try {
     return JSON.parse(text);
   } catch {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(code, `${what} returned a non-JSON body: ${text.slice(0, 120)}`);
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(code, `${what} returned a non-JSON body: ${text.slice(0, 120)}`);
   }
 }
 async function requestDeviceCode(config, deps) {
@@ -29,13 +29,13 @@ async function requestDeviceCode(config, deps) {
       }).toString()
     });
   } catch (err) {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       `device request failed: ${err.message}`
     );
   }
   if (!res.ok) {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       `device endpoint returned HTTP ${res.status}`
     );
@@ -46,7 +46,7 @@ async function requestDeviceCode(config, deps) {
     "device endpoint"
   );
   if (typeof data.device_code !== "string" || typeof data.user_code !== "string") {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       "device response missing device_code/user_code"
     );
@@ -79,14 +79,14 @@ async function pollDeviceToken(config, grant, deps) {
         }).toString()
       });
     } catch (err) {
-      throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+      throw new chunkOLSEWLK5_cjs.AuthCallbackError(
         "oauth_token_exchange_failed",
         `device token poll failed: ${err.message}`
       );
     }
     const data = await res.json().catch(() => ({}));
     if (!res.ok && typeof data.error !== "string") {
-      throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+      throw new chunkOLSEWLK5_cjs.AuthCallbackError(
         "oauth_token_exchange_failed",
         `device token endpoint returned HTTP ${res.status}`
       );
@@ -116,14 +116,14 @@ async function pollDeviceToken(config, grant, deps) {
       continue;
     }
     if (typeof data.error === "string") {
-      throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+      throw new chunkOLSEWLK5_cjs.AuthCallbackError(
         "oauth_token_exchange_failed",
         `device authorization rejected: ${data.error}`
       );
     }
     await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
   }
-  throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+  throw new chunkOLSEWLK5_cjs.AuthCallbackError(
     "oauth_device_code_expired",
     "the device code expired before it was approved"
   );
@@ -146,13 +146,13 @@ async function requestOpenAIUsercode(config, deps) {
       body: JSON.stringify({ client_id: config.clientId })
     });
   } catch (err) {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       `usercode request failed: ${err.message}`
     );
   }
   if (!res.ok) {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       `usercode endpoint returned HTTP ${res.status}`
     );
@@ -163,7 +163,7 @@ async function requestOpenAIUsercode(config, deps) {
     "usercode endpoint"
   );
   if (typeof data.device_auth_id !== "string" || typeof data.user_code !== "string") {
-    throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+    throw new chunkOLSEWLK5_cjs.AuthCallbackError(
       "oauth_device_authorization_failed",
       "usercode response missing device_auth_id/user_code"
     );
@@ -188,7 +188,7 @@ async function openaiDeviceLogin(config, deps, hooks) {
         body: JSON.stringify({ device_auth_id: deviceAuthId, user_code: userCode })
       });
     } catch (err) {
-      throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+      throw new chunkOLSEWLK5_cjs.AuthCallbackError(
         "oauth_token_exchange_failed",
         `device poll failed: ${err.message}`
       );
@@ -196,12 +196,12 @@ async function openaiDeviceLogin(config, deps, hooks) {
     if (res.ok) {
       const data = await parseJsonOrFail(res, "oauth_token_exchange_failed", "device poll");
       if (typeof data.authorization_code !== "string" || typeof data.code_verifier !== "string") {
-        throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+        throw new chunkOLSEWLK5_cjs.AuthCallbackError(
           "oauth_token_exchange_failed",
           "device poll returned no authorization_code"
         );
       }
-      const tokens = await chunk4NLCWGH7_cjs.exchangeCode(
+      const tokens = await chunkRA7IE4NK_cjs.exchangeCode(
         config,
         { code: data.authorization_code, verifier: data.code_verifier },
         deps
@@ -212,14 +212,14 @@ async function openaiDeviceLogin(config, deps, hooks) {
       };
     }
     if (res.status !== 403 && res.status !== 404) {
-      throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+      throw new chunkOLSEWLK5_cjs.AuthCallbackError(
         "oauth_token_exchange_failed",
         `device poll returned HTTP ${res.status}`
       );
     }
     await deps.sleep(intervalMs + POLLING_SAFETY_MARGIN_MS);
   }
-  throw new chunkHUFSABUZ_cjs.AuthCallbackError(
+  throw new chunkOLSEWLK5_cjs.AuthCallbackError(
     "oauth_device_code_expired",
     "the device authorization expired before approval"
   );
@@ -249,51 +249,51 @@ Object.defineProperty(exports, "providerFromApiKeyPrefix", {
 });
 Object.defineProperty(exports, "ensureFreshCredential", {
   enumerable: true,
-  get: function () { return chunk4NLCWGH7_cjs.ensureFreshCredential; }
+  get: function () { return chunkRA7IE4NK_cjs.ensureFreshCredential; }
 });
 Object.defineProperty(exports, "exchangeCode", {
   enumerable: true,
-  get: function () { return chunk4NLCWGH7_cjs.exchangeCode; }
+  get: function () { return chunkRA7IE4NK_cjs.exchangeCode; }
 });
 Object.defineProperty(exports, "persistOAuthTokens", {
   enumerable: true,
-  get: function () { return chunk4NLCWGH7_cjs.persistOAuthTokens; }
+  get: function () { return chunkRA7IE4NK_cjs.persistOAuthTokens; }
 });
 Object.defineProperty(exports, "refreshOAuthTokens", {
   enumerable: true,
-  get: function () { return chunk4NLCWGH7_cjs.refreshOAuthTokens; }
+  get: function () { return chunkRA7IE4NK_cjs.refreshOAuthTokens; }
 });
 Object.defineProperty(exports, "resolveCredential", {
   enumerable: true,
-  get: function () { return chunk4NLCWGH7_cjs.resolveCredential; }
+  get: function () { return chunkRA7IE4NK_cjs.resolveCredential; }
 });
 Object.defineProperty(exports, "CredentialError", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.CredentialError; }
+  get: function () { return chunkNAGPKWOD_cjs.CredentialError; }
 });
 Object.defineProperty(exports, "assertSecureModes", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.assertSecureModes; }
+  get: function () { return chunkNAGPKWOD_cjs.assertSecureModes; }
 });
 Object.defineProperty(exports, "authFilePath", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.authFilePath; }
+  get: function () { return chunkNAGPKWOD_cjs.authFilePath; }
 });
 Object.defineProperty(exports, "credentialHome", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.credentialHome; }
+  get: function () { return chunkNAGPKWOD_cjs.credentialHome; }
 });
 Object.defineProperty(exports, "readAuthFile", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.readAuthFile; }
+  get: function () { return chunkNAGPKWOD_cjs.readAuthFile; }
 });
 Object.defineProperty(exports, "readStoredOAuth", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.readStoredOAuth; }
+  get: function () { return chunkNAGPKWOD_cjs.readStoredOAuth; }
 });
 Object.defineProperty(exports, "writeCredential", {
   enumerable: true,
-  get: function () { return chunkEXTRW7GW_cjs.writeCredential; }
+  get: function () { return chunkNAGPKWOD_cjs.writeCredential; }
 });
 exports.deviceLogin = deviceLogin;
 exports.extractAccountId = extractAccountId;