Tool Permissions

┌──────────────────────────────────────────────────────────────┐
│  1. USER RULES PRE-CHECK (highest priority, FINAL)           │
│     Per-user persistent rules with argument conditions.       │
│     When matched: result is FINAL, no further evaluation.     │
│     Specificity-based: more conditions > fewer conditions.    │
├──────────────────────────────────────────────────────────────┤
│  2. PARENT DELEGATION PRE-CHECK (orchestrator workers)       │
│     Parent deny is FINAL — worker cannot override.            │
│     Parent allow does NOT skip worker restrictions.           │
├──────────────────────────────────────────────────────────────┤
│  3. POLICY CHAIN (composable policies)                       │
│     Deny short-circuits immediately.                          │
│     Allow is remembered but does NOT short-circuit.           │
│     All abstain → defaultVerdict (default: 'deny').           │
│                                                              │
│     If deny + needsApproval → APPROVAL FLOW                 │
│     → onApprovalRequired callback                            │
│     → optional persistent rule creation                      │
└──────────────────────────────────────────────────────────────┘

PermissionPolicyManager.check(context):
  1. UserPermissionRulesEngine.evaluate()
     → allow? → DONE (skip chain entirely)
     → deny?  → DONE (skip chain entirely)
     → ask?   → approval dialog
     → no match → fall through

  2. Parent delegation (if orchestrator worker)
     → parent deny → DONE
     → parent allow → continue

  3. PolicyChain.evaluate()
     → BlocklistPolicy (pri 5) → AllowlistPolicy (pri 10) → RateLimitPolicy (pri 20)
     → RolePolicy (pri 30) → PathRestrictionPolicy (pri 50) → BashFilterPolicy (pri 50)
     → UrlAllowlistPolicy (pri 50) → SessionApprovalPolicy (pri 90)

  4. If deny + needsApproval → onApprovalRequired callback
     → approved? → cache approval, optionally create persistent rule
     → denied? → optionally create persistent deny rule

import { Agent, Connector, Vendor } from 'oneringai';

Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// No permissions config — uses DEFAULT_ALLOWLIST.
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  tools: [readFile, writeFile, bash],
});
// read_file: auto-allowed (in DEFAULT_ALLOWLIST)
// write_file: approval required; rejected because no callback is configured
// bash: approval required on every call; rejected for the same reason

import { Agent } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    // Allowlist is auto-merged with DEFAULT_ALLOWLIST
    allowlist: ['my_safe_tool'],
    blocklist: ['dangerous_tool'],

    // Approval callback — invoked when a tool needs user approval
    onApprovalRequired: async (ctx) => {
      console.log(`Tool '${ctx.toolName}' needs approval. Args:`, ctx.args);
      // In a real app, show a UI dialog
      return { approved: true, scope: 'session' };
    },

  },
});

interface UserPermissionRule {
  /** Unique rule ID (UUID) */
  id: string;

  /** Tool name this rule applies to. Use '*' for all tools. */
  toolName: string;

  /** What to do when this rule matches */
  action: 'allow' | 'deny' | 'ask';

  /**
   * Argument conditions (optional). ALL conditions must match (AND logic).
   * If empty/omitted, rule applies to ALL calls of this tool (blanket rule).
   */
  conditions?: ArgumentCondition[];

  /**
   * If true, this rule is absolute — more specific rules CANNOT override it.
   * "Allow bash unconditionally" means even a "bash + rm -rf → ask" rule is ignored.
   * @default false
   */
  unconditional?: boolean;

  /** Whether this rule is active */
  enabled: boolean;

  /** Human-readable description (shown in settings UI) */
  description?: string;

  /** How this rule was created */
  createdBy: 'user' | 'approval_dialog' | 'admin' | 'system';

  /** ISO timestamp of creation */
  createdAt: string;

  /** ISO timestamp of last update */
  updatedAt: string;

  /** Optional expiry (ISO timestamp). Null/undefined = never expires. */
  expiresAt?: string | null;
}

interface ArgumentCondition {
  /** Argument name to inspect (e.g., 'command', 'path', 'url') */
  argName: string;

  /** Comparison operator */
  operator: ConditionOperator;

  /** Value to compare against. For 'matches'/'not_matches', a regex string. */
  value: string;

