@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/tool-surface.mjs

@@ -67,6 +67,15 @@ import {
   approvalWait,
   fetchSelfProfile,
 } from "./client.mjs";
+// The hq vocabularies the model must pick from (an out-of-vocabulary enum value
+// is a BAD_REQUEST). Sourced from the wire contract so the tool table and the
+// normaliser can never disagree about what hq accepts.
+import {
+  BOARD_COLS,
+  TASK_PRIORITIES,
+  ESCALATION_SEVERITIES,
+  MEMORY_CLASSES,
+} from "./param-contract.mjs";
 
 /** Default org server origin when neither env nor config names one. */
 export const DEFAULT_COHORT_BASE = "https://os.cohortapp.com";
@@ -265,7 +274,7 @@ export const ORG_TOOLS = Object.freeze([
     title: "Send org message",
     description:
       "Post a message into an org channel (messaging.send). Send-gate screened locally; " +
-      "the server enforces channel ACLs + pairing. A clientMsgId is auto-minted for dedup.",
+      "the server enforces channel ACLs + pairing. An idempotencyId is auto-minted for dedup.",
     input_schema: S(
       {
         channelId: str("Channel id (use messaging_open_dm for a member DM)."),
@@ -308,23 +317,46 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "board_complete",
     title: "Complete work item",
-    description: "Mark a claimed board item complete (board.complete).",
-    input_schema: S({ itemId: str("Board item id."), note: str("Completion note (optional).") }, ["itemId"]),
+    description:
+      "Mark a claimed board item complete (board.complete). The server's schema is strict: " +
+      "evidence goes in `proof` (a free-text note is wrapped into proof.note).",
+    input_schema: S(
+      {
+        itemId: str("Board item id."),
+        proof: {
+          type: "object",
+          description: "Evidence of completion (optional) — e.g. {note, url, commit}.",
+        },
+      },
+      ["itemId"],
+    ),
     access: "write",
     binding: { kind: "rpc", method: "board.complete" },
   },
   {
     name: "task_create",
     title: "Create task",
-    description: "Create a task on the org board (board.createTask).",
+    description:
+      "Create a task on the org board (board.createTask). Due dates are NOT settable at " +
+      "create time — create the task, then set dueAt with task_update.",
     input_schema: S(
       {
         title: str("Task title."),
-        description: str("Task body/description (optional)."),
-        assignee: str("Member to assign (optional)."),
-        status: str("Initial status (optional)."),
-        priority: str("Priority (optional)."),
-        dueAt: str("Due date ISO 8601 (optional)."),
+        detail: str("Task body/description (optional)."),
+        assigneeId: str("Member id to assign (optional) — an id, not a name."),
+        col: {
+          type: "string",
+          enum: BOARD_COLS,
+          description: "Initial board column (optional; defaults to triage).",
+        },
+        priority: {
+          type: "string",
+          enum: TASK_PRIORITIES,
+          description: "Priority P0 (highest) .. P4 (optional; defaults to P2).",
+        },
+        channelId: str("The Space/DM whose board this task belongs to (optional)."),
+        workstreamId: str("Workstream/lane id (optional)."),
+        reviewerId: str("Reviewer member id (optional)."),
       },
       ["title"],
     ),
@@ -335,16 +367,26 @@ export const ORG_TOOLS = Object.freeze([
     name: "task_update",
     title: "Update task",
     description:
-      "Update a task's status/fields, or move it into a workstream lane (board.updateTask). Pass workstreamName to assign a task that's sitting in no lane — reuses an existing lane by name or creates it.",
+      "Update a task's column/fields, or move it into a workstream lane (board.updateTask). Pass " +
+      "workstreamName to assign a task that's sitting in no lane — reuses an existing lane by name " +
+      "or creates it. This verb CANNOT reassign a task — use task_assign for that.",
     input_schema: S(
       {
         taskId: str("Task id."),
-        status: str("New status (optional)."),
+        col: {
+          type: "string",
+          enum: BOARD_COLS,
+          description: "Move the task to this board column (optional).",
+        },
         title: str("New title (optional)."),
-        description: str("New description (optional)."),
-        assignee: str("New assignee (optional)."),
-        priority: str("New priority (optional)."),
-        dueAt: str("New due date ISO 8601 (optional)."),
+        detail: str("New description (optional)."),
+        priority: {
+          type: "string",
+          enum: TASK_PRIORITIES,
+          description: "New priority P0..P4 (optional).",
+        },
+        dueAt: str("New due date ISO 8601 (optional; null clears it)."),
+        blockedBy: str("Free-text reason this task is waiting (optional)."),
         workstreamName: str(
           "Move the task into this workstream lane — reuses an existing lane by name or creates it (optional).",
         ),
@@ -354,6 +396,20 @@ export const ORG_TOOLS = Object.freeze([
     access: "write",
     binding: { kind: "rpc", method: "board.updateTask" },
   },
+  {
+    name: "task_assign",
+    title: "Assign task",
+    description:
+      "Set or clear a task's owner (board.assignTask). The assignee must be an ACTIVE member id " +
+      "in this org; pass null to unassign. task_update cannot do this — its schema has no " +
+      "assignee field.",
+    input_schema: S(
+      { taskId: str("Task id."), assigneeId: str("Member id to own the task (null clears it).") },
+      ["taskId", "assigneeId"],
+    ),
+    access: "write",
+    binding: { kind: "rpc", method: "board.assignTask" },
+  },
   {
     name: "task_comment",
     title: "Comment on task",
@@ -374,12 +430,23 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "decision_propose",
     title: "Propose decision",
-    description: "Propose a decision into the org registry (decision.propose).",
+    description:
+      "Propose a decision into the org registry (decision.propose). The rationale is recorded " +
+      "in the explain-yourself `why` block — a decision proposed without it is registered with " +
+      "no rationale at all.",
     input_schema: S(
       {
         title: str("Decision title."),
-        rationale: str("Why (optional)."),
-        scope: str("Scope (optional)."),
+        body: str("The decision text (optional)."),
+        why: {
+          type: "object",
+          description:
+            "Explain-yourself provenance: {reason, options[], clause, wouldChange}. `reason` is " +
+            "the rationale the registry displays.",
+        },
+        tag: str("Scope/tag for the registry, e.g. \"eng\" (optional)."),
+        clause: str("The charter clause this decision rests on (optional)."),
+        supersedes: str("Id of the decision this replaces (optional)."),
       },
       ["title"],
     ),
@@ -398,7 +465,7 @@ export const ORG_TOOLS = Object.freeze([
     name: "decision_comment",
     title: "Comment on decision",
     description: "Comment on a decision (decision.comment).",
-    input_schema: S({ decisionId: str("Decision id."), body: str("Comment body.") }, ["decisionId", "body"]),
+    input_schema: S({ decisionId: str("Decision id."), text: str("Comment text.") }, ["decisionId", "text"]),
     access: "write",
     binding: { kind: "rpc", method: "decision.comment" },
   },
@@ -413,7 +480,9 @@ export const ORG_TOOLS = Object.freeze([
         actionClass: str("Action class, e.g. \"external_comms\"."),
         payload: { type: "object", description: "The intent payload the approval binds (hash-bound server-side)." },
         subject: str("Human-readable subject (optional)."),
-        payload_hash: str("Precomputed sha256 payload hash (optional — pass through from a structured approval_required result)."),
+        payloadHash: str("Precomputed sha256 payload hash (64 hex chars) — pass through from a structured approval_required result. Supply this OR payload."),
+        itemId: str("Board item this approval blocks (optional — the task flips to `blocked`)."),
+        expiresAt: str("ISO 8601 expiry (optional)."),
       },
       ["actionClass"],
     ),
@@ -444,14 +513,19 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "knowledge_append",
     title: "Append org knowledge",
-    description: "Append a knowledge episode to the shared plane (knowledge.append).",
+    description:
+      "Append a knowledge episode to the shared plane (knowledge.append). Enrichment " +
+      "(kind/participants/links/refs) is persisted inside `metadata`.",
     input_schema: S(
       {
-        text: str("The fact/episode text."),
-        kind: str("Kind (optional)."),
-        group: str("Group hint (server enforces ACL; optional)."),
+        body: str("The fact/episode text."),
+        group: str("Group hint (server enforces ACL; optional) — \"org\" | \"unit:<id>\" | \"barrier:<cell>\"."),
+        metadata: {
+          type: "object",
+          description: "Structured enrichment stored with the episode (optional) — e.g. {kind, participants, links, refs}.",
+        },
       },
-      ["text"],
+      ["body"],
     ),
     access: "write",
     binding: { kind: "rpc", method: "knowledge.append" },
@@ -459,14 +533,24 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "memory_author",
     title: "Author org memory",
-    description: "Write to the org memory plane (memory.author).",
+    description:
+      "Write a Cortex index-hint entry to the org memory plane (memory.author). `scopes` is the " +
+      "ACL field (who may recall this), NOT a tag list. Amend an existing entry with " +
+      "{amendOf, note}.",
     input_schema: S(
       {
-        content: str("Memory content."),
-        kind: str("Memory kind (optional)."),
-        tags: arr({ type: "string" }, "Tags (optional)."),
+        memoryClass: {
+          type: "string",
+          enum: MEMORY_CLASSES,
+          description: "Which memory plane this entry belongs to.",
+        },
+        title: str("Short title (<=200 chars) — the entry's headline."),
+        summary: str("The memory content (optional but expected)."),
+        scopes: arr({ type: "string" }, "ACL scopes that may recall this (optional; empty = org-wide)."),
+        amendOf: str("Id of the entry this amends (optional)."),
+        note: str("Revision note — REQUIRED when amendOf is set."),
       },
-      ["content"],
+      ["memoryClass", "title"],
     ),
     access: "write",
     binding: { kind: "rpc", method: "memory.author" },
@@ -475,22 +559,31 @@ export const ORG_TOOLS = Object.freeze([
   {
     name: "member_profile",
     title: "Member profile",
-    description: "One member's full profile (member.get).",
-    input_schema: S({ memberId: str("Member id or slug.") }, ["memberId"]),
+    description: "One member's full profile (member.get). Resolved by SLUG, not by member id.",
+    input_schema: S({ slug: str("Member slug (e.g. \"isla-roselli\").") }, ["slug"]),
     access: "read",
     binding: { kind: "rpc", method: "member.get" },
   },
   {
     name: "escalation_raise",
     title: "Raise escalation",
-    description: "Raise an escalation to the org (escalation.create).",
+    description:
+      "Raise an escalation to the org (escalation.create). An escalation must reference " +
+      "something — supply a taskId or a channelId (or both).",
     input_schema: S(
       {
-        severity: str("Severity, e.g. low|medium|high|critical."),
-        subject: str("Escalation subject."),
-        body: str("Details."),
+        title: str("Escalation title (<=500 chars)."),
+        severity: {
+          type: "string",
+          enum: ESCALATION_SEVERITIES,
+          description: "Severity (optional; defaults to medium).",
+        },
+        detail: str("Details (optional)."),
+        taskId: str("The task being escalated (supply this or channelId)."),
+        channelId: str("The channel being escalated (supply this or taskId)."),
+        waitingOn: str("Who/what this is blocked on (optional)."),
       },
-      ["severity", "subject", "body"],
+      ["title"],
     ),
     access: "write",
     binding: { kind: "rpc", method: "escalation.create" },
@@ -2495,7 +2588,14 @@ export async function executeOrgTool(name, input = {}, o = {}) {
           // Business-dedup ids auto-minted where hq expects them. (artifact.*
           // is sideEffecting:false at the dispatcher — the hq artifact service
           // self-manages its writes — so these params ARE the dedup lane.)
-          if (name === "messaging_send" && !params.clientMsgId) params.clientMsgId = randomUUID();
+          //
+          // messaging.send's dedup key is `idempotencyId` — hq's
+          // sendMessageSchemaV1 REQUIRES it and never reads `clientMsgId` (that
+          // is the COLUMN it de-dups into, not the wire name). Minting the wrong
+          // name meant every message the model sent through this plane came back
+          // BAD_REQUEST. `call()` would mint it now anyway (param-contract), but
+          // minting here keeps the id available to the caller's audit row.
+          if (name === "messaging_send" && !params.idempotencyId) params.idempotencyId = randomUUID();
           if (name === "email_send" && !params.idempotencyId) params.idempotencyId = randomUUID();
           if (name === "artifact_create" && !params.clientMsgId) params.clientMsgId = randomUUID();
           if (name === "artifact_act" && !params.idempotencyKey) params.idempotencyKey = randomUUID();

package/lib/org/tool-surface.test.mjs

@@ -59,11 +59,13 @@ function fakeFetch(body = { ok: true, result: { fine: true } }, { status = 200,
 
 // ── table shape ────────────────────────────────────────────────────────────
 
-test("table: curated 28 + 5 email + 5 artifact + 69 desk tools, snake_case names, valid access + schemas", () => {
+test("table: curated 29 + 5 email + 5 artifact + 69 desk tools, snake_case names, valid access + schemas", () => {
   // 2026-08 mobile-parity delta: +5 mail (report_spam/react/move_mailbox/
   // summarise/ask) and +3 asks (files/calendar/crm) → desk 56 → 64; the
   // call-working-sessions delta adds the 5 calls-desk tools → 69.
-  assert.equal(ORG_TOOLS.length, 107, "28 curated + 5 email + 5 artifact + 69 desk");
+  // The wire-contract fix adds task_assign: hq's editTaskSchema (board.updateTask)
+  // has NO assignee field, so reassignment needs board.assignTask — curated 28 → 29.
+  assert.equal(ORG_TOOLS.length, 108, "29 curated + 5 email + 5 artifact + 69 desk");
   assert.equal(ORG_TOOLS.filter((t) => t.desk).length, 69, "exactly sixty-nine desk tools");
   assert.equal(ORG_TOOLS.filter((t) => t.email).length, 5, "exactly five email tools");
   assert.equal(ORG_TOOLS.filter((t) => t.artifact).length, 5, "exactly five artifact tools");
@@ -88,19 +90,19 @@ test("OUTBOUND_METHODS is DERIVED from outbound:true tools (messaging/email/mail
 test("email gating: family present in the vendored protocol → tools active; override excludes", () => {
   // The email family landed in the vendored protocol (sync-protocol phase 1).
   assert.equal(emailFamilyAvailable(), true, "vendored protocol carries email.send");
-  assert.equal(getOrgTools().length, 107);
+  assert.equal(getOrgTools().length, 108);
   const without = getOrgTools({ emailAvailable: false });
-  assert.equal(without.length, 102);
+  assert.equal(without.length, 103);
   assert.ok(!without.some((t) => t.email), "email tools excluded when family absent");
 });
 
 test("artifact gating: family present → tools active; override excludes (email precedent)", () => {
   assert.equal(artifactFamilyAvailable(), true, "vendored protocol carries artifact.act");
   const without = getOrgTools({ artifactAvailable: false });
-  assert.equal(without.length, 102);
+  assert.equal(without.length, 103);
   assert.ok(!without.some((t) => t.artifact), "artifact tools excluded when family absent");
   const neither = getOrgTools({ emailAvailable: false, artifactAvailable: false, desksAvailable: false });
-  assert.equal(neither.length, 28, "all additive families off → the 28 always-on tools");
+  assert.equal(neither.length, 29, "all additive families off → the 29 always-on tools");
 });
 
 test("isOrgTool / orgToolDef cover the full table; unknown names rejected", () => {
@@ -203,7 +205,7 @@ test("approval_wait: requires approvalId; dispatches the bounded long-poll", asy
 
 // ── executor: send-gate parity (§1.5a) ─────────────────────────────────────
 
-test("messaging_send: screened through the send-gate, clientMsgId auto-minted", async () => {
+test("messaging_send: screened through the send-gate, idempotencyId auto-minted", async () => {
   const screened = [];
   const fetchImpl = fakeFetch({ ok: true, result: { messageId: "m1" } });
   const frame = await executeOrgTool(
@@ -216,7 +218,10 @@ test("messaging_send: screened through the send-gate, clientMsgId auto-minted",
   assert.equal(screened[0].recipient, "C9");
   assert.equal(screened[0].text, "hello org");
   const body = JSON.parse(fetchImpl.calls[0].init.body);
-  assert.ok(body.clientMsgId && body.clientMsgId.length >= 8, "clientMsgId auto-minted");
+  // hq's sendMessageSchemaV1 REQUIRES `idempotencyId`. Minting `clientMsgId`
+  // (the column name, not the wire name) 400'd every message this plane sent.
+  assert.ok(body.idempotencyId && body.idempotencyId.length >= 8, "idempotencyId auto-minted");
+  assert.equal(body.clientMsgId, undefined, "the column name is NOT the wire name");
   assert.ok(fetchImpl.calls[0].init.headers["x-idempotency-key"], "dispatcher idempotency key present");
 });