@elmundi/ship-cli 0.14.2 → 0.15.3

package/lib/commands/knowledge.mjs

@@ -1,18 +1,14 @@
 /**
- * `shipctl knowledge` — manage workspace knowledge buckets.
+ * `shipctl knowledge` — read-only access to workspace knowledge buckets.
  *
- * The canonical knowledge surface is now Ship-owned:
- * ``knowledge_buckets`` contain ``bucket_articles`` and
- * ``knowledge_sources`` records where each article came from. The
- * historical ``init`` command remains as a compatibility wrapper for
- * starter PRs, while ``bootstrap`` is the GitHub Actions entry point
- * that opens the generated knowledge PR after wizard seed merge.
+ * The agent calls this during a routine run to pull bucket articles
+ * into context (the same surface the Navigator chat reads). Bucket
+ * authoring, ingestion, and intel harvest live server-side now;
+ * starter docs are written by the wizard at workspace seed time.
  *
  * Usage:
  *
- *   shipctl knowledge fetch repository-context --workspace <id>
- *   shipctl knowledge bootstrap --workspace <id> --repo <id|owner/name>
- *   shipctl knowledge refresh-intel --workspace <id> --repo <id|owner/name>
+ *   shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
  *
  * Auth: bearer token from ``SHIP_API_TOKEN`` (the same env var the
  * console docs describe for CLI sessions minted under Settings →
@@ -28,28 +24,15 @@
  *   4. ``https://api.ship.elmundi.com`` as the canonical production
  *      workspace API.
  *
- * Workspace + repo resolution:
+ * Workspace resolution:
  *
- *   - ``--workspace`` pins a workspace id; otherwise we fetch
+ *   - ``--workspace`` pins a workspace id; ``SHIP_WORKSPACE_ID`` env
+ *     var serves as a fallback. Without either we fetch
  *     ``GET /v1/workspaces`` and pick the only row. If there are
- *     multiple rows we abort with a helpful message so the caller
- *     either supplies ``--workspace`` or narrows their PAT.
- *   - ``--repo`` pins a repo id (uuid) or a full_name like
- *     ``owner/name``; otherwise we fetch
- *     ``GET /v1/workspaces/{ws}/repos`` and pick the most-recently
- *     activated row — the same heuristic the wizard uses, so
- *     ``shipctl knowledge init`` on a freshly-onboarded workspace
- *     seeds the repo the user just activated.
+ *     multiple rows we abort with a helpful message.
  */
 
