negotium 0.3.0 → 0.3.2

package/dist/runtime/src/mcp/canonical-proxy-server.ts

@@ -85,6 +85,72 @@ const taskTools: Tool[] = [
   },
 ];
 
+const decisionStatus = ["proposed", "accepted", "executed", "rejected", "superseded"];
+const decisionFields = {
+  action: { type: "string" },
+  reasoning: { type: "string" },
+  status: { type: "string", enum: decisionStatus },
+  caused_by: { type: "array", items: { type: "string" } },
+} as const;
+const decisionTools: Tool[] = [
+  {
+    name: "decision_create",
+    description: "Record durable decisions and their causal predecessors in this topic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        decisions: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            properties: decisionFields,
+            required: ["action", "reasoning"],
+          },
+        },
+      },
+      required: ["decisions"],
+    },
+  },
+  {
+    name: "decision_update",
+    description: "Update decisions or causal links in this topic.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        updates: {
+          type: "array",
+          minItems: 1,
+          items: {
+            type: "object",
+            properties: { id: { type: "string" }, ...decisionFields },
+            required: ["id"],
+          },
+        },
+      },
+      required: ["updates"],
+    },
+  },
+  {
+    name: "decision_list",
+    description: "Read this topic's decisions.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "decision_get",
+    description: "Read one decision as JSON.",
+    inputSchema: { type: "object", properties: { id: { type: "string" } }, required: ["id"] },
+  },
+  {
+    name: "decision_delete",
+    description: "Delete decisions from this topic.",
+    inputSchema: {
+      type: "object",
+      properties: { ids: { type: "array", items: { type: "string" } }, all: { type: "boolean" } },
+    },
+  },
+];
+
 const wikiTools: Tool[] = [
   {
     name: "wiki_query",
@@ -160,7 +226,14 @@ const wikiTools: Tool[] = [
   },
 ];
 
-const tools = surface === "task" ? taskTools : surface === "wiki" ? wikiTools : [];
+const tools =
+  surface === "task"
+    ? taskTools
+    : surface === "decision"
+      ? decisionTools
+      : surface === "wiki"
+        ? wikiTools
+        : [];
 const allowed = new Set(tools.map((tool) => tool.name));
 
 function error(text: string): CallToolResult {

package/dist/runtime/src/mcp/decision-server.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import "./stdio-protect";
+import { createDecisionMcpServer } from "#mcp/factories/decision";
+import { connectStdio, parseUserIdArg } from "#mcp/mcp-helpers";
+import { isAgentKind } from "#types";
+
+const args = process.argv.slice(2);
+const topic = args.find((arg) => arg.startsWith("--topic="))?.slice("--topic=".length) || "";
+const topicId = args.find((arg) => arg.startsWith("--topic-id="))?.slice("--topic-id=".length);
+const agentArg = args.find((arg) => arg.startsWith("--agent="))?.slice("--agent=".length);
+const model = args.find((arg) => arg.startsWith("--model="))?.slice("--model=".length);
+
+await connectStdio(
+  createDecisionMcpServer({
+    userId: parseUserIdArg(args),
+    topic,
+    topicId,
+    agent: agentArg && isAgentKind(agentArg) ? agentArg : "codex",
+    model,
+  }),
+);

package/dist/runtime/src/mcp/factories/decision.ts

@@ -0,0 +1,178 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { errMsg } from "#platform/error";
+import {
+  createDecisions,
+  DECISION_STATUS_VALUES,
+  decisionScopeKey,
+  deleteDecisions,
+  readDecisions,
+  renderDecisionList,
+  type StoredDecision,
+  updateDecisions,
+  writeDecisions,
+} from "#storage/decisions";
+import type { AgentKind } from "#types";
+import { mcpError, mcpOk } from "../mcp-helpers";
+
+export interface DecisionMcpContext {
+  userId: string;
+  topic: string;
+  topicId?: string;
+  agent: AgentKind;
+  model?: string;
+}
+
+export interface DecisionMcpHost {
+  readDecisions(userId: string, scopeKey: string): StoredDecision[];
+  writeDecisions(userId: string, scopeKey: string, decisions: StoredDecision[]): void;
+}
+
+export const defaultDecisionMcpHost: DecisionMcpHost = { readDecisions, writeDecisions };
+
+export function createDecisionMcpServer(
+  context: DecisionMcpContext,
+  host: DecisionMcpHost = defaultDecisionMcpHost,
+): McpServer {
+  const scopeKey = context.topic
+    ? decisionScopeKey({ topicId: context.topicId, session: context.topic })
+    : "";
+  const server = new McpServer({ name: "decision", version: "1.0.0" });
+  const requireContext = (): ReturnType<typeof mcpError> | null =>
+    !context.userId || !scopeKey ? mcpError("Error: missing userId/topic context.") : null;
+  const statusEnum = z.enum(DECISION_STATUS_VALUES);
+
+  server.tool(
+    "decision_create",
+    "Record one or more durable decisions in this topic. Include the rationale and causal predecessors.",
+    {
+      decisions: z
+        .array(
+          z.object({
+            action: z.string().min(1).describe("Concise statement of what was decided"),
+            reasoning: z.string().min(1).describe("Why this choice was made"),
+            status: statusEnum.optional().describe("Defaults to accepted"),
+            caused_by: z.array(z.string()).optional().describe("Upstream decision ids"),
+          }),
+        )
+        .min(1),
+    },
+    async ({ decisions: inputs }) => {
+      const guard = requireContext();
+      if (guard) return guard;
+      try {
+        const current = host.readDecisions(context.userId, scopeKey);
+        const { decisions, created } = createDecisions(
+          current,
+          inputs.map((input) => ({
+            action: input.action,
+            reasoning: input.reasoning,
+            status: input.status,
+            causedBy: input.caused_by,
+            agent: context.agent,
+            model: context.model,
+          })),
+        );
+        host.writeDecisions(context.userId, scopeKey, decisions);
+        return mcpOk(
+          `${created.length} decision(s) recorded (${created.map((item) => `#${item.id}`).join(", ")})\n\n${renderDecisionList(decisions)}`,
+        );
+      } catch (error) {
+        return mcpError(`decision_create failed: ${errMsg(error)}`);
+      }
+    },
+  );
+
+  server.tool(
+    "decision_update",
+    "Update decisions or their causal links in this topic.",
+    {
+      updates: z
+        .array(
+          z.object({
+            id: z.string(),
+            action: z.string().min(1).optional(),
+            reasoning: z.string().min(1).optional(),
+            status: statusEnum.optional(),
+            caused_by: z.array(z.string()).optional().describe("Replacement upstream decision ids"),
+          }),
+        )
+        .min(1),
+    },
+    async ({ updates }) => {
+      const guard = requireContext();
+      if (guard) return guard;
+      try {
+        const current = host.readDecisions(context.userId, scopeKey);
+        const { decisions, missing } = updateDecisions(
+          current,
+          updates.map((update) => ({
+            ...update,
+            causedBy: update.caused_by,
+          })),
+        );
+        host.writeDecisions(context.userId, scopeKey, decisions);
+        const warning = missing.length ? `\nMissing ids ignored: ${missing.join(", ")}` : "";
+        return mcpOk(`${renderDecisionList(decisions)}${warning}`);
+      } catch (error) {
+        return mcpError(`decision_update failed: ${errMsg(error)}`);
+      }
+    },
+  );
+
+  server.tool(
+    "decision_list",
+    "Read this topic's decision graph as a concise list.",
+    {},
+    async () => {
+      const guard = requireContext();
+      if (guard) return guard;
+      try {
+        return mcpOk(renderDecisionList(host.readDecisions(context.userId, scopeKey)));
+      } catch (error) {
+        return mcpError(`decision_list failed: ${errMsg(error)}`);
+      }
+    },
+  );
+
+  server.tool(
+    "decision_get",
+    "Read one topic decision as JSON.",
+    { id: z.string() },
+    async ({ id }) => {
+      const guard = requireContext();
+      if (guard) return guard;
+      try {
+        const decision = host
+          .readDecisions(context.userId, scopeKey)
+          .find((item) => item.id === id);
+        return decision
+          ? mcpOk(JSON.stringify(decision, null, 2))
+          : mcpError(`Decision #${id} not found.`);
+      } catch (error) {
+        return mcpError(`decision_get failed: ${errMsg(error)}`);
+      }
+    },
+  );
+
+  server.tool(
+    "decision_delete",
+    "Delete decisions. Downstream causal references to deleted decisions are removed.",
+    { ids: z.array(z.string()).optional(), all: z.boolean().optional() },
+    async ({ ids, all }) => {
+      const guard = requireContext();
+      if (guard) return guard;
+      if (!all && (!ids || ids.length === 0)) return mcpError("Provide ids or all=true.");
+      try {
+        const current = host.readDecisions(context.userId, scopeKey);
+        const { decisions, removed } = deleteDecisions(current, { ids, all });
+        host.writeDecisions(context.userId, scopeKey, decisions);
+        return mcpOk(`${removed} decision(s) deleted\n\n${renderDecisionList(decisions)}`);
+      } catch (error) {
+        return mcpError(`decision_delete failed: ${errMsg(error)}`);
+      }
+    },
+  );
+
+  return server;
+}

package/dist/runtime/src/mcp/factories/index.ts

@@ -29,6 +29,12 @@ export {
   type CompactionLogMcpContext,
   createCompactionLogMcpServer,
 } from "./compaction-log";
+export {
+  createDecisionMcpServer,
+  type DecisionMcpContext,
+  type DecisionMcpHost,
+  defaultDecisionMcpHost,
+} from "./decision";
 export {
   createSessionCommMcpServer,
   type SessionCommMcpHost,

package/dist/runtime/src/mcp/runtime-spec.ts

@@ -17,6 +17,7 @@ export const RUNTIME_MCP_KEY = "runtime";
 export const RUNTIME_MCP_BASE_PATH = "/mcp/runtime";
 export const HOSTED_MCP_SURFACES = [
   "task",
+  "decision",
   "token-stats",
   "system-health",
   "vault",

package/dist/runtime/src/node-host.ts

@@ -67,6 +67,7 @@ export { startSessionInboxWorker } from "#runtime/inbox";
 export { startAiTurn, startDurableTurnRequestWorker } from "#runtime/turn-runner";
 export { appendApiMessage, getApiMessage, listApiMessages } from "#storage/api-messages";
 export { getTopic, upsertTopic } from "#storage/api-topics";
+export { readDecisions, writeDecisionGraphSvg } from "#storage/decisions";
 export type { StoredRuntimeEvent } from "#storage/runtime-events";
 export {
   latestRuntimeEventSeq,

package/dist/runtime/src/platform/config.ts

@@ -99,7 +99,7 @@ export function resolveOutputLanguage(): string {
 }
 
 /** Browser.rs release tested with this Negotium version. */
-export const BROWSER_RS_VERSION = "v0.1.19";
+export const BROWSER_RS_VERSION = "v0.1.21";
 /** Require the authenticated listener and the current Browser.rs tool contract. */
 export const BROWSER_RS_MIN_SECURE_VERSION = "0.1.15";
 
@@ -277,6 +277,7 @@ export const TSCONFIG_PATH = resolve(PROJECT_ROOT, "tsconfig.json");
 export const SESSION_COMM_SERVER = resolve(PROJECT_ROOT, "src/mcp/session-comm/server.ts");
 
 export const TASK_SERVER = resolve(PROJECT_ROOT, "src/mcp/task-server.ts");
+export const DECISION_SERVER = resolve(PROJECT_ROOT, "src/mcp/decision-server.ts");
 export const BROWSER_MCP_SSE_PROXY_SERVER = resolve(
   PROJECT_ROOT,
   "src/mcp/browser-sse-proxy-server.ts",

package/dist/runtime/src/platform/mcp-catalog-policy.ts

@@ -11,6 +11,7 @@ export const COMMON_RUNTIME_MCP_POLICY = {
   runtime: { scopes: ["forum", "manager", "fork", "cron"], forumRequired: true },
   "token-stats": { scopes: ["dm", "forum", "manager", "cron"], forumRequired: true },
   task: { scopes: ["dm", "forum", "manager", "cron"], forumRequired: true },
+  decision: { scopes: ["dm", "forum", "manager", "cron"], forumRequired: true },
   "session-comm": { scopes: ["forum", "fork", "manager"], forumRequired: true },
   wiki: { scopes: ["dm", "forum", "manager", "cron"], forumRequired: true },
   skills: { scopes: ["dm", "forum", "manager", "cron"], forumRequired: true },

package/dist/runtime/src/platform/mcp-config.ts

@@ -11,6 +11,7 @@ import {
   AGENT_HEALTH_SERVER,
   BROWSER_MCP_SSE_PROXY_SERVER,
   CANONICAL_MCP_PROXY_SERVER,
+  DECISION_SERVER,
   envText,
   FALLBACK_AGENT,
   resolveTopicWorkspaceDir,
@@ -417,6 +418,35 @@ const MCP_CATALOG: Record<string, RuntimeMcpCatalogEntry> = {
       );
     },
   },
+  decision: {
+    ...commonRuntimeMcpPolicy("decision"),
+    build(ctx) {
+      const { userId, session, topicId, queryId, agent, model, peerBridge } = ctx;
+      if (peerBridge) {
+        if (!topicId || !queryId) return null;
+        const env = canonicalMcpBridgeEnv({
+          surface: "decision",
+          userId,
+          topicId,
+          queryId,
+          peerBridge,
+        });
+        return env
+          ? buildStdioMcpServer(agent, CANONICAL_MCP_PROXY_SERVER, ["--surface=decision"], env)
+          : null;
+      }
+      const args = [
+        `--user-id=${userId}`,
+        `--topic=${session}`,
+        `--agent=${agent ?? FALLBACK_AGENT}`,
+      ];
+      if (topicId) args.push(`--topic-id=${topicId}`);
+      if (model) args.push(`--model=${model}`);
+      return buildBuiltinMcpServer("decision", ctx, () =>
+        buildStdioMcpServer(agent, DECISION_SERVER, args),
+      );
+    },
+  },
   "session-comm": {
     // Exposed in `manager` scope as well so the General-topic manager agent
     // can wake fresh-created topics via tell_session/ask_session right after
@@ -818,7 +848,7 @@ export function getForumMcpServers(opts: {
   } = opts;
 
   const filter = (name: string) => {
-    if (silent && name === "task") return false;
+    if (silent && (name === "task" || name === "decision")) return false;
     if (enabled === null) return true;
     return (
       enabled.includes(name) || (REQUIRED_FORUM_MCP_SERVERS as readonly string[]).includes(name)

package/dist/runtime/src/prompts/builders.ts

@@ -274,6 +274,7 @@ function buildRuntimeToolSection(
   } = opts;
   const runtimeNamespace = "mcp__runtime";
   const taskNamespace = "mcp__task";
+  const decisionNamespace = "mcp__decision";
   const visualToolLine =
     agentKind === "codex"
       ? `To display charts, tables, or interactive HTML results to the user, call the \`show_html\` function in the \`${runtimeNamespace}\` namespace with { html: "<complete HTML string>", title?: "optional title" }.`
@@ -302,6 +303,7 @@ function buildRuntimeToolSection(
     agentKind === "codex"
       ? `For task tracking, use \`task_create\`, \`task_update\`, \`task_list\`, \`task_get\`, and \`task_delete\` functions in the \`${taskNamespace}\` namespace.`
       : `For task tracking, use MCP tools "${taskNamespace}__task_create", "${taskNamespace}__task_update", "${taskNamespace}__task_list", "${taskNamespace}__task_get", and "${taskNamespace}__task_delete".`;
+  const decisionToolLine = `Use the shared Decision tools in the \`${decisionNamespace}\` namespace when an architectural, product, or operational choice establishes or changes a durable direction or constraint. Do not record routine task progress or temporary implementation details; link causal predecessors when relevant.`;
   const runtimeToolRef = (name: string): string =>
     agentKind === "codex" ? `\`${name}\`` : `"${runtimeNamespace}__${name}"`;
   const spawnSubagentToolLine = `Use ${runtimeToolRef("spawn_subagent")} for self-contained parallel or long-running background work; keep quick work inline.`;
@@ -364,6 +366,9 @@ function buildRuntimeToolSection(
     taskToolLine,
     "Use this shared task store for plans, progress, and checklist updates; it is visible across claude/codex/maestro turns.",
     nativeTaskPolicyLine,
+    "",
+    "## Shared Decisions",
+    decisionToolLine,
     ...extensions.render("after-shared-tasks"),
     ...fileDeliverySection,
     ...extensions.render("before-session-communication"),

package/dist/runtime/src/runtime/visual-html.ts

@@ -55,6 +55,10 @@ export function buildMermaidHtml(
     .controls button:focus-visible{outline:2px solid var(--celadon);outline-offset:1px}
     .zoom-value{min-width:46px;color:var(--graphite);font:500 11px/1 Geist,system-ui,sans-serif;text-align:center;font-variant-numeric:tabular-nums}
     .error{margin:0;white-space:pre-wrap;color:#7D2E2E;background:#FFF5F2;border:1px solid #E4B9B1;border-radius:6px;padding:14px;font:13px ui-monospace,SFMono-Regular,Menlo,monospace}
+    .failure{max-width:56ch;margin:0 auto}
+    .failure p{margin:0 0 12px;color:var(--graphite);font:14px/1.6 Geist,system-ui,sans-serif}
+    .failure details{color:var(--graphite);font:12px/1.5 Geist,system-ui,sans-serif}
+    .failure summary{cursor:pointer;padding:4px 0}
     @media(max-width:600px){.viewport{padding:54px 14px 18px}.controls{top:10px;right:10px}}
   </style>
 </head>
@@ -69,11 +73,58 @@ export function buildMermaidHtml(
   <script data-otium-mermaid-runtime src="${safeScriptUrl}"></script>
   <script>
     (async () => {
+      // An unrendered document reports itself in more than one voice: Mermaid's
+      // own 0x0 guard, and the browser refusing geometry on a path that was
+      // never laid out. Both mean the same thing, so both are worth one retry
+      // and, if it still fails, the same explanation.
+      const unrendered = (error) => {
+        const message = String(error && error.message ? error.message : error);
+        return message.indexOf("not in render tree") !== -1 || message.indexOf("path is empty") !== -1;
+      };
       try {
       const runtime = globalThis.mermaid;
       if (!runtime) throw new Error("Mermaid renderer failed to load.");
       runtime.initialize({ startOnLoad: false, securityLevel: "strict", theme: ${safeTheme} });
-      await runtime.run({ querySelector: ".mermaid" });
+      const host = document.querySelector(".mermaid");
+      // Mermaid sizes every label by appending a probe <svg> to the body and
+      // reading getBBox(), and it throws "svg element not in render tree" the
+      // moment that comes back 0x0. That is what a hidden panel looks like from
+      // in here: the document exists but nothing is in the render tree, so the
+      // measurement has no geometry to report. Ask the same question Mermaid
+      // will ask, and only start once it has an answer.
+      const measurable = () => {
+        const probe = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+        const text = document.createElementNS("http://www.w3.org/2000/svg", "text");
+        text.textContent = "M";
+        probe.appendChild(text);
+        document.body.appendChild(probe);
+        let box = { width: 0, height: 0 };
+        try { box = text.getBBox(); } catch (ignored) {}
+        probe.remove();
+        return box.width > 0 || box.height > 0;
+      };
+      // requestAnimationFrame is the right clock here: a hidden document stops
+      // being animated, so this waits without spinning and resumes on the frame
+      // the panel is shown. The cap counts rendered frames, not wall time.
+      const waitUntilMeasurable = async (maxFrames) => {
+        for (let frame = 0; frame < maxFrames; frame += 1) {
+          if (measurable()) return true;
+          await new Promise((next) => requestAnimationFrame(next));
+        }
+        return measurable();
+      };
+      await waitUntilMeasurable(600);
+      try {
+        await runtime.run({ querySelector: ".mermaid" });
+      } catch (firstAttempt) {
+        if (!unrendered(firstAttempt)) throw firstAttempt;
+        // The panel can be hidden again between the probe and the real measure.
+        // Clear the marker Mermaid leaves behind so the retry is not skipped as
+        // already done, then wait for the render tree once more.
+        host.removeAttribute("data-processed");
+        await waitUntilMeasurable(600);
+        await runtime.run({ querySelector: ".mermaid" });
+      }
       const viewport = document.querySelector(".viewport");
       const svg = document.querySelector(".mermaid svg");
       const value = document.querySelector(".zoom-value");
@@ -100,7 +151,22 @@ export function buildMermaidHtml(
       applyScale(scale, false);
       } catch (error) {
         document.querySelector(".controls")?.remove();
-        document.querySelector(".viewport").innerHTML = '<pre class="error">' + String(error && error.message ? error.message : error).replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])) + '</pre>';
+        const raw = String(error && error.message ? error.message : error);
+        const escape = (value) => value.replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]));
+        // Mermaid aborts the whole render when it cannot place an edge label:
+        // cardinality markers ask for a point a fixed distance along the edge,
+        // and a relation laid out shorter than that walks off the end. Nothing
+        // is wrong with the diagram, so the raw message sends authors looking
+        // for a syntax error that does not exist. Say what actually moves it.
+        const note = raw.indexOf("Could not find a suitable point") !== -1
+          ? "Two nodes ended up too close together for Mermaid to fit a label on the edge between them. Renaming a node, adding another, or setting an explicit direction usually spreads the layout enough to render."
+          : unrendered(error)
+          ? "The panel stayed hidden long enough that there was never a laid-out page to measure the diagram against. Reopening the panel renders it."
+          : "This diagram could not be rendered.";
+        document.querySelector(".viewport").innerHTML =
+          '<div class="failure"><p>' + escape(note) +
+          '</p><details><summary>Technical detail</summary><pre class="error">' +
+          escape(raw) + '</pre></details></div>';
       }
     })();
   </script>