@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/index.d.cts

@@ -1,14 +1,16 @@
-import { T as TheokitAgentError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot, E as ErrorMetadata } from './errors-BgJH9PHi.cjs';
-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, m as ErrorCode, I as IntegrationNotConnectedError, n as InvalidTaskIdError, M as MemoryAdapterError, o as MemoryAdapterErrorCode, N as NetworkError, R as RateLimitError, p as TaskNotFoundError, U as UnknownAgentError, q as UnsupportedBudgetOperationError, r as UnsupportedRunOperationError, s as UnsupportedTaskOperationError, t as isTransientError } from './errors-BgJH9PHi.cjs';
-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-X0DKA943.cjs';
-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 CreateSkillSpec, H as HookName, x as MemoryProviderFactory, y as MemoryProviderHandle, z as MemoryProviderInitOptions, D as PluginContext, E as PostAssistantReplyContext, F as PostToolCallContext, J as PreToolCallContext, K as PreUserSendContext, N as PreUserSendResult, O as ProviderTransform, Q as ProviderTransformContext, R as RecordSessionSummaryArgs, T as SessionLifecycleContext, U as SessionRecord, V as SessionStore, W as SettingSource, X as Skill, Y as SkillsResolver, Z as SkillsResolverContext, _ as SystemPromptContext, $ as SystemPromptMemoryFact, a0 as TelemetrySettings, a1 as ToolCallSummary, a2 as ToolResultTransformContext, a3 as TransformContext } from './agent-X0DKA943.cjs';
-import { k as CostBreakdown, aw 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 PermissionEngine, e as RunEventSink, S as SDKMessage } from './run-BYSHf58D.cjs';
-export { A as AgentConversationTurn, f as AssistantMessage, g as CompletionCheck, h as CompletionCheckResult, i as ConversationStep, j as ConversationTurn, k as CostBreakdown, l as CostSource, m as CostStatus, D as DoomLoopThresholds, G as GenerateOptions, n as GenerateRunResult, I as ImageBlock, o as InputProcessorContext, p as InteractionUpdate, q as McpAuthConfig, r as McpHttpServerConfig, s as McpOAuthConfig, t as McpStdioServerConfig, u as MessageOrigin, v as ModelParameterValue, O as OutputProcessorContext, w as PartialToolCallUpdate, x as PermissionAction, y as PermissionEngineOptions, z as PermissionRule, B as ProcessorControls, E as ProcessorTripwire, F as ProcessorViolation, H as RunCompactBoundaryEvent, J as RunCompletionCheckEvent, K as RunErrorDetail, L as RunEvent, N as RunGitInfo, Q as RunOperation, U as RunPermissionDeniedEvent, V as RunRateLimitEvent, W as RunStatus, X as RunTaskCompletedEvent, Y as RunTaskStartedEvent, Z as RunTaskUpdatedEvent, _ as RunTimelineEvent, $ as RunToCompletionOptions, a0 as RunToCompletionResult, a1 as RunToolProgressEvent, a2 as RunTripwireEvent, a3 as SDKAssistantMessage, a4 as SDKImage, a5 as SDKImageDimension, a6 as SDKObjectDelta, a7 as SDKRequestMessage, a8 as SDKStatusMessage, a9 as SDKSystemMessage, aa as SDKTaskMessage, ab as SDKThinkingMessage, ac as SDKToolUseMessage, ad as SDKUserMessage, ae as SDKUserMessageEvent, af as SendOptions, ag as ShellCommand, ah as ShellConversationTurn, ai as ShellOutput, aj as ShellOutputDeltaUpdate, ak as StepCompletedUpdate, al as StepStartedUpdate, am as StreamToCompletionResult, an as SummaryCompletedUpdate, ao as SummaryStartedUpdate, ap as SummaryUpdate, aq as TextBlock, ar as TextDeltaUpdate, as as ThinkingCompletedUpdate, at as ThinkingDeltaUpdate, au as ThinkingMessage, av as TokenDeltaUpdate, aw as TokenUsage, ax as ToolCall, ay as ToolCallCompletedUpdate, az as ToolCallStartedUpdate, aA as ToolContextMessage, aB as ToolResult, aC as ToolResultGuardOptions, aD as ToolUseBlock, aE as TurnEndedUpdate, aF as UserMessage, aG as UserMessageAppendedUpdate, aH as applyMode, aI as emitRunEvent } from './run-BYSHf58D.cjs';
+import { T as TheokitAgentError, E as ErrorMetadata } from './errors-base-B5g01neU.cjs';
+export { a as ErrorCode } from './errors-base-B5g01neU.cjs';
+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.cjs';
+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.cjs';
+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-C3KO5LKm.cjs';
+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-C3KO5LKm.cjs';
 import * as zod from 'zod';
 import { ZodType, z } from 'zod';
