@codazen/harmonica-mcp 3.1.0 → 3.3.0

package/dist/index.js

@@ -22444,7 +22444,8 @@ var CHECK_MAX_SCORES = {
   pii_scan: 100,
   portfolio_coherence: 5,
   revision_quality: 5,
-  drop_quality: 5
+  drop_quality: 5,
+  root_coda_quality: 5
 };
 
 // ../../libs/harmonica-services/src/mcp/tools/beat-quality-tools.ts
@@ -22523,7 +22524,7 @@ Use get_job_status with jobId="${taskId}" to poll for results, or list_checks to
   };
   server.tool(
     "check_beat_coda_quality",
-    "Enqueue a Beat definition quality check across 7 dimensions (Distinctive, Harmonious, Substantial, Durable, Clear, Strategically Aligned, Business Outcome) \u2014 grades the Beat's Coda and directing context, persisted as beat_coda_quality. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations (more than one Beat), omit wait and poll get_job_status separately to avoid session exhaustion.",
+    "Enqueue a Beat definition quality check across 7 dimensions (Distinctive, Harmonious, Substantial, Durable, Clear, Strategically Aligned, Outcome-Oriented) \u2014 grades the Beat's Coda and directing context, persisted as beat_coda_quality. By default returns a jobId immediately (fire-and-forget) \u2014 use get_job_status or list_checks to retrieve results. Set wait=true to block until the check completes and receive the scorecard inline. WARNING: wait=true holds the MCP session open for 30\u201360s per check \u2014 for bulk operations (more than one Beat), omit wait and poll get_job_status separately to avoid session exhaustion.",
     schema,
     handler
   );
@@ -22648,6 +22649,17 @@ var NOTE_TYPE_LABELS = {
   decision: "Decisions",
   document: "Documents"
 };
+function formatDeliveryPolicy(policy, unresolvedReason) {
+  const LABELS = {
+    openPullRequest: "Open a pull request",
+    requestAgentReview: "Request the agent code review",
+    watchPullRequest: "Watch the pull request to green"
+  };
+  const verdict = (value) => value === true ? "yes \u2014 proceed without asking" : value === false ? "NO \u2014 prohibited, say so rather than asking" : "not set \u2014 ask first";
+  const lines = Object.keys(LABELS).map((step) => `- ${LABELS[step]}: ${verdict(policy?.[step] ?? void 0)}`);
+  const footer = unresolvedReason ? [`- _Policy could not be resolved (${unresolvedReason}) \u2014 ask first; this is not proof that no policy is set._`] : [];
+  return ["## Agent Delivery Policy", ...lines, ...footer].join("\n");
+}
 function formatProjectContext(project, notes, orgCoda) {
   const sections = [];
   sections.push(`# Project: ${project.title}`);
@@ -22657,6 +22669,8 @@ function formatProjectContext(project, notes, orgCoda) {
     const branch = project.repoDefaultBranch ?? "main";
     sections.push(`**Repo:** ${project.repoOwner}/${project.repoName} (branch: ${branch})`);
   }
+  sections.push(`
+${formatDeliveryPolicy(project.agentDeliveryPolicy)}`);
   if (orgCoda) {
     sections.push(`
 ## Organization Coda
@@ -23255,7 +23269,14 @@ ${formatBeatDetail(beat)}${similarityWarning}` }] };
           return { content: [{ type: "text", text: `Revision not found: ${revisionId}` }], isError: true };
         }
         await assertBeatInOrg(client, revision.beatId, ctx.orgId);
