Migrate to @executor-js/emulate 0.7.0's typed control-plane client

0.7.0 ships EmulatorClient + connectEmulator: one typed handle over the
/_emulate control plane (credentials.mint, ledger.list/clear, seed,
reset, manifest, ...) wherever the emulator runs — locally spawned or
hosted. Every hand-rolled fetch + response cast goes away:

- connect-handoff: mints via credentials.mint and asserts against
  LedgerEntry[] (match on request.body) instead of substring-searching
  the raw ledger text.
- targets/cloud setAccessTokenTtl: client.seed() instead of a raw POST.
- CLI ledger command: typed entries, JSON output.
- emulate skill: the client table replaces the raw-endpoint table as
  the primary interface; raw /_emulate stays documented for curl use.

Also folds the CLI onto src/ports.ts claimPorts (from the worktree-env
PR this branch now stacks on) — the CLI's ad-hoc probe-and-walk is
gone; a held block lock marks the instance and releases on down.

Verified: connect-handoff green on selfhost + cloud (the ledger
assertion exercises the hosted resend emulator's typed client), the
token-expiry mcp-execute scenario green on cloud (exercises seed).

Author: RhysSullivan

.claude/skills/emulate/SKILL.md

@@ -17,55 +17,58 @@ auth code.
 
 ## Two ways to get one
 
-**Local, programmatic** (what `e2e/setup/cloud.globalsetup.ts` does):
+**Local, programmatic** (what `e2e/setup/cloud.boot.ts` does):
 
 ```ts
 import { createEmulator } from "@executor-js/emulate";
 const github = await createEmulator({ service: "github", port: 4501 });
-// github.url, github.reset(), await github.close()
+// github.url, await github.close() — plus the full typed client below
 ```
 
 `baseUrl` sets the _advertised_ origin (redirects, form actions, spec
 `servers`) when a proxy fronts the emulator — the bind stays on `port`.
 
-**Hosted, zero-setup** — every service runs on Cloudflare with Durable
-Object state:
+**Attach to a running one** (another process, or hosted on Cloudflare with
+Durable Object state at `https://<service>.emulators.dev` /
+`https://<service>.<instance>.emulators.dev` — catalog at
+`GET https://emulators.dev/_emulate/services`):
 
+```ts
+import { connectEmulator } from "@executor-js/emulate";
+const resend = await connectEmulator({ baseUrl: "https://resend.emulators.dev" });
+// optional: { service: "resend" } verifies the manifest on connect
 ```
-https://<service>.emulators.dev                 # service host
-https://<service>.<instance>.emulators.dev      # your own stateful instance
-GET https://emulators.dev/_emulate/services     # machine-readable catalog
-```
 
-Create a private instance with `POST /_emulate/instances` on the service
-host. The e2e `connect-handoff` scenario uses `https://resend.emulators.dev`
-directly.
+Create a private hosted instance with `POST /_emulate/instances` on the
+service host.
+
+## The typed control-plane client
 
-## The control plane: `/_emulate/*`
+Both `createEmulator` and `connectEmulator` return the same `EmulatorClient`
+surface (since 0.7.0) — use it instead of hand-rolling `/_emulate` fetches:
 
-Every running emulator self-describes. Start at `GET /_emulate/quickstart`
-(plain-text, written for agents) or `GET /_emulate/manifest` (machine-readable:
-surfaces, auth capabilities, per-operation spec coverage, connection snippets).
+| Call                                                               | Use                                                                                                                            |
+| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `client.openapiUrl`                                                | The spec URL — feed it straight to Executor's addSpec to register the emulator as an integration                               |
+| `client.credentials.mint({type:"api-key"})`                        | `IssuedCredential` in the service's real shape: API keys, bearer tokens, OAuth/OIDC clients, client-credentials apps           |
+| `client.ledger.list()` / `.clear()`                                | `LedgerEntry[]`: matched operationId, sanitized headers/body, auth identity, response status, webhook deliveries               |
+| `client.seed({...})`                                               | Add state via the service's seed schema (e.g. WorkOS `{oauth:{default_access_token_ttl_seconds:60}}` to compress token expiry) |
+| `client.reset()`                                                   | Reset state + logs, replay seed — works remotely, unlike the old local-only reset                                              |
+| `client.manifest()` / `.quickstart()` / `.specs()` / `.coverage()` | What the service is, which operations are real vs partial                                                                      |
+| `client.state()` / `.logs()` / `.connections()`                    | Store snapshot, webhook deliveries, copyable SDK/env/curl snippets                                                             |
 
-| Endpoint                     | Use                                                                                                                                 |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `GET /_emulate/openapi`      | A real OpenAPI document for the service — feed it straight to Executor's addSpec to register the emulator as an integration         |
-| `POST /_emulate/credentials` | Mint a credential in the service's real shape: `{"type":"api-key"}`, bearer tokens, OAuth/OIDC clients, client-credentials apps     |
-| `GET /_emulate/ledger`       | Request ledger: matched operationId, sanitized headers/body, auth identity, response status, webhook deliveries. `DELETE` clears it |
-| `POST /_emulate/seed`        | Add state via the service's seed schema (e.g. WorkOS `{"oauth":{"default_access_token_ttl_seconds":60}}` to compress token expiry)  |
-| `POST /_emulate/reset`       | Reset state + logs, replay seed                                                                                                     |
-| `GET /_emulate/state`        | Current store snapshot                                                                                                              |
-| `GET /_emulate/coverage`     | Which operations are implemented vs partial                                                                                         |
-| `GET /_emulate/connections`  | Copyable SDK/env/curl snippets resolved against this instance                                                                       |
+The same routes exist as raw HTTP under `/_emulate/*` (start at
+`GET /_emulate/quickstart`, written for agents) for curl/browser use — but in
+TypeScript, reach for the client; the types are the point.
 
 ## Recipes
 
 **Test an integration end-to-end for real** (the `connect-handoff` pattern):
-mint an API key via `/_emulate/credentials` → register the emulator's
-`/_emulate/openapi` spec with the product → invoke a tool through the
-product → assert the call landed by reading `/_emulate/ledger`. The ledger
-is the proof — "the product made this exact upstream call with this auth" —
-which beats asserting on the product's own response.
+`client.credentials.mint(...)` → register `client.openapiUrl` with the
+product → invoke a tool through the product → find the call in
+`client.ledger.list()` (match on `entry.request.body` / `operationId`). The
+ledger is the proof — "the product made this exact upstream call with this
+auth" — which beats asserting on the product's own response.
 
 **Real OAuth/OIDC flows**: google/okta/microsoft/apple/clerk/workos mint
 OAuth clients and run real authorize/token endpoints. The WorkOS emulator
@@ -75,9 +78,10 @@ clients, and Vault KV. Real SDK + `WORKOS_API_URL` override = the product's
 untouched auth code against it. Set `EMULATE_WORKOS_AUDIENCE=<client_id>`
 before `createEmulator` so minted MCP access tokens carry the right audience.
 
-**A live, human-pokeable cloud instance with zero .env**: see
-`e2e/scripts/cloud-demo.ts` and `e2e/setup/cloud.globalsetup.ts` — WorkOS +
-Autumn emulators + the app's real dev stack.
+**A live, human-pokeable cloud instance with zero .env**:
+`cd e2e && bun run cli up cloud --share` — WorkOS + Autumn emulators + the
+app's real dev stack (recipe in `e2e/setup/cloud.boot.ts`), fronted with
+tailscale HTTPS.
 
 ## Gotchas
 

bun.lock

@@ -18,7 +18,7 @@
   },
   "dependencies": {
     "@executor-js/api": "workspace:*",
-    "@executor-js/emulate": "^0.6.0",
+    "@executor-js/emulate": "^0.7.0",
     "@executor-js/mcporter": "^0.11.4",
     "@executor-js/plugin-graphql": "workspace:*",
     "@executor-js/plugin-mcp": "workspace:*",

e2e/package.json

@@ -18,6 +18,7 @@ import { randomBytes } from "node:crypto";
 import { expect } from "@effect/vitest";
 import { Effect } from "effect";
 import { composePluginApi } from "@executor-js/api/server";
+import { connectEmulator } from "@executor-js/emulate";
 import { openApiHttpPlugin } from "@executor-js/plugin-openapi/api";
 
 import { scenario } from "../src/scenario";
@@ -96,21 +97,16 @@ const executeJson = (session: McpSession, code: string) =>
     return JSON.parse(result.text) as Record<string, unknown>;
   });
 
