@ably/ai-transport 0.1.0 → 0.2.0

package/dist/vercel/codec/decoder.d.ts

@@ -1,22 +1,9 @@
 import { DecoderCoreOptions } from '../../core/codec/decoder.js';
-import { StreamDecoder } from '../../core/codec/types.js';
+import { Decoder } from '../../core/codec/types.js';
+import { VercelInput, VercelOutput } from './events.js';
 /**
- * Vercel AI SDK Decoder
- *
- * Maps Ably inbound messages to DecoderOutput<UIMessageChunk, UIMessage>[].
- *
- * Delegates action dispatch and serial tracking to the decoder core.
- * This file contains only the Vercel-specific event building, discrete
- * event decoding, and synthetic event emission.
- *
- * Domain-specific headers use the `x-domain-` prefix. Transport-level
- * headers use the `x-ably-` prefix.
- */
-import type * as AI from 'ai';
-/**
- * Create a Vercel AI SDK decoder that maps Ably messages to UIMessageChunk
- * events and UIMessage objects via the decoder core.
+ * Create a Vercel AI SDK decoder that maps Ably messages to {@link DecodedMessage}.
  * @param options - Decoder configuration (callbacks, logger).
- * @returns A {@link StreamDecoder} for UIMessageChunk/UIMessage.
+ * @returns A {@link Decoder} typed in both directions for the Vercel codec.
  */
-export declare const createDecoder: (options?: DecoderCoreOptions) => StreamDecoder<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createDecoder: (options?: DecoderCoreOptions) => Decoder<VercelInput, VercelOutput>;

package/dist/vercel/codec/encoder.d.ts

@@ -1,41 +1,11 @@
 import { EncoderCoreOptions } from '../../core/codec/encoder.js';
-import { ChannelWriter, StreamEncoder } from '../../core/codec/types.js';
+import { ChannelWriter, Encoder } from '../../core/codec/types.js';
+import { VercelInput, VercelOutput } from './events.js';
 /**
- * Vercel AI SDK Encoder
- *
- * Maps UIMessageChunk events and complete UIMessage objects to Ably channel
- * operations (publish, appendMessage, updateMessage).
- *
- * Delegates the message append lifecycle (publish, append, close, abort,
- * flush/recover) to the encoder core. This file contains only the
- * Vercel-specific event-to-operation mapping.
- *
- * Domain-specific headers use the `x-domain-` prefix to distinguish them
- * from transport-level `x-ably-` headers.
- *
- * ## Core operations and domain headers
- *
- * Each UIMessageChunk maps to exactly one encoder core operation. Domain
- * headers are passed to every operation that accepts them — the core handles
- * merging, persistence, and deduplication:
- *
- * - **`startStream`**: Opens a message stream. Domain headers become
- *   "persistent headers" — the core repeats them on every subsequent append.
- * - **`appendStream`**: Appends a text delta. Data only, no headers parameter.
- *   The core automatically carries persistent headers from start.
- * - **`closeStream`**: Closes the stream. Pass all domain headers from the
- *   chunk — the core merges them on top of persistent headers, so changed
- *   values (e.g. updated providerMetadata) are picked up and unchanged
- *   values are harmlessly deduplicated.
- * - **`publishDiscrete`**: Publishes a standalone message. All domain headers
- *   for the chunk are passed directly.
- */
-import type * as AI from 'ai';
-/**
- * Create a Vercel AI SDK encoder that maps UIMessageChunk events to Ably
- * channel operations via the encoder core.
+ * Create a Vercel AI SDK encoder that maps VercelInput / VercelOutput to
+ * Ably channel operations via the encoder core.
  * @param writer - The channel writer to publish messages through.
  * @param options - Encoder configuration (clientId, extras, hooks, logger).
- * @returns A {@link StreamEncoder} for UIMessageChunk/UIMessage.
+ * @returns An {@link Encoder} typed in both directions for the Vercel codec.
  */
-export declare const createEncoder: (writer: ChannelWriter, options?: EncoderCoreOptions) => StreamEncoder<AI.UIMessageChunk, AI.UIMessage>;
+export declare const createEncoder: (writer: ChannelWriter, options?: EncoderCoreOptions) => Encoder<VercelInput, VercelOutput>;

package/dist/vercel/codec/events.d.ts

