@the-open-engine/zeroshot 6.25.1 → 6.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-open-engine/zeroshot",
-  "version": "6.25.1",
+  "version": "6.27.0",
   "description": "Multi-agent orchestration engine for Claude, Codex, and Gemini",
   "main": "src/orchestrator.js",
   "bin": {
@@ -40,19 +40,22 @@
     "test:coverage:report": "c8 --reporter=html npm run test:unit && echo 'Coverage report generated at coverage/index.html'",
     "postinstall": "node scripts/fix-node-pty-permissions.js && node scripts/check-path.js",
     "start": "node cli/index.js",
-    "typecheck": "tsc --noEmit && npm run typecheck:cluster",
+    "typecheck": "tsc --noEmit && npm run typecheck:cluster && npm run typecheck:hosted-target && npm run typecheck:hosted-session",
     "typecheck:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.json",
+    "typecheck:hosted-target": "tsc --project tsconfig.hosted-target.json",
+    "typecheck:hosted-session": "tsc --project tsconfig.hosted-session.json",
+    "test:hosted-target": "node --test tests/hosted-target/*.test.ts",
     "typecheck:cluster": "tsc --project tsconfig.cluster.json",
     "lint:agent-cli-provider": "eslint \"src/agent-cli-provider/**/*.ts\" \"tests/agent-cli-provider/**/*.ts\"",
     "build:agent-cli-provider": "tsc --project tsconfig.agent-cli-provider.build.json",
-    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && node scripts/build-cluster.js",
+    "build:cluster": "npm run protocol:generate && tsc --project tsconfig.cluster.cjs.json && tsc --project tsconfig.cluster.esm.json && tsc --project tsconfig.hosted-session.cjs.json && tsc --project tsconfig.hosted-session.esm.json && node scripts/build-cluster.js",
     "test:agent-cli-provider": "node --test tests/agent-cli-provider/*.test.js",
     "test:omp": "npm run build:agent-cli-provider && node --test tests/agent-cli-provider/omp-*.test.js && node tests/run-tests.js tests/omp-rpc-watcher.test.js tests/omp-isolation-capability.test.js tests/omp-docker-auth.test.js tests/omp-docker-fresh-only.test.js",
     "test:providers:live": "npm run build:agent-cli-provider && node scripts/live-provider-smoke.js",
     "check:agent-cli-provider": "npm run check:agent-cli-provider:ci",
     "check:agent-cli-provider:ci": "npm run typecheck:agent-cli-provider && npm run lint:agent-cli-provider && npm run build:agent-cli-provider && npm run test:agent-cli-provider",
-    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js",
-    "test:cluster-package": "npm run build:cluster && node --test tests/cluster/package.test.js",
+    "test:cluster-client": "npm run build:cluster && node --test tests/cluster/client.test.js tests/cluster/parity.test.js tests/cluster/architecture.test.js tests/cluster/verifier-regressions.test.js tests/cluster/request-validation.test.js tests/hosted-session/coordinator.test.js",
+    "test:cluster-package": "npm run build:agent-cli-provider && npm run build:cluster && node --test tests/cluster/package.test.js",
     "dev:link": "npm link",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
@@ -130,6 +133,12 @@
       "require": "./lib/cluster/index.cjs",
       "default": "./lib/cluster/index.cjs"
     },
+    "./hosted-session": {
+      "types": "./lib/hosted-session/index.d.ts",
+      "import": "./lib/hosted-session/index.mjs",
+      "require": "./lib/hosted-session/index.cjs",
+      "default": "./lib/hosted-session/index.cjs"
+    },
     "./package.json": "./package.json",
     "./*": "./*"
   },

package/scripts/build-cluster.js

@@ -4,8 +4,10 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const root = path.resolve(__dirname, '..');
-const buildRoot = path.join(root, '.cluster-build');
-const outputRoot = path.join(root, 'lib/cluster');
+const clusterBuildRoot = path.join(root, '.cluster-build');
+const hostedSessionBuildRoot = path.join(root, '.hosted-session-build');
+const clusterOutputRoot = path.join(root, 'lib/cluster');
+const hostedSessionOutputRoot = path.join(root, 'lib/hosted-session');
 
 function filesBelow(directory) {
   const entries = fs.readdirSync(directory, { withFileTypes: true });
@@ -15,7 +17,7 @@ function filesBelow(directory) {
   });
 }
 
