@openwop/openwop 1.9.0 → 2.0.0

package/dist/client.js

@@ -1,19 +1,35 @@
 /**
- * OpenwopClient — typed HTTP client for the openwop REST surface.
+ * OpenwopClient — typed HTTP client for the OpenWOP v2 REST surface.
  *
- * Hand-authored. Each method maps 1:1 to a documented endpoint in
- * ../../api/openapi.yaml. Request/response types live in ./types.ts.
+ * Hand-authored. Each method maps 1:1 to an operation in
+ * `spec/v2/path-manifest.json` (generated from `api/v2/openapi.yaml`):
+ * bare origin, unversioned path keys, negotiation by the `OpenWOP-Version`
+ * request header (RFC 0172 §A). Request/response types live in ./types.ts;
+ * the error-code union in ./generated.ts.
  *
- * Auth: a single bearer-style API key, supplied at construction. See
- * ../../auth.md for credential format.
+ * Auth: a single bearer-style API key, supplied at construction.
  */
-import { streamEvents } from './sse.js';
+import { streamEvents, streamHostEvents } from './sse.js';
 import { WopError, } from './types.js';
+/** The protocol major this SDK implements; the default for {@link OpenwopClientOptions.major}. */
+export const SDK_PROTOCOL_MAJOR = 2;
+/** Renders the `OpenWOP-Version` request value for a major: `<major>.0` (the OpenAPI grammar is `<major>.<minor>`). */
+export function protocolVersionHeader(major) {
+    if (!Number.isInteger(major) || major < 0) {
+        throw new TypeError(`OpenwopClient: major must be a non-negative integer (got ${String(major)})`);
+    }
+    return `${major}.0`;
+}
 export class OpenwopClient {
     #baseUrl;
     #apiKey;
     #fetch;
     #acceptLanguage;
+    #versionHeader;
+    /** The `OpenWOP-Version` value this client sends on every request. */
+    get protocolVersion() {
+        return this.#versionHeader;
+    }
     constructor(opts) {
         if (!opts.baseUrl)
             throw new TypeError('OpenwopClient: baseUrl is required');
@@ -23,121 +39,101 @@ export class OpenwopClient {
         this.#apiKey = opts.apiKey;
         this.#fetch = opts.fetch ?? fetch;
         this.#acceptLanguage = opts.acceptLanguage;
+        this.#versionHeader = protocolVersionHeader(opts.major ?? SDK_PROTOCOL_MAJOR);
     }
     // ── Discovery ────────────────────────────────────────────────────────
     discovery = {
+        /**
+         * `GET /.well-known/openwop` — one resource whose representation the
+         * `OpenWOP-Version` header selects (capabilities.md §1): with this
+         * client's major the host returns the closed v2 root.
+         */
         capabilities: () => this.#request({ method: 'GET', path: '/.well-known/openwop' }, false),
-        openapi: () => this.#request({ method: 'GET', path: '/v1/openapi.json' }, false),
+        /** `GET /openapi.json` — the self-describing OpenAPI 3.1 document. */
+        openapi: () => this.#request({ method: 'GET', path: '/openapi.json' }, false),
     };
     // ── Workflows ────────────────────────────────────────────────────────
     workflows = {
+        /** `GET /workflows/{workflowId}` */
         get: (workflowId) => this.#request({
             method: 'GET',
-            path: `/v1/workflows/${encodeURIComponent(workflowId)}`,
+            path: `/workflows/${encodeURIComponent(workflowId)}`,
         }),
     };
     // ── Runs ─────────────────────────────────────────────────────────────
     runs = {
+        /** `POST /runs` — the body is closed at the composition (runs.md §Create). */
         create: (body, opts = {}) => this.#request({
             method: 'POST',
-            path: '/v1/runs',
+            path: '/runs',
             body,
             headers: this.#mutationHeaders(opts),
         }),
+        /** `GET /runs/{runId}` — the snapshot (runs.md §Snapshot). */
         get: (runId) => this.#request({
             method: 'GET',
-            path: `/v1/runs/${encodeURIComponent(runId)}`,
+            path: `/runs/${encodeURIComponent(runId)}`,
         }),
-        /**
-         * Fetch the portable JSON diagnostic export for a single run per
-         * `spec/v1/debug-bundle.md`. The bundle's `redactionMode` reflects
-         * the host's advertised `capabilities.compliance.defaultMode`; the
-         * caller MUST treat masked/omitted/hashed fields as the
-         * spec-canonical value. The `truncated` + `truncatedReason` fields
-         * indicate the host hit its size cap.
-         *
-         * Returns `null` when the host doesn't advertise
-         * `capabilities.debugBundle.supported: true` (the endpoint returns
-         * 404 in that case per `debug-bundle.md` §"Authorization").
-         */
-        debugBundle: async (runId, opts = {}) => {
-            const params = new URLSearchParams();
-            if (opts.maxEvents !== undefined)
-                params.set('maxEvents', String(opts.maxEvents));
-            const query = params.toString();
-            const path = `/v1/runs/${encodeURIComponent(runId)}/debug-bundle${query ? `?${query}` : ''}`;
-            try {
-                return await this.#request({ method: 'GET', path });
-            }
-            catch (err) {
-                // Host doesn't advertise the capability → 404. Surface as null so callers
-                // can branch on capability discovery without try/catch.
-                if (err instanceof WopError && err.status === 404)
-                    return null;
-                throw err;
-            }
-        },
+        /** `POST /runs/{runId}/cancel` — `status` is `cancelling` or `cancelled`. */
         cancel: (runId, body = {}, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}/cancel`,
+            path: `/runs/${encodeURIComponent(runId)}/cancel`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
+        /** `POST /runs/{runId}:pause` — `409` when the run is not pausable. */
         pause: (runId, body = {}, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}:pause`,
