@jini-ai/chat 0.3.10 → 0.5.0

package/dist/server/run-finalizer/entry.d.ts

@@ -0,0 +1,47 @@
+import type { Clock } from '@jini-ai/core/primitives';
+/** Saves completed run output independently of a connected client, through host ports. */
+import type { ChatMessage } from '../../core/messages.js';
+import { type RunNotices } from '../../core/run-events/entry.js';
+import type { RunDaemonClient, RunLedger, Scheduler, RunIdClassifier } from './ports.js';
+export type { RunDaemonClient, RunLedger, Scheduler, RunIdClassifier, RunRef, RunProgress, RunSettlement } from './ports.js';
+/** All infrastructure and host messages are explicit; this factory opens no storage. */
+export interface AssistantRunFinalizerArgs {
+    readonly ledger: RunLedger;
+    readonly daemon: RunDaemonClient;
+    readonly clock: Clock;
+    readonly scheduler: Scheduler;
+    readonly runIdClassifier: RunIdClassifier;
+    readonly notices: RunNotices;
+    readonly onError: (args: {
+        operation: 'checkpoint' | 'watch';
+        runId: string;
+        error: unknown;
+    }) => void;
+}
+/** Reconnect delay: 2000ms; retry count: 30; checkpoint interval: 1000ms. */
+export interface AssistantRunFinalizerOptions {
+    readonly reconnectDelayMs?: number;
+    readonly maxReconnects?: number;
+    readonly checkpointIntervalMs?: number;
+}
+export interface AssistantRunFinalizer {
+    /** Ignore non-assistant, terminal, missing-status and externally held runs; deduplicate by run ID. */
+    watch(input: {
+        principalId: string;
+        conversationId: string;
+        message: ChatMessage;
+    }): void;
+    /** Wait for current watches to finish; terminal writes may overtake pending checkpoints. */
+    idle(args: Record<string, never>): Promise<void>;
+    activeCount(args: Record<string, never>): number;
+}
+/** Follow replayable run streams and save through atomic host ledger operations.
+ * The host retains authorization, owner scope, kernel transactions, boot reconciliation, HTTP
+ * credentials and excluded run-ID prefixes. Replay starts at zero; error-before-success and
+ * reconnect exhaustion must not falsely settle a run. Checkpoints are throttled with a trailing
+ * write, and checkpoint/settle atomically reject other runs or terminal rows: first terminal wins.
+ * Frame vocabulary, paragraph boundaries and compaction are shared with the run-event reducer.
+ * Non-success bodies are cancelled and progress scheduling stops at completion. Real database
+ * restart/race coverage remains a host responsibility; this factory never opens storage. */
+export declare function createAssistantRunFinalizer(args: AssistantRunFinalizerArgs, options?: AssistantRunFinalizerOptions): AssistantRunFinalizer;
+//# sourceMappingURL=entry.d.ts.map

package/dist/server/run-finalizer/entry.js

