@ably/ai-transport 0.1.0 → 0.3.0

package/src/core/codec/fields.ts

@@ -0,0 +1,193 @@
+/**
+ * Typed header-field bindings.
+ *
+ * A {@link HeaderField} binds a codec header key to its value type **once**,
+ * and exposes a symmetric {@link HeaderField.read | read} / {@link
+ * HeaderField.write | write} pair over a raw `Record<string, string>` headers
+ * record. Because a single binding drives both the encode and decode side, the
+ * header key and its value type stay in lockstep across directions — a key
+ * cannot be misspelled on one side and silently read as absent on the other.
+ *
+ * This is deliberately **not** a schema library: it is a thin bidirectional
+ * string (de)serializer over the headers record. The SDK ships no hard runtime
+ * dependencies, and a schema approach would force re-declaring peer-SDK-owned
+ * types. The four constructors cover every header value shape the codecs use:
+ *
+ * - {@link strField} — string values, optional default.
+ * - {@link boolField} — `"true"`/`"false"` booleans, optional default.
+ * - {@link jsonField} — JSON-serialized structured values.
+ * - {@link enumField} — string values validated against an allow-list with a
+ *   fallback (e.g. a finish reason).
+ *
+ * Passing a default to `strField`/`boolField` makes the field **total**: its
+ * `read` returns `V` rather than `V | undefined`, for required headers that
+ * should always decode to a concrete value.
+ */
+
+import { parseBool, parseJson } from '../../utils.js';
+
+/**
+ * A header key bound to its value type, with symmetric read/write over a raw
+ * headers record. Created via {@link strField}, {@link boolField}, {@link
+ * jsonField}, or {@link enumField}.
+ *
+ * The `key` plays a dual role in descriptor `fields` tables: it is the wire
+ * header key AND the property name the drivers read off the source object on
+ * encode and write back into the rebuilt object on decode. {@link FieldFor}
+ * enforces this — a declared field's key must name a real property of the
+ * member it lenses onto.
+ * @template V - The decoded value type this field reads and writes.
+ * @template K - The header key literal (preserved so {@link FieldFor} can match it against the member's property names).
+ */
+export interface HeaderField<V, K extends string = string> {
+  /** The raw header key this field reads from and writes to — also the source/rebuilt property name in descriptor tables. */
+  readonly key: K;
+  /**
+   * Read and decode this field's value from a headers record.
+   * @param headers - The raw codec headers record to read from.
+   * @returns The decoded value. For defaulted/validated fields this is total
+   * (the default/fallback is returned when the header is absent or invalid);
+   * otherwise `undefined` when the header is absent.
+   */
+  read(headers: Record<string, string>): V;
+  /**
+   * Encode and write this field's value into a headers record, mutating it in
+   * place. `undefined` (and `null`, for JSON values), and values whose runtime
+   * type doesn't match the field, are skipped — the key is left unset rather
+   * than written. The parameter is `unknown` (not `V`) so a field keeps `V` in
+   * a single covariant position (`read`); this lets heterogeneous fields share a
+   * `HeaderField<unknown>[]` array, which the descriptor drivers rely on. At a
+   * typed call site the caller still passes a `V`.
+   * @param headers - The headers record to mutate.
+   * @param value - The value to encode and set.
+   */
+  write(headers: Record<string, string>, value: unknown): void;
+}
+
+/**
+ * Symmetric codec for a descriptor's wire `data`. Many wire payloads are object
+ * envelopes a decode reads several chunk props out of (e.g. `{ errorText, input }`),
+ * so a single field can't model them. `encode` produces the wire data from the
+ * chunk; `decode` returns the chunk props the envelope contributes, merged into
+ * the rebuilt chunk by the driver.
+ * @template C - The narrowed chunk member.
+ */
+export interface DataCodec<C> {
+  /** Produce the wire `data` from the chunk. */
+  encode: (chunk: C) => unknown;
+  /**
+   * Extract the chunk props this envelope contributes from the wire `data`.
+   * Undefined-valued props are stripped when the driver rebuilds the object —
+   * every rebuild seam (output chunk, input payload, batch part) applies the
+   * same rule, since absent and undefined are indistinguishable on the wire.
+   */
+  decode: (data: unknown) => Partial<C>;
+}
+
+/**
+ * The header fields a descriptor may declare against member `C`. For each
+ * string-keyed property of `C`, a field is acceptable when its key IS that
+ * property name and its value type can hold the property. A mistyped key or a
+ * wrong-typed field (e.g. a `boolField` on a string property) is a compile
+ * error instead of a silently absent header.
+ * @template C - The member (chunk, payload, or part) the fields lens onto.
+ */
+export type FieldFor<C> = {
+  [K in keyof C & string]-?: HeaderField<C[K] | undefined, K>;
+}[keyof C & string];
+
+/**
+ * Bind a string-valued header field.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `string | undefined` (absent → `undefined`).
+ */
+export function strField<K extends string>(key: K): HeaderField<string | undefined, K>;
+/**
+ * Bind a string-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `string` (absent → `fallback`).
+ */
+export function strField<K extends string>(key: K, fallback: string): HeaderField<string, K>;
+export function strField<K extends string>(key: K, fallback?: string): HeaderField<string | undefined, K> {
+  return {
+    key,
+    read: (headers) => headers[key] ?? fallback,
+    write: (headers, value) => {
+      if (typeof value === 'string') headers[key] = value;
+    },
+  };
+}
+
+/**
+ * Bind a boolean-valued header field, serialized as `"true"`/`"false"`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `boolean | undefined` (absent → `undefined`).
+ */
+export function boolField<K extends string>(key: K): HeaderField<boolean | undefined, K>;
+/**
+ * Bind a boolean-valued header field with a default, making it total.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param fallback - Value returned by `read` when the header is absent.
+ * @returns A field whose `read` yields `boolean` (absent → `fallback`).
+ */
+export function boolField<K extends string>(key: K, fallback: boolean): HeaderField<boolean, K>;
+export function boolField<K extends string>(key: K, fallback?: boolean): HeaderField<boolean | undefined, K> {
+  return {
+    key,
+    read: (headers) => parseBool(headers[key]) ?? fallback,
+    write: (headers, value) => {
+      if (typeof value === 'boolean') headers[key] = String(value);
+    },
+  };
+}
+
+/**
+ * Bind a JSON-serialized header field. The value is written with
+ * `JSON.stringify` and read back with `JSON.parse`; malformed JSON reads as
+ * `undefined`. The decoded shape is a trust boundary — the caller asserts it
+ * via the `V` type parameter.
+ * @template V - The expected decoded shape of the JSON value.
+ * @template K - The header key literal. Inferred when `V` is omitted; pass it explicitly alongside `V` when the field participates in a typed descriptor `fields` table.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @returns A field whose `read` yields `V | undefined` (absent or malformed → `undefined`).
+ */
+export const jsonField = <V, K extends string = string>(key: K): HeaderField<V | undefined, K> => ({
+  key,
+  // CAST: header values are wire data parsed via JSON.parse — a trust
+  // boundary. The caller declares the expected shape through `V`; malformed
+  // JSON reads back as `undefined` (parseJson swallows the parse error).
+  read: (headers) => parseJson(headers[key]) as V | undefined,
+  write: (headers, value) => {
+    // Skip undefined and null so an absent value leaves the key unset rather
+    // than serializing to "null".
+    if (value !== undefined && value !== null) headers[key] = JSON.stringify(value);
+  },
+});
+
+/**
+ * Bind a string-valued header field validated against a fixed allow-list,
+ * falling back to a given value when the header is absent or unrecognized. Use
+ * for headers with a small closed set of valid values (e.g. a finish reason).
+ * @template T - The union of allowed string literals, inferred from `allowed`.
+ * @template K - The header key literal, inferred from `key`.
+ * @param key - The header key (and source property name in descriptor tables).
+ * @param allowed - The exhaustive list of valid values.
+ * @param fallback - Value returned by `read` when the header is absent or not in `allowed`.
+ * @returns A total field whose `read` yields one of the allowed literals.
+ */
+export const enumField = <const T extends string, K extends string>(
+  key: K,
+  allowed: readonly T[],
+  fallback: NoInfer<T>,
+): HeaderField<T, K> => ({
+  key,
+  read: (headers) => {
+    const raw = headers[key];
+    // find returns the matched literal (typed T) or undefined — no cast needed.
+    return allowed.find((candidate) => candidate === raw) ?? fallback;
+  },
+  write: (headers, value) => {
+    if (typeof value === 'string') headers[key] = value;
+  },
+});

