@det-acp/core 0.2.0

package/dist/engine/runtime.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Agent Gateway — the core entry point for governing agent actions.
+ *
+ * The gateway operates as a policy evaluation layer that does NOT execute
+ * actions itself. Instead, it evaluates each action request against the
+ * session's policy and records results reported by external executors.
+ *
+ * This is the main entry point for both the library SDK and the sidecar server.
+ *
+ * Flow:
+ *   Agent → gateway.evaluate(sessionId, action)
+ *     → policy check → allow/deny/gate
+ *   Agent executes action externally
+ *   Agent → gateway.recordResult(sessionId, actionId, result)
+ *     → evidence recorded in ledger
+ */
+import type { ActionRequest, ActionResult, EvaluateResponse, GateDecision, Session, SessionReport, SessionState } from '../types.js';
+import { ActionRegistry } from './action-registry.js';
+import { SessionManager } from './session.js';
+import { GateManager } from './gate.js';
+import { EvidenceLedger } from '../ledger/ledger.js';
+export interface GatewayConfig {
+    /** Directory for ledger files. One file per session. */
+    ledgerDir: string;
+    /** Optional: pre-configured action registry (for tool validation). */
+    registry?: ActionRegistry;
+    /** Optional: pre-configured gate manager. */
+    gateManager?: GateManager;
+    /** Callback invoked when a session needs human approval. */
+    onGateRequest?: (sessionId: string, actionId: string, gate: unknown) => void;
+    /** Callback invoked on each session state transition. */
+    onStateChange?: (sessionId: string, from: SessionState, to: SessionState) => void;
+    /** Callback invoked when a session is terminated. */
+    onSessionTerminated?: (sessionId: string, report: SessionReport) => void;
+}
+export declare class AgentGateway {
+    private registry;
+    private gateManager;
+    private sessionManager;
+    private config;
+    private constructor();
+    /**
+     * Create and initialize a new gateway instance.
+     */
+    static create(config: GatewayConfig): Promise<AgentGateway>;
+    /**
+     * Create a new governance session.
+     * Loads the policy from a file path or inline YAML string.
+     */
+    createSession(policySource: string, metadata?: Record<string, unknown>): Promise<Session>;
+    /**
+     * Evaluate a single action against the session's policy.
+     * Returns allow/deny/gate verdict without executing the action.
+     */
+    evaluate(sessionId: string, action: ActionRequest): Promise<EvaluateResponse>;
+    /**
+     * Record the result of an externally-executed action.
+     */
+    recordResult(sessionId: string, actionId: string, result: ActionResult): Promise<void>;
+    /**
+     * Resolve a pending gate (approve or reject).
+     */
+    resolveGate(sessionId: string, actionId: string, decision: GateDecision, respondedBy?: string, reason?: string): Promise<void>;
+    /**
+     * Terminate a session and get the final report.
+     */
+    terminateSession(sessionId: string, reason?: string): Promise<SessionReport>;
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId: string): Session | undefined;
+    /**
+     * List all sessions.
+     */
+    listSessions(): Session[];
+    /**
+     * Get a report for a session.
+     */
+    getSessionReport(sessionId: string): SessionReport;
+    /**
+     * Get the evidence ledger for a session.
+     */
+    getSessionLedger(sessionId: string): EvidenceLedger | undefined;
+    /**
+     * Get the action registry (for registering custom tool adapters).
+     */
+    getRegistry(): ActionRegistry;
+    /**
+     * Get the gate manager.
+     */
+    getGateManager(): GateManager;
+    /**
+     * Get the session manager.
+     */
+    getSessionManager(): SessionManager;
+    private loadPolicy;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/engine/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/engine/runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,YAAY,EAEZ,OAAO,EACP,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,cAAc,EAAyB,MAAM,sBAAsB,CAAC;AAC7E,OAAO,EAAE,cAAc,EAA6B,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,MAAM,WAAW,aAAa;IAC5B,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAC;IAC1B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,4DAA4D;IAC5D,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;IAC7E,yDAAyD;IACzD,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;IAClF,qDAAqD;IACrD,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;CAC1E;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,cAAc,CAAiB;IACvC,OAAO,CAAC,MAAM,CAAgB;IAE9B,OAAO;IAgBP;;OAEG;WACU,MAAM,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IASjE;;;OAGG;IACG,aAAa,CACjB,YAAY,EAAE,MAAM,EACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,OAAO,CAAC;IAKnB;;;OAGG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC;IAI5B;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC;IAIhB;;OAEG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAUhB;;OAEG;IACG,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC;IAQzB;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIlD;;OAEG;IACH,YAAY,IAAI,OAAO,EAAE;IAIzB;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa;IAIlD;;OAEG;IACH,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAI/D;;OAEG;IACH,WAAW,IAAI,cAAc;IAI7B;;OAEG;IACH,cAAc,IAAI,WAAW;IAI7B;;OAEG;IACH,iBAAiB,IAAI,cAAc;IAQnC,OAAO,CAAC,UAAU;CAOnB"}