-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-DEoKhA8a.cjs';
-export { A as AgentMemory, e as ContextBudget, f as ContextManagerKind, g as ContextSnapshot, h as ContextSource, i as ContextSourceStatus, I as InvalidateCacheOptions, j as MemoryAdapter, k as MemoryAdapterCapabilities, l as MemoryContext, m as MemoryFact, n as MemoryRevision, o as MemoryToolSchema, p as MemoryTurnMessage, q as PersonalityPreset, r as ProviderCapability, s as ProviderRoute, R as ResolvedProviderRoute, t as RunUntilIterator, u as SDKAgentPlugins, v as SDKAgentSkillDetail, w as SDKAgentSkills, x as SDKArtifact, y as SDKContextManager, z as SDKPluginMetadata, B as SDKProvidersManager, D as SystemPromptSkillRef, V as Verdict } from './sdk-agent-DEoKhA8a.cjs';
-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-BuiRPrvt.cjs';
+import { S as StructuredOutputError, B as BudgetOptions, a as BudgetHandle, b as BudgetSnapshot } from './errors-DrDEgyz1.cjs';
+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-DrDEgyz1.cjs';
+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-BOiKqOgL.cjs';
+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-BOiKqOgL.cjs';
+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-C3PhZED0.cjs';
 import { StepResult } from './workflow.cjs';
 export { Workflow, agentStep, fn } from './workflow.cjs';
 
@@ -45,6 +47,17 @@ interface CompressibleMessage {
     role: "user" | "assistant" | "system";
     content: string;
 }
+/**
+ * Tokenizer-free token estimate via the conventional ~4-chars-per-token
+ * heuristic: `ceil(text.length / CHARS_PER_TOKEN)`. `""` → 0; any non-empty text → ≥ 1.
+ * A cheap PRE-CALL gate for {@link shouldCompact} — NOT exact tokenization
+ * (a consumer needing exactness supplies their own tokenizer). Uses UTF-16
+ * `.length` (code units), so multibyte text is approximate.
+ *
+ * `built-in-processors.ts` re-exports this under the same name, so both entry points keep working
+ * and there is one implementation behind them.
+ */
+declare function estimateTokens(text: string): number;
 
 /**
  * M50 (agent-builder) — session-transcript compaction.
@@ -68,6 +81,9 @@ interface CompactResult {
 }
 
 /**
+ * Owner: `src/` (2 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public types for `Agent.batch` (ADRs D134-D140).
  *
  * Run N prompts in parallel with bounded concurrency. Each prompt gets
@@ -250,11 +266,8 @@ type StreamObjectEvent<T> = {
  *
  * @public
  */
