@warlock.js/ai 4.4.0 → 4.6.0

package/esm/mock/mock-sdk.mjs

@@ -1,5 +1,8 @@
 import { approximateTokenCount } from "../utils/token-count.mjs";
+import { MockImageModel } from "./mock-image-model.mjs";
 import { MockModel } from "./mock-model.mjs";
+import { MockSpeechModel } from "./mock-speech-model.mjs";
+import { MockTranscriptionModel } from "./mock-transcription-model.mjs";
 
 //#region ../@warlock.js/ai/src/mock/mock-sdk.ts
 /**
@@ -18,14 +21,38 @@ import { MockModel } from "./mock-model.mjs";
 */
 function MockSDK(config = {}) {
 	const models = [];
+	const imageModels = [];
+	const speechModels = [];
+	const transcriptionModels = [];
 	const responses = config.responses ?? [{ content: "Mock response" }];
+	const imageResponses = config.imageResponses ?? [{}];
+	const speechResponses = config.speechResponses ?? [{}];
+	const transcriptionResponses = config.transcriptionResponses ?? [{}];
 	return {
 		models,
+		imageModels,
+		speechModels,
+		transcriptionModels,
 		model(modelConfig) {
 			const model = new MockModel(modelConfig.name ?? config.defaultModelName ?? "mock-model", responses, config.capabilities);
 			models.push(model);
 			return model;
 		},
+		image(imageConfig) {
+			const model = new MockImageModel(imageConfig.name ?? config.defaultModelName ?? "mock-image-model", imageResponses, imageConfig.pricing ?? config.imagePricing);
+			imageModels.push(model);
+			return model;
+		},
+		speech(speechConfig) {
+			const model = new MockSpeechModel(speechConfig.name ?? config.defaultModelName ?? "mock-speech-model", speechResponses, speechConfig.pricing ?? config.speechPricing);
+			speechModels.push(model);
+			return model;
+		},
+		transcribe(transcribeConfig) {
+			const model = new MockTranscriptionModel(transcribeConfig.name ?? config.defaultModelName ?? "mock-transcription-model", transcriptionResponses, transcribeConfig.pricing ?? config.transcriptionPricing);
+			transcriptionModels.push(model);
+			return model;
+		},
 		async count(text, _model) {
 			return approximateTokenCount(text);
 		}

package/esm/mock/mock-sdk.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mock-sdk.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-sdk.ts"],"sourcesContent":["import type {\n  ModelConfig,\n  SDKAdapterContract,\n} from \"../contracts/sdk-adapter.contract\";\nimport { approximateTokenCount } from \"../utils/token-count\";\nimport type { MockSDKConfig } from \"./mock-config.type\";\nimport { MockModel } from \"./mock-model\";\n\n/**\n * Creates a mock SDK adapter for testing — no HTTP calls, fully configurable.\n *\n * @example\n * const mock = MockSDK({\n *   responses: [\n *     { content: \"Hello from mock!\" },\n *     { content: \"Second response\" },\n *   ],\n * });\n * const model = mock.model({ name: \"gpt-4o\" });\n * const result = await model.complete([{ role: \"user\", content: \"Hi\" }]);\n * console.log(result.content); // \"Hello from mock!\"\n */\nexport function MockSDK(config: MockSDKConfig = {}): SDKAdapterContract & {\n  /** All model instances created by this SDK — for inspecting calls in tests */\n  models: MockModel[];\n} {\n  const models: MockModel[] = [];\n  const responses = config.responses ?? [{ content: \"Mock response\" }];\n\n  return {\n    models,\n    model(modelConfig: ModelConfig) {\n      const model = new MockModel(\n        modelConfig.name ?? config.defaultModelName ?? \"mock-model\",\n        responses,\n        config.capabilities,\n      );\n      models.push(model);\n      return model;\n    },\n    async count(text: string, _model?: string): Promise<number> {\n      return approximateTokenCount(text);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAsBA,SAAgB,QAAQ,SAAwB,CAAC,GAG/C;CACA,MAAM,SAAsB,CAAC;CAC7B,MAAM,YAAY,OAAO,aAAa,CAAC,EAAE,SAAS,gBAAgB,CAAC;CAEnE,OAAO;EACL;EACA,MAAM,aAA0B;GAC9B,MAAM,QAAQ,IAAI,UAChB,YAAY,QAAQ,OAAO,oBAAoB,cAC/C,WACA,OAAO,YACT;GACA,OAAO,KAAK,KAAK;GACjB,OAAO;EACT;EACA,MAAM,MAAM,MAAc,QAAkC;GAC1D,OAAO,sBAAsB,IAAI;EACnC;CACF;AACF"}
+{"version":3,"file":"mock-sdk.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-sdk.ts"],"sourcesContent":["import type { ImageModelConfig } from \"../contracts/image-model.contract\";\nimport type {\n  ModelConfig,\n  SDKAdapterContract,\n} from \"../contracts/sdk-adapter.contract\";\nimport type { SpeechModelConfig } from \"../contracts/speech-model.contract\";\nimport type { TranscriptionModelConfig } from \"../contracts/transcription-model.contract\";\nimport { approximateTokenCount } from \"../utils/token-count\";\nimport type { MockSDKConfig } from \"./mock-config.type\";\nimport { MockImageModel } from \"./mock-image-model\";\nimport { MockModel } from \"./mock-model\";\nimport { MockSpeechModel } from \"./mock-speech-model\";\nimport { MockTranscriptionModel } from \"./mock-transcription-model\";\n\n/**\n * Creates a mock SDK adapter for testing — no HTTP calls, fully configurable.\n *\n * @example\n * const mock = MockSDK({\n *   responses: [\n *     { content: \"Hello from mock!\" },\n *     { content: \"Second response\" },\n *   ],\n * });\n * const model = mock.model({ name: \"gpt-4o\" });\n * const result = await model.complete([{ role: \"user\", content: \"Hi\" }]);\n * console.log(result.content); // \"Hello from mock!\"\n */\nexport function MockSDK(config: MockSDKConfig = {}): SDKAdapterContract & {\n  /** All model instances created by this SDK — for inspecting calls in tests */\n  models: MockModel[];\n  /** All image-model instances created by this SDK — for inspecting calls in tests */\n  imageModels: MockImageModel[];\n  /** All speech-model instances created by this SDK — for inspecting calls in tests */\n  speechModels: MockSpeechModel[];\n  /** All transcription-model instances created by this SDK — for inspecting calls in tests */\n  transcriptionModels: MockTranscriptionModel[];\n} {\n  const models: MockModel[] = [];\n  const imageModels: MockImageModel[] = [];\n  const speechModels: MockSpeechModel[] = [];\n  const transcriptionModels: MockTranscriptionModel[] = [];\n  const responses = config.responses ?? [{ content: \"Mock response\" }];\n  const imageResponses = config.imageResponses ?? [{}];\n  const speechResponses = config.speechResponses ?? [{}];\n  const transcriptionResponses = config.transcriptionResponses ?? [{}];\n\n  return {\n    models,\n    imageModels,\n    speechModels,\n    transcriptionModels,\n    model(modelConfig: ModelConfig) {\n      const model = new MockModel(\n        modelConfig.name ?? config.defaultModelName ?? \"mock-model\",\n        responses,\n        config.capabilities,\n      );\n      models.push(model);\n      return model;\n    },\n    image(imageConfig: ImageModelConfig) {\n      const model = new MockImageModel(\n        imageConfig.name ?? config.defaultModelName ?? \"mock-image-model\",\n        imageResponses,\n        imageConfig.pricing ?? config.imagePricing,\n      );\n      imageModels.push(model);\n      return model;\n    },\n    speech(speechConfig: SpeechModelConfig) {\n      const model = new MockSpeechModel(\n        speechConfig.name ?? config.defaultModelName ?? \"mock-speech-model\",\n        speechResponses,\n        speechConfig.pricing ?? config.speechPricing,\n      );\n      speechModels.push(model);\n      return model;\n    },\n    transcribe(transcribeConfig: TranscriptionModelConfig) {\n      const model = new MockTranscriptionModel(\n        transcribeConfig.name ?? config.defaultModelName ?? \"mock-transcription-model\",\n        transcriptionResponses,\n        transcribeConfig.pricing ?? config.transcriptionPricing,\n      );\n      transcriptionModels.push(model);\n      return model;\n    },\n    async count(text: string, _model?: string): Promise<number> {\n      return approximateTokenCount(text);\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,QAAQ,SAAwB,CAAC,GAS/C;CACA,MAAM,SAAsB,CAAC;CAC7B,MAAM,cAAgC,CAAC;CACvC,MAAM,eAAkC,CAAC;CACzC,MAAM,sBAAgD,CAAC;CACvD,MAAM,YAAY,OAAO,aAAa,CAAC,EAAE,SAAS,gBAAgB,CAAC;CACnE,MAAM,iBAAiB,OAAO,kBAAkB,CAAC,CAAC,CAAC;CACnD,MAAM,kBAAkB,OAAO,mBAAmB,CAAC,CAAC,CAAC;CACrD,MAAM,yBAAyB,OAAO,0BAA0B,CAAC,CAAC,CAAC;CAEnE,OAAO;EACL;EACA;EACA;EACA;EACA,MAAM,aAA0B;GAC9B,MAAM,QAAQ,IAAI,UAChB,YAAY,QAAQ,OAAO,oBAAoB,cAC/C,WACA,OAAO,YACT;GACA,OAAO,KAAK,KAAK;GACjB,OAAO;EACT;EACA,MAAM,aAA+B;GACnC,MAAM,QAAQ,IAAI,eAChB,YAAY,QAAQ,OAAO,oBAAoB,oBAC/C,gBACA,YAAY,WAAW,OAAO,YAChC;GACA,YAAY,KAAK,KAAK;GACtB,OAAO;EACT;EACA,OAAO,cAAiC;GACtC,MAAM,QAAQ,IAAI,gBAChB,aAAa,QAAQ,OAAO,oBAAoB,qBAChD,iBACA,aAAa,WAAW,OAAO,aACjC;GACA,aAAa,KAAK,KAAK;GACvB,OAAO;EACT;EACA,WAAW,kBAA4C;GACrD,MAAM,QAAQ,IAAI,uBAChB,iBAAiB,QAAQ,OAAO,oBAAoB,4BACpD,wBACA,iBAAiB,WAAW,OAAO,oBACrC;GACA,oBAAoB,KAAK,KAAK;GAC9B,OAAO;EACT;EACA,MAAM,MAAM,MAAc,QAAkC;GAC1D,OAAO,sBAAsB,IAAI;EACnC;CACF;AACF"}

package/esm/mock/mock-speech-model.d.mts

@@ -0,0 +1,31 @@
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { GeneratedAudio, SpeechGenerationResponse, SpeechModelContract, SpeechModelPricing, SpeechOptions } from "../contracts/speech-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/mock/mock-speech-model.d.ts
+/** One scripted response for a {@link MockSpeechModel}. */
+type MockSpeechResponse = {
+  audio?: GeneratedAudio;
+  usage?: Usage; /** Characters synthesized; defaults to the input text length. */
+  characters?: number;
+  error?: Error;
+  delay?: number;
+};
+/** One recorded `generate()` invocation, for test assertions. */
+type MockSpeechCall = {
+  text: string;
+  options: SpeechOptions | undefined;
+};
+/** Deterministic {@link SpeechModelContract} double for tests — no HTTP. */
+declare class MockSpeechModel implements SpeechModelContract {
+  readonly name: string;
+  private readonly responses;
+  readonly pricing?: SpeechModelPricing | undefined;
+  readonly provider = "mock";
+  readonly calls: MockSpeechCall[];
+  private callIndex;
+  constructor(name: string, responses: MockSpeechResponse[], pricing?: SpeechModelPricing | undefined);
+  generate(text: string, options?: SpeechOptions): Promise<SpeechGenerationResponse>;
+}
+//#endregion
+export { MockSpeechCall, MockSpeechModel, MockSpeechResponse };
+//# sourceMappingURL=mock-speech-model.d.mts.map

package/esm/mock/mock-speech-model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-speech-model.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-speech-model.ts"],"mappings":";;;;;KAUY,kBAAA;EACV,KAAA,GAAQ,cAAA;EACR,KAAA,GAAQ,KAAA;EAER,UAAA;EACA,KAAA,GAAQ,KAAA;EACR,KAAA;AAAA;;KAIU,cAAA;EAAmB,IAAA;EAAc,OAAA,EAAS,aAAa;AAAA;;cAGtD,eAAA,YAA2B,mBAAA;EAAA,SAOpB,IAAA;EAAA,iBACC,SAAA;EAAA,SACD,OAAA,GAAU,kBAAA;EAAA,SARZ,QAAA;EAAA,SACA,KAAA,EAAO,cAAA;EAAA,QAEf,SAAA;cAGU,IAAA,UACC,SAAA,EAAW,kBAAA,IACZ,OAAA,GAAU,kBAAA;EAGf,QAAA,CAAS,IAAA,UAAc,OAAA,GAAU,aAAA,GAAgB,OAAA,CAAQ,wBAAA;AAAA"}

package/esm/mock/mock-speech-model.mjs

@@ -0,0 +1,39 @@
+//#region ../@warlock.js/ai/src/mock/mock-speech-model.ts
+/** Deterministic {@link SpeechModelContract} double for tests — no HTTP. */
+var MockSpeechModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async generate(text, options) {
+		this.calls.push({
+			text,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		return {
+			audio: response.audio ?? {
+				type: "base64",
+				base64: "AAAA",
+				mediaType: "audio/mpeg"
+			},
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			},
+			characters: response.characters ?? text.length
+		};
+	}
+};
+
+//#endregion
+export { MockSpeechModel };
+//# sourceMappingURL=mock-speech-model.mjs.map

package/esm/mock/mock-speech-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-speech-model.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-speech-model.ts"],"sourcesContent":["import type {\n  GeneratedAudio,\n  SpeechGenerationResponse,\n  SpeechModelContract,\n  SpeechModelPricing,\n  SpeechOptions,\n} from \"../contracts/speech-model.contract\";\nimport type { Usage } from \"../contracts/result/usage.type\";\n\n/** One scripted response for a {@link MockSpeechModel}. */\nexport type MockSpeechResponse = {\n  audio?: GeneratedAudio;\n  usage?: Usage;\n  /** Characters synthesized; defaults to the input text length. */\n  characters?: number;\n  error?: Error;\n  delay?: number;\n};\n\n/** One recorded `generate()` invocation, for test assertions. */\nexport type MockSpeechCall = { text: string; options: SpeechOptions | undefined };\n\n/** Deterministic {@link SpeechModelContract} double for tests — no HTTP. */\nexport class MockSpeechModel implements SpeechModelContract {\n  public readonly provider = \"mock\";\n  public readonly calls: MockSpeechCall[] = [];\n\n  private callIndex = 0;\n\n  public constructor(\n    public readonly name: string,\n    private readonly responses: MockSpeechResponse[],\n    public readonly pricing?: SpeechModelPricing,\n  ) {}\n\n  public async generate(text: string, options?: SpeechOptions): Promise<SpeechGenerationResponse> {\n    this.calls.push({ text, options });\n\n    const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};\n    this.callIndex += 1;\n\n    if (response.delay) {\n      await new Promise((resolve) => setTimeout(resolve, response.delay));\n    }\n    if (response.error) {\n      throw response.error;\n    }\n\n    return {\n      audio: response.audio ?? { type: \"base64\", base64: \"AAAA\", mediaType: \"audio/mpeg\" },\n      usage: response.usage ?? { input: 0, output: 0, total: 0 },\n      characters: response.characters ?? text.length,\n    };\n  }\n}\n"],"mappings":";;AAuBA,IAAa,kBAAb,MAA4D;CAM1D,AAAO,YACL,AAAgB,MAChB,AAAiB,WACjB,AAAgB,SAChB;EAHgB;EACC;EACD;kBARS;eACe,CAAC;mBAEvB;CAMjB;CAEH,MAAa,SAAS,MAAc,SAA4D;EAC9F,KAAK,MAAM,KAAK;GAAE;GAAM;EAAQ,CAAC;EAEjC,MAAM,WAAW,KAAK,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,UAAU,SAAS,CAAC,MAAM,CAAC;EACzF,KAAK,aAAa;EAElB,IAAI,SAAS,OACX,MAAM,IAAI,SAAS,YAAY,WAAW,SAAS,SAAS,KAAK,CAAC;EAEpE,IAAI,SAAS,OACX,MAAM,SAAS;EAGjB,OAAO;GACL,OAAO,SAAS,SAAS;IAAE,MAAM;IAAU,QAAQ;IAAQ,WAAW;GAAa;GACnF,OAAO,SAAS,SAAS;IAAE,OAAO;IAAG,QAAQ;IAAG,OAAO;GAAE;GACzD,YAAY,SAAS,cAAc,KAAK;EAC1C;CACF;AACF"}

