@theokit/sdk 4.50.0 → 4.51.1

package/dist/index.d.cts

@@ -806,6 +806,122 @@ declare class AgentFactory {
     static create(common: Partial<AgentOptions>): AgentFactory;
 }
 
+/**
+ * Decide whether a tool call proceeds, and say WHY — as a typed signal rather than a tool result.
+ *
+ * When a veto is delivered as an ordinary tool result, the MODEL reads it as output: it sees a
+ * string, concludes the tool failed for some reason, and retries or works around it. A denial, an
+ * error, and a tool that legitimately returned the word "denied" become indistinguishable to
+ * everything downstream — including the surface that should be telling the user what happened.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is a precedence: an explicit per-tool decision outranks the mode, a convenience mode does
+ * not overturn an explicit refusal, and anything undecided falls to the mode. The VOCABULARY is not
+ * — which tools exist belongs to the product and arrives as data. Nothing here names one.
+ *
+ * Deliberately separate from the blast-radius policy: that one answers "what does this action
+ * reach", this one answers "who said yes". Keeping them apart is what lets a product gate on reach
+ * without re-implementing the mode ladder, and compose both where it needs to.
+ *
+ * @public
+ */
+/** What the operator chose for everything not decided per tool. @public */
+type ApprovalMode = "ask" | "never-ask" | "refuse-all";
+/** @public */
+type ApprovalOutcome = "allow" | "ask" | "deny";
+/** @public */
+type ApprovalReason = "explicitly-allowed" | "explicitly-denied" | "mode-ask" | "mode-never-ask" | "mode-refuse-all";
+/** @public */
+interface ApprovalInput {
+    readonly tool: string;
+    readonly mode: ApprovalMode;
+    /** Tools the operator allowed once and for all. */
+    readonly allowed?: readonly string[];
+    /** Tools the operator refused. Outranks `allowed` and every mode. */
+    readonly denied?: readonly string[];
+}
+/** @public */
+interface ApprovalDecision {
+    readonly outcome: ApprovalOutcome;
+    readonly reason: ApprovalReason;
+    /** The tool the decision was about, so a surface names it without re-deriving it. */
+    readonly tool: string;
+}
+/**
+ * @returns the outcome, why it was reached, and the tool it was about.
+ * @public
+ */
+declare function decideApproval(input: ApprovalInput): ApprovalDecision;
+
+/**
+ * Decide an action by what it REACHES and whether it can be undone — not by its name.
+ *
+ * A sandbox answers "which files may this process touch", and that is a different question from the
+ * one that decides whether an action is safe. A tool that drops a production database touches no
+ * file the sandbox cares about; a tool that lists pods reaches an entire cluster while writing
+ * nothing. Confinement covers the disk, not the reach.
+ *
+ * With nothing better available, every product gates on the tool's NAME: an allowlist of strings
+ * that says nothing about what the tool does, drifts the moment one is renamed, and cannot be
+ * reasoned about by anyone who did not write it. A guard each product re-implements is a guard some
+ * product forgets.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is: an action declares the scope it reaches and whether it is reversible, and a policy
+ * decides from those two facts plus what the operator granted. The VOCABULARY is not — which scopes
+ * exist ("cluster:prod", "billing-account", "the laptop") belongs to the product and arrives as
+ * data. Nothing in this module names a scope, the same way the security floor names no sandbox mode
+ * and the trust posture names no capability.
+ *
+ * ## Why the reason is part of the answer
+ *
+ * "The sandbox stopped this" and "you never granted reach to that scope" are different facts with
+ * different fixes, and an operator told the wrong one widens the wrong thing. So a decision carries
+ * WHY — the same reason a trust posture reports its `source` and a wiring record distinguishes
+ * withheld-by-trust from never-configured.
+ *
+ * @public
+ */
+/** What an action reaches, and whether it can be taken back. @public */
+interface DeclaredAction {
+    /**
+     * The product's name for what this action reaches. An empty string is treated as UNDECLARED and
+     * refused: a tool that forgot to declare is not a tool that reaches nothing.
+     */
+    readonly scope: string;
+    /**
+     * Whether the action can be undone. Reversible actions inside a granted scope proceed;
+     * irreversible ones ask, because granting reach is not granting destruction.
+     */
+    readonly reversible: boolean;
+}
+/** @public */
+interface BlastRadiusInput {
+    readonly action: DeclaredAction;
+    /** Scopes the operator granted reach to. Empty grants nothing — never everything. */
+    readonly granted: readonly string[];
+    /** Scopes where the operator pre-approved irreversible actions, so an unattended run can work. */
+    readonly irreversibleAllowed?: readonly string[];
+}
+/** @public */
+type BlastRadiusOutcome = "allow" | "require-approval" | "refuse";
+/** Why the decision came out that way. Rendered to the operator and read by an audit. @public */
+type BlastRadiusReason = "within-granted-scope" | "irreversible" | "scope-not-granted" | "scope-undeclared";
+/** @public */
+interface BlastRadiusDecision {
+    readonly outcome: BlastRadiusOutcome;
+    readonly reason: BlastRadiusReason;
+    /** The scope the decision was made about, so a surface can name it without re-deriving it. */
+    readonly scope: string;
+}
+/**
+ * @returns the outcome with the reason and the scope it was decided on.
+ * @public
+ */
+declare function evaluateBlastRadius(input: BlastRadiusInput): BlastRadiusDecision;
+
 /**
  * computeCost — apply pricing entries to a TokenUsage and produce a
  * CostBreakdown (ADRs D377, D378).
@@ -1067,6 +1183,48 @@ declare class UnicodeNormalizer {
     static create(opts?: UnicodeNormalizerOptions): Processor;
 }
 
+/**
+ * Report whether a credential resolved — never what it is.
+ *
+ * Every agent product grows a "why can't I use this model?" surface: a doctor command, a status
+ * panel, a startup diagnostic. Each needs to know whether a credential resolved, and each is one
+ * careless line from printing it. The line is careless precisely because it is convenient — the
+ * value is right there, and whoever is debugging a routing problem wants to see it.
+ *
+ * So presence-only is the DEFAULT here rather than each consumer's discipline. Discipline is what
+ * every product has until the day it does not, and a leaked key is not a defect anyone can withdraw.
+ *
+ * ## Why a fingerprint and not a prefix
+ *
+ * A report has to be actionable: two people asking "is it the same key?" need something to compare.
+ * The convenient answer — the first eight characters — is still the secret, and it is enough to
+ * identify a key in a breach corpus. A hash is not.
+ *
+ * @public
+ */
+/** @public */
+interface CredentialInput {
+    /** The product's name for the provider. This module never knows one of its own. */
+    readonly provider: string;
+    /** The resolved secret, or `undefined`/empty when nothing resolved. */
+    readonly value: string | undefined;
+    /** Where it came from, in the product's vocabulary — `env`, `file`, `keychain`, `oauth`. */
+    readonly source: string;
+}
+/** @public */
+interface CredentialReport {
+    readonly provider: string;
+    readonly present: boolean;
+    readonly source: string;
+    /** Eight hex characters of a hash. Absent when no credential resolved. Never a prefix. */
+    readonly fingerprint?: string;
+}
+/**
+ * @returns a report safe to log, render and attach to a support bundle.
+ * @public
+ */
+declare function describeCredential(input: CredentialInput): CredentialReport;
+
 /**
  * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
  *
@@ -2235,6 +2393,51 @@ interface SecurityFloorInput {
  */
 declare function applySecurityFloor(input: SecurityFloorInput): string | undefined;
 
