@opengoat/core 2026.2.9

package/dist/core/orchestration/application/orchestration.service.js

@@ -0,0 +1,1044 @@
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { isDiscoverableByOrchestrator } from "../../agents/index.js";
+import { DEFAULT_AGENT_ID, normalizeAgentId } from "../../domain/agent-id.js";
+import { createNoopLogger } from "../../logging/index.js";
+import { OrchestrationPlannerService } from "./orchestration-planner.service.js";
+import { RoutingService } from "./routing.service.js";
+const MAX_ORCHESTRATION_STEPS = 12;
+const MAX_DELEGATION_STEPS = 8;
+const SHARED_NOTES_MAX_CHARS = 12_000;
+const RECENT_EVENTS_WINDOW = 10;
+export class OrchestrationService {
+    providerService;
+    skillService;
+    agentManifestService;
+    sessionService;
+    commandRunner;
+    routingService;
+    plannerService;
+    fileSystem;
+    pathPort;
+    nowIso;
+    logger;
+    constructor(deps) {
+        this.providerService = deps.providerService;
+        this.skillService = deps.skillService;
+        this.agentManifestService = deps.agentManifestService;
+        this.sessionService = deps.sessionService;
+        this.commandRunner = deps.commandRunner;
+        this.routingService = deps.routingService ?? new RoutingService();
+        this.plannerService = deps.plannerService ?? new OrchestrationPlannerService();
+        this.fileSystem = deps.fileSystem;
+        this.pathPort = deps.pathPort;
+        this.nowIso = deps.nowIso;
+        this.logger = (deps.logger ?? createNoopLogger()).child({ scope: "orchestration-service" });
+    }
+    async routeMessage(paths, entryAgentId, message) {
+        const manifests = await this.agentManifestService.listManifests(paths);
+        const resolvedEntryAgentId = resolveEntryAgentId(entryAgentId, manifests);
+        return this.routingService.decide({
+            entryAgentId: resolvedEntryAgentId,
+            message,
+            manifests
+        });
+    }
+    async runAgent(paths, entryAgentId, options) {
+        const runId = generateRunId();
+        const runLogger = this.logger.child({ runId });
+        const startedAt = this.nowIso();
+        const manifests = await this.agentManifestService.listManifests(paths);
+        const resolvedEntryAgentId = resolveEntryAgentId(entryAgentId, manifests);
+        runLogger.info("Starting agent run.", {
+            entryAgentId,
+            resolvedEntryAgentId
+        });
+        emitRunStatusEvent(options, {
+            stage: "run_started",
+            runId,
+            timestamp: this.nowIso(),
+            agentId: resolvedEntryAgentId
+        });
+        if (resolvedEntryAgentId !== DEFAULT_AGENT_ID) {
+            runLogger.info("Running direct non-orchestrator invocation.", {
+                targetAgentId: resolvedEntryAgentId
+            });
+            const sessionAgentId = options.directAgentSession ? resolvedEntryAgentId : DEFAULT_AGENT_ID;
+            const direct = await this.invokeAgentWithSession(paths, resolvedEntryAgentId, {
+                ...options,
+                message: options.message
+            }, { sessionAgentId, runId });
+            const completedAt = this.nowIso();
+            const routing = {
+                entryAgentId: resolvedEntryAgentId,
+                targetAgentId: resolvedEntryAgentId,
+                confidence: 1,
+                reason: "Direct invocation of a non-orchestrator agent.",
+                rewrittenMessage: options.message,
+                candidates: []
+            };
+            const trace = await this.buildAndWriteTrace({
+                paths,
+                runId,
+                startedAt,
+                completedAt,
+                entryAgentId: resolvedEntryAgentId,
+                userMessage: options.message,
+                routing,
+                execution: direct.execution,
+                durationMs: 0,
+                session: direct.session,
+                orchestration: {
+                    mode: "single-agent",
+                    finalMessage: direct.execution.stdout,
+                    steps: [],
+                    sessionGraph: {
+                        nodes: [
+                            {
+                                agentId: resolvedEntryAgentId,
+                                providerId: direct.execution.providerId,
+                                sessionKey: direct.session?.sessionKey,
+                                sessionId: direct.session?.sessionId,
+                                providerSessionId: direct.execution.providerSessionId
+                            }
+                        ],
+                        edges: []
+                    },
+                    taskThreads: []
+                }
+            });
+            emitRunStatusEvent(options, {
+                stage: "run_completed",
+                runId,
+                timestamp: this.nowIso(),
+                agentId: resolvedEntryAgentId
+            });
+            return {
+                ...direct.execution,
+                entryAgentId: resolvedEntryAgentId,
+                routing,
+                tracePath: trace.tracePath,
+                session: direct.session,
+                orchestration: trace.trace.orchestration
+            };
+        }
+        const startTime = Date.now();
+        const loopResult = await this.runAiOrchestrationLoop(paths, runId, manifests, options, runLogger);
+        const durationMs = Date.now() - startTime;
+        const completedAt = this.nowIso();
+        const routing = {
+            entryAgentId: DEFAULT_AGENT_ID,
+            targetAgentId: DEFAULT_AGENT_ID,
+            confidence: 0.9,
+            reason: "AI orchestration loop executed by orchestrator.",
+            rewrittenMessage: options.message,
+            candidates: []
+        };
+        const trace = await this.buildAndWriteTrace({
+            paths,
+            runId,
+            startedAt,
+            completedAt,
+            entryAgentId: DEFAULT_AGENT_ID,
+            userMessage: options.message,
+            routing,
+            execution: loopResult.execution,
+            durationMs,
+            orchestration: {
+                mode: "ai-loop",
+                finalMessage: loopResult.finalMessage,
+                steps: loopResult.steps,
+                sessionGraph: loopResult.sessionGraph,
+                taskThreads: loopResult.taskThreads
+            }
+        });
+        emitRunStatusEvent(options, {
+            stage: "run_completed",
+            runId,
+            timestamp: this.nowIso(),
+            agentId: DEFAULT_AGENT_ID
+        });
+        return {
+            ...loopResult.execution,
+            entryAgentId: DEFAULT_AGENT_ID,
+            routing,
+            tracePath: trace.tracePath,
+            orchestration: trace.trace.orchestration
+        };
+    }
+    async runAiOrchestrationLoop(paths, runId, manifests, options, runLogger) {
+        const steps = [];
+        const sessionGraph = {
+            nodes: [],
+            edges: []
+        };
+        const taskThreads = new Map();
+        const sharedNotes = [];
+        const recentEvents = [];
+        let orchestratorSkillsSnapshot = await this.skillService.buildSkillsPrompt(paths, DEFAULT_AGENT_ID);
+        let orchestratorSkillsSummary = orchestratorSkillsSnapshot.skills.map((skill) => ({
+            id: skill.id,
+            name: skill.name,
+            description: skill.description,
+            source: skill.source
+        }));
+        let delegationCount = 0;
+        let finalMessage = "";
+        let lastExecution = await this.buildSyntheticExecution(paths, DEFAULT_AGENT_ID);
+        runLogger.info("Starting orchestration loop.", {
+            maxSteps: MAX_ORCHESTRATION_STEPS,
+            maxDelegations: MAX_DELEGATION_STEPS,
+            loadedSkills: orchestratorSkillsSummary.length
+        });
+        for (let step = 1; step <= MAX_ORCHESTRATION_STEPS; step += 1) {
+            const stepLogger = runLogger.child({ step });
+            const plannerPrompt = this.plannerService.buildPlannerPrompt({
+                userMessage: options.message,
+                step,
+                maxSteps: MAX_ORCHESTRATION_STEPS,
+                sharedNotes: clampText(sharedNotes.join("\n\n"), SHARED_NOTES_MAX_CHARS),
+                recentEvents,
+                agents: manifests,
+                taskThreads: summarizeTaskThreads(taskThreads),
+                skills: orchestratorSkillsSummary
+            });
+            stepLogger.debug("Planner prompt payload.", {
+                prompt: plannerPrompt
+            });
+            emitRunStatusEvent(options, {
+                stage: "planner_started",
+                runId,
+                timestamp: this.nowIso(),
+                step,
+                agentId: DEFAULT_AGENT_ID
+            });
+            const plannerCall = await this.invokeAgentWithSession(paths, DEFAULT_AGENT_ID, {
+                ...options,
+                message: plannerPrompt,
+                skillsPromptOverride: orchestratorSkillsSnapshot.prompt,
+                sessionRef: options.sessionRef,
+                forceNewSession: step === 1 ? options.forceNewSession : false
+            }, { silent: true, runId, step });
+            const plannerRawOutput = plannerCall.execution.stdout.trim() || plannerCall.execution.stderr.trim();
+            stepLogger.debug("Planner raw output payload.", {
+                output: plannerRawOutput
+            });
+            if (plannerCall.execution.code !== 0) {
+                const providerFailureMessage = renderPlannerProviderFailureMessage(plannerCall.execution.providerId, plannerCall.execution.code, plannerCall.execution.stderr || plannerCall.execution.stdout);
+                const plannerDecision = {
+                    rationale: "Planner provider invocation failed.",
+                    action: {
+                        type: "respond_user",
+                        mode: "direct",
+                        reason: "planner_provider_failure",
+                        message: providerFailureMessage
+                    }
+                };
+                emitRunStatusEvent(options, {
+                    stage: "planner_decision",
+                    runId,
+                    timestamp: this.nowIso(),
+                    step,
+                    agentId: DEFAULT_AGENT_ID,
+                    actionType: "respond_user",
+                    mode: "direct"
+                });
+                stepLogger.warn("Planner provider invocation failed.", {
+                    providerId: plannerCall.execution.providerId,
+                    code: plannerCall.execution.code,
+                    stderr: plannerCall.execution.stderr,
+                    stdout: plannerCall.execution.stdout
+                });
+                addSessionNode(sessionGraph, DEFAULT_AGENT_ID, plannerCall.session, plannerCall.execution);
+                const stepLog = {
+                    step,
+                    timestamp: this.nowIso(),
+                    plannerRawOutput,
+                    plannerDecision,
+                    note: `Planner provider ${plannerCall.execution.providerId} failed with code ${plannerCall.execution.code}.`
+                };
+                steps.push(stepLog);
+                finalMessage = providerFailureMessage;
+                lastExecution = {
+                    ...plannerCall.execution,
+                    stdout: ensureTrailingNewline(providerFailureMessage)
+                };
+                break;
+            }
+            const plannerDecision = this.plannerService.parseDecision(plannerRawOutput, "I could not complete orchestration due to planner output parsing issues.");
+            emitRunStatusEvent(options, {
+                stage: "planner_decision",
+                runId,
+                timestamp: this.nowIso(),
+                step,
+                agentId: DEFAULT_AGENT_ID,
+                actionType: plannerDecision.action.type,
+                targetAgentId: plannerDecision.action.type === "delegate_to_agent"
+                    ? normalizeAgentId(plannerDecision.action.targetAgentId)
+                    : undefined,
+                mode: plannerDecision.action.mode
+            });
+            stepLogger.info("Planner decision parsed.", {
+                actionType: plannerDecision.action.type,
+                actionMode: plannerDecision.action.mode ?? "direct",
+                rationale: plannerDecision.rationale
+            });
+            addSessionNode(sessionGraph, DEFAULT_AGENT_ID, plannerCall.session, plannerCall.execution);
+            const stepLog = {
+                step,
+                timestamp: this.nowIso(),
+                plannerRawOutput,
+                plannerDecision
+            };
+            const actionResult = await this.executeAction({
+                paths,
+                runId,
+                step,
+                action: plannerDecision.action,
+                manifests,
+                options,
+                sessionGraph,
+                stepLog,
+                sharedNotes,
+                recentEvents,
+                taskThreads,
+                logger: stepLogger
+            });
+            steps.push(stepLog);
+            if (actionResult.finalMessage !== undefined) {
+                finalMessage = actionResult.finalMessage;
+                if (actionResult.execution) {
+                    lastExecution = actionResult.execution;
+                }
+                break;
+            }
+            if (actionResult.execution) {
+                lastExecution = actionResult.execution;
+            }
+            if (plannerDecision.action.type === "delegate_to_agent") {
+                delegationCount += 1;
+            }
+            if (plannerDecision.action.type === "install_skill" &&
+                (normalizeAgentId(plannerDecision.action.targetAgentId ?? DEFAULT_AGENT_ID) || DEFAULT_AGENT_ID) ===
+                    DEFAULT_AGENT_ID) {
+                orchestratorSkillsSnapshot = await this.skillService.buildSkillsPrompt(paths, DEFAULT_AGENT_ID);
+                orchestratorSkillsSummary = orchestratorSkillsSnapshot.skills.map((skill) => ({
+                    id: skill.id,
+                    name: skill.name,
+                    description: skill.description,
+                    source: skill.source
+                }));
+            }
+            if (delegationCount >= MAX_DELEGATION_STEPS) {
+                stepLogger.warn("Delegation safety limit reached.");
+                finalMessage = "Stopped orchestration after reaching delegation safety limit.";
+                break;
+            }
+        }
+        if (!finalMessage) {
+            finalMessage =
+                sharedNotes.length > 0
+                    ? `Orchestration reached step limit.\n\nCurrent synthesis:\n${clampText(sharedNotes.join("\n\n"), 2000)}`
+                    : "Orchestration stopped at safety step limit without a final response.";
+        }
+        if (!lastExecution.stdout.trim()) {
+            lastExecution = {
+                ...lastExecution,
+                code: 0,
+                stdout: ensureTrailingNewline(finalMessage),
+                stderr: lastExecution.stderr
+            };
+        }
+        return {
+            finalMessage,
+            execution: lastExecution,
+            steps,
+            sessionGraph,
+            taskThreads: summarizeTaskThreads(taskThreads)
+        };
+    }
+    async executeAction(params) {
+        const action = params.action;
+        if (action.type === "finish" || action.type === "respond_user") {
+            const message = action.message.trim() || "Completed.";
+            params.logger.info("Completing orchestration with direct response.", {
+                actionType: action.type
+            });
+            params.stepLog.note = action.reason;
+            this.addRecentEvent(params.recentEvents, `Step ${params.step}: ${action.type}`);
+            return {
+                finalMessage: message,
+                execution: {
+                    ...(await this.buildSyntheticExecution(params.paths, DEFAULT_AGENT_ID)),
+                    code: 0,
+                    stdout: ensureTrailingNewline(message)
+                }
+            };
+        }
+        if (action.type === "read_workspace_file") {
+            const resolvedPath = this.resolveWorkspacePath({
+                paths: params.paths,
+                requestedPath: action.path,
+                workingPathHint: params.options.cwd
+            });
+            params.logger.info("Reading workspace file for orchestration context.", {
+                path: resolvedPath
+            });
+            const exists = await this.fileSystem.exists(resolvedPath);
+            const content = exists ? await this.fileSystem.readFile(resolvedPath) : `[MISSING] ${resolvedPath}`;
+            params.sharedNotes.push(clampText(`Read ${action.path}:\n${content}`, 2500));
+            params.stepLog.artifactIO = { readPath: resolvedPath };
+            this.addRecentEvent(params.recentEvents, `Read file ${action.path}`);
+            return {};
+        }
+        if (action.type === "write_workspace_file") {
+            const resolvedPath = this.resolveWorkspacePath({
+                paths: params.paths,
+                requestedPath: action.path,
+                workingPathHint: params.options.cwd
+            });
+            params.logger.info("Writing workspace file for orchestration context.", {
+                path: resolvedPath
+            });
+            await this.fileSystem.ensureDir(path.dirname(resolvedPath));
+            await this.fileSystem.writeFile(resolvedPath, ensureTrailingNewline(action.content));
+            params.stepLog.artifactIO = { writePath: resolvedPath };
+            this.addRecentEvent(params.recentEvents, `Wrote file ${action.path}`);
+            return {};
+        }
+        if (action.type === "install_skill") {
+            const targetAgentId = normalizeAgentId(action.targetAgentId ?? DEFAULT_AGENT_ID) || DEFAULT_AGENT_ID;
+            params.logger.info("Installing skill requested by orchestrator action.", {
+                targetAgentId,
+                skillName: action.skillName
+            });
+            const result = await this.skillService.installSkill(params.paths, {
+                scope: "agent",
+                agentId: targetAgentId,
+                skillName: action.skillName,
+                sourcePath: action.sourcePath,
+                description: action.description,
+                content: action.content
+            });
+            const installedFor = result.agentId || targetAgentId;
+            params.stepLog.note = `Installed skill ${result.skillId} for ${installedFor} (${result.source}).`;
+            params.sharedNotes.push(`Skill installed: ${result.skillId} for ${installedFor} from ${result.source} at ${result.installedPath}`);
+            this.addRecentEvent(params.recentEvents, `Installed skill ${result.skillId} for ${installedFor} (${result.source})`);
+            return {};
+        }
+        const targetAgentId = normalizeAgentId(action.targetAgentId);
+        const targetManifest = params.manifests.find((manifest) => manifest.agentId === targetAgentId);
+        if (!targetManifest || !isDiscoverableByOrchestrator(targetManifest)) {
+            const note = `Invalid delegation target "${action.targetAgentId}" (missing, non-receivable, or non-discoverable).`;
+            params.logger.warn("Invalid delegation target.", {
+                requestedTargetAgentId: action.targetAgentId
+            });
+            params.sharedNotes.push(note);
+            params.stepLog.note = note;
+            this.addRecentEvent(params.recentEvents, note);
+            return {};
+        }
+        const taskKey = resolveTaskKey(action.taskKey, targetAgentId, params.step);
+        const requestedSessionPolicy = action.sessionPolicy ?? "auto";
+        const existingThread = params.taskThreads.get(taskKey);
+        const canReuseThread = Boolean(existingThread && existingThread.agentId === targetAgentId);
+        const effectiveSessionPolicy = requestedSessionPolicy === "reuse" ? (canReuseThread ? "reuse" : "new") : requestedSessionPolicy;
+        const forceNewTaskSession = effectiveSessionPolicy === "new" || !canReuseThread;
+        if (requestedSessionPolicy === "reuse" && !canReuseThread) {
+            const note = `Requested reuse for task "${taskKey}" but no matching thread exists; creating a new session.`;
+            params.sharedNotes.push(note);
+            this.addRecentEvent(params.recentEvents, note);
+            params.logger.warn("Requested task session reuse but no matching thread was found.", {
+                taskKey,
+                targetAgentId
+            });
+        }
+        const targetRuntime = await this.providerService.getAgentRuntimeProfile(params.paths, targetAgentId);
+        const mode = action.mode ?? "hybrid";
+        params.logger.info("Delegating task to agent.", {
+            fromAgentId: DEFAULT_AGENT_ID,
+            toAgentId: targetAgentId,
+            targetWorkspaceAccess: targetRuntime.workspaceAccess,
+            mode,
+            reason: action.reason,
+            taskKey,
+            sessionPolicy: effectiveSessionPolicy
+        });
+        emitRunStatusEvent(params.options, {
+            stage: "delegation_started",
+            runId: params.runId,
+            timestamp: this.nowIso(),
+            step: params.step,
+            agentId: DEFAULT_AGENT_ID,
+            targetAgentId,
+            providerId: targetRuntime.providerId,
+            mode,
+            detail: action.reason
+        });
+        const handoffBaseDir = this.pathPort.join(params.paths.sessionsDir, params.runId);
+        let outboundPath;
+        if (mode === "artifacts" || mode === "hybrid") {
+            await this.fileSystem.ensureDir(handoffBaseDir);
+            outboundPath = this.pathPort.join(handoffBaseDir, `step-${String(params.step).padStart(2, "0")}-to-${targetAgentId}.md`);
+            const handoffDocument = renderHandoffDocument({
+                step: params.step,
+                userMessage: params.options.message,
+                delegateMessage: action.message,
+                expectedOutput: action.expectedOutput,
+                sharedNotes: params.sharedNotes
+            });
+            await this.fileSystem.writeFile(outboundPath, ensureTrailingNewline(handoffDocument));
+            params.stepLog.artifactIO = {
+                ...params.stepLog.artifactIO,
+                writePath: outboundPath
+            };
+        }
+        const delegateMessage = renderDelegateMessage({
+            step: params.step,
+            userMessage: params.options.message,
+            delegateMessage: action.message,
+            expectedOutput: action.expectedOutput,
+            mode,
+            outboundPath,
+            exposeArtifactPath: targetRuntime.workspaceAccess === "internal",
+            sharedNotes: params.sharedNotes
+        });
+        params.logger.debug("Delegation message payload.", {
+            fromAgentId: DEFAULT_AGENT_ID,
+            toAgentId: targetAgentId,
+            taskKey,
+            request: delegateMessage,
+            mode,
+            outboundPath
+        });
+        const providerSessionId = effectiveSessionPolicy !== "new" && existingThread?.agentId === targetAgentId
+            ? existingThread.providerSessionId
+            : undefined;
+        const delegateCall = await this.invokeAgentWithSession(params.paths, targetAgentId, {
+            message: delegateMessage,
+            env: params.options.env,
+            cwd: params.options.cwd,
+            sessionRef: `agent:${targetAgentId}:task:${taskKey}`,
+            forceNewSession: forceNewTaskSession,
+            providerSessionId,
+            forceNewProviderSession: forceNewTaskSession
+        }, { silent: true, runId: params.runId, step: params.step });
+        const responseText = delegateCall.execution.stdout.trim() ||
+            (delegateCall.execution.stderr.trim() ? `[stderr] ${delegateCall.execution.stderr.trim()}` : "");
+        params.logger.debug("Delegation response payload.", {
+            fromAgentId: DEFAULT_AGENT_ID,
+            toAgentId: targetAgentId,
+            code: delegateCall.execution.code,
+            providerId: delegateCall.execution.providerId,
+            response: responseText
+        });
+        let inboundPath;
+        if (mode === "artifacts" || mode === "hybrid") {
+            await this.fileSystem.ensureDir(handoffBaseDir);
+            inboundPath = this.pathPort.join(handoffBaseDir, `step-${String(params.step).padStart(2, "0")}-from-${targetAgentId}.md`);
+            await this.fileSystem.writeFile(inboundPath, ensureTrailingNewline(responseText || "(empty response)"));
+            params.stepLog.artifactIO = {
+                ...params.stepLog.artifactIO,
+                readPath: inboundPath
+            };
+        }
+        params.stepLog.agentCall = {
+            targetAgentId,
+            taskKey,
+            sessionPolicy: effectiveSessionPolicy,
+            request: delegateMessage,
+            response: responseText,
+            code: delegateCall.execution.code,
+            providerId: delegateCall.execution.providerId,
+            sessionKey: delegateCall.session?.sessionKey,
+            sessionId: delegateCall.session?.sessionId,
+            providerSessionId: delegateCall.execution.providerSessionId,
+            workingTreeEffect: delegateCall.workingTreeEffect
+        };
+        addSessionNode(params.sessionGraph, targetAgentId, delegateCall.session, delegateCall.execution);
+        upsertTaskThread(params.taskThreads, {
+            taskKey,
+            agentId: targetAgentId,
+            createdStep: params.step,
+            updatedStep: params.step,
+            providerId: delegateCall.execution.providerId,
+            providerSessionId: delegateCall.execution.providerSessionId,
+            sessionKey: delegateCall.session?.sessionKey,
+            sessionId: delegateCall.session?.sessionId,
+            lastResponse: summarizeText(responseText || "(no response)")
+        });
+        params.sessionGraph.edges.push({
+            fromAgentId: DEFAULT_AGENT_ID,
+            toAgentId: targetAgentId,
+            reason: action.reason || params.stepLog.plannerDecision.rationale
+        });
+        const delegationFailure = summarizeDelegationFailure({
+            targetAgentId,
+            providerId: delegateCall.execution.providerId,
+            code: delegateCall.execution.code,
+            responseText,
+            workingTreeEffect: delegateCall.workingTreeEffect
+        });
+        if (delegationFailure) {
+            params.stepLog.note = delegationFailure.message;
+            this.addRecentEvent(params.recentEvents, delegationFailure.message);
+            params.sharedNotes.push(clampText(delegationFailure.message, 1200));
+            params.logger.warn("Delegation failed; stopping orchestration loop.", {
+                targetAgentId,
+                providerId: delegateCall.execution.providerId,
+                code: delegateCall.execution.code,
+                failureReason: delegationFailure.reason
+            });
+            return {
+                finalMessage: delegationFailure.message,
+                execution: {
+                    ...delegateCall.execution,
+                    code: delegateCall.execution.code !== 0 ? delegateCall.execution.code : 1,
+                    stdout: ensureTrailingNewline(delegationFailure.message)
+                }
+            };
+        }
+        const note = `Delegated to ${targetAgentId} [task:${taskKey}]: ${summarizeText(responseText || "(no response)")}`;
+        params.sharedNotes.push(clampText(note, 2000));
+        this.addRecentEvent(params.recentEvents, note);
+        if (delegateCall.workingTreeEffect && delegateCall.workingTreeEffect.enabled) {
+            const effectNote = `Working tree effect (${targetAgentId}): ${delegateCall.workingTreeEffect.summary}`;
+            params.sharedNotes.push(clampText(effectNote, 1200));
+            this.addRecentEvent(params.recentEvents, effectNote);
+        }
+        return {
+            execution: delegateCall.execution
+        };
+    }
+    addRecentEvent(events, value) {
+        events.push(summarizeText(value));
+        while (events.length > RECENT_EVENTS_WINDOW) {
+            events.shift();
+        }
+    }
+    resolveWorkspacePath(input) {
+        const { requestedPath, workingPathHint } = input;
+        const normalized = requestedPath.replace(/\\/g, "/").trim();
+        const runWorkingPath = resolveInvocationWorkingPath(workingPathHint);
+        const unsafeSegments = normalized.split("/").filter((segment) => segment === "..");
+        if (unsafeSegments.length > 0) {
+            return this.pathPort.join(runWorkingPath, ".opengoat", "coordination", "unsafe-path-blocked.md");
+        }
+        const relative = normalized.replace(/^\/+/, "");
+        return this.pathPort.join(runWorkingPath, relative || ".opengoat/coordination/context.md");
+    }
+    async invokeAgentWithSession(paths, agentId, options, behavior = {}) {
+        const sessionAgentId = normalizeAgentId(behavior.sessionAgentId ?? agentId) || DEFAULT_AGENT_ID;
+        this.logger.debug("Preparing agent invocation with session context.", {
+            agentId,
+            sessionAgentId,
+            message: options.message,
+            sessionRef: options.sessionRef,
+            forceNewSession: options.forceNewSession,
+            disableSession: options.disableSession,
+            providerSessionId: options.providerSessionId,
+            forceNewProviderSession: options.forceNewProviderSession
+        });
+        const preparedSession = await this.sessionService.prepareRunSession(paths, sessionAgentId, {
+            sessionRef: options.sessionRef,
+            forceNew: options.forceNewSession,
+            disableSession: options.disableSession,
+            workingPath: options.cwd,
+            userMessage: options.message
+        });
+        const invokeOptions = sanitizeProviderInvokeOptions({
+            ...options,
+            sessionContext: preparedSession.enabled ? preparedSession.contextPrompt : undefined
+        });
+        if (behavior.silent) {
+            delete invokeOptions.onStdout;
+            delete invokeOptions.onStderr;
+        }
+        const workingPath = preparedSession.enabled ? preparedSession.info.workingPath : resolveInvocationWorkingPath(options.cwd);
+        const beforeSnapshot = await this.captureWorkingTreeSnapshot(workingPath);
+        const execution = await this.providerService.invokeAgent(paths, agentId, invokeOptions, {
+            runId: behavior.runId,
+            step: behavior.step,
+            hooks: {
+                onInvocationStarted: (event) => {
+                    emitRunStatusEvent(options, {
+                        stage: "provider_invocation_started",
+                        runId: event.runId ?? behavior.runId ?? "unknown-run",
+                        timestamp: event.timestamp,
+                        step: event.step ?? behavior.step,
+                        agentId: event.agentId,
+                        providerId: event.providerId
+                    });
+                },
+                onInvocationCompleted: (event) => {
+                    emitRunStatusEvent(options, {
+                        stage: "provider_invocation_completed",
+                        runId: event.runId ?? behavior.runId ?? "unknown-run",
+                        timestamp: event.timestamp,
+                        step: event.step ?? behavior.step,
+                        agentId: event.agentId,
+                        providerId: event.providerId,
+                        code: event.code
+                    });
+                }
+            }
+        });
+        const afterSnapshot = await this.captureWorkingTreeSnapshot(workingPath);
+        const workingTreeEffect = summarizeWorkingTreeEffect(beforeSnapshot, afterSnapshot);
+        this.logger.debug("Agent invocation execution returned.", {
+            agentId,
+            sessionAgentId,
+            providerId: execution.providerId,
+            code: execution.code,
+            stdout: execution.stdout,
+            stderr: execution.stderr,
+            providerSessionId: execution.providerSessionId,
+            workingTreeEffect: workingTreeEffect?.summary
+        });
+        if (!preparedSession.enabled) {
+            return {
+                execution,
+                workingTreeEffect,
+                session: undefined
+            };
+        }
+        const assistantContent = execution.stdout.trim() ||
+            (execution.stderr.trim()
+                ? `[Provider error code ${execution.code}] ${execution.stderr.trim()}`
+                : `[Provider exited with code ${execution.code}]`);
+        const postRunCompaction = await this.sessionService.recordAssistantReply(paths, preparedSession.info, assistantContent);
+        return {
+            execution,
+            workingTreeEffect,
+            session: {
+                ...preparedSession.info,
+                preRunCompactionApplied: preparedSession.compactionApplied,
+                postRunCompaction
+            }
+        };
+    }
+    async buildAndWriteTrace(params) {
+        const trace = {
+            schemaVersion: 2,
+            runId: params.runId,
+            startedAt: params.startedAt,
+            completedAt: params.completedAt,
+            entryAgentId: params.entryAgentId,
+            userMessage: params.userMessage,
+            routing: params.routing,
+            session: params.session
+                ? {
+                    ...params.session,
+                    postRunCompactionApplied: params.session.postRunCompaction?.applied ?? false,
+                    postRunCompactionSummary: params.session.postRunCompaction?.summary
+                }
+                : undefined,
+            execution: {
+                agentId: params.execution.agentId,
+                providerId: params.execution.providerId,
+                code: params.execution.code,
+                stdout: params.execution.stdout,
+                stderr: params.execution.stderr,
+                durationMs: params.durationMs
+            },
+            orchestration: params.orchestration
+        };
+        const tracePath = await this.writeTrace(params.paths, trace);
+        return { tracePath, trace };
+    }
+    async captureWorkingTreeSnapshot(workingPath) {
+        if (!this.commandRunner) {
+            return undefined;
+        }
+        if (!(await this.fileSystem.exists(workingPath))) {
+            return undefined;
+        }
+        try {
+            const result = await this.commandRunner.run({
+                command: "git",
+                args: ["status", "--porcelain=v1", "--untracked-files=all"],
+                cwd: workingPath
+            });
+            if (result.code !== 0) {
+                return undefined;
+            }
+            const entries = parsePorcelainEntries(result.stdout);
+            return {
+                enabled: true,
+                workingPath,
+                entries
+            };
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async buildSyntheticExecution(paths, agentId) {
+        const binding = await this.providerService.getAgentProvider(paths, agentId);
+        return {
+            ...binding,
+            code: 0,
+            stdout: "",
+            stderr: ""
+        };
+    }
+    async writeTrace(paths, trace) {
+        await this.fileSystem.ensureDir(paths.runsDir);
+        const tracePath = this.pathPort.join(paths.runsDir, `${trace.runId}.json`);
+        await this.fileSystem.writeFile(tracePath, `${JSON.stringify(trace, null, 2)}\n`);
+        return tracePath;
+    }
+}
+function generateRunId() {
+    return randomUUID().toLowerCase();
+}
+function resolveInvocationWorkingPath(cwd) {
+    const normalized = cwd?.trim();
+    if (normalized) {
+        return path.resolve(normalized);
+    }
+    return process.cwd();
+}
+function parsePorcelainEntries(stdout) {
+    const lines = stdout
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .filter(Boolean);
+    return lines.map((line) => {
+        const status = line.slice(0, 2);
+        const rawPath = line.length > 3 ? line.slice(3).trim() : "";
+        const finalPath = rawPath.includes(" -> ") ? rawPath.split(" -> ").at(-1)?.trim() || rawPath : rawPath;
+        return {
+            raw: `${status} ${finalPath}`.trim(),
+            path: finalPath
+        };
+    });
+}
+function summarizeWorkingTreeEffect(beforeSnapshot, afterSnapshot) {
+    if (!beforeSnapshot || !afterSnapshot || !beforeSnapshot.enabled || !afterSnapshot.enabled) {
+        return undefined;
+    }
+    const beforeMap = new Map(beforeSnapshot.entries.map((entry) => [entry.path, entry.raw]));
+    const afterMap = new Map(afterSnapshot.entries.map((entry) => [entry.path, entry.raw]));
+    const touched = new Set();
+    for (const [path, raw] of afterMap.entries()) {
+        if (beforeMap.get(path) !== raw) {
+            touched.add(path);
+        }
+    }
+    for (const [path, raw] of beforeMap.entries()) {
+        if (afterMap.get(path) !== raw) {
+            touched.add(path);
+        }
+    }
+    const touchedPaths = [...touched].sort((left, right) => left.localeCompare(right));
+    const summary = touchedPaths.length === 0
+        ? "No tracked changes detected."
+        : `Touched ${touchedPaths.length} path(s): ${touchedPaths.slice(0, 8).join(", ")}${touchedPaths.length > 8 ? ", ..." : ""}`;
+    return {
+        enabled: true,
+        workingPath: afterSnapshot.workingPath,
+        beforeEntries: beforeSnapshot.entries.length,
+        afterEntries: afterSnapshot.entries.length,
+        touchedPaths,
+        summary
+    };
+}
+function resolveEntryAgentId(entryAgentId, manifests) {
+    const normalizedEntryAgentId = normalizeAgentId(entryAgentId) || DEFAULT_AGENT_ID;
+    if (manifests.some((manifest) => manifest.agentId === normalizedEntryAgentId)) {
+        return normalizedEntryAgentId;
+    }
+    if (manifests.some((manifest) => manifest.agentId === DEFAULT_AGENT_ID)) {
+        return DEFAULT_AGENT_ID;
+    }
+    return manifests[0]?.agentId || normalizedEntryAgentId;
+}
+function emitRunStatusEvent(options, event) {
+    options.hooks?.onEvent?.(event);
+}
+function sanitizeProviderInvokeOptions(options) {
+    const sanitized = { ...options };
+    delete sanitized.sessionRef;
+    delete sanitized.forceNewSession;
+    delete sanitized.disableSession;
+    delete sanitized.directAgentSession;
+    delete sanitized.hooks;
+    return sanitized;
+}
+function renderDelegateMessage(params) {
+    const lines = [
+        `Delegation step: ${params.step}`,
+        "",
+        "Original user request:",
+        params.userMessage,
+        "",
+        "Delegation instruction:",
+        params.delegateMessage,
+        ""
+    ];
+    if (params.expectedOutput?.trim()) {
+        lines.push("Expected output:", params.expectedOutput.trim(), "");
+    }
+    if (params.sharedNotes.length > 0) {
+        lines.push("Shared notes from previous steps:", clampText(params.sharedNotes.join("\n\n"), 4000), "");
+    }
+    if ((params.mode === "artifacts" || params.mode === "hybrid") && params.outboundPath && params.exposeArtifactPath) {
+        lines.push(`Coordination file: ${params.outboundPath}`, "You may use this markdown artifact for durable handoff context.", "");
+    }
+    else if (params.mode === "artifacts" || params.mode === "hybrid") {
+        lines.push("Coordination artifacts are managed internally by the orchestrator.", "");
+    }
+    lines.push("Return a concise result for the orchestrator.");
+    return lines.join("\n");
+}
+function renderHandoffDocument(params) {
+    return [
+        `# Delegation Step ${params.step}`,
+        "",
+        "## User Request",
+        params.userMessage,
+        "",
+        "## Delegation Instruction",
+        params.delegateMessage,
+        "",
+        "## Expected Output",
+        params.expectedOutput?.trim() || "(not specified)",
+        "",
+        "## Prior Notes",
+        params.sharedNotes.length > 0 ? clampText(params.sharedNotes.join("\n\n"), 4000) : "(none)"
+    ].join("\n");
+}
+function addSessionNode(graph, agentId, session, execution) {
+    if (!session) {
+        return;
+    }
+    const exists = graph.nodes.some((node) => node.agentId === agentId &&
+        node.providerId === execution?.providerId &&
+        node.sessionKey === session.sessionKey &&
+        node.sessionId === session.sessionId &&
+        node.providerSessionId === execution?.providerSessionId);
+    if (exists) {
+        return;
+    }
+    graph.nodes.push({
+        agentId,
+        providerId: execution?.providerId,
+        sessionKey: session.sessionKey,
+        sessionId: session.sessionId,
+        providerSessionId: execution?.providerSessionId
+    });
+}
+function resolveTaskKey(actionTaskKey, targetAgentId, step) {
+    const explicit = actionTaskKey?.trim().toLowerCase();
+    if (explicit) {
+        return explicit;
+    }
+    return `${targetAgentId}-step-${String(step).padStart(2, "0")}`;
+}
+function upsertTaskThread(threads, next) {
+    const existing = threads.get(next.taskKey);
+    if (!existing) {
+        threads.set(next.taskKey, next);
+        return;
+    }
+    threads.set(next.taskKey, {
+        ...existing,
+        ...next,
+        createdStep: existing.createdStep,
+        updatedStep: next.updatedStep
+    });
+}
+function summarizeTaskThreads(threads) {
+    return [...threads.values()]
+        .sort((left, right) => left.createdStep - right.createdStep)
+        .map((thread) => ({
+        taskKey: thread.taskKey,
+        agentId: thread.agentId,
+        providerId: thread.providerId,
+        providerSessionId: thread.providerSessionId,
+        sessionKey: thread.sessionKey,
+        sessionId: thread.sessionId,
+        createdStep: thread.createdStep,
+        updatedStep: thread.updatedStep,
+        lastResponse: thread.lastResponse
+    }));
+}
+function summarizeText(value) {
+    const normalized = value.replace(/\s+/g, " ").trim();
+    if (normalized.length <= 180) {
+        return normalized;
+    }
+    return `${normalized.slice(0, 177)}...`;
+}
+function ensureTrailingNewline(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}
+function renderPlannerProviderFailureMessage(providerId, code, detailsRaw) {
+    const details = detailsRaw.trim();
+    const summary = details
+        ? `\n\nProvider error details:\n${clampText(details, 1200)}`
+        : "";
+    return [
+        `The orchestrator provider (${providerId}) failed while planning (exit code ${code}).`,
+        "Open provider setup in the desktop app and verify credentials/model configuration.",
+        summary
+    ]
+        .join("\n")
+        .trim();
+}
+function summarizeDelegationFailure(params) {
+    if (params.code !== 0) {
+        const detail = summarizeText(params.responseText || "(no provider details)");
+        return {
+            reason: "provider_error",
+            message: [
+                `The delegated agent "${params.targetAgentId}" failed via provider "${params.providerId}" (exit code ${params.code}).`,
+                `Details: ${detail}`
+            ].join("\n")
+        };
+    }
+    const blockReason = extractBlockedNoProgressReason(params.responseText, params.workingTreeEffect);
+    if (!blockReason) {
+        return undefined;
+    }
+    return {
+        reason: "blocked_no_progress",
+        message: [
+            `The delegated agent "${params.targetAgentId}" could not continue this request.`,
+            blockReason
+        ].join("\n")
+    };
+}
+function extractBlockedNoProgressReason(responseText, workingTreeEffect) {
+    const normalized = responseText.toLowerCase();
+    if (!normalized.trim()) {
+        return undefined;
+    }
+    const toolUnavailableSignals = [
+        /write_file/,
+        /run_shell_command/,
+        /tool(?:s)? (?:is|are)?\s*(?:not found|unavailable|missing|not listed|not available)/,
+        /cannot create .* file/,
+        /i(?:'| a)?m stuck/,
+        /unable to proceed/
+    ];
+    const hasToolSignal = toolUnavailableSignals.some((pattern) => pattern.test(normalized));
+    if (!hasToolSignal) {
+        return undefined;
+    }
+    const noTrackedChanges = !workingTreeEffect?.enabled || workingTreeEffect.touchedPaths.length === 0;
+    if (!noTrackedChanges) {
+        return undefined;
+    }
+    return "It reported missing runtime tools/permissions and made no tracked workspace changes. Check provider capabilities or switch to a compatible agent provider for file-editing tasks.";
+}
+function clampText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    const head = value.slice(0, Math.floor(maxChars * 0.7));
+    const tail = value.slice(-(maxChars - head.length - 20));
+    return `${head}\n...[truncated]...\n${tail}`;
+}
+//# sourceMappingURL=orchestration.service.js.map