  /** Case-insensitive comparison. @default true */
  ignoreCase?: boolean;
}

type ConditionOperator =
  | 'starts_with'    // value starts with the given string
  | 'not_starts_with'
  | 'contains'       // value contains the given string
  | 'not_contains'
  | 'equals'         // exact equality
  | 'not_equals'
  | 'matches'        // regex match
  | 'not_matches';   // regex negation

// Allow bash only for npm commands
{ argName: 'command', operator: 'starts_with', value: 'npm' }

// Deny commands containing 'sudo'
{ argName: 'command', operator: 'contains', value: 'sudo' }

// Allow write_file only for .ts files
{ argName: 'path', operator: 'matches', value: '\\.ts$' }

// Deny web_fetch for non-HTTPS URLs
{ argName: 'url', operator: 'not_starts_with', value: 'https://' }

// Allow edit_file only for a specific file
{ argName: 'file_path', operator: 'equals', value: '/workspace/config.json' }

// Deny bash commands matching dangerous patterns
{ argName: 'command', operator: 'not_matches', value: 'rm\\s+-rf|dd\\s+if=|mkfs' }

// Example: these rules coexist without conflict
const rules: UserPermissionRule[] = [
  // Blanket: allow bash by default (specificity: 0)
  { id: '1', toolName: 'bash', action: 'allow', enabled: true,
    createdBy: 'user', createdAt: '...', updatedAt: '...' },

  // Conditional: ask before rm commands (specificity: 1, overrides blanket)
  { id: '2', toolName: 'bash', action: 'ask',
    conditions: [{ argName: 'command', operator: 'contains', value: 'rm' }],
    enabled: true, createdBy: 'user', createdAt: '...', updatedAt: '...' },

  // More specific: deny rm -rf (specificity: 2, overrides the 'ask' above)
  { id: '3', toolName: 'bash', action: 'deny',
    conditions: [
      { argName: 'command', operator: 'contains', value: 'rm' },
      { argName: 'command', operator: 'contains', value: '-rf' },
    ],
    enabled: true, createdBy: 'user', createdAt: '...', updatedAt: '...' },
];

// Deny all MCP tools
{
  id: '1', toolName: '*', action: 'deny',
  conditions: [{ argName: '__toolSource', operator: 'starts_with', value: 'mcp' }],
  enabled: true, createdBy: 'admin', createdAt: '...', updatedAt: '...',
}

// Allow only filesystem category tools
{
  id: '2', toolName: '*', action: 'allow',
  conditions: [{ argName: '__toolCategory', operator: 'equals', value: 'filesystem' }],
  enabled: true, createdBy: 'admin', createdAt: '...', updatedAt: '...',
}

// Block all desktop tools
{
  id: '3', toolName: '*', action: 'deny',
  conditions: [{ argName: '__toolCategory', operator: 'equals', value: 'desktop' }],
  enabled: true, createdBy: 'user', createdAt: '...', updatedAt: '...',
}

const engine = agent.policyManager.userRules;

// Add a rule
await engine.addRule({
  id: crypto.randomUUID(),
  toolName: 'bash',
  action: 'ask',
  conditions: [{ argName: 'command', operator: 'contains', value: 'rm' }],
  enabled: true,
  description: 'Ask before any rm commands',
  createdBy: 'user',
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
}, userId);

// Update a rule
await engine.updateRule(ruleId, { action: 'deny' }, userId);

// Remove a rule
await engine.removeRule(ruleId, userId);

// Get all rules
const allRules = engine.getRules();

// Get rules for a specific tool
const bashRules = engine.getRulesForTool('bash');

// Get a single rule by ID
const rule = engine.getRule(ruleId);

// Enable/disable a rule
await engine.enableRule(ruleId, userId);
await engine.disableRule(ruleId, userId);

