@nexus-ai-nexoralabs/cli 0.1.0

package/dist/tools/approvalGate.js

@@ -0,0 +1,137 @@
+/**
+ * NEXUS AI — Approval Gate
+ *
+ * Deterministic execution gate positioned immediately before tool execution.
+ * Evaluates human approval status for a given task step.
+ *
+ * Pipeline sequence:
+ *   Plan -> PlanValidator -> PermissionEngine -> ApprovalPolicyEngine -> ApprovalGate -> ToolExecutor
+ *
+ * SECURITY GUARANTEES:
+ *  - Missing, pending, rejected, expired, or cancelled approvals BLOCK execution completely.
+ *  - Approval DOES NOT grant authorization — PermissionEngine remains mandatory.
+ */
+import { Logger } from '../common/logger.js';
+export class ApprovalGate {
+    logger;
+    constructor(logLevel = 'info') {
+        this.logger = new Logger('ApprovalGate', logLevel);
+    }
+    /**
+     * Evaluate whether execution is permitted according to the approval request state.
+     */
+    evaluateGate(approvalRequest) {
+        if (!approvalRequest) {
+            this.logger.warn('Approval gate evaluation rejected: no approval request provided');
+            return {
+                allowed: false,
+                reason: 'No approval request found for step execution.',
+                status: 'rejected',
+                requiresUserAction: false,
+            };
+        }
+        const { approvalId, taskId, stepId, toolId, status, expiresAt } = approvalRequest;
+        // Check expiration if pending
+        if (status === 'pending') {
+            const nowIso = new Date().toISOString();
+            if (expiresAt <= nowIso) {
+                this.logger.warn(`Approval gate evaluation rejected: approval request '${approvalId}' expired`, {
+                    approvalId,
+                    taskId,
+                    stepId,
+                    toolId,
+                    expiresAt,
+                });
+                return {
+                    allowed: false,
+                    reason: `Human approval request '${approvalId}' expired at ${expiresAt}.`,
+                    approvalId,
+                    status: 'expired',
+                    requiresUserAction: false,
+                };
+            }
+            this.logger.info(`Approval gate evaluation halted: approval request '${approvalId}' is pending user decision`, {
+                approvalId,
+                taskId,
+                stepId,
+                toolId,
+            });
+            return {
+                allowed: false,
+                reason: `Human approval is pending for step '${stepId}' using tool '${toolId}'.`,
+                approvalId,
+                status: 'pending',
+                requiresUserAction: true,
+            };
+        }
+        if (status === 'approved') {
+            this.logger.info(`Approval gate evaluation passed: approval request '${approvalId}' is approved`, {
+                approvalId,
+                taskId,
+                stepId,
+                toolId,
+            });
+            return {
+                allowed: true,
+                reason: 'Human approval granted.',
+                approvalId,
+                status: 'approved',
+                requiresUserAction: false,
+            };
+        }
+        if (status === 'rejected') {
+            this.logger.warn(`Approval gate evaluation rejected: approval request '${approvalId}' was rejected`, {
+                approvalId,
+                taskId,
+                stepId,
+                toolId,
+            });
+            return {
+                allowed: false,
+                reason: `Human approval was rejected for step '${stepId}'.`,
+                approvalId,
+                status: 'rejected',
+                requiresUserAction: false,
+            };
+        }
+        if (status === 'expired') {
+            this.logger.warn(`Approval gate evaluation rejected: approval request '${approvalId}' is expired`, {
+                approvalId,
+                taskId,
+                stepId,
+                toolId,
+            });
+            return {
+                allowed: false,
+                reason: `Human approval request '${approvalId}' has expired.`,
+                approvalId,
+                status: 'expired',
+                requiresUserAction: false,
+            };
+        }
+        if (status === 'cancelled') {
+            this.logger.warn(`Approval gate evaluation rejected: approval request '${approvalId}' was cancelled`, {
+                approvalId,
+                taskId,
+                stepId,
+                toolId,
+            });
+            return {
+                allowed: false,
+                reason: `Human approval request '${approvalId}' was cancelled.`,
+                approvalId,
+                status: 'cancelled',
+                requiresUserAction: false,
+            };
+        }
+        this.logger.error(`Approval gate evaluation failed: invalid approval status '${String(status)}'`, { approvalId });
+        return {
+            allowed: false,
+            reason: `Invalid approval status '${String(status)}'.`,
+            approvalId,
+            status,
+            requiresUserAction: false,
+        };
+    }
+}
+//# sourceMappingURL=approvalGate.js.map

