feat(http-recorder): prepare independent beta release

Author: kitlangton

.changeset/brave-cassettes-record.md

@@ -0,0 +1,5 @@
+---
+"@opencode-ai/http-recorder": minor
+---
+
+Publish the initial beta of the Effect HTTP and WebSocket record/replay library.

.changeset/config.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
+  "changelog": "@changesets/cli/changelog",
+  "commit": false,
+  "fixed": [],
+  "linked": [],
+  "access": "public",
+  "baseBranch": "dev",
+  "updateInternalDependencies": "patch",
+  "ignore": []
+}

.github/workflows/http-recorder-release.yml

@@ -0,0 +1,35 @@
+name: http-recorder release
+
+on:
+  workflow_dispatch:
+
+concurrency: http-recorder-release
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  release:
+    if: github.repository == 'anomalyco/opencode' && github.ref == 'refs/heads/dev'
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+      - uses: ./.github/actions/setup-bun
+
+      - name: Verify package
+        working-directory: packages/http-recorder
+        run: |
+          bun run test
+          bun typecheck
+
+      - name: Publish beta
+        run: |
+          if [ -n "$NODE_AUTH_TOKEN" ]; then
+            npm config set //registry.npmjs.org/:_authToken "$NODE_AUTH_TOKEN"
+          fi
+          bun run release:http-recorder
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

bun.lock

@@ -12,9 +12,12 @@
     "dev:console": "ulimit -n 10240 2>/dev/null; bun run --cwd packages/console/app dev",
     "dev:stats": "bun sst shell --stage=production -- bun run --cwd packages/stats/app dev",
     "dev:storybook": "bun --cwd packages/storybook storybook",
+    "changeset": "changeset",
     "lint": "oxlint",
+    "release:http-recorder": "bun ./packages/http-recorder/script/publish.ts",
     "typecheck": "bun turbo typecheck",
     "upgrade-opentui": "bun run script/upgrade-opentui.ts",
+    "version:http-recorder": "bun ./packages/http-recorder/script/version.ts",
     "postinstall": "bun run --cwd packages/core fix-node-pty",
     "prepare": "husky",
     "random": "echo 'Random script'",
