@agent-assistant/policy 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Action, RiskLevel, RiskClassifier, PolicyRule, PolicyDecision, PolicyEvaluationContext, PolicyEngineConfig, PolicyEngine, ApprovalHint, ApprovalResolution, AuditEvent, AuditSink, EvaluationResult, } from './types.js';
+export { defaultRiskClassifier, InMemoryAuditSink, PolicyError, RuleNotFoundError, ClassificationError, } from './types.js';
+export { createActionPolicy } from './policy.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { defaultRiskClassifier, InMemoryAuditSink, PolicyError, RuleNotFoundError, ClassificationError, } from './types.js';
+export { createActionPolicy } from './policy.js';

package/dist/policy.d.ts

@@ -0,0 +1,2 @@
+import { type PolicyEngine, type PolicyEngineConfig } from './types.js';
+export declare function createActionPolicy(config?: PolicyEngineConfig): PolicyEngine;

package/dist/policy.js

@@ -0,0 +1,129 @@
+import { nanoid } from 'nanoid';
+import { ClassificationError, PolicyError, RuleNotFoundError, defaultRiskClassifier, } from './types.js';
+const VALID_RISK_LEVELS = new Set(['low', 'medium', 'high', 'critical']);
+/** Cap for the bounded eval-record map used for approval correlation. */
+const EVAL_RECORD_CAP = 1000;
+export function createActionPolicy(config) {
+    // ── Internal state ────────────────────────────────────────────────────────
+    const rules = [];
+    let registrationCounter = 0;
+    const resolvedClassifier = config?.classifier ?? defaultRiskClassifier;
+    const resolvedFallback = config?.fallbackDecision ?? 'require_approval';
+    const resolvedAuditSink = config?.auditSink ?? { record: async () => { } };
+    // Bounded map for approval correlation (reconciliation Decision 1).
+    const evalRecords = new Map();
+    const evalRecordOrder = [];
+    // ── Helpers ───────────────────────────────────────────────────────────────
+    function getSortedRules() {
+        return [...rules].sort((a, b) => {
+            const pa = a.rule.priority ?? 100;
+            const pb = b.rule.priority ?? 100;
+            if (pa !== pb)
+                return pa - pb;
+            return a.registrationIndex - b.registrationIndex;
+        });
+    }
+    function storeEvalRecord(id, record) {
+        evalRecords.set(id, record);
+        evalRecordOrder.push(id);
+        if (evalRecordOrder.length > EVAL_RECORD_CAP) {
+            const oldest = evalRecordOrder.shift();
+            evalRecords.delete(oldest);
+        }
+    }
+    // ── Engine ────────────────────────────────────────────────────────────────
+    return {
+        registerRule(rule) {
+            if (rules.some((r) => r.rule.id === rule.id)) {
+                // Decision 5: throw PolicyError, not RuleNotFoundError
+                throw new PolicyError(`Rule with id '${rule.id}' is already registered.`);
+            }
+            rules.push({ rule, registrationIndex: registrationCounter++ });
+        },
+        removeRule(ruleId) {
+            const index = rules.findIndex((r) => r.rule.id === ruleId);
+            if (index === -1) {
+                throw new RuleNotFoundError(ruleId);
+            }
+            rules.splice(index, 1);
+        },
+        listRules() {
+            return getSortedRules().map((r) => r.rule);
+        },
+        async evaluate(action) {
+            // 1. Classify risk — validate return value (reconciliation Decision 2)
+            let riskLevel;
+            try {
+                const raw = await resolvedClassifier.classify(action);
+                if (!VALID_RISK_LEVELS.has(raw)) {
+                    throw new ClassificationError(`Classifier returned invalid risk level '${raw}' for action '${action.id}'. ` +
+                        `Expected one of: low, medium, high, critical.`);
+                }
+                riskLevel = raw;
+            }
+            catch (err) {
+                if (err instanceof ClassificationError)
+                    throw err;
+                throw new ClassificationError(`Classifier failed for action '${action.id}'`, err);
+            }
+            // 2. Build evaluation context (no workspaceId per reconciliation Decision 4)
+            const context = {
+                sessionId: action.sessionId,
+                userId: action.userId,
+                proactive: action.proactive,
+                metadata: action.metadata,
+            };
+            // 3. Evaluate rules in priority order (first-match-wins)
+            let decision = null;
+            for (const { rule } of getSortedRules()) {
+                try {
+                    const result = await rule.evaluate(action, riskLevel, context);
+                    if (result !== null) {
+                        decision = result;
+                        break;
+                    }
+                }
+                catch (err) {
+                    throw new PolicyError(`Rule '${rule.id}' threw during evaluation`, err);
+                }
+            }
+            // 4. Apply fallback when no rule matched
+            if (decision === null) {
+                decision = {
+                    action: resolvedFallback,
+                    ruleId: 'fallback',
+                    riskLevel,
+                    reason: 'No registered rule matched this action.',
+                };
+            }
+            // 5. Record audit event
+            const auditEventId = nanoid();
+            const auditEvent = {
+                id: auditEventId,
+                action,
+                riskLevel,
+                decision,
+                evaluatedAt: new Date().toISOString(),
+            };
+            await resolvedAuditSink.record(auditEvent);
+            // 6. Store eval record for approval correlation (bounded, reconciliation Decision 1)
+            storeEvalRecord(auditEventId, { action, riskLevel, decision });
+            return { decision, auditEventId };
+        },
+        async recordApproval(auditEventId, resolution) {
+            const record = evalRecords.get(auditEventId);
+            if (!record) {
+                throw new PolicyError(`Unknown auditEventId '${auditEventId}'. Cannot record approval resolution.`);
+            }
+            const approvalAuditEvent = {
+                id: nanoid(),
+                action: record.action,
+                riskLevel: record.riskLevel,
+                decision: record.decision,
+                evaluatedAt: new Date().toISOString(),
+                approval: resolution,
+            };
+            await resolvedAuditSink.record(approvalAuditEvent);
+        },
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,100 @@
+export interface Action {
+    id: string;
+    type: string;
+    description: string;
+    sessionId: string;
+    userId: string;
+    proactive: boolean;
+    metadata?: Record<string, unknown>;
+}
+export type RiskLevel = 'low' | 'medium' | 'high' | 'critical';
+export interface RiskClassifier {
+    classify(action: Action): RiskLevel | Promise<RiskLevel>;
+}
+export declare const defaultRiskClassifier: RiskClassifier;
+export interface PolicyEvaluationContext {
+    sessionId: string;
+    userId: string;
+    proactive: boolean;
+    metadata?: Record<string, unknown>;
+}
+export interface ApprovalHint {
+    approver?: string;
+    timeoutMs?: number;
+    prompt?: string;
+}
+export interface PolicyDecision {
+    action: 'allow' | 'deny' | 'require_approval' | 'escalate';
+    ruleId: string;
+    riskLevel: RiskLevel;
+    reason?: string;
+    approvalHint?: ApprovalHint;
+}
+export interface PolicyRule {
+    id: string;
+    priority?: number;
+    evaluate(action: Action, riskLevel: RiskLevel, context: PolicyEvaluationContext): PolicyDecision | null | Promise<PolicyDecision | null>;
+    description?: string;
+}
+export interface ApprovalResolution {
+    approved: boolean;
+    approvedBy?: string;
+    resolvedAt: string;
+    comment?: string;
+}
+export interface AuditEvent {
+    id: string;
+    action: Action;
+    riskLevel: RiskLevel;
+    decision: PolicyDecision;
+    evaluatedAt: string;
+    approval?: ApprovalResolution;
+}
+export interface AuditSink {
+    record(event: AuditEvent): Promise<void>;
+}
+/**
+ * Returned by evaluate(). Contains the policy decision and the audit event ID
+ * for approval correlation (reconciliation Decision 1).
+ */
+export interface EvaluationResult {
+    decision: PolicyDecision;
+    auditEventId: string;
+}
+export interface PolicyEngineConfig {
+    classifier?: RiskClassifier;
+    fallbackDecision?: PolicyDecision['action'];
+    auditSink?: AuditSink;
+}
+export interface PolicyEngine {
+    evaluate(action: Action): Promise<EvaluationResult>;
+    registerRule(rule: PolicyRule): void;
+    removeRule(ruleId: string): void;
+    listRules(): PolicyRule[];
+    /**
+     * Record an approval resolution against a prior evaluation's audit event.
+     * Emits a new AuditEvent to the sink with the original action, decision,
+     * and the provided ApprovalResolution populated in the `approval` field.
+     *
+     * The engine stores a bounded map of auditEventId -> { action, riskLevel, decision }
+     * from recent evaluations (cap: 1000, evicts oldest). Throws PolicyError if the
+     * auditEventId is unknown or has been evicted.
+     */
+    recordApproval(auditEventId: string, resolution: ApprovalResolution): Promise<void>;
+}
+export declare class PolicyError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class RuleNotFoundError extends PolicyError {
+    readonly ruleId: string;
+    constructor(ruleId: string);
+}
+export declare class ClassificationError extends PolicyError {
+    constructor(message: string, cause?: unknown);
+}
+export declare class InMemoryAuditSink implements AuditSink {
+    readonly events: AuditEvent[];
+    record(event: AuditEvent): Promise<void>;
+    clear(): void;
+}

package/dist/types.js

@@ -0,0 +1,37 @@
+// ─── Action and Classification ───────────────────────────────────────────────
+export const defaultRiskClassifier = {
+    classify: (_action) => 'medium',
+};
+// ─── Error Types ──────────────────────────────────────────────────────────────
+export class PolicyError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'PolicyError';
+    }
+}
+export class RuleNotFoundError extends PolicyError {
+    ruleId;
+    constructor(ruleId) {
+        super(`Policy rule not found: ${ruleId}`);
+        this.ruleId = ruleId;
+        this.name = 'RuleNotFoundError';
+    }
+}
+export class ClassificationError extends PolicyError {
+    constructor(message, cause) {
+        super(message, cause);
+        this.name = 'ClassificationError';
+    }
+}
+// ─── InMemoryAuditSink ────────────────────────────────────────────────────────
+export class InMemoryAuditSink {
+    events = [];
+    async record(event) {
+        this.events.push(event);
+    }
+    clear() {
+        this.events.length = 0;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-assistant/policy",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Action classification, gating, and audit contracts for agent assistants",
   "type": "module",
   "main": "./dist/index.js",