@beanx/cathygo-protocol 0.1.1 → 0.1.3

package/dist/index.d.ts

@@ -26,6 +26,11 @@ type CathyGOConnectResult = {
         max_payload_bytes: number;
         max_upload_bytes: number;
         heartbeat_interval_ms: number;
+        attachment_relay_max_files_per_send?: number;
+        attachment_relay_max_concurrent_transfers?: number;
+        attachment_relay_chunk_bytes?: number;
+        attachment_relay_max_file_bytes?: number;
+        attachment_relay_progress_min_interval_ms?: number;
     };
 };
 type CathyGORequest = {
@@ -59,8 +64,12 @@ type LearningTurnEventPayload = {
     input_mode?: "text" | "image" | "text_image" | string;
     required_model_capabilities?: string[];
     message_id?: string;
+    role?: "user" | "assistant" | "system";
     delta?: string;
     message?: string;
+    parts?: ConversationMessagePart[];
+    metadata?: Record<string, unknown>;
+    created_at?: string;
     blocks?: unknown[];
     status?: "accepted" | "idle" | "running" | "stopping" | "completed" | "failed" | "cancelled" | string;
     reason?: string;
@@ -78,7 +87,7 @@ type LearningTurnEventPayload = {
 };
 type LearningTurnEvent = {
     type: "event";
-    event: "session.created" | "session.deleted" | "session.input.accepted" | "session.stop.requested" | "turn.started" | "assistant.delta" | "assistant.completed" | "turn.completed" | "turn.failed" | "turn.cancelled" | "agent.activity.started" | "agent.activity.updated" | "agent.activity.completed" | "agent.progress.delta" | `debug.${string}` | `experimental.${string}`;
+    event: "session.created" | "session.deleted" | "session.input.accepted" | "session.stop.requested" | "user.message.created" | "turn.started" | "assistant.delta" | "assistant.completed" | "turn.completed" | "turn.failed" | "turn.cancelled" | "agent.activity.started" | "agent.activity.updated" | "agent.activity.completed" | "agent.progress.delta" | `debug.${string}` | `experimental.${string}`;
     seq: number;
     payload: LearningTurnEventPayload;
 };
@@ -93,7 +102,21 @@ type AgentPresenceEvent = {
         [key: string]: unknown;
     };
 };
-type CathyGOIncomingFrame = CathyGOResponse | LearningTurnEvent | AgentPresenceEvent;
+type AttachmentRelayProgress = {
+    transfer_id: string;
+    received_bytes: number;
+    total_bytes: number;
+    percent: number;
+    batch_id?: string;
+    index?: number;
+};
+type AttachmentRelayProgressEvent = {
+    type: "event";
+    event: "attachment.relay.progress";
+    seq?: number;
+    payload: AttachmentRelayProgress;
+};
+type CathyGOIncomingFrame = CathyGOResponse | LearningTurnEvent | AgentPresenceEvent | AttachmentRelayProgressEvent;
 type CathyGOFrame = CathyGORequest | CathyGOIncomingFrame;
 type TextTurnInput = {
     text: string;
@@ -175,6 +198,7 @@ interface ConversationMessage {
     parts?: ConversationMessagePart[];
     turn_id?: string | null;
     created_at: string;
+    metadata?: Record<string, unknown>;
 }
 interface ConversationDetail {
     session: ConversationSummary & {
@@ -211,6 +235,13 @@ interface GatewayAttachment {
     width?: number | null;
     height?: number | null;
     created_at?: string | null;
+    thumbnail?: GatewayAttachmentThumbnail | null;
+}
+interface GatewayAttachmentThumbnail {
+    mime_type: string;
+    data_base64: string;
+    width?: number | null;
+    height?: number | null;
 }
 interface ConversationMessagePart {
     id?: string;
@@ -336,6 +367,7 @@ type AttachmentCommitParams = {
     blob?: AttachmentCommitBlob;
     metadata?: Record<string, unknown>;
 };
+type AttachmentRelayProgressHandler = (progress: AttachmentRelayProgress) => void;
 type LearningTurnEventHandler = (event: LearningTurnEvent) => void;
 type CathyGOProtocolClientCallbacks = {
     onOpen?: () => void;
@@ -343,6 +375,7 @@ type CathyGOProtocolClientCallbacks = {
     onError?: () => void;
     onFrame?: (frame: CathyGOIncomingFrame) => void;
     onTurnEvent?: LearningTurnEventHandler;
+    onAttachmentRelayProgress?: AttachmentRelayProgressHandler;
 };
 
 type CathyGOTransportFrameHandler = (frame: CathyGOIncomingFrame) => void;
@@ -370,6 +403,7 @@ declare class CathyGOProtocolClient {
     private requestSeq;
     private pending;
     private turnHandlers;
+    private attachmentRelayProgressHandlers;
     private lastConnect?;
     private lastEventSeq;
     private connectOptions;
@@ -378,6 +412,7 @@ declare class CathyGOProtocolClient {
     updateConnectOptions(patch: Partial<CathyGOConnectOptions>): void;
     updateCallbacks(callbacks: CathyGOProtocolClientCallbacks): void;
     onTurnEvent(handler: LearningTurnEventHandler): () => void;
+    onAttachmentRelayProgress(handler: AttachmentRelayProgressHandler): () => void;
     connect(): Promise<CathyGOConnectResult>;
     reconnect(options?: Partial<CathyGOConnectOptions>): Promise<CathyGOConnectResult>;
     disconnect(): void;
@@ -386,6 +421,11 @@ declare class CathyGOProtocolClient {
         max_payload_bytes: number;
         max_upload_bytes: number;
         heartbeat_interval_ms: number;
+        attachment_relay_max_files_per_send?: number;
+        attachment_relay_max_concurrent_transfers?: number;
+        attachment_relay_chunk_bytes?: number;
+        attachment_relay_max_file_bytes?: number;
+        attachment_relay_progress_min_interval_ms?: number;
     } | undefined;
     createSession(metadata?: Record<string, unknown>): Promise<string>;
     listSessions(limit?: number): Promise<ConversationSummary[]>;
@@ -411,6 +451,17 @@ declare function connectPayload(options: CathyGOConnectOptions): Record<string,
 declare function parseConnectPayload(payload: Record<string, unknown>): CathyGOConnectResult;
 declare function settingsFromPayload(payload: Record<string, unknown>): GatewayVisibleSettings;
 declare function isLearningTurnEvent(frame: CathyGOIncomingFrame): frame is LearningTurnEvent;
+declare function isAttachmentRelayProgressEvent(frame: CathyGOIncomingFrame): frame is AttachmentRelayProgressEvent;
+
+type UploadAttachmentViaRelayOptions = {
+    transferId?: string;
+    sessionId?: string;
+    metadata?: Record<string, unknown>;
+    chunkBytes?: number;
+    onProgress?: (progress: AttachmentRelayProgress) => void;
+    signal?: AbortSignal;
+};
+declare function uploadAttachmentViaRelay(client: CathyGOProtocolClient, file: File, options?: UploadAttachmentViaRelayOptions): Promise<GatewayAttachment>;
 
 type LearningCapability = NonNullable<SessionInputOptions["capability"]>;
 declare function textTurnInput(text: string): TurnInput;
@@ -418,4 +469,4 @@ declare function photoQuestionTurnInput(text: string, attachments: GatewayAttach
 declare function capabilityForTurn(attachments: GatewayAttachment[]): LearningCapability;
 declare function learningTurnInput(text: string, attachments: GatewayAttachment[]): TurnInput;
 
-export { type AgentActivity, type AgentPresenceEvent, type AttachmentCommitBlob, type AttachmentCommitParams, type AttachmentInput, type BeanXAccountRuntimeConfig, CathyGOClientError, type CathyGOClientRole, type CathyGOConnectOptions, type CathyGOConnectResult, type CathyGODeviceContext, type CathyGOFrame, type CathyGOIncomingFrame, CathyGOProtocolClient, type CathyGOProtocolClientCallbacks, type CathyGOProtocolClientOptions, type CathyGORequest, type CathyGOResponse, type CathyGOTransport, type CathyGOTransportEventHandler, type CathyGOTransportFrameHandler, type ConversationDetail, type ConversationMessage, type ConversationMessagePart, type ConversationSummary, type GatewayAgentProfile, type GatewayAttachment, type GatewayModelConfig, type GatewayModelConfigUpdate, type GatewayModelOption, type GatewayModelStatus, type GatewayVisibleSettings, type LearningCapability, type LearningTurnEvent, type LearningTurnEventHandler, type LearningTurnEventPayload, type ListResponse, type MessagePartInput, type MultimodalTurnInput, type SameSessionPolicy, type SessionInputOptions, type SessionInputResult, type SessionRuntimeSnapshot, type SessionStopResult, type SettingsItem, type SettingsItemKind, type SettingsSection, type TextTurnInput, type TurnInput, type UploadScope, capabilityForTurn, connectPayload, isLearningTurnEvent, learningTurnInput, parseConnectPayload, photoQuestionTurnInput, settingsFromPayload, textTurnInput };
+export { type AgentActivity, type AgentPresenceEvent, type AttachmentCommitBlob, type AttachmentCommitParams, type AttachmentInput, type AttachmentRelayProgress, type AttachmentRelayProgressEvent, type AttachmentRelayProgressHandler, type BeanXAccountRuntimeConfig, CathyGOClientError, type CathyGOClientRole, type CathyGOConnectOptions, type CathyGOConnectResult, type CathyGODeviceContext, type CathyGOFrame, type CathyGOIncomingFrame, CathyGOProtocolClient, type CathyGOProtocolClientCallbacks, type CathyGOProtocolClientOptions, type CathyGORequest, type CathyGOResponse, type CathyGOTransport, type CathyGOTransportEventHandler, type CathyGOTransportFrameHandler, type ConversationDetail, type ConversationMessage, type ConversationMessagePart, type ConversationSummary, type GatewayAgentProfile, type GatewayAttachment, type GatewayModelConfig, type GatewayModelConfigUpdate, type GatewayModelOption, type GatewayModelStatus, type GatewayVisibleSettings, type LearningCapability, type LearningTurnEvent, type LearningTurnEventHandler, type LearningTurnEventPayload, type ListResponse, type MessagePartInput, type MultimodalTurnInput, type SameSessionPolicy, type SessionInputOptions, type SessionInputResult, type SessionRuntimeSnapshot, type SessionStopResult, type SettingsItem, type SettingsItemKind, type SettingsSection, type TextTurnInput, type TurnInput, type UploadAttachmentViaRelayOptions, type UploadScope, capabilityForTurn, connectPayload, isAttachmentRelayProgressEvent, isLearningTurnEvent, learningTurnInput, parseConnectPayload, photoQuestionTurnInput, settingsFromPayload, textTurnInput, uploadAttachmentViaRelay };

package/dist/index.js

@@ -26,6 +26,7 @@ var CathyGOProtocolClient = class {
   requestSeq = 1;
   pending = /* @__PURE__ */ new Map();
   turnHandlers = /* @__PURE__ */ new Set();
+  attachmentRelayProgressHandlers = /* @__PURE__ */ new Set();
   lastConnect;
   lastEventSeq = 0;
   connectOptions;
@@ -40,6 +41,10 @@ var CathyGOProtocolClient = class {
     this.turnHandlers.add(handler);
     return () => this.turnHandlers.delete(handler);
   }
+  onAttachmentRelayProgress(handler) {
+    this.attachmentRelayProgressHandlers.add(handler);
+    return () => this.attachmentRelayProgressHandlers.delete(handler);
+  }
   async connect() {
     if (this.isConnected() && this.lastConnect) {
       return this.lastConnect;
@@ -205,6 +210,12 @@ var CathyGOProtocolClient = class {
         handler(frame);
       }
     }
+    if (isAttachmentRelayProgressEvent(frame)) {
+      this.callbacks.onAttachmentRelayProgress?.(frame.payload);
+      for (const handler of this.attachmentRelayProgressHandlers) {
+        handler(frame.payload);
+      }
+    }
     this.callbacks.onFrame?.(frame);
   }
 };
@@ -254,6 +265,9 @@ function settingsFromPayload(payload) {
 function isLearningTurnEvent(frame) {
   return frame.type === "event" && (frame.event.startsWith("session.") || frame.event.startsWith("turn.") || frame.event.startsWith("agent.activity.") || frame.event.startsWith("agent.progress.") || frame.event.startsWith("assistant.") || frame.event.startsWith("debug.") || frame.event.startsWith("experimental."));
 }
+function isAttachmentRelayProgressEvent(frame) {
+  return frame.type === "event" && frame.event === "attachment.relay.progress";
+}
 function turnStartResultFromPayload(payload, fallbackSessionId) {
   return {
     session_id: String(payload.session_id ?? fallbackSessionId),
@@ -280,6 +294,126 @@ function compactParams(params) {
   return Object.fromEntries(Object.entries(params).filter(([, value]) => value !== void 0));
 }
 
+// src/relay-attachment-upload.ts
+async function uploadAttachmentViaRelay(client, file, options = {}) {
+  const transferId = options.transferId ?? createTransferId();
+  const mimeType = file.type || "application/octet-stream";
+  const buffer = await file.arrayBuffer();
+  const bytes = new Uint8Array(buffer);
+  const sha256 = await sha256Hex(buffer);
+  const limits = client.getLimits();
+  const chunkBytes = options.chunkBytes ?? Number(limits?.attachment_relay_chunk_bytes ?? DEFAULT_RELAY_CHUNK_BYTES);
+  if (options.signal?.aborted) {
+    throw new DOMException("Attachment relay upload aborted.", "AbortError");
+  }
+  const openPayload = await client.request("attachment.relay.open", {
+    transfer_id: transferId,
+    session_id: options.sessionId,
+    mime_type: mimeType,
+    size_bytes: bytes.byteLength,
+    sha256,
+    original_name: file.name || void 0,
+    metadata: options.metadata
+  });
+  const negotiatedChunkBytes = Number(openPayload.chunk_bytes ?? chunkBytes) || chunkBytes;
+  try {
+    let seq = 0;
+    for (let offset = 0; offset < bytes.byteLength; offset += negotiatedChunkBytes) {
+      if (options.signal?.aborted) {
+        await client.request("attachment.relay.abort", { transfer_id: transferId });
+        throw new DOMException("Attachment relay upload aborted.", "AbortError");
+      }
+      const chunk = bytes.subarray(offset, offset + negotiatedChunkBytes);
+      const pushPayload = await client.request("attachment.relay.push", {
+        transfer_id: transferId,
+        seq,
+        data_base64: bytesToBase64(chunk)
+      });
+      seq += 1;
+      options.onProgress?.({
+        transfer_id: transferId,
+        received_bytes: Number(pushPayload.received_bytes ?? offset + chunk.byteLength),
+        total_bytes: Number(pushPayload.total_bytes ?? bytes.byteLength),
+        percent: percent(
+          Number(pushPayload.received_bytes ?? offset + chunk.byteLength),
+          Number(pushPayload.total_bytes ?? bytes.byteLength)
+        ),
+        batch_id: stringOrUndefined(options.metadata?.batch_id),
+        index: numberOrUndefined(options.metadata?.index)
+      });
+    }
+    const closePayload = await client.request("attachment.relay.close", {
+      transfer_id: transferId
+    });
+    return normalizeGatewayAttachment(closePayload.attachment);
+  } catch (error) {
+    if (!(error instanceof DOMException && error.name === "AbortError")) {
+      try {
+        await client.request("attachment.relay.abort", { transfer_id: transferId });
+      } catch {
+      }
+    }
+    throw error;
+  }
+}
+var DEFAULT_RELAY_CHUNK_BYTES = 65536;
+function createTransferId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return `xfer_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`;
+  }
+  return `xfer_${Date.now().toString(36)}`;
+}
+function percent(receivedBytes, totalBytes) {
+  if (totalBytes <= 0) return 0;
+  return Math.min(100, Math.max(0, Math.round(receivedBytes * 100 / totalBytes)));
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let index = 0; index < bytes.length; index += 1) {
+    binary += String.fromCharCode(bytes[index] ?? 0);
+  }
+  return btoa(binary);
+}
+async function sha256Hex(buffer) {
+  const digest = await crypto.subtle.digest("SHA-256", buffer);
+  return Array.from(new Uint8Array(digest)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function normalizeGatewayAttachment(value) {
+  const attachment = value ?? {};
+  const id = String(attachment.id ?? attachment.attachment_id ?? "");
+  if (!id) {
+    throw new Error("attachment.relay.close did not return an attachment id.");
+  }
+  return {
+    id,
+    kind: "image",
+    uri: String(attachment.uri ?? ""),
+    original_name: stringOrNull(attachment.original_name),
+    mime_type: stringOrNull(attachment.mime_type),
+    size_bytes: numberOrNull(attachment.size_bytes),
+    sha256: stringOrNull(attachment.sha256),
+    width: numberOrNull(attachment.width),
+    height: numberOrNull(attachment.height),
+    created_at: stringOrNull(attachment.created_at),
+    thumbnail: attachment.thumbnail
+  };
+}
+function stringOrUndefined(value) {
+  if (typeof value !== "string") return void 0;
+  const text = value.trim();
+  return text || void 0;
+}
+function stringOrNull(value) {
+  return stringOrUndefined(value) ?? null;
+}
+function numberOrUndefined(value) {
+  if (typeof value !== "number" || Number.isNaN(value)) return void 0;
+  return value;
+}
+function numberOrNull(value) {
+  return numberOrUndefined(value) ?? null;
+}
+
 // src/turn-input.ts
 function textTurnInput(text) {
   return { text };
@@ -315,10 +449,12 @@ export {
   CathyGOProtocolClient,
   capabilityForTurn,
   connectPayload,
+  isAttachmentRelayProgressEvent,
   isLearningTurnEvent,
   learningTurnInput,
   parseConnectPayload,
   photoQuestionTurnInput,
   settingsFromPayload,
-  textTurnInput
+  textTurnInput,
+  uploadAttachmentViaRelay
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beanx/cathygo-protocol",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "files": [
     "dist"