libretto 0.2.3 → 0.2.5

package/dist/index.js

@@ -4,6 +4,7 @@ import {
   prettyConsoleSink,
   jsonlConsoleSink
 } from "./shared/logger/sinks.js";
+import { createLLMClientFromModel } from "./shared/llm/ai-sdk-adapter.js";
 import {
   SESSION_STATE_VERSION,
   SessionStatusSchema,
@@ -25,11 +26,7 @@ import {
   downloadViaClick,
   downloadAndSave
 } from "./runtime/download/download.js";
-import {
-  debugPause,
-  DebugPauseSignal,
-  isDebugPauseSignal
-} from "./shared/debug/pause.js";
+import { pause } from "./shared/debug/pause.js";
 import {
   isDebugMode,
   isDryRun,
@@ -52,10 +49,7 @@ import {
   clearHighlights
 } from "./shared/visualization/highlight.js";
 import {
-  launchBrowser,
-  debugPause as debugPause2,
-  DebugPauseSignal as DebugPauseSignal2,
-  isDebugPauseSignal as isDebugPauseSignal2
+  launchBrowser
 } from "./shared/run/api.js";
 import {
   LibrettoWorkflow,
@@ -63,18 +57,16 @@ import {
   workflow
 } from "./shared/workflow/workflow.js";
 export {
-  DebugPauseSignal,
   LIBRETTO_WORKFLOW_BRAND,
   LibrettoWorkflow,
   Logger,
-  DebugPauseSignal2 as RunDebugPauseSignal,
   SESSION_STATE_VERSION,
   SessionStateFileSchema,
   SessionStatusSchema,
   attemptWithRecovery,
   clearHighlights,
   createFileLogSink,
-  debugPause,
+  createLLMClientFromModel,
   defaultLogger,
   detectSubmissionError,
   downloadAndSave,
@@ -89,17 +81,15 @@ export {
   instrumentContext,
   instrumentPage,
   isDebugMode,
-  isDebugPauseSignal,
   isDryRun,
-  isDebugPauseSignal2 as isRunDebugPauseSignal,
   jsonlConsoleSink,
   launchBrowser,
   moveGhostCursor,
   pageRequest,
   parseSessionStateContent,
   parseSessionStateData,
+  pause,
   prettyConsoleSink,
-  debugPause2 as runDebugPause,
   serializeSessionState,
   shouldPauseBeforeMutation,
   showHighlight,

package/dist/shared/debug/index.cjs

@@ -18,15 +18,13 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var debug_exports = {};
 __export(debug_exports, {
-  DebugPauseSignal: () => import_pause.DebugPauseSignal,
-  debugPause: () => import_pause.debugPause,
-  isDebugPauseSignal: () => import_pause.isDebugPauseSignal
+  pause: () => import_pause.pause,
+  setSessionForPause: () => import_pause.setSessionForPause
 });
 module.exports = __toCommonJS(debug_exports);
 var import_pause = require("./pause.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 });

package/dist/shared/debug/index.d.cts

@@ -1,2 +1 @@
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from './pause.cjs';
-import 'playwright';
+export { pause, setSessionForPause } from './pause.cjs';

package/dist/shared/debug/index.d.ts

@@ -1,2 +1 @@
-export { DebugPauseContext, DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal } from './pause.js';
-import 'playwright';
+export { pause, setSessionForPause } from './pause.js';

package/dist/shared/debug/index.js

@@ -1,10 +1,5 @@
-import {
-  debugPause,
-  DebugPauseSignal,
-  isDebugPauseSignal
-} from "./pause.js";
+import { pause, setSessionForPause } from "./pause.js";
 export {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 };

package/dist/shared/debug/pause.cjs

@@ -1,7 +1,9 @@
 "use strict";
+var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __export = (target, all) => {
   for (var name in all)
@@ -15,42 +17,74 @@ var __copyProps = (to, from, except, desc) => {
   }
   return to;
 };
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var pause_exports = {};
 __export(pause_exports, {
-  DebugPauseSignal: () => DebugPauseSignal,
-  debugPause: () => debugPause,
-  isDebugPauseSignal: () => isDebugPauseSignal
+  pause: () => pause,
+  setSessionForPause: () => setSessionForPause
 });
 module.exports = __toCommonJS(pause_exports);
-class DebugPauseSignal extends Error {
-  details;
-  constructor(details) {
-    super(`Workflow paused at ${details.url}`);
-    this.name = "DebugPauseSignal";
-    this.details = details;
+var import_node_fs = require("node:fs");
+var import_promises = require("node:fs/promises");
+let _sessionName;
+function setSessionForPause(session) {
+  _sessionName = session;
+}
+function getSessionFromProcessArgs() {
+  const rawPayload = process.argv[2];
+  if (!rawPayload) return void 0;
+  try {
+    const parsed = JSON.parse(rawPayload);
+    return typeof parsed.session === "string" ? parsed.session : void 0;
+  } catch {
+    return void 0;
   }
 }
-function isDebugPauseSignal(error) {
-  if (!error || typeof error !== "object") return false;
-  const candidate = error;
-  if (candidate.name !== "DebugPauseSignal") return false;
-  return typeof candidate.details?.sessionName === "string" && typeof candidate.details?.pausedAt === "string" && typeof candidate.details?.url === "string";
+function resolveSession() {
+  return _sessionName ?? getSessionFromProcessArgs();
 }
-async function debugPause(context) {
-  const url = context.page.url();
+async function pause() {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const session = resolveSession();
+  if (!session) {
+    return;
+  }
+  const { getPauseSignalPaths, removeSignalIfExists } = await import("../../cli/core/pause-signals.js");
+  const { getSessionDir } = await import("../../cli/core/context.js");
+  const signalPaths = getPauseSignalPaths(session);
+  const { pausedSignalPath, resumeSignalPath } = signalPaths;
+  await (0, import_promises.mkdir)(getSessionDir(session), { recursive: true });
+  await removeSignalIfExists(resumeSignalPath);
   const details = {
-    sessionName: context.session,
+    sessionName: session,
     pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    url
+    url: "unknown"
   };
-  console.log(`[debugPause] Paused at ${url}`);
-  console.log("[debugPause] Signaling pause to supervisor...");
-  throw new DebugPauseSignal(details);
+  await (0, import_promises.writeFile)(pausedSignalPath, JSON.stringify(details, null, 2), "utf8");
+  console.log(`[pause] Paused (session: ${session})`);
+  console.log("[pause] Waiting for resume signal...");
+  const RESUME_POLL_INTERVAL_MS = 250;
+  while (!(0, import_node_fs.existsSync)(resumeSignalPath)) {
+    await new Promise(
+      (resolve) => setTimeout(resolve, RESUME_POLL_INTERVAL_MS)
+    );
+  }
+  await removeSignalIfExists(resumeSignalPath);
+  await removeSignalIfExists(pausedSignalPath);
+  console.log("[pause] Resume signal received. Continuing workflow...");
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 });

package/dist/shared/debug/pause.d.cts

@@ -1,23 +1,16 @@
-import { Page } from 'playwright';
-
-type DebugPauseContext = {
-    page: Page;
-    session: string;
-};
-type DebugPauseDetails = {
-    sessionName: string;
-    pausedAt: string;
-    url: string;
-};
-declare class DebugPauseSignal extends Error {
-    readonly details: DebugPauseDetails;
-    constructor(details: DebugPauseDetails);
-}
-declare function isDebugPauseSignal(error: unknown): error is DebugPauseSignal;
 /**
- * Signals a workflow pause to the caller.
- * This always throws a typed signal that supervisors can intercept.
+ * Called by the CLI runtime to make the session name available to `pause()`.
+ */
+declare function setSessionForPause(session: string): void;
+/**
+ * Standalone pause function.
+ *
+ * - In production (`NODE_ENV === "production"`), returns immediately (no-op).
+ * - Otherwise, writes a `.paused` signal file and polls for a `.resume` signal,
+ *   using the same file-based mechanism as the CLI runner.
+ *
+ * Import directly: `import { pause } from "libretto";`
  */
-declare function debugPause(context: DebugPauseContext): Promise<never>;
+declare function pause(): Promise<void>;
 
-export { type DebugPauseContext, type DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal };
+export { pause, setSessionForPause };

package/dist/shared/debug/pause.d.ts

@@ -1,23 +1,16 @@
-import { Page } from 'playwright';
-
-type DebugPauseContext = {
-    page: Page;
-    session: string;
-};
-type DebugPauseDetails = {
-    sessionName: string;
-    pausedAt: string;
-    url: string;
-};
-declare class DebugPauseSignal extends Error {
-    readonly details: DebugPauseDetails;
-    constructor(details: DebugPauseDetails);
-}
-declare function isDebugPauseSignal(error: unknown): error is DebugPauseSignal;
 /**
- * Signals a workflow pause to the caller.
- * This always throws a typed signal that supervisors can intercept.
+ * Called by the CLI runtime to make the session name available to `pause()`.
+ */
+declare function setSessionForPause(session: string): void;
+/**
+ * Standalone pause function.
+ *
+ * - In production (`NODE_ENV === "production"`), returns immediately (no-op).
+ * - Otherwise, writes a `.paused` signal file and polls for a `.resume` signal,
+ *   using the same file-based mechanism as the CLI runner.
+ *
+ * Import directly: `import { pause } from "libretto";`
  */
-declare function debugPause(context: DebugPauseContext): Promise<never>;
+declare function pause(): Promise<void>;
 
-export { type DebugPauseContext, type DebugPauseDetails, DebugPauseSignal, debugPause, isDebugPauseSignal };
+export { pause, setSessionForPause };

package/dist/shared/debug/pause.js

@@ -1,30 +1,55 @@
-class DebugPauseSignal extends Error {
-  details;
-  constructor(details) {
-    super(`Workflow paused at ${details.url}`);
-    this.name = "DebugPauseSignal";
-    this.details = details;
+import { existsSync } from "node:fs";
+import { mkdir, writeFile } from "node:fs/promises";
+let _sessionName;
+function setSessionForPause(session) {
+  _sessionName = session;
+}
+function getSessionFromProcessArgs() {
+  const rawPayload = process.argv[2];
+  if (!rawPayload) return void 0;
+  try {
+    const parsed = JSON.parse(rawPayload);
+    return typeof parsed.session === "string" ? parsed.session : void 0;
+  } catch {
+    return void 0;
   }
 }
-function isDebugPauseSignal(error) {
-  if (!error || typeof error !== "object") return false;
-  const candidate = error;
-  if (candidate.name !== "DebugPauseSignal") return false;
-  return typeof candidate.details?.sessionName === "string" && typeof candidate.details?.pausedAt === "string" && typeof candidate.details?.url === "string";
+function resolveSession() {
+  return _sessionName ?? getSessionFromProcessArgs();
 }
-async function debugPause(context) {
-  const url = context.page.url();
+async function pause() {
+  if (process.env.NODE_ENV === "production") {
+    return;
+  }
+  const session = resolveSession();
+  if (!session) {
+    return;
+  }
+  const { getPauseSignalPaths, removeSignalIfExists } = await import("../../cli/core/pause-signals.js");
+  const { getSessionDir } = await import("../../cli/core/context.js");
+  const signalPaths = getPauseSignalPaths(session);
+  const { pausedSignalPath, resumeSignalPath } = signalPaths;
+  await mkdir(getSessionDir(session), { recursive: true });
+  await removeSignalIfExists(resumeSignalPath);
   const details = {
-    sessionName: context.session,
+    sessionName: session,
     pausedAt: (/* @__PURE__ */ new Date()).toISOString(),
-    url
+    url: "unknown"
   };
-  console.log(`[debugPause] Paused at ${url}`);
-  console.log("[debugPause] Signaling pause to supervisor...");
-  throw new DebugPauseSignal(details);
+  await writeFile(pausedSignalPath, JSON.stringify(details, null, 2), "utf8");
+  console.log(`[pause] Paused (session: ${session})`);
+  console.log("[pause] Waiting for resume signal...");
+  const RESUME_POLL_INTERVAL_MS = 250;
+  while (!existsSync(resumeSignalPath)) {
+    await new Promise(
+      (resolve) => setTimeout(resolve, RESUME_POLL_INTERVAL_MS)
+    );
+  }
+  await removeSignalIfExists(resumeSignalPath);
+  await removeSignalIfExists(pausedSignalPath);
+  console.log("[pause] Resume signal received. Continuing workflow...");
 }
 export {
-  DebugPauseSignal,
-  debugPause,
-  isDebugPauseSignal
+  pause,
+  setSessionForPause
 };

package/dist/shared/llm/ai-sdk-adapter.cjs

@@ -0,0 +1,67 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var ai_sdk_adapter_exports = {};
+__export(ai_sdk_adapter_exports, {
+  createLLMClientFromModel: () => createLLMClientFromModel
+});
+module.exports = __toCommonJS(ai_sdk_adapter_exports);
+var import_ai = require("ai");
+function createLLMClientFromModel(model) {
+  return {
+    async generateObject(opts) {
+      const { object } = await (0, import_ai.generateObject)({
+        model,
+        schema: opts.schema,
+        prompt: opts.prompt,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    },
+    async generateObjectFromMessages(opts) {
+      const messages = opts.messages.map((msg) => {
+        if (typeof msg.content === "string") {
+          return { role: msg.role, content: msg.content };
+        }
+        if (msg.role === "assistant") {
+          return {
+            role: "assistant",
+            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+          };
+        }
+        return {
+          role: "user",
+          content: msg.content.map(
+            (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
+          )
+        };
+      });
+      const { object } = await (0, import_ai.generateObject)({
+        model,
+        schema: opts.schema,
+        messages,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    }
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createLLMClientFromModel
+});

package/dist/shared/llm/ai-sdk-adapter.d.cts

@@ -0,0 +1,22 @@
+import { LanguageModel } from 'ai';
+import { LLMClient } from './types.cjs';
+import 'zod';
+
+/**
+ * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
+ *
+ * This eliminates the need for consumers to write their own adapter
+ * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
+ * or any other Vercel AI SDK-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClientFromModel } from "libretto/llm";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+ * ```
+ */
+declare function createLLMClientFromModel(model: LanguageModel): LLMClient;
+
+export { createLLMClientFromModel };

package/dist/shared/llm/ai-sdk-adapter.d.ts

@@ -0,0 +1,22 @@
+import { LanguageModel } from 'ai';
+import { LLMClient } from './types.js';
+import 'zod';
+
+/**
+ * Creates a libretto LLMClient from a Vercel AI SDK LanguageModel.
+ *
+ * This eliminates the need for consumers to write their own adapter
+ * when using @ai-sdk/openai, @ai-sdk/anthropic, @ai-sdk/google-vertex,
+ * or any other Vercel AI SDK-compatible provider.
+ *
+ * @example
+ * ```typescript
+ * import { createLLMClientFromModel } from "libretto/llm";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const llmClient = createLLMClientFromModel(openai("gpt-4o"));
+ * ```
+ */
+declare function createLLMClientFromModel(model: LanguageModel): LLMClient;
+
+export { createLLMClientFromModel };

package/dist/shared/llm/ai-sdk-adapter.js

@@ -0,0 +1,43 @@
+import { generateObject } from "ai";
+function createLLMClientFromModel(model) {
+  return {
+    async generateObject(opts) {
+      const { object } = await generateObject({
+        model,
+        schema: opts.schema,
+        prompt: opts.prompt,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    },
+    async generateObjectFromMessages(opts) {
+      const messages = opts.messages.map((msg) => {
+        if (typeof msg.content === "string") {
+          return { role: msg.role, content: msg.content };
+        }
+        if (msg.role === "assistant") {
+          return {
+            role: "assistant",
+            content: msg.content.filter((part) => part.type === "text").map((part) => ({ type: "text", text: part.text }))
+          };
+        }
+        return {
+          role: "user",
+          content: msg.content.map(
+            (part) => part.type === "text" ? { type: "text", text: part.text } : { type: "image", image: part.image }
+          )
+        };
+      });
+      const { object } = await generateObject({
+        model,
+        schema: opts.schema,
+        messages,
+        temperature: opts.temperature ?? 0
+      });
+      return object;
+    }
+  };
+}
+export {
+  createLLMClientFromModel
+};

package/dist/shared/llm/index.cjs

@@ -18,11 +18,14 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var llm_exports = {};
 __export(llm_exports, {
-  createLLMClient: () => import_client.createLLMClient
+  createLLMClient: () => import_client.createLLMClient,
+  createLLMClientFromModel: () => import_ai_sdk_adapter.createLLMClientFromModel
 });
 module.exports = __toCommonJS(llm_exports);
 var import_client = require("./client.js");
+var import_ai_sdk_adapter = require("./ai-sdk-adapter.js");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createLLMClient
+  createLLMClient,
+  createLLMClientFromModel
 });

package/dist/shared/llm/index.d.cts

@@ -1,3 +1,5 @@
 export { LLMClient, Message, MessageContentPart } from './types.cjs';
 export { createLLMClient } from './client.cjs';
+export { createLLMClientFromModel } from './ai-sdk-adapter.cjs';
 import 'zod';
+import 'ai';

package/dist/shared/llm/index.d.ts

@@ -1,3 +1,5 @@
 export { LLMClient, Message, MessageContentPart } from './types.js';
 export { createLLMClient } from './client.js';
+export { createLLMClientFromModel } from './ai-sdk-adapter.js';
 import 'zod';
+import 'ai';

package/dist/shared/llm/index.js

@@ -1,4 +1,6 @@
 import { createLLMClient } from "./client.js";
+import { createLLMClientFromModel } from "./ai-sdk-adapter.js";
 export {
-  createLLMClient
+  createLLMClient,
+  createLLMClientFromModel
 };

package/dist/shared/llm/types.d.cts

@@ -17,13 +17,45 @@ type Message = {
  * Users provide their own implementation backed by any LLM provider
  * (OpenAI, Anthropic, etc.). Libretto uses this interface for AI extraction,
  * recovery agents, and error detection.
+ *
+ * **Error handling:** implementations should throw on failure rather than
+ * returning sentinel values (e.g. `null` or `undefined`). Libretto relies
+ * on exceptions to trigger retry/recovery logic.
+ *
+ * A ready-made adapter for the Vercel AI SDK is available via
+ * {@link createLLMClientFromModel} in `libretto/llm`.
  */
 interface LLMClient {
+    /**
+     * Generate a structured object from a single text prompt.
+     *
+     * The underlying model **must** support structured / JSON output so that
+     * the response can be parsed and validated against the provided Zod schema.
+     *
+     * @param opts.prompt - The text prompt sent to the model.
+     * @param opts.schema - A Zod schema describing the expected response shape.
+     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+     * @returns The parsed object matching the schema.
+     * @throws On LLM or parsing failure.
+     */
     generateObject<T extends z.ZodType>(opts: {
         prompt: string;
         schema: T;
         temperature?: number;
     }): Promise<z.infer<T>>;
+    /**
+     * Generate a structured object from a conversation-style message array.
+     *
+     * Messages may contain **image content** (base64 data URIs via
+     * {@link MessageContentPart}), so the backing model must support
+     * vision / multimodal input when images are present.
+     *
+     * @param opts.messages - Ordered list of user/assistant messages, potentially multimodal.
+     * @param opts.schema - A Zod schema describing the expected response shape.
+     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+     * @returns The parsed object matching the schema.
+     * @throws On LLM or parsing failure.
+     */
     generateObjectFromMessages<T extends z.ZodType>(opts: {
         messages: Message[];
         schema: T;

package/dist/shared/llm/types.d.ts

@@ -17,13 +17,45 @@ type Message = {
  * Users provide their own implementation backed by any LLM provider
  * (OpenAI, Anthropic, etc.). Libretto uses this interface for AI extraction,
  * recovery agents, and error detection.
+ *
+ * **Error handling:** implementations should throw on failure rather than
+ * returning sentinel values (e.g. `null` or `undefined`). Libretto relies
+ * on exceptions to trigger retry/recovery logic.
+ *
+ * A ready-made adapter for the Vercel AI SDK is available via
+ * {@link createLLMClientFromModel} in `libretto/llm`.
  */
 interface LLMClient {
+    /**
+     * Generate a structured object from a single text prompt.
+     *
+     * The underlying model **must** support structured / JSON output so that
+     * the response can be parsed and validated against the provided Zod schema.
+     *
+     * @param opts.prompt - The text prompt sent to the model.
+     * @param opts.schema - A Zod schema describing the expected response shape.
+     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+     * @returns The parsed object matching the schema.
+     * @throws On LLM or parsing failure.
+     */
     generateObject<T extends z.ZodType>(opts: {
         prompt: string;
         schema: T;
         temperature?: number;
     }): Promise<z.infer<T>>;
+    /**
+     * Generate a structured object from a conversation-style message array.
+     *
+     * Messages may contain **image content** (base64 data URIs via
+     * {@link MessageContentPart}), so the backing model must support
+     * vision / multimodal input when images are present.
+     *
+     * @param opts.messages - Ordered list of user/assistant messages, potentially multimodal.
+     * @param opts.schema - A Zod schema describing the expected response shape.
+     * @param opts.temperature - Sampling temperature (default chosen by implementation, typically 0).
+     * @returns The parsed object matching the schema.
+     * @throws On LLM or parsing failure.
+     */
     generateObjectFromMessages<T extends z.ZodType>(opts: {
         messages: Message[];
         schema: T;