+/**
+ * Refuse to destroy a session another process is still writing.
+ *
+ * Every agent product that lets a user delete or overwrite a session needs this, and the failure is
+ * unrecoverable in the worst way: a transcript removed underneath a running session takes with it
+ * everything that session had not flushed, and nothing errors. The user sees a successful delete.
+ *
+ * ## The ordering is the point
+ *
+ * The check runs BEFORE anything is mutated. Removing a registry entry and then refusing leaves a
+ * session that can be neither opened nor deleted — worse than either outcome on its own. So this is
+ * a function the caller passes through rather than a flag it may consult afterwards: the throw is
+ * what stops the mutation, and there is no way to read the answer and forget to act on it.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is: a session declared live is not destroyable, and refusing says which one and why. The
+ * VOCABULARY is not — how a product decides liveness (a pointer file, the newest transcript, a
+ * lease, an active registry entry) is its own. Nothing here touches a filesystem.
+ *
+ * @public
+ */
+
+/** Why the destruction was refused. @public */
+type LiveSessionReason = "session-is-live" | "liveness-undetermined";
+/** @public */
+declare class LiveSessionError extends TheokitAgentError {
+    readonly name = "LiveSessionError";
+    readonly sessionId: string;
+    readonly reason: LiveSessionReason;
+    constructor(sessionId: string, reason: LiveSessionReason);
+}
+/**
+ * Throw unless `sessionId` is safe to destroy.
+ *
+ * @param live - the sessions the product declares live, or `undefined` when it could not tell.
+ *   The distinction is load-bearing: an EMPTY set is a legitimate answer (nothing is open), while
+ *   `undefined` refuses. A product that swallowed a read error and returned `[]` would hand this
+ *   guard the one input that disables it entirely, on exactly the path that destroys data.
+ * @throws LiveSessionError naming the session and the reason — "close that session" and "the guard
+ *   could not read" have different fixes, and conflating them sends the user to close nothing.
+ * @public
+ */
+declare function guardSessionDestruction(sessionId: string, live: readonly string[] | undefined): void;
+
 /**
  * M3 #62 — scoped session state.
  *
@@ -2723,6 +2926,41 @@ declare class Theokit {
     };
 }
 
+/**
+ * Attach a blast-radius declaration to a tool, so the approval layer gates on what the tool DOES.
+ *
+ * Without this the only key available to a policy is the tool's NAME, which says nothing about the
+ * action, drifts the moment a tool is renamed, and cannot be reviewed by anyone who did not write
+ * it. `delete_namespace` and `list_pods` differ by a word.
+ *
+ * ## Why a wrapper rather than a field on the input schema
+ *
+ * `inputSchema` is what the MODEL sees. Blast radius is not for the model — it is for the approval
+ * layer — and putting it there would leak policy into the prompt and let a model-authored argument
+ * influence its own gate. The declaration rides alongside the tool instead, under a symbol so it
+ * cannot collide with a tool's own properties or be serialised into a prompt by accident.
+ *
+ * @public
+ */
+
+/** @public */
+type WithBlastRadius<T> = T & {
+    readonly [DECLARED]?: DeclaredAction;
+};
+/**
+ * @returns the same tool, with its action declared. The tool is not otherwise altered — the model
+ *   must see exactly what it saw before.
+ * @public
+ */
+declare function withBlastRadius<T extends object>(tool: T, action: DeclaredAction): WithBlastRadius<T>;
+/**
+ * @returns the declared action, or `undefined` when the tool never declared one — NOT an empty
+ *   action. "Never declared" and "declared as reaching nothing" are different facts, and collapsing
+ *   them is how an unreviewed tool passes as harmless.
+ * @public
+ */
+declare function describeAction(tool: object): DeclaredAction | undefined;
+
 /**
  * SE7 — `ToolError`: thrown FROM a tool `handler` to report a failure back to
  * the model with structured content (text and/or an image), not just a string.
@@ -2973,4 +3211,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, 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, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, 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, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, 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, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, 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 };

package/dist/index.d.ts

@@ -806,6 +806,122 @@ declare class AgentFactory {
     static create(common: Partial<AgentOptions>): AgentFactory;
 }
 
+/**
+ * Decide whether a tool call proceeds, and say WHY — as a typed signal rather than a tool result.
+ *
+ * When a veto is delivered as an ordinary tool result, the MODEL reads it as output: it sees a
+ * string, concludes the tool failed for some reason, and retries or works around it. A denial, an
+ * error, and a tool that legitimately returned the word "denied" become indistinguishable to
+ * everything downstream — including the surface that should be telling the user what happened.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is a precedence: an explicit per-tool decision outranks the mode, a convenience mode does
+ * not overturn an explicit refusal, and anything undecided falls to the mode. The VOCABULARY is not
+ * — which tools exist belongs to the product and arrives as data. Nothing here names one.
+ *
+ * Deliberately separate from the blast-radius policy: that one answers "what does this action
+ * reach", this one answers "who said yes". Keeping them apart is what lets a product gate on reach
+ * without re-implementing the mode ladder, and compose both where it needs to.
+ *
+ * @public
+ */
+/** What the operator chose for everything not decided per tool. @public */
+type ApprovalMode = "ask" | "never-ask" | "refuse-all";
+/** @public */
+type ApprovalOutcome = "allow" | "ask" | "deny";
+/** @public */
+type ApprovalReason = "explicitly-allowed" | "explicitly-denied" | "mode-ask" | "mode-never-ask" | "mode-refuse-all";
+/** @public */
+interface ApprovalInput {
+    readonly tool: string;
+    readonly mode: ApprovalMode;
+    /** Tools the operator allowed once and for all. */
+    readonly allowed?: readonly string[];
+    /** Tools the operator refused. Outranks `allowed` and every mode. */
+    readonly denied?: readonly string[];
+}
+/** @public */
+interface ApprovalDecision {
+    readonly outcome: ApprovalOutcome;
+    readonly reason: ApprovalReason;
+    /** The tool the decision was about, so a surface names it without re-deriving it. */
+    readonly tool: string;
+}
+/**
+ * @returns the outcome, why it was reached, and the tool it was about.
+ * @public
+ */
+declare function decideApproval(input: ApprovalInput): ApprovalDecision;
+
+/**
+ * Decide an action by what it REACHES and whether it can be undone — not by its name.
+ *
+ * A sandbox answers "which files may this process touch", and that is a different question from the
+ * one that decides whether an action is safe. A tool that drops a production database touches no
+ * file the sandbox cares about; a tool that lists pods reaches an entire cluster while writing
+ * nothing. Confinement covers the disk, not the reach.
+ *
+ * With nothing better available, every product gates on the tool's NAME: an allowlist of strings
+ * that says nothing about what the tool does, drifts the moment one is renamed, and cannot be
+ * reasoned about by anyone who did not write it. A guard each product re-implements is a guard some
+ * product forgets.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is: an action declares the scope it reaches and whether it is reversible, and a policy
+ * decides from those two facts plus what the operator granted. The VOCABULARY is not — which scopes
+ * exist ("cluster:prod", "billing-account", "the laptop") belongs to the product and arrives as
+ * data. Nothing in this module names a scope, the same way the security floor names no sandbox mode
+ * and the trust posture names no capability.
+ *
+ * ## Why the reason is part of the answer
+ *
+ * "The sandbox stopped this" and "you never granted reach to that scope" are different facts with
+ * different fixes, and an operator told the wrong one widens the wrong thing. So a decision carries
+ * WHY — the same reason a trust posture reports its `source` and a wiring record distinguishes
+ * withheld-by-trust from never-configured.
+ *
+ * @public
+ */
+/** What an action reaches, and whether it can be taken back. @public */
+interface DeclaredAction {
+    /**
+     * The product's name for what this action reaches. An empty string is treated as UNDECLARED and
+     * refused: a tool that forgot to declare is not a tool that reaches nothing.
+     */
+    readonly scope: string;
+    /**
+     * Whether the action can be undone. Reversible actions inside a granted scope proceed;
+     * irreversible ones ask, because granting reach is not granting destruction.
+     */
+    readonly reversible: boolean;
+}
+/** @public */
+interface BlastRadiusInput {
+    readonly action: DeclaredAction;
+    /** Scopes the operator granted reach to. Empty grants nothing — never everything. */
+    readonly granted: readonly string[];
+    /** Scopes where the operator pre-approved irreversible actions, so an unattended run can work. */
+    readonly irreversibleAllowed?: readonly string[];
+}
+/** @public */
+type BlastRadiusOutcome = "allow" | "require-approval" | "refuse";
+/** Why the decision came out that way. Rendered to the operator and read by an audit. @public */
+type BlastRadiusReason = "within-granted-scope" | "irreversible" | "scope-not-granted" | "scope-undeclared";
+/** @public */
+interface BlastRadiusDecision {
+    readonly outcome: BlastRadiusOutcome;
+    readonly reason: BlastRadiusReason;
+    /** The scope the decision was made about, so a surface can name it without re-deriving it. */
+    readonly scope: string;
+}
+/**
+ * @returns the outcome with the reason and the scope it was decided on.
+ * @public
+ */
+declare function evaluateBlastRadius(input: BlastRadiusInput): BlastRadiusDecision;
+
 /**
  * computeCost — apply pricing entries to a TokenUsage and produce a
  * CostBreakdown (ADRs D377, D378).
@@ -1067,6 +1183,48 @@ declare class UnicodeNormalizer {
     static create(opts?: UnicodeNormalizerOptions): Processor;
 }
 
+/**
+ * Report whether a credential resolved — never what it is.
+ *
+ * Every agent product grows a "why can't I use this model?" surface: a doctor command, a status
+ * panel, a startup diagnostic. Each needs to know whether a credential resolved, and each is one
+ * careless line from printing it. The line is careless precisely because it is convenient — the
+ * value is right there, and whoever is debugging a routing problem wants to see it.
+ *
+ * So presence-only is the DEFAULT here rather than each consumer's discipline. Discipline is what
+ * every product has until the day it does not, and a leaked key is not a defect anyone can withdraw.
+ *
+ * ## Why a fingerprint and not a prefix
+ *
+ * A report has to be actionable: two people asking "is it the same key?" need something to compare.
+ * The convenient answer — the first eight characters — is still the secret, and it is enough to
+ * identify a key in a breach corpus. A hash is not.
+ *
+ * @public
+ */
+/** @public */
+interface CredentialInput {
+    /** The product's name for the provider. This module never knows one of its own. */
+    readonly provider: string;
+    /** The resolved secret, or `undefined`/empty when nothing resolved. */
+    readonly value: string | undefined;
+    /** Where it came from, in the product's vocabulary — `env`, `file`, `keychain`, `oauth`. */
+    readonly source: string;
+}
+/** @public */
+interface CredentialReport {
+    readonly provider: string;
+    readonly present: boolean;
+    readonly source: string;
+    /** Eight hex characters of a hash. Absent when no credential resolved. Never a prefix. */
+    readonly fingerprint?: string;
+}
+/**
+ * @returns a report safe to log, render and attach to a support bundle.
+ * @public
+ */
+declare function describeCredential(input: CredentialInput): CredentialReport;
+
 /**
  * Plugin contract — RUNTIME value + type re-exports (T1.1, ADRs D97-D101).
  *
@@ -2235,6 +2393,51 @@ interface SecurityFloorInput {
  */
 declare function applySecurityFloor(input: SecurityFloorInput): string | undefined;
 
