@warlock.js/ai-live 4.6.0

package/esm/mock/index.d.mts

@@ -0,0 +1,52 @@
+import { RealtimeConnectConfig, RealtimeConnection, RealtimeEvent, RealtimeTransport } from "../contracts/realtime.contract.mjs";
+import { GeneratedVideo, VideoGenerationResponse, VideoModelContract, VideoModelPricing, VideoOptions } from "../contracts/video.contract.mjs";
+import { Usage } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-live/src/mock/index.d.ts
+/** One scripted response for a {@link MockVideoModel}. */
+type MockVideoResponse = {
+  video?: GeneratedVideo;
+  usage?: Usage;
+  durationSeconds?: number;
+  error?: Error;
+};
+/** Deterministic {@link VideoModelContract} double for tests — no HTTP, no polling. */
+declare class MockVideoModel implements VideoModelContract {
+  readonly name: string;
+  private readonly responses;
+  readonly pricing?: VideoModelPricing | undefined;
+  readonly provider = "mock";
+  readonly calls: {
+    prompt: string;
+    options: VideoOptions | undefined;
+  }[];
+  private callIndex;
+  constructor(name: string, responses: MockVideoResponse[], pricing?: VideoModelPricing | undefined);
+  generate(prompt: string, options?: VideoOptions): Promise<VideoGenerationResponse>;
+}
+/** A recording {@link RealtimeConnection} the mock transport hands back. */
+declare class MockRealtimeConnection implements RealtimeConnection {
+  private readonly scripted;
+  readonly sentAudio: {
+    base64: string;
+    mediaType: string;
+  }[];
+  readonly sentText: string[];
+  closed: boolean;
+  constructor(scripted: RealtimeEvent[]);
+  sendAudio(base64: string, mediaType: string): void;
+  sendText(text: string): void;
+  events(): AsyncIterable<RealtimeEvent>;
+  close(): Promise<void>;
+}
+/** Deterministic {@link RealtimeTransport} double — scripts the event stream, records sends. */
+declare class MockRealtimeTransport implements RealtimeTransport {
+  private readonly scriptedEvents;
+  readonly connectConfigs: RealtimeConnectConfig[];
+  lastConnection?: MockRealtimeConnection;
+  constructor(scriptedEvents?: RealtimeEvent[]);
+  connect(config: RealtimeConnectConfig): Promise<RealtimeConnection>;
+}
+//#endregion
+export { MockRealtimeConnection, MockRealtimeTransport, MockVideoModel, MockVideoResponse };
+//# sourceMappingURL=index.d.mts.map

package/esm/mock/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/mock/index.ts"],"mappings":";;;;;;KAgBY,iBAAA;EACV,KAAA,GAAQ,cAAA;EACR,KAAA,GAAQ,KAAA;EACR,eAAA;EACA,KAAA,GAAQ,KAAA;AAAA;;cAIG,cAAA,YAA0B,kBAAA;EAAA,SAOnB,IAAA;EAAA,iBACC,SAAA;EAAA,SACD,OAAA,GAAU,iBAAA;EAAA,SARZ,QAAA;EAAA,SACA,KAAA;IAAS,MAAA;IAAgB,OAAA,EAAS,YAAA;EAAA;EAAA,QAE1C,SAAA;cAGU,IAAA,UACC,SAAA,EAAW,iBAAA,IACZ,OAAA,GAAU,iBAAA;EAGf,QAAA,CACX,MAAA,UACA,OAAA,GAAU,YAAA,GACT,OAAA,CAAQ,uBAAA;AAAA;;cAmBA,sBAAA,YAAkC,kBAAA;EAAA,iBAKT,QAAA;EAAA,SAJpB,SAAA;IAAa,MAAA;IAAgB,SAAA;EAAA;EAAA,SAC7B,QAAA;EACT,MAAA;cAE6B,QAAA,EAAU,aAAA;EAEvC,SAAA,CAAU,MAAA,UAAgB,SAAA;EAI1B,QAAA,CAAS,IAAA;EAIF,MAAA,IAAU,aAAA,CAAc,aAAA;EAMzB,KAAA,IAAS,OAAA;AAAA;;cAMX,qBAAA,YAAiC,iBAAA;EAAA,iBAIR,cAAA;EAAA,SAHpB,cAAA,EAAgB,qBAAA;EACzB,cAAA,GAAiB,sBAAA;cAEY,cAAA,GAAgB,aAAA;EAEvC,OAAA,CAAQ,MAAA,EAAQ,qBAAA,GAAwB,OAAA,CAAQ,kBAAA;AAAA"}

package/esm/mock/index.mjs

@@ -0,0 +1,74 @@
+//#region ../@warlock.js/ai-live/src/mock/index.ts
+/** Deterministic {@link VideoModelContract} double for tests — no HTTP, no polling. */
+var MockVideoModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async generate(prompt, options) {
+		this.calls.push({
+			prompt,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.error) throw response.error;
+		return {
+			video: response.video ?? {
+				type: "url",
+				url: "https://mock/video.mp4",
+				mediaType: "video/mp4"
+			},
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			},
+			durationSeconds: response.durationSeconds ?? options?.durationSeconds ?? 5
+		};
+	}
+};
+/** A recording {@link RealtimeConnection} the mock transport hands back. */
+var MockRealtimeConnection = class {
+	constructor(scripted) {
+		this.scripted = scripted;
+		this.sentAudio = [];
+		this.sentText = [];
+		this.closed = false;
+	}
+	sendAudio(base64, mediaType) {
+		this.sentAudio.push({
+			base64,
+			mediaType
+		});
+	}
+	sendText(text) {
+		this.sentText.push(text);
+	}
+	async *events() {
+		for (const event of this.scripted) yield event;
+	}
+	async close() {
+		this.closed = true;
+	}
+};
+/** Deterministic {@link RealtimeTransport} double — scripts the event stream, records sends. */
+var MockRealtimeTransport = class {
+	constructor(scriptedEvents = []) {
+		this.scriptedEvents = scriptedEvents;
+		this.connectConfigs = [];
+	}
+	async connect(config) {
+		this.connectConfigs.push(config);
+		this.lastConnection = new MockRealtimeConnection(this.scriptedEvents);
+		return this.lastConnection;
+	}
+};
+
+//#endregion
+export { MockRealtimeConnection, MockRealtimeTransport, MockVideoModel };
+//# sourceMappingURL=index.mjs.map

