ennodia 0.3.0 → 0.4.1

package/src/index.ts

@@ -1,8 +1,12 @@
 export { pragmaticSchema, type PragmaticOptions } from "./pragmatic";
 export {
+  CORE_TOOL_NAMES,
+  TOOL_SETS,
   createEnnodiaServer,
   shutdownEnnodia,
+  type EnnodiaServerOptions,
   type EnnodiaShutdownOptions,
+  type ToolSet,
 } from "./server";
 export {
   EnnodiaCore,

package/src/runs.ts

@@ -6,7 +6,7 @@ import {
   type BudgetCheck,
   type BudgetLimits,
 } from "./budget";
-import type { CompareManager, CompareView } from "./compare";
+import { MAX_PROMPT_CANDIDATE_CHARS, type CompareManager, type CompareView } from "./compare";
 import { diagnoseTasks, type TaskDiagnosis } from "./diagnosis";
 import type {
   DiscoverHarnessesOptions,
@@ -14,7 +14,7 @@ import type {
   HarnessDiscovery,
   ReasoningEffort,
 } from "./harnesses";
-import { assertNativeSandboxSupported, assertNativeSubagentsSupported, assertReasoningEffortSupported } from "./harnesses";
+import { assertHarnessSettingsSupported } from "./harnesses";
 import {
   noopHistorySink,
   type HistorySink,
@@ -264,9 +264,7 @@ export class RunManager {
     for (const harnessId of selectedHarnessIds) {
       const adapter = this.dependencies.findHarnessAdapter(harnessId);
       if (adapter) {
-        assertReasoningEffortSupported(adapter, input.reasoningEffort);
-        assertNativeSubagentsSupported(adapter, input.nativeSubagents);
-        assertNativeSandboxSupported(adapter, input.nativeSandbox);
+        assertHarnessSettingsSupported(adapter, input);
       }
     }
 
@@ -561,13 +559,21 @@ export class RunManager {
       return;
     }
 
-    const finalAnswer = result.advisor?.answer.trim() ||
+    const advice = result.advisor?.answer.trim() ||
       result.synthesis?.text.trim();
+    // When the Advisor chose a candidate to use unchanged, the answer carries
+    // that candidate's own text after the Advisor's reason.
+    const chosen = result.candidates.find((candidate) => candidate.id === result.advisor?.chosenSourceId);
+    const finalAnswer = advice && chosen
+      ? `${advice}\n\nChosen answer from ${chosen.label ?? chosen.id}, unchanged:\n\n${chosen.content}`
+      : advice;
     if (result.status === "succeeded" && finalAnswer) {
       this.pushEvent(run, {
         type: "compare-succeeded",
         compareId: compare.id,
-        message: "Compare returned the Advisor recommendation.",
+        message: chosen
+          ? `Compare returned the Advisor recommendation and the chosen answer from ${chosen.label ?? chosen.id}.`
+          : "Compare returned the Advisor recommendation.",
       });
       this.succeedRun(run, finalAnswer);
       return;
@@ -589,7 +595,10 @@ export class RunManager {
       compareId,
       undefined,
       {
-        includeCandidates: false,
+        // A chosen candidate fits in the Advisor's evidence, so this cap
+        // keeps it whole.
+        includeCandidates: true,
+        maxCandidateChars: MAX_PROMPT_CANDIDATE_CHARS,
         includeEvents: true,
         maxEvents: 25,
       },

package/src/server.ts

@@ -1,5 +1,5 @@
 import { pragmaticSchema } from "./pragmatic";
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { McpServer, type RegisteredTool } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { compositionalSliceSchema } from "./compositional";
 import {
@@ -50,12 +50,58 @@ const budgetSchema = z
 
 export type EnnodiaShutdownOptions = EnnodiaCoreShutdownOptions;
 
-export function createEnnodiaServer(core: EnnodiaCore = defaultCore): McpServer {
+/** Every tool definition is loaded into each session of every agent that
+ * has Ennodia configured, even when Ennodia is never called. The core set
+ * covers handing work to one agent or a team, Compare, waiting, and
+ * cancelling. The full set adds raw tasks, compositional slices, Plan
+ * Advisor, budget estimates, and skill installation. */
+export const CORE_TOOL_NAMES: readonly string[] = [
+  "ennodia_run",
+  "ennodia_get_run",
+  "ennodia_cancel_run",
+  "ennodia_list_harnesses",
+  "ennodia_list_skills",
+  "ennodia_history",
+];
+
+/** Clients such as Codex run read-only tools without an approval prompt,
+ * so polling a run never stops for approval. Tools that start agents reach
+ * model providers, and their workers can change files when the caller allows
+ * it, so they claim neither read-only nor harmless. */
+export function toolAnnotations(name: string): { readOnlyHint: boolean; openWorldHint: boolean; destructiveHint?: boolean; idempotentHint?: boolean } {
+  if (/^ennodia_(?:list_|get_|history$|plan$|estimate_)/.test(name)) return { readOnlyHint: true, openWorldHint: false };
+  if (name.startsWith("ennodia_cancel_")) return { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+  if (name === "ennodia_install_skills") return { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
+  return { readOnlyHint: false, openWorldHint: true };
+}
+
+export const TOOL_SETS = ["core", "all"] as const;
+export type ToolSet = (typeof TOOL_SETS)[number];
+
+export type EnnodiaServerOptions = {
+  /** Defaults to "core". */
+  tools?: ToolSet;
+};
+
+export function createEnnodiaServer(
+  core: EnnodiaCore = defaultCore,
+  options: EnnodiaServerOptions = {},
+): McpServer {
   const server = new McpServer({
     name: "ennodia",
     version: ENNODIA_VERSION,
   });
 
+  // Keep each registration, so the core set can drop the others below, and
+  // add the annotations that tell clients which calls only read.
+  const registered = new Map<string, RegisteredTool>();
+  const registerTool = server.registerTool.bind(server) as (name: string, config: { annotations?: object }, ...rest: unknown[]) => RegisteredTool;
+  server.registerTool = ((name: string, config: { annotations?: object }, ...rest: unknown[]) => {
+    const tool = registerTool(name, { ...config, annotations: { ...toolAnnotations(name), ...config.annotations } }, ...rest);
+    registered.set(name, tool);
+    return tool;
+  }) as McpServer["registerTool"];
+
   server.registerTool(
     "ennodia_list_harnesses",
     {
@@ -1218,6 +1264,13 @@ export function createEnnodiaServer(core: EnnodiaCore = defaultCore): McpServer
     async ({ taskId }) => jsonResult(core.cancelTask(taskId)),
   );
 
+  // Removing before connect sends no list-changed notification.
+  if ((options.tools ?? "core") === "core") {
+    for (const [name, tool] of registered) {
+      if (!CORE_TOOL_NAMES.includes(name)) tool.remove();
+    }
+  }
+
   return server;
 }
 

package/src/tasks.ts

@@ -10,7 +10,7 @@ import type {
   HarnessRunInput,
   HarnessUsage,
 } from "./harnesses";
-import { assertNativeSandboxSupported, assertNativeSubagentsSupported, assertReasoningEffortSupported, DEFAULT_TASK_TIMEOUT_MS, withInputGuidance } from "./harnesses";
+import { assertHarnessSettingsSupported, DEFAULT_TASK_TIMEOUT_MS, inputGuidanceNotes, withInputGuidance } from "./harnesses";
 import { preview, tailItems } from "./internal";
 import { signalOwnedProcess } from "./process";
 import {
@@ -19,11 +19,14 @@ import {
   type AppliedSkillInfo,
 } from "./skills";
 
+/** Ennodia's own instructions are tagged, so workers do not read them as task content. */
+export const EXECUTION_NOTICE_TAG = "ennodia-execution-notice";
+
 export type TaskStatus = "running" | "succeeded" | "failed" | "cancelled";
 
 export type TaskEvent = {
   at: string;
-  type: "started" | "input-guidance" | "stdout" | "stderr" | "exit" | "cancel" | "error";
+  type: "started" | "input-guidance" | "restart" | "stdout" | "stderr" | "exit" | "cancel" | "error";
   message?: string;
 };
 
@@ -83,6 +86,9 @@ export type TaskView = {
   /** Set when this task ran against an isolated copy of the requested cwd
    * (see HarnessRunInput.isolateCwd), naming the original directory. */
   isolatedFrom?: string;
+  /** Starts repeated because another instance of the same CLI held shared
+   * local state. Present only when a restart happened. */
+  startupRestarts?: number;
 };
 
 export type TaskViewOptions = {
@@ -138,6 +144,11 @@ type InternalTask = Omit<
   isolatedCwd?: string;
   extractUsage?: HarnessAdapter["extractUsage"];
   failureReason?: HarnessAdapter["failureReason"];
+  /** The exact spawn, kept so a start that met a startup conflict can run again. */
+  spawnInput: TaskSpawnInput;
+  stdinText?: string;
+  startupConflict?: RegExp;
+  attemptStartedAtMs: number;
 };
 
 export type StartTaskResult = {
@@ -146,6 +157,8 @@ export type StartTaskResult = {
 
 export type TaskManagerOptions = {
   drainTimeoutMs?: number;
+  /** Base delay before restarting a start that met a startup conflict. */
+  startupRestartDelayMs?: number;
   maxTasks?: number;
   spawn?: TaskSpawn;
   removeIsolatedCwd?: (path: string) => void;
@@ -161,10 +174,16 @@ const DEFAULT_MAX_TASKS = 200;
 const MAX_CAPTURE_CHARS = 200_000;
 const MAX_EVENT_MESSAGE_CHARS = 4_000;
 const MAX_EVENTS = 300;
+// A startup conflict shows up within moments of launch. Later failures are
+// not restarted, because the worker may have started real work.
+const STARTUP_CONFLICT_WINDOW_MS = 10_000;
+const MAX_STARTUP_RESTARTS = 3;
+const STARTUP_RESTART_DELAY_MS = 500;
 
 export class TaskManager {
   private readonly tasks = new Map<string, InternalTask>();
   private readonly drainTimeoutMs: number;
+  private readonly startupRestartDelayMs: number;
   private readonly maxTasks: number;
   private readonly spawn: TaskSpawn;
   private readonly removeIsolatedCwd: (path: string) => void;
@@ -175,6 +194,7 @@ export class TaskManager {
 
   constructor(options: TaskManagerOptions = {}) {
     this.drainTimeoutMs = options.drainTimeoutMs ?? DEFAULT_DRAIN_TIMEOUT_MS;
+    this.startupRestartDelayMs = options.startupRestartDelayMs ?? STARTUP_RESTART_DELAY_MS;
     this.maxTasks = Math.max(1, options.maxTasks ?? DEFAULT_MAX_TASKS);
     this.spawn = options.spawn ?? ((input) => Bun.spawn(input));
     this.ownsProcessGroups = !options.spawn && process.platform !== "win32";
@@ -214,9 +234,7 @@ export class TaskManager {
     if (input.persistSession && (!adapter.supportsSessionContinuation || input.isolateCwd)) {
       throw new Error("Persistent sessions require a supported harness and a persistent working directory.");
     }
-    assertReasoningEffortSupported(adapter, input.reasoningEffort);
-    assertNativeSubagentsSupported(adapter, input.nativeSubagents);
-    assertNativeSandboxSupported(adapter, input.nativeSandbox);
+    assertHarnessSettingsSupported(adapter, input);
     if (adapter.supportsNativeSandbox) input = { ...input, nativeSandbox: input.nativeSandbox ?? "read-only" };
 
     const sourceCwd = input.cwd ?? process.cwd();
@@ -244,26 +262,46 @@ export class TaskManager {
     const now = Date.now();
     const deadlineMs = now + timeoutMs;
     const deadlineAt = new Date(deadlineMs).toISOString();
-    const guidedPrompt = withInputGuidance(input.prompt, adapter);
-    const executionPrompt = `${guidedPrompt}
-
-Ennodia execution notice:
-Execution allowance: ${timeoutMs} ms from task launch (${input.timeoutMs === undefined ? "Ennodia default" : "caller supplied"}). Deadline (UTC): ${deadlineAt}. This is a hard cutoff, not a completion estimate or a target duration.
-Check actual UTC time before attributing incomplete work to the deadline. Do not report a cutoff merely because the task is difficult or the answer is getting long. Continue within the remaining allowance unless complete or blocked by a demonstrated access or tool failure.
-Configured native sandbox: ${input.nativeSandbox ?? "harness-managed; check available permissions"}. Report any mismatch between the assignment and available access before attempting the work.
-Before the cutoff, return useful partial findings, verification performed, remaining work, and a justified continuation budget if needed. Only the caller can authorize a follow-up.
-Use only tools and permissions actually available in this session; the caller's tools are not automatically inherited. If access is missing, report the exact tool, file, or permission and its impact. Try a permitted alternative when useful; do not repeat an unchanged failed attempt or claim success without evidence.`;
+    const guidance = inputGuidanceNotes(input.prompt, adapter);
+    const noticeLines = [
+      `Execution allowance: ${timeoutMs} ms from task launch (${input.timeoutMs === undefined ? "Ennodia default" : "caller supplied"}). Deadline (UTC): ${deadlineAt}. This is a hard cutoff, not a completion estimate or a target duration.`,
+      "Check actual UTC time before attributing incomplete work to the deadline. Do not report a cutoff merely because the task is difficult or the answer is getting long. Continue within the remaining allowance unless complete or blocked by a demonstrated access or tool failure.",
+      `Configured native sandbox: ${input.nativeSandbox ?? "harness-managed; check available permissions"}. Report any mismatch between the assignment and available access before attempting the work.`,
+      "Before the cutoff, return useful partial findings, verification performed, remaining work, and a justified continuation budget if needed. Only the caller can authorize a follow-up.",
+      "Use only tools and permissions actually available in this session; the caller's tools are not automatically inherited. If access is missing, report the exact tool, file, or permission and its impact. Try a permitted alternative when useful; do not repeat an unchanged failed attempt or claim success without evidence.",
+    ];
+    // An adapter that takes operator instructions gets Ennodia's notices
+    // there. Other workers get them as tagged blocks after the task.
+    let systemNotice: string | undefined;
+    let executionPrompt: string;
+    if (adapter.systemNotices) {
+      executionPrompt = input.prompt;
+      systemNotice = [
+        "Ennodia, the local tool that started this session for its caller, sets these limits for the task.",
+        ...noticeLines,
+        ...(guidance ? ["When the task needs native media inspection:", ...guidance.map((note) => `- ${note}`)] : []),
+      ].join("\n");
+    } else {
+      executionPrompt = `${withInputGuidance(input.prompt, adapter)}
+
+<${EXECUTION_NOTICE_TAG}>
+From Ennodia, not part of the task above.
+${noticeLines.join("\n")}
+</${EXECUTION_NOTICE_TAG}>`;
+    }
     const augmentedPrompt = input.skills && input.skills.length > 0
       ? augmentPrompt(executionPrompt, input.skills, adapter.id)
       : executionPrompt;
     let commandSpec: CommandSpec;
     let cwd: string;
+    let spawnInput: TaskSpawnInput;
     let child: TaskProcess;
     try {
       commandSpec = adapter.buildCommand(discovery.commandPath, {
         ...input,
         cwd: resolvedInputCwd,
         prompt: augmentedPrompt,
+        systemNotice,
         finalMessagePath,
         nativeSessionId: previous?.nativeSessionId,
       });
@@ -273,7 +311,7 @@ Use only tools and permissions actually available in this session; the caller's
         throw new Error(`Working directory does not exist: ${cwd}`);
       }
 
-      child = this.spawn({
+      spawnInput = {
         cmd: [commandSpec.command, ...commandSpec.args],
         cwd,
         env: { ...process.env, ...commandSpec.env },
@@ -281,7 +319,8 @@ Use only tools and permissions actually available in this session; the caller's
         stdout: "pipe",
         stderr: "pipe",
         detached: process.platform !== "win32",
-      });
+      };
+      child = this.spawn(spawnInput);
     } catch (error) {
       cleanupFailedStartArtifacts(
         finalMessagePath,
@@ -307,7 +346,7 @@ Use only tools and permissions actually available in this session; the caller's
       isolatedFrom,
       command: [
         basename(commandSpec.command),
-        ...commandSpec.args.map((arg) => arg === augmentedPrompt ? "<prompt>" : arg),
+        ...commandSpec.args.map((arg) => arg === augmentedPrompt ? "<prompt>" : arg === systemNotice ? "<ennodia-notice>" : arg),
         ...(commandSpec.stdin === undefined ? [] : ["<stdin-prompt>"]),
       ],
       promptPreview: preview(input.prompt),
@@ -328,6 +367,10 @@ Use only tools and permissions actually available in this session; the caller's
       isolatedCwd,
       extractUsage: adapter.extractUsage,
       failureReason: adapter.failureReason,
+      spawnInput,
+      stdinText: commandSpec.stdin,
+      startupConflict: adapter.startupConflict,
+      attemptStartedAtMs: Date.now(),
     };
 
     task.process = child;
@@ -339,7 +382,7 @@ Use only tools and permissions actually available in this session; the caller's
     if (previous) previous.continuationTaskId = task.id;
     this.pruneTasks(task.id);
     this.pushEvent(task, { type: "started", message: `Task started. Execution limit: ${timeoutMs}ms (${task.timeoutSource}); deadline: ${task.deadlineAt}. This is not a completion estimate.` });
-    if (guidedPrompt !== input.prompt) {
+    if (guidance) {
       this.pushEvent(task, {
         type: "input-guidance",
         message: "Media input guidance was included in the worker prompt. Native inspection remains unverified until the worker reports evidence.",
@@ -366,24 +409,7 @@ Use only tools and permissions actually available in this session; the caller's
 
     task.settled = this.watchExit(task, child);
     void task.settled;
-
-    if (commandSpec.stdin !== undefined) {
-      try {
-        const childStdin = child.stdin;
-        if (!childStdin) {
-          throw new Error("Child stdin pipe was not available.");
-        }
-
-        childStdin.write(commandSpec.stdin);
-        childStdin.end();
-      } catch (error) {
-        this.pushEvent(task, {
-          type: "error",
-          message: error instanceof Error ? error.message : String(error),
-        });
-        this.terminate(task);
-      }
-    }
+    this.writeStdin(task, child);
 
     return { task: this.toView(task) };
   }
@@ -495,9 +521,16 @@ Use only tools and permissions actually available in this session; the caller's
   ): Promise<void> {
     let terminalStatus: TaskStatus = "failed";
     try {
-      const exitCode = await child.exited;
+      let exitCode = await child.exited;
       if (task.killTimeout) this.signal(task, "SIGKILL");
       await this.waitForOutputDrain(task);
+      while (exitCode !== 0 && this.metStartupConflict(task)) {
+        const restarted = await this.restartAfterConflict(task);
+        if (!restarted) break;
+        exitCode = await restarted.exited;
+        if (task.killTimeout) this.signal(task, "SIGKILL");
+        await this.waitForOutputDrain(task);
+      }
       task.exitCode = exitCode;
 
       if (task.cancelRequested) {
@@ -553,6 +586,80 @@ Use only tools and permissions actually available in this session; the caller's
     }
   }
 
+  private writeStdin(task: InternalTask, child: TaskProcess): void {
+    if (task.stdinText === undefined) {
+      return;
+    }
+
+    try {
+      const childStdin = child.stdin;
+      if (!childStdin) {
+        throw new Error("Child stdin pipe was not available.");
+      }
+
+      childStdin.write(task.stdinText);
+      childStdin.end();
+    } catch (error) {
+      this.pushEvent(task, {
+        type: "error",
+        message: error instanceof Error ? error.message : String(error),
+      });
+      this.terminate(task);
+    }
+  }
+
+  /** A start that lost a race for the CLI's shared local state did no work,
+   * so running the same command again is safe. */
+  private metStartupConflict(task: InternalTask): boolean {
+    return Boolean(task.startupConflict?.test(task.stderr)) &&
+      !task.stdout.trim() &&
+      !task.cancelRequested && !task.timedOut && !task.drainTimedOut && !this.shuttingDown &&
+      (task.startupRestarts ?? 0) < MAX_STARTUP_RESTARTS &&
+      Date.now() - task.attemptStartedAtMs < STARTUP_CONFLICT_WINDOW_MS;
+  }
+
+  private async restartAfterConflict(task: InternalTask): Promise<TaskProcess | undefined> {
+    const restart = (task.startupRestarts ?? 0) + 1;
+    // Jitter spreads out tasks that met the same conflict together.
+    const delayMs = Math.round(this.startupRestartDelayMs * restart * (1 + Math.random()));
+    this.pushEvent(task, {
+      type: "restart",
+      message: `The CLI stopped during startup because another instance held shared local state. Restart ${restart} of ${MAX_STARTUP_RESTARTS} in ${delayMs}ms. stderr: ${tail(task.stderr, 500).trim()}`,
+    });
+    await Bun.sleep(delayMs);
+    if (task.cancelRequested || task.timedOut || this.shuttingDown) {
+      return undefined;
+    }
+
+    // Clear anything the failed start left in its process group.
+    this.signal(task, "SIGKILL");
+    let child: TaskProcess;
+    try {
+      child = this.spawn(task.spawnInput);
+    } catch (error) {
+      this.pushEvent(task, {
+        type: "error",
+        message: `Restart failed: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      return undefined;
+    }
+
+    task.forceSignalled = false;
+    task.startupRestarts = restart;
+    task.stdout = "";
+    task.stderr = "";
+    task.streamCaptureTruncated = false;
+    task.process = child;
+    task.pid = child.pid;
+    task.attemptStartedAtMs = Date.now();
+    task.streamsDone = Promise.all([
+      this.pipeStreamSafely(task, "stdout", child.stdout),
+      this.pipeStreamSafely(task, "stderr", child.stderr),
+    ]).then(() => undefined);
+    this.writeStdin(task, child);
+    return child;
+  }
+
   private async collectFinalMessage(task: InternalTask): Promise<void> {
     if (!task.finalMessagePath) {
       return;
@@ -865,6 +972,7 @@ Use only tools and permissions actually available in this session; the caller's
           task.stderr.length > (includeOutput ? maxOutputChars : 0)),
       usage: task.usage,
       isolatedFrom: task.isolatedFrom,
+      startupRestarts: task.startupRestarts || undefined,
     };
   }
 

package/src/version.ts

@@ -1 +1 @@
-export const ENNODIA_VERSION = "0.3.0";
+export const ENNODIA_VERSION = "0.4.1";

package/bench/README.md

@@ -1,34 +0,0 @@
-# Benchmarks
-
-Ennodia's first release-candidate benchmark is `multi-model-bug-recall`: small
-TypeScript review fixtures with committed oracles. It measures if
-parallel peer review plus Compare recovers more required findings than a solo
-harness answer.
-
-The default command is deterministic and uses committed reference outputs:
-
-```sh
-bun run bench:bug-recall
-```
-
-The live command starts a fresh Ennodia Model Context Protocol (MCP) server and
-runs real harnesses. It is intentionally not part of `bun run verify`.
-
-```sh
-bun run bench:bug-recall:live -- --fixture 001-missing-await
-```
-
-Useful flags:
-
-- `--fixture <id>` runs one fixture. Repeat it to select multiple fixtures.
-- `--harness <id>` adds a solo baseline harness in live mode. Defaults to
-  `codex` and `claude-code`.
-- `--judge-harness <id>` and `--advisor-harness <id>` select Compare roles.
-- `--synthesizer-harness <id>` is a deprecated alias for
-  `--advisor-harness <id>`.
-- `--timeout-ms <ms>` sets the per-run timeout for live harness calls.
-- `--out <dir>` writes results to a specific directory.
-
-Results are written under `bench/results/bug-recall/`. Raw benchmark output is
-gitignored by default because live runs include model output and environment
-metadata.