-const VERSION = "v1";
-
-/** Static starters with source markdown under ``artifacts/knowledge-starters``.
- * Procedural catalog recipes are exposed by the backend under the
- * ``ship-recipes/<pattern-id>`` prefix because that list is generated from
- * on-disk pattern artifacts at runtime. */
-export const STATIC_KNOWLEDGE_SLUGS = ["code-style", "ui-runbook"];
-export const RECIPE_KNOWLEDGE_PREFIX = "ship-recipes/";
+const VERSION = "v2";
 
 /**
  * @param {{baseUrl?: string, json?: boolean}} ctx
@@ -61,22 +44,10 @@ export async function knowledgeCommand(ctx, rest) {
     printKnowledgeHelp();
     return;
   }
-  if (sub === "init") {
-    await knowledgeInitCommand(ctx, args);
-    return;
-  }
   if (sub === "fetch") {
     await knowledgeFetchCommand(ctx, args);
     return;
   }
-  if (sub === "bootstrap") {
-    await knowledgeBootstrapCommand(ctx, args);
-    return;
-  }
-  if (sub === "refresh-intel" || sub === "refresh-context") {
-    await knowledgeRefreshIntelCommand(ctx, args);
-    return;
-  }
   console.error(
     `Unknown 'shipctl knowledge' subcommand: ${sub}\nRun: shipctl knowledge --help`,
   );
@@ -84,111 +55,31 @@ export async function knowledgeCommand(ctx, rest) {
 }
 
 function printKnowledgeHelp() {
-  console.log(`shipctl knowledge — manage workspace knowledge buckets (${VERSION})
+  console.log(`shipctl knowledge — read workspace knowledge buckets (${VERSION})
 
 SUBCOMMANDS
-  shipctl knowledge init [--workspace <id>] [--repo <id|owner/name>]
-                         [--only <csv>] [--json]
   shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]
-  shipctl knowledge bootstrap [--workspace <id>] [--repo <id|owner/name>]
-                             [--json]
-  shipctl knowledge refresh-intel [--workspace <id>] [--repo <id|owner/name>]
-                                 [--json]
-
-INIT FLAGS
-  --workspace <id>   Workspace UUID. Defaults to the only workspace
-                     the caller's PAT can see.
-  --repo <ref>       Workspace repo UUID, or GitHub 'owner/name'.
-                     Defaults to the most-recently activated repo in
-                     the resolved workspace.
-  --only <csv>       Comma-separated starter slugs. Defaults to the
-                     full backend catalog, including static starters
-                     (${STATIC_KNOWLEDGE_SLUGS.join(", ")}) and generated
-                     recipe starters under ${RECIPE_KNOWLEDGE_PREFIX}<pattern-id>.
-  --base-url URL     Workspace control-plane API. See env fallbacks.
-  --json             Emit a machine-readable JSON summary.
 
 ENV
   SHIP_API_TOKEN             Required. Bearer PAT minted at /settings.
+  SHIP_WORKSPACE_ID          Optional. Skips the /v1/workspaces lookup.
   SHIP_WORKSPACE_API_BASE    Optional override for the control plane.
   SHIP_API_BASE              Fallback only (co-located proxies).
 
 EXIT
-  0  PR opened (or idempotently already present)
+  0  bucket fetched
   1  arg / config error
   2  auth error (401)
   3  network / HTTP 5xx
 `);
 }
 
-/**
- * @param {{baseUrl?: string, json?: boolean}} ctx
- * @param {string[]} args
- */
-async function knowledgeInitCommand(ctx, args) {
-  const opts = parseInitArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
-  const token = process.env.SHIP_API_TOKEN || "";
-  if (!token) {
-    console.error(
-      "SHIP_API_TOKEN is required. Mint one at /settings in the Ship console.",
-    );
-    process.exit(1);
-  }
-
-  const selection = opts.only;
-  if (selection !== null) {
-    const unknown = selection.filter((s) => !isKnownKnowledgeStarterSlug(s));
-    if (unknown.length) {
-      console.error(
-        `Unknown knowledge slug(s): ${unknown.join(", ")}\nKnown static slugs: ${STATIC_KNOWLEDGE_SLUGS.join(", ")}; recipe slugs must start with ${RECIPE_KNOWLEDGE_PREFIX}`,
-      );
-      process.exit(1);
-    }
-  }
-
-  let workspaceId = opts.workspace;
-  if (!workspaceId) {
-    workspaceId = await resolveSoleWorkspace(baseUrl, token);
-  }
-
-  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
-
-  const body = selection === null ? {} : { selection };
-  const result = await apiPostJson(
-    baseUrl,
-    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/knowledge_seed`,
-    body,
-    token,
-  );
-
-  if (ctx.json || opts.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  const files = Array.isArray(result.files) ? result.files : [];
-  console.log(
-    `Seeded compatibility knowledge files for workspace ${workspaceId} / repo ${repoId}:\n` +
-      `  PR #${result.pr_number}: ${result.pr_url}\n` +
-      `  Branch: ${result.branch}\n` +
-      `  Files: ${files.join(", ") || "(none)"}\n` +
-      `\nShip-owned repository context is refreshed separately with:\n` +
-      `  shipctl knowledge refresh-intel --workspace ${workspaceId} --repo ${repoId}`,
-  );
-}
-
-export function isKnownKnowledgeStarterSlug(slug) {
-  return (
-    STATIC_KNOWLEDGE_SLUGS.includes(slug) ||
-    slug.startsWith(RECIPE_KNOWLEDGE_PREFIX)
-  );
-}
-
 async function knowledgeFetchCommand(ctx, args) {
   const opts = parseFetchArgs(args);
   const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
   const token = requireToken();
-  let workspaceId = opts.workspace;
+  let workspaceId =
+    opts.workspace || (process.env.SHIP_WORKSPACE_ID || "").trim() || "";
   if (!workspaceId) {
     workspaceId = await resolveSoleWorkspace(baseUrl, token);
   }
@@ -227,87 +118,14 @@ async function knowledgeFetchCommand(ctx, args) {
   }
 }
 