package/esm/mock/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/mock/index.ts"],"sourcesContent":["import type { Usage } from \"@warlock.js/ai\";\nimport type {\n  RealtimeConnectConfig,\n  RealtimeConnection,\n  RealtimeEvent,\n  RealtimeTransport,\n} from \"../contracts/realtime.contract\";\nimport type {\n  GeneratedVideo,\n  VideoGenerationResponse,\n  VideoModelContract,\n  VideoModelPricing,\n  VideoOptions,\n} from \"../contracts/video.contract\";\n\n/** One scripted response for a {@link MockVideoModel}. */\nexport type MockVideoResponse = {\n  video?: GeneratedVideo;\n  usage?: Usage;\n  durationSeconds?: number;\n  error?: Error;\n};\n\n/** Deterministic {@link VideoModelContract} double for tests — no HTTP, no polling. */\nexport class MockVideoModel implements VideoModelContract {\n  public readonly provider = \"mock\";\n  public readonly calls: { prompt: string; options: VideoOptions | undefined }[] = [];\n\n  private callIndex = 0;\n\n  public constructor(\n    public readonly name: string,\n    private readonly responses: MockVideoResponse[],\n    public readonly pricing?: VideoModelPricing,\n  ) {}\n\n  public async generate(\n    prompt: string,\n    options?: VideoOptions,\n  ): Promise<VideoGenerationResponse> {\n    this.calls.push({ prompt, options });\n\n    const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};\n    this.callIndex += 1;\n\n    if (response.error) {\n      throw response.error;\n    }\n\n    return {\n      video: response.video ?? { type: \"url\", url: \"https://mock/video.mp4\", mediaType: \"video/mp4\" },\n      usage: response.usage ?? { input: 0, output: 0, total: 0 },\n      durationSeconds: response.durationSeconds ?? options?.durationSeconds ?? 5,\n    };\n  }\n}\n\n/** A recording {@link RealtimeConnection} the mock transport hands back. */\nexport class MockRealtimeConnection implements RealtimeConnection {\n  public readonly sentAudio: { base64: string; mediaType: string }[] = [];\n  public readonly sentText: string[] = [];\n  public closed = false;\n\n  public constructor(private readonly scripted: RealtimeEvent[]) {}\n\n  public sendAudio(base64: string, mediaType: string): void {\n    this.sentAudio.push({ base64, mediaType });\n  }\n\n  public sendText(text: string): void {\n    this.sentText.push(text);\n  }\n\n  public async *events(): AsyncIterable<RealtimeEvent> {\n    for (const event of this.scripted) {\n      yield event;\n    }\n  }\n\n  public async close(): Promise<void> {\n    this.closed = true;\n  }\n}\n\n/** Deterministic {@link RealtimeTransport} double — scripts the event stream, records sends. */\nexport class MockRealtimeTransport implements RealtimeTransport {\n  public readonly connectConfigs: RealtimeConnectConfig[] = [];\n  public lastConnection?: MockRealtimeConnection;\n\n  public constructor(private readonly scriptedEvents: RealtimeEvent[] = []) {}\n\n  public async connect(config: RealtimeConnectConfig): Promise<RealtimeConnection> {\n    this.connectConfigs.push(config);\n    this.lastConnection = new MockRealtimeConnection(this.scriptedEvents);\n    return this.lastConnection;\n  }\n}\n"],"mappings":";;AAwBA,IAAa,iBAAb,MAA0D;CAMxD,AAAO,YACL,AAAgB,MAChB,AAAiB,WACjB,AAAgB,SAChB;EAHgB;EACC;EACD;kBARS;eACsD,CAAC;mBAE9D;CAMjB;CAEH,MAAa,SACX,QACA,SACkC;EAClC,KAAK,MAAM,KAAK;GAAE;GAAQ;EAAQ,CAAC;EAEnC,MAAM,WAAW,KAAK,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,UAAU,SAAS,CAAC,MAAM,CAAC;EACzF,KAAK,aAAa;EAElB,IAAI,SAAS,OACX,MAAM,SAAS;EAGjB,OAAO;GACL,OAAO,SAAS,SAAS;IAAE,MAAM;IAAO,KAAK;IAA0B,WAAW;GAAY;GAC9F,OAAO,SAAS,SAAS;IAAE,OAAO;IAAG,QAAQ;IAAG,OAAO;GAAE;GACzD,iBAAiB,SAAS,mBAAmB,SAAS,mBAAmB;EAC3E;CACF;AACF;;AAGA,IAAa,yBAAb,MAAkE;CAKhE,AAAO,YAAY,AAAiB,UAA2B;EAA3B;mBAJiC,CAAC;kBACjC,CAAC;gBACtB;CAEgD;CAEhE,AAAO,UAAU,QAAgB,WAAyB;EACxD,KAAK,UAAU,KAAK;GAAE;GAAQ;EAAU,CAAC;CAC3C;CAEA,AAAO,SAAS,MAAoB;EAClC,KAAK,SAAS,KAAK,IAAI;CACzB;CAEA,OAAc,SAAuC;EACnD,KAAK,MAAM,SAAS,KAAK,UACvB,MAAM;CAEV;CAEA,MAAa,QAAuB;EAClC,KAAK,SAAS;CAChB;AACF;;AAGA,IAAa,wBAAb,MAAgE;CAI9D,AAAO,YAAY,AAAiB,iBAAkC,CAAC,GAAG;EAAtC;wBAHsB,CAAC;CAGgB;CAE3E,MAAa,QAAQ,QAA4D;EAC/E,KAAK,eAAe,KAAK,MAAM;EAC/B,KAAK,iBAAiB,IAAI,uBAAuB,KAAK,cAAc;EACpE,OAAO,KAAK;CACd;AACF"}

package/esm/realtime/realtime.d.mts