package/esm/mock/mock-transcription-model.d.mts

@@ -0,0 +1,32 @@
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { AudioInput, TranscribeOptions, TranscriptionModelContract, TranscriptionModelPricing, TranscriptionResponse, TranscriptionSegment } from "../contracts/transcription-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/mock/mock-transcription-model.d.ts
+/** One scripted response for a {@link MockTranscriptionModel}. */
+type MockTranscriptionResponse = {
+  text?: string;
+  segments?: TranscriptionSegment[];
+  durationSeconds?: number;
+  usage?: Usage;
+  error?: Error;
+  delay?: number;
+};
+/** One recorded `transcribe()` invocation, for test assertions. */
+type MockTranscriptionCall = {
+  audio: AudioInput;
+  options: TranscribeOptions | undefined;
+};
+/** Deterministic {@link TranscriptionModelContract} double for tests — no HTTP. */
+declare class MockTranscriptionModel implements TranscriptionModelContract {
+  readonly name: string;
+  private readonly responses;
+  readonly pricing?: TranscriptionModelPricing | undefined;
+  readonly provider = "mock";
+  readonly calls: MockTranscriptionCall[];
+  private callIndex;
+  constructor(name: string, responses: MockTranscriptionResponse[], pricing?: TranscriptionModelPricing | undefined);
+  transcribe(audio: AudioInput, options?: TranscribeOptions): Promise<TranscriptionResponse>;
+}
+//#endregion
+export { MockTranscriptionCall, MockTranscriptionModel, MockTranscriptionResponse };
+//# sourceMappingURL=mock-transcription-model.d.mts.map

