@dxos/edge-client 0.9.0 → 0.9.1-main.c7dcc2e112

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/edge-client",
-  "version": "0.9.0",
+  "version": "0.9.1-main.c7dcc2e112",
   "description": "EDGE Client",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -28,6 +28,11 @@
       "types": "./dist/types/src/edge-ws-muxer.d.ts",
       "default": "./dist/lib/neutral/edge-ws-muxer.mjs"
     },
+    "./service": {
+      "source": "./src/service/index.ts",
+      "types": "./dist/types/src/service/index.d.ts",
+      "default": "./dist/lib/neutral/service/index.mjs"
+    },
     "./testing": {
       "source": "./src/testing/index.ts",
       "types": "./dist/types/src/testing/index.d.ts",
@@ -45,22 +50,22 @@
     "@opentelemetry/api": "^1.9.1",
     "isomorphic-ws": "^5.0.0",
     "ws": "^8.17.1",
-    "@dxos/async": "0.9.0",
-    "@dxos/context": "0.9.0",
-    "@dxos/credentials": "0.9.0",
-    "@dxos/crypto": "0.9.0",
-    "@dxos/effect": "0.9.0",
-    "@dxos/errors": "0.9.0",
-    "@dxos/invariant": "0.9.0",
-    "@dxos/keyring": "0.9.0",
-    "@dxos/keys": "0.9.0",
-    "@dxos/log": "0.9.0",
-    "@dxos/util": "0.9.0",
-    "@dxos/node-std": "0.9.0",
-    "@dxos/protocols": "0.9.0"
+    "@dxos/context": "0.9.1-main.c7dcc2e112",
+    "@dxos/credentials": "0.9.1-main.c7dcc2e112",
+    "@dxos/async": "0.9.1-main.c7dcc2e112",
+    "@dxos/errors": "0.9.1-main.c7dcc2e112",
+    "@dxos/effect": "0.9.1-main.c7dcc2e112",
+    "@dxos/invariant": "0.9.1-main.c7dcc2e112",
+    "@dxos/keyring": "0.9.1-main.c7dcc2e112",
+    "@dxos/keys": "0.9.1-main.c7dcc2e112",
+    "@dxos/node-std": "0.9.1-main.c7dcc2e112",
+    "@dxos/log": "0.9.1-main.c7dcc2e112",
+    "@dxos/protocols": "0.9.1-main.c7dcc2e112",
+    "@dxos/crypto": "0.9.1-main.c7dcc2e112",
+    "@dxos/util": "0.9.1-main.c7dcc2e112"
   },
   "devDependencies": {
-    "@dxos/test-utils": "0.9.0"
+    "@dxos/test-utils": "0.9.1-main.c7dcc2e112"
   },
   "peerDependencies": {
     "effect": "3.21.3"

package/src/edge-ai-http-client.test.ts

@@ -0,0 +1,37 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import { describe, test } from 'vitest';
+
+import { patchAnthropicMessagesRequestBody } from './edge-ai-http-client';
+
+describe('patchAnthropicMessagesRequestBody', () => {
+  test('adds eager_input_streaming to user-defined tools', ({ expect }) => {
+    const body = JSON.stringify({
+      model: 'claude-sonnet-4-6',
+      stream: true,
+      tools: [
+        {
+          name: 'delegate-task',
+          description: 'Delegate work',
+          input_schema: { type: 'object', properties: { title: { type: 'string' } } },
+        },
+        {
+          name: 'bash',
+          type: 'bash_20250124',
+        },
+      ],
+    });
+
+    const patched = JSON.parse(patchAnthropicMessagesRequestBody(body) as string);
+
+    expect(patched.tools[0]).toMatchObject({ eager_input_streaming: true });
+    expect(patched.tools[1]).not.toHaveProperty('eager_input_streaming');
+  });
+
+  test('leaves non-json bodies unchanged', ({ expect }) => {
+    const body = 'not-json';
+    expect(patchAnthropicMessagesRequestBody(body)).toBe(body);
+  });
+});

package/src/edge-ai-http-client.ts

@@ -31,11 +31,72 @@ export class ByokError extends BaseError.extend('ByokError', 'BYOK authenticatio
   }
 }
 