-        return { content: [{ type: "text", text: formatRevisionDetail(revision) }] };
+        const resolution = await client.resolveDeliveryPolicy(revisionId);
+        const policyBlock = `
+
+${formatDeliveryPolicy(
+          resolution.resolved ? resolution.policy : void 0,
+          resolution.resolved ? void 0 : resolution.reason
+        )}`;
+        return { content: [{ type: "text", text: formatRevisionDetail(revision) + policyBlock }] };
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         return { content: [{ type: "text", text: `Failed to get revision: ${message}` }], isError: true };
@@ -25836,7 +25857,7 @@ var BEAT_QUALITY_DIMENSIONS = [
   "durable",
   "clear",
   "strategicallyAligned",
-  "businessOutcome"
+  "outcomeOriented"
 ];
 var BeatDimensionScoreSchema = external_exports.object({
   dimension: external_exports.enum(BEAT_QUALITY_DIMENSIONS),
@@ -26200,6 +26221,7 @@ var ScopeNotebookApiSchema = external_exports.object({
 var NotebookResponseSchema = external_exports.object({ notebook: NotebookApiSchema }).passthrough();
 var NotebookScopesResponseSchema = external_exports.object({ scopes: external_exports.array(NotebookScopeRefSchema) }).passthrough();
 var ScopeNotebooksResponseSchema = external_exports.object({ notebooks: external_exports.array(ScopeNotebookApiSchema) }).passthrough();
+var NotebookSharingResponseSchema = external_exports.object({ guestView: external_exports.boolean() }).passthrough();
 var NotebookShortcutApiSchema = external_exports.object({
   notebookId: external_exports.string(),
   scopeType: NotebookScopeTypeSchema,
@@ -26325,7 +26347,8 @@ var CHECK_TARGET_TYPES = [
   "revision",
   "beat_version",
   "project",
-  "drop"
+  "drop",
+  "organization"
 ];
 var CheckTargetTypeSchema = external_exports.enum(CHECK_TARGET_TYPES);
 var CheckApiSchema = external_exports.object({
@@ -26577,7 +26600,7 @@ var StoredMessageSchema = external_exports.object({
 var ConversationsResponseSchema = external_exports.array(ConversationSummarySchema);
 var MessagesResponseSchema = external_exports.array(StoredMessageSchema);
 var StartSessionRequestBodySchema = external_exports.object({
-  projectId: external_exports.string().min(1),
+  systemId: external_exports.string().min(1),
   message: external_exports.string().min(1),
   revisionId: external_exports.string().min(1).optional(),
   enableWebSearch: external_exports.boolean().optional()
@@ -28487,6 +28510,59 @@ Notes filed: ${createdNotes.length}`);
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/organization-tools.ts
+var ROOT_CODA_POLL_INTERVAL_MS = 4e3;
+var ROOT_CODA_POLL_TIMEOUT_MS = 18e4;
+var ROOT_CODA_POLL_MAX_CONSECUTIVE_ERRORS = 3;
+async function pollForRootCodaCheck(client, taskId) {
+  const deadline = Date.now() + ROOT_CODA_POLL_TIMEOUT_MS;
+  let consecutiveErrors = 0;
+  while (Date.now() < deadline) {
+    const [task, err] = await client.getTask(taskId).then(
+      (t) => [t, null],
+      (e) => [null, e]
+    );
+    if (err) {
+      consecutiveErrors++;
+      if (consecutiveErrors >= ROOT_CODA_POLL_MAX_CONSECUTIVE_ERRORS) {
+        throw new Error(`getTask failed ${consecutiveErrors} times: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      await new Promise((r) => setTimeout(r, ROOT_CODA_POLL_INTERVAL_MS));
+      continue;
+    }
+    consecutiveErrors = 0;
+    if (!task) throw new Error(`Task ${taskId} not found`);
+    if (task.status === "completed") {
+      if (!task.result) throw new Error(`Task ${taskId} completed with no result`);
+      const result = task.result;
+      if (!Array.isArray(result.dimensions) || typeof result.overallScore !== "number") {
+        throw new Error(`Task ${taskId} did not return a root Coda scorecard \u2014 was it a run_check task?`);
+      }
+      return result;
+    }
+    if (task.status === "failed") throw new Error(`Root Coda quality check failed: ${task.error ?? "unknown error"}`);
+    await new Promise((r) => setTimeout(r, ROOT_CODA_POLL_INTERVAL_MS));
+  }
+  throw new Error(`Root Coda quality check timed out after ${ROOT_CODA_POLL_TIMEOUT_MS / 1e3}s`);
+}
+function formatRootCodaReport(check2) {
+  const bar = (score, max) => {
+    const filled = Math.max(0, Math.min(max, Math.round(score)));
+    return "\u2588".repeat(filled) + "\u2591".repeat(max - filled);
+  };
+  const dims = check2.dimensions.map(
+    (d) => `**${d.label}** ${bar(d.score, d.maxScore)} ${d.score}/${d.maxScore}
+${d.rationale}${d.suggestions?.length ? `
+\u2022 ${d.suggestions.join("\n\u2022 ")}` : ""}`
+  ).join("\n\n");
+  return [
+    `## Root Coda Quality \u2014 ${check2.targetId}`,
+    `**Overall Score:** ${check2.overallScore}/5`,
+    `**Summary:** ${check2.summary}`,
+    check2.topSuggestion ? `**Top Suggestion:** ${check2.topSuggestion}` : "",
+    "",
+    dims
+  ].filter(Boolean).join("\n");
+}
 function registerOrganizationTools(server, ctx, client) {
   server.tool(
     "get_organization",
@@ -28616,6 +28692,67 @@ function registerOrganizationTools(server, ctx, client) {
       return { content: [{ type: "text", text }] };
     }
   );
+  server.tool(
+    "compose_root_coda",
+    "Generate and apply an Organization's root Coda (top-level purpose statement) from its name, industry, description, and existing Coda if any. Drafts via LLM, applies directly to the Organization, then runs a root_coda_quality check \u2014 if the first score is below 4.0, performs exactly one automatic self-revision pass incorporating the feedback before finishing. Returns a job ID \u2014 use get_job_status to track progress.",
+    {
+      orgId: external_exports.string().min(1).describe("The organization ID")
+    },
+    async ({ orgId }) => {
+      try {
+        const task = await client.composeRootCoda(orgId);
+        return {
+          content: [{
+            type: "text",
+            text: [
+              "Root Coda composition queued.",
+              "",
+              `**Organization:** ${orgId}`,
+              `**Task ID:** ${task.taskId}`,
+              `**Status:** ${task.status}`,
+              "",
+              "The agent will gather context, draft a Coda, apply it to the Organization, and grade it \u2014 revising once automatically if the first score is below 4.0.",
+              "Use `get_job_status` with the job ID to check progress."
+            ].join("\n")
+          }]
+        };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `compose_root_coda failed: ${message}` }], isError: true };
+      }
+    }
+  );
+  server.tool(
+    "check_root_coda_quality",
+    "Run a six-dimension quality check on an Organization's root Coda (Discriminating, Attributed, Reciprocal, Bounded, Generative, Consequential). By default returns a taskId immediately \u2014 set wait=true to block and receive the full scorecard inline.",
+    {
+      orgId: external_exports.string().min(1).describe("The organization ID"),
+      wait: external_exports.boolean().optional().describe("Block until the check completes and return the scorecard inline. Default: false.")
+    },
+    async ({ orgId, wait }) => {
+      try {
+        const { taskId } = await client.runCheck(orgId, "root_coda_quality", orgId);
+        if (!wait) {
+          return {
+            content: [{
+              type: "text",
+              text: [
+                `Root Coda quality check enqueued for ${orgId}.`,
+                `Task ID: ${taskId}`,
+                "",
+                `Use get_job_status with jobId="${taskId}" to poll, or list_checks with checkType="root_coda_quality" to view results.`
+              ].join("\n")
+            }]
+          };
+        }
+        const check2 = await pollForRootCodaCheck(client, taskId);
+        return { content: [{ type: "text", text: formatRootCodaReport(check2) }] };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { content: [{ type: "text", text: `Root Coda quality check failed: ${message}` }], isError: true };
+      }
+    }
+  );
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/plan-quality-tools.ts
@@ -28830,7 +28967,7 @@ function formatConsolidationResult(primaryId, primary, archivedBeatIds, notesRea
 function registerPortfolioCoherenceTools(server, ctx, client) {
   server.tool(
     "check_portfolio_coherence",
-    "Run a portfolio coherence check on a project. Clusters Beats by semantic similarity to surface fragmentation (merge candidates) and checks what fraction of Beats have a VP-readable business outcome score. By default returns a taskId immediately \u2014 set wait=true to block and receive the full report inline.",
+    "Run a portfolio coherence check on a project. Clusters Beats by semantic similarity to surface fragmentation (merge candidates) and checks what fraction of Beats name an outcome their authoriser would recognise. By default returns a taskId immediately \u2014 set wait=true to block and receive the full report inline.",
     {
       projectId: external_exports.string().min(1).describe("The project ID"),
       wait: external_exports.boolean().optional().describe("Block until the check completes and return the report inline. Default: false.")
@@ -30029,6 +30166,9 @@ async function resolveSnapshotInput(input) {
   return trimmed;
 }
 function formatImportSummary(result, targetTeamspaceId) {
+  if (!result.counts || result.counts.beats == null) {
+    throw new Error(`Import of system ${result.projectId} completed but returned no counts \u2014 check worker logs for a TransactionCanceledException`);
+  }
   const lines = [
     `Imported system: ${result.projectId}`,
     `  Beats: ${result.counts.beats}`,
@@ -30316,7 +30456,12 @@ function registerProjectTools(server, ctx, client) {
     repoOwner: external_exports.string().optional().describe("GitHub repository owner (org or user)"),
     repoName: external_exports.string().optional().describe("GitHub repository name"),
     repoDefaultBranch: external_exports.string().optional().describe('Default branch for code check (defaults to "main")'),
-    rateLimitOverrides: external_exports.record(external_exports.string(), external_exports.object({ maxPerHour: external_exports.number().min(0) })).optional().describe('Per-task-type rate limit overrides, e.g. {"agent_chat":{"maxPerHour":100}}. Overrides env var and compiled defaults.')
+    rateLimitOverrides: external_exports.record(external_exports.string(), external_exports.object({ maxPerHour: external_exports.number().min(0) })).optional().describe('Per-task-type rate limit overrides, e.g. {"agent_chat":{"maxPerHour":100}}. Overrides env var and compiled defaults.'),
+    agentDeliveryPolicy: external_exports.object({
+      openPullRequest: external_exports.boolean().nullable().optional().describe("Open a pull request when the work is ready."),
+      requestAgentReview: external_exports.boolean().nullable().optional().describe("Request the agent code review (the agent-review label)."),
+      watchPullRequest: external_exports.boolean().nullable().optional().describe("Watch the pull request and drive it to green.")
+    }).optional().describe("Delivery latitude for agents on this System: which pull-request steps they may take without asking. Each field is tri-state \u2014 omit it to leave it alone, true to let agents proceed, false to forbid the step outright, null to clear it back to asking.")
   };
   const updateSystemHandler = async ({ systemId, ...updates }) => {
     try {
@@ -31867,7 +32012,7 @@ function createHttpClient(config2) {
         const result = await request(
           "POST",
           `/api/organizations/${encodeURIComponent(sourceOrgId)}/transfer-project`,
-          { projectId, targetOrgId }
+          { systemId: projectId, targetOrgId }
         );
         const project = result?.project ? {
           ...result.project,
@@ -32975,6 +33120,15 @@ function createHttpClient(config2) {
       if (!result?.taskId) throw new Error("Draft coda enqueue failed: no taskId returned");
       return { taskId: result.taskId, taskType: "draft_coda", status: result.status ?? "pending", projectId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
     },
+    composeRootCoda: async (orgId) => {
+      const result = await request(
+        "POST",
+        `/api/organizations/${encodeURIComponent(orgId)}/compose-root-coda`,
+        {}
+      );
+      if (!result?.taskId) throw new Error("Compose root Coda enqueue failed: no taskId returned");
+      return { taskId: result.taskId, taskType: "compose_root_coda", status: result.status ?? "pending", projectId: orgId, createdAt: (/* @__PURE__ */ new Date()).toISOString() };
+    },
     validateAssumptions: async (projectId, noteIds) => {
       const result = await request(
         "POST",
@@ -33042,7 +33196,19 @@ function createHttpClient(config2) {
       return download;
     },
     importSystemSnapshot: (snapshot, options) => request("POST", "/api/systems/import", { ...snapshot, importOptions: options }, LONG_RUNNING_TIMEOUT_MS),
-    importSystemSnapshotFromUrl: (url2, options) => request("POST", "/api/systems/import", { snapshotUrl: url2, importOptions: options }, LONG_RUNNING_TIMEOUT_MS),
+    importSystemSnapshotFromUrl: async (url2, options) => {
+      const enqueued = await request(
+        "POST",
+        "/api/systems/import",
+        { snapshotUrl: url2, importOptions: options }
+      );
+      if (!enqueued?.taskId) {
+        throw new Error("importSystemSnapshotFromUrl: API did not return a taskId");
+      }
+      const importResult = await pollTaskResult(enqueued.taskId);
+      if (importResult == null) throw new Error(`Task ${enqueued.taskId} completed but returned no result \u2014 check worker logs for a TransactionCanceledException`);
+      return importResult;
+    },
     // Embedding similarity
     embedProjectEntities: (projectId) => request("POST", `/api/systems/${encodeURIComponent(projectId)}/embeddings/generate`),
     findSimilarNotes: async (noteId, projectId, options) => {
@@ -33438,6 +33604,18 @@ function createHttpClient(config2) {
     // Systems owned directly by an Account (B-278 v17). A 404 here means either
     // no such Account or the feature flag is off; both read as "nothing to show",
     // which is why request() returning undefined maps to an empty list.
+    // Delegates to the endpoint that calls the same service the direct adapter
+    // uses, so neither adapter carries its own copy of the fail-closed rule.
+    // request() maps a 404 to undefined; that is itself unresolvable, so it
+    // becomes an explicit unresolved result rather than a thrown error.
+    resolveDeliveryPolicy: async (revisionId) => {
+      const res = await request(
+        "GET",
+        `/api/revisions/${encodeURIComponent(revisionId)}/delivery-policy`
+      );
+      if (!res) return { resolved: false, reason: "revision_not_found" };
+      return res;
+    },
     listAccountSystems: async (accountId) => {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/systems`);
       return res?.systems ?? [];
@@ -33873,7 +34051,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"3.1.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"3.3.0"} starting\u2026`);
   const config2 = loadConfig();
   const client = createHttpClient({
     apiBaseUrl: config2.apiBaseUrl,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codazen/harmonica-mcp",
-  "version": "3.1.0",
+  "version": "3.3.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {