agent-relay 1.1.0 → 1.2.3

package/dist/memory/types.js

@@ -0,0 +1,8 @@
+/**
+ * Agent Relay Memory Types
+ *
+ * Core types for the memory adapter system. Memory adapters provide
+ * semantic storage and retrieval of agent learnings and context.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/policy/agent-policy.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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.
+ */
+/**
+ * PRPM-style policy file format (YAML or JSON)
+ *
+ * Policy files are loaded from (in order of precedence):
+ * 1. User-level: ~/.config/agent-relay/policies/*.yaml (NOT in source control)
+ * 2. Cloud: Workspace config from dashboard (stored in database)
+ *
+ * PRPM packages install to the user-level location to avoid polluting repos.
+ * Install via: prpm install @org/strict-agent-rules --global
+ *
+ * Example policy file (~/.config/agent-relay/policies/strict-rules.yaml):
+ * ```yaml
+ * name: strict-spawn-rules
+ * version: 1.0.0
+ * description: Restrict agent spawning to leads only
+ *
+ * agents:
+ *   - name: Lead
+ *     canSpawn: ["*"]
+ *     canMessage: ["*"]
+ *   - name: Worker*
+ *     canSpawn: []
+ *     canMessage: ["Lead", "Coordinator"]
+ *
+ * settings:
+ *   requireExplicitAgents: false
+ *   auditEnabled: true
+ * ```
+ */
+/**
+ * Agent policy definition
+ */
+export interface AgentPolicy {
+    /** Agent name pattern (supports wildcards: "Lead", "Worker*", "*") */
+    name: string;
+    /** Allowed tools (empty = all allowed, ["none"] = no tools) */
+    allowedTools?: string[];
+    /** Agents this agent can spawn (empty = can spawn any) */
+    canSpawn?: string[];
+    /** Agents this agent can message (empty = can message any) */
+    canMessage?: string[];
+    /** Maximum concurrent spawns allowed */
+    maxSpawns?: number;
+    /** Rate limit: messages per minute */
+    rateLimit?: number;
+    /** Whether this agent can be spawned by others */
+    canBeSpawned?: boolean;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Workspace-level policy configuration
+ */
+export interface WorkspacePolicy {
+    /** Default policy for agents without explicit config */
+    defaultPolicy: AgentPolicy;
+    /** Named agent policies */
+    agents: AgentPolicy[];
+    /** Global settings */
+    settings: {
+        /** Require explicit agent definitions (reject unknown agents) */
+        requireExplicitAgents: boolean;
+        /** Enable audit logging */
+        auditEnabled: boolean;
+        /** Maximum total agents */
+        maxTotalAgents: number;
+    };
+}
+/**
+ * Policy decision with reasoning
+ */
+export interface PolicyDecision {
+    allowed: boolean;
+    reason: string;
+    policySource: 'repo' | 'local' | 'workspace' | 'default';
+    matchedPolicy?: AgentPolicy;
+}
+/**
+ * Audit log entry
+ */
+export interface AuditEntry {
+    timestamp: number;
+    action: 'spawn' | 'message' | 'tool' | 'release';
+    actor: string;
+    target?: string;
+    decision: PolicyDecision;
+    context?: Record<string, unknown>;
+}
+/**
+ * Cloud policy fetcher interface
+ * Implement this to fetch workspace policies from cloud API
+ */
+export interface CloudPolicyFetcher {
+    getWorkspacePolicy(workspaceId: string): Promise<WorkspacePolicy | null>;
+}
+export declare class AgentPolicyService {
+    private projectRoot;
+    private workspaceId?;
+    private cloudFetcher?;
+    private cachedWorkspacePolicy?;
+    private cachedLocalPolicy?;
+    private policyCacheExpiry;
+    private localPolicyCacheExpiry;
+    private auditLog;
+    private strictMode;
+    /** Cache TTL in milliseconds (5 minutes) */
+    private static readonly CACHE_TTL_MS;
+    /** Local policy cache TTL (1 minute - files can change) */
+    private static readonly LOCAL_CACHE_TTL_MS;
+    /** Maximum audit log entries to keep in memory */
+    private static readonly MAX_AUDIT_ENTRIES;
+    constructor(options: {
+        projectRoot: string;
+        workspaceId?: string;
+        cloudFetcher?: CloudPolicyFetcher;
+        strictMode?: boolean;
+    });
+    /**
+     * Get the user-level policies directory
+     * Uses ~/.config/agent-relay/policies/ (not in source control)
+     */
+    private getUserPoliciesDir;
+    /**
+     * Load policies from user-level directory (PRPM-installable)
+     * Files are YAML/JSON with agent policy definitions
+     * Location: ~/.config/agent-relay/policies/*.yaml
+     */
+    private loadLocalPolicies;
+    /**
+     * Simple YAML parser for policy files
+     * Handles basic key: value and arrays
+     */
+    private parseSimpleYaml;
+    /**
+     * Parse a YAML value string
+     */
+    private parseValue;
+    /**
+     * Check if an agent can spawn another agent
+     */
+    canSpawn(spawnerName: string, targetName: string, targetCli: string): Promise<PolicyDecision>;
+    /**
+     * Check if an agent can send a message to another agent
+     */
+    canMessage(senderName: string, recipientName: string): Promise<PolicyDecision>;
+    /**
+     * Check if an agent can use a specific tool
+     */
+    canUseTool(agentName: string, toolName: string): Promise<PolicyDecision>;
+    /**
+     * Get the effective policy for an agent
+     * Fallback chain: repo config → user PRPM policies → cloud workspace → defaults
+     */
+    getAgentPolicy(agentName: string): Promise<{
+        matchedPolicy: AgentPolicy;
+        policySource: 'repo' | 'local' | 'workspace' | 'default';
+    }>;
+    /**
+     * Get workspace policy from cloud (with caching)
+     */
+    private getWorkspacePolicy;
+    /**
+     * Find matching policy from a list (supports wildcards)
+     */
+    private findMatchingPolicy;
+    /**
+     * Check if a name matches any pattern in the list
+     * Supports: exact match, prefix* match, *suffix match, * (all)
+     */
+    private matchesPattern;
+    /**
+     * Convert AgentConfig to AgentPolicy
+     */
+    private configToPolicy;
+    /**
+     * Record an audit entry
+     */
+    private audit;
+    /**
+     * Get audit log entries
+     */
+    getAuditLog(options?: {
+        limit?: number;
+        action?: AuditEntry['action'];
+        actor?: string;
+        deniedOnly?: boolean;
+    }): AuditEntry[];
+    /**
+     * Clear audit log
+     */
+    clearAuditLog(): void;
+    /**
+     * Invalidate cached workspace policy
+     */
+    invalidateCache(): void;
+    /**
+     * Get a human-readable policy summary for an agent
+     * This can be injected into agent prompts to inform them of their permissions
+     */
+    getPolicySummary(agentName: string): Promise<string>;
+    /**
+     * Get a concise policy instruction for injection into agent prompts
+     */
+    getPolicyInstruction(agentName: string): Promise<string | null>;
+}
+/**
+ * Create a policy service for a project
+ */
+export declare function createPolicyService(options: {
+    projectRoot: string;
+    workspaceId?: string;
+    cloudFetcher?: CloudPolicyFetcher;
+    strictMode?: boolean;
+}): AgentPolicyService;
+//# sourceMappingURL=agent-policy.d.ts.map