nemoris 0.1.0

package/src/runtime/executor.js

@@ -0,0 +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
+    };
+  }
+}

package/src/runtime/failure-ping.js

@@ -0,0 +1,67 @@
+/**
+ * Sends a failure ping to the Telegram operator when a job fails,
+ * and a user-friendly error message to the originating chat.
+ * Never throws — all errors are caught and logged internally.
+ */
+
+function isRetryableError(err) {
+  const msg = (err?.message || "").toLowerCase();
+  const status = err?.status || err?.statusCode || 0;
+  return status >= 500 || err?.code === "ETIMEDOUT" ||
+    msg.includes("etimedout") || msg.includes("timeout") || msg.includes("fetch failed");
+}
+
+/**
+ * @param {object} job
+ * @param {Error} error
+ * @param {object} options
+ * @param {string} options.botToken
+ * @param {string} options.operatorChatId
+ * @param {Function} [options.fetchImpl]
+ */
+export async function sendFailurePing(job, error, options = {}) {
+  const { botToken, operatorChatId, fetchImpl } = options;
+
+  if (!botToken) return;
+  if (job.source === "completion_ping") return;
+
+  const fetchFn = fetchImpl || globalThis.fetch;
+
+  // Send user-friendly error to the originating chat
+  if (job.chat_id) {
+    const isTurnTimeout = error?.message === "turn_timeout";
+    let userMsg;
+    if (isTurnTimeout) {
+      userMsg = "⚠️ Turn timed out after 2 minutes. Try again or /stop to reset.";
+    } else if (isRetryableError(error)) {
+      userMsg = "⚠️ Provider hiccup — couldn't complete that. Try again in a moment.";
+    } else {
+      const snippet = (error?.message || "unknown error").slice(0, 120);
+      userMsg = `⚠️ Something went wrong: ${snippet}. Try again or /stop to reset.`;
+    }
+    try {
+      await fetchFn(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ chat_id: job.chat_id, text: userMsg }),
+      });
+    } catch (sendErr) {
+      console.error(JSON.stringify({ service: "error_delivery", event: "failed", error: sendErr.message, jobId: job.job_id }));
+    }
+  }
+
+  // Operator notification (detailed)
+  if (operatorChatId) {
+    const errorSnippet = (error?.message || String(error)).slice(0, 120);
+    const text = `⚠️ Job failed\nAgent: ${job.agent_id}\nJob: ${job.job_id}\nError: ${errorSnippet}\nSource: ${job.source}`;
+    try {
+      await fetchFn(`https://api.telegram.org/bot${botToken}/sendMessage`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ chat_id: operatorChatId, text }),
+      });
+    } catch (sendErr) {
+      console.error(JSON.stringify({ service: "failure_ping", error: sendErr.message, jobId: job.job_id }));
+    }
+  }
+}

package/src/runtime/flows.js