@@ -0,0 +1,29 @@
+import { RealtimeOptions, RealtimeSession } from "../contracts/realtime.contract.mjs";
+
+//#region ../@warlock.js/ai-live/src/realtime/realtime.d.ts
+/**
+ * Open a live duplex voice session — the stateful primitive of
+ * `@warlock.js/ai-live`. Connects through the provided
+ * {@link RealtimeOptions.transport} (an OpenAI Realtime WebSocket
+ * adapter, a mock in tests), then hands back a {@link RealtimeSession}
+ * you drive: push audio/text in, consume the event stream out, and
+ * `close()` to end it and receive a `type: "realtime"` report for the
+ * cost/observability surfaces.
+ *
+ * Unlike the one-shot `ai.*` verbs, this returns a long-lived session —
+ * its closest sibling is `ai.orchestrator`. Keeping the transport
+ * pluggable is what lets the session surface ship without hard-wiring a
+ * WebSocket dependency.
+ *
+ * @example
+ * const session = await ai.realtime({ transport, model: "gpt-realtime", voice: "alloy" });
+ * session.sendAudio(micChunk, "audio/pcm");
+ * for await (const event of session.events()) {
+ *   if (event.type === "audio") speaker.write(event.base64);
+ * }
+ * const report = await session.close();
+ */
+declare function realtime(options: RealtimeOptions): Promise<RealtimeSession>;
+//#endregion
+export { realtime };
+//# sourceMappingURL=realtime.d.mts.map

package/esm/realtime/realtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/realtime/realtime.ts"],"mappings":";;;;;AA6BA;;;;;;;;;;;;;AAAiF;;;;;;;iBAA3D,QAAA,CAAS,OAAA,EAAS,eAAA,GAAkB,OAAA,CAAQ,eAAA"}

package/esm/realtime/realtime.mjs

@@ -0,0 +1,61 @@
+import { generateRunId } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-live/src/realtime/realtime.ts
+/**
+* Open a live duplex voice session — the stateful primitive of
+* `@warlock.js/ai-live`. Connects through the provided
+* {@link RealtimeOptions.transport} (an OpenAI Realtime WebSocket
+* adapter, a mock in tests), then hands back a {@link RealtimeSession}
+* you drive: push audio/text in, consume the event stream out, and
+* `close()` to end it and receive a `type: "realtime"` report for the
+* cost/observability surfaces.
+*
+* Unlike the one-shot `ai.*` verbs, this returns a long-lived session —
+* its closest sibling is `ai.orchestrator`. Keeping the transport
+* pluggable is what lets the session surface ship without hard-wiring a
+* WebSocket dependency.
+*
+* @example
+* const session = await ai.realtime({ transport, model: "gpt-realtime", voice: "alloy" });
+* session.sendAudio(micChunk, "audio/pcm");
+* for await (const event of session.events()) {
+*   if (event.type === "audio") speaker.write(event.base64);
+* }
+* const report = await session.close();
+*/
+async function realtime(options) {
+	const runId = generateRunId("realtime");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const connection = await options.transport.connect({
+		model: options.model,
+		voice: options.voice,
+		instructions: options.instructions
+	});
+	let report;
+	return {
+		sendAudio: (base64, mediaType) => connection.sendAudio(base64, mediaType),
+		sendText: (text) => connection.sendText(text),
+		events: () => connection.events(),
+		async close() {
+			if (report) return report;
+			await connection.close();
+			report = {
+				runId,
+				rootRunId: runId,
+				type: "realtime",
+				name: options.name ?? "realtime",
+				status: "completed",
+				startedAt,
+				endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+				duration: performance.now() - startPerf,
+				...options.sessionId ? { sessionId: options.sessionId } : {}
+			};
+			return report;
+		}
+	};
+}
+
+//#endregion
+export { realtime };
+//# sourceMappingURL=realtime.mjs.map

package/esm/realtime/realtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"realtime.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/realtime/realtime.ts"],"sourcesContent":["import { generateRunId } from \"@warlock.js/ai\";\nimport type {\n  RealtimeOptions,\n  RealtimeReport,\n  RealtimeSession,\n} from \"../contracts/realtime.contract\";\n\n/**\n * Open a live duplex voice session — the stateful primitive of\n * `@warlock.js/ai-live`. Connects through the provided\n * {@link RealtimeOptions.transport} (an OpenAI Realtime WebSocket\n * adapter, a mock in tests), then hands back a {@link RealtimeSession}\n * you drive: push audio/text in, consume the event stream out, and\n * `close()` to end it and receive a `type: \"realtime\"` report for the\n * cost/observability surfaces.\n *\n * Unlike the one-shot `ai.*` verbs, this returns a long-lived session —\n * its closest sibling is `ai.orchestrator`. Keeping the transport\n * pluggable is what lets the session surface ship without hard-wiring a\n * WebSocket dependency.\n *\n * @example\n * const session = await ai.realtime({ transport, model: \"gpt-realtime\", voice: \"alloy\" });\n * session.sendAudio(micChunk, \"audio/pcm\");\n * for await (const event of session.events()) {\n *   if (event.type === \"audio\") speaker.write(event.base64);\n * }\n * const report = await session.close();\n */\nexport async function realtime(options: RealtimeOptions): Promise<RealtimeSession> {\n  const runId = generateRunId(\"realtime\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const connection = await options.transport.connect({\n    model: options.model,\n    voice: options.voice,\n    instructions: options.instructions,\n  });\n\n  let report: RealtimeReport | undefined;\n\n  return {\n    sendAudio: (base64, mediaType) => connection.sendAudio(base64, mediaType),\n    sendText: (text) => connection.sendText(text),\n    events: () => connection.events(),\n    async close(): Promise<RealtimeReport> {\n      // Idempotent — closing twice returns the first report, never\n      // re-tears-down the connection.\n      if (report) {\n        return report;\n      }\n\n      await connection.close();\n\n      report = {\n        runId,\n        rootRunId: runId,\n        type: \"realtime\",\n        name: options.name ?? \"realtime\",\n        status: \"completed\",\n        startedAt,\n        endedAt: new Date().toISOString(),\n        duration: performance.now() - startPerf,\n        ...(options.sessionId ? { sessionId: options.sessionId } : {}),\n      };\n\n      return report;\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,eAAsB,SAAS,SAAoD;CACjF,MAAM,QAAQ,cAAc,UAAU;CACtC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,aAAa,MAAM,QAAQ,UAAU,QAAQ;EACjD,OAAO,QAAQ;EACf,OAAO,QAAQ;EACf,cAAc,QAAQ;CACxB,CAAC;CAED,IAAI;CAEJ,OAAO;EACL,YAAY,QAAQ,cAAc,WAAW,UAAU,QAAQ,SAAS;EACxE,WAAW,SAAS,WAAW,SAAS,IAAI;EAC5C,cAAc,WAAW,OAAO;EAChC,MAAM,QAAiC;GAGrC,IAAI,QACF,OAAO;GAGT,MAAM,WAAW,MAAM;GAEvB,SAAS;IACP;IACA,WAAW;IACX,MAAM;IACN,MAAM,QAAQ,QAAQ;IACtB,QAAQ;IACR;IACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;IAChC,UAAU,YAAY,IAAI,IAAI;IAC9B,GAAI,QAAQ,YAAY,EAAE,WAAW,QAAQ,UAAU,IAAI,CAAC;GAC9D;GAEA,OAAO;EACT;CACF;AACF"}

