@theokit/sdk 4.49.0 → 4.51.0

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).
  *
@@ -2019,6 +2177,87 @@ type MutableEnv = Record<string, string | undefined>;
  */
 declare function loadProjectEnv(env?: MutableEnv, load?: (() => void) | undefined): void;
 
+/**
+ * Decide which session artifacts may be deleted — and never delete them.
+ *
+ * This package creates session artifacts (transcripts, locks, temp files) and cleans up only what is
+ * in flight in the operation doing the cleaning: a lock it just released, a `.tmp` from a failed
+ * atomic write. Nothing collects the rest, so every consumer either writes its own collector or lets
+ * the directory grow without bound — and a hand-rolled collector on the path that deletes a user's
+ * transcript is the worst place for each product to learn the same lessons separately.
+ *
+ * ## Planning is not deleting, deliberately
+ *
+ * A function that decided AND deleted could not be tested without a filesystem, and the case that
+ * matters most — "we could not establish whether this session is live" — would have to be simulated
+ * rather than asserted. Here the decision is pure: the plan IS the dry run, and executing it is a
+ * separate act on a value someone can read first. That separation is the dry-run guarantee, rather
+ * than a flag that has to be remembered.
+ *
+ * ## The tri-state
+ *
+ * `keep`, `reap`, `undetermined`. An artifact whose liveness could not be established is never
+ * reaped and never quietly counted as dead. Collapsing "could not determine" into "not there" is how
+ * a collector deletes a session running on another machine, or behind a mount that answered slowly.
+ * The third bucket costs a branch and buys the only guarantee worth having on this path.
+ *
+ * @public
+ */
+
+/** Raised when a retention policy cannot be honoured as written. @public */
+declare class RetentionPolicyError extends TheokitAgentError {
+    readonly name = "RetentionPolicyError";
+}
+/** @public */
+interface ReapableArtifact {
+    readonly id: string;
+    /** Epoch milliseconds. Compared against an injected `nowMs`, never against a read clock. */
+    readonly lastModifiedMs: number;
+    /**
+     * Whether a writer still holds this artifact. `"unknown"` when the caller could not establish it —
+     * a stale lock behind a slow mount, a PID on another host — and it is honoured as a third answer
+     * rather than folded into `false`.
+     */
+    readonly live: boolean | "unknown";
+}
+/** @public */
+interface RetentionPolicy {
+    /** Artifacts strictly older than this are candidates. The boundary itself is kept. */
+    readonly maxAgeMs: number;
+    /**
+     * A FLOOR on how many artifacts survive: "you will always have your last N sessions". When
+     * liveness and the retention window already spare N or more, this changes nothing; when they
+     * spare fewer, the newest of the remainder are spared until the count reaches N.
+     *
+     * Undetermined artifacts do NOT count toward the floor. Their liveness was never established, so
+     * counting them would let a transient mount failure satisfy the floor with artifacts nobody
+     * confirmed exist as sessions — and quietly delete the ones that do.
+     */
+    readonly keepLast: number;
+}
+/** Why an artifact survived. @public */
+type KeepReason = "live" | "within-retention" | "keep-last";
+/** @public */
+interface KeptArtifact extends ReapableArtifact {
+    readonly reason: KeepReason;
+}
+/** @public */
+interface ReapPlan {
+    /** Safe to delete. Everything here was decided, not defaulted. */
+    readonly reap: readonly ReapableArtifact[];
+    readonly keep: readonly KeptArtifact[];
+    /** Liveness could not be established. Never deleted, never counted as kept. */
+    readonly undetermined: readonly ReapableArtifact[];
+}
+/** @public */
+interface ReapPlanInput {
+    readonly artifacts: readonly ReapableArtifact[];
+    readonly retention: RetentionPolicy;
+    /** Injected so the plan is reproducible and testable; this module never reads a clock. */
+    readonly nowMs: number;
+}
+declare function planReaping(input: ReapPlanInput): ReapPlan;
+
 /** The internal JSON-Schema shape the synthetic `output` tool consumes. */
 type NormalizedJsonSchema = Record<string, unknown>;
 /**
@@ -2154,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.
  *
@@ -2642,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.
@@ -2892,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, 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, 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, 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 };