nemoris 0.1.0 → 0.1.2

package/src/runtime/executor.js

@@ -1,500 +1,500 @@
-import path from "node:path";
-import crypto from "node:crypto";
-import { DatabaseSync } from "node:sqlite";
-import { mkdirSync } from "node:fs";
-import { Scheduler } from "./scheduler.js";
-import { ProviderRegistry } from "../providers/registry.js";
-import { RunStore } from "./run-store.js";
-import { getProviderModePolicy } from "./guards.js";
-import { buildInteractionPlan, formatInteractionContract } from "./interaction-contract.js";
-import { InteractionNotifier } from "./notifier.js";
-import { TokenCounter } from "./token-counter.js";
-import { PeerRegistry } from "./peer-registry.js";
-import { createRuntimeId } from "../utils/ids.js";
-import { processToolOutput } from "./input-sanitiser.js";
-import { ToolRegistry } from "../tools/registry.js";
-import { registerMicroToolHandlers } from "../tools/micro/index.js";
-import { ExecApprovalGate } from "./exec-approvals.js";
-import { CircuitBreaker, ensureBreakerSchema } from "../providers/circuit-breaker.js";
-import { SchedulerStateStore } from "./scheduler-state.js";
-import { buildCapabilitiesPrompt } from "./capabilities-prompt.js";
-import { attemptProvider } from "./provider-attempt.js";
-import { buildOutputTemplate, formatOutputContract, formatReportGuidance, normalizeResult } from "./result-normalizer.js";
-import { runToolLoop } from "./tool-loop.js";
-
-export { parseToolUseBlocks, formatToolResults, executeToolCalls } from "./tool-loop.js";
-
-function buildSystemPrompt(plan, options = {}) {
-  const nativeStructuredOutput = options.nativeStructuredOutput ?? false;
-  const responseSchema = options.responseSchema || null;
-  const toolSchemas = options.toolSchemas || [];
-  const isInteractive = plan.job.trigger === "interactive";
-
-  const toolText = plan.packet.layers.tools.length
-    ? `Allowed tools: ${plan.packet.layers.tools.join(", ")}.`
-    : "No tools allowed.";
-  const soulText = plan.packet.layers.identity?.soul
-    ? `${plan.packet.layers.identity.soul.trim()}`
-    : "";
-  const purposeText = plan.packet.layers.identity?.purpose
-    ? `## Purpose\n${plan.packet.layers.identity.purpose.trim()}`
-    : "";
-  const userText = plan.packet.layers.identity?.user
-    ? `${plan.packet.layers.identity.user.trim()}`
-    : "";
-
-  const contextFileTexts = (plan.packet.layers.identity?.contextFiles || [])
-    .map(({ name, content }) => `---\n## ${name}\n\n${content.trim()}\n---`)
-    .join("\n\n");
-
-  if (isInteractive) {
-    return [
-      soulText,
-      userText,
-      purposeText,
-      contextFileTexts || null,
-      buildCapabilitiesPrompt(toolSchemas),
-      "Respond in plain conversational language. Do not output JSON, structured task packets, or completion sections.",
-      "Be concise, direct, and helpful. Match the tone of the user's message.",
-      "If the user asks a question, answer it. If they give a task, do it and report back naturally.",
-      toolText,
-    ]
-      .filter(Boolean)
-      .join("\n\n");
-  }
-
-  const interactionText = plan.packet.layers.interactionContract
-    ? `Interaction contract:\n${formatInteractionContract(plan.packet.layers.interactionContract)}`
-    : "";
-  const contractText = plan.packet.layers.outputContract
-    ? `Output contract:\n${formatOutputContract(plan.packet.layers.outputContract)}`
-    : "";
-  const guidanceText = plan.packet.layers.reportGuidance
-    ? `Report guidance:\n${formatReportGuidance(plan.packet.layers.reportGuidance)}`
-    : "";
-  const templateText = !nativeStructuredOutput && plan.packet.layers.outputContract
-    ? buildOutputTemplate(plan.packet.layers.outputContract)
-    : null;
-  const nativeSchemaText = nativeStructuredOutput && plan.packet.layers.outputContract
-    ? "Native structured output is enabled for this provider. Follow the contract exactly and return only schema-valid content."
-    : null;
-  const reasoningFieldText = nativeStructuredOutput && responseSchema?.reasoningField
-    ? `Use the ${responseSchema.reasoningField} field for compact reasoning before finalizing the structured output.`
-    : null;
-
-  return [
-    "You are Nemoris V2 executing a bounded shadow-mode job.",
-    "Use only the supplied task packet.",
-    "Do not assume the transcript is the system of record.",
-    "Summarize the result tightly and list the next actions.",
-    toolText,
-    soulText,
-    purposeText,
-    interactionText,
-    contractText,
-    guidanceText,
-    nativeSchemaText,
-    reasoningFieldText,
-    templateText ? `Follow this output template exactly when possible:\n${templateText}` : null
-  ]
-    .filter(Boolean)
-    .join("\n\n");
-}
-
-function buildUserMessage(plan, options = {}) {
-  const nativeStructuredOutput = options.nativeStructuredOutput ?? false;
-  const responseSchema = options.responseSchema || null;
-  const isInteractive = plan.job.trigger === "interactive";
-
-  const memoryLines = plan.packet.layers.memory
-    .map((item) => {
-      const primaryText = item.summary || item.content || item.reason || "";
-      const rawLine = `- [${item.type}/${item.category || "uncategorized"}] ${item.title || "memory"}: ${primaryText}`;
-      const source = item.sourceBackend || item.category || "memory";
-      const { tagged } = processToolOutput(rawLine, source);
-      return tagged;
-    })
-    .join("\n");
-
-  if (isInteractive) {
-    const parts = [plan.packet.objective];
-    if (plan.packet.conversationContext?.length) {
-      const contextLines = plan.packet.conversationContext
-        .map((turn) => `${turn.role}: ${turn.content}`)
-        .join("\n");
-      parts.unshift(`Previous conversation:\n${contextLines}`);
-    }
-    if (memoryLines) {
-      parts.push(`\n(Context from memory:\n${memoryLines})`);
-    }
-    return parts.join("\n\n");
-  }
-
-  const artifactLines = plan.packet.layers.artifacts.length
-    ? `Artifacts:\n${plan.packet.layers.artifacts.map((item) => {
-        const { tagged } = processToolOutput(`- ${item}`, "artifact");
-        return tagged;
-      }).join("\n")}`
-    : "Artifacts: none";
-  const contractReminder = !nativeStructuredOutput && plan.packet.layers.outputContract?.requiredSections?.length
-    ? `Required sections: ${plan.packet.layers.outputContract.requiredSections.join(", ")}.`
-    : "Required sections: none.";
-  const noneReminder = !nativeStructuredOutput && plan.packet.layers.outputContract?.requiredSections?.length
-    ? "If a required section has no concrete data, include the section anyway and say 'None'."
-    : null;
-  const schemaReminder = nativeStructuredOutput
-    ? "Return only the structured JSON object required by the provider schema."
-    : "Return JSON with keys: summary, output, nextActions.";
-  const reasoningReminder = nativeStructuredOutput && responseSchema?.reasoningField
-    ? `Put concise reasoning in ${responseSchema.reasoningField} before the final output fields.`
-    : null;
-
-  return [
-    `Objective: ${plan.packet.objective}`,
-    `Budget: ${plan.packet.budget.maxTokens} tokens, ${plan.packet.budget.maxRuntimeSeconds}s`,
-    plan.packet.layers.checkpoint
-      ? `Checkpoint: status=${plan.packet.layers.checkpoint.status}; next=${(plan.packet.layers.checkpoint.nextActions || []).join(", ") || "none"}`
-      : "Checkpoint: none",
-    memoryLines ? `Relevant memory:\n${memoryLines}` : "Relevant memory: none",
-    artifactLines,
-    contractReminder,
-    schemaReminder,
-    reasoningReminder,
-    "The output field must satisfy the system output contract.",
-    noneReminder,
-    "Prefer specific evidence from memory over generic reassurance.",
-    "The completion summary must be suitable for an explicit pingback and handoff."
-  ]
-    .filter(Boolean)
-    .join("\n\n");
-}
-
-export class Executor {
-  constructor({ projectRoot, liveRoot, stateRoot, fetchImpl, execApprovalGate = null } = {}) {
-    this.projectRoot = projectRoot;
-    this.liveRoot = liveRoot;
-    this.stateRoot = stateRoot;
-    this.scheduler = new Scheduler({ projectRoot, liveRoot, stateRoot });
-    this.registry = new ProviderRegistry({ fetchImpl });
-    this.runStore = new RunStore({ rootDir: path.join(stateRoot, "runs") });
-    this.notifier = new InteractionNotifier({ stateRoot });
-    this.tokenCounter = new TokenCounter();
-    this.toolRegistry = new ToolRegistry();
-    this.stateStore = new SchedulerStateStore({ rootDir: path.join(stateRoot, "scheduler") });
-    this._breakerDb = null;
-    this._breakers = new Map();
-    this.execApprovalGate = execApprovalGate || new ExecApprovalGate({ sendFn: async () => {} });
-  }
-
-  async initToolRegistry() {
-    if (this._toolsInitialized) return;
-    this._toolContext = {};
-    registerMicroToolHandlers(this.toolRegistry, this._toolContext);
-    try {
-      const { join } = await import("node:path");
-      await this.toolRegistry.loadTools(join(this.projectRoot, "config", "tools"));
-    } catch {
-      /* no tools dir is fine */
-    }
-    this._toolsInitialized = true;
-  }
-
-  _getBreaker(modelId, runtimeConfig) {
-    if (!this._breakerDb) {
-      const schedulerDir = path.join(this.stateRoot, "scheduler");
-      mkdirSync(schedulerDir, { recursive: true });
-      const dbPath = path.join(schedulerDir, "scheduler.sqlite");
-      this._breakerDb = new DatabaseSync(dbPath, { timeout: 5000 });
-      ensureBreakerSchema(this._breakerDb);
-    }
-    if (this._breakers.has(modelId)) return this._breakers.get(modelId);
-    const cbConfig = runtimeConfig?.circuit_breaker || runtimeConfig?.circuitBreaker || {};
-    const breaker = CircuitBreaker.forProvider(modelId, this._breakerDb, {
-      failureThreshold: cbConfig.failure_threshold ?? 5,
-      resetTimeoutSeconds: cbConfig.reset_timeout_seconds ?? 30,
-      transientCodes: cbConfig.transient_codes ?? [408, 429, 500, 502, 503, 504]
-    });
-    this._breakers.set(modelId, breaker);
-    return breaker;
-  }
-
-  _logUsage({ sessionId, jobId, modelId, providerId, usage, costUsd }) {
-    this.stateStore.db.prepare(`INSERT INTO usage_log (id, session_id, job_id, ts, model, tokens_in, tokens_out, cost_usd, provider, cache_in, cache_creation)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
-      .run(
-        crypto.randomUUID(),
-        sessionId,
-        jobId,
-        Date.now(),
-        modelId,
-        usage.tokensIn,
-        usage.tokensOut,
-        costUsd,
-        providerId,
-        usage.cacheIn,
-        usage.cacheCreation
-      );
-  }
-
-  setExecApprovalGate(execApprovalGate) {
-    if (execApprovalGate) {
-      this.execApprovalGate = execApprovalGate;
-    }
-  }
-
-  async executeJob(jobId, options = {}) {
-    const mode = options.mode || "dry-run";
-    let plan = null;
-    let routingDecision = null;
-    let modelId = null;
-    let providerId = null;
-    let providerCapabilities = null;
-    let invocation = null;
-    let preflight = null;
-    let fallback = null;
-    let health = null;
-    let providerModePolicy = null;
-    let result = null;
-    const runId = createRuntimeId("run");
-
-    try {
-      await this.initToolRegistry();
-      await this.stateStore.ensureReady();
-      plan = options.plan || await this.scheduler.hydrateJob(jobId, {
-        shadowImport: options.shadowImport ?? true,
-        objective: options.objective,
-        artifactRefs: options.artifactRefs,
-        memoryLimit: options.memoryLimit,
-        reportGuidanceOverride: options.reportGuidanceOverride,
-        retrievalBlendOverride: options.retrievalBlendOverride
-      });
-      const runtime = await this.scheduler.loadRuntime();
-      if (this._toolContext) {
-        this._toolContext.workspaceRoot = plan.agent?.workspaceRoot || this.projectRoot;
-      }
-      this.runStore.setRetentionPolicy(runtime.runtime?.retention?.runs || {});
-      this.notifier.configureRetention(runtime.runtime?.retention?.notifications || {});
-      const peerRegistry = new PeerRegistry(runtime.peers);
-      const agentPolicy = plan.policies?.tools?.[plan.agent?.tool_policy]
-        || { default: "deny", allowed: plan.packet.layers.tools || [], blocked: [] };
-      const toolSchemas = this.toolRegistry.schemasForAgent(plan.agent?.id, agentPolicy);
-
-      const providerAttempt = await attemptProvider({
-        plan,
-        runtime,
-        options: {
-          ...options,
-          mode,
-          registry: this.registry,
-          tokenCounter: this.tokenCounter,
-          toolSchemas,
-          buildSystemPrompt,
-          buildUserMessage,
-          getBreaker: this._getBreaker.bind(this)
-        }
-      });
-
-      routingDecision = providerAttempt.routingDecision;
-      modelId = providerAttempt.modelId;
-      providerId = providerAttempt.providerId;
-      providerCapabilities = providerAttempt.providerCapabilities;
-      invocation = providerAttempt.invocation;
-      preflight = providerAttempt.preflight;
-      fallback = providerAttempt.fallback;
-      health = providerAttempt.health;
-      providerModePolicy = providerAttempt.providerModePolicy;
-
-      const toolLoop = await runToolLoop({
-        initialResponse: providerAttempt.response,
-        adapter: providerAttempt.adapter,
-        invocation,
-        registry: this.toolRegistry,
-        policy: agentPolicy,
-        agentConfig: plan.agent,
-        approvalGate: this.execApprovalGate,
-        options: {
-          enabled: providerAttempt.toolLoopEnabled,
-          jobId: plan.job.id,
-          agentId: plan.agent?.id,
-          maxToolCalls: plan.packet.budget?.maxToolCalls || plan.job?.limits?.max_tool_calls_per_turn || 20,
-          skipApprovalNotification: options.skipApprovalNotification === true,
-        }
-      });
-
-      const ackNotification = await this.notifier.queueAck(plan, {
-        runId,
-        mode,
-        providerId,
-        providerCapabilities,
-        modelId,
-        routingDecision
-      });
-
-      const normalized = await normalizeResult({
-        plan,
-        rawResponse: toolLoop.finalResponse,
-        toolResults: toolLoop.toolResults,
-        usage: providerAttempt.toolLoopEnabled ? undefined : providerAttempt.usage,
-        options: {
-          mode,
-          adapter: providerAttempt.adapter,
-          modelId,
-          providerId,
-          pendingApprovalResult: toolLoop.pendingApprovalResult || null,
-          sessionId: options.sessionId,
-          logUsage: ({ sessionId, usage, costUsd }) => this._logUsage({
-            sessionId,
-            jobId: plan.job.id,
-            modelId,
-            providerId,
-            usage,
-            costUsd
-          })
-        }
-      });
-      result = normalized.result;
-
-      const handoffConfig = plan.packet.layers.interactionContract?.handoff || null;
-      const handoffSuggestions =
-        handoffConfig?.enabled
-          ? peerRegistry.suggestPeers({
-              taskType: plan.job.taskType,
-              query: handoffConfig.capabilityQuery || plan.job.taskType || plan.job.id,
-              preferredDeliveryProfile: plan.agent?.deliveryProfile || null,
-              trustLevel: handoffConfig.trustLevel || null,
-              limit: handoffConfig.maxSuggestions || 3
-            })
-          : [];
-      const interaction = buildInteractionPlan(plan, result, null, {
-        handoffSuggestions
-      });
-      const run = {
-        id: runId,
-        timestamp: new Date().toISOString(),
-        mode,
-        providerId,
-        providerCapabilities,
-        modelId,
-        routingDecision,
-        providerModePolicy,
-        fallback,
-        providerHealth: health,
-        preflight,
-        invocation,
-        plan,
-        result,
-        usage: normalized.usage,
-        costUsd: normalized.costUsd,
-        cached: normalized.cached,
-        toolCalls: toolLoop.toolResults,
-        pendingApproval: Boolean(toolLoop.pendingApprovalResult),
-        interaction,
-        idempotencyKey: options.idempotencyKey || null
-      };
-
-      const notificationFiles = [ackNotification?.filePath].filter(Boolean);
-      if (interaction?.yield?.required) {
-        const followUpNotification = await this.notifier.queueFollowUp(run);
-        run.followUp = interaction.yield;
-        run.followUpFile = followUpNotification?.filePath || null;
-        notificationFiles.push(followUpNotification?.filePath);
-      } else {
-        const completionNotification = await this.notifier.queueCompletion(run);
-        const handoffNotification = await this.notifier.queueHandoff(run);
-        notificationFiles.push(completionNotification?.filePath, handoffNotification?.filePath);
-      }
-      run.notificationFiles = notificationFiles.filter(Boolean);
-
-      const filePath = await this.runStore.saveRun(jobId, run);
-      return {
-        filePath,
-        ...run
-      };
-    } catch (error) {
-      if (error?.routingDecision) routingDecision = error.routingDecision;
-      if (error?.providerId) providerId = error.providerId;
-      if (error?.modelId) modelId = error.modelId;
-      if (error?.providerCapabilities) providerCapabilities = error.providerCapabilities;
-      if (error?.invocation) invocation = error.invocation;
-      if (error?.preflight) preflight = error.preflight;
-      if (error?.fallback) fallback = error.fallback;
-
-      if (plan) {
-        const errorNotification = await this.notifier.queueError({
-          plan,
-          error,
-          context: {
-            runId,
-            mode,
-            providerId,
-            providerCapabilities,
-            modelId,
-            routingDecision,
-            timestamp: new Date().toISOString()
-          }
-        });
-
-        const failedRun = {
-          id: runId,
-          timestamp: new Date().toISOString(),
-          mode,
-          providerId,
-          providerCapabilities,
-          modelId,
-          routingDecision,
-          providerModePolicy: mode === "provider" ? getProviderModePolicy() : null,
-          fallback,
-          preflight,
-          invocation,
-          plan,
-          error: {
-            message: error.message
-          },
-          notificationFiles: [errorNotification?.filePath].filter(Boolean)
-        };
-
-        const filePath = await this.runStore.saveRun(jobId, failedRun);
-        error.runFile = filePath;
-      }
-
-      throw error;
-    }
-  }
-
-  async shadowCompare(jobId) {
-    const [run, jobComparisons] = await Promise.all([
-      this.executeJob(jobId, { mode: "dry-run", shadowImport: true }),
-      this.scheduler.compareJobs()
-    ]);
-
-    const relatedLive = jobComparisons.find((job) => job.v2JobId === jobId)?.closestLiveJobs || [];
-
-    const comparison = {
-      timestamp: new Date().toISOString(),
-      jobId,
-      v2Run: {
-        mode: run.mode,
-        providerId: run.providerId,
-        modelId: run.modelId,
-        routingDecision: run.routingDecision,
-        summary: run.result.summary,
-        output: run.result.output,
-        providerHealth: run.providerHealth,
-        runFile: run.filePath
-      },
-      liveCandidates: relatedLive,
-      notes: [
-        relatedLive.length === 0
-          ? "No close live cron analogue found."
-          : `Found ${relatedLive.length} possible live cron analogues.`,
-        "Use provider mode only after dry-run shape looks correct."
-      ]
-    };
-
-    const filePath = await this.runStore.saveRun(`${jobId}-comparison`, comparison);
-    return {
-      filePath,
-      ...comparison
-    };
-  }
-}
+import path from "node:path";
+import crypto from "node:crypto";
+import { DatabaseSync } from "node:sqlite";
+import { mkdirSync } from "node:fs";
+import { Scheduler } from "./scheduler.js";
+import { ProviderRegistry } from "../providers/registry.js";
+import { RunStore } from "./run-store.js";
+import { getProviderModePolicy } from "./guards.js";
+import { buildInteractionPlan, formatInteractionContract } from "./interaction-contract.js";
+import { InteractionNotifier } from "./notifier.js";
+import { TokenCounter } from "./token-counter.js";
+import { PeerRegistry } from "./peer-registry.js";
+import { createRuntimeId } from "../utils/ids.js";
+import { processToolOutput } from "./input-sanitiser.js";
+import { ToolRegistry } from "../tools/registry.js";
+import { registerMicroToolHandlers } from "../tools/micro/index.js";
+import { ExecApprovalGate } from "./exec-approvals.js";
+import { CircuitBreaker, ensureBreakerSchema } from "../providers/circuit-breaker.js";
+import { SchedulerStateStore } from "./scheduler-state.js";
+import { buildCapabilitiesPrompt } from "./capabilities-prompt.js";
+import { attemptProvider } from "./provider-attempt.js";
+import { buildOutputTemplate, formatOutputContract, formatReportGuidance, normalizeResult } from "./result-normalizer.js";
+import { runToolLoop } from "./tool-loop.js";
+
+export { parseToolUseBlocks, formatToolResults, executeToolCalls } from "./tool-loop.js";
+
+function buildSystemPrompt(plan, options = {}) {
+  const nativeStructuredOutput = options.nativeStructuredOutput ?? false;
+  const responseSchema = options.responseSchema || null;
+  const toolSchemas = options.toolSchemas || [];
+  const isInteractive = plan.job.trigger === "interactive";
+
+  const toolText = plan.packet.layers.tools.length
+    ? `Allowed tools: ${plan.packet.layers.tools.join(", ")}.`
+    : "No tools allowed.";
+  const soulText = plan.packet.layers.identity?.soul
+    ? `${plan.packet.layers.identity.soul.trim()}`
+    : "";
+  const purposeText = plan.packet.layers.identity?.purpose
+    ? `## Purpose\n${plan.packet.layers.identity.purpose.trim()}`
+    : "";
+  const userText = plan.packet.layers.identity?.user
+    ? `${plan.packet.layers.identity.user.trim()}`
+    : "";
+
+  const contextFileTexts = (plan.packet.layers.identity?.contextFiles || [])
+    .map(({ name, content }) => `---\n## ${name}\n\n${content.trim()}\n---`)
+    .join("\n\n");
+
+  if (isInteractive) {
+    return [
+      soulText,
+      userText,
+      purposeText,
+      contextFileTexts || null,
+      buildCapabilitiesPrompt(toolSchemas),
+      "Respond in plain conversational language. Do not output JSON, structured task packets, or completion sections.",
+      "Be concise, direct, and helpful. Match the tone of the user's message.",
+      "If the user asks a question, answer it. If they give a task, do it and report back naturally.",
+      toolText,
+    ]
+      .filter(Boolean)
+      .join("\n\n");
+  }
+
+  const interactionText = plan.packet.layers.interactionContract
+    ? `Interaction contract:\n${formatInteractionContract(plan.packet.layers.interactionContract)}`
+    : "";
+  const contractText = plan.packet.layers.outputContract
+    ? `Output contract:\n${formatOutputContract(plan.packet.layers.outputContract)}`
+    : "";
+  const guidanceText = plan.packet.layers.reportGuidance
+    ? `Report guidance:\n${formatReportGuidance(plan.packet.layers.reportGuidance)}`
+    : "";
+  const templateText = !nativeStructuredOutput && plan.packet.layers.outputContract
+    ? buildOutputTemplate(plan.packet.layers.outputContract)
+    : null;
+  const nativeSchemaText = nativeStructuredOutput && plan.packet.layers.outputContract
+    ? "Native structured output is enabled for this provider. Follow the contract exactly and return only schema-valid content."
+    : null;
+  const reasoningFieldText = nativeStructuredOutput && responseSchema?.reasoningField
+    ? `Use the ${responseSchema.reasoningField} field for compact reasoning before finalizing the structured output.`
+    : null;
+
+  return [
+    "You are Nemoris V2 executing a bounded shadow-mode job.",
+    "Use only the supplied task packet.",
+    "Do not assume the transcript is the system of record.",
+    "Summarize the result tightly and list the next actions.",
+    toolText,
+    soulText,
+    purposeText,
+    interactionText,
+    contractText,
+    guidanceText,
+    nativeSchemaText,
+    reasoningFieldText,
+    templateText ? `Follow this output template exactly when possible:\n${templateText}` : null
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+function buildUserMessage(plan, options = {}) {
+  const nativeStructuredOutput = options.nativeStructuredOutput ?? false;
+  const responseSchema = options.responseSchema || null;
+  const isInteractive = plan.job.trigger === "interactive";
+
+  const memoryLines = plan.packet.layers.memory
+    .map((item) => {
+      const primaryText = item.summary || item.content || item.reason || "";
+      const rawLine = `- [${item.type}/${item.category || "uncategorized"}] ${item.title || "memory"}: ${primaryText}`;
+      const source = item.sourceBackend || item.category || "memory";
+      const { tagged } = processToolOutput(rawLine, source);
+      return tagged;
+    })
+    .join("\n");
+
+  if (isInteractive) {
+    const parts = [plan.packet.objective];
+    if (plan.packet.conversationContext?.length) {
+      const contextLines = plan.packet.conversationContext
+        .map((turn) => `${turn.role}: ${turn.content}`)
+        .join("\n");
+      parts.unshift(`Previous conversation:\n${contextLines}`);
+    }
+    if (memoryLines) {
+      parts.push(`\n(Context from memory:\n${memoryLines})`);
+    }
+    return parts.join("\n\n");
+  }
+
+  const artifactLines = plan.packet.layers.artifacts.length
+    ? `Artifacts:\n${plan.packet.layers.artifacts.map((item) => {
+        const { tagged } = processToolOutput(`- ${item}`, "artifact");
+        return tagged;
+      }).join("\n")}`
+    : "Artifacts: none";
+  const contractReminder = !nativeStructuredOutput && plan.packet.layers.outputContract?.requiredSections?.length
+    ? `Required sections: ${plan.packet.layers.outputContract.requiredSections.join(", ")}.`
+    : "Required sections: none.";
+  const noneReminder = !nativeStructuredOutput && plan.packet.layers.outputContract?.requiredSections?.length
+    ? "If a required section has no concrete data, include the section anyway and say 'None'."
+    : null;
+  const schemaReminder = nativeStructuredOutput
+    ? "Return only the structured JSON object required by the provider schema."
+    : "Return JSON with keys: summary, output, nextActions.";
+  const reasoningReminder = nativeStructuredOutput && responseSchema?.reasoningField
+    ? `Put concise reasoning in ${responseSchema.reasoningField} before the final output fields.`
+    : null;
+
+  return [
+    `Objective: ${plan.packet.objective}`,
+    `Budget: ${plan.packet.budget.maxTokens} tokens, ${plan.packet.budget.maxRuntimeSeconds}s`,
+    plan.packet.layers.checkpoint
+      ? `Checkpoint: status=${plan.packet.layers.checkpoint.status}; next=${(plan.packet.layers.checkpoint.nextActions || []).join(", ") || "none"}`
+      : "Checkpoint: none",
+    memoryLines ? `Relevant memory:\n${memoryLines}` : "Relevant memory: none",
+    artifactLines,
+    contractReminder,
+    schemaReminder,
+    reasoningReminder,
+    "The output field must satisfy the system output contract.",
+    noneReminder,
+    "Prefer specific evidence from memory over generic reassurance.",
+    "The completion summary must be suitable for an explicit pingback and handoff."
+  ]
+    .filter(Boolean)
+    .join("\n\n");
+}
+
+export class Executor {
+  constructor({ projectRoot, liveRoot, stateRoot, fetchImpl, execApprovalGate = null } = {}) {
+    this.projectRoot = projectRoot;
+    this.liveRoot = liveRoot;
+    this.stateRoot = stateRoot;
+    this.scheduler = new Scheduler({ projectRoot, liveRoot, stateRoot });
+    this.registry = new ProviderRegistry({ fetchImpl });
+    this.runStore = new RunStore({ rootDir: path.join(stateRoot, "runs") });
+    this.notifier = new InteractionNotifier({ stateRoot });
+    this.tokenCounter = new TokenCounter();
+    this.toolRegistry = new ToolRegistry();
+    this.stateStore = new SchedulerStateStore({ rootDir: path.join(stateRoot, "scheduler") });
+    this._breakerDb = null;
+    this._breakers = new Map();
+    this.execApprovalGate = execApprovalGate || new ExecApprovalGate({ sendFn: async () => {} });
+  }
+
+  async initToolRegistry() {
+    if (this._toolsInitialized) return;
+    this._toolContext = {};
+    registerMicroToolHandlers(this.toolRegistry, this._toolContext);
+    try {
+      const { join } = await import("node:path");
+      await this.toolRegistry.loadTools(join(this.projectRoot, "config", "tools"));
+    } catch {
+      /* no tools dir is fine */
+    }
+    this._toolsInitialized = true;
+  }
+
+  _getBreaker(modelId, runtimeConfig) {
+    if (!this._breakerDb) {
+      const schedulerDir = path.join(this.stateRoot, "scheduler");
+      mkdirSync(schedulerDir, { recursive: true });
+      const dbPath = path.join(schedulerDir, "scheduler.sqlite");
+      this._breakerDb = new DatabaseSync(dbPath, { timeout: 5000 });
+      ensureBreakerSchema(this._breakerDb);
+    }
+    if (this._breakers.has(modelId)) return this._breakers.get(modelId);
+    const cbConfig = runtimeConfig?.circuit_breaker || runtimeConfig?.circuitBreaker || {};
+    const breaker = CircuitBreaker.forProvider(modelId, this._breakerDb, {
+      failureThreshold: cbConfig.failure_threshold ?? 5,
+      resetTimeoutSeconds: cbConfig.reset_timeout_seconds ?? 30,
+      transientCodes: cbConfig.transient_codes ?? [408, 429, 500, 502, 503, 504]
+    });
+    this._breakers.set(modelId, breaker);
+    return breaker;
+  }
+
+  _logUsage({ sessionId, jobId, modelId, providerId, usage, costUsd }) {
+    this.stateStore.db.prepare(`INSERT INTO usage_log (id, session_id, job_id, ts, model, tokens_in, tokens_out, cost_usd, provider, cache_in, cache_creation)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+      .run(
+        crypto.randomUUID(),
+        sessionId,
+        jobId,
+        Date.now(),
+        modelId,
+        usage.tokensIn,
+        usage.tokensOut,
+        costUsd,
+        providerId,
+        usage.cacheIn,
+        usage.cacheCreation
+      );
+  }
+
+  setExecApprovalGate(execApprovalGate) {
+    if (execApprovalGate) {
+      this.execApprovalGate = execApprovalGate;
+    }
+  }
+
+  async executeJob(jobId, options = {}) {
+    const mode = options.mode || "dry-run";
+    let plan = null;
+    let routingDecision = null;
+    let modelId = null;
+    let providerId = null;
+    let providerCapabilities = null;
+    let invocation = null;
+    let preflight = null;
+    let fallback = null;
+    let health = null;
+    let providerModePolicy = null;
+    let result = null;
+    const runId = createRuntimeId("run");
+
+    try {
+      await this.initToolRegistry();
+      await this.stateStore.ensureReady();
+      plan = options.plan || await this.scheduler.hydrateJob(jobId, {
+        shadowImport: options.shadowImport ?? true,
+        objective: options.objective,
+        artifactRefs: options.artifactRefs,
+        memoryLimit: options.memoryLimit,
+        reportGuidanceOverride: options.reportGuidanceOverride,
+        retrievalBlendOverride: options.retrievalBlendOverride
+      });
+      const runtime = await this.scheduler.loadRuntime();
+      if (this._toolContext) {
+        this._toolContext.workspaceRoot = plan.agent?.workspaceRoot || this.projectRoot;
+      }
+      this.runStore.setRetentionPolicy(runtime.runtime?.retention?.runs || {});
+      this.notifier.configureRetention(runtime.runtime?.retention?.notifications || {});
+      const peerRegistry = new PeerRegistry(runtime.peers);
+      const agentPolicy = plan.policies?.tools?.[plan.agent?.tool_policy]
+        || { default: "deny", allowed: plan.packet.layers.tools || [], blocked: [] };
+      const toolSchemas = this.toolRegistry.schemasForAgent(plan.agent?.id, agentPolicy);
+
+      const providerAttempt = await attemptProvider({
+        plan,
+        runtime,
+        options: {
+          ...options,
+          mode,
+          registry: this.registry,
+          tokenCounter: this.tokenCounter,
+          toolSchemas,
+          buildSystemPrompt,
+          buildUserMessage,
+          getBreaker: this._getBreaker.bind(this)
+        }
+      });
+
+      routingDecision = providerAttempt.routingDecision;
+      modelId = providerAttempt.modelId;
+      providerId = providerAttempt.providerId;
+      providerCapabilities = providerAttempt.providerCapabilities;
+      invocation = providerAttempt.invocation;
+      preflight = providerAttempt.preflight;
+      fallback = providerAttempt.fallback;
+      health = providerAttempt.health;
+      providerModePolicy = providerAttempt.providerModePolicy;
+
+      const toolLoop = await runToolLoop({
+        initialResponse: providerAttempt.response,
+        adapter: providerAttempt.adapter,
+        invocation,
+        registry: this.toolRegistry,
+        policy: agentPolicy,
+        agentConfig: plan.agent,
+        approvalGate: this.execApprovalGate,
+        options: {
+          enabled: providerAttempt.toolLoopEnabled,
+          jobId: plan.job.id,
+          agentId: plan.agent?.id,
+          maxToolCalls: plan.packet.budget?.maxToolCalls || plan.job?.limits?.max_tool_calls_per_turn || 20,
+          skipApprovalNotification: options.skipApprovalNotification === true,
+        }
+      });
+
+      const ackNotification = await this.notifier.queueAck(plan, {
+        runId,
+        mode,
+        providerId,
+        providerCapabilities,
+        modelId,
+        routingDecision
+      });
+
+      const normalized = await normalizeResult({
+        plan,
+        rawResponse: toolLoop.finalResponse,
+        toolResults: toolLoop.toolResults,
+        usage: providerAttempt.toolLoopEnabled ? undefined : providerAttempt.usage,
+        options: {
+          mode,
+          adapter: providerAttempt.adapter,
+          modelId,
+          providerId,
+          pendingApprovalResult: toolLoop.pendingApprovalResult || null,
+          sessionId: options.sessionId,
+          logUsage: ({ sessionId, usage, costUsd }) => this._logUsage({
+            sessionId,
+            jobId: plan.job.id,
+            modelId,
+            providerId,
+            usage,
+            costUsd
+          })
+        }
+      });
+      result = normalized.result;
+
+      const handoffConfig = plan.packet.layers.interactionContract?.handoff || null;
+      const handoffSuggestions =
+        handoffConfig?.enabled
+          ? peerRegistry.suggestPeers({
+              taskType: plan.job.taskType,
+              query: handoffConfig.capabilityQuery || plan.job.taskType || plan.job.id,
+              preferredDeliveryProfile: plan.agent?.deliveryProfile || null,
+              trustLevel: handoffConfig.trustLevel || null,
+              limit: handoffConfig.maxSuggestions || 3
+            })
+          : [];
+      const interaction = buildInteractionPlan(plan, result, null, {
+        handoffSuggestions
+      });
+      const run = {
+        id: runId,
+        timestamp: new Date().toISOString(),
+        mode,
+        providerId,
+        providerCapabilities,
+        modelId,
+        routingDecision,
+        providerModePolicy,
+        fallback,
+        providerHealth: health,
+        preflight,
+        invocation,
+        plan,
+        result,
+        usage: normalized.usage,
+        costUsd: normalized.costUsd,
+        cached: normalized.cached,
+        toolCalls: toolLoop.toolResults,
+        pendingApproval: Boolean(toolLoop.pendingApprovalResult),
+        interaction,
+        idempotencyKey: options.idempotencyKey || null
+      };
+
+      const notificationFiles = [ackNotification?.filePath].filter(Boolean);
+      if (interaction?.yield?.required) {
+        const followUpNotification = await this.notifier.queueFollowUp(run);
+        run.followUp = interaction.yield;
+        run.followUpFile = followUpNotification?.filePath || null;
+        notificationFiles.push(followUpNotification?.filePath);
+      } else {
+        const completionNotification = await this.notifier.queueCompletion(run);
+        const handoffNotification = await this.notifier.queueHandoff(run);
+        notificationFiles.push(completionNotification?.filePath, handoffNotification?.filePath);
+      }
+      run.notificationFiles = notificationFiles.filter(Boolean);
+
+      const filePath = await this.runStore.saveRun(jobId, run);
+      return {
+        filePath,
+        ...run
+      };
+    } catch (error) {
+      if (error?.routingDecision) routingDecision = error.routingDecision;
+      if (error?.providerId) providerId = error.providerId;
+      if (error?.modelId) modelId = error.modelId;
+      if (error?.providerCapabilities) providerCapabilities = error.providerCapabilities;
+      if (error?.invocation) invocation = error.invocation;
+      if (error?.preflight) preflight = error.preflight;
+      if (error?.fallback) fallback = error.fallback;
+
+      if (plan) {
+        const errorNotification = await this.notifier.queueError({
+          plan,
+          error,
+          context: {
+            runId,
+            mode,
+            providerId,
+            providerCapabilities,
+            modelId,
+            routingDecision,
+            timestamp: new Date().toISOString()
+          }
+        });
+
+        const failedRun = {
+          id: runId,
+          timestamp: new Date().toISOString(),
+          mode,
+          providerId,
+          providerCapabilities,
+          modelId,
+          routingDecision,
+          providerModePolicy: mode === "provider" ? getProviderModePolicy() : null,
+          fallback,
+          preflight,
+          invocation,
+          plan,
+          error: {
+            message: error.message
+          },
+          notificationFiles: [errorNotification?.filePath].filter(Boolean)
+        };
+
+        const filePath = await this.runStore.saveRun(jobId, failedRun);
+        error.runFile = filePath;
+      }
+
+      throw error;
+    }
+  }
+
+  async shadowCompare(jobId) {
+    const [run, jobComparisons] = await Promise.all([
+      this.executeJob(jobId, { mode: "dry-run", shadowImport: true }),
+      this.scheduler.compareJobs()
+    ]);
+
+    const relatedLive = jobComparisons.find((job) => job.v2JobId === jobId)?.closestLiveJobs || [];
+
+    const comparison = {
+      timestamp: new Date().toISOString(),
+      jobId,
+      v2Run: {
+        mode: run.mode,
+        providerId: run.providerId,
+        modelId: run.modelId,
+        routingDecision: run.routingDecision,
+        summary: run.result.summary,
+        output: run.result.output,
+        providerHealth: run.providerHealth,
+        runFile: run.filePath
+      },
+      liveCandidates: relatedLive,
+      notes: [
+        relatedLive.length === 0
+          ? "No close live cron analogue found."
+          : `Found ${relatedLive.length} possible live cron analogues.`,
+        "Use provider mode only after dry-run shape looks correct."
+      ]
+    };
+
+    const filePath = await this.runStore.saveRun(`${jobId}-comparison`, comparison);
+    return {
+      filePath,
+      ...comparison
+    };
+  }
+}