@ably/ai-transport 0.1.0 → 0.2.0

package/src/vercel/codec/events.ts

@@ -0,0 +1,87 @@
+/**
+ * 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';
+
+import type {
+  Regenerate,
+  ToolApprovalResponse,
+  ToolResult,
+  ToolResultError,
+  UserMessage,
+} from '../../core/codec/types.js';
+
+// ---------------------------------------------------------------------------
+// Domain payloads
+//
+// The core well-known tool variants are domain-independent: the Vercel
+// layer supplies the concrete payload shapes. Tool outputs are inherently
+// tool-defined, so `output` stays `unknown` — but confined here, never in
+// the core.
+// ---------------------------------------------------------------------------
+
+/** 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;
+}
+
+// ---------------------------------------------------------------------------
+// Unions
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+
+// ---------------------------------------------------------------------------
+// Projection re-export
+// ---------------------------------------------------------------------------
+
+export type { VercelProjection } from './reducer.js';

package/src/vercel/codec/index.ts

@@ -1,35 +1,82 @@
 /**
- * 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';
 
 import type { Codec } from '../../core/codec/types.js';
-import { createAccumulator } from './accumulator.js';
 import { createDecoder } from './decoder.js';
 import { createEncoder } from './encoder.js';
+import type {
+  VercelInput,
+  VercelOutput,
+  VercelToolApprovalResponsePayload,
+  VercelToolResultErrorPayload,
+  VercelToolResultPayload,
+} from './events.js';
+import { fold, getMessages, init, type VercelProjection } from './reducer.js';
 
 /**
- * Vercel AI SDK codec implementing `Codec<UIMessageChunk, UIMessage>`.
+ * Vercel AI SDK codec implementing
+ * `Codec<VercelInput, VercelOutput, VercelProjection, UIMessage>`.
  *
- * Provides factory methods for creating encoders, decoders, and accumulators
- * that map between Vercel's UIMessageChunk/UIMessage types and Ably's native
- * message primitives.
+ * Folds `VercelInput`s and `VercelOutput`s into a `VercelProjection`
+ * carrying `UIMessage[]`. Encoder and decoder factories handle the wire
+ * mapping for both directions.
  */
-export const UIMessageCodec: Codec<AI.UIMessageChunk, AI.UIMessage> = {
+const uiMessageCodecImpl = {
+  // Internal field - picked up by registerAgent via AdapterTagHolder cast. Spec: AIT-CT1a3, AIT-ST1a3.
+  adapterTag: 'vercel-ai-sdk-ui-message' as const,
+  init,
+  fold,
   createEncoder,
   createDecoder,
-  createAccumulator,
-
-  isTerminal: (event: AI.UIMessageChunk): boolean =>
-    event.type === 'finish' || event.type === 'error' || event.type === 'abort',
+  getMessages,
+  createUserMessage: (message: AI.UIMessage): VercelInput => ({ kind: 'user-message', message }),
+  createRegenerate: (target: string, parent: string): VercelInput => ({
+    kind: 'regenerate',
+    target,
+    parent,
+  }),
+  createToolResult: (codecMessageId: string, payload: VercelToolResultPayload): VercelInput => ({
+    kind: 'tool-result',
+    codecMessageId,
+    payload,
+  }),
+  createToolResultError: (codecMessageId: string, payload: VercelToolResultErrorPayload): VercelInput => ({
+    kind: 'tool-result-error',
+    codecMessageId,
+    payload,
+  }),
+  createToolApprovalResponse: (codecMessageId: string, payload: VercelToolApprovalResponsePayload): VercelInput => ({
+    kind: 'tool-approval-response',
+    codecMessageId,
+    payload,
+  }),
 };
+
+// Validate Codec conformance via `satisfies` on the variable (no excess-property
+// check, so the internal `adapterTag` is permitted) while keeping the concrete
+// type so the codec-specific factories (createToolResult, etc.) stay callable.
+export const UIMessageCodec = uiMessageCodecImpl satisfies Codec<
+  VercelInput,
+  VercelOutput,
+  VercelProjection,
+  AI.UIMessage
+>;
+
+export type { VercelInput, VercelOutput } from './events.js';
+export { type VercelProjection } from './reducer.js';