feat(sdk): add HttpApi clients and embedded host (#33445)

packages/client/README.md

@@ -0,0 +1,27 @@
+# @opencode-ai/client
+
+Private generation target for clients derived directly from OpenCode's authoritative Effect `HttpApi`.
+
+## Entrypoints
+
+- `@opencode-ai/client`: zero-Effect Promise client using `fetch`.
+- `@opencode-ai/client/effect`: rich Effect network client using an environment-provided `HttpClient`.
+
+The generated surface starts with the Session group from Server's concrete API. The build compiler reads `@opencode-ai/server/api`; the generated Effect runtime imports a client-local projection built from Protocol, with a generation-equivalence test preventing transport drift. Run `bun run generate` after changing the contract and `bun run check:generated` to detect committed-output drift.
+
+The Effect entrypoint uses canonical decoded values such as `Session.ID`, `Location.Ref`, and `Prompt`. These datatypes come from the lightweight `@opencode-ai/schema` package and are re-exported so callers depend only on the client surface. Protocol owns endpoint construction and middleware placement; Server supplies the concrete middleware keys used by the build-time API.
+
+The Promise root remains structural and has no Core or Effect runtime dependency. `/effect` depends only on Effect, Schema, and Protocol and is browser-bundle safe. Bundle-boundary tests enforce both import graphs.
+
+Effect consumers construct canonical decoded inputs:
+
+```ts
+import { AbsolutePath, Location, OpenCode, Prompt } from "@opencode-ai/client/effect"
+
+const client = yield * OpenCode.make({ baseUrl: "https://opencode.example" })
+yield *
+  client.sessions.create({
+    location: Location.Ref.make({ directory: AbsolutePath.make("/workspace") }),
+  })
+yield * client.sessions.prompt({ sessionID, prompt: Prompt.make({ text: "Hello" }) })
+```

packages/client/package.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "https://json.schemastore.org/package.json",
+  "name": "@opencode-ai/client",
+  "private": true,
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./src/index.ts",
+    "./effect": "./src/effect.ts"
+  },
+  "scripts": {
+    "generate": "bun run script/build.ts",
+    "check:generated": "bun run generate && git diff --exit-code -- src/generated src/generated-effect",
+    "test": "bun test --timeout 5000",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@opencode-ai/schema": "workspace:*",
+    "@opencode-ai/protocol": "workspace:*"
+  },
+  "peerDependencies": {
+    "effect": "4.0.0-beta.83"
+  },
+  "peerDependenciesMeta": {
+    "effect": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@effect/platform-node": "catalog:",
+    "@opencode-ai/core": "workspace:*",
+    "@opencode-ai/httpapi-codegen": "workspace:*",
+    "@opencode-ai/server": "workspace:*",
+    "@tsconfig/bun": "catalog:",
+    "@types/bun": "catalog:",
+    "@typescript/native-preview": "catalog:",
+    "effect": "catalog:"
+  }
+}

packages/client/script/build.ts

@@ -0,0 +1,23 @@
+import { NodeFileSystem } from "@effect/platform-node"
+import { compile, emitEffectImported, emitPromise, write } from "@opencode-ai/httpapi-codegen"
+import { Api } from "@opencode-ai/server/api"
+import { Effect } from "effect"
+import { HttpApi } from "effect/unstable/httpapi"
+import { fileURLToPath } from "url"
+
+const contract = compile(HttpApi.make("opencode-client").add(Api.groups["server.session"]), {
+  groupNames: { "server.session": "sessions" },
+})
+
+await Effect.runPromise(
+  Effect.all(
+    [
+      write(emitPromise(contract), fileURLToPath(new URL("../src/generated", import.meta.url))),
+      write(
+        emitEffectImported(contract, { module: "../contract", group: "SessionGroup" }),
+        fileURLToPath(new URL("../src/generated-effect", import.meta.url)),
+      ),
+    ],
+    { concurrency: 2, discard: true },
+  ).pipe(Effect.provide(NodeFileSystem.layer)),
+)

packages/client/src/contract.ts

@@ -0,0 +1,19 @@
+import { makeDefaultApi } from "@opencode-ai/protocol/api"
+import { InvalidRequestError, SessionNotFoundError } from "@opencode-ai/protocol/errors"
+import { HttpApiMiddleware } from "effect/unstable/httpapi"
+
+class LocationMiddleware extends HttpApiMiddleware.Service<LocationMiddleware>()(
+  "@opencode-ai/client/LocationMiddleware",
+) {}
+
+class SessionLocationMiddleware extends HttpApiMiddleware.Service<SessionLocationMiddleware>()(
+  "@opencode-ai/client/SessionLocationMiddleware",
+  { error: [InvalidRequestError, SessionNotFoundError] },
+) {}
+
+const Api = makeDefaultApi({
+  locationMiddleware: LocationMiddleware,
+  sessionLocationMiddleware: SessionLocationMiddleware,
+})
+
+export const SessionGroup = Api.groups["server.session"]

packages/client/src/effect.ts

@@ -0,0 +1,12 @@
+// TODO: Keep additional network capabilities inside Schema and Protocol as the client grows; /effect must never import
+// Core or Server. Preserve these datatype exports so internal model reorganizations do not require caller migrations.
+export * from "./generated-effect/index"
+export { Agent } from "@opencode-ai/schema/agent"
+export { Location } from "@opencode-ai/schema/location"
+export { Model } from "@opencode-ai/schema/model"
+export { Provider } from "@opencode-ai/schema/provider"
+export { AbsolutePath, RelativePath } from "@opencode-ai/schema/schema"
+export { Session } from "@opencode-ai/schema/session"
+export { SessionInput } from "@opencode-ai/schema/session-input"
+export { SessionMessage } from "@opencode-ai/schema/session-message"
+export { Prompt } from "@opencode-ai/schema/prompt"

packages/client/src/generated-effect/.httpapi-codegen.json

@@ -0,0 +1,5 @@
+[
+  "client-error.ts",
+  "client.ts",
+  "index.ts"
+]

packages/client/src/generated-effect/client-error.ts

@@ -0,0 +1,5 @@
+import { Schema } from "effect"
+
+export class ClientError extends Schema.TaggedErrorClass<ClientError>()("ClientError", {
+  cause: Schema.Defect(),
+}) {}

packages/client/src/generated-effect/client.ts