-async function knowledgeRefreshIntelCommand(ctx, args) {
-  const opts = parseRefreshArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
-  const token = requireToken();
-  let workspaceId = opts.workspace;
-  if (!workspaceId) {
-    workspaceId = await resolveSoleWorkspace(baseUrl, token);
-  }
-  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
-  const result = await apiPostJson(
-    baseUrl,
-    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/intel/harvest`,
-    {},
-    token,
-  );
-  if (ctx.json || opts.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  const where = result.enqueued
-    ? `queued as job ${result.job_id || "(unknown)"}`
-    : `completed inline, intel_id=${result.intel_id || "(none)"}`;
-  console.log(
-    `Repository context refresh for workspace ${workspaceId} / repo ${repoId}: ${where}\n` +
-      `Fetch it with: shipctl knowledge fetch repository-context --workspace ${workspaceId}`,
-  );
-}
-
-async function knowledgeBootstrapCommand(ctx, args) {
-  const opts = parseBootstrapArgs(args);
-  const baseUrl = resolveBaseUrl(opts.baseUrl || explicitGlobalBaseUrl(ctx));
-  const token = requireToken();
-  let workspaceId = opts.workspace;
-  if (!workspaceId) {
-    workspaceId = await resolveSoleWorkspace(baseUrl, token);
-  }
-  const repoId = await resolveRepoId(baseUrl, token, workspaceId, opts.repo);
-  const result = await apiPostJson(
-    baseUrl,
-    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos/${encodeURIComponent(repoId)}/knowledge/bootstrap`,
-    {},
-    token,
-  );
-  if (ctx.json || opts.json) {
-    console.log(JSON.stringify(result, null, 2));
-    return;
-  }
-  const files = Array.isArray(result.files) ? result.files : [];
-  if (result.status === "already_done") {
-    console.log(
-      `Knowledge bootstrap already completed for workspace ${workspaceId} / repo ${repoId}:\n` +
-        `  PR #${result.pr_number || "?"}: ${result.pr_url || "(unknown)"}`,
-    );
-    return;
-  }
-  console.log(
-    `Knowledge bootstrap opened PR #${result.pr_number} for workspace ${workspaceId} / repo ${repoId}:\n` +
-      `  ${result.pr_url}\n` +
-      `  Files: ${files.join(", ") || "(none)"}`,
-  );
-}
-
 function explicitGlobalBaseUrl(ctx) {
   return ctx?.baseUrlSource === "flag" ? ctx.baseUrl : null;
 }
 
