@neta-art/cohub-protocol 1.0.0

package/dist/realtime/websocket.d.ts

@@ -0,0 +1,315 @@
+import { z } from "zod";
+import type { ContentBlock } from "../core/content.js";
+import type { MessageRecord } from "../model/session.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 declare const channelEnvelopeSchema: 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 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 ChannelEnvelope = RealtimeEnvelope;
+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;
+export type ChannelServerEnvelope = ChannelEnvelope;

package/dist/realtime/websocket.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+const contentBlockMetaSchema = z.record(z.string(), z.unknown());
+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()),
+});
+export const channelEnvelopeSchema = realtimeEnvelopeSchema;

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/task/index.d.ts

@@ -0,0 +1,14 @@
+export type TaskType = string;
+export interface TaskPayload {
+    type: TaskType;
+    spaceId?: string;
+    sessionId?: string;
+    userId?: string;
+    cronJobId?: string;
+    data?: Record<string, unknown>;
+}
+export type TaskRunStatus = "pending" | "running" | "completed" | "failed";
+export interface TaskScheduleConfig {
+    pattern: string;
+    timezone?: string;
+}

package/dist/task/index.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 {};