+/**
+ * Thrown by {@link EdgeAiHttpClient} when EDGE rejects an AI request with 429 because the
+ * authenticated profile exceeded a metering limit. Wrapped as the `cause` of an
+ * {@link HttpClientError.ResponseError} so it survives `@effect/ai`'s error mapping.
+ */
+export class UsageQuotaExceededError extends BaseError.extend('UsageQuotaExceededError', 'Usage quota exceeded') {}
+
 /**
  * Copy pasted from https://github.com/Effect-TS/effect/blob/main/packages/platform/src/internal/fetchHttpClient.ts
  */
 export const requestInitTagKey = '@effect/platform/FetchHttpClient/FetchOptions';
 
+type AnthropicMessagesPayload = {
+  tools?: ReadonlyArray<Record<string, unknown>>;
+};
+
+const isUserDefinedAnthropicTool = (tool: Record<string, unknown>): boolean =>
+  tool.input_schema != null && typeof tool.input_schema === 'object';
+
+/**
+ * Enables Anthropic fine-grained tool input streaming for client-defined tools.
+ * Provider tools (bash, web_search, etc.) are left unchanged.
+ */
+export const patchAnthropicMessagesRequestBody = (body: BodyInit | undefined): BodyInit | undefined => {
+  if (body == null) {
+    return body;
+  }
+
+  const decodeBody = (): string | undefined => {
+    if (typeof body === 'string') {
+      return body;
+    }
+    if (body instanceof Uint8Array) {
+      return new TextDecoder().decode(body);
+    }
+    return undefined;
+  };
+
+  const text = decodeBody();
+  if (text == null) {
+    return body;
+  }
+
+  try {
+    const payload = JSON.parse(text) as AnthropicMessagesPayload;
+    if (!Array.isArray(payload.tools)) {
+      return body;
+    }
+
+    payload.tools = payload.tools.map((tool) =>
+      isUserDefinedAnthropicTool(tool) ? { ...tool, eager_input_streaming: true } : tool,
+    );
+
+    const patched = JSON.stringify(payload);
+    return typeof body === 'string' ? patched : new TextEncoder().encode(patched);
+  } catch {
+    return body;
+  }
+};
+
+const readStreamBody = (stream: ReadableStream<Uint8Array>): Effect.Effect<string | undefined> =>
+  Effect.promise(async () => {
+    const response = new Response(stream);
+    return await response.text();
+  });
+
 /**
  * An `@effect/platform` {@link HttpClient.HttpClient} that routes requests through the
  * authenticated EDGE AI endpoint via {@link EdgeHttpClient.anthropicAiRequest}, instead of
@@ -67,7 +128,7 @@ export class EdgeAiHttpClient {
                 ...options,
                 method: request.method,
                 headers,
-                body,
+                body: patchAnthropicMessagesRequestBody(body),
                 signal,
               }),
             ),
@@ -107,6 +168,27 @@ export class EdgeAiHttpClient {
                 ),
               );
             }
+            // Platform quota (not BYOK): reserve/commit rejected the request before upstream AI.
+            if (!carriedByok && response.status === 429) {
+              return Effect.tryPromise({
+                try: () => response.clone().json() as Promise<{ error?: { message?: string } } | undefined>,
+                catch: () => undefined,
+              }).pipe(
+                Effect.orElseSucceed(() => undefined),
+                Effect.flatMap((body) =>
+                  Effect.fail(
+                    new HttpClientError.ResponseError({
+                      request,
+                      response: httpResponse,
+                      reason: 'StatusCode',
+                      cause: new UsageQuotaExceededError({
+                        message: body?.error?.message,
+                      }),
+                    }),
+                  ),
+                ),
+              );
+            }
             return Effect.succeed(httpResponse);
           }),
         );
@@ -118,7 +200,10 @@ export class EdgeAiHttpClient {
         case 'FormData':
           return send(request.body.formData);
         case 'Stream':
-          return Stream.toReadableStreamEffect(request.body.stream).pipe(Effect.flatMap(send));
+          return Stream.toReadableStreamEffect(request.body.stream).pipe(
+            Effect.flatMap((readable) => readStreamBody(readable)),
+            Effect.flatMap((text) => send(text)),
+          );
       }
 
       return send(undefined);

package/src/edge-http-client.ts

@@ -28,7 +28,6 @@ import {
   type FeedProtocol,
   type GetAgentStatusResponseBody,
   type GetNotarizationResponseBody,
-  type GetPluginVersionsResponseBody,
   type GetPluginsResponseBody,
   type ImportBundleRequest,
   type InitiateOAuthFlowRequest,
@@ -63,6 +62,12 @@ export type EdgeQueryQueueResponse = {
   prevCursor?: string;
 };
 
+export type UploadPluginBundleRequest = {
+  slug: string;
+  version: string;
+  files: { path: string; content: string }[];
+};
+
 export type TriggersDispatcherStatus = {
   isActive: boolean;
   nextCronTaskRunTimestamp?: number;
@@ -379,14 +384,21 @@ export class EdgeHttpClient extends BaseHttpClient {
     return this._call(ctx, new URL('/registry/plugins', this.baseUrl), { ...args, method: 'GET' });
   }
 
-  public async getRegistryPluginVersions(
+  /**
+   * Uploads a built plugin bundle to the registry's R2-backed hosting. Authenticated
+   * with the caller's hub identity (verifiable presentation) — `setIdentity` must
+   * have been called. Returns the canonical `moduleUrl` (the hosted `manifest.json`).
+   */
+  public async uploadPluginBundle(
     ctx: Context,
-    repo: string,
+    request: UploadPluginBundleRequest,
     args?: EdgeHttpCallArgs,
-  ): Promise<GetPluginVersionsResponseBody> {
-    return this._call(ctx, new URL(`/registry/plugins/${encodeURIComponent(repo)}/versions`, this.baseUrl), {
+  ): Promise<{ moduleUrl: string }> {
+    return this._call(ctx, new URL('/registry/upload', this.baseUrl), {
+      body: request,
+      method: 'POST',
+      auth: true,
       ...args,
-      method: 'GET',
     });
   }
 

package/src/hub-http-client.ts

@@ -14,9 +14,11 @@ import {
   type RedeemInvitationCodeResponse,
   type RequestAccessRequest,
   type RequestAccessResponse,
+  type GetProfileUsageResponse,
   type ResendVerificationEmailResponse,
   type ValidateInvitationCodeResponse,
 } from '@dxos/protocols';
+import { createUrl } from '@dxos/util';
 
 import { BaseHttpClient, type BaseHttpClientOptions, type EdgeHttpCallArgs } from './base-http-client';
 
@@ -115,4 +117,22 @@ export class HubHttpClient extends BaseHttpClient {
   ): Promise<ResendVerificationEmailResponse> {
     return this._call(ctx, new URL('/account/email/resend-verification', this.baseUrl), { ...args, method: 'POST' });
   }
+
+  /**
+   * Rolling-window usage and effective limits for the authenticated identity.
+   * Served from the per-user metering DO; optional `windowSeconds` defaults to the largest limit window.
+   */
+  public async getProfileUsage(
+    ctx: Context,
+    query?: { windowSeconds?: number },
+    args?: EdgeHttpCallArgs,
+  ): Promise<GetProfileUsageResponse> {
+    return this._call(
+      ctx,
+      createUrl(new URL('/api/metering/profile/usage', this.baseUrl), {
+        windowSeconds: query?.windowSeconds,
+      }),
+      { ...args, method: 'GET' },
+    );
+  }
 }

package/src/service/Image.ts

@@ -0,0 +1,61 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// @import-as-namespace
+
+// Image service helpers built on the generic {@link EdgeServiceClient}. The
+// worker exposes two contract-identical routes (`/upload` and `/thumbnail`,
+// both returning `{ id, url }`); we mirror them so callers stay on whichever
+// route they already use.
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+import { type EdgeServiceClient, type EdgeServiceError } from './edge-service';
+
+/**
+ * Default Composer image-service base URL — the Cloudflare Worker used in
+ * production. Override per-environment via the client's `baseUrl`.
+ */
+// TODO(burdon): Get from config.
+export const DEFAULT_IMAGE_SERVICE_URL = 'https://image-service-main.dxos.workers.dev';
+
+/** Hosted image returned by the service: a CDN `url` and its storage `id`. */
+export const Result = Schema.Struct({
+  id: Schema.optional(Schema.String),
+  url: Schema.String,
+});
+export type Result = typeof Result.Type;
+
+export type UploadOptions = {
+  /** Multipart field name. */
+  field?: string;
+  /** Upload filename. */
+  filename?: string;
+};
+
+/** Store an image and return its hosted CDN URL (POST `/upload`). */
+export const upload = (
+  client: EdgeServiceClient,
+  blob: Blob,
+  opts?: UploadOptions,
+): Effect.Effect<Result, EdgeServiceError> => uploadToPath(client, blob, '/upload', opts);
+
+/** Store an image and create a thumbnail, returning its hosted CDN URL (POST `/thumbnail`). */
+export const thumbnail = (
+  client: EdgeServiceClient,
+  blob: Blob,
+  opts?: UploadOptions,
+): Effect.Effect<Result, EdgeServiceError> => uploadToPath(client, blob, '/thumbnail', opts);
+
+const uploadToPath = (
+  client: EdgeServiceClient,
+  blob: Blob,
+  path: string,
+  opts?: UploadOptions,
+): Effect.Effect<Result, EdgeServiceError> => {
+  const form = new FormData();
+  form.append(opts?.field ?? 'file', blob, opts?.filename ?? 'image');
+  return client.postForm(path, form, Result);
+};

package/src/service/edge-service.test.ts

@@ -0,0 +1,151 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { describe, test } from 'vitest';
+
+import { EffectEx } from '@dxos/effect';
+
+import { EdgeServiceClient, EdgeServiceError } from './edge-service';
+import * as Image from './Image';
+
+const Echo = Schema.Struct({ value: Schema.String });
+
+// Minimal Response stub so tests stay free of a real fetch implementation.
+type StubResponse = {
+  ok: boolean;
+  status: number;
+  json?: () => Promise<unknown>;
+  text?: () => Promise<string>;
+};
+
+type Captured = { url: string; init: RequestInit };
+
+const stubFetch = (
+  handler: (captured: Captured) => StubResponse | Promise<StubResponse>,
+): { fetch: typeof globalThis.fetch; calls: Captured[] } => {
+  const calls: Captured[] = [];
+  const fetch = (async (input: any, init: any) => {
+    const captured: Captured = { url: input.toString(), init: init ?? {} };
+    calls.push(captured);
+    return (await handler(captured)) as unknown as Response;
+  }) as typeof globalThis.fetch;
+  return { fetch, calls };
+};
+
+const json = (body: unknown, status = 200): StubResponse => ({
+  ok: status >= 200 && status < 300,
+  status,
+  json: () => Promise.resolve(body),
+  text: () => Promise.resolve(JSON.stringify(body)),
+});
+
+describe('EdgeServiceClient', () => {
+  test('postJson resolves and decodes the response', async ({ expect }) => {
+    const { fetch, calls } = stubFetch(() => json({ value: 'pong' }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+
+    const result = await EffectEx.runPromise(client.postJson('/ping', { ping: true }, Echo));
+    expect(result).toEqual({ value: 'pong' });
+    expect(calls[0].url).toBe('https://edge.test/ping');
+    expect((calls[0].init.headers as Headers).get('Content-Type')).toBe('application/json');
+  });
+
+  test('sets the client-tag header when configured', async ({ expect }) => {
+    const { fetch, calls } = stubFetch(() => json({ value: 'ok' }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', clientTag: 'ci-e2e', fetch });
+
+    await EffectEx.runPromise(client.postJson('/ping', {}, Echo));
+    expect((calls[0].init.headers as Headers).get('X-DXOS-Client-Tag')).toBe('ci-e2e');
+  });
+
+  test('merges authHeaders when provided', async ({ expect }) => {
+    const { fetch, calls } = stubFetch(() => json({ value: 'ok' }));
+    const client = new EdgeServiceClient({
+      baseUrl: 'https://edge.test',
+      fetch,
+      authHeaders: () => Effect.succeed({ Authorization: 'Bearer xyz' }),
+    });
+
+    await EffectEx.runPromise(client.postJson('/ping', {}, Echo));
+    expect((calls[0].init.headers as Headers).get('Authorization')).toBe('Bearer xyz');
+  });
+
+  test('non-2xx fails with EdgeServiceError carrying the status', async ({ expect }) => {
+    const { fetch } = stubFetch(() => ({ ok: false, status: 422, text: () => Promise.resolve('bad image') }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+
+    const error = await EffectEx.runPromise(Effect.flip(client.postForm('/upload', new FormData(), Echo)));
+    expect(error).toBeInstanceOf(EdgeServiceError);
+    expect(error.status).toBe(422);
+    expect(error.message).toContain('bad image');
+  });
+
+  test('malformed JSON fails with EdgeServiceError', async ({ expect }) => {
+    const { fetch } = stubFetch(() => ({
+      ok: true,
+      status: 200,
+      json: () => Promise.reject(new Error('Unexpected token')),
+    }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+
+    const error = await EffectEx.runPromise(Effect.flip(client.postJson('/ping', {}, Echo)));
+    expect(error).toBeInstanceOf(EdgeServiceError);
+    expect(error.message).toContain('parse JSON');
+  });
+
+  test('schema mismatch fails with EdgeServiceError', async ({ expect }) => {
+    const { fetch } = stubFetch(() => json({ wrong: 'shape' }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+
+    const error = await EffectEx.runPromise(Effect.flip(client.postJson('/ping', {}, Echo)));
+    expect(error).toBeInstanceOf(EdgeServiceError);
+    expect(error.message).toContain('schema');
+  });
+
+  test('non-serializable body fails with EdgeServiceError, not a synchronous throw', async ({ expect }) => {
+    const { fetch } = stubFetch(() => json({ value: 'ok' }));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+
+    const error = await EffectEx.runPromise(Effect.flip(client.postJson('/ping', circular, Echo)));
+    expect(error).toBeInstanceOf(EdgeServiceError);
+    expect(error.message).toContain('serialize');
+  });
+
+  test('transport rejection fails with EdgeServiceError', async ({ expect }) => {
+    const { fetch } = stubFetch(() => Promise.reject(new Error('ECONNREFUSED')));
+    const client = new EdgeServiceClient({ baseUrl: 'https://edge.test', fetch });
+
+    const error = await EffectEx.runPromise(Effect.flip(client.postJson('/ping', {}, Echo)));
+    expect(error).toBeInstanceOf(EdgeServiceError);
+    expect(error.cause).toBeInstanceOf(Error);
+  });
+});
+
+describe('Image', () => {
+  test('upload posts file field to /upload and returns the hosted URL', async ({ expect }) => {
+    const { fetch, calls } = stubFetch(() => json({ id: 'abc', url: 'https://cdn.test/abc/public' }));
+    const client = new EdgeServiceClient({ baseUrl: Image.DEFAULT_IMAGE_SERVICE_URL, fetch });
+    const blob = new Blob([new Uint8Array([1, 2, 3])], { type: 'image/png' });
+
+    const result = await EffectEx.runPromise(Image.upload(client, blob, { filename: 'pic.png' }));
+    expect(result).toEqual({ id: 'abc', url: 'https://cdn.test/abc/public' });
+    expect(calls[0].url).toBe(`${Image.DEFAULT_IMAGE_SERVICE_URL}/upload`);
+    const form = calls[0].init.body as FormData;
+    expect(form.get('file')).toBeInstanceOf(Blob);
+  });
+
+  test('thumbnail posts to /thumbnail', async ({ expect }) => {
+    const { fetch, calls } = stubFetch(() => json({ url: 'https://cdn.test/x/public' }));
+    const client = new EdgeServiceClient({ baseUrl: Image.DEFAULT_IMAGE_SERVICE_URL, fetch });
+    const blob = new Blob([new Uint8Array([1])], { type: 'image/png' });
+
+    const result = await EffectEx.runPromise(Image.thumbnail(client, blob));
+    expect(result.url).toBe('https://cdn.test/x/public');
+    expect(calls[0].url).toBe(`${Image.DEFAULT_IMAGE_SERVICE_URL}/thumbnail`);
+  });
+});

package/src/service/edge-service.ts

@@ -0,0 +1,139 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Lightweight client for EDGE-hosted HTTP services — intentionally free of the
+// heavy transitive dependencies (`@dxos/context`, `@dxos/protocols`) that
+// `BaseHttpClient` pulls in, so it bundles cleanly into browser / workerd. The
+// only runtime dependencies are `effect` and `@dxos/log`.
+
+import * as Data from 'effect/Data';
+import * as Duration from 'effect/Duration';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+
+// Matches EDGE_CLIENT_TAG_HEADER from @dxos/protocols. Duplicated here (as in
+// `cors-proxy`) to avoid importing the heavy protocols bundle.
+const EDGE_CLIENT_TAG_HEADER = 'X-DXOS-Client-Tag';
+
+const DEFAULT_TIMEOUT = Duration.seconds(15);
+
+/** Number of body characters retained for the error message on a non-2xx response. */
+const ERROR_BODY_LIMIT = 512;
+
+export type EdgeServiceClientOptions = {
+  /** Base URL the service is hosted at; request paths resolve against it. */
+  baseUrl: string;
+  /** Tag included in the {@link EDGE_CLIENT_TAG_HEADER} header for metering. */
+  clientTag?: string;
+  /** Per-request timeout. */
+  timeout?: Duration.DurationInput;
+  /** Injectable for deterministic tests; defaults to `globalThis.fetch`. */
+  fetch?: typeof globalThis.fetch;
+  /** Auth seam invoked per request; unused by the image service today. */
+  authHeaders?: () => Effect.Effect<Record<string, string>>;
+};
+
+/** Single failure type for every transport, status, and decode error. */
+export class EdgeServiceError extends Data.TaggedError('EdgeServiceError')<{
+  message: string;
+  status?: number;
+  cause?: unknown;
+}> {}
+
+export class EdgeServiceClient {
+  readonly #baseUrl: string;
+  readonly #clientTag: string | undefined;
+  readonly #timeout: Duration.Duration;
+  readonly #fetch: typeof globalThis.fetch;
+  readonly #authHeaders: (() => Effect.Effect<Record<string, string>>) | undefined;
+
+  constructor(options: EdgeServiceClientOptions) {
+    this.#baseUrl = options.baseUrl;
+    this.#clientTag = options.clientTag;
+    this.#timeout = Duration.decode(options.timeout ?? DEFAULT_TIMEOUT);
+    // Bind so `fetch` keeps its expected `this` when injected as a method reference.
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    this.#fetch = fetchImpl.bind(globalThis);
+    this.#authHeaders = options.authHeaders;
+  }
+
+  get baseUrl(): string {
+    return this.#baseUrl;
+  }
+
+  /** POST a `FormData` (multipart) body and decode the JSON response. */
+  postForm<A>(path: string, form: FormData, schema: Schema.Schema<A>): Effect.Effect<A, EdgeServiceError> {
+    // The runtime sets `Content-Type: multipart/form-data` with the boundary;
+    // setting it manually here would omit the boundary and break parsing.
+    return this.#request(path, schema, { method: 'POST', body: form });
+  }
+
+  /** POST a JSON body and decode the JSON response. */
+  postJson<A>(path: string, body: unknown, schema: Schema.Schema<A>): Effect.Effect<A, EdgeServiceError> {
+    // Serialize inside the Effect so a circular/non-serializable body surfaces as
+    // EdgeServiceError rather than throwing synchronously from the call site.
+    return Effect.try({
+      try: () => JSON.stringify(body),
+      catch: (cause) => new EdgeServiceError({ message: 'Failed to serialize JSON request body', cause }),
+    }).pipe(
+      Effect.flatMap((json) =>
+        this.#request(path, schema, {
+          method: 'POST',
+          body: json,
+          headers: { 'Content-Type': 'application/json' },
+        }),
+      ),
+    );
+  }
+
+  #request<A>(path: string, schema: Schema.Schema<A>, init: RequestInit): Effect.Effect<A, EdgeServiceError> {
+    return Effect.gen(this, function* () {
+      const url = new URL(path, this.#baseUrl);
+      const headers = new Headers(init.headers ?? undefined);
+      if (this.#clientTag) {
+        headers.set(EDGE_CLIENT_TAG_HEADER, this.#clientTag);
+      }
+      if (this.#authHeaders) {
+        const auth = yield* this.#authHeaders();
+        for (const [key, value] of Object.entries(auth)) {
+          headers.set(key, value);
+        }
+      }
+
+      const response = yield* Effect.tryPromise({
+        try: (signal) => this.#fetch(url, { ...init, headers, signal }),
+        catch: (cause) => new EdgeServiceError({ message: `Request to ${url.pathname} failed`, cause }),
+      });
+
+      if (!response.ok) {
+        // Body text aids debugging but may be large; truncate and never throw on read.
+        const detail = yield* Effect.promise(() => response.text().catch(() => '')).pipe(
+          Effect.map((text) => text.slice(0, ERROR_BODY_LIMIT)),
+        );
+        return yield* new EdgeServiceError({
+          message: `Service responded ${response.status}${detail ? `: ${detail}` : ''}`,
+          status: response.status,
+        });
+      }
+
+      const json = yield* Effect.tryPromise({
+        try: () => response.json(),
+        catch: (cause) =>
+          new EdgeServiceError({ message: 'Failed to parse JSON response', status: response.status, cause }),
+      });
+
+      return yield* Schema.decodeUnknown(schema)(json).pipe(
+        Effect.mapError(
+          (cause) =>
+            new EdgeServiceError({ message: 'Response did not match expected schema', status: response.status, cause }),
+        ),
+      );
+    }).pipe(
+      Effect.timeoutFail({
+        duration: this.#timeout,
+        onTimeout: () => new EdgeServiceError({ message: `Request to ${path} timed out` }),
+      }),
+    );
+  }
+}