@openwop/openwop 1.8.0 → 2.0.0

package/src/client.ts

@@ -1,14 +1,16 @@
 /**
- * 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, type EventsStreamOptions } from './sse.js';
+import { streamEvents, streamHostEvents, type EventsStreamOptions, type HostEventsStreamOptions } from './sse.js';
 import {
   WopError,
   type AuditVerifyResult,
@@ -24,19 +26,19 @@ import {
   type Capabilities,
   type CancelRunRequest,
   type CancelRunResponse,
+  type CompensationProjection,
   type CreateRunRequest,
   type CreateRunResponse,
+  type EffectLedgerProjection,
+  type EffectSeamManifest,
   type ErrorEnvelope,
   type ForkRunRequest,
   type ForkRunResponse,
   type Annotation,
   type CreateAnnotationRequest,
-  type WorkspaceFile,
-  type PutWorkspaceFileRequest,
   type GetPromptRequest,
+  type HostEventDoc,
   type InterruptByTokenInspection,
-  type DebugBundle,
-  type DebugBundleOptions,
   type ListPromptsRequest,
   type ListPromptsResponse,
   type PromptTemplate,
@@ -67,18 +69,31 @@ import {
   type CompactToolDescriptor,
   type AgentDeployment,
   type AgentDeploymentTransition,
-  type CreateUserAgentRequest,
-  type UserAgentRecord,
-  type AgentPackRegistryResponse,
-  type InstallAgentPackRequest,
-  type InstallAgentPackResponse,
 } 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: number): string {
+  if (!Number.isInteger(major) || major < 0) {
+    throw new TypeError(`OpenwopClient: major must be a non-negative integer (got ${String(major)})`);
+  }
+  return `${major}.0`;
+}
+
 export interface OpenwopClientOptions {
   /** Base URL of the openwop server, e.g., `https://api.example.com`. Trailing slash optional. */
   readonly baseUrl: string;
-  /** API key (bearer-style). See auth.md. */
+  /** API key (bearer-style). */
   readonly apiKey: string;
+  /**
+   * The protocol major to negotiate (RFC 0172 §A.3). Every request carries
+   * `OpenWOP-Version: <major>.0`; a host that does not list the major answers
+   * `406 protocol_version_unsupported` with `details.protocolVersions[]`.
+   * Default {@link SDK_PROTOCOL_MAJOR} (2).
+   */
+  readonly major?: number;
   /** Optional fetch implementation override (test injection). Defaults to global `fetch`. */
   readonly fetch?: typeof fetch;
   /** Default `Accept-Language` to send. Optional. */
@@ -86,9 +101,9 @@ export interface OpenwopClientOptions {
 }
 
 export interface MutationOptions {
-  /** RFC-spec'd Idempotency-Key for at-most-once mutation semantics. */
+  /** `Idempotency-Key` for at-most-once mutation semantics (idempotency.md Layer 1). */
   readonly idempotencyKey?: string;
-  /** Optional X-Dedup hint for cross-host claim coordination on POST /v1/runs. */
+  /** `OpenWOP-Dedup: enforce` — the host rejects a duplicate `(tenantId, scopeId)` with `409 run_already_active` (runs.md §Create). */
   readonly dedup?: 'enforce';
 }
 
