@beanx/cathygo-protocol 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,386 @@
+type CathyGOClientRole = "parent" | "child" | "developer";
+type CathyGODeviceContext = {
+    deviceId: string;
+    displayName?: string;
+    platform: string;
+    appVersion?: string;
+};
+type CathyGOConnectOptions = {
+    authToken: string;
+    device?: CathyGODeviceContext;
+    clientId?: string;
+    clientVersion?: string;
+    role?: CathyGOClientRole;
+    scopes?: string[];
+};
+type CathyGOConnectResult = {
+    protocol: {
+        name: "cathygo.vnext";
+        version: number;
+    };
+    features: {
+        methods: string[];
+        events: string[];
+    };
+    limits: {
+        max_payload_bytes: number;
+        max_upload_bytes: number;
+        heartbeat_interval_ms: number;
+    };
+};
+type CathyGORequest = {
+    type: "req";
+    id: string;
+    method: string;
+    params?: Record<string, unknown>;
+};
+type CathyGOResponse = {
+    type: "res";
+    id: string;
+    status: "ok" | "error";
+    payload?: Record<string, unknown>;
+    error?: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+    };
+};
+type LearningTurnEventPayload = {
+    session_id?: string;
+    turn_id?: string;
+    capability?: "chat" | "photo_question";
+    input_summary?: string;
+    input_mode?: "text" | "image" | "text_image" | string;
+    required_model_capabilities?: string[];
+    message_id?: string;
+    delta?: string;
+    message?: string;
+    blocks?: unknown[];
+    status?: "running" | "completed" | "failed" | "cancelled";
+    reason?: string;
+    phase?: "queued" | "model" | "reasoning" | "tool" | "generating" | string;
+    source?: "provider_reasoning_summary" | "public_progress" | "system_progress" | "hidden_reasoning" | string;
+    text_delta?: string;
+    text?: string;
+    durable?: boolean;
+    error?: {
+        code?: string;
+        message?: string;
+        retryable?: boolean;
+    };
+    [key: string]: unknown;
+};
+type LearningTurnEvent = {
+    type: "event";
+    event: "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;
+};
+type AgentPresenceEvent = {
+    type: "event";
+    event: "agent.online" | "agent.offline";
+    seq: number;
+    cursor?: string;
+    payload: {
+        agent_id: string;
+        status: "online" | "offline";
+        [key: string]: unknown;
+    };
+};
+type CathyGOIncomingFrame = CathyGOResponse | LearningTurnEvent | AgentPresenceEvent;
+type CathyGOFrame = CathyGORequest | CathyGOIncomingFrame;
+type TextTurnInput = {
+    text: string;
+};
+type MessagePartInput = {
+    type: "text";
+    text: string;
+    metadata?: Record<string, unknown>;
+} | {
+    type: "image";
+    attachment_id: string;
+    metadata?: Record<string, unknown>;
+};
+type AttachmentInput = {
+    attachment_id: string;
+    kind: "image";
+    mime_type?: string | null;
+    uri?: string | null;
+    metadata?: Record<string, unknown>;
+};
+type MultimodalTurnInput = {
+    parts: MessagePartInput[];
+    attachments?: AttachmentInput[];
+};
+type TurnInput = TextTurnInput | MultimodalTurnInput;
+type TurnStartOptions = {
+    capability?: "chat" | "photo_question";
+    metadata?: Record<string, unknown>;
+};
+type TurnStartResult = {
+    session_id: string;
+    turn_id: string;
+    status: string;
+};
+type UploadScope = {
+    sessionId?: string;
+    ownerId?: string;
+};
+interface ConversationSummary {
+    session_id: string;
+    title: string;
+    preview: string;
+    status: "active" | "archived";
+    message_count: number;
+    updated_at: string;
+    created_at: string;
+    metadata?: Record<string, unknown>;
+}
+interface ConversationMessage {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    parts?: ConversationMessagePart[];
+    turn_id?: string | null;
+    created_at: string;
+}
+interface ConversationDetail {
+    session: ConversationSummary;
+    messages: ConversationMessage[];
+    activities?: AgentActivity[];
+}
+interface AgentActivity {
+    activity_id: string;
+    session_id: string;
+    turn_id: string;
+    kind: "model" | "tool" | "skill" | "vision" | "memory" | "system";
+    status: "running" | "completed" | "failed" | "cancelled";
+    title: string;
+    summary?: string;
+    detail?: string;
+    started_at?: string;
+    completed_at?: string;
+    error?: {
+        code?: string;
+        message: string;
+    };
+}
+interface GatewayAttachment {
+    id: string;
+    kind: "image";
+    uri: string;
+    original_name?: string | null;
+    mime_type?: string | null;
+    size_bytes?: number | null;
+    sha256?: string | null;
+    width?: number | null;
+    height?: number | null;
+    created_at?: string | null;
+}
+interface ConversationMessagePart {
+    id?: string;
+    type: "text" | "image";
+    text?: string | null;
+    attachment_id?: string | null;
+    attachment?: GatewayAttachment;
+}
+interface GatewayAgentProfile {
+    agent_instance_id?: string;
+    display_name?: string;
+    grade?: number | null;
+    default_subject?: string | null;
+    default_goal?: string | null;
+    locale?: string;
+    timezone?: string;
+}
+interface GatewayVisibleSettings {
+    app_name?: string;
+    shell?: string;
+    gateway_url?: string;
+    token?: string;
+    editable?: boolean;
+    protocol_version?: number;
+    gateway_version?: string;
+    mode?: string;
+    device_context?: Record<string, unknown>;
+    agent_profile?: GatewayAgentProfile | null;
+    model?: GatewayModelStatus;
+    model_config?: GatewayModelConfig;
+    model_options?: GatewayModelOption[];
+    beanx_account?: BeanXAccountRuntimeConfig;
+    settings_schema_version?: number;
+    sections?: SettingsSection[];
+}
+interface BeanXAccountRuntimeConfig {
+    api_url?: string | null;
+    supabase_url?: string | null;
+    supabase_anon_key?: string | null;
+    configured?: boolean;
+}
+interface GatewayModelStatus {
+    provider: string;
+    requested_provider?: string;
+    display_name?: string;
+    model?: string | null;
+    base_url?: string | null;
+    configured: boolean;
+    capabilities?: string[];
+    missing_config_keys: string[];
+    error?: string | null;
+}
+interface GatewayModelConfig {
+    provider: string;
+    model?: string | null;
+    base_url?: string | null;
+    api_key_status: "set" | "missing" | "not_required" | string;
+    routing_mode?: string;
+    model_selection_label?: string;
+    source?: string | null;
+    reasoning_effort?: string;
+}
+interface GatewayModelConfigUpdate {
+    provider: string;
+    model?: string;
+    base_url?: string;
+    api_key?: string;
+    clear_api_key?: boolean;
+    reasoning_effort?: string;
+}
+interface GatewayModelOption {
+    id: string;
+    label: string;
+    description?: string;
+    requires_api_key: boolean;
+    api_key_status?: "set" | "missing" | "not_required" | string;
+    selected?: boolean;
+    capabilities?: string[];
+    model?: string;
+    base_url?: string;
+    reasoning_effort?: string;
+    supports_reasoning?: boolean;
+}
+type SettingsItemKind = "readonly_text" | "text" | "password" | "select" | "toggle" | "number" | "status" | "secret_status" | "key_value" | "list" | "json";
+interface SettingsSection {
+    id: string;
+    title: string;
+    status: string;
+    description?: string | null;
+    items: SettingsItem[];
+}
+interface SettingsItem {
+    id: string;
+    label: string;
+    kind: SettingsItemKind;
+    value?: unknown;
+    display_value?: string | null;
+    source?: string | null;
+    editable?: boolean;
+    sensitive?: boolean;
+    requires_restart?: boolean;
+    visibility?: "normal" | "advanced" | "developer" | string;
+    read_only_reason?: string | null;
+}
+interface ListResponse<T> {
+    has_more: boolean;
+    [key: string]: T[] | boolean;
+}
+type AttachmentCommitBlob = {
+    blob_id?: string;
+    data_base64?: string;
+    mime_type?: string;
+    size_bytes?: number;
+    sha256?: string;
+};
+type AttachmentCommitParams = {
+    session_id?: string;
+    attachment_id?: string;
+    blob_id?: string;
+    kind?: "image";
+    mime_type?: string;
+    original_name?: string;
+    blob?: AttachmentCommitBlob;
+    metadata?: Record<string, unknown>;
+};
+type LearningTurnEventHandler = (event: LearningTurnEvent) => void;
+type CathyGOProtocolClientCallbacks = {
+    onOpen?: () => void;
+    onClose?: () => void;
+    onError?: () => void;
+    onFrame?: (frame: CathyGOIncomingFrame) => void;
+    onTurnEvent?: LearningTurnEventHandler;
+};
+
+type CathyGOTransportFrameHandler = (frame: CathyGOIncomingFrame) => void;
+type CathyGOTransportEventHandler = () => void;
+type CathyGOTransport = {
+    connect(): Promise<void>;
+    sendFrame(frame: CathyGORequest): void;
+    onFrame(handler: CathyGOTransportFrameHandler): () => void;
+    onClose?(handler: CathyGOTransportEventHandler): () => void;
+    onError?(handler: CathyGOTransportEventHandler): () => void;
+    close(): void;
+    isOpen(): boolean;
+};
+
+declare class CathyGOClientError extends Error {
+    readonly code?: string | undefined;
+    constructor(message: string, code?: string | undefined);
+}
+type CathyGOProtocolClientOptions = {
+    connect: CathyGOConnectOptions;
+    callbacks?: CathyGOProtocolClientCallbacks;
+};
+declare class CathyGOProtocolClient {
+    private readonly transport;
+    private requestSeq;
+    private pending;
+    private turnHandlers;
+    private lastConnect?;
+    private lastEventSeq;
+    private connectOptions;
+    private callbacks;
+    constructor(transport: CathyGOTransport, options: CathyGOProtocolClientOptions);
+    updateConnectOptions(patch: Partial<CathyGOConnectOptions>): void;
+    updateCallbacks(callbacks: CathyGOProtocolClientCallbacks): void;
+    onTurnEvent(handler: LearningTurnEventHandler): () => void;
+    connect(): Promise<CathyGOConnectResult>;
+    reconnect(options?: Partial<CathyGOConnectOptions>): Promise<CathyGOConnectResult>;
+    disconnect(): void;
+    isConnected(): boolean;
+    getLimits(): {
+        max_payload_bytes: number;
+        max_upload_bytes: number;
+        heartbeat_interval_ms: number;
+    } | undefined;
+    createSession(metadata?: Record<string, unknown>): Promise<string>;
+    listSessions(limit?: number): Promise<ConversationSummary[]>;
+    getSession(sessionId: string): Promise<ConversationDetail>;
+    deleteSession(sessionId: string): Promise<void>;
+    startTurn(sessionId: string, input: TurnInput, options?: TurnStartOptions): Promise<TurnStartResult>;
+    subscribeTurn(turnId: string, afterSeq?: number): Promise<void>;
+    subscribeSession(sessionId: string, afterSeq?: number): Promise<void>;
+    cancelTurn(turnId: string): Promise<void>;
+    regenerateLastTurn(sessionId: string): Promise<TurnStartResult>;
+    commitAttachment(params: AttachmentCommitParams): Promise<GatewayAttachment>;
+    getSettings(): Promise<GatewayVisibleSettings>;
+    updateSettings(settings: Record<string, unknown>): Promise<GatewayVisibleSettings>;
+    updateModelConfig(modelConfig: GatewayModelConfigUpdate): Promise<GatewayVisibleSettings>;
+    request(method: string, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    private sendRequest;
+    private send;
+    private rejectPending;
+    private unwrap;
+    private handleFrame;
+}
+declare function connectPayload(options: CathyGOConnectOptions): Record<string, unknown>;
+declare function parseConnectPayload(payload: Record<string, unknown>): CathyGOConnectResult;
+declare function settingsFromPayload(payload: Record<string, unknown>): GatewayVisibleSettings;
+declare function isLearningTurnEvent(frame: CathyGOIncomingFrame): frame is LearningTurnEvent;
+
+type LearningCapability = NonNullable<TurnStartOptions["capability"]>;
+declare function textTurnInput(text: string): TurnInput;
+declare function photoQuestionTurnInput(text: string, attachments: GatewayAttachment[]): TurnInput;
+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 SettingsItem, type SettingsItemKind, type SettingsSection, type TextTurnInput, type TurnInput, type TurnStartOptions, type TurnStartResult, type UploadScope, capabilityForTurn, connectPayload, isLearningTurnEvent, learningTurnInput, parseConnectPayload, photoQuestionTurnInput, settingsFromPayload, textTurnInput };