package/esm/mock/mock-transcription-model.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-transcription-model.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-transcription-model.ts"],"mappings":";;;;;KAWY,yBAAA;EACV,IAAA;EACA,QAAA,GAAW,oBAAA;EACX,eAAA;EACA,KAAA,GAAQ,KAAA;EACR,KAAA,GAAQ,KAAA;EACR,KAAA;AAAA;;KAIU,qBAAA;EAA0B,KAAA,EAAO,UAAA;EAAY,OAAA,EAAS,iBAAiB;AAAA;;cAGtE,sBAAA,YAAkC,0BAAA;EAAA,SAO3B,IAAA;EAAA,iBACC,SAAA;EAAA,SACD,OAAA,GAAU,yBAAA;EAAA,SARZ,QAAA;EAAA,SACA,KAAA,EAAO,qBAAA;EAAA,QAEf,SAAA;cAGU,IAAA,UACC,SAAA,EAAW,yBAAA,IACZ,OAAA,GAAU,yBAAA;EAGf,UAAA,CACX,KAAA,EAAO,UAAA,EACP,OAAA,GAAU,iBAAA,GACT,OAAA,CAAQ,qBAAA;AAAA"}

package/esm/mock/mock-transcription-model.mjs

@@ -0,0 +1,36 @@
+//#region ../@warlock.js/ai/src/mock/mock-transcription-model.ts
+/** Deterministic {@link TranscriptionModelContract} double for tests — no HTTP. */
+var MockTranscriptionModel = class {
+	constructor(name, responses, pricing) {
+		this.name = name;
+		this.responses = responses;
+		this.pricing = pricing;
+		this.provider = "mock";
+		this.calls = [];
+		this.callIndex = 0;
+	}
+	async transcribe(audio, options) {
+		this.calls.push({
+			audio,
+			options
+		});
+		const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};
+		this.callIndex += 1;
+		if (response.delay) await new Promise((resolve) => setTimeout(resolve, response.delay));
+		if (response.error) throw response.error;
+		return {
+			text: response.text ?? "mock transcript",
+			...response.segments ? { segments: response.segments } : {},
+			...response.durationSeconds !== void 0 ? { durationSeconds: response.durationSeconds } : {},
+			usage: response.usage ?? {
+				input: 0,
+				output: 0,
+				total: 0
+			}
+		};
+	}
+};
+
+//#endregion
+export { MockTranscriptionModel };
+//# sourceMappingURL=mock-transcription-model.mjs.map