-const mintEmulatorApiKey = Effect.promise(async () => {
-  const response = await fetch(`${EMULATOR_BASE}/_emulate/credentials`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ type: "api-key" }),
-  });
-  const body = (await response.json()) as { credential?: { token?: string } };
-  const token = body.credential?.token;
-  if (!token) throw new Error(`emulator credential mint failed: ${JSON.stringify(body)}`);
-  return token;
-});
+// The typed control-plane client — minting and ledger reads with real shapes
+// instead of hand-rolled fetch + casts.
+const emulator = Effect.promise(() => connectEmulator({ baseUrl: EMULATOR_BASE }));
 
-const fetchLedgerText = Effect.promise(async () => {
-  const response = await fetch(`${EMULATOR_BASE}/_emulate/ledger`);
-  return response.text();
+const mintEmulatorApiKey = Effect.gen(function* () {
+  const client = yield* emulator;
+  const credential = yield* Effect.promise(() => client.credentials.mint({ type: "api-key" }));
+  const token = credential.token;
+  if (!token) throw new Error(`emulator credential mint failed: ${JSON.stringify(credential)}`);
+  return token;
 });
 
 scenario(
@@ -210,9 +206,13 @@ const runScenario = (input: {
     const sent = yield* executeJson(session, sendEmailCode(integration, emailSubject));
     expect(sent.ok, `email sent through the pasted connection: ${JSON.stringify(sent)}`).toBe(true);
 
-    const ledger = yield* fetchLedgerText;
+    const emulatorClient = yield* emulator;
+    const entries = yield* Effect.promise(() => emulatorClient.ledger.list());
+    const recorded = entries.find((entry) =>
+      JSON.stringify(entry.request.body ?? "").includes(emailSubject),
+    );
     expect(
-      ledger.includes(emailSubject),
+      recorded?.summary,
       "the emulator's request ledger recorded the call made through Executor",
-    ).toBe(true);
+    ).toBeDefined();
   });

e2e/scenarios/connect-handoff.test.ts

@@ -437,8 +437,10 @@ const ledger = async (targetName: string, service = "workos") => {
   const state = readState(targetName);
   const url = state?.urls?.[service];
   if (!url) throw new Error(`no ${service} emulator url recorded for ${targetName}`);
-  const response = await fetch(new URL("/_emulate/ledger", url));
-  console.log(await response.text());
+  const { connectEmulator } = await import("@executor-js/emulate");
+  const client = await connectEmulator({ baseUrl: url });
+  const entries = await client.ledger.list();
+  console.log(JSON.stringify(entries, null, 2));
 };
 
 // --- lifecycle commands ----------------------------------------------------

e2e/scripts/cli.ts

@@ -8,6 +8,8 @@ import { randomUUID } from "node:crypto";
 
 import { Effect } from "effect";
 
+import { connectEmulator } from "@executor-js/emulate";
+
 import { e2ePort } from "../src/ports";
 import type { Identity, Target } from "../src/target";
 
@@ -60,12 +62,10 @@ export const cloudTarget = (): Target => ({
   // scenarios can compress the lifecycle (the TtlControl service).
   setAccessTokenTtl: (seconds) =>
     Effect.promise(async () => {
-      const response = await fetch(`http://127.0.0.1:${WORKOS_EMULATOR_PORT}/_emulate/seed`, {
-        method: "POST",
-        headers: { "content-type": "application/json" },
-        body: JSON.stringify({ oauth: { default_access_token_ttl_seconds: seconds } }),
+      const workos = await connectEmulator({
+        baseUrl: `http://127.0.0.1:${WORKOS_EMULATOR_PORT}`,
       });
-      if (!response.ok) throw new Error(`seeding emulator TTL failed (${response.status})`);
+      await workos.seed({ oauth: { default_access_token_ttl_seconds: seconds } });
     }),
   newIdentity: ({ org = true } = {}) =>
     Effect.promise(async (): Promise<Identity> => {