package/dist/index.js

@@ -0,0 +1,289 @@
+// src/client.ts
+var CathyGOClientError = class extends Error {
+  constructor(message, code) {
+    super(message);
+    this.code = code;
+    this.name = "CathyGOClientError";
+  }
+  code;
+};
+var CathyGOProtocolClient = class {
+  constructor(transport, options) {
+    this.transport = transport;
+    this.connectOptions = options.connect;
+    this.callbacks = options.callbacks ?? {};
+    this.transport.onFrame((frame) => this.handleFrame(frame));
+    this.transport.onClose?.(() => {
+      this.rejectPending("CathyGO socket closed");
+      this.callbacks.onClose?.();
+    });
+    this.transport.onError?.(() => {
+      this.rejectPending("CathyGO socket error");
+      this.callbacks.onError?.();
+    });
+  }
+  transport;
+  requestSeq = 1;
+  pending = /* @__PURE__ */ new Map();
+  turnHandlers = /* @__PURE__ */ new Set();
+  lastConnect;
+  lastEventSeq = 0;
+  connectOptions;
+  callbacks;
+  updateConnectOptions(patch) {
+    this.connectOptions = { ...this.connectOptions, ...patch };
+  }
+  updateCallbacks(callbacks) {
+    this.callbacks = callbacks;
+  }
+  onTurnEvent(handler) {
+    this.turnHandlers.add(handler);
+    return () => this.turnHandlers.delete(handler);
+  }
+  async connect() {
+    if (this.isConnected() && this.lastConnect) {
+      return this.lastConnect;
+    }
+    this.lastConnect = void 0;
+    this.transport.close();
+    await this.transport.connect();
+    this.callbacks.onOpen?.();
+    const response = await this.sendRequest(
+      "client.connect",
+      connectPayload(this.connectOptions),
+      "cathygo_connect"
+    );
+    this.lastConnect = parseConnectPayload(this.unwrap(response, "client.connect"));
+    return this.lastConnect;
+  }
+  async reconnect(options) {
+    if (options) this.updateConnectOptions(options);
+    this.disconnect();
+    return this.connect();
+  }
+  disconnect() {
+    this.transport.close();
+    this.lastConnect = void 0;
+    this.lastEventSeq = 0;
+    this.rejectPending("CathyGO socket closed");
+  }
+  isConnected() {
+    return this.transport.isOpen();
+  }
+  getLimits() {
+    return this.lastConnect?.limits;
+  }
+  async createSession(metadata = {}) {
+    const payload = await this.request("session.create", { metadata });
+    return String(payload.session_id ?? "");
+  }
+  async listSessions(limit = 50) {
+    const payload = await this.request("session.list", { limit });
+    return payload.sessions ?? [];
+  }
+  async getSession(sessionId) {
+    const payload = await this.request("session.get", { session_id: sessionId });
+    return payload;
+  }
+  async deleteSession(sessionId) {
+    await this.request("session.delete", { session_id: sessionId });
+  }
+  async startTurn(sessionId, input, options = {}) {
+    const payload = await this.request("turn.start", {
+      session_id: sessionId,
+      capability: options.capability,
+      input,
+      metadata: options.metadata
+    });
+    return {
+      session_id: String(payload.session_id ?? sessionId),
+      turn_id: String(payload.turn_id ?? ""),
+      status: String(payload.status ?? "accepted")
+    };
+  }
+  async subscribeTurn(turnId, afterSeq) {
+    await this.request("turn.subscribe", {
+      turn_id: turnId,
+      after_seq: afterSeq ?? this.lastEventSeq
+    });
+  }
+  async subscribeSession(sessionId, afterSeq) {
+    await this.request("session.subscribe", {
+      session_id: sessionId,
+      after_seq: afterSeq ?? this.lastEventSeq
+    });
+  }
+  async cancelTurn(turnId) {
+    await this.request("turn.cancel", { turn_id: turnId });
+  }
+  async regenerateLastTurn(sessionId) {
+    const payload = await this.request("turn.regenerate", { session_id: sessionId });
+    return {
+      session_id: String(payload.session_id ?? sessionId),
+      turn_id: String(payload.turn_id ?? ""),
+      status: String(payload.status ?? "accepted")
+    };
+  }
+  async commitAttachment(params) {
+    const payload = await this.request("attachment.commit", params);
+    return payload.attachment ?? payload;
+  }
+  async getSettings() {
+    return settingsFromPayload(await this.request("settings.get"));
+  }
+  async updateSettings(settings) {
+    return settingsFromPayload(await this.request("settings.update", { settings }));
+  }
+  async updateModelConfig(modelConfig) {
+    return this.updateSettings({ model_config: modelConfig });
+  }
+  async request(method, params = {}) {
+    if (!this.isConnected() || !this.lastConnect) {
+      await this.connect();
+    }
+    const response = await this.sendRequest(method, params);
+    return this.unwrap(response, method);
+  }
+  sendRequest(method, params = {}, id) {
+    const requestId = id ?? `cathygo_req_${this.requestSeq++}`;
+    const response = new Promise((resolve, reject) => {
+      this.pending.set(requestId, { resolve, reject });
+    });
+    this.send(method, params, requestId);
+    return response;
+  }
+  send(method, params, id) {
+    const requestId = id ?? `cathygo_req_${this.requestSeq++}`;
+    const frame = {
+      type: "req",
+      id: requestId,
+      method,
+      params
+    };
+    this.transport.sendFrame(frame);
+    return requestId;
+  }
+  rejectPending(message) {
+    for (const pending of this.pending.values()) {
+      pending.reject(new Error(message));
+    }
+    this.pending.clear();
+  }
+  unwrap(response, method) {
+    if (response.status !== "ok") {
+      throw new CathyGOClientError(
+        response.error?.message ?? `${method} failed`,
+        response.error?.code
+      );
+    }
+    return response.payload ?? {};
+  }
+  handleFrame(frame) {
+    if (frame.type === "res") {
+      const pending = this.pending.get(frame.id);
+      if (pending) {
+        this.pending.delete(frame.id);
+        pending.resolve(frame);
+      }
+    }
+    if (isLearningTurnEvent(frame)) {
+      if (typeof frame.seq === "number" && frame.seq > this.lastEventSeq) {
+        this.lastEventSeq = frame.seq;
+      }
+      this.callbacks.onTurnEvent?.(frame);
+      for (const handler of this.turnHandlers) {
+        handler(frame);
+      }
+    }
+    this.callbacks.onFrame?.(frame);
+  }
+};
+function connectPayload(options) {
+  return {
+    protocol: { name: "cathygo.vnext", version: 1 },
+    client: {
+      id: options.clientId ?? "cathygo-web-shell",
+      version: options.clientVersion ?? "0.1.0",
+      platform: options.device?.platform ?? "web"
+    },
+    role: options.role ?? "child",
+    scopes: options.scopes ?? ["learning.write", "session.read", "session.write", "settings.write"],
+    device: options.device ? {
+      id: options.device.deviceId,
+      name: options.device.displayName ?? options.device.platform,
+      platform: options.device.platform,
+      app_version: options.device.appVersion
+    } : { id: "cathygo-web-shell", name: "CathyGO Web", platform: "web" },
+    auth: { token: options.authToken }
+  };
+}
+function parseConnectPayload(payload) {
+  const protocol = payload.protocol;
+  const features = payload.features ?? {
+    methods: [],
+    events: []
+  };
+  const limits = payload.limits ?? {
+    max_payload_bytes: 262144,
+    max_upload_bytes: 10 * 1024 * 1024,
+    heartbeat_interval_ms: 15e3
+  };
+  return {
+    protocol: protocol ?? { name: "cathygo.vnext", version: 1 },
+    features,
+    limits
+  };
+}
+function settingsFromPayload(payload) {
+  return {
+    ...payload.settings ?? {},
+    settings_schema_version: Number(payload.settings_schema_version ?? 0) || void 0,
+    sections: payload.sections
+  };
+}
+function isLearningTurnEvent(frame) {
+  return frame.type === "event" && (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."));
+}
+
+// src/turn-input.ts
+function textTurnInput(text) {
+  return { text };
+}
+function photoQuestionTurnInput(text, attachments) {
+  return {
+    parts: [
+      ...text ? [{ type: "text", text }] : [],
+      ...attachments.map((attachment) => ({
+        type: "image",
+        attachment_id: attachment.id
+      }))
+    ],
+    attachments: attachments.map((attachment) => ({
+      attachment_id: attachment.id,
+      kind: "image",
+      mime_type: attachment.mime_type,
+      uri: attachment.uri
+    }))
+  };
+}
+function capabilityForTurn(attachments) {
+  return attachments.length ? "photo_question" : "chat";
+}
+function learningTurnInput(text, attachments) {
+  if (attachments.length === 0) {
+    return textTurnInput(text);
+  }
+  return photoQuestionTurnInput(text, attachments);
+}
+export {
+  CathyGOClientError,
+  CathyGOProtocolClient,
+  capabilityForTurn,
+  connectPayload,
+  isLearningTurnEvent,
+  learningTurnInput,
+  parseConnectPayload,
+  photoQuestionTurnInput,
+  settingsFromPayload,
+  textTurnInput
+};

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@beanx/cathygo-protocol",
+  "version": "0.1.0",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}