@@ -94,6 +97,7 @@
   },
   "devDependencies": {
     "@actions/artifact": "5.0.1",
+    "@changesets/cli": "2.31.0",
     "@tsconfig/bun": "catalog:",
     "@types/mime-types": "3.0.1",
     "@typescript/native-preview": "catalog:",

package.json

@@ -0,0 +1,43 @@
+# HTTP Recorder
+
+The HTTP recorder is a public testing library for recording real Effect transport traffic into deterministic cassettes and replaying it without contacting the upstream service.
+
+## Language
+
+**Library Version**:
+The independently managed semantic version of `@opencode-ai/http-recorder` published to npm.
+_Avoid_: OpenCode version
+
+**OpenCode Release Version**:
+The version applied to OpenCode applications and packages by the repository-wide release process. It does not determine the **Library Version**.
+
+**Effect Compatibility Version**:
+The exact Effect 4 beta against which the package's unstable HTTP and socket integrations are built and verified.
+
+**Provider Conversation**:
+A finite WebSocket connection in which either peer may send first, the client sends one or more JSON commands, server frames follow in causal order, and the application closes after a terminal event.
+
+**Connection Identity**:
+The explicit cassette name supplied to the WebSocket recorder. It identifies the recorded conversation during replay.
+
+**Completed Conversation**:
+A WebSocket socket run that opened and finished successfully after recording a valid finite transcript.
+
+**Client Frame Match**:
+The replay check that requires an outgoing application frame to equal the next recorded client frame after redaction. Text JSON ignores object-key order; other text and binary frames match exactly.
+
+## Relationships
+
+- The **Library Version** begins with the public beta at `0.1.0` and advances independently through Changesets.
+- Repository-wide OpenCode release synchronization must not rewrite the **Library Version**.
+- The initial **Effect Compatibility Version** is `4.0.0-beta.83`; compatibility with later Effect betas is not implied.
+- Changing the **Effect Compatibility Version** requires a new **Library Version** and clean-consumer package verification.
+- A **Provider Conversation** is the canonical WebSocket scenario for evaluating the public beta contract; arbitrary socket emulation is not implied.
+- Application code owns WebSocket construction, including URL, protocols, timeout, authentication, and close policy; the recorder decorates the resulting Effect `Socket.Socket` service.
+- **Connection Identity**, not the live WebSocket destination, selects and validates a replay. The beta does not validate URL or handshake configuration during replay.
+- Only a **Completed Conversation** is committed to a cassette; failed, interrupted, unopened, or invalid runs do not produce a recording.
+- Replay requires every recorded frame to be consumed before application close.
+- Terminal close codes, close reasons, connection timing, and transport failures are not cassette events in the first public beta.
+- Every outgoing replay frame must satisfy the **Client Frame Match** before later server frames are released.
+- The first public beta does not expose a custom WebSocket frame matcher.
+- Replay starts incoming frame handlers in recorded order and may run them concurrently; it waits for every handler before the socket run completes but does not guarantee handler completion order.

packages/http-recorder/CONTEXT.md

@@ -9,13 +9,13 @@ Use it for provider integrations, retries, polling, multi-step flows, and any te
 ## Install
 
 ```sh
-bun add effect@4.0.0-beta.74
+bun add effect@4.0.0-beta.83 @effect/platform-node@4.0.0-beta.83
 bun add -d @opencode-ai/http-recorder@beta @effect/vitest vitest
 ```
 
 The package supports Node.js 22+ and Bun. It is not intended for browsers, workers, or Deno.
 
-Effect `4.0.0-beta.74` has a known declaration error (`SchemaErrorTypeId` is missing). Until that upstream declaration is fixed, TypeScript consumers need:
+Effect `4.0.0-beta.83` currently contains unresolved symbols in its published declarations. Until those upstream declarations are fixed, TypeScript consumers need:
 
 ```json
 {
@@ -89,41 +89,58 @@ That is the complete public API. `http` provides a fetch-backed recorded `HttpCl
 
 ## WebSockets
 
-WebSocket cassettes preserve one ordered transcript of client and server text or binary frames. Replay follows that chronology: server frames are released until the next recorded client frame, then replay waits for the application to send the matching frame before continuing.
+Effect models a WebSocket as a `Socket.Socket` service. A program obtains a scoped `writer` for outgoing frames and runs one receive loop for the lifetime of a connection. The application supplies the live URL-bound socket; the recorder decorates that service without owning its URL, protocols, authentication, timeout, or close policy.
+
+The cassette name is the connection identity during replay. Replay does not validate the live URL or handshake configuration.
 
 ```ts
-import { assert, it } from "@effect/vitest"
+import { it } from "@effect/vitest"
 import { NodeSocket } from "@effect/platform-node"
 import { Effect, Layer } from "effect"
 import { Socket } from "effect/unstable/socket"
 import { HttpRecorder } from "@opencode-ai/http-recorder"
 
-const echo = Effect.gen(function* () {
+const conversation = Effect.gen(function* () {
   const socket = yield* Socket.Socket
   const write = yield* socket.writer
 
-  yield* socket.runString(
-    (message) =>
-      Effect.gen(function* () {
-        assert.strictEqual(message, "hello")
-        yield* write(new Socket.CloseEvent(1000))
-      }),
-    { onOpen: write("hello") },
+  yield* socket.runString((message) =>
+    Effect.gen(function* () {
+      const event: unknown = JSON.parse(message)
+
+      if (typeof event !== "object" || event === null || !("type" in event)) return
+      if (event.type === "session.created") {
+        yield* write(JSON.stringify({ type: "response.create", prompt: "hello" }))
+      }
+      if (event.type === "response.completed") {
+        yield* write(new Socket.CloseEvent(1000, "done"))
+      }
+    }),
   )
 })
 
-const recordedSocket = HttpRecorder.socket("echo/hello").pipe(
+const recordedSocket = HttpRecorder.socket("provider/conversation").pipe(
   Layer.provide(
-    NodeSocket.layerWebSocket("wss://ws.postman-echo.com/raw", {
+    NodeSocket.layerWebSocket("wss://provider.example/realtime", {
       closeCodeIsError: (code) => code !== 1000,
     }),
   ),
 )
 
-it.effect("exchanges WebSocket frames", () => echo.pipe(Effect.provide(recordedSocket)))
+it.effect("completes a provider conversation", () => conversation.pipe(Effect.scoped, Effect.provide(recordedSocket)))
 ```
 
-The application owns the WebSocket URL and protocols through normal Effect layer wiring. The recorder wraps that socket without duplicating its URL in recorder configuration. Provide separate socket layers for separate endpoints or concurrent connections.
+`socket.runString` owns the receive loop and finishes when the connection closes or fails. Its optional `onOpen` effect is the safe place to send protocols whose client speaks first. The writer is scoped because sending is valid only while a connection run is active.
+
+WebSocket cassettes preserve one ordered transcript of client and server text or binary frames. Replay releases recorded server frames until it reaches a client frame, waits for the application to write the matching frame, then continues. This preserves causal ordering without reproducing network timing.
+
+Client text frames containing JSON compare canonically, so object-key order does not matter. Changed fields, extra fields, non-JSON text, and binary frames must match exactly after redaction. There is intentionally no custom WebSocket matcher in this beta.
+
+Incoming frame handlers start in recorded order and may run concurrently, matching Effect's socket abstraction. Replay waits for all handlers before the socket run completes, but handler completion order is not guaranteed. Use Effect synchronization such as `Queue`, `Ref`, or `Deferred` instead of unsynchronized mutable state.
+
+A cassette is written only after the live socket opened and its run completed successfully. Failed, interrupted, unopened, or invalid runs do not produce a recording. During replay, closing before every recorded frame is consumed fails the test.
+
+The application owns the WebSocket URL and protocols through normal Effect layer wiring. Provide separate recorder and live socket layers for separate endpoints or concurrent connections. One recorder layer supports sequential reconnects, but rejects concurrent runs.
 
 Text frames use the same JSON-field and body redaction as HTTP bodies. Binary frames are stored losslessly as base64. Client and server frame kinds must match during replay.
 
@@ -195,6 +212,8 @@ interface RecorderOptions {
   readonly redact?: RedactOptions
   readonly match?: RequestMatcher
 }
+
+type SocketRecorderOptions = Omit<RecorderOptions, "match">
 ```
 
 `directory` defaults to `<cwd>/test/fixtures/recordings`.
@@ -207,7 +226,7 @@ Cassettes are readable JSON files intended to be committed with your tests. HTTP
 
 - Responses are buffered while recording and replaying, so this beta is not suitable for tests that assert streaming timing, cancellation, or backpressure.
 - WebSocket replay preserves frame chronology and content, not real network timing or backpressure.
-- WebSocket V1 cassettes do not reproduce terminal close codes, close reasons, or transport failures. Failed and interrupted live runs are not recorded.
+- WebSocket V1 cassettes do not reproduce terminal close codes, close reasons, handshake configuration, or transport failures. Failed and interrupted live runs are not recorded.
 - WebSocket transcripts are retained in memory until the connection finishes; avoid using this beta for unbounded sessions.
 - The package currently requires the exact Effect beta listed above.
 - Cassette format version `1` has no migration tooling yet.

packages/http-recorder/README.md

@@ -0,0 +1,33 @@
+# Release
+
+`@opencode-ai/http-recorder` is versioned independently from OpenCode and published under the npm `beta` tag.
+
+## Prepare A Release
+
+1. Add a Changeset for every user-facing package change.
+2. Run `bunx changeset status` and confirm that only `@opencode-ai/http-recorder` will be bumped.
+3. Merge the package changes into `dev`.
+4. From a branch based on the latest `dev`, run `bun run version:http-recorder`.
+5. Review the generated version and `packages/http-recorder/CHANGELOG.md`, then open and merge the release PR.
+
+The first minor Changeset advances the unpublished `0.0.0` package to `0.1.0`. OpenCode's repository-wide release script deliberately excludes this package from its version synchronization.
+
+## Verify And Publish
+
+Before merging the release PR, run these commands from `packages/http-recorder`:
+
+```sh
+bun run test
+bun typecheck
+bun run verify:package
+```
+
+After the release PR reaches `dev`, manually dispatch the `http-recorder release` workflow from the `dev` branch. The workflow repeats the focused tests, builds and verifies the exact tarball in a clean npm consumer, and publishes it with provenance under the `beta` tag.
+
+The bootstrap release requires an npm automation token in the repository's `NPM_TOKEN` secret. After the package exists, configure npm trusted publishing for `.github/workflows/http-recorder-release.yml` and the `npm` GitHub environment, then remove the token so later releases use GitHub OIDC.
+
+Verify the result:
+
+```sh
+npm view @opencode-ai/http-recorder version dist-tags --json
+```

packages/http-recorder/RELEASE.md

@@ -1,6 +1,6 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
-  "version": "1.17.9",
+  "version": "0.0.0",
   "name": "@opencode-ai/http-recorder",
   "description": "Record and replay Effect HTTP client traffic with deterministic cassettes",
   "type": "module",
@@ -51,8 +51,7 @@
     "typescript": "catalog:"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.83",
-    "@effect/platform-node-shared": "4.0.0-beta.83"
+    "@effect/platform-node": "4.0.0-beta.83"
   },
   "peerDependencies": {
     "effect": "4.0.0-beta.83"

packages/http-recorder/package.json

@@ -0,0 +1,34 @@
+#!/usr/bin/env bun
+import { $ } from "bun"
+import { fileURLToPath } from "node:url"
+import { pack } from "./pack.js"
+import { verifyPackage } from "./verify-package.js"
+
+const dir = fileURLToPath(new URL("..", import.meta.url))
+process.chdir(dir)
+
+const published = async (name: string, version: string) => {
+  const result = await $`npm view ${name}@${version} version`.quiet().nothrow()
+  if (result.exitCode === 0) return true
+  const stderr = result.stderr.toString()
+  if (stderr.includes("E404")) return false
+  throw new Error(`Failed to check whether ${name}@${version} is published:\n${stderr}`)
+}
+
+// oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion -- package.json is validated by the package schema and build checks.
+const pkg = JSON.parse(await Bun.file("package.json").text()) as { readonly name: string; readonly version: string }
+if (pkg.version === "0.0.0") throw new Error("Version the HTTP recorder before publishing")
+if (!(await Bun.file("CHANGELOG.md").exists()))
+  throw new Error("Generate the HTTP recorder changelog before publishing")
+
+if (await published(pkg.name, pkg.version)) {
+  console.log(`already published ${pkg.name}@${pkg.version}`)
+} else {
+  const archive = await pack()
+  try {
+    await verifyPackage(archive)
+    await $`npm publish ${archive} --tag beta --access public --provenance`
+  } finally {
+    await Bun.file(archive).delete()
+  }
+}