@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/goals/collaborate.mjs

@@ -0,0 +1,415 @@
+/**
+ * lib/goals/collaborate.mjs — route a classified candidate through the
+ * collaboration primitives that ALREADY EXIST.
+ *
+ * There is no new coordination mechanism anywhere in this file. Every
+ * disposition lands on machinery that is already wired end to end:
+ *
+ *   SELF          → a board work item (`board.create`) + the local queue.
+ *   COLLABORATE   → a `work-claim` LEASE (lib/org/leases.mjs, 3s fail-open) so
+ *                   two agents cannot both drive the same objective work, then
+ *                   the board item + a comment naming the contributor.
+ *   HANDOFF       → a handoff ENVELOPE (lib/org/handoff.sendHandoff →
+ *                   `handoff.offer`), which rides the human channels, so every
+ *                   delegation is visible to the responsible humans.
+ *   NEEDS_REVIEW  → `approval.request` (lib/org/approvals.mjs) when the action
+ *                   class is gated — the one human-decision path that is
+ *                   already well-wired end to end — otherwise a REVIEW handoff
+ *                   to the named reviewer.
+ *   (escalate)    → `escalation.create`, the existing method, when the decision
+ *                   table says "ask, don't pile on more tasks".
+ *
+ * Where the spec anticipates a method hq has not shipped yet
+ * (`board.requestReview`, `escalation.ask`), this module PREFERS it when the
+ * vendored protocol carries it and otherwise falls back to the existing
+ * primitive **with a logged degradation**. It never silently does nothing.
+ *
+ * Fail-open, never silent: an unreachable server produces
+ * `{ok:false, reason}` plus a log line, and the caller still writes the local
+ * backlog item — the work survives the partition, the collaboration is retried.
+ *
+ * @module lib/goals/collaborate
+ */
+
+"use strict";
+
+import { createHash } from "node:crypto";
+
+import { methodDef } from "../org/protocol.mjs";
+
+/** The lease scope self-directed work claims. One of the four LEASE_SCOPES. */
+export const WORK_LEASE_SCOPE = "work-claim";
+
+function logOf(deps) {
+  return deps && typeof deps.log === "function" ? deps.log : () => {};
+}
+
+/** Stable resource id for an objective's work lease. Pure + deterministic. */
+export function workResourceId(objectiveKey, title) {
+  const h = createHash("sha1").update(`${objectiveKey}|${title}`).digest("hex").slice(0, 10);
+  return `objective:${objectiveKey}:${h}`;
+}
+
+// ---------------------------------------------------------------------------
+// Lazily-resolved defaults (so a test can inject everything and touch no I/O)
+// ---------------------------------------------------------------------------
+
+async function defaultCreateItem(item, deps) {
+  const { createItem } = await import("../org/board.mjs");
+  return createItem(item, { cfg: deps.cfg, base: deps.base, token: deps.token, fetchImpl: deps.fetchImpl });
+}
+
+async function defaultSendHandoff(o, deps) {
+  const { sendHandoff } = await import("../org/handoff.mjs");
+  return sendHandoff({ ...o, cfg: deps.cfg, fetchImpl: deps.fetchImpl, agentRoot: deps.agentRoot, directory: deps.directory });
+}
+
+async function defaultRequestApproval(o, deps) {
+  const { requestApproval } = await import("../org/approvals.mjs");
+  return requestApproval({ ...o, cfg: deps.cfg, fetchImpl: deps.fetchImpl, agentRoot: deps.agentRoot });
+}
+
+async function defaultClaimLease(scope, resourceId, opts) {
+  const { claimLease } = await import("../org/leases.mjs");
+  return claimLease(scope, resourceId, opts);
+}
+
+async function defaultCall(method, params, deps) {
+  const { call } = await import("../org/client.mjs");
+  return call(method, params, { base: deps.base, token: deps.token, orgId: deps.orgId, fetchImpl: deps.fetchImpl });
+}
+
+function pick(deps, name, fallback) {
+  return deps && typeof deps[name] === "function" ? deps[name] : fallback;
+}
+
+// ---------------------------------------------------------------------------
+// The board item — every disposition creates one, so the work is visible
+// ---------------------------------------------------------------------------
+
+/**
+ * Create the org board item that carries the work, stamped with the full
+ * provenance chain (`why`). Fail-open: an unreachable org returns
+ * `{ok:false, itemId:null, reason}` and the caller still writes locally.
+ *
+ * @param {object} item - { id, title, objectiveKey, obligationKey, why, priority, assignee? }
+ * @param {object} deps
+ * @returns {Promise<{ok:boolean, itemId:string|null, reason:string, frame?:object}>}
+ */
+export async function createWorkItem(item, deps = {}) {
+  const create = pick(deps, "createItem", (i) => defaultCreateItem(i, deps));
+  const payload = {
+    id: item.id,
+    title: item.title,
+    status: "open",
+    priority: item.priority || "normal",
+    assignee: item.assignee || deps.memberId || undefined,
+    // `why` is mandatory for machine-created work: {reason, objectiveKey,
+    // obligationKey, clause, expectedDelta}. A task a human cannot trace is a
+    // task a human cannot trust.
+    why: item.why || null,
+    objectiveKey: item.objectiveKey || null,
+    obligationKey: item.obligationKey || null,
+  };
+  let frame;
+  try {
+    frame = await create(payload);
+  } catch (err) {
+    logOf(deps)("warn", `[goals] board.create threw for "${item.title}": ${err && err.message ? err.message : err}`);
+    return { ok: false, itemId: null, reason: "board-create-threw" };
+  }
+  const ok = !!(frame && frame.ok);
+  if (!ok) {
+    logOf(deps)(
+      "warn",
+      `[goals] board.create failed for "${item.title}": ${(frame && frame.error && frame.error.code) || "unknown"} — the local backlog item still stands`
+    );
+  }
+  return {
+    ok,
+    itemId: ok ? (frame.result && (frame.result.id || frame.result.itemId)) || item.id : null,
+    reason: ok ? "created" : (frame && frame.error && frame.error.code) || "board-create-failed",
+    frame,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-disposition routers
+// ---------------------------------------------------------------------------
+
+/** COLLABORATE — claim the work lease before the item exists, so two agents racing the same objective resolve to one owner. */
+export async function routeCollaborate(item, classification, deps = {}) {
+  const claim = pick(deps, "claimLease", (s, r, o) => defaultClaimLease(s, r, o));
+  const resourceId = workResourceId(item.objectiveKey, item.title);
+  let lease;
+  try {
+    lease = await claim(WORK_LEASE_SCOPE, resourceId, {
+      holder: deps.memberId || undefined,
+      base: deps.base,
+      token: deps.token,
+      fetchImpl: deps.fetchImpl,
+    });
+  } catch (err) {
+    logOf(deps)("warn", `[goals] work-claim lease threw for ${resourceId}: ${err && err.message ? err.message : err}`);
+    lease = { held: true, failedOpen: true, reason: "lease-threw-fail-open" };
+  }
+  if (!lease.held) {
+    logOf(deps)("info", `[goals] standing down on "${item.title}" — a peer holds the work-claim lease (${lease.reason})`);
+    return { routed: "COLLABORATE", primitive: "lease", ok: false, reason: `lease-lost:${lease.reason}`, resourceId, item: null };
+  }
+  if (lease.failedOpen) {
+    logOf(deps)("warn", `[goals] work-claim lease for ${resourceId} FAILED OPEN (${lease.reason}) — proceeding, duplicate work is possible`);
+  }
+  const created = await createWorkItem(item, deps);
+  // Tell the contributor, over the existing board comment method.
+  let notified = null;
+  if (created.ok && classification.contributors.length > 0) {
+    const callImpl = pick(deps, "callImpl", (m, p) => defaultCall(m, p, deps));
+    try {
+      notified = await callImpl("board.comment", {
+        itemId: created.itemId,
+        body: `Working "${item.title}" toward ${item.objectiveKey}. Contributors: ${classification.contributors.join(", ")}.`,
+        mentionedMemberIds: classification.contributors,
+      });
+    } catch (err) {
+      logOf(deps)("warn", `[goals] could not comment the collaborator note: ${err && err.message ? err.message : err}`);
+    }
+  }
+  return {
+    routed: "COLLABORATE",
+    primitive: "lease+board",
+    ok: created.ok,
+    reason: created.reason,
+    resourceId,
+    leaseToken: lease.leaseToken || null,
+    failedOpen: !!lease.failedOpen,
+    itemId: created.itemId,
+    notified: !!(notified && notified.ok),
+  };
+}
+
+/** HANDOFF — the item first (a Cohort handoff must reference a work item), then the envelope. */
+export async function routeHandoff(item, classification, deps = {}) {
+  const created = await createWorkItem({ ...item, assignee: classification.target }, deps);
+  const send = pick(deps, "sendHandoff", (o) => defaultSendHandoff(o, deps));
+  let res;
+  try {
+    res = await send({
+      from: deps.memberId || "",
+      to: classification.target,
+      intent: item.title,
+      itemId: created.itemId || item.id,
+      payload: {
+        objectiveKey: item.objectiveKey,
+        obligationKey: item.obligationKey,
+        why: item.why,
+        expectedDelta: item.expectedDelta ?? null,
+        successCriteria: item.successCriteria || [],
+      },
+      dueBy: item.dueBy || undefined,
+    });
+  } catch (err) {
+    logOf(deps)("warn", `[goals] handoff to ${classification.target} threw: ${err && err.message ? err.message : err}`);
+    return { routed: "HANDOFF", primitive: "handoff.offer", ok: false, reason: "handoff-threw", itemId: created.itemId };
+  }
+  if (!res || !res.sent) {
+    logOf(deps)(
+      "warn",
+      `[goals] handoff to ${classification.target} was NOT sent (${(res && res.transport && res.transport.reason) || "unknown"}) — the work item exists and is unassigned in practice`
+    );
+  }
+  return {
+    routed: "HANDOFF",
+    primitive: "handoff.offer",
+    ok: !!(res && res.sent),
+    reason: (res && res.transport && res.transport.reason) || (res && res.sent ? "offered" : "not-sent"),
+    target: classification.target,
+    itemId: created.itemId,
+    runId: (res && res.runId) || null,
+  };
+}
+
+/**
+ * NEEDS_REVIEW — a gated action class goes through `approval.request` (the
+ * existing, well-wired human-decision path). A plain named reviewer goes
+ * through `board.requestReview` IF the vendored protocol carries it, else a
+ * REVIEW handoff envelope, with the fallback logged.
+ */
+export async function routeNeedsReview(item, classification, deps = {}) {
+  const created = await createWorkItem(item, deps);
+
+  if (classification.gatedClasses.length > 0) {
+    const request = pick(deps, "requestApproval", (o) => defaultRequestApproval(o, deps));
+    let res;
+    try {
+      res = await request({
+        action: item.obligationKey || item.title,
+        classification: classification.gatedClasses,
+        payload: {
+          title: item.title,
+          objectiveKey: item.objectiveKey,
+          obligationKey: item.obligationKey,
+          why: item.why,
+        },
+        subject: `${item.title} (advances ${item.objectiveKey})`,
+        itemId: created.itemId || item.id,
+        approver: classification.target ? { id: classification.target } : undefined,
+        requester: deps.memberId || undefined,
+      });
+    } catch (err) {
+      logOf(deps)("warn", `[goals] approval.request threw for "${item.title}": ${err && err.message ? err.message : err}`);
+      return { routed: "NEEDS_REVIEW", primitive: "approval.request", ok: false, reason: "approval-threw", itemId: created.itemId };
+    }
+    if (!res.requested) {
+      logOf(deps)(
+        "warn",
+        `[goals] "${item.title}" is gated (${classification.gatedClasses.join("+")}) but no approval could be requested — the item stays BLOCKED, not executed`
+      );
+    }
+    return {
+      routed: "NEEDS_REVIEW",
+      primitive: "approval.request",
+      ok: !!res.requested,
+      reason: res.requested ? "approval-pending" : "approval-not-requested",
+      approvalId: res.id || null,
+      classes: classification.gatedClasses,
+      itemId: created.itemId,
+      blocked: !res.requested,
+    };
+  }
+
+  // Plain review. Prefer the first-class method once hq ships it.
+  if (methodDef("board.requestReview")) {
+    const callImpl = pick(deps, "callImpl", (m, p) => defaultCall(m, p, deps));
+    try {
+      const frame = await callImpl("board.requestReview", {
+        itemId: created.itemId || item.id,
+        reviewer: classification.target,
+      });
+      return {
+        routed: "NEEDS_REVIEW",
+        primitive: "board.requestReview",
+        ok: !!(frame && frame.ok),
+        reason: frame && frame.ok ? "review-requested" : (frame && frame.error && frame.error.code) || "review-request-failed",
+        reviewer: classification.target,
+        itemId: created.itemId,
+      };
+    } catch (err) {
+      logOf(deps)("warn", `[goals] board.requestReview threw: ${err && err.message ? err.message : err}`);
+    }
+  } else {
+    logOf(deps)(
+      "info",
+      "[goals] board.requestReview is not in the vendored protocol — falling back to a REVIEW handoff envelope (degradation, not a silent skip)"
+    );
+  }
+
+  const send = pick(deps, "sendHandoff", (o) => defaultSendHandoff(o, deps));
+  let res;
+  try {
+    res = await send({
+      from: deps.memberId || "",
+      to: classification.target,
+      intent: `Review: ${item.title}`,
+      itemId: created.itemId || item.id,
+      payload: { review: true, objectiveKey: item.objectiveKey, why: item.why },
+    });
+  } catch (err) {
+    logOf(deps)("warn", `[goals] review handoff threw: ${err && err.message ? err.message : err}`);
+    return { routed: "NEEDS_REVIEW", primitive: "handoff.offer(review)", ok: false, reason: "review-handoff-threw", itemId: created.itemId };
+  }
+  return {
+    routed: "NEEDS_REVIEW",
+    primitive: "handoff.offer(review)",
+    ok: !!(res && res.sent),
+    reason: (res && res.transport && res.transport.reason) || "not-sent",
+    reviewer: classification.target,
+    itemId: created.itemId,
+    degraded: true,
+  };
+}
+
+/** SELF — just the board item; the local backlog write is the caller's job. */
+export async function routeSelf(item, classification, deps = {}) {
+  const created = await createWorkItem(item, deps);
+  return {
+    routed: "SELF",
+    primitive: "board.create",
+    ok: created.ok,
+    reason: created.reason,
+    itemId: created.itemId,
+    capabilityGap: classification.capabilityGap || null,
+  };
+}
+
+/**
+ * The decision table's "ask, don't pile on" branch: raise an escalation with
+ * concrete options rather than creating more tasks. Uses `escalation.create`,
+ * which the vendored protocol already carries.
+ *
+ * @param {object} o - { objectiveKey, question, options[], gap, why }
+ * @param {object} deps
+ * @returns {Promise<{ok:boolean, reason:string, id:string|null}>}
+ */
+export async function raiseEscalation(o = {}, deps = {}) {
+  const callImpl = pick(deps, "callImpl", (m, p) => defaultCall(m, p, deps));
+  const method = methodDef("escalation.ask") ? "escalation.ask" : "escalation.create";
+  if (method === "escalation.create" && methodDef("escalation.ask") == null) {
+    logOf(deps)("info", "[goals] escalation.ask is not in the vendored protocol — using escalation.create with the options in the body");
+  }
+  let frame;
+  try {
+    frame = await callImpl(method, {
+      title: o.question,
+      question: o.question,
+      body: [
+        o.question,
+        "",
+        ...(o.options || []).map((opt, i) => `${i + 1}. ${typeof opt === "string" ? opt : opt.label}`),
+        "",
+        `Objective: ${o.objectiveKey}. Gap: ${o.gap && o.gap.gap} vs target ${o.gap && o.gap.target} (${o.gap && o.gap.trend}).`,
+      ].join("\n"),
+      options: (o.options || []).map((opt) => (typeof opt === "string" ? { label: opt } : opt)),
+      severity: o.severity || "normal",
+      objectiveKey: o.objectiveKey,
+    });
+  } catch (err) {
+    logOf(deps)("warn", `[goals] ${method} threw: ${err && err.message ? err.message : err}`);
+    return { ok: false, reason: "escalation-threw", id: null };
+  }
+  const ok = !!(frame && frame.ok);
+  if (!ok) {
+    logOf(deps)(
+      "warn",
+      `[goals] ${method} failed (${(frame && frame.error && frame.error.code) || "unknown"}) — the question is still recorded in the audit ledger`
+    );
+  }
+  return { ok, reason: ok ? "raised" : (frame && frame.error && frame.error.code) || "failed", id: ok && frame.result ? frame.result.id || null : null, method };
+}
+
+/**
+ * Dispatch one classified candidate to its primitive.
+ * @param {object} item @param {object} classification @param {object} deps
+ * @returns {Promise<object>} the route result
+ */
+export async function routeWorkItem(item, classification, deps = {}) {
+  switch (classification.disposition) {
+    case "HANDOFF": return routeHandoff(item, classification, deps);
+    case "COLLABORATE": return routeCollaborate(item, classification, deps);
+    case "NEEDS_REVIEW": return routeNeedsReview(item, classification, deps);
+    case "SELF":
+    default: return routeSelf(item, classification, deps);
+  }
+}
+
+export default {
+  WORK_LEASE_SCOPE,
+  workResourceId,
+  createWorkItem,
+  routeWorkItem,
+  routeSelf,
+  routeCollaborate,
+  routeHandoff,
+  routeNeedsReview,
+  raiseEscalation,
+};