package/src/core/codec/index.ts

@@ -1,17 +1,25 @@
-export { eventOutput } from './decoder.js';
 export type {
   ChannelWriter,
   Codec,
-  DecoderOutput,
-  DiscreteEncoder,
+  CodecEvent,
+  CodecInputEvent,
+  CodecMessage,
+  CodecOutputEvent,
+  DecodedMessage,
+  Decoder,
+  Encoder,
   EncoderOptions,
   Extras,
-  MessageAccumulator,
   MessagePayload,
-  StreamDecoder,
-  StreamEncoder,
+  Reducer,
+  ReducerMeta,
+  Regenerate,
   StreamPayload,
   StreamTrackerState,
+  ToolApprovalResponse,
+  ToolResult,
+  ToolResultError,
+  UserMessage,
   WriteOptions,
 } from './types.js';
 
@@ -26,3 +34,45 @@ export { createDecoderCore } from './decoder.js';
 // Lifecycle tracker
 export type { LifecycleTracker, PhaseConfig } from './lifecycle-tracker.js';
 export { createLifecycleTracker } from './lifecycle-tracker.js';
+
+// Typed header-field bindings
+export type { DataCodec, FieldFor, HeaderField } from './fields.js';
+export { boolField, enumField, jsonField, strField } from './fields.js';
+
+// Well-known input factories (merged into every codec by defineCodec)
+export type { WellKnownInputFactories } from './well-known-inputs.js';
+
+// Output descriptor authoring surface
+export type {
+  EscapeHatchCore,
+  HeaderBuilder,
+  OutputDecodeContext,
+  OutputDescriptor,
+  OutputEncodeHatchContext,
+  OutputEventSpec,
+  OutputStreamEndContext,
+  OutputStreamSpec,
+} from './output-descriptors.js';
+
+// Input descriptor authoring surface
+export type {
+  BatchAssembleContext,
+  BatchMessageHeaders,
+  BatchSpec,
+  InputDescriptor,
+  InputEventSpec,
+  PartBuilder,
+  PartSpec,
+} from './input-descriptors.js';
+
+// Codec composition factory
+export type {
+  CodecReducer,
+  DefineCodecConfig,
+  DefinedCodec,
+  InputBuilder,
+  LifecycleDiscreteContext,
+  LifecyclePolicy,
+  OutputBuilder,
+} from './define-codec.js';
+export { defineCodec } from './define-codec.js';

