@od-oneapp/ai-platform 0.1.0

package/src/streaming/core/auto-resume.ts

@@ -0,0 +1,276 @@
+/**
+ * @fileoverview Auto-resume helpers for interrupted streams.
+ */
+
+export interface ResumeMessage {
+  id?: string;
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  createdAt?: Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface PendingToolCall {
+  toolCallId: string;
+  toolName: string;
+  args?: Record<string, unknown>;
+  createdAt?: Date;
+}
+
+export interface StreamResumeState {
+  streamId: string;
+  messages: ResumeMessage[];
+  pendingToolCalls: PendingToolCall[];
+  lastUpdatedAt: Date;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ResumeStorage {
+  get: (streamId: string) => Promise<StreamResumeState | null>;
+  set: (streamId: string, state: StreamResumeState, ttlMs?: number) => Promise<void>;
+  delete: (streamId: string) => Promise<void>;
+}
+
+export interface AutoResumeConfig {
+  streamId: string;
+  storage: ResumeStorage;
+  ttlMs?: number;
+}
+
+export interface AutoResumeHandler {
+  saveState: (
+    state: Omit<StreamResumeState, 'streamId' | 'lastUpdatedAt'>,
+  ) => Promise<StreamResumeState>;
+  loadState: () => Promise<StreamResumeState | null>;
+  clearState: () => Promise<void>;
+  detect: (
+    messages: ResumeMessage[],
+    pendingToolCalls?: PendingToolCall[],
+  ) => ResumeDetectionResult;
+}
+
+export interface ResumeDetectionResult {
+  shouldResume: boolean;
+  reason: 'pending-tool-call' | 'last-message-user' | 'no-resume';
+  state?: StreamResumeState;
+}
+
+export interface ResumeStreamPart {
+  type: 'data-appendMessage';
+  data: string;
+  transient?: boolean;
+}
+
+const safeStringify = (value: unknown): string => {
+  const seen = new WeakSet<object>();
+
+  return JSON.stringify(value, (key, current) => {
+    void key;
+    if (typeof current === 'bigint') {
+      return current.toString();
+    }
+
+    if (current instanceof Date) {
+      return current.toISOString();
+    }
+
+    if (typeof current === 'object' && current !== null) {
+      if (seen.has(current)) {
+        return '[Circular]';
+      }
+      seen.add(current);
+    }
+
+    return current;
+  });
+};
+
+type StoredState = {
+  state: StreamResumeState;
+  expiresAt?: number;
+};
+
+export function createInMemoryStorage(): ResumeStorage {
+  const store = new Map<string, StoredState>();
+
+  return {
+    async get(streamId: string): Promise<StreamResumeState | null> {
+      const entry = store.get(streamId);
+      if (!entry) return null;
+
+      if (entry.expiresAt && Date.now() > entry.expiresAt) {
+        store.delete(streamId);
+        return null;
+      }
+
+      return entry.state;
+    },
+
+    async set(streamId: string, state: StreamResumeState, ttlMs?: number): Promise<void> {
+      store.set(streamId, {
+        state,
+        expiresAt: typeof ttlMs === 'number' ? Date.now() + ttlMs : undefined,
+      });
+    },
+
+    async delete(streamId: string): Promise<void> {
+      store.delete(streamId);
+    },
+  };
+}
+
+export function createExternalStorage(storage: ResumeStorage): ResumeStorage {
+  return storage;
+}
+
+export function detectResumeState(options: {
+  streamId: string;
+  messages: ResumeMessage[];
+  pendingToolCalls?: PendingToolCall[];
+  metadata?: Record<string, unknown>;
+}): ResumeDetectionResult {
+  const pendingToolCalls = options.pendingToolCalls ?? [];
+  const lastMessage = options.messages.at(-1);
+
+  if (pendingToolCalls.length > 0) {
+    return {
+      shouldResume: true,
+      reason: 'pending-tool-call',
+      state: {
+        streamId: options.streamId,
+        messages: options.messages,
+        pendingToolCalls,
+        lastUpdatedAt: new Date(),
+        metadata: options.metadata,
+      },
+    };
+  }
+
+  if (lastMessage?.role === 'user') {
+    return {
+      shouldResume: true,
+      reason: 'last-message-user',
+      state: {
+        streamId: options.streamId,
+        messages: options.messages,
+        pendingToolCalls,
+        lastUpdatedAt: new Date(),
+        metadata: options.metadata,
+      },
+    };
+  }
+
+  return {
+    shouldResume: false,
+    reason: 'no-resume',
+  };
+}
+
+export function restoreDataStreamMessages(messages: ResumeMessage[]): ResumeStreamPart[] {
+  return messages.map(message => ({
+    type: 'data-appendMessage',
+    data: safeStringify(message),
+    transient: true,
+  }));
+}
+
+export function buildContinuationPrompt(
+  messages: ResumeMessage[],
+  pendingToolCalls: PendingToolCall[] = [],
+): string {
+  const lastUser = [...messages].reverse().find(message => message.role === 'user');
+  const lastAssistant = [...messages].reverse().find(message => message.role === 'assistant');
+
+  const lines: string[] = [
+    'Continue the conversation from the last point without repeating prior content.',
+  ];
+
+  if (pendingToolCalls.length > 0) {
+    const pending = pendingToolCalls
+      .map(call => `${call.toolName} (${call.toolCallId})`)
+      .join(', ');
+    lines.push(`Pending tool calls: ${pending}.`);
+  }
+
+  if (lastUser) {
+    lines.push(`Last user message: ${lastUser.content}`);
+  }
+
+  if (lastAssistant) {
+    lines.push(`Last assistant message: ${lastAssistant.content}`);
+  }
+
+  return lines.join('\n');
+}
+
+export function createStreamStateTracker(options: {
+  streamId: string;
+  messages?: ResumeMessage[];
+  pendingToolCalls?: PendingToolCall[];
+  metadata?: Record<string, unknown>;
+}) {
+  const messages = [...(options.messages ?? [])];
+  const pendingToolCalls = [...(options.pendingToolCalls ?? [])];
+  let { metadata } = options;
+
+  return {
+    addMessage(message: ResumeMessage) {
+      messages.push(message);
+    },
+    addPendingToolCall(toolCall: PendingToolCall) {
+      pendingToolCalls.push(toolCall);
+    },
+    resolveToolCall(toolCallId: string) {
+      const index = pendingToolCalls.findIndex(call => call.toolCallId === toolCallId);
+      if (index >= 0) {
+        pendingToolCalls.splice(index, 1);
+      }
+    },
+    setMetadata(nextMetadata: Record<string, unknown>) {
+      metadata = nextMetadata;
+    },
+    getState(): StreamResumeState {
+      return {
+        streamId: options.streamId,
+        messages: [...messages],
+        pendingToolCalls: [...pendingToolCalls],
+        lastUpdatedAt: new Date(),
+        metadata,
+      };
+    },
+    reset() {
+      messages.length = 0;
+      pendingToolCalls.length = 0;
+      metadata = undefined;
+    },
+  };
+}
+
+export function createAutoResume(config: AutoResumeConfig): AutoResumeHandler {
+  return {
+    async saveState(state) {
+      const nextState: StreamResumeState = {
+        streamId: config.streamId,
+        messages: state.messages,
+        pendingToolCalls: state.pendingToolCalls,
+        lastUpdatedAt: new Date(),
+        metadata: state.metadata,
+      };
+      await config.storage.set(config.streamId, nextState, config.ttlMs);
+      return nextState;
+    },
+    async loadState() {
+      return config.storage.get(config.streamId);
+    },
+    async clearState() {
+      await config.storage.delete(config.streamId);
+    },
+    detect(messages, pendingToolCalls) {
+      return detectResumeState({
+        streamId: config.streamId,
+        messages,
+        pendingToolCalls,
+      });
+    },
+  };
+}

package/src/streaming/core/index.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview Streaming module for artifact and data streaming.
+ * @module @od-oneapp/ai-platform/streaming
+ *
+ * @example
+ * ```ts
+ * import { createArtifactStreamWriter, streamArtifact } from '@od-oneapp/ai-platform/streaming';
+ *
+ * // In a tool execution
+ * const writer = createArtifactStreamWriter(dataStream);
+ * writer.writeId('doc-123');
+ * writer.writeKind('text');
+ * writer.writeTextDelta('Hello world');
+ * writer.writeFinish(true);
+ *
+ * // Multi-step streaming
+ * import { createUIMessageStreamMerger, multiStepAgent } from '@od-oneapp/ai-platform/streaming';
+ * ```
+ */
+
+export {
+  type StreamPartType,
+  type StreamPart,
+  type IdStreamPart,
+  type KindStreamPart,
+  type TitleStreamPart,
+  type StatusStreamPart,
+  type TextDeltaStreamPart,
+  type CodeDeltaStreamPart,
+  type ProgressStreamPart,
+  type FinishStreamPart,
+  type ErrorStreamPart,
+  type ClearStreamPart,
+  type AnyStreamPart,
+  type CustomUIDataTypes,
+  type ArtifactStreamWriter,
+} from './types';
+
+export {
+  createArtifactStreamWriter,
+  streamArtifact,
+  createBufferedStreamWriter,
+  type DataStreamWriter,
+} from './protocol';
+
+// Multi-step streaming
+export {
+  MultiStepWriter,
+  createMultiStepStreamResponse,
+  createMultiStepStream,
+  executeMultiStepStream,
+  createTextStep,
+  createToolStep,
+  createConditionalStep,
+  createParallelStep,
+  createStepPipeline,
+  chainSteps,
+  type MultiStepStreamEvent,
+  type StepDefinition,
+  type MultiStepStreamOptions,
+} from './multi-step';
+
+// Auto-resume
+export {
+  // Main factory
+  createAutoResume,
+  // Detection
+  detectResumeState,
+  // Message restoration
+  restoreDataStreamMessages,
+  buildContinuationPrompt,
+  // Storage
+  createInMemoryStorage,
+  createExternalStorage,
+  // Stream tracking
+  createStreamStateTracker,
+  // Types
+  type StreamResumeState,
+  type ResumeMessage,
+  type PendingToolCall,
+  type ResumeStorage,
+  type AutoResumeConfig,
+  type AutoResumeHandler,
+  type ResumeDetectionResult,
+} from './auto-resume';