maka-agent 0.2.0-dev.3.20260830 → 0.2.0-dev.31.20260913

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/04-ai-sdk-workflow/02-workflow-chat-transport.mdx

@@ -0,0 +1,361 @@
+---
+title: WorkflowChatTransport
+description: API Reference for the WorkflowChatTransport class.
+---
+
+# `WorkflowChatTransport`
+
+A [`ChatTransport`](/docs/ai-sdk-ui/transport) implementation for [`useChat`](/docs/reference/ai-sdk-ui/use-chat) that enables automatic stream reconnection for workflow-based chat apps. It posts messages to a chat endpoint, extracts the `x-workflow-run-id` response header, and reconnects to a `/{runId}/stream` endpoint on interruption (network failures, page refreshes, function timeouts).
+
+Unlike [`DefaultChatTransport`](/docs/ai-sdk-ui/transport) which assumes the full response arrives in a single HTTP request, `WorkflowChatTransport` is designed for the [Workflow SDK](https://vercel.com/docs/workflow) where the initial response stream may be interrupted by function timeouts. The transport automatically detects missing `finish` events and reconnects to resume from where the stream left off.
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@ai-sdk/workflow';
+
+export default function Chat() {
+  const { messages, sendMessage } = useChat({
+    transport: new WorkflowChatTransport({
+      api: '/api/chat',
+      maxConsecutiveErrors: 5,
+    }),
+  });
+
+  // ... render chat UI
+}
+```
+
+## Import
+
+<Snippet
+  text={`import { WorkflowChatTransport } from "@ai-sdk/workflow"`}
+  prompt={false}
+/>
+
+## Constructor
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: 'api',
+      type: 'string',
+      isOptional: true,
+      description:
+        "API endpoint for chat requests. The reconnection endpoint is derived from this as `{api}/{runId}/stream`. Default: '/api/chat'.",
+    },
+    {
+      name: 'fetch',
+      type: 'typeof fetch',
+      isOptional: true,
+      description:
+        'Custom fetch implementation to use for HTTP requests. Default: global fetch.',
+    },
+    {
+      name: 'maxConsecutiveErrors',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of consecutive errors allowed during reconnection attempts before giving up. Default: 3.',
+    },
+    {
+      name: 'initialStartIndex',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Default chunk index to start from when reconnecting. Negative values read from the end of a durable UIMessageChunk stream (e.g., -50 fetches the last 50 chunks), useful for resuming after a page refresh without replaying the full conversation. Raw ModelCallStreamPart streams do not support negative UI chunk indexes. Can be overridden per-call via reconnectToStream options. Default: 0.',
+    },
+    {
+      name: 'onChatSendMessage',
+      type: '(response: Response, options: SendMessagesOptions) => void | Promise<void>',
+      isOptional: true,
+      description:
+        'Callback invoked after the initial POST request succeeds. Useful for inspecting response headers (e.g., extracting workflow run ID) or tracking chat history on the client side.',
+    },
+    {
+      name: 'onChatEnd',
+      type: '({ chatId, chunkIndex }) => void | Promise<void>',
+      isOptional: true,
+      description:
+        'Callback invoked when the stream ends (receives a finish chunk). Receives the chat ID and total chunk count. Useful for cleanup or state updates.',
+    },
+    {
+      name: 'prepareSendMessagesRequest',
+      type: 'PrepareSendMessagesRequest',
+      isOptional: true,
+      description:
+        'Function to customize the POST request before sending. Can override the API endpoint, headers, credentials, and body.',
+    },
+    {
+      name: 'prepareReconnectToStreamRequest',
+      type: 'PrepareReconnectToStreamRequest',
+      isOptional: true,
+      description:
+        'Function to customize the reconnection GET request. Can override the API endpoint, headers, and credentials.',
+    },
+  ]}
+/>
+
+## Methods
+
+### `sendMessages()`
+
+Sends messages to the chat endpoint via POST and returns a streaming response. If the stream is interrupted (no `finish` event received), the transport automatically reconnects via GET to `{api}/{runId}/stream?startIndex={chunkIndex}` to resume from where it left off.
+
+The POST request includes the messages as JSON and expects the response to include an `x-workflow-run-id` header identifying the workflow run.
+
+```ts
+const stream = await transport.sendMessages({
+  chatId: 'chat-123',
+  trigger: 'submit-message',
+  messages: [...],
+  abortSignal: controller.signal,
+});
+```
+
+<PropertiesTable
+  content={[
+    {
+      name: 'chatId',
+      type: 'string',
+      description: 'Unique identifier for the chat session.',
+    },
+    {
+      name: 'trigger',
+      type: "'submit-message' | 'regenerate-message'",
+      description: 'The type of message submission.',
+    },
+    {
+      name: 'messageId',
+      type: 'string | undefined',
+      description:
+        'ID of the message to regenerate, or undefined for new messages.',
+    },
+    {
+      name: 'messages',
+      type: 'UIMessage[]',
+      description:
+        'Array of UI messages representing the conversation history.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal | undefined',
+      description:
+        'Signal to abort the request. Propagated to both the initial POST and any reconnection GET requests.',
+    },
+  ]}
+/>
+
+#### Returns
+
+Returns a `Promise<ReadableStream<UIMessageChunk>>` that includes chunks from both the initial POST response and any automatic reconnection.
+
+### `reconnectToStream()`
+
+Reconnects to an existing chat stream that was previously interrupted. Useful for resuming after a page refresh or when the client needs to re-establish a connection.
+
+```ts
+const stream = await transport.reconnectToStream({
+  chatId: 'chat-123',
+  startIndex: -50, // Optional: fetch last 50 chunks
+});
+```
+
+<PropertiesTable
+  content={[
+    {
+      name: 'chatId',
+      type: 'string',
+      description:
+        'The chat ID to reconnect to. Used to construct the reconnection URL.',
+    },
+    {
+      name: 'abortSignal',
+      type: 'AbortSignal | undefined',
+      description: 'Signal to abort the reconnection request.',
+    },
+    {
+      name: 'startIndex',
+      type: 'number',
+      isOptional: true,
+      description:
+        "Override the start index for this reconnection. Negative values read from the end when the server's durable stream and tail-index header use the same UIMessageChunk index space. When omitted, falls back to the constructor's initialStartIndex.",
+    },
+  ]}
+/>
+
+#### Returns
+
+Returns a `Promise<ReadableStream<UIMessageChunk> | null>`.
+
+## How Reconnection Works
+
+The transport follows this flow:
+
+1. **POST** to `{api}` with messages. The response must include an `x-workflow-run-id` header.
+2. **Stream** the SSE response, counting chunks as they arrive.
+3. **Detect interruption**: If the stream closes without a `finish` event (e.g., function timeout, network error), the transport knows the response is incomplete.
+4. **Reconnect** via GET to `{api}/{runId}/stream?startIndex={chunkIndex}` to resume from the last received chunk.
+5. **Retry**: If the reconnection stream also interrupts, retry up to `maxConsecutiveErrors` times.
+6. **Complete**: Once a `finish` event is received, call `onChatEnd` and close the stream.
+
+### Negative Start Index
+
+When `initialStartIndex` is negative (e.g., `-50`), the transport sends it as-is in the first reconnection request. The server should resolve this to an absolute position and return the `x-workflow-stream-tail-index` response header so the transport can compute the correct position for subsequent retries.
+
+If the header is missing or invalid, the transport falls back to replaying from the beginning (`startIndex=0`).
+
+Negative indexes require a durable server stream whose stored objects are
+already `UIMessageChunk` objects. The raw `WorkflowAgent` conversion shown
+below supports non-negative indexes only.
+
+## Server Requirements
+
+For `WorkflowChatTransport` to work, your server must provide two endpoints:
+
+### POST `{api}` (e.g., `/api/chat`)
+
+- Accept messages as JSON body
+- Return an SSE stream of `UIMessageChunk` events
+- Include an `x-workflow-run-id` response header
+
+### GET `{api}/{runId}/stream` (e.g., `/api/chat/{runId}/stream`)
+
+- Accept a `startIndex` query parameter
+- Return the SSE stream starting from the given chunk index
+- For negative `startIndex`, resolve to the tail and include `x-workflow-stream-tail-index` response header
+
+See the [WorkflowAgent guide](/docs/agents/workflow-agent) for complete endpoint examples.
+
+## Examples
+
+### Basic Usage with useChat
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@ai-sdk/workflow';
+import { useMemo } from 'react';
+
+export default function Chat() {
+  const transport = useMemo(
+    () => new WorkflowChatTransport({ api: '/api/chat' }),
+    [],
+  );
+
+  const { messages, sendMessage, status } = useChat({ transport });
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role === 'user' ? 'User: ' : 'AI: '}
+          {message.parts.map((part, index) =>
+            part.type === 'text' ? <span key={index}>{part.text}</span> : null,
+          )}
+        </div>
+      ))}
+      <button onClick={() => sendMessage({ text: 'Hello!' })}>Send</button>
+    </div>
+  );
+}
+```
+
+### With Callbacks
+
+```tsx
+'use client';
+
+import { useChat } from '@ai-sdk/react';
+import { WorkflowChatTransport } from '@ai-sdk/workflow';
+import { useMemo } from 'react';
+
+export default function Chat() {
+  const transport = useMemo(
+    () =>
+      new WorkflowChatTransport({
+        api: '/api/chat',
+        maxConsecutiveErrors: 5,
+        onChatSendMessage: response => {
+          const runId = response.headers.get('x-workflow-run-id');
+          console.log('Workflow run started:', runId);
+        },
+        onChatEnd: ({ chatId, chunkIndex }) => {
+          console.log(`Chat ${chatId} complete, ${chunkIndex} chunks`);
+        },
+      }),
+    [],
+  );
+
+  const { messages, sendMessage } = useChat({ transport });
+
+  // ... render chat UI
+}
+```
+
+### Server-Side Endpoints (Next.js)
+
+```ts filename="app/api/chat/route.ts"
+import { createModelCallToUIChunkTransform } from '@ai-sdk/workflow';
+import { createUIMessageStreamResponse, type UIMessage } from 'ai';
+import { start } from 'workflow/api';
+import { chat } from '@/workflow/agent-chat';
+
+export async function POST(request: Request) {
+  const { messages }: { messages: UIMessage[] } = await request.json();
+  const run = await start(chat, [messages]);
+
+  return createUIMessageStreamResponse({
+    stream: run.readable.pipeThrough(createModelCallToUIChunkTransform()),
+    headers: {
+      'x-workflow-run-id': run.runId,
+    },
+  });
+}
+```
+
+```ts filename="app/api/chat/[runId]/stream/route.ts"
+import { createModelCallToUIChunkTransform } from '@ai-sdk/workflow';
+import { createUIMessageStreamResponse } from 'ai';
+import type { NextRequest } from 'next/server';
+import { getRun } from 'workflow/api';
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ runId: string }> },
+) {
+  const { runId } = await params;
+  const startIndex = Number(
+    new URL(request.url).searchParams.get('startIndex') ?? '0',
+  );
+  if (!Number.isSafeInteger(startIndex) || startIndex < 0) {
+    return Response.json(
+      { error: 'startIndex must be a non-negative safe integer' },
+      { status: 400 },
+    );
+  }
+
+  const run = await getRun(runId);
+  const readable = run
+    .getReadable({ startIndex: 0 })
+    .pipeThrough(
+      createModelCallToUIChunkTransform({ uiStartIndex: startIndex }),
+    );
+
+  return createUIMessageStreamResponse({
+    stream: readable,
+    headers: {
+      'x-workflow-run-id': runId,
+    },
+  });
+}
+```
+
+This `WorkflowAgent` endpoint replays raw `ModelCallStreamPart` objects from
+index `0`, then applies the transport's non-negative cursor after converting
+them to `UIMessageChunk` objects. Negative start indexes require a durable
+stream whose stored objects are already `UIMessageChunk` objects.

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/04-ai-sdk-workflow/03-generate-video.mdx

@@ -0,0 +1,157 @@
+---
+title: generateVideo
+description: API Reference for durable video generation in workflows.
+---
+
+# `generateVideo()`
+
+Generates videos durably inside a workflow. The helper starts an asynchronous
+video generation job with a Workflow webhook URL, suspends the workflow until
+the provider sends a terminal notification, and then retrieves the completed
+result with one status request.
+
+Unlike [`experimental_generateVideo`](/docs/reference/ai-sdk-core/generate-video)
+from `ai`, this helper does not download provider-hosted videos. URL results
+remain URLs so your workflow can decide whether to persist, copy, or process
+them in another step without serializing the video bytes through workflow step
+boundaries.
+
+```ts
+import { experimental_generateVideo as generateVideo } from '@ai-sdk/workflow/video';
+
+export async function videoWorkflow(prompt: string) {
+  'use workflow';
+
+  // The workflow suspends while the video renders, consuming no compute.
+  const result = await generateVideo({
+    model: 'klingai/kling-v3.0-t2v',
+    prompt,
+  });
+
+  return result.videos;
+}
+```
+
+The selected model must support asynchronous start and status operations and
+provider webhooks. The helper must be called from a Workflow SDK workflow.
+
+## Import
+
+<Snippet
+  text={`import { experimental_generateVideo as generateVideo } from "@ai-sdk/workflow/video"`}
+  prompt={false}
+/>
+
+## Parameters
+
+The helper accepts the same parameters as `experimental_startVideo` from `ai`,
+except `webhookUrl` and `abortSignal`. It creates and manages the webhook URL.
+
+<PropertiesTable
+  content={[
+    {
+      name: 'model',
+      type: 'VideoModel',
+      isRequired: true,
+      description:
+        'The asynchronous video model to use. A string compatible with Vercel AI Gateway or a serializable provider model.',
+    },
+    {
+      name: 'prompt',
+      type: 'string | GenerateVideoPrompt',
+      isRequired: true,
+      description: 'The prompt or image prompt used to generate the video.',
+    },
+    {
+      name: 'n',
+      type: 'number',
+      isOptional: true,
+      description: 'Number of videos to generate. Default: 1.',
+    },
+    {
+      name: 'aspectRatio',
+      type: '`${number}:${number}` | "adaptive"',
+      isOptional: true,
+      description: 'Aspect ratio of the generated videos.',
+    },
+    {
+      name: 'resolution',
+      type: '`${number}x${number}`',
+      isOptional: true,
+      description: 'Resolution of the generated videos.',
+    },
+    {
+      name: 'duration',
+      type: 'number',
+      isOptional: true,
+      description: 'Duration of each generated video in seconds.',
+    },
+    {
+      name: 'maxVideosPerCall',
+      type: 'number',
+      isOptional: true,
+      description: 'Maximum number of videos that may be started in one call.',
+    },
+    {
+      name: 'fps',
+      type: 'number',
+      isOptional: true,
+      description: 'Frames per second for the generated videos.',
+    },
+    {
+      name: 'seed',
+      type: 'number',
+      isOptional: true,
+      description: 'Seed used for deterministic generation when supported.',
+    },
+    {
+      name: 'frameImages',
+      type: 'Array<{ image: DataContent; frameType: VideoModelV4FrameType }>',
+      isOptional: true,
+      description: 'Role-tagged first and last frame images.',
+    },
+    {
+      name: 'inputReferences',
+      type: 'Array<DataContent | { data: DataContent; mediaType?: string }>',
+      isOptional: true,
+      description: 'Reference images or videos for the generation.',
+    },
+    {
+      name: 'generateAudio',
+      type: 'boolean',
+      isOptional: true,
+      description: 'Whether to generate audio with the video.',
+    },
+    {
+      name: 'providerOptions',
+      type: 'ProviderOptions',
+      isOptional: true,
+      description: 'Additional provider-specific options.',
+    },
+    {
+      name: 'headers',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description: 'Additional HTTP headers for start and status requests.',
+    },
+    {
+      name: 'maxRetries',
+      type: 'number',
+      isOptional: true,
+      description:
+        'Maximum number of AI SDK retries for each start and status request. Default: 2.',
+    },
+  ]}
+/>
+
+## Returns
+
+Returns the completed status result from the provider. `videos` contains raw
+provider video data discriminated by `type`:
+
+- `url`: A provider-hosted URL and media type
+- `base64`: Base64-encoded video data and media type
+- `binary`: A `Uint8Array` and media type
+
+Hosted URLs can expire. Handle any video you need to retain in a separate
+workflow step.

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/04-ai-sdk-workflow/index.mdx

@@ -0,0 +1,32 @@
+---
+title: AI SDK Workflow
+description: Reference documentation for @ai-sdk/workflow
+collapsed: true
+---
+
+# AI SDK Workflow
+
+[`@ai-sdk/workflow`](/docs/agents/workflow-agent) provides the `WorkflowAgent` class for building durable, resumable AI agents that run inside a workflow. It handles tool schema serialization, workflow step boundaries, and built-in tool approval flows.
+
+<IndexCards
+  cards={[
+    {
+      title: 'WorkflowAgent',
+      description:
+        'Create durable AI agents with tool calling, streaming, and workflow integration.',
+      href: '/docs/reference/ai-sdk-workflow/workflow-agent',
+    },
+    {
+      title: 'WorkflowChatTransport',
+      description:
+        'Chat transport with automatic stream reconnection for workflow-based apps.',
+      href: '/docs/reference/ai-sdk-workflow/workflow-chat-transport',
+    },
+    {
+      title: 'generateVideo',
+      description:
+        'Generate videos durably with provider webhooks and no implicit downloads.',
+      href: '/docs/reference/ai-sdk-workflow/generate-video',
+    },
+  ]}
+/>

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/05-ai-sdk-errors/ai-invalid-argument-error.mdx

@@ -0,0 +1,31 @@
+---
+title: AI_InvalidArgumentError
+description: Learn how to fix AI_InvalidArgumentError
+---
+
+# AI_InvalidArgumentError
+
+This error occurs when an invalid argument was provided.
+
+For example, `getTextFromDataUrl` throws this error when its `dataUrl` argument
+is malformed or cannot be decoded. Utility validation that is used by higher
+level APIs also uses this error, so you can handle invalid arguments with one
+stable error guard.
+
+## Properties
+
+- `parameter`: The name of the parameter that is invalid
+- `value`: The invalid value
+- `message`: The error message
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_InvalidArgumentError` using:
+
+```typescript
+import { InvalidArgumentError } from 'ai';
+
+if (InvalidArgumentError.isInstance(error)) {
+  console.error(`Invalid ${error.parameter}:`, error.message);
+}
+```

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/05-ai-sdk-errors/ai-no-image-generated-error.mdx

@@ -0,0 +1,43 @@
+---
+title: AI_NoImageGeneratedError
+description: Learn how to fix AI_NoImageGeneratedError
+---
+
+# AI_NoImageGeneratedError
+
+This error occurs when the AI provider fails to generate an image.
+It can arise due to the following reasons:
+
+- The model failed to generate a response.
+- The model generated an invalid response.
+
+## Properties
+
+- `message`: The error message (optional, defaults to `'No image generated.'`).
+- `calls`: Results from the underlying image model calls, including generated images, provider metadata, response metadata, warnings, and usage (optional).
+- `responses`: Metadata about the image model responses, including timestamp, model, and headers (optional).
+- `cause`: The cause of the error. You can use this for more detailed error handling (optional).
+
+## Checking for this Error
+
+You can check if an error is an instance of `AI_NoImageGeneratedError` using:
+
+```typescript
+import { generateImage, NoImageGeneratedError } from 'ai';
+
+try {
+  await generateImage({ model, prompt });
+} catch (error) {
+  if (NoImageGeneratedError.isInstance(error)) {
+    console.log('NoImageGeneratedError');
+    console.log('Cause:', error.cause);
+    console.log('Responses:', error.responses);
+
+    for (const call of error.calls ?? []) {
+      console.log('Provider metadata:', call.providerMetadata);
+      console.log('Warnings:', call.warnings);
+      console.log('Usage:', call.usage);
+    }
+  }
+}
+```

package/node_modules/@maka/runtime/node_modules/ai/docs/07-reference/05-ai-sdk-errors/ai-stream-provider-error.mdx

@@ -0,0 +1,52 @@
+---
+title: AI_StreamProviderError
+description: Learn how to handle AI_StreamProviderError
+---
+
+# AI_StreamProviderError
+
+This error represents a well-formed error event reported by a provider after a
+model response stream has started. The AI SDK exposes it in streaming error
+parts and callbacks such as the `streamText` `onError` callback.
+
+## Properties
+
+- `message`: The provider error message
+- `type`: The provider-defined error type (optional)
+- `code`: The provider-defined error code as a string or number (optional)
+- `statusCode`: The HTTP-equivalent status code when supplied by or inferable from provider metadata (optional)
+- `isRetryable`: Whether retrying the model call may succeed
+- `data`: The original provider error payload (optional)
+- `cause`: The underlying error that caused the failure (optional)
+
+`isRetryable` is a retry classification, not an automatic retry. A stream may
+already contain partial output, so applications should decide whether to
+discard, replace, or preserve that output before starting another model call.
+
+## Checking for this Error
+
+Use `StreamProviderError.isInstance` so identification also works when multiple
+AI SDK versions are present:
+
+```typescript
+import { StreamProviderError, streamText } from 'ai';
+
+const result = streamText({
+  model: __MODEL__,
+  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
+  onError: ({ error }) => {
+    if (StreamProviderError.isInstance(error) && error.isRetryable) {
+      // Schedule an application-managed retry.
+    }
+  },
+});
+```
+
+Providers may not include enough metadata to determine a status code. In that
+case, `statusCode` is `undefined`, and retryability is classified
+conservatively. Provider-specific status and retry mappings are supplied by the
+provider adapter rather than inferred from arbitrary provider error type or code
+substrings. Provider `type` and `code` values are preserved independently, even
+when a numeric code is also used to determine `statusCode`. Errors that are
+already `Error` instances and malformed or unknown provider values are
+preserved unchanged.