package/dist/tools/approvalGate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvalGate.js","sourceRoot":"","sources":["../../src/tools/approvalGate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,MAAM,EAAY,MAAM,qBAAqB,CAAC;AAEvD,MAAM,OAAO,YAAY;IACf,MAAM,CAAS;IAEvB,YAAY,WAAqB,MAAM;QACrC,IAAI,CAAC,MAAM,GAAG,IAAI,MAAM,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;OAEG;IACH,YAAY,CAAC,eAAuC;QAClD,IAAI,CAAC,eAAe,EAAE,CAAC;YACrB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,iEAAiE,CAAC,CAAC;YACpF,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,+CAA+C;gBACvD,MAAM,EAAE,UAAU;gBAClB,kBAAkB,EAAE,KAAK;aAC1B,CAAC;QACJ,CAAC;QAED,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG,eAAe,CAAC;QAElF,8BAA8B;QAC9B,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;YACxC,IAAI,SAAS,IAAI,MAAM,EAAE,CAAC;gBACxB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,UAAU,WAAW,EAAE;oBAC9F,UAAU;oBACV,MAAM;oBACN,MAAM;oBACN,MAAM;oBACN,SAAS;iBACV,CAAC,CAAC;gBACH,OAAO;oBACL,OAAO,EAAE,KAAK;oBACd,MAAM,EAAE,2BAA2B,UAAU,gBAAgB,SAAS,GAAG;oBACzE,UAAU;oBACV,MAAM,EAAE,SAAS;oBACjB,kBAAkB,EAAE,KAAK;iBAC1B,CAAC;YACJ,CAAC;YAED,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sDAAsD,UAAU,4BAA4B,EAAE;gBAC7G,UAAU;gBACV,MAAM;gBACN,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,uCAAuC,MAAM,iBAAiB,MAAM,IAAI;gBAChF,UAAU;gBACV,MAAM,EAAE,SAAS;gBACjB,kBAAkB,EAAE,IAAI;aACzB,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,sDAAsD,UAAU,eAAe,EAAE;gBAChG,UAAU;gBACV,MAAM;gBACN,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,MAAM,EAAE,yBAAyB;gBACjC,UAAU;gBACV,MAAM,EAAE,UAAU;gBAClB,kBAAkB,EAAE,KAAK;aAC1B,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,UAAU,EAAE,CAAC;YAC1B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,UAAU,gBAAgB,EAAE;gBACnG,UAAU;gBACV,MAAM;gBACN,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,yCAAyC,MAAM,IAAI;gBAC3D,UAAU;gBACV,MAAM,EAAE,UAAU;gBAClB,kBAAkB,EAAE,KAAK;aAC1B,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,UAAU,cAAc,EAAE;gBACjG,UAAU;gBACV,MAAM;gBACN,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,2BAA2B,UAAU,gBAAgB;gBAC7D,UAAU;gBACV,MAAM,EAAE,SAAS;gBACjB,kBAAkB,EAAE,KAAK;aAC1B,CAAC;QACJ,CAAC;QAED,IAAI,MAAM,KAAK,WAAW,EAAE,CAAC;YAC3B,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,wDAAwD,UAAU,iBAAiB,EAAE;gBACpG,UAAU;gBACV,MAAM;gBACN,MAAM;gBACN,MAAM;aACP,CAAC,CAAC;YACH,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,MAAM,EAAE,2BAA2B,UAAU,kBAAkB;gBAC/D,UAAU;gBACV,MAAM,EAAE,WAAW;gBACnB,kBAAkB,EAAE,KAAK;aAC1B,CAAC;QACJ,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,6DAA6D,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;QAClH,OAAO;YACL,OAAO,EAAE,KAAK;YACd,MAAM,EAAE,4BAA4B,MAAM,CAAC,MAAM,CAAC,IAAI;YACtD,UAAU;YACV,MAAM;YACN,kBAAkB,EAAE,KAAK;SAC1B,CAAC;IACJ,CAAC;CACF"}

package/dist/tools/approvalPolicyEngine.d.ts