import type { ApprovalRequestContext, ApprovalDecision } from 'oneringai';

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    onApprovalRequired: async (ctx: ApprovalRequestContext): Promise<ApprovalDecision> => {
      // ctx contains rich context for the approval dialog
      console.log(`Tool: ${ctx.toolName}`);
      console.log(`Risk level: ${ctx.riskLevel}`);
      console.log(`Arguments:`, ctx.args);
      console.log(`Reason: ${ctx.decision.reason}`);
      console.log(`Policy: ${ctx.decision.policyName}`);

      if (ctx.approvalMessage) {
        console.log(`Message: ${ctx.approvalMessage}`);
      }
      if (ctx.sensitiveArgs) {
        console.log(`Sensitive args: ${ctx.sensitiveArgs.join(', ')}`);
      }

      // Show your UI dialog here...
      const userChoice = await showApprovalDialog(ctx);

      if (userChoice === 'allow_once') {
        return { approved: true, scope: 'once' };
      }

      if (userChoice === 'allow_session') {
        return { approved: true, scope: 'session' };
      }

      if (userChoice === 'always_allow') {
        return {
          approved: true,
          scope: 'always',
          remember: true,  // creates a persistent user rule
        };
      }

      if (userChoice === 'always_allow_with_conditions') {
        return {
          approved: true,
          createRule: {
            description: 'Allow write_file in /workspace',
            conditions: [
              { argName: 'path', operator: 'starts_with', value: '/workspace/' },
            ],
          },
        };
      }

      if (userChoice === 'deny_forever') {
        return {
          approved: false,
          scope: 'never',
          remember: true,  // creates a persistent deny rule
        };
      }

      return { approved: false, reason: 'User denied' };
    },
  },
});

interface ApprovalRequestContext extends PolicyContext {
  /** The deny decision that triggered this approval request */
  decision: PolicyDecision;

  /** Tool's risk level (from tool permission config or default) */
  riskLevel: RiskLevel;  // 'low' | 'medium' | 'high' | 'critical'

  /** Custom approval message (from tool permission config) */
  approvalMessage?: string;

  /** Argument names to highlight as sensitive in approval UI */
  sensitiveArgs?: string[];

  /** Policy-provided approval scope key */
  approvalKey?: string;

  /** Suggested approval scope */
  approvalScope?: 'once' | 'session' | 'persistent';
}

interface PolicyContext {
  toolName: string;                      // Tool being invoked
  args: Record<string, unknown>;         // Parsed arguments
  userId?: string;                       // From ToolContext.userId
  roles?: string[];                      // From agent config userRoles
  agentId?: string;
  parentAgentId?: string;                // For orchestrator workers
  sessionId?: string;
  iteration?: number;                    // Agentic loop iteration
  executionId?: string;                  // For tracing
  toolSource?: string;                   // built-in, connector:xxx, mcp, custom
  toolCategory?: string;                 // filesystem, web, shell, etc.
  toolNamespace?: string;
  toolTags?: string[];
  toolPermissionConfig?: ToolPermissionConfig;  // Merged tool + registration config
}

interface ApprovalDecision {
  approved: boolean;
  scope?: PermissionScope;   // 'once' | 'session' | 'always' | 'never'
  reason?: string;           // Reason for denial
  approvedBy?: string;       // Identifier of approver
  remember?: boolean;        // Create persistent rule (shorthand)

  /** Explicit rule creation with argument conditions */
  createRule?: {
    description?: string;
    conditions?: ArgumentCondition[];
    expiresAt?: string | null;   // ISO timestamp, null = never
    unconditional?: boolean;
  };
}

User clicks "Always Allow" in dialog
    ↓
ApprovalDecision { approved: true, remember: true, scope: 'always' }
    ↓
PermissionPolicyManager.createRuleFromApproval()
    ↓
UserPermissionRulesEngine.addRule({
  toolName, action: 'allow', createdBy: 'approval_dialog'
})
    ↓
Rule persisted to IUserPermissionRulesStorage
    ↓
Next call: user rule matches → immediate allow (no policy chain, no dialog)

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    // Merged with DEFAULT_ALLOWLIST by PermissionPolicyManager.fromConfig().
    allowlist: ['my_safe_tool', 'another_safe_tool'],
  },
});

agent.policyManager.allowlistAdd('my_tool');
agent.policyManager.allowlistRemove('my_tool');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: { blocklist: ['dangerous_tool', 'deprecated_tool'] },
});

agent.policyManager.blocklistAdd('bad_tool');   // also removes from allowlist
agent.policyManager.blocklistRemove('bad_tool');

const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    defaultScope: 'once',
    onApprovalRequired: async (request) => showApprovalDialog(request),
  },
});

