@rigkit/runtime-client 0.0.0-canary-20260518T014918-c5bc0c2

package/README.md

@@ -0,0 +1,3 @@
+# @rigkit/runtime-client
+
+Shared client and daemon manager for Rigkit runtime hosts.

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@rigkit/runtime-client",
+  "version": "0.0.0-canary-20260518T014918-c5bc0c2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/freestyle-sh/rigkit.git",
+    "directory": "packages/runtime-client"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "dependencies": {
+    "@effect/platform": "0.96.1",
+    "effect": "^3.21.2",
+    "ws": "^8.20.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "latest"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  }
+}

package/src/api.ts

@@ -0,0 +1,242 @@
+import {
+  HttpApi,
+  HttpApiEndpoint,
+  HttpApiGroup,
+  HttpApiSchema,
+  OpenApi,
+} from "@effect/platform";
+import { Schema } from "effect";
+import { SUPPORTED_RUNTIME_API_VERSION } from "./http.ts";
+
+const UnknownRecord = Schema.Record({ key: Schema.String, value: Schema.Unknown });
+const OptionalString = Schema.optional(Schema.String);
+
+export const RuntimeControlHealthEffectSchema = Schema.Struct({
+  ok: Schema.Boolean,
+  projectId: Schema.String,
+  runtimeFingerprint: OptionalString,
+  projectDir: Schema.String,
+  configPath: Schema.String,
+  statePath: OptionalString,
+  globalFragmentRoot: OptionalString,
+  engineVersion: Schema.String,
+  runtimeVersion: Schema.String,
+  expiresAt: Schema.String,
+}).annotations({ identifier: "Health" });
+
+export const RuntimeControlMetadataEffectSchema = Schema.Struct({
+  apiVersion: Schema.Number,
+  engineVersion: Schema.String,
+  runtimeVersion: Schema.String,
+  protocolHash: Schema.String,
+}).annotations({ identifier: "RuntimeMetadata" });
+
+export const RuntimeControlWorkflowSummaryEffectSchema = Schema.Struct({
+  name: Schema.String,
+  providers: Schema.Array(Schema.String),
+  nodes: Schema.Array(Schema.String),
+  operations: Schema.Array(Schema.String),
+  createsWorkspace: Schema.Boolean,
+}).annotations({ identifier: "WorkflowSummary" });
+
+export const RuntimeControlProjectInfoEffectSchema = Schema.Struct({
+  projectDir: Schema.String,
+  configPath: Schema.String,
+  statePath: OptionalString,
+  workflow: Schema.optional(RuntimeControlWorkflowSummaryEffectSchema),
+  workflows: Schema.Array(RuntimeControlWorkflowSummaryEffectSchema),
+}).annotations({ identifier: "ProjectInfo" });
+
+export const RuntimeControlOperationCliEffectSchema = Schema.Struct({
+  positionals: Schema.optional(Schema.Array(Schema.Struct({
+    name: Schema.String,
+    index: Schema.Number,
+  }))),
+  options: Schema.optional(Schema.Array(Schema.Struct({
+    name: Schema.String,
+    flag: Schema.String,
+    aliases: Schema.optional(Schema.Array(Schema.String)),
+    required: Schema.optional(Schema.Boolean),
+    runtime: Schema.optional(Schema.Boolean),
+    type: Schema.optional(Schema.Literal("string", "boolean", "number")),
+  }))),
+}).annotations({ identifier: "RuntimeOperationCli" });
+
+export const RuntimeControlOperationEffectSchema = Schema.Struct({
+  id: Schema.String,
+  aliases: Schema.optional(Schema.Array(Schema.String)),
+  kind: Schema.Literal("command", "workspace-action"),
+  source: Schema.Literal("core", "config"),
+  title: Schema.String,
+  description: Schema.String,
+  createsWorkspace: Schema.optional(Schema.Boolean),
+  cli: Schema.optional(RuntimeControlOperationCliEffectSchema),
+  inputSchema: UnknownRecord,
+}).annotations({ identifier: "RuntimeOperation" });
+
+export const RuntimeControlOperationsManifestEffectSchema = Schema.Struct({
+  operations: Schema.Array(RuntimeControlOperationEffectSchema),
+  workspaceOperations: Schema.Array(RuntimeControlOperationEffectSchema),
+}).annotations({ identifier: "OperationsManifest" });
+
+export const RuntimeControlWorkflowsResponseEffectSchema = Schema.Struct({
+  workflows: Schema.Array(RuntimeControlWorkflowSummaryEffectSchema),
+}).annotations({ identifier: "WorkflowsResponse" });
+
+export const RuntimeControlWorkspaceEffectSchema = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  workflow: Schema.String,
+  ctx: UnknownRecord,
+  createdAt: Schema.String,
+  updatedAt: Schema.String,
+}).annotations({ identifier: "Workspace" });
+
+export const RuntimeControlWorkspacesResponseEffectSchema = Schema.Struct({
+  workspaces: Schema.Array(RuntimeControlWorkspaceEffectSchema),
+}).annotations({ identifier: "WorkspacesResponse" });
+
+export const RuntimeControlSnapshotsResponseEffectSchema = Schema.Struct({
+  snapshots: Schema.Array(Schema.Unknown),
+}).annotations({ identifier: "SnapshotsResponse" });
+
+export const RuntimeControlCacheEntryEffectSchema = Schema.Struct({
+  scope: Schema.Literal("local", "global"),
+  workflow: Schema.String,
+  nodePath: Schema.String,
+  nodeName: Schema.String,
+  nodeKind: Schema.String,
+  runId: Schema.String,
+  invalidated: Schema.Boolean,
+  createdAt: Schema.String,
+  fragmentHash: Schema.optional(Schema.String),
+}).annotations({ identifier: "CacheEntry" });
+
+export const RuntimeControlCacheResponseEffectSchema = Schema.Struct({
+  entries: Schema.Array(RuntimeControlCacheEntryEffectSchema),
+}).annotations({ identifier: "CacheResponse" });
+
+export const RuntimeControlCacheClearRequestEffectSchema = Schema.Struct({
+  scope: Schema.optional(Schema.Literal("local", "global", "all")),
+}).annotations({ identifier: "CacheClearRequest" });
+
+export const RuntimeControlCacheClearResponseEffectSchema = Schema.Struct({
+  ok: Schema.Boolean,
+  deleted: Schema.Number,
+}).annotations({ identifier: "CacheClearResponse" });
+
+export const RuntimeControlCacheInvalidateRequestEffectSchema = Schema.Struct({
+  workflow: Schema.optional(Schema.String),
+  nodePaths: Schema.optional(Schema.Array(Schema.String)),
+}).annotations({ identifier: "CacheInvalidateRequest" });
+
+export const RuntimeControlCacheInvalidateResponseEffectSchema = Schema.Struct({
+  ok: Schema.Boolean,
+  invalidated: Schema.Number,
+}).annotations({ identifier: "CacheInvalidateResponse" });
+
+export const RuntimeControlRunEffectSchema = Schema.Struct({
+  runId: Schema.String,
+  operation: Schema.String,
+  input: Schema.Unknown,
+  status: Schema.Literal("running", "completed", "failed"),
+  result: Schema.optional(Schema.Unknown),
+  error: Schema.optional(Schema.Struct({
+    code: Schema.String,
+    message: Schema.String,
+  })),
+  createdAt: Schema.String,
+  updatedAt: Schema.String,
+}).annotations({ identifier: "Run" });
+
+export const RuntimeControlRunsResponseEffectSchema = Schema.Struct({
+  runs: Schema.Array(RuntimeControlRunEffectSchema),
+}).annotations({ identifier: "RunsResponse" });
+
+export const RuntimeControlRunOperationRequestEffectSchema = Schema.Struct({
+  operation: Schema.NonEmptyString,
+  input: Schema.optional(Schema.Unknown),
+}).annotations({ identifier: "RunOperationRequest" });
+
+export const RuntimeControlRunStartedEffectSchema = Schema.Struct({
+  runId: Schema.String,
+  operation: Schema.String,
+  status: Schema.Literal("running", "completed", "failed"),
+  eventsUrl: Schema.String,
+  sessionUrl: Schema.String,
+}).annotations({ identifier: "RunStarted" });
+
+export const RuntimeControlHostResponseEffectSchema = Schema.Union(
+  Schema.Struct({
+    error: Schema.Struct({
+      code: Schema.optional(Schema.String),
+      message: Schema.optional(Schema.String),
+    }),
+  }),
+  Schema.Struct({
+    result: Schema.optional(Schema.Unknown),
+  }),
+).annotations({ identifier: "HostResponse" });
+
+export const RuntimeControlOkResponseEffectSchema = Schema.Struct({
+  ok: Schema.Boolean,
+}).annotations({ identifier: "OkResponse" });
+
+export type RuntimeControlHealth = Schema.Schema.Type<typeof RuntimeControlHealthEffectSchema>;
+export type RuntimeControlMetadata = Schema.Schema.Type<typeof RuntimeControlMetadataEffectSchema>;
+export type RuntimeControlWorkflowSummary = Schema.Schema.Type<typeof RuntimeControlWorkflowSummaryEffectSchema>;
+export type RuntimeControlProjectInfo = Schema.Schema.Type<typeof RuntimeControlProjectInfoEffectSchema>;
+export type RuntimeControlOperationCli = Schema.Schema.Type<typeof RuntimeControlOperationCliEffectSchema>;
+export type RuntimeControlOperation = Schema.Schema.Type<typeof RuntimeControlOperationEffectSchema>;
+export type RuntimeControlOperationsManifest = Schema.Schema.Type<typeof RuntimeControlOperationsManifestEffectSchema>;
+export type RuntimeControlWorkflowsResponse = Schema.Schema.Type<typeof RuntimeControlWorkflowsResponseEffectSchema>;
+export type RuntimeControlWorkspace = Schema.Schema.Type<typeof RuntimeControlWorkspaceEffectSchema>;
+export type RuntimeControlWorkspacesResponse = Schema.Schema.Type<typeof RuntimeControlWorkspacesResponseEffectSchema>;
+export type RuntimeControlSnapshotsResponse = Schema.Schema.Type<typeof RuntimeControlSnapshotsResponseEffectSchema>;
+export type RuntimeControlCacheEntry = Schema.Schema.Type<typeof RuntimeControlCacheEntryEffectSchema>;
+export type RuntimeControlCacheResponse = Schema.Schema.Type<typeof RuntimeControlCacheResponseEffectSchema>;
+export type RuntimeControlCacheClearRequest = Schema.Schema.Type<typeof RuntimeControlCacheClearRequestEffectSchema>;
+export type RuntimeControlCacheClearResponse = Schema.Schema.Type<typeof RuntimeControlCacheClearResponseEffectSchema>;
+export type RuntimeControlCacheInvalidateRequest = Schema.Schema.Type<typeof RuntimeControlCacheInvalidateRequestEffectSchema>;
+export type RuntimeControlCacheInvalidateResponse = Schema.Schema.Type<typeof RuntimeControlCacheInvalidateResponseEffectSchema>;
+export type RuntimeControlRunOperationRequest = Schema.Schema.Type<typeof RuntimeControlRunOperationRequestEffectSchema>;
+export type RuntimeControlRun = Schema.Schema.Type<typeof RuntimeControlRunEffectSchema>;
+export type RuntimeControlRunsResponse = Schema.Schema.Type<typeof RuntimeControlRunsResponseEffectSchema>;
+export type RuntimeControlRunStarted = Schema.Schema.Type<typeof RuntimeControlRunStartedEffectSchema>;
+export type RuntimeControlHostResponse = Schema.Schema.Type<typeof RuntimeControlHostResponseEffectSchema>;
+export type RuntimeControlOkResponse = Schema.Schema.Type<typeof RuntimeControlOkResponseEffectSchema>;
+
+const runId = HttpApiSchema.param("runId", Schema.String);
+const requestId = HttpApiSchema.param("requestId", Schema.String);
+
+export const runtimeControlApi = HttpApi.make("rigkit-runtime")
+  .annotate(OpenApi.Title, "Rigkit runtime")
+  .annotate(OpenApi.Version, String(SUPPORTED_RUNTIME_API_VERSION))
+  .add(
+    HttpApiGroup.make("control", { topLevel: true })
+      .add(HttpApiEndpoint.get("health", "/health").addSuccess(RuntimeControlHealthEffectSchema))
+      .add(HttpApiEndpoint.get("openApi", "/openapi.json").addSuccess(Schema.Unknown))
+      .add(HttpApiEndpoint.get("runtime", "/runtime").addSuccess(RuntimeControlMetadataEffectSchema))
+      .add(HttpApiEndpoint.get("project", "/project").addSuccess(RuntimeControlProjectInfoEffectSchema))
+      .add(HttpApiEndpoint.get("operations", "/operations").addSuccess(RuntimeControlOperationsManifestEffectSchema))
+      .add(HttpApiEndpoint.get("workflows", "/workflows").addSuccess(RuntimeControlWorkflowsResponseEffectSchema))
+      .add(HttpApiEndpoint.get("workspaces", "/workspaces").addSuccess(RuntimeControlWorkspacesResponseEffectSchema))
+      .add(HttpApiEndpoint.get("snapshots", "/snapshots").addSuccess(RuntimeControlSnapshotsResponseEffectSchema))
+      .add(HttpApiEndpoint.get("cache", "/cache").addSuccess(RuntimeControlCacheResponseEffectSchema))
+      .add(HttpApiEndpoint.post("clearCache", "/cache/clear")
+        .setPayload(RuntimeControlCacheClearRequestEffectSchema)
+        .addSuccess(RuntimeControlCacheClearResponseEffectSchema))
+      .add(HttpApiEndpoint.post("invalidateCache", "/cache/invalidate")
+        .setPayload(RuntimeControlCacheInvalidateRequestEffectSchema)
+        .addSuccess(RuntimeControlCacheInvalidateResponseEffectSchema))
+      .add(HttpApiEndpoint.get("runs", "/runs").addSuccess(RuntimeControlRunsResponseEffectSchema))
+      .add(HttpApiEndpoint.post("startRun", "/runs")
+        .setPayload(RuntimeControlRunOperationRequestEffectSchema)
+        .addSuccess(RuntimeControlRunStartedEffectSchema, { status: 202 }))
+      .add(HttpApiEndpoint.get("run")`/runs/${runId}`.addSuccess(RuntimeControlRunEffectSchema))
+      .add(HttpApiEndpoint.get("runEvents")`/runs/${runId}/events`.addSuccess(Schema.String))
+      .add(HttpApiEndpoint.post("hostResponse")`/host-responses/${requestId}`
+        .setPayload(RuntimeControlHostResponseEffectSchema)
+        .addSuccess(RuntimeControlOkResponseEffectSchema))
+      .add(HttpApiEndpoint.post("shutdown", "/shutdown").addSuccess(RuntimeControlOkResponseEffectSchema)),
+  );