@@ -0,0 +1,32 @@
+/**
+ * NEXUS AI — Approval Policy Engine
+ *
+ * Deterministically classifies planned tool actions according to risk and policy
+ * rules to determine whether explicit human approval is required before execution.
+ *
+ * Security Invariant:
+ *  - Default behavior is SAFE.
+ *  - Unknown tools, disabled tools, or unrecognized risk levels default to POLICY_DENIED or REQUIRES_APPROVAL.
+ *  - No permissive fallbacks exist.
+ */
+import type { ToolDefinition, ToolCapability } from './types.js';
+import type { ApprovalDecision, ApprovalPolicyConfig } from './approvalTypes.js';
+import { LogLevel } from '../common/logger.js';
+export declare class ApprovalPolicyEngine {
+    private config;
+    private logger;
+    constructor(config?: Partial<ApprovalPolicyConfig>, logLevel?: LogLevel);
+    /**
+     * Deterministically evaluate whether a requested tool action requires human approval.
+     */
+    evaluate(toolDef: ToolDefinition | null, requestedCapability: ToolCapability): ApprovalDecision;
+    /**
+     * Get current approval policy configuration.
+     */
+    getConfig(): Readonly<ApprovalPolicyConfig>;
+    /**
+     * Update approval policy configuration.
+     */
+    updateConfig(config: Partial<ApprovalPolicyConfig>): void;
+}
+//# sourceMappingURL=approvalPolicyEngine.d.ts.map

package/dist/tools/approvalPolicyEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvalPolicyEngine.d.ts","sourceRoot":"","sources":["../../src/tools/approvalPolicyEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,cAAc,EAAiB,MAAM,YAAY,CAAC;AAChF,OAAO,KAAK,EACV,gBAAgB,EAChB,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,CAAC,EAAE,OAAO,CAAC,oBAAoB,CAAC,EAAE,QAAQ,GAAE,QAAiB;IAK/E;;OAEG;IACH,QAAQ,CACN,OAAO,EAAE,cAAc,GAAG,IAAI,EAC9B,mBAAmB,EAAE,cAAc,GAClC,gBAAgB;IAiHnB;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,oBAAoB,CAAC;IAI3C;;OAEG;IACH,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,oBAAoB,CAAC,GAAG,IAAI;CAG1D"}

package/dist/tools/approvalPolicyEngine.js

