@openwop/cli 0.18.2 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # OpenWOP CLI
 
-The OpenWOP CLI is the local control plane for the [OpenWOP](https://github.com/openwop/openwop) demo app (`apps/workflow-engine`, live at [app.openwop.dev](https://app.openwop.dev)) and a lightweight client for any OpenWOP-compatible host.
+The OpenWOP CLI is the local control plane for the [OpenWOP](https://github.com/openwop/openwop) reference app ([`openwop/openwop-app`](https://github.com/openwop/openwop-app), live at [app.openwop.dev](https://app.openwop.dev)) and a lightweight client for any OpenWOP-compatible host.
 
 This is the standalone home of the `@openwop/cli` package; it ships independently of the [`openwop/openwop`](https://github.com/openwop/openwop) spec corpus.
 
@@ -12,16 +12,36 @@ The CLI is a host-agnostic **control plane**: every group drives one protocol su
 |---|---|
 | **Setup & health** | `onboard` · `doctor` · `demo` · `health` · `capabilities` · `config` · `completion` · `upgrade` |
 | **Run lifecycle** | `runs` · `chat` · `interrupts` · `workflows` · `catalog` · `media` |
-| **Agents & orchestration** | `agents` · `roster` · `org-chart` · `kanban` · `workforces` (`fleet`) |
+| **Agents & orchestration** | `agents` · `roster` · `org-chart` · `kanban` (`boards`) · `workforces` (`fleet`) · `agent-profile` · `agent-packs` · `agent-allowlists` · `agent-ops` · `evals` · `twin` · `reviews` |
 | **Governance & safety** | `approvals` · `governance` (`policy`) · `consent` · `toggles` |
-| **Identity & access** | `orgs` · `users` · `profiles` · `auth` (`sso`) |
+| **Identity & access** | `orgs` (`org`) · `workspaces` · `users` · `profiles` · `auth` (`sso`) |
 | **Extensibility & connections** | `packs` · `mcp` · `connections` (`conn`) · `providers` · `byok` |
 | **Memory & workspace** | `memory` · `workspace` · `prompts` |
 | **Automation & messaging** | `cron` · `webhooks` · `messaging` · `relay` · `notifications` · `notify` |
 | **Observability & admin** | `analytics` (`usage`) · `account` · `admin` · `brand` · `conformance` |
-| **Product surfaces** | `crm` · `csm` · `comments` · `sharing` · `forms` · `email` · `chat-widget` · `marketplace` · `kb` · `cms` · `documents` · `projects` |
+| **Product surfaces** | `crm` · `csm` · `comments` · `sharing` · `forms` · `email` · `chat-widget` · `marketplace` · `kb` · `cms` · `documents` · `projects` · `strategy` · `advisors` · `campaigns-orchestration` · `notebooks` · `podcasts` · `priority-matrix` |
+| **Protocol surfaces (RFC)** | `a2a` · `triggers` · `goals` · `proposals` · `export` / `import` |
 
-> **Recent sprint (`[Unreleased]`, slated for `0.3.0`):** 11 new groups + a `cron enable/disable` extension surfaced the host's governance/safety, identity, extensibility, orchestration, and observability surfaces — `approvals`, `governance`, `consent`, `toggles`, `users`, `profiles`, `auth`, `mcp`, `connections`, `workforces`, `analytics`. See [`CHANGELOG.md`](./CHANGELOG.md) for the per-group detail.
+> **`0.18.x`:** the catalog now covers the full app feature surface — the agent
+> platform (`agent-profile`, `agent-packs`, `agent-allowlists`, `agent-ops`,
+> `evals`, `twin`, `reviews`), workspace tenancy (`workspaces`), and the product
+> surfaces (`strategy`, `advisors`, `campaigns-orchestration`, `notebooks`,
+> `podcasts`, `priority-matrix`) — alongside the protocol RFC surfaces (`a2a`,
+> `triggers`, `goals`, `proposals`, `export`/`import`). See [`CHANGELOG.md`](./CHANGELOG.md)
+> for the per-group detail.
+
+## Protocol version support (v2 and v1)
+
+The CLI speaks the **OpenWOP wire directly** — no SDK dependency — and negotiates the protocol major once per invocation (`src/protocol.ts`, per `spec/v2/core/versioning.md` §1.5):
+
+- It reads `/.well-known/openwop` and selects the **highest major it implements that the host advertises** in `protocolVersions[]` — 2 when the host lists any `2.x`, otherwise 1.
+- Under major 2, every request for an operation named in `spec/v2/path-manifest.json` goes to the **unversioned path with `OpenWOP-Version: 2.0`** (`/v1/runs` → `/runs`). Host-proprietary routes the manifest does not name — the demo backend's `/v1/host/sample/*` — are sent exactly as written; they have no v2 home yet (`versioning.md` §5).
+- Under major 1 nothing changes: `/v1/…` paths, header-less, the v1 default the overlap guarantees.
+- `OPENWOP_PROTOCOL_MAJOR=1` or `=2` pins the major without probing discovery.
+
+`openwop doctor`'s `protocol` row reports `protocolVersions`, `preferredVersion`, and the major this process selected; it fails only when the host advertises neither major the CLI implements.
+
+The pre-1.0 `0.18.x` line was frozen v1-only; that decision was reversed with 1.0.0 (CHANGELOG). The frozen line stays on branch `cli-v1-frozen` for anyone who needs a client that never sends `OpenWOP-Version`.
 
 ## Install
 

package/dist/cli.js

@@ -967,14 +967,105 @@ function project(root, name, relativeDir) {
 // src/sse.ts
 import { createInterface as createInterface2 } from "node:readline";
 
+// src/protocol.ts
+var CLI_PROTOCOL_MAJORS = [2, 1];
+var V2_PATH_TEMPLATES = [
+  "/agents",
+  "/agents/org-chart",
+  "/agents/org-chart/{departmentId}",
+  "/agents/roster",
+  "/agents/roster/{rosterId}",
+  "/agents/{agentId}",
+  "/agents/{agentId}/deployments",
+  "/audit/verify",
+  "/content/pages",
+  "/content/pages/{pageId}/sections/{sectionId}",
+  "/content/pages/{slug}",
+  "/content/settings",
+  "/host/effect-seams",
+  "/host/events",
+  "/interrupts/{token}",
+  "/prompts",
+  "/prompts/{templateId}",
+  "/prompts:render",
+  "/runs",
+  "/runs/{runId}",
+  "/runs/{runId}/ancestry",
+  "/runs/{runId}/annotations",
+  "/runs/{runId}/artifacts/{artifactId}",
+  "/runs/{runId}/cancel",
+  "/runs/{runId}/compensation",
+  "/runs/{runId}/effects",
+  "/runs/{runId}/eval-summary",
+  "/runs/{runId}/events",
+  "/runs/{runId}/events/poll",
+  "/runs/{runId}/interrupts/{nodeId}",
+  "/runs/{runId}:diff",
+  "/runs/{runId}:fork",
+  "/runs/{runId}:pause",
+  "/runs/{runId}:resume",
+  "/runs:bulk-cancel",
+  "/tools",
+  "/tools/{toolId}",
+  "/trigger-subscriptions",
+  "/webhooks",
+  "/webhooks/{webhookId}",
+  "/workflows/{workflowId}"
+];
+var V2_MATCHERS = V2_PATH_TEMPLATES.map(
+  (t) => new RegExp(`^${t.replace(/[.:]/g, "\\$&").replace(/\{[A-Za-z]+\}/g, "[^/]+")}$`)
+);
+function v2Twin(path) {
+  const q = path.indexOf("?");
+  const bare = q === -1 ? path : path.slice(0, q);
+  const query = q === -1 ? "" : path.slice(q);
+  if (!bare.startsWith("/v1/")) return null;
+  const unversioned = bare.slice("/v1".length);
+  return V2_MATCHERS.some((m) => m.test(unversioned)) ? `${unversioned}${query}` : null;
+}
+function selectMajor(protocolVersions) {
+  const advertised = Array.isArray(protocolVersions) ? protocolVersions.filter((v) => typeof v === "string") : [];
+  for (const major of CLI_PROTOCOL_MAJORS) {
+    if (advertised.some((v) => v.startsWith(`${major}.`))) return major;
+  }
+  return 1;
+}
+async function negotiateMajor(ctx) {
+  if (ctx.protocolMajor !== void 0) return ctx.protocolMajor;
+  const pinned = ctx.env?.OPENWOP_PROTOCOL_MAJOR;
+  if (pinned === "1" || pinned === "2") {
+    ctx.protocolMajor = Number(pinned);
+    return ctx.protocolMajor;
+  }
+  let major = 1;
+  try {
+    const url = new URL(".well-known/openwop", ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
+    const res = await ctx.fetchImpl(url, { method: "GET", headers: { accept: "application/json" } });
+    if (res.ok) {
+      const doc = JSON.parse(await res.text());
+      major = selectMajor(doc?.protocolVersions);
+    }
+  } catch {
+  }
+  ctx.protocolMajor = major;
+  return major;
+}
+async function resolveRequest(ctx, path, headers) {
+  const major = await negotiateMajor(ctx);
+  if (major !== 2) return { path, headers };
+  const twin = v2Twin(path);
+  if (twin === null) return { path, headers };
+  return { path: twin, headers: { ...headers, "openwop-version": "2.0" } };
+}
+
 // src/api.ts
-async function requestJson(ctx, path, options = {}) {
-  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
-  const headers = {
+async function requestJson(ctx, requestedPath, options = {}) {
+  const { path, headers } = await resolveRequest(ctx, requestedPath, {
     accept: "application/json",
     ...options.body !== void 0 ? { "content-type": "application/json" } : {},
     ...options.headers ?? {}
-  };
+  });
+  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
   if (options.auth !== false && ctx.apiKey) {
     headers.authorization = `Bearer ${ctx.apiKey}`;
   }
@@ -1045,8 +1136,8 @@ async function streamRunEvents(ctx, runId, { onEvent, useStream = true, timeoutM
   await streamViaPoll(ctx, runId, onEvent, timeoutMs);
 }
 async function streamViaSse(ctx, runId, onEvent) {
-  const url = new URL(`/v1/runs/${encodeURIComponent(runId)}/events`, ctx.baseUrl);
-  const headers = { accept: "text/event-stream" };
+  const { path, headers } = await resolveRequest(ctx, `/v1/runs/${encodeURIComponent(runId)}/events`, { accept: "text/event-stream" });
+  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
   if (ctx.apiKey) headers.authorization = `Bearer ${ctx.apiKey}`;
   const res = await ctx.fetchImpl(url, { method: "GET", headers });
   if (!res.ok) throw new HttpError(`HTTP ${res.status}`, res.status, null);
@@ -9291,6 +9382,16 @@ async function runDoctor(ctx, argv) {
   const health = await probeEndpoint(ctx, "/health");
   if (health.ok) checks.push(ok("demo health", `${ctx.baseUrl}/health responded`));
   else checks.push(warn("demo health", `demo is not reachable at ${ctx.baseUrl} (${health.message})`));
+  const discovery = await safeRequest(ctx, "/.well-known/openwop", { auth: false });
+  const versions = discovery?.ok ? discovery.body?.protocolVersions : void 0;
+  if (Array.isArray(versions) && versions.length > 0) {
+    const advertised = versions.filter((v) => typeof v === "string");
+    const preferred = typeof discovery.body?.preferredVersion === "string" ? discovery.body.preferredVersion : "?";
+    const selected = await negotiateMajor(ctx);
+    const detail = `protocolVersions ${advertised.join(", ")}; preferredVersion ${preferred}; CLI speaks major ${selected}`;
+    if (advertised.some((v) => v.startsWith(`${selected}.`))) checks.push(ok("protocol", detail));
+    else checks.push(fail("protocol", `${detail} \u2014 host advertises neither major this CLI implements; see README \xA7"Protocol version support"`));
+  }
   const daemon = await safeRequest(ctx, "/v1/host/sample/daemon-status");
   if (daemon.ok && daemon.body) {
     const b = daemon.body;

package/dist/openwop.js

@@ -968,14 +968,105 @@ function project(root, name, relativeDir) {
 // src/sse.ts
 import { createInterface as createInterface2 } from "node:readline";
 
+// src/protocol.ts
+var CLI_PROTOCOL_MAJORS = [2, 1];
+var V2_PATH_TEMPLATES = [
+  "/agents",
+  "/agents/org-chart",
+  "/agents/org-chart/{departmentId}",
+  "/agents/roster",
+  "/agents/roster/{rosterId}",
+  "/agents/{agentId}",
+  "/agents/{agentId}/deployments",
+  "/audit/verify",
+  "/content/pages",
+  "/content/pages/{pageId}/sections/{sectionId}",
+  "/content/pages/{slug}",
+  "/content/settings",
+  "/host/effect-seams",
+  "/host/events",
+  "/interrupts/{token}",
+  "/prompts",
+  "/prompts/{templateId}",
+  "/prompts:render",
+  "/runs",
+  "/runs/{runId}",
+  "/runs/{runId}/ancestry",
+  "/runs/{runId}/annotations",
+  "/runs/{runId}/artifacts/{artifactId}",
+  "/runs/{runId}/cancel",
+  "/runs/{runId}/compensation",
+  "/runs/{runId}/effects",
+  "/runs/{runId}/eval-summary",
+  "/runs/{runId}/events",
+  "/runs/{runId}/events/poll",
+  "/runs/{runId}/interrupts/{nodeId}",
+  "/runs/{runId}:diff",
+  "/runs/{runId}:fork",
+  "/runs/{runId}:pause",
+  "/runs/{runId}:resume",
+  "/runs:bulk-cancel",
+  "/tools",
+  "/tools/{toolId}",
+  "/trigger-subscriptions",
+  "/webhooks",
+  "/webhooks/{webhookId}",
+  "/workflows/{workflowId}"
+];
+var V2_MATCHERS = V2_PATH_TEMPLATES.map(
+  (t) => new RegExp(`^${t.replace(/[.:]/g, "\\$&").replace(/\{[A-Za-z]+\}/g, "[^/]+")}$`)
+);
+function v2Twin(path) {
+  const q = path.indexOf("?");
+  const bare = q === -1 ? path : path.slice(0, q);
+  const query = q === -1 ? "" : path.slice(q);
+  if (!bare.startsWith("/v1/")) return null;
+  const unversioned = bare.slice("/v1".length);
+  return V2_MATCHERS.some((m) => m.test(unversioned)) ? `${unversioned}${query}` : null;
+}
+function selectMajor(protocolVersions) {
+  const advertised = Array.isArray(protocolVersions) ? protocolVersions.filter((v) => typeof v === "string") : [];
+  for (const major of CLI_PROTOCOL_MAJORS) {
+    if (advertised.some((v) => v.startsWith(`${major}.`))) return major;
+  }
+  return 1;
+}
+async function negotiateMajor(ctx) {
+  if (ctx.protocolMajor !== void 0) return ctx.protocolMajor;
+  const pinned = ctx.env?.OPENWOP_PROTOCOL_MAJOR;
+  if (pinned === "1" || pinned === "2") {
+    ctx.protocolMajor = Number(pinned);
+    return ctx.protocolMajor;
+  }
+  let major = 1;
+  try {
+    const url = new URL(".well-known/openwop", ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
+    const res = await ctx.fetchImpl(url, { method: "GET", headers: { accept: "application/json" } });
+    if (res.ok) {
+      const doc = JSON.parse(await res.text());
+      major = selectMajor(doc?.protocolVersions);
+    }
+  } catch {
+  }
+  ctx.protocolMajor = major;
+  return major;
+}
+async function resolveRequest(ctx, path, headers) {
+  const major = await negotiateMajor(ctx);
+  if (major !== 2) return { path, headers };
+  const twin = v2Twin(path);
+  if (twin === null) return { path, headers };
+  return { path: twin, headers: { ...headers, "openwop-version": "2.0" } };
+}
+
 // src/api.ts
-async function requestJson(ctx, path, options = {}) {
-  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
-  const headers = {
+async function requestJson(ctx, requestedPath, options = {}) {
+  const { path, headers } = await resolveRequest(ctx, requestedPath, {
     accept: "application/json",
     ...options.body !== void 0 ? { "content-type": "application/json" } : {},
     ...options.headers ?? {}
-  };
+  });
+  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
   if (options.auth !== false && ctx.apiKey) {
     headers.authorization = `Bearer ${ctx.apiKey}`;
   }
@@ -1046,8 +1137,8 @@ async function streamRunEvents(ctx, runId, { onEvent, useStream = true, timeoutM
   await streamViaPoll(ctx, runId, onEvent, timeoutMs);
 }
 async function streamViaSse(ctx, runId, onEvent) {
-  const url = new URL(`/v1/runs/${encodeURIComponent(runId)}/events`, ctx.baseUrl);
-  const headers = { accept: "text/event-stream" };
+  const { path, headers } = await resolveRequest(ctx, `/v1/runs/${encodeURIComponent(runId)}/events`, { accept: "text/event-stream" });
+  const url = new URL(path.replace(/^\//, ""), ctx.baseUrl.endsWith("/") ? ctx.baseUrl : `${ctx.baseUrl}/`);
   if (ctx.apiKey) headers.authorization = `Bearer ${ctx.apiKey}`;
   const res = await ctx.fetchImpl(url, { method: "GET", headers });
   if (!res.ok) throw new HttpError(`HTTP ${res.status}`, res.status, null);
@@ -9292,6 +9383,16 @@ async function runDoctor(ctx, argv) {
   const health = await probeEndpoint(ctx, "/health");
   if (health.ok) checks.push(ok("demo health", `${ctx.baseUrl}/health responded`));
   else checks.push(warn("demo health", `demo is not reachable at ${ctx.baseUrl} (${health.message})`));
+  const discovery = await safeRequest(ctx, "/.well-known/openwop", { auth: false });
+  const versions = discovery?.ok ? discovery.body?.protocolVersions : void 0;
+  if (Array.isArray(versions) && versions.length > 0) {
+    const advertised = versions.filter((v) => typeof v === "string");
+    const preferred = typeof discovery.body?.preferredVersion === "string" ? discovery.body.preferredVersion : "?";
+    const selected = await negotiateMajor(ctx);
+    const detail = `protocolVersions ${advertised.join(", ")}; preferredVersion ${preferred}; CLI speaks major ${selected}`;
+    if (advertised.some((v) => v.startsWith(`${selected}.`))) checks.push(ok("protocol", detail));
+    else checks.push(fail("protocol", `${detail} \u2014 host advertises neither major this CLI implements; see README \xA7"Protocol version support"`));
+  }
   const daemon = await safeRequest(ctx, "/v1/host/sample/daemon-status");
   if (daemon.ok && daemon.body) {
     const b = daemon.body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwop/cli",
-  "version": "0.18.2",
+  "version": "1.0.0",
   "description": "OpenWOP CLI for operating the workflow-engine demo app and OpenWOP-compatible hosts.",
   "license": "Apache-2.0",
   "type": "module",