@@ -0,0 +1,51 @@
+import { Regenerate, ToolApprovalResponse, ToolResult, ToolResultError, UserMessage } from '../../core/codec/types.js';
+/**
+ * Vercel codec input/output unions.
+ *
+ * The codec splits cleanly along the protocol's `ai-input` / `ai-output`
+ * wire seam:
+ *
+ * - **`VercelOutput`** = `AI.UIMessageChunk` — the AI SDK's streamed-output
+ *   domain model, published by the agent on `ai-output`.
+ * - **`VercelInput`** = a discriminated union of the SDK's well-known
+ *   input shapes — published by the client on `ai-input`. The Vercel
+ *   codec has no codec-local input variants today: every variant comes
+ *   from `@ably/ai-transport`'s well-known set.
+ */
+import type * as AI from 'ai';
+/** Vercel domain payload for a {@link ToolResult}. */
+export interface VercelToolResultPayload {
+    /** The tool call this result corresponds to. */
+    toolCallId: string;
+    /** The tool's output value. Tool-defined shape. */
+    output: unknown;
+}
+/** Vercel domain payload for a {@link ToolResultError}. */
+export interface VercelToolResultErrorPayload {
+    /** The tool call this error corresponds to. */
+    toolCallId: string;
+    /** Human-readable description of the failure. */
+    message: string;
+}
+/** Vercel domain payload for a {@link ToolApprovalResponse}. */
+export interface VercelToolApprovalResponsePayload {
+    /** The tool call this approval responds to. */
+    toolCallId: string;
+    /** Whether the user approved the tool execution. */
+    approved: boolean;
+    /** Optional human-readable reason (typically used on denial). */
+    reason?: string;
+}
+/**
+ * The Vercel codec's `TInput` — every record-shape a client publishes on
+ * the `ai-input` wire. Composed from the SDK's well-known input shapes,
+ * with the tool variants parameterized by the Vercel domain payloads above.
+ */
+export type VercelInput = UserMessage<AI.UIMessage> | Regenerate | ToolResult<VercelToolResultPayload> | ToolResultError<VercelToolResultErrorPayload> | ToolApprovalResponse<VercelToolApprovalResponsePayload>;
+/**
+ * The Vercel codec's `TOutput` — every record-shape the agent publishes
+ * on the `ai-output` wire. The Vercel codec passes the AI SDK's
+ * `UIMessageChunk` through unchanged.
+ */
+export type VercelOutput = AI.UIMessageChunk;
+export type { VercelProjection } from './reducer.js';

package/dist/vercel/codec/index.d.ts

@@ -1,22 +1,34 @@
-import { Codec } from '../../core/codec/types.js';
+import { VercelInput, VercelOutput, VercelToolApprovalResponsePayload, VercelToolResultErrorPayload, VercelToolResultPayload } from './events.js';
+import { VercelProjection } from './reducer.js';
 /**
- * Vercel AI SDK codec — maps UIMessageChunk events and UIMessage objects
- * to/from native Ably message primitives (publish, append, update, delete).
+ * Vercel AI SDK codec — implements
+ * `Codec<VercelInput, VercelOutput, VercelProjection, UIMessage>`.
+ *
+ * The codec is the reducer (extends `Reducer<VercelInput | VercelOutput,
+ * VercelProjection>`) plus encoder/decoder factories and `getMessages`
+ * for Tree population.
  *
  * ```ts
  * import { UIMessageCodec } from '@ably/ai-transport/vercel';
  *
  * const encoder = UIMessageCodec.createEncoder(writer, options);
  * const decoder = UIMessageCodec.createDecoder();
- * const accumulator = UIMessageCodec.createAccumulator();
+ * const projection = UIMessageCodec.init();
  * ```
  */
 import type * as AI from 'ai';
-/**
- * Vercel AI SDK codec implementing `Codec<UIMessageChunk, UIMessage>`.
- *
- * Provides factory methods for creating encoders, decoders, and accumulators
- * that map between Vercel's UIMessageChunk/UIMessage types and Ably's native
- * message primitives.
- */
-export declare const UIMessageCodec: Codec<AI.UIMessageChunk, AI.UIMessage>;
+export declare const UIMessageCodec: {
+    adapterTag: "vercel-ai-sdk-ui-message";
+    init: () => VercelProjection;
+    fold: (state: VercelProjection, event: VercelInput | VercelOutput, meta: import('../../core/codec/types.js').ReducerMeta) => VercelProjection;
+    createEncoder: (writer: import('../../core/codec/types.js').ChannelWriter, options?: import('../../index.js').EncoderCoreOptions) => import('../../core/codec/types.js').Encoder<VercelInput, VercelOutput>;
+    createDecoder: (options?: import('../../index.js').DecoderCoreOptions) => import('../../core/codec/types.js').Decoder<VercelInput, VercelOutput>;
+    getMessages: (projection: VercelProjection) => import('../../core/codec/types.js').CodecMessage<AI.UIMessage>[];
+    createUserMessage: (message: AI.UIMessage) => VercelInput;
+    createRegenerate: (target: string, parent: string) => VercelInput;
+    createToolResult: (codecMessageId: string, payload: VercelToolResultPayload) => VercelInput;
+    createToolResultError: (codecMessageId: string, payload: VercelToolResultErrorPayload) => VercelInput;
+    createToolApprovalResponse: (codecMessageId: string, payload: VercelToolApprovalResponsePayload) => VercelInput;
+};
+export type { VercelInput, VercelOutput } from './events.js';
+export { type VercelProjection } from './reducer.js';