+            path: `/runs/${encodeURIComponent(runId)}:pause`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
+        /** `POST /runs/{runId}:resume` — `409` when the run is not paused. */
         resume: (runId, body = {}, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}:resume`,
+            path: `/runs/${encodeURIComponent(runId)}:resume`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
         /**
-         * Bulk-cancel a set of in-flight runs in a single request per
-         * `rest-endpoints.md` §"POST /v1/runs:bulk-cancel" (closes R1).
-         * The top-level call returns 200 + per-id `results[]` whenever the
-         * request reaches the host; partial failures surface inside the
-         * array (each entry carries `ok: boolean` + optional `error`). Host-
-         * defined cap on `runIds[]` length (RECOMMENDED 100); over-cap
-         * returns `400 validation_error` with `details.maxRunIds`.
+         * `POST /runs:bulk-cancel` — `200 { results[] }` in request order even
+         * when every id failed; per-id authorization yields `ok: false` with
+         * `run_forbidden` in that entry, never a top-level `403` (runs.md §Cancel).
          */
         bulkCancel: (body, opts = {}) => this.#request({
             method: 'POST',
-            path: '/v1/runs:bulk-cancel',
+            path: '/runs:bulk-cancel',
             body,
             headers: this.#mutationHeaders(opts),
         }),
+        /** `POST /runs/{runId}:fork` — `mode: replay | branch` (runs.md §Fork; replay.md). */
         fork: (runId, body, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}:fork`,
+            path: `/runs/${encodeURIComponent(runId)}:fork`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
         /**
-         * RFC 0056 — record a non-blocking quality annotation (rating / correction
-         * / label / flag) on a run/event/node. Returns the persisted `Annotation`.
-         * Throws on non-2xx (`501` when the host doesn't advertise
-         * `capabilities.feedback.supported`).
+         * `POST /runs/{runId}/annotations` — a live notification, never a run
+         * event. Throws on non-2xx (`501` when the host doesn't advertise
+         * `feedback`).
          */
         createAnnotation: (runId, body, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}/annotations`,
+            path: `/runs/${encodeURIComponent(runId)}/annotations`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
         /**
-         * RFC 0056 — list a run's annotations (tenant-scoped). Returns `null` when
-         * the host doesn't advertise `capabilities.feedback` (404/501), so callers
-         * can branch on capability discovery without try/catch.
+         * `GET /runs/{runId}/annotations` — returns `null` when the host doesn't
+         * advertise `feedback` (404/501), so callers can branch on capability
+         * discovery without try/catch.
          */
         listAnnotations: async (runId) => {
             try {
                 const res = await this.#request({
                     method: 'GET',
-                    path: `/v1/runs/${encodeURIComponent(runId)}/annotations`,
+                    path: `/runs/${encodeURIComponent(runId)}/annotations`,
                 });
                 return res.annotations;
             }
@@ -148,21 +144,17 @@ export class OpenwopClient {
             }
         },
         /**
-         * RFC 0040 §C — fetch the run's immediate parent in the cross-host
-         * composition chain. Returns `parent: null` for top-level runs;
-         * `parent.wellKnownUrl` is set when the parent is on a different
-         * host, so callers walk the chain one hop at a time.
-         *
+         * `GET /runs/{runId}/ancestry` — the run's immediate parent in the
+         * cross-host composition chain; `parent: null` for top-level runs.
          * Returns `null` when the host doesn't advertise
-         * `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`
-         * (the endpoint returns 404 in that case per
-         * `spec/v1/multi-agent-execution.md` §"GET /v1/runs/{runId}/ancestry").
+         * `multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported`
+         * (the endpoint 404s).
          */
         ancestry: async (runId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/runs/${encodeURIComponent(runId)}/ancestry`,
+                    path: `/runs/${encodeURIComponent(runId)}/ancestry`,
                 });
             }
             catch (err) {
@@ -172,18 +164,15 @@ export class OpenwopClient {
             }
         },
         /**
-         * RFC 0054 — deterministic, replay-aware structured diff of two runs
-         * (typically a run and its `:fork`). Requires `runs:read` on BOTH
-         * `runId` and `against`. Returns `null` when the host doesn't
-         * implement the endpoint (404 per `spec/v1/rest-endpoints.md`
-         * §`GET /v1/runs/{runId}:diff`). `divergedAtSeq` is null + `eventDiffs`
-         * empty when the two logs are identical.
+         * `GET /runs/{runId}:diff?against=` — deterministic, replay-aware diff of
+         * two runs; requires `runs:read` on both. OPTIONAL surface: `null` on
+         * `404`. Identical logs yield `divergedAtSeq: null` + empty `eventDiffs`.
          */
         diff: async (runId, against) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
+                    path: `/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
                 });
             }
             catch (err) {
@@ -193,18 +182,15 @@ export class OpenwopClient {
             }
         },
         /**
-         * RFC 0081 §C — the `EvalSummary` scorecard for a terminal eval run (one
-         * started via `runs.create({ mode: 'eval', evalSuiteRef, agentId })`):
-         * aggregate + per-task scores, cost, latency, schema-validity, and
-         * redaction-safe safety findings. Returns `null` when the host doesn't
-         * advertise `capabilities.agents.evalSuite` or the run isn't an eval run
-         * (404). Throws `409` while the run is still in progress.
+         * `GET /runs/{runId}/eval-summary` — the `EvalSummary` for a terminal eval
+         * run. `null` on `404` (not an eval run, or `agents.evalSuite`
+         * unadvertised); throws `409` while the run is still in progress.
          */
         evalSummary: async (runId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/runs/${encodeURIComponent(runId)}/eval-summary`,
+                    path: `/runs/${encodeURIComponent(runId)}/eval-summary`,
                 });
             }
             catch (err) {
@@ -214,15 +200,14 @@ export class OpenwopClient {
             }
         },
         /**
-         * Read a run-produced artifact by id (`GET /v1/runs/{runId}/artifacts/{artifactId}`).
-         * The artifact body is implementation-defined per the host. Returns `null`
-         * on 404 (no such artifact, or the host doesn't store artifacts).
+         * `GET /runs/{runId}/artifacts/{artifactId}` — an implementation-defined
+         * JSON object. `null` on `404`.
          */
         getArtifact: async (runId, artifactId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
+                    path: `/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
                 });
             }
             catch (err) {
@@ -231,10 +216,51 @@ export class OpenwopClient {
                 throw err;
             }
         },
+        /**
+         * `GET /runs/{runId}/compensation` (RFC 0173 §C.1) — the compensation
+         * plan and attempts. Gated on `compensation`; `null` on `404`.
+         */
+        compensation: async (runId) => {
+            try {
+                return await this.#request({
+                    method: 'GET',
+                    path: `/runs/${encodeURIComponent(runId)}/compensation`,
+                });
+            }
+            catch (err) {
+                if (err instanceof WopError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        },
+        /**
+         * `GET /runs/{runId}/effects` (RFC 0173 §C.2) — the Layer-2 effect ledger,
+         * business-identity keyed. Gated on `idempotency`; `null` on `404`.
+         */
+        effects: async (runId) => {
+            try {
+                return await this.#request({
+                    method: 'GET',
+                    path: `/runs/${encodeURIComponent(runId)}/effects`,
+                });
+            }
+            catch (err) {
+                if (err instanceof WopError && err.status === 404)
+                    return null;
+                throw err;
+            }
+        },
+        /**
+         * `GET /runs/{runId}/events/poll` — the long-poll fallback (events.md
+         * §Poll). `afterSequence` returns events with `sequence > afterSequence`;
+         * omission means from the first event. The response's `lastSequence` is
+         * the highest sequence in the log (`-1` when empty) — feed it back as the
+         * next `afterSequence`.
+         */
         pollEvents: (runId, params = {}) => {
             const search = new URLSearchParams();
-            if (params.lastSequence !== undefined) {
-                search.set('lastSequence', String(params.lastSequence));
+            if (params.afterSequence !== undefined) {
+                search.set('afterSequence', String(params.afterSequence));
             }
             if (params.timeoutSeconds !== undefined) {
                 search.set('timeout', String(params.timeoutSeconds));
@@ -242,25 +268,38 @@ export class OpenwopClient {
             const qs = search.toString();
             return this.#request({
                 method: 'GET',
-                path: `/v1/runs/${encodeURIComponent(runId)}/events/poll${qs ? `?${qs}` : ''}`,
+                path: `/runs/${encodeURIComponent(runId)}/events/poll${qs ? `?${qs}` : ''}`,
             });
         },
         /**
-         * Async-iterable SSE consumer. The connection auto-closes when the
-         * server closes the stream (terminal run event); break out of the
-         * loop or call `signal.abort()` to terminate early.
+         * `GET /runs/{runId}/events` — async-iterable SSE consumer. The
+         * connection auto-closes after the run's terminal event; break out of
+         * the loop or call `signal.abort()` to terminate early.
+         */
+        events: (runId, opts = {}) => streamEvents(this.#streamContext(), runId, opts),
+    };
+    // ── Host ─────────────────────────────────────────────────────────────
+    host = {
+        /**
+         * `GET /host/effect-seams` (RFC 0173 §C) — every outbound effect seam
+         * replay suppression covers. Throws `401` when unauthenticated.
          */
-        events: (runId, opts = {}) => streamEvents({ baseUrl: this.#baseUrl, apiKey: this.#apiKey }, runId, opts),
+        effectSeams: () => this.#request({ method: 'GET', path: '/host/effect-seams' }),
+        /**
+         * `GET /host/events` — the `hostEvents` channel (heartbeat messages) as
+         * SSE; content-free of run data. A host MAY declare another address
+         * under `heartbeat.deliveryChannel` — pass it as `opts.path`.
+         */
+        events: (opts = {}) => streamHostEvents(this.#streamContext(), opts),
     };
     // ── Manifest-agent inventory (RFC 0072 §A) ───────────────────────────
-    // Read-only. Gated on `capabilities.agents.manifestRuntime`; both methods
-    // return `null` when the host doesn't advertise it (the endpoints 404).
-    // Dispatch is not here: a manifest agent runs as a `runs.create` whose
-    // workflow node pins it via `WorkflowNode.agent` (RFC 0072 §B).
+    // Read-only. Gated on `agents`; the methods return `null` when the host
+    // doesn't advertise it (the endpoints 404).
     agents = {
+        /** `GET /agents` */
         list: async () => {
             try {
-                return await this.#request({ method: 'GET', path: '/v1/agents' });
+                return await this.#request({ method: 'GET', path: '/agents' });
             }
             catch (err) {
                 if (err instanceof WopError && err.status === 404)
@@ -268,11 +307,12 @@ export class OpenwopClient {
                 throw err;
             }
         },
+        /** `GET /agents/{agentId}` */
         get: async (agentId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/agents/${encodeURIComponent(agentId)}`,
+                    path: `/agents/${encodeURIComponent(agentId)}`,
                 });
             }
             catch (err) {
@@ -281,17 +321,12 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0082 §C/§E — list a manifest agent's deployment records (per-(agentId,
-         * version) lifecycle state + channels + canary + rollback pointer). Returns
-         * `null` when the host doesn't advertise `capabilities.agents.deployment`
-         * (the endpoint 404s).
-         */
+        /** `GET /agents/{agentId}/deployments` (RFC 0082 §C/§E) — `null` when unadvertised. */
         listDeployments: async (agentId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+                    path: `/agents/${encodeURIComponent(agentId)}/deployments`,
                 });
             }
             catch (err) {
@@ -300,28 +335,17 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0082 §E — request a deployment state transition (promote / pause /
-         * deprecate / rollback / adjust-canary). The host authorizes fail-closed
-         * against the RFC 0049 `deploy:*` scope, runs any RFC 0051 approvalGate, and
-         * enforces RFC 0081 `requiredEval` before emitting `deployment.promoted`.
-         * Returns the updated deployment record. Throws on non-2xx (`403` fail-closed
-         * / `eval_gate_unmet`; `400` `no_active_deployment` / unsupported state).
-         */
+        /** `POST /agents/{agentId}/deployments` (RFC 0082 §E) — a deployment state transition. */
         transitionDeployment: (agentId, body, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+            path: `/agents/${encodeURIComponent(agentId)}/deployments`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
-        /**
-         * RFC 0086 §B — list the standing agent roster (named instances + their
-         * workflow portfolios) visible to the caller. Returns `null` when the host
-         * doesn't advertise `capabilities.agents.roster` (the endpoint 404s).
-         */
+        /** `GET /agents/roster` (RFC 0086 §B) — `null` when unadvertised. */
         listRoster: async () => {
             try {
-                return await this.#request({ method: 'GET', path: '/v1/agents/roster' });
+                return await this.#request({ method: 'GET', path: '/agents/roster' });
             }
             catch (err) {
                 if (err instanceof WopError && err.status === 404)
@@ -329,15 +353,12 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0086 §B — return one standing roster entry. Returns `null` on 404
-         * (no such entry, cross-tenant, or the capability is unadvertised).
-         */
+        /** `GET /agents/roster/{rosterId}` (RFC 0086 §B) — `null` on `404`. */
         getRosterEntry: async (rosterId) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/agents/roster/${encodeURIComponent(rosterId)}`,
+                    path: `/agents/roster/${encodeURIComponent(rosterId)}`,
                 });
             }
             catch (err) {
@@ -346,14 +367,10 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0087 §C — return the caller's agent org-chart (departments + roles +
-         * `reportsTo` over roster members; descriptive — confers no authority).
-         * Returns `null` when the host doesn't advertise `capabilities.agents.orgChart`.
-         */
+        /** `GET /agents/org-chart` (RFC 0087 §C) — `null` when unadvertised. */
         getOrgChart: async () => {
             try {
-                return await this.#request({ method: 'GET', path: '/v1/agents/org-chart' });
+                return await this.#request({ method: 'GET', path: '/agents/org-chart' });
             }
             catch (err) {
                 if (err instanceof WopError && err.status === 404)
@@ -361,18 +378,13 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0087 §D — one department's subtree + responsibility roll-up (the
-         * union of its members' RFC 0086 portfolios). `recursive: false` scopes the
-         * roll-up to direct members. Returns `null` on 404 (unknown/cross-tenant
-         * department, or the capability is unadvertised).
-         */
+        /** `GET /agents/org-chart/{departmentId}` (RFC 0087 §D) — `null` on `404`. */
         getOrgChartDepartment: async (departmentId, opts = {}) => {
             const qs = opts.recursive === false ? '?recursive=false' : '';
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
+                    path: `/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
                 });
             }
             catch (err) {
@@ -382,18 +394,12 @@ export class OpenwopClient {
             }
         },
     };
-    // RFC 0078 — portable tool catalog (spec/v1/tool-catalog.md). The host
-    // projects every node-pack / workflow / mcp / connector / host-extension
-    // tool visible to the caller onto a uniform `ToolDescriptor`.
+    // ── RFC 0078 — portable tool catalog (gated on `toolCatalog`) ─────────
     tools = {
-        /**
-         * RFC 0078 §B — list the portable `ToolDescriptor`s visible to the caller.
-         * Returns `null` when the host doesn't advertise `capabilities.toolCatalog`
-         * (the endpoint 404s), so callers can branch on capability discovery.
-         */
+        /** `GET /tools` — `null` when the host doesn't advertise `toolCatalog`. */
         list: async () => {
             try {
-                return await this.#request({ method: 'GET', path: '/v1/tools' });
+                return await this.#request({ method: 'GET', path: '/tools' });
             }
             catch (err) {
                 if (err instanceof WopError && err.status === 404)
@@ -401,17 +407,12 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0112 — list the `CompactToolDescriptor`s via `GET /v1/tools?view=compact`
-         * when the host advertises `capabilities.toolCatalog.compactView`. Unwraps the
-         * `{ tools: CompactToolDescriptor[] }` envelope. Returns `null` when the host
-         * doesn't advertise the catalog (the endpoint 404s).
-         */
+        /** `GET /tools?view=compact` (RFC 0112) — unwraps `{ tools }`; `null` when unadvertised. */
         listCompact: async () => {
             try {
                 const res = await this.#request({
                     method: 'GET',
-                    path: '/v1/tools?view=compact',
+                    path: '/tools?view=compact',
                 });
                 return res.tools ?? [];
             }
@@ -421,18 +422,13 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /**
-         * RFC 0078 §B — return one `ToolDescriptor` by its stable `toolId`. Returns
-         * `null` on 404 (no such tool, or the capability is unadvertised). Pass
-         * `{ view: 'compact' }` (RFC 0112) to receive the `CompactToolDescriptor`
-         * projection instead.
-         */
+        /** `GET /tools/{toolId}` — `null` on `404`; `{ view: 'compact' }` for the compact projection. */
         get: async (toolId, opts = {}) => {
             const query = opts.view === 'compact' ? '?view=compact' : '';
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/tools/${encodeURIComponent(toolId)}${query}`,
+                    path: `/tools/${encodeURIComponent(toolId)}${query}`,
                 });
             }
             catch (err) {
@@ -442,136 +438,57 @@ export class OpenwopClient {
             }
         },
     };
-    // ── User-authored agents (sample-extension; non-normative) ───────────
-    // Backs the workflow-engine sample app's Agents tab. Pack-installed
-    // agents come through the `.agents` inventory above (RFC 0072 §A).
-    // These methods wrap the `POST/DELETE /v1/host/sample/agents` +
-    // `GET/POST /v1/host/sample/registry/agent-packs` host extensions.
-    // Returns `null` on 404 (capability absent — matches the `.agents`
-    // surface pattern); throws on other failures.
-    userAgents = {
-        create: async (body, opts = {}) => {
-            return await this.#request({
-                method: 'POST',
-                path: '/v1/host/sample/agents',
-                body,
-                ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
-            });
-        },
-        delete: async (agentId) => {
-            try {
-                await this.#request({
-                    method: 'DELETE',
-                    path: `/v1/host/sample/agents/${encodeURIComponent(agentId)}`,
-                });
-                return true;
-            }
-            catch (err) {
-                if (err instanceof WopError && err.status === 404)
-                    return false;
-                throw err;
-            }
-        },
-        listAvailablePacks: async () => {
-            try {
-                return await this.#request({
-                    method: 'GET',
-                    path: '/v1/host/sample/registry/agent-packs',
-                });
-            }
-            catch (err) {
-                if (err instanceof WopError && err.status === 404)
-                    return null;
-                throw err;
-            }
-        },
-        installPack: async (body) => {
-            return await this.#request({
-                method: 'POST',
-                path: '/v1/host/sample/registry/agent-packs/install',
-                body,
-            });
-        },
-    };
     // ── HITL interrupts (run-scoped + signed-token) ──────────────────────
     interrupts = {
+        /** `POST /runs/{runId}/interrupts/{nodeId}` */
         resolveByRun: (runId, nodeId, body, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(nodeId)}`,
+            path: `/runs/${encodeURIComponent(runId)}/interrupts/${encodeURIComponent(nodeId)}`,
             body,
             headers: this.#mutationHeaders(opts),
         }),
         /**
-         * Inspect an interrupt via signed token — useful for showing the
-         * interrupt's `kind`, `data`, and `resumeSchema` to a downstream
-         * UI before the user resolves. Token is the auth, no API key
-         * required (signed-token endpoints intentionally bypass bearer
-         * auth so external systems can resolve without openwop credentials).
+         * `GET /interrupts/{token}` — inspect via signed token. The token is the
+         * auth; no API key is sent (signed-token endpoints bypass bearer auth so
+         * external systems can resolve without openwop credentials).
          */
         inspectByToken: (token) => this.#request({
             method: 'GET',
-            path: `/v1/interrupts/${encodeURIComponent(token)}`,
+            path: `/interrupts/${encodeURIComponent(token)}`,
         }, false),
-        /**
-         * Resolve an interrupt via signed token — used by external
-         * systems (calendar webhooks, payment confirmations) that the
-         * engine handed a callback URL at suspension time.
-         */
+        /** `POST /interrupts/{token}` — resolve via signed token. */
         resolveByToken: (token, body, opts = {}) => this.#request({
             method: 'POST',
-            path: `/v1/interrupts/${encodeURIComponent(token)}`,
+            path: `/interrupts/${encodeURIComponent(token)}`,
             body,
             headers: this.#mutationHeaders(opts),
         }, false),
     };
-    // ── Webhook subscriptions (per spec/v1/webhooks.md) ─────────────────────
+    // ── Webhook subscriptions (webhooks.md; gated on `webhooks`) ─────────
     webhooks = {
         /**
-         * Register a webhook subscription. Server signs deliveries with
-         * HMAC-SHA256 over `${timestamp}.${rawBody}` using the
-         * registration-time secret per `spec/v1/webhooks.md` §"Signature
-         * recipe". The secret is returned ONCE in the response — store it
-         * server-side for verification; the host cannot recover it.
+         * `POST /webhooks` — `{ url, events[], secret?, tags? }`; `url` MUST be
+         * `https://`. Deliveries are signed HMAC-SHA256 over
+         * `${timestamp}.${rawBody}` under the `OpenWOP-*` header family (verify
+         * with `@openwop/openwop/webhooks`).
          */
         register: (body, opts = {}) => this.#request({
             method: 'POST',
-            path: '/v1/webhooks',
+            path: '/webhooks',
             body,
             headers: this.#mutationHeaders(opts),
         }),
-        /**
-         * Unregister a webhook subscription. Returns void on success;
-         * throws `WopError` with `subscription_not_found` on unknown
-         * subscriptionId.
-         */
-        unregister: async (subscriptionId) => {
+        /** `DELETE /webhooks/{webhookId}` — `204`; throws `404` when unknown, `403` outside the tenant. */
+        unregister: async (webhookId) => {
             await this.#request({
                 method: 'DELETE',
-                path: `/v1/webhooks/${encodeURIComponent(subscriptionId)}`,
+                path: `/webhooks/${encodeURIComponent(webhookId)}`,
             });
         },
     };