@@ -0,0 +1,164 @@
+// Generated by @opencode-ai/httpapi-codegen. Do not edit.
+import { Effect, Schema } from "effect"
+import { Sse } from "effect/unstable/encoding"
+import { HttpClientError } from "effect/unstable/http"
+import { HttpApi, HttpApiClient } from "effect/unstable/httpapi"
+import { SessionGroup } from "../contract"
+import { ClientError } from "./client-error"
+
+const Api = HttpApi.make("generated").add(SessionGroup)
+
+type RawClient = HttpApiClient.ForApi<typeof Api>
+
+const mapClientError = <E>(error: E) =>
+  HttpClientError.isHttpClientError(error) || Schema.isSchemaError(error) || Sse.Retry.is(error)
+    ? new ClientError({ cause: error })
+    : error
+
+type Endpoint0_0Request = Parameters<RawClient["server.session"]["session.list"]>[0]
+type Endpoint0_0Input = {
+  readonly workspace?: Endpoint0_0Request["query"]["workspace"]
+  readonly limit?: Endpoint0_0Request["query"]["limit"]
+  readonly order?: Endpoint0_0Request["query"]["order"]
+  readonly search?: Endpoint0_0Request["query"]["search"]
+  readonly directory?: Endpoint0_0Request["query"]["directory"]
+  readonly project?: Endpoint0_0Request["query"]["project"]
+  readonly subpath?: Endpoint0_0Request["query"]["subpath"]
+  readonly cursor?: Endpoint0_0Request["query"]["cursor"]
+}
+const Endpoint0_0 = (raw: RawClient["server.session"]) => (input?: Endpoint0_0Input) =>
+  raw["session.list"]({
+    query: {
+      workspace: input?.workspace,
+      limit: input?.limit,
+      order: input?.order,
+      search: input?.search,
+      directory: input?.directory,
+      project: input?.project,
+      subpath: input?.subpath,
+      cursor: input?.cursor,
+    },
+  }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint0_1Request = Parameters<RawClient["server.session"]["session.create"]>[0]
+type Endpoint0_1Input = {
+  readonly id?: Endpoint0_1Request["payload"]["id"]
+  readonly agent?: Endpoint0_1Request["payload"]["agent"]
+  readonly model?: Endpoint0_1Request["payload"]["model"]
+  readonly location?: Endpoint0_1Request["payload"]["location"]
+}
+const Endpoint0_1 = (raw: RawClient["server.session"]) => (input?: Endpoint0_1Input) =>
+  raw["session.create"]({
+    payload: { id: input?.id, agent: input?.agent, model: input?.model, location: input?.location },
+  }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+type Endpoint0_2Request = Parameters<RawClient["server.session"]["session.get"]>[0]
+type Endpoint0_2Input = { readonly sessionID: Endpoint0_2Request["params"]["sessionID"] }
+const Endpoint0_2 = (raw: RawClient["server.session"]) => (input: Endpoint0_2Input) =>
+  raw["session.get"]({ params: { sessionID: input.sessionID } }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+type Endpoint0_3Request = Parameters<RawClient["server.session"]["session.switchAgent"]>[0]
+type Endpoint0_3Input = {
+  readonly sessionID: Endpoint0_3Request["params"]["sessionID"]
+  readonly agent: Endpoint0_3Request["payload"]["agent"]
+}
+const Endpoint0_3 = (raw: RawClient["server.session"]) => (input: Endpoint0_3Input) =>
+  raw["session.switchAgent"]({ params: { sessionID: input.sessionID }, payload: { agent: input.agent } }).pipe(
+    Effect.mapError(mapClientError),
+  )
+
+type Endpoint0_4Request = Parameters<RawClient["server.session"]["session.switchModel"]>[0]
+type Endpoint0_4Input = {
+  readonly sessionID: Endpoint0_4Request["params"]["sessionID"]
+  readonly model: Endpoint0_4Request["payload"]["model"]
+}
+const Endpoint0_4 = (raw: RawClient["server.session"]) => (input: Endpoint0_4Input) =>
+  raw["session.switchModel"]({ params: { sessionID: input.sessionID }, payload: { model: input.model } }).pipe(
+    Effect.mapError(mapClientError),
+  )
+
+type Endpoint0_5Request = Parameters<RawClient["server.session"]["session.prompt"]>[0]
+type Endpoint0_5Input = {
+  readonly sessionID: Endpoint0_5Request["params"]["sessionID"]
+  readonly id?: Endpoint0_5Request["payload"]["id"]
+  readonly prompt: Endpoint0_5Request["payload"]["prompt"]
+  readonly delivery?: Endpoint0_5Request["payload"]["delivery"]
+  readonly resume?: Endpoint0_5Request["payload"]["resume"]
+}
+const Endpoint0_5 = (raw: RawClient["server.session"]) => (input: Endpoint0_5Input) =>
+  raw["session.prompt"]({
+    params: { sessionID: input.sessionID },
+    payload: { id: input.id, prompt: input.prompt, delivery: input.delivery, resume: input.resume },
+  }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+type Endpoint0_6Request = Parameters<RawClient["server.session"]["session.compact"]>[0]
+type Endpoint0_6Input = { readonly sessionID: Endpoint0_6Request["params"]["sessionID"] }
+const Endpoint0_6 = (raw: RawClient["server.session"]) => (input: Endpoint0_6Input) =>
+  raw["session.compact"]({ params: { sessionID: input.sessionID } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint0_7Request = Parameters<RawClient["server.session"]["session.wait"]>[0]
+type Endpoint0_7Input = { readonly sessionID: Endpoint0_7Request["params"]["sessionID"] }
+const Endpoint0_7 = (raw: RawClient["server.session"]) => (input: Endpoint0_7Input) =>
+  raw["session.wait"]({ params: { sessionID: input.sessionID } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint0_8Request = Parameters<RawClient["server.session"]["session.revert.stage"]>[0]
+type Endpoint0_8Input = {
+  readonly sessionID: Endpoint0_8Request["params"]["sessionID"]
+  readonly messageID: Endpoint0_8Request["payload"]["messageID"]
+  readonly files?: Endpoint0_8Request["payload"]["files"]
+}
+const Endpoint0_8 = (raw: RawClient["server.session"]) => (input: Endpoint0_8Input) =>
+  raw["session.revert.stage"]({
+    params: { sessionID: input.sessionID },
+    payload: { messageID: input.messageID, files: input.files },
+  }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+type Endpoint0_9Request = Parameters<RawClient["server.session"]["session.revert.clear"]>[0]
+type Endpoint0_9Input = { readonly sessionID: Endpoint0_9Request["params"]["sessionID"] }
+const Endpoint0_9 = (raw: RawClient["server.session"]) => (input: Endpoint0_9Input) =>
+  raw["session.revert.clear"]({ params: { sessionID: input.sessionID } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint0_10Request = Parameters<RawClient["server.session"]["session.revert.commit"]>[0]
+type Endpoint0_10Input = { readonly sessionID: Endpoint0_10Request["params"]["sessionID"] }
+const Endpoint0_10 = (raw: RawClient["server.session"]) => (input: Endpoint0_10Input) =>
+  raw["session.revert.commit"]({ params: { sessionID: input.sessionID } }).pipe(Effect.mapError(mapClientError))
+
+type Endpoint0_11Request = Parameters<RawClient["server.session"]["session.context"]>[0]
+type Endpoint0_11Input = { readonly sessionID: Endpoint0_11Request["params"]["sessionID"] }
+const Endpoint0_11 = (raw: RawClient["server.session"]) => (input: Endpoint0_11Input) =>
+  raw["session.context"]({ params: { sessionID: input.sessionID } }).pipe(
+    Effect.mapError(mapClientError),
+    Effect.map((value) => value.data),
+  )
+
+const adaptGroup0 = (raw: RawClient["server.session"]) => ({
+  list: Endpoint0_0(raw),
+  create: Endpoint0_1(raw),
+  get: Endpoint0_2(raw),
+  switchAgent: Endpoint0_3(raw),
+  switchModel: Endpoint0_4(raw),
+  prompt: Endpoint0_5(raw),
+  compact: Endpoint0_6(raw),
+  wait: Endpoint0_7(raw),
+  stage: Endpoint0_8(raw),
+  clear: Endpoint0_9(raw),
+  commit: Endpoint0_10(raw),
+  context: Endpoint0_11(raw),
+})
+
+const adaptClient = (raw: RawClient) => ({ sessions: adaptGroup0(raw["server.session"]) })
+
+export const make = (options?: { readonly baseUrl?: URL | string }) =>
+  HttpApiClient.make(Api, options).pipe(Effect.map(adaptClient))

packages/client/src/generated-effect/index.ts

@@ -0,0 +1,2 @@
+export { ClientError } from "./client-error"
+export * as OpenCode from "./client"

packages/client/src/generated/.httpapi-codegen.json

@@ -0,0 +1,6 @@
+[
+  "client-error.ts",
+  "client.ts",
+  "index.ts",
+  "types.ts"
+]

packages/client/src/generated/client-error.ts

@@ -0,0 +1,11 @@
+export type ClientErrorReason = "Transport" | "UnexpectedStatus" | "UnsupportedContentType" | "MalformedResponse"
+
+export class ClientError extends Error {
+  override readonly name = "ClientError"
+  constructor(
+    readonly reason: ClientErrorReason,
+    options?: ErrorOptions,
+  ) {
+    super(reason, options)
+  }
+}

packages/client/src/generated/client.ts

@@ -0,0 +1,349 @@
+import type {
+  SessionsListInput,
+  SessionsListOutput,
+  SessionsCreateInput,
+  SessionsCreateOutput,
+  SessionsGetInput,
+  SessionsGetOutput,
+  SessionsSwitchAgentInput,
+  SessionsSwitchAgentOutput,
+  SessionsSwitchModelInput,
+  SessionsSwitchModelOutput,
+  SessionsPromptInput,
+  SessionsPromptOutput,
+  SessionsCompactInput,
+  SessionsCompactOutput,
+  SessionsWaitInput,
+  SessionsWaitOutput,
+  SessionsStageInput,
+  SessionsStageOutput,
+  SessionsClearInput,
+  SessionsClearOutput,
+  SessionsCommitInput,
+  SessionsCommitOutput,
+  SessionsContextInput,
+  SessionsContextOutput,
+} from "./types"
+import { ClientError } from "./client-error"
+
+export interface ClientOptions {
+  readonly baseUrl: string
+  readonly fetch?: typeof globalThis.fetch
+  readonly headers?: HeadersInit
+}
+
+export interface RequestOptions {
+  readonly signal?: AbortSignal
+  readonly headers?: HeadersInit
+}
+
+interface RequestDescriptor {
+  readonly method: string
+  readonly path: string
+  readonly query?: Record<string, unknown>
+  readonly headers?: Record<string, unknown>
+  readonly body?: unknown
+  readonly successStatus: number
+  readonly declaredStatuses: ReadonlyArray<number>
+  readonly empty: boolean
+}
+
+export function make(options: ClientOptions) {
+  const fetch = options.fetch ?? globalThis.fetch
+
+  const prepare = (descriptor: RequestDescriptor, requestOptions?: RequestOptions) => {
+    const url = new URL(descriptor.path, options.baseUrl)
+    for (const [key, value] of Object.entries(descriptor.query ?? {})) appendQuery(url.searchParams, key, value)
+    const headers = new Headers(options.headers)
+    for (const [key, value] of Object.entries(descriptor.headers ?? {})) {
+      if (value !== undefined && value !== null) headers.set(key, String(value))
+    }
+    for (const [key, value] of new Headers(requestOptions?.headers)) headers.set(key, value)
+    if (descriptor.body !== undefined && !headers.has("content-type")) headers.set("content-type", "application/json")
+    return {
+      url,
+      init: {
+        method: descriptor.method,
+        signal: requestOptions?.signal,
+        headers,
+        body: descriptor.body === undefined ? undefined : JSON.stringify(descriptor.body),
+      } satisfies RequestInit,
+    }
+  }
+
+  const execute = async (descriptor: RequestDescriptor, requestOptions?: RequestOptions) => {
+    try {
+      const prepared = prepare(descriptor, requestOptions)
+      return await fetch(prepared.url, prepared.init)
+    } catch (cause) {
+      throw new ClientError("Transport", { cause })
+    }
+  }
+
+  const responseError = async (response: Response, descriptor: RequestDescriptor): Promise<never> => {
+    if (descriptor.declaredStatuses.includes(response.status)) throw await json(response)
+    try {
+      await response.body?.cancel()
+    } catch {}
+    throw new ClientError("UnexpectedStatus", { cause: { status: response.status } })
+  }
+
+  const request = async <A>(descriptor: RequestDescriptor, requestOptions?: RequestOptions): Promise<A> => {
+    const response = await execute(descriptor, requestOptions)
+    if (response.status !== descriptor.successStatus) return responseError(response, descriptor)
+    if (descriptor.empty) {
+      try {
+        await response.body?.cancel()
+      } catch {}
+      return undefined as A
+    }
+    return (await json(response)) as A
+  }
+
+  const sse = <A>(descriptor: RequestDescriptor, requestOptions?: RequestOptions): AsyncIterable<A> => ({
+    async *[Symbol.asyncIterator]() {
+      const response = await execute(descriptor, requestOptions)
+      if (response.status !== descriptor.successStatus) await responseError(response, descriptor)
+      if (!isContentType(response, "text/event-stream")) {
+        try {
+          await response.body?.cancel()
+        } catch {}
+        throw new ClientError("UnsupportedContentType")
+      }
+      if (response.body === null) throw new ClientError("MalformedResponse")
+      const reader = response.body.getReader()
+      const decoder = new TextDecoder()
+      let buffer = ""
+      try {
+        while (true) {
+          let next
+          try {
+            next = await reader.read()
+          } catch (cause) {
+            throw new ClientError("Transport", { cause })
+          }
+          buffer += decoder.decode(next.value, { stream: !next.done })
+          if (buffer.length > 1_048_576) throw new ClientError("MalformedResponse")
+          const trailingCarriageReturn = !next.done && buffer.endsWith("\r")
+          if (trailingCarriageReturn) buffer = buffer.slice(0, -1)
+          buffer = buffer.replaceAll("\r\n", "\n").replaceAll("\r", "\n")
+          if (trailingCarriageReturn) buffer += "\r"
+          if (next.done && buffer !== "") buffer += "\n\n"
+          let boundary = buffer.indexOf("\n\n")
+          while (boundary >= 0) {
+            const block = buffer.slice(0, boundary)
+            buffer = buffer.slice(boundary + 2)
+            const data = block
+              .split("\n")
+              .flatMap((line) => (line.startsWith("data:") ? [line.slice(5).trimStart()] : []))
+              .join("\n")
+            if (data !== "") {
+              try {
+                yield JSON.parse(data) as A
+              } catch (cause) {
+                throw new ClientError("MalformedResponse", { cause })
+              }
+            }
+            boundary = buffer.indexOf("\n\n")
+          }
+          if (next.done) return
+        }
+      } finally {
+        try {
+          await reader.cancel()
+        } catch {}
+        reader.releaseLock()
+      }
+    },
+  })
+
+  return {
+    sessions: {
+      list: (input?: SessionsListInput, requestOptions?: RequestOptions) =>
+        request<SessionsListOutput>(
+          {
+            method: "GET",
+            path: `/api/session`,
+            query: {
+              workspace: input?.workspace,
+              limit: input?.limit,
+              order: input?.order,
+              search: input?.search,
+              directory: input?.directory,
+              project: input?.project,
+              subpath: input?.subpath,
+              cursor: input?.cursor,
+            },
+            successStatus: 200,
+            declaredStatuses: [400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ),
+      create: (input?: SessionsCreateInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsCreateOutput }>(
+          {
+            method: "POST",
+            path: `/api/session`,
+            body: { id: input?.id, agent: input?.agent, model: input?.model, location: input?.location },
+            successStatus: 200,
+            declaredStatuses: [401, 400],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
+      get: (input: SessionsGetInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsGetOutput }>(
+          {
+            method: "GET",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}`,
+            successStatus: 200,
+            declaredStatuses: [404, 400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
+      switchAgent: (input: SessionsSwitchAgentInput, requestOptions?: RequestOptions) =>
+        request<SessionsSwitchAgentOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/agent`,
+            body: { agent: input.agent },
+            successStatus: 204,
+            declaredStatuses: [404, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      switchModel: (input: SessionsSwitchModelInput, requestOptions?: RequestOptions) =>
+        request<SessionsSwitchModelOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/model`,
+            body: { model: input.model },
+            successStatus: 204,
+            declaredStatuses: [404, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      prompt: (input: SessionsPromptInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsPromptOutput }>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/prompt`,
+            body: { id: input.id, prompt: input.prompt, delivery: input.delivery, resume: input.resume },
+            successStatus: 200,
+            declaredStatuses: [409, 404, 400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
+      compact: (input: SessionsCompactInput, requestOptions?: RequestOptions) =>
+        request<SessionsCompactOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/compact`,
+            successStatus: 204,
+            declaredStatuses: [404, 503, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      wait: (input: SessionsWaitInput, requestOptions?: RequestOptions) =>
+        request<SessionsWaitOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/wait`,
+            successStatus: 204,
+            declaredStatuses: [404, 503, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      stage: (input: SessionsStageInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsStageOutput }>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/revert/stage`,
+            body: { messageID: input.messageID, files: input.files },
+            successStatus: 200,
+            declaredStatuses: [404, 500, 400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
+      clear: (input: SessionsClearInput, requestOptions?: RequestOptions) =>
+        request<SessionsClearOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/revert/clear`,
+            successStatus: 204,
+            declaredStatuses: [404, 500, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      commit: (input: SessionsCommitInput, requestOptions?: RequestOptions) =>
+        request<SessionsCommitOutput>(
+          {
+            method: "POST",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/revert/commit`,
+            successStatus: 204,
+            declaredStatuses: [404, 400, 401],
+            empty: true,
+          },
+          requestOptions,
+        ),
+      context: (input: SessionsContextInput, requestOptions?: RequestOptions) =>
+        request<{ readonly data: SessionsContextOutput }>(
+          {
+            method: "GET",
+            path: `/api/session/${encodeURIComponent(input.sessionID)}/context`,
+            successStatus: 200,
+            declaredStatuses: [404, 500, 400, 401],
+            empty: false,
+          },
+          requestOptions,
+        ).then((value) => value.data),
+    },
+  }
+}
+
+function appendQuery(params: URLSearchParams, key: string, value: unknown): void {
+  if (value === undefined || value === null) return
+  if (Array.isArray(value)) {
+    for (const item of value) appendQuery(params, key, item)
+    return
+  }
+  if (typeof value === "object") {
+    for (const [child, item] of Object.entries(value)) appendQuery(params, `${key}[${child}]`, item)
+    return
+  }
+  params.append(key, String(value))
+}
+
+async function json(response: Response): Promise<unknown> {
+  if (!isContentType(response, "application/json") && !response.headers.get("content-type")?.includes("+json")) {
+    try {
+      await response.body?.cancel()
+    } catch {}
+    throw new ClientError("UnsupportedContentType")
+  }
+  let text: string
+  try {
+    text = await response.text()
+  } catch (cause) {
+    throw new ClientError("Transport", { cause })
+  }
+  if (text === "") throw new ClientError("MalformedResponse")
+  try {
+    return JSON.parse(text)
+  } catch (cause) {
+    throw new ClientError("MalformedResponse", { cause })
+  }
+}
+
+function isContentType(response: Response, expected: string) {
+  return response.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase() === expected
+}

packages/client/src/generated/index.ts

@@ -0,0 +1,3 @@
+export { ClientError, type ClientErrorReason } from "./client-error"
+export * as OpenCode from "./client"
+export * from "./types"

packages/client/src/generated/types.ts

@@ -0,0 +1,631 @@
+export type JsonValue =
+  | null
+  | boolean
+  | number
+  | string
+  | ReadonlyArray<JsonValue>
+  | { readonly [key: string]: JsonValue }
+
+export type InvalidCursorError = { readonly _tag: "InvalidCursorError"; readonly message: string }
+export const isInvalidCursorError = (value: unknown): value is InvalidCursorError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "InvalidCursorError"
+
+export type InvalidRequestError = {
+  readonly _tag: "InvalidRequestError"
+  readonly message: string
+  readonly kind?: string | undefined
+  readonly field?: string | undefined
+}
+export const isInvalidRequestError = (value: unknown): value is InvalidRequestError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "InvalidRequestError"
+
+export type UnauthorizedError = { readonly _tag: "UnauthorizedError"; readonly message: string }
+export const isUnauthorizedError = (value: unknown): value is UnauthorizedError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "UnauthorizedError"
+
+export type SessionNotFoundError = {
+  readonly _tag: "SessionNotFoundError"
+  readonly sessionID: string
+  readonly message: string
+}
+export const isSessionNotFoundError = (value: unknown): value is SessionNotFoundError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "SessionNotFoundError"
+
+export type ConflictError = {
+  readonly _tag: "ConflictError"
+  readonly message: string
+  readonly resource?: string | undefined
+}
+export const isConflictError = (value: unknown): value is ConflictError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "ConflictError"
+
+export type ServiceUnavailableError = {
+  readonly _tag: "ServiceUnavailableError"
+  readonly message: string
+  readonly service?: string | undefined
+}
+export const isServiceUnavailableError = (value: unknown): value is ServiceUnavailableError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "ServiceUnavailableError"
+
+export type MessageNotFoundError = {
+  readonly _tag: "MessageNotFoundError"
+  readonly sessionID: string
+  readonly messageID: string
+  readonly message: string
+}
+export const isMessageNotFoundError = (value: unknown): value is MessageNotFoundError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "MessageNotFoundError"
+
+export type UnknownError = {
+  readonly _tag: "UnknownError"
+  readonly message: string
+  readonly ref?: string | undefined
+}
+export const isUnknownError = (value: unknown): value is UnknownError =>
+  typeof value === "object" && value !== null && "_tag" in value && value._tag === "UnknownError"
+
+export type SessionsListInput = {
+  readonly workspace?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["workspace"]
+  readonly limit?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["limit"]
+  readonly order?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["order"]
+  readonly search?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["search"]
+  readonly directory?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["directory"]
+  readonly project?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["project"]
+  readonly subpath?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["subpath"]
+  readonly cursor?: {
+    readonly workspace?: string | undefined
+    readonly limit?: string | undefined
+    readonly order?: "asc" | "desc" | undefined
+    readonly search?: string | undefined
+    readonly directory?: string | undefined
+    readonly project?: string | undefined
+    readonly subpath?: string | undefined
+    readonly cursor?: string | undefined
+  }["cursor"]
+}
+
+export type SessionsListOutput = {
+  readonly data: ReadonlyArray<{
+    readonly id: string
+    readonly parentID?: string
+    readonly projectID: string
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly cost: number
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+    readonly time: { readonly created: number; readonly updated: number; readonly archived?: number | null }
+    readonly title: string
+    readonly location: { readonly directory: string; readonly workspaceID?: string | null | null }
+    readonly subpath?: string | null
+    readonly revert?: {
+      readonly messageID: string
+      readonly partID?: string | null
+      readonly snapshot?: string | null
+      readonly diff?: string | null
+      readonly files?: ReadonlyArray<{
+        readonly path: string
+        readonly status: "added" | "modified" | "deleted"
+        readonly additions: number
+        readonly deletions: number
+        readonly patch: string
+      }> | null
+    } | null
+  }>
+  readonly cursor: { readonly previous?: string | null; readonly next?: string | null }
+}
+
+export type SessionsCreateInput = {
+  readonly id?: {
+    readonly id?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string | null | null } | null
+  }["id"]
+  readonly agent?: {
+    readonly id?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string | null | null } | null
+  }["agent"]
+  readonly model?: {
+    readonly id?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string | null | null } | null
+  }["model"]
+  readonly location?: {
+    readonly id?: string | null
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly location?: { readonly directory: string; readonly workspaceID?: string | null | null } | null
+  }["location"]
+}
+
+export type SessionsCreateOutput = {
+  readonly data: {
+    readonly id: string
+    readonly parentID?: string
+    readonly projectID: string
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly cost: number
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+    readonly time: { readonly created: number; readonly updated: number; readonly archived?: number | null }
+    readonly title: string
+    readonly location: { readonly directory: string; readonly workspaceID?: string | null | null }
+    readonly subpath?: string | null
+    readonly revert?: {
+      readonly messageID: string
+      readonly partID?: string | null
+      readonly snapshot?: string | null
+      readonly diff?: string | null
+      readonly files?: ReadonlyArray<{
+        readonly path: string
+        readonly status: "added" | "modified" | "deleted"
+        readonly additions: number
+        readonly deletions: number
+        readonly patch: string
+      }> | null
+    } | null
+  }
+}["data"]
+
+export type SessionsGetInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsGetOutput = {
+  readonly data: {
+    readonly id: string
+    readonly parentID?: string
+    readonly projectID: string
+    readonly agent?: string | null
+    readonly model?: { readonly id: string; readonly providerID: string; readonly variant?: string | null } | null
+    readonly cost: number
+    readonly tokens: {
+      readonly input: number
+      readonly output: number
+      readonly reasoning: number
+      readonly cache: { readonly read: number; readonly write: number }
+    }
+    readonly time: { readonly created: number; readonly updated: number; readonly archived?: number | null }
+    readonly title: string
+    readonly location: { readonly directory: string; readonly workspaceID?: string | null | null }
+    readonly subpath?: string | null
+    readonly revert?: {
+      readonly messageID: string
+      readonly partID?: string | null
+      readonly snapshot?: string | null
+      readonly diff?: string | null
+      readonly files?: ReadonlyArray<{
+        readonly path: string
+        readonly status: "added" | "modified" | "deleted"
+        readonly additions: number
+        readonly deletions: number
+        readonly patch: string
+      }> | null
+    } | null
+  }
+}["data"]
+
+export type SessionsSwitchAgentInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly agent: { readonly agent: string }["agent"]
+}
+
+export type SessionsSwitchAgentOutput = void
+
+export type SessionsSwitchModelInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly model: {
+    readonly model: { readonly id: string; readonly providerID: string; readonly variant?: string | undefined }
+  }["model"]
+}
+
+export type SessionsSwitchModelOutput = void
+
+export type SessionsPromptInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly id?: {
+    readonly id?: string | undefined
+    readonly prompt: {
+      readonly text: string
+      readonly files?:
+        | ReadonlyArray<{
+            readonly uri: string
+            readonly mime: string
+            readonly name?: string | undefined
+            readonly description?: string | undefined
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+      readonly agents?:
+        | ReadonlyArray<{
+            readonly name: string
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+    }
+    readonly delivery?: "steer" | "queue" | undefined
+    readonly resume?: boolean | undefined
+  }["id"]
+  readonly prompt: {
+    readonly id?: string | undefined
+    readonly prompt: {
+      readonly text: string
+      readonly files?:
+        | ReadonlyArray<{
+            readonly uri: string
+            readonly mime: string
+            readonly name?: string | undefined
+            readonly description?: string | undefined
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+      readonly agents?:
+        | ReadonlyArray<{
+            readonly name: string
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+    }
+    readonly delivery?: "steer" | "queue" | undefined
+    readonly resume?: boolean | undefined
+  }["prompt"]
+  readonly delivery?: {
+    readonly id?: string | undefined
+    readonly prompt: {
+      readonly text: string
+      readonly files?:
+        | ReadonlyArray<{
+            readonly uri: string
+            readonly mime: string
+            readonly name?: string | undefined
+            readonly description?: string | undefined
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+      readonly agents?:
+        | ReadonlyArray<{
+            readonly name: string
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+    }
+    readonly delivery?: "steer" | "queue" | undefined
+    readonly resume?: boolean | undefined
+  }["delivery"]
+  readonly resume?: {
+    readonly id?: string | undefined
+    readonly prompt: {
+      readonly text: string
+      readonly files?:
+        | ReadonlyArray<{
+            readonly uri: string
+            readonly mime: string
+            readonly name?: string | undefined
+            readonly description?: string | undefined
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+      readonly agents?:
+        | ReadonlyArray<{
+            readonly name: string
+            readonly source?: { readonly start: number; readonly end: number; readonly text: string } | undefined
+          }>
+        | undefined
+    }
+    readonly delivery?: "steer" | "queue" | undefined
+    readonly resume?: boolean | undefined
+  }["resume"]
+}
+
+export type SessionsPromptOutput = {
+  readonly data: {
+    readonly admittedSeq: number
+    readonly id: string
+    readonly sessionID: string
+    readonly prompt: {
+      readonly text: string
+      readonly files?: ReadonlyArray<{
+        readonly uri: string
+        readonly mime: string
+        readonly name?: string | null
+        readonly description?: string | null
+        readonly source?: { readonly start: number; readonly end: number; readonly text: string } | null
+      }> | null
+      readonly agents?: ReadonlyArray<{
+        readonly name: string
+        readonly source?: { readonly start: number; readonly end: number; readonly text: string } | null
+      }> | null
+    }
+    readonly delivery: "steer" | "queue"
+    readonly timeCreated: number
+    readonly promotedSeq?: number | null
+  }
+}["data"]
+
+export type SessionsCompactInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsCompactOutput = void
+
+export type SessionsWaitInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsWaitOutput = void
+
+export type SessionsStageInput = {
+  readonly sessionID: { readonly sessionID: string }["sessionID"]
+  readonly messageID: { readonly messageID: string; readonly files?: boolean | undefined }["messageID"]
+  readonly files?: { readonly messageID: string; readonly files?: boolean | undefined }["files"]
+}
+
+export type SessionsStageOutput = {
+  readonly data: {
+    readonly messageID: string
+    readonly partID?: string | undefined
+    readonly snapshot?: string | undefined
+    readonly diff?: string | undefined
+    readonly files?:
+      | ReadonlyArray<{
+          readonly path: string
+          readonly status: "added" | "modified" | "deleted"
+          readonly additions: number
+          readonly deletions: number
+          readonly patch: string
+        }>
+      | undefined
+  }
+}["data"]
+
+export type SessionsClearInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsClearOutput = void
+
+export type SessionsCommitInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsCommitOutput = void
+
+export type SessionsContextInput = { readonly sessionID: { readonly sessionID: string }["sessionID"] }
+
+export type SessionsContextOutput = {
+  readonly data: ReadonlyArray<
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+        readonly type: "agent-switched"
+        readonly agent: string
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+        readonly type: "model-switched"
+        readonly model: { readonly id: string; readonly providerID: string; readonly variant?: string | null }
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+        readonly text: string
+        readonly files?: ReadonlyArray<{
+          readonly uri: string
+          readonly mime: string
+          readonly name?: string | null
+          readonly description?: string | null
+          readonly source?: { readonly start: number; readonly end: number; readonly text: string } | null
+        }> | null
+        readonly agents?: ReadonlyArray<{
+          readonly name: string
+          readonly source?: { readonly start: number; readonly end: number; readonly text: string } | null
+        }> | null
+        readonly type: "user"
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+        readonly sessionID: string
+        readonly text: string
+        readonly type: "synthetic"
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+        readonly type: "system"
+        readonly text: string
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number; readonly completed?: number | null }
+        readonly type: "shell"
+        readonly callID: string
+        readonly command: string
+        readonly output: string
+      }
+    | {
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number; readonly completed?: number | null }
+        readonly type: "assistant"
+        readonly agent: string
+        readonly model: { readonly id: string; readonly providerID: string; readonly variant?: string | null }
+        readonly content: ReadonlyArray<
+          | { readonly type: "text"; readonly id: string; readonly text: string }
+          | {
+              readonly type: "reasoning"
+              readonly id: string
+              readonly text: string
+              readonly providerMetadata?: { readonly [x: string]: { readonly [x: string]: JsonValue } } | null
+            }
+          | {
+              readonly type: "tool"
+              readonly id: string
+              readonly name: string
+              readonly provider?: {
+                readonly executed: boolean
+                readonly metadata?: { readonly [x: string]: { readonly [x: string]: JsonValue } } | null
+                readonly resultMetadata?: { readonly [x: string]: { readonly [x: string]: JsonValue } } | null
+              } | null
+              readonly state:
+                | { readonly status: "pending"; readonly input: string }
+                | {
+                    readonly status: "running"
+                    readonly input: { readonly [x: string]: JsonValue }
+                    readonly structured: { readonly [x: string]: any }
+                    readonly content: ReadonlyArray<
+                      | { readonly type: "text"; readonly text: string }
+                      | {
+                          readonly type: "file"
+                          readonly uri: string
+                          readonly mime: string
+                          readonly name?: string | null
+                        }
+                    >
+                  }
+                | {
+                    readonly status: "completed"
+                    readonly input: { readonly [x: string]: JsonValue }
+                    readonly attachments?: ReadonlyArray<{
+                      readonly uri: string
+                      readonly mime: string
+                      readonly name?: string | null
+                      readonly description?: string | null
+                      readonly source?: { readonly start: number; readonly end: number; readonly text: string } | null
+                    }> | null
+                    readonly content: ReadonlyArray<
+                      | { readonly type: "text"; readonly text: string }
+                      | {
+                          readonly type: "file"
+                          readonly uri: string
+                          readonly mime: string
+                          readonly name?: string | null
+                        }
+                    >
+                    readonly outputPaths?: ReadonlyArray<string> | null
+                    readonly structured: { readonly [x: string]: any }
+                    readonly result?: JsonValue | null
+                  }
+                | {
+                    readonly status: "error"
+                    readonly input: { readonly [x: string]: JsonValue }
+                    readonly content: ReadonlyArray<
+                      | { readonly type: "text"; readonly text: string }
+                      | {
+                          readonly type: "file"
+                          readonly uri: string
+                          readonly mime: string
+                          readonly name?: string | null
+                        }
+                    >
+                    readonly structured: { readonly [x: string]: any }
+                    readonly error: { readonly type: "unknown"; readonly message: string }
+                    readonly result?: JsonValue | null
+                  }
+              readonly time: {
+                readonly created: number
+                readonly ran?: number | null
+                readonly completed?: number | null
+                readonly pruned?: number | null
+              }
+            }
+        >
+        readonly snapshot?: {
+          readonly start?: string | null
+          readonly end?: string | null
+          readonly files?: ReadonlyArray<string> | null
+        } | null
+        readonly finish?: string | null
+        readonly cost?: number | null
+        readonly tokens?: {
+          readonly input: number
+          readonly output: number
+          readonly reasoning: number
+          readonly cache: { readonly read: number; readonly write: number }
+        } | null
+        readonly error?: { readonly type: "unknown"; readonly message: string } | null
+      }
+    | {
+        readonly type: "compaction"
+        readonly reason: "auto" | "manual"
+        readonly summary: string
+        readonly recent: string
+        readonly id: string
+        readonly metadata?: { readonly [x: string]: JsonValue } | null
+        readonly time: { readonly created: number }
+      }
+  >
+}["data"]

packages/client/src/index.ts

@@ -0,0 +1 @@
+export * from "./generated/index"

packages/client/test/contract-identity.test.ts

@@ -0,0 +1,60 @@
+import { expect, test } from "bun:test"
+import { Schema } from "effect"
+import { AgentV2 } from "@opencode-ai/core/agent"
+import { Location as CoreLocation } from "@opencode-ai/core/location"
+import { ModelV2 } from "@opencode-ai/core/model"
+import { SessionV2 } from "@opencode-ai/core/session"
+import { SessionInput as CoreSessionInput } from "@opencode-ai/core/session/input"
+import { SessionMessage as CoreSessionMessage } from "@opencode-ai/core/session/message"
+import { Prompt as CorePrompt } from "@opencode-ai/core/session/prompt"
+import { Agent } from "@opencode-ai/schema/agent"
+import { Location } from "@opencode-ai/schema/location"
+import { Model } from "@opencode-ai/schema/model"
+import { Project } from "@opencode-ai/schema/project"
+import { Provider } from "@opencode-ai/schema/provider"
+import { Prompt } from "@opencode-ai/schema/prompt"
+import { Session } from "@opencode-ai/schema/session"
+import { SessionInput } from "@opencode-ai/schema/session-input"
+import { SessionMessage } from "@opencode-ai/schema/session-message"
+import { Workspace } from "@opencode-ai/schema/workspace"
+import { Api } from "@opencode-ai/server/api"
+import { compile, emitPromise } from "@opencode-ai/httpapi-codegen"
+import { HttpApi } from "effect/unstable/httpapi"
+import { SessionGroup } from "../src/contract"
+
+test("Core and Server reuse the authoritative Schema and Protocol values", () => {
+  expect(AgentV2.ID).toBe(Agent.ID)
+  expect(CoreLocation.Ref).toBe(Location.Ref)
+  expect(ModelV2.Ref).toBe(Model.Ref)
+  expect(SessionV2.Info).toBe(Session.Info)
+  expect(CoreSessionInput.Admitted).toBe(SessionInput.Admitted)
+  expect(CoreSessionMessage.Message).toBe(SessionMessage.Message)
+  expect(CorePrompt).toBe(Prompt)
+  expect(Api.groups["server.session"].identifier).toBe("server.session")
+  expect(SessionGroup.identifier).toBe(Api.groups["server.session"].identifier)
+  expect(Session.ID.create()).toStartWith("ses_")
+  expect(Project.ID.global).toBe("global")
+  expect(Provider.ID.anthropic).toBe("anthropic")
+  expect(Workspace.ID.create()).toStartWith("wrk_")
+})
+
+test("client and Server Session contracts generate identically", () => {
+  const options = { groupNames: { "server.session": "sessions" } }
+  const server = compile(HttpApi.make("server").add(Api.groups["server.session"]), options)
+  const client = compile(HttpApi.make("client").add(SessionGroup), options)
+
+  expect(emitPromise(client)).toEqual(emitPromise(server))
+})
+
+test("shared DTO schemas construct and decode plain objects", () => {
+  const made = Prompt.make({ text: "hello" })
+  const decoded = Schema.decodeUnknownSync(Prompt)({ text: "hello" })
+  const content = Schema.decodeUnknownSync(SessionMessage.AssistantText)({ type: "text", id: "part_1", text: "hi" })
+
+  expect(Object.getPrototypeOf(made)).toBe(Object.prototype)
+  expect(Object.getPrototypeOf(decoded)).toBe(Object.prototype)
+  expect(Object.getPrototypeOf(content)).toBe(Object.prototype)
+  expect(Prompt.ast.annotations?.identifier).toBe("Prompt")
+  expect(SessionMessage.AssistantText.ast.annotations?.identifier).toBe("Session.Message.Assistant.Text")
+  expect(CoreSessionMessage.AssistantText).toBe(SessionMessage.AssistantText)
+})

packages/client/test/effect.test.ts

@@ -0,0 +1,98 @@
+import { expect, test } from "bun:test"
+import { DateTime, Effect } from "effect"
+import { HttpClient, HttpClientResponse } from "effect/unstable/http"
+import { AbsolutePath, Agent, Location, Model, OpenCode, Prompt, Session } from "../src/effect"
+
+test("sessions.get returns the decoded Effect projection", async () => {
+  const httpClient = HttpClient.make((request) =>
+    Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(session))),
+  )
+  const result = await Effect.gen(function* () {
+    const client = yield* OpenCode.make({ baseUrl: "http://localhost:3000" })
+    return yield* client.sessions.get({ sessionID: Session.ID.make("ses_test") })
+  }).pipe(Effect.provideService(HttpClient.HttpClient, httpClient), Effect.runPromise)
+
+  expect(DateTime.toEpochMillis(result.time.created)).toBe(1_717_171_717_000)
+})
+
+test("session methods retain decoded Effect inputs and outputs", async () => {
+  const httpClient = HttpClient.make((request) => {
+    const url = request.url
+    if (url.includes("/prompt")) {
+      return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(admission)))
+    }
+    if (url.includes("/context")) {
+      return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json({ data: [] })))
+    }
+    if (request.method === "POST" && url.endsWith("/api/session")) {
+      return Effect.succeed(HttpClientResponse.fromWeb(request, Response.json(session)))
+    }
+    if (request.method === "POST") {
+      return Effect.succeed(HttpClientResponse.fromWeb(request, new Response(null, { status: 204 })))
+    }
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(request, Response.json({ data: [session.data], cursor: { next: "next" } })),
+    )
+  })
+  const result = await Effect.gen(function* () {
+    const client = yield* OpenCode.make({ baseUrl: "http://localhost:3000" })
+    const page = yield* client.sessions.list({ limit: 10 })
+    const created = yield* client.sessions.create({
+      location: Location.Ref.make({ directory: AbsolutePath.make("/tmp/project") }),
+    })
+    yield* client.sessions.switchAgent({ sessionID: Session.ID.make("ses_test"), agent: Agent.ID.make("build") })
+    yield* client.sessions.switchModel({
+      sessionID: Session.ID.make("ses_test"),
+      model: Model.Ref.make({ id: "claude", providerID: "anthropic" }),
+    })
+    const admitted = yield* client.sessions.prompt({
+      sessionID: Session.ID.make("ses_test"),
+      prompt: Prompt.make({ text: "Hello" }),
+      resume: false,
+    })
+    yield* client.sessions.compact({ sessionID: Session.ID.make("ses_test") })
+    yield* client.sessions.wait({ sessionID: Session.ID.make("ses_test") })
+    const context = yield* client.sessions.context({ sessionID: Session.ID.make("ses_test") })
+    return { page, created, admitted, context }
+  }).pipe(Effect.provideService(HttpClient.HttpClient, httpClient), Effect.runPromise)
+
+  expect(DateTime.toEpochMillis(result.page.data[0].time.created)).toBe(1_717_171_717_000)
+  expect(Object.getPrototypeOf(result.page.data[0])).toBe(Object.prototype)
+  expect(Object.getPrototypeOf(result.created)).toBe(Object.prototype)
+  expect(result.created.id).toBe("ses_test")
+  expect(Object.getPrototypeOf(result.admitted)).toBe(Object.prototype)
+  expect(Object.getPrototypeOf(result.admitted.prompt)).toBe(Object.prototype)
+  expect(DateTime.toEpochMillis(result.admitted.timeCreated)).toBe(1_717_171_717_000)
+  expect(result.context).toEqual([])
+})
+
+const session = {
+  data: {
+    id: "ses_test",
+    projectID: "project",
+    cost: 0,
+    tokens: {
+      input: 1,
+      output: 2,
+      reasoning: 3,
+      cache: { read: 4, write: 5 },
+    },
+    time: {
+      created: 1_717_171_717_000,
+      updated: 1_717_171_717_000,
+    },
+    title: "Test",
+    location: { directory: "/tmp/project" },
+  },
+}
+
+const admission = {
+  data: {
+    admittedSeq: 0,
+    id: "msg_test",
+    sessionID: "ses_test",
+    prompt: { text: "Hello" },
+    delivery: "steer",
+    timeCreated: 1_717_171_717_000,
+  },
+}

packages/client/test/import-boundaries.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test"
+import { realpathSync } from "node:fs"
+import { mkdtemp, rm } from "node:fs/promises"
+import { join, resolve, sep } from "node:path"
+
+const directory = resolve(import.meta.dir, "..")
+const effect = realpathSync(resolve(import.meta.dir, "../node_modules/effect"))
+const schema = resolve(import.meta.dir, "../../schema")
+const protocol = resolve(import.meta.dir, "../../protocol")
+const core = resolve(import.meta.dir, "../../core")
+const server = resolve(import.meta.dir, "../../server")
+
+describe("public import boundaries", () => {
+  test("isolates each public entrypoint", async () => {
+    const root = await bundleInputs("@opencode-ai/client", "browser")
+
+    expect(within(root, effect)).toEqual([])
+    expect(within(root, schema)).toEqual([])
+    expect(within(root, protocol)).toEqual([])
+    expect(within(root, core)).toEqual([])
+    expect(within(root, server)).toEqual([])
+
+    const network = await bundleInputs("@opencode-ai/client/effect", "browser")
+
+    expect(within(network, effect).length).toBeGreaterThan(0)
+    expect(within(network, schema).length).toBeGreaterThan(0)
+    expect(within(network, protocol).length).toBeGreaterThan(0)
+    expect(within(network, core)).toEqual([])
+    expect(within(network, server)).toEqual([])
+  })
+})
+
+async function bundleInputs(specifier: string, target: "browser" | "bun") {
+  const temporary = await mkdtemp(join(import.meta.dir, ".import-boundary-"))
+  const entrypoint = join(temporary, "index.ts")
+  const metafile = join(temporary, "meta.json")
+  try {
+    await Bun.write(entrypoint, `export * from ${JSON.stringify(specifier)}`)
+    const child = Bun.spawn(
+      [
+        process.execPath,
+        "build",
+        entrypoint,
+        `--target=${target}`,
+        "--format=esm",
+        "--packages=bundle",
+        `--metafile=${metafile}`,
+        `--outdir=${join(temporary, "out")}`,
+      ],
+      { cwd: directory, stdout: "pipe", stderr: "pipe" },
+    )
+    const [exitCode, stdout, stderr] = await Promise.all([
+      child.exited,
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+    ])
+    if (exitCode !== 0) throw new Error(stdout + stderr)
+    const metadata = await Bun.file(metafile).json()
+    return Object.keys(metadata.inputs).map((input) => resolve(directory, input))
+  } finally {
+    await rm(temporary, { recursive: true, force: true })
+  }
+}
+
+function within(inputs: ReadonlyArray<string>, directory: string) {
+  const prefix = directory.endsWith(sep) ? directory : directory + sep
+  return inputs.filter((input) => input === directory || input.startsWith(prefix))
+}

packages/client/test/promise.test.ts

@@ -0,0 +1,117 @@
+import { expect, test } from "bun:test"
+import { isUnauthorizedError, OpenCode } from "../src"
+
+test("sessions.get returns the wire projection", async () => {
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async (input) => {
+      expect(typeof input === "string" ? input : input instanceof URL ? input.href : input.url).toBe(
+        "http://localhost:3000/api/session/ses_test",
+      )
+      return Response.json(session)
+    },
+  })
+
+  const result = await client.sessions.get({ sessionID: "ses_test" })
+
+  expect(result.time.created).toBe(1_717_171_717_000)
+})
+
+test("session methods use the public HTTP contract", async () => {
+  const requests: Array<{ url: string; init?: RequestInit }> = []
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async (input, init) => {
+      const url = typeof input === "string" ? input : input instanceof URL ? input.href : input.url
+      requests.push({ url, init })
+      if (url.includes("/prompt")) return Response.json(admission)
+      if (url.includes("/context")) return Response.json({ data: [] })
+      if (init?.method === "POST" && url.endsWith("/api/session")) return Response.json(session)
+      if (init?.method === "POST") return new Response(null, { status: 204 })
+      return Response.json({ data: [session.data], cursor: { next: "next" } })
+    },
+  })
+
+  const page = await client.sessions.list({ limit: "10", order: "desc" })
+  const created = await client.sessions.create({ location: { directory: "/tmp/project" } })
+  await client.sessions.switchAgent({ sessionID: "ses_test", agent: "build" })
+  await client.sessions.switchModel({
+    sessionID: "ses_test",
+    model: { id: "claude", providerID: "anthropic" },
+  })
+  const admitted = await client.sessions.prompt({
+    sessionID: "ses_test",
+    prompt: { text: "Hello" },
+    resume: false,
+  })
+  await client.sessions.compact({ sessionID: "ses_test" })
+  await client.sessions.wait({ sessionID: "ses_test" })
+  const context = await client.sessions.context({ sessionID: "ses_test" })
+
+  expect(page.cursor.next).toBe("next")
+  expect(created.id).toBe("ses_test")
+  expect(admitted.id).toBe("msg_test")
+  expect(context).toEqual([])
+  expect(requests.map((request) => [request.init?.method, request.url])).toEqual([
+    ["GET", "http://localhost:3000/api/session?limit=10&order=desc"],
+    ["POST", "http://localhost:3000/api/session"],
+    ["POST", "http://localhost:3000/api/session/ses_test/agent"],
+    ["POST", "http://localhost:3000/api/session/ses_test/model"],
+    ["POST", "http://localhost:3000/api/session/ses_test/prompt"],
+    ["POST", "http://localhost:3000/api/session/ses_test/compact"],
+    ["POST", "http://localhost:3000/api/session/ses_test/wait"],
+    ["GET", "http://localhost:3000/api/session/ses_test/context"],
+  ])
+  const body = requests[4]?.init?.body
+  if (typeof body !== "string") throw new Error("Expected JSON request body")
+  expect(JSON.parse(body)).toEqual({
+    prompt: { text: "Hello" },
+    resume: false,
+  })
+})
+
+test("middleware errors remain declared client errors", async () => {
+  const client = OpenCode.make({
+    baseUrl: "http://localhost:3000",
+    fetch: async () =>
+      Response.json({ _tag: "UnauthorizedError", message: "Authentication required" }, { status: 401 }),
+  })
+
+  try {
+    await client.sessions.create({})
+    throw new Error("Expected request to fail")
+  } catch (error) {
+    expect(isUnauthorizedError(error)).toBe(true)
+  }
+})
+
+const session = {
+  data: {
+    id: "ses_test",
+    projectID: "project",
+    cost: 0,
+    tokens: {
+      input: 1,
+      output: 2,
+      reasoning: 3,
+      cache: { read: 4, write: 5 },
+    },
+    time: {
+      created: 1_717_171_717_000,
+      updated: 1_717_171_717_000,
+    },
+    title: "Test",
+    location: { directory: "/tmp/project" },
+  },
+}
+
+const admission = {
+  data: {
+    admittedSeq: 0,
+    id: "msg_test",
+    sessionID: "ses_test",
+    prompt: { text: "Hello" },
+    delivery: "steer",
+    timeCreated: 1_717_171_717_000,
+  },
+}

packages/client/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "@tsconfig/bun/tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "noUncheckedIndexedAccess": false
+  },
+  "include": ["src"]
+}