package/esm/mock/mock-transcription-model.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-transcription-model.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-transcription-model.ts"],"sourcesContent":["import type { Usage } from \"../contracts/result/usage.type\";\nimport type {\n  AudioInput,\n  TranscribeOptions,\n  TranscriptionModelContract,\n  TranscriptionModelPricing,\n  TranscriptionResponse,\n  TranscriptionSegment,\n} from \"../contracts/transcription-model.contract\";\n\n/** One scripted response for a {@link MockTranscriptionModel}. */\nexport type MockTranscriptionResponse = {\n  text?: string;\n  segments?: TranscriptionSegment[];\n  durationSeconds?: number;\n  usage?: Usage;\n  error?: Error;\n  delay?: number;\n};\n\n/** One recorded `transcribe()` invocation, for test assertions. */\nexport type MockTranscriptionCall = { audio: AudioInput; options: TranscribeOptions | undefined };\n\n/** Deterministic {@link TranscriptionModelContract} double for tests — no HTTP. */\nexport class MockTranscriptionModel implements TranscriptionModelContract {\n  public readonly provider = \"mock\";\n  public readonly calls: MockTranscriptionCall[] = [];\n\n  private callIndex = 0;\n\n  public constructor(\n    public readonly name: string,\n    private readonly responses: MockTranscriptionResponse[],\n    public readonly pricing?: TranscriptionModelPricing,\n  ) {}\n\n  public async transcribe(\n    audio: AudioInput,\n    options?: TranscribeOptions,\n  ): Promise<TranscriptionResponse> {\n    this.calls.push({ audio, options });\n\n    const response = this.responses[Math.min(this.callIndex, this.responses.length - 1)] ?? {};\n    this.callIndex += 1;\n\n    if (response.delay) {\n      await new Promise((resolve) => setTimeout(resolve, response.delay));\n    }\n    if (response.error) {\n      throw response.error;\n    }\n\n    return {\n      text: response.text ?? \"mock transcript\",\n      ...(response.segments ? { segments: response.segments } : {}),\n      ...(response.durationSeconds !== undefined\n        ? { durationSeconds: response.durationSeconds }\n        : {}),\n      usage: response.usage ?? { input: 0, output: 0, total: 0 },\n    };\n  }\n}\n"],"mappings":";;AAwBA,IAAa,yBAAb,MAA0E;CAMxE,AAAO,YACL,AAAgB,MAChB,AAAiB,WACjB,AAAgB,SAChB;EAHgB;EACC;EACD;kBARS;eACsB,CAAC;mBAE9B;CAMjB;CAEH,MAAa,WACX,OACA,SACgC;EAChC,KAAK,MAAM,KAAK;GAAE;GAAO;EAAQ,CAAC;EAElC,MAAM,WAAW,KAAK,UAAU,KAAK,IAAI,KAAK,WAAW,KAAK,UAAU,SAAS,CAAC,MAAM,CAAC;EACzF,KAAK,aAAa;EAElB,IAAI,SAAS,OACX,MAAM,IAAI,SAAS,YAAY,WAAW,SAAS,SAAS,KAAK,CAAC;EAEpE,IAAI,SAAS,OACX,MAAM,SAAS;EAGjB,OAAO;GACL,MAAM,SAAS,QAAQ;GACvB,GAAI,SAAS,WAAW,EAAE,UAAU,SAAS,SAAS,IAAI,CAAC;GAC3D,GAAI,SAAS,oBAAoB,SAC7B,EAAE,iBAAiB,SAAS,gBAAgB,IAC5C,CAAC;GACL,OAAO,SAAS,SAAS;IAAE,OAAO;IAAG,QAAQ;IAAG,OAAO;GAAE;EAC3D;CACF;AACF"}

package/esm/object-stream/index.d.mts

@@ -0,0 +1,2 @@
+import { ObjectStreamEvent, StreamObjectParams, collectStreamObject, streamObject } from "./stream-object.mjs";
+import { parsePartialJson } from "./parse-partial-json.mjs";

package/esm/object-stream/index.mjs

@@ -0,0 +1,4 @@
+import { parsePartialJson } from "./parse-partial-json.mjs";
+import { collectStreamObject, streamObject } from "./stream-object.mjs";
+
+export {  };

package/esm/object-stream/parse-partial-json.d.mts

@@ -0,0 +1,22 @@
+//#region ../@warlock.js/ai/src/object-stream/parse-partial-json.d.ts
+/**
+ * Best-effort parse of a possibly-truncated JSON string into the value it
+ * is "on its way to" becoming. Used by {@link streamObject} to emit a
+ * partial object snapshot from each streamed delta before the full reply
+ * has arrived.
+ *
+ * Returns `undefined` when the prefix can't yet be coerced into a value
+ * (so the caller simply waits for more text). The FINAL parse in
+ * `streamObject` is always strict `JSON.parse` — this tolerant parser only
+ * powers the in-flight snapshots, so a too-clever completion never affects
+ * the authoritative result.
+ *
+ * @example
+ * parsePartialJson('{"name":"Al');      // → { name: "Al" }
+ * parsePartialJson('{"items":[1,2,');   // → { items: [1, 2] }
+ * parsePartialJson('{"a":1,"b"');       // → { a: 1 } (drops the dangling key)
+ */
+declare function parsePartialJson(text: string): unknown | undefined;
+//#endregion
+export { parsePartialJson };
+//# sourceMappingURL=parse-partial-json.d.mts.map

package/esm/object-stream/parse-partial-json.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-partial-json.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/object-stream/parse-partial-json.ts"],"mappings":";;AAiBA;;;;AAA6C;;;;;;;;;;;;iBAA7B,gBAAA,CAAiB,IAAY"}

package/esm/object-stream/parse-partial-json.mjs