// Programmatically approve a tool for the session
agent.policyManager.approve('write_file', {
  scope: 'session',
  approvedBy: 'admin',
});

// With TTL expiration
agent.policyManager.approve('bash', {
  scope: 'session',
  ttlMs: 300000, // 5 minutes
});

// Revoke an approval
agent.policyManager.revoke('write_file');

// Check cache
agent.policyManager.isApproved('write_file'); // true/false

// Clear all session approvals
agent.policyManager.clearSession();

// Source-level illustration; PathRestrictionPolicy is not a package-root export in the current v2 public surface.
const policy = new PathRestrictionPolicy({
  // Required: allowed path prefixes (canonicalized at construction)
  allowedPaths: ['/workspace', '/tmp', process.cwd()],

  // Optional: customize which tools are checked
  // Default: write_file, edit_file, read_file, list_directory, glob, grep
  tools: ['write_file', 'edit_file', 'read_file', 'list_directory', 'glob', 'grep'],

  // Optional: which argument names contain file paths
  // Default: path, file_path, target_path, directory, pattern
  pathArgs: ['path', 'file_path', 'target_path', 'directory', 'pattern'],

  // Optional: resolve symlinks for existing files
  resolveSymlinks: true,  // default: true

  // Optional: base path for resolving relative paths
  basePath: process.cwd(),  // default: process.cwd()
});

// Source-level illustration; BashFilterPolicy is not a package-root export in the current v2 public surface.
const policy = new BashFilterPolicy({
  // Deny patterns (checked first, any match → deny with needsApproval)
  denyPatterns: [
    /rm\s+-rf/,
    /sudo\s+/,
    /chmod\s+777/,
    /curl.*\|.*sh/,     // pipe curl to shell
  ],
  denyCommands: ['shutdown', 'reboot', 'mkfs'],

  // Allow patterns (if matched after deny check, abstain → other policies decide)
  allowPatterns: [/^(ls|cat|echo|pwd|whoami)/],
  allowCommands: ['npm', 'node', 'git', 'tsc', 'npx'],

  // Argument containing the command (default: 'command')
  commandArg: 'command',
});

// Source-level illustration; UrlAllowlistPolicy is not a package-root export in the current v2 public surface.
const policy = new UrlAllowlistPolicy({
  allowedDomains: [
    'api.github.com',       // exact match (also matches www.api.github.com)
    '.example.com',         // suffix: matches sub.example.com, NOT example.com
    'internal.corp.net',    // exact + subdomains
  ],

  // Optional configuration
  allowedProtocols: ['http:', 'https:'],  // default
  tools: ['web_fetch', 'web_search', 'web_scrape'],  // default
  urlArgs: ['url', 'query', 'target_url'],  // default
});

// Source-level illustration; RolePolicy is not a package-root export in the current v2 public surface.
const policy = new RolePolicy([
  {
    role: 'admin',
    allowTools: ['*'],  // admins can use everything
  },
  {
    role: 'developer',
    allowTools: ['read_file', 'write_file', 'edit_file', 'bash', 'glob', 'grep'],
    denyTools: ['desktop_mouse_click'],  // no desktop automation
  },
  {
    role: 'viewer',
    allowTools: ['read_file', 'glob', 'grep', 'list_directory'],
    denyTools: ['write_file', 'edit_file', 'bash'],
  },
  {
    role: 'restricted',
    denyTools: ['*'],  // deny everything (overrides any allow from other roles)
  },
]);

// Set user roles on the agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  userRoles: ['developer'],  // passed to PolicyContext.roles
  permissions: {
    policies: [policy],
  },
});

// Source-level illustration; RateLimitPolicy is not a package-root export in the current v2 public surface.
const policy = new RateLimitPolicy({
  limits: {
    'web_fetch': { maxCalls: 10, windowMs: 60_000 },   // 10 per minute
    'bash': { maxCalls: 5, windowMs: 30_000 },          // 5 per 30 seconds
    'web_search': { maxCalls: 20, windowMs: 60_000 },   // 20 per minute
  },

  // Optional: default limit for tools not explicitly configured
  defaultLimit: { maxCalls: 100, windowMs: 60_000 },
});

// Reset counters
policy.reset('web_fetch');  // reset one tool
policy.reset();             // reset all tools

