@theokit/sdk 2.4.0 → 2.5.0

package/dist/index.d.cts

@@ -1428,8 +1428,9 @@ declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateR
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
- * Evaluates a tool name against an ordered list of rules.
- * First matching rule wins; default is "allow" when no rule matches.
+ * Evaluates a tool name against an ordered list of rules. First matching rule
+ * wins; when no rule matches the `defaultAction` is returned (M7-4 — default
+ * `"allow"`, opt into default-deny via `{ defaultAction: "deny" }`).
  */
 type PermissionAction = "allow" | "deny" | "ask";
 interface PermissionRule {
@@ -1438,15 +1439,49 @@ interface PermissionRule {
     /** Action to take when rule matches. */
     action: PermissionAction;
 }
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /** Action when no rule matches. Default `"allow"` (backward-compatible). M7-4. */
+    readonly defaultAction?: PermissionAction;
+}
 declare class PermissionEngine {
     private readonly rules;
-    constructor(rules: PermissionRule[]);
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
     /**
-     * Evaluate a tool name against the rules. First match wins; default "allow".
+     * Evaluate a tool name against the rules. First match wins; falls back to the
+     * configured `defaultAction` (default `"allow"`) when no rule matches.
      */
     evaluate(toolName: string): PermissionAction;
 }
 
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * Resolver for the `"ask"` verdict. Returns a veto (`{block,message}`) to deny
+     * or `undefined` to allow. Default: fail-closed (block with "requires approval").
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/**
+ * Build a `general` plugin that vetoes tool calls per the engine's verdict.
+ * Register it on an agent's plugin manager (same as the ACP permission plugin).
+ */
+declare function createPermissionPlugin(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -2151,4 +2186,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, PermissionEngine, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionPluginOptions, type PermissionRule, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };

package/dist/index.d.ts

@@ -1428,8 +1428,9 @@ declare function migrateSqliteToLance(options: MigrateOptions): Promise<MigrateR
 /**
  * `PermissionEngine` — first-match permission rules for tool invocations.
  *
- * Evaluates a tool name against an ordered list of rules.
- * First matching rule wins; default is "allow" when no rule matches.
+ * Evaluates a tool name against an ordered list of rules. First matching rule
+ * wins; when no rule matches the `defaultAction` is returned (M7-4 — default
+ * `"allow"`, opt into default-deny via `{ defaultAction: "deny" }`).
  */
 type PermissionAction = "allow" | "deny" | "ask";
 interface PermissionRule {
@@ -1438,15 +1439,49 @@ interface PermissionRule {
     /** Action to take when rule matches. */
     action: PermissionAction;
 }
+/** Options for {@link PermissionEngine}. */
+interface PermissionEngineOptions {
+    /** Action when no rule matches. Default `"allow"` (backward-compatible). M7-4. */
+    readonly defaultAction?: PermissionAction;
+}
 declare class PermissionEngine {
     private readonly rules;
-    constructor(rules: PermissionRule[]);
+    private readonly defaultAction;
+    constructor(rules: PermissionRule[], options?: PermissionEngineOptions);
     /**
-     * Evaluate a tool name against the rules. First match wins; default "allow".
+     * Evaluate a tool name against the rules. First match wins; falls back to the
+     * configured `defaultAction` (default `"allow"`) when no rule matches.
      */
     evaluate(toolName: string): PermissionAction;
 }
 
+/**
+ * M7-5 — `createPermissionPlugin`: wire a {@link PermissionEngine} into the
+ * `definePlugin` `pre_tool_call` veto seam. This is the canonical exemplar that
+ * gives `PermissionEngine` a real caller (it was previously exported-but-unwired):
+ * on each tool call the engine's verdict maps to the veto contract —
+ * `"deny"` -> block, `"ask"` -> the caller's `onAsk` resolver (or block, fail-closed),
+ * `"allow"` -> pass.
+ *
+ * @public
+ */
+
+/** Options for {@link createPermissionPlugin}. */
+interface PermissionPluginOptions {
+    /** Plugin name (default `"permission-engine"`). */
+    readonly name?: string;
+    /**
+     * Resolver for the `"ask"` verdict. Returns a veto (`{block,message}`) to deny
+     * or `undefined` to allow. Default: fail-closed (block with "requires approval").
+     */
+    readonly onAsk?: (toolName: string) => PreToolCallDecision | undefined;
+}
+/**
+ * Build a `general` plugin that vetoes tool calls per the engine's verdict.
+ * Register it on an agent's plugin manager (same as the ACP permission plugin).
+ */
+declare function createPermissionPlugin(engine: PermissionEngine, opts?: PermissionPluginOptions): Plugin;
+
 /**
  * Public security namespace (T2.1, ADR D68).
  *
@@ -2151,4 +2186,4 @@ declare function toShareGptTrajectory(result: BatchResult, options?: {
     model?: string;
 }): ShareGptTrajectory | null;
 
-export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, PermissionEngine, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDefinition, type AgentFactory, AgentOperationOptions, AgentOptions, type AgentPromptResult, type AgentRegistryOptions, type BatchItem, type BatchOptions, type BatchProgress, type BatchResult, Budget, BudgetHandle, BudgetOptions, BudgetSnapshot, BudgetTracker, CloudOptions, ContextSettings, ConversationStorageAdapter, type CounterBudgetTrackerOptions, CustomTool, type DeepPartial, type DefineProviderOptions, type DefineToolSpec, type DreamingSweepOptions, type DreamingSweepResult, EventBus, type EvictReason, FileSystemConversationStorage, GenerateObjectError, type GenerateObjectOptions, type GenerateObjectResult, GetAgentOptions, GetRunOptions, type HookName, InMemoryConversationStorage, JobQueue, ListAgentsOptions, ListResult, ListRunsOptions, LiveAgentRegistry, LocalOptions, McpServerConfig, Memory, MemoryContext, MemoryId, MemoryProvider, MemorySettings, type MigrateOptions, type MigrateResult, type ModelListItem, type ModelParameterDefinition, ModelSelection, type ModelVariant, type PermissionAction, PermissionEngine, type PermissionEngineOptions, type PermissionPluginOptions, type PermissionRule, type Plugin, type PluginContext, PluginsSettings, type PostAssistantReplyContext, type PreToolCallContext, type PreToolCallDecision, type PreUserSendContext, type PreUserSendResult, type ProviderProfile, ProviderRoutingSettings, type ReplayHistoryOptions, Run, RunResult, SDKAgent, SDKAgentInfo, SDKMessage, type SDKModel, SDKProvider, type SDKRepository, type SDKUser, Security, type ShareGptMessage, type ShareGptTrajectory, SkillsSettings, type Squad, type SquadOptions, type SquadRun, StoredMessage, 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, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isValidTaskId, migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };

package/dist/index.js

@@ -18712,25 +18712,47 @@ async function migrateSqliteToLance2(options) {
 
 // src/permission-engine.ts
 var PermissionEngine = class {
-  constructor(rules) {
+  constructor(rules, options = {}) {
     this.rules = rules;
+    this.defaultAction = options.defaultAction ?? "allow";
   }
   rules;
+  defaultAction;
   /**
-   * Evaluate a tool name against the rules. First match wins; default "allow".
+   * Evaluate a tool name against the rules. First match wins; falls back to the
+   * configured `defaultAction` (default `"allow"`) when no rule matches.
    */
   evaluate(toolName) {
     for (const rule of this.rules) {
-      if (typeof rule.tool === "string") {
-        if (rule.tool === toolName) return rule.action;
-      } else {
-        if (rule.tool.test(toolName)) return rule.action;
-      }
+      const matches = typeof rule.tool === "string" ? rule.tool === toolName : rule.tool.test(toolName);
+      if (matches) return rule.action;
     }
-    return "allow";
+    return this.defaultAction;
   }
 };
 
