agent-relay 1.1.0 → 1.2.3

package/dist/policy/agent-policy.js

@@ -0,0 +1,665 @@
+/**
+ * Agent Policy Service
+ *
+ * Manages agent permissions and rules with multi-level fallback:
+ * 1. Repo-level policy (.claude/agents/*.md)
+ * 2. Workspace-level policy (from cloud API)
+ * 3. Built-in safe defaults
+ *
+ * Provides spawn authorization, tool permission checks, and audit logging.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { findAgentConfig } from '../utils/agent-config.js';
+import os from 'node:os';
+/** Built-in safe defaults when no policy exists */
+const DEFAULT_POLICY = {
+    name: '*',
+    allowedTools: undefined, // All tools allowed by default
+    canSpawn: undefined, // Can spawn any agent
+    canMessage: undefined, // Can message any agent
+    maxSpawns: 10,
+    rateLimit: 60, // 60 messages per minute
+    canBeSpawned: true,
+};
+/** Restrictive defaults for unknown agents in strict mode */
+const STRICT_DEFAULT_POLICY = {
+    name: '*',
+    allowedTools: ['Read', 'Grep', 'Glob'], // Read-only by default
+    canSpawn: [], // Cannot spawn
+    canMessage: ['Lead', 'Coordinator'], // Can only message leads
+    maxSpawns: 0,
+    rateLimit: 10,
+    canBeSpawned: false,
+};
+export class AgentPolicyService {
+    projectRoot;
+    workspaceId;
+    cloudFetcher;
+    cachedWorkspacePolicy;
+    cachedLocalPolicy;
+    policyCacheExpiry = 0;
+    localPolicyCacheExpiry = 0;
+    auditLog = [];
+    strictMode;
+    /** Cache TTL in milliseconds (5 minutes) */
+    static CACHE_TTL_MS = 5 * 60 * 1000;
+    /** Local policy cache TTL (1 minute - files can change) */
+    static LOCAL_CACHE_TTL_MS = 60 * 1000;
+    /** Maximum audit log entries to keep in memory */
+    static MAX_AUDIT_ENTRIES = 1000;
+    constructor(options) {
+        this.projectRoot = options.projectRoot;
+        this.workspaceId = options.workspaceId;
+        this.cloudFetcher = options.cloudFetcher;
+        this.strictMode = options.strictMode ?? false;
+    }
+    /**
+     * Get the user-level policies directory
+     * Uses ~/.config/agent-relay/policies/ (not in source control)
+     */
+    getUserPoliciesDir() {
+        const configDir = process.env.AGENT_RELAY_CONFIG_DIR ??
+            path.join(os.homedir(), '.config', 'agent-relay');
+        return path.join(configDir, 'policies');
+    }
+    /**
+     * Load policies from user-level directory (PRPM-installable)
+     * Files are YAML/JSON with agent policy definitions
+     * Location: ~/.config/agent-relay/policies/*.yaml
+     */
+    loadLocalPolicies() {
+        // Check cache
+        if (this.cachedLocalPolicy && Date.now() < this.localPolicyCacheExpiry) {
+            return this.cachedLocalPolicy;
+        }
+        const policiesDir = this.getUserPoliciesDir();
+        if (!fs.existsSync(policiesDir)) {
+            return null;
+        }
+        try {
+            const files = fs.readdirSync(policiesDir).filter(f => f.endsWith('.yaml') || f.endsWith('.yml') || f.endsWith('.json'));
+            if (files.length === 0) {
+                return null;
+            }
+            // Merge all policy files
+            const mergedAgents = [];
+            let mergedSettings = {
+                requireExplicitAgents: false,
+                auditEnabled: true,
+                maxTotalAgents: 50,
+            };
+            let mergedDefault = { ...DEFAULT_POLICY };
+            for (const file of files) {
+                const filePath = path.join(policiesDir, file);
+                const content = fs.readFileSync(filePath, 'utf-8');
+                let parsed;
+                if (file.endsWith('.json')) {
+                    parsed = JSON.parse(content);
+                }
+                else {
+                    // Simple YAML parsing for policy files
+                    parsed = this.parseSimpleYaml(content);
+                }
+                // Merge agents
+                if (Array.isArray(parsed.agents)) {
+                    for (const agent of parsed.agents) {
+                        if (agent && typeof agent === 'object' && 'name' in agent) {
+                            mergedAgents.push(agent);
+                        }
+                    }
+                }
+                // Merge settings (later files override)
+                if (parsed.settings && typeof parsed.settings === 'object') {
+                    mergedSettings = { ...mergedSettings, ...parsed.settings };
+                }
+                // Merge default policy
+                if (parsed.defaultPolicy && typeof parsed.defaultPolicy === 'object') {
+                    mergedDefault = { ...mergedDefault, ...parsed.defaultPolicy };
+                }
+            }
+            const policy = {
+                defaultPolicy: mergedDefault,
+                agents: mergedAgents,
+                settings: mergedSettings,
+            };
+            this.cachedLocalPolicy = policy;
+            this.localPolicyCacheExpiry = Date.now() + AgentPolicyService.LOCAL_CACHE_TTL_MS;
+            return policy;
+        }
+        catch (err) {
+            console.error('[policy] Failed to load local policies:', err);
+            return null;
+        }
+    }
+    /**
+     * Simple YAML parser for policy files
+     * Handles basic key: value and arrays
+     */
+    parseSimpleYaml(content) {
+        const result = {};
+        const lines = content.split('\n');
+        let _currentKey = '';
+        let currentArray = null;
+        let currentObject = null;
+        let indent = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            // Skip comments and empty lines
+            if (!trimmed || trimmed.startsWith('#'))
+                continue;
+            // Calculate indentation
+            const lineIndent = line.length - line.trimStart().length;
+            // Array item
+            if (trimmed.startsWith('- ')) {
+                const value = trimmed.slice(2).trim();
+                // Object in array (e.g., "- name: Worker")
+                if (value.includes(':')) {
+                    const [key, val] = value.split(':').map(s => s.trim());
+                    currentObject = { [key]: this.parseValue(val) };
+                    if (currentArray) {
+                        currentArray.push(currentObject);
+                    }
+                }
+                else {
+                    // Simple array value
+                    if (currentArray) {
+                        currentArray.push(this.parseValue(value));
+                    }
+                }
+                continue;
+            }
+            // Key: value pair
+            const colonIdx = trimmed.indexOf(':');
+            if (colonIdx > 0) {
+                const key = trimmed.slice(0, colonIdx).trim();
+                const value = trimmed.slice(colonIdx + 1).trim();
+                // If we're inside an object in an array
+                if (currentObject && lineIndent > indent) {
+                    currentObject[key] = this.parseValue(value);
+                    continue;
+                }
+                // Top-level or section key
+                if (value === '' || value === '|' || value === '>') {
+                    // Start of array or nested object
+                    _currentKey = key;
+                    currentArray = [];
+                    currentObject = null;
+                    indent = lineIndent;
+                    result[key] = currentArray;
+                }
+                else {
+                    // Simple key: value
+                    if (lineIndent === 0) {
+                        result[key] = this.parseValue(value);
+                        _currentKey = '';
+                        currentArray = null;
+                        currentObject = null;
+                    }
+                    else if (currentObject) {
+                        currentObject[key] = this.parseValue(value);
+                    }
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Parse a YAML value string
+     */
+    parseValue(value) {
+        if (!value || value === '~' || value === 'null')
+            return null;
+        if (value === 'true')
+            return true;
+        if (value === 'false')
+            return false;
+        // Array notation [a, b, c]
+        if (value.startsWith('[') && value.endsWith(']')) {
+            const inner = value.slice(1, -1);
+            if (!inner.trim())
+                return [];
+            return inner.split(',').map(s => {
+                const trimmed = s.trim().replace(/^["']|["']$/g, '');
+                return trimmed;
+            });
+        }
+        // Number
+        if (/^-?\d+(\.\d+)?$/.test(value)) {
+            return parseFloat(value);
+        }
+        // String (remove quotes if present)
+        return value.replace(/^["']|["']$/g, '');
+    }
+    /**
+     * Check if an agent can spawn another agent
+     */
+    async canSpawn(spawnerName, targetName, targetCli) {
+        const spawnerPolicy = await this.getAgentPolicy(spawnerName);
+        const targetPolicy = await this.getAgentPolicy(targetName);
+        // Check if target can be spawned
+        if (targetPolicy.matchedPolicy?.canBeSpawned === false) {
+            const decision = {
+                allowed: false,
+                reason: `Agent "${targetName}" is not allowed to be spawned`,
+                policySource: targetPolicy.policySource,
+                matchedPolicy: targetPolicy.matchedPolicy,
+            };
+            this.audit('spawn', spawnerName, targetName, decision, { cli: targetCli });
+            return decision;
+        }
+        // Check if spawner can spawn
+        const canSpawnList = spawnerPolicy.matchedPolicy?.canSpawn;
+        if (canSpawnList !== undefined && canSpawnList.length > 0) {
+            const canSpawn = this.matchesPattern(targetName, canSpawnList);
+            if (!canSpawn) {
+                const decision = {
+                    allowed: false,
+                    reason: `Agent "${spawnerName}" is not allowed to spawn "${targetName}"`,
+                    policySource: spawnerPolicy.policySource,
+                    matchedPolicy: spawnerPolicy.matchedPolicy,
+                };
+                this.audit('spawn', spawnerName, targetName, decision, { cli: targetCli });
+                return decision;
+            }
+        }
+        // Check max spawns (would need spawn count tracking - placeholder)
+        const decision = {
+            allowed: true,
+            reason: 'Spawn permitted by policy',
+            policySource: spawnerPolicy.policySource,
+            matchedPolicy: spawnerPolicy.matchedPolicy,
+        };
+        this.audit('spawn', spawnerName, targetName, decision, { cli: targetCli });
+        return decision;
+    }
+    /**
+     * Check if an agent can send a message to another agent
+     */
+    async canMessage(senderName, recipientName) {
+        const senderPolicy = await this.getAgentPolicy(senderName);
+        const canMessageList = senderPolicy.matchedPolicy?.canMessage;
+        if (canMessageList !== undefined && canMessageList.length > 0) {
+            const canMessage = this.matchesPattern(recipientName, canMessageList);
+            if (!canMessage) {
+                const decision = {
+                    allowed: false,
+                    reason: `Agent "${senderName}" is not allowed to message "${recipientName}"`,
+                    policySource: senderPolicy.policySource,
+                    matchedPolicy: senderPolicy.matchedPolicy,
+                };
+                this.audit('message', senderName, recipientName, decision);
+                return decision;
+            }
+        }
+        const decision = {
+            allowed: true,
+            reason: 'Message permitted by policy',
+            policySource: senderPolicy.policySource,
+            matchedPolicy: senderPolicy.matchedPolicy,
+        };
+        this.audit('message', senderName, recipientName, decision);
+        return decision;
+    }
+    /**
+     * Check if an agent can use a specific tool
+     */
+    async canUseTool(agentName, toolName) {
+        const policy = await this.getAgentPolicy(agentName);
+        const allowedTools = policy.matchedPolicy?.allowedTools;
+        if (allowedTools !== undefined) {
+            // ["none"] means no tools allowed
+            if (allowedTools.length === 1 && allowedTools[0] === 'none') {
+                const decision = {
+                    allowed: false,
+                    reason: `Agent "${agentName}" is not allowed to use any tools`,
+                    policySource: policy.policySource,
+                    matchedPolicy: policy.matchedPolicy,
+                };
+                this.audit('tool', agentName, toolName, decision);
+                return decision;
+            }
+            // Check if tool is in allowed list
+            const allowed = this.matchesPattern(toolName, allowedTools);
+            if (!allowed) {
+                const decision = {
+                    allowed: false,
+                    reason: `Agent "${agentName}" is not allowed to use tool "${toolName}"`,
+                    policySource: policy.policySource,
+                    matchedPolicy: policy.matchedPolicy,
+                };
+                this.audit('tool', agentName, toolName, decision);
+                return decision;
+            }
+        }
+        const decision = {
+            allowed: true,
+            reason: 'Tool usage permitted by policy',
+            policySource: policy.policySource,
+            matchedPolicy: policy.matchedPolicy,
+        };
+        this.audit('tool', agentName, toolName, decision);
+        return decision;
+    }
+    /**
+     * Get the effective policy for an agent
+     * Fallback chain: repo config → user PRPM policies → cloud workspace → defaults
+     */
+    async getAgentPolicy(agentName) {
+        // 1. Try repo-level config (.claude/agents/*.md)
+        const repoConfig = findAgentConfig(agentName, this.projectRoot);
+        if (repoConfig) {
+            return {
+                matchedPolicy: this.configToPolicy(repoConfig),
+                policySource: 'repo',
+            };
+        }
+        // 2. Try user-level PRPM policies (~/.config/agent-relay/policies/*.yaml)
+        const localPolicy = this.loadLocalPolicies();
+        if (localPolicy) {
+            // Check for strict mode in local policy
+            if (localPolicy.settings?.requireExplicitAgents) {
+                const matchedPolicy = this.findMatchingPolicy(agentName, localPolicy.agents);
+                if (matchedPolicy) {
+                    return { matchedPolicy, policySource: 'local' };
+                }
+                // Unknown agent in strict mode
+                return {
+                    matchedPolicy: { ...STRICT_DEFAULT_POLICY, name: agentName },
+                    policySource: 'local',
+                };
+            }
+            // Find matching policy
+            const matchedPolicy = this.findMatchingPolicy(agentName, localPolicy.agents);
+            if (matchedPolicy) {
+                return { matchedPolicy, policySource: 'local' };
+            }
+            // Use local default
+            if (localPolicy.defaultPolicy) {
+                return {
+                    matchedPolicy: { ...localPolicy.defaultPolicy, name: agentName },
+                    policySource: 'local',
+                };
+            }
+        }
+        // 3. Try workspace-level policy from cloud
+        const workspacePolicy = await this.getWorkspacePolicy();
+        if (workspacePolicy) {
+            // Check for strict mode
+            if (workspacePolicy.settings?.requireExplicitAgents) {
+                // In strict mode, unknown agents get restrictive defaults
+                const matchedPolicy = this.findMatchingPolicy(agentName, workspacePolicy.agents);
+                if (matchedPolicy) {
+                    return { matchedPolicy, policySource: 'workspace' };
+                }
+                // Unknown agent in strict mode
+                return {
+                    matchedPolicy: { ...STRICT_DEFAULT_POLICY, name: agentName },
+                    policySource: 'workspace',
+                };
+            }
+            // Find matching policy
+            const matchedPolicy = this.findMatchingPolicy(agentName, workspacePolicy.agents);
+            if (matchedPolicy) {
+                return { matchedPolicy, policySource: 'workspace' };
+            }
+            // Use workspace default
+            if (workspacePolicy.defaultPolicy) {
+                return {
+                    matchedPolicy: { ...workspacePolicy.defaultPolicy, name: agentName },
+                    policySource: 'workspace',
+                };
+            }
+        }
+        // 4. Fall back to built-in defaults
+        const defaultPolicy = this.strictMode ? STRICT_DEFAULT_POLICY : DEFAULT_POLICY;
+        return {
+            matchedPolicy: { ...defaultPolicy, name: agentName },
+            policySource: 'default',
+        };
+    }
+    /**
+     * Get workspace policy from cloud (with caching)
+     */
+    async getWorkspacePolicy() {
+        if (!this.workspaceId || !this.cloudFetcher) {
+            return null;
+        }
+        // Check cache
+        if (this.cachedWorkspacePolicy && Date.now() < this.policyCacheExpiry) {
+            return this.cachedWorkspacePolicy;
+        }
+        try {
+            const policy = await this.cloudFetcher.getWorkspacePolicy(this.workspaceId);
+            if (policy) {
+                this.cachedWorkspacePolicy = policy;
+                this.policyCacheExpiry = Date.now() + AgentPolicyService.CACHE_TTL_MS;
+            }
+            return policy;
+        }
+        catch (err) {
+            console.error('[policy] Failed to fetch workspace policy:', err);
+            // Return cached policy if available, even if expired
+            return this.cachedWorkspacePolicy ?? null;
+        }
+    }
+    /**
+     * Find matching policy from a list (supports wildcards)
+     */
+    findMatchingPolicy(agentName, policies) {
+        // First try exact match
+        const exactMatch = policies.find(p => p.name.toLowerCase() === agentName.toLowerCase());
+        if (exactMatch)
+            return exactMatch;
+        // Then try pattern match
+        for (const policy of policies) {
+            if (this.matchesPattern(agentName, [policy.name])) {
+                return policy;
+            }
+        }
+        return null;
+    }
+    /**
+     * Check if a name matches any pattern in the list
+     * Supports: exact match, prefix* match, *suffix match, * (all)
+     */
+    matchesPattern(name, patterns) {
+        const lowerName = name.toLowerCase();
+        for (const pattern of patterns) {
+            const lowerPattern = pattern.toLowerCase();
+            // Wildcard all
+            if (lowerPattern === '*')
+                return true;
+            // Exact match
+            if (lowerPattern === lowerName)
+                return true;
+            // Prefix match (e.g., "Worker*" matches "WorkerA")
+            if (lowerPattern.endsWith('*')) {
+                const prefix = lowerPattern.slice(0, -1);
+                if (lowerName.startsWith(prefix))
+                    return true;
+            }
+            // Suffix match (e.g., "*Lead" matches "TeamLead")
+            if (lowerPattern.startsWith('*')) {
+                const suffix = lowerPattern.slice(1);
+                if (lowerName.endsWith(suffix))
+                    return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Convert AgentConfig to AgentPolicy
+     */
+    configToPolicy(config) {
+        return {
+            name: config.name,
+            allowedTools: config.allowedTools,
+            // Other fields come from defaults since repo config doesn't specify them
+            canSpawn: undefined,
+            canMessage: undefined,
+            maxSpawns: 10,
+            rateLimit: 60,
+            canBeSpawned: true,
+        };
+    }
+    /**
+     * Record an audit entry
+     */
+    audit(action, actor, target, decision, context) {
+        const entry = {
+            timestamp: Date.now(),
+            action,
+            actor,
+            target,
+            decision,
+            context,
+        };
+        this.auditLog.push(entry);
+        // Trim log if too large
+        if (this.auditLog.length > AgentPolicyService.MAX_AUDIT_ENTRIES) {
+            this.auditLog = this.auditLog.slice(-AgentPolicyService.MAX_AUDIT_ENTRIES / 2);
+        }
+        // Log denied actions
+        if (!decision.allowed) {
+            console.warn(`[policy] DENIED: ${action} by ${actor}${target ? ` -> ${target}` : ''}: ${decision.reason}`);
+        }
+    }
+    /**
+     * Get audit log entries
+     */
+    getAuditLog(options) {
+        let entries = [...this.auditLog];
+        if (options?.action) {
+            entries = entries.filter(e => e.action === options.action);
+        }
+        if (options?.actor) {
+            entries = entries.filter(e => e.actor === options.actor);
+        }
+        if (options?.deniedOnly) {
+            entries = entries.filter(e => !e.decision.allowed);
+        }
+        if (options?.limit) {
+            entries = entries.slice(-options.limit);
+        }
+        return entries;
+    }
+    /**
+     * Clear audit log
+     */
+    clearAuditLog() {
+        this.auditLog = [];
+    }
+    /**
+     * Invalidate cached workspace policy
+     */
+    invalidateCache() {
+        this.cachedWorkspacePolicy = undefined;
+        this.policyCacheExpiry = 0;
+    }
+    /**
+     * Get a human-readable policy summary for an agent
+     * This can be injected into agent prompts to inform them of their permissions
+     */
+    async getPolicySummary(agentName) {
+        const { matchedPolicy, policySource } = await this.getAgentPolicy(agentName);
+        const lines = [
+            `# Agent Policy for ${agentName}`,
+            `Source: ${policySource}`,
+            '',
+        ];
+        // Tools
+        if (matchedPolicy.allowedTools) {
+            if (matchedPolicy.allowedTools.length === 1 && matchedPolicy.allowedTools[0] === 'none') {
+                lines.push('**Tools**: No tools allowed');
+            }
+            else {
+                lines.push(`**Allowed Tools**: ${matchedPolicy.allowedTools.join(', ')}`);
+            }
+        }
+        else {
+            lines.push('**Tools**: All tools allowed');
+        }
+        // Spawning
+        if (matchedPolicy.canSpawn) {
+            if (matchedPolicy.canSpawn.length === 0) {
+                lines.push('**Spawning**: Cannot spawn other agents');
+            }
+            else {
+                lines.push(`**Can Spawn**: ${matchedPolicy.canSpawn.join(', ')}`);
+            }
+        }
+        else {
+            lines.push('**Spawning**: Can spawn any agent');
+        }
+        // Messaging
+        if (matchedPolicy.canMessage) {
+            if (matchedPolicy.canMessage.length === 0) {
+                lines.push('**Messaging**: Cannot message other agents');
+            }
+            else {
+                lines.push(`**Can Message**: ${matchedPolicy.canMessage.join(', ')}`);
+            }
+        }
+        else {
+            lines.push('**Messaging**: Can message any agent');
+        }
+        // Limits
+        if (matchedPolicy.maxSpawns !== undefined) {
+            lines.push(`**Max Spawns**: ${matchedPolicy.maxSpawns}`);
+        }
+        if (matchedPolicy.rateLimit !== undefined) {
+            lines.push(`**Rate Limit**: ${matchedPolicy.rateLimit} messages/min`);
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Get a concise policy instruction for injection into agent prompts
+     */
+    async getPolicyInstruction(agentName) {
+        const { matchedPolicy, policySource: _policySource } = await this.getAgentPolicy(agentName);
+        // Only generate instructions if there are restrictions
+        const hasRestrictions = matchedPolicy.allowedTools !== undefined ||
+            matchedPolicy.canSpawn !== undefined ||
+            matchedPolicy.canMessage !== undefined;
+        if (!hasRestrictions) {
+            return null; // No restrictions, no need to inform agent
+        }
+        const restrictions = [];
+        if (matchedPolicy.allowedTools) {
+            if (matchedPolicy.allowedTools.length === 1 && matchedPolicy.allowedTools[0] === 'none') {
+                restrictions.push('You are not allowed to use any tools.');
+            }
+            else {
+                restrictions.push(`You may only use these tools: ${matchedPolicy.allowedTools.join(', ')}.`);
+            }
+        }
+        if (matchedPolicy.canSpawn) {
+            if (matchedPolicy.canSpawn.length === 0) {
+                restrictions.push('You are not allowed to spawn other agents.');
+            }
+            else {
+                restrictions.push(`You may only spawn these agents: ${matchedPolicy.canSpawn.join(', ')}.`);
+            }
+        }
+        if (matchedPolicy.canMessage) {
+            if (matchedPolicy.canMessage.length === 0) {
+                restrictions.push('You are not allowed to message other agents.');
+            }
+            else {
+                restrictions.push(`You may only message these agents: ${matchedPolicy.canMessage.join(', ')}.`);
+            }
+        }
+        if (restrictions.length === 0) {
+            return null;
+        }
+        return `[Policy Restrictions]\n${restrictions.join('\n')}`;
+    }
+}
+/**
+ * Create a policy service for a project
+ */
+export function createPolicyService(options) {
+    return new AgentPolicyService(options);
+}
+//# sourceMappingURL=agent-policy.js.map

package/dist/policy/cloud-policy-fetcher.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Cloud Policy Fetcher
+ *
+ * Fetches workspace agent policies from the cloud API.
+ * Used by workspace containers to get their policy configuration.
+ */
+import type { CloudPolicyFetcher } from './agent-policy.js';
+/**
+ * Create a cloud policy fetcher for workspace containers
+ */
+export declare function createCloudPolicyFetcher(): CloudPolicyFetcher | null;
+//# sourceMappingURL=cloud-policy-fetcher.d.ts.map