-    // ── Prompt library (RFC 0028; gated on capabilities.prompts.*) ──
-    //
-    // Read endpoints (list, get, render) gate on
-    // `capabilities.prompts.endpointsSupported: true`. Mutating endpoints
-    // (create, update, delete) additionally require
-    // `capabilities.prompts.mutableLibrary: true`. Hosts that don't advertise
-    // the relevant capability return `501 capability_not_provided`; the SDK
-    // surfaces that as a `WopError`. Clients SHOULD pre-flight via
-    // `getCapabilities()` before calling.
-    //
-    // NOTE: `capabilities.prompts.supported: true` (without
-    // `endpointsSupported: true`) ONLY gates node-execution PromptRef
-    // resolution per RFC 0027 Phase A; it does NOT imply these endpoints are
-    // available. See spec/v1/prompts.md §"Capability advertisement" for the
-    // two-axis gating split.
+    // ── Prompt library (RFC 0028; gated on `prompts`) ────────────────────
     prompts = {
-        /**
-         * List prompt templates available to the caller per RFC 0028 §A
-         * (operationId `listPromptTemplates`). Supports kind / tag / modelClass
-         * / source filters + opaque cursor pagination.
-         */
+        /** `GET /prompts` — kind / tag / modelClass / source filters + cursor pagination. */
         list: (req = {}) => {
             const search = new URLSearchParams();
             if (req.kind)
@@ -589,15 +506,10 @@ export class OpenwopClient {
             const query = search.toString();
             return this.#request({
                 method: 'GET',
-                path: `/v1/prompts${query ? `?${query}` : ''}`,
+                path: `/prompts${query ? `?${query}` : ''}`,
             });
         },