package/dist/engine/runtime.js

@@ -0,0 +1,138 @@
+/**
+ * Agent Gateway — the core entry point for governing agent actions.
+ *
+ * The gateway operates as a policy evaluation layer that does NOT execute
+ * actions itself. Instead, it evaluates each action request against the
+ * session's policy and records results reported by external executors.
+ *
+ * This is the main entry point for both the library SDK and the sidecar server.
+ *
+ * Flow:
+ *   Agent → gateway.evaluate(sessionId, action)
+ *     → policy check → allow/deny/gate
+ *   Agent executes action externally
+ *   Agent → gateway.recordResult(sessionId, actionId, result)
+ *     → evidence recorded in ledger
+ */
+import { createDefaultRegistry } from './action-registry.js';
+import { SessionManager } from './session.js';
+import { GateManager } from './gate.js';
+import { loadPolicyFromFile, parsePolicyYaml } from '../policy/loader.js';
+export class AgentGateway {
+    registry;
+    gateManager;
+    sessionManager;
+    config;
+    constructor(config, registry) {
+        this.config = config;
+        this.registry = config.registry ?? registry;
+        this.gateManager = config.gateManager ?? new GateManager();
+        const sessionConfig = {
+            ledgerDir: config.ledgerDir,
+            gateManager: this.gateManager,
+            onGateRequest: config.onGateRequest,
+            onStateChange: config.onStateChange,
+            onSessionTerminated: config.onSessionTerminated,
+        };
+        this.sessionManager = new SessionManager(sessionConfig);
+    }
+    /**
+     * Create and initialize a new gateway instance.
+     */
+    static async create(config) {
+        const registry = config.registry ?? await createDefaultRegistry();
+        return new AgentGateway(config, registry);
+    }
+    // ---------------------------------------------------------------------------
+    // Session management
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new governance session.
+     * Loads the policy from a file path or inline YAML string.
+     */
+    async createSession(policySource, metadata) {
+        const policy = this.loadPolicy(policySource);
+        return this.sessionManager.createSession(policy, metadata);
+    }
+    /**
+     * Evaluate a single action against the session's policy.
+     * Returns allow/deny/gate verdict without executing the action.
+     */
+    async evaluate(sessionId, action) {
+        return this.sessionManager.evaluate(sessionId, action);
+    }
+    /**
+     * Record the result of an externally-executed action.
+     */
+    async recordResult(sessionId, actionId, result) {
+        return this.sessionManager.recordResult(sessionId, actionId, result);
+    }
+    /**
+     * Resolve a pending gate (approve or reject).
+     */
+    async resolveGate(sessionId, actionId, decision, respondedBy, reason) {
+        return this.sessionManager.resolveGate(sessionId, actionId, decision, respondedBy, reason);
+    }
+    /**
+     * Terminate a session and get the final report.
+     */
+    async terminateSession(sessionId, reason) {
+        return this.sessionManager.terminate(sessionId, reason);
+    }
+    // ---------------------------------------------------------------------------
+    // Introspection
+    // ---------------------------------------------------------------------------
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId) {
+        return this.sessionManager.getSession(sessionId);
+    }
+    /**
+     * List all sessions.
+     */
+    listSessions() {
+        return this.sessionManager.listSessions();
+    }
+    /**
+     * Get a report for a session.
+     */
+    getSessionReport(sessionId) {
+        return this.sessionManager.getReport(sessionId);
+    }
+    /**
+     * Get the evidence ledger for a session.
+     */
+    getSessionLedger(sessionId) {
+        return this.sessionManager.getLedger(sessionId);
+    }
+    /**
+     * Get the action registry (for registering custom tool adapters).
+     */
+    getRegistry() {
+        return this.registry;
+    }
+    /**
+     * Get the gate manager.
+     */
+    getGateManager() {
+        return this.gateManager;
+    }
+    /**
+     * Get the session manager.
+     */
+    getSessionManager() {
+        return this.sessionManager;
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    loadPolicy(policySource) {
+        // Check if it's inline YAML (contains newlines or colons)
+        if (policySource.includes('\n') || policySource.includes(':')) {
+            return parsePolicyYaml(policySource);
+        }
+        return loadPolicyFromFile(policySource);
+    }
+}
+//# sourceMappingURL=runtime.js.map

