@theokit/sdk 4.44.0 → 4.45.0

package/dist/index.d.cts

@@ -1977,6 +1977,64 @@ declare class Security {
     static addPattern(re: RegExp): void;
 }
 
+/**
+ * Resolve a security-relevant setting across configuration layers, where a lower-trust layer may
+ * TIGHTEN it and never loosen it.
+ *
+ * Layered configuration usually resolves last-wins, and for the keys that decide confinement — a
+ * sandbox mode, an approval policy — last-wins is a hole. With plain precedence a project layer
+ * outranks the user's own file, so a cloned repository can hand itself the most permissive setting
+ * and the operator's global choice loses silently, at the moment the directory is opened. Nothing
+ * fails; the confinement is simply gone.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is generic: named layers may only move the value in the confining direction, while one
+ * designated layer — the operator's explicit flag — wins in both. The VOCABULARY is not: which
+ * values count as more permissive, what the layers are called, and which one is the operator's are
+ * all the consumer's, and are parameters.
+ *
+ * That distinction is what makes this extractable when a keypress router was not. Here the
+ * vocabulary is DATA — two lists and a name — so a second product supplies its own without
+ * inheriting the first's words. An interface shaped by one product's states would have given the
+ * second consumer something to route around.
+ *
+ * ## Why the override is not validated
+ *
+ * `override` is returned verbatim, even when it is outside `permissiveness`. Validating the
+ * operator's flag is the consumer's job: it owns the vocabulary, the error message and the exit
+ * code. Silently dropping an unrecognised flag would be worse than passing it through — the
+ * operator would see their explicit instruction ignored with no explanation.
+ *
+ * A value outside the vocabulary in a RESTRICTED layer is different and IS ignored: a typo in a
+ * repository's config must neither become the effective setting nor be treated as maximally
+ * permissive.
+ *
+ * @public
+ */
+/** @public */
+interface SecurityFloorInput {
+    /**
+     * The vocabulary, ordered from most confined to least. Index is permissiveness, so
+     * `["read-only", "workspace-write", "danger-full-access"]` says read-only confines the most.
+     */
+    readonly permissiveness: readonly string[];
+    /** Layers that may only tighten — typically anything a repository or environment can supply. */
+    readonly restricted: readonly string[];
+    /** The layer that wins outright in both directions — the operator's explicit flag. */
+    readonly override: string;
+    /**
+     * Values per layer. Layers absent from `restricted` are unconstrained, which is how a `user`
+     * layer loosens its own `defaults`.
+     */
+    readonly layers: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * @returns the resolved value, or `undefined` when no layer supplied one.
+ * @public
+ */
+declare function applySecurityFloor(input: SecurityFloorInput): string | undefined;
+
 /**
  * M3 #62 — scoped session state.
  *
@@ -2575,4 +2633,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-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 DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, 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, 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 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, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };
+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 DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, 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, 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, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, applySecurityFloor, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };

package/dist/index.d.ts

@@ -1977,6 +1977,64 @@ declare class Security {
     static addPattern(re: RegExp): void;
 }
 
+/**
+ * Resolve a security-relevant setting across configuration layers, where a lower-trust layer may
+ * TIGHTEN it and never loosen it.
+ *
+ * Layered configuration usually resolves last-wins, and for the keys that decide confinement — a
+ * sandbox mode, an approval policy — last-wins is a hole. With plain precedence a project layer
+ * outranks the user's own file, so a cloned repository can hand itself the most permissive setting
+ * and the operator's global choice loses silently, at the moment the directory is opened. Nothing
+ * fails; the confinement is simply gone.
+ *
+ * ## What is generic here, and what is not
+ *
+ * The RULE is generic: named layers may only move the value in the confining direction, while one
+ * designated layer — the operator's explicit flag — wins in both. The VOCABULARY is not: which
+ * values count as more permissive, what the layers are called, and which one is the operator's are
+ * all the consumer's, and are parameters.
+ *
+ * That distinction is what makes this extractable when a keypress router was not. Here the
+ * vocabulary is DATA — two lists and a name — so a second product supplies its own without
+ * inheriting the first's words. An interface shaped by one product's states would have given the
+ * second consumer something to route around.
+ *
+ * ## Why the override is not validated
+ *
+ * `override` is returned verbatim, even when it is outside `permissiveness`. Validating the
+ * operator's flag is the consumer's job: it owns the vocabulary, the error message and the exit
+ * code. Silently dropping an unrecognised flag would be worse than passing it through — the
+ * operator would see their explicit instruction ignored with no explanation.
+ *
+ * A value outside the vocabulary in a RESTRICTED layer is different and IS ignored: a typo in a
+ * repository's config must neither become the effective setting nor be treated as maximally
+ * permissive.
+ *
+ * @public
+ */
+/** @public */
+interface SecurityFloorInput {
+    /**
+     * The vocabulary, ordered from most confined to least. Index is permissiveness, so
+     * `["read-only", "workspace-write", "danger-full-access"]` says read-only confines the most.
+     */
+    readonly permissiveness: readonly string[];
+    /** Layers that may only tighten — typically anything a repository or environment can supply. */
+    readonly restricted: readonly string[];
+    /** The layer that wins outright in both directions — the operator's explicit flag. */
+    readonly override: string;
+    /**
+     * Values per layer. Layers absent from `restricted` are unconstrained, which is how a `user`
+     * layer loosens its own `defaults`.
+     */
+    readonly layers: Readonly<Record<string, string | undefined>>;
+}
+/**
+ * @returns the resolved value, or `undefined` when no layer supplied one.
+ * @public
+ */
+declare function applySecurityFloor(input: SecurityFloorInput): string | undefined;
+
 /**
  * M3 #62 — scoped session state.
  *
@@ -2575,4 +2633,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-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 DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, 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, 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 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, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };
+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 DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DiagnosticsSink, type DreamingSweepOptions, type DreamingSweepResult, 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, 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, UnicodeNormalizer, type UnicodeNormalizerOptions, UsageAccumulator, applySecurityFloor, chargeAndCheckThresholds, computeCost, createCounterBudgetTracker, estimateTokens, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, loadProjectEnv, migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, setDiagnosticsSink, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -1624,6 +1624,39 @@ var Security = class {
   }
 };
 
+// src/security-floor.ts
+function permissivenessOf(order, value) {
+  if (value === void 0) return -1;
+  return order.indexOf(value);
+}
+function baseline(input) {
+  const { restricted, override, layers } = input;
+  let value;
+  for (const [name, candidate] of Object.entries(layers)) {
+    if (name === override || restricted.includes(name)) continue;
+    if (candidate !== void 0) value = candidate;
+  }
+  return value;
+}
+function tightenOnly(input, start) {
+  const { permissiveness, restricted, layers } = input;
+  let resolved = start;
+  let ceiling = permissivenessOf(permissiveness, start);
+  for (const layer of restricted) {
+    const candidate = layers[layer];
+    if (candidate === void 0) continue;
+    const level = permissivenessOf(permissiveness, candidate);
+    if (level < 0) continue;
+    if (ceiling >= 0 && level > ceiling) continue;
+    resolved = candidate;
+    ceiling = level;
+  }
+  return resolved;
+}
+function applySecurityFloor(input) {
+  return input.layers[input.override] ?? tightenOnly(input, baseline(input));
+}
+
 // src/session-scope.ts
 function scopedConversationId(scope, id) {
   return `${scope}__${id}`;
@@ -2122,6 +2155,6 @@ function safeStringify(v) {
   }
 }
 
-export { AgentFactory, Budget, EventBus, JobQueue, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, SOVEREIGN_ENV_KEYS, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UnicodeNormalizer, applyMode, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, inferApiMode, loadProjectEnv, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory };
+export { AgentFactory, Budget, EventBus, JobQueue, Memory, NoopMemoryProvider, PermissionEngine, PermissionPlugin, Plugin, Provider, SOVEREIGN_ENV_KEYS, Security, Skill, SkillReadTool, Squad, Task, Theokit, TokenLimiter, UnicodeNormalizer, applyMode, applySecurityFloor, chargeAndCheckThresholds, createCounterBudgetTracker, estimateTokens, extractRawId, inferApiMode, loadProjectEnv, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeSchema, normalizeUsage, preflightCheck, runGoalLoop, scopedConversationId, sessionScopePrefix, toShareGptTrajectory };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map