@@ -0,0 +1,141 @@
+/**
+ * NEXUS AI — Approval Policy Engine
+ *
+ * Deterministically classifies planned tool actions according to risk and policy
+ * rules to determine whether explicit human approval is required before execution.
+ *
+ * Security Invariant:
+ *  - Default behavior is SAFE.
+ *  - Unknown tools, disabled tools, or unrecognized risk levels default to POLICY_DENIED or REQUIRES_APPROVAL.
+ *  - No permissive fallbacks exist.
+ */
+import { DEFAULT_APPROVAL_POLICY_CONFIG } from './approvalTypes.js';
+import { Logger } from '../common/logger.js';
+export class ApprovalPolicyEngine {
+    config;
+    logger;
+    constructor(config, logLevel = 'info') {
+        this.config = { ...DEFAULT_APPROVAL_POLICY_CONFIG, ...config };
+        this.logger = new Logger('ApprovalPolicyEngine', logLevel);
+    }
+    /**
+     * Deterministically evaluate whether a requested tool action requires human approval.
+     */
+    evaluate(toolDef, requestedCapability) {
+        // 1. Tool availability check
+        if (!toolDef) {
+            this.logger.warn(`Approval policy evaluation failed: tool definition is null`);
+            return {
+                requiresApproval: false,
+                decision: 'POLICY_DENIED',
+                reason: 'Tool is not registered in the system tool registry.',
+                riskLevel: 'high',
+            };
+        }
+        if (!toolDef.enabled) {
+            this.logger.warn(`Approval policy evaluation failed: tool '${toolDef.id}' is disabled`);
+            return {
+                requiresApproval: false,
+                decision: 'POLICY_DENIED',
+                reason: `Tool '${toolDef.id}' is disabled in the system tool registry.`,
+                riskLevel: toolDef.riskLevel || 'high',
+            };
+        }
+        // 2. Capability verification
+        if (!toolDef.requiredPermissions.includes(requestedCapability)) {
+            this.logger.warn(`Approval policy evaluation failed: tool '${toolDef.id}' does not support capability '${requestedCapability}'`);
+            return {
+                requiresApproval: false,
+                decision: 'POLICY_DENIED',
+                reason: `Tool '${toolDef.id}' does not declare requested capability '${requestedCapability}'.`,
+                riskLevel: toolDef.riskLevel || 'high',
+            };
+        }
+        const riskLevel = toolDef.riskLevel;
+        // 3. Risk-based deterministic policy decision
+        switch (riskLevel) {
+            case 'low':
+                if (this.config.autoApproveLowRisk) {
+                    return {
+                        requiresApproval: false,
+                        decision: 'AUTO_APPROVED',
+                        reason: 'Low-risk operation automatically approved by security policy.',
+                        riskLevel: 'low',
+                    };
+                }
+                return {
+                    requiresApproval: true,
+                    decision: 'REQUIRES_APPROVAL',
+                    reason: 'Low-risk operation requires explicit human approval per current policy configuration.',
+                    riskLevel: 'low',
+                };
+            case 'medium':
+                if (this.config.requireApprovalForMediumRisk) {
+                    return {
+                        requiresApproval: true,
+                        decision: 'REQUIRES_APPROVAL',
+                        reason: 'Medium-risk tool action requires explicit human approval.',
+                        riskLevel: 'medium',
+                    };
+                }
+                return {
+                    requiresApproval: false,
+                    decision: 'AUTO_APPROVED',
+                    reason: 'Medium-risk operation auto-approved by custom policy configuration.',
+                    riskLevel: 'medium',
+                };
+            case 'high':
+                if (this.config.requireApprovalForHighRisk) {
+                    return {
+                        requiresApproval: true,
+                        decision: 'REQUIRES_APPROVAL',
+                        reason: 'High-risk tool action requires explicit human approval.',
+                        riskLevel: 'high',
+                    };
+                }
+                return {
+                    requiresApproval: false,
+                    decision: 'AUTO_APPROVED',
+                    reason: 'High-risk operation auto-approved by custom policy configuration.',
+                    riskLevel: 'high',
+                };
+            case 'critical':
+                if (this.config.requireApprovalForCriticalRisk) {
+                    return {
+                        requiresApproval: true,
+                        decision: 'REQUIRES_APPROVAL',
+                        reason: 'Critical-risk tool action requires explicit human approval.',
+                        riskLevel: 'critical',
+                    };
+                }
+                return {
+                    requiresApproval: false,
+                    decision: 'POLICY_DENIED',
+                    reason: 'Critical-risk operation denied by default policy.',
+                    riskLevel: 'critical',
+                };
+            default:
+                // Unknown risk level handling — default safe policy is DENY or REQUIRE APPROVAL
+                this.logger.warn(`Unknown risk level '${String(riskLevel)}' encountered for tool '${toolDef.id}'`);
+                return {
+                    requiresApproval: true,
+                    decision: 'REQUIRES_APPROVAL',
+                    reason: `Unknown risk level '${String(riskLevel)}' requires explicit human approval.`,
+                    riskLevel: 'high',
+                };
+        }
+    }
+    /**
+     * Get current approval policy configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Update approval policy configuration.
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+}
+//# sourceMappingURL=approvalPolicyEngine.js.map

package/dist/tools/approvalPolicyEngine.js.map

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

package/dist/tools/approvalTypes.d.ts

@@ -0,0 +1,67 @@
+/**
+ * NEXUS AI — P5-F: Human Approval & Execution Control Types
+ *
+ * Provides normalized data contracts, states, policy configurations,
+ * and decision structures for the human approval system.
+ */
+import type { ToolCapability, ToolRiskLevel } from './types.js';
+export type ApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired' | 'cancelled';
+/**
+ * Terminal approval states that must never be reopened.
+ */
+export declare const TERMINAL_APPROVAL_STATES: ReadonlySet<ApprovalStatus>;
+/**
+ * Structured approval request metadata.
+ * Note: Secrets, full prompts, model responses, and raw document contents are EXCLUDED.
+ */
+export interface ApprovalRequest {
+    approvalId: string;
+    taskId: string;
+    planId?: string;
+    stepId: string;
+    toolId: string;
+    riskLevel: ToolRiskLevel;
+    requestedCapability: ToolCapability;
+    status: ApprovalStatus;
+    createdAt: string;
+    resolvedAt?: string;
+    expiresAt: string;
+    decisionReason?: string;
+}
+export interface CreateApprovalRequestDto {
+    taskId: string;
+    planId?: string;
+    stepId: string;
+    toolId: string;
+    riskLevel?: ToolRiskLevel;
+    requestedCapability: ToolCapability;
+    ttlMs?: number;
+}
+export interface ApprovalPolicyConfig {
+    /** If true, low-risk operations (e.g. read-only filesystem) are auto-approved. Default: true. */
+    autoApproveLowRisk: boolean;
+    /** Require explicit approval for medium-risk operations. Default: true. */
+    requireApprovalForMediumRisk: boolean;
+    /** Require explicit approval for high-risk operations. Default: true. */
+    requireApprovalForHighRisk: boolean;
+    /** Require explicit approval for critical-risk operations. Default: true. */
+    requireApprovalForCriticalRisk: boolean;
+    /** Default lifetime of a pending approval request in milliseconds. Default: 300,000 (5 minutes). */
+    defaultTtlMs: number;
+}
+export declare const DEFAULT_APPROVAL_POLICY_CONFIG: ApprovalPolicyConfig;
+export type ApprovalPolicyDecisionCode = 'AUTO_APPROVED' | 'REQUIRES_APPROVAL' | 'POLICY_DENIED';
+export interface ApprovalDecision {
+    requiresApproval: boolean;
+    decision: ApprovalPolicyDecisionCode;
+    reason: string;
+    riskLevel: ToolRiskLevel;
+}
+export interface ApprovalGateResult {
+    allowed: boolean;
+    reason: string;
+    approvalId?: string;
+    status: ApprovalStatus;
+    requiresUserAction: boolean;
+}
+//# sourceMappingURL=approvalTypes.d.ts.map

package/dist/tools/approvalTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvalTypes.d.ts","sourceRoot":"","sources":["../../src/tools/approvalTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAE3F;;GAEG;AACH,eAAO,MAAM,wBAAwB,EAAE,WAAW,CAAC,cAAc,CAK/D,CAAC;AAEH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;IACzB,mBAAmB,EAAE,cAAc,CAAC;IACpC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,aAAa,CAAC;IAC1B,mBAAmB,EAAE,cAAc,CAAC;IACpC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,iGAAiG;IACjG,kBAAkB,EAAE,OAAO,CAAC;IAC5B,2EAA2E;IAC3E,4BAA4B,EAAE,OAAO,CAAC;IACtC,yEAAyE;IACzE,0BAA0B,EAAE,OAAO,CAAC;IACpC,6EAA6E;IAC7E,8BAA8B,EAAE,OAAO,CAAC;IACxC,oGAAoG;IACpG,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,8BAA8B,EAAE,oBAM5C,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG,eAAe,GAAG,mBAAmB,GAAG,eAAe,CAAC;AAEjG,MAAM,WAAW,gBAAgB;IAC/B,gBAAgB,EAAE,OAAO,CAAC;IAC1B,QAAQ,EAAE,0BAA0B,CAAC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,aAAa,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,kBAAkB,EAAE,OAAO,CAAC;CAC7B"}

package/dist/tools/approvalTypes.js

@@ -0,0 +1,23 @@
+/**
+ * NEXUS AI — P5-F: Human Approval & Execution Control Types
+ *
+ * Provides normalized data contracts, states, policy configurations,
+ * and decision structures for the human approval system.
+ */
+/**
+ * Terminal approval states that must never be reopened.
+ */
+export const TERMINAL_APPROVAL_STATES = new Set([
+    'approved',
+    'rejected',
+    'expired',
+    'cancelled',
+]);
+export const DEFAULT_APPROVAL_POLICY_CONFIG = {
+    autoApproveLowRisk: true,
+    requireApprovalForMediumRisk: true,
+    requireApprovalForHighRisk: true,
+    requireApprovalForCriticalRisk: true,
+    defaultTtlMs: 5 * 60 * 1000, // 5 minutes
+};
+//# sourceMappingURL=approvalTypes.js.map

package/dist/tools/approvalTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approvalTypes.js","sourceRoot":"","sources":["../../src/tools/approvalTypes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH;;GAEG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAgC,IAAI,GAAG,CAAC;IAC3E,UAAU;IACV,UAAU;IACV,SAAS;IACT,WAAW;CACZ,CAAC,CAAC;AA4CH,MAAM,CAAC,MAAM,8BAA8B,GAAyB;IAClE,kBAAkB,EAAE,IAAI;IACxB,4BAA4B,EAAE,IAAI;IAClC,0BAA0B,EAAE,IAAI;IAChC,8BAA8B,EAAE,IAAI;IACpC,YAAY,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,YAAY;CAC1C,CAAC"}

package/dist/tools/index.d.ts

@@ -0,0 +1,72 @@
+import type { SubsystemStatus } from '../storage/index.js';
+import type { AgentTaskService } from '../orchestration/agentTaskService.js';
+import type { ToolDefinition, ToolInvocationRequest, ToolInvocationResult, ToolExecutionRequest, ToolExecutionResult, PermissionPolicy } from './types.js';
+import { ToolRegistry } from './toolRegistry.js';
+import { PermissionEngine } from './permissionEngine.js';
+import { ToolExecutor } from './toolExecutor.js';
+import { LogLevel } from '../common/logger.js';
+export * from './types.js';
+export * from './approvalTypes.js';
+export * from './adapters/terminalTypes.js';
+export { ToolRegistry } from './toolRegistry.js';
+export { PermissionEngine } from './permissionEngine.js';
+export { ToolExecutor } from './toolExecutor.js';
+export { ApprovalPolicyEngine } from './approvalPolicyEngine.js';
+export { ApprovalGate } from './approvalGate.js';
+export { FilesystemAdapter, ReadonlyFilesystemAdapter, calculateContentHash, isSecretFile, generateUnifiedDiff } from './adapters/filesystemAdapter.js';
+export { TerminalAdapter, buildSanitizedEnv, validateWorkspaceCwd } from './adapters/terminalAdapter.js';
+export { TerminalCommandPolicy } from './adapters/terminalCommandPolicy.js';
+export interface IToolGateway {
+    initialize(taskService?: AgentTaskService, workspaceRoot?: string): Promise<SubsystemStatus>;
+    getStatus(): SubsystemStatus;
+    authorizeInvocation(request: ToolInvocationRequest): ToolInvocationResult;
+    executeTool(request: ToolExecutionRequest): ToolExecutionResult | Promise<ToolExecutionResult>;
+}
+export declare const READONLY_FILESYSTEM_TOOL_DEFINITION: ToolDefinition;
+export declare const WORKSPACE_TREE_TOOL_DEFINITION: ToolDefinition;
+export declare const CODE_SEARCH_TOOL_DEFINITION: ToolDefinition;
+export declare const FILESYSTEM_WRITE_TOOL_DEFINITION: ToolDefinition;
+export declare const FILESYSTEM_EDIT_TOOL_DEFINITION: ToolDefinition;
+export declare const TERMINAL_EXECUTE_TOOL_DEFINITION: ToolDefinition;
+export declare class ToolGateway implements IToolGateway {
+    private initialized;
+    private workspaceRoot;
+    registry: ToolRegistry;
+    permissionEngine: PermissionEngine;
+    executor: ToolExecutor | null;
+    private taskService;
+    private logger;
+    private logLevel;
+    constructor(policy?: PermissionPolicy, logLevel?: LogLevel);
+    initialize(taskService?: AgentTaskService, workspaceRoot?: string): Promise<SubsystemStatus>;
+    /**
+     * Register a tool definition with the central registry.
+     */
+    registerTool(definition: ToolDefinition): void;
+    /**
+     * Retrieve a registered tool by ID.
+     */
+    getTool(id: string): ToolDefinition | null;
+    /**
+     * Get workspace root directory path.
+     */
+    getWorkspaceRoot(): string;
+    /**
+     * List all registered tools.
+     */
+    listTools(): ToolDefinition[];
+    /**
+     * Authorize a tool invocation request against security policy and registry.
+     * NOTE: Returns authorization status ONLY. Does NOT execute code.
+     */
+    authorizeInvocation(request: ToolInvocationRequest): ToolInvocationResult;
+    /**
+     * Execute an authorized tool request through the secure execution pipeline:
+     * Agent Task -> Tool Invocation Request -> Tool Registry -> Permission Engine -> Authorization -> Workspace Validation -> Adapter -> Result.
+     *
+     * SECURITY GUARANTEE: If authorization is DENIED, execution is NEVER attempted.
+     */
+    executeTool(request: ToolExecutionRequest): ToolExecutionResult | Promise<ToolExecutionResult>;
+    getStatus(): SubsystemStatus;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

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