package/dist/engine/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../src/engine/runtime.ts"],"names":[],"mappings":"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"}

package/dist/engine/session.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Session Manager — manages the lifecycle of governance sessions.
+ *
+ * Replaces the batch Job model with a streaming, action-at-a-time model.
+ * Each session tracks an ongoing interaction between an agent and the
+ * control plane, evaluating actions one at a time against a policy.
+ *
+ * Key behaviors:
+ *  - evaluate(): checks a single action against policy + session state
+ *  - recordResult(): records the outcome of an externally-executed action
+ *  - terminate(): ends the session and generates a report
+ *  - Budget tracking is cumulative across the session
+ */
+import type { ActionRequest, ActionResult, EvaluateResponse, GateDecision, Policy, Session, SessionAction, SessionReport, SessionState } from '../types.js';
+import { GateManager } from './gate.js';
+import { EvidenceLedger } from '../ledger/ledger.js';
+export interface SessionManagerConfig {
+    /** Directory for ledger files. One file per session. */
+    ledgerDir: string;
+    /** Gate manager for handling approval flows */
+    gateManager: GateManager;
+    /** Callback invoked when a gate is requested */
+    onGateRequest?: (sessionId: string, actionId: string, gate: SessionAction['validation']['gate']) => void;
+    /** Callback invoked when session state changes */
+    onStateChange?: (sessionId: string, from: SessionState, to: SessionState) => void;
+    /** Callback invoked when a session is terminated */
+    onSessionTerminated?: (sessionId: string, report: SessionReport) => void;
+}
+export declare class SessionManager {
+    private sessions;
+    private config;
+    constructor(config: SessionManagerConfig);
+    /**
+     * Create a new session with a loaded policy.
+     */
+    createSession(policy: Policy, metadata?: Record<string, unknown>): Promise<Session>;
+    /**
+     * Evaluate a single action against the session's policy + state.
+     * Returns allow/deny/gate verdict without executing the action.
+     */
+    evaluate(sessionId: string, action: ActionRequest): Promise<EvaluateResponse>;
+    /**
+     * Record the result of an externally-executed action.
+     */
+    recordResult(sessionId: string, actionId: string, result: ActionResult): Promise<void>;
+    /**
+     * Resolve a gate (approve or reject a pending action).
+     */
+    resolveGate(sessionId: string, actionId: string, decision: GateDecision, respondedBy?: string, reason?: string): Promise<void>;
+    /**
+     * Terminate a session.
+     */
+    terminate(sessionId: string, reason?: string): Promise<SessionReport>;
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId: string): Session | undefined;
+    /**
+     * List all sessions.
+     */
+    listSessions(): Session[];
+    /**
+     * Get the ledger for a session.
+     */
+    getLedger(sessionId: string): EvidenceLedger | undefined;
+    /**
+     * Generate a report for a session.
+     */
+    getReport(sessionId: string): SessionReport;
+    private getEntryRequired;
+    private generateReport;
+    private getBudgetSnapshot;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/engine/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/engine/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EAGZ,gBAAgB,EAChB,YAAY,EACZ,MAAM,EACN,OAAO,EACP,aAAa,EACb,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,WAAW,oBAAoB;IACnC,wDAAwD;IACxD,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,WAAW,EAAE,WAAW,CAAC;IACzB,gDAAgD;IAChD,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC;IACzG,kDAAkD;IAClD,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,EAAE,YAAY,KAAK,IAAI,CAAC;IAClF,oDAAoD;IACpD,mBAAmB,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;CAC1E;AASD,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,MAAM,CAAuB;gBAEzB,MAAM,EAAE,oBAAoB;IAQxC;;OAEG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,OAAO,CAAC;IA4CnB;;;OAGG;IACG,QAAQ,CACZ,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,aAAa,GACpB,OAAO,CAAC,gBAAgB,CAAC;IAkI5B;;OAEG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,IAAI,CAAC;IAsChB;;OAEG;IACG,WAAW,CACf,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,YAAY,EACtB,WAAW,CAAC,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,IAAI,CAAC;IAgChB;;OAEG;IACG,SAAS,CACb,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,aAAa,CAAC;IAqCzB;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAIlD;;OAEG;IACH,YAAY,IAAI,OAAO,EAAE;IAIzB;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAIxD;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa;IAS3C,OAAO,CAAC,gBAAgB;IAQxB,OAAO,CAAC,cAAc;IAqCtB,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/engine/session.js