+// src/permission-plugin.ts
+function createPermissionPlugin(engine, opts = {}) {
+  return definePlugin({
+    name: opts.name ?? "permission-engine",
+    version: "1.0.0",
+    kind: "general",
+    register(ctx) {
+      ctx.on("pre_tool_call", (rawCtx) => {
+        const { name } = rawCtx;
+        const action = engine.evaluate(name);
+        if (action === "deny") {
+          return { block: true, message: `denied by permission engine: ${name}` };
+        }
+        if (action === "ask") {
+          return opts.onAsk ? opts.onAsk(name) : { block: true, message: `requires approval: ${name}` };
+        }
+        return void 0;
+      });
+    }
+  });
+}
+
 // src/security.ts
 init_security();
 var Security = class {
@@ -19500,6 +19522,6 @@ function safeStringify2(v) {
   }
 }
 
-export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
+export { Agent, AgentBuilder, AgentDisposedError, AgentRunError, AuthenticationError, Budget, BudgetExceededError, ConfigurationError, Cron, EventBus, FileSystemConversationStorage, GenerateObjectError, InMemoryConversationStorage, IntegrationNotConnectedError, InvalidTaskIdError, JobQueue, Memory, MemoryAdapterError, NetworkError, PermissionEngine, RateLimitError, Security, StreamObjectError, Task, TaskNotFoundError, Theokit, TheokitAgentError, UnknownAgentError, UnsupportedBudgetOperationError, UnsupportedRunOperationError, UnsupportedTaskOperationError, UsageAccumulator, buildReplayHistory, chargeAndCheckThresholds, computeCost, createAgentFactory, createCounterBudgetTracker, createNoopMemoryProvider, createPermissionPlugin, createSquad, definePlugin, defineProvider, defineTool, extractRawId, getPricingEntry, inferApiMode, isTransientError, migrateSqliteToLance2 as migrateSqliteToLance, mkMemoryId, normalizeUsage, preflightCheck, toShareGptTrajectory, withCwdMutex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map