@@ -105,6 +120,12 @@ export class OpenwopClient {
   readonly #apiKey: string;
   readonly #fetch: typeof fetch;
   readonly #acceptLanguage: string | undefined;
+  readonly #versionHeader: string;
+
+  /** The `OpenWOP-Version` value this client sends on every request. */
+  get protocolVersion(): string {
+    return this.#versionHeader;
+  }
 
   constructor(opts: OpenwopClientOptions) {
     if (!opts.baseUrl) throw new TypeError('OpenwopClient: baseUrl is required');
@@ -113,69 +134,53 @@ 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 ────────────────────────────────────────────────────────
   readonly 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: (): Promise<Capabilities> =>
       this.#request<Capabilities>({ method: 'GET', path: '/.well-known/openwop' }, false),
 
+    /** `GET /openapi.json` — the self-describing OpenAPI 3.1 document. */
     openapi: (): Promise<unknown> =>
-      this.#request<unknown>({ method: 'GET', path: '/v1/openapi.json' }, false),
+      this.#request<unknown>({ method: 'GET', path: '/openapi.json' }, false),
   };
 
   // ── Workflows ────────────────────────────────────────────────────────
   readonly workflows = {
+    /** `GET /workflows/{workflowId}` */
     get: (workflowId: string): Promise<unknown> =>
       this.#request<unknown>({
         method: 'GET',
-        path: `/v1/workflows/${encodeURIComponent(workflowId)}`,
+        path: `/workflows/${encodeURIComponent(workflowId)}`,
       }),
   };
 
   // ── Runs ─────────────────────────────────────────────────────────────
   readonly runs = {
+    /** `POST /runs` — the body is closed at the composition (runs.md §Create). */
     create: (body: CreateRunRequest, opts: MutationOptions = {}): Promise<CreateRunResponse> =>
       this.#request<CreateRunResponse>({
         method: 'POST',
-        path: '/v1/runs',
+        path: '/runs',
         body,
         headers: this.#mutationHeaders(opts),
       }),
 