@@ -0,0 +1,83 @@
+/**
+ * Cross-Pillar Flows — coordinates seams between pillars.
+ */
+
+export async function flowTaskEscalationToOperator(task, deliveryAck, telegramSend, { chatId, retryDelays } = {}) {
+  const chain = JSON.parse(task.escalation_chain);
+  const target = chain[task.escalation_index] || "operator";
+  if (target !== "operator") {
+    throw new Error(`Flow 1 only handles operator escalation, got target: ${target}`);
+  }
+  const body = [
+    `${task.assigned_agent} timed out on: ${task.objective}`,
+    task.error_slot ? `Error: ${task.error_slot}` : null,
+    `Result so far: ${task.result_slot || "none"}`,
+    "Want me to intervene?",
+  ].filter(Boolean).join("\n");
+  return deliveryAck.sendWithGuarantee({
+    sourceAgent: task.owner_agent,
+    criticality: "decision_required",
+    payload: { text: body },
+    chatId,
+    correlationId: task.envelope_id,
+    sendFn: (payload) => telegramSend({ text: payload.text, chatId }),
+    retryDelays,
+  });
+}
+
+export async function flowTaskCompletionToMemory(task, writeBuffer) {
+  const summary = task.result_slot
+    ? (typeof task.result_slot === "string" ? task.result_slot : JSON.stringify(task.result_slot))
+    : "no result";
+  const content = `Task "${task.objective}" completed by ${task.assigned_agent}: ${summary.slice(0, 500)}`;
+  writeBuffer.add({
+    content,
+    confidence: 0.85,
+    sourceAgent: task.assigned_agent,
+    category: "task_result",
+    type: "fact",
+  });
+}
+
+export async function flowDecisionResponseToTask(envelope, operatorMessage, taskContract, { resolveAgent, callerAgent } = {}) {
+  const task = taskContract.db.prepare(
+    "SELECT * FROM tasks WHERE envelope_id = ?"
+  ).get(envelope.correlation_id);
+  if (!task) return { action: "unstructured", reason: "no linked task" };
+
+  const msg = operatorMessage.toLowerCase();
+
+  if (msg.includes("retry")) {
+    const newTask = taskContract.createTask({
+      ownerAgent: task.owner_agent,
+      assignedAgent: task.assigned_agent,
+      objective: task.objective,
+      deadlineMinutes: Math.max(10, Math.round((new Date(task.deadline_at) - new Date(task.created_at)) / 60000)),
+    });
+    return { action: "retry", newTaskId: newTask.task_id, originalTaskId: task.task_id };
+  }
+
+  if (msg.includes("cancel")) {
+    try {
+      taskContract.transition(task.task_id, "cancelled", task.owner_agent);
+    } catch { /* may not be in cancellable state */ }
+    return { action: "cancel", taskId: task.task_id };
+  }
+
+  if (msg.includes("reassign")) {
+    const match = operatorMessage.match(/reassign(?:\s+to)?\s+(\w+)/i);
+    const targetName = match?.[1];
+    if (targetName && resolveAgent && resolveAgent(targetName)) {
+      const newTask = taskContract.createTask({
+        ownerAgent: task.owner_agent,
+        assignedAgent: targetName,
+        objective: task.objective,
+        deadlineMinutes: Math.max(10, Math.round((new Date(task.deadline_at) - new Date(task.created_at)) / 60000)),
+      });
+      return { action: "reassign", newTaskId: newTask.task_id, assignedAgent: targetName };
+    }
+    return { action: "unstructured", reason: `Could not resolve agent: ${targetName}` };
+  }
+
+  return { action: "unstructured", message: operatorMessage };
+}

package/src/runtime/guards.js

@@ -0,0 +1,45 @@
+const DEFAULT_PROVIDER_MODE = {
+  allowProviderExecution: false,
+  allowRemoteProviders: false,
+  allowedJobIds: ["heartbeat-check", "workspace-health", "memory-rollup"],
+  allowedLanes: ["local_cheap", "local_report", "report_fallback_lowcost"],
+  requireHealthyProvider: true
+};
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+export function getProviderModePolicy() {
+  return {
+    ...DEFAULT_PROVIDER_MODE,
+    allowProviderExecution: readFlag("NEMORIS_ALLOW_PROVIDER_MODE"),
+    allowRemoteProviders: readFlag("NEMORIS_ALLOW_REMOTE_PROVIDER_MODE")
+  };
+}
+
+export function assertProviderExecutionAllowed({ jobId, modelLane, providerId, interactive = false }) {
+  const policy = getProviderModePolicy();
+
+  if (!policy.allowProviderExecution) {
+    throw new Error("Provider mode disabled. Set NEMORIS_ALLOW_PROVIDER_MODE=1 to enable guarded shadow execution.");
+  }
+
+  // Interactive jobs (Telegram, agent dispatch) bypass job-id and lane allowlists
+  if (!interactive) {
+    if (!policy.allowedJobIds.includes(jobId)) {
+      throw new Error(`Provider mode not allowed for job ${jobId}.`);
+    }
+
+    if (!policy.allowedLanes.includes(modelLane)) {
+      throw new Error(`Provider mode not allowed for lane ${modelLane}.`);
+    }
+  }
+
+  if (providerId !== "ollama" && !policy.allowRemoteProviders) {
+    throw new Error(`Remote provider execution blocked for ${providerId}. Set NEMORIS_ALLOW_REMOTE_PROVIDER_MODE=1 to override.`);
+  }
+
+  return policy;
+}