@neta-art/cohub-protocol 1.2.0 → 1.2.1

package/dist/gateway/index.d.ts

@@ -48,20 +48,42 @@ export interface GatewayInboundEvent {
     meta?: Record<string, unknown> | null;
 }
 export interface GatewaySessionOutputBase {
-    type: "session.turn.progress" | "session.turn.final" | "session.turn.error" | "session.message.persisted";
+    type: "session.turn.patch" | "session.turn.error" | "session.message.persisted";
     spaceId: string;
     sessionId: string;
 }
-export interface GatewaySessionTurnProgressOutput extends GatewaySessionOutputBase {
-    type: "session.turn.progress";
+export type GatewaySessionPatchOperation = {
+    o: "append";
+    p: string;
+    v: unknown;
+} | {
+    o: "replace";
+    p: string;
+    v: unknown;
+} | {
+    o: "add";
+    p: string;
+    v: unknown;
+} | {
+    o: "merge";
+    p: string;
+    v: Record<string, unknown>;
+} | {
+    o: "remove";
+    p: string;
+} | {
+    v: unknown;
+    o?: undefined;
+    p?: undefined;
+};
+export interface GatewaySessionTurnPatchOutput extends GatewaySessionOutputBase {
+    type: "session.turn.patch";
+    turnId: string | null;
+    messageId: string | null;
     anchorUserMessageId: string | null;
-    content: ContentBlock[];
-}
-export interface GatewaySessionTurnFinalOutput extends GatewaySessionOutputBase {
-    type: "session.turn.final";
-    sessionMessageId: string | null;
-    anchorUserMessageId: string | null;
-    content: ContentBlock[];
+    seq: number;
+    baseSeq: number;
+    ops: GatewaySessionPatchOperation[];
 }
 export interface GatewaySessionTurnErrorOutput extends GatewaySessionOutputBase {
     type: "session.turn.error";
@@ -72,7 +94,7 @@ export interface GatewaySessionMessagePersistedOutput extends GatewaySessionOutp
     type: "session.message.persisted";
     message: MessageRecord;
 }
-export type GatewaySessionOutput = GatewaySessionTurnProgressOutput | GatewaySessionTurnFinalOutput | GatewaySessionTurnErrorOutput | GatewaySessionMessagePersistedOutput;
+export type GatewaySessionOutput = GatewaySessionTurnPatchOutput | GatewaySessionTurnErrorOutput | GatewaySessionMessagePersistedOutput;
 export interface GatewayOutboundCommand {
     commandId: string;
     timestamp: number;

package/dist/gateway.d.ts

@@ -0,0 +1,136 @@
+export type ChannelProvider = "web" | "websocket" | "discord" | "feishu" | "telegram" | "slack";
+export declare function buildSessionSourceChannel(event: GatewayInboundEvent): string;
+export interface DiscordChannelConfig {
+    inbound?: {
+        requireMentionInGuild?: boolean;
+    };
+    outbound?: {
+        showThinking?: boolean;
+        showToolCalls?: boolean;
+    };
+}
+export type ChannelConfig = DiscordChannelConfig | FeishuChannelConfig | Record<string, unknown>;
+export interface FeishuChannelConfig {
+    brand?: "feishu" | "lark";
+    inbound?: {
+        requireMentionInGroup?: boolean;
+    };
+    outbound?: {
+        renderMode?: "card" | "post";
+        showThinking?: boolean;
+        showToolCalls?: boolean;
+    };
+}
+export interface GatewayInboundEvent {
+    eventId: string;
+    timestamp: number;
+    eventType?: "message_create" | "conversation_create";
+    channelId: string;
+    provider: ChannelProvider;
+    externalChatId: string;
+    externalMessageId: string;
+    bindingKey?: string;
+    conversation: {
+        id: string;
+        parentId?: string | null;
+        meta?: Record<string, unknown> | null;
+    };
+    message?: {
+        parentMessageId?: string | null;
+        meta?: Record<string, unknown> | null;
+    };
+    sender: {
+        id: string;
+        name?: string;
+    };
+    content: import("./session-ingestion.js").ContentBlock[];
+    meta?: Record<string, unknown> | null;
+}
+export interface GatewaySessionOutputBase {
+    type: "session.turn.progress" | "session.turn.final" | "session.turn.error" | "session.message.persisted";
+    spaceId: string;
+    sessionId: string;
+}
+export interface GatewaySessionTurnProgressOutput extends GatewaySessionOutputBase {
+    type: "session.turn.progress";
+    anchorUserMessageId: string | null;
+    content: import("./session-ingestion.js").ContentBlock[];
+}
+export interface GatewaySessionTurnFinalOutput extends GatewaySessionOutputBase {
+    type: "session.turn.final";
+    sessionMessageId: string | null;
+    anchorUserMessageId: string | null;
+    content: import("./session-ingestion.js").ContentBlock[];
+}
+export interface GatewaySessionTurnErrorOutput extends GatewaySessionOutputBase {
+    type: "session.turn.error";
+    anchorUserMessageId: string | null;
+    error: string;
+}
+export interface GatewaySessionMessagePersistedOutput extends GatewaySessionOutputBase {
+    type: "session.message.persisted";
+    message: import("./session-ingestion.js").MessageRecord;
+}
+export type GatewaySessionOutput = GatewaySessionTurnProgressOutput | GatewaySessionTurnFinalOutput | GatewaySessionTurnErrorOutput | GatewaySessionMessagePersistedOutput;
+export interface DiscordDeliveryPlan {
+    adapter: "discord";
+    mode: "send" | "upsert";
+    primaryText: string;
+    continuationChunks: string[];
+    files: string[];
+    replyToExternalMessageId?: string;
+    turnAnchorMessageId?: string | null;
+    preferredEditExternalMessageId?: string | null;
+}
+export interface FeishuDeliveryPlan {
+    adapter: "feishu";
+    mode: "create_or_update";
+    renderMode: "card" | "post";
+    msgType: "interactive" | "post";
+    content: string;
+    imageKeys: string[];
+    replyToExternalMessageId?: string;
+    turnAnchorMessageId?: string | null;
+    preferredEditExternalMessageId?: string | null;
+}
+export type GatewayDeliveryPlan = DiscordDeliveryPlan | FeishuDeliveryPlan;
+export interface GatewayOutboundCommand {
+    commandId: string;
+    timestamp: number;
+    channelId: string;
+    provider: ChannelProvider;
+    externalChatId: string;
+    content: import("./session-ingestion.js").ContentBlock[];
+    replyToExternalMessageId?: string;
+    spaceId?: string;
+    spaceSessionId?: string;
+    sessionMessageId?: string;
+    deliveryPlan?: GatewayDeliveryPlan | null;
+    meta?: (Record<string, unknown> & {
+        sessionOutput?: GatewaySessionOutput | null;
+    }) | null;
+}
+export interface GatewayControlCommand {
+    action: "connect" | "disconnect" | "reload";
+    configs: {
+        channelId: string;
+        provider: ChannelProvider;
+        credentials: Record<string, unknown>;
+    }[];
+}
+export type GatewayLogDirection = "inbound" | "outbound";
+export type GatewayLogStatus = "pending" | "success" | "failed";
+export interface GatewayLogEvent {
+    logId: string;
+    timestamp: number;
+    direction: GatewayLogDirection;
+    provider: ChannelProvider;
+    channelId: string;
+    externalChatId: string;
+    externalMessageId?: string;
+    rawPayload: Record<string, unknown>;
+    normalizedPayload?: Record<string, unknown>;
+    status: GatewayLogStatus;
+    errorMessage?: string;
+    correlationId?: string;
+}

package/dist/gateway.js

@@ -0,0 +1,48 @@
+export function buildSessionSourceChannel(event) {
+    const provider = event.provider;
+    const meta = (event.conversation?.meta ?? event.meta ?? {});
+    switch (provider) {
+        case "discord":
+            return buildDiscordSourceChannel(event, meta);
+        case "feishu":
+            return buildFeishuSourceChannel(event, meta);
+        case "web":
+            return "web";
+        default:
+            return `${provider}:${event.conversation?.id?.trim() || event.externalChatId}`;
+    }
+}
+function buildDiscordSourceChannel(event, meta) {
+    const isDm = meta.isDm === true;
+    const guildName = typeof meta.guildName === "string" ? meta.guildName : null;
+    const channelName = typeof meta.channelName === "string" ? meta.channelName : null;
+    const parentChannelName = typeof meta.parentChannelName === "string" ? meta.parentChannelName : null;
+    const threadName = typeof meta.threadName === "string" ? meta.threadName : null;
+    const senderName = event.sender?.name ?? null;
+    if (isDm) {
+        return `discord:dm:${senderName ?? event.sender.id}`;
+    }
+    if (threadName && parentChannelName && guildName) {
+        return `discord:${guildName}:#${parentChannelName}>${threadName}`;
+    }
+    if (channelName && guildName) {
+        return `discord:${guildName}:#${channelName}`;
+    }
+    if (guildName) {
+        return `discord:${guildName}`;
+    }
+    return `discord:${event.conversation?.id?.trim() || event.externalChatId}`;
+}
+function buildFeishuSourceChannel(event, meta) {
+    const chatType = meta.chatType;
+    const chatName = typeof meta.chatName === "string" ? meta.chatName : null;
+    const senderName = event.sender?.name ?? null;
+    const isDm = chatType === "p2p";
+    if (isDm) {
+        return `feishu:dm:${senderName ?? event.sender.id}`;
+    }
+    if (chatName) {
+        return `feishu:group:${chatName}`;
+    }
+    return `feishu:${event.conversation?.id?.trim() || event.externalChatId}`;
+}

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 export * from "./core/content.js";
 export * from "./core/usage.js";
 export * from "./model/session.js";
+export * from "./model/turn.js";
 export * from "./realtime/stream.js";
 export * from "./realtime/websocket.js";
 export * from "./gateway/index.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export * from "./core/content.js";
 export * from "./core/usage.js";
 export * from "./model/session.js";
+export * from "./model/turn.js";
 export * from "./realtime/stream.js";
 export * from "./realtime/websocket.js";
 export * from "./gateway/index.js";

package/dist/model/session.d.ts

@@ -1,5 +1,6 @@
 import type { ContentBlock } from "../core/content.js";
 import type { Usage } from "../core/usage.js";
+export type { MessageToolCallsFile, SessionTurnIntent, SessionTurnIntermediateIndex, SessionTurnIntermediateSummary, SessionTurnRecord, SessionTurnStatus, SessionTurnSummary, StoredIntermediateMessage, StoredIntermediateMessageToolCallSummary, StoredToolCall, TurnIntermediateMessagesFile, } from "./turn.js";
 export type SessionPromptInput = {
     spaceId: string;
     sessionId: string;
@@ -9,9 +10,10 @@ export type SessionPromptInput = {
     };
     meta?: {
         source?: string;
-        intent?: "auto" | "continue" | "new_session" | "fork";
+        intent?: "auto" | "continue" | "new_session" | "fork" | "steer" | "followup";
         model?: string;
         provider?: string;
+        turnId?: string;
     } | null;
 };
 export type RegisterSessionInput = {

package/dist/model/turn.d.ts

@@ -0,0 +1,95 @@
+import type { ContentBlock } from "../core/content.js";
+import type { Usage } from "../core/usage.js";
+export type SessionTurnStatus = "running" | "completed" | "failed" | "interrupted";
+export type SessionTurnIntent = "steer" | "followup";
+export type SessionTurnSummary = {
+    text?: string | null;
+    finishReason?: "completed" | "failed" | "interrupted";
+    interruptedByTurnId?: string | null;
+};
+export type SessionTurnIntermediateIndex = {
+    version: 1;
+    messagesObjectKey: string | null;
+    messagesSizeBytes?: number | null;
+    toolCallsBaseObjectKey?: string | null;
+};
+export type SessionTurnIntermediateSummary = {
+    messageCount: number;
+    toolCallCount: number;
+    usage?: Usage | null;
+    lastMessageText?: string | null;
+    hasError?: boolean;
+};
+export type StoredIntermediateMessageToolCallSummary = {
+    id: string;
+    name: string;
+    status: "running" | "done" | "failed";
+    input: Record<string, unknown>;
+};
+export type StoredIntermediateMessage = {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant" | "system";
+    content: ContentBlock[];
+    text: string | null;
+    provider: string | null;
+    model: string | null;
+    stopReason: string | null;
+    errorMessage: string | null;
+    usage: Usage | null;
+    toolCalls: StoredIntermediateMessageToolCallSummary[];
+    toolCallsObjectKey: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: string;
+};
+export type StoredToolCall = {
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    result: {
+        content: string | ContentBlock[] | null;
+        isError: boolean;
+    } | null;
+    meta: Record<string, unknown> | null;
+};
+export type MessageToolCallsFile = {
+    version: 1;
+    spaceId: string;
+    sessionId: string;
+    turnId: string;
+    messageId: string;
+    toolCalls: StoredToolCall[];
+};
+export type TurnIntermediateMessagesFile = {
+    version: 1;
+    spaceId: string;
+    sessionId: string;
+    turnId: string;
+    summary: SessionTurnIntermediateSummary;
+    messages: StoredIntermediateMessage[];
+};
+export type SessionTurnRecord = {
+    id: string;
+    sessionId: string;
+    userUuid: string | null;
+    sequence: number;
+    status: SessionTurnStatus;
+    intent: SessionTurnIntent;
+    userContent: ContentBlock[];
+    userText: string | null;
+    assistantContent: ContentBlock[] | null;
+    assistantText: string | null;
+    provider: string | null;
+    model: string | null;
+    stopReason: string | null;
+    errorMessage: string | null;
+    usage: Usage | null;
+    summary: SessionTurnSummary | null;
+    intermediateIndex: SessionTurnIntermediateIndex | null;
+    intermediateSummary: SessionTurnIntermediateSummary | null;
+    meta: Record<string, unknown> | null;
+    startedAt: string | null;
+    completedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+};

package/dist/model/turn.js

@@ -0,0 +1 @@
+export {};

package/dist/permissions.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Permission level for space / session resources.
+ *
+ * - `read`   — anyone can read (including anonymous users)
+ * - `write`  — anyone can read and write
+ * - `private` — explicitly deny access (no fallback to parent)
+ */
+export type ResourcePermissionLevel = "read" | "write" | "private";

package/dist/permissions.js

@@ -0,0 +1 @@
+export {};

package/dist/realtime/stream.d.ts

@@ -3,6 +3,9 @@ export type SessionStreamEvent = {
     type: "stream_update";
     spaceId: string;
     sessionId: string;
+    turnId?: string | null;
+    seq: number;
+    baseSeq: number;
     content: ContentBlock[];
     sourceMessageId: string | null;
     timestamp: number;

package/dist/realtime/websocket.d.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { ContentBlock } from "../core/content.js";
 import type { MessageRecord } from "../model/session.js";
 import type { SpaceFsChangedPayload } from "../fs/index.js";
+export declare const WS_COMPACT_STREAM_CAPABILITY = "session.compact_stream.v1";
 export declare const contentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"text">;
     text: z.ZodString;
@@ -50,6 +51,7 @@ export declare const wsClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     requestId: z.ZodOptional<z.ZodString>;
     payload: z.ZodObject<{
         token: z.ZodString;
+        capabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"session.message.create">;
@@ -143,11 +145,33 @@ export declare const channelEnvelopeSchema: z.ZodObject<{
     sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
+export declare const realtimeCompactFrameSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    t: z.ZodLiteral<"d">;
+    sid: z.ZodString;
+    s: z.ZodNumber;
+    b: z.ZodNumber;
+    v: z.ZodUnknown;
+}, z.core.$strip>, z.ZodObject<{
+    t: z.ZodLiteral<"p">;
+    sid: z.ZodString;
+    s: z.ZodNumber;
+    b: z.ZodNumber;
+    o: z.ZodEnum<{
+        append: "append";
+        replace: "replace";
+        add: "add";
+        merge: "merge";
+        remove: "remove";
+    }>;
+    p: z.ZodString;
+    v: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>], "t">;
 export type WsClientEvent = {
     type: "auth";
     requestId?: string;
     payload: {
         token: string;
+        capabilities?: string[];
     };
 } | {
     type: "session.message.create";
@@ -173,6 +197,7 @@ export type WsClientEvent = {
 };
 export type RealtimeEnvelope = z.output<typeof realtimeEnvelopeSchema>;
 export type ChannelEnvelope = RealtimeEnvelope;
+export type RealtimeCompactFrame = z.output<typeof realtimeCompactFrameSchema>;
 export type RealtimeEnvelopeBase = RealtimeEnvelope;
 export type RealtimeDomain = RealtimeEnvelopeBase["domain"];
 export type SystemReadyEvent = {
@@ -272,18 +297,45 @@ export type SessionTurnProgressEvent = {
         content: ContentBlock[];
     };
 };
-export type SessionTurnFinalEvent = {
+export type RealtimePatchOperation = {
+    o: "append";
+    p: string;
+    v: unknown;
+} | {
+    o: "replace";
+    p: string;
+    v: unknown;
+} | {
+    o: "add";
+    p: string;
+    v: unknown;
+} | {
+    o: "merge";
+    p: string;
+    v: Record<string, unknown>;
+} | {
+    o: "remove";
+    p: string;
+} | {
+    v: unknown;
+    o?: undefined;
+    p?: undefined;
+};
+export type SessionTurnPatchEvent = {
     id: string;
     timestamp: number;
     domain: "session";
-    type: "session.turn.final";
+    type: "session.turn.patch";
     requestId?: string | null;
     spaceId: string;
     sessionId: string;
     payload: {
-        sessionMessageId: string | null;
+        turnId: string | null;
+        messageId: string | null;
         anchorUserMessageId: string | null;
-        content: ContentBlock[];
+        seq: number;
+        baseSeq: number;
+        ops: RealtimePatchOperation[];
     };
 };
 export type SessionTurnErrorEvent = {
@@ -299,6 +351,7 @@ export type SessionTurnErrorEvent = {
         error: string;
     };
 };
+export type RealtimeMessageRecord = Pick<MessageRecord, "id" | "sessionId" | "role" | "content" | "text" | "sequence" | "provider" | "model" | "stopReason" | "errorMessage" | "usage" | "meta" | "createdAt">;
 export type SessionMessagePersistedEvent = {
     id: string;
     timestamp: number;
@@ -308,7 +361,7 @@ export type SessionMessagePersistedEvent = {
     spaceId: string;
     sessionId: string;
     payload: {
-        message: MessageRecord;
+        message: RealtimeMessageRecord;
     };
 };
 export type SpaceFsChangedEvent = {
@@ -321,6 +374,6 @@ export type SpaceFsChangedEvent = {
     sessionId?: string | null;
     payload: SpaceFsChangedPayload;
 };
-export type RealtimeServerEvent = SystemReadyEvent | SystemAuthOkEvent | SystemRequestErrorEvent | SystemPongEvent | SystemAckOkEvent | SessionRequestAcceptedEvent | SessionRequestErrorEvent | SessionTurnProgressEvent | SessionTurnFinalEvent | SessionTurnErrorEvent | SessionMessagePersistedEvent | SpaceFsChangedEvent;
+export type RealtimeServerEvent = SystemReadyEvent | SystemAuthOkEvent | SystemRequestErrorEvent | SystemPongEvent | SystemAckOkEvent | SessionRequestAcceptedEvent | SessionRequestErrorEvent | SessionTurnProgressEvent | SessionTurnPatchEvent | SessionTurnErrorEvent | SessionMessagePersistedEvent | SpaceFsChangedEvent;
 export type WsServerEnvelope = RealtimeEnvelope;
 export type ChannelServerEnvelope = ChannelEnvelope;

package/dist/realtime/websocket.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 const contentBlockMetaSchema = z.record(z.string(), z.unknown());
+export const WS_COMPACT_STREAM_CAPABILITY = "session.compact_stream.v1";
 export const contentBlockSchema = z.discriminatedUnion("type", [
     z.object({
         type: z.literal("text"),
@@ -45,7 +46,10 @@ export const wsClientEventSchema = z.discriminatedUnion("type", [
     z.object({
         type: z.literal("auth"),
         requestId: z.string().optional(),
-        payload: z.object({ token: z.string().min(1) }),
+        payload: z.object({
+            token: z.string().min(1),
+            capabilities: z.array(z.string().min(1)).optional(),
+        }),
     }),
     z.object({
         type: z.literal("session.message.create"),
@@ -83,3 +87,21 @@ export const realtimeEnvelopeSchema = z.object({
     payload: z.record(z.string(), z.unknown()),
 });
 export const channelEnvelopeSchema = realtimeEnvelopeSchema;
+export const realtimeCompactFrameSchema = z.discriminatedUnion("t", [
+    z.object({
+        t: z.literal("d"),
+        sid: z.string().min(1),
+        s: z.number().int().nonnegative(),
+        b: z.number().int().nonnegative(),
+        v: z.unknown(),
+    }),
+    z.object({
+        t: z.literal("p"),
+        sid: z.string().min(1),
+        s: z.number().int().nonnegative(),
+        b: z.number().int().nonnegative(),
+        o: z.enum(["append", "replace", "add", "merge", "remove"]),
+        p: z.string().min(1),
+        v: z.unknown().optional(),
+    }),
+]);

package/dist/responses.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/responses.js

@@ -0,0 +1,4 @@
+export {};
+// Responses API has been removed.
+// Sessions now work via simple POST /sessions/:id/messages.
+// Frontend live updates are delivered via Gateway WebSocket.

package/dist/session-ingestion.d.ts

@@ -0,0 +1,158 @@
+export type ContentBlockMeta = Record<string, unknown>;
+export type ContentBlock = {
+    type: "text";
+    text: string;
+    _meta?: ContentBlockMeta;
+} | {
+    type: "thinking";
+    thinking: string;
+    signature?: string;
+    _meta?: ContentBlockMeta;
+} | {
+    type: "image";
+    source: {
+        type: "url";
+        url: string;
+    } | {
+        type: "base64";
+        media_type: string;
+        data: string;
+    };
+    _meta?: ContentBlockMeta;
+} | {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+    _meta?: ContentBlockMeta;
+} | {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string | ContentBlock[];
+    is_error?: boolean;
+    _meta?: ContentBlockMeta;
+} | {
+    type: "system_note";
+    note_type: "session_created" | "forked" | "compacted" | "info";
+    text: string;
+    _meta?: ContentBlockMeta;
+};
+export type SessionPromptInput = {
+    spaceId: string;
+    sessionId: string;
+    userMessageId?: string | null;
+    message: {
+        content: ContentBlock[];
+    };
+    meta?: {
+        source?: string;
+        intent?: "auto" | "continue" | "new_session" | "fork";
+        model?: string;
+        provider?: string;
+    } | null;
+};
+export type RegisterSessionInput = {
+    spaceId: string;
+    sessionId: string;
+    title?: string | null;
+    source?: string | null;
+    externalSessionId?: string | null;
+    meta?: Record<string, unknown> | null;
+};
+export type PersistMessageInput = {
+    spaceId: string;
+    sessionId: string;
+    previousMessageId?: string | null;
+    anchorUserMessageId?: string | null;
+    idempotencyKey: string;
+    message: {
+        role?: "user" | "assistant" | "system";
+        externalMessageId?: string | null;
+        protocolMessageId?: string | null;
+        content: ContentBlock[];
+        text?: string | null;
+        provider?: string | null;
+        model?: string | null;
+        stopReason?: string | null;
+        errorMessage?: string | null;
+        meta?: Record<string, unknown> | null;
+        usage?: {
+            input?: number;
+            output?: number;
+            costTotal?: number;
+        } | null;
+    };
+};
+export type UpdateSessionInfoInput = {
+    spaceId: string;
+    sessionId: string;
+    title?: string | null;
+    updatedAt?: string | null;
+    meta?: Record<string, unknown> | null;
+};
+export type SessionStreamEvent = {
+    type: "stream_update";
+    spaceId: string;
+    sessionId: string;
+    /** `content` always contains delta blocks to be merged into the current streaming state. */
+    content: ContentBlock[];
+    sourceMessageId: string | null;
+    timestamp: number;
+    turnEnd?: boolean;
+    anchorUserMessageId?: string | null;
+};
+export type SessionStreamError = {
+    type: "error";
+    spaceId: string;
+    sessionId: string | null;
+    error: string;
+};
+export type SessionBindingRecord = {
+    id: string;
+    spaceId: string;
+    spaceSessionId: string;
+    spaceChannelId: string;
+    provider: string;
+    bindingKey: string;
+    externalChatId: string;
+    status: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: string;
+    updatedAt: string;
+    lastMessageAt: string | null;
+};
+export type SessionRecord = {
+    id: string;
+    spaceId: string;
+    title: string | null;
+    source: string | null;
+    status: string | null;
+    externalSessionId: string | null;
+    meta: Record<string, unknown> | null;
+    parentSessionId: string | null;
+    forkedFromMessageId: string | null;
+    lineageRootSessionId: string | null;
+    forkDepth: number;
+    latestMessageText: string | null;
+    lastMessageAt: string | null;
+    lastMessageId: string | null;
+    createdAt: string;
+    updatedAt: string;
+};
+export type MessageRecord = {
+    id: string;
+    sessionId: string;
+    role: "user" | "assistant" | "system";
+    content: ContentBlock[];
+    text: string | null;
+    sequence: number;
+    provider: string | null;
+    model: string | null;
+    stopReason: string | null;
+    errorMessage: string | null;
+    usageInput: number | null;
+    usageOutput: number | null;
+    costTotal: string | null;
+    meta: Record<string, unknown> | null;
+    createdAt: string;
+};

package/dist/session-ingestion.js

@@ -0,0 +1,2 @@
+// ─── Content Block — Anthropic-style, single source of truth ───
+export {};

package/dist/space-fs.d.ts

@@ -0,0 +1,33 @@
+export type SpaceFsEntry = {
+    name: string;
+    path: string;
+    type: "file" | "dir" | "symlink";
+    size: number;
+    mimeType: string | null;
+    mtimeMs: number;
+};
+export type SpaceFsTreeResponse = {
+    path: string;
+    entries: SpaceFsEntry[];
+};
+export type SpaceFsFileKind = "text" | "binary";
+export type SpaceFsEncoding = "utf-8" | "base64";
+export type SpaceFsFileResponse = {
+    path: string;
+    name: string;
+    size: number;
+    mimeType: string | null;
+    mtimeMs: number;
+    kind: SpaceFsFileKind;
+    encoding: SpaceFsEncoding;
+    content: string;
+};
+export type SpaceFsWriteFileInput = {
+    path: string;
+    content: string;
+    encoding: SpaceFsEncoding;
+};
+export type SpaceFsMoveInput = {
+    fromPath: string;
+    toPath: string;
+};

package/dist/space-fs.js

@@ -0,0 +1 @@
+export {};

package/dist/space-sandbox.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Space sandbox lifecycle status.
+ *
+ * Internal infrastructure state only.
+ * Not intended as a primary user-facing concept.
+ */
+export type SpaceSandboxStatus = "pending" | "provisioning" | "ready" | "stopped" | "error" | "terminated";

package/dist/space-sandbox.js

@@ -0,0 +1 @@
+export {};

package/dist/tasks.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Task system protocol definitions.
+ * Shared between API (scheduler) and Worker (executor).
+ */
+/**
+ * Task type identifier.
+ * Open-ended — add new types as needed.
+ */
+export type TaskType = string;
+/**
+ * Universal task payload carried by every BullMQ job.
+ * Fields like spaceId / sessionId are optional
+ * so tasks can be scoped or global.
+ */
+export interface TaskPayload {
+    type: TaskType;
+    /** Optional: which space this task relates to */
+    spaceId?: string;
+    /** Optional: which session this task relates to */
+    sessionId?: string;
+    /** Optional: the user who owns / triggered this task */
+    userId?: string;
+    /** Optional: cron job that spawned this execution (set by API on enqueue) */
+    cronJobId?: string;
+    /** Task-specific parameters */
+    data?: Record<string, unknown>;
+}
+/**
+ * Task run status in the database.
+ *
+ * Flow:
+ *   pending (API-enqueued only)
+ *     → running (worker picked up)
+ *       → completed | failed
+ */
+export type TaskRunStatus = "pending" | "running" | "completed" | "failed";
+/**
+ * Cron schedule configuration passed from the client.
+ */
+export interface TaskScheduleConfig {
+    /** Cron expression, e.g. "0 10 * * *" */
+    pattern: string;
+    /** IANA timezone, defaults to "Asia/Shanghai" */
+    timezone?: string;
+}

package/dist/tasks.js

@@ -0,0 +1,5 @@
+/**
+ * Task system protocol definitions.
+ * Shared between API (scheduler) and Worker (executor).
+ */
+export {};

package/dist/websocket.d.ts

@@ -0,0 +1,299 @@
+import { z } from "zod";
+import type { ContentBlock, MessageRecord } from "./session-ingestion.js";
+export declare const contentBlockSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"text">;
+    text: z.ZodString;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"thinking">;
+    thinking: z.ZodString;
+    signature: z.ZodOptional<z.ZodString>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"image">;
+    source: z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"url">;
+        url: z.ZodString;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"base64">;
+        media_type: z.ZodString;
+        data: z.ZodString;
+    }, z.core.$strip>]>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_use">;
+    id: z.ZodString;
+    name: z.ZodString;
+    input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_result">;
+    tool_use_id: z.ZodString;
+    content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnknown>]>;
+    is_error: z.ZodOptional<z.ZodBoolean>;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"system_note">;
+    note_type: z.ZodEnum<{
+        session_created: "session_created";
+        forked: "forked";
+        compacted: "compacted";
+        info: "info";
+    }>;
+    text: z.ZodString;
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>], "type">;
+export declare const wsClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"auth">;
+    requestId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodObject<{
+        token: z.ZodString;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"session.message.create">;
+    requestId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodObject<{
+        spaceId: z.ZodString;
+        sessionId: z.ZodString;
+        clientMessageId: z.ZodOptional<z.ZodString>;
+        content: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+            type: z.ZodLiteral<"text">;
+            text: z.ZodString;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"thinking">;
+            thinking: z.ZodString;
+            signature: z.ZodOptional<z.ZodString>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"image">;
+            source: z.ZodUnion<readonly [z.ZodObject<{
+                type: z.ZodLiteral<"url">;
+                url: z.ZodString;
+            }, z.core.$strip>, z.ZodObject<{
+                type: z.ZodLiteral<"base64">;
+                media_type: z.ZodString;
+                data: z.ZodString;
+            }, z.core.$strip>]>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_use">;
+            id: z.ZodString;
+            name: z.ZodString;
+            input: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"tool_result">;
+            tool_use_id: z.ZodString;
+            content: z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodUnknown>]>;
+            is_error: z.ZodOptional<z.ZodBoolean>;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"system_note">;
+            note_type: z.ZodEnum<{
+                session_created: "session_created";
+                forked: "forked";
+                compacted: "compacted";
+                info: "info";
+            }>;
+            text: z.ZodString;
+            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        }, z.core.$strip>], "type">>;
+        model: z.ZodOptional<z.ZodString>;
+        provider: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ping">;
+    requestId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ack">;
+    requestId: z.ZodOptional<z.ZodString>;
+    payload: z.ZodOptional<z.ZodObject<{
+        eventId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>], "type">;
+export declare const realtimeEnvelopeSchema: z.ZodObject<{
+    id: z.ZodString;
+    timestamp: z.ZodNumber;
+    domain: z.ZodEnum<{
+        system: "system";
+        session: "session";
+        space: "space";
+    }>;
+    type: z.ZodString;
+    requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    spaceId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    sessionId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export type { ContentBlock };
+export type WsClientEvent = {
+    type: "auth";
+    requestId?: string;
+    payload: {
+        token: string;
+    };
+} | {
+    type: "session.message.create";
+    requestId?: string;
+    payload: {
+        spaceId: string;
+        sessionId: string;
+        clientMessageId?: string;
+        content: ContentBlock[];
+        model?: string;
+        provider?: string;
+    };
+} | {
+    type: "ping";
+    requestId?: string;
+    payload?: Record<string, unknown>;
+} | {
+    type: "ack";
+    requestId?: string;
+    payload?: {
+        eventId?: string;
+    };
+};
+export type RealtimeEnvelope = z.output<typeof realtimeEnvelopeSchema>;
+export type RealtimeEnvelopeBase = RealtimeEnvelope;
+export type RealtimeDomain = RealtimeEnvelopeBase["domain"];
+export type SystemReadyEvent = {
+    id: string;
+    timestamp: number;
+    domain: "system";
+    type: "system.ready";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: {
+        connectionId: string;
+    };
+};
+export type SystemAuthOkEvent = {
+    id: string;
+    timestamp: number;
+    domain: "system";
+    type: "system.auth.ok";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: {
+        connectionId: string;
+        user: Record<string, unknown>;
+    };
+};
+export type SystemRequestErrorEvent = {
+    id: string;
+    timestamp: number;
+    domain: "system";
+    type: "system.request.error";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: {
+        code: string;
+        message: string;
+    };
+};
+export type SystemPongEvent = {
+    id: string;
+    timestamp: number;
+    domain: "system";
+    type: "system.pong";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: Record<string, never>;
+};
+export type SystemAckOkEvent = {
+    id: string;
+    timestamp: number;
+    domain: "system";
+    type: "system.ack.ok";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: Record<string, never>;
+};
+export type SessionRequestAcceptedEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.request.accepted";
+    requestId?: string | null;
+    spaceId: string;
+    sessionId: string;
+    payload: {
+        clientMessageId?: string | null;
+    };
+};
+export type SessionRequestErrorEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.request.error";
+    requestId?: string | null;
+    spaceId?: string | null;
+    sessionId?: string | null;
+    payload: {
+        code: string;
+        message: string;
+        clientMessageId?: string | null;
+    };
+};
+export type SessionTurnProgressEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.turn.progress";
+    requestId?: string | null;
+    spaceId: string;
+    sessionId: string;
+    payload: {
+        anchorUserMessageId: string | null;
+        content: ContentBlock[];
+    };
+};
+export type SessionTurnFinalEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.turn.final";
+    requestId?: string | null;
+    spaceId: string;
+    sessionId: string;
+    payload: {
+        sessionMessageId: string | null;
+        anchorUserMessageId: string | null;
+        content: ContentBlock[];
+    };
+};
+export type SessionTurnErrorEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.turn.error";
+    requestId?: string | null;
+    spaceId: string;
+    sessionId: string;
+    payload: {
+        anchorUserMessageId: string | null;
+        error: string;
+    };
+};
+export type SessionMessagePersistedEvent = {
+    id: string;
+    timestamp: number;
+    domain: "session";
+    type: "session.message.persisted";
+    requestId?: string | null;
+    spaceId: string;
+    sessionId: string;
+    payload: {
+        message: MessageRecord;
+    };
+};
+export type RealtimeServerEvent = SystemReadyEvent | SystemAuthOkEvent | SystemRequestErrorEvent | SystemPongEvent | SystemAckOkEvent | SessionRequestAcceptedEvent | SessionRequestErrorEvent | SessionTurnProgressEvent | SessionTurnFinalEvent | SessionTurnErrorEvent | SessionMessagePersistedEvent;
+export type WsServerEnvelope = RealtimeEnvelope;

package/dist/websocket.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+const contentBlockMetaSchema = z.record(z.string(), z.unknown());
+// ── Schemas ──
+export const contentBlockSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("text"),
+        text: z.string(),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("thinking"),
+        thinking: z.string(),
+        signature: z.string().optional(),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("image"),
+        source: z.union([
+            z.object({ type: z.literal("url"), url: z.string().url() }),
+            z.object({ type: z.literal("base64"), media_type: z.string(), data: z.string() }),
+        ]),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("tool_use"),
+        id: z.string(),
+        name: z.string(),
+        input: z.record(z.string(), z.unknown()),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("tool_result"),
+        tool_use_id: z.string(),
+        content: z.union([z.string(), z.array(z.unknown())]),
+        is_error: z.boolean().optional(),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+    z.object({
+        type: z.literal("system_note"),
+        note_type: z.enum(["session_created", "forked", "compacted", "info"]),
+        text: z.string(),
+        _meta: contentBlockMetaSchema.optional(),
+    }),
+]);
+export const wsClientEventSchema = z.discriminatedUnion("type", [
+    z.object({
+        type: z.literal("auth"),
+        requestId: z.string().optional(),
+        payload: z.object({ token: z.string().min(1) }),
+    }),
+    z.object({
+        type: z.literal("session.message.create"),
+        requestId: z.string().optional(),
+        payload: z.object({
+            spaceId: z.string().uuid(),
+            sessionId: z.string().uuid(),
+            clientMessageId: z.string().optional(),
+            content: z.array(contentBlockSchema).min(1),
+            model: z.string().optional(),
+            provider: z.string().optional(),
+        }),
+    }),
+    z.object({
+        type: z.literal("ping"),
+        requestId: z.string().optional(),
+        payload: z.record(z.string(), z.unknown()).optional(),
+    }),
+    z.object({
+        type: z.literal("ack"),
+        requestId: z.string().optional(),
+        payload: z.object({
+            eventId: z.string().optional(),
+        }).optional(),
+    }),
+]);
+export const realtimeEnvelopeSchema = z.object({
+    id: z.string(),
+    timestamp: z.number(),
+    domain: z.enum(["system", "session", "space"]),
+    type: z.string(),
+    requestId: z.string().nullable().optional(),
+    spaceId: z.string().nullable().optional(),
+    sessionId: z.string().nullable().optional(),
+    payload: z.record(z.string(), z.unknown()),
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub-protocol",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Shared protocol definitions for the Cohub agent collaboration platform.",
   "license": "UNLICENSED",
   "private": false,