@@ -0,0 +1,78 @@
+//#region ../@warlock.js/ai/src/object-stream/parse-partial-json.ts
+/**
+* Best-effort parse of a possibly-truncated JSON string into the value it
+* is "on its way to" becoming. Used by {@link streamObject} to emit a
+* partial object snapshot from each streamed delta before the full reply
+* has arrived.
+*
+* Returns `undefined` when the prefix can't yet be coerced into a value
+* (so the caller simply waits for more text). The FINAL parse in
+* `streamObject` is always strict `JSON.parse` — this tolerant parser only
+* powers the in-flight snapshots, so a too-clever completion never affects
+* the authoritative result.
+*
+* @example
+* parsePartialJson('{"name":"Al');      // → { name: "Al" }
+* parsePartialJson('{"items":[1,2,');   // → { items: [1, 2] }
+* parsePartialJson('{"a":1,"b"');       // → { a: 1 } (drops the dangling key)
+*/
+function parsePartialJson(text) {
+	const trimmed = text.trim();
+	if (!trimmed) return void 0;
+	const direct = tryParse(trimmed);
+	if (direct.ok) return direct.value;
+	const completed = completePartialJson(trimmed);
+	if (completed === void 0) return void 0;
+	const parsed = tryParse(completed);
+	return parsed.ok ? parsed.value : void 0;
+}
+function tryParse(text) {
+	try {
+		return {
+			ok: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return { ok: false };
+	}
+}
+/**
+* Reconstruct a parseable JSON string from a truncated prefix by closing
+* open strings/containers and trimming dangling separators, keys, and
+* partial literals. Tries the most faithful completion first, then falls
+* back to dropping the unfinished tail.
+*/
+function completePartialJson(text) {
+	const stack = [];
+	let inString = false;
+	let escaped = false;
+	for (const ch of text) {
+		if (inString) {
+			if (escaped) escaped = false;
+			else if (ch === "\\") escaped = true;
+			else if (ch === "\"") inString = false;
+			continue;
+		}
+		if (ch === "\"") inString = true;
+		else if (ch === "{" || ch === "[") stack.push(ch);
+		else if (ch === "}" || ch === "]") stack.pop();
+	}
+	const closers = () => stack.map((c) => c === "{" ? "}" : "]").reverse().join("");
+	let core = text;
+	if (inString) core += "\"";
+	core = core.replace(/\s+$/, "");
+	if (core.endsWith(",")) core = core.slice(0, -1);
+	if (core.endsWith(":")) core += "null";
+	const attempts = [core + closers()];
+	if (stack[stack.length - 1] === "{") {
+		const droppedKey = core.replace(/,?\s*"(?:[^"\\]|\\.)*"\s*$/, "");
+		attempts.push(droppedKey.replace(/,\s*$/, "") + closers());
+	}
+	const droppedLiteral = core.replace(/[:,]?\s*[A-Za-z0-9.+\-eE]+$/, (match) => match.trimStart().startsWith(":") ? ":null" : "");
+	attempts.push(droppedLiteral.replace(/,\s*$/, "") + closers());
+	for (const candidate of attempts) if (tryParse(candidate).ok) return candidate;
+}
+
+//#endregion
+export { parsePartialJson };
+//# sourceMappingURL=parse-partial-json.mjs.map

