@openwop/openwop 1.9.0 → 2.0.0

package/README.md

@@ -1,155 +1,102 @@
-# `@openwop/openwop` — TypeScript SDK for the Multi-Agent Workflow Orchestration Protocol
+# `@openwop/openwop` 2.x — TypeScript SDK for OpenWOP v2 hosts
 
-**openwop is an open, wire-level protocol for multi-agent workflow orchestration** — a single contract for runs in which LLM agents, deterministic tools, sub-workflows, and human reviewers collaborate, with durable suspend / resume, replay, version negotiation, and observability owned by the protocol itself. This package is the reference TypeScript client: typed methods for every spec'd REST endpoint plus an async-iterable SSE consumer, zero runtime deps.
+**openwop is an open, wire-level protocol for multi-agent workflow orchestration.** This package is the reference TypeScript client for the **v2 major** (`spec/v2/`, RFC 0168 §D): one typed method per operation in `spec/v2/path-manifest.json` (51 operations), an async-iterable SSE consumer for the run and host event channels, and zero runtime dependencies.
 
 ```bash
-npm install @openwop/openwop
+npm install @openwop/openwop@2   # 2.0.0 — v2-only; the 1.x client stays on `@openwop/openwop@1`
 ```
 
-> **Spec:** [github.com/openwop/openwop](https://github.com/openwop/openwop) · **Status:** FINAL v1 (2026-04-27) · **Mirrors:** [`api/openapi.yaml`](https://github.com/openwop/openwop/blob/main/api/openapi.yaml)
+> **Spec:** [github.com/openwop/openwop](https://github.com/openwop/openwop) · **Corpus tag:** see [`CORPUS_TAG`](../../CORPUS_TAG) · **Mirrors:** [`api/v2/openapi.yaml`](../../api/v2/openapi.yaml), [`api/v2/asyncapi.yaml`](../../api/v2/asyncapi.yaml), [`schemas/v2/`](../../schemas/v2/), [`spec/v2/errors.json`](../../spec/v2/errors.json)
+>
+> The 1.x package (`sdk/typescript/`) is untouched and keeps publishing for v1 hosts. This is a v2-ONLY client: it never sends a `/v1/…` path.
 
-The SDK is hand-authored rather than codegen'd from OpenAPI for two reasons:
+## What is different from 1.x (RFC 0172 / 0171 / 0173)
 
-1. **Idiomatic shape.** OpenAPI codegen produces verbose accessors (`api.runs.runs_create()`, etc.) that are nicer if hand-curated. A v1 reference SDK should set the API style other ecosystems (Python, Go) follow.
-2. **Stays close to the spec.** Each method maps 1:1 to a documented endpoint, and types come from the spec's JSON Schemas (referenced via the OpenAPI doc), not from a generator's intermediate representation.
-
----
+| 1.x | 2.x |
+| --- | --- |
+| `/v1/runs`, `/v1/agents`, … | Bare origin, unversioned path keys: `/runs`, `/agents`, … There is no `/v2/` path space. |
+| Negotiation by `protocolVersion` | `OpenWOP-Version: <major>.0` on **every** request (ctor option `major`, default `2`); the host answers `406 protocol_version_unsupported` with `details.protocolVersions[]` when it does not list the major. |
+| `X-Dedup` | `OpenWOP-Dedup` (`MutationOptions.dedup`). Every non-standard header is `OpenWOP-<Name>` (headers.md). |
+| `pollEvents({ lastSequence })` | `pollEvents({ afterSequence })`; the response is the closed `{ runId, events, lastSequence, status, isTerminal }`. |
+| Open discovery root, `supported: boolean` | The closed v2 root: `protocolVersions[]` + `preferredVersion` REQUIRED, every family a `CapabilityRecord` `{ status, since, until?, witness, …facets }` (presence is the claim). Family and metadata keys are generated from `schemas/v2/capabilities.schema.json`. |
+| `ErrorEnvelope.error: string` | `ErrorCode \| VendorErrorCode` — the 94-member union is generated from `spec/v2/errors.json` (`ERROR_CODES`, `ERROR_CODE_HTTP_STATUS`, `RETRIABLE_ERROR_CODES`). |
+| `workspace.*` (4), `runs.debugBundle`, `userAgents.*` (host-sample seams), `RegistryClient` | Removed — not v2 operations. The pack registry is a separate wire surface a client resolves through `.well-known/openwop-registry.json` `endpoints` (packs.md). |
+| — | `runs.compensation`, `runs.effects`, `host.effectSeams` (RFC 0173), `host.events` (the `hostEvents` SSE channel). |
+| Webhook `openwop-Webhook-*` legacy names, `v1=<hex>` | `OpenWOP-*` only (`X-openwop-*` accepted through the overlap); `sha256=<hex>`; an unrecognized `OpenWOP-Signature-Algorithm` is rejected. Import from `@openwop/openwop/webhooks` — the barrel no longer carries `node:crypto`. |
 
 ## Quickstart
 
 ```typescript
-import { OpenwopClient } from '@openwop/openwop';
+import { OpenwopClient, WopError, isTerminalRunStatus } from '@openwop/openwop';
 
 const client = new OpenwopClient({
   baseUrl: 'https://api.example.com',
   apiKey: 'hk_test_abc123',
+  // major: 2 — the default; every request carries `OpenWOP-Version: 2.0`.
 });
 
-// Discovery
+// Discovery — the closed v2 root; `webhooks` is a record or absent, never `supported: false`.
 const caps = await client.discovery.capabilities();
-console.log(caps.protocolVersion, caps.limits);
-
-// Workflows
-const wf = await client.workflows.get('my-workflow-id');
+console.log(caps.preferredVersion, caps.protocolVersions, caps.webhooks?.status);
 
-// Run lifecycle
-const { runId } = await client.runs.create({
-  workflowId: 'my-workflow-id',
-  inputs: { foo: 'bar' },
-});
+// Runs
+const { runId } = await client.runs.create(
+  { workflowId: 'my-workflow', inputs: { q: 'hello' }, configurable: { version: 1, run: { runTimeoutMs: 60_000 } } },
+  { idempotencyKey: crypto.randomUUID(), dedup: 'enforce' },
+);
 
-// Poll (or use SSE — see below)
-let snap = await client.runs.get(runId);
-while (snap.status !== 'completed' && snap.status !== 'failed') {
-  await new Promise((r) => setTimeout(r, 500));
-  snap = await client.runs.get(runId);
+for await (const event of client.runs.events(runId, { streamMode: ['updates', 'messages'] })) {
+  console.log(event.sequence, event.type);
 }
 
-// Cancel mid-flight
-await client.runs.cancel(runId, { reason: 'user request' });
-
-// HITL approval (run-scoped)
-await client.interrupts.resolveByRun(runId, 'gate', { resumeValue: { action: 'accept' } });
-
-// Replay / fork
-const fork = await client.runs.fork(runId, { fromSeq: 5, mode: 'branch' });
-
-// SSE stream
-for await (const event of client.runs.events(runId, { streamMode: 'updates' })) {
-  console.log(event.type, event.payload);
+// Long-poll fallback: feed `lastSequence` back as `afterSequence`.
+let cursor: number | undefined;
+for (;;) {
+  const page = await client.runs.pollEvents(runId, cursor === undefined ? {} : { afterSequence: cursor });
+  cursor = page.lastSequence;
+  if (page.isTerminal) break;
 }
-```
 
----
+// RFC 0173 read projections
+const compensation = await client.runs.compensation(runId); // null when `compensation` is unadvertised
+const effects = await client.runs.effects(runId);
 
-## Quickstart (Node)
+// Errors route on the registered code, never on `message`.
+try {
+  await client.runs.get('tenant/does-not-exist');
+} catch (err) {
+  if (err instanceof WopError && err.envelope?.error === 'not_found') { /* … */ }
+}
 
-```bash
-cd sdk/typescript
-npm install        # installs @openwop/openwop deps locally (NOT in parent monorepo)
-npx tsc --noEmit   # typecheck the SDK source
+void isTerminalRunStatus;
 ```
 
----
-
-## What's Covered In v1.0
-
-| Endpoint | SDK method |
-|---|---|
-| `GET /.well-known/openwop` | `client.discovery.capabilities()` |
-| `GET /v1/openapi.json` | `client.discovery.openapi()` |
-| `GET /v1/workflows/{id}` | `client.workflows.get(id)` |
-| `POST /v1/runs` | `client.runs.create(body, opts?)` |
-| `GET /v1/runs/{id}` | `client.runs.get(id)` |
-| `GET /v1/runs/{id}/events` (SSE) | `client.runs.events(id, opts?)` (async iterable) |
-| `GET /v1/runs/{id}/events/poll` | `client.runs.pollEvents(id, opts?)` |
-| `POST /v1/runs/{id}/cancel` | `client.runs.cancel(id, body?)` |
-| `POST /v1/runs:bulk-cancel` | `client.runs.bulkCancel(body, opts?)` |
-| `POST /v1/runs/{id}:pause` | `client.runs.pause(id, body?, opts?)` |
-| `POST /v1/runs/{id}:resume` | `client.runs.resume(id, body?, opts?)` |
-| `POST /v1/runs/{id}:fork` | `client.runs.fork(id, body)` |
-| `POST /v1/runs/{id}/interrupts/{nodeId}` | `client.interrupts.resolveByRun(id, nodeId, body)` |
-| `GET /v1/interrupts/{token}` | `client.interrupts.inspectByToken(token)` |
-| `POST /v1/interrupts/{token}` | `client.interrupts.resolveByToken(token, body)` |
-| `GET /v1/audit/verify` | `client.audit.verify(fromSeq, toSeq)` |
-
-**Idempotency-Key** is supported via the `idempotencyKey` option on every mutation method.
-
-**Typed `RunConfigurable`** — `client.runs.create(...).configurable` is now a typed surface with reserved keys (`recursionLimit`, `model`, `temperature`, `maxTokens`, `promptOverrides`) plus pass-through for impl extensions.
-
-## Error Handling
+Webhook receivers (server-only):
 
 ```typescript
-import { HTTP_ERROR_CODES, isHttpErrorCode, WopError } from '@openwop/openwop';
-
-try {
-  await client.runs.create({ workflowId: 'my-workflow-id' });
-} catch (err) {
-  if (err instanceof WopError && isHttpErrorCode(err.envelope?.error)) {
-    console.error(err.envelope.error, err.envelope.details);
-  }
-}
+import { readWebhookHeaders, verifyWebhookSignature } from '@openwop/openwop/webhooks';
+
+const read = readWebhookHeaders(req.headers);
+const outcome = read
+  ? verifyWebhookSignature(secret, read.signatureHeader, read.timestampHeader, rawBody, {
+      ...(read.algorithmHeader === undefined ? {} : { algorithmHeader: read.algorithmHeader }),
+    })
+  : { valid: false as const, reason: 'malformed_signature_header' as const };
 ```
 
-`HTTP_ERROR_CODES` is the canonical REST/MCP error-envelope vocabulary (`unauthenticated`, `validation_error`, `run_already_active`, etc.). Contextual fields live under `ErrorEnvelope.details`; for example retry hints are `details.retryAfter`, not a top-level response field. `RUN_ERROR_CODES` is separate and applies to `RunSnapshot.error.code` after a run itself fails.
-
----
+## Generated surface
 
-## Not In The v1.0 SDK
+`src/generated.ts` is produced by `scripts/generate.mjs` from the vendored `spec/v2/errors.json` and `schemas/v2/capabilities.schema.json`. `npm run generate` rewrites it; `npm run generate:check` (run by `scripts/sdks-check.sh`) fails when it drifts from the corpus at `CORPUS_TAG`.
 
-| Feature | Why |
-|---|---|
-| Webhook subscription helpers | v1 specifies webhook delivery, but the SDK keeps endpoint coverage focused on the run lifecycle and conformance-critical surfaces. |
-| Hosted registry publishing helpers | Node-pack registry publishing needs operator-specific credentials and policy; use direct HTTP until a dedicated package workflow is warranted. |
-| Auto-retry with exponential backoff | Retry policy is application-specific. The SDK exposes structured errors so callers can implement their own retry envelope. |
-| Separate browser entrypoint (`@openwop/openwop/browser`) | The default ESM build uses standard `fetch`/`ReadableStream` primitives and can be bundled by modern tools; a dedicated browser subpath can ship later without changing the v1 surface. |
+## Method ↔ operation map
 
----
+Every one of the 51 `spec/v2/path-manifest.json` operations has exactly one method; `scripts/check-sdk-parity.mjs --manifest spec/v2/path-manifest.json --expectations sdk/parity-expectations-v2.json` enforces it. See [`sdk/PARITY.md`](../PARITY.md) §v2.
 
-## Layout
+## Development
 
+```bash
+npm install
+npm run typecheck   # strict + exactOptionalPropertyTypes
+npm test
+npm run generate:check
 ```
-sdk/typescript/
-  README.md                  — this file
-  package.json               — @openwop/openwop package manifest
-  tsconfig.json              — strict TS, ESM
-  src/
-    index.ts                 — public surface (OpenwopClient + types)
-    client.ts                — OpenwopClient class (auth, request helper)
-    types.ts                 — request/response types mirrored from the OpenAPI spec
-    sse.ts                   — async-iterable SSE consumer
-```
-
----
-
-## Versioning
-
-This SDK tracks OpenWOP v1. SDK majors match the protocol major; v1.x SDK releases remain forward-compatible with the v1 wire contract. Mismatch behavior is forward-compat tolerant — see `../../version-negotiation.md`. Breaking spec changes will increment the SDK major.
-
-## References
-
-- Spec corpus: `../../README.md`
-- OpenAPI: `../../api/openapi.yaml` (the SDK mirrors this surface)
-- AsyncAPI: `../../api/asyncapi.yaml` (the SSE consumer follows these channels)
-- **[`../PARITY.md`](../PARITY.md)** — cross-SDK feature-parity matrix (TS/Python/Go).
-- **[`../smoke/`](../smoke/)** — runnable wire-smoke scripts against a reference host.