ennodia 0.1.0-rc.0

package/src/diagnosis.ts

@@ -0,0 +1,161 @@
+import type { TaskView } from "./tasks";
+
+export type TaskOutputPreview = {
+  harnessId: string;
+  chars: number;
+  preview: string;
+};
+
+export type TaskDiagnosis = {
+  summary: string;
+  likelyCause: string;
+  suggestions: string[];
+  partialOutputPreviews?: TaskOutputPreview[];
+};
+
+const PREVIEW_CHARS = 240;
+
+export function diagnoseTasks(tasks: TaskView[]): TaskDiagnosis | undefined {
+  const failedTasks = tasks.filter((task) => task.status !== "succeeded");
+  if (failedTasks.length === 0) {
+    return undefined;
+  }
+
+  if (failedTasks.every((task) => task.status === "cancelled")) {
+    return undefined;
+  }
+
+  const summary = failedTasks.map(summaryLine).join(" ");
+  const partialOutputPreviews = failedTasks
+    .map(outputPreview)
+    .filter(isTaskOutputPreview);
+
+  return {
+    summary,
+    likelyCause: likelyCause(failedTasks),
+    suggestions: suggestions(failedTasks, partialOutputPreviews.length > 0),
+    partialOutputPreviews: partialOutputPreviews.length > 0
+      ? partialOutputPreviews
+      : undefined,
+  };
+}
+
+function likelyCause(tasks: TaskView[]): string {
+  if (tasks.every((task) => task.timedOut)) {
+    if (tasks.some(outputChars) && tasks.some(hasRecentOutput)) {
+      return "Task needed more time; at least one provider was still producing output before the deadline.";
+    }
+
+    if (tasks.some(outputChars)) {
+      return "Provider timeout after partial progress.";
+    }
+
+    return "Provider timeout before useful output; this may be slow startup, a model hang, or provider configuration.";
+  }
+
+  if (tasks.some((task) => task.drainTimedOut)) {
+    return "Output drain timed out; captured output may be incomplete.";
+  }
+
+  if (tasks.some((task) => task.exitCode !== undefined && task.exitCode !== 0)) {
+    return "Provider command error or bad configuration.";
+  }
+
+  if (tasks.some((task) => task.status === "cancelled")) {
+    return "Some providers were cancelled before returning an answer.";
+  }
+
+  return "Provider failure; inspect task events and captured output for details.";
+}
+
+function suggestions(
+  tasks: TaskView[],
+  hasPartialOutput: boolean,
+): string[] {
+  const result = new Set<string>();
+
+  if (tasks.some((task) => task.timedOut)) {
+    result.add("Retry the timed-out provider with a longer timeoutMs.");
+  }
+
+  if (hasPartialOutput) {
+    result.add("Inspect partial output and events with ennodia_get_task.");
+  }
+
+  if (tasks.some((task) => task.exitCode !== undefined && task.exitCode !== 0)) {
+    result.add("Inspect stderr and task events with ennodia_get_task.");
+    result.add("Retry with a different harness if the provider command looks broken.");
+  }
+
+  if (tasks.some((task) => task.drainTimedOut)) {
+    result.add("Inspect captured output; the process exited but output capture did not fully drain.");
+  }
+
+  if (result.size === 0) {
+    result.add("Inspect task events with ennodia_get_task.");
+  }
+
+  return [...result];
+}
+
+function summaryLine(task: TaskView): string {
+  const status = task.timedOut ? "timed out" : task.status;
+  const facts = [
+    `${task.harnessName} ${status} after ${formatDuration(task.elapsedMs)}.`,
+    `${task.stdoutChars + task.stderrChars} chars captured.`,
+  ];
+
+  if (task.exitCode !== undefined && task.exitCode !== null) {
+    facts.push(`Exit code ${task.exitCode}.`);
+  }
+
+  return facts.join(" ");
+}
+
+function outputPreview(task: TaskView): TaskOutputPreview | undefined {
+  const output = `${task.stdout.trim()}\n${task.stderr.trim()}`.trim();
+  if (!output) {
+    return undefined;
+  }
+
+  return {
+    harnessId: task.harnessId,
+    chars: task.stdoutChars + task.stderrChars,
+    preview: truncate(output.replace(/\s+/g, " "), PREVIEW_CHARS),
+  };
+}
+
+function outputChars(task: TaskView): number {
+  return task.stdoutChars + task.stderrChars;
+}
+
+function hasRecentOutput(task: TaskView): boolean {
+  if (!task.lastOutputAt || !task.endedAt) {
+    return false;
+  }
+
+  return new Date(task.endedAt).getTime() - new Date(task.lastOutputAt).getTime() <
+    10_000;
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1_000) {
+    return `${ms}ms`;
+  }
+
+  return `${Math.round(ms / 1_000)}s`;
+}
+
+function truncate(text: string, maxChars: number): string {
+  if (text.length <= maxChars) {
+    return text;
+  }
+
+  return `${text.slice(0, maxChars - 3)}...`;
+}
+
+function isTaskOutputPreview(
+  preview: TaskOutputPreview | undefined,
+): preview is TaskOutputPreview {
+  return Boolean(preview);
+}

