@compilr-dev/sdk 0.2.0 → 0.2.2

package/dist/agent.js

@@ -29,17 +29,27 @@ function toRunResult(raw) {
     };
 }
 /**
- * Build permission manager options from config
+ * Build permission manager options from config.
+ *
+ * When a PermissionCallback is provided:
+ * - defaultLevel is 'always' (tools auto-allowed unless rules say otherwise)
+ * - includeDefaults is true (agents library's built-in rules for dangerous tools)
+ * - Custom rules can be passed via permissionRules
+ *
+ * This matches the CLI pattern: everything allowed by default, only dangerous
+ * tools (bash, write_file, edit, etc.) require user approval.
  */
-function buildPermissions(permissions, presetDefault) {
+function buildPermissions(permissions, presetDefault, permissionRules, includeDefaultRules) {
     const mode = permissions ?? presetDefault ?? 'auto';
     if (mode === 'read-only') {
         return { defaultLevel: 'deny' };
     }
     if (typeof mode === 'function') {
         return {
-            defaultLevel: 'once',
+            defaultLevel: 'always',
             onPermissionRequest: mode,
+            rules: permissionRules,
+            includeDefaults: includeDefaultRules ?? true,
         };
     }
     // 'auto' — allow all tools
@@ -102,7 +112,7 @@ class CompilrAgentImpl {
             });
         }
         // Build agent config