interface ToolPermissionConfig {
  /** When approval is required: 'once' | 'session' | 'always' | 'never' */
  scope?: PermissionScope;

  /** Risk classification: 'low' | 'medium' | 'high' | 'critical' */
  riskLevel?: RiskLevel;

  /** Custom message shown in approval UI */
  approvalMessage?: string;

  /** Argument names to highlight as sensitive (also used for audit redaction) */
  sensitiveArgs?: string[];

  /** Expiration time for session approvals (ms) */
  sessionTTLMs?: number;
}

const myTool: ToolFunction = {
  definition: {
    type: 'function',
    function: {
      name: 'deploy_service',
      description: 'Deploy a service to production',
      parameters: {
        type: 'object',
        properties: {
          service: { type: 'string' },
          environment: { type: 'string' },
        },
        required: ['service', 'environment'],
      },
    },
  },
  execute: async (args) => { /* ... */ },
  permission: {
    scope: 'once',          // require approval every time
    riskLevel: 'critical',
    approvalMessage: 'This will deploy to production. Are you sure?',
    sensitiveArgs: ['environment'],
    sessionTTLMs: 300_000,  // session approvals expire after 5 minutes
  },
};

agent.tools.register(myTool, {
  permission: {
    scope: 'session',      // override: approve once per session instead of every call
    riskLevel: 'medium',   // downgrade risk from critical
  },
});

interface IUserPermissionRulesStorage {
  /** Load all rules for a user. Returns null if no rules exist. */
  load(userId: string | undefined): Promise<UserPermissionRule[] | null>;

  /** Save all rules for a user (full replacement). */
  save(userId: string | undefined, rules: UserPermissionRule[]): Promise<void>;

  /** Delete all rules for a user. */
  delete(userId: string | undefined): Promise<void>;

  /** Check if rules exist for a user. */
  exists(userId: string | undefined): Promise<boolean>;

  /** Get storage path (for debugging/display). */
  getPath(userId: string | undefined): string;
}

// Reference implementation — file-based
import { FileUserPermissionRulesStorage } from 'oneringai';

const storage = new FileUserPermissionRulesStorage();

// Custom implementation
class MongoPermissionRulesStorage implements IUserPermissionRulesStorage {
  async load(userId) { /* query MongoDB */ }
  async save(userId, rules) { /* upsert to MongoDB */ }
  async delete(userId) { /* delete from MongoDB */ }
  async exists(userId) { /* check existence */ }
  getPath(userId) { return `mongodb://permissions/${userId ?? 'default'}`; }
}

agent.policyManager.on('permission:audit', async (entry: PermissionAuditEntry) => {
  await myAuditLog.record(entry);
});

import { StorageRegistry, FileUserPermissionRulesStorage } from 'oneringai';

// Global configuration
StorageRegistry.configure({
  permissionRules: new MongoPermissionRulesStorage(), // Implement per-user partitioning inside this storage.
});

// Or per-agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    userRulesStorage: new FileUserPermissionRulesStorage(),
    // NOTE: there is no built-in auditStorage/policyStorage config field —
    // persist audit entries yourself via agent.policyManager.on('permission:audit', ...).
  },
});

import { createOrchestrator } from 'oneringai';

// Orchestrator with strict permissions
const orchestrator = await createOrchestrator({
  connector: 'openai',
  model: 'gpt-4.1',
  agentTypes: {
    developer: {
      systemPrompt: 'Write code',
      tools: [readFile, writeFile, bash],
    },
  },
});

// Public manager shortcut: parent-chain restriction, subject to the precedence above.
orchestrator.policyManager.blocklistAdd('bash');
// For argument-aware restrictions, add your own IPermissionPolicy implementation.

import { PermissionPolicyManager } from 'oneringai';

const parentManager = PermissionPolicyManager.fromConfig({ /* parent policies */ });
const workerManager = PermissionPolicyManager.fromConfig({ /* worker policies */ });

// Worker cannot exceed parent permissions
workerManager.setParentEvaluator(parentManager);

// Check parent
const parent = workerManager.getParentEvaluator(); // PermissionPolicyManager | undefined