-function copyBuild(sourceRoot, mode) {
+function copyBuild(sourceRoot, outputRoot, mode) {
   for (const source of filesBelow(sourceRoot)) {
     const relative = path.relative(sourceRoot, source);
     const extension = path.extname(relative);
@@ -37,7 +39,19 @@ function copyBuild(sourceRoot, mode) {
   }
 }
 
-fs.rmSync(outputRoot, { recursive: true, force: true });
-copyBuild(path.join(buildRoot, 'cjs'), 'cjs');
-copyBuild(path.join(buildRoot, 'esm'), 'esm');
-fs.rmSync(buildRoot, { recursive: true, force: true });
+fs.rmSync(clusterOutputRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionOutputRoot, { recursive: true, force: true });
+copyBuild(path.join(clusterBuildRoot, 'cjs'), clusterOutputRoot, 'cjs');
+copyBuild(path.join(clusterBuildRoot, 'esm'), clusterOutputRoot, 'esm');
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'cjs', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'cjs'
+);
+copyBuild(
+  path.join(hostedSessionBuildRoot, 'esm', 'hosted-session'),
+  hostedSessionOutputRoot,
+  'esm'
+);
+fs.rmSync(clusterBuildRoot, { recursive: true, force: true });
+fs.rmSync(hostedSessionBuildRoot, { recursive: true, force: true });

package/src/cluster/client.ts

@@ -16,16 +16,25 @@ import {
   WatchSubscriptionStream,
 } from './subscriptions.js';
 
+export interface WebSocketFactoryOptions {
+  readonly headers?: Readonly<Record<string, string>>;
+}
 export interface ConnectOptions {
   readonly protocols?: string | readonly string[];
-  readonly webSocketFactory?: (url: string, protocols?: string | readonly string[]) => WebSocketLike | Promise<WebSocketLike>;
+  readonly webSocketFactory?: (url: string, protocols?: string | readonly string[], options?: WebSocketFactoryOptions) => WebSocketLike | Promise<WebSocketLike>;
   readonly signal?: AbortSignal;
   readonly initialize?: InitializeParams;
+  readonly headers?: Readonly<Record<string, string>>;
 }
 export interface WatchSubscription { readonly result: WatchResult; readonly stream: WatchSubscriptionStream; }
 export interface LogsSubscription { readonly result: LogsResult; readonly stream: LogsSubscriptionStream; }
 export interface AgentAttachSubscription { readonly result: AgentAttachResult; readonly stream: AgentAttachSubscriptionStream; }
 export interface CoherentWatchSubscription extends WatchSubscription { readonly snapshot: GetResult; }
+export interface ConnectInitializedResult {
+  readonly connection: Connection;
+  readonly client: ClusterClient;
+  readonly initializeResult: InitializeResult;
+}
 
 export class ClusterClient {
   constructor(readonly connection: Connection) {}
@@ -114,6 +123,7 @@ export class ClusterClient {
 async function defaultWebSocketFactory(
   url: string,
   protocols?: string | readonly string[],
+  options?: WebSocketFactoryOptions,
 ): Promise<WebSocketLike> {
   const globalWebSocket = (globalThis as {
     readonly WebSocket?: new (
@@ -121,9 +131,16 @@ async function defaultWebSocketFactory(
       protocols?: string | readonly string[],
     ) => WebSocketLike;
   }).WebSocket;
-  if (globalWebSocket) return new globalWebSocket(url, protocols);
+  if (globalWebSocket) {
+    if (options?.headers && Object.keys(options.headers).length > 0) {
+      throw new ClusterConfigError(
+        'WebSocket upgrade headers require the ws library; the browser WebSocket API cannot carry request headers',
+        'HEADERS_UNSUPPORTED',
+      );
+    }
+    return new globalWebSocket(url, protocols);
+  }
   try {
-    // Dynamic loading keeps the optional Node runtime off the browser/global-WebSocket path.
     const imported: unknown = await import('ws');
     const candidate = imported !== null && typeof imported === 'object' && 'default' in imported
       ? imported.default
@@ -134,8 +151,9 @@ async function defaultWebSocketFactory(
     const Constructor = candidate as new (
       url: string,
       protocols?: string | readonly string[],
+      options?: { readonly headers?: Readonly<Record<string, string>> },
     ) => WebSocketLike;
-    return new Constructor(url, protocols);
+    return options?.headers ? new Constructor(url, protocols, { headers: options.headers }) : new Constructor(url, protocols);
   } catch (cause) {
     throw new ClusterConfigError(
       "No WebSocket runtime is available; install 'ws' or pass webSocketFactory",
@@ -181,7 +199,7 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
   const factory = options.webSocketFactory ?? defaultWebSocketFactory;
   let socket: WebSocketLike | undefined;
   try {
-    socket = await factory(url, options.protocols);
+    socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
     await waitForOpen(socket, options.signal);
     const connection = new Connection(socket);
     await new ClusterClient(connection).initialize(
@@ -197,3 +215,25 @@ export async function connect(url: string, options: ConnectOptions = {}): Promis
     throw error;
   }
 }
+
+export async function connectInitialized(url: string, options: ConnectOptions = {}): Promise<ConnectInitializedResult> {
+  const factory = options.webSocketFactory ?? defaultWebSocketFactory;
+  let socket: WebSocketLike | undefined;
+  try {
+    socket = await factory(url, options.protocols, options.headers ? { headers: options.headers } : undefined);
+    await waitForOpen(socket, options.signal);
+    const connection = new Connection(socket);
+    const client = new ClusterClient(connection);
+    const initializeResult = await client.initialize(
+      options.initialize,
+      options.signal === undefined ? {} : { signal: options.signal },
+    );
+    return { connection, client, initializeResult };
+  } catch (error) {
+    if (socket) {
+      try { await socket.close(); }
+      catch { /* preserve the construction error */ }
+    }
+    throw error;
+  }
+}

package/src/cluster/connection.ts

@@ -27,6 +27,20 @@ export const CONNECTION_TRANSITIONS: Readonly<Record<ConnectionState, readonly C
   CLOSED: Object.freeze([] as const),
 });
 export const PROTOCOL_DIAGNOSTIC_CAPACITY = 128;
+export const CLOSE_REASON_MAX_BYTES = 123;
+const CLOSE_REASON_ENCODER = new TextEncoder();
+function boundedCloseReason(reason: string): string {
+  const retained: string[] = [];
+  const scratch = new Uint8Array(4);
+  let bytes = 0;
+  for (const codePoint of reason) {
+    const { written } = CLOSE_REASON_ENCODER.encodeInto(codePoint, scratch);
+    if (bytes + written > CLOSE_REASON_MAX_BYTES) break;
+    retained.push(codePoint);
+    bytes += written;
+  }
+  return retained.join('');
+}
 export interface CallOptions { readonly signal?: AbortSignal; readonly requestTimeoutMs?: number; }
 
 type Deferred<T> = {
@@ -70,6 +84,8 @@ export class Connection {
   readonly #removeSocketListeners: Array<() => void> = [];
   readonly #ownedSubscriptions = new WeakSet<SubscriptionRegistration>();
   #closePromise?: Promise<void>;
+  #closeCode: number | undefined;
+  #closeReason: string | undefined;
   readonly closeDiagnostics: unknown[] = [];
   readonly protocolDiagnostics: ClusterProtocolError[] = [];
 
@@ -80,12 +96,14 @@ export class Connection {
     this.#removeSocketListeners.push(
       addSocketListener(socket, 'message', (event) => this.#onMessage(event)),
       addSocketListener(socket, 'error', () => { void this.#startClose(false); }),
-      addSocketListener(socket, 'close', () => { void this.#startClose(false); }),
+      addSocketListener(socket, 'close', (...args: unknown[]) => { this.#captureCloseState(args); void this.#startClose(false); }),
     );
   }
   get state(): ConnectionState { return this.#state; }
   get pendingSize(): number { return this.#pending.size; }
   get subscriptionCount(): number { return this.#subscriptions.size; }
+  get closeCode(): number | undefined { return this.#closeCode; }
+  get closeReason(): string | undefined { return this.#closeReason; }
   call<M extends UnaryClusterMethod>(method: M, params: ClusterMethodParams[M], options: CallOptions = {}): Promise<ClusterMethodResults[M]> {
     if (!(UNARY_METHODS as readonly string[]).includes(method)) {
       throw new ClusterConfigError(`${method} is a subscription method`, 'INVALID_METHOD');
@@ -266,6 +284,19 @@ export class Connection {
     if (this.protocolDiagnostics.length === PROTOCOL_DIAGNOSTIC_CAPACITY) this.protocolDiagnostics.shift();
     this.protocolDiagnostics.push(new ClusterProtocolError(message, 'INVALID_PEER_FRAME', cause === undefined ? undefined : { cause }));
   }
+  #captureCloseState(args: unknown[]): void {
+    if (args.length === 0) return;
+    const first = args[0];
+    if (typeof first === 'number') {
+      this.#closeCode = first;
+      const raw = args.length > 1 ? String(args[1]) : undefined;
+      this.#closeReason = raw === undefined ? undefined : boundedCloseReason(raw);
+    } else if (first !== null && typeof first === 'object') {
+      const event = first as { code?: unknown; reason?: unknown };
+      if (typeof event.code === 'number') this.#closeCode = event.code;
+      if (typeof event.reason === 'string') this.#closeReason = boundedCloseReason(event.reason);
+    }
+  }
   #startClose(sendCancels: boolean): Promise<void> {
     if (this.#closePromise) return this.#closePromise; if (this.#state === 'CLOSED') return Promise.resolve();
     this.#transition('CLOSING'); this.#closePromise = Promise.resolve().then(() => this.#finishClose(sendCancels)); return this.#closePromise;

package/src/cluster/index.ts

@@ -14,7 +14,7 @@ export {
 export { assertGraphProfile, assertGraphProfileSupported, assertGraphSpec } from './validators.js';
 export * from './payload-value.js';
 export * from './json-source.js';
-export { CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
+export { CLOSE_REASON_MAX_BYTES, CONNECTION_TRANSITIONS, PROTOCOL_DIAGNOSTIC_CAPACITY, Connection } from './connection.js';
 export type {
   CallOptions,
   ConnectionState,
@@ -32,11 +32,13 @@ export type {
   WatchSubscriptionItem,
   WatchSubscriptionClosedItem,
 } from './subscriptions.js';
-export { ClusterClient, connect } from './client.js';
+export { ClusterClient, connect, connectInitialized } from './client.js';
 export type {
   AgentAttachSubscription,
   CoherentWatchSubscription,
+  ConnectInitializedResult,
   ConnectOptions,
   LogsSubscription,
   WatchSubscription,
+  WebSocketFactoryOptions,
 } from './client.js';

package/src/cluster/ws.d.ts

@@ -2,6 +2,7 @@ declare module 'ws' {
   const WebSocket: new (
     url: string,
     protocols?: string | readonly string[],
+    options?: { readonly headers?: Readonly<Record<string, string>> },
   ) => import('./index.js').WebSocketLike;
   export default WebSocket;
 }

package/src/hosted-session/coordinator.ts

@@ -0,0 +1,110 @@
+import { ClusterConfigError, connectInitialized } from '../cluster/index.js';
+import type { ServerCapabilities, GraphProfile } from '../cluster/index.js';
+import type { ConnectOptions } from '../cluster/index.js';
+import type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';
+
+function combineSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined {
+  const defined = signals.filter((s): s is AbortSignal => s !== undefined);
+  if (defined.length === 0) return undefined;
+  if (defined.length === 1) return defined[0];
+  return AbortSignal.any(defined);
+}
+
+export class HostedSessionCoordinator {
+  readonly #getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly #connectOptions: Omit<ConnectOptions, 'headers' | 'signal'> | undefined;
+  readonly #clock: { now(): number };
+  readonly #closeController = new AbortController();
+  #referenceCapabilities: ServerCapabilities | undefined;
+  #closed = false;
+
+  constructor(init: HostedSessionInit) {
+    this.#getAccess = init.getAccess;
+    this.#connectOptions = init.connectOptions;
+    this.#clock = init.clock ?? Date;
+  }
+
+  async open(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#referenceCapabilities = session.initializeResult.capabilities;
+    return session;
+  }
+
+  async replace(signal?: AbortSignal): Promise<InitializedSession> {
+    this.#requireNotClosed();
+    const session = await this.#createSession(signal);
+    this.#verifyCapabilities(session.initializeResult.capabilities, session);
+    return session;
+  }
+
+  renewalDeadline(access: AccessResponse, receivedAt: number): number {
+    const expiresAt = Date.parse(access.expiresAt);
+    if (Number.isNaN(expiresAt)) {
+      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    }
+    const lifetime = expiresAt - receivedAt;
+    return Math.min(expiresAt - 30_000, receivedAt + 0.8 * lifetime);
+  }
+
+  async close(): Promise<void> {
+    this.#closed = true;
+    this.#closeController.abort();
+  }
+
+  async #createSession(signal?: AbortSignal): Promise<InitializedSession> {
+    const combined = combineSignals([signal, this.#closeController.signal]);
+    const access = await this.#getAccess(combined);
+    const expiresAt = Date.parse(access.expiresAt);
+    if (Number.isNaN(expiresAt)) {
+      throw new ClusterConfigError(`invalid expiresAt: ${access.expiresAt}`, 'INVALID_EXPIRY');
+    }
+    if (expiresAt <= this.#clock.now()) {
+      throw new ClusterConfigError('access token is already expired', 'ACCESS_EXPIRED');
+    }
+
+    let endpoint: URL;
+    try {
+      endpoint = new URL(access.endpoint);
+    } catch {
+      throw new ClusterConfigError('hosted access endpoint is invalid', 'INVALID_ENDPOINT');
+    }
+    if (endpoint.protocol !== 'wss:') {
+      throw new ClusterConfigError('hosted access endpoint must use wss', 'INSECURE_ENDPOINT');
+    }
+
+    return connectInitialized(endpoint.href, {
+      ...this.#connectOptions,
+      headers: { Authorization: `Bearer ${access.token}` },
+      ...(combined !== undefined ? { signal: combined } : {}),
+    });
+  }
+
+  #verifyCapabilities(incoming: ServerCapabilities, session: InitializedSession): void {
+    if (!this.#referenceCapabilities) return;
+    const ref = this.#referenceCapabilities;
+    const mismatches: string[] = [];
+
+    if (ref.graphProfiles) {
+      const incomingProfiles = new Set<GraphProfile>(incoming.graphProfiles ?? []);
+      for (const profile of ref.graphProfiles) {
+        if (!incomingProfiles.has(profile)) mismatches.push(`missing graphProfile: ${profile}`);
+      }
+    }
+    if (ref.logs && !incoming.logs) mismatches.push('missing capability: logs');
+    if (ref.agentAttach && !incoming.agentAttach)
+      mismatches.push('missing capability: agentAttach');
+
+    if (mismatches.length > 0) {
+      void session.connection.close();
+      throw new ClusterConfigError(
+        `replacement capabilities incompatible: ${mismatches.join(', ')}`,
+        'INCOMPATIBLE_CAPABILITIES'
+      );
+    }
+  }
+
+  #requireNotClosed(): void {
+    if (this.#closed) throw new ClusterConfigError('coordinator is closed', 'COORDINATOR_CLOSED');
+  }
+}

package/src/hosted-session/index.ts

@@ -0,0 +1,2 @@
+export { HostedSessionCoordinator } from './coordinator.js';
+export type { AccessResponse, HostedSessionInit, InitializedSession } from './types.js';

package/src/hosted-session/types.ts

@@ -0,0 +1,21 @@
+import type { Connection } from '../cluster/index.js';
+import type { ClusterClient, ConnectOptions } from '../cluster/index.js';
+import type { InitializeResult } from '../cluster/index.js';
+
+export interface AccessResponse {
+  readonly endpoint: string;
+  readonly token: string;
+  readonly expiresAt: string;
+}
+
+export interface HostedSessionInit {
+  readonly getAccess: (signal?: AbortSignal) => Promise<AccessResponse>;
+  readonly connectOptions?: Omit<ConnectOptions, 'headers' | 'signal'>;
+  readonly clock?: { now(): number };
+}
+
+export interface InitializedSession {
+  readonly connection: Connection;
+  readonly client: ClusterClient;
+  readonly initializeResult: InitializeResult;
+}

package/src/hosted-target/bounds.ts

@@ -0,0 +1,6 @@
+export const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const MAX_PAGINATION_PAGES = 100;
+export const MAX_RETRY_ATTEMPTS = 3;
+export const MAX_RETRY_ELAPSED_MS = 30_000;
+export const MAX_ERROR_BODY_BYTES = 8192;
+export const IDEMPOTENCY_KEY_PATTERN = /^[a-zA-Z0-9_-]{1,128}$/;

package/src/hosted-target/errors.ts

@@ -0,0 +1,90 @@
+function sanitize(text: string): string {
+  return text
+    .replace(/Authorization:\s*Bearer\s+\S+/gi, 'Authorization: Bearer [REDACTED]')
+    .replace(/token["']?\s*[:=]\s*["'][^"']+["']/gi, 'token: "[REDACTED]"')
+    .replace(/https?:\/\/[^\s]*(?:token|key|secret|credential|auth)[^\s]*/gi, '[REDACTED_URL]');
+}
+
+function sanitizeCause(cause: unknown): unknown {
+  if (!cause) return cause;
+  if (cause instanceof Error) {
+    const cleaned = new Error(sanitize(cause.message));
+    cleaned.name = cause.name;
+    if (cause.cause) cleaned.cause = sanitizeCause(cause.cause);
+    return cleaned;
+  }
+  if (typeof cause === 'string') return sanitize(cause);
+  return cause;
+}
+
+export class TargetAdapterError extends Error {
+  readonly code: string;
+  readonly retryable: boolean;
+
+  constructor(code: string, message: string, retryable: boolean, cause?: unknown) {
+    super(sanitize(message), { cause: sanitizeCause(cause) });
+    this.name = 'TargetAdapterError';
+    this.code = code;
+    this.retryable = retryable;
+  }
+}
+
+export class TargetAuthError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('AUTH_FAILED', message, false, cause);
+    this.name = 'TargetAuthError';
+  }
+}
+
+export class TargetConflictError extends TargetAdapterError {
+  readonly idempotencyKey: string;
+
+  constructor(idempotencyKey: string, message: string, cause?: unknown) {
+    super('CONFLICT', message, true, cause);
+    this.name = 'TargetConflictError';
+    this.idempotencyKey = idempotencyKey;
+  }
+}
+
+export class TargetRateLimitError extends TargetAdapterError {
+  readonly retryAfterMs: number | undefined;
+
+  constructor(message: string, retryAfterMs?: number, cause?: unknown) {
+    super('RATE_LIMITED', message, true, cause);
+    this.name = 'TargetRateLimitError';
+    this.retryAfterMs = retryAfterMs;
+  }
+}
+
+export class TargetTransportError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('TRANSPORT', message, true, cause);
+    this.name = 'TargetTransportError';
+  }
+}
+
+export class TargetProtocolError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('PROTOCOL', message, false, cause);
+    this.name = 'TargetProtocolError';
+  }
+}
+
+export class TargetCapacityError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('CAPACITY', message, false, cause);
+    this.name = 'TargetCapacityError';
+  }
+}
+
+export class TargetNotFoundError extends TargetAdapterError {
+  constructor(message: string, cause?: unknown) {
+    super('NOT_FOUND', message, false, cause);
+    this.name = 'TargetNotFoundError';
+  }
+}
+
+export function isRetryable(error: unknown): boolean {
+  if (error instanceof TargetAdapterError) return error.retryable;
+  return false;
+}

package/src/hosted-target/index.ts

@@ -0,0 +1,44 @@
+export type { TargetAdapter } from './target-adapter.ts';
+export { ZeroCloudV1TargetAdapter } from './zero-cloud-v1-adapter.ts';
+export {
+  TargetAdapterError,
+  TargetAuthError,
+  TargetConflictError,
+  TargetRateLimitError,
+  TargetTransportError,
+  TargetProtocolError,
+  TargetCapacityError,
+  TargetNotFoundError,
+  isRetryable,
+} from './errors.ts';
+export type {
+  TargetAccessTokenProvider,
+  CapsuleState,
+  Capsule,
+  CapsuleAccess,
+  CapsuleListPage,
+  CapsuleLimits,
+  AllocateRequest,
+  HttpTransport,
+  Clock,
+  RetryPolicy,
+  TargetDiscovery,
+} from './types.ts';
+export { KNOWN_CAPSULE_STATES } from './types.ts';
+export {
+  MAX_RESPONSE_BYTES,
+  MAX_PAGINATION_PAGES,
+  MAX_RETRY_ATTEMPTS,
+  MAX_RETRY_ELAPSED_MS,
+  MAX_ERROR_BODY_BYTES,
+  IDEMPOTENCY_KEY_PATTERN,
+} from './bounds.ts';
+export { DefaultRetryPolicy, parseRetryAfter } from './retry.ts';
+export {
+  assertRequiredFields,
+  assertKnownEnum,
+  assertCapsule,
+  assertCapsuleAccess,
+  assertCapsuleLimits,
+  assertCapsuleListPage,
+} from './response-validation.ts';

package/src/hosted-target/response-validation.ts

@@ -0,0 +1,86 @@
+import { TargetProtocolError } from './errors.ts';
+import { KNOWN_CAPSULE_STATES } from './types.ts';
+import type { Capsule, CapsuleAccess, CapsuleLimits, CapsuleListPage } from './types.ts';
+
+export function assertRequiredFields(
+  body: unknown,
+  fields: readonly string[],
+  context: string,
+): asserts body is Record<string, unknown> {
+  if (body === null || typeof body !== 'object') {
+    throw new TargetProtocolError(`${context}: expected object, got ${typeof body}`);
+  }
+  const record = body as Record<string, unknown>;
+  for (const field of fields) {
+    if (record[field] === undefined || record[field] === null) {
+      throw new TargetProtocolError(`${context}: missing required field "${field}"`);
+    }
+  }
+}
+
+export function assertKnownEnum(value: string, known: readonly string[], field: string): void {
+  if (!known.includes(value)) {
+    // eslint-disable-next-line no-console
+    console.warn(`Unknown ${field} value: "${value}". Known values: ${known.join(', ')}`);
+  }
+}
+
+export function assertCapsule(body: unknown): Capsule {
+  assertRequiredFields(body, ['id', 'state', 'createdAt'], 'Capsule');
+  const record = body as Record<string, unknown>;
+  if (typeof record['id'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "id" must be a string');
+  }
+  if (typeof record['state'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "state" must be a string');
+  }
+  if (typeof record['createdAt'] !== 'string') {
+    throw new TargetProtocolError('Capsule: "createdAt" must be a string');
+  }
+  assertKnownEnum(record['state'] as string, KNOWN_CAPSULE_STATES, 'CapsuleState');
+  return record as unknown as Capsule;
+}
+
+export function assertCapsuleAccess(body: unknown): CapsuleAccess {
+  assertRequiredFields(body, ['endpoint', 'token', 'expiresAt'], 'CapsuleAccess');
+  const record = body as Record<string, unknown>;
+  if (typeof record['endpoint'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "endpoint" must be a string');
+  }
+  if (typeof record['token'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "token" must be a string');
+  }
+  if (typeof record['expiresAt'] !== 'string') {
+    throw new TargetProtocolError('CapsuleAccess: "expiresAt" must be a string');
+  }
+  return record as unknown as CapsuleAccess;
+}
+
+export function assertCapsuleLimits(body: unknown): CapsuleLimits {
+  assertRequiredFields(body, ['maxConcurrent', 'maxPerHour'], 'CapsuleLimits');
+  const record = body as Record<string, unknown>;
+  if (typeof record['maxConcurrent'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxConcurrent" must be a number');
+  }
+  if (typeof record['maxPerHour'] !== 'number') {
+    throw new TargetProtocolError('CapsuleLimits: "maxPerHour" must be a number');
+  }
+  return record as unknown as CapsuleLimits;
+}
+
+export function assertCapsuleListPage(body: unknown): CapsuleListPage {
+  assertRequiredFields(body, ['items'], 'CapsuleListPage');
+  const record = body as Record<string, unknown>;
+  if (!Array.isArray(record['items'])) {
+    throw new TargetProtocolError('CapsuleListPage: "items" must be an array');
+  }
+  const items = (record['items'] as unknown[]).map((item) => assertCapsule(item));
+  const cursor = record['cursor'];
+  if (cursor !== undefined && cursor !== null && typeof cursor !== 'string') {
+    throw new TargetProtocolError('CapsuleListPage: "cursor" must be a string if present');
+  }
+  if (typeof cursor === 'string') {
+    return { items, cursor };
+  }
+  return { items };
+}