@cohortapp/agent-sdk 2.10.0 → 2.11.1

package/lib/org/resource-tools.mjs

@@ -0,0 +1,317 @@
+/**
+ * lib/org/resource-tools.mjs — the `resource_*` desk tools, GENERATED.
+ *
+ * THE FAMILY. `OrgResource` is a venture's own deliverable catalogue: one
+ * org-scoped card per artifact (deck, one-pager, film, site, data room…),
+ * keyed `(orgId, slug)`, written by the FTLAB portal, by Genesis, by the
+ * artifact ingest, or by hand, and rendered to humans at `/resources`. Until
+ * this wave it was reachable from NO agent code path in either plane — a
+ * venture's own AI colleagues could not list, add, correct, reorder or remove
+ * a single one of the venture's deliverables. Eight protocol methods now
+ * exist; these are their curated tools.
+ *
+ * WHY THIS FILE IS A GENERATOR AND NOT A TABLE. hq's responder desks expose
+ * 239 ops across 11 families; maestro's curated table exposed 69 desk tools
+ * across 9 — files 29 vs 7, crm 44 vs 8. That divergence has one cause: the two
+ * tool tables are hand-written twice, so they drift the moment one side moves
+ * and nobody hand-copies the delta. This family refuses to be able to drift the
+ * same way. The tool NAME, the ACCESS TIER, the BINDING and the DESK TAG are
+ * all DERIVED from the vendored protocol declaration — the same declaration
+ * hq's handlers are registered from — and the only thing a human writes here is
+ * PRESENTATION: the title, the description, and the input schema. Add a ninth
+ * `resource.*` method to `lib/org/protocol.mjs` and sync it, and a ninth tool
+ * appears on the next import with no edit to this file; `resource-tools.test.mjs`
+ * then goes red until someone gives it a real description. The capability is
+ * never dark and the gap is never quiet — which is the whole thesis of the
+ * wave that shipped the family.
+ *
+ * ACCESS. `expectedAccessFor` derives the tier from the method's protocol
+ * SCOPE, never from a literal typed here: `resource.list` / `resource.get` ride
+ * `org.read` → `access:"read"` (every tier's lookup set, including
+ * least-privilege "default"); the six writes ride `org.write` →
+ * `access:"write"` (ceo + leadership). NONE is `access:"admin"` — that is the
+ * CEO-only escape-hatch tier, and a venture's colleagues are default- and
+ * leadership-tier agents, so parking their own deliverables there would ship
+ * this family exactly as dark as it was before. See lib/org/tool-access.mjs.
+ *
+ * NO `outbound` FLAG ANYWHERE IN THIS BLOCK. A card is org-internal metadata;
+ * nothing here puts free text a human reads onto an outbound channel, and the
+ * send-gate lane stays exactly messaging_send / email_send / email_draft_send /
+ * org_call_share_step.
+ *
+ * THE FILES BRIDGE IS A POINTER, NOT A SECOND DRIVE. A card returns its own
+ * columns plus a `fileId`, and NOTHING derived from the `WorkspaceFile` — no
+ * bytes, name, mime, size, version or share list. The catalogue is org-wide
+ * under `org.read` while the drive is seat-scoped by `driveVisibilityWhere`, so
+ * a resource tool that re-served file content would be a one-call bypass of the
+ * share filter. Bytes are read with `files_get` / `files_doc_read` /
+ * `org_rpc files.exportRequest`. `resource_attach_file` is the one seam, and hq
+ * resolves the id through the drive's own `getFileOrThrow` (org pin +
+ * `canSeeDriveFile`, NOT_FOUND either way), so it can neither cite another
+ * tenant's file nor act as an existence oracle for one this seat cannot see.
+ *
+ * Node builtins only. ESM.
+ *
+ * @module lib/org/resource-tools
+ */
+
+"use strict";
+
+import { METHODS } from "./protocol.mjs";
+import { expectedAccessFor } from "./tool-access.mjs";
+
+/** The protocol family these tools are generated from. */
+export const RESOURCE_FAMILY = "resource";
+
+/** The desk tag every generated entry carries (gates on DESK_PROBES.resource). */
+export const RESOURCE_DESK = "resource";
+
+// Schema helpers — same shapes tool-surface.mjs builds its entries with.
+const S = (properties, required = []) => ({ type: "object", properties, required });
+const str = (description) => ({ type: "string", description });
+const num = (description) => ({ type: "number", description });
+const bool = (description) => ({ type: "boolean", description });
+const obj = (description) => ({ type: "object", description });
+const arr = (items, description) => ({ type: "array", items, description });
+
+/**
+ * PRESENTATION ONLY, keyed by protocol method. No `name`, no `access`, no
+ * `binding`, no `desk` — those four are derived, and a literal here would be
+ * the hand-copy this file exists to prevent.
+ *
+ * Each description carries what the schema cannot: the semantics an agent gets
+ * wrong on the first try (total-vs-partial reorder, shallow-merge metadata,
+ * what survives a delete) and the refusals it will otherwise learn by
+ * BAD_REQUEST.
+ * @type {Readonly<Record<string, {title: string, description: string, input_schema: object}>>}
+ */
+export const RESOURCE_PRESENTATION = Object.freeze({
+  "resource.list": {
+    title: "List venture deliverables",
+    description:
+      "This venture's deliverable catalogue (resource.list) — the same cards, in the same " +
+      "order, that humans see at /resources: sortOrder asc, then createdAt asc. Each card is " +
+      "{id, slug, kind, title, description, url, previewImageUrl, source, fileId, metadata, " +
+      "sortOrder, createdAt, updatedAt}. `source` says who put it there — \"ftlab-portal\" " +
+      "(pushed by the venture portal and re-upserted on every push), \"genesis\", or " +
+      "\"manual\" (created through this desk). `fileId` non-null means the artifact is also " +
+      "filed in the workspace drive: read it with files_get / files_doc_read, NOT from here — " +
+      "this desk returns the card's own columns and nothing about the file itself. Filters: " +
+      "`kind`, `source`, free-text `q` (matches title OR description, case-insensitive), " +
+      "`hasFile` (true = only drive-backed cards, false = only link-only cards, omit = both). " +
+      "No cursor — raise `limit` (max 200) if the catalogue is long.",
+    input_schema: S({
+      kind: str("Filter by card kind, e.g. \"deck\", \"one-pager\", \"film\", \"site\" (≤64 chars)."),
+      source: str("Filter by provenance: \"ftlab-portal\" | \"genesis\" | \"manual\" (≤64 chars)."),
+      q: str("Free text; matches title OR description, case-insensitive (≤200 chars)."),
+      hasFile: bool("true = only cards with a drive fileId; false = only link-only cards; omit = both."),
+      limit: num("Max cards 1..200 (default 100)."),
+    }),
+  },
+  "resource.get": {
+    title: "Get one deliverable",
+    description:
+      "One catalogue card by `slug` (the stable org-scoped natural key the portal, the " +
+      "/resources page and every tool here use) or by `resourceId` — pass EXACTLY ONE; " +
+      "neither or both is a BAD_REQUEST. Returns the card's own columns only. A card in " +
+      "another workspace answers NOT_FOUND identically to one that never existed, so this is " +
+      "not an existence oracle — do not read NOT_FOUND as \"it belongs to someone else\".",
+    input_schema: S({
+      slug: str("Card slug, e.g. \"deck-seed-round\" (preferred — stable across re-pushes)."),
+      resourceId: str("Card id (cuid). Alternative to slug; never pass both."),
+    }),
+  },
+  "resource.create": {
+    title: "Add a deliverable",
+    description:
+      "Add a card to the venture's catalogue (resource.create). `url` OR `fileId` must be " +
+      "present — a card pointing nowhere is the exact state this desk exists to end. Omit " +
+      "`slug` and the server derives one from kind + title (and suffixes -2, -3 on collision) " +
+      "using the SAME transform the portal uses, so a portal push and an agent create agree. " +
+      "`source` is NOT an input: the server stamps \"manual\", so an agent cannot relabel its " +
+      "own card as portal-provenance. This is NOT an upsert — an existing slug answers " +
+      "CONFLICT rather than overwriting a portal row someone guessed the slug of; correct an " +
+      "existing card with resource_update. `metadata` is free JSON (object only, ≤16KB) for " +
+      "provenance such as sha256/runId/documentVersion — NEVER put a credential in it; only " +
+      "its KEY NAMES ride the event chain.",
+    input_schema: S(
+      {
+        kind: str("Card kind, e.g. \"deck\" | \"one-pager\" | \"film\" | \"site\" (≤64 chars)."),
+        title: str("Human title as it appears at /resources (≤200 chars)."),
+        url: str("Public https URL (≤2048) or an in-app path like \"/files/abc123\". Required unless fileId is given."),
+        fileId: str("Workspace drive file id to cite. Required unless url is given; must be a file this seat can already see."),
+        slug: str("Optional explicit slug: lowercase a-z0-9 words joined by single hyphens, ≤64. Omit to let the server derive it."),
+        description: str("One or two sentences a human reads under the title (≤2000 chars)."),
+        previewImageUrl: str("Thumbnail URL (≤2048)."),
+        metadata: obj("Free-JSON provenance object, ≤16KB serialized. No secrets."),
+        sortOrder: num("Position 0..10000 (ties break on createdAt asc). Omit to append."),
+      },
+      ["kind", "title"],
+    ),
+  },
+  "resource.update": {
+    title: "Correct a deliverable",
+    description:
+      "Edit an existing card (resource.update), addressed by EXACTLY ONE of `slug` or " +
+      "`resourceId`. At least one mutable field is required, else BAD_REQUEST. `metadata` is a " +
+      "SHALLOW MERGE over what is already there — {...prior, ...patch} — and a key you pass as " +
+      "null is DELETED. It is deliberately not a whole-object replace: the artifact ingest " +
+      "writes sha256/runId/documentVersion/byteState/driveUrl into metadata, and a replace " +
+      "would let a one-field edit destroy the delivery provenance. Three fields are NOT " +
+      "editable here, each on purpose: `slug` (it is the ref AND the portal's re-sync key — " +
+      "renaming it would orphan the upsert and duplicate the card on the next push), `fileId` " +
+      "(re-pointing a card at a different drive row is a separately-audited act — use " +
+      "resource_attach_file), and `source` (provenance is server-owned).",
+    input_schema: S({
+      slug: str("Card slug to edit (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+      kind: str("New kind (≤64 chars)."),
+      title: str("New title (≤200 chars)."),
+      description: str("New description (≤2000 chars); null clears it."),
+      url: str("New https URL (≤2048) or in-app path."),
+      previewImageUrl: str("New thumbnail URL (≤2048); null clears it."),
+      metadata: obj("Metadata PATCH — shallow-merged; a key set to null is removed. ≤16KB serialized."),
+      sortOrder: num("New position 0..10000. This is the PARTIAL nudge; resource_reorder is the total re-sort."),
+    }),
+  },
+  "resource.delete": {
+    title: "Remove a deliverable",
+    description:
+      "Remove a card from the catalogue (resource.delete), addressed by EXACTLY ONE of `slug` " +
+      "or `resourceId`. THE CARD ONLY: the WorkspaceFile it cited is NOT deleted and not even " +
+      "soft-deleted — the drive owns its own 30-day recovery lane — which is why the reply " +
+      "carries `fileRetained: true`. Relay that truth; do not tell a human the file is gone. " +
+      "The card's Cortex SOURCES entry goes with it, so a removed deliverable stops being " +
+      "discoverable. CAVEAT worth saying out loud: deleting a card whose `source` is " +
+      "\"ftlab-portal\" is not permanent — the next portal push re-upserts it on its natural " +
+      "key. If a portal card is wrong, fix it upstream or correct it with resource_update.",
+    input_schema: S({
+      slug: str("Card slug to remove (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+    }),
+  },
+  "resource.reorder": {
+    title: "Re-sort the catalogue",
+    description:
+      "Set the whole catalogue's order (resource.reorder) — this is what changes what a human " +
+      "sees FIRST at /resources. TOTAL, not partial: `slugs` must name EVERY card in this " +
+      "workspace exactly once, and each gets sortOrder = its index. Anything else is a " +
+      "CONFLICT that names the missing, unknown and duplicated slugs back to you — which is " +
+      "the feature, not the friction: a card created by the portal while you were composing " +
+      "the list surfaces as a refusal instead of silently scrambling the order. So list first " +
+      "(resource_list), reorder from THAT list, and re-list if it refuses. To nudge one card " +
+      "without touching the rest, use resource_update { sortOrder } instead. Returns the full " +
+      "catalogue in its new order — no re-list needed.",
+    input_schema: S(
+      {
+        slugs: arr(
+          { type: "string" },
+          "Every slug in the workspace, exactly once, in the order you want (1..500).",
+        ),
+      },
+      ["slugs"],
+    ),
+  },
+  "resource.attachFile": {
+    title: "Cite a drive file on a card",
+    description:
+      "Point a catalogue card at a workspace drive file (resource.attachFile), addressed by " +
+      "EXACTLY ONE of `slug` or `resourceId`. This is a LINK write, not a byte write: it sets " +
+      "fileId and merges {driveUrl:\"/files/<fileId>\"} into metadata. hq resolves the file " +
+      "through the drive's own permission check, so you may only cite a file this seat can " +
+      "already see, and a file you cannot see answers NOT_FOUND exactly like one that does not " +
+      "exist. `setUrl` defaults to FALSE and should usually stay there: a deck, one-pager or " +
+      "film keeps its public URL because the venture's own site and outreach link that object " +
+      "— pass setUrl:true only when the card's destination really should become the in-app " +
+      "file. Attaching does not copy, move or re-share the file.",
+    input_schema: S(
+      {
+        fileId: str("Workspace drive file id to cite."),
+        slug: str("Card slug (preferred). Never pass both slug and resourceId."),
+        resourceId: str("Card id (cuid). Alternative to slug."),
+        setUrl: bool("Also rewrite the card's url to /files/<fileId>. Default false — an external URL is usually load-bearing."),
+      },
+      ["fileId"],
+    ),
+  },
+  "resource.detachFile": {
+    title: "Stop citing a drive file",
+    description:
+      "Clear a card's drive citation (resource.detachFile), addressed by EXACTLY ONE of `slug` " +
+      "or `resourceId`: fileId → null and the `driveUrl` key drops out of metadata. The " +
+      "WorkspaceFile is untouched. The card's `url` is left exactly as it was UNLESS you pass " +
+      "a replacement `url`. One guard: if the card's only destination IS the file being " +
+      "detached (its url is /files/<fileId>), `url` is REQUIRED and the call answers CONFLICT " +
+      "without it — otherwise this verb would manufacture the dead card the whole family " +
+      "exists to prevent.",
+    input_schema: S({
+      slug: str("Card slug (preferred). Never pass both slug and resourceId."),
+      resourceId: str("Card id (cuid). Alternative to slug."),
+      url: str("Replacement destination — required when the card's url is the /files/<fileId> being detached."),
+    }),
+  },
+});
+
+/**
+ * `resource.attachFile` → `resource_attach_file`. Dots become underscores and
+ * camelCase humps split, so the tool name is a pure function of the protocol
+ * name and cannot be typed differently from it.
+ * @param {string} method
+ * @returns {string}
+ */
+export function toolNameForMethod(method) {
+  return String(method)
+    .replace(/\./g, "_")
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+/**
+ * Build the curated `resource_*` entries from the VENDORED protocol table.
+ *
+ * Order follows the protocol declaration, so the tool block reads in the order
+ * the family was designed in. Returns `[]` when the vendored protocol carries
+ * no `resource` family at all — an older protocol degrades cleanly, exactly
+ * like the desk gates.
+ *
+ * A family method with no presentation entry still gets a tool, built from the
+ * descriptor: an under-described capability is a documentation bug, but a
+ * MISSING one is the failure this whole wave was called to fix, so drift
+ * surfaces as a red test (resource-tools.test.mjs asserts the presentation
+ * table covers the family exactly) and never as a dark verb.
+ *
+ * @param {Record<string, {family?:string, scope?:string, sideEffecting?:boolean}>} [methods]
+ * @returns {Array<object>}
+ */
+export function buildResourceTools(methods = METHODS) {
+  const out = [];
+  for (const [method, def] of Object.entries(methods || {})) {
+    if (!def || def.family !== RESOURCE_FAMILY) continue;
+    // Scope is the authority (it is what hq gates on). The `??` arm only fires
+    // for a method the REAL vendored table does not carry — i.e. a synthetic
+    // table under test — and mirrors sideEffecting so such a row still lands on
+    // the correct side of the read/write line rather than defaulting open.
+    const access = expectedAccessFor(method) ?? (def.sideEffecting ? "write" : "read");
+    const p = RESOURCE_PRESENTATION[method];
+    out.push({
+      name: toolNameForMethod(method),
+      title: p ? p.title : method,
+      description: p
+        ? p.description
+        : `Undocumented ${RESOURCE_FAMILY} verb (${method}) — generated from the protocol ` +
+          `declaration so the capability is reachable; add a presentation entry in ` +
+          `lib/org/resource-tools.mjs.`,
+      input_schema: p ? p.input_schema : S({}),
+      access,
+      desk: RESOURCE_DESK,
+      binding: { kind: "rpc", method },
+    });
+  }
+  return out;
+}
+
+/**
+ * The generated block, spliced into `ORG_TOOLS` by lib/org/tool-surface.mjs.
+ * @type {ReadonlyArray<object>}
+ */
+export const RESOURCE_TOOLS = Object.freeze(buildResourceTools());