agent-relay-sdk 0.2.0 → 0.2.2

package/src/context-probe.ts

@@ -0,0 +1,257 @@
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
+import type { ContextProbeMetrics } from "./types.js";
+
+export interface ContextProbeOptions {
+  wrapCommand?: string;
+  agentId?: string;
+  stateDir?: string;
+  standalone?: boolean;
+  now?: number;
+  env?: Record<string, string | undefined>;
+  parsePatterns?: ParsePattern[];
+}
+
+export interface ParsePattern {
+  name: string;
+  regex: RegExp;
+  extract(match: RegExpMatchArray): Partial<ContextProbeMetrics>;
+}
+
+export interface ContextProbeRunResult {
+  metrics: ContextProbeMetrics | null;
+  stateFile?: string;
+  wrappedExitCode?: number;
+  wrappedStdout?: string;
+  wrappedStderr?: string;
+  output: string;
+}
+
+export const DEFAULT_CONTEXT_PROBE_STATE_DIR = tmpdir();
+
+export const DEFAULT_CONTEXT_PROBE_PATTERNS: ParsePattern[] = [
+  {
+    name: "percent",
+    regex: /(\d+(?:\.\d+)?)%\s*(?:context|ctx)?/i,
+    extract: (match) => ({ contextPercent: Number(match[1]) }),
+  },
+  {
+    name: "token-count",
+    regex: /(\d[\d,]*)\s*\/\s*(\d[\d,]*)\s*(?:tokens?|tok)/i,
+    extract: (match) => ({
+      tokensUsed: parseInt(String(match[1]).replace(/,/g, ""), 10),
+      tokensMax: parseInt(String(match[2]).replace(/,/g, ""), 10),
+    }),
+  },
+  {
+    name: "quota",
+    regex: /quota[:\s]+(\d+(?:\.\d+)?)\s*%/i,
+    extract: (match) => ({ quotaUsed: Number(match[1]) }),
+  },
+];
+
+export function contextProbeStatePath(agentId: string, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): string {
+  return join(stateDir, `agent-relay-context-${safeStateId(agentId)}.json`);
+}
+
+export function parseContextProbeMetrics(
+  input: string,
+  options: Pick<ContextProbeOptions, "agentId" | "now" | "parsePatterns" | "env"> = {},
+): ContextProbeMetrics | null {
+  const timestamp = options.now ?? Date.now();
+  const fromJson = parseClaudeStatusLineInput(input, options.agentId, timestamp, options.env);
+  if (fromJson) return fromJson;
+
+  const partial: Partial<ContextProbeMetrics> = {};
+  for (const pattern of options.parsePatterns ?? DEFAULT_CONTEXT_PROBE_PATTERNS) {
+    const match = input.match(pattern.regex);
+    if (match) Object.assign(partial, pattern.extract(match));
+  }
+  if (partial.contextPercent === undefined && partial.tokensUsed !== undefined && partial.tokensMax) {
+    partial.contextPercent = (partial.tokensUsed / partial.tokensMax) * 100;
+  }
+  if (partial.contextPercent === undefined) return null;
+  return normalizeMetrics({
+    agentId: options.agentId || envAgentId(options.env) || "unknown",
+    contextPercent: partial.contextPercent,
+    tokensUsed: partial.tokensUsed,
+    tokensMax: partial.tokensMax,
+    quotaUsed: partial.quotaUsed,
+    quotaLimit: partial.quotaLimit,
+    quotaResetIn: partial.quotaResetIn,
+    source: partial.source ?? "statusline",
+    confidence: partial.confidence ?? "estimated",
+    timestamp,
+  });
+}
+
+export function contextStateFromProbeMetrics(metrics: ContextProbeMetrics) {
+  return {
+    utilization: Math.max(0, Math.min(1, metrics.contextPercent / 100)),
+    ...(metrics.tokensUsed !== undefined ? { tokensUsed: metrics.tokensUsed } : {}),
+    ...(metrics.tokensMax !== undefined ? { tokensMax: metrics.tokensMax } : {}),
+    lifecycleState: "working" as const,
+    warmTopics: [],
+    activeMemories: [],
+    tasksSinceCompact: 0,
+    lastUpdatedAt: metrics.timestamp,
+    source: metrics.source,
+    confidence: metrics.confidence,
+  };
+}
+
+export function writeContextProbeState(metrics: ContextProbeMetrics, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): string {
+  const file = contextProbeStatePath(metrics.agentId, stateDir);
+  mkdirSync(dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, JSON.stringify(metrics, null, 2));
+  renameSync(tmp, file);
+  return file;
+}
+
+export function readContextProbeState(agentId: string, stateDir = DEFAULT_CONTEXT_PROBE_STATE_DIR): ContextProbeMetrics | null {
+  try {
+    const parsed = JSON.parse(readFileSync(contextProbeStatePath(agentId, stateDir), "utf8")) as unknown;
+    return isContextProbeMetrics(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function runContextProbe(input: string, options: ContextProbeOptions = {}): ContextProbeRunResult {
+  let wrappedExitCode: number | undefined;
+  let wrappedStdout = "";
+  let wrappedStderr = "";
+  if (options.wrapCommand) {
+    const result = spawnSync(options.wrapCommand, {
+      input,
+      shell: true,
+      encoding: "utf8",
+      env: { ...process.env, ...(options.env ?? {}) },
+    });
+    wrappedExitCode = typeof result.status === "number" ? result.status : result.error ? 1 : 0;
+    wrappedStdout = result.stdout ?? "";
+    wrappedStderr = result.stderr ?? "";
+  }
+
+  const metrics = parseContextProbeMetrics(input, options) ??
+    (wrappedStdout ? parseContextProbeMetrics(wrappedStdout, { ...options, now: options.now }) : null);
+  const stateFile = metrics ? writeContextProbeState(metrics, options.stateDir) : undefined;
+  const output = options.wrapCommand ? wrappedStdout : standaloneOutput(metrics);
+  return { metrics, stateFile, wrappedExitCode, wrappedStdout, wrappedStderr, output };
+}
+
+function parseClaudeStatusLineInput(
+  input: string,
+  explicitAgentId: string | undefined,
+  timestamp: number,
+  env: Record<string, string | undefined> | undefined,
+): ContextProbeMetrics | null {
+  let data: unknown;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    return null;
+  }
+  if (!isRecord(data)) return null;
+  const context = isRecord(data.context_window) ? data.context_window : undefined;
+  if (!context) return null;
+  const contextPercent = numberValue(context.used_percentage);
+  const tokensMax = numberValue(context.context_window_size);
+  const usage = isRecord(context.current_usage) ? context.current_usage : undefined;
+  const tokensUsed = sumNumbers(
+    usage?.input_tokens,
+    usage?.cache_creation_input_tokens,
+    usage?.cache_read_input_tokens,
+  );
+  if (contextPercent === undefined && tokensUsed === undefined) return null;
+  const rateLimits = isRecord(data.rate_limits) ? data.rate_limits : undefined;
+  const fiveHour = isRecord(rateLimits?.five_hour) ? rateLimits.five_hour : undefined;
+  const model = stringValue(data.model) ?? envString(env, "CLAUDE_MODEL");
+  const effort = isRecord(data.effort) ? stringValue(data.effort.level) : stringValue(data.effort);
+  const resolvedEffort = effort ?? envString(env, "CLAUDE_EFFORT") ?? envString(env, "CLAUDE_CODE_EFFORT_LEVEL");
+  return normalizeMetrics({
+    agentId: explicitAgentId || envAgentId(env) || stringValue(data.session_id) || "unknown",
+    contextPercent: contextPercent ?? ((tokensUsed ?? 0) / (tokensMax || 1)) * 100,
+    tokensUsed,
+    tokensMax,
+    quotaUsed: numberValue(fiveHour?.used_percentage),
+    quotaResetIn: secondsUntil(numberValue(fiveHour?.resets_at), timestamp),
+    ...(model ? { model } : {}),
+    ...(resolvedEffort ? { effort: resolvedEffort } : {}),
+    source: "statusline",
+    confidence: "exact",
+    timestamp,
+  });
+}
+
+function normalizeMetrics(metrics: ContextProbeMetrics): ContextProbeMetrics {
+  return {
+    ...metrics,
+    contextPercent: Math.max(0, Math.min(100, metrics.contextPercent)),
+  };
+}
+
+function standaloneOutput(metrics: ContextProbeMetrics | null): string {
+  if (!metrics) return "agent-relay context: unavailable";
+  const pct = Math.round(metrics.contextPercent);
+  const tokens = metrics.tokensUsed && metrics.tokensMax ? ` ${formatTokens(metrics.tokensUsed)}/${formatTokens(metrics.tokensMax)}` : "";
+  return `agent-relay context: ${pct}%${tokens}`;
+}
+
+function formatTokens(tokens: number): string {
+  if (tokens >= 1_000_000) return `${(tokens / 1_000_000).toFixed(1)}M`;
+  if (tokens >= 1_000) return `${Math.round(tokens / 1_000)}K`;
+  return String(tokens);
+}
+
+function safeStateId(agentId: string): string {
+  return basename(agentId).replace(/[^a-zA-Z0-9._-]/g, "-") || "unknown";
+}
+
+function envAgentId(env: Record<string, string | undefined> | undefined): string | undefined {
+  if (env !== undefined) return stringValue(env.AGENT_RELAY_AGENT_ID) ?? stringValue(env.AGENT_RELAY_ID);
+  return stringValue(process.env.AGENT_RELAY_AGENT_ID) ?? stringValue(process.env.AGENT_RELAY_ID);
+}
+
+function envString(env: Record<string, string | undefined> | undefined, key: string): string | undefined {
+  if (env !== undefined) return stringValue(env[key]);
+  return stringValue(process.env[key]);
+}
+
+function numberValue(value: unknown): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+
+function stringValue(value: unknown): string | undefined {
+  return typeof value === "string" && value ? value : undefined;
+}
+
+function sumNumbers(...values: unknown[]): number | undefined {
+  let total = 0;
+  let seen = false;
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      total += value;
+      seen = true;
+    }
+  }
+  return seen ? total : undefined;
+}
+
+function secondsUntil(epochSeconds: number | undefined, nowMs: number): number | undefined {
+  return epochSeconds === undefined ? undefined : Math.max(0, Math.round(epochSeconds - nowMs / 1000));
+}
+
+function isContextProbeMetrics(value: unknown): value is ContextProbeMetrics {
+  return isRecord(value) &&
+    typeof value.agentId === "string" &&
+    typeof value.contextPercent === "number" &&
+    typeof value.timestamp === "number";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/contracts.ts

@@ -0,0 +1,47 @@
+import type { ContractCompatibility, ContractCompatibilityIssue, RuntimeContractName, RuntimeContracts } from "./types.js";
+
+export const CONTRACT_VERSIONS = {
+  relayApi: 1,
+  orchestratorProtocol: 3,
+  runnerProtocol: 1,
+  providerPluginProtocol: 1,
+} as const satisfies Record<RuntimeContractName, number>;
+
+export const CONTRACT_REQUIREMENTS = {
+  orchestratorProtocol: { min: 3, maxExclusive: 4 },
+  runnerProtocol: { min: 1, maxExclusive: 2 },
+  providerPluginProtocol: { min: 1, maxExclusive: 2 },
+} as const;
+
+export interface ContractRequirement {
+  min: number;
+  maxExclusive: number;
+}
+
+export function contractCompatibility(
+  contracts: RuntimeContracts,
+  requirements: Partial<Record<RuntimeContractName, ContractRequirement>>,
+): ContractCompatibility {
+  const issues: ContractCompatibilityIssue[] = [];
+  let unknown = false;
+
+  for (const [contract, requirement] of Object.entries(requirements) as Array<[RuntimeContractName, ContractRequirement]>) {
+    const actual = contracts[contract];
+    const expected = `>=${requirement.min} <${requirement.maxExclusive}`;
+    if (!Number.isFinite(actual)) {
+      unknown = true;
+      issues.push({ contract, expected });
+      continue;
+    }
+    if (actual! < requirement.min || actual! >= requirement.maxExclusive) {
+      issues.push({ contract, expected, actual });
+    }
+  }
+
+  const incompatible = issues.some((issue) => issue.actual !== undefined);
+  return {
+    status: incompatible ? "incompatible" : unknown ? "unknown" : "compatible",
+    compatible: !incompatible && !unknown,
+    issues,
+  };
+}

package/src/http-client.ts

@@ -1,4 +1,4 @@
-import type { AgentCard, PollQuery, RegisterAgentInput, SendMessageInput, Message } from "./types.js";
+import type { AgentCard, Artifact, ArtifactKind, ArtifactSensitivity, PollQuery, RegisterAgentInput, SendMessageInput, Message, MessageDeliveryState, MessageDeliveryStatus, ReplyObligation, Task, TaskStatusInput } from "./types.js";
 
 export interface HttpClientOptions {
   baseUrl: string;
@@ -20,7 +20,7 @@ export class RelayHttpError extends Error {
 
 export class RelayHttpClient {
   private readonly baseUrl: string;
-  private readonly token?: string;
+  private token?: string;
   private readonly timeout: number;
 
   constructor(options: HttpClientOptions) {
@@ -29,6 +29,10 @@ export class RelayHttpClient {
     this.timeout = options.timeout ?? 10_000;
   }
 
+  setToken(token?: string): void {
+    this.token = token;
+  }
+
   registerAgent(input: RegisterAgentInput): Promise<AgentCard> {
     return this.json("POST", "/api/agents", input) as Promise<AgentCard>;
   }
@@ -39,6 +43,10 @@ export class RelayHttpClient {
     return this.parseResponse(response, "GET", `/api/agents/${id}`) as Promise<AgentCard>;
   }
 
+  listReplyObligations(agentId: string): Promise<ReplyObligation[]> {
+    return this.json("GET", `/api/agents/${encodeURIComponent(agentId)}/reply-obligations`) as Promise<ReplyObligation[]>;
+  }
+
   listAgents(filter: { tag?: string; machine?: string; status?: string } = {}): Promise<AgentCard[]> {
     const url = this.url("/api/agents");
     for (const [key, value] of Object.entries(filter)) {
@@ -47,16 +55,16 @@ export class RelayHttpClient {
     return this.jsonUrl("GET", url) as Promise<AgentCard[]>;
   }
 
-  async heartbeat(agentId: string): Promise<void> {
-    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`);
+  async heartbeat(agentId: string, instanceId?: string): Promise<void> {
+    await this.json("POST", `/api/agents/${encodeURIComponent(agentId)}/heartbeat`, instanceId ? { instanceId } : undefined);
   }
 
-  async setStatus(agentId: string, status: string): Promise<void> {
-    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { status });
+  async setStatus(agentId: string, status: string, instanceId?: string): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/status`, { status, ...(instanceId ? { instanceId } : {}) });
   }
 
-  async setReady(agentId: string, ready: boolean): Promise<void> {
-    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready });
+  async setReady(agentId: string, ready: boolean, instanceId?: string): Promise<void> {
+    await this.json("PATCH", `/api/agents/${encodeURIComponent(agentId)}/ready`, { ready, ...(instanceId ? { instanceId } : {}) });
   }
 
   async setLabel(agentId: string, label: string | null): Promise<void> {
@@ -93,13 +101,54 @@ export class RelayHttpClient {
     return this.json("GET", `/api/messages/${messageId}/thread`) as Promise<Message[]>;
   }
 
+  getMessageDelivery(messageId: number): Promise<MessageDeliveryState> {
+    return this.json("GET", `/api/messages/${messageId}/delivery`) as Promise<MessageDeliveryState>;
+  }
+
+  recordMessageDeliveryAttempt(messageId: number, input: {
+    agentId?: string;
+    status: MessageDeliveryStatus;
+    error?: string;
+    nextRetryAt?: number;
+    poisonReason?: string;
+  }): Promise<MessageDeliveryState> {
+    return this.json("POST", `/api/messages/${messageId}/delivery/attempts`, input) as Promise<MessageDeliveryState>;
+  }
+
+  updateMessageDelivery(messageId: number, input: {
+    action: "retry-now" | "mark-dead" | "clear";
+    reason?: string;
+    agentId?: string;
+  }): Promise<MessageDeliveryState> {
+    return this.json("POST", `/api/messages/${messageId}/delivery/actions`, input) as Promise<MessageDeliveryState>;
+  }
+
   async claimMessage(messageId: number, agentId: string): Promise<boolean> {
+    return (await this.claimMessageResult(messageId, agentId)).ok;
+  }
+
+  async claimMessageResult(messageId: number, agentId: string): Promise<{ ok: boolean; claimExpiresAt?: number; task?: Task }> {
     const path = `/api/messages/${messageId}/claim`;
     const response = await this.request("POST", path, { agentId });
-    if (response.ok) return true;
-    if ([400, 404, 409].includes(response.status)) return false;
+    if (response.ok) return this.parseResponse(response, "POST", path) as Promise<{ ok: boolean; claimExpiresAt?: number; task?: Task }>;
+    if ([400, 404, 409].includes(response.status)) return { ok: false };
+    await this.parseResponse(response, "POST", path);
+    return { ok: false };
+  }
+
+  async renewMessageClaim(messageId: number, agentId: string): Promise<{ ok: boolean; claimExpiresAt?: number }> {
+    const path = `/api/messages/${messageId}/claim/renew`;
+    const response = await this.request("POST", path, { agentId });
+    if (response.ok) return this.parseResponse(response, "POST", path) as Promise<{ ok: boolean; claimExpiresAt?: number }>;
+    if ([400, 404, 409].includes(response.status)) return { ok: false };
     await this.parseResponse(response, "POST", path);
-    return false;
+    return { ok: false };
+  }
+
+  async updateTaskStatus(taskId: number, input: TaskStatusInput): Promise<Task> {
+    const payload = await this.json("PATCH", `/api/tasks/${taskId}/status`, input) as { task?: Task };
+    if (!payload.task) throw new Error(`task status update failed: missing task ${taskId}`);
+    return payload.task;
   }
 
   async markRead(messageId: number, agentId: string): Promise<void> {
@@ -114,6 +163,90 @@ export class RelayHttpClient {
     return this.json("GET", "/api/messages/cursor") as Promise<{ latestId: number }>;
   }
 
+  async uploadArtifact(
+    file: Blob | Buffer | ReadableStream,
+    opts: {
+      filename?: string;
+      mediaType?: string;
+      digest?: string;
+      kind?: ArtifactKind;
+      sensitivity?: ArtifactSensitivity;
+      metadata?: Record<string, unknown>;
+      expiresAt?: number;
+    } = {},
+  ): Promise<Artifact> {
+    if (opts.metadata && !(file instanceof ReadableStream)) {
+      const form = new FormData();
+      if (file instanceof Blob) {
+        form.append("file", file, opts.filename);
+      } else {
+        const arrayBuffer = file.buffer.slice(file.byteOffset, file.byteOffset + file.byteLength) as ArrayBuffer;
+        form.append("file", new Blob([arrayBuffer], { type: opts.mediaType }), opts.filename);
+      }
+      if (opts.filename) form.append("filename", opts.filename);
+      if (opts.digest) form.append("digest", opts.digest);
+      if (opts.kind) form.append("kind", opts.kind);
+      if (opts.sensitivity) form.append("sensitivity", opts.sensitivity);
+      if (opts.expiresAt) form.append("expiresAt", String(opts.expiresAt));
+      form.append("metadata", JSON.stringify(opts.metadata));
+      const response = await this.requestRaw("POST", "/api/artifacts", form);
+      return this.parseResponse(response, "POST", "/api/artifacts") as Promise<Artifact>;
+    }
+
+    const headers: Record<string, string> = {};
+    if (opts.mediaType) headers["Content-Type"] = opts.mediaType;
+    if (opts.filename) headers["X-Artifact-Filename"] = opts.filename;
+    if (opts.digest) headers["X-Artifact-Digest"] = opts.digest;
+    if (opts.kind) headers["X-Artifact-Kind"] = opts.kind;
+    if (opts.sensitivity) headers["X-Artifact-Sensitivity"] = opts.sensitivity;
+    if (opts.expiresAt) headers["X-Artifact-Expires-At"] = String(opts.expiresAt);
+
+    let body: BodyInit;
+    if (file instanceof Blob) body = file;
+    else if (file instanceof ReadableStream) body = file;
+    else body = file as unknown as BodyInit;
+
+    const response = await this.requestRaw("POST", "/api/artifacts", body, headers);
+    return this.parseResponse(response, "POST", "/api/artifacts") as Promise<Artifact>;
+  }
+
+  async downloadArtifact(id: string): Promise<{ stream: ReadableStream<Uint8Array>; meta: Artifact }> {
+    const meta = await this.getArtifact(id);
+    const path = `/api/artifacts/${encodeURIComponent(id)}/content`;
+    const response = await this.requestRaw("GET", path);
+    await this.parseResponseForOk(response, "GET", path);
+    if (!response.body) throw new RelayHttpError("GET", path, response.status, response.statusText, "missing response body");
+    return { stream: response.body as ReadableStream<Uint8Array>, meta };
+  }
+
+  async getArtifact(id: string): Promise<Artifact> {
+    return this.json("GET", `/api/artifacts/${encodeURIComponent(id)}`) as Promise<Artifact>;
+  }
+
+  async artifactExists(id: string): Promise<boolean> {
+    const response = await this.requestRaw("HEAD", `/api/artifacts/${encodeURIComponent(id)}/content`);
+    if (response.status === 404) return false;
+    await this.parseResponseForOk(response, "HEAD", `/api/artifacts/${id}/content`);
+    return true;
+  }
+
+  async deleteArtifact(id: string): Promise<void> {
+    await this.json("DELETE", `/api/artifacts/${encodeURIComponent(id)}`);
+  }
+
+  listArtifacts(query: { messageId?: number; taskId?: number; createdBy?: string; limit?: number } = {}): Promise<Artifact[]> {
+    const url = this.url("/api/artifacts");
+    if (query.messageId !== undefined) url.searchParams.set("messageId", String(query.messageId));
+    if (query.taskId !== undefined) url.searchParams.set("taskId", String(query.taskId));
+    if (query.createdBy) url.searchParams.set("createdBy", query.createdBy);
+    if (query.limit !== undefined) url.searchParams.set("limit", String(query.limit));
+    return this.jsonUrl("GET", url) as Promise<Artifact[]>;
+  }
+
+  renewRuntimeToken(): Promise<{ token: string; record: { jti: string; profileId?: string; expiresAt?: number }; previous: { jti: string; expiresAt?: number } }> {
+    return this.json("POST", "/api/runtime-tokens/renew") as Promise<{ token: string; record: { jti: string; profileId?: string; expiresAt?: number }; previous: { jti: string; expiresAt?: number } }>;
+  }
+
   private json(method: string, path: string, body?: unknown): Promise<unknown> {
     return this.jsonUrl(method, this.url(path), body);
   }
@@ -138,6 +271,28 @@ export class RelayHttpClient {
     }
   }
 
+  private async requestRaw(method: string, pathOrUrl: string | URL, body?: BodyInit, headers: Record<string, string> = {}): Promise<Response> {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeout);
+    try {
+      return await fetch(pathOrUrl instanceof URL ? pathOrUrl : this.url(pathOrUrl), {
+        method,
+        headers: this.headers(headers),
+        body,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  private async parseResponseForOk(response: Response, method: string, path: string): Promise<void> {
+    if (!response.ok) {
+      const text = await response.text();
+      throw new RelayHttpError(method, path, response.status, response.statusText, text);
+    }
+  }
+
   private async parseResponse(response: Response, method: string, path: string): Promise<unknown> {
     if (!response.ok) {
       const text = await response.text();

package/src/index.ts

@@ -1,7 +1,10 @@
 export * from "./types.js";
+export * from "./contracts.js";
+export * from "./provider-catalog.js";
 export * from "./protocol.js";
 export * from "./reconnect.js";
 export * from "./http-client.js";
 export * from "./bus-client.js";
 export * from "./provider-base.js";
 export * from "./claim-tracker.js";
+export * from "./context-probe.js";

package/src/protocol.ts

@@ -79,6 +79,9 @@ export interface RegisteredFrame extends BusFrame {
     epoch: number;
     cursor: number;
     sessionId: string;
+    features?: {
+      heartbeatAck?: boolean;
+    };
   };
 }
 
@@ -141,6 +144,7 @@ export type ClientBusFrame =
   | ResumeFrame;
 
 export type ServerBusFrame =
+  | AckFrame
   | RegisteredFrame
   | EventFrame
   | CommandResultFrame