package/dist/vercel/codec/reducer.d.ts

@@ -0,0 +1,144 @@
+import { CodecMessage, ReducerMeta } from '../../core/codec/types.js';
+import { VercelInput, VercelOutput } from './events.js';
+/**
+ * Vercel AI SDK reducer.
+ *
+ * Pure `(init, fold)` over the `VercelInput | VercelOutput` union. Folds
+ * input variants (user-message, tool-result, tool-result-error,
+ * tool-approval-response) and `UIMessageChunk` outputs into a
+ * VercelProjection holding `UIMessage[]` plus internal stream-tracker
+ * state.
+ *
+ * The reducer is stateless: every fold is `(state, event, meta) → state'`,
+ * with no instance state. Mutation in place is allowed — the projection
+ * is single-owner.
+ *
+ * Idempotency is **per conflict key**, not stream-wide: when two events
+ * compete for the same logical state (e.g. two `tool-output-available`
+ * for the same `toolCallId`), the higher-serial one wins and the other
+ * is dropped. Unrelated events arrive freely in any order. See
+ * `_conflictKeyOf` for the per-variant key derivation.
+ *
+ * Client-published tool resolutions (`ToolResult`, `ToolResultError`,
+ * `ToolApprovalResponse`) carry `codecMessageId` targeting the assistant
+ * they amend; the reducer applies the resolution onto that assistant's
+ * `dynamic-tool` part directly. If the assistant has not yet arrived in
+ * the projection (out-of-order delivery), the resolution is buffered in
+ * `pendingToolResolutions` and re-evaluated on each subsequent fold.
+ */
+import type * as AI from 'ai';
+/**
+ * Tracks an in-progress tool part within a UIMessage. Text and reasoning
+ * parts don't need this — we write to them directly via partIndex. Tool
+ * parts need an extra `inputText` buffer because deltas arrive as raw
+ * JSON fragments that must be accumulated before parsing.
+ */
+interface ToolPartTracker {
+    /** Index in the message's parts array. */
+    partIndex: number;
+    /** Accumulated streaming input text (for JSON parsing on completion). */
+    inputText: string;
+}
+/** Per-codecMessageId tracking state for in-progress streams within a UIMessage. */
+interface MessageTrackers {
+    /** Text stream id → partIndex. */
+    text: Map<string, number>;
+    /** Reasoning stream id → partIndex. */
+    reasoning: Map<string, number>;
+    /** Tool call id → tracker. */
+    tools: Map<string, ToolPartTracker>;
+}
+/**
+ * The per-Run state produced by the Vercel codec's reducer.
+ *
+ * The SDK reads only `messages` (via `Codec.getMessages`). The remaining
+ * fields are internal to the reducer; they happen to live on the
+ * projection because the projection is the only thing the reducer can
+ * carry from fold to fold (it has no instance state).
+ */
+export interface VercelProjection {
+    /**
+     * UIMessages produced or modified in this Run, in publication order,
+     * each paired with its codec-message-id. The reducer correlates strictly
+     * on `codecMessageId`; `message.id` is preserved verbatim from the source
+     * (the AI SDK stream's `start.messageId` for assistants, the caller's id
+     * for user messages) and is never used as an identity key.
+     */
+    messages: CodecMessage<AI.UIMessage>[];
+    /**
+     * Per-conflict-key high-water-marks. Maps a codec-derived conflict key
+     * (see `_conflictKeyOf`) to the highest `meta.serial` already folded for
+     * that key. Events whose serial is `<=` the stored value are dropped as
+     * duplicates of an already-incorporated operation. Events that have no
+     * conflict key (additive content, lifecycle markers) are folded
+     * unconditionally.
+     */
+    conflictSerials: Map<string, string>;
+    /** Per-codecMessageId tracker state for streamed parts. Internal — do not access. */
+    trackers: Map<string, MessageTrackers>;
+    /**
+     * Tool-resolution events that arrived before any assistant in this
+     * projection had a matching `toolCallId`. Re-evaluated on every
+     * subsequent fold so that an out-of-order tool output is folded as
+     * soon as the corresponding assistant lands.
+     */
+    pendingToolResolutions: PendingToolResolution[];
+}
+/**
+ * A buffered tool resolution waiting for its assistant message to arrive.
+ * The reducer scans pending entries after every successful fold so an
+ * out-of-order tool output is promoted as soon as the matching assistant
+ * is added to the projection.
+ */
+interface PendingToolResolution {
+    /** The codec-message-id of the assistant the resolution targets. */
+    targetCodecMessageId: string;
+    /** Tool call this resolution targets. */
+    toolCallId: string;
+    /** Serial of the wire message — used by the conflict-key check on promotion. */
+    serial: string;
+    /** Variant of the tool-resolution used to transition the assistant's tool part. */
+    resolution: {
+        kind: 'tool-result';
+        output: unknown;
+    } | {
+        kind: 'tool-result-error';
+        message: string;
+    } | {
+        kind: 'tool-approval-response';
+        approved: boolean;
+        reason?: string;
+    };
+}
+/**
+ * Build an empty initial projection.
+ * @returns A fresh VercelProjection with no messages and no tracker state.
+ */
+export declare const init: () => VercelProjection;
+/**
+ * Fold one input or output event into the projection. Mutates and returns
+ * `state`.
+ *
+ * Idempotency is per conflict key (see `_conflictKeyOf`): if the event has
+ * a conflict key and the projection has already folded an event for that
+ * key at a higher-or-equal serial, this call is a no-op. Events without a
+ * conflict key (additive content, lifecycle markers) are folded
+ * unconditionally. Orphan events (e.g. tool-output for an unknown
+ * toolCallId) are dropped silently inside the per-variant fold helpers.
+ * @param state - Projection to fold into (may be mutated in place).
+ * @param event - Input or output event to fold.
+ * @param meta - Transport-derived metadata (serial, optional messageId).
+ * @returns The same projection reference, possibly mutated.
+ */
+export declare const fold: (state: VercelProjection, event: VercelInput | VercelOutput, meta: ReducerMeta) => VercelProjection;
+/**
+ * Extract the UIMessage list from a projection, each paired with its
+ * codec-message-id. Client-published tool resolutions amend existing
+ * assistants in place via `kind: 'tool-result'` etc. — they never
+ * materialise as their own UIMessage in the projection, so no filtering is
+ * needed here.
+ * @param projection - Projection produced by `init` + repeated `fold` calls.
+ * @returns The visible messages with their codec-message-ids, in publication order.
+ */
+export declare const getMessages: (projection: VercelProjection) => CodecMessage<AI.UIMessage>[];
+export {};