package/esm/video/video.d.mts

@@ -0,0 +1,59 @@
+import { GeneratedVideo, VideoModelContract } from "../contracts/video.contract.mjs";
+import { BaseReport, ExecuteResult, FlowObserveOption } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-live/src/video/video.d.ts
+/** Parameters for {@link video}. `model` comes from an adapter's `video({ name })`. */
+type VideoParams = {
+  model: VideoModelContract;
+  prompt: string;
+  durationSeconds?: number;
+  aspectRatio?: string;
+  resolution?: string;
+  negativePrompt?: string;
+  signal?: AbortSignal;
+  observe?: FlowObserveOption;
+  sessionId?: string;
+  name?: string;
+  options?: Record<string, unknown>;
+};
+/** Success payload of a {@link video} run. */
+type VideoData = {
+  video: GeneratedVideo;
+};
+/** The report node a {@link video} run produces (`type: "video"`). */
+type VideoReport = BaseReport & {
+  type: "video";
+  model: {
+    name: string;
+    provider: string;
+  }; /** Final clip duration in seconds, when reported. */
+  durationSeconds?: number;
+};
+/** Result envelope of {@link video} — the uniform `{ data, error, usage, report }`. */
+type VideoResult = ExecuteResult<VideoData> & {
+  type: "video";
+  report: VideoReport;
+};
+/**
+ * Generate a video from a text prompt — the moving-image verb of the
+ * output-modality track. The adapter hides the provider's submit→poll
+ * job, so this returns the framework's uniform never-throws envelope:
+ *
+ * - **Never throws.** Provider failures surface as a typed `AIError`.
+ * - **Cost-truth.** `usage.cost` is filled per-second (Sora / Veo) or
+ *   per-token, folding into the same `Usage.cost` rollup as everything else.
+ * - **Observable.** The completed {@link VideoReport} routes to any
+ *   registered `Observer` via the shared `observe` seam.
+ *
+ * @example
+ * const { data, error } = await ai.video({
+ *   model: sora.video({ name: "sora-2", pricing: { perSecond: 0.1 } }),
+ *   prompt: "a timelapse of a city skyline at dusk, cinematic",
+ *   durationSeconds: 8,
+ * });
+ * if (!error) download(data.video);
+ */
+declare function video(params: VideoParams): Promise<VideoResult>;
+//#endregion
+export { VideoData, VideoParams, VideoReport, VideoResult, video };
+//# sourceMappingURL=video.d.mts.map

package/esm/video/video.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/video/video.ts"],"mappings":";;;;;KAqBY,WAAA;EACV,KAAA,EAAO,kBAAA;EACP,MAAA;EACA,eAAA;EACA,WAAA;EACA,UAAA;EACA,cAAA;EACA,MAAA,GAAS,WAAA;EACT,OAAA,GAAU,iBAAA;EACV,SAAA;EACA,IAAA;EACA,OAAA,GAAU,MAAA;AAAA;;KAIA,SAAA;EAAc,KAAA,EAAO,cAAc;AAAA;;KAGnC,WAAA,GAAc,UAAU;EAClC,IAAA;EACA,KAAA;IAAS,IAAA;IAAc,QAAA;EAAA,GATb;EAWV,eAAA;AAAA;AAPF;AAAA,KAWY,WAAA,GAAc,aAAA,CAAc,SAAA;EAAe,IAAA;EAAe,MAAA,EAAQ,WAAA;AAAA;AAR9E;;;;;;;;;;;AAIiB;AAIjB;;;;;;;AARA,iBA6BsB,KAAA,CAAM,MAAA,EAAQ,WAAA,GAAc,OAAA,CAAQ,WAAA"}

package/esm/video/video.mjs