@@ -0,0 +1,156 @@
+import { isTerminalRunStatus } from '../../core/messages.js';
+import { readSseFrames, runContentFromEvents, runEventsForSave, runInterruptedNotice, translateRunFrame } from '../../core/run-events/entry.js';
+/** Follow replayable run streams and save through atomic host ledger operations.
+ * The host retains authorization, owner scope, kernel transactions, boot reconciliation, HTTP
+ * credentials and excluded run-ID prefixes. Replay starts at zero; error-before-success and
+ * reconnect exhaustion must not falsely settle a run. Checkpoints are throttled with a trailing
+ * write, and checkpoint/settle atomically reject other runs or terminal rows: first terminal wins.
+ * Frame vocabulary, paragraph boundaries and compaction are shared with the run-event reducer.
+ * Non-success bodies are cancelled and progress scheduling stops at completion. Real database
+ * restart/race coverage remains a host responsibility; this factory never opens storage. */
+export function createAssistantRunFinalizer(args, options = {}) {
+    const { daemon, scheduler } = args;
+    const now = () => args.clock.nowMs();
+    const reconnectDelayMs = options.reconnectDelayMs ?? 2_000;
+    const maxReconnects = options.maxReconnects ?? 30;
+    const checkpointIntervalMs = options.checkpointIntervalMs ?? 1_000;
+    // Diagnostics must not change run/checkpoint behavior, even when the host callback throws.
+    function reportError(input) {
+        try {
+            args.onError(input);
+        }
+        catch { /* The host owns reporting failures. */ }
+    }
+    const active = new Map();
+    async function settle(watch, status, events) {
+        watch.terminal = true;
+        if (watch.trailing)
+            scheduler.cancel({ handle: watch.trailing.handle });
+        watch.trailing = undefined;
+        await args.ledger.settle({
+            conversationId: watch.conversationId,
+            messageId: watch.messageId,
+            runId: watch.runId,
+            status,
+            content: runContentFromEvents({ events }),
+            events: runEventsForSave({ events }),
+            endedAt: now(),
+        });
+    }
+    function settleInterrupted(watch) {
+        return settle(watch, "canceled", [...watch.events, runInterruptedNotice({ notice: args.notices.interrupted })]);
+    }
+    // Coalesce one pending write and one trailing timer. Never block frame consumption on storage.
+    // Growth-only checkpointing avoids shrinking a saved answer during replay from event zero.
+    async function checkpoint(watch) {
+        if (watch.terminal || watch.checkpointPending)
+            return;
+        if (watch.events.length <= watch.checkpointedEvents)
+            return;
+        const wait = checkpointIntervalMs - (now() - watch.checkpointedAt);
+        if (wait > 0) {
+            if (!watch.trailing) {
+                watch.trailing = { handle: scheduler.schedule({ task: () => {
+                            watch.trailing = undefined;
+                            void checkpoint(watch);
+                        }, delayMs: wait }) };
+            }
+            return;
+        }
+        if (watch.trailing)
+            scheduler.cancel({ handle: watch.trailing.handle });
+        watch.trailing = undefined;
+        watch.checkpointedEvents = watch.events.length;
+        watch.checkpointedAt = now();
+        watch.checkpointPending = true;
+        await args.ledger
+            .checkpoint({
+            conversationId: watch.conversationId,
+            messageId: watch.messageId,
+            runId: watch.runId,
+            content: runContentFromEvents({ events: watch.events }),
+            events: runEventsForSave({ events: watch.events }),
+        })
+            .catch((error) => reportError({ operation: "checkpoint", runId: watch.runId, error }))
+            .finally(() => {
+            watch.checkpointPending = false;
+            void checkpoint(watch);
+        });
+    }
+    async function readStream(watch) {
+        const response = await daemon.openEvents({ runId: watch.runId, principalId: watch.principalId });
+        if (response.status === 404 || !response.ok || !response.body) {
+            await response.body?.cancel().catch(() => undefined);
+            return response.status === 404 ? { kind: "gone" } : { kind: "dropped" };
+        }
+        // Each connection replays the complete history, rather than appending duplicate deltas.
+        watch.events = [];
+        watch.failed = false;
+        for await (const frame of readSseFrames({ body: response.body })) {
+            const outcome = translateRunFrame({ kind: frame.event, raw: frame.data, notices: args.notices });
+            watch.events.push(...outcome.events);
+            if (outcome.error)
+                watch.failed = true;
+            if (outcome.terminal) {
+                watch.terminal = true;
+                return { kind: "ended", status: watch.failed && outcome.terminal === "succeeded" ? "failed" : outcome.terminal };
+            }
+            void checkpoint(watch);
+        }
+        return { kind: "dropped" };
+    }
+    async function follow(watch) {
+        for (let attempt = 0; attempt <= maxReconnects; attempt += 1) {
+            const result = await readStream(watch).catch(() => ({ kind: "dropped" }));
+            if (result.kind === "ended")
+                return settle(watch, result.status, watch.events);
+            if (result.kind === "gone")
+                return settleInterrupted(watch);
+            if ((await daemon.runStatus({ runId: watch.runId, principalId: watch.principalId })) === 404)
+                return settleInterrupted(watch);
+            await scheduler.sleep({ delayMs: reconnectDelayMs });
+        }
+        // Exhaustion alone is not evidence of a terminal run; the host can reattach or repair at boot.
+    }
+    return {
+        watch({ principalId, conversationId, message }) {
+            const runId = message.runId;
+            if (message.role !== "assistant" || !runId || !args.runIdClassifier.isDaemonRunId({ runId }))
+                return;
+            if (message.runStatus === undefined || isTerminalRunStatus({ status: message.runStatus }))
+                return;
+            if (active.has(runId))
+                return;
+            const watch = {
+                principalId,
+                conversationId,
+                messageId: message.id,
+                runId,
+                events: [],
+                failed: false,
+                checkpointedEvents: 0,
+                checkpointedAt: Number.NEGATIVE_INFINITY,
+                checkpointPending: false,
+                terminal: false,
+            };
+            const done = follow(watch)
+                .catch((error) => {
+                reportError({ operation: "watch", runId, error });
+            })
+                .finally(() => {
+                watch.terminal = true;
+                if (watch.trailing)
+                    scheduler.cancel({ handle: watch.trailing.handle });
+                watch.trailing = undefined;
+                active.delete(runId);
+            });
+            active.set(runId, { watch, done });
+        },
+        async idle(_args) {
+            while (active.size > 0)
+                await Promise.all([...active.values()].map((entry) => entry.done));
+        },
+        activeCount: (_args) => active.size,
+    };
+}
+//# sourceMappingURL=entry.js.map