package/dist/vercel/codec/tool-transitions.d.ts

@@ -1,8 +1,8 @@
 /**
  * Shared tool part transition logic for the Vercel AI SDK codec.
  *
- * Extracted from the accumulator so the tool output state transition logic
- * lives in one place, reusable by the accumulator and any other callers.
+ * Keeps the tool output state transition logic in one place, reusable by the
+ * Vercel codec reducer and any other callers.
  */
 import type * as AI from 'ai';
 /** The set of UIMessageChunk types that represent tool output transitions. */

package/dist/vercel/index.d.ts

@@ -1,6 +1,5 @@
+export type { VercelInput, VercelOutput, VercelProjection } from './codec/index.js';
 export { UIMessageCodec } from './codec/index.js';
-export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext, VercelClientTransportOptions, VercelServerTransportOptions, } from './transport/index.js';
-export { createChatTransport, createClientTransport, createServerTransport } from './transport/index.js';
-export { applyToolEventsToHistory } from './tool-events.js';
-export type { PrepareApprovalTurnOptions, PrepareApprovalTurnResult, StreamResponseWithApprovalRedirectOptions, ToolApprovalDecision, } from './tool-approvals.js';
-export { applyToolApprovalsToHistory, extractApprovalDecisionsFromHistory, prepareApprovalTurn, streamResponseWithApprovalRedirect, } from './tool-approvals.js';
+export type { ChatTransport, ChatTransportOptions, SendMessagesRequestContext, VercelAgentSessionOptions, VercelClientSessionOptions, } from './transport/index.js';
+export { createAgentSession, createChatTransport, createClientSession } from './transport/index.js';
+export { vercelRunOutcome } from './run-end-reason.js';