package/esm/object-stream/parse-partial-json.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-partial-json.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/object-stream/parse-partial-json.ts"],"sourcesContent":["/**\n * Best-effort parse of a possibly-truncated JSON string into the value it\n * is \"on its way to\" becoming. Used by {@link streamObject} to emit a\n * partial object snapshot from each streamed delta before the full reply\n * has arrived.\n *\n * Returns `undefined` when the prefix can't yet be coerced into a value\n * (so the caller simply waits for more text). The FINAL parse in\n * `streamObject` is always strict `JSON.parse` — this tolerant parser only\n * powers the in-flight snapshots, so a too-clever completion never affects\n * the authoritative result.\n *\n * @example\n * parsePartialJson('{\"name\":\"Al');      // → { name: \"Al\" }\n * parsePartialJson('{\"items\":[1,2,');   // → { items: [1, 2] }\n * parsePartialJson('{\"a\":1,\"b\"');       // → { a: 1 } (drops the dangling key)\n */\nexport function parsePartialJson(text: string): unknown | undefined {\n  const trimmed = text.trim();\n  if (!trimmed) return undefined;\n\n  // Fast path: already-valid JSON.\n  const direct = tryParse(trimmed);\n  if (direct.ok) return direct.value;\n\n  const completed = completePartialJson(trimmed);\n  if (completed === undefined) return undefined;\n\n  const parsed = tryParse(completed);\n  return parsed.ok ? parsed.value : undefined;\n}\n\nfunction tryParse(text: string): { ok: true; value: unknown } | { ok: false } {\n  try {\n    return { ok: true, value: JSON.parse(text) };\n  } catch {\n    return { ok: false };\n  }\n}\n\n/**\n * Reconstruct a parseable JSON string from a truncated prefix by closing\n * open strings/containers and trimming dangling separators, keys, and\n * partial literals. Tries the most faithful completion first, then falls\n * back to dropping the unfinished tail.\n */\nfunction completePartialJson(text: string): string | undefined {\n  const stack: Array<\"{\" | \"[\"> = [];\n  let inString = false;\n  let escaped = false;\n\n  for (const ch of text) {\n    if (inString) {\n      if (escaped) escaped = false;\n      else if (ch === \"\\\\\") escaped = true;\n      else if (ch === '\"') inString = false;\n      continue;\n    }\n    if (ch === '\"') inString = true;\n    else if (ch === \"{\" || ch === \"[\") stack.push(ch);\n    else if (ch === \"}\" || ch === \"]\") stack.pop();\n  }\n\n  const closers = () =>\n    stack\n      .map(c => (c === \"{\" ? \"}\" : \"]\"))\n      .reverse()\n      .join(\"\");\n\n  // Faithful completion: close an open string, drop a trailing comma,\n  // fill a dangling `key:` with null, then close containers.\n  let core = text;\n  if (inString) core += '\"';\n  core = core.replace(/\\s+$/, \"\");\n  if (core.endsWith(\",\")) core = core.slice(0, -1);\n  if (core.endsWith(\":\")) core += \"null\";\n\n  const attempts: string[] = [core + closers()];\n\n  // Fallback 1: drop a dangling object key (a `\"...\"` with no value yet).\n  if (stack[stack.length - 1] === \"{\") {\n    const droppedKey = core.replace(/,?\\s*\"(?:[^\"\\\\]|\\\\.)*\"\\s*$/, \"\");\n    attempts.push(droppedKey.replace(/,\\s*$/, \"\") + closers());\n  }\n\n  // Fallback 2: drop a partial trailing literal / number (e.g. `tr`, `12.`).\n  const droppedLiteral = core.replace(/[:,]?\\s*[A-Za-z0-9.+\\-eE]+$/, match =>\n    match.trimStart().startsWith(\":\") ? \":null\" : \"\",\n  );\n  attempts.push(droppedLiteral.replace(/,\\s*$/, \"\") + closers());\n\n  for (const candidate of attempts) {\n    if (tryParse(candidate).ok) return candidate;\n  }\n\n  return undefined;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAiBA,SAAgB,iBAAiB,MAAmC;CAClE,MAAM,UAAU,KAAK,KAAK;CAC1B,IAAI,CAAC,SAAS,OAAO;CAGrB,MAAM,SAAS,SAAS,OAAO;CAC/B,IAAI,OAAO,IAAI,OAAO,OAAO;CAE7B,MAAM,YAAY,oBAAoB,OAAO;CAC7C,IAAI,cAAc,QAAW,OAAO;CAEpC,MAAM,SAAS,SAAS,SAAS;CACjC,OAAO,OAAO,KAAK,OAAO,QAAQ;AACpC;AAEA,SAAS,SAAS,MAA4D;CAC5E,IAAI;EACF,OAAO;GAAE,IAAI;GAAM,OAAO,KAAK,MAAM,IAAI;EAAE;CAC7C,QAAQ;EACN,OAAO,EAAE,IAAI,MAAM;CACrB;AACF;;;;;;;AAQA,SAAS,oBAAoB,MAAkC;CAC7D,MAAM,QAA0B,CAAC;CACjC,IAAI,WAAW;CACf,IAAI,UAAU;CAEd,KAAK,MAAM,MAAM,MAAM;EACrB,IAAI,UAAU;GACZ,IAAI,SAAS,UAAU;QAClB,IAAI,OAAO,MAAM,UAAU;QAC3B,IAAI,OAAO,MAAK,WAAW;GAChC;EACF;EACA,IAAI,OAAO,MAAK,WAAW;OACtB,IAAI,OAAO,OAAO,OAAO,KAAK,MAAM,KAAK,EAAE;OAC3C,IAAI,OAAO,OAAO,OAAO,KAAK,MAAM,IAAI;CAC/C;CAEA,MAAM,gBACJ,MACG,KAAI,MAAM,MAAM,MAAM,MAAM,GAAI,CAAC,CACjC,QAAQ,CAAC,CACT,KAAK,EAAE;CAIZ,IAAI,OAAO;CACX,IAAI,UAAU,QAAQ;CACtB,OAAO,KAAK,QAAQ,QAAQ,EAAE;CAC9B,IAAI,KAAK,SAAS,GAAG,GAAG,OAAO,KAAK,MAAM,GAAG,EAAE;CAC/C,IAAI,KAAK,SAAS,GAAG,GAAG,QAAQ;CAEhC,MAAM,WAAqB,CAAC,OAAO,QAAQ,CAAC;CAG5C,IAAI,MAAM,MAAM,SAAS,OAAO,KAAK;EACnC,MAAM,aAAa,KAAK,QAAQ,8BAA8B,EAAE;EAChE,SAAS,KAAK,WAAW,QAAQ,SAAS,EAAE,IAAI,QAAQ,CAAC;CAC3D;CAGA,MAAM,iBAAiB,KAAK,QAAQ,gCAA+B,UACjE,MAAM,UAAU,CAAC,CAAC,WAAW,GAAG,IAAI,UAAU,EAChD;CACA,SAAS,KAAK,eAAe,QAAQ,SAAS,EAAE,IAAI,QAAQ,CAAC;CAE7D,KAAK,MAAM,aAAa,UACtB,IAAI,SAAS,SAAS,CAAC,CAAC,IAAI,OAAO;AAIvC"}

package/esm/object-stream/stream-object.d.mts

@@ -0,0 +1,68 @@
+import { Message } from "../contracts/conversation-message.type.mjs";
+import { AIError } from "../errors/ai-error.mjs";
+import { Usage } from "../contracts/result/usage.type.mjs";
+import { ModelCallOptions, ModelContract } from "../contracts/model.contract.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region ../@warlock.js/ai/src/object-stream/stream-object.d.ts
+/**
+ * One event in a {@link streamObject} run.
+ *
+ * - `text-delta` — the raw token text as it streams (for a "typing" view).
+ * - `partial` — a best-effort snapshot of the object so far, re-parsed
+ *   from the accumulated text on each delta (only emitted when it changed).
+ * - `done` — terminal: the final text is strictly parsed and validated
+ *   against the schema. `valid` + `value` on success; `valid: false` +
+ *   `error` when the output wasn't valid JSON or failed the schema.
+ */
+type ObjectStreamEvent<T> = {
+  type: "text-delta";
+  delta: string;
+} | {
+  type: "partial";
+  value: unknown;
+} | {
+  type: "done";
+  valid: true;
+  value: T;
+  usage: Usage;
+} | {
+  type: "done";
+  valid: false;
+  error: AIError;
+  usage: Usage;
+};
+/** Parameters for {@link streamObject}. */
+type StreamObjectParams<T> = {
+  /** The model to stream from (e.g. `sdk.model({ name })`). */model: ModelContract; /** The prompt messages. */
+  messages: Message[]; /** Standard Schema the final object is validated against. */
+  schema: StandardSchemaV1<T>; /** Extra model call options (e.g. `responseSchema`, `temperature`). */
+  options?: ModelCallOptions;
+};
+/**
+ * Stream a structured object: emit raw token deltas, progressively-parsed
+ * partial-object snapshots, and a final strictly-validated object — the
+ * first-class structured-output streaming primitive (A1). Reuses the
+ * model's existing `stream()` seam; the partial snapshots come from a
+ * tolerant {@link parsePartialJson}, while the terminal `done` event is a
+ * strict `JSON.parse` + schema validation, so an over-eager partial parse
+ * never affects the authoritative result.
+ *
+ * Pair it with a `structuredOutput`-capable model and a `responseSchema`
+ * (via `options`) for the cleanest JSON; otherwise prompt the model to
+ * reply with JSON only.
+ *
+ * @example
+ * for await (const event of streamObject({ model, messages, schema })) {
+ *   if (event.type === "partial") render(event.value);          // live UI
+ *   if (event.type === "done" && event.valid) save(event.value); // final
+ * }
+ */
+declare function streamObject<T>(params: StreamObjectParams<T>): AsyncIterable<ObjectStreamEvent<T>>;
+/** Collect a {@link streamObject} run down to just its terminal event. */
+declare function collectStreamObject<T>(stream: AsyncIterable<ObjectStreamEvent<T>>): Promise<Extract<ObjectStreamEvent<T>, {
+  type: "done";
+}>>;
+//#endregion
+export { ObjectStreamEvent, StreamObjectParams, collectStreamObject, streamObject };
+//# sourceMappingURL=stream-object.d.mts.map

package/esm/object-stream/stream-object.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-object.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/object-stream/stream-object.ts"],"mappings":";;;;;;;;;;AAiBA;;;;;;;KAAY,iBAAA;EACN,IAAA;EAAoB,KAAA;AAAA;EACpB,IAAA;EAAiB,KAAA;AAAA;EACjB,IAAA;EAAc,KAAA;EAAa,KAAA,EAAO,CAAA;EAAG,KAAA,EAAO,KAAA;AAAA;EAC5C,IAAA;EAAc,KAAA;EAAc,KAAA,EAAO,OAAA;EAAS,KAAA,EAAO,KAAA;AAAA;;KAG7C,kBAAA;EAHkD,6DAK5D,KAAA,EAAO,aAAA,EAFG;EAIV,QAAA,EAAU,OAAA,IAJkB;EAM5B,MAAA,EAAQ,gBAAA,CAAiB,CAAA,GAFf;EAIV,OAAA,GAAU,gBAAA;AAAA;;;;;;;;;;;;;;;AAAgB;AAsB5B;;;;iBAAuB,YAAA,IACrB,MAAA,EAAQ,kBAAA,CAAmB,CAAA,IAC1B,aAAA,CAAc,iBAAA,CAAkB,CAAA;;iBAoEb,mBAAA,IACpB,MAAA,EAAQ,aAAA,CAAc,iBAAA,CAAkB,CAAA,KACvC,OAAA,CAAQ,OAAA,CAAQ,iBAAA,CAAkB,CAAA;EAAM,IAAA;AAAA"}

package/esm/object-stream/stream-object.mjs

@@ -0,0 +1,104 @@
+import { SchemaValidationError } from "../errors/schema-validation-error.mjs";
+import "../errors/index.mjs";
+import { parsePartialJson } from "./parse-partial-json.mjs";
+
+//#region ../@warlock.js/ai/src/object-stream/stream-object.ts
+/**
+* Stream a structured object: emit raw token deltas, progressively-parsed
+* partial-object snapshots, and a final strictly-validated object — the
+* first-class structured-output streaming primitive (A1). Reuses the
+* model's existing `stream()` seam; the partial snapshots come from a
+* tolerant {@link parsePartialJson}, while the terminal `done` event is a
+* strict `JSON.parse` + schema validation, so an over-eager partial parse
+* never affects the authoritative result.
+*
+* Pair it with a `structuredOutput`-capable model and a `responseSchema`
+* (via `options`) for the cleanest JSON; otherwise prompt the model to
+* reply with JSON only.
+*
+* @example
+* for await (const event of streamObject({ model, messages, schema })) {
+*   if (event.type === "partial") render(event.value);          // live UI
+*   if (event.type === "done" && event.valid) save(event.value); // final
+* }
+*/
+async function* streamObject(params) {
+	const { model, messages, schema, options } = params;
+	let accumulated = "";
+	let lastPartialKey;
+	let usage = {
+		input: 0,
+		output: 0,
+		total: 0
+	};
+	for await (const chunk of model.stream(messages, options)) if (chunk.type === "delta") {
+		accumulated += chunk.content;
+		yield {
+			type: "text-delta",
+			delta: chunk.content
+		};
+		const partial = parsePartialJson(accumulated);
+		if (partial !== void 0) {
+			const key = safeStringify(partial);
+			if (key !== lastPartialKey) {
+				lastPartialKey = key;
+				yield {
+					type: "partial",
+					value: partial
+				};
+			}
+		}
+	} else if (chunk.type === "done") usage = chunk.usage;
+	yield await finalize(accumulated, schema, usage);
+}
+/** Strict parse + schema validation of the complete streamed text. */
+async function finalize(text, schema, usage) {
+	const cleaned = stripJsonFences(text).trim();
+	let parsed;
+	try {
+		parsed = JSON.parse(cleaned);
+	} catch (cause) {
+		return {
+			type: "done",
+			valid: false,
+			error: new SchemaValidationError("streamObject: the final streamed output was not valid JSON", { cause }),
+			usage
+		};
+	}
+	const result = await schema["~standard"].validate(parsed);
+	if ("issues" in result && result.issues) return {
+		type: "done",
+		valid: false,
+		error: new SchemaValidationError("streamObject: the streamed object failed schema validation", { issues: result.issues }),
+		usage
+	};
+	return {
+		type: "done",
+		valid: true,
+		value: result.value,
+		usage
+	};
+}
+/** Collect a {@link streamObject} run down to just its terminal event. */
+async function collectStreamObject(stream) {
+	let done;
+	for await (const event of stream) if (event.type === "done") done = event;
+	if (!done) throw new SchemaValidationError("streamObject: stream ended without a terminal event");
+	return done;
+}
+/** Strip a leading/trailing ```json fence the model may wrap output in. */
+function stripJsonFences(text) {
+	const fenced = text.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+	return fenced ? fenced[1] : text;
+}
+function safeStringify(value) {
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+//#endregion
+export { collectStreamObject, streamObject };
+//# sourceMappingURL=stream-object.mjs.map

package/esm/object-stream/stream-object.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-object.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/object-stream/stream-object.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\nimport type { Message } from \"../contracts/conversation-message.type\";\nimport type { ModelCallOptions, ModelContract } from \"../contracts/model.contract\";\nimport type { Usage } from \"../contracts/result/usage.type\";\nimport { AIError, SchemaValidationError } from \"../errors\";\nimport { parsePartialJson } from \"./parse-partial-json\";\n\n/**\n * One event in a {@link streamObject} run.\n *\n * - `text-delta` — the raw token text as it streams (for a \"typing\" view).\n * - `partial` — a best-effort snapshot of the object so far, re-parsed\n *   from the accumulated text on each delta (only emitted when it changed).\n * - `done` — terminal: the final text is strictly parsed and validated\n *   against the schema. `valid` + `value` on success; `valid: false` +\n *   `error` when the output wasn't valid JSON or failed the schema.\n */\nexport type ObjectStreamEvent<T> =\n  | { type: \"text-delta\"; delta: string }\n  | { type: \"partial\"; value: unknown }\n  | { type: \"done\"; valid: true; value: T; usage: Usage }\n  | { type: \"done\"; valid: false; error: AIError; usage: Usage };\n\n/** Parameters for {@link streamObject}. */\nexport type StreamObjectParams<T> = {\n  /** The model to stream from (e.g. `sdk.model({ name })`). */\n  model: ModelContract;\n  /** The prompt messages. */\n  messages: Message[];\n  /** Standard Schema the final object is validated against. */\n  schema: StandardSchemaV1<T>;\n  /** Extra model call options (e.g. `responseSchema`, `temperature`). */\n  options?: ModelCallOptions;\n};\n\n/**\n * Stream a structured object: emit raw token deltas, progressively-parsed\n * partial-object snapshots, and a final strictly-validated object — the\n * first-class structured-output streaming primitive (A1). Reuses the\n * model's existing `stream()` seam; the partial snapshots come from a\n * tolerant {@link parsePartialJson}, while the terminal `done` event is a\n * strict `JSON.parse` + schema validation, so an over-eager partial parse\n * never affects the authoritative result.\n *\n * Pair it with a `structuredOutput`-capable model and a `responseSchema`\n * (via `options`) for the cleanest JSON; otherwise prompt the model to\n * reply with JSON only.\n *\n * @example\n * for await (const event of streamObject({ model, messages, schema })) {\n *   if (event.type === \"partial\") render(event.value);          // live UI\n *   if (event.type === \"done\" && event.valid) save(event.value); // final\n * }\n */\nexport async function* streamObject<T>(\n  params: StreamObjectParams<T>,\n): AsyncIterable<ObjectStreamEvent<T>> {\n  const { model, messages, schema, options } = params;\n\n  let accumulated = \"\";\n  let lastPartialKey: string | undefined;\n  let usage: Usage = { input: 0, output: 0, total: 0 };\n\n  for await (const chunk of model.stream(messages, options)) {\n    if (chunk.type === \"delta\") {\n      accumulated += chunk.content;\n      yield { type: \"text-delta\", delta: chunk.content };\n\n      const partial = parsePartialJson(accumulated);\n      if (partial !== undefined) {\n        const key = safeStringify(partial);\n        if (key !== lastPartialKey) {\n          lastPartialKey = key;\n          yield { type: \"partial\", value: partial };\n        }\n      }\n    } else if (chunk.type === \"done\") {\n      usage = chunk.usage;\n    }\n  }\n\n  yield await finalize(accumulated, schema, usage);\n}\n\n/** Strict parse + schema validation of the complete streamed text. */\nasync function finalize<T>(\n  text: string,\n  schema: StandardSchemaV1<T>,\n  usage: Usage,\n): Promise<ObjectStreamEvent<T>> {\n  const cleaned = stripJsonFences(text).trim();\n\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(cleaned);\n  } catch (cause) {\n    return {\n      type: \"done\",\n      valid: false,\n      error: new SchemaValidationError(\n        \"streamObject: the final streamed output was not valid JSON\",\n        { cause },\n      ),\n      usage,\n    };\n  }\n\n  const result = await schema[\"~standard\"].validate(parsed);\n  if (\"issues\" in result && result.issues) {\n    return {\n      type: \"done\",\n      valid: false,\n      error: new SchemaValidationError(\n        \"streamObject: the streamed object failed schema validation\",\n        { issues: result.issues },\n      ),\n      usage,\n    };\n  }\n\n  return { type: \"done\", valid: true, value: (result as { value: T }).value, usage };\n}\n\n/** Collect a {@link streamObject} run down to just its terminal event. */\nexport async function collectStreamObject<T>(\n  stream: AsyncIterable<ObjectStreamEvent<T>>,\n): Promise<Extract<ObjectStreamEvent<T>, { type: \"done\" }>> {\n  let done: Extract<ObjectStreamEvent<T>, { type: \"done\" }> | undefined;\n  for await (const event of stream) {\n    if (event.type === \"done\") done = event;\n  }\n  if (!done) {\n    throw new SchemaValidationError(\"streamObject: stream ended without a terminal event\");\n  }\n  return done;\n}\n\n/** Strip a leading/trailing ```json fence the model may wrap output in. */\nfunction stripJsonFences(text: string): string {\n  const fenced = text.match(/```(?:json)?\\s*([\\s\\S]*?)\\s*```/i);\n  return fenced ? fenced[1] : text;\n}\n\nfunction safeStringify(value: unknown): string {\n  try {\n    return JSON.stringify(value);\n  } catch {\n    return String(value);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAsDA,gBAAuB,aACrB,QACqC;CACrC,MAAM,EAAE,OAAO,UAAU,QAAQ,YAAY;CAE7C,IAAI,cAAc;CAClB,IAAI;CACJ,IAAI,QAAe;EAAE,OAAO;EAAG,QAAQ;EAAG,OAAO;CAAE;CAEnD,WAAW,MAAM,SAAS,MAAM,OAAO,UAAU,OAAO,GACtD,IAAI,MAAM,SAAS,SAAS;EAC1B,eAAe,MAAM;EACrB,MAAM;GAAE,MAAM;GAAc,OAAO,MAAM;EAAQ;EAEjD,MAAM,UAAU,iBAAiB,WAAW;EAC5C,IAAI,YAAY,QAAW;GACzB,MAAM,MAAM,cAAc,OAAO;GACjC,IAAI,QAAQ,gBAAgB;IAC1B,iBAAiB;IACjB,MAAM;KAAE,MAAM;KAAW,OAAO;IAAQ;GAC1C;EACF;CACF,OAAO,IAAI,MAAM,SAAS,QACxB,QAAQ,MAAM;CAIlB,MAAM,MAAM,SAAS,aAAa,QAAQ,KAAK;AACjD;;AAGA,eAAe,SACb,MACA,QACA,OAC+B;CAC/B,MAAM,UAAU,gBAAgB,IAAI,CAAC,CAAC,KAAK;CAE3C,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,OAAO;CAC7B,SAAS,OAAO;EACd,OAAO;GACL,MAAM;GACN,OAAO;GACP,OAAO,IAAI,sBACT,8DACA,EAAE,MAAM,CACV;GACA;EACF;CACF;CAEA,MAAM,SAAS,MAAM,OAAO,YAAY,CAAC,SAAS,MAAM;CACxD,IAAI,YAAY,UAAU,OAAO,QAC/B,OAAO;EACL,MAAM;EACN,OAAO;EACP,OAAO,IAAI,sBACT,8DACA,EAAE,QAAQ,OAAO,OAAO,CAC1B;EACA;CACF;CAGF,OAAO;EAAE,MAAM;EAAQ,OAAO;EAAM,OAAQ,OAAwB;EAAO;CAAM;AACnF;;AAGA,eAAsB,oBACpB,QAC0D;CAC1D,IAAI;CACJ,WAAW,MAAM,SAAS,QACxB,IAAI,MAAM,SAAS,QAAQ,OAAO;CAEpC,IAAI,CAAC,MACH,MAAM,IAAI,sBAAsB,qDAAqD;CAEvF,OAAO;AACT;;AAGA,SAAS,gBAAgB,MAAsB;CAC7C,MAAM,SAAS,KAAK,MAAM,kCAAkC;CAC5D,OAAO,SAAS,OAAO,KAAK;AAC9B;AAEA,SAAS,cAAc,OAAwB;CAC7C,IAAI;EACF,OAAO,KAAK,UAAU,KAAK;CAC7B,QAAQ;EACN,OAAO,OAAO,KAAK;CACrB;AACF"}

package/esm/observe/index.mjs

@@ -0,0 +1,4 @@
+import { getObservers, isObserveAll, registerObserver, setObserveAll } from "./observer-registry.mjs";
+import { notifyObservers, resolveObservers } from "./resolve-observers.mjs";
+
+export {  };

package/esm/observe/observer-registry.d.mts

@@ -0,0 +1,30 @@
+import { Observer } from "./observer.contract.mjs";
+
+//#region ../@warlock.js/ai/src/observe/observer-registry.d.ts
+/**
+ * Register a global {@link Observer}. Every flow that resolves to
+ * "observed" (via `observeAll` or `observe: true`) routes its completed
+ * report to it. An observability tool registers its collector here once,
+ * when its config is applied.
+ */
+declare function registerObserver(observer: Observer): void;
+/**
+ * The currently registered global observers. Returned as a read-only
+ * snapshot reference — callers must not mutate it; use
+ * {@link registerObserver} to add and {@link clearObservers} (test-only)
+ * to reset.
+ */
+declare function getObservers(): readonly Observer[];
+/**
+ * Set the global "observe every flow by default" flag. An observability
+ * tool flips this on when configured with its own observe-all option.
+ */
+declare function setObserveAll(value: boolean): void;
+/**
+ * Read the global "observe every flow by default" flag. Consulted by the
+ * observe-resolution helper when a flow left `observe` undefined.
+ */
+declare function isObserveAll(): boolean;
+//#endregion
+export { getObservers, isObserveAll, registerObserver, setObserveAll };
+//# sourceMappingURL=observer-registry.d.mts.map

package/esm/observe/observer-registry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-registry.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/observe/observer-registry.ts"],"mappings":";;;;;AAwBA;;;;iBAAgB,gBAAA,CAAiB,QAAkB,EAAR,QAAQ;AAUnD;;;;AAAiD;AAQjD;AARA,iBAAgB,YAAA,aAAyB,QAAQ;;;AAQL;AAQ5C;iBARgB,aAAA,CAAc,KAAc;;;AAQhB;;iBAAZ,YAAA"}