@od-oneapp/ai-platform 0.1.0

package/src/streaming/core/multi-step.ts

@@ -0,0 +1,471 @@
+/**
+ * Multi-Step Streaming Module
+ *
+ * SDK v6 patterns for streaming multi-step agent executions:
+ * - createUIMessageStream with sendFinish: false
+ * - Step-by-step UI updates
+ * - Nested stream forwarding
+ *
+ * @module streaming/multi-step
+ */
+
+import { createUIMessageStream, createUIMessageStreamResponse } from '../../shared';
+
+import type {
+  SDKStreamTextResult,
+  SDKUIMessage,
+  SDKUIMessageStreamWriter,
+  SDKToolSet,
+} from '../../shared';
+
+// -----------------------------------------------------------------------------
+// Types
+// -----------------------------------------------------------------------------
+
+/** Multi-step stream event */
+export interface MultiStepStreamEvent {
+  type:
+    | 'step-start'
+    | 'step-text'
+    | 'step-tool-call'
+    | 'step-tool-result'
+    | 'step-end'
+    | 'finish'
+    | 'error';
+  stepIndex?: number;
+  stepName?: string;
+  content?: string;
+  toolCall?: {
+    id: string;
+    name: string;
+    input: unknown;
+  };
+  toolResult?: {
+    id: string;
+    name: string;
+    result: unknown;
+  };
+  error?: Error;
+}
+
+/** Step definition for multi-step execution */
+export interface StepDefinition<TContext = unknown> {
+  /** Step name */
+  name: string;
+  /** Execute the step */
+  execute: (context: TContext, writer: SDKUIMessageStreamWriter<SDKUIMessage>) => Promise<TContext>;
+  /** Optional: check if step should run */
+  shouldRun?: (context: TContext) => boolean;
+}
+
+/** Multi-step stream options */
+export interface MultiStepStreamOptions<TContext> {
+  /** Initial context */
+  initialContext: TContext;
+  /** Steps to execute */
+  steps: StepDefinition<TContext>[];
+  /** Error handler */
+  onError?: (error: Error, stepIndex: number) => void;
+  /** Step completion handler */
+  onStepComplete?: (stepIndex: number, context: TContext) => void;
+}
+
+// -----------------------------------------------------------------------------
+// Multi-Step Stream Writer
+// -----------------------------------------------------------------------------
+
+type MultiStepStreamWriter = SDKUIMessageStreamWriter<SDKUIMessage>;
+type MultiStepStreamResult = SDKStreamTextResult<SDKToolSet, never>;
+
+/**
+ * Enhanced writer for multi-step streams.
+ * Wraps UIMessageStreamWriter with step-aware methods.
+ *
+ * Note: SDK v6 uses typed message chunks. This wrapper uses
+ * the `data-{name}` format for custom data parts to maintain
+ * compatibility with the typed stream protocol.
+ */
+export class MultiStepWriter {
+  private currentStep = 0;
+  private stepStarted = false;
+
+  constructor(
+    private readonly writer: MultiStepStreamWriter,
+    private readonly options?: { sendFinish?: boolean },
+  ) {}
+
+  /**
+   * Start a new step.
+   * Uses data-step-event format for SDK v6 compatibility.
+   */
+  startStep(name: string): void {
+    if (name.trim().length === 0) {
+      throw new Error('Step name is required');
+    }
+    this.stepStarted = true;
+    // Use data-${name} format for custom data in SDK v6
+    this.writer.write({
+      type: 'data-step-event',
+      data: { event: 'step-start', stepIndex: this.currentStep, stepName: name },
+    });
+  }
+
+  /**
+   * End the current step.
+   */
+  endStep(): void {
+    this.writer.write({
+      type: 'data-step-event',
+      data: { event: 'step-end', stepIndex: this.currentStep },
+    });
+    this.currentStep++;
+    this.stepStarted = false;
+  }
+
+  /**
+   * Write text delta within current step.
+   * Uses the standard text-delta format.
+   */
+  writeText(text: string): void {
+    this.writer.write({
+      type: 'text-delta',
+      id: `step-${this.currentStep}`,
+      delta: text,
+    });
+  }
+
+  /**
+   * Write tool call within current step.
+   */
+  writeToolCall(id: string, name: string, input: unknown): void {
+    this.writer.write({
+      type: 'data-step-event',
+      data: {
+        event: 'step-tool-call',
+        stepIndex: this.currentStep,
+        toolCall: { id, name, input },
+      },
+    });
+  }
+
+  /**
+   * Write tool result within current step.
+   */
+  writeToolResult(id: string, name: string, result: unknown): void {
+    this.writer.write({
+      type: 'data-step-event',
+      data: {
+        event: 'step-tool-result',
+        stepIndex: this.currentStep,
+        toolResult: { id, name, result },
+      },
+    });
+  }
+
+  /**
+   * Forward a streamText result to this writer.
+   * Uses merge() to combine streams properly in SDK v6.
+   */
+  async forwardStream(
+    stream: MultiStepStreamResult,
+    options?: { sendFinish?: boolean },
+  ): Promise<void> {
+    void options;
+    // SDK v6 uses toUIMessageStream() which returns a ReadableStream
+    // Use merge() to forward the stream
+    const uiStream = stream.toUIMessageStream?.<SDKUIMessage>();
+    if (uiStream) {
+      this.writer.merge(uiStream);
+    }
+  }
+
+  /**
+   * Write error.
+   */
+  writeError(error: Error): void {
+    this.writer.write({
+      type: 'error',
+      errorText: error.message,
+    });
+  }
+
+  /**
+   * Finish the stream.
+   */
+  finish(): void {
+    if (this.options?.sendFinish !== false) {
+      this.writer.write({
+        type: 'finish',
+        finishReason: 'stop',
+      });
+    }
+  }
+
+  /** Get current step index */
+  get stepIndex(): number {
+    return this.currentStep;
+  }
+
+  /** Get underlying writer */
+  get raw(): MultiStepStreamWriter {
+    return this.writer;
+  }
+}
+
+// -----------------------------------------------------------------------------
+// Multi-Step Stream Factory
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a multi-step streaming response.
+ *
+ * @example
+ * ```typescript
+ * // API Route
+ * export async function POST(request: Request) {
+ *   const { messages } = await request.json();
+ *
+ *   return createMultiStepStreamResponse({
+ *     initialContext: { messages, results: [] },
+ *     steps: [
+ *       {
+ *         name: 'analyze',
+ *         execute: async (ctx, writer) => {
+ *           writer.startStep('Analyzing query...');
+ *           const result = await streamText({
+ *             model,
+ *             prompt: 'Analyze: ' + ctx.messages[0].content,
+ *           });
+ *           await writer.forwardStream(result, { sendFinish: false });
+ *           writer.endStep();
+ *           return { ...ctx, analysis: await result.text };
+ *         },
+ *       },
+ *       {
+ *         name: 'respond',
+ *         execute: async (ctx, writer) => {
+ *           writer.startStep('Generating response...');
+ *           const result = await streamText({
+ *             model,
+ *             prompt: `Based on: ${ctx.analysis}\nRespond to user.`,
+ *           });
+ *           await writer.forwardStream(result);
+ *           writer.endStep();
+ *           return ctx;
+ *         },
+ *       },
+ *     ],
+ *   });
+ * }
+ * ```
+ */
+export function createMultiStepStreamResponse<TContext>(
+  options: MultiStepStreamOptions<TContext>,
+): Response {
+  const stream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      await executeMultiStepStream(writer, options);
+    },
+  });
+
+  return createUIMessageStreamResponse({ stream });
+}
+
+/**
+ * Create a multi-step stream (raw stream, not Response).
+ */
+export function createMultiStepStream<TContext>(
+  options: MultiStepStreamOptions<TContext>,
+): ReadableStream {
+  return createUIMessageStream({
+    execute: async ({ writer }) => {
+      await executeMultiStepStream(writer, options);
+    },
+  });
+}
+
+/**
+ * Execute multi-step stream with provided writer.
+ */
+export async function executeMultiStepStream<TContext>(
+  rawWriter: MultiStepStreamWriter,
+  options: MultiStepStreamOptions<TContext>,
+): Promise<TContext> {
+  const { initialContext, steps, onError, onStepComplete } = options;
+  const writer = new MultiStepWriter(rawWriter);
+
+  let context = initialContext;
+
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i];
+
+    // Check if step should run
+    if (!step || (step.shouldRun && !step.shouldRun(context))) {
+      continue;
+    }
+
+    try {
+      // Execute step
+      context = await step.execute(context, rawWriter);
+
+      // Notify completion
+      onStepComplete?.(i, context);
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      writer.writeError(err);
+      onError?.(err, i);
+      throw err;
+    }
+  }
+
+  writer.finish();
+  return context;
+}
+
+// -----------------------------------------------------------------------------
+// Step Helpers
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a streaming text step.
+ */
+export function createTextStep<TContext>(config: {
+  name: string;
+  getPrompt: (context: TContext) => string;
+  streamText: (prompt: string) => Promise<MultiStepStreamResult>;
+  updateContext: (context: TContext, text: string) => TContext;
+  shouldRun?: (context: TContext) => boolean;
+}): StepDefinition<TContext> {
+  return {
+    name: config.name,
+    shouldRun: config.shouldRun,
+    execute: async (context, writer) => {
+      const msWriter = new MultiStepWriter(writer);
+      msWriter.startStep(config.name);
+
+      const prompt = config.getPrompt(context);
+      const result = await config.streamText(prompt);
+
+      await msWriter.forwardStream(result, { sendFinish: false });
+      msWriter.endStep();
+
+      const text = await result.text;
+      return config.updateContext(context, text);
+    },
+  };
+}
+
+/**
+ * Create a tool execution step.
+ */
+export function createToolStep<TContext, TResult>(config: {
+  name: string;
+  toolName: string;
+  getInput: (context: TContext) => unknown;
+  executeTool: (input: unknown) => Promise<TResult>;
+  updateContext: (context: TContext, result: TResult) => TContext;
+  shouldRun?: (context: TContext) => boolean;
+}): StepDefinition<TContext> {
+  return {
+    name: config.name,
+    shouldRun: config.shouldRun,
+    execute: async (context, writer) => {
+      const msWriter = new MultiStepWriter(writer);
+      msWriter.startStep(config.name);
+
+      const input = config.getInput(context);
+      const toolCallId = `call_${Date.now()}`;
+
+      msWriter.writeToolCall(toolCallId, config.toolName, input);
+
+      const result = await config.executeTool(input);
+
+      msWriter.writeToolResult(toolCallId, config.toolName, result);
+      msWriter.endStep();
+
+      return config.updateContext(context, result);
+    },
+  };
+}
+
+/**
+ * Create a conditional step that branches based on context.
+ */
+export function createConditionalStep<TContext>(config: {
+  name: string;
+  condition: (context: TContext) => boolean;
+  ifTrue: StepDefinition<TContext>;
+  ifFalse?: StepDefinition<TContext>;
+}): StepDefinition<TContext> {
+  return {
+    name: config.name,
+    execute: async (context, writer) => {
+      const step = config.condition(context) ? config.ifTrue : config.ifFalse;
+
+      if (step) {
+        return step.execute(context, writer);
+      }
+
+      return context;
+    },
+  };
+}
+
+/**
+ * Create a parallel step that runs multiple steps concurrently.
+ * Note: Results are merged into context in order of completion.
+ */
+export function createParallelStep<TContext>(config: {
+  name: string;
+  steps: StepDefinition<TContext>[];
+  mergeResults: (context: TContext, results: TContext[]) => TContext;
+}): StepDefinition<TContext> {
+  return {
+    name: config.name,
+    execute: async (context, writer) => {
+      const msWriter = new MultiStepWriter(writer);
+      msWriter.startStep(config.name);
+
+      // Execute all steps in parallel
+      const results = await Promise.all(config.steps.map(step => step.execute(context, writer)));
+
+      msWriter.endStep();
+
+      return config.mergeResults(context, results);
+    },
+  };
+}
+
+// -----------------------------------------------------------------------------
+// Utilities
+// -----------------------------------------------------------------------------
+
+/**
+ * Create a simple multi-step pipeline.
+ */
+export function createStepPipeline<TContext>(
+  ...steps: StepDefinition<TContext>[]
+): StepDefinition<TContext>[] {
+  return steps;
+}
+
+/**
+ * Chain steps sequentially.
+ */
+export function chainSteps<TContext>(
+  name: string,
+  steps: StepDefinition<TContext>[],
+): StepDefinition<TContext> {
+  return {
+    name,
+    execute: async (context, writer) => {
+      let current = context;
+      for (const step of steps) {
+        if (!step.shouldRun || step.shouldRun(current)) {
+          current = await step.execute(current, writer);
+        }
+      }
+      return current;
+    },
+  };
+}

package/src/streaming/core/protocol.ts

@@ -0,0 +1,194 @@
+/**
+ * @fileoverview Streaming protocol utilities for artifact streaming.
+ * @module @od-oneapp/ai-platform/streaming
+ */
+
+import type { ArtifactStreamWriter, CustomUIDataTypes } from './types';
+
+/**
+ * Generic data stream writer interface.
+ * Compatible with AI SDK's data stream patterns.
+ */
+export interface DataStreamWriter {
+  write(data: unknown): void;
+}
+
+/**
+ * Creates an artifact stream writer for custom data streaming.
+ *
+ * @param writer - Data stream writer with write method
+ * @returns Artifact stream writer with typed methods
+ *
+ * @example
+ * ```ts
+ * // With createUIMessageStream
+ * const stream = createUIMessageStream({
+ *   execute: async ({ writer }) => {
+ *     const artifactWriter = createArtifactStreamWriter({
+ *       write: (data) => writer.write(JSON.stringify(data)),
+ *     });
+ *     artifactWriter.writeId('artifact-123');
+ *     artifactWriter.writeTextDelta('Hello world');
+ *     artifactWriter.writeFinish(true);
+ *   },
+ * });
+ * ```
+ */
+export function createArtifactStreamWriter(writer: DataStreamWriter): ArtifactStreamWriter {
+  return {
+    writeId(id: string) {
+      writer.write({ type: 'id', data: id });
+    },
+
+    writeKind(kind: string) {
+      writer.write({ type: 'kind', data: kind });
+    },
+
+    writeTitle(title: string) {
+      writer.write({ type: 'title', data: title });
+    },
+
+    writeStatus(status: CustomUIDataTypes['status']) {
+      writer.write({ type: 'status', data: status });
+    },
+
+    writeTextDelta(text: string) {
+      writer.write({ type: 'textDelta', data: text });
+    },
+
+    writeCodeDelta(code: string, language?: string) {
+      writer.write({ type: 'codeDelta', data: { code, language } });
+    },
+
+    writeProgress(current: number, total: number, message?: string) {
+      writer.write({ type: 'progress', data: { current, total, message } });
+    },
+
+    writeFinish(success: boolean, metadata?: Record<string, unknown>) {
+      writer.write({ type: 'finish', data: { success, metadata } });
+    },
+
+    writeError(message: string, code?: string, recoverable?: boolean) {
+      writer.write({ type: 'error', data: { message, code, recoverable } });
+    },
+
+    clear() {
+      writer.write({ type: 'clear', data: null });
+    },
+  };
+}
+
+/**
+ * Helper to stream artifact creation with standard lifecycle.
+ *
+ * @param writer - Data stream writer
+ * @param config - Artifact configuration
+ * @param generator - Async generator that yields content
+ *
+ * @example
+ * ```ts
+ * await streamArtifact(writer, {
+ *   id: 'doc-123',
+ *   kind: 'text',
+ *   title: 'My Document',
+ * }, async function* () {
+ *   yield 'Hello ';
+ *   yield 'World!';
+ * });
+ * ```
+ */
+export async function streamArtifact(
+  dataWriter: DataStreamWriter,
+  config: {
+    id: string;
+    kind: string;
+    title: string;
+  },
+  generator: () => AsyncGenerator<string, void, unknown>,
+): Promise<void> {
+  const writer = createArtifactStreamWriter(dataWriter);
+
+  try {
+    // Initialize artifact
+    writer.writeId(config.id);
+    writer.writeKind(config.kind);
+    writer.writeTitle(config.title);
+    writer.writeStatus('streaming');
+
+    // Stream content
+    for await (const chunk of generator()) {
+      writer.writeTextDelta(chunk);
+    }
+
+    // Complete
+    writer.writeStatus('complete');
+    writer.writeFinish(true);
+  } catch (error) {
+    writer.writeStatus('error');
+    writer.writeError(
+      error instanceof Error ? error.message : 'Unknown error',
+      'STREAM_ERROR',
+      false,
+    );
+    writer.writeFinish(false);
+    throw error;
+  }
+}
+
+/**
+ * Creates a buffered stream writer that batches writes for efficiency.
+ *
+ * @param writer - Data stream writer
+ * @param options - Buffer options
+ * @returns Buffered writer with flush method
+ */
+export function createBufferedStreamWriter(
+  writer: DataStreamWriter,
+  options: {
+    /** Buffer size before auto-flush */
+    bufferSize?: number;
+    /** Time in ms before auto-flush */
+    flushInterval?: number;
+  } = {},
+) {
+  const { bufferSize = 10, flushInterval = 100 } = options;
+  const buffer: Array<{ type: string; data: unknown }> = [];
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  function flush() {
+    if (buffer.length === 0) return;
+
+    for (const item of buffer) {
+      writer.write(item);
+    }
+    buffer.length = 0;
+
+    if (flushTimer) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+
+  function scheduleFlush() {
+    if (flushTimer) return;
+    flushTimer = setTimeout(flush, flushInterval);
+  }
+
+  function write(type: string, data: unknown) {
+    buffer.push({ type, data });
+
+    if (buffer.length >= bufferSize) {
+      flush();
+    } else {
+      scheduleFlush();
+    }
+  }
+
+  return {
+    write,
+    flush,
+    get bufferLength() {
+      return buffer.length;
+    },
+  };
+}