package/src/harnesses.ts

@@ -0,0 +1,302 @@
+import { existsSync } from "node:fs";
+
+export type HarnessKind = "cli" | "app";
+
+export type HarnessRunInput = {
+  prompt: string;
+  cwd?: string;
+  model?: string;
+  timeoutMs?: number;
+};
+
+export type CommandSpec = {
+  command: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  stdin?: string;
+};
+
+export type HarnessAdapter = {
+  id: string;
+  name: string;
+  kind: HarnessKind;
+  commandCandidates: string[];
+  appPaths?: string[];
+  versionArgs?: string[];
+  capabilities: string[];
+  notes?: string[];
+  buildCommand?: (commandPath: string, input: HarnessRunInput) => CommandSpec;
+};
+
+export type HarnessDiscovery = {
+  id: string;
+  name: string;
+  kind: HarnessKind;
+  available: boolean;
+  runnable: boolean;
+  commandPath?: string;
+  appPath?: string;
+  version?: string;
+  capabilities: string[];
+  notes: string[];
+};
+
+export type DiscoverHarnessesOptions = {
+  refresh?: boolean;
+  maxAgeMs?: number;
+};
+
+type CaptureResult = {
+  exitCode: number | null;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+};
+
+const DEFAULT_VERSION_TIMEOUT_MS = 2_500;
+const DEFAULT_DISCOVERY_CACHE_MS = 30_000;
+
+let cachedDiscovery:
+  | { createdAtMs: number; harnesses: HarnessDiscovery[] }
+  | undefined;
+let inFlightDiscovery: Promise<HarnessDiscovery[]> | undefined;
+
+export const harnessAdapters: HarnessAdapter[] = [
+  {
+    id: "claude-code",
+    name: "Claude Code",
+    kind: "cli",
+    commandCandidates: ["claude"],
+    versionArgs: ["--version"],
+    capabilities: ["reasoning", "code", "agents", "mcp", "non-interactive-cli"],
+    notes: ["Runs through the supported Claude Code CLI surface."],
+    buildCommand: (commandPath, input) => {
+      const args = [
+        "-p",
+        "--output-format",
+        "text",
+        "--no-session-persistence",
+      ];
+
+      if (input.model) {
+        args.push("--model", input.model);
+      }
+
+      args.push(input.prompt);
+      return { command: commandPath, args, cwd: input.cwd };
+    },
+  },
+  {
+    id: "codex",
+    name: "Codex CLI",
+    kind: "cli",
+    commandCandidates: ["codex"],
+    versionArgs: ["--version"],
+    capabilities: ["reasoning", "code", "agents", "mcp", "non-interactive-cli"],
+    notes: ["Defaults to read-only sandboxing for Ennodia-launched tasks."],
+    buildCommand: (commandPath, input) => {
+      const args = [
+        "exec",
+        "--color",
+        "never",
+        "--sandbox",
+        "read-only",
+        "--skip-git-repo-check",
+        "--ephemeral",
+      ];
+
+      if (input.cwd) {
+        args.push("-C", input.cwd);
+      }
+
+      if (input.model) {
+        args.push("--model", input.model);
+      }
+
+      args.push(input.prompt);
+      return { command: commandPath, args, cwd: input.cwd };
+    },
+  },
+  {
+    id: "opencode",
+    name: "OpenCode",
+    kind: "cli",
+    commandCandidates: ["opencode"],
+    versionArgs: ["--version"],
+    capabilities: ["reasoning", "code", "agents", "non-interactive-cli"],
+    notes: ["Runs through `opencode run` without permission-bypass flags."],
+    buildCommand: (commandPath, input) => {
+      const args = ["run"];
+
+      if (input.cwd) {
+        args.push("--dir", input.cwd);
+      }
+
+      if (input.model) {
+        args.push("--model", input.model);
+      }
+
+      args.push(input.prompt);
+      return { command: commandPath, args, cwd: input.cwd };
+    },
+  },
+  {
+    id: "antigravity",
+    name: "Antigravity",
+    kind: "cli",
+    commandCandidates: ["agy"],
+    versionArgs: ["--version"],
+    appPaths: [
+      "/Applications/Antigravity.app",
+      "/Applications/Antigravity IDE.app",
+    ],
+    capabilities: ["ide", "browser-automation", "agents", "non-interactive-cli"],
+    notes: [
+      "Runs through the supported `agy` CLI surface.",
+      "Defaults to Antigravity sandbox mode for Ennodia-launched tasks.",
+      "Sends prompts through stdin because `agy --print` does not consume positional prompts.",
+    ],
+    buildCommand: (commandPath, input) => {
+      const args = [
+        "--sandbox",
+        "--print",
+        "--print-timeout",
+        toGoDuration(input.timeoutMs),
+      ];
+
+      if (input.cwd) {
+        args.push("--add-dir", input.cwd);
+      }
+
+      if (input.model) {
+        args.push("--model", input.model);
+      }
+
+      return { command: commandPath, args, cwd: input.cwd, stdin: input.prompt };
+    },
+  },
+];
+
+export async function discoverHarnesses(
+  options: DiscoverHarnessesOptions = {},
+): Promise<HarnessDiscovery[]> {
+  const now = Date.now();
+  const maxAgeMs = options.maxAgeMs ?? DEFAULT_DISCOVERY_CACHE_MS;
+
+  if (
+    !options.refresh &&
+    cachedDiscovery &&
+    now - cachedDiscovery.createdAtMs <= maxAgeMs
+  ) {
+    return cachedDiscovery.harnesses;
+  }
+
+  if (!options.refresh && inFlightDiscovery) {
+    return inFlightDiscovery;
+  }
+
+  inFlightDiscovery = Promise.all(harnessAdapters.map(discoverHarness)).then(
+    (harnesses) => {
+      cachedDiscovery = { createdAtMs: Date.now(), harnesses };
+      return harnesses;
+    },
+  );
+
+  try {
+    return await inFlightDiscovery;
+  } finally {
+    inFlightDiscovery = undefined;
+  }
+}
+
+export function findHarnessAdapter(id: string): HarnessAdapter | undefined {
+  return harnessAdapters.find((adapter) => adapter.id === id);
+}
+
+async function discoverHarness(
+  adapter: HarnessAdapter,
+): Promise<HarnessDiscovery> {
+  const commandPath = adapter.commandCandidates
+    .map((candidate) => Bun.which(candidate))
+    .find((match): match is string => Boolean(match));
+
+  const appPath = adapter.appPaths?.find((path) => existsSync(path));
+  const version = commandPath ? await readVersion(commandPath, adapter) : undefined;
+  const available = Boolean(commandPath || appPath);
+  const runnable = Boolean(commandPath && adapter.buildCommand);
+
+  return {
+    id: adapter.id,
+    name: adapter.name,
+    kind: adapter.kind,
+    available,
+    runnable,
+    commandPath,
+    appPath,
+    version,
+    capabilities: adapter.capabilities,
+    notes: adapter.notes ?? [],
+  };
+}
+
+async function readVersion(
+  commandPath: string,
+  adapter: HarnessAdapter,
+): Promise<string | undefined> {
+  if (!adapter.versionArgs) {
+    return undefined;
+  }
+
+  const result = await capture(commandPath, adapter.versionArgs, {
+    timeoutMs: DEFAULT_VERSION_TIMEOUT_MS,
+  });
+
+  const text = `${result.stdout}\n${result.stderr}`.trim();
+  return text || undefined;
+}
+
+async function capture(
+  command: string,
+  args: string[],
+  options: { timeoutMs: number },
+): Promise<CaptureResult> {
+  const process = Bun.spawn({
+    cmd: [command, ...args],
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  let timedOut = false;
+  const timeout = setTimeout(() => {
+    timedOut = true;
+    process.kill();
+  }, options.timeoutMs);
+
+  try {
+    const [stdout, stderr, exitCode] = await Promise.all([
+      streamToText(process.stdout),
+      streamToText(process.stderr),
+      process.exited,
+    ]);
+
+    return { stdout, stderr, exitCode, timedOut };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function streamToText(
+  stream: ReadableStream<Uint8Array> | null,
+): Promise<string> {
+  if (!stream) {
+    return "";
+  }
+
+  return await new Response(stream).text();
+}
+
+function toGoDuration(timeoutMs = 5 * 60 * 1000): string {
+  const seconds = Math.max(1, Math.ceil(timeoutMs / 1000));
+  return `${seconds}s`;
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createEnnodiaServer, shutdownEnnodia } from "./server";
+
+const server = createEnnodiaServer();
+const transport = new StdioServerTransport();
+const SHUTDOWN_DEADLINE_MS = 5_000;
+let shutdownPromise: Promise<void> | undefined;
+
+transport.onclose = () => {
+  void shutdown("transport closed");
+};
+
+process.once("SIGINT", () => {
+  void shutdown("SIGINT", 130);
+});
+
+process.once("SIGTERM", () => {
+  void shutdown("SIGTERM", 143);
+});
+
+try {
+  await server.connect(transport);
+} catch (error) {
+  console.error(error instanceof Error ? error.stack ?? error.message : error);
+  await shutdownEnnodia({ deadlineMs: SHUTDOWN_DEADLINE_MS });
+  process.exit(1);
+}
+
+async function shutdown(reason: string, exitCode?: number): Promise<void> {
+  shutdownPromise ??= Promise.resolve().then(() => closeAndShutdown(reason));
+
+  await shutdownPromise;
+
+  if (exitCode !== undefined) {
+    process.exit(exitCode);
+  }
+}
+
+async function closeAndShutdown(reason: string): Promise<void> {
+  try {
+    await server.close();
+  } catch (error) {
+    console.error(
+      `Failed to close MCP server after ${reason}: ${
+        error instanceof Error ? error.message : String(error)
+      }`,
+    );
+  }
+
+  await shutdownEnnodia({ deadlineMs: SHUTDOWN_DEADLINE_MS });
+}

package/src/planner.ts

@@ -0,0 +1,106 @@
+import type { HarnessDiscovery } from "./harnesses";
+
+export type RoutePlan = {
+  category: "code" | "research" | "browser" | "image" | "general";
+  reasons: string[];
+  candidates: string[];
+  selected?: string;
+  parallelSuggested: boolean;
+  compareSuggested: boolean;
+  mermaid: string;
+};
+
+export function planRoute(
+  prompt: string,
+  harnesses: HarnessDiscovery[],
+): RoutePlan {
+  const lower = prompt.toLowerCase();
+  const runnable = harnesses.filter((harness) => harness.runnable);
+  const runnableIds = new Set(runnable.map((harness) => harness.id));
+  const reasons: string[] = [];
+
+  let category: RoutePlan["category"] = "general";
+
+  if (/\b(code|bug|diff|repo|typescript|javascript|python|test|review)\b/.test(lower)) {
+    category = "code";
+    reasons.push("The prompt looks code-oriented.");
+  } else if (/\b(browser|website|click|screenshot|ui|page|automation)\b/.test(lower)) {
+    category = "browser";
+    reasons.push("The prompt mentions browser or UI automation.");
+  } else if (/\b(image|visual|design|screenshot|mockup)\b/.test(lower)) {
+    category = "image";
+    reasons.push("The prompt mentions visual or image work.");
+  } else if (/\b(research|compare|latest|source|web|investigate)\b/.test(lower)) {
+    category = "research";
+    reasons.push("The prompt looks research-oriented.");
+  } else {
+    reasons.push("No specialist category was obvious, so Ennodia chose a general route.");
+  }
+
+  const preferredByCategory: Record<RoutePlan["category"], string[]> = {
+    code: ["codex", "claude-code", "opencode", "antigravity"],
+    research: ["claude-code", "codex", "opencode"],
+    browser: ["antigravity", "opencode", "claude-code", "codex"],
+    image: ["antigravity", "claude-code", "opencode", "codex"],
+    general: ["claude-code", "codex", "opencode", "antigravity"],
+  };
+
+  const candidates = [
+    ...preferredByCategory[category].filter((id) => runnableIds.has(id)),
+    ...runnable.map((harness) => harness.id).filter(
+      (id) => !preferredByCategory[category].includes(id),
+    ),
+  ];
+
+  const complexSignals = /\b(compare|several|multiple|parallel|architecture|review|tradeoff|best|judge)\b/.test(
+    lower,
+  );
+  const parallelSuggested = candidates.length > 1 && complexSignals;
+  const compareSuggested = parallelSuggested;
+
+  return {
+    category,
+    reasons,
+    candidates,
+    selected: candidates[0],
+    parallelSuggested,
+    compareSuggested,
+    mermaid: renderPlanMermaid(candidates, parallelSuggested, compareSuggested),
+  };
+}
+
+function renderPlanMermaid(
+  candidates: string[],
+  parallelSuggested: boolean,
+  compareSuggested: boolean,
+): string {
+  const lines = [
+    "flowchart TD",
+    '    request["Request"]',
+    '    classify["Classify"]',
+    '    plan["Plan route"]',
+    "    request --> classify",
+    "    classify --> plan",
+  ];
+
+  const selected = parallelSuggested ? candidates : candidates.slice(0, 1);
+
+  for (const id of selected) {
+    const nodeId = id.replace(/[^a-zA-Z0-9]/g, "_");
+    lines.push(`    ${nodeId}["${id}"]`);
+    lines.push(`    plan --> ${nodeId}`);
+  }
+
+  if (compareSuggested && selected.length > 1) {
+    lines.push('    compare["Compare outputs"]');
+    for (const id of selected) {
+      const nodeId = id.replace(/[^a-zA-Z0-9]/g, "_");
+      lines.push(`    ${nodeId} --> compare`);
+    }
+    lines.push('    compare --> result["Final result"]');
+  } else {
+    lines.push('    plan --> result["Final result"]');
+  }
+
+  return lines.join("\n");
+}