package/src/client.ts

@@ -0,0 +1,261 @@
+import {
+  FetchHttpClient,
+  Headers,
+  HttpApiClient,
+  HttpClient,
+  HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "@effect/platform";
+import { Cause, Effect, Exit, Option } from "effect";
+import {
+  RuntimeAuthError,
+  RuntimeConnectionError,
+  RuntimeHttpError,
+  RuntimeProtocolError,
+  isRuntimeClientError,
+  type RuntimeClientError,
+} from "./errors.ts";
+import { assertSupportedApiVersionHeader, toRuntimeTransportError } from "./http.ts";
+import { RuntimeErrorResponseSchema } from "./schemas.ts";
+import {
+  runtimeControlApi,
+  type RuntimeControlHealth,
+  type RuntimeControlHostResponse,
+  type RuntimeControlCacheClearRequest,
+  type RuntimeControlCacheClearResponse,
+  type RuntimeControlCacheInvalidateRequest,
+  type RuntimeControlCacheInvalidateResponse,
+  type RuntimeControlCacheResponse,
+  type RuntimeControlMetadata,
+  type RuntimeControlOkResponse,
+  type RuntimeControlOperationsManifest,
+  type RuntimeControlProjectInfo,
+  type RuntimeControlRun,
+  type RuntimeControlRunOperationRequest,
+  type RuntimeControlRunsResponse,
+  type RuntimeControlRunStarted,
+  type RuntimeControlSnapshotsResponse,
+  type RuntimeControlWorkflowsResponse,
+  type RuntimeControlWorkspacesResponse,
+} from "./api.ts";
+
+export type RuntimeHttpClientOptions = {
+  readonly baseUrl: string;
+  readonly token: string;
+};
+
+export type RuntimeHttpClient = {
+  health(): Promise<RuntimeControlHealth>;
+  openApi(): Promise<unknown>;
+  runtime(): Promise<RuntimeControlMetadata>;
+  project(): Promise<RuntimeControlProjectInfo>;
+  operations(): Promise<RuntimeControlOperationsManifest>;
+  workflows(): Promise<RuntimeControlWorkflowsResponse>;
+  workspaces(): Promise<RuntimeControlWorkspacesResponse>;
+  snapshots(): Promise<RuntimeControlSnapshotsResponse>;
+  cache(): Promise<RuntimeControlCacheResponse>;
+  clearCache(body: RuntimeControlCacheClearRequest): Promise<RuntimeControlCacheClearResponse>;
+  invalidateCache(body: RuntimeControlCacheInvalidateRequest): Promise<RuntimeControlCacheInvalidateResponse>;
+  runs(): Promise<RuntimeControlRunsResponse>;
+  startRun(body: RuntimeControlRunOperationRequest): Promise<RuntimeControlRunStarted>;
+  run(runId: string): Promise<RuntimeControlRun>;
+  hostResponse(requestId: string, body: RuntimeControlHostResponse): Promise<RuntimeControlOkResponse>;
+  shutdown(): Promise<RuntimeControlOkResponse>;
+};
+
+type RuntimeControlApiClient = Effect.Effect.Success<ReturnType<typeof runtimeControlApiClientEffect>>;
+type RuntimeHttpResponse<A> = [A, HttpClientResponse.HttpClientResponse];
+type RuntimeHttpContext = {
+  readonly method: string;
+  readonly path: string;
+};
+
+export function runtimeHttpClientEffect(
+  options: RuntimeHttpClientOptions,
+): Effect.Effect<RuntimeHttpClient, RuntimeClientError> {
+  return Effect.succeed(createRuntimeHttpClient(options));
+}
+
+export function createRuntimeHttpClient(options: RuntimeHttpClientOptions): RuntimeHttpClient {
+  return makeRuntimeHttpClient({
+    baseUrl: options.baseUrl.replace(/\/+$/, ""),
+    token: options.token,
+  });
+}
+
+function runtimeControlApiClientEffect(options: RuntimeHttpClientOptions) {
+  return HttpApiClient.make(runtimeControlApi, {
+    baseUrl: options.baseUrl,
+    transformClient: HttpClient.mapRequest(HttpClientRequest.bearerToken(options.token)),
+  });
+}
+
+function makeRuntimeHttpClient(options: RuntimeHttpClientOptions): RuntimeHttpClient {
+  return {
+    health: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.health({ withResponse: true })), {
+        method: "GET",
+        path: "/health",
+      }),
+    openApi: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.openApi({ withResponse: true })), {
+        method: "GET",
+        path: "/openapi.json",
+      }),
+    runtime: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.runtime({ withResponse: true })), {
+        method: "GET",
+        path: "/runtime",
+      }),
+    project: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.project({ withResponse: true })), {
+        method: "GET",
+        path: "/project",
+      }),
+    operations: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.operations({ withResponse: true })), {
+        method: "GET",
+        path: "/operations",
+      }),
+    workflows: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.workflows({ withResponse: true })), {
+        method: "GET",
+        path: "/workflows",
+      }),
+    workspaces: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.workspaces({ withResponse: true })), {
+        method: "GET",
+        path: "/workspaces",
+      }),
+    snapshots: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.snapshots({ withResponse: true })), {
+        method: "GET",
+        path: "/snapshots",
+      }),
+    cache: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.cache({ withResponse: true })), {
+        method: "GET",
+        path: "/cache",
+      }),
+    clearCache: (body) =>
+      runRuntimeHttpRequest(
+        withRuntimeControlClient(options, (client) => client.clearCache({ payload: body, withResponse: true })),
+        { method: "POST", path: "/cache/clear" },
+      ),
+    invalidateCache: (body) =>
+      runRuntimeHttpRequest(
+        withRuntimeControlClient(options, (client) => client.invalidateCache({ payload: body, withResponse: true })),
+        { method: "POST", path: "/cache/invalidate" },
+      ),
+    runs: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.runs({ withResponse: true })), {
+        method: "GET",
+        path: "/runs",
+      }),
+    startRun: (body) =>
+      runRuntimeHttpRequest(
+        withRuntimeControlClient(options, (client) => client.startRun({ payload: body, withResponse: true })),
+        { method: "POST", path: "/runs" },
+      ),
+    run: (runId) =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.run({ path: { runId }, withResponse: true })), {
+        method: "GET",
+        path: `/runs/${encodeURIComponent(runId)}`,
+      }),
+    hostResponse: (requestId, body) => {
+      const path = `/host-responses/${encodeURIComponent(requestId)}`;
+      if ("error" in body) {
+        return runRuntimeHttpRequest(
+          withRuntimeControlClient(options, (client) =>
+            client.hostResponse({ path: { requestId }, payload: { error: body.error }, withResponse: true })
+          ),
+          { method: "POST", path },
+        );
+      }
+      return runRuntimeHttpRequest(
+        withRuntimeControlClient(options, (client) =>
+          client.hostResponse({ path: { requestId }, payload: { result: body.result }, withResponse: true })
+        ),
+        { method: "POST", path },
+      );
+    },
+    shutdown: () =>
+      runRuntimeHttpRequest(withRuntimeControlClient(options, (client) => client.shutdown({ withResponse: true })), {
+        method: "POST",
+        path: "/shutdown",
+      }),
+  };
+}
+
+function withRuntimeControlClient<A>(
+  options: RuntimeHttpClientOptions,
+  run: (client: RuntimeControlApiClient) => Effect.Effect<RuntimeHttpResponse<A>, unknown, never>,
+) {
+  return Effect.flatMap(
+    Effect.provide(runtimeControlApiClientEffect(options), FetchHttpClient.layer),
+    run,
+  );
+}
+
+async function runRuntimeHttpRequest<A>(
+  program: Effect.Effect<RuntimeHttpResponse<A>, unknown, never>,
+  context: RuntimeHttpContext,
+): Promise<A> {
+  const response = await runRuntimeHttpEffect(program, context);
+  const [value, httpResponse] = response;
+  try {
+    assertSupportedApiVersionHeader(Option.getOrNull(Headers.get(httpResponse.headers, "x-rigkit-api-version")));
+  } catch (error) {
+    throw toRuntimeTransportError(error, context);
+  }
+  return value;
+}
+
+async function runRuntimeHttpEffect<A>(
+  program: Effect.Effect<A, unknown, never>,
+  context: RuntimeHttpContext,
+): Promise<A> {
+  const exit = await Effect.runPromiseExit(program);
+  if (Exit.isSuccess(exit)) return exit.value;
+  throw await runtimeHttpClientError(Cause.squash(exit.cause), context);
+}
+
+async function runtimeHttpClientError(cause: unknown, context: RuntimeHttpContext): Promise<RuntimeClientError> {
+  if (isRuntimeClientError(cause)) return cause;
+  if (cause instanceof HttpClientError.ResponseError) {
+    const status = cause.response.status;
+    const message = await responseErrorMessage(cause);
+    if (status === 401 || status === 403) {
+      return new RuntimeAuthError({ ...context, status, message });
+    }
+    if (status >= 200 && status < 300) {
+      return new RuntimeProtocolError({
+        ...context,
+        message: `${context.method} ${context.path} returned invalid response`,
+        cause,
+      });
+    }
+    return new RuntimeHttpError({ ...context, status, message, cause });
+  }
+  if (cause instanceof HttpClientError.RequestError) {
+    return new RuntimeConnectionError({ ...context, cause });
+  }
+  return new RuntimeProtocolError({
+    ...context,
+    message: `${context.method} ${context.path} returned invalid response`,
+    cause,
+  });
+}
+
+async function responseErrorMessage(error: HttpClientError.ResponseError): Promise<string | undefined> {
+  try {
+    const text = await Effect.runPromise(error.response.text);
+    if (!text) return undefined;
+    const parsed = JSON.parse(text);
+    const body = RuntimeErrorResponseSchema.safeParse(parsed);
+    return body.success ? body.data.error.message : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/errors.ts

@@ -0,0 +1,124 @@
+export type RuntimeStartupErrorReason =
+  | "missing-runtime"
+  | "lock-timeout"
+  | "startup-timeout"
+  | "exited-before-ready"
+  | "invalid-ready-output"
+  | "unhealthy-after-start";
+
+export class RuntimeStartupError extends Error {
+  readonly reason: RuntimeStartupErrorReason;
+  readonly projectDir?: string;
+  readonly path?: string;
+
+  constructor(input: {
+    reason: RuntimeStartupErrorReason;
+    message: string;
+    projectDir?: string;
+    path?: string;
+    cause?: unknown;
+  }) {
+    super(input.message, { cause: input.cause });
+    this.name = "RuntimeStartupError";
+    this.reason = input.reason;
+    this.projectDir = input.projectDir;
+    this.path = input.path;
+  }
+}
+
+export class RuntimeApiVersionError extends Error {
+  readonly version: string | null;
+  readonly supportedVersion: number;
+
+  constructor(input: { version: string | null; supportedVersion: number }) {
+    super(
+      input.version
+        ? `Unsupported Rigkit runtime API version ${input.version}; this host supports ${input.supportedVersion}`
+        : `Runtime did not report x-rigkit-api-version; this host requires ${input.supportedVersion}`,
+    );
+    this.name = "RuntimeApiVersionError";
+    this.version = input.version;
+    this.supportedVersion = input.supportedVersion;
+  }
+}
+
+export class RuntimeAuthError extends Error {
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+
+  constructor(input: { status: number; method: string; path: string; message?: string }) {
+    super(input.message ?? `${input.method} ${input.path} failed with authentication status ${input.status}`);
+    this.name = "RuntimeAuthError";
+    this.status = input.status;
+    this.method = input.method;
+    this.path = input.path;
+  }
+}
+
+export class RuntimeHttpError extends Error {
+  readonly status: number;
+  readonly method: string;
+  readonly path: string;
+
+  constructor(input: { status: number; method: string; path: string; message?: string; cause?: unknown }) {
+    super(input.message ?? `${input.method} ${input.path} failed with ${input.status}`, { cause: input.cause });
+    this.name = "RuntimeHttpError";
+    this.status = input.status;
+    this.method = input.method;
+    this.path = input.path;
+  }
+}
+
+export class RuntimeConnectionError extends Error {
+  readonly method: string;
+  readonly path: string;
+
+  constructor(input: { method: string; path: string; message?: string; cause?: unknown }) {
+    super(input.message ?? `${input.method} ${input.path} failed before the runtime responded`, { cause: input.cause });
+    this.name = "RuntimeConnectionError";
+    this.method = input.method;
+    this.path = input.path;
+  }
+}
+
+export class RuntimeProtocolError extends Error {
+  readonly method: string;
+  readonly path: string;
+
+  constructor(input: { method: string; path: string; message: string; cause?: unknown }) {
+    super(input.message, { cause: input.cause });
+    this.name = "RuntimeProtocolError";
+    this.method = input.method;
+    this.path = input.path;
+  }
+}
+
+export class RuntimeSessionError extends Error {
+  readonly url: string;
+
+  constructor(input: { url: string; message?: string; cause?: unknown }) {
+    super(input.message ?? `WebSocket session failed for ${input.url}`, { cause: input.cause });
+    this.name = "RuntimeSessionError";
+    this.url = input.url;
+  }
+}
+
+export type RuntimeClientError =
+  | RuntimeStartupError
+  | RuntimeApiVersionError
+  | RuntimeAuthError
+  | RuntimeHttpError
+  | RuntimeConnectionError
+  | RuntimeProtocolError
+  | RuntimeSessionError;
+
+export function isRuntimeClientError(error: unknown): error is RuntimeClientError {
+  return error instanceof RuntimeStartupError
+    || error instanceof RuntimeApiVersionError
+    || error instanceof RuntimeAuthError
+    || error instanceof RuntimeHttpError
+    || error instanceof RuntimeConnectionError
+    || error instanceof RuntimeProtocolError
+    || error instanceof RuntimeSessionError;
+}