package/src/core/codec/input-descriptor-decoder.ts

@@ -0,0 +1,97 @@
+/**
+ * Generic input decode driver over an input descriptor set — the input-side
+ * sibling of {@link import('./output-descriptor-decoder.js')}.
+ *
+ * Rebuilds inputs from one inbound `ai-input` message, dispatching on the codec
+ * `kind` header. A single `event` rebuilds its field bag (and `data`) and wraps
+ * it into the `{ kind, codecMessageId, payload }` envelope; `wireOnly` events
+ * decode to `[]`. A
+ * `batch` reads the `partType` sub-discriminator, rebuilds the part via its
+ * sub-table, `assemble`s it into a one-part input, and the driver stamps the
+ * `kind` plus the codec-message-id reconstructed from the transport header.
+ *
+ * Returns bare `TInput[]`, never `CodecEvent[]` — direction tagging is
+ * core-owned, downstream at the decode→fold seam.
+ */
+
+import { HEADER_CODEC_MESSAGE_ID } from '../../constants.js';
+import { stripUndefined } from '../../utils.js';
+import { PART_TYPE_HEADER, partFor, readFields } from './field-bag.js';
+import type {
+  BatchDescriptor,
+  InputDecodeContext,
+  InputDescriptor,
+  InputEventDescriptor,
+} from './input-descriptors.js';
+
+/** Decodes inbound `ai-input` messages of union `U` from an input descriptor set. */
+export interface InputDescriptorDecoder<U> {
+  /**
+   * Rebuild zero or more inputs from one inbound `ai-input` message.
+   * @param ctx - The inbound message context (codec kind, data, header tiers).
+   * @returns The decoded inputs (empty when no descriptor matches or the input is wire-only).
+   */
+  decode(ctx: InputDecodeContext): U[];
+}
+
+/**
+ * Build an input decode driver for an input descriptor set.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @returns An {@link InputDescriptorDecoder} that reconstructs inputs from the wire.
+ */
+export const createInputDescriptorDecoder = <U extends { kind: string }>(
+  descriptors: readonly InputDescriptor<U>[],
+): InputDescriptorDecoder<U> => {
+  const byKind = new Map<string, InputDescriptor<U>>();
+  for (const descriptor of descriptors) byKind.set(descriptor.kind, descriptor);
+
+  const decodeEvent = (descriptor: InputEventDescriptor, ctx: InputDecodeContext): U[] => {
+    if (descriptor.wireOnly) return [];
+
+    const bag = readFields(descriptor.fields, ctx.codecHeaders);
+    if (descriptor.data) Object.assign(bag, descriptor.data.decode(ctx.data));
+
+    const codecMessageId = ctx.transportHeaders[HEADER_CODEC_MESSAGE_ID] ?? '';
+    // The payload bag is stripped of undefined-valued props — the same rule
+    // every rebuild seam applies to its innermost bag (absent and undefined
+    // are indistinguishable on the wire). The envelope keys are always defined.
+    // CAST: the rebuild seam — `bag` is assembled from the descriptor's declared
+    // fields and data codec onto the payload, so the `{ kind, codecMessageId, payload }`
+    // envelope conforms to the matched member by construction.
+    return [{ kind: descriptor.kind, codecMessageId, payload: stripUndefined(bag) } as unknown as U];
+  };
+
+  const decodeBatch = (descriptor: BatchDescriptor<U>, ctx: InputDecodeContext): U[] => {
+    const partType = ctx.codecHeaders[PART_TYPE_HEADER] ?? '';
+    const partDesc = partFor(descriptor.parts, partType);
+    if (!partDesc) return [];
+
+    const bag = readFields(partDesc.fields, ctx.codecHeaders);
+    if (partDesc.data) Object.assign(bag, partDesc.data.decode(ctx.data));
+    bag.type = partType;
+
+    // `assemble` takes the erased part (`unknown`); `bag` is the part rebuilt from
+    // its declared fields/data plus the `partType` written to the domain `type`
+    // field. The header tiers carry the per-message metadata (id, role, …) the
+    // batch stamped on every part, so `assemble` can rebuild the message envelope.
+    const partial = descriptor.assemble(stripUndefined(bag), {
+      codecHeaders: ctx.codecHeaders,
+      transportHeaders: ctx.transportHeaders,
+    });
+    // CAST: the driver stamps the shared `kind` onto the assembled one-part input; together
+    // they complete the matched member. A batch creates a new message (not addressed by a
+    // codec-message-id, unlike single `event`s), so none is stamped — the per-message
+    // identity rides the transport header and is recovered by `assemble` when needed.
+    return [{ kind: descriptor.kind, ...partial } as unknown as U];
+  };
+
+  return {
+    decode: (ctx) => {
+      const descriptor = byKind.get(ctx.codecKind);
+      if (!descriptor) return [];
+      if (descriptor.construct === 'event') return decodeEvent(descriptor, ctx);
+      return decodeBatch(descriptor, ctx);
+    },
+  };
+};

