@neta-art/cohub-protocol 1.0.0

package/README.md

@@ -0,0 +1,30 @@
+# @neta-art/cohub-protocol
+
+Shared protocol definitions for the Cohub agent collaboration platform.
+
+This package provides the stable type surface used across Cohub services and client SDKs — covering spaces, checkpoints, sessions, realtime events, gateway contracts, tasks, and filesystem operations.
+
+## Install
+
+```bash
+npm install @neta-art/cohub-protocol
+```
+
+## Subpath exports
+
+| Subpath | Contents |
+|---|---|
+| `@neta-art/cohub-protocol/core` | Low-level primitives — content blocks, usage, shared types |
+| `@neta-art/cohub-protocol/model` | Business records and input models — sessions, spaces, checkpoints |
+| `@neta-art/cohub-protocol/realtime` | WebSocket and streaming event protocol definitions |
+| `@neta-art/cohub-protocol/gateway` | Stable gateway contracts for external channels |
+| `@neta-art/cohub-protocol/task` | Task scheduler and worker contracts |
+| `@neta-art/cohub-protocol/fs` | Space filesystem DTOs |
+
+## Usage
+
+```ts
+import { type ContentBlock } from "@neta-art/cohub-protocol/core";
+import { type SessionInput } from "@neta-art/cohub-protocol/model";
+import { type RealtimeEvent } from "@neta-art/cohub-protocol/realtime";
+```

package/dist/core/content.d.ts

@@ -0,0 +1,39 @@
+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;
+};

package/dist/core/content.js

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

package/dist/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./content.js";
+export * from "./usage.js";

package/dist/core/index.js

@@ -0,0 +1,2 @@
+export * from "./content.js";
+export * from "./usage.js";

package/dist/core/usage.d.ts

@@ -0,0 +1,14 @@
+export type Usage = {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    cost?: {
+        input?: number;
+        output?: number;
+        cacheRead?: number;
+        cacheWrite?: number;
+        total?: number;
+    } | null;
+};

package/dist/core/usage.js

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

package/dist/fs/index.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/fs/index.js

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

package/dist/gateway/index.d.ts

@@ -0,0 +1,114 @@
+import type { ContentBlock } from "../core/content.js";
+import type { MessageRecord } from "../model/session.js";
+export type ChannelProvider = "web" | "websocket" | "discord" | "feishu" | "telegram" | "slack";
+export interface DiscordChannelConfig {
+    inbound?: {
+        requireMentionInGuild?: boolean;
+    };
+    outbound?: {
+        showThinking?: boolean;
+        showToolCalls?: boolean;
+    };
+}
+export interface FeishuChannelConfig {
+    brand?: "feishu" | "lark";
+    inbound?: {
+        requireMentionInGroup?: boolean;
+    };
+    outbound?: {
+        renderMode?: "card" | "post";
+        showThinking?: boolean;
+        showToolCalls?: boolean;
+    };
+}
+export type ChannelConfig = DiscordChannelConfig | FeishuChannelConfig | Record<string, unknown>;
+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: 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: ContentBlock[];
+}
+export interface GatewaySessionTurnFinalOutput extends GatewaySessionOutputBase {
+    type: "session.turn.final";
+    sessionMessageId: string | null;
+    anchorUserMessageId: string | null;
+    content: 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: MessageRecord;
+}
+export type GatewaySessionOutput = GatewaySessionTurnProgressOutput | GatewaySessionTurnFinalOutput | GatewaySessionTurnErrorOutput | GatewaySessionMessagePersistedOutput;
+export interface GatewayOutboundCommand {
+    commandId: string;
+    timestamp: number;
+    channelId: string;
+    provider: ChannelProvider;
+    externalChatId: string;
+    content: ContentBlock[];
+    replyToExternalMessageId?: string;
+    spaceId?: string;
+    spaceSessionId?: string;
+    sessionMessageId?: string;
+    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/index.js

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

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

@@ -0,0 +1,8 @@
+export * from "./core/content.js";
+export * from "./core/usage.js";
+export * from "./model/session.js";
+export * from "./realtime/stream.js";
+export * from "./realtime/websocket.js";
+export * from "./gateway/index.js";
+export * from "./task/index.js";
+export * from "./fs/index.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export * from "./core/content.js";
+export * from "./core/usage.js";
+export * from "./model/session.js";
+export * from "./realtime/stream.js";
+export * from "./realtime/websocket.js";
+export * from "./gateway/index.js";
+export * from "./task/index.js";
+export * from "./fs/index.js";

package/dist/model/session.d.ts

@@ -0,0 +1,98 @@
+import type { ContentBlock } from "../core/content.js";
+import type { Usage } from "../core/usage.js";
+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?: Usage | null;
+    };
+};
+export type UpdateSessionInfoInput = {
+    spaceId: string;
+    sessionId: string;
+    title?: string | null;
+    updatedAt?: string | null;
+    meta?: Record<string, unknown> | null;
+};
+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;
+    usage: Usage | null;
+    meta: Record<string, unknown> | null;
+    createdAt: string;
+};

package/dist/model/session.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/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./stream.js";
+export * from "./websocket.js";

package/dist/realtime/index.js

@@ -0,0 +1,2 @@
+export * from "./stream.js";
+export * from "./websocket.js";

package/dist/realtime/stream.d.ts

@@ -0,0 +1,17 @@
+import type { ContentBlock } from "../core/content.js";
+export type SessionStreamEvent = {
+    type: "stream_update";
+    spaceId: string;
+    sessionId: string;
+    content: ContentBlock[];
+    sourceMessageId: string | null;
+    timestamp: number;
+    turnEnd?: boolean;
+    anchorUserMessageId?: string | null;
+};
+export type SessionStreamError = {
+    type: "error";
+    spaceId: string;
+    sessionId: string | null;
+    error: string;
+};

package/dist/realtime/stream.js

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