+/**
+ * Refuse to destroy a session another process is still writing.
+ *
+ * Every agent product that lets a user delete or overwrite a session needs this, and the failure is
+ * unrecoverable in the worst way: a transcript removed underneath a running session takes with it
+ * everything that session had not flushed, and nothing errors. The user sees a successful delete.
+ *
+ * ## The ordering is the point
+ *
+ * The check runs BEFORE anything is mutated. Removing a registry entry and then refusing leaves a
+ * session that can be neither opened nor deleted — worse than either outcome on its own. So this is
+ * a function the caller passes through rather than a flag it may consult afterwards: the throw is
+ * what stops the mutation, and there is no way to read the answer and forget to act on it.
+ *
+ * ## What is generic, and what is not
+ *
+ * The RULE is: a session declared live is not destroyable, and refusing says which one and why. The
+ * VOCABULARY is not — how a product decides liveness (a pointer file, the newest transcript, a
+ * lease, an active registry entry) is its own. Nothing here touches a filesystem.
+ *
+ * @public
+ */
+
+/** Why the destruction was refused. @public */
+type LiveSessionReason = "session-is-live" | "liveness-undetermined";
+/** @public */
+declare class LiveSessionError extends TheokitAgentError {
+    readonly name = "LiveSessionError";
+    readonly sessionId: string;
+    readonly reason: LiveSessionReason;
+    constructor(sessionId: string, reason: LiveSessionReason);
+}
+/**
+ * Throw unless `sessionId` is safe to destroy.
+ *
+ * @param live - the sessions the product declares live, or `undefined` when it could not tell.
+ *   The distinction is load-bearing: an EMPTY set is a legitimate answer (nothing is open), while
+ *   `undefined` refuses. A product that swallowed a read error and returned `[]` would hand this
+ *   guard the one input that disables it entirely, on exactly the path that destroys data.
+ * @throws LiveSessionError naming the session and the reason — "close that session" and "the guard
+ *   could not read" have different fixes, and conflating them sends the user to close nothing.
+ * @public
+ */
+declare function guardSessionDestruction(sessionId: string, live: readonly string[] | undefined): void;
+
 /**
  * M3 #62 — scoped session state.
  *
@@ -2723,6 +2926,41 @@ declare class Theokit {
     };
 }
 
+/**
+ * Attach a blast-radius declaration to a tool, so the approval layer gates on what the tool DOES.
+ *
+ * Without this the only key available to a policy is the tool's NAME, which says nothing about the
+ * action, drifts the moment a tool is renamed, and cannot be reviewed by anyone who did not write
+ * it. `delete_namespace` and `list_pods` differ by a word.
+ *
+ * ## Why a wrapper rather than a field on the input schema
+ *
+ * `inputSchema` is what the MODEL sees. Blast radius is not for the model — it is for the approval
+ * layer — and putting it there would leak policy into the prompt and let a model-authored argument
+ * influence its own gate. The declaration rides alongside the tool instead, under a symbol so it
+ * cannot collide with a tool's own properties or be serialised into a prompt by accident.
+ *
+ * @public
+ */
+
+/** @public */
+type WithBlastRadius<T> = T & {
+    readonly [DECLARED]?: DeclaredAction;
+};
+/**
+ * @returns the same tool, with its action declared. The tool is not otherwise altered — the model
+ *   must see exactly what it saw before.
+ * @public
+ */
+declare function withBlastRadius<T extends object>(tool: T, action: DeclaredAction): WithBlastRadius<T>;
+/**
+ * @returns the declared action, or `undefined` when the tool never declared one — NOT an empty
+ *   action. "Never declared" and "declared as reaching nothing" are different facts, and collapsing
+ *   them is how an unreviewed tool passes as harmless.
+ * @public
+ */
+declare function describeAction(tool: object): DeclaredAction | undefined;
+
 /**
  * SE7 — `ToolError`: thrown FROM a tool `handler` to report a failure back to
  * the model with structured content (text and/or an image), not just a string.
@@ -2973,4 +3211,4 @@ interface WiringRecordInput<K extends string> {
  */
 declare function recordWiring<K extends string>(input: WiringRecordInput<K>): Readonly<Record<K, WiredEntity>>;
 
