@codazen/harmonica-mcp 5.2.0 → 5.3.0

package/dist/index.js

@@ -21287,6 +21287,23 @@ watchPullRequest:
 
 Re-read the policy before each step rather than caching it, so a human revoking
 a toggle mid-flight takes effect on your next action.`;
+var WORK_ITEM_LIFECYCLE_INSTRUCTIONS = `WORK ITEM LIFECYCLE (CHANNEL-INDEPENDENT)
+
+When you perform substantive work for a known Work Item, keep that Work Item's
+status accurate even when the work happens outside a Harmonica Session.
+
+- Before starting, get the Work Item and transition it from \`not_started\` to
+  \`in_progress\` with \`transition_work_item_status\`. Resume a \`blocked\` item
+  only when its blocker has cleared. Do not reopen a \`done\` item unless new
+  work genuinely belongs to that same item.
+- When its requested outcome is actually complete, transition it to \`done\`.
+  If work cannot proceed, transition it to \`blocked\`. A conversation, task,
+  or Session ending is not evidence that every associated Work Item is done.
+- Manage multiple Work Items independently. Leave untouched items unchanged;
+  completing or blocking one must not change the others. A Session association
+  is useful lineage, but it is never required in order to update status.
+- If the status tool is unavailable or fails, say plainly that the Work Item
+  status was not updated rather than implying that it was.`;
 async function createMcpServer(ctx, client, registerTools, registerResources) {
   let guidelines;
   try {
@@ -21294,7 +21311,11 @@ async function createMcpServer(ctx, client, registerTools, registerResources) {
   } catch (err) {
     console.warn("[MCP] Failed to load beat guidelines for server instructions:", err);
   }
-  const instructions = [guidelines, DELIVERY_LATITUDE_INSTRUCTIONS].filter(Boolean).join("\n\n");
+  const instructions = [
+    guidelines,
+    DELIVERY_LATITUDE_INSTRUCTIONS,
+    WORK_ITEM_LIFECYCLE_INSTRUCTIONS
+  ].filter(Boolean).join("\n\n");
   const server = new McpServer({
     name: "harmonica",
     version: "0.1.0"
@@ -22429,9 +22450,9 @@ var CHECK_MAX_SCORES = {
 var BeatQualityGateError = class extends Error {
   code = "beat_quality_gate_failed";
   failure;
-  constructor(failure) {
-    super(failure.message);
-    this.failure = failure;
+  constructor(failure2) {
+    super(failure2.message);
+    this.failure = failure2;
   }
 };
 var PlanVersionsIdempotencyError = class extends Error {
@@ -25746,6 +25767,7 @@ var NotificationSchema2 = external_exports.object({
   systemId: external_exports.string(),
   beatId: external_exports.string().optional(),
   revisionId: external_exports.string().optional(),
+  workItemIds: external_exports.array(external_exports.string()).optional(),
   noteId: external_exports.string().optional(),
   checkId: external_exports.string().optional(),
   actorType: external_exports.enum(["user", "system"]),
@@ -25941,6 +25963,7 @@ var StartSessionRequestBodySchema = external_exports.object({
   systemId: external_exports.string().min(1),
   message: external_exports.string().min(1),
   revisionId: external_exports.string().min(1).optional(),
+  workItemIds: external_exports.array(external_exports.string().min(1)).max(50).optional(),
   /** Caller's own Session id — nests the new Session under it (B-231). */
   parentSessionId: external_exports.string().min(1).optional(),
   enableWebSearch: external_exports.boolean().optional()
@@ -26010,7 +26033,8 @@ var WORK_ITEM_EFFORT_SIZES = [
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
 var WorkItemEffortSizeSchema = external_exports.enum(WORK_ITEM_EFFORT_SIZES);
 var HumanAssigneeApiSchema = external_exports.object({
@@ -26150,9 +26174,24 @@ var WORK_ORDER_SIZES = [
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
 var WorkOrderSizeApiSchema = external_exports.enum(WORK_ORDER_SIZES);
+var WORK_ORDER_SIZE_VALUE_UNITS = {
+  XS: 4,
+  // half a person-day
+  S: 8,
+  // one person-day
+  M: 24,
+  // three person-days
+  L: 40,
+  // one person-week
+  XL: 80,
+  // two person-weeks
+  XXL: 160
+  // four person-weeks
+};
 var WORK_REQUEST_ORIGINS = [
   "client",
   "internal"
@@ -26195,6 +26234,9 @@ var WorkOrderApiSchema = external_exports.object({
   needsDecisionReason: NeedsDecisionReasonApiSchema.optional(),
   /** Absent when the Order arrived before it was sized, which the composition counts. */
   size: WorkOrderSizeApiSchema.optional(),
+  archived: external_exports.boolean().optional(),
+  archivedAt: external_exports.string().optional(),
+  archivedReason: external_exports.string().optional(),
   createdBy: external_exports.string().optional(),
   version: external_exports.number().optional(),
   createdAt: external_exports.string(),
@@ -26245,6 +26287,30 @@ var AccountApiSchema = external_exports.object({
   updatedAt: external_exports.string()
 }).passthrough();
 var AccountsResponseSchema = external_exports.object({ accounts: external_exports.array(AccountApiSchema) }).passthrough();
+var ManagedRelationshipStatusApiSchema = external_exports.enum(["active", "suspended", "revoked"]);
+var ManagedRelationshipApiSchema = external_exports.object({
+  relationshipId: external_exports.string(),
+  agencyOrgId: external_exports.string(),
+  customerOrgId: external_exports.string(),
+  agencyAccountId: external_exports.string(),
+  accountIds: external_exports.array(external_exports.string()),
+  status: ManagedRelationshipStatusApiSchema,
+  createdBy: external_exports.string(),
+  statusChangedBy: external_exports.string().nullish(),
+  statusChangedAt: external_exports.string().nullish(),
+  suspendedBy: external_exports.string().nullish(),
+  suspendedAt: external_exports.string().nullish(),
+  reactivatedBy: external_exports.string().nullish(),
+  reactivatedAt: external_exports.string().nullish(),
+  revokedBy: external_exports.string().nullish(),
+  revokedAt: external_exports.string().nullish(),
+  version: external_exports.number(),
+  createdAt: external_exports.string(),
+  updatedAt: external_exports.string()
+}).passthrough();
+var ManagedRelationshipsResponseSchema = external_exports.object({
+  relationships: external_exports.array(ManagedRelationshipApiSchema)
+}).passthrough();
 var AccountSystemApiSchema = external_exports.object({
   systemId: external_exports.string(),
   accountId: external_exports.string(),
@@ -26982,6 +27048,100 @@ ${formatLayerDetail(layer)}` }] };
   );
 }
 
+// ../../libs/harmonica-services/src/mcp/tools/managed-relationship-tools.ts
+function formatRelationship(relationship) {
+  if (!relationship) return "Managed relationship not found.";
+  return [
+    `ID: ${relationship.relationshipId}`,
+    `Agency Organization: ${relationship.agencyOrgId}`,
+    `Customer Organization: ${relationship.customerOrgId}`,
+    `Agency Account: ${relationship.agencyAccountId}`,
+    `Customer Accounts: ${relationship.accountIds.join(", ")}`,
+    `Status: ${relationship.status}`
+  ].join("\n");
+}
+function failure(action, error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  return {
+    content: [{ type: "text", text: `Failed to ${action}: ${message}` }],
+    isError: true
+  };
+}
+function registerManagedRelationshipTools(server, _ctx, client) {
+  server.tool(
+    "create_managed_relationship",
+    "Connect an agency Organization to a separately owned customer Organization and grant the agency access only to the named customer Accounts. Both Organizations, the agency commercial Account, and every customer Account must already exist. Phase 1 is administrator-provisioned; no approval request is sent.",
+    {
+      agencyOrgId: external_exports.string().describe("The managing agency Organization ID"),
+      customerOrgId: external_exports.string().describe("The customer-owned Organization ID"),
+      agencyAccountId: external_exports.string().describe("The agency-owned commercial Account for this customer"),
+      accountIds: external_exports.array(external_exports.string()).min(1).max(10).describe("Customer-owned Account IDs delegated to the agency")
+    },
+    async (input) => {
+      try {
+        const relationship = await client.createManagedRelationship(input);
+        return { content: [{ type: "text", text: `Created managed relationship.
+${formatRelationship(relationship)}` }] };
+      } catch (error2) {
+        return failure("create managed relationship", error2);
+      }
+    }
+  );
+  server.tool(
+    "list_managed_relationships",
+    "List customer Organizations and Account scopes managed by an agency Organization.",
+    { agencyOrgId: external_exports.string().describe("The managing agency Organization ID") },
+    async ({ agencyOrgId }) => {
+      try {
+        const relationships = await client.listManagedRelationships(agencyOrgId);
+        const text = relationships.length === 0 ? "No managed customer organizations found." : relationships.map(formatRelationship).join("\n\n");
+        return { content: [{ type: "text", text }] };
+      } catch (error2) {
+        return failure("list managed relationships", error2);
+      }
+    }
+  );
+  server.tool(
+    "get_managed_relationship",
+    "Get one managed relationship and its explicitly delegated customer Account IDs.",
+    { relationshipId: external_exports.string().describe("The managed relationship ID") },
+    async ({ relationshipId }) => {
+      try {
+        return {
+          content: [{
+            type: "text",
+            text: formatRelationship(await client.getManagedRelationship(relationshipId))
+          }]
+        };
+      } catch (error2) {
+        return failure("get managed relationship", error2);
+      }
+    }
+  );
+  server.tool(
+    "set_managed_relationship_status",
+    "Suspend, reactivate, or permanently revoke a managed relationship. Revoked relationships cannot be reactivated.",
+    {
+      relationshipId: external_exports.string().describe("The managed relationship ID"),
+      status: external_exports.enum(["active", "suspended", "revoked"]).describe("The target status")
+    },
+    async ({ relationshipId, status }) => {
+      try {
+        const relationship = await client.setManagedRelationshipStatus(relationshipId, status);
+        if (!relationship) {
+          return {
+            content: [{ type: "text", text: "Managed relationship not found." }],
+            isError: true
+          };
+        }
+        return { content: [{ type: "text", text: formatRelationship(relationship) }] };
+      } catch (error2) {
+        return failure("update managed relationship", error2);
+      }
+    }
+  );
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/membership-tools.ts
 var orgIdArg = external_exports.string().describe("The organization ID \u2014 see list_organizations");
 function registerMembershipTools(server, ctx, client) {
@@ -28352,22 +28512,16 @@ ${formatTree(tree.root)}` }] };
       }
       let scopeSystemId = systemId;
       if (!scopeSystemId) {
-        let bindings;
         let bindingsFetchFailed = false;
         try {
-          bindings = await client.getNotebookScopeBindings(notebookId);
+          const bindings = await client.getNotebookScopeBindings(notebookId);
           scopeSystemId = bindings?.find((b) => b.scopeType === "system")?.scopeId;
         } catch {
           bindingsFetchFailed = true;
         }
         if (!scopeSystemId) {
-          if (!bindingsFetchFailed) {
-            const hasLegacyProjectBinding = bindings?.some((b) => b.scopeType === "project");
-            if (hasLegacyProjectBinding) {
-              return { content: [{ type: "text", text: `Notebook "${notebookId}" has only a legacy 'project' scope binding \u2014 record may need B-247 migration re-check.` }], isError: true };
-            }
-          }
-          return { content: [{ type: "text", text: "No system scope: pass systemId or bind the notebook to a system first." }], isError: true };
+          const msg = bindingsFetchFailed ? "Failed to look up notebook scope binding \u2014 this may be transient. Pass an explicit systemId to proceed." : "No system scope: pass systemId or bind the notebook to a system first.";
+          return { content: [{ type: "text", text: msg }], isError: true };
         }
       }
       let tree;
@@ -28471,10 +28625,9 @@ ${formatTree(tree.root)}` }] };
         return { content: [{ type: "text", text: `Element "${elementId}" is not a live collection \u2014 its configuration cannot be edited here.` }], isError: true };
       }
       const base = existing.query;
-      const normalizedScope = systemId ? `system:${systemId}` : base.scope.replace(/^project:/, "system:");
-      const colonIdx = normalizedScope.indexOf(":");
-      if (colonIdx <= 0 || colonIdx === normalizedScope.length - 1) {
-        return { content: [{ type: "text", text: `Stored scope '${base.scope}' has no system id \u2014 pass an explicit systemId to re-bind this collection.` }], isError: true };
+      const normalizedScope = systemId ? `system:${systemId}` : base.scope;
+      if (!normalizedScope.startsWith("system:") || normalizedScope.length <= "system:".length) {
+        return { content: [{ type: "text", text: `Stored scope '${base.scope}' is not a valid system scope \u2014 pass an explicit systemId to re-bind this collection.` }], isError: true };
       }
       const mergedQuery = {
         source: "notes",
@@ -30764,19 +30917,16 @@ function registerSnapshotTools(server, ctx, client) {
   );
 }
 function normalizeSnapshot(raw) {
-  const anyRaw = raw;
   return {
     ...raw,
-    // Compat: v3 and earlier snapshots have 'project' instead of 'system'
-    system: raw.system ?? anyRaw["project"],
+    system: raw.system,
     beats: raw.beats ?? [],
     beatIndex: raw.beatIndex ?? [],
     proposals: raw.proposals ?? [],
     proposalIndex: raw.proposalIndex ?? [],
     revisions: raw.revisions ?? [],
     revisionIndex: raw.revisionIndex ?? [],
-    // Compat: v3 and earlier snapshots have 'projectRevisionIndex'
-    systemRevisionIndex: raw.systemRevisionIndex ?? anyRaw["projectRevisionIndex"] ?? [],
+    systemRevisionIndex: raw.systemRevisionIndex ?? [],
     activities: raw.activities ?? [],
     activityIndex: raw.activityIndex ?? [],
     notes: raw.notes ?? [],
@@ -30789,8 +30939,7 @@ function normalizeSnapshot(raw) {
     promptLogs: raw.promptLogs ?? [],
     beatVersions: raw.beatVersions ?? [],
     beatBeatVersionIndex: raw.beatBeatVersionIndex ?? [],
-    // Compat: v3 and earlier snapshots have 'projectBeatVersionIndex'
-    systemBeatVersionIndex: raw.systemBeatVersionIndex ?? anyRaw["projectBeatVersionIndex"] ?? [],
+    systemBeatVersionIndex: raw.systemBeatVersionIndex ?? [],
     beatVersionDropAssignments: raw.beatVersionDropAssignments ?? [],
     drops: raw.drops ?? [],
     accountDropIndex: raw.accountDropIndex ?? [],
@@ -30886,8 +31035,11 @@ function assertSnapshotShape(val, sourceHint) {
   if (typeof obj["version"] !== "number" || obj["version"] <= 0) {
     throw new Error(`Snapshot${sourceHint} has an invalid or missing 'version' field \u2014 it may not be a valid project snapshot.`);
   }
-  const systemOrProject = obj["system"] ?? obj["project"];
-  if (typeof systemOrProject !== "object" || systemOrProject === null || typeof systemOrProject["systemId"] !== "string") {
+  const system = obj["system"];
+  if (typeof system !== "object" || system === null || typeof system["systemId"] !== "string") {
+    if (typeof obj["project"] === "object" && obj["project"] !== null) {
+      throw new Error(`Snapshot${sourceHint} uses the v1-v3 'project' field format, which is no longer supported. Export a fresh snapshot from your environment and re-import.`);
+    }
     throw new Error(`Snapshot${sourceHint} is missing 'system.systemId' \u2014 it may not be a valid project snapshot.`);
   }
 }
@@ -31497,7 +31649,7 @@ ${t.acceptanceCriteria}` : null,
   };
   server.tool(
     "create_track",
-    'Create a Track under a Movement. Use for scoped initiatives \u2014 client SOWs, internal phases, engagement containers \u2014 that collect Deliverables and Drops. Do NOT use for software capabilities the product provides to end users (those are Beats). Recognition cues: "this engagement", "this SOW", "this phase of work", "the client project", "this track" \u2192 Track.',
+    'Create a Track under a Movement. Use for scoped initiatives \u2014 client SOWs, internal phases, engagement containers \u2014 that collect work items and Drops. Do NOT use for software capabilities the product provides to end users (those are Beats). Recognition cues: "this engagement", "this SOW", "this phase of work", "the client project", "this track" \u2192 Track.',
     createTrackSchema,
     createTrackHandler
   );
@@ -31937,24 +32089,47 @@ function registerValueVelocityTools(server, ctx, client) {
   );
 }
 
-// ../../libs/harmonica-services/src/mcp/tools/work-item-tools.ts
-var WORK_ITEM_STATUS_ENUM = ["not_started", "in_progress", "blocked", "done"];
-function formatOwner(owner) {
-  return owner ? `${owner.name} <${owner.email}>` : "unassigned";
-}
+// ../../libs/harmonica-services/src/tool-schemas/sizing.ts
+var WORK_ORDER_SIZE_ENUM = [
+  "XS",
+  "S",
+  "M",
+  "L",
+  "XL",
+  "XXL"
+];
 var WORK_ITEM_EFFORT_SIZE_ENUM = [
   "XS",
   "S",
   "M",
   "L",
-  "XL"
+  "XL",
+  "XXL"
 ];
+var SIZE_LABELS = {
+  XS: "half a person-day",
+  S: "one person-day",
+  M: "three person-days",
+  L: "one person-week",
+  XL: "two person-weeks",
+  XXL: "four person-weeks"
+};
+var SIZE_TABLE = WORK_ORDER_SIZE_ENUM.map(
+  (size) => `${size}=${SIZE_LABELS[size]} (${WORK_ORDER_SIZE_VALUE_UNITS[size]} VU)`
+).join(", ");
+var SIZE_BASIS = `Estimate the effort with NO AI assistance \u2014 the fully-human person-hours. Do NOT size what it will actually take with AI. Person-hours, not calendar time: two people for a week is XL, not L. ${SIZE_TABLE}.`;
+
+// ../../libs/harmonica-services/src/mcp/tools/work-item-tools.ts
+var WORK_ITEM_STATUS_ENUM = ["not_started", "in_progress", "blocked", "done"];
+function formatOwner(owner) {
+  return owner ? `${owner.name} <${owner.email}>` : "unassigned";
+}
 function registerWorkItemTools(server, _ctx, client) {
   server.tool(
     "list_track_work_items",
-    'List all work items under a Track (DeliverableGroup). A work item is an owned, statused unit of operational work. Recognition cues: "what work is on this track", "list the work items" \u2192 list_track_work_items.',
+    'List all work items under a Track. A work item is an owned, statused unit of operational work. Recognition cues: "what work is on this track", "list the work items" \u2192 list_track_work_items.',
     {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID")
+      trackId: external_exports.string().describe("The Track ID")
     },
     async ({ trackId }) => {
       const workItems = await client.listTrackWorkItems(trackId);
@@ -32000,15 +32175,15 @@ function registerWorkItemTools(server, _ctx, client) {
   );
   server.tool(
     "create_work_item",
-    'Create a work item under a Track (DeliverableGroup). A work item is an owned, statused unit of operational work \u2014 it is NOT a Beat. Starts in "not_started" status. Optionally link it to a Beat Version for capability lineage (v2, N-4E09-6574) \u2014 the link is one-directional and never required. Optionally link it to a Work Order it delivers part of; leaving it unattached is a supported state, not a gap to fill (N-4E09-7160). Optionally link it to a Bar it is planned into; leaving it unplanned is likewise a real state, not a gap (B-298).',
+    'Create a work item under a Track. A work item is an owned, statused unit of operational work \u2014 it is NOT a Beat. Starts in "not_started" status. Optionally link it to a Beat Version for capability lineage (v2, N-4E09-6574) \u2014 the link is one-directional and never required. Optionally link it to a Work Order it delivers part of; leaving it unattached is a supported state, not a gap to fill (N-4E09-7160). Optionally link it to a Bar it is planned into; leaving it unplanned is likewise a real state, not a gap (B-298).',
     {
-      trackId: external_exports.string().describe("The Track (DeliverableGroup) ID this work item belongs to"),
+      trackId: external_exports.string().describe("The Track ID this work item belongs to"),
       title: external_exports.string().min(1).max(300).describe("Work item title"),
       ownerName: external_exports.string().min(1).optional().describe("Optional owner display name (requires ownerEmail too)"),
       ownerEmail: external_exports.string().email().optional().describe("Optional owner email (requires ownerName too). A work item may be left unowned."),
       committedEstimateHours: external_exports.number().nonnegative().optional().describe("Optional committed estimate in hours"),
-      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).optional().describe("Optional rough t-shirt effort size (delivery lens) \u2014 independent of valueUnits"),
-      valueUnits: external_exports.number().nonnegative().optional().describe("Optional Value Units (commercial lens) \u2014 independent of effortSize"),
+      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).optional().describe(`Optional rough t-shirt effort size \u2014 seeds valueUnits. ${SIZE_BASIS}`),
+      valueUnits: external_exports.number().nonnegative().optional().describe(`Optional Value Units \u2014 fully-human person-hours. Defaults from effortSize; pass only to override. ${SIZE_BASIS}`),
       costPerValueUnit: external_exports.number().nonnegative().optional().describe("Optional price per Value Unit"),
       createdBy: external_exports.string().optional().describe("Optional creator identity for audit"),
       beatVersionId: external_exports.string().min(1).optional().describe("Optional Beat Version to link for capability lineage. Must exist."),
@@ -32056,7 +32231,9 @@ function registerWorkItemTools(server, _ctx, client) {
       unassignOwner: external_exports.boolean().optional().describe("Pass true to clear the owner, leaving the work item unowned. Cannot be combined with ownerName/ownerEmail."),
       committedEstimateHours: external_exports.number().nonnegative().optional().describe("New committed estimate in hours"),
       actualHours: external_exports.number().nonnegative().optional().describe("New actual hours logged"),
-      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).nullable().optional().describe("Rough t-shirt effort size (delivery lens). Pass null to clear; omit to leave untouched."),
+      effortSize: external_exports.enum(WORK_ITEM_EFFORT_SIZE_ENUM).nullable().optional().describe(
+        `Rough t-shirt effort size. Pass null to clear; omit to leave untouched. ${SIZE_BASIS}`
+      ),
       valueUnits: external_exports.number().nonnegative().nullable().optional().describe("Value Units (commercial lens). Pass null to clear; omit to leave untouched."),
       costPerValueUnit: external_exports.number().nonnegative().nullable().optional().describe("Price per Value Unit. Pass null to clear; omit to leave untouched."),
       beatVersionId: external_exports.string().min(1).nullable().optional().describe("Link to a Beat Version for capability lineage. Pass null to unlink; omit to leave the current link untouched."),
@@ -32117,10 +32294,10 @@ function registerWorkItemTools(server, _ctx, client) {
   );
   server.tool(
     "move_work_item",
-    "Move a work item to a different Track (DeliverableGroup). Re-derives its teamspace/org scope from the new Track.",
+    "Move a work item to a different Track. Re-derives its teamspace/org scope from the new Track.",
     {
       workItemId: external_exports.string().describe("The work item ID"),
-      newTrackId: external_exports.string().describe("The destination Track (DeliverableGroup) ID. Must exist.")
+      newTrackId: external_exports.string().describe("The destination Track ID. Must exist.")
     },
     async ({ workItemId, newTrackId }) => {
       const wi = await client.moveWorkItem(workItemId, newTrackId);
@@ -32163,13 +32340,12 @@ function registerWorkItemTools(server, _ctx, client) {
 }
 
 // ../../libs/harmonica-services/src/tool-schemas/work-order.ts
-var WORK_ORDER_SIZE_ENUM = ["XS", "S", "M", "L", "XL"];
 var create_work_order = {
   workRequestId: external_exports.string().min(1).describe("The Work Request this order was split from \u2014 immutable lineage"),
   title: external_exports.string().min(1).max(300).describe("Work order title"),
   description: external_exports.string().max(1e4).optional().describe("Optional detail beyond the title"),
   size: external_exports.enum(WORK_ORDER_SIZE_ENUM).optional().describe(
-    "Optional t-shirt size. An order can arrive before it is sized; a request's composition counts unsized orders rather than hiding them."
+    "Optional t-shirt size. An order can arrive before it is sized; a request's composition counts unsized orders rather than hiding them. " + SIZE_BASIS
   ),
   createdBy: external_exports.string().optional().describe("Optional creator identity for audit")
 };
@@ -32192,13 +32368,6 @@ var NEEDS_DECISION_REASON_ENUM = [
   "exceeds_capacity",
   "incoherent_with_decision"
 ];
-var WORK_ORDER_SIZE_ENUM2 = [
-  "XS",
-  "S",
-  "M",
-  "L",
-  "XL"
-];
 function oneLine(value) {
   return value.replace(/[\r\n]+/g, " ");
 }
@@ -32214,14 +32383,14 @@ function registerWorkOrderTools(server, _ctx, client) {
     // exactly the caller this alias exists to greet. Requiring it would answer
     // the migrated caller with a schema error instead of the migration message.
     {
-      trackId: external_exports.string().optional().describe("Ignored \u2014 the Track (DeliverableGroup) ID is no longer meaningful for Order scoping")
+      trackId: external_exports.string().optional().describe("Ignored \u2014 the Track ID is no longer meaningful for Order scoping")
     },
     async () => {
       return {
         content: [
           {
             type: "text",
-            text: "list_track_work_orders is deprecated. Use list_movement_work_orders(movementId) to fetch all Orders for an engagement \u2014 Orders are now scoped to their Movement, not their Track. If you have only a Track id, its Movement is on the Track itself: get_deliverable_group(trackId) returns movementId."
+            text: "list_track_work_orders is deprecated. Use list_movement_work_orders(movementId) to fetch all Orders for an engagement \u2014 Orders are now scoped to their Movement, not their Track. If you have only a Track id, its Movement is on the Track itself: get_track(trackId) returns movementId."
           }
         ],
         // The caller asked for a list and is getting none. A result without
@@ -32306,7 +32475,9 @@ function registerWorkOrderTools(server, _ctx, client) {
       workOrderId: external_exports.string().describe("The Work Order ID"),
       title: external_exports.string().min(1).max(300).optional().describe("New title"),
       description: external_exports.string().max(1e4).nullable().optional().describe("New description. Pass null to clear; omit to leave untouched."),
-      size: external_exports.enum(WORK_ORDER_SIZE_ENUM2).nullable().optional().describe("New t-shirt size. Pass null to return it to unsized; omit to leave untouched.")
+      size: external_exports.enum(WORK_ORDER_SIZE_ENUM).nullable().optional().describe(
+        "New t-shirt size. Pass null to return it to unsized; omit to leave untouched. " + SIZE_BASIS
+      )
     },
     async ({ workOrderId, title, description, size }) => {
       if (title === void 0 && description === void 0 && size === void 0) {
@@ -32336,7 +32507,7 @@ function registerWorkOrderTools(server, _ctx, client) {
     // the callers who have already stopped sending these.
     {
       workOrderId: external_exports.string().optional().describe("Ignored \u2014 a Work Order is no longer moveable between Tracks"),
-      newTrackId: external_exports.string().optional().describe("Ignored \u2014 a Track (DeliverableGroup) is no longer a valid parent for Orders")
+      newTrackId: external_exports.string().optional().describe("Ignored \u2014 a Track is no longer a valid parent for Orders")
     },
     async () => {
       return {
@@ -32538,6 +32709,14 @@ function registerWorkRequestTools(server, _ctx, client) {
   );
 }
 
+// ../../libs/harmonica-services/src/work-item-ids.ts
+function normalizeWorkItemIds(value) {
+  if (!Array.isArray(value)) return [];
+  return [...new Set(
+    value.filter((id) => typeof id === "string").map((id) => id.trim()).filter(Boolean)
+  )];
+}
+
 // ../../libs/harmonica-services/src/mcp/tools/workflow-tools.ts
 var TASK_STATUSES = ["pending", "running", "completed", "failed"];
 function registerWorkflowTools(server, ctx, client) {
@@ -32728,17 +32907,19 @@ ${JSON.stringify(task.result, null, 2)}
       systemId: external_exports.string().min(1).describe("The system ID \u2014 the trusted scope the session is rooted at"),
       message: external_exports.string().min(1).describe("Free-form first message describing what the session should do"),
       revisionId: external_exports.string().min(1).optional().describe("Optional Revision ID (rev-<uuid>). When provided, the Worker routes to the typed implementation session path (prepareRevisionImplementationSession), enabling file hint generation and richer session context. Omit for investigation, planning, or freeform sessions."),
+      workItemIds: external_exports.array(external_exports.string().min(1)).max(50).optional().describe("Optional Work Items associated with this session at kickoff. Each moves to in_progress when execution starts; the agent manages each item outcome independently."),
       parentSessionId: external_exports.string().min(1).optional().describe("Your current Session ID (sess-<uuid>). Pass it when you are kicking off this session as part of your own work \u2014 the new session then nests under yours in the session tree and can report back to you. Omit for a standalone session.")
     },
-    async ({ systemId, message, revisionId, parentSessionId }) => {
+    async ({ systemId, message, revisionId, workItemIds, parentSessionId }) => {
       try {
         await assertSystemExists(client, systemId);
         const task = await client.startSession(
           systemId,
           message,
           { name: ctx.user.name, email: ctx.user.email },
-          revisionId?.trim() || parentSessionId?.trim() ? {
+          revisionId?.trim() || workItemIds?.length || parentSessionId?.trim() ? {
             ...revisionId?.trim() && { revisionId: revisionId.trim() },
+            ...workItemIds?.length && { workItemIds: normalizeWorkItemIds(workItemIds) },
             ...parentSessionId?.trim() && { parentSessionId: parentSessionId.trim() }
           } : void 0
         );
@@ -32966,6 +33147,7 @@ var TOOL_PROFILES = Object.freeze({
     registerOrganizationTools,
     registerTeamspaceTools,
     registerMembershipTools,
+    registerManagedRelationshipTools,
     registerSystemTools,
     registerSystemLifecycleTools,
     allow(registerBeatVersionTools, ["relocate_beat_version"])
@@ -33045,6 +33227,7 @@ function registerAllTools(server, ctx, client, profile) {
   registerValueVelocityTools(server, ctx, client);
   registerNotebookTools(server, ctx, client);
   registerAccountTools(server, ctx, client);
+  registerManagedRelationshipTools(server, ctx, client);
   registerMovementTools(server, ctx, client);
   registerExternalMappingTools(server, ctx, client);
   registerWorkItemTools(server, ctx, client);
@@ -34387,6 +34570,7 @@ function createHttpClient(config2) {
     // Agent sessions
     startSession: async (systemId, message, triggeredBy, options) => {
       const trimmedRevisionId = options?.revisionId?.trim();
+      const workItemIds = normalizeWorkItemIds(options?.workItemIds);
       const trimmedParentSessionId = options?.parentSessionId?.trim();
       const result = await request(
         "POST",
@@ -34396,6 +34580,7 @@ function createHttpClient(config2) {
           message,
           ...triggeredBy && { triggeredBy },
           ...trimmedRevisionId && { revisionId: trimmedRevisionId },
+          ...workItemIds?.length && { workItemIds },
           ...trimmedParentSessionId && { parentSessionId: trimmedParentSessionId }
         }
       );
@@ -35034,6 +35219,31 @@ function createHttpClient(config2) {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/movements`);
       return res?.movements ?? [];
     },
+    createManagedRelationship: async (input) => {
+      const { agencyOrgId, ...body } = input;
+      const result = await request(
+        "POST",
+        `/api/organizations/${encodeURIComponent(agencyOrgId)}/managed-relationships`,
+        body
+      );
+      if (result === void 0) throw new Error("Resource not found when creating managed relationship");
+      return result;
+    },
+    getManagedRelationship: async (relationshipId) => request("GET", `/api/managed-relationships/${encodeURIComponent(relationshipId)}`),
+    listManagedRelationships: async (agencyOrgId) => {
+      const result = await request(
+        "GET",
+        `/api/organizations/${encodeURIComponent(agencyOrgId)}/managed-relationships`
+      );
+      return result?.relationships ?? [];
+    },
+    setManagedRelationshipStatus: async (relationshipId, status) => {
+      return request(
+        "PATCH",
+        `/api/managed-relationships/${encodeURIComponent(relationshipId)}/status`,
+        { status }
+      );
+    },
     listChildAccounts: async (accountId) => {
       const res = await request("GET", `/api/accounts/${encodeURIComponent(accountId)}/children`);
       return res?.accounts ?? [];
@@ -35553,7 +35763,7 @@ function loadConfig() {
   };
 }
 async function main() {
-  console.error(`[harmonica-mcp] v${"5.2.0"} starting\u2026`);
+  console.error(`[harmonica-mcp] v${"5.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": "5.2.0",
+  "version": "5.3.0",
   "description": "MCP server for Harmonica — connect any MCP-compatible AI assistant to Harmonica",
   "license": "MIT",
   "bin": {