package/dist/server/run-finalizer/ports.d.ts

@@ -0,0 +1,52 @@
+import type { AgentEvent } from '../../core/events.js';
+import type { ChatRunStatus } from '../../core/messages.js';
+/** Exactly which run owns the row; the host binds authorization and storage scope. */
+export interface RunRef {
+    readonly conversationId: string;
+    readonly messageId: string;
+    readonly runId: string;
+}
+export interface RunProgress extends RunRef {
+    readonly content: string;
+    readonly events: readonly AgentEvent[];
+}
+export interface RunSettlement extends RunProgress {
+    readonly status: Extract<ChatRunStatus, 'succeeded' | 'failed' | 'canceled'>;
+    readonly endedAt: number;
+}
+/** Storage contract only. Both methods must atomically reject a different run or terminal row.
+ * First terminal write wins; a late checkpoint cannot reopen or replace that row. */
+export interface RunLedger {
+    checkpoint(args: RunProgress): Promise<boolean>;
+    settle(args: RunSettlement): Promise<boolean>;
+}
+/** Host adapter owns URL, auth, headers and transport timeout policy. Events replay from zero. */
+export interface RunDaemonClient {
+    openEvents(args: {
+        runId: string;
+        principalId: string;
+    }): Promise<Response>;
+    runStatus(args: {
+        runId: string;
+        principalId: string;
+    }): Promise<number | null>;
+}
+/** Scheduling returns an opaque handle; a host Node adapter can unref its timer here. */
+export interface Scheduler {
+    schedule(args: {
+        task: () => void;
+        delayMs: number;
+    }): unknown;
+    cancel(args: {
+        handle: unknown;
+    }): void;
+    sleep(args: {
+        delayMs: number;
+    }): Promise<void>;
+}
+export interface RunIdClassifier {
+    isDaemonRunId(args: {
+        runId: string;
+    }): boolean;
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/store/contracts/index.d.ts

@@ -0,0 +1,5 @@
+/** Closed metadata directory for the public neutral entry. Its full source closure is
+ * verified by store/__tests__/import-isolation.test.ts and the packed Node consumer.
+ */
+export * from '@jini-ai/chat/store';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/contracts/index.js

@@ -0,0 +1,5 @@
+/** Closed metadata directory for the public neutral entry. Its full source closure is
+ * verified by store/__tests__/import-isolation.test.ts and the packed Node consumer.
+ */
+export * from '@jini-ai/chat/store';
+//# sourceMappingURL=index.js.map

package/dist/store/errors.d.ts

@@ -0,0 +1,12 @@
+import type { ChatStoreErrorCode } from './ports.js';
+/** Stable public errors; messages never expose owner IDs, cursors or driver details.
+ * @example new ChatStoreError({ code: 'conflict' }, { cause: originalError })
+ */
+export declare class ChatStoreError extends Error {
+    readonly name: "ChatStoreError";
+    readonly code: ChatStoreErrorCode;
+    constructor({ code }: {
+        code: ChatStoreErrorCode;
+    }, options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/store/errors.js

@@ -0,0 +1,18 @@
+const MESSAGES = {
+    'invalid-input': 'Invalid chat store input.',
+    'invalid-cursor': 'Invalid chat page cursor.',
+    conflict: 'Chat store conflict.',
+    unavailable: 'Chat store unavailable.',
+};
+/** Stable public errors; messages never expose owner IDs, cursors or driver details.
+ * @example new ChatStoreError({ code: 'conflict' }, { cause: originalError })
+ */
+export class ChatStoreError extends Error {
+    name = 'ChatStoreError';
+    code;
+    constructor({ code }, options) {
+        super(MESSAGES[code], options);
+        this.code = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/store/index.d.ts

@@ -0,0 +1,4 @@
+/** Neutral store contracts and errors. SQL adapters are explicit child entries. */
+export type * from './ports.js';
+export { ChatStoreError } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/index.js

@@ -0,0 +1,2 @@
+export { ChatStoreError } from './errors.js';
+//# sourceMappingURL=index.js.map

package/dist/store/legacy/index.d.ts

@@ -0,0 +1,3 @@
+/** Legacy local project conversations, distinct from tenant-scoped ai_* history. */
+export type ChatSessionMode = 'design' | 'chat' | 'plan';
+//# sourceMappingURL=index.d.ts.map

package/dist/store/legacy/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/store/legacy/sqlite/conversations.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @module db/conversations/conversations
+ * Owns conversation CRUD and list/get queries with per-conversation run summaries and
+ * total run-duration aggregation. Imports only the core/ kernel (types + rows helper).
+ */
+import type { SqliteDb } from '@jini-ai/db/sqlite';
+import type { DbRow } from '@jini-ai/db/core';
+import type { ChatSessionMode } from '../index.js';
+/**
+ * Returns all conversations for a project, newest first, each enriched with message count,
+ * the latest assistant run summary, and total accumulated run duration across all terminal runs.
+ * @param db Open SQLite database handle.
+ * @param projectId The project whose conversations to list.
+ */
+export declare function listConversations({ db, projectId }: {
+    db: SqliteDb;
+    projectId: string;
+}): {
+    latestRun: {
+        durationMs?: number;
+        endedAt?: number | undefined;
+        startedAt?: number | undefined;
+        status: string;
+    } | undefined;
+    totalDurationMs?: number;
+    id: any;
+    projectId: any;
+    title: any;
+    sessionMode: ChatSessionMode;
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+}[];
+/**
+ * Fetches a single conversation by id with its latest run summary and total run duration.
+ * Returns null when no matching conversation exists.
+ * @param db Open SQLite database handle.
+ * @param id Conversation id.
+ */
+export declare function getConversation({ db, id }: {
+    db: SqliteDb;
+    id: string;
+}): {
+    totalDurationMs?: number;
+    latestRun: {
+        durationMs?: number;
+        endedAt?: number | undefined;
+        startedAt?: number | undefined;
+        status: string;
+    } | undefined;
+    id: any;
+    projectId: any;
+    title: any;
+    sessionMode: ChatSessionMode;
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+} | null;
+/**
+ * Coerces an arbitrary database value to a valid ChatSessionMode, defaulting to 'design'.
+ * Upholds the invariant that no conversation ever carries an unknown session mode.
+ * @param value Raw value read from the session_mode column.
+ * @returns A valid ChatSessionMode: 'chat', 'plan', or 'design'.
+ */
+export declare function normalizeConversationSessionMode({ value }: {
+    value: unknown;
+}): ChatSessionMode;
+/**
+ * Inserts a new conversation row and returns the full conversation record (including run summary).
+ * Normalizes sessionMode before persisting so the stored value is always a valid ChatSessionMode.
+ * @param db Open SQLite database handle.
+ * @param c Conversation fields to insert.
+ */
+export declare function insertConversation({ db, c }: {
+    db: SqliteDb;
+    c: DbRow;
+}): {
+    totalDurationMs?: number;
+    latestRun: {
+        durationMs?: number;
+        endedAt?: number | undefined;
+        startedAt?: number | undefined;
+        status: string;
+    } | undefined;
+    id: any;
+    projectId: any;
+    title: any;
+    sessionMode: ChatSessionMode;
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+} | null;
+/**
+ * Applies a partial patch to an existing conversation, merging with the current record.
+ * Returns null when the conversation does not exist; otherwise returns the updated record.
+ * @param db Open SQLite database handle.
+ * @param id Conversation id to update.
+ * @param patch Fields to overwrite; sessionMode and updatedAt are normalized before persisting.
+ */
+export declare function updateConversation({ db, id, patch }: {
+    db: SqliteDb;
+    id: string;
+    patch: DbRow;
+}): {
+    totalDurationMs?: number;
+    latestRun: {
+        durationMs?: number;
+        endedAt?: number | undefined;
+        startedAt?: number | undefined;
+        status: string;
+    } | undefined;
+    id: any;
+    projectId: any;
+    title: any;
+    sessionMode: ChatSessionMode;
+    messageCount: number;
+    createdAt: number;
+    updatedAt: number;
+} | null;
+/**
+ * Removes a conversation row by id. Cascading deletes on messages are handled by the schema.
+ * @param db Open SQLite database handle.
+ * @param id Conversation id to delete.
+ */
+export declare function deleteConversation({ db, id }: {
+    db: SqliteDb;
+    id: string;
+}): void;
+//# sourceMappingURL=conversations.d.ts.map