-export { Agent, AgentBuilder, AgentDefinition, AgentDescription, AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, CustomTool, 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, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, ToolResultContentBlock, type TrustLevel, type TrustPosture, type TrustPostureInput, type TrustSource, UngatedCapabilityError, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, type WiredEntity, type WiringRecordInput, applySecurityFloor, auditEnvReachability, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, foldLayers, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, planReaping, preflightCheck, recordWiring, resolveTrustPosture, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, verifyLayerOrdering, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, 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, BudgetTracker, CloudOptions, ContextSettings, type CounterBudgetTrackerOptions, type CredentialInput, type CredentialReport, 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, JudgeResult, type KeepReason, type KeptArtifact, LayerOrderError, type LayerValues, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LiveSessionError, type LiveSessionReason, LocalOptions, McpServerConfig, Memory, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, NoopMemoryProvider, type NormalizedJsonSchema, PermissionEngine, type PermissionGate, type PermissionGateContext, type PermissionGateDecision, PermissionMode, PermissionPlugin, type PermissionPluginOptions, Plugin, PluginsSettings, PreToolCallDecision, Processor, Provider, ProviderProfile, ProviderRoutingSettings, type ReapPlan, type ReapPlanInput, type ReapableArtifact, type RetentionPolicy, RetentionPolicyError, Run, RunEventSink, RunResult, 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, Theokit, TheokitAgentError, type TheokitRequestOptions, TokenLimiter, type TokenLimiterOptions, Tool, ToolError, 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 };