package/src/core/codec/input-descriptor-encoder.ts

@@ -0,0 +1,150 @@
+/**
+ * Generic input encode driver over an input descriptor set — the input-side
+ * sibling of {@link import('./output-descriptor-encoder.js')}.
+ *
+ * Builds a `kind`→descriptor registry once, then routes each input: a single
+ * `event` publishes one discrete message (fields/data lensed onto the member's
+ * `payload`, or kind-only when `wireOnly`); a `batch` explodes the domain
+ * message into one wire event per part and publishes them atomically, with a
+ * built-in ≥1-event guarantee so the codec-message-id and role survive an empty
+ * decomposition. Headers are always built through the descriptor's declared
+ * fields ({@link writeFields}), so the imperative paths can't drift.
+ */
+
+import * as Ably from 'ably';
+
+import { ErrorCode } from '../../errors.js';
+import { KIND_HEADER, PART_TYPE_HEADER, partFor, prop, writeFields } from './field-bag.js';
+import type {
+  BatchDescriptor,
+  BatchMessageHeaders,
+  InputDescriptor,
+  InputEncodeContext,
+  InputEncoderCore,
+  InputEventDescriptor,
+} from './input-descriptors.js';
+import type { MessagePayload } from './types.js';
+
+/** Encodes inputs of union `U` to channel operations via an input descriptor set. */
+export interface InputDescriptorEncoder<U> {
+  /**
+   * Encode one input through its descriptor.
+   * @param input - The input to encode.
+   * @param core - The input encoder core to publish through.
+   * @param ctx - Per-write context (write options, carrying the codec-message-id).
+   * @returns A promise resolving when the publish operation completes.
+   */
+  encode(input: U, core: InputEncoderCore, ctx: InputEncodeContext): Promise<void>;
+}
+
+// Layer the batch's per-message transport headers onto a part payload, if any.
+const withMessageTransport = (payload: MessagePayload, message: BatchMessageHeaders | undefined): MessagePayload =>
+  message?.transportHeaders === undefined
+    ? payload
+    : { ...payload, transportHeaders: { ...payload.transportHeaders, ...message.transportHeaders } };
+
+/**
+ * Build an input encode driver for an input descriptor set bound to a wire name.
+ * @template U - The codec's input union.
+ * @param descriptors - The input descriptor set (events + batches).
+ * @param wireName - The Ably message name for the input direction (`ai-input`).
+ * @returns An {@link InputDescriptorEncoder} routing each input through its descriptor.
+ */
+export const createInputDescriptorEncoder = <U extends { kind: string }>(
+  descriptors: readonly InputDescriptor<U>[],
+  wireName: string,
+): InputDescriptorEncoder<U> => {
+  const byKind = new Map<string, InputDescriptor<U>>();
+  for (const descriptor of descriptors) byKind.set(descriptor.kind, descriptor);
+
+  const encodeEvent = async (
+    descriptor: InputEventDescriptor,
+    input: U,
+    core: InputEncoderCore,
+    ctx: InputEncodeContext,
+  ): Promise<void> => {
+    if (descriptor.wireOnly) {
+      // Kind only: no fields, no data — the parent/target ride transport headers.
+      await core.publishDiscrete(
+        { name: wireName, data: '', codecHeaders: { [KIND_HEADER]: descriptor.kind } },
+        ctx.opts,
+      );
+      return;
+    }
+    // A non-wireOnly input nests its domain data under `payload` — fields and
+    // data are authored against it. Fail fast on a payload-less member instead
+    // of silently publishing empty data the decoder can't rebuild from.
+    const source = prop(input, 'payload');
+    if (typeof source !== 'object' || source === null) {
+      throw new Ably.ErrorInfo(
+        `unable to encode input; event '${descriptor.kind}' carries no payload object — declare it wireOnly or use an encode escape hatch`,
+        ErrorCode.InvalidArgument,
+        400,
+      );
+    }
+    const codecHeaders = writeFields(descriptor.fields, descriptor.kind, source);
+    const data = descriptor.data ? descriptor.data.encode(source) : '';
+    await core.publishDiscrete({ name: wireName, data, codecHeaders }, ctx.opts);
+  };
+
+  const encodeBatch = async (
+    descriptor: BatchDescriptor<U>,
+    input: U,
+    core: InputEncoderCore,
+    ctx: InputEncodeContext,
+  ): Promise<void> => {
+    // Per-message headers (e.g. message id, role) are stamped on every part so
+    // the decode side can reconstruct the shared message envelope from any one.
+    const message = descriptor.messageHeaders?.(input);
+    const payloads: MessagePayload[] = [];
+    for (const part of descriptor.explode(input)) {
+      const partType = descriptor.partTypeOf(part);
+      const partDesc = partFor(descriptor.parts, partType);
+      if (!partDesc) continue;
+      // CAST: a part is indexed by its declared fields; the part descriptor only
+      // runs against the part its predicate/literal matched, so the source has the
+      // field's type at runtime. The wire `partType` is the resolved part type.
+      const source = part as object;
+      const codecHeaders = {
+        ...writeFields(partDesc.fields, descriptor.kind, source),
+        ...message?.codecHeaders,
+        [PART_TYPE_HEADER]: partType,
+      };
+      const data = partDesc.data ? partDesc.data.encode(part) : '';
+      payloads.push(withMessageTransport({ name: wireName, data, codecHeaders }, message));
+    }
+
+    if (payloads.length === 0) {
+      // ≥1-event guarantee: emit one bare part so the per-message headers (e.g.
+      // the message id and role) reach the wire even when no exploded part
+      // matched a descriptor. This fallback carries no partType, so the batch
+      // decode path yields no input for it — a codec that needs an empty
+      // message to round-trip must guarantee ≥1 encodable part in `explode`
+      // (e.g. by substituting a canonical empty part).
+      payloads.push(
+        withMessageTransport(
+          { name: wireName, data: '', codecHeaders: { [KIND_HEADER]: descriptor.kind, ...message?.codecHeaders } },
+          message,
+        ),
+      );
+    }
+
+    await core.publishDiscreteBatch(payloads, ctx.opts);
+  };
+
+  return {
+    encode: async (input, core, ctx) => {
+      const descriptor = byKind.get(input.kind);
+      if (!descriptor) {
+        throw new Ably.ErrorInfo(
+          `unable to publish; unsupported input kind '${input.kind}'`,
+          ErrorCode.InvalidArgument,
+          400,
+        );
+      }
+      await (descriptor.construct === 'event'
+        ? encodeEvent(descriptor, input, core, ctx)
+        : encodeBatch(descriptor, input, core, ctx));
+    },
+  };
+};