@@ -0,0 +1,118 @@
+import { AIError, ProviderError, REPORT_SCHEMA_VERSION, computeCost, generateRunId, resolveObservers, stampReportLineage } from "@warlock.js/ai";
+
+//#region ../@warlock.js/ai-live/src/video/video.ts
+/**
+* Generate a video from a text prompt — the moving-image verb of the
+* output-modality track. The adapter hides the provider's submit→poll
+* job, so this returns the framework's uniform never-throws envelope:
+*
+* - **Never throws.** Provider failures surface as a typed `AIError`.
+* - **Cost-truth.** `usage.cost` is filled per-second (Sora / Veo) or
+*   per-token, folding into the same `Usage.cost` rollup as everything else.
+* - **Observable.** The completed {@link VideoReport} routes to any
+*   registered `Observer` via the shared `observe` seam.
+*
+* @example
+* const { data, error } = await ai.video({
+*   model: sora.video({ name: "sora-2", pricing: { perSecond: 0.1 } }),
+*   prompt: "a timelapse of a city skyline at dusk, cinematic",
+*   durationSeconds: 8,
+* });
+* if (!error) download(data.video);
+*/
+async function video(params) {
+	const { model, prompt } = params;
+	const runId = generateRunId("video");
+	const startedAt = (/* @__PURE__ */ new Date()).toISOString();
+	const startPerf = performance.now();
+	const usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	let data;
+	let error;
+	let status = "completed";
+	let durationSeconds;
+	try {
+		const response = await model.generate(prompt, {
+			durationSeconds: params.durationSeconds,
+			aspectRatio: params.aspectRatio,
+			resolution: params.resolution,
+			negativePrompt: params.negativePrompt,
+			signal: params.signal,
+			...params.options
+		});
+		Object.assign(usage, response.usage);
+		durationSeconds = response.durationSeconds;
+		if (usage.cost === void 0) {
+			const cost = computeVideoCost(usage, durationSeconds, model.pricing);
+			if (cost !== void 0) usage.cost = cost;
+		}
+		data = { video: response.video };
+	} catch (thrown) {
+		error = thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });
+		status = params.signal?.aborted ? "cancelled" : "failed";
+	}
+	const report = {
+		runId,
+		rootRunId: runId,
+		name: params.name ?? "video",
+		type: "video",
+		status,
+		error,
+		startedAt,
+		endedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		duration: performance.now() - startPerf,
+		usage,
+		children: [],
+		model: {
+			name: model.name,
+			provider: model.provider
+		},
+		...durationSeconds !== void 0 ? { durationSeconds } : {},
+		reportSchemaVersion: REPORT_SCHEMA_VERSION
+	};
+	stampReportLineage(report, {
+		rootRunId: runId,
+		sessionId: params.sessionId
+	});
+	for (const observer of resolveObservers(params.observe)) try {
+		await observer.collect(report);
+	} catch {}
+	return {
+		type: "video",
+		data,
+		error,
+		usage,
+		report
+	};
+}
+/**
+* Price a video run: `perSecond × durationSeconds` (per-second metering,
+* attributed to `cost.output`) wins when configured, otherwise the
+* standard token math. Returns `undefined` when no usable pricing is
+* present.
+*/
+function computeVideoCost(usage, durationSeconds, pricing) {
+	if (!pricing) return;
+	if (pricing.perSecond !== void 0) {
+		if (durationSeconds === void 0) return;
+		return {
+			input: 0,
+			output: durationSeconds * pricing.perSecond
+		};
+	}
+	if (pricing.input !== void 0 && pricing.output !== void 0) return computeCost(usage, {
+		input: pricing.input,
+		output: pricing.output
+	});
+}
+/** Best-effort message for a non-`AIError` thrown value. */
+function toMessage(thrown) {
+	return thrown instanceof Error ? thrown.message : String(thrown);
+}
+
+//#endregion
+export { video };
+//# sourceMappingURL=video.mjs.map

