@holbrookab/temporal-ai-connectors

Protocol-v2 delivery, replay, state, and AI SDK projection for Temporal AI workflows.

The package keeps provisional provider output separate from workflow-accepted state:

• preview-* events are visible immediately and remain replaceable.
• record-upsert is a complete, versioned canonical snapshot written by the workflow.
• acceptedAttemptId replaces only the exact preview that produced a record.
• stream-end closes the subscription only after a final cursor replay.

Protocol v2 is a clean break from the v1 attempt/chunk envelope. See the migration map before upgrading.

Packages

• @holbrookab/temporal-ai-connectors/core: protocol types, parsers, reducer, selectors, and subscribe-first replay.
• @holbrookab/temporal-ai-connectors/ai-sdk: AI SDK v7 transport and UIMessageChunk projection.
• @holbrookab/temporal-ai-connectors/adapters/appsync-dynamodb: AppSync live delivery and DynamoDB replay.
• @holbrookab/temporal-ai-connectors/adapters/redis-dynamodb: Redis/SSE live delivery with DynamoDB replay.
• @holbrookab/temporal-ai-connectors/vercel: environment and AWS OIDC helpers.

End-to-end streaming

import { createAppSyncTemporalUpdateChatTransport } from
  "@holbrookab/temporal-ai-connectors/adapters/appsync-dynamodb";
import {
  applyUpdateEvent,
  createUpdateState,
  selectPreviewText,
} from "@holbrookab/temporal-ai-connectors/core";

// AI SDK useChat receives data-workflow-preview immediately. It receives native
// text only after the workflow writes the accepted message record.
export const transport = createAppSyncTemporalUpdateChatTransport({
  api: "/api/chat",
});

let updates = createUpdateState("workflow-stream-id");
updates = applyUpdateEvent(updates, previewChunkFromSubscription);
console.log(selectPreviewText(updates)); // visible before durable persistence

updates = applyUpdateEvent(updates, acceptedRecordFromSubscription);
console.log(selectPreviewText(updates)); // ""; recordsById now owns the content

Applications should render canonical records and overlay selectVisiblePreviews(state) until a matching acceptedAttemptId arrives. Failed and canceled previews remain in reducer state for audit/debugging but are excluded from visible selectors.

Naming and wire contract

• TypeScript exports use PascalCase.
• JSON fields use camelCase.
• Discriminants and multiword wire values use kebab-case.
• Cursors order durable delivery; eventId is only the semantic idempotency key.

The frozen schemas and golden fixtures are in protocol/v2. See the protocol and streaming guide for reducer, replay, adapter, projection, and failure semantics.

The supported AI SDK target is ai@7 / @ai-sdk/react@4.