+    /** `GET /runs/{runId}` — the snapshot (runs.md §Snapshot). */
     get: (runId: string): Promise<RunSnapshot> =>
       this.#request<RunSnapshot>({
         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: string, opts: DebugBundleOptions = {}): Promise<DebugBundle | null> => {
-      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<DebugBundle>({ 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: string,
       body: CancelRunRequest = {},
@@ -183,11 +188,12 @@ export class OpenwopClient {
     ): Promise<CancelRunResponse> =>
       this.#request<CancelRunResponse>({
         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: string,
       body: PauseRunRequest = {},
@@ -195,11 +201,12 @@ export class OpenwopClient {
     ): Promise<PauseRunResponse> =>
       this.#request<PauseRunResponse>({
         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: string,
       body: ResumeRunRequest = {},
@@ -207,19 +214,15 @@ export class OpenwopClient {
     ): Promise<ResumeRunResponse> =>
       this.#request<ResumeRunResponse>({
         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: BulkCancelRunsRequest,
@@ -227,11 +230,12 @@ export class OpenwopClient {
     ): Promise<BulkCancelRunsResponse> =>
       this.#request<BulkCancelRunsResponse>({
         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: string,
       body: ForkRunRequest,
@@ -239,16 +243,15 @@ export class OpenwopClient {
     ): Promise<ForkRunResponse> =>
       this.#request<ForkRunResponse>({
         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: string,
@@ -257,21 +260,21 @@ export class OpenwopClient {
     ): Promise<Annotation> =>
       this.#request<Annotation>({
         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: string): Promise<readonly Annotation[] | null> => {
       try {
         const res = await this.#request<{ annotations: Annotation[] }>({
           method: 'GET',
-          path: `/v1/runs/${encodeURIComponent(runId)}/annotations`,
+          path: `/runs/${encodeURIComponent(runId)}/annotations`,
         });
         return res.annotations;
       } catch (err) {
@@ -281,21 +284,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: string): Promise<RunAncestryResponse | null> => {
       try {
         return await this.#request<RunAncestryResponse>({
           method: 'GET',
-          path: `/v1/runs/${encodeURIComponent(runId)}/ancestry`,
+          path: `/runs/${encodeURIComponent(runId)}/ancestry`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -304,18 +303,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: string, against: string): Promise<RunDiffResponse | null> => {
       try {
         return await this.#request<RunDiffResponse>({
           method: 'GET',
-          path: `/v1/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
+          path: `/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -324,18 +320,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: string): Promise<EvalSummary | null> => {
       try {
         return await this.#request<EvalSummary>({
           method: 'GET',
-          path: `/v1/runs/${encodeURIComponent(runId)}/eval-summary`,
+          path: `/runs/${encodeURIComponent(runId)}/eval-summary`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -344,15 +337,46 @@ 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: string, artifactId: string): Promise<Record<string, unknown> | null> => {
       try {
         return await this.#request<Record<string, unknown>>({
           method: 'GET',
-          path: `/v1/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
+          path: `/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * `GET /runs/{runId}/compensation` (RFC 0173 §C.1) — the compensation
+     * plan and attempts. Gated on `compensation`; `null` on `404`.
+     */
+    compensation: async (runId: string): Promise<CompensationProjection | null> => {
+      try {
+        return await this.#request<CompensationProjection>({
+          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: string): Promise<EffectLedgerProjection | null> => {
+      try {
+        return await this.#request<EffectLedgerProjection>({
+          method: 'GET',
+          path: `/runs/${encodeURIComponent(runId)}/effects`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -360,13 +384,20 @@ export class OpenwopClient {
       }
     },
 
+    /**
+     * `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: string,
-      params: { lastSequence?: number; timeoutSeconds?: number } = {},
+      params: { afterSequence?: number; timeoutSeconds?: number } = {},
     ): Promise<PollEventsResponse> => {
       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));
@@ -374,39 +405,57 @@ export class OpenwopClient {
       const qs = search.toString();
       return this.#request<PollEventsResponse>({
         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: string, opts: EventsStreamOptions = {}): AsyncGenerator<RunEventDoc, void, void> =>
-      streamEvents({ baseUrl: this.#baseUrl, apiKey: this.#apiKey }, runId, opts),
+      streamEvents(this.#streamContext(), runId, opts),
+  };
+
+  // ── Host ─────────────────────────────────────────────────────────────
+  readonly host = {
+    /**
+     * `GET /host/effect-seams` (RFC 0173 §C) — every outbound effect seam
+     * replay suppression covers. Throws `401` when unauthenticated.
+     */
+    effectSeams: (): Promise<EffectSeamManifest> =>
+      this.#request<EffectSeamManifest>({ 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: HostEventsStreamOptions = {}): AsyncGenerator<HostEventDoc, void, void> =>
+      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).
   readonly agents = {
+    /** `GET /agents` */
     list: async (): Promise<AgentInventoryResponse | null> => {
       try {
-        return await this.#request<AgentInventoryResponse>({ method: 'GET', path: '/v1/agents' });
+        return await this.#request<AgentInventoryResponse>({ method: 'GET', path: '/agents' });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
 
+    /** `GET /agents/{agentId}` */
     get: async (agentId: string): Promise<AgentInventoryEntry | null> => {
       try {
         return await this.#request<AgentInventoryEntry>({
           method: 'GET',
-          path: `/v1/agents/${encodeURIComponent(agentId)}`,
+          path: `/agents/${encodeURIComponent(agentId)}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -414,17 +463,12 @@ export class OpenwopClient {
       }
     },
 
-    /**
-     * 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: string): Promise<readonly AgentDeployment[] | null> => {
       try {
         return await this.#request<AgentDeployment[]>({
           method: 'GET',
-          path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+          path: `/agents/${encodeURIComponent(agentId)}/deployments`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -432,14 +476,7 @@ export class OpenwopClient {
       }
     },
 
-    /**
-     * 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: string,
       body: AgentDeploymentTransition,
@@ -447,34 +484,27 @@ export class OpenwopClient {
     ): Promise<AgentDeployment> =>
       this.#request<AgentDeployment>({
         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 (): Promise<AgentRosterResponse | null> => {
       try {
-        return await this.#request<AgentRosterResponse>({ method: 'GET', path: '/v1/agents/roster' });
+        return await this.#request<AgentRosterResponse>({ method: 'GET', path: '/agents/roster' });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
         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: string): Promise<AgentRosterEntry | null> => {
       try {
         return await this.#request<AgentRosterEntry>({
           method: 'GET',
-          path: `/v1/agents/roster/${encodeURIComponent(rosterId)}`,
+          path: `/agents/roster/${encodeURIComponent(rosterId)}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -482,26 +512,17 @@ export class OpenwopClient {
       }
     },
 
-    /**
-     * 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 (): Promise<AgentOrgChart | null> => {
       try {
-        return await this.#request<AgentOrgChart>({ method: 'GET', path: '/v1/agents/org-chart' });
+        return await this.#request<AgentOrgChart>({ method: 'GET', path: '/agents/org-chart' });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
         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: string,
       opts: { recursive?: boolean } = {},
@@ -510,7 +531,7 @@ export class OpenwopClient {
       try {
         return await this.#request<OrgChartResponsibilityView>({
           method: 'GET',
-          path: `/v1/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
+          path: `/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -519,35 +540,24 @@ 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`) ─────────
   readonly 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 (): Promise<readonly ToolDescriptor[] | null> => {
       try {
-        return await this.#request<ToolDescriptor[]>({ method: 'GET', path: '/v1/tools' });
+        return await this.#request<ToolDescriptor[]>({ method: 'GET', path: '/tools' });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
         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 (): Promise<readonly CompactToolDescriptor[] | null> => {
       try {
         const res = await this.#request<{ tools?: readonly CompactToolDescriptor[] }>({
           method: 'GET',
-          path: '/v1/tools?view=compact',
+          path: '/tools?view=compact',
         });
         return res.tools ?? [];
       } catch (err) {
@@ -556,12 +566,7 @@ export class OpenwopClient {
       }
     },
 
-    /**
-     * 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: string,
       opts: { readonly view?: 'standard' | 'compact' } = {},
@@ -570,7 +575,7 @@ export class OpenwopClient {
       try {
         return await this.#request<ToolDescriptor | CompactToolDescriptor>({
           method: 'GET',
-          path: `/v1/tools/${encodeURIComponent(toolId)}${query}`,
+          path: `/tools/${encodeURIComponent(toolId)}${query}`,
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 404) return null;
@@ -579,61 +584,9 @@ 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.
-  readonly userAgents = {
-    create: async (body: CreateUserAgentRequest, opts: MutationOptions = {}): Promise<UserAgentRecord> => {
-      return await this.#request<UserAgentRecord>({
-        method: 'POST',
-        path: '/v1/host/sample/agents',
-        body,
-        ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
-      });
-    },
-
-    delete: async (agentId: string): Promise<boolean> => {
-      try {
-        await this.#request<void>({
-          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 (): Promise<AgentPackRegistryResponse | null> => {
-      try {
-        return await this.#request<AgentPackRegistryResponse>({
-          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: InstallAgentPackRequest,
-    ): Promise<InstallAgentPackResponse> => {
-      return await this.#request<InstallAgentPackResponse>({
-        method: 'POST',
-        path: '/v1/host/sample/registry/agent-packs/install',
-        body,
-      });
-    },
-  };
-
   // ── HITL interrupts (run-scoped + signed-token) ──────────────────────
   readonly interrupts = {
+    /** `POST /runs/{runId}/interrupts/{nodeId}` */
     resolveByRun: (
       runId: string,
       nodeId: string,
@@ -642,32 +595,26 @@ export class OpenwopClient {
     ): Promise<ResolveInterruptResponse> =>
       this.#request<ResolveInterruptResponse>({
         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: string): Promise<InterruptByTokenInspection> =>
       this.#request<InterruptByTokenInspection>(
         {
           method: 'GET',
-          path: `/v1/interrupts/${encodeURIComponent(token)}`,
+          path: `/interrupts/${encodeURIComponent(token)}`,
         },
         false, // unauthenticated (token IS the auth)
       ),
 
-    /**
-     * 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: string,
       body: ResolveInterruptRequest,
@@ -676,7 +623,7 @@ export class OpenwopClient {
       this.#request<ResolveInterruptByTokenResponse>(
         {
           method: 'POST',
-          path: `/v1/interrupts/${encodeURIComponent(token)}`,
+          path: `/interrupts/${encodeURIComponent(token)}`,
           body,
           headers: this.#mutationHeaders(opts),
         },
@@ -684,14 +631,13 @@ export class OpenwopClient {
       ),
   };
 
-  // ── Webhook subscriptions (per spec/v1/webhooks.md) ─────────────────────
+  // ── Webhook subscriptions (webhooks.md; gated on `webhooks`) ─────────
   readonly 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: RegisterWebhookRequest,
@@ -699,45 +645,23 @@ export class OpenwopClient {
     ): Promise<RegisterWebhookResponse> =>
       this.#request<RegisterWebhookResponse>({
         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: string): Promise<void> => {
+    /** `DELETE /webhooks/{webhookId}` — `204`; throws `404` when unknown, `403` outside the tenant. */
+    unregister: async (webhookId: string): Promise<void> => {
       await this.#request<unknown>({
         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`) ────────────────────
   readonly 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: ListPromptsRequest = {}): Promise<ListPromptsResponse> => {
       const search = new URLSearchParams();
       if (req.kind) search.set('kind', req.kind);
@@ -749,16 +673,11 @@ export class OpenwopClient {
       const query = search.toString();
       return this.#request<ListPromptsResponse>({
         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: GetPromptRequest): Promise<PromptTemplate | null> => {
       const search = new URLSearchParams();
       if (req.version) search.set('version', req.version);
@@ -767,58 +686,34 @@ export class OpenwopClient {
       try {
         return await this.#request<PromptTemplate>({
           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: RenderPromptRequest): Promise<RenderPromptResponse> => {
       return this.#request<RenderPromptResponse>({
         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: PromptTemplate, opts: MutationOptions = {}): Promise<void> => {
       return this.#request<void>({
         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: string,
       template: PromptTemplate,
@@ -826,38 +721,27 @@ export class OpenwopClient {
     ): Promise<PromptTemplate> => {
       return this.#request<PromptTemplate>({
         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: string): Promise<void> => {
       return this.#request<void>({
         method: 'DELETE',
-        path: `/v1/prompts/${encodeURIComponent(templateId)}`,
+        path: `/prompts/${encodeURIComponent(templateId)}`,
       });
     },
   };
 
-  // ── Audit-log integrity (gated on openwop-audit-log-integrity profile) ──
+  // ── Audit-log integrity ──────────────────────────────────────────────
   readonly 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: number, toSeq: number): Promise<AuditVerifyResult> => {
       const search = new URLSearchParams();
@@ -865,20 +749,19 @@ export class OpenwopClient {
       search.set('toSeq', String(toSeq));
       return this.#request<AuditVerifyResult>({
         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`) ──────────
   readonly 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 (): Promise<readonly LocalizedContentPage[] | null> => {
       try {
         return await this.#request<readonly LocalizedContentPage[]>({
           method: 'GET',
-          path: '/v1/content/pages',
+          path: '/content/pages',
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 501) return null;
@@ -886,10 +769,7 @@ export class OpenwopClient {
       }
     },
 
-    /** `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: string,
       acceptLanguage?: string,
@@ -897,7 +777,7 @@ export class OpenwopClient {
       try {
         return await this.#request<LocalizedContentPageResponse>({
           method: 'GET',
-          path: `/v1/content/pages/${encodeURIComponent(slug)}`,
+          path: `/content/pages/${encodeURIComponent(slug)}`,
           ...(acceptLanguage
             ? { headers: { 'Accept-Language': acceptLanguage } }
             : {}),
@@ -909,17 +789,15 @@ export class OpenwopClient {
       }
     },
 
-    /** `POST /v1/content/pages` — create a page record (admin). Throws the
-     *  typed `WopError` on `400`/`401`/`403`. */
+    /** `POST /content/pages` (admin). */
     createPage: (body: LocalizedContentPage): Promise<LocalizedContentPage> =>
       this.#request<LocalizedContentPage>({
         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: string,
       sectionId: string,
@@ -927,17 +805,16 @@ export class OpenwopClient {
     ): Promise<LocalizedContentSection> =>
       this.#request<LocalizedContentSection>({
         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 (): Promise<LocalizedContentLanguageSettings | null> => {
       try {
         return await this.#request<LocalizedContentLanguageSettings>({
           method: 'GET',
-          path: '/v1/content/settings',
+          path: '/content/settings',
         });
       } catch (err) {
         if (err instanceof WopError && err.status === 501) return null;
@@ -945,126 +822,44 @@ export class OpenwopClient {
       }
     },
 
-    /** `PUT /v1/content/settings` — replace language settings (admin). */
+    /** `PUT /content/settings` (admin). */
     putSettings: (
       body: LocalizedContentLanguageSettings,
     ): Promise<LocalizedContentLanguageSettings> =>
       this.#request<LocalizedContentLanguageSettings>({
         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`) ─────────
   readonly 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: TriggerSubscriptionRegistration,
     ): Promise<CreateTriggerSubscriptionResponse> =>
       this.#request<CreateTriggerSubscriptionResponse>({
         method: 'POST',
-        path: '/v1/trigger-subscriptions',
+        path: '/trigger-subscriptions',
         body,
       }),
   };
 
-  // ── Agent workspace files (RFC 0059; gated on capabilities.workspace) ──
-  readonly 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: { prefix?: string } = {}): Promise<readonly WorkspaceFile[] | null> => {
-      const search = new URLSearchParams();
-      if (opts.prefix !== undefined) search.set('prefix', opts.prefix);
-      const qs = search.toString();
-      try {
-        const res = await this.#request<{ files: WorkspaceFile[] }>({
-          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: string, opts: { version?: number } = {}): Promise<WorkspaceFile | null> => {
-      const search = new URLSearchParams();
-      if (opts.version !== undefined) search.set('version', String(opts.version));
-      const qs = search.toString();
-      try {
-        return await this.#request<WorkspaceFile>({
-          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: string,
-      body: PutWorkspaceFileRequest,
-      opts: MutationOptions & { ifMatch?: string } = {},
-    ): Promise<WorkspaceFile> => {
-      const headers = this.#mutationHeaders(opts);
-      if (opts.ifMatch !== undefined) headers['If-Match'] = opts.ifMatch;
-      return this.#request<WorkspaceFile>({
-        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: string, opts: MutationOptions = {}): Promise<boolean> => {
-      try {
-        await this.#request<void>({
-          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(): { baseUrl: string; apiKey: string; protocolVersion: string; fetch: typeof fetch } {
+    return {
+      baseUrl: this.#baseUrl,
+      apiKey: this.#apiKey,
+      protocolVersion: this.#versionHeader,
+      fetch: this.#fetch,
+    };
+  }
+
   #mutationHeaders(opts: MutationOptions): Record<string, string> {
     const h: Record<string, string> = {};
     if (opts.idempotencyKey) h['Idempotency-Key'] = opts.idempotencyKey;
-    if (opts.dedup) h['X-Dedup'] = opts.dedup;
+    if (opts.dedup) h['OpenWOP-Dedup'] = opts.dedup;
     return h;
   }
 
@@ -1072,6 +867,8 @@ export class OpenwopClient {
     const url = `${this.#baseUrl}${opts.path}`;
     const headers: Record<string, string> = {
       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) {
@@ -1080,7 +877,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;
     }
 
@@ -1094,19 +891,16 @@ 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: ErrorEnvelope | undefined;
       try {
-        const parsed = text.length > 0 ? JSON.parse(text) : undefined;
-        if (parsed && typeof parsed === 'object' && 'error' in parsed && 'message' in parsed) {
-          env = parsed as ErrorEnvelope;
-        }
+        const parsed: unknown = text.length > 0 ? JSON.parse(text) : undefined;
+        if (isErrorEnvelope(parsed)) env = parsed;
       } catch {
         // not JSON; leave envelope undefined
       }
@@ -1121,11 +915,18 @@ export class OpenwopClient {
         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: unknown): value is ErrorEnvelope {
+  if (typeof value !== 'object' || value === null) return false;
+  const rec = value as Record<string, unknown>;
+  return typeof rec['error'] === 'string' && typeof rec['message'] === 'string';
+}