ennodia 0.4.1 → 0.5.0

package/src/runs.ts

@@ -6,8 +6,9 @@ import {
   type BudgetCheck,
   type BudgetLimits,
 } from "./budget";
-import { MAX_PROMPT_CANDIDATE_CHARS, type CompareManager, type CompareView } from "./compare";
+import { MAX_PROMPT_CANDIDATE_CHARS, type CompareManager, type CompareView, type KeepInMindNote } from "./compare";
 import { diagnoseTasks, type TaskDiagnosis } from "./diagnosis";
+import { HarnessReadinessError, harnessAttention, nativeReadinessFailure, type HarnessAttention, type PreflightReport, type HarnessReadiness, type ReadinessState } from "./readiness";
 import type {
   DiscoverHarnessesOptions,
   HarnessAdapter,
@@ -98,6 +99,10 @@ export type RunStartInput = {
 };
 
 export type RunView = {
+  installation?: InstallationReport;
+  actionRequired?: HarnessAttention[];
+  preflight?: PreflightReport;
+  coverage?: { requested: number; succeeded: number; failed: number; skipped: number };
   id: string;
   status: RunStatus;
   mode: RunMode;
@@ -126,6 +131,8 @@ export type RunView = {
   etaConfidence: "timeout-budget" | "unknown" | "complete";
   finalAnswer?: string;
   finalAnswerChars: number;
+  /** Recipient context from Compare, kept separate from answer artifacts. */
+  keepInMind?: KeepInMindNote[];
   error?: string;
   diagnosis?: TaskDiagnosis;
   failedTaskDiagnosis?: TaskDiagnosis;
@@ -158,11 +165,14 @@ export type PlanRoute = (
 ) => RoutePlan;
 
 export type RunManagerDependencies = {
+  getInstallation?: () => InstallationReport;
   taskManager: TaskManager;
   compareManager: CompareManager;
   discoverHarnesses: DiscoverHarnesses;
   findHarnessAdapter: FindHarnessAdapter;
   planRoute: PlanRoute;
+  prepareHarnesses?: (harnesses: HarnessDiscovery[], ids: string[], input: RunStartInput) => Promise<PreflightReport>;
+  describeReadiness?: (harness: HarnessDiscovery, state: ReadinessState, model?: string) => HarnessReadiness;
 };
 
 export type RunManagerShutdownOptions = {
@@ -175,6 +185,8 @@ export type RunManagerOptions = {
 };
 
 type InternalRun = {
+  actionRequired?: HarnessAttention[];
+  preflight?: PreflightReport;
   id: string;
   status: RunStatus;
   mode: RunMode;
@@ -191,6 +203,7 @@ type InternalRun = {
   taskIds: string[];
   compareId?: string;
   finalAnswer?: string;
+  keepInMind?: KeepInMindNote[];
   error?: string;
   diagnosis?: TaskDiagnosis;
   failedTaskDiagnosis?: TaskDiagnosis;
@@ -258,6 +271,8 @@ export class RunManager {
     const selectedHarnessIds = selectHarnessIds(input.harnessId, mode, plan);
 
     if (selectedHarnessIds.length === 0) {
+      const blocked = harnessAttention(harnesses);
+      if (blocked.length) throw new HarnessReadinessError(blocked);
       throw new Error("No runnable harnesses were found.");
     }
 
@@ -290,6 +305,9 @@ export class RunManager {
       throw new Error(`Budget limit exceeded: ${budget.issues.join(" ")}`);
     }
 
+    const preflight = await this.dependencies.prepareHarnesses?.(harnesses, selectedHarnessIds, {
+      ...input, budget: input.budget?.maxEstimatedInputTokens !== undefined ? { ...input.budget, maxEstimatedInputTokens: input.budget.maxEstimatedInputTokens - budget.estimate.estimatedTotalInputTokens } : input.budget,
+    });
     const now = Date.now();
     const run: InternalRun = {
       id: randomUUID(),
@@ -309,6 +327,8 @@ export class RunManager {
       createdAtMs: now,
       updatedAtMs: now,
       events: [],
+      preflight,
+      actionRequired: input.harnessId ? undefined : plan.actionRequired,
       appliedSkills: input.skills?.map(toAppliedSkillInfo),
       budget,
     };
@@ -460,6 +480,11 @@ export class RunManager {
       const task = await this.dependencies.taskManager.waitForTerminal(taskId);
       if (task && run.status !== "cancelled") {
         this.pushEvent(run, eventFromTask(task));
+        const state = task.status === "failed" ? nativeReadinessFailure(task.stdout, task.stderr) : undefined;
+        if (state) {
+          const discovery = (await this.dependencies.discoverHarnesses()).find(h => h.id === task.harnessId);
+          if (discovery?.readiness) run.actionRequired = [...(run.actionRequired ?? []).filter(a => a.harnessId !== task.harnessId), { harnessId: task.harnessId, harnessName: task.harnessName, readiness: this.dependencies.describeReadiness?.(discovery, state, task.model) ?? { ...discovery.readiness, state, model: task.model } }];
+        }
       }
       return task;
     });
@@ -568,6 +593,9 @@ export class RunManager {
       ? `${advice}\n\nChosen answer from ${chosen.label ?? chosen.id}, unchanged:\n\n${chosen.content}`
       : advice;
     if (result.status === "succeeded" && finalAnswer) {
+      if (result.advisor?.keepInMind?.length) {
+        run.keepInMind = result.advisor.keepInMind;
+      }
       this.pushEvent(run, {
         type: "compare-succeeded",
         compareId: compare.id,
@@ -667,9 +695,19 @@ export class RunManager {
       etaConfidence: eta.etaConfidence,
       finalAnswer: finalAnswer ? truncate(finalAnswer, maxAnswerChars) : undefined,
       finalAnswerChars: finalAnswer?.length ?? 0,
+      keepInMind: run.keepInMind,
       error: run.error,
       diagnosis: run.diagnosis,
       failedTaskDiagnosis: run.failedTaskDiagnosis,
+      actionRequired: run.actionRequired,
+      installation: this.dependencies.getInstallation?.(),
+      preflight: run.preflight,
+      coverage: {
+        requested: run.selectedHarnessIds.length + (run.harnessOverridden ? 0 : run.plan.actionRequired?.length ?? 0),
+        succeeded: run.taskIds.filter(id => this.dependencies.taskManager.get(id, { includeOutput: false, includeEvents: false })?.status === "succeeded").length,
+        failed: run.taskIds.filter(id => ["failed", "cancelled"].includes(this.dependencies.taskManager.get(id, { includeOutput: false, includeEvents: false })?.status ?? "")).length,
+        skipped: run.harnessOverridden ? 0 : run.plan.actionRequired?.length ?? 0,
+      },
       eventCount: run.events.length,
       events: options.includeEvents === false ? [] : tailItems(run.events, maxEvents),
       appliedSkills: run.appliedSkills,
@@ -1094,3 +1132,4 @@ async function settleWithDeadline(
     });
   });
 }
+import type { InstallationReport } from "./installation";

package/src/server.ts

@@ -10,7 +10,10 @@ import {
 import { renderPlanMermaid } from "./planner";
 import { formatHarnessPriorityList } from "./priority";
 import { ENNODIA_VERSION } from "./version";
-import { REASONING_EFFORTS } from "./harnesses";
+import { REASONING_EFFORTS, type HarnessDiscovery } from "./harnesses";
+import { HarnessReadinessError, harnessAttention, type HarnessAttention } from "./readiness";
+import type { InstallationReport } from "./installation";
+import { ACCESS_TEXT, HARNESS_GUIDE_URL, INSTALL_GUIDE_URL, MCP_APP_MIME_TYPE, SETUP_APP_HTML, SETUP_APP_TOOL_META, SETUP_APP_URI, accessRank, type AccessKey } from "./setup-app";
 
 const defaultCore = createDefaultEnnodiaCore();
 const comparePriorityText = formatHarnessPriorityList();
@@ -60,6 +63,8 @@ export const CORE_TOOL_NAMES: readonly string[] = [
   "ennodia_get_run",
   "ennodia_cancel_run",
   "ennodia_list_harnesses",
+  "ennodia_setup",
+  "ennodia_check_harnesses",
   "ennodia_list_skills",
   "ennodia_history",
 ];
@@ -69,7 +74,7 @@ export const CORE_TOOL_NAMES: readonly string[] = [
  * 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 (/^ennodia_(?:list_|get_|history$|plan$|estimate_|setup$)/.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 };
@@ -90,13 +95,24 @@ export function createEnnodiaServer(
   const server = new McpServer({
     name: "ennodia",
     version: ENNODIA_VERSION,
-  });
+  }, { instructions: serverInstructions(core.getInstallation?.()) });
 
   // 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 handler = rest[rest.length - 1] as (...args: unknown[]) => Promise<unknown>;
+    rest[rest.length - 1] = async (...args: unknown[]) => {
+      try { return await handler(...args); }
+      catch (error) {
+        if (error instanceof HarnessReadinessError) {
+          const installation = core.getInstallation?.();
+          return { ...setupResult({ error: error.message, installation, actionRequired: error.actionRequired, coverage: { started: 0 } }, error.actionRequired, installation), isError: true };
+        }
+        throw error;
+      }
+    };
     const tool = registerTool(name, { ...config, annotations: { ...toolAnnotations(name), ...config.annotations } }, ...rest);
     registered.set(name, tool);
     return tool;
@@ -107,7 +123,7 @@ export function createEnnodiaServer(
     {
       title: "List Ennodia harnesses",
       description:
-        "Discover local harnesses, availability, versions, capabilities, adapter notes, and inputGuidance. Before audio/image/video work, read inputGuidance: model capabilities do not guarantee native input through a harness. Use first when setup or routing fails.",
+        "Discover supported agents and cached readiness for routing. Do not summarize it for the user; for setup or status requests call ennodia_setup. Read inputGuidance before media work.",
       inputSchema: {
         refresh: z
           .boolean()
@@ -120,6 +136,42 @@ export function createEnnodiaServer(
     async ({ refresh }) => jsonResult(await core.listHarnesses({ refresh })),
   );
 
+  // Read-only, so clients such as Codex show setup without an approval prompt.
+  server.registerTool("ennodia_setup", {
+    title: "Show Ennodia setup",
+    description: "Show the user Ennodia's agents: each agent's status and the exact fix for blocked ones. Refreshes native sign-in status without model requests. Hosts that render MCP Apps show a card with check buttons; others get a Markdown panel to show the user.",
+    _meta: SETUP_APP_TOOL_META,
+  }, async () => {
+    const harnesses = await core.listHarnesses({ refresh: true });
+    const installation = core.getInstallation?.(true);
+    return setupResult({ installation, harnesses, actionRequired: harnessAttention(harnesses) }, harnesses, installation);
+  });
+
+  server.registerTool("ennodia_check_harnesses", {
+    title: "Recheck or upgrade Ennodia harnesses",
+    description: "Recheck Ennodia's installation and recover affected harnesses. Return installation scope, runtime/package/storage limitations, native recovery commands and actionRequired. Target affected harnessIds; unrelated blockers do not prevent authorized work on usable routes. verify makes a small real model call; upgrade runs supported updaters before rechecking. Never switch account/provider/model silently.",
+    _meta: SETUP_APP_TOOL_META,
+    inputSchema: {
+      harnessIds: z.array(z.string().min(1)).min(1).optional().describe("Harnesses to recheck. Omit for all installed harnesses."),
+      model: z.string().min(1).optional().describe("Exact model to verify on the selected route."),
+      cwd: z.string().optional().describe("Workspace identity for the readiness receipt; probes run in an empty temporary directory."),
+      refresh: z.boolean().default(true).describe("Invalidate cached readiness and recheck native status."),
+      verify: z.boolean().default(false).describe("Verify each selected route with a bounded real model request. Uses provider capacity."),
+      upgrade: z.boolean().default(false).describe("Run supported updaters now, then rediscover and recheck. Deferred while Ennodia tasks are active."),
+    },
+  }, async input => {
+    const result = await core.checkHarnesses(input);
+    return setupResult(result, result.harnesses, result.installation);
+  });
+
+  // Hosts that render MCP Apps show this card for the two tools above.
+  // Other hosts ignore the resource and keep the Markdown panel.
+  server.registerResource("ennodia-setup", SETUP_APP_URI, {
+    title: "Ennodia setup",
+    description: "Setup card for hosts that render MCP Apps.",
+    mimeType: MCP_APP_MIME_TYPE,
+  }, async () => ({ contents: [{ uri: SETUP_APP_URI, mimeType: MCP_APP_MIME_TYPE, text: SETUP_APP_HTML, _meta: { ui: { prefersBorder: true, permissions: { clipboardWrite: {} } } } }] }));
+
   server.registerTool(
     "ennodia_list_skills",
     {
@@ -690,7 +742,7 @@ export function createEnnodiaServer(
         prompt: z
           .string()
           .min(1)
-          .describe("The user task to route to local AI harnesses. For native media, first read ennodia_list_harnesses inputGuidance, specify local paths and a harness/model, then verify one small sample with mode single and compare false. Ennodia sends text, not media attachments."),
+          .describe("The user task to route to local AI harnesses. Include relevant Keep in mind constraints, evidence, and unresolved assumptions in this prompt. For native media, first read ennodia_list_harnesses inputGuidance, specify local paths and a harness/model, then verify one small sample with mode single and compare false. Ennodia sends text, not media attachments."),
         category: categorySchema.optional(),
         harnessId: z
           .string()
@@ -850,7 +902,7 @@ export function createEnnodiaServer(
     {
       title: "Get Ennodia run",
       description:
-        "Inspect a run or wait up to waitMs for completion. Prefer waitMs: 30000, compact: true and includeEvents: false while awaiting results. A nonterminal response means work continues; do not claim its findings were consumed.",
+        "Inspect a run or wait up to waitMs for completion, including task-specific keepInMind notes when Compare returns them. Prefer waitMs: 30000, compact: true and includeEvents: false while awaiting results. A nonterminal response means work continues; do not claim its findings were consumed.",
       inputSchema: {
         runId: z.string().min(1).describe("Run ID returned by ennodia_run."),
         compact: z.boolean().default(false).describe("Omit repeated routing, budget, prompt preview and skill metadata. Preserve status, timing, task IDs, answers and errors. Answer and event limits still apply. Use false for full diagnostics."),
@@ -1141,7 +1193,7 @@ export function createEnnodiaServer(
     {
       title: "Get Ennodia Judge + Result Advisor comparison",
       description:
-        "Inspect comparison status, candidate inputs, Judge analysis, Result Advisor answer, child task IDs, degradation state, and ETA.",
+        "Inspect comparison status, candidate inputs, Judge analysis, Result Advisor answer and keepInMind notes with evidence and uncertainty, child task IDs, degradation state, and ETA.",
       inputSchema: {
         compareId: z
           .string()
@@ -1280,6 +1332,53 @@ export async function shutdownEnnodia(
   await defaultCore.shutdown(options);
 }
 
+/** Startup instructions load into every session that has Ennodia configured,
+ * so they stay short and keep Ennodia quiet until there is something to fix. */
+export function serverInstructions(installation?: InstallationReport): string {
+  const lines = [
+    "Ennodia hands work to the user's other local agents. Do not open with Ennodia's status or list agents the user did not ask about: ennodia_run checks the agents it selects before starting.",
+    "If a requested agent is blocked, the result carries an ennodia://setup panel: show the user its fix as written. After the user fixes it, recheck that agent and model with ennodia_check_harnesses (verify: true), then continue the task. If a run skipped agents (actionRequired), say so in one line. Unrelated blockers must not hold up work on usable agents.",
+    "For setup or status requests, call ennodia_setup and show its panel. Hosts that render MCP Apps show it as a card; then add one line at most.",
+    "Unverified means not checked yet, not failed. A verified default model does not prove access to other models. Never collect credentials in chat, never switch account, provider or model silently, and never claim a check ran when it did not. Follow the user's existing authorization and the host's approval policy; add no approval step of your own.",
+  ];
+  if (installation?.status === "broken") lines.push(`Ennodia's installation is broken: ${installation.limitations.join(" ")} Tell the user before starting work and link ${INSTALL_GUIDE_URL}.`);
+  else if (installation?.status === "limited") lines.push(`Installation notes, to mention only when they affect the request: ${installation.limitations.join(" ")}`);
+  return lines.join("\n");
+}
+
+function accessKey(route: HarnessDiscovery | HarnessAttention): AccessKey {
+  return "id" in route && !route.runnable ? "missing" : route.readiness?.state ?? "unverified";
+}
+
+/** Keep the JSON text contract intact for clients that parse tool text, and
+ * add the panel an agent shows when the host has no card: each agent's status
+ * in plain words, then the exact sign-in commands. */
+function setupResult(value: unknown, routes: (HarnessDiscovery | HarnessAttention)[], installation?: InstallationReport) {
+  const cell = (text: string) => text.replaceAll("|", "\\|").replace(/[\r\n]+/g, " ");
+  const lines = ["## Ennodia agents"];
+  if (installation && installation.status !== "healthy") {
+    lines.push("", `Installation ${installation.status}:`, ...installation.limitations.map(limit => `- ${limit}`), "", `Repair it with the [installation guide](${INSTALL_GUIDE_URL}), then restart the MCP connection.`);
+  }
+  const rows = routes.map(route => {
+    const key = accessKey(route);
+    return { name: "id" in route ? route.name : route.harnessName, model: route.readiness?.model, key, command: key === "login-required" ? route.readiness?.recovery?.command ?? [] : [] };
+  }).sort((a, b) => accessRank(a.key) - accessRank(b.key));
+  if (rows.length) lines.push("", "| Agent | Status | Next step |", "| --- | --- | --- |");
+  else lines.push("", `No supported agents were found. Install one with the [harness guide](${HARNESS_GUIDE_URL}).`);
+  for (const row of rows) {
+    const next = row.key === "missing" ? `${ACCESS_TEXT.missing.next} [Install guide](${HARNESS_GUIDE_URL})` : ACCESS_TEXT[row.key].next;
+    lines.push(`| ${cell(row.name + (row.model ? ` · ${row.model}` : ""))} | ${ACCESS_TEXT[row.key].label} | ${cell(next)} |`);
+  }
+  // Only a login blocker calls for a command. Other blockers need credits or a new key.
+  for (const row of rows.filter(row => row.command.length)) {
+    const command = row.command.map(arg => /^[A-Za-z0-9_./:@=+-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`).join(" ");
+    const fence = "`".repeat(Math.max(3, ...[...command.matchAll(/`+/g)].map(match => match[0].length + 1)));
+    lines.push("", `Sign in to ${row.name} in a terminal:`, "", `${fence}sh\n${command}\n${fence}`);
+  }
+  if (rows.some(row => accessRank(row.key) === 0)) lines.push("", "Keep sign-in and API keys in each agent's own CLI, never in this chat.");
+  return { content: [...jsonResult(value).content, { type: "resource" as const, resource: { uri: "ennodia://setup", mimeType: "text/markdown", text: lines.join("\n") } }] };
+}
+
 function jsonResult(value: unknown) {
   return {
     content: [

package/src/setup-app.ts

@@ -0,0 +1,338 @@
+import type { ReadinessState } from "./readiness";
+import { ENNODIA_VERSION } from "./version";
+
+/** MCP Apps (`io.modelcontextprotocol/ui`, stable 2026-01-26) lets a host show
+ * a server's HTML view inside the conversation. Ennodia uses one view: a card
+ * of agents and their fixes. Other hosts show the Markdown panel instead.
+ * The card calls only `ennodia_check_harnesses` and never collects credentials. */
+export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+export const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+export const SETUP_APP_URI = "ui://ennodia/setup.html";
+
+/** The flat key serves hosts that predate the nested `ui.resourceUri` form. */
+export const SETUP_APP_TOOL_META = { ui: { resourceUri: SETUP_APP_URI }, "ui/resourceUri": SETUP_APP_URI };
+
+export type AccessKey = ReadinessState | "missing";
+
+/** Plain words for each agent state, shared by the Markdown panel and the card. */
+export const ACCESS_TEXT: Record<AccessKey, { label: string; next: string }> = {
+  "login-required": { label: "Needs sign-in", next: "Sign in with the command below, then check again." },
+  "credentials-expired": { label: "API key expired", next: "Replace the key in the agent's own settings, then check again. Signing in does not renew it." },
+  "quota-exhausted": { label: "Out of quota", next: "Restore credits or quota with the provider, then check again. Signing in does not help." },
+  "model-unavailable": { label: "Model unavailable", next: "This agent cannot use this model. Pick another from its model list." },
+  "setup-required": { label: "Needs setup", next: "Finish the agent's own setup, then check again." },
+  unreachable: { label: "Check failed", next: "The check did not finish. Look at the connection or the agent's setup, then check again." },
+  updating: { label: "Updating", next: "An update is running. Check again when it finishes." },
+  unverified: { label: "Not checked yet", next: "Ennodia checks it on first use." },
+  ready: { label: "Ready", next: "" },
+  missing: { label: "Not available", next: "Not installed, or it cannot run without a terminal." },
+};
+
+/** Agents that need the user come first, unavailable ones last. */
+export function accessRank(key: AccessKey): number {
+  return key === "unverified" ? 1 : key === "ready" ? 2 : key === "missing" ? 3 : 0;
+}
+
+export const HARNESS_GUIDE_URL = "https://ennodia.cherninlab.com/docs/reference/supported-harnesses/";
+export const INSTALL_GUIDE_URL = "https://ennodia.cherninlab.com/docs/install/";
+
+/** Plain ES5 so it runs in any host webview without a build step. */
+const SETUP_APP_SCRIPT = String.raw`
+(function () {
+  "use strict";
+  var ACCESS = __ACCESS__, RANK = __RANK__;
+  var state = { agents: [], installation: null, input: {}, host: {}, busy: {}, notes: {}, newlyReady: {}, error: "", loaded: false };
+  var nextId = 1, pending = {}, lastHeight = 0;
+
+  function post(message) { window.parent.postMessage(message, "*"); }
+  function request(method, params) {
+    var id = nextId++;
+    post({ jsonrpc: "2.0", id: id, method: method, params: params || {} });
+    return new Promise(function (resolve, reject) { pending[id] = { resolve: resolve, reject: reject }; });
+  }
+  function notify(method, params) { post({ jsonrpc: "2.0", method: method, params: params || {} }); }
+  function reply(id, result) { post({ jsonrpc: "2.0", id: id, result: result }); }
+
+  window.addEventListener("message", function (event) {
+    if (event.source !== window.parent) return;
+    var m = event.data;
+    if (!m || m.jsonrpc !== "2.0") return;
+    if (m.method === undefined) {
+      var waiting = pending[m.id];
+      if (!waiting) return;
+      delete pending[m.id];
+      if (m.error) waiting.reject(new Error(m.error.message || "The host rejected the request."));
+      else waiting.resolve(m.result);
+      return;
+    }
+    switch (m.method) {
+      case "ui/notifications/tool-input": state.input = (m.params && m.params.arguments) || {}; break;
+      case "ui/notifications/tool-result": showResult(m.params); break;
+      case "ui/notifications/tool-cancelled": state.loaded = true; state.error = "The check was cancelled."; render(); break;
+      case "ui/notifications/host-context-changed": applyContext(m.params); break;
+      case "ui/resource-teardown": case "ping": if (m.id !== undefined) reply(m.id, {}); break;
+      default: if (m.id !== undefined) post({ jsonrpc: "2.0", id: m.id, error: { code: -32601, message: "Method not found" } });
+    }
+  });
+
+  function parse(result) {
+    var blocks = (result && result.content) || [];
+    for (var i = 0; i < blocks.length; i++) {
+      if (blocks[i].type !== "text") continue;
+      try { return JSON.parse(blocks[i].text); } catch (error) { return { error: blocks[i].text }; }
+    }
+    return { error: "Ennodia returned no agent data." };
+  }
+  function failed(result, data) { return Boolean(result && result.isError || data.error); }
+
+  function normalize(h) {
+    var r = h.readiness || {};
+    var key = h.runnable === false ? "missing" : (ACCESS[r.state] ? r.state : "unverified");
+    return { id: h.id, name: h.name || h.id, model: r.model || "", key: key,
+      command: key === "login-required" && r.recovery && Array.isArray(r.recovery.command) ? r.recovery.command : [] };
+  }
+  function find(id) { for (var i = 0; i < state.agents.length; i++) if (state.agents[i].id === id) return state.agents[i]; return null; }
+  function merge(list) {
+    (list || []).forEach(function (h) {
+      var agent = normalize(h), current = find(agent.id);
+      if (current) state.agents[state.agents.indexOf(current)] = agent; else state.agents.push(agent);
+    });
+  }
+
+  function showResult(result) {
+    var data = parse(result);
+    state.loaded = true;
+    state.error = failed(result, data) ? (data.error || "Ennodia reported an error.") : "";
+    if (data.installation) state.installation = data.installation;
+    merge(data.harnesses);
+    // Sort once: rows keep their place after a check, so nothing moves under the pointer.
+    state.agents.sort(function (a, b) { return RANK[a.key] - RANK[b.key]; });
+    render();
+  }
+
+  function check(agent) {
+    var args = { harnessIds: [agent.id], refresh: true, verify: true };
+    var model = agent.model || state.input.model;
+    if (model) args.model = model;
+    if (state.input.cwd) args.cwd = state.input.cwd;
+    var before = agent.key;
+    state.busy[agent.id] = true;
+    state.notes[agent.id] = "Checking…";
+    render();
+    request("tools/call", { name: "ennodia_check_harnesses", arguments: args }).then(function (result) {
+      var data = parse(result);
+      if (failed(result, data)) { state.notes[agent.id] = data.error || "The check failed."; return; }
+      if (data.installation) state.installation = data.installation;
+      merge(data.harnesses);
+      var now = find(agent.id);
+      state.notes[agent.id] = now && now.key === "ready" ? "Ready now." : now && now.key === before ? "No change yet." : "";
+      if (now && now.key === "ready" && before !== "ready") state.newlyReady[agent.id] = true;
+    }, function (error) { state.notes[agent.id] = error.message || "The check failed."; })
+      .then(function () { delete state.busy[agent.id]; render(); });
+  }
+
+  function tellAgent(agent, node) {
+    node.disabled = true;
+    var text = agent.name + (agent.model ? " (" + agent.model + ")" : "") + " is ready in Ennodia now.";
+    request("ui/message", { role: "user", content: [{ type: "text", text: text }] }).then(function () {
+      delete state.newlyReady[agent.id]; state.notes[agent.id] = "Sent to the chat."; render();
+    }, function () { node.disabled = false; state.notes[agent.id] = "The host did not accept the message."; render(); });
+  }
+
+  function openLink(url) {
+    if (state.host.openLinks) request("ui/open-link", { url: url }).catch(function () { window.open(url, "_blank", "noopener"); });
+    else window.open(url, "_blank", "noopener");
+  }
+
+  function shellQuote(args) {
+    return args.map(function (arg) { return /^[A-Za-z0-9_.\/:@=+-]+$/.test(arg) ? arg : "'" + arg.replace(/'/g, "'\\''") + "'"; }).join(" ");
+  }
+
+  function copy(text, node, code) {
+    var reset = function () { setTimeout(function () { node.textContent = "Copy"; }, 1600); };
+    var selected = function () {
+      var range = document.createRange(); range.selectNodeContents(code);
+      var selection = window.getSelection(); selection.removeAllRanges(); selection.addRange(range);
+      node.textContent = "Selected"; reset();
+    };
+    if (navigator.clipboard && navigator.clipboard.writeText) navigator.clipboard.writeText(text).then(function () { node.textContent = "Copied"; reset(); }, selected);
+    else selected();
+  }
+
+  function el(tag, className, text) {
+    var node = document.createElement(tag);
+    if (className) node.className = className;
+    if (text !== undefined) node.textContent = text;
+    return node;
+  }
+  function button(label, className, onClick) {
+    var node = el("button", className, label);
+    node.type = "button";
+    node.addEventListener("click", function () { onClick(node); });
+    return node;
+  }
+
+  function renderAgent(agent) {
+    var needsUser = RANK[agent.key] === 0;
+    var item = el("li", "agent " + (needsUser ? "action" : agent.key === "missing" ? "unavailable" : agent.key));
+    var head = el("div", "head");
+    head.appendChild(el("span", "dot"));
+    var name = el("span", "name", agent.name);
+    if (agent.model) name.appendChild(el("span", "model", agent.model));
+    head.appendChild(name);
+    head.appendChild(el("span", "status", ACCESS[agent.key].label));
+    item.appendChild(head);
+    // An unchecked agent needs nothing from the user; its button is enough.
+    if (ACCESS[agent.key].next && agent.key !== "unverified") item.appendChild(el("p", "next", ACCESS[agent.key].next));
+    if (agent.command.length) {
+      var row = el("div", "command");
+      var code = el("code", "", shellQuote(agent.command));
+      row.appendChild(code);
+      row.appendChild(button("Copy", "ghost", function (node) { copy(code.textContent, node, code); }));
+      item.appendChild(row);
+    }
+    if (state.notes[agent.id]) item.appendChild(el("p", "note", state.notes[agent.id]));
+    var actions = el("div", "actions");
+    if (state.host.serverTools && agent.key !== "ready" && agent.key !== "missing") {
+      var checkButton = button(agent.key === "unverified" ? "Verify" : "Check again", needsUser ? "primary" : "", function () { check(agent); });
+      checkButton.disabled = Boolean(state.busy[agent.id]);
+      actions.appendChild(checkButton);
+    }
+    if (agent.key === "missing") actions.appendChild(button("Install guide", "", function () { openLink(__GUIDE__); }));
+    if (state.newlyReady[agent.id] && state.host.message) actions.appendChild(button("Tell the agent", "primary", function (node) { tellAgent(agent, node); }));
+    if (actions.childNodes.length) item.appendChild(actions);
+    return item;
+  }
+
+  function render() {
+    document.getElementById("loading").hidden = state.loaded;
+    var list = document.getElementById("agents");
+    list.textContent = "";
+    state.agents.forEach(function (a) { list.appendChild(renderAgent(a)); });
+    if (state.loaded && !state.agents.length && !state.error) list.appendChild(el("li", "agent", "No supported agents were found on this machine."));
+    var error = document.getElementById("error");
+    error.textContent = state.error; error.hidden = !state.error;
+    var install = document.getElementById("install"), report = state.installation;
+    install.textContent = "";
+    install.hidden = !report || report.status === "healthy";
+    if (!install.hidden) {
+      install.appendChild(el("p", "", "Ennodia installation: " + report.status + "."));
+      var notes = el("ul");
+      (report.limitations || []).forEach(function (text) { notes.appendChild(el("li", "", text)); });
+      install.appendChild(notes);
+      install.appendChild(button("Installation guide", "", function () { openLink(__INSTALL__); }));
+    }
+    document.getElementById("cost").hidden = !state.host.serverTools || !state.agents.some(function (a) { return a.key !== "ready" && a.key !== "missing"; });
+    resize();
+  }
+
+  function resize() {
+    var height = Math.ceil(document.documentElement.getBoundingClientRect().height);
+    if (height === lastHeight) return;
+    lastHeight = height;
+    notify("ui/notifications/size-changed", { height: height });
+  }
+
+  function applyContext(context) {
+    if (!context) return;
+    var root = document.documentElement;
+    if (context.theme === "light" || context.theme === "dark") { root.setAttribute("data-theme", context.theme); root.style.colorScheme = context.theme; }
+    var variables = context.styles && context.styles.variables;
+    if (variables) Object.keys(variables).forEach(function (key) { if (variables[key]) root.style.setProperty(key, variables[key]); });
+    var fonts = context.styles && context.styles.css && context.styles.css.fonts;
+    if (fonts && !document.getElementById("host-fonts")) { var style = el("style", "", fonts); style.id = "host-fonts"; document.head.appendChild(style); }
+  }
+
+  if (window.ResizeObserver) new ResizeObserver(resize).observe(document.documentElement);
+  render();
+  request("ui/initialize", { appInfo: { name: "ennodia-setup", version: __VERSION__ }, appCapabilities: { availableDisplayModes: ["inline"] }, protocolVersion: "2026-01-26" })
+    .then(function (result) {
+      state.host = (result && result.hostCapabilities) || {};
+      applyContext(result && result.hostContext);
+      notify("ui/notifications/initialized", {});
+      render();
+    }, function () { state.loaded = true; state.error = "This host did not start the Ennodia card."; render(); });
+})();
+`;
+
+const SETUP_APP_STYLE = `
+:root {
+  color-scheme: light dark;
+  --fb-bg: #ffffff; --fb-soft: #f4f4f2; --fb-text: #1c1b19; --fb-muted: #5f5d58; --fb-border: #e4e2dc;
+  --fb-ok: #1f7a3d; --fb-warn: #a65b00; --fb-bad: #b42318;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-theme="light"]) { --fb-bg: #1b1b1a; --fb-soft: #262624; --fb-text: #f2f1ee; --fb-muted: #a9a69f; --fb-border: #3a3936; --fb-ok: #5fd08a; --fb-warn: #f0b04d; --fb-bad: #ff8a7a; }
+}
+:root[data-theme="dark"] { --fb-bg: #1b1b1a; --fb-soft: #262624; --fb-text: #f2f1ee; --fb-muted: #a9a69f; --fb-border: #3a3936; --fb-ok: #5fd08a; --fb-warn: #f0b04d; --fb-bad: #ff8a7a; }
+* { box-sizing: border-box; }
+html, body { margin: 0; }
+body {
+  background: var(--color-background-primary, var(--fb-bg)); color: var(--color-text-primary, var(--fb-text));
+  font: var(--font-text-sm-size, 14px)/var(--font-text-sm-line-height, 1.45) var(--font-sans, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif);
+}
+main { padding: 14px 16px 12px; }
+h1 { font-size: var(--font-heading-xs-size, 15px); font-weight: var(--font-weight-semibold, 600); margin: 0; }
+ul { list-style: none; margin: 0; padding: 0; }
+#agents { margin-top: 10px; border-top: 1px solid var(--color-border-primary, var(--fb-border)); }
+.agent { padding: 10px 0; border-bottom: 1px solid var(--color-border-primary, var(--fb-border)); }
+.head { display: flex; align-items: center; gap: 8px; }
+.dot { width: 8px; height: 8px; border-radius: 50%; flex: none; background: var(--color-text-tertiary, var(--fb-muted)); }
+.ready .dot { background: var(--color-text-success, var(--fb-ok)); }
+.action .dot { background: var(--color-text-warning, var(--fb-warn)); }
+.unavailable .dot { background: transparent; border: 1px solid var(--color-text-tertiary, var(--fb-muted)); }
+.name { font-weight: var(--font-weight-medium, 500); min-width: 0; overflow-wrap: anywhere; }
+.model { margin-left: 6px; font-weight: var(--font-weight-normal, 400); color: var(--color-text-secondary, var(--fb-muted)); font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); font-size: 0.92em; }
+.status { margin-left: auto; white-space: nowrap; color: var(--color-text-secondary, var(--fb-muted)); }
+.ready .status { color: var(--color-text-success, var(--fb-ok)); }
+.action .status { color: var(--color-text-warning, var(--fb-warn)); }
+.next, .note { margin: 4px 0 0 16px; color: var(--color-text-secondary, var(--fb-muted)); }
+.note { color: var(--color-text-primary, var(--fb-text)); }
+.command { display: flex; align-items: center; gap: 8px; margin: 8px 0 0 16px; padding: 6px 6px 6px 10px; border-radius: var(--border-radius-md, 8px); background: var(--color-background-secondary, var(--fb-soft)); }
+.command code { flex: 1 1 auto; min-width: 0; overflow-x: auto; white-space: nowrap; font: 0.92em/1.4 var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); }
+.actions { display: flex; align-items: center; flex-wrap: wrap; gap: 8px; margin: 8px 0 0 16px; }
+button {
+  font: inherit; color: inherit; cursor: pointer; padding: 4px 10px; border-radius: var(--border-radius-sm, 6px);
+  border: 1px solid var(--color-border-primary, var(--fb-border)); background: var(--color-background-primary, var(--fb-bg));
+}
+button:hover { background: var(--color-background-secondary, var(--fb-soft)); }
+button:focus-visible { outline: 2px solid var(--color-ring-primary, var(--fb-text)); outline-offset: 1px; }
+button:disabled { cursor: default; opacity: 0.55; }
+button.primary { background: var(--color-background-inverse, var(--fb-text)); color: var(--color-text-inverse, var(--fb-bg)); border-color: transparent; }
+button.ghost { border-color: transparent; background: transparent; padding: 2px 8px; }
+#install { margin-top: 10px; padding: 8px 10px; border-radius: var(--border-radius-md, 8px); background: var(--color-background-secondary, var(--fb-soft)); }
+#install p { margin: 0 0 4px; font-weight: var(--font-weight-medium, 500); }
+#install ul { margin: 0 0 8px 16px; list-style: disc; color: var(--color-text-secondary, var(--fb-muted)); }
+#loading, .cost { margin: 10px 0 0; color: var(--color-text-secondary, var(--fb-muted)); }
+.cost { font-size: 0.92em; }
+.error { margin: 10px 0 0; color: var(--color-text-danger, var(--fb-bad)); }
+`;
+
+const ACCESS_KEYS = Object.keys(ACCESS_TEXT) as AccessKey[];
+
+export const SETUP_APP_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ennodia agents</title>
+<style>${SETUP_APP_STYLE}</style>
+</head>
+<body>
+<main>
+<h1>Ennodia agents</h1>
+<p id="loading">Checking agents…</p>
+<p id="error" class="error" role="alert" hidden></p>
+<ul id="agents" aria-live="polite"></ul>
+<section id="install" hidden></section>
+<p id="cost" class="cost" hidden>A check sends at most one small model request.</p>
+</main>
+<script>${SETUP_APP_SCRIPT
+  .replace("__ACCESS__", () => JSON.stringify(ACCESS_TEXT))
+  .replace("__RANK__", () => JSON.stringify(Object.fromEntries(ACCESS_KEYS.map(key => [key, accessRank(key)]))))
+  .replace("__GUIDE__", () => JSON.stringify(HARNESS_GUIDE_URL))
+  .replace("__INSTALL__", () => JSON.stringify(INSTALL_GUIDE_URL))
+  .replace("__VERSION__", () => JSON.stringify(ENNODIA_VERSION))}</script>
+</body>
+</html>
+`;