package/esm/video/video.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai-live/src/video/video.ts"],"sourcesContent":["import {\n  AIError,\n  computeCost,\n  generateRunId,\n  ProviderError,\n  REPORT_SCHEMA_VERSION,\n  resolveObservers,\n  stampReportLineage,\n  type BaseReport,\n  type ExecuteResult,\n  type FlowObserveOption,\n  type ModelPricing,\n  type Usage,\n} from \"@warlock.js/ai\";\nimport type {\n  GeneratedVideo,\n  VideoModelContract,\n  VideoModelPricing,\n} from \"../contracts/video.contract\";\n\n/** Parameters for {@link video}. `model` comes from an adapter's `video({ name })`. */\nexport type VideoParams = {\n  model: VideoModelContract;\n  prompt: string;\n  durationSeconds?: number;\n  aspectRatio?: string;\n  resolution?: string;\n  negativePrompt?: string;\n  signal?: AbortSignal;\n  observe?: FlowObserveOption;\n  sessionId?: string;\n  name?: string;\n  options?: Record<string, unknown>;\n};\n\n/** Success payload of a {@link video} run. */\nexport type VideoData = { video: GeneratedVideo };\n\n/** The report node a {@link video} run produces (`type: \"video\"`). */\nexport type VideoReport = BaseReport & {\n  type: \"video\";\n  model: { name: string; provider: string };\n  /** Final clip duration in seconds, when reported. */\n  durationSeconds?: number;\n};\n\n/** Result envelope of {@link video} — the uniform `{ data, error, usage, report }`. */\nexport type VideoResult = ExecuteResult<VideoData> & { type: \"video\"; report: VideoReport };\n\n/**\n * Generate a video from a text prompt — the moving-image verb of the\n * output-modality track. The adapter hides the provider's submit→poll\n * job, so this returns the framework's uniform never-throws envelope:\n *\n * - **Never throws.** Provider failures surface as a typed `AIError`.\n * - **Cost-truth.** `usage.cost` is filled per-second (Sora / Veo) or\n *   per-token, folding into the same `Usage.cost` rollup as everything else.\n * - **Observable.** The completed {@link VideoReport} routes to any\n *   registered `Observer` via the shared `observe` seam.\n *\n * @example\n * const { data, error } = await ai.video({\n *   model: sora.video({ name: \"sora-2\", pricing: { perSecond: 0.1 } }),\n *   prompt: \"a timelapse of a city skyline at dusk, cinematic\",\n *   durationSeconds: 8,\n * });\n * if (!error) download(data.video);\n */\nexport async function video(params: VideoParams): Promise<VideoResult> {\n  const { model, prompt } = params;\n\n  const runId = generateRunId(\"video\");\n  const startedAt = new Date().toISOString();\n  const startPerf = performance.now();\n\n  const usage: Usage = { input: 0, output: 0, total: 0 };\n  let data: VideoData | undefined;\n  let error: AIError | undefined;\n  let status: VideoReport[\"status\"] = \"completed\";\n  let durationSeconds: number | undefined;\n\n  try {\n    const response = await model.generate(prompt, {\n      durationSeconds: params.durationSeconds,\n      aspectRatio: params.aspectRatio,\n      resolution: params.resolution,\n      negativePrompt: params.negativePrompt,\n      signal: params.signal,\n      ...params.options,\n    });\n\n    Object.assign(usage, response.usage);\n    durationSeconds = response.durationSeconds;\n\n    if (usage.cost === undefined) {\n      const cost = computeVideoCost(usage, durationSeconds, model.pricing);\n      if (cost !== undefined) {\n        usage.cost = cost;\n      }\n    }\n\n    data = { video: response.video };\n  } catch (thrown) {\n    error =\n      thrown instanceof AIError ? thrown : new ProviderError(toMessage(thrown), { cause: thrown });\n    status = params.signal?.aborted ? \"cancelled\" : \"failed\";\n  }\n\n  const report: VideoReport = {\n    runId,\n    rootRunId: runId,\n    name: params.name ?? \"video\",\n    type: \"video\",\n    status,\n    error,\n    startedAt,\n    endedAt: new Date().toISOString(),\n    duration: performance.now() - startPerf,\n    usage,\n    children: [],\n    model: { name: model.name, provider: model.provider },\n    ...(durationSeconds !== undefined ? { durationSeconds } : {}),\n    reportSchemaVersion: REPORT_SCHEMA_VERSION,\n  };\n\n  stampReportLineage(report, { rootRunId: runId, sessionId: params.sessionId });\n\n  for (const observer of resolveObservers(params.observe)) {\n    try {\n      await observer.collect(report);\n    } catch {\n      // Isolate observer failures — never break the run.\n    }\n  }\n\n  return { type: \"video\", data, error, usage, report };\n}\n\n/**\n * Price a video run: `perSecond × durationSeconds` (per-second metering,\n * attributed to `cost.output`) wins when configured, otherwise the\n * standard token math. Returns `undefined` when no usable pricing is\n * present.\n */\nfunction computeVideoCost(\n  usage: Usage,\n  durationSeconds: number | undefined,\n  pricing: VideoModelPricing | undefined,\n): ModelPricing | undefined {\n  if (!pricing) {\n    return undefined;\n  }\n\n  if (pricing.perSecond !== undefined) {\n    if (durationSeconds === undefined) {\n      return undefined;\n    }\n    return { input: 0, output: durationSeconds * pricing.perSecond };\n  }\n\n  if (pricing.input !== undefined && pricing.output !== undefined) {\n    return computeCost(usage, { input: pricing.input, output: pricing.output });\n  }\n\n  return undefined;\n}\n\n/** Best-effort message for a non-`AIError` thrown value. */\nfunction toMessage(thrown: unknown): string {\n  return thrown instanceof Error ? thrown.message : String(thrown);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAoEA,eAAsB,MAAM,QAA2C;CACrE,MAAM,EAAE,OAAO,WAAW;CAE1B,MAAM,QAAQ,cAAc,OAAO;CACnC,MAAM,6BAAY,IAAI,KAAK,EAAC,CAAC,YAAY;CACzC,MAAM,YAAY,YAAY,IAAI;CAElC,MAAM,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CACrD,IAAI;CACJ,IAAI;CACJ,IAAI,SAAgC;CACpC,IAAI;CAEJ,IAAI;EACF,MAAM,WAAW,MAAM,MAAM,SAAS,QAAQ;GAC5C,iBAAiB,OAAO;GACxB,aAAa,OAAO;GACpB,YAAY,OAAO;GACnB,gBAAgB,OAAO;GACvB,QAAQ,OAAO;GACf,GAAG,OAAO;EACZ,CAAC;EAED,OAAO,OAAO,OAAO,SAAS,KAAK;EACnC,kBAAkB,SAAS;EAE3B,IAAI,MAAM,SAAS,QAAW;GAC5B,MAAM,OAAO,iBAAiB,OAAO,iBAAiB,MAAM,OAAO;GACnE,IAAI,SAAS,QACX,MAAM,OAAO;EAEjB;EAEA,OAAO,EAAE,OAAO,SAAS,MAAM;CACjC,SAAS,QAAQ;EACf,QACE,kBAAkB,UAAU,SAAS,IAAI,cAAc,UAAU,MAAM,GAAG,EAAE,OAAO,OAAO,CAAC;EAC7F,SAAS,OAAO,QAAQ,UAAU,cAAc;CAClD;CAEA,MAAM,SAAsB;EAC1B;EACA,WAAW;EACX,MAAM,OAAO,QAAQ;EACrB,MAAM;EACN;EACA;EACA;EACA,0BAAS,IAAI,KAAK,EAAC,CAAC,YAAY;EAChC,UAAU,YAAY,IAAI,IAAI;EAC9B;EACA,UAAU,CAAC;EACX,OAAO;GAAE,MAAM,MAAM;GAAM,UAAU,MAAM;EAAS;EACpD,GAAI,oBAAoB,SAAY,EAAE,gBAAgB,IAAI,CAAC;EAC3D,qBAAqB;CACvB;CAEA,mBAAmB,QAAQ;EAAE,WAAW;EAAO,WAAW,OAAO;CAAU,CAAC;CAE5E,KAAK,MAAM,YAAY,iBAAiB,OAAO,OAAO,GACpD,IAAI;EACF,MAAM,SAAS,QAAQ,MAAM;CAC/B,QAAQ,CAER;CAGF,OAAO;EAAE,MAAM;EAAS;EAAM;EAAO;EAAO;CAAO;AACrD;;;;;;;AAQA,SAAS,iBACP,OACA,iBACA,SAC0B;CAC1B,IAAI,CAAC,SACH;CAGF,IAAI,QAAQ,cAAc,QAAW;EACnC,IAAI,oBAAoB,QACtB;EAEF,OAAO;GAAE,OAAO;GAAG,QAAQ,kBAAkB,QAAQ;EAAU;CACjE;CAEA,IAAI,QAAQ,UAAU,UAAa,QAAQ,WAAW,QACpD,OAAO,YAAY,OAAO;EAAE,OAAO,QAAQ;EAAO,QAAQ,QAAQ;CAAO,CAAC;AAI9E;;AAGA,SAAS,UAAU,QAAyB;CAC1C,OAAO,kBAAkB,QAAQ,OAAO,UAAU,OAAO,MAAM;AACjE"}

