@nexus-ai-nexoralabs/cli 0.1.0

package/dist/orchestration/humanApprovalService.js

@@ -0,0 +1,346 @@
+/**
+ * NEXUS AI — Human Approval Service
+ *
+ * Orchestrates the human approval lifecycle: request creation, policy evaluation,
+ * task state machine integration (transition to/from awaiting_approval), expiration,
+ * resolution, and privacy-safe audit logging.
+ *
+ * SECURITY INVARIANTS:
+ *  - Terminal approval states (approved, rejected, expired, cancelled) CANNOT be reopened.
+ *  - Approval DOES NOT equal permission — authorization remains mandatory via PermissionEngine.
+ *  - Privacy-safe logging: Secrets, full prompts, model responses, and raw document contents are NEVER logged.
+ */
+import { TERMINAL_APPROVAL_STATES } from '../tools/approvalTypes.js';
+import { ApprovalPolicyEngine } from '../tools/approvalPolicyEngine.js';
+import { ApprovalGate } from '../tools/approvalGate.js';
+import { AgentStateMachine } from './agentStateMachine.js';
+import { Logger } from '../common/logger.js';
+export class HumanApprovalService {
+    taskService;
+    toolGateway;
+    repository;
+    policyEngine;
+    approvalGate;
+    logger;
+    // In-memory store fallback if repository is not passed
+    memoryStore = new Map();
+    constructor(taskService, toolGateway, repository, policyConfig, logLevel = 'info') {
+        this.taskService = taskService;
+        this.toolGateway = toolGateway;
+        this.repository = repository;
+        this.logger = new Logger('HumanApprovalService', logLevel);
+        this.policyEngine = new ApprovalPolicyEngine(policyConfig, logLevel);
+        this.approvalGate = new ApprovalGate(logLevel);
+    }
+    /**
+     * Create an approval request for a task step based on policy evaluation.
+     */
+    createApprovalRequest(dto) {
+        const { taskId, planId, stepId, toolId, requestedCapability, ttlMs } = dto;
+        const nowIso = new Date().toISOString();
+        const effectiveTtlMs = ttlMs ?? this.policyEngine.getConfig().defaultTtlMs;
+        const expiresAt = new Date(Date.now() + effectiveTtlMs).toISOString();
+        // 1. Resolve tool definition from ToolRegistry
+        const toolDef = this.toolGateway.getTool(toolId);
+        const riskLevel = dto.riskLevel ?? (toolDef ? toolDef.riskLevel : 'high');
+        // 2. Evaluate policy
+        const decision = this.policyEngine.evaluate(toolDef, requestedCapability);
+        let initialStatus = 'pending';
+        let decisionReason;
+        if (decision.decision === 'AUTO_APPROVED') {
+            initialStatus = 'approved';
+            decisionReason = decision.reason;
+        }
+        else if (decision.decision === 'POLICY_DENIED') {
+            initialStatus = 'rejected';
+            decisionReason = decision.reason;
+        }
+        const approvalId = `appr-${taskId}-${stepId}-${Date.now()}-${Math.random().toString(36).substring(2, 6)}`;
+        const request = {
+            approvalId,
+            taskId,
+            planId,
+            stepId,
+            toolId,
+            riskLevel,
+            requestedCapability,
+            status: initialStatus,
+            createdAt: nowIso,
+            resolvedAt: initialStatus !== 'pending' ? nowIso : undefined,
+            expiresAt,
+            decisionReason,
+        };
+        // 3. Persist request
+        this.saveApproval(request);
+        // 4. Privacy-safe audit log
+        this.logger.info(`Approval request created`, {
+            approvalId: request.approvalId,
+            taskId: request.taskId,
+            stepId: request.stepId,
+            toolId: request.toolId,
+            riskLevel: request.riskLevel,
+            status: request.status,
+            decision: decision.decision,
+            reasonCategory: decision.reason,
+            timestamp: request.createdAt,
+        });
+        // 5. Task state machine integration
+        let task = this.taskService.getTask(taskId);
+        if (initialStatus === 'pending') {
+            // Transition task state to 'awaiting_approval' if not already terminal or awaiting
+            if (task.state !== 'awaiting_approval' && !AgentStateMachine.isTerminal(task.state)) {
+                if (task.state === 'created' || task.state === 'verifying' || task.state === 'observing' || task.state === 'executing') {
+                    task = this.taskService.transitionTask(taskId, { targetState: 'planning', currentStep: stepId });
+                }
+                task = this.taskService.transitionTask(taskId, {
+                    targetState: 'awaiting_approval',
+                    currentStep: stepId,
+                });
+            }
+        }
+        else if (initialStatus === 'rejected') {
+            // Fail/cancel task on policy denial
+            if (!AgentStateMachine.isTerminal(task.state)) {
+                task = this.taskService.failTask(taskId, {
+                    errorCategory: 'POLICY_DENIED',
+                    currentStep: stepId,
+                });
+            }
+        }
+        return { approval: request, decision, task };
+    }
+    /**
+     * Resolve a pending approval request with explicit user decision ('approved' | 'rejected').
+     */
+    resolveApproval(approvalId, userDecision, reason) {
+        let approval = this.getApproval(approvalId);
+        if (!approval) {
+            this.logger.error(`Failed to resolve approval: approvalId '${approvalId}' not found`);
+            throw new Error(`Approval request '${approvalId}' not found.`);
+        }
+        // 1. Terminal state check — NO SILENT REOPENING OF TERMINAL APPROVALS!
+        if (TERMINAL_APPROVAL_STATES.has(approval.status)) {
+            const msg = `Transition rejected: approval '${approvalId}' is in terminal state '${approval.status}' and cannot be resolved to '${userDecision}'.`;
+            this.logger.warn(msg, { approvalId, status: approval.status });
+            return {
+                success: false,
+                approval,
+                task: this.taskService.getTask(approval.taskId),
+                error: msg,
+            };
+        }
+        const nowIso = new Date().toISOString();
+        // 2. Check expiration
+        if (approval.expiresAt <= nowIso) {
+            approval.status = 'expired';
+            approval.resolvedAt = nowIso;
+            approval.decisionReason = 'Approval request expired before decision was submitted.';
+            this.saveApproval(approval);
+            this.logger.warn(`Approval request '${approvalId}' expired before resolution`, { approvalId });
+            return {
+                success: false,
+                approval,
+                task: this.taskService.getTask(approval.taskId),
+                error: `Approval request '${approvalId}' has expired.`,
+            };
+        }
+        // 3. Check associated task state — cannot approve if task is terminal or cancelled
+        let task = this.taskService.getTask(approval.taskId);
+        if (AgentStateMachine.isTerminal(task.state) || task.state === 'cancelled') {
+            approval.status = 'cancelled';
+            approval.resolvedAt = nowIso;
+            approval.decisionReason = `Task '${task.id}' is in terminal state '${task.state}'.`;
+            this.saveApproval(approval);
+            this.logger.warn(`Cannot resolve approval '${approvalId}': associated task '${task.id}' is in terminal state '${task.state}'`, {
+                approvalId,
+                taskId: task.id,
+                taskState: task.state,
+            });
+            return {
+                success: false,
+                approval,
+                task,
+                error: `Associated task '${task.id}' is in terminal state '${task.state}'.`,
+            };
+        }
+        // 4. Perform resolution transition
+        const finalReason = reason ?? (userDecision === 'approved' ? 'User granted approval' : 'User rejected approval');
+        approval.status = userDecision;
+        approval.resolvedAt = nowIso;
+        approval.decisionReason = finalReason;
+        this.saveApproval(approval);
+        // 5. Privacy-safe audit log
+        this.logger.info(`Approval request resolved`, {
+            approvalId: approval.approvalId,
+            taskId: approval.taskId,
+            stepId: approval.stepId,
+            toolId: approval.toolId,
+            decision: userDecision,
+            reasonCategory: finalReason,
+            timestamp: nowIso,
+        });
+        // 6. Integrate with AgentStateMachine
+        if (userDecision === 'approved') {
+            // Transition task state: awaiting_approval -> executing
+            if (task.state === 'awaiting_approval') {
+                task = this.taskService.transitionTask(task.id, {
+                    targetState: 'executing',
+                    currentStep: approval.stepId,
+                });
+            }
+        }
+        else {
+            // Transition task state: awaiting_approval -> cancelled
+            if (task.state === 'awaiting_approval') {
+                task = this.taskService.cancelTask(task.id);
+            }
+        }
+        return {
+            success: true,
+            approval,
+            task,
+        };
+    }
+    /**
+     * Retrieve an approval request by ID, automatically evaluating expiration if pending.
+     */
+    getApproval(approvalId) {
+        let approval = null;
+        if (this.repository) {
+            approval = this.repository.findById(approvalId);
+        }
+        else {
+            approval = this.memoryStore.get(approvalId) ?? null;
+        }
+        if (!approval)
+            return null;
+        // Auto-expire if pending and past expiration timestamp
+        if (approval.status === 'pending') {
+            const nowIso = new Date().toISOString();
+            if (approval.expiresAt <= nowIso) {
+                approval.status = 'expired';
+                approval.resolvedAt = nowIso;
+                approval.decisionReason = 'Approval request expired.';
+                this.saveApproval(approval);
+            }
+        }
+        return approval;
+    }
+    /**
+     * Retrieve all approval requests for a task.
+     */
+    getApprovalsForTask(taskId) {
+        if (this.repository) {
+            return this.repository.findByTaskId(taskId);
+        }
+        return Array.from(this.memoryStore.values()).filter((a) => a.taskId === taskId);
+    }
+    /**
+     * List all pending approval requests.
+     */
+    listPendingApprovals() {
+        if (this.repository) {
+            return this.repository.listPending();
+        }
+        return Array.from(this.memoryStore.values()).filter((a) => a.status === 'pending');
+    }
+    /**
+     * Respond to an approval request with decision APPROVED or REJECTED.
+     */
+    respondToApproval(approvalId, params) {
+        const userDecision = params.decision.toLowerCase();
+        const result = this.resolveApproval(approvalId, userDecision, params.reason);
+        if (!result.success) {
+            throw new Error(result.error || `Failed to resolve approval request '${approvalId}'`);
+        }
+        return result.approval;
+    }
+    /**
+     * Evaluate the ApprovalGate for a given task step.
+     */
+    evaluateGateForStep(taskId, stepId) {
+        let request = null;
+        if (this.repository) {
+            request = this.repository.findPendingForStep(taskId, stepId);
+            if (!request) {
+                // Find latest resolved request for this step if not pending
+                const all = this.repository.findByTaskId(taskId).filter((a) => a.stepId === stepId);
+                if (all.length > 0) {
+                    request = all[all.length - 1];
+                }
+            }
+        }
+        else {
+            const all = Array.from(this.memoryStore.values()).filter((a) => a.taskId === taskId && a.stepId === stepId);
+            if (all.length > 0) {
+                request = all[all.length - 1];
+            }
+        }
+        return this.approvalGate.evaluateGate(request);
+    }
+    /**
+     * Expire all stale pending approvals.
+     */
+    expireStaleApprovals() {
+        const nowIso = new Date().toISOString();
+        if (this.repository) {
+            return this.repository.expireStaleApprovals(nowIso);
+        }
+        let count = 0;
+        for (const approval of this.memoryStore.values()) {
+            if (approval.status === 'pending' && approval.expiresAt <= nowIso) {
+                approval.status = 'expired';
+                approval.resolvedAt = nowIso;
+                approval.decisionReason = 'Approval request expired.';
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Invalidate/cancel all pending approvals for a task (e.g. when task is cancelled).
+     */
+    cancelApprovalsForTask(taskId, reason = 'Task cancelled') {
+        const nowIso = new Date().toISOString();
+        if (this.repository) {
+            return this.repository.cancelPendingForTask(taskId, nowIso, reason);
+        }
+        let count = 0;
+        for (const approval of this.memoryStore.values()) {
+            if (approval.taskId === taskId && approval.status === 'pending') {
+                approval.status = 'cancelled';
+                approval.resolvedAt = nowIso;
+                approval.decisionReason = reason;
+                count++;
+            }
+        }
+        return count;
+    }
+    /**
+     * Get policy engine instance.
+     */
+    getPolicyEngine() {
+        return this.policyEngine;
+    }
+    /**
+     * Get approval gate instance.
+     */
+    getGate() {
+        return this.approvalGate;
+    }
+    saveApproval(request) {
+        if (this.repository) {
+            const existing = this.repository.findById(request.approvalId);
+            if (existing) {
+                this.repository.updateStatus(request.approvalId, request.status, request.resolvedAt, request.decisionReason);
+            }
+            else {
+                this.repository.create(request);
+            }
+        }
+        else {
+            this.memoryStore.set(request.approvalId, request);
+        }
+    }
+}
+//# sourceMappingURL=humanApprovalService.js.map

package/dist/orchestration/humanApprovalService.js.map

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

package/dist/orchestration/index.d.ts

@@ -0,0 +1,47 @@
+import type { SubsystemStatus } from '../storage/index.js';
+import type { AgentTaskRepository } from '../storage/repositories/agentTaskRepository.js';
+import type { ApprovalRepository } from '../storage/repositories/approvalRepository.js';
+import type { ToolGateway } from '../tools/index.js';
+import type { ModelGateway } from '../intelligence/modelGateway.js';
+import { AgentTaskService } from './agentTaskService.js';
+import { AgentExecutionService } from './agentExecutionService.js';
+import { PlanSynthesisService } from './planner.js';
+import { HumanApprovalService } from './humanApprovalService.js';
+import { CodingAgentService } from './codingAgentService.js';
+import { LogLevel } from '../common/logger.js';
+export * from './types.js';
+export * from './codingAgentTypes.js';
+export { AgentStateMachine } from './agentStateMachine.js';
+export { AgentTaskService } from './agentTaskService.js';
+export { AgentExecutionService } from './agentExecutionService.js';
+export { PlanValidator, PlanSynthesisService } from './planner.js';
+export { HumanApprovalService } from './humanApprovalService.js';
+export { CodingAgentService } from './codingAgentService.js';
+export { CodingAgentDiscovery } from './codingAgentDiscovery.js';
+export { CodingAgentVerifier } from './codingAgentVerifier.js';
+export { CodingRepairService } from './codingRepairService.js';
+export type { CreateAgentTaskDto, TransitionAgentTaskDto, FailAgentTaskDto } from './agentTaskService.js';
+export type { TransitionResult } from './agentStateMachine.js';
+export interface IOrchestrator {
+    initialize(taskRepo: AgentTaskRepository, toolGateway?: ToolGateway, modelGateway?: ModelGateway, approvalRepo?: ApprovalRepository): Promise<SubsystemStatus>;
+    getStatus(): SubsystemStatus;
+    readonly tasks: AgentTaskService;
+    readonly execution?: AgentExecutionService;
+    readonly planner?: PlanSynthesisService;
+    readonly approvals?: HumanApprovalService;
+    readonly codingAgent?: CodingAgentService;
+}
+export declare class Orchestrator implements IOrchestrator {
+    private initialized;
+    private logger;
+    private logLevel;
+    tasks: AgentTaskService;
+    execution?: AgentExecutionService;
+    planner?: PlanSynthesisService;
+    approvals?: HumanApprovalService;
+    codingAgent?: CodingAgentService;
+    constructor(logLevel?: LogLevel);
+    initialize(taskRepo: AgentTaskRepository, toolGateway?: ToolGateway, modelGateway?: ModelGateway, approvalRepo?: ApprovalRepository): Promise<SubsystemStatus>;
+    getStatus(): SubsystemStatus;
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/orchestration/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAC3D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,gDAAgD,CAAC;AAC1F,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAiB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAEvD,cAAc,YAAY,CAAC;AAC3B,cAAc,uBAAuB,CAAC;AACtC,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAC/D,YAAY,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC1G,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,WAAW,EACzB,YAAY,CAAC,EAAE,YAAY,EAC3B,YAAY,CAAC,EAAE,kBAAkB,GAChC,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5B,SAAS,IAAI,eAAe,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAC3C,QAAQ,CAAC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,SAAS,CAAC,EAAE,oBAAoB,CAAC;IAC1C,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAC;CAC3C;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAW;IACpB,KAAK,EAAG,gBAAgB,CAAC;IACzB,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,OAAO,CAAC,EAAE,oBAAoB,CAAC;IAC/B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC,WAAW,CAAC,EAAE,kBAAkB,CAAC;gBAE5B,QAAQ,GAAE,QAAiB;IAKjC,UAAU,CACd,QAAQ,EAAE,mBAAmB,EAC7B,WAAW,CAAC,EAAE,WAAW,EACzB,YAAY,CAAC,EAAE,YAAY,EAC3B,YAAY,CAAC,EAAE,kBAAkB,GAChC,OAAO,CAAC,eAAe,CAAC;IAiC3B,SAAS,IAAI,eAAe;CAe7B"}

package/dist/orchestration/index.js

@@ -0,0 +1,67 @@
+import { AgentTaskService } from './agentTaskService.js';
+import { AgentExecutionService } from './agentExecutionService.js';
+import { PlanSynthesisService, PlanValidator } from './planner.js';
+import { HumanApprovalService } from './humanApprovalService.js';
+import { CodingAgentService } from './codingAgentService.js';
+import { Logger } from '../common/logger.js';
+export * from './types.js';
+export * from './codingAgentTypes.js';
+export { AgentStateMachine } from './agentStateMachine.js';
+export { AgentTaskService } from './agentTaskService.js';
+export { AgentExecutionService } from './agentExecutionService.js';
+export { PlanValidator, PlanSynthesisService } from './planner.js';
+export { HumanApprovalService } from './humanApprovalService.js';
+export { CodingAgentService } from './codingAgentService.js';
+export { CodingAgentDiscovery } from './codingAgentDiscovery.js';
+export { CodingAgentVerifier } from './codingAgentVerifier.js';
+export { CodingRepairService } from './codingRepairService.js';
+export class Orchestrator {
+    initialized = false;
+    logger;
+    logLevel;
+    tasks;
+    execution;
+    planner;
+    approvals;
+    codingAgent;
+    constructor(logLevel = 'info') {
+        this.logLevel = logLevel;
+        this.logger = new Logger('Orchestrator', logLevel);
+    }
+    async initialize(taskRepo, toolGateway, modelGateway, approvalRepo) {
+        this.tasks = new AgentTaskService(taskRepo, this.logLevel);
+        if (toolGateway) {
+            this.approvals = new HumanApprovalService(this.tasks, toolGateway, approvalRepo, undefined, this.logLevel);
+            this.logger.info('HumanApprovalService initialized');
+            this.execution = new AgentExecutionService(this.tasks, toolGateway, this.approvals, this.logLevel);
+            this.logger.info('AgentExecutionService initialized');
+            if (modelGateway) {
+                this.planner = new PlanSynthesisService(modelGateway, toolGateway, this.logLevel);
+                this.logger.info('PlanSynthesisService initialized');
+                const validator = new PlanValidator(toolGateway);
+                this.codingAgent = new CodingAgentService(this.tasks, toolGateway, this.execution, this.planner, validator, this.logLevel);
+                this.logger.info('CodingAgentService initialized');
+            }
+            else {
+                this.logger.info('PlanSynthesisService & CodingAgentService skipped (no ModelGateway provided)');
+            }
+        }
+        this.initialized = true;
+        return this.getStatus();
+    }
+    getStatus() {
+        const plannerReady = this.planner !== undefined;
+        const execReady = this.execution !== undefined;
+        const approvalReady = this.approvals !== undefined;
+        const codingAgentReady = this.codingAgent !== undefined;
+        return {
+            name: 'Orchestrator',
+            initialized: this.initialized,
+            status: this.initialized ? 'ok' : 'degraded',
+            message: this.initialized
+                ? `Orchestrator ready — execution: ${execReady ? 'yes' : 'no'}, planner: ${plannerReady ? 'yes' : 'no'}, approvals: ${approvalReady ? 'yes' : 'no'}, codingAgent: ${codingAgentReady ? 'yes' : 'no'}`
+                : 'Uninitialized',
+        };
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/orchestration/index.js.map

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

package/dist/orchestration/planner.d.ts

@@ -0,0 +1,105 @@
+/**
+ * NEXUS AI — P5-E: Agent Plan Synthesis & Controlled Task Orchestration
+ *
+ * Security invariant:
+ *   PlanSynthesisService is an UNTRUSTED PLAN GENERATOR.
+ *   It has NO execution authority — it cannot call tools, modify task state,
+ *   or interact with the PermissionEngine.
+ *   The AgentExecutionService (P5-D) remains the sole execution authority.
+ *
+ * Data flow:
+ *   PlanSynthesisService
+ *     → ModelGateway (plain-text inference only)
+ *     → PlanValidator (deterministic, stateless, no side effects)
+ *     → PlanSynthesisResult (validated AgentPlan or typed error)
+ *     → caller passes AgentPlan.steps to AgentExecutionService.runExecutionLoop()
+ */
+import type { ModelGateway } from '../intelligence/modelGateway.js';
+import type { ToolGateway } from '../tools/index.js';
+import type { PlanSynthesisOptions, PlanSynthesisResult, PlanValidationResult } from './types.js';
+import { LogLevel } from '../common/logger.js';
+/**
+ * Utility to determine if a task goal represents an authoring/creation request.
+ *
+ * Uses word-boundary regex matching to prevent substring false-positives
+ * (e.g. 'typescript' must not match keyword 'script').
+ */
+export declare function isAuthoringGoal(goalText: string): boolean;
+/**
+ * Deterministic, stateless plan validator.
+ *
+ * Validates a raw model-generated plan proposal against the tool registry.
+ * No side effects. No execution. Returns a typed validation result.
+ *
+ * Security note: model-generated params are treated as untrusted strings.
+ * The validator does NOT evaluate or execute any param values.
+ */
+export declare class PlanValidator {
+    private toolGateway;
+    constructor(toolGateway: ToolGateway);
+    /**
+     * Validate a raw parsed plan proposal.
+     * Returns a deterministic result with all errors (does not short-circuit on first error).
+     */
+    validate(proposal: unknown, taskId: string, maxSteps?: number, taskGoal?: string): PlanValidationResult;
+}
+/**
+ * PlanSynthesisService — generates structured, validated agent plans using
+ * the ModelGateway.
+ *
+ * SECURITY CONTRACT:
+ * - This service is an UNTRUSTED PLAN GENERATOR.
+ * - It has NO access to ToolExecutor, PermissionEngine, or AgentExecutionService.
+ * - It passes only plain-text prompts to the model and returns structured data.
+ * - The resulting AgentPlan carries zero execution authority.
+ * - Callers must pass plan.steps to AgentExecutionService.runExecutionLoop()
+ *   for execution, which enforces all authorization and sandbox boundaries.
+ */
+export declare class PlanSynthesisService {
+    private modelGateway;
+    private toolGateway;
+    private logger;
+    private validator;
+    private planVersion;
+    constructor(modelGateway: ModelGateway, toolGateway: ToolGateway, logLevel?: LogLevel);
+    /**
+     * Synthesize a validated agent plan for the given task.
+     *
+     * Flow:
+     *  1. Build a structured prompt listing available tools + constraints.
+     *  2. Invoke ModelGateway with a low-temperature generation call.
+     *  3. Extract the JSON plan block from the raw model output.
+     *  4. Parse the JSON.
+     *  5. Run PlanValidator (deterministic, no side effects).
+     *  6. If valid → assemble and return AgentPlan.
+     *     If invalid → return PlanSynthesisResult with typed errors.
+     */
+    synthesize(taskId: string, options: PlanSynthesisOptions): Promise<PlanSynthesisResult>;
+    /**
+     * Build the structured planner prompt.
+     * Lists available registered tools with their IDs and required capabilities
+     * so the model can only reference tools that exist in the registry.
+     */
+    private buildPlannerPrompt;
+    /**
+     * Build targeted retry prompt requesting JSON correction.
+     */
+    private buildRetryPlannerPrompt;
+    /**
+     * Extract a JSON object from raw model output.
+     *
+     * Handles:
+     *  - Pure JSON responses (ideal)
+     *  - JSON wrapped in markdown code fences (```json ... ```)
+     *  - Leading/trailing conversational text
+     *  - Sanitization of unescaped raw control characters (newlines/tabs) inside JSON strings
+     *
+     * Throws if no valid JSON object can be extracted.
+     */
+    private extractJsonFromModelOutput;
+    /**
+     * Repair unescaped raw newlines, tabs, and trailing commas inside JSON string candidate.
+     */
+    private sanitizeJsonString;
+}
+//# sourceMappingURL=planner.d.ts.map

package/dist/orchestration/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","sourceRoot":"","sources":["../../src/orchestration/planner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAGV,oBAAoB,EACpB,mBAAmB,EAEnB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAU,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAkEvD;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAsCzD;AAMD;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACZ,OAAO,CAAC,WAAW;gBAAX,WAAW,EAAE,WAAW;IAE5C;;;OAGG;IACH,QAAQ,CACN,QAAQ,EAAE,OAAO,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,GAAE,MAA0B,EACpC,QAAQ,CAAC,EAAE,MAAM,GAChB,oBAAoB;CAiPxB;AAMD;;;;;;;;;;;GAWG;AACH,qBAAa,oBAAoB;IAM7B,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,WAAW;IANrB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,SAAS,CAAgB;IACjC,OAAO,CAAC,WAAW,CAAK;gBAGd,YAAY,EAAE,YAAY,EAC1B,WAAW,EAAE,WAAW,EAChC,QAAQ,GAAE,QAAiB;IAM7B;;;;;;;;;;;OAWG;IACG,UAAU,CACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,mBAAmB,CAAC;IAmK/B;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IA8B1B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAiDlC;;OAEG;IACH,OAAO,CAAC,kBAAkB;CAwC3B"}