@codazen/harmonica-mcp 3.0.1 → 3.2.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
@@ -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 };
@@ -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()
@@ -26862,7 +26885,7 @@ var EligibleBeatVersionForDropSchema = external_exports.object({
   createdAt: external_exports.string(),
   updatedAt: external_exports.string(),
   humanAssignee: external_exports.object({ email: external_exports.string(), name: external_exports.string() }).optional(),
-  currentDropAssignment: external_exports.object({ dropId: external_exports.string(), dropCode: external_exports.string(), state: external_exports.string() }).optional()
+  currentDropAssignment: external_exports.object({ dropId: external_exports.string(), dropCode: external_exports.string().optional(), state: external_exports.string() }).optional()
 }).passthrough();
 var ScoredDropCandidateSchema = external_exports.object({
   bv: EligibleBeatVersionForDropSchema,
@@ -26879,6 +26902,34 @@ var ScoredDropCandidateSchema = external_exports.object({
   atRisk: external_exports.boolean(),
   requiredSlope: external_exports.number().nullable().optional()
 }).passthrough();
+var DUTY_ALTITUDES = ["portfolio", "system", "account"];
+var DUTY_HOLDER_TYPES = ["human", "agent"];
+var DUTY_MODES = ["accountable", "responsible"];
+var DutyAltitudeApiSchema = external_exports.enum(DUTY_ALTITUDES);
+var DutyHolderTypeApiSchema = external_exports.enum(DUTY_HOLDER_TYPES);
+var DutyModeApiSchema = external_exports.enum(DUTY_MODES);
+var DerivedStaffingStateApiSchema = external_exports.enum(["agent-held", "supported", "observed"]);
+var DutyAssignmentApiSchema = external_exports.object({
+  dutyAssignmentId: external_exports.string(),
+  accountId: external_exports.string(),
+  orgId: external_exports.string(),
+  role: external_exports.string(),
+  altitude: DutyAltitudeApiSchema,
+  scopeId: external_exports.string(),
+  holderType: DutyHolderTypeApiSchema,
+  holderId: external_exports.string(),
+  supportingAssistantId: external_exports.string().optional(),
+  mode: DutyModeApiSchema,
+  parentDutyAssignmentId: external_exports.string().optional(),
+  effectiveFrom: external_exports.string(),
+  effectiveTo: external_exports.string().optional(),
+  createdBy: external_exports.string().optional(),
+  version: external_exports.number().optional(),
+  createdAt: external_exports.string(),
+  updatedAt: external_exports.string()
+}).passthrough();
+var DutyAssignmentsResponseSchema = external_exports.object({ dutyAssignments: external_exports.array(DutyAssignmentApiSchema).optional() }).passthrough();
+var DutyAssignmentResponseSchema = external_exports.object({ dutyAssignment: DutyAssignmentApiSchema }).passthrough();
 var DropProposalApiSchema = external_exports.object({
   accountId: external_exports.string(),
   revisionIds: external_exports.array(external_exports.string()),
@@ -28459,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",
@@ -28588,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
@@ -30213,6 +30378,13 @@ function registerProjectLifecycleTools(server, ctx, client) {
 
 // ../../libs/harmonica-services/src/mcp/tools/system-tools.ts
 var import_crypto5 = require("crypto");
+
+// ../../libs/harmonica-services/src/utils/normalize-create-account-id.ts
+function normalizeCreateAccountId(accountId) {
+  return accountId?.trim() || void 0;
+}
+
+// ../../libs/harmonica-services/src/mcp/tools/system-tools.ts
 function accountLine(request, resolved) {
   const requested = request["accountId"];
   if (requested === null || requested === "") return "**Account:** (unlinked)";
@@ -30281,7 +30453,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 {
@@ -30366,11 +30543,12 @@ function registerProjectTools(server, ctx, client) {
     description: external_exports.string().optional().describe("System description"),
     strategy: external_exports.string().optional().describe('System strategy markdown \u2014 Org Strategy + System Strategy ("System Coda")'),
     teamspaceId: external_exports.string().optional().describe("Teamspace ID to associate this system with"),
+    accountId: external_exports.string().optional().describe("Account that owns this System \u2014 the client or internal org unit. Set it at creation so the System appears in the Account's Systems list; omit only for a System that belongs to no Account."),
     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")')
   };
-  const createSystemHandler = async ({ title, description, strategy, teamspaceId, repoOwner, repoName, repoDefaultBranch }) => {
+  const createSystemHandler = async ({ title, description, strategy, teamspaceId, accountId, repoOwner, repoName, repoDefaultBranch }) => {
     if (teamspaceId) {
       const teamspace = await client.getTeamspace(teamspaceId);
       if (!teamspace) {
@@ -30380,6 +30558,7 @@ function registerProjectTools(server, ctx, client) {
         return { content: [{ type: "text", text: "Teamspace does not belong to this organization" }], isError: true };
       }
     }
+    const account = normalizeCreateAccountId(accountId);
     try {
       const project = await client.createSystem({
         projectId: (0, import_crypto5.randomUUID)(),
@@ -30390,6 +30569,7 @@ function registerProjectTools(server, ctx, client) {
         strategy,
         status: "active",
         teamspaceId,
+        ...account !== void 0 && { accountId: account },
         repoOwner,
         repoName,
         repoDefaultBranch
@@ -30400,6 +30580,7 @@ function registerProjectTools(server, ctx, client) {
         `**ID:** ${project.projectId}`,
         `**Title:** ${project.title}`,
         `**Status:** ${project.status}`,
+        project.accountId ? `**Account:** ${project.accountId}` : "",
         project.description ? `**Description:** ${project.description}` : "",
         project.repoOwner ? `**Repo:** ${project.repoOwner}/${project.repoName}` : "",
         project.repoDefaultBranch ? `**Default Branch:** ${project.repoDefaultBranch}` : ""
@@ -30410,7 +30591,7 @@ function registerProjectTools(server, ctx, client) {
       return { content: [{ type: "text", text: `Failed to create system: ${message}` }], isError: true };
     }
   };
-  server.tool("create_system", "Create a new system in the configured organization", createSystemSchema, createSystemHandler);
+  server.tool("create_system", "Create a new system in the configured organization. Pass accountId whenever the system belongs to a client \u2014 a system created without it is not listed under any Account.", createSystemSchema, createSystemHandler);
 }
 
 // ../../libs/harmonica-services/src/mcp/tools/teamspace-tools.ts
@@ -31828,7 +32009,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,
@@ -31863,7 +32044,10 @@ function createHttpClient(config2) {
         teamspaceId: input.teamspaceId,
         name: input.title,
         description: input.description,
-        strategy: input.strategy
+        strategy: input.strategy,
+        // Without this the owning Account is dropped on the wire and the System
+        // is created unlinked — invisible in the Account's Systems list.
+        ...input.accountId !== void 0 && { accountId: input.accountId }
       });
       return { ...raw, projectId: raw?.id ?? raw?.projectId, title: raw?.name ?? raw?.title, orgId: raw?.organizationId ?? raw?.orgId };
     },
@@ -31898,7 +32082,10 @@ function createHttpClient(config2) {
         teamspaceId: input.teamspaceId,
         name: input.title,
         description: input.description,
-        strategy: input.strategy
+        strategy: input.strategy,
+        // Without this the owning Account is dropped on the wire and the System
+        // is created unlinked — invisible in the Account's Systems list.
+        ...input.accountId !== void 0 && { accountId: input.accountId }
       });
       return { ...raw, orgId: raw?.organizationId ?? raw?.orgId };
     },
@@ -32930,6 +33117,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",
@@ -32997,7 +33193,17 @@ 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");
+      }
+      return pollTaskResult(enqueued.taskId);
+    },
     // Embedding similarity
     embedProjectEntities: (projectId) => request("POST", `/api/systems/${encodeURIComponent(projectId)}/embeddings/generate`),
     findSimilarNotes: async (noteId, projectId, options) => {
@@ -33393,6 +33599,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 ?? [];
@@ -33828,7 +34046,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"3.0.1"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"3.2.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.0.1",
+  "version": "3.2.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {