@dbos-inc/vercel-ai 0.2.5 → 0.4.4

package/README.md

@@ -2,13 +2,10 @@
 
 [DBOS](https://docs.dbos.dev/) durable execution for the [Vercel AI SDK](https://ai-sdk.dev/).
 
-This package makes AI SDK **agents** durable, backed by your Postgres database.
-All you have to do is wrap your model with `durableCalls` and run your generation inside a DBOS workflow.
+This package makes AI SDK agents durable, backed by your Postgres database.
+All you have to do is wrap your model with `durableCalls` and your tools with `durableTools` and run your agents inside a DBOS workflow.
 Then, this integration automatically checkpoints every action your agents take in Postgres.
-If your process crashes mid-agent, DBOS replays the completed steps from their checkpoints and the agent resumes exactly where it left off.
-
-This package is implemented as standard AI SDK [middleware](https://ai-sdk.dev/docs/ai-sdk-core/middleware), so you keep your provider, your model configuration, and the familiar APIs like `generateText`, `streamText`, and `ToolLoopAgent`.
-Durability is transparent to your agent code.
+If your process is interrupted, DBOS replays your agent from its checkpoints so it resumes from where it left off.
 
 ```ts
 import { DBOS } from '@dbos-inc/dbos-sdk';
@@ -47,95 +44,120 @@ npm install @dbos-inc/vercel-ai @dbos-inc/dbos-sdk ai
 
 Requires DBOS v4.21+ or v5, AI SDK v7+, and a Postgres database for DBOS.
 
-## How it works
+## Durable Model Calls
 
-When an agent runs inside a DBOS workflow, DBOS makes three things durable:
+To durably checkpoint each call you make to a model, wrap your model in `durableCalls`.
+Then, call your model or agent from a workflow:
 
-- **Every model call.** `durableCalls()` is AI SDK middleware that intercepts `doGenerate`/`doStream` and runs each call through [`DBOS.runStep`](https://docs.dbos.dev/typescript/tutorials/step-tutorial). The complete result (content, usage, finish reason, response metadata) is checkpointed in Postgres. On recovery, completed calls replay from their checkpoints without contacting the model provider.
-- **The agent loop.** Because DBOS workflows replay deterministically on recovery and each model call replays from its checkpoint, a multi-step, tool-calling agent resumes from the first unfinished step instead of restarting from the beginning.
-- **Tool calls.** MCP tools (via [`durableMCPTools`](#mcp-tools)) are checkpointed automatically. Your own tools' side effects are durable when you wrap their `execute` in `DBOS.runStep` (see [Tools](#tools)).
+```ts
+import { DBOS } from '@dbos-inc/dbos-sdk';
+import { ToolLoopAgent, wrapLanguageModel } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { durableCalls } from '@dbos-inc/vercel-ai';
 
-Outside a workflow (or inside another step) the wrapped model calls the provider directly with no checkpointing, so the same model works anywhere in your app.
+const model = wrapLanguageModel({ model: openai('gpt-5'), middleware: durableCalls() });
+const agent = new ToolLoopAgent({ model, instructions: 'You are a helpful research assistant.', tools });
 
-All DBOS step options are accepted and apply per model call:
+const researchAgent = DBOS.registerWorkflow(
+  async (question: string) => {
+    const result = await agent.stream({ prompt: question });
+    for await (const delta of result.textStream) process.stdout.write(delta);
+    return await result.text;
+  },
+  { name: 'researchAgent' },
+);
+```
+
+You can parameterize `durableCalls` to configure model call retries and timeouts:
 
 ```ts
 durableCalls({
-  retriesAllowed: true,   // retry failed model calls (default: true)
-  maxAttempts: 5,         // total attempts when retries are allowed (default: 3)
-  intervalSeconds: 1,     // delay before first retry (default: 1)
-  backoffRate: 2,         // exponential backoff multiplier (default: 2)
-  shouldRetry: (error) => true,  // per-error retry predicate (default: skip provider-declared non-retryable errors and aborts)
-  timeoutMS: 60000,       // per-attempt timeout
-  name: 'my-model-call',  // step name (default: "<provider>.<modelId>.<operation>")
+  name?: string;              // step name (default: "<provider>.<modelId>.<operation>")
+  retriesAllowed?: boolean;   // retry failed model calls (default: true)
+  maxAttempts?: number;       // total attempts when retries are allowed (default: 3)
+  intervalSeconds?: number;   // delay before first retry (default: 1)
+  backoffRate?: number;       // exponential backoff multiplier (default: 2)
+  shouldRetry?: (error: unknown) => boolean;  // default: skip provider-declared non-retryable errors and aborts
+  timeoutMS?: number;         // per-attempt timeout
+  durableStream?: string;     // stream each call's output to this durable stream
+  include?: { requestBody?: boolean; responseBody?: boolean };  // checkpoint raw provider bodies; match generateText's `include` (default: false)
 });
 ```
 
-Retries are on by default so that a transient provider error is absorbed inside a single durable step.
-The default `shouldRetry` treats errors the provider marks non-retryable (an AI SDK `APICallError`/`GatewayError` with `isRetryable === false`, e.g. a 401 or an invalid-request 400) and aborts/timeouts as terminal, so they fail fast instead of retrying `maxAttempts` times. 
-Pass your own `shouldRetry` to override it, or `retriesAllowed: false` to disable step retries.
-
-Because DBOS owns retries by default, pass `maxRetries: 0` to the AI SDK call so retry behavior is governed in one place; otherwise the two compose multiplicatively and each AI SDK retry is a fresh step.
-
-## Streaming
+## Durable Streams
 
-You can stream durable model responses inside a workflow with `streamText`.
-During streaming, DBOS checkpoints only the final completed output, not individual deltas.
-As a consequence:
-
-- You can safely forward streamed deltas to a UI or terminal, but you should not perform durable steps on them because model responses are not resumable. Instead, run your own durable steps on the complete result (`result.text`) after the stream ends. Tool calls performed by the AI SDK during streaming are already durable because they execute after the model call has been checkpointed.
-- Do not exit a stream before it completes. To stop reading early, either drain the stream (`await result.consumeStream()`) or abort it.
-- To abort early, pass an `abortSignal` to `streamText` and fire it. The abort detaches your consumer, but inside a workflow it does not cut the model call short; the step keeps draining and checkpoints the complete response.
-- The AI SDK's own `timeout` option does not bound a durable model call, because its signal is an abort signal. Bound the call with the step's `timeoutMS` instead (`durableCalls({ timeoutMS })`), which DBOS tears down deterministically.
+You can **durably stream** agent or model output so it can be read by an external client or UI.
+To do this, configure `durableCalls` or `durableTools`/`durableMCPTools` with a durable stream name:
 
 ```ts
-import { streamText } from 'ai';
-import { durableCalls } from '@dbos-inc/vercel-ai';
+import { createUIMessageStreamResponse, streamText } from 'ai';
+import { durableCalls, durableTools, readDurableStream } from '@dbos-inc/vercel-ai';
 
-const model = wrapLanguageModel({
-  model: openai('gpt-5'),
-  middleware: durableCalls({ retriesAllowed: true, maxAttempts: 5 }),
-});
+const model = wrapLanguageModel({ model: openai('gpt-5'), middleware: durableCalls({ durableStream: 'ui' }) });
+const tools = durableTools(myTools, { durableStream: 'ui' });
 
-const streamingAgent = DBOS.registerWorkflow(async (prompt: string) => {
-  const result = streamText({ model, prompt });
-  for await (const delta of result.textStream) {
-    process.stdout.write(delta);
-  }
+const chatTurn = DBOS.registerWorkflow(async (messages: ModelMessage[]) => {
+  const result = streamText({ model, messages, tools, stopWhen: stepCountIs(10) });
   return await result.text;
-}, { name: 'streamingAgent' });
+}, { name: 'chatTurn' });
+
+const handle = await DBOS.startWorkflow(chatTurn)(messages);
+return createUIMessageStreamResponse({
+  stream: readDurableStream({ workflowID: handle.workflowID, key: 'ui', messageId }),
+});
 ```
 
-## Tools
+You can read from a durable stream using `readDurableStream`, for example to stream it to a UI.
+It emits a stream of AI SDK `UIMessageChunk`.
+You can also pass a `DBOSClient` into `readDurableStream` to read it from a different process.
+
+You can write your own data to a stream with `writeDurableStream(key, chunks)`.
+Your streams are closed when your workflow finishes; you can also close a stream early using `closeDurableStream`.
+
+If a workflow is interrupted during a model call, when the workflow recovers, it restarts the model call and streams its output again.
+Readers that connect afterwards see the model's output once; live readers receive a transient `data-dbos-superseded` chunk indicating the model call has been restarted.
 
-Model calls in a tool-calling loop are each checkpointed individually, so a recovered agent resumes mid-loop.
-You should wrap your tool's `execute` in a DBOS step so it is checkpointed too.
+## Durable Tools
+
+To durably checkpoint your agents' tool calls, wrap them in `durableTools`:
 
 ```ts
 import { tool, stepCountIs } from 'ai';
+import { durableTools } from '@dbos-inc/vercel-ai';
 import { z } from 'zod';
 
+const tools = durableTools({
+  getWeather: tool({
+    description: 'Get the weather for a city',
+    inputSchema: z.object({ city: z.string() }),
+    execute: ({ city }) => fetchWeather(city),
+  }),
+});
+
 const agent = DBOS.registerWorkflow(async (question: string) => {
-  const result = await generateText({
-    model,
-    prompt: question,
-    tools: {
-      getWeather: tool({
-        description: 'Get the weather for a city',
-        inputSchema: z.object({ city: z.string() }),
-        execute: ({ city }) => DBOS.runStep(() => fetchWeather(city), { name: 'getWeather' }),
-      }),
-    },
-    stopWhen: stepCountIs(10),
-  });
+  const result = await generateText({ model, prompt: question, tools, stopWhen: stepCountIs(10) });
   return result.text;
 }, { name: 'weatherAgent' });
 ```
 
-### MCP tools
+You can pass step configuration (such as timeouts or retries) to `durableTools`.
+You can set defaults for all tools or configure tools individually.
+Retries are off by default.
 
-`durableMCPTools` wraps an [MCP](https://modelcontextprotocol.io/) client (e.g. from [`@ai-sdk/mcp`](https://www.npmjs.com/package/@ai-sdk/mcp)) so both the tool listing and every tool call run as durable steps.
-Each tool call is checkpointed so recovery replays results instead of re-invoking the tool:
+```ts
+const tools = durableTools(myTools, {
+  timeoutMS: 30_000,
+  tools: {
+    getWeather: { retriesAllowed: true, maxAttempts: 3 },
+  },
+});
+```
+
+When using durable tools, to ensure the ordering of parallel tool calls is consistent during recovery, do not await I/O in callbacks that run before a tool executes, such as `onToolExecutionStart`.
+
+### Durable MCP Tools
+
+`durableMCPTools` wraps an [MCP](https://modelcontextprotocol.io/) client (for example, from [`@ai-sdk/mcp`](https://www.npmjs.com/package/@ai-sdk/mcp)) so both the tool listing and every tool call run as durable steps:
 
 ```ts
 import { createMCPClient } from '@ai-sdk/mcp';
@@ -157,30 +179,34 @@ const tools = await durableMCPTools(mcpClient, {
 });
 ```
 
-## Concurrency
+## Durable Subagents
 
-Run **one durable model call at a time within a single workflow**.
-DBOS requires workflows to be deterministic, but the AI SDK issues concurrent model calls in nondeterministic order.
-To guard against nondeterminism, this integration throws an error if it detects concurrent durable model calls in the same workflow.
-Sequential calls (including a normal tool-calling loop, where each model call completes before the next begins) are unaffected.
-
-To fan out model calls in parallel, give each its own **child workflow**:
+You can delegate complex tasks to **subagents**, which act as tools for their "parent" agent.
+To create a durable subagent, wrap your agent in `agentTool`, then pass it into `durableTools` just like any other tool:
 
 ```ts
-const summarizeOne = DBOS.registerWorkflow(
-  async (doc: string) => (await generateText({ model, prompt: `Summarize: ${doc}` })).text,
-  { name: 'summarizeOne' },
-);
+import { ToolLoopAgent } from 'ai';
+import { agentTool, durableTools } from '@dbos-inc/vercel-ai';
 
-const summarizeAll = DBOS.registerWorkflow(async (docs: string[]) => {
-  const handles = await Promise.all(
-    docs.map((doc) => DBOS.startWorkflow(summarizeOne)(doc)),
-  );
-  return Promise.all(handles.map((h) => h.getResult()));
-}, { name: 'summarizeAll' });
+const researcher = new ToolLoopAgent({ model, instructions: 'Research thoroughly.', tools: researchTools });
+
+const research = agentTool({
+  name: 'research',                          // subagent name
+  description: 'Research a question in depth',
+  inputSchema: z.object({ question: z.string() }),
+  agent: researcher,
+  prompt: ({ question }) => question,        // tool input → prompt (or ModelMessage[])
+});
+
+const tools = durableTools({ research, getWeather }, { durableStream: 'ui' });
+const orchestrator = new ToolLoopAgent({ model, tools });
 ```
 
-## Embeddings
+Internally, subagents are implemented as child workflows of the parent agent workflow, so each call has its own checkpoints and parallel calls are safe.
+Call `agentTool` before `DBOS.launch()`, since it registers that workflow.
+By default, the tool returns the subagent's final text; you can configure this with the `output` parameter.
+
+## Durable Embedding Models
 
 `durableEmbeddingCalls` enables durable calls to embedding models:
 
@@ -193,12 +219,10 @@ const embeddingModel = wrapEmbeddingModel({
   middleware: durableEmbeddingCalls({ retriesAllowed: true }),
 });
 
-const { embeddings } = await embedMany({ model: embeddingModel, values: chunks, maxParallelCalls: 1 });
+const { embeddings } = await embedMany({ model: embeddingModel, values: chunks });
 ```
 
-Pass `maxParallelCalls: 1` when embedding more values than the model's per-call limit. `embedMany` otherwise splits the input into batches and runs them concurrently, which the concurrency guard rejects (their step order would be nondeterministic on replay); `maxParallelCalls: 1` runs the batches sequentially, keeping them durable and replay-safe.
-
-## Images
+## Durable Image Models
 
 `durableImageCalls` makes image generation durable:
 

package/dist/agent-tool.d.ts

@@ -0,0 +1,42 @@
+import type { FlexibleSchema, ModelMessage, Tool } from 'ai' with { 'resolution-mode': 'import' };
+/** Marks a tool built by agentTool: durableTools leaves it unwrapped (it is a child workflow, not a step) and binds its durable stream. */
+export declare const AGENT_TOOL: unique symbol;
+type StreamingAgent = {
+    stream(options: {
+        prompt: string;
+    } | {
+        messages: ModelMessage[];
+    }): PromiseLike<{
+        consumeStream(): PromiseLike<void>;
+        readonly text: PromiseLike<string>;
+    }>;
+};
+export interface AgentToolOptions<INPUT, AGENT extends StreamingAgent, OUTPUT> {
+    /** Name of the child workflow; must be unique. */
+    name: string;
+    description: string;
+    inputSchema: FlexibleSchema<INPUT>;
+    agent: AGENT;
+    /** Turns the tool's input into the sub-agent's prompt. */
+    prompt: (input: INPUT) => string | ModelMessage[];
+    /** Turns the sub-agent's result into the tool's output (default: its final text); must be serializable. */
+    output?: (result: Awaited<ReturnType<AGENT['stream']>>) => OUTPUT | Promise<OUTPUT>;
+    /** Record the call in this durable stream: a `data-dbos-subagent` part naming the child workflow, then its output. */
+    durableStream?: string;
+    /** Name of a DBOS queue to run each child on, e.g. to bound how many sub-agents run at once. */
+    queue?: string;
+    /** Workflow timeout for each child. */
+    timeoutMS?: number;
+}
+export type AgentTool<INPUT, OUTPUT> = Tool<INPUT, OUTPUT> & {
+    /** The registered child workflow; call it directly to run the sub-agent without a model in the loop. */
+    workflow: (input: INPUT) => Promise<OUTPUT>;
+};
+/**
+ * Wraps an agent as a tool whose every call runs as a child workflow: durable at model-call granularity, with its own
+ * concurrency guard, safe to call in parallel, and visible as a child in the parent's step list. Call it at module load,
+ * before `DBOS.launch()`, since it registers the child workflow.
+ */
+export declare function agentTool<INPUT, AGENT extends StreamingAgent, OUTPUT = string>(options: AgentToolOptions<INPUT, AGENT, OUTPUT>): AgentTool<INPUT, OUTPUT>;
+export {};
+//# sourceMappingURL=agent-tool.d.ts.map

package/dist/agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.d.ts","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,IAAI,CAAC,OAAO,iBAAiB,EAAE,QAAQ,EAAE,CAAC;AAIlG,2IAA2I;AAC3I,eAAO,MAAM,UAAU,EAAE,OAAO,MAAoD,CAAC;AAkBrF,KAAK,cAAc,GAAG;IACpB,MAAM,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG;QAAE,QAAQ,EAAE,YAAY,EAAE,CAAA;KAAE,GAAG,WAAW,CAAC;QAAE,aAAa,IAAI,WAAW,CAAC,IAAI,CAAC,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAAE,CAAC,CAAC;CAC7J,CAAC;AAEF,MAAM,WAAW,gBAAgB,CAAC,KAAK,EAAE,KAAK,SAAS,cAAc,EAAE,MAAM;IAC3E,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,cAAc,CAAC,KAAK,CAAC,CAAC;IACnC,KAAK,EAAE,KAAK,CAAC;IACb,0DAA0D;IAC1D,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,MAAM,GAAG,YAAY,EAAE,CAAC;IAClD,2GAA2G;IAC3G,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpF,sHAAsH;IACtH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,gGAAgG;IAChG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,SAAS,CAAC,KAAK,EAAE,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IAC3D,wGAAwG;IACxG,QAAQ,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,SAAS,cAAc,EAAE,MAAM,GAAG,MAAM,EAC5E,OAAO,EAAE,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,GAC9C,SAAS,CAAC,KAAK,EAAE,MAAM,CAAC,CAa1B"}

package/dist/agent-tool.js

@@ -0,0 +1,92 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AGENT_TOOL = void 0;
+exports.agentTool = agentTool;
+const node_async_hooks_1 = require("node:async_hooks");
+const dbos_sdk_1 = require("@dbos-inc/dbos-sdk");
+const durable_stream_1 = require("./durable-stream");
+const internal_1 = require("./internal");
+/** Marks a tool built by agentTool: durableTools leaves it unwrapped (it is a child workflow, not a step) and binds its durable stream. */
+exports.AGENT_TOOL = Symbol.for('@dbos-inc/vercel-ai/agentTool');
+// Captured at module load, outside any workflow: a cancellation triggered by an abort must not claim a function id in the parent's log.
+const outsideWorkflow = node_async_hooks_1.AsyncLocalStorage.snapshot();
+// The child's row appears shortly after the call starts and a cancel of a missing row is a no-op, so wait for it, giving up once the call has settled.
+async function cancelChild(childID, settled) {
+    for (let i = 0; i < 100 && !settled(); i++) {
+        if (await dbos_sdk_1.DBOS.getWorkflowStatus(childID)) {
+            // The child's own sub-agents are its children; without the cascade they would run on with nobody awaiting them.
+            await dbos_sdk_1.DBOS.cancelWorkflow(childID, { cancelChildren: true });
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    }
+}
+/**
+ * Wraps an agent as a tool whose every call runs as a child workflow: durable at model-call granularity, with its own
+ * concurrency guard, safe to call in parallel, and visible as a child in the parent's step list. Call it at module load,
+ * before `DBOS.launch()`, since it registers the child workflow.
+ */
+function agentTool(options) {
+    const { name, agent, prompt, output } = options;
+    const run = async (input) => {
+        const request = prompt(input);
+        // stream, not generate: only streamed calls write to a durable stream.
+        const result = await agent.stream(typeof request === 'string' ? { prompt: request } : { messages: request });
+        await result.consumeStream();
+        return output ? await output(result) : (await result.text);
+    };
+    const registered = dbos_sdk_1.DBOS.registerWorkflow(run, { name });
+    // Unbound on purpose: DBOS's registered invoker reads `this`, and as a method `this` would be the tool object.
+    const workflow = (input) => registered(input);
+    return build(options, registered, workflow, options.durableStream);
+}
+function build(options, registered, workflow, durableStream) {
+    const { name, description, inputSchema, queue, timeoutMS } = options;
+    const execute = async (input, execOptions) => {
+        if (!(0, internal_1.isInWorkflowFunction)())
+            return workflow(input);
+        const { toolCallId } = execOptions;
+        // The tool call id comes from the checkpointed model output, so the child id is the same on replay and known for cancellation.
+        const childID = `${dbos_sdk_1.DBOS.workflowID}-${toolCallId}`;
+        // Start and getResult each reserve their function id synchronously here, so parallel calls replay in order.
+        const started = dbos_sdk_1.DBOS.startWorkflow(registered, { workflowID: childID, queueName: queue, timeoutMS })(input);
+        const pending = dbos_sdk_1.DBOS.getResult(childID);
+        started.catch(() => { });
+        pending.catch(() => { });
+        let settled = false;
+        const cancel = () => void outsideWorkflow(() => cancelChild(childID, () => settled)).catch(() => { });
+        execOptions.abortSignal?.addEventListener('abort', cancel, { once: true });
+        if (execOptions.abortSignal?.aborted)
+            cancel();
+        try {
+            if (durableStream) {
+                await (0, durable_stream_1.writeDurableStream)(durableStream, [
+                    { type: 'data-dbos-subagent', id: toolCallId, data: { toolCallId, workflowID: childID, name } },
+                ]);
+            }
+            await started;
+            const result = (await pending);
+            // A tool record, not a raw chunk, so the reader masks a sub-agent's error text like any other tool's.
+            if (durableStream)
+                await (0, durable_stream_1.writeToolRecord)(durableStream, toolCallId, { output: result });
+            return result;
+        }
+        catch (error) {
+            if (durableStream)
+                await (0, durable_stream_1.writeToolRecord)(durableStream, toolCallId, { errorText: error instanceof Error ? error.message : String(error) });
+            throw error;
+        }
+        finally {
+            settled = true;
+            execOptions.abortSignal?.removeEventListener('abort', cancel);
+        }
+    };
+    return {
+        description,
+        inputSchema,
+        execute,
+        workflow,
+        [exports.AGENT_TOOL]: (key) => build(options, registered, workflow, key),
+    };
+}
+//# sourceMappingURL=agent-tool.js.map

package/dist/agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.js","sourceRoot":"","sources":["../src/agent-tool.ts"],"names":[],"mappings":"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"}

package/dist/durable-stream.d.ts

@@ -0,0 +1,112 @@
+import type { UIMessageChunk } from 'ai' with { 'resolution-mode': 'import' };
+import type { LanguageModelV4FinishReason, LanguageModelV4StreamPart } from '@ai-sdk/provider' with { 'resolution-mode': 'import' };
+/** Durable stream config: the DBOS stream key, or the key plus batching limits for the model step's writes. */
+export type DurableStreamOptions = string | {
+    key: string;
+    maxBatchParts?: number;
+    maxBatchDelayMs?: number;
+};
+/** One DBOS stream value; the reader turns these into AI SDK UI message chunks. */
+export type DurableStreamRecord = {
+    kind: 'model';
+    step: number;
+    attempt: string;
+    parts: LanguageModelV4StreamPart[];
+} | {
+    kind: 'model-end';
+    step: number;
+    attempt: string;
+    finishReason?: LanguageModelV4FinishReason;
+    aborted?: true;
+} | {
+    kind: 'tool';
+    step: number;
+    attempt: number;
+    toolCallId: string;
+    output?: unknown;
+    errorText?: string;
+} | {
+    kind: 'ui';
+    step?: number;
+    attempt?: number;
+    chunks: UIMessageChunk[];
+} | {
+    kind: 'end';
+    finishReason: string;
+};
+interface ResolvedDurableStream {
+    key: string;
+    maxBatchParts: number;
+    maxBatchDelayMs: number;
+}
+export declare function resolveDurableStream(options: DurableStreamOptions | undefined): ResolvedDurableStream | undefined;
+/** Batches a live model step's parts into step-scope stream writes; nothing is written on replay because the step body does not run. */
+export declare class ModelStreamWriter {
+    private readonly config;
+    private pending;
+    private chain;
+    private failure;
+    private timer;
+    private readonly step;
+    private readonly attempt;
+    constructor(config: ResolvedDurableStream);
+    push(part: LanguageModelV4StreamPart): void;
+    /** Flushes, records how the call ended, and resolves once every write is durable; a write that failed after retries fails the call here. */
+    end(outcome: {
+        finishReason: LanguageModelV4FinishReason;
+    } | {
+        aborted: true;
+    }): Promise<void>;
+    /** After a failure: flush what streamed so the record matches what the consumer saw; the stream's end then comes from the workflow's status. */
+    abandon(): Promise<void>;
+    private flush;
+    private write;
+}
+/** Records a tool call's outcome from inside its step. */
+export declare function writeToolRecord(key: string, toolCallId: string, outcome: {
+    output: unknown;
+} | {
+    errorText: string;
+}): Promise<void>;
+/**
+ * Appends UI message chunks to a durable stream. From a step the write is cheap and at-least-once, so give data parts
+ * stable ids; from workflow code it is a checkpointed step, so the number of calls must be deterministic.
+ */
+export declare function writeDurableStream(key: string, chunks: UIMessageChunk[]): Promise<void>;
+/** Marks the end of the turn explicitly and closes the stream; without it the reader infers the end from the last model call or the workflow's status. */
+export declare function closeDurableStream(key: string, finishReason?: string): Promise<void>;
+/** What the reader needs from DBOS: the `DBOS` class in a launched process, or a `DBOSClient` anywhere else. */
+export interface DurableStreamSource {
+    readStream<T>(workflowID: string, key: string, options?: {
+        offset?: number;
+    }): AsyncGenerator<T, void, unknown>;
+    readStreamOffset<T>(workflowID: string, key: string, offset: number, options?: {
+        timeoutSeconds?: number;
+    }): Promise<T>;
+    retrieveWorkflow(workflowID: string): {
+        getStatus(): Promise<{
+            status: string;
+            error?: unknown;
+        } | null>;
+    };
+}
+export interface ReadDurableStreamOptions {
+    workflowID: string;
+    key: string;
+    /** Id for the `start` chunk; omitted on a resume (`offset` > 0). */
+    messageId?: string;
+    /** Number of records already consumed, from the last `data-dbos-offset` chunk. */
+    offset?: number;
+    /** Defaults to `DBOS`; pass a `DBOSClient` to read from a process that has not launched DBOS. */
+    client?: DurableStreamSource;
+    /** Emit reasoning parts (default true, as in the AI SDK). */
+    sendReasoning?: boolean;
+    /** Emit source parts (default false, as in the AI SDK). */
+    sendSources?: boolean;
+    /** Text sent to clients for a workflow or tool error; defaults to a generic message, as in the AI SDK, so server details stay private. */
+    onError?: (error: unknown) => string;
+}
+/** Reads a durable stream as AI SDK UI message chunks, live or after the fact, resuming from `offset`. */
+export declare function readDurableStream(options: ReadDurableStreamOptions): ReadableStream<UIMessageChunk>;
+export {};
+//# sourceMappingURL=durable-stream.d.ts.map

package/dist/durable-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-stream.d.ts","sourceRoot":"","sources":["../src/durable-stream.ts"],"names":[],"mappings":"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"}