-        const permissionsConfig = buildPermissions(config?.permissions, preset.defaultPermissions);
+        const permissionsConfig = buildPermissions(config?.permissions, preset.defaultPermissions, config?.permissionRules, config?.includeDefaultRules);
         const guardrailsConfig = buildGuardrails(config?.guardrails);
         this.agent = new Agent({
             provider,
@@ -114,6 +124,8 @@ class CompilrAgentImpl {
             permissions: {
                 defaultLevel: permissionsConfig.defaultLevel,
                 onPermissionRequest: permissionsConfig.onPermissionRequest,
+                rules: permissionsConfig.rules,
+                includeDefaults: permissionsConfig.includeDefaults,
             },
             guardrails: {
                 enabled: guardrailsConfig.enabled,

package/dist/config.d.ts

@@ -1,7 +1,7 @@
 /**
  * SDK configuration types
  */
-import type { LLMProvider, Message, Tool, HooksConfig, AnchorInput, AgentEvent, ToolExecutionResult } from '@compilr-dev/agents';
+import type { LLMProvider, Message, Tool, ToolPermission, HooksConfig, AnchorInput, AgentEvent, ToolExecutionResult } from '@compilr-dev/agents';
 import type { Preset } from './presets/types.js';
 /**
  * Supported provider types for auto-detection
@@ -128,6 +128,17 @@ export interface CompilrAgentConfig {
     tools?: ToolConfig;
     /** Permission mode. Default: 'auto' */
     permissions?: 'auto' | 'read-only' | PermissionCallback;
+    /**
+     * Tool-specific permission rules (e.g., bash='once', read_file='always').
+     * When omitted with a PermissionCallback, the agents library's built-in
+     * defaults are used (includeDefaults: true).
+     */
+    permissionRules?: ToolPermission[];
+    /**
+     * Whether to include the agents library's built-in default permission rules.
+     * Default: true when a PermissionCallback is provided, false otherwise.
+     */
+    includeDefaultRules?: boolean;
     /** Guardrail configuration. Default: true */
     guardrails?: boolean | GuardrailConfig;
     /** Lifecycle hooks */

package/dist/index.d.ts

@@ -59,5 +59,7 @@ export { STEP_ORDER, GUIDED_STEP_CRITERIA, getNextStep, isValidTransition, getSt
 export { platformSkills, designSkill, sketchSkill, prdSkill, refineSkill, refineItemSkill, architectureSkill, sessionNotesSkill, buildSkill, scaffoldSkill, } from './skills/index.js';
 export { defineTool, createSuccessResult, createErrorResult, mergeHooks, createLoggingHooks, createClaudeProvider, createOpenAIProvider, createGeminiNativeProvider, createOllamaProvider, createTogetherProvider, createGroqProvider, createFireworksProvider, createPerplexityProvider, createOpenRouterProvider, createMockProvider, MockProvider, Agent, ContextManager, DEFAULT_CONTEXT_CONFIG, createTaskTool, createSuggestTool, defaultAgentTypes, TOOL_SETS, BUILTIN_GUARDRAILS, TOOL_NAMES, getDefaultShellManager, builtinSkills, AnchorManager, MCPManager, AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 export type { Tool, HooksConfig, AgentEvent, Message, LLMProvider, AnchorInput, ToolExecutionResult, AgentRunResult, PermissionHandler, ToolPermission, AgentTypeConfig, GuardrailTriggeredHandler, BeforeLLMHookResult, BeforeToolHook, BeforeToolHookResult, AfterToolHook, AgentState, AgentConfig, SessionInfo, Anchor, AnchorScope, AnchorClearOptions, AnchorPriority, AnchorQueryOptions, FileAccessType, FileAccess, GuardrailResult, GuardrailContext, MCPClient, MCPToolDefinition, } from '@compilr-dev/agents';
+export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
+export type { PermissionRule, PermissionMode, PermissionLevel } from './permissions.js';
 export { readFileTool, writeFileTool, createBashTool, bashTool, bashOutputTool, killShellTool, grepTool, globTool, editTool, todoWriteTool, todoReadTool, createTodoTools, TodoStore, webFetchTool, suggestTool, } from '@compilr-dev/agents';
 export { gitStatusTool, gitDiffTool, gitLogTool, gitCommitTool, gitBranchTool, gitStashTool, gitBlameTool, gitFileHistoryTool, detectProjectTool, findProjectRootTool, runTestsTool, runLintTool, runBuildTool, runFormatTool, findDefinitionTool, findReferencesTool, findTodosTool, checkOutdatedTool, findVulnerabilitiesTool, analyzeTestCoverageTool, getFileStructureTool, getComplexityTool, allCodingTools, unifiedTools, } from '@compilr-dev/agents-coding';

package/dist/index.js

@@ -153,6 +153,10 @@ MCPManager,
 // Error types
 AgentError, ProviderError, ToolError, ToolTimeoutError, MaxIterationsError, AbortError, } from '@compilr-dev/agents';
 // =============================================================================
+// Shared Permission Defaults & Utilities
+// =============================================================================
+export { DEFAULT_PERMISSION_RULES, findMatchingRule, permissionModeLabel, permissionLevelLabel, } from './permissions.js';
+// =============================================================================
 // Individual Tool Re-exports (for consumers that build custom tool registries)
 // =============================================================================
 // Base tools from @compilr-dev/agents

package/dist/permissions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared permission types and defaults for CLI and Desktop.
+ *
+ * Both consumers define the same default rules and modes. This module
+ * provides a single source of truth so they stay in sync.
+ */
+import type { ToolPermission } from '@compilr-dev/agents';
+/**
+ * Permission level for a tool.
+ * Re-exported from agents for convenience.
+ */
+export type PermissionLevel = 'always' | 'session' | 'once' | 'deny';
+/**
+ * Extended permission rule with UI metadata.
+ * Extends ToolPermission with an isDefault flag so UIs can distinguish
+ * built-in rules from user-customized ones (default rules cannot be deleted).
+ */
+export interface PermissionRule extends ToolPermission {
+    /** True for built-in rules (cannot be deleted, only level can be changed) */
+    isDefault?: boolean;
+}
+/**
+ * Global permission mode controlling how the permission system behaves.
+ * - 'normal': Use rule-based checking (check each tool's configured level)
+ * - 'plan': Always prompt before any tool execution (ignores rules)
+ * - 'auto-accept': Allow everything without prompting
+ */
+export type PermissionMode = 'normal' | 'plan' | 'auto-accept';
+/**
+ * Default permission rules shared between CLI and Desktop.
+ *
+ * The model is "allow by default, restrict dangerous tools":
+ * - Read-only tools (read_file, glob, grep) → always allowed
+ * - Write/execute tools (bash, write_file, edit) → ask once per invocation
+ * - Git mutating tools (git_commit, git_branch) → ask once
+ * - Runner tools (run_tests, run_lint) → ask once
+ */
+export declare const DEFAULT_PERMISSION_RULES: PermissionRule[];
+/**
+ * Find the matching permission rule for a tool name.
+ * Checks exact match first, then wildcard patterns (e.g., git_* matches git_commit).
+ */
+export declare function findMatchingRule(rules: PermissionRule[], toolName: string): PermissionRule | null;
+/**
+ * Display label for a permission mode.
+ */
+export declare function permissionModeLabel(mode: PermissionMode): string;
+/**
+ * Display label for a permission level.
+ */
+export declare function permissionLevelLabel(level: PermissionLevel): string;

package/dist/permissions.js

@@ -0,0 +1,85 @@
+/**
+ * Shared permission types and defaults for CLI and Desktop.
+ *
+ * Both consumers define the same default rules and modes. This module
+ * provides a single source of truth so they stay in sync.
+ */
+// =============================================================================
+// Default Rules
+// =============================================================================
+/**
+ * Default permission rules shared between CLI and Desktop.
+ *
+ * The model is "allow by default, restrict dangerous tools":
+ * - Read-only tools (read_file, glob, grep) → always allowed
+ * - Write/execute tools (bash, write_file, edit) → ask once per invocation
+ * - Git mutating tools (git_commit, git_branch) → ask once
+ * - Runner tools (run_tests, run_lint) → ask once
+ */
+export const DEFAULT_PERMISSION_RULES = [
+    { toolName: 'bash', level: 'once', description: 'Execute shell commands', isDefault: true },
+    { toolName: 'write_file', level: 'once', description: 'Write/create files', isDefault: true },
+    { toolName: 'edit', level: 'once', description: 'Edit file contents', isDefault: true },
+    { toolName: 'git_commit', level: 'once', description: 'Create git commits', isDefault: true },
+    { toolName: 'git_branch', level: 'once', description: 'Create/delete branches', isDefault: true },
+    { toolName: 'run_tests', level: 'once', description: 'Run test suite', isDefault: true },
+    {
+        toolName: 'run_lint',
+        level: 'once',
+        description: 'Run linter (may auto-fix)',
+        isDefault: true,
+    },
+    { toolName: 'read_file', level: 'always', description: 'Read files', isDefault: true },
+    { toolName: 'glob', level: 'always', description: 'Find files by pattern', isDefault: true },
+    { toolName: 'grep', level: 'always', description: 'Search file contents', isDefault: true },
+];
+// =============================================================================
+// Utilities
+// =============================================================================
+/**
+ * Find the matching permission rule for a tool name.
+ * Checks exact match first, then wildcard patterns (e.g., git_* matches git_commit).
+ */
+export function findMatchingRule(rules, toolName) {
+    // Exact match first
+    const exact = rules.find((r) => r.toolName === toolName);
+    if (exact)
+        return exact;
+    // Wildcard match (e.g., git_* → /^git_.*$/)
+    for (const rule of rules) {
+        if (rule.toolName.includes('*')) {
+            const pattern = new RegExp('^' + rule.toolName.replace(/\*/g, '.*') + '$');
+            if (pattern.test(toolName))
+                return rule;
+        }
+    }
+    return null;
+}
+/**
+ * Display label for a permission mode.
+ */
+export function permissionModeLabel(mode) {
+    switch (mode) {
+        case 'normal':
+            return 'Normal';
+        case 'plan':
+            return 'Plan (ask for everything)';
+        case 'auto-accept':
+            return 'Auto-accept (no prompts)';
+    }
+}
+/**
+ * Display label for a permission level.
+ */
+export function permissionLevelLabel(level) {
+    switch (level) {
+        case 'always':
+            return 'Always allow';
+        case 'session':
+            return 'Ask once per session';
+        case 'once':
+            return 'Ask every time';
+        case 'deny':
+            return 'Always deny';
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compilr-dev/sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Universal agent runtime for building AI-powered applications",
   "type": "module",
   "main": "dist/index.js",