-/**
- * @param {string[]} args
- * @returns {{
- *   workspace: string|null,
- *   repo: string|null,
- *   only: string[]|null,
- *   baseUrl: string|null,
- *   json: boolean,
- * }}
- */
-function parseInitArgs(args) {
+function parseFetchArgs(args) {
   const out = {
+    slug: null,
     workspace: null,
-    repo: null,
-    only: null,
     baseUrl: null,
     json: false,
   };
@@ -329,8 +147,6 @@ function parseInitArgs(args) {
   while (copy.length) {
     if (
       consume("--workspace", "workspace") ||
-      consume("--repo", "repo") ||
-      consume("--only", "only") ||
       consume("--base-url", "baseUrl")
     ) {
       continue;
@@ -344,81 +160,19 @@ function parseInitArgs(args) {
       printKnowledgeHelp();
       process.exit(0);
     }
-    console.error(`Unknown flag: ${copy[0]}`);
-    process.exit(1);
-  }
-  if (out.only !== null) {
-    out.only = String(out.only)
-      .split(",")
-      .map((s) => s.trim())
-      .filter(Boolean);
-  }
-  return out;
-}
-
-function parseFetchArgs(args) {
-  const out = parseCommonArgs(args, { slug: null });
-  if (!out.slug) {
-    console.error("Usage: shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]");
-    process.exit(1);
-  }
-  return out;
-}
-
-function parseRefreshArgs(args) {
-  return parseCommonArgs(args, { repo: null });
-}
-
-function parseBootstrapArgs(args) {
-  return parseCommonArgs(args, { repo: null });
-}
-
-function parseCommonArgs(args, extra) {
-  const out = {
-    workspace: null,
-    baseUrl: null,
-    json: false,
-    ...extra,
-  };
-  const copy = [...args];
-  const consume = (flag, key) => {
-    if (copy[0] === flag && copy[1] !== undefined) {
-      copy.shift();
-      out[key] = String(copy.shift());
-      return true;
-    }
-    const p = `${flag}=`;
-    if (copy[0] && copy[0].startsWith(p)) {
-      out[key] = copy[0].slice(p.length);
-      copy.shift();
-      return true;
-    }
-    return false;
-  };
-  while (copy.length) {
-    if (
-      consume("--workspace", "workspace") ||
-      consume("--repo", "repo") ||
-      consume("--base-url", "baseUrl")
-    ) {
-      continue;
-    }
-    if (copy[0] === "--json") {
-      out.json = true;
-      copy.shift();
-      continue;
-    }
-    if (!String(copy[0]).startsWith("-") && "slug" in out && out.slug === null) {
+    if (!String(copy[0]).startsWith("-") && out.slug === null) {
       out.slug = String(copy.shift());
       continue;
     }
-    if (copy[0] === "--help" || copy[0] === "-h") {
-      printKnowledgeHelp();
-      process.exit(0);
-    }
     console.error(`Unknown flag: ${copy[0]}`);
     process.exit(1);
   }
+  if (!out.slug) {
+    console.error(
+      "Usage: shipctl knowledge fetch <bucket-slug> [--workspace <id>] [--json]",
+    );
+    process.exit(1);
+  }
   return out;
 }
 
@@ -467,53 +221,6 @@ async function resolveSoleWorkspace(baseUrl, token) {
   return String(rows[0].id);
 }
 
-/**
- * @param {string} baseUrl
- * @param {string} token
- * @param {string} workspaceId
- * @param {string|null} hint
- * @returns {Promise<string>}
- */
-async function resolveRepoId(baseUrl, token, workspaceId, hint) {
-  // Direct UUID? Accept it verbatim — avoids a list call.
-  if (hint && /^[0-9a-fA-F-]{32,36}$/.test(hint) && hint.includes("-")) {
-    return hint;
-  }
-  const rows = await apiGetJson(
-    baseUrl,
-    `/v1/workspaces/${encodeURIComponent(workspaceId)}/repos`,
-    token,
-  );
-  if (!Array.isArray(rows) || rows.length === 0) {
-    console.error(
-      `Workspace ${workspaceId} has no activated repos. Activate one in the console first.`,
-    );
-    process.exit(1);
-  }
-  if (hint) {
-    const match = rows.find(
-      (r) =>
-        r.full_name === hint ||
-        `${r.owner ?? ""}/${r.name ?? ""}` === hint ||
-        r.id === hint,
-    );
-    if (!match) {
-      const known = rows.map((r) => r.full_name ?? r.id).join(", ");
-      console.error(
-        `--repo ${hint} doesn't match any activated repo in workspace ${workspaceId}.\nKnown: ${known}`,
-      );
-      process.exit(1);
-    }
-    return String(match.id);
-  }
-  const sorted = [...rows].sort((a, b) => {
-    const ax = a.activated_at ? Date.parse(a.activated_at) : 0;
-    const bx = b.activated_at ? Date.parse(b.activated_at) : 0;
-    return bx - ax;
-  });
-  return String(sorted[0].id);
-}
-
 /**
  * @param {string} baseUrl
  * @param {string} path
@@ -523,16 +230,6 @@ async function apiGetJson(baseUrl, path, token) {
   return apiRequest(baseUrl, path, "GET", token, null);
 }
 
-/**
- * @param {string} baseUrl
- * @param {string} path
- * @param {Record<string, unknown>} body
- * @param {string} token
- */
-async function apiPostJson(baseUrl, path, body, token) {
-  return apiRequest(baseUrl, path, "POST", token, body);
-}
-
 /**
  * @param {string} baseUrl
  * @param {string} path

package/lib/commands/preflight.mjs

@@ -0,0 +1,213 @@
+/**
+ * `shipctl preflight` — Phase 4 lifecycle gate.
+ *
+ * The trigger workflow runs this *before* `shipctl run` so a missing
+ * secret or an unauthorised role denial surfaces as a structured
+ * inbox-shaped result instead of a half-spawned agent that crashes
+ * mid-prompt. Two outputs depending on the result:
+ *
+ *   ready=true  → exit 0, JSON body shows the resolved deny list
+ *                  + the env contract that passed.
+ *   ready=false → exit 0 but `ready: false` and a list of
+ *                  ``missing_secrets`` and/or ``denied_role`` reasons.
+ *                  The workflow's case statement uses this to skip
+ *                  the run cleanly without consuming a Cursor seat.
+ *
+ * Phase 4 MVP scope (ship narrow, expand on real need):
+ *   - Secrets check: SHIP_API_TOKEN, SHIP_WORKSPACE_ID,
+ *     SHIP_API_BASE (or SHIP_WORKSPACE_API_BASE), and CURSOR_API_KEY
+ *     when provider is cursor (the default).
+ *   - Role denial surfacing: read the resolved role's `denied_tools`
+ *     so the workflow can decide whether the role is even runnable
+ *     in this environment (e.g. a future check that flags "reviewer
+ *     needs gh auth, not git push" rejections at the runner side).
+ *   - No tool detection (gh, jq, gitleaks, etc) — those are workflow
+ *     concerns, and the runner itself complains loudly. We do NOT
+ *     want preflight to grow into a general 'verify' clone.
+ */
+
+import path from "node:path";
+
+import { findShipRoot, readConfig } from "../config/io.mjs";
+import { resolveProvider } from "../agents/index.mjs";
+
+const EXIT_OK = 0;
+const EXIT_USAGE = 2;
+
+
+export async function preflightCommand(ctx, rest) {
+  const args = parseArgs(rest);
+  if (args.help) {
+    printHelp();
+    process.exit(EXIT_OK);
+  }
+
+  const cwd = args.cwd || process.cwd();
+  const root = findShipRoot(cwd);
+  // Without a Ship root we can still preflight the env — a missing
+  // ``.ship/config.yml`` is itself a missing-tool reason.
+  const config = root ? readConfig(cwd).config : null;
+
+  const env = readEnv();
+  const missingSecrets = [];
+  if (!env.apiToken) missingSecrets.push("SHIP_API_TOKEN");
+  if (!env.workspaceId) missingSecrets.push("SHIP_WORKSPACE_ID");
+  if (!env.apiBase) missingSecrets.push("SHIP_API_BASE");
+
+  // Provider-specific secrets only when we know which provider the
+  // workflow will resolve to. ``args.routine`` / ``args.specialist``
+  // is optional — when absent we report the workspace-default
+  // provider (typically ``cursor``).
+  const provider = config
+    ? resolveProvider(config, args.routine || args.specialist)
+    : "cursor";
+  if (provider === "cursor" && !env.cursorKey) {
+    missingSecrets.push("CURSOR_API_KEY");
+  }
+
+  // Role-side denial surfacing. We don't *enforce* the deny list
+  // here — that's the runner's job once an agent runtime ships
+  // tool-execution metadata Ship can intercept. Preflight just
+  // reports the list so the workflow can pre-empt unsupported
+  // combinations (and so `verify` can audit drift between the
+  // Ship default and the workspace override).
+  let deniedTools = [];
+  if (env.apiToken && env.apiBase && env.workspaceId && (args.routine || args.specialist)) {
+    const slug = args.specialist || resolveSpecialistFromRoutine(config, args.routine);
+    if (slug) {
+      try {
+        const role = await fetchResolvedRole({
+          apiBase: env.apiBase,
+          apiToken: env.apiToken,
+          workspaceId: env.workspaceId,
+          slug,
+        });
+        deniedTools = Array.isArray(role?.denied_tools) ? role.denied_tools : [];
+      } catch (err) {
+        // Role-resolve failures degrade — preflight stays useful for
+        // the secret-check half even when the API is unreachable.
+        if (!ctx.json && !args.json) {
+          console.error(
+            `warn: agent-role resolve failed (${err instanceof Error ? err.message : err}); deny-list unverified.`,
+          );
+        }
+      }
+    }
+  }
+
+  const ready = missingSecrets.length === 0;
+  const result = {
+    ready,
+    provider,
+    missing_secrets: missingSecrets,
+    denied_tools: deniedTools,
+    routine: args.routine || null,
+    specialist: args.specialist || null,
+  };
+
+  if (ctx.json || args.json) {
+    console.log(JSON.stringify(result, null, 2));
+    process.exit(EXIT_OK);
+  }
+
+  if (!ready) {
+    console.error(`Ship preflight: NOT READY — missing ${missingSecrets.join(", ")}`);
+  } else {
+    console.log(`Ship preflight: ready (${provider}${deniedTools.length ? `, deny ${deniedTools.length}` : ""})`);
+  }
+  process.exit(EXIT_OK);
+}
+
+
+function parseArgs(rest) {
+  const out = {
+    routine: null,
+    specialist: null,
+    cwd: null,
+    json: false,
+    help: false,
+  };
+  const copy = [...rest];
+  while (copy.length) {
+    const a = copy[0];
+    if (a === "--help" || a === "-h") { out.help = true; copy.shift(); continue; }
+    if (a === "--json") { out.json = true; copy.shift(); continue; }
+    if (a === "--routine" && copy[1] !== undefined) { out.routine = copy[1]; copy.splice(0, 2); continue; }
+    if (a === "--specialist" && copy[1] !== undefined) { out.specialist = copy[1]; copy.splice(0, 2); continue; }
+    if (a === "--cwd" && copy[1] !== undefined) { out.cwd = path.resolve(copy[1]); copy.splice(0, 2); continue; }
+    console.error(`unknown argument: ${a}`);
+    process.exit(EXIT_USAGE);
+  }
+  return out;
+}
+
+
+function printHelp() {
+  console.log(`shipctl preflight — verify the env + role contract before launching the runner.
+
+USAGE
+  shipctl preflight [--routine <id> | --specialist <slug>] [--json] [--cwd <dir>]
+
+OUTPUT
+  JSON shape:
+    {
+      "ready": true|false,
+      "provider": "cursor"|...,
+      "missing_secrets": ["SHIP_API_TOKEN", ...],
+      "denied_tools": ["git_commit", ...],   // resolved role's deny list
+      "routine": "...",
+      "specialist": "..."
+    }
+
+EXIT
+  0 always (so the workflow's case statement can branch on the JSON);
+  the workflow checks 'ready' to decide whether to skip the run.
+`);
+}
+
+
+function readEnv() {
+  return {
+    apiBase: stripSlash(
+      process.env.SHIP_API_BASE || process.env.SHIP_WORKSPACE_API_BASE || "",
+    ),
+    apiToken: process.env.SHIP_API_TOKEN || "",
+    workspaceId: process.env.SHIP_WORKSPACE_ID || "",
+    cursorKey: process.env.CURSOR_API_KEY || "",
+  };
+}
+
+
+function stripSlash(s) {
+  return s.replace(/\/+$/, "");
+}
+
+
+function resolveSpecialistFromRoutine(config, routineId) {
+  if (!routineId || !config) return null;
+  const routine = config?.process?.routines?.[routineId] || config?.routines?.[routineId];
+  if (!routine || typeof routine !== "object") return null;
+  const direct = typeof routine.specialist === "string" ? routine.specialist : null;
+  if (direct) return direct;
+  const nested = typeof routine.specialist?.id === "string" ? routine.specialist.id : null;
+  if (nested) return nested;
+  // Legacy ``pattern: role-X`` carries the slug as ``X``.
+  const pattern = typeof routine.pattern === "string" ? routine.pattern : null;
+  if (pattern && pattern.startsWith("role-")) return pattern.slice("role-".length);
+  return null;
+}
+
+
+async function fetchResolvedRole({ apiBase, apiToken, workspaceId, slug }) {
+  const url = `${apiBase}/v1/workspaces/${encodeURIComponent(workspaceId)}/agent-roles/${encodeURIComponent(slug)}/resolve`;
+  const res = await fetch(url, {
+    headers: {
+      Accept: "application/json",
+      Authorization: `Bearer ${apiToken}`,
+    },
+  });
+  if (!res.ok) {
+    throw new Error(`agent-roles resolve ${res.status}`);
+  }
+  return res.json();
+}