interface PermissionAuditEntry {
  id: string;                    // Unique entry ID (UUID)
  timestamp: string;             // ISO timestamp
  toolName: string;              // Tool that was checked
  decision: 'allow' | 'deny';   // Policy evaluation result
  finalOutcome:                  // Final execution outcome
    | 'executed'                 // Tool was allowed and executed
    | 'blocked'                  // Tool was hard-blocked
    | 'approval_granted'         // User approved via dialog
    | 'approval_denied';         // User denied via dialog
  reason: string;                // Human-readable reason
  policyName?: string;           // Policy that made the deciding verdict
  userId?: string;               // User who triggered the check
  agentId?: string;              // Agent that triggered the check
  args?: Record<string, unknown>; // Redacted arguments
  executionId?: string;          // Execution ID for correlation
  approvalRequired?: boolean;    // Whether approval was requested
  approvalKey?: string;          // Approval cache key
  metadata?: Record<string, unknown>;
}

const manager = agent.policyManager;

manager.on('permission:allow', (entry: PermissionAuditEntry) => {
  console.log(`Allowed: ${entry.toolName} by ${entry.policyName}`);
});

manager.on('permission:deny', (entry: PermissionAuditEntry) => {
  console.log(`Denied: ${entry.toolName} — ${entry.reason}`);
});

manager.on('permission:approval_granted', (entry: PermissionAuditEntry) => {
  console.log(`Approved by user: ${entry.toolName}`);
});

manager.on('permission:approval_denied', (entry: PermissionAuditEntry) => {
  console.log(`User denied: ${entry.toolName}`);
});

// Catch-all audit event (fires for EVERY decision, in addition to specific events)
manager.on('permission:audit', (entry: PermissionAuditEntry) => {
  myAuditLog.record(entry);
});

// Policy lifecycle events
manager.on('policy:added', ({ name }) => console.log(`Policy added: ${name}`));
manager.on('policy:removed', ({ name }) => console.log(`Policy removed: ${name}`));
manager.on('session:cleared', () => console.log('Session approvals cleared'));

import { FileUserPermissionRulesStorage } from 'oneringai';
import type { IPermissionPolicy } from 'oneringai';

const noSudoPolicy: IPermissionPolicy = {
  name: 'app:no-sudo',
  priority: 50,
  evaluate: (ctx) =>
    ctx.toolName === 'bash' && String(ctx.args.command ?? '').includes('sudo')
      ? { verdict: 'deny', reason: 'sudo is disabled', policyName: 'app:no-sudo' }
      : { verdict: 'abstain', reason: 'not applicable', policyName: 'app:no-sudo' },
};

// Legacy config — still works, auto-translated to policies
const legacyAgent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    defaultScope: 'session',
    allowlist: ['my_tool'],
    blocklist: ['bad_tool'],
    onApprovalRequired: async (ctx) => ({ approved: true }),
  },
});
legacyAgent.permissions.approve('tool');  // ToolPermissionManager (deprecated)

// New policy config — explicitly uses policies
const policyAgent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  permissions: {
    allowlist: ['my_tool'],
    blocklist: ['bad_tool'],
    policies: [noSudoPolicy],
    onApprovalRequired: async (ctx) => ({ approved: true }),
    userRulesStorage: new FileUserPermissionRulesStorage(),
  },
});
policyAgent.policyManager.userRules.addRule(rule);  // PermissionPolicyManager

import { PermissionPolicyManager } from 'oneringai';

// From legacy config
const manager = PermissionPolicyManager.fromLegacyConfig({
  allowlist: ['my_tool'],
  blocklist: ['bad_tool'],
  defaultScope: 'session',
});

// From new config with policies
const managerVariant2 = PermissionPolicyManager.fromConfig({
  allowlist: ['my_tool'],
  policies: [noSudoPolicy],
  userRulesStorage: new FileUserPermissionRulesStorage(),
  // NOTE: policyChain and auditStorage are not read by fromConfig() — see notes above.
});

// New API (preferred)
const policyManager = agent.policyManager;

// Deprecated (still works for backward compatibility)
const legacyManager = agent.permissions;

ToolManager.execute()
    ↓
ToolExecutionPipeline.beforeExecute()
    ↓
PermissionEnforcementPlugin (priority: 1; normalizer priority 0 also runs)
    ↓