-declare class StreamObjectError extends Error {
+declare class StreamObjectError extends StructuredOutputError {
     readonly name = "StreamObjectError";
-    readonly code: "no_tool_call" | "parse_failed";
-    readonly cause?: unknown;
-    constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
 }
 
 /**
@@ -334,11 +347,8 @@ interface GenerateObjectResult<T> {
  *
  * @public
  */
-declare class GenerateObjectError extends Error {
+declare class GenerateObjectError extends StructuredOutputError {
     readonly name = "GenerateObjectError";
-    readonly code: "no_tool_call" | "parse_failed";
-    readonly cause?: unknown;
-    constructor(code: "no_tool_call" | "parse_failed", message: string, cause?: unknown);
 }
 
 /**
@@ -534,6 +544,9 @@ declare class LiveAgentRegistry {
 }
 
 /**
+ * Owner: `src/` (1 of 2 importers). Derived from the import graph, not
+ * declared — `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * The shape of a persisted session turn, as a HOST reads it.
  *
  * Lives in `types/` because it is public contract — `Agent.transcript()` returns it (theokit#146).
@@ -736,7 +749,7 @@ declare class Agent {
      *
      *   This bullet used to say the opposite ("Disposed agents are NOT auto-deleted...
      *   call `Agent.delete(agentId)` first"). It was measured false in M91:
-     *   `tests/m91-getorcreate-after-dispose.test.ts` builds an agent, disposes it, and
+     *   `tests/agent-getorcreate-after-dispose.test.ts` builds an agent, disposes it, and
      *   gets a different instance back. The claim was about the PERSISTENT registry and
      *   read as being about the live cache — and consumers built around the wrong half.
      *   The agent-builder's M85 interrupt rotates the session id to work around a
@@ -1115,11 +1128,11 @@ declare function computeCost(args: ComputeArgs): CostBreakdown;
 /**
  * Budget enforcement (ADRs D383, D386, EC-7/8/9).
  *
- * - `preflightCheck(name, estimatedUsd)` — em `block` mode, throw
+ * - `preflightCheck(name, estimatedUsd)` — in `block` mode, throw
  *   `BudgetExceededError` before the LLM call if any limit would be
  *   exceeded (EC-9 — the caller invokes it inside the mutex section).
- * - `chargeAndCheckThresholds(name, actualUsd)` — apply charge ao
- *   ledger + invokes onThreshold/onExceed callbacks isolated in
+ * - `chargeAndCheckThresholds(name, actualUsd)` — apply the charge to the
+ *   ledger + invoke onThreshold/onExceed callbacks isolated in
  *   try/catch (EC-8).
  *
  * @internal
@@ -1373,13 +1386,15 @@ declare class Budget {
  *
  * @public
  */
-
 /**
  * Approximate token count from string length. This is an ESTIMATE
  * (≈ UTF-16-code-units / 4, NOT Unicode code points, NOT an exact per-model
  * tokenizer count) — good enough for a coarse cap, and dependency-free.
+ *
+ * Re-exported rather than reimplemented: the ratio lives in `compaction.ts`, which is where the
+ * heuristic is load-bearing. The name and the behaviour here are unchanged.
  */
-declare function estimateTokens(text: string): number;
+
 /** Options for {@link createUnicodeNormalizer}. @public */
 interface UnicodeNormalizerOptions {
     /** Remove C0 + C1 control chars + DEL (keeps tab / newline / carriage-return). Default `false`. */
@@ -1394,12 +1409,18 @@ interface TokenLimiterOptions {
     /** Over the limit: `"truncate"` (default, cut to fit) or `"block"` (abort with a tripwire). */
     strategy?: "truncate" | "block";
 }
-/** SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015). @public */
+/** SE36 — `TokenLimiter.create` replaces `createTokenLimiter` (ADR 0015). @public  *
+ * `TokenLimiter.create` returns a **`Processor`**, not a `TokenLimiter`. The class is
+ * the namespace; the processor is the product.
+ */
 declare class TokenLimiter {
     private constructor();
     static create(opts: TokenLimiterOptions): Processor;
 }
-/** SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015). @public */
+/** SE36 — `UnicodeNormalizer.create` replaces `createUnicodeNormalizer` (ADR 0015). @public  *
+ * `UnicodeNormalizer.create` returns a **`Processor`**, not a `UnicodeNormalizer`. The
+ * class is the namespace; the processor is the product.
+ */
 declare class UnicodeNormalizer {
     private constructor();
     static create(opts?: UnicodeNormalizerOptions): Processor;
@@ -1557,7 +1578,10 @@ declare class Provider {
  * @public
  */
 
-/** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public */
+/** SE36 — `SkillReadTool.create` replaces `defineSkillReadTool` (ADR 0015). @public  *
+ * `SkillReadTool.create` returns a **`CustomTool`** — a skill-reading tool, not a
+ * `SkillReadTool` instance.
+ */
 declare class SkillReadTool {
     private constructor();
     static create(skills: ReadonlyArray<InlineSkill>): CustomTool;
@@ -1585,9 +1609,22 @@ interface SanitizeOptions {
      * descended into).
      */
     schema?: ZodType;
-    /** Recurse into nested objects/arrays. Default `false` (shallow). */
+    /**
+     * Recurse into nested plain objects. Default `false` (shallow).
+     *
+     * ARRAYS ARE NOT GATED BY THIS. Their string elements are sanitized by whichever rungs are on —
+     * `trim` is on by default — because a value does not stop being a string by sitting in a list, and
+     * a caller who saw `{ tag: "  a  " }` trimmed has no reason to expect `{ tags: ["  a  "] }` left
+     * alone. What `deep` gates is descending into OBJECTS, wherever they are: at the top level, nested,
+     * or inside an array.
+     */
     deep?: boolean;
-    /** Max recursion depth when `deep` is set. Default `8`. */
+    /**
+     * Max recursion depth. Default `8`.
+     *
+     * Counts every hop, array or object, so a deeply nested structure cannot recurse without bound even
+     * when `deep` is off — array descent is not gated by `deep`, and this is what bounds it.
+     */
     maxDepth?: number;
 }
 
@@ -2006,6 +2043,23 @@ type DiagnosticsSink = (message: string) => void;
  */
 declare function setDiagnosticsSink(next: DiagnosticsSink | undefined): void;
 
+/**
+ * The fail-safe emitter for the `RunEvent` stream — runtime, deliberately NOT in `types/`.
+ *
+ * Eleven modules across `agent-loop/`, `runtime/`, `task/` and `local-agent/` call it; the type it
+ * carries stays in `types/run-events.ts`, which is what `types/` is for. Sibling of
+ * `internal/diagnostics.ts`, which swallows sink failures on the same principle and for the same
+ * reason: observability degrades what you can SEE, never what the agent DOES.
+ *
+ * @internal
+ */
+/**
+ * SE2 — emit a {@link RunEvent} to an optional sink, swallowing any sink error so
+ * observability can never break the run (fail-safe, mirrors the EventBus EC-2
+ * contract). No-op when the sink is absent.
+ */
+declare function emitRunEvent(sink: RunEventSink$1 | undefined, event: RunEvent): void;
+
 /**
  * Run `fn` after every earlier `withCwdMutex` call for the same `key` has settled, and return
  * what `fn` returns.
@@ -2071,6 +2125,29 @@ declare class NoopMemoryProvider {
     static create(): MemoryProvider;
 }
 
+/**
+ * Task-id grammar (D368) — runtime, deliberately NOT in `types/`.
+ *
+ * It lived in `types/task.ts`, which `types/index.ts` re-exports with `export type *`. That star
+ * cannot carry a value, so the only reason `isValidTaskId` ever reached a consumer is that the DTS
+ * rollup hoists the declaration while the runtime bundle emits nothing — exactly the shape of #279,
+ * where the import typechecked and was `undefined` at the call site. `src/index.ts` re-exports both
+ * names from here, so the public API is unchanged.
+ *
+ * @internal
+ */
+/**
+ * Validates a task ID against the public grammar + reserved prefixes.
+ * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
+ *
+ * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
+ * to register their own IDs; user-facing surfaces (`Task.submit`,
+ * `agent.send({ task: { id } })`) leave it false.
+ */
+declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
+/** Re-exported for adapter implementations + tests. */
+declare const TASK_RESERVED_PREFIXES: readonly string[];
+
 /**
  * The subset of the OpenTelemetry `Span` API this SDK calls.
  *
@@ -2287,6 +2364,12 @@ interface MemoryIndexHandle {
         filesUpdated: number;
         chunksWritten: number;
         chunksEmbedded: number;
+        /**
+         * Whether this backend actually walked a corpus. `false` on the Lance backend, which is a
+         * vector store fed by explicit writes and has no corpus — its zero counts mean "not applicable",
+         * not "nothing to reindex". Read this before treating the counts as a measurement.
+         */
+        supported: boolean;
     }>;
     search(query: string, options?: {
         maxResults?: number;
@@ -2308,6 +2391,12 @@ interface MemoryIndexHandle {
         filesIndexed: number;
         chunksIndexed: number;
         lastSyncMs?: number;
+        /**
+         * Whether `filesIndexed` / `chunksIndexed` were measured. `false` on the Lance backend, whose
+         * store is async while `status()` is not — the zeros there are placeholders, so
+         * `chunksIndexed > 0` is not a valid test for "is the index populated".
+         */
+        countsExact: boolean;
     };
     close(): Promise<void> | void;
 }
@@ -2493,6 +2582,121 @@ interface MigrateResult {
  */
 declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateResult>;
 
+/**
+ * `PermissionEngine` — first-match permission rules for tool invocations.
+ *
+ * Evaluates a tool name (and optional arguments, #55) against an ordered list
+ * of rules. First matching rule wins; when no rule matches the `defaultAction`
+ * is returned. #55 — the default is now `"ask"` (FAIL-CLOSED): a permission
+ * engine that cannot positively allow must not silently allow. Opt back into
+ * the previous fail-open behavior with `{ defaultAction: "allow" }`.
+ */
+type PermissionAction = "allow" | "deny" | "ask";
+
+/**
+ * SE1 — apply a {@link PermissionMode} to a rule-engine verdict. Pure.
+ *
+ * `explicit` is `true` when the verdict came from a rule that matched by name (and
+ * args), `false` when it is the fail-closed default for an unmatched call. The flag
+ * is load-bearing for `acceptEdits`, which auto-approves the unmatched default but
+ * keeps honoring an explicit `ask` rule (unlike `bypass`, which allows even that).
+ *
+ * INVARIANT (both a peer project + Codex): an explicit `deny` is immune to EVERY
+ * auto-approve mode — `bypass`/`acceptEdits` never un-deny.
+ */
+declare function applyMode(verdict: PermissionAction, mode: PermissionMode, explicit: boolean): PermissionAction;
+/**
+ * #55 — an argument matcher. A rule with `args` gates on the tool's argument
+ * VALUES, not just its name: an exact string, a RegExp (tested against the
+ * stringified value), or a predicate. Every declared arg must match for the
+ * rule to apply — so `{ tool: "shell", args: { command: /rm\s+-rf/ } }` denies
+ * a destructive shell call while leaving `ls` to fall through.
+ */
+type ArgMatcher = string | RegExp | ((value: unknown) => boolean);
+/**
+ * One entry in a {@link PermissionEngine}'s ordered rule list.
+ *
+ * Order is the semantics. The engine walks the list and the first rule whose `tool` matches — and
+ * whose `args` matchers all pass, when it declares any — decides; nothing after it is consulted. Put
+ * the narrow rules first: a catch-all `tool` RegExp placed above a specific deny makes that deny
+ * unreachable, and nothing warns you.
+ *
+ * `args` is what lets one tool name resolve differently depending on what it is asked to do —
+ * `{ tool: "shell", args: { command: /rm\s+-rf/ }, action: "deny" }` blocks the destructive call and
+ * leaves `ls` to fall through to a later rule. Every declared matcher must pass.
+ *
+ * **A rule that declares an argument the call did not supply does not match**, whatever form the
+ * matcher takes — string, RegExp or predicate. The predicate is not invoked with `undefined`; the
+ * guard runs first, for every matcher form. Evaluation continues to the next rule.
+ *
+ * That was not always true, and the fix is the reason this paragraph is explicit (#367). A predicate
+ * used to be called anyway, so `(v) => v !== "prod"` returned true for a missing argument and an
+ * ALLOW rule authorized a call that supplied nothing, while `(v) => v.includes("rm")` threw a
+ * TypeError out of the permission gate. This docblock told consumers to guard every predicate by
+ * hand for months after `argMatches` stopped needing it — you do not have to.
+ *
+ * A rule that matches yields an EXPLICIT verdict, and that is what makes it survive a permissive
+ * `PermissionMode`: `acceptEdits` auto-approves the unmatched default but still honours an explicit
+ * `ask` rule, and an explicit `deny` is immune to every mode, `bypass` included.
+ */
+interface PermissionRule {
+    /** Tool name (exact string) or pattern (RegExp). */
+    tool: string | RegExp;
+    /**
+     * #55 — optional per-argument matchers. When present, the rule matches only
+     * if the tool name matches AND every declared arg predicate matches the
+     * corresponding call argument. A missing/undefined arg fails its predicate
+     * (the rule does not match) — never throws.
+     */
+    args?: Record<string, ArgMatcher>;
+    /** Action to take when rule matches. */
+    action: PermissionAction;
+}
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /**
+     * Action when no rule matches. #55 — default is now `"ask"` (fail-closed): a
+     * permission engine that cannot positively allow must not silently allow.
+     * Pass `"allow"` to restore the previous fail-open behavior.
+     */
+    readonly defaultAction?: PermissionAction;
+}
+/**
+ * Ordered first-match permission rules for tool invocations — the policy object you hand to
+ * `PermissionPlugin.create()` to have it enforced.
+ *
+ * On its own it enforces nothing. `evaluate(toolName, args, mode)` is a pure function returning
+ * `"allow" | "deny" | "ask"`, and no part of the SDK calls it until the engine is wrapped in a plugin
+ * and that plugin is registered on an agent. The plugin is where a verdict becomes behaviour: `deny`
+ * blocks the tool call, `allow` passes it through, and `ask` is routed to the host's `canUseTool`
+ * gate — with no gate configured, `ask` blocks. So constructing an engine and never registering it
+ * is a policy that does nothing, which is the mistake worth knowing about first.
+ *
+ * It is fail-closed by default: a call no rule matches resolves to `"ask"`, not `"allow"`, so a tool
+ * the rules never mention needs a human — or an explicit `{ defaultAction: "allow" }` — before it
+ * runs. Keep that default if you intend to use `PermissionMode: "plan"` for read-only behaviour,
+ * because `plan` gates on the RESOLVED verdict: an engine built with `defaultAction: "allow"` still
+ * allows every unmatched call under `plan`.
+ *
+ * The rules array is stored by reference and walked afresh on every `evaluate` call. Mutating the
+ * array you passed in therefore changes the policy of a live engine; build a new engine when you
+ * want a policy change to be a deliberate, visible event.
+ */
+declare class PermissionEngine {
+    #private;
+    private readonly rules;
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
+    /**
+     * Evaluate a tool name (and optional arguments) against the rules. First
+     * match wins; falls back to the configured `defaultAction` (default `"ask"`,
+     * fail-closed) when no rule matches. #55 — a rule with `args` gates on the
+     * argument values, so the same tool name can resolve to different actions
+     * depending on what it is asked to do.
+     */
+    evaluate(toolName: string, args?: Record<string, unknown>, mode?: PermissionMode): PermissionAction;
+}
+
 /**
  * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
  * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
@@ -3091,6 +3295,9 @@ declare class Squad {
 }
 
 /**
+ * Owner: `internal/task/` (4 of 5 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public type contract for the Task observability registry (ADRs D361-D374).
  *
  * Tasks are an opt-in observability layer over async work in the SDK
@@ -3219,7 +3426,7 @@ interface TaskSubmitOptions {
      * throwing sink never breaks the task). The dedicated `Task.subscribe(id)`
      * channel is unaffected.
      */
-    readonly onRunEvent?: RunEventSink;
+    readonly onRunEvent?: RunEventSink$1;
 }
 /** Options shape for `TaskStore` factory (D364). */
 type TaskStoreOptions = {
@@ -3233,17 +3440,6 @@ interface TaskCancelResult {
     readonly cancelled: boolean;
     readonly alreadyTerminal: boolean;
 }
-/**
- * Validates a task ID against the public grammar + reserved prefixes.
- * Throws `InvalidTaskIdError` from `../errors.js` on rejection.
- *
- * Adapter callers (workflow/batch/cron) MUST set `allowReserved: true`
- * to register their own IDs; user-facing surfaces (`Task.submit`,
- * `agent.send({ task: { id } })`) leave it false.
- */
-declare function isValidTaskId(id: string, allowReserved: boolean): boolean;
-/** Re-exported for adapter implementations + tests. */
-declare const TASK_RESERVED_PREFIXES: readonly string[];
 
 /**
  * `Task` — observable async work registry (Adoption Roadmap gap #2,
@@ -3378,6 +3574,9 @@ interface ProviderCapabilities {
 }
 
 /**
+ * Owner: `internal/catalog/` (2 of 3 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Account-level user info returned by `Theokit.me()`.
  *
  * @public
@@ -3637,6 +3836,9 @@ declare class ToolError extends TheokitAgentError {
 }
 
 /**
+ * Owner: `src/` (1 of 1 importers). Derived from the import graph, not declared —
+ * `tests/lint/types-name-their-owner.test.ts` re-derives it.
+ *
  * Public types for ShareGPT trajectory export (ADR D139).
  *
  * Output format for fine-tuning datasets — consumed by HuggingFace, Axolotl,
@@ -3920,4 +4122,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type ApprovalDecision, type ApprovalInput, type ApprovalMode, type ApprovalOutcome, type ApprovalReason, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, type BlastRadiusDecision, type BlastRadiusInput, type BlastRadiusOutcome, type BlastRadiusReason, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, type BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, type CustomTool, type DeclaredAction, type DeclaredLayer, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, type EnvOptOut, type EnvReachabilityAudit, type EnvReachabilityInput, ErrorMetadata, EventBus, type EvictReason, GOAL_CONTINUATION_MARKER, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, GoalEvent, type GoalLoopAgent, GoalOptions, GoalResult, InlineSkill, JobQueue, type JobQueueOptions, JudgeCredentialError, type JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, type LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, type MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, type OTelSpan, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, type PermissionRule, Plugin, PluginsSettings, PreToolCallDecision, type Processor, Provider, type ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink$1 as RunEventSink, RunResult, type SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, SOVEREIGN_ENV_KEYS, Security, type SecurityFloorInput, type SessionMessage, type SessionMessagePart, type SessionScope, type ShareGptMessage, type ShareGptTrajectory, SkillReadTool, SkillsSettings, type SovereignEnvKey, Squad, type SquadOptions, type SquadRun, StreamObjectError, type StreamObjectEvent, type StreamObjectOptions, SystemPromptResolver, TASK_RESERVED_PREFIXES, Task, type TaskCancelResult, type TaskConfigureOptions, type TaskEvent, type TaskFilter, type TaskHandle, type TaskKind, type TaskState, type TaskStoreOptions, type TaskSubmitOptions, type TaskWorkContext, type TaskWorkFn, type TelemetryHandle, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, type ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, type WithBlastRadius, applyMode, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, decideApproval, describeAction, describeCredential, emitRunEvent, estimateTokens, evaluateBlastRadius, extractRawId, foldLayers, getPricingEntry, guardSessionDestruction, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withBlastRadius, withCwdMutex };