@neta-art/cohub 1.6.0 → 1.7.1

package/README.md

@@ -120,6 +120,27 @@ space.on("message.persisted", (event) => {
 });
 ```
 
+For product UIs, prefer the normalized generation stream. It folds
+`session.turn.snapshot`, `session.turn.patch`, legacy `session.turn.progress`,
+persisted assistant messages, finalized turns, and turn errors into stable
+semantic events.
+
+```ts
+const stop = session.subscribeGeneration({
+  state(event) {
+    console.log(event.source, event.state.contentBlocks);
+  },
+  commit(event) {
+    if (event.commit.kind === "final") {
+      console.log("assistant final", event.commit.message);
+    }
+  },
+  outOfSync() {
+    // Fetch `session.turns.streamSnapshot()` or reconcile persisted turns.
+  },
+});
+```
+
 Supported business event names:
 
 - `turn.patch`

package/dist/apis/prompts.d.ts

@@ -1,9 +1,8 @@
-import type { Fetch } from "../transport.js";
+import type { HttpTransport, Fetch } from "../transport.js";
 import type { PromptTemplateCatalogResponse } from "../types.js";
 export declare class PromptsApi {
-    private readonly fetcher;
-    private readonly baseUrl;
-    constructor(fetcher: Fetch, baseUrl: string);
+    private readonly transport;
+    constructor(transport: HttpTransport);
     list(options?: {
         spaceId?: string;
     }, customFetch?: Fetch): Promise<PromptTemplateCatalogResponse>;

package/dist/apis/prompts.js

@@ -1,22 +1,16 @@
 export class PromptsApi {
-    fetcher;
-    baseUrl;
-    constructor(fetcher, baseUrl) {
-        this.fetcher = fetcher;
-        this.baseUrl = baseUrl;
+    transport;
+    constructor(transport) {
+        this.transport = transport;
     }
     async list(options, customFetch) {
-        const fetchImpl = customFetch ?? this.fetcher;
         const params = new URLSearchParams();
         if (options?.spaceId)
             params.set("spaceId", options.spaceId);
         const query = params.toString();
-        const base = this.baseUrl ? `${this.baseUrl}/api/prompts` : "/api/prompts";
-        const url = query ? `${base}?${query}` : base;
-        const response = await fetchImpl(url);
-        if (!response.ok) {
-            throw new Error(`Failed to fetch prompt templates: ${response.status} ${response.statusText}`);
-        }
-        return response.json();
+        const path = query ? `/api/prompts?${query}` : "/api/prompts";
+        return this.transport.request(path, {
+            fetch: customFetch,
+        });
     }
 }

package/dist/apis/search.d.ts

@@ -0,0 +1,10 @@
+import type { Fetch, HttpTransport } from "../transport.js";
+import type { GlobalSearchResponse } from "../types.js";
+export declare class SearchApi {
+    private readonly transport;
+    constructor(transport: HttpTransport);
+    query(input: {
+        q: string;
+        limit?: number;
+    }, customFetch?: Fetch): Promise<GlobalSearchResponse>;
+}

package/dist/apis/search.js

@@ -0,0 +1,14 @@
+export class SearchApi {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    query(input, customFetch) {
+        const params = new URLSearchParams({ q: input.q });
+        if (input.limit !== undefined)
+            params.set("limit", String(input.limit));
+        return this.transport.request(`/api/search?${params.toString()}`, {
+            fetch: customFetch,
+        });
+    }
+}

package/dist/apis/spaces.d.ts

@@ -2,13 +2,21 @@ import type { SpacePublicEndpoints } from "@neta-art/cohub-protocol/ports";
 import type { WebsocketClient, WebsocketEventPayload } from "../websocket.js";
 import type { HttpTransport, Fetch } from "../transport.js";
 import { type SessionPatchApplyResult } from "../session-patch-reducer.js";
-import type { CheckpointRecord, ContentBlock, SessionMessageResponse, SessionMessagesPaginatedResponse, SessionMessagesResponse, SessionTurnResponse, SessionTurnStreamSnapshotResponse, SessionTurnIndexResponse, SessionTurnWindowResponse, SessionTurnsPaginatedResponse, SessionTurnSignedUrlsResponse, SessionRecord, SpaceAccessPolicy, SpaceBootstrapSource, SpaceChannelBindingInput, SpaceCheckpointDetailResponse, SpaceCreateResponse, CreateSpacePromptInput, CreateSpacePromptResponse, SpaceEnvInput, SpaceFsCompleteUploadInput, SpaceFsCompleteUploadResponse, SpaceFsCreateUploadInput, SpaceFsCreateUploadResponse, SpaceFsFileResponse, SpaceFsMoveInput, SpaceFsTreeResponse, SpaceFsUploadResponse, SpaceUsageResponse, SpaceFsWriteFileInput, SpaceMarkKind, SpaceMarkListItem, SpaceMarkResourceType, SpaceMember, SpaceRecord, SpaceRole, SpaceSessionsResponse } from "../types.js";
+import { SessionGenerationStreamClient, type GenerationStreamSubscriptionHandlers } from "../session-generation-stream.js";
+import type { CheckpointRecord, ContentBlock, SessionForkRecord, SessionMessageResponse, SessionMessagesPaginatedResponse, SessionMessagesResponse, SessionTurnResponse, SessionTurnStreamSnapshotResponse, SessionTurnIndexResponse, SessionTurnWindowResponse, SessionTurnsPaginatedResponse, SessionTurnSignedUrlsResponse, SessionRecord, SpaceAccessPolicy, SpaceBootstrapSource, SpaceChannelBindingInput, SpaceCheckpointDetailResponse, SpaceCreateResponse, CreateSpacePromptInput, CreateSpacePromptResponse, SpaceEnvInput, SpaceFsCompleteUploadInput, SpaceFsCompleteUploadResponse, SpaceFsCreateUploadInput, SpaceFsCreateUploadResponse, SpaceFsFileResponse, SpaceFsMoveInput, SpaceFsTreeResponse, SpaceFsUploadResponse, SpaceUsageResponse, SpaceFsWriteFileInput, SpaceMarkKind, SpaceMarkListItem, SpaceMarkResourceType, SpaceMember, SpaceRecord, SpaceRole, SpaceSessionsResponse } from "../types.js";
 import { SpaceInvitationsApi } from "./invitations.js";
 export type SessionSubscriptionHandlers = {
     patch?: (event: WebsocketEventPayload) => void;
+    /**
+     * @deprecated Use `session.subscribeGeneration({ state })` for normalized
+     * snapshot/patch/progress generation state.
+     */
     patchState?: (result: SessionPatchApplyResult) => void;
+    /** @deprecated Use `session.subscribeGeneration({ state })`. */
     snapshot?: (event: WebsocketEventPayload) => void;
+    /** @deprecated Legacy progress events are normalized by `subscribeGeneration`. */
     progress?: (event: WebsocketEventPayload) => void;
+    /** @deprecated Use `session.subscribeGeneration({ commit, finalized })`. */
     final?: (event: WebsocketEventPayload) => void;
     turnUpdated?: (event: WebsocketEventPayload) => void;
     turnFinalized?: (event: WebsocketEventPayload) => void;
@@ -140,6 +148,7 @@ export declare class SessionClient {
     readonly messages: SessionMessagesClient;
     readonly turns: SessionTurnsClient;
     readonly realtime: SessionRealtimeClient;
+    readonly generation: SessionGenerationStreamClient;
     constructor(spaceId: string, id: string, transport: HttpTransport, websocketClient: WebsocketClient | null);
     get(customFetch?: Fetch): Promise<{
         space: SpaceRecord;
@@ -153,7 +162,16 @@ export declare class SessionClient {
     } | Fetch, customFetch?: Fetch): Promise<{
         ok: true;
     }>;
+    turn(turnId: string): {
+        fork: (input?: {
+            title?: string | null;
+        }) => Promise<{
+            session: SessionRecord;
+            fork: SessionForkRecord;
+        }>;
+    };
     subscribe(handlers: SessionSubscriptionHandlers): () => void;
+    subscribeGeneration(handlers: GenerationStreamSubscriptionHandlers): () => void;
     on(type: SessionEventName, handler: (event: WebsocketEventPayload) => void): () => void;
 }
 export declare class SpaceSessionsApi {

package/dist/apis/spaces.js

@@ -1,5 +1,6 @@
 import { ensureRealtimeConnected } from "../realtime.js";
 import { SessionPatchReducer, } from "../session-patch-reducer.js";
+import { SessionGenerationStreamClient, } from "../session-generation-stream.js";
 import { SpaceInvitationsApi } from "./invitations.js";
 const DEFAULT_DEDUP_WINDOW_MS = 2000;
 const getFilenameFromContentDisposition = (value) => {
@@ -405,6 +406,7 @@ export class SessionClient {
     messages;
     turns;
     realtime;
+    generation;
     constructor(spaceId, id, transport, websocketClient) {
         this.spaceId = spaceId;
         this.id = id;
@@ -412,6 +414,7 @@ export class SessionClient {
         this.messages = new SessionMessagesClient(transport, id);
         this.turns = new SessionTurnsClient(transport, id);
         this.realtime = new SessionRealtimeClient(websocketClient, spaceId, id);
+        this.generation = new SessionGenerationStreamClient(websocketClient, spaceId, id);
     }
     get(customFetch) {
         return this.transport.request(`/api/sessions/${this.id}`, {
@@ -435,9 +438,21 @@ export class SessionClient {
             fetch,
         });
     }
+    turn(turnId) {
+        return {
+            fork: (input = {}) => this.transport.request(`/api/sessions/${this.id}/turns/${turnId}/fork`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(input),
+            }),
+        };
+    }
     subscribe(handlers) {
         return this.realtime.subscribe(handlers);
     }
+    subscribeGeneration(handlers) {
+        return this.generation.subscribe(handlers);
+    }
     on(type, handler) {
         return this.realtime.on(type, handler);
     }

package/dist/client.d.ts

@@ -4,6 +4,7 @@ import { ExploreApi } from "./apis/explore.js";
 import { ModelsApi } from "./apis/models.js";
 import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
+import { SearchApi } from "./apis/search.js";
 import { SpaceClient, SpacesApi, type WebSocketConnectionState } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
@@ -16,6 +17,7 @@ export declare class CohubClient {
     readonly models: ModelsApi;
     readonly prompts: PromptsApi;
     readonly sessionAccess: SessionAccessApi;
+    readonly search: SearchApi;
     readonly tasks: TasksApi;
     readonly cronJobs: CronJobsApi;
     readonly explore: ExploreApi;

package/dist/client.js

@@ -4,6 +4,7 @@ import { ExploreApi } from "./apis/explore.js";
 import { ModelsApi } from "./apis/models.js";
 import { PromptsApi } from "./apis/prompts.js";
 import { SessionAccessApi } from "./apis/session-access.js";
+import { SearchApi } from "./apis/search.js";
 import { SpaceClient, SpacesApi } from "./apis/spaces.js";
 import { TasksApi } from "./apis/tasks.js";
 import { UserApi } from "./apis/user.js";
@@ -18,6 +19,7 @@ export class CohubClient {
     models;
     prompts;
     sessionAccess;
+    search;
     tasks;
     cronJobs;
     explore;
@@ -39,8 +41,9 @@ export class CohubClient {
         this.channels = new ChannelsApi(this.transport);
         this.user = new UserApi(this.transport, apiBaseUrl, options.setStoredAuthToken, options.clearStoredAuthToken);
         this.models = new ModelsApi(this.transport);
-        this.prompts = new PromptsApi(options.fetch ?? fetch, apiBaseUrl);
+        this.prompts = new PromptsApi(this.transport);
         this.sessionAccess = new SessionAccessApi(this.transport);
+        this.search = new SearchApi(this.transport);
         this.tasks = new TasksApi(this.transport);
         this.cronJobs = new CronJobsApi(this.transport);
         this.explore = new ExploreApi(this.transport);

package/dist/http.js

@@ -27,7 +27,7 @@ export class CohubHttpClient {
         this.channels = new ChannelsApi(this.transport);
         this.user = new UserApi(this.transport, apiBaseUrl, options.setStoredAuthToken, options.clearStoredAuthToken);
         this.models = new ModelsApi(this.transport);
-        this.prompts = new PromptsApi(options.fetch ?? fetch, apiBaseUrl);
+        this.prompts = new PromptsApi(this.transport);
         this.sessionAccess = new SessionAccessApi(this.transport);
         this.tasks = new TasksApi(this.transport);
         this.cronJobs = new CronJobsApi(this.transport);

package/dist/index.d.ts

@@ -2,11 +2,13 @@ export { CohubHttpClient, createHttpClient } from "./http.js";
 export { CohubClient, createCohubClient } from "./client.js";
 export { WebsocketClient, createWebsocketClient } from "./websocket.js";
 export { SessionPatchReducer, createSessionPatchReducer } from "./session-patch-reducer.js";
+export { SessionGenerationStreamClient, createSessionGenerationStreamClient, parseAssistantMessageCommit, } from "./session-generation-stream.js";
 export { HttpError } from "./transport.js";
 export type { RawHttpResponse } from "./transport.js";
 export { COHUB_ENVIRONMENTS, normalizeBaseUrl, normalizeWebsocketUrl, resolveApiBaseUrl, resolveCohubEnvironment, resolveWebsocketUrl, } from "./environment.js";
 export type { CohubClientOptions, Fetch } from "./transport.js";
 export type { CohubEnvironment } from "./environment.js";
 export type { SessionPatchApplyInput, SessionPatchApplyResult, SessionPatchState, SessionPatchStatus, } from "./session-patch-reducer.js";
+export type { AssistantMessageCommit, GenerationStreamCommitEvent, GenerationStreamErrorEvent, GenerationStreamEvent, GenerationStreamFinalizedEvent, GenerationStreamIntermediateMessage, GenerationStreamOutOfSyncEvent, GenerationStreamStateEvent, GenerationStreamSubscriptionHandlers, GenerationStreamTurnUpdatedEvent, } from "./session-generation-stream.js";
 export * from "./types.js";
 export type { SessionEventName, SessionSubscriptionHandlers, SpaceChannelBindingRecord, SpaceEventName, WebSocketConnectionState } from "./apis/spaces.js";

package/dist/index.js

@@ -2,6 +2,7 @@ export { CohubHttpClient, createHttpClient } from "./http.js";
 export { CohubClient, createCohubClient } from "./client.js";
 export { WebsocketClient, createWebsocketClient } from "./websocket.js";
 export { SessionPatchReducer, createSessionPatchReducer } from "./session-patch-reducer.js";
+export { SessionGenerationStreamClient, createSessionGenerationStreamClient, parseAssistantMessageCommit, } from "./session-generation-stream.js";
 export { HttpError } from "./transport.js";
 export { COHUB_ENVIRONMENTS, normalizeBaseUrl, normalizeWebsocketUrl, resolveApiBaseUrl, resolveCohubEnvironment, resolveWebsocketUrl, } from "./environment.js";
 export * from "./types.js";

package/dist/session-generation-stream.d.ts

@@ -0,0 +1,114 @@
+import type { ContentBlock, Usage } from "@neta-art/cohub-protocol/core";
+import type { MessageRecord, SessionTurnRecord } from "@neta-art/cohub-protocol/model";
+import { type SessionPatchState } from "./session-patch-reducer.js";
+import type { WebsocketClient, WebsocketEventPayload } from "./websocket.js";
+export type AssistantMessageCommit = {
+    kind: "intermediate";
+    message: MessageRecord;
+    isFinal: false;
+} | {
+    kind: "final";
+    message: MessageRecord;
+    isFinal: true;
+} | {
+    kind: "error";
+    message: MessageRecord;
+    isFinal: true;
+} | {
+    kind: "ignored";
+    message: MessageRecord;
+    isFinal: false;
+};
+export type GenerationStreamIntermediateMessage = {
+    id?: string;
+    sessionId?: string;
+    role?: "user" | "assistant" | "system";
+    messageId: string | null;
+    messageOrdinal: number | null;
+    content: ContentBlock[];
+    text?: string | null;
+    provider?: string | null;
+    model?: string | null;
+    stopReason?: string | null;
+    errorMessage?: string | null;
+    usage?: Usage | null;
+    toolCallsObjectKey?: string | null;
+    meta?: Record<string, unknown> | null;
+    createdAt?: string;
+};
+export type GenerationStreamStateEvent = {
+    type: "state";
+    source: "snapshot" | "patch" | "progress";
+    state: SessionPatchState;
+    messageId: string | null;
+    messageOrdinal: number | null;
+    intermediateMessages: GenerationStreamIntermediateMessage[];
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamCommitEvent = {
+    type: "commit";
+    commit: AssistantMessageCommit;
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamFinalizedEvent = {
+    type: "finalized";
+    turn: SessionTurnRecord;
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamTurnUpdatedEvent = {
+    type: "turn_updated";
+    turn: Partial<SessionTurnRecord>;
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamErrorEvent = {
+    type: "error";
+    message: string;
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamOutOfSyncEvent = {
+    type: "out_of_sync";
+    source: "snapshot" | "patch";
+    reason: "duplicate" | "version_mismatch" | "invalid";
+    state: SessionPatchState;
+    rawEvent: WebsocketEventPayload;
+};
+export type GenerationStreamEvent = GenerationStreamStateEvent | GenerationStreamCommitEvent | GenerationStreamFinalizedEvent | GenerationStreamTurnUpdatedEvent | GenerationStreamErrorEvent | GenerationStreamOutOfSyncEvent;
+export type GenerationStreamSubscriptionHandlers = {
+    event?: (event: GenerationStreamEvent) => void;
+    state?: (event: GenerationStreamStateEvent) => void;
+    commit?: (event: GenerationStreamCommitEvent) => void;
+    finalized?: (event: GenerationStreamFinalizedEvent) => void;
+    turnUpdated?: (event: GenerationStreamTurnUpdatedEvent) => void;
+    error?: (event: GenerationStreamErrorEvent) => void;
+    outOfSync?: (event: GenerationStreamOutOfSyncEvent) => void;
+};
+export declare function parseAssistantMessageCommit(message: MessageRecord): AssistantMessageCommit;
+export declare class SessionGenerationStreamClient {
+    private readonly websocketClient;
+    private readonly spaceId;
+    private readonly sessionId;
+    private readonly reducer;
+    private messageId;
+    private messageOrdinal;
+    private intermediateMessages;
+    private progressState;
+    constructor(websocketClient: WebsocketClient | null, spaceId: string, sessionId: string);
+    subscribe(handlers: GenerationStreamSubscriptionHandlers): () => void;
+    private emit;
+    private resetCurrentMessage;
+    private appendCurrentMessage;
+    private addIntermediateMessage;
+    private handleAppliedState;
+    private prepareMessageBoundary;
+    private handleSnapshot;
+    private handlePatch;
+    private handleProgress;
+    private handlePersisted;
+    private handleFinalized;
+    private handleEvent;
+}
+export declare function createSessionGenerationStreamClient(input: {
+    websocketClient: WebsocketClient | null;
+    spaceId: string;
+    sessionId: string;
+}): SessionGenerationStreamClient;

package/dist/session-generation-stream.js

@@ -0,0 +1,514 @@
+import { ensureRealtimeConnected } from "./realtime.js";
+import { SessionPatchReducer, } from "./session-patch-reducer.js";
+const isRecord = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const isContentBlockArray = (value) => Array.isArray(value) &&
+    value.every((item) => isRecord(item) && typeof item.type === "string");
+const stringField = (record, key) => {
+    const value = record[key];
+    return typeof value === "string" ? value : null;
+};
+const numberField = (record, key) => {
+    const value = record[key];
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+};
+const getMessageKind = (message) => {
+    const kind = message.meta?.messageKind;
+    return typeof kind === "string" ? kind : null;
+};
+export function parseAssistantMessageCommit(message) {
+    if (message.role !== "assistant") {
+        return { kind: "ignored", message, isFinal: false };
+    }
+    const kind = getMessageKind(message);
+    if (kind === "assistant_intermediate") {
+        return { kind: "intermediate", message, isFinal: false };
+    }
+    if (kind === "assistant_final") {
+        return { kind: "final", message, isFinal: true };
+    }
+    if (kind === "assistant_error") {
+        return { kind: "error", message, isFinal: true };
+    }
+    return { kind: "ignored", message, isFinal: false };
+}
+function cloneContentBlock(block) {
+    return structuredClone(block);
+}
+function getStreamIndex(block) {
+    const value = block._meta?.streamIndex;
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function findMergeTargetIndex(result, block) {
+    const streamIndex = getStreamIndex(block);
+    if (streamIndex != null) {
+        return result.findIndex((existing) => existing.type === block.type && getStreamIndex(existing) === streamIndex);
+    }
+    if (block.type === "tool_use") {
+        return result.findIndex((existing) => existing.type === "tool_use" && existing.id === block.id);
+    }
+    if (block.type === "tool_result") {
+        return result.findIndex((existing) => existing.type === "tool_result" &&
+            existing.tool_use_id === block.tool_use_id);
+    }
+    return -1;
+}
+function mergeStreamingDeltaBlocks(existing, delta) {
+    if (delta.length === 0)
+        return existing;
+    const result = existing.map(cloneContentBlock);
+    for (const block of delta) {
+        const targetIndex = findMergeTargetIndex(result, block);
+        if (targetIndex === -1) {
+            result.push(cloneContentBlock(block));
+            continue;
+        }
+        const target = result[targetIndex];
+        if (block.type === "text" && target?.type === "text") {
+            target.text += block.text;
+            continue;
+        }
+        if (block.type === "thinking" && target?.type === "thinking") {
+            target.thinking += block.thinking;
+            if (block.signature)
+                target.signature = block.signature;
+            if (block._meta)
+                target._meta = { ...(target._meta ?? {}), ...block._meta };
+            continue;
+        }
+        result[targetIndex] = Object.assign(target ?? {}, cloneContentBlock(block));
+    }
+    return result;
+}
+function parseSnapshotMessage(value) {
+    if (!isRecord(value) || !isContentBlockArray(value.content))
+        return null;
+    return {
+        messageId: stringField(value, "messageId"),
+        messageOrdinal: numberField(value, "messageOrdinal"),
+        content: value.content,
+        ...(typeof value.id === "string" ? { id: value.id } : {}),
+        ...(typeof value.sessionId === "string" ? { sessionId: value.sessionId } : {}),
+        ...(value.role === "user" ||
+            value.role === "assistant" ||
+            value.role === "system"
+            ? { role: value.role }
+            : {}),
+        ...(typeof value.text === "string" ? { text: value.text } : {}),
+        ...(typeof value.provider === "string" ? { provider: value.provider } : {}),
+        ...(typeof value.model === "string" ? { model: value.model } : {}),
+        ...(typeof value.stopReason === "string"
+            ? { stopReason: value.stopReason }
+            : {}),
+        ...(typeof value.errorMessage === "string"
+            ? { errorMessage: value.errorMessage }
+            : {}),
+        ...(isRecord(value.usage) ? { usage: value.usage } : {}),
+        ...(typeof value.toolCallsObjectKey === "string"
+            ? { toolCallsObjectKey: value.toolCallsObjectKey }
+            : {}),
+        ...(isRecord(value.meta) ? { meta: value.meta } : {}),
+        ...(typeof value.createdAt === "string" ? { createdAt: value.createdAt } : {}),
+    };
+}
+function messageRecordToIntermediate(message) {
+    if (!isContentBlockArray(message.content) || message.content.length === 0) {
+        return null;
+    }
+    const meta = isRecord(message.meta) ? message.meta : {};
+    return {
+        id: message.id,
+        sessionId: message.sessionId,
+        role: message.role,
+        messageId: typeof meta.streamMessageId === "string"
+            ? meta.streamMessageId
+            : message.id ?? null,
+        messageOrdinal: typeof meta.messageOrdinal === "number" ? meta.messageOrdinal : null,
+        content: message.content,
+        text: message.text,
+        provider: message.provider,
+        model: message.model,
+        stopReason: message.stopReason,
+        errorMessage: message.errorMessage,
+        usage: message.usage,
+        meta: message.meta,
+        createdAt: message.createdAt,
+    };
+}
+function resolveStreamMessageId(input) {
+    if (input.messageId?.trim())
+        return input.messageId.trim();
+    if (input.messageOrdinal == null)
+        return null;
+    if (input.turnId?.trim()) {
+        return `turn:${input.turnId.trim()}:assistant:${input.messageOrdinal}`;
+    }
+    return `session:${input.sessionId}:assistant:${input.messageOrdinal}:${input.anchorUserMessageId ?? "unknown"}`;
+}
+function getTurnIdFromMessage(message) {
+    const turnId = message.meta?.turnId;
+    return typeof turnId === "string" ? turnId : null;
+}
+export class SessionGenerationStreamClient {
+    websocketClient;
+    spaceId;
+    sessionId;
+    reducer = new SessionPatchReducer();
+    messageId = null;
+    messageOrdinal = null;
+    intermediateMessages = [];
+    progressState = null;
+    constructor(websocketClient, spaceId, sessionId) {
+        this.websocketClient = websocketClient;
+        this.spaceId = spaceId;
+        this.sessionId = sessionId;
+    }
+    subscribe(handlers) {
+        if (!this.websocketClient) {
+            throw new Error("realtime transport is not configured for this client");
+        }
+        ensureRealtimeConnected(this.websocketClient);
+        const stream = new SessionGenerationStreamClient(this.websocketClient, this.spaceId, this.sessionId);
+        const unsubscribe = this.websocketClient.on("event", (event) => {
+            if (event.spaceId !== this.spaceId || event.sessionId !== this.sessionId) {
+                return;
+            }
+            stream.handleEvent(event, handlers);
+        });
+        return () => unsubscribe();
+    }
+    emit(handlers, event) {
+        handlers.event?.(event);
+        if (event.type === "state")
+            handlers.state?.(event);
+        if (event.type === "commit")
+            handlers.commit?.(event);
+        if (event.type === "finalized")
+            handlers.finalized?.(event);
+        if (event.type === "turn_updated")
+            handlers.turnUpdated?.(event);
+        if (event.type === "error")
+            handlers.error?.(event);
+        if (event.type === "out_of_sync")
+            handlers.outOfSync?.(event);
+    }
+    resetCurrentMessage() {
+        this.messageId = null;
+        this.messageOrdinal = null;
+        this.progressState = null;
+    }
+    appendCurrentMessage(state) {
+        if (state.contentBlocks.length === 0)
+            return;
+        this.addIntermediateMessage({
+            messageId: this.messageId,
+            messageOrdinal: this.messageOrdinal,
+            content: state.contentBlocks,
+        });
+    }
+    addIntermediateMessage(message) {
+        const index = this.intermediateMessages.findIndex((existing) => {
+            if (message.messageId && existing.messageId) {
+                return existing.messageId === message.messageId;
+            }
+            return (message.messageOrdinal !== null &&
+                existing.messageOrdinal === message.messageOrdinal);
+        });
+        if (index < 0) {
+            this.intermediateMessages = [...this.intermediateMessages, message];
+            return;
+        }
+        this.intermediateMessages = this.intermediateMessages.map((existing, i) => i === index ? { ...existing, ...message } : existing);
+    }
+    handleAppliedState(handlers, source, result, rawEvent, messageId, messageOrdinal) {
+        if (!result.applied) {
+            this.emit(handlers, {
+                type: "out_of_sync",
+                source: source === "progress" ? "patch" : source,
+                reason: result.reason,
+                state: result.state,
+                rawEvent,
+            });
+            return;
+        }
+        this.progressState = result.state;
+        this.messageId = messageId;
+        this.messageOrdinal = messageOrdinal;
+        this.emit(handlers, {
+            type: "state",
+            source,
+            state: result.state,
+            messageId,
+            messageOrdinal,
+            intermediateMessages: [...this.intermediateMessages],
+            rawEvent,
+        });
+    }
+    prepareMessageBoundary(input) {
+        const current = this.progressState ??
+            this.reducer.get({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+            });
+        const nextMessageId = resolveStreamMessageId({
+            sessionId: this.sessionId,
+            turnId: input.turnId,
+            anchorUserMessageId: input.anchorUserMessageId,
+            messageId: input.messageId,
+            messageOrdinal: input.messageOrdinal,
+        });
+        const differentTurn = Boolean(current.turnId && input.turnId && current.turnId !== input.turnId);
+        const messageChanged = Boolean(nextMessageId &&
+            current.contentBlocks.length > 0 &&
+            this.messageId &&
+            nextMessageId !== this.messageId);
+        if (differentTurn) {
+            this.intermediateMessages = [];
+            this.resetCurrentMessage();
+            this.reducer.start({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: input.turnId,
+            });
+        }
+        else if (messageChanged) {
+            this.appendCurrentMessage(current);
+            this.resetCurrentMessage();
+            this.reducer.start({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: input.turnId ?? current.turnId,
+            });
+        }
+        return nextMessageId;
+    }
+    handleSnapshot(event, handlers) {
+        const payload = event.payload;
+        const current = isRecord(payload.current) ? payload.current : null;
+        const content = current ? current.content : null;
+        const seq = typeof payload.seq === "number" ? payload.seq : null;
+        if (!current || !isContentBlockArray(content) || seq === null) {
+            this.emit(handlers, {
+                type: "out_of_sync",
+                source: "snapshot",
+                reason: "invalid",
+                state: this.reducer.get({ spaceId: this.spaceId, sessionId: this.sessionId }),
+                rawEvent: event,
+            });
+            return;
+        }
+        const turnId = typeof payload.turnId === "string" ? payload.turnId : null;
+        const anchorUserMessageId = typeof payload.anchorUserMessageId === "string"
+            ? payload.anchorUserMessageId
+            : null;
+        const messageOrdinal = numberField(current, "messageOrdinal");
+        const messageId = this.prepareMessageBoundary({
+            turnId,
+            messageId: stringField(current, "messageId"),
+            messageOrdinal,
+            anchorUserMessageId,
+        });
+        this.intermediateMessages = Array.isArray(payload.intermediateMessages)
+            ? payload.intermediateMessages
+                .map(parseSnapshotMessage)
+                .filter((message) => message !== null)
+            : [];
+        const result = this.reducer.applySnapshot({
+            spaceId: this.spaceId,
+            sessionId: this.sessionId,
+            turnId,
+            seq,
+            contentBlocks: content,
+            anchorUserMessageId,
+            appendPath: stringField(current, "appendPath"),
+        });
+        this.handleAppliedState(handlers, "snapshot", result, event, messageId, messageOrdinal);
+    }
+    handlePatch(event, handlers) {
+        const payload = event.payload;
+        const seq = typeof payload.seq === "number" ? payload.seq : null;
+        const baseSeq = typeof payload.baseSeq === "number" ? payload.baseSeq : null;
+        if (seq === null || baseSeq === null || !Array.isArray(payload.ops)) {
+            this.emit(handlers, {
+                type: "out_of_sync",
+                source: "patch",
+                reason: "invalid",
+                state: this.reducer.get({ spaceId: this.spaceId, sessionId: this.sessionId }),
+                rawEvent: event,
+            });
+            return;
+        }
+        const turnId = typeof payload.turnId === "string" ? payload.turnId : null;
+        const anchorUserMessageId = typeof payload.anchorUserMessageId === "string"
+            ? payload.anchorUserMessageId
+            : null;
+        const messageOrdinal = typeof payload.messageOrdinal === "number" ? payload.messageOrdinal : null;
+        const messageId = this.prepareMessageBoundary({
+            turnId,
+            messageId: typeof payload.messageId === "string" ? payload.messageId : null,
+            messageOrdinal,
+            anchorUserMessageId,
+        });
+        const input = {
+            spaceId: this.spaceId,
+            sessionId: this.sessionId,
+            turnId,
+            seq,
+            baseSeq,
+            ops: payload.ops,
+            anchorUserMessageId,
+        };
+        const result = this.reducer.applyPatch(input);
+        this.handleAppliedState(handlers, "patch", result, event, messageId, messageOrdinal);
+    }
+    handleProgress(event, handlers) {
+        const payload = event.payload;
+        if (!isContentBlockArray(payload.content))
+            return;
+        const current = this.progressState ??
+            this.reducer.get({ spaceId: this.spaceId, sessionId: this.sessionId });
+        const turnId = typeof payload.turnId === "string" ? payload.turnId : current.turnId;
+        const anchorUserMessageId = typeof payload.anchorUserMessageId === "string"
+            ? payload.anchorUserMessageId
+            : current.anchorUserMessageId;
+        const messageOrdinal = typeof payload.messageOrdinal === "number"
+            ? payload.messageOrdinal
+            : this.messageOrdinal;
+        const messageId = this.prepareMessageBoundary({
+            turnId,
+            messageId: typeof payload.messageId === "string" ? payload.messageId : this.messageId,
+            messageOrdinal,
+            anchorUserMessageId,
+        });
+        const base = this.progressState?.turnId === turnId ? this.progressState : current;
+        const state = {
+            ...base,
+            spaceId: this.spaceId,
+            sessionId: this.sessionId,
+            status: "streaming",
+            contentBlocks: mergeStreamingDeltaBlocks(base.contentBlocks, payload.content),
+            anchorUserMessageId,
+            turnId,
+        };
+        this.progressState = state;
+        this.messageId = messageId;
+        this.messageOrdinal = messageOrdinal;
+        this.emit(handlers, {
+            type: "state",
+            source: "progress",
+            state,
+            messageId,
+            messageOrdinal,
+            intermediateMessages: [...this.intermediateMessages],
+            rawEvent: event,
+        });
+    }
+    handlePersisted(event, handlers) {
+        const message = event.payload.message;
+        if (!isRecord(message))
+            return;
+        const commit = parseAssistantMessageCommit(message);
+        if (commit.kind === "intermediate") {
+            const intermediate = messageRecordToIntermediate(commit.message);
+            if (intermediate) {
+                this.addIntermediateMessage(intermediate);
+            }
+            this.reducer.reset({ spaceId: this.spaceId, sessionId: this.sessionId });
+            this.resetCurrentMessage();
+        }
+        if (commit.kind === "final") {
+            this.reducer.complete({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: getTurnIdFromMessage(commit.message),
+            });
+            this.resetCurrentMessage();
+        }
+        if (commit.kind === "error") {
+            this.reducer.fail({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: getTurnIdFromMessage(commit.message),
+            });
+            this.resetCurrentMessage();
+        }
+        this.emit(handlers, {
+            type: "commit",
+            commit,
+            rawEvent: event,
+        });
+    }
+    handleFinalized(event, handlers) {
+        const turn = event.payload.turn;
+        if (!isRecord(turn))
+            return;
+        const typedTurn = turn;
+        if (typedTurn.status === "interrupted") {
+            this.reducer.interrupt({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: typedTurn.id,
+            });
+        }
+        else {
+            this.reducer.complete({
+                spaceId: this.spaceId,
+                sessionId: this.sessionId,
+                turnId: typedTurn.id,
+            });
+        }
+        this.resetCurrentMessage();
+        this.emit(handlers, {
+            type: "finalized",
+            turn: typedTurn,
+            rawEvent: event,
+        });
+    }
+    handleEvent(event, handlers) {
+        switch (event.type) {
+            case "session.turn.snapshot":
+                this.handleSnapshot(event, handlers);
+                return;
+            case "session.turn.patch":
+                this.handlePatch(event, handlers);
+                return;
+            case "session.turn.progress":
+                this.handleProgress(event, handlers);
+                return;
+            case "session.message.persisted":
+                this.handlePersisted(event, handlers);
+                return;
+            case "session.turn.finalized":
+                this.handleFinalized(event, handlers);
+                return;
+            case "session.turn.updated": {
+                const turn = event.payload.turn;
+                if (!isRecord(turn))
+                    return;
+                this.emit(handlers, {
+                    type: "turn_updated",
+                    turn: turn,
+                    rawEvent: event,
+                });
+                return;
+            }
+            case "session.turn.error": {
+                const message = typeof event.payload.error === "string" && event.payload.error.trim()
+                    ? event.payload.error.trim()
+                    : "Generation failed";
+                this.reducer.fail({ spaceId: this.spaceId, sessionId: this.sessionId });
+                this.resetCurrentMessage();
+                this.emit(handlers, {
+                    type: "error",
+                    message,
+                    rawEvent: event,
+                });
+                return;
+            }
+            default:
+                return;
+        }
+    }
+}
+export function createSessionGenerationStreamClient(input) {
+    return new SessionGenerationStreamClient(input.websocketClient, input.spaceId, input.sessionId);
+}

package/dist/session-patch-reducer.js

@@ -20,9 +20,27 @@ function getStreamIndex(block) {
     const value = block._meta?.streamIndex;
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
+function blockIdentityCompatible(prev, next) {
+    if (prev.type !== next.type)
+        return false;
+    if (prev.type === "tool_use" && next.type === "tool_use")
+        return prev.id === next.id && prev.name === next.name;
+    if (prev.type === "tool_result" && next.type === "tool_result")
+        return prev.tool_use_id === next.tool_use_id;
+    return true;
+}
 function findBlockByStreamIndex(blocks, streamIndex) {
     return blocks.findIndex((block) => getStreamIndex(block) === streamIndex);
 }
+function findBlockForReplacement(blocks, streamIndex, nextBlock) {
+    const compatibleIndex = blocks.findIndex((block) => getStreamIndex(block) === streamIndex && blockIdentityCompatible(block, nextBlock));
+    if (compatibleIndex >= 0)
+        return compatibleIndex;
+    const sameStreamIndex = blocks.findIndex((block) => getStreamIndex(block) === streamIndex);
+    if (sameStreamIndex >= 0 && nextBlock.type !== "tool_use" && nextBlock.type !== "tool_result")
+        return sameStreamIndex;
+    return -1;
+}
 function sortBlocksByStreamIndex(blocks) {
     return [...blocks].sort((a, b) => {
         const aIndex = getStreamIndex(a);
@@ -227,7 +245,7 @@ function applyPatchOpsToBlocks(current, ops, initialAppendPath) {
             const streamIndex = Number(match[1]);
             const block = cloneBlock(op.v);
             block._meta = { ...(block._meta ?? {}), streamIndex };
-            const blockIndex = findBlockByStreamIndex(next, streamIndex);
+            const blockIndex = findBlockForReplacement(next, streamIndex, block);
             if (blockIndex >= 0) {
                 next[blockIndex] = block;
             }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { SessionBindingRecord as ProtocolSessionBindingRecord, SessionRecord as ProtocolSessionRecord, SessionTurnIndexItem, SessionTurnRecord } from "@neta-art/cohub-protocol/model";
+import type { SessionBindingRecord as ProtocolSessionBindingRecord, SessionRecord as ProtocolSessionRecord, SessionForkRecord, SessionTurnIndexItem, SessionTurnRecord, SessionTurnSegmentRecord } from "@neta-art/cohub-protocol/model";
 import type { ChannelConfig } from "@neta-art/cohub-protocol/gateway";
 import type { ContentBlock, Usage } from "@neta-art/cohub-protocol/core";
 import type { MessageRecord } from "@neta-art/cohub-protocol/model";
@@ -24,7 +24,7 @@ export type UserRulesResponse = {
     source: "config-space";
     path: string;
 };
-export type { ContentBlock, MessageRecord, SessionTurnRecord, SessionTurnIndexItem };
+export type { ContentBlock, MessageRecord, SessionTurnRecord, SessionTurnIndexItem, SessionForkRecord, SessionTurnSegmentRecord };
 export type SpaceFsEntry = {
     name: string;
     path: string;
@@ -279,6 +279,32 @@ export type SpaceChannelBindingInput = {
     channelId: string;
     config?: ChannelConfig | null;
 };
+export type GlobalSearchResult = {
+    type: "turn" | "session" | "space";
+    id: string;
+    spaceId: string;
+    sessionId: string | null;
+    turnId: string | null;
+    sequence: number | null;
+    title: string;
+    excerpt: string | null;
+    spaceName: string | null;
+    sessionTitle: string | null;
+    matchedField: "userText" | "title" | "name" | "description";
+    href: string;
+    score: number;
+    textScore: number;
+    recencyScore: number;
+    typePriorityScore: number;
+    updatedAt: string | null;
+    source: "remote";
+};
+export type GlobalSearchResponse = {
+    items: GlobalSearchResult[];
+    query: string;
+    source: "remote";
+    degraded?: boolean;
+};
 export type SpaceSessionsResponse = {
     sessions: SessionRecord[];
     pageInfo?: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neta-art/cohub",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "Cohub SDK for spaces, sessions, checkpoints, and realtime agent collaboration.",
   "license": "UNLICENSED",
   "private": false,
@@ -44,7 +44,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@neta-art/cohub-protocol": "1.4.0"
+    "@neta-art/cohub-protocol": "1.5.0"
   },
   "devDependencies": {
     "typescript": "^6.0.3"