PolicyContext built from: tool args + ToolContext + registration metadata
    ↓
PermissionPolicyManager.check()
    ↓
If denied → throws ToolPermissionDeniedError
If allowed → execution continues to next plugin / tool handler

// Internal illustration; not a consumer call. This happens in BaseAgent:
this._agentContext.tools.setPermissionManager(this._policyManager);

import {
  Agent, Connector, Vendor,
  FileUserPermissionRulesStorage,
} from 'oneringai';
import type {
  ApprovalRequestContext,
  ApprovalDecision,
  IPermissionPolicy,
  PermissionAuditEntry,
} from 'oneringai';

declare function promptUser(question: string): Promise<'y' | 'n' | 'always'>;

// The package root exposes the policy interface, so applications can encode
// restrictions without importing source-internal policy implementations.
const workspaceSafetyPolicy: IPermissionPolicy = {
  name: 'app:workspace-safety',
  priority: 50,
  evaluate(ctx) {
    if (ctx.toolName === 'bash') {
      const command = String(ctx.args.command ?? '');
      if (/\b(?:sudo|rm\s+-rf)\b/.test(command)) {
        return {
          verdict: 'deny',
          reason: 'Privileged and recursive-delete commands are blocked',
          policyName: 'app:workspace-safety',
        };
      }
    }

    if (['read_file', 'write_file', 'edit_file'].includes(ctx.toolName)) {
      const path = String(ctx.args.path ?? '');
      if (!path.startsWith('/workspace/')) {
        return {
          verdict: 'deny',
          reason: 'File access is restricted to /workspace',
          policyName: 'app:workspace-safety',
        };
      }
    }

    return {
      verdict: 'abstain',
      reason: 'No workspace restriction matched',
      policyName: 'app:workspace-safety',
    };
  },
};

// Setup connector
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// Create agent with full permission configuration
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-4.1',
  userId: 'alice',
  userRoles: ['developer'],

  permissions: {
    // Lists
    allowlist: ['my_custom_tool'],
    blocklist: ['legacy_dangerous_tool'],

    policies: [workspaceSafetyPolicy],

    // Per-user rules storage (persistent)
    userRulesStorage: new FileUserPermissionRulesStorage(),

    // Approval dialog
    onApprovalRequired: async (ctx: ApprovalRequestContext): Promise<ApprovalDecision> => {
      console.log(`[APPROVAL NEEDED] ${ctx.toolName}`);
      console.log(`  Risk: ${ctx.riskLevel}`);
      console.log(`  Reason: ${ctx.decision.reason}`);
      console.log(`  Args: ${JSON.stringify(ctx.args)}`);

      // Auto-approve low-risk tools for the session
      if (ctx.riskLevel === 'low') {
        return { approved: true, scope: 'session' };
      }

      // Always deny critical tools without asking
      if (ctx.riskLevel === 'critical') {
        return { approved: false, reason: 'Critical tools require admin approval' };
      }

      // Prompt the user for medium/high risk tools
      const answer = await promptUser(`Allow ${ctx.toolName}? (y/n/always)`);
      if (answer === 'always') {
        return {
          approved: true,
          createRule: {
            description: `User approved ${ctx.toolName}`,
            conditions: ctx.approvalKey !== ctx.toolName
              ? [{ argName: 'path', operator: 'starts_with', value: ctx.args.path as string }]
              : undefined,
          },
        };
      }
      return { approved: answer === 'y' };
    },
  },
});

// Listen to audit events
agent.policyManager.on('permission:audit', (entry: PermissionAuditEntry) => {
  console.log(`[AUDIT] ${entry.decision} ${entry.toolName}: ${entry.reason}`);
});

// Add a user rule programmatically
await agent.policyManager.userRules.addRule({
  id: crypto.randomUUID(),
  toolName: 'write_file',
  action: 'allow',
  conditions: [
    { argName: 'path', operator: 'starts_with', value: '/workspace/src/' },
  ],
  enabled: true,
  description: 'Allow writing to src directory',
  createdBy: 'admin',
  createdAt: new Date().toISOString(),
  updatedAt: new Date().toISOString(),
}, 'alice');

// Run the agent — all tool calls are permission-checked automatically
const result = await agent.run('Read the README and refactor the auth module');