-        /**
-         * Fetch a single PromptTemplate by id per RFC 0028 §A
-         * (operationId `getPromptTemplate`). Optionally pin a SemVer
-         * `version`; supply `libraryId` to disambiguate when multiple installed
-         * packs ship the same templateId.
-         */
+        /** `GET /prompts/{templateId}` — `null` on `404`; a `400 prompt_ref_ambiguous` still throws. */
         get: async (req) => {
             const search = new URLSearchParams();
             if (req.version)
@@ -608,90 +520,55 @@ export class OpenwopClient {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/prompts/${encodeURIComponent(req.templateId)}${query ? `?${query}` : ''}`,
+                    path: `/prompts/${encodeURIComponent(req.templateId)}${query ? `?${query}` : ''}`,
                 });
             }
             catch (err) {
-                // Return null on 404 (no such template), consistent with the other
-                // get-by-id methods (`agents.get`, `tools.get`, …) and the Python/Go
-                // SDKs; a `400 prompt_ref_ambiguous` and other errors still throw so
-                // callers can distinguish "not found" from "ambiguous reference".
                 if (err instanceof WopError && err.status === 404)
                     return null;
                 throw err;
             }
         },
-        /**
-         * Render a PromptTemplate with supplied variable bindings per RFC 0028
-         * §A (operationId `renderPromptTemplate`). Returns composed body +
-         * sha256 hash + per-variable hashes. The deterministic-hash invariant
-         * (RFC 0028 §A) requires the `hash` to match what a matching
-         * `prompt.composed` event would carry at dispatch time. Does NOT
-         * dispatch an LLM call. Secret-source variable values MUST be supplied
-         * as `[REDACTED:<credentialRef>]` markers per
-         * SECURITY/threat-model-secret-leakage.md §SR-1.
-         */
+        /** `POST /prompts:render` — composed body + sha256 hash; does NOT dispatch an LLM call. */
         render: (req) => {
             return this.#request({
                 method: 'POST',
-                path: '/v1/prompts:render',
+                path: '/prompts:render',
                 body: req,
             });
         },
-        /**
-         * Create a new user-source PromptTemplate per RFC 0028 §A
-         * (operationId `createPromptTemplate`). Mutating endpoint —
-         * requires `capabilities.prompts.mutableLibrary: true`. Supports
-         * `Idempotency-Key` per the standard `MutationOptions` pattern.
-         */
+        /** `POST /prompts` — requires `prompts.mutableLibrary`. */
         create: (template, opts = {}) => {
             return this.#request({
                 method: 'POST',
-                path: '/v1/prompts',
+                path: '/prompts',
                 body: template,
                 headers: this.#mutationHeaders(opts),
             });
         },
-        /**
-         * Replace an existing user-source PromptTemplate per RFC 0028 §A
-         * (operationId `updatePromptTemplate`). Submitted SemVer MUST be
-         * strictly greater than stored. Mutating endpoint — requires
-         * `capabilities.prompts.mutableLibrary: true`. Pack-sourced and
-         * host-built-in templates are read-only (host returns 403).
-         */
+        /** `PUT /prompts/{templateId}` — the submitted SemVer MUST be strictly greater than stored. */
         update: (templateId, template, opts = {}) => {
             return this.#request({
                 method: 'PUT',
-                path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+                path: `/prompts/${encodeURIComponent(templateId)}`,
                 body: template,
                 headers: this.#mutationHeaders(opts),
             });
         },
-        /**
-         * Delete a user-source PromptTemplate per RFC 0028 §A
-         * (operationId `deletePromptTemplate`). Mutating endpoint —
-         * requires `capabilities.prompts.mutableLibrary: true`. Pack-sourced
-         * and host-built-in templates are read-only (host returns 403).
-         */
+        /** `DELETE /prompts/{templateId}` */
         delete: (templateId) => {
             return this.#request({
                 method: 'DELETE',
-                path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+                path: `/prompts/${encodeURIComponent(templateId)}`,
             });
         },
     };
-    // ── Audit-log integrity (gated on openwop-audit-log-integrity profile) ──
+    // ── Audit-log integrity ──────────────────────────────────────────────
     audit = {
         /**
-         * Verify the audit-log hash chain over `[fromSeq, toSeq]` per
-         * `auth-profiles.md` §`openwop-audit-log-integrity` §4. Requires
-         * the `audit:read` scope on the API key. Returns chain-validity
-         * verdict + signed checkpoints + any detected anomalies.
-         *
-         * Hosts that do NOT advertise the profile return `404` and throw
-         * a `WopError`. Clients SHOULD pre-flight via
-         * `client.getCapabilities()` (or directly inspect
-         * `capabilities.auth.profiles[]`) before calling.
+         * `GET /audit/verify?fromSeq&toSeq` — chain-validity verdict + signed
+         * checkpoints + anomalies. Requires the `audit:read` scope; a host that
+         * does not serve the profile answers `404`.
          */
         verify: (fromSeq, toSeq) => {
             const search = new URLSearchParams();
@@ -699,19 +576,18 @@ export class OpenwopClient {
             search.set('toSeq', String(toSeq));
             return this.#request({
                 method: 'GET',
-                path: `/v1/audit/verify?${search.toString()}`,
+                path: `/audit/verify?${search.toString()}`,
             });
         },
     };
-    // ── RFC 0103 Localized content surface (gated on capabilities.content) ──
+    // ── RFC 0103 Localized content surface (gated on `content`) ──────────
     content = {
-        /** `GET /v1/content/pages` — list page records. Returns `null` when the
-         *  host doesn't advertise `capabilities.content` (501). */
+        /** `GET /content/pages` — `null` when the host doesn't advertise `content` (501). */
         listPages: async () => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: '/v1/content/pages',
+                    path: '/content/pages',
                 });
             }
             catch (err) {
@@ -720,15 +596,12 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /** `GET /v1/content/pages/{slug}` — the negotiated locale's resolved page +
-         *  sections. `acceptLanguage` rides the `Accept-Language` header (the Stable
-         *  `i18n.md` negotiation; no `?locale=`). Returns `null` on `404`
-         *  (no such published page) or `501` (uncapable). */
+        /** `GET /content/pages/{slug}` — `acceptLanguage` rides `Accept-Language`; `null` on `404`/`501`. */
         getPage: async (slug, acceptLanguage) => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: `/v1/content/pages/${encodeURIComponent(slug)}`,
+                    path: `/content/pages/${encodeURIComponent(slug)}`,
                     ...(acceptLanguage
                         ? { headers: { 'Accept-Language': acceptLanguage } }
                         : {}),
@@ -740,27 +613,24 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /** `POST /v1/content/pages` — create a page record (admin). Throws the
-         *  typed `WopError` on `400`/`401`/`403`. */
+        /** `POST /content/pages` (admin). */
         createPage: (body) => this.#request({
             method: 'POST',
-            path: '/v1/content/pages',
+            path: '/content/pages',
             body,
         }),
-        /** `PUT /v1/content/pages/{pageId}/sections/{sectionId}` — upsert a
-         *  section's field overlay for a locale (admin). */
+        /** `PUT /content/pages/{pageId}/sections/{sectionId}` (admin). */
         putSection: (pageId, sectionId, body) => this.#request({
             method: 'PUT',
-            path: `/v1/content/pages/${encodeURIComponent(pageId)}/sections/${encodeURIComponent(sectionId)}`,
+            path: `/content/pages/${encodeURIComponent(pageId)}/sections/${encodeURIComponent(sectionId)}`,
             body,
         }),
-        /** `GET /v1/content/settings` — language settings. Returns `null` when the
-         *  host doesn't advertise `capabilities.content` (501). */
+        /** `GET /content/settings` — `null` when the host doesn't advertise `content` (501). */
         getSettings: async () => {
             try {
                 return await this.#request({
                     method: 'GET',
-                    path: '/v1/content/settings',
+                    path: '/content/settings',
                 });
             }
             catch (err) {
@@ -769,127 +639,45 @@ export class OpenwopClient {
                 throw err;
             }
         },
-        /** `PUT /v1/content/settings` — replace language settings (admin). */
+        /** `PUT /content/settings` (admin). */
         putSettings: (body) => this.#request({
             method: 'PUT',
-            path: '/v1/content/settings',
+            path: '/content/settings',
             body,
         }),
     };
-    // ── RFC 0099 Trigger subscriptions (gated on capabilities.triggerBridge) ──
+    // ── RFC 0099 Trigger subscriptions (gated on `triggerBridge`) ─────────
     triggerSubscriptions = {
-        /** `POST /v1/trigger-subscriptions` — register an external-event trigger.
-         *  The `binding.secret*` is returned ONCE at creation (SR-1); persist it.
-         *  Throws the typed `WopError` on `400`/`401`/`403`, or `501` when the host
-         *  doesn't advertise the trigger-bridge ingestion surface. */
+        /** `POST /trigger-subscriptions` — the `binding.secret*` is returned ONCE; persist it. */
         create: (body) => this.#request({
             method: 'POST',
-            path: '/v1/trigger-subscriptions',
+            path: '/trigger-subscriptions',
             body,
         }),
     };
-    // ── Agent workspace files (RFC 0059; gated on capabilities.workspace) ──
-    workspace = {
-        /**
-         * RFC 0059 — list workspace file metadata (no bodies) for the caller's
-         * `{tenant, workspace}`. Optional `prefix` filters the flat `path`
-         * namespace. Returns `null` when the host doesn't advertise
-         * `capabilities.workspace.supported` (501), so callers can branch on
-         * capability discovery without try/catch.
-         */
-        listFiles: async (opts = {}) => {
-            const search = new URLSearchParams();
-            if (opts.prefix !== undefined)
-                search.set('prefix', opts.prefix);
-            const qs = search.toString();
-            try {
-                const res = await this.#request({
-                    method: 'GET',
-                    path: `/v1/host/workspace/files${qs ? `?${qs}` : ''}`,
-                });
-                return res.files;
-            }
-            catch (err) {
-                if (err instanceof WopError && err.status === 501)
-                    return null;
-                throw err;
-            }
-        },
-        /**
-         * RFC 0059 — read one workspace file. Pass `version` for a historical
-         * snapshot when `capabilities.workspace.versioned`. Returns `null` when
-         * the file is absent (404) or the host doesn't advertise the capability
-         * (501).
-         */
-        getFile: async (path, opts = {}) => {
-            const search = new URLSearchParams();
-            if (opts.version !== undefined)
-                search.set('version', String(opts.version));
-            const qs = search.toString();
-            try {
-                return await this.#request({
-                    method: 'GET',
-                    path: `/v1/host/workspace/files/${encodeURIComponent(path)}${qs ? `?${qs}` : ''}`,
-                });
-            }
-            catch (err) {
-                if (err instanceof WopError && (err.status === 404 || err.status === 501))
-                    return null;
-                throw err;
-            }
-        },
-        /**
-         * RFC 0059 — atomic create/replace of a workspace file. Pass `ifMatch`
-         * (the file's current `etag`) for optimistic concurrency; a stale token
-         * throws a `WopError` with status `409` (`workspace_conflict`). Content
-         * beyond `capabilities.workspace.maxFileBytes` throws `413`
-         * (`workspace_too_large`). Returns the persisted `WorkspaceFile`.
-         */
-        putFile: (path, body, opts = {}) => {
-            const headers = this.#mutationHeaders(opts);
-            if (opts.ifMatch !== undefined)
-                headers['If-Match'] = opts.ifMatch;
-            return this.#request({
-                method: 'PUT',
-                path: `/v1/host/workspace/files/${encodeURIComponent(path)}`,
-                body,
-                headers,
-            });
-        },
-        /**
-         * RFC 0059 — delete a workspace file. Returns `true` on success (`204`),
-         * `false` when the file is absent (404) or the host doesn't advertise the
-         * capability (501).
-         */
-        deleteFile: async (path, opts = {}) => {
-            try {
-                await this.#request({
-                    method: 'DELETE',
-                    path: `/v1/host/workspace/files/${encodeURIComponent(path)}`,
-                    headers: this.#mutationHeaders(opts),
-                });
-                return true;
-            }
-            catch (err) {
-                if (err instanceof WopError && (err.status === 404 || err.status === 501))
-                    return false;
-                throw err;
-            }
-        },
-    };
     // ── Internals ────────────────────────────────────────────────────────
+    #streamContext() {
+        return {
+            baseUrl: this.#baseUrl,
+            apiKey: this.#apiKey,
+            protocolVersion: this.#versionHeader,
+            fetch: this.#fetch,
+        };
+    }
     #mutationHeaders(opts) {
         const h = {};
         if (opts.idempotencyKey)
             h['Idempotency-Key'] = opts.idempotencyKey;
         if (opts.dedup)
-            h['X-Dedup'] = opts.dedup;
+            h['OpenWOP-Dedup'] = opts.dedup;
         return h;
     }
     async #request(opts, authenticated = true) {
         const url = `${this.#baseUrl}${opts.path}`;
         const headers = {
             Accept: 'application/json',
+            // RFC 0172 §A.3 — on every request, authenticated or not.
+            'OpenWOP-Version': this.#versionHeader,
             ...(opts.headers ?? {}),
         };
         if (opts.body !== undefined && headers['Content-Type'] === undefined) {
@@ -898,7 +686,7 @@ export class OpenwopClient {
         if (authenticated) {
             headers.Authorization = `Bearer ${this.#apiKey}`;
         }
-        if (this.#acceptLanguage) {
+        if (this.#acceptLanguage && headers['Accept-Language'] === undefined) {
             headers['Accept-Language'] = this.#acceptLanguage;
         }
         const init = { method: opts.method, headers };
@@ -910,17 +698,15 @@ export class OpenwopClient {
         }
         const res = await this.#fetch(url, init);
         const text = await res.text();
-        // Capture traceparent for error reporting per observability.md
-        // §Trace context propagation. Header name is case-insensitive per
-        // RFC 9110; fetch normalizes to lowercase but be defensive.
+        // Capture traceparent for error reporting (observability.md §Trace
+        // context propagation). Header names are case-insensitive per RFC 9110.
         const traceparent = res.headers.get('traceparent') ?? res.headers.get('Traceparent') ?? undefined;
         if (!res.ok) {
             let env;
             try {
                 const parsed = text.length > 0 ? JSON.parse(text) : undefined;
-                if (parsed && typeof parsed === 'object' && 'error' in parsed && 'message' in parsed) {
+                if (isErrorEnvelope(parsed))
                     env = parsed;
-                }
             }
             catch {
                 // not JSON; leave envelope undefined
@@ -934,10 +720,17 @@ export class OpenwopClient {
         }
         catch {
             throw new WopError(res.status, text, {
-                error: 'invalid_json',
+                error: 'internal_error',
                 message: 'Server returned non-JSON body for a 2xx response',
+                details: { sdk: 'invalid_json' },
             }, traceparent);
         }
     }
 }
+function isErrorEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const rec = value;
+    return typeof rec['error'] === 'string' && typeof rec['message'] === 'string';
+}
 //# sourceMappingURL=client.js.map