@@ -0,0 +1,343 @@
+/**
+ * Session Manager — manages the lifecycle of governance sessions.
+ *
+ * Replaces the batch Job model with a streaming, action-at-a-time model.
+ * Each session tracks an ongoing interaction between an agent and the
+ * control plane, evaluating actions one at a time against a policy.
+ *
+ * Key behaviors:
+ *  - evaluate(): checks a single action against policy + session state
+ *  - recordResult(): records the outcome of an externally-executed action
+ *  - terminate(): ends the session and generates a report
+ *  - Budget tracking is cumulative across the session
+ */
+import { nanoid } from 'nanoid';
+import { evaluateSessionAction } from '../policy/evaluator.js';
+import { EvidenceLedger } from '../ledger/ledger.js';
+export class SessionManager {
+    sessions = new Map();
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    // ---------------------------------------------------------------------------
+    // Session lifecycle
+    // ---------------------------------------------------------------------------
+    /**
+     * Create a new session with a loaded policy.
+     */
+    async createSession(policy, metadata) {
+        const id = nanoid(16);
+        const now = new Date().toISOString();
+        const budget = {
+            startedAt: Date.now(),
+            filesChanged: 0,
+            totalOutputBytes: 0,
+            retries: 0,
+            costUsd: 0,
+            actionsEvaluated: 0,
+            actionsDenied: 0,
+        };
+        const session = {
+            id,
+            policy,
+            state: 'active',
+            budget,
+            actions: [],
+            metadata,
+            createdAt: now,
+            updatedAt: now,
+        };
+        // Initialize ledger
+        const ledger = new EvidenceLedger(`${this.config.ledgerDir}/${id}.jsonl`);
+        await ledger.init();
+        await ledger.append(id, 'session:start', {
+            policy: policy.name,
+            version: policy.version,
+            metadata: metadata ?? {},
+        });
+        this.sessions.set(id, {
+            session,
+            ledger,
+            recentActionTimestamps: [],
+        });
+        return session;
+    }
+    /**
+     * Evaluate a single action against the session's policy + state.
+     * Returns allow/deny/gate verdict without executing the action.
+     */
+    async evaluate(sessionId, action) {
+        const entry = this.getEntryRequired(sessionId);
+        const { session, ledger } = entry;
+        // Generate action ID
+        const actionId = nanoid(12);
+        const actionIndex = session.actions.length;
+        // Evaluate against policy + session state
+        const result = evaluateSessionAction(action, session.policy, session);
+        // Update budget counters
+        session.budget.actionsEvaluated++;
+        if (result.verdict === 'deny') {
+            session.budget.actionsDenied++;
+        }
+        // Create session action record
+        const sessionAction = {
+            id: actionId,
+            index: actionIndex,
+            request: action,
+            validation: result,
+            timestamp: new Date().toISOString(),
+        };
+        session.actions.push(sessionAction);
+        session.updatedAt = new Date().toISOString();
+        // Track timestamp for rate limiting
+        entry.recentActionTimestamps.push(Date.now());
+        // Prune timestamps older than 2 minutes
+        const twoMinutesAgo = Date.now() - 120_000;
+        entry.recentActionTimestamps = entry.recentActionTimestamps.filter((t) => t >= twoMinutesAgo);
+        // Log to ledger
+        await ledger.append(sessionId, 'action:evaluate', {
+            actionId,
+            actionIndex,
+            tool: action.tool,
+            verdict: result.verdict,
+            reasons: result.reasons,
+        });
+        // Handle gate verdict
+        if (result.verdict === 'gate' && result.gate) {
+            const prevState = session.state;
+            session.state = 'paused';
+            this.config.onStateChange?.(sessionId, prevState, 'paused');
+            // Request approval through gate manager
+            const gateResponse = await this.config.gateManager.requestApproval(sessionId, actionId, action, result.gate);
+            await ledger.append(sessionId, 'gate:requested', {
+                actionId,
+                tool: action.tool,
+                gate: result.gate,
+            });
+            // If gate was auto-approved or handler-approved, resume
+            if (gateResponse.decision === 'approved') {
+                session.state = 'active';
+                this.config.onStateChange?.(sessionId, 'paused', 'active');
+                await ledger.append(sessionId, 'gate:approved', {
+                    actionId,
+                    respondedBy: gateResponse.respondedBy,
+                    reason: gateResponse.reason,
+                });
+                return {
+                    actionId,
+                    decision: 'allow',
+                    reasons: [`Gate approved: ${gateResponse.reason ?? 'approved'}`],
+                    budgetRemaining: this.getBudgetSnapshot(session),
+                    warnings: result.warnings,
+                };
+            }
+            if (gateResponse.decision === 'rejected') {
+                session.state = 'active';
+                this.config.onStateChange?.(sessionId, 'paused', 'active');
+                await ledger.append(sessionId, 'gate:rejected', {
+                    actionId,
+                    respondedBy: gateResponse.respondedBy,
+                    reason: gateResponse.reason,
+                });
+                return {
+                    actionId,
+                    decision: 'deny',
+                    reasons: [`Gate rejected: ${gateResponse.reason ?? 'rejected'}`],
+                    budgetRemaining: this.getBudgetSnapshot(session),
+                };
+            }
+            // Decision is 'pending' — session stays paused
+            this.config.onGateRequest?.(sessionId, actionId, result.gate);
+            return {
+                actionId,
+                decision: 'gate',
+                reasons: result.reasons,
+                gate: result.gate,
+                budgetRemaining: this.getBudgetSnapshot(session),
+            };
+        }
+        // Check if session should be auto-terminated (max denials exceeded)
+        if (session.policy.session?.max_denials != null &&
+            session.budget.actionsDenied >= session.policy.session.max_denials) {
+            await this.terminate(sessionId, `Maximum denial limit reached (${session.budget.actionsDenied})`);
+        }
+        return {
+            actionId,
+            decision: result.verdict,
+            reasons: result.reasons,
+            budgetRemaining: this.getBudgetSnapshot(session),
+            warnings: result.warnings,
+        };
+    }
+    /**
+     * Record the result of an externally-executed action.
+     */
+    async recordResult(sessionId, actionId, result) {
+        const entry = this.getEntryRequired(sessionId);
+        const { session, ledger } = entry;
+        const action = session.actions.find((a) => a.id === actionId);
+        if (!action) {
+            throw new Error(`Action "${actionId}" not found in session "${sessionId}"`);
+        }
+        if (action.result) {
+            throw new Error(`Result already recorded for action "${actionId}"`);
+        }
+        action.result = result;
+        session.updatedAt = new Date().toISOString();
+        // Update budget based on result
+        if (result.artifacts) {
+            for (const artifact of result.artifacts) {
+                if (artifact.type === 'diff' || artifact.type === 'checksum') {
+                    session.budget.filesChanged++;
+                }
+            }
+        }
+        if (result.output != null) {
+            const outputSize = JSON.stringify(result.output).length;
+            session.budget.totalOutputBytes += outputSize;
+        }
+        await ledger.append(sessionId, 'action:result', {
+            actionId,
+            tool: action.request.tool,
+            success: result.success,
+            durationMs: result.durationMs,
+            error: result.error,
+        });
+    }
+    /**
+     * Resolve a gate (approve or reject a pending action).
+     */
+    async resolveGate(sessionId, actionId, decision, respondedBy, reason) {
+        const entry = this.getEntryRequired(sessionId);
+        const { session, ledger } = entry;
+        // Resolve through gate manager
+        const response = this.config.gateManager.resolve(sessionId, actionId, decision, respondedBy, reason);
+        const eventType = decision === 'approved' ? 'gate:approved' : 'gate:rejected';
+        await ledger.append(sessionId, eventType, {
+            actionId,
+            respondedBy: response.respondedBy,
+            reason: response.reason,
+        });
+        // Resume session if no more pending gates
+        if (session.state === 'paused') {
+            const pending = this.config.gateManager.getPendingForSession(sessionId);
+            if (pending.length === 0) {
+                const prevState = session.state;
+                session.state = 'active';
+                session.updatedAt = new Date().toISOString();
+                this.config.onStateChange?.(sessionId, prevState, 'active');
+            }
+        }
+    }
+    /**
+     * Terminate a session.
+     */
+    async terminate(sessionId, reason) {
+        const entry = this.getEntryRequired(sessionId);
+        const { session, ledger } = entry;
+        const prevState = session.state;
+        session.state = 'terminated';
+        session.terminatedAt = new Date().toISOString();
+        session.terminationReason = reason;
+        session.updatedAt = session.terminatedAt;
+        this.config.onStateChange?.(sessionId, prevState, 'terminated');
+        // Clear any pending gates
+        this.config.gateManager.clearSession(sessionId);
+        const report = this.generateReport(session);
+        await ledger.append(sessionId, 'session:terminate', {
+            reason,
+            totalActions: report.totalActions,
+            allowed: report.allowed,
+            denied: report.denied,
+            gated: report.gated,
+            durationMs: report.durationMs,
+        });
+        await ledger.close();
+        this.config.onSessionTerminated?.(sessionId, report);
+        return report;
+    }
+    // ---------------------------------------------------------------------------
+    // Introspection
+    // ---------------------------------------------------------------------------
+    /**
+     * Get a session by ID.
+     */
+    getSession(sessionId) {
+        return this.sessions.get(sessionId)?.session;
+    }
+    /**
+     * List all sessions.
+     */
+    listSessions() {
+        return Array.from(this.sessions.values()).map((e) => e.session);
+    }
+    /**
+     * Get the ledger for a session.
+     */
+    getLedger(sessionId) {
+        return this.sessions.get(sessionId)?.ledger;
+    }
+    /**
+     * Generate a report for a session.
+     */
+    getReport(sessionId) {
+        const entry = this.getEntryRequired(sessionId);
+        return this.generateReport(entry.session);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    getEntryRequired(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry) {
+            throw new Error(`Session "${sessionId}" not found`);
+        }
+        return entry;
+    }
+    generateReport(session) {
+        const startedAt = new Date(session.createdAt).getTime();
+        const endedAt = session.terminatedAt
+            ? new Date(session.terminatedAt).getTime()
+            : Date.now();
+        let allowed = 0;
+        let denied = 0;
+        let gated = 0;
+        for (const action of session.actions) {
+            switch (action.validation.verdict) {
+                case 'allow':
+                    allowed++;
+                    break;
+                case 'deny':
+                    denied++;
+                    break;
+                case 'gate':
+                    gated++;
+                    break;
+            }
+        }
+        return {
+            sessionId: session.id,
+            state: session.state,
+            totalActions: session.actions.length,
+            allowed,
+            denied,
+            gated,
+            durationMs: endedAt - startedAt,
+            budgetUsed: { ...session.budget },
+            actions: session.actions,
+        };
+    }
+    getBudgetSnapshot(session) {
+        const elapsed = Date.now() - session.budget.startedAt;
+        return {
+            runtimeMs: elapsed,
+            filesChanged: session.budget.filesChanged,
+            totalOutputBytes: session.budget.totalOutputBytes,
+            actionsEvaluated: session.budget.actionsEvaluated,
+            actionsDenied: session.budget.actionsDenied,
+            costUsd: session.budget.costUsd,
+        };
+    }
+}
+//# sourceMappingURL=session.js.map