package/llms-full.txt

@@ -0,0 +1,210 @@
+# Warlock AI Live — full skills
+
+> Package: `@warlock.js/ai-live`
+
+> Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/ai-live/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
+
+## use-ai-live  `@warlock.js/ai-live/use-ai-live/SKILL.md`
+
+---
+name: use-ai-live
+description: 'Live & generative rich-media add-on for @warlock.js/ai. A side-effect import `import "@warlock.js/ai-live"` mounts two heavy modalities onto the shared `ai.*` facade: `ai.video({ model, prompt })` — text-to-video (Sora / Veo / Kling-class), the async submit→poll job hidden behind the same uniform never-throws `{ data, error, usage, report }` envelope as `ai.image`, with per-second cost-truth folded into `Usage.cost`; and `ai.realtime({ transport, model })` — a stateful duplex VOICE SESSION over a pluggable `RealtimeTransport` (sendAudio / sendText / events() / close()→RealtimeReport). Videos are a discriminated `GeneratedVideo = { type: "url" } | { type: "base64" }`; session output is a `RealtimeEvent` union (audio | transcript | tool-call | error | done). Ships `MockVideoModel` + `MockRealtimeTransport` for HTTP-free tests. Triggers: `ai.video`, `ai.realtime`, `VideoModelContract`, `GeneratedVideo`, `VideoModelPricing`, `RealtimeSession`, `RealtimeTransport`, `RealtimeEvent`, `RealtimeReport`, `MockVideoModel`, `MockRealtimeTransport`; ''generate a video'', ''text to video'', ''sora'', ''veo'', ''realtime voice'', ''duplex voice session'', ''live voice agent'', ''barge-in'', ''per-second video cost''; typical import `import "@warlock.js/ai-live"` + `import { ai } from "@warlock.js/ai"`. Skip: still-image OUTPUT — [[generate-images]]; text-to-speech / transcription (one-shot audio, not a session) — [[generate-speech]]; chat agents / tools / workflows — `@warlock.js/ai/run-ai-agent/SKILL.md`.'
+---
+
+# Live rich-media — `ai.video` + `ai.realtime` (`@warlock.js/ai-live`)
+
+`@warlock.js/ai` ships the synchronous modality verbs (`ai.agent`, `ai.image`, `ai.speech`, `ai.transcribe`). `ai-live` adds the two that need heavyweight, demand-gated machinery — a **long-running job** (video) and a **persistent network session** (realtime voice) — kept in their own package so the core stays dependency-light.
+
+Both mount onto the same `ai.*` facade by a **side-effect import**:
+
+```ts
+import "@warlock.js/ai-live"; // lights up ai.video + ai.realtime on the shared Ai facade
+import { ai } from "@warlock.js/ai";
+```
+
+The mount mirrors how `@warlock.js/ai-tools` mounts `ai.mcp` and `@warlock.js/ai-workspace` mounts `ai.workspace`: a `declare module "@warlock.js/ai"` interface-merge plus `ai.video = video; ai.realtime = realtime` at load. Forget the side-effect import and `ai.video` is a compile-time `undefined` — not a silent runtime miss.
+
+## `ai.video` — text-to-video, uniform envelope
+
+Prompt in / one video out. The adapter hides the provider's async **submit→poll** lifecycle and resolves only when the clip is ready, so the verb returns the framework's uniform **never-throws** `{ data, error, usage, report }` — the exact shape `ai.image` returns, so video spend and traces fold into the same dashboards.
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const { data, error, usage, report } = await ai.video({
+  model: sora.video({ name: "sora-2", pricing: { perSecond: 0.1 } }), // VideoModelContract
+  prompt: "a timelapse of a city skyline at dusk, cinematic",
+  durationSeconds: 8,
+  aspectRatio: "16:9",
+});
+
+if (error) {
+  console.warn(error.code);   // typed AIError — NEVER thrown
+} else {
+  const clip = data.video;    // GeneratedVideo (discriminated)
+  if (clip.type === "url") download(clip.url);
+  else save(Buffer.from(clip.base64, "base64"), clip.mediaType);
+}
+```
+
+### Shape
+
+```ts
+type VideoResult = ExecuteResult<VideoData> & { type: "video"; report: VideoReport };
+type VideoData = { video: GeneratedVideo };
+
+type GeneratedVideo =
+  | { type: "url"; url: string; mediaType?: string }
+  | { type: "base64"; base64: string; mediaType: string };
+
+// VideoParams (provider-neutral) — the model is the only required field beyond prompt:
+await ai.video({
+  model,                 // VideoModelContract from an adapter's video({ name })
+  prompt: "...",
+  durationSeconds: 8,    // requested clip length
+  aspectRatio: "9:16",
+  resolution: "1080p",   // hint
+  negativePrompt: "blurry, watermark",
+  signal,                // AbortSignal → status "cancelled"
+  observe: collector,    // route the report to an Observer (panoptic), like agents
+  sessionId: "campaign-42",
+  name: "hero-clip",     // report node name (defaults to "video")
+  options: { seed: 7 },  // provider-specific escape hatch, forwarded verbatim
+});
+```
+
+`VideoModelContract` is the moving-image sibling of `ImageModelContract` — `{ name, provider, pricing?, generate(prompt, options) }` — produced by an adapter's `video()` factory. An adapter with no video API simply doesn't define `video()`.
+
+## Video cost-truth — per-second first
+
+`VideoModelPricing` carries `{ perSecond?, input?, output? }`. Per-second wins when set (video is metered by clip length): `usage.cost = { input: 0, output: durationSeconds × perSecond }`, attributed to `cost.output`. A token-metered model falls back to the standard `computeCost` against reported tokens. No usable pricing → `usage.cost` stays `undefined` (honest "cost unknown", never a false zero). A pre-priced adapter response is honored, not overwritten. The final `durationSeconds` from the provider (not just the requested one) drives the math and lands on `report.durationSeconds`.
+
+## `ai.realtime` — a duplex voice SESSION (not a one-shot)
+
+Unlike every other `ai.*` verb, `ai.realtime()` returns a **stateful, long-lived session** — its closest sibling is `ai.orchestrator`. You open it over a pluggable **`RealtimeTransport`** (the low-level connection to the provider's realtime endpoint), push microphone audio / text turns in, consume an async **event stream** out, and `close()` to end it and receive a `RealtimeReport` for the cost/observability surfaces.
+
+```ts
+import { ai } from "@warlock.js/ai";
+
+const session = await ai.realtime({
+  transport: openAiRealtime({ apiKey }), // RealtimeTransport (own adapter)
+  model: "gpt-realtime",
+  voice: "alloy",
+  instructions: "You are a friendly phone receptionist.",
+  sessionId: "call-8891",
+});
+
+session.sendAudio(micChunkBase64, "audio/pcm"); // push mic audio upstream
+session.sendText("Please hold for one moment."); // or a text turn
+
+for await (const event of session.events()) {    // duplex output
+  switch (event.type) {
+    case "audio":      speaker.write(event.base64); break;
+    case "transcript": if (event.final) log(event.role, event.text); break;
+    case "tool-call":  await handleTool(event.name, event.input); break;
+    case "error":      console.warn(event.error.code); break;
+    case "done":       break;
+  }
+}
+
+const report = await session.close(); // RealtimeReport — idempotent
+```
+
+### Session contract & event union
+
+```ts
+interface RealtimeSession {
+  sendAudio(base64: string, mediaType: string): void;
+  sendText(text: string): void;
+  events(): AsyncIterable<RealtimeEvent>;
+  close(): Promise<RealtimeReport>; // idempotent — second close() returns the first report
+}
+
+type RealtimeEvent =
+  | { type: "audio"; base64: string; mediaType: string }
+  | { type: "transcript"; role: "user" | "assistant"; text: string; final: boolean }
+  | { type: "tool-call"; id: string; name: string; input: unknown }
+  | { type: "error"; error: AIError }   // typed, non-fatal
+  | { type: "done" };                   // server ended the session
+
+type RealtimeReport = {
+  runId: string; rootRunId: string; type: "realtime";
+  name: string; status: "completed" | "failed" | "cancelled";
+  startedAt: string; endedAt: string; duration: number; sessionId?: string;
+};
+```
+
+The transport seam is what lets `ai-live` ship the session surface without hard-wiring `ws` (it's an optional peer). A concrete transport implements just two interfaces: `RealtimeTransport.connect(config) → RealtimeConnection` (with `sendAudio` / `sendText` / `events()` / `close()`).
+
+## Pattern — a live phone receptionist over a channel
+
+```ts
+import "@warlock.js/ai-live";
+import { ai } from "@warlock.js/ai";
+
+async function handleCall(caller: PhoneChannel, transport: RealtimeTransport) {
+  const session = await ai.realtime({
+    transport,
+    model: "gpt-realtime",
+    voice: "alloy",
+    instructions: "Greet the caller and route them to the right department.",
+    sessionId: caller.id,
+  });
+
+  // Pump caller audio → session (fire-and-forget).
+  caller.onAudio((chunk) => session.sendAudio(chunk, "audio/pcm"));
+
+  // Pump session output → caller, until the model signals done.
+  for await (const event of session.events()) {
+    if (event.type === "audio") caller.playAudio(event.base64);
+    if (event.type === "done") break;
+  }
+
+  const report = await session.close();
+  metrics.record({ runId: report.runId, seconds: report.duration / 1000 });
+}
+```
+
+## Testing — mocks, no HTTP, no sockets
+
+`@warlock.js/ai-live` exports deterministic doubles so both verbs test offline.
+
+```ts
+import { ai } from "@warlock.js/ai";
+import { MockVideoModel, MockRealtimeTransport } from "@warlock.js/ai-live";
+
+// Video — script the returned clip / usage / duration; assert cost math + recorded calls.
+const model = new MockVideoModel("mock-video", [{ durationSeconds: 8 }], { perSecond: 0.1 });
+const { data, usage } = await ai.video({ model, prompt: "x", durationSeconds: 8 });
+// data.video → { type: "url", url: "https://mock/video.mp4", ... }
+// usage.cost.output === 0.8   (8 × 0.1)
+// model.calls[0] → { prompt: "x", options: { durationSeconds: 8, ... } }
+
+// Realtime — script the outbound event stream; assert what the session sent.
+const transport = new MockRealtimeTransport([
+  { type: "transcript", role: "assistant", text: "Hi!", final: true },
+  { type: "done" },
+]);
+const session = await ai.realtime({ transport, model: "mock-realtime" });
+session.sendText("hello");
+for await (const e of session.events()) { /* ... */ }
+const report = await session.close();
+// transport.lastConnection.sentText → ["hello"]
+// transport.connectConfigs[0] → { model: "mock-realtime", ... }
+// report.status === "completed"
+```
+
+Feed `MockVideoModel` an `{ error }` response and `ai.video` lands it on `result.error` (never throws), setting `report.status` to `"failed"` (or `"cancelled"` when the signal aborted).
+
+## Status — contracts now, transports next
+
+`4.6.0` introduces the package: the `VideoModelContract` / `RealtimeSession` contracts, the `ai.video()` verb (uniform envelope + per-second cost-truth, tested against `MockVideoModel`), and the `ai.realtime()` session primitive over a pluggable transport (tested against `MockRealtimeTransport`). The first **concrete provider transports** — an OpenAI Realtime **WebSocket** for `ai.realtime`, and **Sora / Veo** video adapters for `ai.video` — are the next implementation step; the seams are defined so they drop in without changing the verb surface.
+
+## See also
+
+- [[generate-images]] — still-image OUTPUT (`ai.image`), the synchronous sibling `ai.video` mirrors.
+- [[generate-speech]] — one-shot text-to-speech / transcription (`ai.speech` / `ai.transcribe`); use `ai.realtime` instead when you need a live duplex conversation, not a single audio render.
+- `@warlock.js/ai/observe-ai-flows/SKILL.md` — the `observe` seam both verbs route their reports through.
+- `@warlock.js/ai/run-orchestrator/SKILL.md` — the other session-shaped primitive `ai.realtime` resembles.
+
+