@beanx/cathygo-protocol 0.1.0 → 0.1.2

package/README.md

@@ -0,0 +1,30 @@
+# @beanx/cathygo-protocol
+
+Public TypeScript protocol package for CathyGO Web/iOS clients.
+
+Current active upgrade plan:
+
+- [`../../docs/session-runtime-vnext-upgrade-plan.md`](../../docs/session-runtime-vnext-upgrade-plan.md)
+
+## vNext Role
+
+This package owns the typed client contract for:
+
+- request/response multiplexing over local WebSocket or BeanX Relay transport
+- `session.input` with `client_input_id`
+- `session.stop`
+- `session.resume`
+- `session.subscribe(session_id, after_seq, follow=true)`
+- stable event names for user messages, session loop lifecycle, assistant
+  deltas, terminal events, and replay
+
+It must not own product rendering state. Session view state and rendering
+helpers belong in `@beanx/cathygo-web-core`.
+
+## First vNext Deliverables
+
+- Add event/request/result types from the upgrade plan.
+- Update `CathyGOProtocolClient` methods.
+- Add tests for input idempotency fields, stop payloads, removed legacy command
+  rejection, and event typing.
+- Bump to `0.2.0` only after local Web validates the new runtime path.

package/dist/index.d.ts

@@ -48,15 +48,25 @@ type CathyGOResponse = {
 type LearningTurnEventPayload = {
     session_id?: string;
     turn_id?: string;
+    turn_ids?: string[];
+    client_input_id?: string;
+    client_turn_id?: string;
+    interrupted_turn_id?: string;
+    interrupted_turn_ids?: string[];
+    same_session_policy?: SameSessionPolicy;
     capability?: "chat" | "photo_question";
     input_summary?: string;
     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?: "running" | "completed" | "failed" | "cancelled";
+    status?: "accepted" | "idle" | "running" | "stopping" | "completed" | "failed" | "cancelled" | string;
     reason?: string;
     phase?: "queued" | "model" | "reasoning" | "tool" | "generating" | string;
     source?: "provider_reasoning_summary" | "public_progress" | "system_progress" | "hidden_reasoning" | string;
@@ -72,7 +82,7 @@ type LearningTurnEventPayload = {
 };
 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}`;
+    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;
 };
@@ -113,14 +123,39 @@ type MultimodalTurnInput = {
     attachments?: AttachmentInput[];
 };
 type TurnInput = TextTurnInput | MultimodalTurnInput;
-type TurnStartOptions = {
+type SameSessionPolicy = "interrupt" | "reject";
+type SessionInputOptions = {
     capability?: "chat" | "photo_question";
     metadata?: Record<string, unknown>;
+    clientInputId?: string;
+    clientTurnId?: string;
+    sameSessionPolicy?: SameSessionPolicy;
 };
-type TurnStartResult = {
+type SessionInputResult = {
     session_id: string;
     turn_id: string;
-    status: string;
+    status: "accepted" | "running" | "completed" | "failed" | "cancelled" | string;
+    client_input_id?: string;
+    client_turn_id?: string;
+    same_session_policy?: SameSessionPolicy;
+    interrupted_turn_id?: string;
+    interrupted_turn_ids?: string[];
+    idempotent_replay?: boolean;
+};
+type SessionStopResult = {
+    session_id: string;
+    status: "stopping" | "idle" | string;
+    turn_id?: string;
+    turn_ids?: string[];
+};
+type SessionRuntimeSnapshot = {
+    status: "idle" | "running" | "stopping" | string;
+    active_turn_id?: string | null;
+    active_turn_ids?: string[];
+    active_client_input_id?: string | null;
+    active_client_turn_id?: string | null;
+    last_event_seq: number;
+    last_durable_seq?: number;
 };
 type UploadScope = {
     sessionId?: string;
@@ -135,6 +170,7 @@ interface ConversationSummary {
     updated_at: string;
     created_at: string;
     metadata?: Record<string, unknown>;
+    runtime?: SessionRuntimeSnapshot;
 }
 interface ConversationMessage {
     id: string;
@@ -143,11 +179,15 @@ interface ConversationMessage {
     parts?: ConversationMessagePart[];
     turn_id?: string | null;
     created_at: string;
+    metadata?: Record<string, unknown>;
 }
 interface ConversationDetail {
-    session: ConversationSummary;
+    session: ConversationSummary & {
+        runtime?: SessionRuntimeSnapshot;
+    };
     messages: ConversationMessage[];
     activities?: AgentActivity[];
+    runtime?: SessionRuntimeSnapshot;
 }
 interface AgentActivity {
     activity_id: string;
@@ -176,6 +216,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;
@@ -356,11 +403,11 @@ declare class CathyGOProtocolClient {
     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>;
+    inputSession(sessionId: string, input: TurnInput, options?: SessionInputOptions): Promise<SessionInputResult>;
     subscribeSession(sessionId: string, afterSeq?: number): Promise<void>;
-    cancelTurn(turnId: string): Promise<void>;
-    regenerateLastTurn(sessionId: string): Promise<TurnStartResult>;
+    stopSession(sessionId: string): Promise<SessionStopResult>;
+    resumeSession(sessionId: string, afterSeq?: number): Promise<ConversationDetail>;
+    regenerateSession(sessionId: string): Promise<SessionInputResult>;
     commitAttachment(params: AttachmentCommitParams): Promise<GatewayAttachment>;
     getSettings(): Promise<GatewayVisibleSettings>;
     updateSettings(settings: Record<string, unknown>): Promise<GatewayVisibleSettings>;
@@ -377,10 +424,10 @@ declare function parseConnectPayload(payload: Record<string, unknown>): CathyGOC
 declare function settingsFromPayload(payload: Record<string, unknown>): GatewayVisibleSettings;
 declare function isLearningTurnEvent(frame: CathyGOIncomingFrame): frame is LearningTurnEvent;
 
-type LearningCapability = NonNullable<TurnStartOptions["capability"]>;
+type LearningCapability = NonNullable<SessionInputOptions["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 };
+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 };

package/dist/index.js

@@ -88,24 +88,20 @@ var CathyGOProtocolClient = class {
   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 inputSession(sessionId, input, options = {}) {
+    const payload = await this.request(
+      "session.input",
+      compactParams({
+        session_id: sessionId,
+        capability: options.capability,
+        input,
+        metadata: options.metadata,
+        client_input_id: options.clientInputId,
+        client_turn_id: options.clientTurnId,
+        same_session_policy: options.sameSessionPolicy
+      })
+    );
+    return turnStartResultFromPayload(payload, sessionId);
   }
   async subscribeSession(sessionId, afterSeq) {
     await this.request("session.subscribe", {
@@ -113,11 +109,25 @@ var CathyGOProtocolClient = class {
       after_seq: afterSeq ?? this.lastEventSeq
     });
   }
-  async cancelTurn(turnId) {
-    await this.request("turn.cancel", { turn_id: turnId });
+  async stopSession(sessionId) {
+    const payload = await this.request("session.stop", { session_id: sessionId });
+    return {
+      session_id: String(payload.session_id ?? sessionId),
+      status: String(payload.status ?? "idle"),
+      turn_id: optionalString(payload.turn_id),
+      turn_ids: Array.isArray(payload.turn_ids) ? payload.turn_ids.map((value) => String(value)) : void 0
+    };
   }
-  async regenerateLastTurn(sessionId) {
-    const payload = await this.request("turn.regenerate", { session_id: sessionId });
+  async resumeSession(sessionId, afterSeq) {
+    const detail = await this.getSession(sessionId);
+    await this.subscribeSession(
+      sessionId,
+      afterSeq ?? detail.runtime?.last_event_seq ?? detail.session.runtime?.last_event_seq
+    );
+    return detail;
+  }
+  async regenerateSession(sessionId) {
+    const payload = await this.request("session.regenerate", { session_id: sessionId });
     return {
       session_id: String(payload.session_id ?? sessionId),
       turn_id: String(payload.turn_id ?? ""),
@@ -242,7 +252,32 @@ function settingsFromPayload(payload) {
   };
 }
 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."));
+  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 turnStartResultFromPayload(payload, fallbackSessionId) {
+  return {
+    session_id: String(payload.session_id ?? fallbackSessionId),
+    turn_id: String(payload.turn_id ?? ""),
+    status: String(payload.status ?? "accepted"),
+    client_input_id: optionalString(payload.client_input_id),
+    client_turn_id: optionalString(payload.client_turn_id),
+    same_session_policy: sameSessionPolicy(payload.same_session_policy),
+    interrupted_turn_id: optionalString(payload.interrupted_turn_id),
+    interrupted_turn_ids: Array.isArray(payload.interrupted_turn_ids) ? payload.interrupted_turn_ids.map((value) => String(value)) : void 0,
+    idempotent_replay: payload.idempotent_replay === true
+  };
+}
+function optionalString(value) {
+  if (value === void 0 || value === null) return void 0;
+  const text = String(value).trim();
+  return text || void 0;
+}
+function sameSessionPolicy(value) {
+  if (value === "interrupt" || value === "reject") return value;
+  return void 0;
+}
+function compactParams(params) {
+  return Object.fromEntries(Object.entries(params).filter(([, value]) => value !== void 0));
 }
 
 // src/turn-input.ts

package/package.json

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