apple-llm 0.1.0 → 0.2.0

package/dist/cli.js

@@ -1,15 +1,3054 @@
 #!/usr/bin/env node
-import {
-  AppleLLM,
-  AppleLLMError,
-  captureScreenshot,
-  installCloudShortcut,
-  parseImageFlag,
-  probe
-} from "./chunk-FQTRQ3KP.js";
 
 // src/cli.ts
-import { readFile } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
+
+// src/cloud.ts
+import { execFile as execFile2 } from "child_process";
+import { mkdtemp, readFile, rm, stat, writeFile } from "fs/promises";
+import os from "os";
+import path from "path";
+import { promisify as promisify2 } from "util";
+
+// src/errors.ts
+var AppleLLMError = class extends Error {
+  constructor(message, tier, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+    this.tier = tier;
+    this.name = new.target.name;
+  }
+  tier;
+  code = "APPLE_LLM_ERROR";
+};
+var ModelUnavailableError = class extends AppleLLMError {
+  constructor(message, reason, tier, options) {
+    super(message, tier, options);
+    this.reason = reason;
+  }
+  reason;
+  code = "MODEL_UNAVAILABLE";
+};
+var SchemaRejectedError = class extends AppleLLMError {
+  code = "SCHEMA_REJECTED";
+};
+var SchemaValidationError = class extends AppleLLMError {
+  constructor(message, issues, text, tier) {
+    super(message, tier);
+    this.issues = issues;
+    this.text = text;
+  }
+  issues;
+  text;
+  code = "SCHEMA_VALIDATION";
+};
+var ContextLengthError = class extends AppleLLMError {
+  constructor(message, tier, contextSize, tokenCount) {
+    super(message, tier);
+    this.contextSize = contextSize;
+    this.tokenCount = tokenCount;
+  }
+  contextSize;
+  tokenCount;
+  code = "CONTEXT_LENGTH";
+};
+var QuotaError = class extends AppleLLMError {
+  constructor(message, tier, resetDate) {
+    super(message, tier);
+    this.resetDate = resetDate;
+  }
+  resetDate;
+  code = "QUOTA";
+};
+var TimeoutError = class extends AppleLLMError {
+  code = "TIMEOUT";
+};
+var AbortError = class extends AppleLLMError {
+  code = "ABORTED";
+};
+var SetupRequiredError = class extends AppleLLMError {
+  constructor(message, step, tier) {
+    super(message, tier);
+    this.step = step;
+  }
+  step;
+  code = "SETUP_REQUIRED";
+};
+var RefusalError = class extends AppleLLMError {
+  code = "REFUSAL";
+};
+var ToolExecutionError = class extends AppleLLMError {
+  constructor(message, toolName, options) {
+    super(message, "device", options);
+    this.toolName = toolName;
+  }
+  toolName;
+  code = "TOOL_EXECUTION";
+};
+var ModelBusyError = class extends AppleLLMError {
+  code = "MODEL_BUSY";
+};
+var UnsupportedError = class extends AppleLLMError {
+  code = "UNSUPPORTED";
+};
+function unavailableMessage(reason) {
+  const base = "Apple\u2019s on-device model is not available";
+  if (reason?.includes("appleIntelligenceNotEnabled")) {
+    return `${base}: Apple Intelligence is turned off.
+Enable it in System Settings \u203A Apple Intelligence & Siri, then try again.`;
+  }
+  if (reason?.includes("modelNotReady")) {
+    return `${base}: the model is still downloading.
+Leave the Mac online and plugged in for a few minutes, then try again.`;
+  }
+  if (reason?.includes("deviceNotEligible")) {
+    return `${base}: this Mac is not eligible for Apple Intelligence.`;
+  }
+  if (reason?.includes("unsupportedPlatform")) {
+    return `${base}: this platform is not supported (macOS on Apple Silicon only).`;
+  }
+  if (reason?.includes("unsupportedOSVersion")) {
+    return `${base}: needs macOS 26 or later.`;
+  }
+  if (reason?.includes("noSwiftCompiler")) {
+    return `${base}: no Swift compiler found.
+Install the Xcode command line tools with \`xcode-select --install\`, then try again.`;
+  }
+  return `${base}${reason ? `: ${reason}` : "."}`;
+}
+function toUnavailableReason(reason) {
+  if (reason?.includes("appleIntelligenceNotEnabled")) return "appleIntelligenceNotEnabled";
+  if (reason?.includes("modelNotReady")) return "modelNotReady";
+  if (reason?.includes("deviceNotEligible")) return "deviceNotEligible";
+  if (reason?.includes("unsupportedPlatform")) return "unsupportedPlatform";
+  if (reason?.includes("unsupportedOSVersion")) return "unsupportedOSVersion";
+  if (reason?.includes("noSwiftCompiler")) return "noSwiftCompiler";
+  return "unknown";
+}
+
+// src/json-recovery.ts
+function stripCodeFences(text) {
+  const trimmed = text.trim();
+  const fenced = /```(?:json)?\s*\n?([\s\S]*?)```/i.exec(trimmed);
+  if (fenced?.[1] !== void 0) return fenced[1].trim();
+  if (trimmed.startsWith("```")) {
+    return trimmed.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/, "").trim();
+  }
+  return trimmed;
+}
+function extractJsonSpan(text) {
+  for (let start = 0; start < text.length; start += 1) {
+    const open = text[start];
+    if (open !== "{" && open !== "[") continue;
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i += 1) {
+      const ch = text[i];
+      if (escaped) {
+        escaped = false;
+        continue;
+      }
+      if (ch === "\\") {
+        if (inString) escaped = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = !inString;
+        continue;
+      }
+      if (inString) continue;
+      if (ch === open) depth += 1;
+      else if (ch === close) {
+        depth -= 1;
+        if (depth === 0) return text.slice(start, i + 1);
+      }
+    }
+  }
+  return null;
+}
+function parseLlmJson(raw) {
+  const text = stripCodeFences(raw);
+  try {
+    return JSON.parse(text);
+  } catch {
+  }
+  let offset = 0;
+  while (offset < text.length) {
+    const span = extractJsonSpan(text.slice(offset));
+    if (span === null) break;
+    try {
+      return JSON.parse(span);
+    } catch {
+    }
+    const idx = text.indexOf(span, offset);
+    offset = (idx === -1 ? offset : idx) + 1;
+  }
+  throw new Error(`Model returned invalid JSON: ${raw.slice(0, 200)}`);
+}
+
+// src/target.ts
+import { execFile } from "child_process";
+import { promisify } from "util";
+var execFileAsync = promisify(execFile);
+function isAppleSiliconMac() {
+  return process.platform === "darwin" && process.arch === "arm64";
+}
+function targetTripleFrom(versionOutput, arch = process.arch) {
+  const [major, minor = "0"] = versionOutput.trim().split(".");
+  if (!major || !/^\d+$/.test(major)) return null;
+  if (minor !== void 0 && !/^\d+$/.test(minor)) return null;
+  const cpu = arch === "x64" || arch === "x86_64" ? "x86_64" : "arm64";
+  return `${cpu}-apple-macos${major}.${minor}`;
+}
+async function macosMajor() {
+  try {
+    const { stdout } = await execFileAsync("sw_vers", ["-productVersion"]);
+    const major = Number.parseInt(stdout.trim().split(".")[0] ?? "", 10);
+    return Number.isFinite(major) ? major : null;
+  } catch {
+    return null;
+  }
+}
+async function hostTarget() {
+  for (const [cmd, args] of [
+    ["xcrun", ["--show-sdk-version"]],
+    ["sw_vers", ["-productVersion"]]
+  ]) {
+    try {
+      const { stdout } = await execFileAsync(cmd, args);
+      const triple = targetTripleFrom(stdout);
+      if (triple !== null) return triple;
+    } catch {
+    }
+  }
+  return null;
+}
+async function findSwiftc() {
+  try {
+    await execFileAsync("xcrun", ["-f", "swiftc"]);
+    return { command: "xcrun", prefixArgs: ["swiftc"] };
+  } catch {
+  }
+  const { stat: stat3 } = await import("fs/promises");
+  try {
+    await stat3("/usr/bin/swiftc");
+    return { command: "/usr/bin/swiftc", prefixArgs: [] };
+  } catch {
+    return null;
+  }
+}
+
+// src/cloud.ts
+var execFileAsync2 = promisify2(execFile2);
+var CLOUD_SHORTCUT_NAME = "Apple LLM Cloud";
+var CLOUD_SHORTCUT_NAME_WEB = "Apple LLM Cloud Web";
+var CALL_TIMEOUT_MS = 12e4;
+var CLOUD_CONTEXT_TOKENS = 32768;
+var IMPORT_TIMEOUT_MS = 9e4;
+var IMPORT_POLL_MS = 2e3;
+function shortcutDefinition(webSearch = false) {
+  const parameters = {
+    // Stable UUID: re-running setup re-imports the same action rather than
+    // accumulating variants.
+    UUID: webSearch ? "B47F1A90-2D5E-4C83-A6F1-9E0C7B34D215" : "3827CFFE-3A65-4456-BFA0-49EF061ACEE3",
+    // Plain text out. "Automatic" reshapes the result to suit whatever action
+    // comes next, and nothing comes next here.
+    WFGenerativeResultType: "Text",
+    // The shortcut's own input, spliced in as a variable. U+FFFC is the
+    // object-replacement character marking the attachment's position.
+    WFLLMPrompt: {
+      Value: {
+        string: "\uFFFC",
+        attachmentsByRange: { "{0, 1}": { Type: "ExtensionInput" } }
+      },
+      WFSerializationType: "WFTextTokenString"
+    }
+  };
+  if (webSearch) parameters.WFAllowWebSearch = true;
+  return {
+    WFWorkflowMinimumClientVersionString: "900",
+    WFWorkflowMinimumClientVersion: 900,
+    WFWorkflowClientVersion: "5037.0.17",
+    WFWorkflowIcon: {
+      WFWorkflowIconStartColor: 431817727,
+      WFWorkflowIconGlyphNumber: 61440
+    },
+    WFWorkflowOutputContentItemClasses: [],
+    WFWorkflowHasOutputFallback: false,
+    WFWorkflowActions: [
+      {
+        WFWorkflowActionIdentifier: "is.workflow.actions.askllm",
+        WFWorkflowActionParameters: parameters
+      }
+    ],
+    WFWorkflowInputContentItemClasses: ["WFStringContentItem", "WFRichTextContentItem"],
+    WFWorkflowImportQuestions: [],
+    WFQuickActionSurfaces: [],
+    WFWorkflowTypes: ["WFWorkflowTypeShowInSearch"],
+    WFWorkflowHasShortcutInputVariables: true
+  };
+}
+async function listShortcuts() {
+  try {
+    const { stdout } = await execFileAsync2("shortcuts", ["list"], { timeout: 2e4 });
+    return stdout.split("\n").map((l) => l.trim()).filter((l) => l !== "");
+  } catch {
+    return [];
+  }
+}
+async function installCount(name = CLOUD_SHORTCUT_NAME) {
+  return (await listShortcuts()).filter((l) => l === name).length;
+}
+function cloudSetupHint() {
+  return "The cloud tier needs a one-time shortcut installed.\nRun:  apple-llm setup-cloud\nIt generates and signs the shortcut on this machine \u2014 no account, no API key, nothing uploaded.";
+}
+function duplicateMessage(count, name) {
+  return `${count} shortcuts are named "${name}"; \`shortcuts run\` cannot tell them apart and fails with "Couldn't find shortcut".
+Delete the duplicates in the Shortcuts app, then try again.`;
+}
+async function installCloudShortcut(onProgress, options = {}) {
+  const name = options.webSearch === true ? CLOUD_SHORTCUT_NAME_WEB : CLOUD_SHORTCUT_NAME;
+  const existing = await installCount(name);
+  if (existing > 1) throw new AppleLLMError(duplicateMessage(existing, name), "cloud");
+  if (existing === 1 && options.force !== true) {
+    onProgress?.({ status: `"${name}" is already installed` });
+    return;
+  }
+  const dir = await mkdtemp(path.join(os.tmpdir(), "apple-llm-shortcut-"));
+  try {
+    const jsonPath = path.join(dir, "definition.json");
+    const unsignedPath = path.join(dir, "unsigned.shortcut");
+    const signedPath = path.join(dir, `${name}.shortcut`);
+    await writeFile(jsonPath, JSON.stringify(shortcutDefinition(options.webSearch)), "utf8");
+    await execFileAsync2("plutil", ["-convert", "binary1", "-o", unsignedPath, jsonPath]);
+    onProgress?.({ status: "signing the shortcut locally" });
+    await execFileAsync2("shortcuts", ["sign", "-m", "anyone", "-i", unsignedPath, "-o", signedPath]);
+    onProgress?.({ status: `installing "${name}" (Shortcuts imports asynchronously)` });
+    await execFileAsync2("open", [signedPath]);
+    const deadline = Date.now() + IMPORT_TIMEOUT_MS;
+    for (; ; ) {
+      if (await installCount(name) >= 1) break;
+      if (Date.now() > deadline) {
+        throw new SetupRequiredError(
+          `Shortcuts did not import "${name}" within ${IMPORT_TIMEOUT_MS / 1e3}s.
+If a confirmation panel is open in the Shortcuts app, accept it and run setup again.`,
+          "setup-cloud",
+          "cloud"
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, IMPORT_POLL_MS));
+    }
+    onProgress?.({ status: `"${name}" installed` });
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+async function probeCloud() {
+  if (process.platform !== "darwin") {
+    return { available: false, installed: false, reason: `unsupportedPlatform: this machine reports "${process.platform}"` };
+  }
+  if (!isAppleSiliconMac()) {
+    return { available: false, installed: false, reason: "deviceNotEligible: Apple Intelligence needs Apple Silicon" };
+  }
+  try {
+    await execFileAsync2("shortcuts", ["list"], { timeout: 2e4 });
+  } catch {
+    return { available: false, installed: false, reason: "this system does not provide /usr/bin/shortcuts" };
+  }
+  const count = await installCount();
+  if (count === 0) {
+    return { available: false, installed: false, reason: cloudSetupHint() };
+  }
+  if (count > 1) {
+    return { available: false, installed: true, reason: duplicateMessage(count, CLOUD_SHORTCUT_NAME) };
+  }
+  return { available: true, installed: true, contextSize: CLOUD_CONTEXT_TOKENS };
+}
+var CloudClient = class {
+  ready = false;
+  /** Last known quota, set by `probe()` so a call can fail fast. */
+  quota;
+  /** What the framework says the server model can do, when it could be read. */
+  model;
+  /**
+   * Tell the client what the framework reported about the quota.
+   *
+   * Worth doing because a `shortcuts run` against an exhausted quota costs a
+   * full round trip to find out; this turns that into an immediate typed error.
+   */
+  setQuota(quota) {
+    this.quota = quota;
+    this.model = quota;
+  }
+  /** Whether the server model is known to read images. False when it could not be read (macOS 26). */
+  get supportsImages() {
+    return this.model?.capabilities?.vision === true;
+  }
+  assertQuota() {
+    if (this.quota?.status !== "limitReached") return;
+    throw new QuotaError(
+      "Apple Private Cloud Compute quota is exhausted (reported by the framework before the call was made).\nFall back to the on-device tier, or try again later.",
+      "cloud",
+      this.quota.resetDate === void 0 ? void 0 : new Date(this.quota.resetDate)
+    );
+  }
+  get label() {
+    return "apple private cloud compute";
+  }
+  get contextSize() {
+    return this.model?.contextSize ?? CLOUD_CONTEXT_TOKENS;
+  }
+  async ensureReady(onProgress) {
+    if (this.ready) return;
+    const probe2 = await probeCloud();
+    if (!probe2.available) {
+      if (probe2.installed !== true) {
+        throw new SetupRequiredError(probe2.reason ?? cloudSetupHint(), "setup-cloud", "cloud");
+      }
+      throw new AppleLLMError(probe2.reason ?? "the cloud tier is unavailable", "cloud");
+    }
+    this.ready = true;
+    onProgress?.({ status: `apple private cloud compute ready (${CLOUD_CONTEXT_TOKENS} token context)` });
+  }
+  async text(request) {
+    await this.ensureReady();
+    this.assertQuota();
+    const name = request.webSearch === true ? CLOUD_SHORTCUT_NAME_WEB : CLOUD_SHORTCUT_NAME;
+    if (request.webSearch === true && await installCount(name) !== 1) {
+      throw new SetupRequiredError(
+        `webSearch needs the "${name}" shortcut.
+Run:  apple-llm setup-cloud --web-search`,
+        "setup-cloud --web-search",
+        "cloud"
+      );
+    }
+    const images = await imageInputs(request.images);
+    let prompt = request.system ? `${request.system}
+
+${request.prompt}` : request.prompt;
+    const labels = images.map((image, i) => image.label === void 0 ? void 0 : `${i + 1}: ${image.label}`);
+    if (labels.some((label) => label !== void 0)) {
+      prompt = `${prompt}
+
+Attached images, in order \u2014 ${labels.map((l, i) => l ?? `${i + 1}`).join(", ")}.`;
+    }
+    const dir = await mkdtemp(path.join(os.tmpdir(), "apple-llm-cloud-"));
+    try {
+      const inPath = path.join(dir, "prompt.txt");
+      const outPath = path.join(dir, "reply.txt");
+      await writeFile(inPath, prompt, "utf8");
+      const inputs = [inPath, ...images.map((image) => image.path)].flatMap((p) => ["-i", p]);
+      try {
+        await execFileAsync2("shortcuts", ["run", name, ...inputs, "-o", outPath], {
+          timeout: CALL_TIMEOUT_MS,
+          killSignal: "SIGKILL",
+          signal: request.signal
+        });
+      } catch (error) {
+        if (request.signal?.aborted === true) {
+          throw new AbortError("The request was aborted.", "cloud", { cause: request.signal.reason });
+        }
+        throw describeRunFailure(error, name);
+      }
+      let reply;
+      try {
+        reply = await readFile(outPath, "utf8");
+      } catch {
+        throw new AppleLLMError("Apple cloud generation produced no output.", "cloud");
+      }
+      if (reply.trim() === "") {
+        throw new AppleLLMError("Apple cloud generation returned an empty reply.", "cloud");
+      }
+      return reply;
+    } finally {
+      await rm(dir, { recursive: true, force: true });
+    }
+  }
+  /**
+   * There is no constrained decoding on this tier, so the schema is spelled out
+   * in the prompt and the reply is mined for JSON. The shape is a request here,
+   * not a guarantee — unlike on device.
+   */
+  async json(request) {
+    const instruction = `Reply with a single JSON value matching this JSON Schema. Output only the JSON, with no commentary and no code fence.
+
+${JSON.stringify(request.schema, null, 2)}`;
+    const system = request.system ? `${request.system}
+
+${instruction}` : instruction;
+    return parseLlmJson(await this.text({ ...request, system }));
+  }
+  // eslint-disable-next-line class-methods-use-this
+  close() {
+  }
+};
+async function imageInputs(images) {
+  const out = [];
+  for (const image of images ?? []) {
+    const entry = typeof image === "string" ? { path: image } : image;
+    const absolute = path.resolve(entry.path);
+    try {
+      await stat(absolute);
+    } catch {
+      throw new AppleLLMError(`Image not found: ${entry.path}`, "cloud");
+    }
+    out.push({ path: absolute, ...entry.label === void 0 ? {} : { label: entry.label } });
+  }
+  return out;
+}
+function describeRunFailure(error, name = CLOUD_SHORTCUT_NAME) {
+  const err = error;
+  if (err.killed === true) {
+    return new TimeoutError(
+      `Apple cloud generation got no response within ${CALL_TIMEOUT_MS / 1e3}s. Open "${name}" in the Shortcuts app and check that Request is bound to the Shortcut Input variable \u2014 an unbound Request makes the action wait for a human.`,
+      "cloud"
+    );
+  }
+  const stderr = err.stderr?.trim() ?? "";
+  if (/maximum allowed length/i.test(stderr)) {
+    return new ContextLengthError(
+      `The prompt exceeded the cloud model's ~${CLOUD_CONTEXT_TOKENS}-token context window.`,
+      "cloud"
+    );
+  }
+  if (/QuotaLimitReached|quota/i.test(stderr)) {
+    const match = /(\d{4}-\d{2}-\d{2}[T ][\d:]+)/.exec(stderr);
+    const resetDate = match ? new Date(match[1].replace(" ", "T")) : void 0;
+    return new QuotaError(
+      `Apple Private Cloud Compute quota reached.${resetDate ? ` Resets ${resetDate.toISOString()}.` : ""}
+Fall back to the on-device tier, or try again later.`,
+      "cloud",
+      resetDate !== void 0 && !Number.isNaN(resetDate.getTime()) ? resetDate : void 0
+    );
+  }
+  if (/Couldn.t find shortcut/i.test(stderr)) {
+    return new SetupRequiredError(
+      `Shortcuts could not find "${name}".
+${cloudSetupHint()}`,
+      "setup-cloud",
+      "cloud"
+    );
+  }
+  return new AppleLLMError(
+    `Apple cloud generation failed: ${stderr !== "" ? stderr : err.message ?? String(error)}`,
+    "cloud"
+  );
+}
+
+// src/device.ts
+import { execFile as execFile4 } from "child_process";
+import { randomUUID } from "crypto";
+import { promisify as promisify4 } from "util";
+
+// src/compile.ts
+import { execFile as execFile3 } from "child_process";
+import { chmod, mkdir, readFile as readFile2, rename, rm as rm2, stat as stat2 } from "fs/promises";
+import { createHash } from "crypto";
+import os2 from "os";
+import path2 from "path";
+import { fileURLToPath } from "url";
+import { promisify as promisify3 } from "util";
+var execFileAsync3 = promisify3(execFile3);
+function cacheDir() {
+  return path2.join(os2.homedir(), "Library", "Caches", "apple-llm", "bin");
+}
+function fingerprint(source, triple) {
+  return createHash("sha256").update(`${source}
+${triple}`, "utf8").digest("hex").slice(0, 12);
+}
+var cachedSource;
+async function helperSource() {
+  if (cachedSource !== void 0) return cachedSource;
+  const here = path2.dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    path2.join(here, "..", "swift", "helper.swift"),
+    path2.join(here, "swift", "helper.swift")
+  ];
+  for (const candidate of candidates) {
+    try {
+      cachedSource = await readFile2(candidate, "utf8");
+      return cachedSource;
+    } catch {
+    }
+  }
+  throw new Error(
+    `apple-llm could not find its embedded helper.swift (looked in ${candidates.join(", ")}).`
+  );
+}
+async function fileExists(p) {
+  try {
+    await stat2(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var inFlight;
+var cachedKey;
+async function ensureBinary(onProgress, options = {}) {
+  if (options.force === true) {
+    inFlight = void 0;
+    cachedKey = void 0;
+  } else if (inFlight !== void 0 && cachedKey !== void 0) {
+    const pending = inFlight;
+    try {
+      const source = await helperSource();
+      const triple = await hostTarget() ?? process.arch;
+      if (fingerprint(source, triple) === cachedKey) return pending;
+      inFlight = void 0;
+      cachedKey = void 0;
+    } catch {
+      return pending;
+    }
+  }
+  if (inFlight === void 0) {
+    try {
+      const source = await helperSource();
+      const triple = await hostTarget() ?? process.arch;
+      cachedKey = fingerprint(source, triple);
+    } catch {
+    }
+    inFlight = build(onProgress).catch((err) => {
+      inFlight = void 0;
+      cachedKey = void 0;
+      throw err;
+    });
+  }
+  return inFlight;
+}
+async function build(onProgress) {
+  const source = await helperSource();
+  const triple = await hostTarget() ?? process.arch;
+  const dir = cacheDir();
+  const target = path2.join(dir, `fm-helper-${fingerprint(source, triple)}`);
+  if (await fileExists(target)) return target;
+  const swiftc = await findSwiftc();
+  if (swiftc === null) {
+    throw new ModelUnavailableError(
+      "apple-llm needs a Swift compiler to build its on-device helper, but none was found.\nInstall the Xcode command line tools with `xcode-select --install`, then try again.",
+      "noSwiftCompiler",
+      "device"
+    );
+  }
+  onProgress?.({ status: "building the Apple on-device helper (one time, a few seconds)" });
+  await mkdir(dir, { recursive: true });
+  const unique = `${process.pid}.${Math.random().toString(36).slice(2)}`;
+  const sourcePath = `${target}.${unique}.swift`;
+  const staging = `${target}.${unique}.tmp`;
+  const { writeFile: writeFile3 } = await import("fs/promises");
+  await writeFile3(sourcePath, source, "utf8");
+  try {
+    const targetArgs = triple.includes("-apple-") ? ["-target", triple] : [];
+    await execFileAsync3(swiftc.command, [
+      ...swiftc.prefixArgs,
+      ...targetArgs,
+      "-parse-as-library",
+      "-O",
+      sourcePath,
+      "-o",
+      staging
+    ]);
+    await chmod(staging, 493);
+    await rename(staging, target);
+  } catch (err) {
+    await rm2(staging, { force: true });
+    if (await fileExists(target)) return target;
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ModelUnavailableError(
+      `Failed to build the Apple on-device helper with ${swiftc.command}.
+${reason.slice(0, 400)}
+This usually means the macOS SDK predates the Foundation Models framework (macOS 26+).`,
+      "unsupportedOSVersion",
+      "device"
+    );
+  } finally {
+    await rm2(sourcePath, { force: true });
+  }
+  onProgress?.({ status: "helper built" });
+  return target;
+}
+
+// src/messages.ts
+function splitMessages(messages) {
+  const systems = [];
+  const rest = [];
+  for (const message of messages) {
+    if (message.role === "system") systems.push(message.content);
+    else rest.push(message);
+  }
+  let lastUser = -1;
+  for (let i = rest.length - 1; i >= 0; i -= 1) {
+    if (rest[i].role === "user") {
+      lastUser = i;
+      break;
+    }
+  }
+  if (lastUser === -1) {
+    throw new AppleLLMError("A message list needs at least one user message.");
+  }
+  const tail = rest.slice(lastUser + 1);
+  const final = tail[tail.length - 1];
+  if (final !== void 0 && final.role !== "tool") {
+    throw new AppleLLMError(
+      "The last message must be from the user, or a tool result answering the assistant\u2019s tool call."
+    );
+  }
+  const callNames = /* @__PURE__ */ new Map();
+  for (const message of rest) {
+    if (message.role === "assistant") for (const call of message.toolCalls ?? []) callNames.set(call.id, call);
+  }
+  const history = [];
+  for (const message of rest.slice(0, lastUser)) {
+    const entry = toHistory(message, callNames);
+    if (entry !== void 0) history.push(entry);
+  }
+  const replay = [];
+  for (const message of tail) {
+    if (message.role !== "tool") continue;
+    const call = callNames.get(message.toolCallId);
+    replay.push({
+      name: message.name ?? call?.name ?? "",
+      arguments: call?.arguments ?? {},
+      output: message.content
+    });
+  }
+  const last = rest[lastUser];
+  return {
+    system: systems.length > 0 ? systems.join("\n\n") : void 0,
+    history,
+    prompt: last.content,
+    images: last.images ?? [],
+    replay
+  };
+}
+function toHistory(message, calls) {
+  switch (message.role) {
+    case "user": {
+      const images = message.images?.length ?? 0;
+      const note = images === 0 ? "" : ` [${images === 1 ? "an image was" : `${images} images were`} attached here]`;
+      return { role: "user", content: `${message.content}${note}` };
+    }
+    case "assistant":
+      return {
+        role: "assistant",
+        content: message.content ?? "",
+        ...message.toolCalls !== void 0 && message.toolCalls.length > 0 ? { toolCalls: message.toolCalls } : {}
+      };
+    case "tool":
+      return {
+        role: "tool",
+        toolCallId: message.toolCallId,
+        name: message.name ?? calls.get(message.toolCallId)?.name ?? "tool",
+        content: message.content
+      };
+    default:
+      return void 0;
+  }
+}
+function renderHistory(history) {
+  return history.map((entry) => {
+    if (entry.role === "user") return `User: ${entry.content}`;
+    if (entry.role === "tool") return `Tool ${entry.name} returned: ${entry.content}`;
+    const calls = (entry.toolCalls ?? []).map((c) => `[called ${c.name}(${JSON.stringify(c.arguments)})]`);
+    return `Assistant: ${[entry.content, ...calls].filter((s) => s !== "").join(" ")}`;
+  }).join("\n");
+}
+function canonicalJson(value) {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
+  if (value !== null && typeof value === "object") {
+    const keys = Object.keys(value).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value) ?? "null";
+}
+var ReplayBook = class {
+  unused;
+  constructor(results) {
+    this.unused = [...results];
+  }
+  take(name, args) {
+    const key = canonicalJson(args);
+    let index = this.unused.findIndex((r) => r.name === name && canonicalJson(r.arguments) === key);
+    if (index < 0) index = this.unused.findIndex((r) => r.name === name);
+    if (index < 0) return void 0;
+    const [hit] = this.unused.splice(index, 1);
+    return hit.output;
+  }
+};
+
+// src/protocol.ts
+import { spawn } from "child_process";
+var defaultSpawner = (binary, args) => spawn(binary, args, { stdio: ["pipe", "pipe", "pipe"] });
+function abortErrorFrom(signal) {
+  const reason = signal.reason;
+  if (reason instanceof AppleLLMError) return reason;
+  if (reason instanceof Error && reason.name === "TimeoutError") {
+    return new TimeoutError(`Apple generation timed out: ${reason.message}`, "device", { cause: reason });
+  }
+  return new AbortError("The request was aborted.", void 0, { cause: reason });
+}
+var HelperServer = class {
+  constructor(binary, options = {}) {
+    this.binary = binary;
+    this.timeoutMs = options.timeoutMs ?? 12e4;
+    this.spawner = options.spawner ?? defaultSpawner;
+  }
+  binary;
+  child;
+  buffer = "";
+  queue = [];
+  /** Serialises callers so one request's reply cannot be handed to another. */
+  chain = Promise.resolve();
+  inFlight = 0;
+  /** The helper's recent stderr, quoted when it dies. Always drained: an unread pipe blocks the writer. */
+  stderrTail = "";
+  timeoutMs;
+  spawner;
+  start() {
+    if (this.child !== void 0 && this.child.exitCode === null && !this.child.killed) {
+      return this.child;
+    }
+    const child = this.spawner(this.binary, ["--serve"]);
+    this.child = child;
+    this.buffer = "";
+    this.stderrTail = "";
+    child.stdout?.on("data", (chunk) => {
+      this.buffer += chunk.toString();
+      for (; ; ) {
+        const newline = this.buffer.indexOf("\n");
+        if (newline === -1) break;
+        const line = this.buffer.slice(0, newline).trim();
+        this.buffer = this.buffer.slice(newline + 1);
+        if (line !== "") this.dispatch(line);
+      }
+    });
+    child.stderr?.on("data", (chunk) => {
+      this.stderrTail = (this.stderrTail + chunk.toString()).slice(-2e3);
+    });
+    const fail = (err) => {
+      if (this.child === child) this.child = void 0;
+      const pending = this.queue;
+      this.queue = [];
+      for (const p of pending) {
+        clearTimeout(p.timer);
+        p.finish(void 0, err);
+      }
+    };
+    child.on("error", (err) => fail(err instanceof Error ? err : new Error(String(err))));
+    child.on("close", (code) => {
+      const tail = this.stderrTail.trim();
+      fail(new AppleLLMError(`Apple helper exited with code ${code}${tail ? `: ${tail.slice(-400)}` : ""}`, "device"));
+    });
+    child.stdin?.on("error", () => {
+    });
+    const killer = () => {
+      if (child.exitCode === null) child.kill();
+    };
+    process.once("exit", killer);
+    child.once("close", () => process.removeListener("exit", killer));
+    this.setRef(this.inFlight > 0);
+    return child;
+  }
+  /** Keep the event loop alive only while a request is in flight. */
+  setRef(on) {
+    const child = this.child;
+    if (child === void 0) return;
+    const handles = [child, child.stdin, child.stdout, child.stderr];
+    for (const handle of handles) {
+      if (on) handle?.ref?.();
+      else handle?.unref?.();
+    }
+  }
+  /** Route one line: an event to the head's hooks, anything else completes the head. */
+  dispatch(line) {
+    const head = this.queue[0];
+    if (head === void 0) return;
+    let parsed;
+    try {
+      const value = JSON.parse(line);
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        parsed = value;
+      }
+    } catch {
+    }
+    if (parsed?.done === false) {
+      this.arm(head);
+      if (head.abandoned) {
+        const call = parsed.toolCall;
+        if (typeof call?.id === "string") this.write({ op: "toolResult", callId: call.id, stop: true });
+        return;
+      }
+      try {
+        head.hooks.onEvent?.(parsed, (control) => this.write(control));
+      } catch {
+      }
+      return;
+    }
+    this.queue.shift();
+    clearTimeout(head.timer);
+    head.finish(line);
+  }
+  /**
+   * (Re)start the wedge timer. It measures silence, not total time: every
+   * event resets it, so a long stream is fine while a helper that stops
+   * talking is not.
+   */
+  arm(entry) {
+    clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => this.timeOut(entry), this.timeoutMs);
+  }
+  /**
+   * Pause the wedge timer while the client itself is busy — a function tool
+   * running in JS. The helper is legitimately silent then: it is waiting on us.
+   */
+  pause() {
+    const head = this.queue[0];
+    if (head !== void 0) clearTimeout(head.timer);
+  }
+  /** Resume the wedge timer paused by `pause()`. */
+  resume() {
+    const head = this.queue[0];
+    if (head !== void 0) this.arm(head);
+  }
+  timeOut(entry) {
+    const index = this.queue.indexOf(entry);
+    if (index < 0) return;
+    this.queue.splice(index, 1);
+    this.stop();
+    entry.finish(
+      void 0,
+      new TimeoutError(`Apple on-device generation timed out after ${this.timeoutMs / 1e3}s of silence.`, "device")
+    );
+  }
+  /** Write a control line (cancel, toolResult) for the request in flight. */
+  write(control) {
+    this.child?.stdin?.write(`${JSON.stringify(control)}
+`);
+  }
+  /**
+   * One request. Resolves with its final line; events go to `hooks.onEvent`.
+   * Serialised against every other request through one chain.
+   */
+  request(payload, hooks = {}) {
+    const { signal } = hooks;
+    if (signal?.aborted === true) return Promise.reject(abortErrorFrom(signal));
+    let entry;
+    let rejectCaller = () => void 0;
+    const caller = new Promise((resolve, reject) => {
+      rejectCaller = reject;
+      const run = () => {
+        if (signal?.aborted === true) {
+          reject(abortErrorFrom(signal));
+          return Promise.resolve();
+        }
+        const child = this.start();
+        this.inFlight += 1;
+        this.setRef(true);
+        return new Promise((settle) => {
+          const pending = {
+            hooks,
+            abandoned: false,
+            finish: (line, err) => {
+              this.inFlight -= 1;
+              if (this.inFlight === 0) this.setRef(false);
+              settle();
+              if (pending.abandoned) return;
+              if (err !== void 0) reject(err);
+              else resolve(line ?? "");
+            }
+          };
+          entry = pending;
+          this.arm(pending);
+          this.queue.push(pending);
+          child.stdin?.write(`${payload.replace(/\n/g, " ")}
+`);
+        });
+      };
+      const slot = this.chain.then(run, run);
+      this.chain = slot.catch(() => void 0);
+    });
+    if (signal !== void 0) {
+      const onAbort = () => {
+        if (entry !== void 0 && this.queue.includes(entry)) {
+          entry.abandoned = true;
+          if (hooks.id !== void 0) this.write({ op: "cancel", id: hooks.id });
+        }
+        rejectCaller(abortErrorFrom(signal));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+      const detach = () => signal.removeEventListener("abort", onAbort);
+      caller.then(detach, detach);
+    }
+    return caller;
+  }
+  /** Version-1 shape: one request, one line. */
+  send(payload, hooks = {}) {
+    return this.request(payload, hooks);
+  }
+  /**
+   * Streaming request, kept for callers of the version-1 API: deltas go to
+   * `onDelta` and the promise resolves with the final line.
+   */
+  stream(payload, onDelta, hooks = {}) {
+    return this.request(payload, {
+      ...hooks,
+      onEvent: (event, write) => {
+        if (typeof event.delta === "string") onDelta(event.delta);
+        hooks.onEvent?.(event, write);
+      }
+    });
+  }
+  stop() {
+    const child = this.child;
+    this.child = void 0;
+    if (child !== void 0 && child.exitCode === null) {
+      child.stdin?.end();
+      child.kill();
+    }
+  }
+};
+
+// src/schema.ts
+var SCHEMA_MAP_KEYS = ["properties", "$defs", "definitions"];
+var SCHEMA_LIST_KEYS = ["anyOf", "oneOf", "allOf"];
+var SCHEMA_KEYS = ["items", "not", "additionalItems"];
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function sanitize(name, counter) {
+  const cleaned = name.replace(/[^A-Za-z0-9_]/g, "");
+  if (cleaned.length === 0 || /^[0-9]/.test(cleaned)) {
+    counter.n += 1;
+    return `Schema${counter.n}`;
+  }
+  return cleaned;
+}
+function titleFrom(name, ctx) {
+  const base = sanitize(name, ctx.counter);
+  if (!ctx.used.has(base)) {
+    ctx.used.add(base);
+    return base;
+  }
+  for (let i = 2; ; i += 1) {
+    const candidate = `${base}${i}`;
+    if (!ctx.used.has(candidate)) {
+      ctx.used.add(candidate);
+      return candidate;
+    }
+  }
+}
+function memberType(value) {
+  if (typeof value === "number") return Number.isInteger(value) ? "integer" : "number";
+  if (typeof value === "boolean") return "boolean";
+  return "string";
+}
+function rewriteRef(ref, ctx) {
+  const slash = ref.lastIndexOf("/");
+  if (slash === -1) return ref;
+  const name = ref.slice(slash + 1);
+  const title = ctx.defTitles.get(name);
+  return title === void 0 || title === name ? ref : `${ref.slice(0, slash + 1)}${title}`;
+}
+function convertNode(node, name, ctx) {
+  const out = {};
+  let nullable = false;
+  const converted = /* @__PURE__ */ new Map();
+  const properties = node.properties;
+  if (isPlainObject(properties)) {
+    for (const [key, value] of Object.entries(properties)) {
+      converted.set(
+        key,
+        isPlainObject(value) ? convertNode(value, key, ctx) : { schema: value, nullable: false }
+      );
+    }
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if (key === "type" || key === "enum" || key === "required" || key === "properties") continue;
+    if (key === "$ref" && typeof value === "string") {
+      out.$ref = rewriteRef(value, ctx);
+    } else if (SCHEMA_MAP_KEYS.includes(key) && isPlainObject(value)) {
+      const isDefs = key === "$defs" || key === "definitions";
+      const mapped = {};
+      for (const [childName, childValue] of Object.entries(value)) {
+        if (!isPlainObject(childValue)) {
+          mapped[childName] = childValue;
+          continue;
+        }
+        const child = convertNode(childValue, childName, ctx).schema;
+        const reserved = isDefs ? ctx.defTitles.get(childName) : void 0;
+        if (reserved !== void 0) child.title = reserved;
+        mapped[childName] = child;
+      }
+      out[key] = mapped;
+    } else if (SCHEMA_LIST_KEYS.includes(key) && Array.isArray(value)) {
+      if (key === "allOf") {
+        const allOfConverted = value.map(
+          (entry) => isPlainObject(entry) ? convertNode(entry, name, ctx).schema : entry
+        );
+        if (allOfConverted.length === 1 && isPlainObject(allOfConverted[0])) {
+          for (const [k, v] of Object.entries(allOfConverted[0])) {
+            if (out[k] === void 0) out[k] = v;
+          }
+        } else {
+          out.allOf = allOfConverted;
+        }
+      } else {
+        const branches = value.filter((entry) => !(isPlainObject(entry) && entry.type === "null"));
+        if (branches.length !== value.length) nullable = true;
+        const convertedBranches = branches.map(
+          (entry) => isPlainObject(entry) ? convertNode(entry, name, ctx) : { schema: entry, nullable: false }
+        );
+        if (convertedBranches.some((b) => b.nullable)) nullable = true;
+        if (convertedBranches.length === 1 && isPlainObject(convertedBranches[0].schema)) {
+          for (const [k, v] of Object.entries(convertedBranches[0].schema)) {
+            if (out[k] === void 0) out[k] = v;
+          }
+        } else if (convertedBranches.length > 0) {
+          out.anyOf = convertedBranches.map((b) => b.schema);
+        }
+      }
+    } else if (SCHEMA_KEYS.includes(key) && isPlainObject(value)) {
+      out[key] = convertNode(value, name, ctx).schema;
+    } else {
+      out[key] = value;
+    }
+  }
+  const rawType = node.type;
+  if (Array.isArray(rawType)) {
+    const nonNull = rawType.filter((t) => t !== "null");
+    if (nonNull.length !== rawType.length) nullable = true;
+    if (nonNull.length > 1) {
+      out.anyOf = nonNull.map((t) => ({ type: t }));
+    } else {
+      out.type = nonNull[0] ?? "string";
+    }
+  } else if (rawType !== void 0) {
+    out.type = rawType;
+  }
+  const rawEnum = node.enum;
+  if (Array.isArray(rawEnum) && rawEnum.length > 0) {
+    const members = rawEnum.filter((v) => v !== null);
+    if (members.length !== rawEnum.length) nullable = true;
+    if (members.length > 0) {
+      delete out.type;
+      if (members.every((v) => typeof v === "string")) {
+        out.anyOf = members.map((value) => ({ type: "string", const: value }));
+      } else {
+        const types = [...new Set(members.map(memberType))];
+        if (types.length === 1) out.type = types[0];
+        else out.anyOf = types.map((t) => ({ type: t }));
+      }
+    }
+  }
+  const merged = converted.size === 0 && isPlainObject(out.properties);
+  const isObject2 = !merged && (out.type === "object" || converted.size > 0);
+  if (isObject2) {
+    const props = {};
+    for (const [key, child] of converted) props[key] = child.schema;
+    out.properties = props;
+    const originalRequired = Array.isArray(node.required) ? node.required : [];
+    out.required = originalRequired.filter((key) => !converted.get(key)?.nullable);
+    const keys = Object.keys(props);
+    const declaredOrder = Array.isArray(node["x-order"]) ? node["x-order"].filter((k) => typeof k === "string" && keys.includes(k)) : [];
+    out["x-order"] = [...declaredOrder, ...keys.filter((k) => !declaredOrder.includes(k))];
+    if (typeof out.title === "string") ctx.used.add(out.title);
+    else out.title = titleFrom(name, ctx);
+    if (out.additionalProperties === void 0) out.additionalProperties = false;
+  } else if (Array.isArray(node.required)) {
+    out.required = node.required;
+  }
+  if ((Array.isArray(out.anyOf) || Array.isArray(out.allOf)) && typeof out.title !== "string") {
+    out.title = titleFrom(name, ctx);
+  }
+  if (out.type === "string" && out.anyOf === void 0 && out.allOf === void 0)
+    delete out.title;
+  delete out.pattern;
+  return { schema: out, nullable };
+}
+function reserveDefTitles(schema, ctx) {
+  for (const key of ["$defs", "definitions"]) {
+    const defs = schema[key];
+    if (!isPlainObject(defs)) continue;
+    for (const [name, value] of Object.entries(defs)) {
+      const declared = isPlainObject(value) && typeof value.title === "string" ? value.title : null;
+      const title = declared ?? sanitize(name, ctx.counter);
+      ctx.defTitles.set(name, title);
+      ctx.used.add(title);
+    }
+  }
+}
+function toAppleSchema(schema, rootName = "Response") {
+  const ctx = { counter: { n: 0 }, defTitles: /* @__PURE__ */ new Map(), used: /* @__PURE__ */ new Set() };
+  reserveDefTitles(schema, ctx);
+  const { $schema: _draft, ...rest } = schema;
+  return convertNode(rest, rootName, ctx).schema;
+}
+
+// src/standard-schema.ts
+function isStandardSchema(value) {
+  if (value === null || typeof value !== "object" && typeof value !== "function") return false;
+  const props = value["~standard"];
+  return props !== null && typeof props === "object" && typeof props.validate === "function";
+}
+function resolveSchema(schema) {
+  if (!isStandardSchema(schema)) return { json: schema };
+  const props = schema["~standard"];
+  const describe = props.jsonSchema;
+  if (describe === void 0 || typeof describe.input !== "function") {
+    throw new UnsupportedError(
+      `This ${props.vendor} schema cannot describe itself as JSON Schema, which Apple's decoder needs.
+` + (props.vendor === "valibot" ? "Wrap it: `toStandardJsonSchema(schema)` from @valibot/to-json-schema." : "Use a version that implements Standard JSON Schema (zod >= 4.2, arktype >= 2.1), or pass a JSON Schema.")
+    );
+  }
+  let json;
+  try {
+    json = describe.input({ target: "draft-2020-12" });
+  } catch {
+    json = describe.input({ target: "draft-07" });
+  }
+  return { json, validate: async (value) => props.validate(value) };
+}
+function formatPath(path4) {
+  if (path4 === void 0 || path4.length === 0) return "";
+  return path4.map((segment) => typeof segment === "object" && segment !== null ? segment.key : segment).map((key) => String(key)).join(".");
+}
+function describeIssues(issues) {
+  return issues.slice(0, 8).map((issue) => {
+    const at = formatPath(issue.path);
+    return at === "" ? issue.message : `${at}: ${issue.message}`;
+  }).join("; ");
+}
+async function validateWith(resolved, value, text, tier) {
+  if (resolved.validate === void 0) {
+    const issues = checkPatterns(value, resolved.json);
+    if (issues.length === 0) return value;
+    throw new SchemaValidationError(
+      `The model's reply did not satisfy the schema: ${describeIssues(issues)}`,
+      issues.map((issue) => ({ message: issue.message, path: issue.path })),
+      text,
+      tier
+    );
+  }
+  const result = await resolved.validate(value);
+  if (result.issues !== void 0) {
+    throw new SchemaValidationError(
+      `The model's reply did not satisfy the schema: ${describeIssues(result.issues)}`,
+      result.issues.map((issue) => ({ message: issue.message, path: issue.path })),
+      text,
+      tier
+    );
+  }
+  return result.value;
+}
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function allowsNull(schema) {
+  if (!isObject(schema)) return false;
+  if (schema.type === "null" || schema.nullable === true) return true;
+  if (Array.isArray(schema.type) && schema.type.includes("null")) return true;
+  if (Array.isArray(schema.enum) && schema.enum.includes(null)) return true;
+  for (const key of ["anyOf", "oneOf"]) {
+    const branches = schema[key];
+    if (Array.isArray(branches) && branches.some(allowsNull)) return true;
+  }
+  return false;
+}
+function restoreNulls(value, schema, root = schema, depth = 0) {
+  if (depth > 32 || !isObject(schema)) return value;
+  const ref = schema.$ref;
+  if (typeof ref === "string") {
+    const target = resolveRef(ref, root);
+    return target === void 0 ? value : restoreNulls(value, target, root, depth + 1);
+  }
+  for (const key of ["anyOf", "oneOf"]) {
+    const branches = schema[key];
+    if (Array.isArray(branches)) {
+      const nonNull = branches.filter((b) => !(isObject(b) && b.type === "null"));
+      if (nonNull.length === 1 && isObject(nonNull[0])) {
+        return restoreNulls(value, nonNull[0], root, depth + 1);
+      }
+      return value;
+    }
+  }
+  if (Array.isArray(schema.allOf) && schema.allOf.length === 1 && isObject(schema.allOf[0])) {
+    return restoreNulls(value, schema.allOf[0], root, depth + 1);
+  }
+  if (Array.isArray(value)) {
+    return isObject(schema.items) ? value.map((item) => restoreNulls(item, schema.items, root, depth + 1)) : value;
+  }
+  if (!isObject(value) || !isObject(schema.properties)) return value;
+  const properties = schema.properties;
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const out = { ...value };
+  for (const [key, child] of Object.entries(properties)) {
+    if (out[key] === void 0) {
+      if (required.includes(key) && allowsNull(child)) out[key] = null;
+      continue;
+    }
+    if (isObject(child)) out[key] = restoreNulls(out[key], child, root, depth + 1);
+  }
+  return out;
+}
+function resolveRef(ref, root) {
+  const match = /^#\/(\$defs|definitions)\/(.+)$/.exec(ref);
+  if (match === null) return ref === "#" ? root : void 0;
+  const defs = root[match[1]];
+  const target = isObject(defs) ? defs[decodeURIComponent(match[2])] : void 0;
+  return isObject(target) ? target : void 0;
+}
+function checkPatterns(value, schema, root = schema, path4 = [], depth = 0) {
+  if (depth > 32 || !isObject(schema)) return [];
+  if (typeof schema.$ref === "string") {
+    const target = resolveRef(schema.$ref, root);
+    return target === void 0 ? [] : checkPatterns(value, target, root, path4, depth + 1);
+  }
+  if (Array.isArray(schema.allOf) && schema.allOf.length === 1 && isObject(schema.allOf[0])) {
+    return checkPatterns(value, schema.allOf[0], root, path4, depth + 1);
+  }
+  for (const key of ["anyOf", "oneOf"]) {
+    const branches = schema[key];
+    if (!Array.isArray(branches)) continue;
+    const nonNull = branches.filter((b) => !(isObject(b) && b.type === "null"));
+    return nonNull.length === 1 && isObject(nonNull[0]) && value !== null ? checkPatterns(value, nonNull[0], root, path4, depth + 1) : [];
+  }
+  if (typeof value === "string" && typeof schema.pattern === "string") {
+    let regex;
+    try {
+      regex = new RegExp(schema.pattern, "u");
+    } catch {
+      regex = void 0;
+    }
+    return regex === void 0 || regex.test(value) ? [] : [{ message: `must match the pattern ${schema.pattern}`, path: path4 }];
+  }
+  if (Array.isArray(value) && isObject(schema.items)) {
+    return value.flatMap((item, i) => checkPatterns(item, schema.items, root, [...path4, i], depth + 1));
+  }
+  if (isObject(value) && isObject(schema.properties)) {
+    return Object.entries(schema.properties).flatMap(
+      ([key, child]) => value[key] === void 0 || !isObject(child) ? [] : checkPatterns(value[key], child, root, [...path4, key], depth + 1)
+    );
+  }
+  return [];
+}
+
+// src/tools.ts
+var BUILT_IN_TOOLS = /* @__PURE__ */ new Set(["ocr", "barcode", "spotlight"]);
+function tool(definition) {
+  return definition;
+}
+var TOOL_NAME = /^[A-Za-z_][A-Za-z0-9_-]{0,63}$/;
+var EMPTY_PARAMETERS = { type: "object", properties: {}, required: [] };
+function normalizeTools(tools) {
+  const out = { builtIn: [], functions: [] };
+  if (tools === void 0) return out;
+  const entries = Array.isArray(tools) ? [...tools] : Object.entries(tools).map(([name, def]) => ({ ...def, name: def.name ?? name }));
+  const seen = /* @__PURE__ */ new Set();
+  for (const entry of entries) {
+    if (typeof entry === "string") {
+      if (!BUILT_IN_TOOLS.has(entry)) {
+        throw new AppleLLMError(`Unknown tool "${entry}" (want ${[...BUILT_IN_TOOLS].join(", ")}).`, "device");
+      }
+      if (!out.builtIn.includes(entry)) out.builtIn.push(entry);
+      continue;
+    }
+    if (entry === null || typeof entry !== "object" || typeof entry.name !== "string") {
+      throw new AppleLLMError("A function tool needs a name.", "device");
+    }
+    if (!TOOL_NAME.test(entry.name)) {
+      throw new AppleLLMError(
+        `Tool name "${entry.name}" is invalid: use letters, digits, "_" or "-", starting with a letter or "_".`,
+        "device"
+      );
+    }
+    if (seen.has(entry.name) || BUILT_IN_TOOLS.has(entry.name)) {
+      throw new AppleLLMError(`Tool name "${entry.name}" is used twice.`, "device");
+    }
+    seen.add(entry.name);
+    const resolved = entry.parameters === void 0 ? void 0 : resolveSchema(entry.parameters);
+    out.functions.push({ ...entry, resolved, json: resolved?.json ?? EMPTY_PARAMETERS });
+  }
+  return out;
+}
+function toolOutputText(value) {
+  if (typeof value === "string") return value;
+  if (value === void 0) return "";
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+
+// src/device.ts
+var execFileAsync4 = promisify4(execFile4);
+var DEFAULT_TEMPERATURE = 0.4;
+var DEFAULT_MAX_TOKENS = 2048;
+var DEFAULT_MAX_TOOL_CALLS = 8;
+var CALL_TIMEOUT_MS2 = 12e4;
+var BUSY_RETRY_DELAYS_MS = [250, 1e3, 2500];
+function assertTools(tools) {
+  if (tools === void 0) return;
+  for (const tool2 of tools) {
+    if (!BUILT_IN_TOOLS.has(tool2)) {
+      throw new AppleLLMError(
+        `Unknown tool "${tool2}" (want ${[...BUILT_IN_TOOLS].join(", ")}).`,
+        "device"
+      );
+    }
+  }
+}
+async function probeDevice(onProgress) {
+  if (process.platform !== "darwin") {
+    return { available: false, reason: `unsupportedPlatform: this machine reports "${process.platform}"` };
+  }
+  if (!isAppleSiliconMac()) {
+    return { available: false, reason: "deviceNotEligible: Apple Intelligence needs Apple Silicon" };
+  }
+  const major = await macosMajor();
+  if (major !== null && major < 26) {
+    return { available: false, reason: `unsupportedOSVersion: needs macOS 26 or later, this is ${major}` };
+  }
+  let binary;
+  try {
+    binary = await ensureBinary(onProgress);
+  } catch (err) {
+    return { available: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+  try {
+    const { stdout } = await execFileAsync4(binary, ["--probe"], { timeout: 2e4 });
+    return JSON.parse(stdout.trim());
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err);
+    return { available: false, reason: `the helper could not be run: ${reason.slice(0, 300)}` };
+  }
+}
+function raiseFor(response, raw, toolFailure) {
+  const detail = response.error ?? raw.slice(0, 200);
+  switch (response.kind) {
+    case "availability":
+      throw new ModelUnavailableError(
+        unavailableMessage(detail),
+        toUnavailableReason(detail),
+        "device"
+      );
+    case "schema":
+      throw new SchemaRejectedError(
+        `Apple rejected the response schema: ${detail}
+Every object needs a title, an x-order and additionalProperties; enums must be anyOf/const; unions cannot include null.`,
+        "device"
+      );
+    case "context":
+      throw new ContextLengthError(
+        `The prompt exceeded the on-device context window: ${detail}`,
+        "device",
+        response.contextSize,
+        response.tokenCount
+      );
+    case "quota": {
+      const parsed = response.resetDate === void 0 ? void 0 : new Date(response.resetDate);
+      const resetDate = parsed !== void 0 && !Number.isNaN(parsed.getTime()) ? parsed : void 0;
+      throw new QuotaError(
+        `Apple rate limited the on-device model: ${detail}`,
+        "device",
+        resetDate
+      );
+    }
+    case "guardrail":
+      throw new RefusalError(`The on-device model declined to answer: ${detail}`, "device");
+    case "timeout":
+      throw new TimeoutError(`Apple on-device generation timed out: ${detail}`, "device");
+    case "cancelled":
+      throw new AbortError("The request was cancelled.", "device");
+    case "tool": {
+      const name = toolFailure?.name ?? response.tool ?? "unknown";
+      const cause = toolFailure?.error;
+      const why = cause instanceof Error ? cause.message : cause === void 0 ? detail : String(cause);
+      throw new ToolExecutionError(`Tool "${name}" failed: ${why}`, name, { cause });
+    }
+    case "unsupported":
+      throw new UnsupportedError(`Apple on-device generation failed: ${detail}`, "device");
+    case "busy":
+      throw new ModelBusyError(
+        "Apple\u2019s on-device model is busy serving other processes and turned the request away (ModelManagerError 1042), even after retrying. Try again shortly.",
+        "device"
+      );
+    default:
+      throw new AppleLLMError(`Apple on-device generation failed: ${detail}`, "device");
+  }
+}
+function usageFrom(raw) {
+  if (raw === void 0 || typeof raw.inputTokens !== "number" || typeof raw.outputTokens !== "number") {
+    return void 0;
+  }
+  return {
+    inputTokens: raw.inputTokens,
+    outputTokens: raw.outputTokens,
+    totalTokens: raw.inputTokens + raw.outputTokens,
+    ...typeof raw.cachedInputTokens === "number" ? { cachedInputTokens: raw.cachedInputTokens } : {}
+  };
+}
+function finishFrom(raw) {
+  if (raw === "length") return "length";
+  if (raw === "toolCalls") return "tool-calls";
+  return "stop";
+}
+var DeviceClient = class {
+  constructor(options = {}) {
+    this.options = options;
+    this.server = options.server;
+  }
+  options;
+  binary;
+  probeResult;
+  server;
+  readying;
+  get label() {
+    const variant = this.probeResult?.variant;
+    return variant ? `apple on-device (${variant})` : "apple on-device";
+  }
+  get contextSize() {
+    return this.probeResult?.contextSize;
+  }
+  /** Probe and build once; concurrent first calls share the one attempt. */
+  async ensureReady(onProgress) {
+    if (this.probeResult?.available === true && this.binary !== void 0) return;
+    this.readying ??= (async () => {
+      const probe2 = await probeDevice(onProgress);
+      this.probeResult = probe2;
+      if (!probe2.available) {
+        throw new ModelUnavailableError(
+          unavailableMessage(probe2.reason),
+          toUnavailableReason(probe2.reason),
+          "device"
+        );
+      }
+      this.binary = await ensureBinary(onProgress);
+      onProgress?.({
+        status: `apple on-device model ready${probe2.variant ? ` (${probe2.variant}, ${probe2.contextSize} token context)` : ""}`
+      });
+    })().finally(() => {
+      this.readying = void 0;
+    });
+    return this.readying;
+  }
+  getProbe() {
+    return this.probeResult;
+  }
+  async helper() {
+    if (this.options.server !== void 0) return this.options.server;
+    await this.ensureReady();
+    const binary = this.binary ?? await ensureBinary();
+    this.server ??= new HelperServer(binary, { timeoutMs: CALL_TIMEOUT_MS2 });
+    return this.server;
+  }
+  /** Send one single-line envelope and return the parsed reply, raising a typed error on failure. */
+  async exchange(envelope, signal) {
+    const server = await this.helper();
+    const id = randomUUID();
+    const raw = await server.request(JSON.stringify({ ...envelope, id }), { signal, id });
+    const response = parse(raw);
+    if (response.ok !== true) raiseFor(response, raw);
+    return response;
+  }
+  /** The request envelope, shared by every generation path. */
+  async envelopeFor(request, op) {
+    assertTools(request.tools);
+    return {
+      op,
+      instructions: request.system ?? "",
+      prompt: await withDocuments(request.prompt, request.documents),
+      schema: request.schema ?? null,
+      temperature: request.temperature ?? DEFAULT_TEMPERATURE,
+      maxTokens: request.maxTokens ?? DEFAULT_MAX_TOKENS,
+      includeSchemaInPrompt: request.includeSchemaInPrompt,
+      reuseSession: request.reuseSession ?? false,
+      sessionId: request.sessionId,
+      history: request.history !== void 0 && request.history.length > 0 ? request.history : void 0,
+      trimHistory: request.trimHistory,
+      tools: request.tools !== void 0 && request.tools.length > 0 ? request.tools : void 0,
+      functions: request.functions !== void 0 && request.functions.length > 0 ? request.functions.map((fn) => ({
+        name: fn.name,
+        description: fn.description ?? "",
+        parameters: toAppleSchema(fn.json, `${fn.name}Arguments`)
+      })) : void 0,
+      images: request.images,
+      useCase: request.useCase ?? this.options.useCase,
+      guardrails: request.guardrails ?? this.options.guardrails,
+      sampling: request.sampling
+    };
+  }
+  /**
+   * One generation, with every event handled: text deltas, partial objects,
+   * and function tool calls, which run here and answer the helper.
+   */
+  async run(request, op = "generate", hooks = {}) {
+    const envelope = await this.envelopeFor(request, op);
+    const server = await this.helper();
+    const functions = new Map((request.functions ?? []).map((fn) => [fn.name, fn]));
+    const maxToolCalls = hooks.maxToolCalls ?? DEFAULT_MAX_TOOL_CALLS;
+    const calls = [];
+    let toolFailure;
+    const answerToolCall = async (call, write) => {
+      const reply = (fields) => write({ op: "toolResult", callId: call.id, ...fields });
+      const fn = functions.get(call.name);
+      if (fn === void 0) {
+        reply({ output: `There is no tool named "${call.name}".`, isError: true });
+        return;
+      }
+      if (calls.length > maxToolCalls) {
+        call.output = "Tool call limit reached. Answer with the information you already have.";
+        reply({ output: call.output });
+        return;
+      }
+      const replayed = hooks.replay?.take(call.name, call.arguments);
+      if (replayed !== void 0) {
+        call.output = replayed;
+        reply({ output: replayed });
+        return;
+      }
+      if (fn.execute === void 0) {
+        reply({ stop: true });
+        return;
+      }
+      let args = restoreNulls(call.arguments, fn.json);
+      if (fn.resolved?.validate !== void 0) {
+        const checked2 = await fn.resolved.validate(args);
+        if (checked2.issues !== void 0) {
+          call.output = `Invalid arguments: ${describeIssues(checked2.issues)}`;
+          reply({ output: call.output });
+          return;
+        }
+        args = checked2.value;
+      }
+      server.pause();
+      try {
+        const result = await fn.execute(args, { toolCallId: call.id, signal: hooks.signal });
+        call.output = toolOutputText(result);
+        reply({ output: call.output });
+      } catch (error) {
+        toolFailure = { name: call.name, error };
+        reply({ output: error instanceof Error ? error.message : String(error), isError: true });
+      } finally {
+        server.resume();
+      }
+    };
+    let delivered = false;
+    const attempt = (id = randomUUID()) => server.request(JSON.stringify({ ...envelope, id }), {
+      id,
+      signal: hooks.signal,
+      onEvent: (event, write) => {
+        delivered = true;
+        if (typeof event.delta === "string") {
+          if (event.delta !== "") hooks.onDelta?.(event.delta);
+        } else if (typeof event.partial === "string") {
+          hooks.onPartial?.(event.partial);
+        } else if (event.toolCall !== null && typeof event.toolCall === "object") {
+          const toolCall = event.toolCall;
+          const call = {
+            id: String(toolCall.id ?? randomUUID()),
+            name: String(toolCall.name ?? ""),
+            arguments: toolCall.arguments ?? {}
+          };
+          calls.push(call);
+          try {
+            hooks.onToolCall?.(call);
+          } catch {
+          }
+          void answerToolCall(call, write).catch((error) => {
+            toolFailure ??= { name: call.name, error };
+            write({ op: "toolResult", callId: call.id, output: String(error), isError: true });
+          });
+        }
+      }
+    });
+    let raw = await attempt();
+    let response = parse(raw);
+    for (const delay of BUSY_RETRY_DELAYS_MS) {
+      if (response.ok === true || response.kind !== "busy" || delivered) break;
+      await sleep(delay, hooks.signal);
+      raw = await attempt();
+      response = parse(raw);
+    }
+    if (response.ok !== true) raiseFor(response, raw, toolFailure);
+    if (typeof response.content !== "string") {
+      throw new AppleLLMError("Apple helper returned no content.", "device");
+    }
+    const builtIn = (response.toolCalls ?? []).filter((c) => typeof c.name === "string" && !functions.has(c.name)).map((c) => ({
+      id: String(c.id ?? ""),
+      name: String(c.name),
+      arguments: c.arguments ?? {},
+      ...typeof c.output === "string" ? { output: c.output } : {}
+    }));
+    return {
+      content: response.content,
+      finishReason: finishFrom(response.finishReason),
+      usage: usageFrom(response.usage),
+      toolCalls: [...calls, ...builtIn],
+      trimmedTurns: typeof response.trimmedTurns === "number" ? response.trimmedTurns : 0
+    };
+  }
+  /** One request. Returns the helper's `content` string, unparsed. */
+  async complete(request, hooks = {}) {
+    return (await this.run(request, "generate", hooks)).content;
+  }
+  /**
+   * Streaming text. Deltas arrive via onDelta as the model generates; the
+   * promise resolves with the full text.
+   */
+  async stream(prompt, options = {}) {
+    const { onDelta, signal, ...rest } = options;
+    return (await this.run({ ...rest, prompt, schema: null }, "stream", { onDelta, signal })).content;
+  }
+  /**
+   * Conversation history for a named session: the mirrored turns the helper
+   * persisted, oldest first. Survives helper restarts, and the next call
+   * rebuilds the native transcript from it.
+   */
+  async history(sessionId) {
+    const response = await this.exchange({ op: "history", sessionId, instructions: "" });
+    return {
+      instructions: typeof response.instructions === "string" ? response.instructions : "",
+      history: Array.isArray(response.history) ? response.history : []
+    };
+  }
+  /** Drop a named session (and its persisted history), or all of them. */
+  async resetSession(sessionId) {
+    await this.exchange({ op: "reset", sessionId: sessionId ?? "", instructions: "" });
+  }
+  /**
+   * How many tokens a request costs, before sending it.
+   *
+   * The point is to turn a ContextLengthError into an arithmetic check: compare
+   * against `contextSize` and trim, rather than discovering the ceiling by
+   * hitting it. Counts everything that shares the window: instructions,
+   * history, tools, schema, images and inlined documents.
+   */
+  async countTokens(prompt, options = {}) {
+    const envelope = await this.envelopeFor(
+      {
+        prompt,
+        system: options.system,
+        images: options.images,
+        tools: options.tools,
+        documents: options.documents,
+        history: options.history,
+        schema: options.schema === void 0 ? null : toAppleSchema(options.schema),
+        functions: options.functions
+      },
+      "generate"
+    );
+    const response = await this.exchange({ ...envelope, op: "countTokens" }, options.signal);
+    if (typeof response.tokens !== "number" || typeof response.contextSize !== "number") {
+      throw new AppleLLMError("Apple helper returned an unreadable token count.", "device");
+    }
+    return { tokens: response.tokens, contextSize: response.contextSize };
+  }
+  /**
+   * Load the model assets now so the first real call does not pay for it.
+   *
+   * Cheap and idempotent, but do not expect much on a warm machine: with the
+   * assets already resident this measured 0.31s against 0.36s for an
+   * unprewarmed first call — inside the noise. The win is on a genuinely cold
+   * system, where the very first call to the framework here took 7.8s. Worth
+   * calling at startup when you know a request is coming; not worth building
+   * around.
+   */
+  async prewarm(system) {
+    await this.exchange({ op: "prewarm", instructions: system ?? "" });
+  }
+  async text(prompt, options = {}) {
+    return this.complete({ ...options, prompt, schema: null });
+  }
+  async json(prompt, options) {
+    const content = await this.complete({ ...options, prompt, schema: toAppleSchema(options.schema) });
+    try {
+      return restoreNulls(JSON.parse(content), options.schema);
+    } catch {
+      throw new AppleLLMError(
+        `Apple on-device model returned invalid JSON: ${content.slice(0, 200)}`,
+        "device"
+      );
+    }
+  }
+  /** Shut the helper process down. Safe to call more than once. */
+  close() {
+    this.server?.stop();
+    this.server = void 0;
+  }
+};
+function sleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted === true) {
+      reject(abortErrorFrom(signal));
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortErrorFrom(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function parse(raw) {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new AppleLLMError(`Apple helper returned an unreadable envelope: ${raw.slice(0, 200)}`, "device");
+  }
+}
+async function withDocuments(prompt, documents) {
+  if (documents === void 0 || documents.length === 0) return prompt;
+  const { readFile: readFile4, stat: stat3 } = await import("fs/promises");
+  const parts = [prompt];
+  for (const doc of documents) {
+    let size = 0;
+    try {
+      size = (await stat3(doc)).size;
+    } catch {
+      throw new AppleLLMError(`Document not found: ${doc}`);
+    }
+    if (size > 512e3) {
+      throw new AppleLLMError(`Document too large to inline (>${512e3} bytes): ${doc}`);
+    }
+    let text;
+    try {
+      text = await readFile4(doc, "utf8");
+    } catch {
+      throw new AppleLLMError(`Document is not readable text: ${doc}`);
+    }
+    if (text.includes("\uFFFD")) {
+      throw new AppleLLMError(`Document is not readable text: ${doc}`);
+    }
+    parts.push(`
+
+--- Document: ${doc} ---
+${text}`);
+  }
+  return parts.join("");
+}
+function parseImageFlag(value) {
+  const sep = value.lastIndexOf("::");
+  if (sep > 0) {
+    const path4 = value.slice(0, sep);
+    const label = value.slice(sep + 2).trim();
+    if (path4 !== "" && label !== "") return { path: path4, label };
+  }
+  return value;
+}
+
+// src/stream.ts
+var Channel = class {
+  items = [];
+  waiter;
+  closed = false;
+  push(value) {
+    this.offer({ value });
+  }
+  end() {
+    this.offer({ done: true });
+  }
+  fail(error) {
+    this.offer({ error });
+  }
+  offer(item) {
+    if (this.closed) return;
+    if (!("value" in item)) this.closed = true;
+    const waiter = this.waiter;
+    if (waiter !== void 0) {
+      this.waiter = void 0;
+      waiter(item);
+    } else {
+      this.items.push(item);
+    }
+  }
+  next() {
+    const item = this.items.shift();
+    if (item !== void 0) return Promise.resolve(item);
+    return new Promise((resolve) => {
+      this.waiter = resolve;
+    });
+  }
+};
+var ResultStream = class {
+  /** Everything about the finished generation: text, usage, tool calls, finish reason. */
+  result;
+  channel = new Channel();
+  controller = new AbortController();
+  final;
+  iterated = false;
+  finished = false;
+  constructor(run, pick) {
+    this.result = run((chunk) => this.channel.push(chunk), this.controller.signal).then(
+      (result) => {
+        this.finished = true;
+        this.channel.end();
+        return result;
+      },
+      (error) => {
+        this.finished = true;
+        this.channel.fail(error);
+        throw error;
+      }
+    );
+    this.final = this.result.then(pick);
+    this.result.catch(() => void 0);
+    this.final.catch(() => void 0);
+  }
+  /** Stop generating. The promise and the iterator both reject with an AbortError. */
+  abort(reason) {
+    this.controller.abort(reason);
+  }
+  then(onfulfilled, onrejected) {
+    return this.final.then(onfulfilled, onrejected);
+  }
+  catch(onrejected) {
+    return this.final.catch(onrejected);
+  }
+  finally(onfinally) {
+    return this.final.finally(onfinally);
+  }
+  [Symbol.asyncIterator]() {
+    if (this.iterated) throw new Error("A stream can only be iterated once.");
+    this.iterated = true;
+    return {
+      next: async () => {
+        const item = await this.channel.next();
+        if ("value" in item) return { value: item.value, done: false };
+        if ("error" in item) throw item.error;
+        return { value: void 0, done: true };
+      },
+      return: async () => {
+        if (!this.finished) this.abort();
+        return { value: void 0, done: true };
+      }
+    };
+  }
+};
+
+// src/client.ts
+async function probe(onProgress) {
+  const [device, cloud] = await Promise.all([probeDevice(onProgress), probeCloud()]);
+  if (device.cloud !== void 0) {
+    const { capabilities, contextSize, ...quota } = device.cloud;
+    cloud.quota = quota;
+    if (capabilities !== void 0) cloud.capabilities = capabilities;
+    if (contextSize !== void 0 && cloud.contextSize !== void 0) cloud.contextSize = contextSize;
+  }
+  return { device, cloud };
+}
+function anySignal(signals) {
+  const list = signals.filter((s) => s !== void 0);
+  if (list.length <= 1) return list[0];
+  const any = AbortSignal.any;
+  if (typeof any === "function") return any(list);
+  const controller = new AbortController();
+  for (const signal of list) {
+    if (signal.aborted) {
+      controller.abort(signal.reason);
+      break;
+    }
+    signal.addEventListener("abort", () => controller.abort(signal.reason), { once: true });
+  }
+  return controller.signal;
+}
+var AppleLLM = class {
+  device;
+  cloud;
+  /** Which tier `auto` settled on, once resolved. */
+  resolved;
+  readying;
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  get tier() {
+    return this.options.tier ?? "auto";
+  }
+  /** Human-readable name of the tier in use, for logs. */
+  get label() {
+    if (this.resolved === "cloud") return this.cloud?.label ?? "apple private cloud compute";
+    if (this.resolved === "device") return this.device?.label ?? "apple on-device";
+    return `apple (${this.tier})`;
+  }
+  /** Context window of the resolved tier, in tokens. */
+  get contextSize() {
+    if (this.resolved === "cloud") return this.cloud?.contextSize ?? CLOUD_CONTEXT_TOKENS;
+    return this.device?.contextSize;
+  }
+  /**
+   * Resolve the tier and do any one-time setup. Called automatically, but
+   * exposed so a caller can pay the compile cost up front with a progress bar.
+   * Concurrent first calls share one attempt.
+   */
+  async ensureReady(onProgress) {
+    if (this.resolved !== void 0) return;
+    this.readying ??= this.resolve(onProgress ?? this.options.onProgress).finally(() => {
+      this.readying = void 0;
+    });
+    return this.readying;
+  }
+  newDevice() {
+    return new DeviceClient({ useCase: this.options.useCase, guardrails: this.options.guardrails });
+  }
+  async readyCloud(progress) {
+    this.cloud ??= new CloudClient();
+    await this.cloud.ensureReady(progress);
+    this.cloud.setQuota((await probeDevice().catch(() => void 0))?.cloud);
+    this.resolved = "cloud";
+  }
+  async resolve(progress) {
+    if (this.tier === "device") {
+      this.device ??= this.newDevice();
+      await this.device.ensureReady(progress);
+      this.resolved = "device";
+      return;
+    }
+    if (this.tier === "cloud") {
+      await this.readyCloud(progress);
+      return;
+    }
+    this.device ??= this.newDevice();
+    try {
+      await this.device.ensureReady(progress);
+      this.resolved = "device";
+    } catch (deviceError) {
+      try {
+        await this.readyCloud(progress);
+      } catch (cloudError) {
+        const deviceReason = deviceError instanceof Error ? deviceError.message : String(deviceError);
+        const cloudReason = cloudError instanceof Error ? cloudError.message : String(cloudError);
+        throw new ModelUnavailableError(
+          `No Apple model is available.
+
+On-device: ${deviceReason}
+
+Cloud: ${cloudReason}`,
+          deviceError instanceof ModelUnavailableError ? deviceError.reason : "unknown"
+        );
+      }
+    }
+  }
+  /** Free text. */
+  async text(input2, options = {}) {
+    return (await this.execute(input2, options, {})).text;
+  }
+  async generate(input2, options = {}) {
+    const { schema, ...rest } = options;
+    return this.execute(input2, rest, { schema: schema === void 0 ? void 0 : resolveSchema(schema) });
+  }
+  /**
+   * Ask for JSON. On device the *shape* is guaranteed by constrained decoding;
+   * a Standard Schema's own validation (refinements, transforms) then runs on
+   * top, and the result is typed by it. On cloud the shape is requested in the
+   * prompt and recovered from the reply. Either way, a reply that fails
+   * validation is retried once with the problems pointed out, then raised as a
+   * SchemaValidationError.
+   */
+  async json(input2, options) {
+    const { schema, ...rest } = options;
+    const result = await this.execute(input2, rest, { schema: resolveSchema(schema) });
+    return result.object;
+  }
+  /**
+   * Streaming text. Iterate it for deltas, or await it for the whole reply:
+   *
+   *   for await (const delta of llm.stream(prompt)) process.stdout.write(delta);
+   *   const text = await llm.stream(prompt, { onDelta });
+   *
+   * On the cloud tier the reply arrives as one chunk: Shortcuts is not
+   * incremental.
+   */
+  stream(input2, options = {}) {
+    const { onDelta, ...rest } = options;
+    return new ResultStream(
+      (emit, signal) => this.execute(input2, rest, {
+        streaming: true,
+        signal,
+        onDelta: (delta) => {
+          onDelta?.(delta);
+          emit(delta);
+        }
+      }),
+      (result) => result.text
+    );
+  }
+  /**
+   * Streaming JSON: partial objects as the model fills them in — render a form
+   * or a card while it is still being written — and the final object, parsed
+   * and validated, as the awaited value.
+   *
+   *   for await (const partial of llm.streamJson(prompt, { schema })) render(partial);
+   */
+  streamJson(input2, options) {
+    const { schema, ...rest } = options;
+    const resolved = resolveSchema(schema);
+    return new ResultStream(
+      (emit, signal) => this.execute(input2, rest, {
+        schema: resolved,
+        streaming: true,
+        signal,
+        onPartial: (json) => {
+          try {
+            emit(JSON.parse(json));
+          } catch {
+          }
+        }
+      }),
+      (result) => result.object
+    );
+  }
+  /** The one path every generation takes. */
+  async execute(input2, options, mode) {
+    const started = Date.now();
+    await this.ensureReady();
+    let prompt;
+    let history = [];
+    let replay;
+    let system = options.system ?? this.options.system;
+    let trimHistory;
+    let images = options.images;
+    if (typeof input2 === "string") {
+      prompt = input2;
+    } else {
+      if (options.sessionId !== void 0) {
+        throw new AppleLLMError(
+          "Pass either a message list or a sessionId, not both: a named session keeps its own history."
+        );
+      }
+      const split = splitMessages(input2);
+      prompt = split.prompt;
+      history = split.history;
+      replay = split.replay.length > 0 ? new ReplayBook(split.replay) : void 0;
+      if (split.system !== void 0) system = system === void 0 ? split.system : `${system}
+
+${split.system}`;
+      trimHistory = options.trimHistory ?? true;
+      if (split.images.length > 0) images = [...images ?? [], ...split.images];
+    }
+    const tools = normalizeTools(options.tools);
+    const timeoutMs = options.timeoutMs ?? this.options.timeoutMs;
+    const signal = anySignal([
+      options.signal,
+      mode.signal,
+      timeoutMs === void 0 ? void 0 : AbortSignal.timeout(timeoutMs)
+    ]);
+    if (signal?.aborted === true) throw abortErrorFrom(signal);
+    const attempt = async (feedback) => {
+      const promptText = feedback === void 0 ? prompt : `${prompt}
+
+${feedback}`;
+      let text;
+      let finishReason2 = "stop";
+      let usage;
+      let toolCalls = [];
+      let trimmedTurns = 0;
+      if (this.resolved === "cloud") {
+        this.assertCloudCompatible({ ...options, images }, tools.builtIn.length + tools.functions.length > 0);
+        let cloudPrompt = await withDocuments(promptText, options.documents);
+        if (history.length > 0) {
+          cloudPrompt = `Conversation so far:
+${renderHistory(history)}
+
+New message from the user:
+${cloudPrompt}`;
+        }
+        let cloudSystem = system;
+        if (mode.schema !== void 0) {
+          const instruction = "Reply with a single JSON value matching this JSON Schema. Output only the JSON, with no commentary and no code fence.\n\n" + JSON.stringify(mode.schema.json, null, 2);
+          cloudSystem = cloudSystem ? `${cloudSystem}
+
+${instruction}` : instruction;
+        }
+        text = await this.cloud.text({
+          system: cloudSystem,
+          prompt: cloudPrompt,
+          webSearch: options.webSearch,
+          signal,
+          images: images !== void 0 && images.length > 0 ? images : void 0
+        });
+        if (mode.schema === void 0) mode.onDelta?.(text);
+      } else {
+        const outcome = await this.device.run(
+          {
+            system,
+            prompt: promptText,
+            schema: mode.schema === void 0 ? null : toAppleSchema(mode.schema.json),
+            temperature: options.temperature ?? this.options.temperature,
+            maxTokens: options.maxTokens ?? this.options.maxTokens,
+            images,
+            documents: options.documents,
+            sessionId: options.sessionId,
+            history: history.length > 0 ? history : void 0,
+            trimHistory,
+            tools: tools.builtIn.length > 0 ? tools.builtIn : void 0,
+            functions: tools.functions.length > 0 ? tools.functions : void 0,
+            useCase: options.useCase ?? this.options.useCase,
+            guardrails: options.guardrails ?? this.options.guardrails,
+            sampling: options.sampling ?? this.options.sampling
+          },
+          mode.streaming === true ? "stream" : "generate",
+          {
+            signal,
+            onDelta: mode.onDelta,
+            onPartial: mode.onPartial,
+            replay,
+            maxToolCalls: options.maxToolCalls
+          }
+        );
+        text = outcome.content;
+        finishReason2 = outcome.finishReason;
+        usage = outcome.usage;
+        toolCalls = outcome.toolCalls;
+        trimmedTurns = outcome.trimmedTurns;
+      }
+      let object;
+      if (mode.schema !== void 0 && finishReason2 !== "tool-calls") {
+        object = await this.parseObject(text, mode.schema);
+        if (this.resolved === "cloud") mode.onPartial?.(JSON.stringify(object));
+      }
+      return {
+        text,
+        object,
+        finishReason: finishReason2,
+        usage,
+        toolCalls,
+        trimmedTurns,
+        tier: this.resolved === "cloud" ? "cloud" : "device",
+        durationMs: Date.now() - started,
+        message: {
+          role: "assistant",
+          content: finishReason2 === "tool-calls" ? null : text,
+          ...toolCalls.length > 0 ? { toolCalls: toolCalls.map(({ id, name, arguments: args }) => ({ id, name, arguments: args })) } : {}
+        }
+      };
+    };
+    try {
+      return await attempt();
+    } catch (error) {
+      if (!(error instanceof SchemaValidationError) || mode.streaming === true) throw error;
+      return attempt(
+        `Your previous answer was rejected: ${error.message.replace(/^The model's reply did not satisfy the schema: /, "")}. Answer again, fixing those problems.`
+      );
+    }
+  }
+  /** Parse, restore nulls, validate. Throws SchemaValidationError for anything the schema rejects. */
+  async parseObject(text, schema) {
+    const tier = this.resolved === "cloud" ? "cloud" : "device";
+    let value;
+    try {
+      value = tier === "cloud" ? parseLlmJson(text) : JSON.parse(text);
+    } catch {
+      throw new SchemaValidationError("The model did not reply with valid JSON.", [{ message: "invalid JSON" }], text, tier);
+    }
+    return validateWith(schema, restoreNulls(value, schema.json), text, tier);
+  }
+  assertCloudCompatible(options, hasTools) {
+    const refuse = (what) => {
+      throw new UnsupportedError(`${what} needs the on-device tier.`, "cloud");
+    };
+    if (options.images !== void 0 && options.images.length > 0 && this.cloud?.supportsImages !== true) {
+      throw new UnsupportedError(
+        "images on the cloud tier need a server model that reads them \u2014 macOS 27 (Golden Gate) or later, where the helper can confirm it. Use the on-device tier for images here.",
+        "cloud"
+      );
+    }
+    if (options.sessionId !== void 0) refuse("sessionId");
+    if (hasTools) refuse("tools");
+  }
+  /** Conversation history for a named session (device tier only). */
+  async history(sessionId) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new UnsupportedError("history needs the on-device tier.", "cloud");
+    }
+    return this.device.history(sessionId);
+  }
+  /** Drop a named session, or all sessions when omitted (device tier only). */
+  async resetSession(sessionId) {
+    await this.ensureReady();
+    if (this.resolved === "device") await this.device.resetSession(sessionId);
+  }
+  /**
+   * A named conversation: calls sharing one native transcript, like one thread
+   * in the Siri app. History persists across helper restarts, and the
+   * transcript is rebuilt from it — trimmed to fit when it outgrows the window.
+   */
+  conversation(sessionId, options = {}) {
+    return new Conversation(this, sessionId, options);
+  }
+  /**
+   * Write with Siri, anywhere you type: drafting, rewriting and feedback
+   * built on the permissive-content-transformation guardrails. Device tier
+   * only — these are transformation tasks the default guardrails refuse.
+   */
+  async rewrite(text, options = {}) {
+    const { instruction, ...rest } = options;
+    return this.text(`Rewrite the following text. ${instruction ?? "Keep the meaning, improve clarity."}
+
+---
+${text}`, {
+      ...rest,
+      guardrails: rest.guardrails ?? "permissive",
+      system: rest.system ?? "You rewrite text. Reply with only the rewritten text, no commentary."
+    });
+  }
+  async proofread(text, options = {}) {
+    return this.text(`Fix spelling, grammar and punctuation in the following text. Preserve the meaning and tone.
+
+---
+${text}`, {
+      ...options,
+      guardrails: options.guardrails ?? "permissive",
+      system: options.system ?? "You proofread text. Reply with only the corrected text, no commentary."
+    });
+  }
+  /**
+   * Summarise text of any length. Text that does not fit the context window
+   * is summarised in parts, then the parts are summarised together — so a
+   * long report works on an 8k-token model instead of failing.
+   */
+  async summarize(text, options = {}) {
+    const { length, ...rest } = options;
+    const once = (body, what, size) => this.text(`Summarize ${what} in ${size}.
+
+---
+${body}`, {
+      ...rest,
+      guardrails: rest.guardrails ?? "permissive",
+      system: rest.system ?? "You summarize text tersely."
+    });
+    let current = text;
+    for (let round = 0; round < 4; round += 1) {
+      const chunks = await this.chunksFor(current, rest.maxTokens);
+      if (chunks.length <= 1) break;
+      const parts = [];
+      for (const chunk of chunks) {
+        parts.push(await once(chunk, "this part of a longer document", "a few sentences, keeping names, numbers and decisions"));
+      }
+      current = parts.join("\n\n");
+    }
+    return once(current, current === text ? "the following text" : "these notes on a longer document", length ?? "one short paragraph");
+  }
+  /** Split text into pieces that each fit one call, on paragraph boundaries where possible. */
+  async chunksFor(text, maxTokens) {
+    await this.ensureReady();
+    const window = this.contextSize ?? 4096;
+    const budget = Math.max(512, window - (maxTokens ?? this.options.maxTokens ?? 1024) - 256);
+    let tokens;
+    if (this.resolved === "device") {
+      try {
+        tokens = (await this.device.countTokens(text)).tokens;
+      } catch {
+        tokens = Math.ceil(text.length / 3);
+      }
+    } else {
+      tokens = Math.ceil(text.length / 3);
+    }
+    if (tokens <= budget) return [text];
+    const maxChars = Math.floor(text.length / tokens * budget * 0.85);
+    const chunks = [];
+    let current = "";
+    for (const paragraph of text.split(/\n\s*\n/)) {
+      const pieces = paragraph.length > maxChars ? paragraph.match(new RegExp(`[\\s\\S]{1,${maxChars}}`, "g")) ?? [] : [paragraph];
+      for (const piece of pieces) {
+        if (current.length + piece.length + 2 > maxChars && current !== "") {
+          chunks.push(current);
+          current = "";
+        }
+        current = current === "" ? piece : `${current}
+
+${piece}`;
+      }
+    }
+    if (current !== "") chunks.push(current);
+    return chunks;
+  }
+  async draft(topic, options = {}) {
+    const { kind, ...rest } = options;
+    return this.text(`Write a ${kind ?? "short draft"} about the following topic.
+
+---
+${topic}`, {
+      ...rest,
+      system: rest.system ?? "You are a helpful writing assistant."
+    });
+  }
+  async tone(text, tone, options = {}) {
+    return this.text(`Rewrite the following text to sound more ${tone}.
+
+---
+${text}`, {
+      ...options,
+      guardrails: options.guardrails ?? "permissive",
+      system: options.system ?? "You rewrite text. Reply with only the rewritten text, no commentary."
+    });
+  }
+  /**
+   * Ask about what's on screen: captures a screenshot (interactive selection
+   * by default, like Cmd+Shift+Space Visual Intelligence) and asks the model
+   * about it with vision. Device tier, macOS 27+.
+   */
+  async askScreen(question, options = {}) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new UnsupportedError("askScreen needs the on-device tier.", "cloud");
+    }
+    const { mode, ...rest } = options;
+    const shot = await captureScreenshot(mode ?? "interactive");
+    try {
+      return await this.text(question, { ...rest, images: [...rest.images ?? [], shot] });
+    } finally {
+      const { rm: rm4 } = await import("fs/promises");
+      await rm4(shot, { force: true }).catch(() => void 0);
+    }
+  }
+  /**
+   * `json()` in the `(system, user, schema)` shape many LLM clients use, for
+   * dropping this in behind an existing interface.
+   */
+  async completeJson(system, user, schema) {
+    return this.json(user, { system, schema });
+  }
+  /**
+   * How many tokens a request costs, before sending it. Device tier only.
+   *
+   * Turns a ContextLengthError into arithmetic: compare against `contextSize`
+   * and trim, rather than finding the ceiling by hitting it. Counts
+   * everything that shares the window — instructions, message history, tools,
+   * schema, images and documents.
+   */
+  async countTokens(input2, options = {}) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new UnsupportedError("countTokens needs the on-device tier.", "cloud");
+    }
+    let prompt;
+    let history;
+    let system = options.system ?? this.options.system;
+    if (typeof input2 === "string") {
+      prompt = input2;
+    } else {
+      const split = splitMessages(input2);
+      prompt = split.prompt;
+      history = split.history;
+      if (split.system !== void 0) system = system === void 0 ? split.system : `${system}
+
+${split.system}`;
+    }
+    const tools = normalizeTools(options.tools);
+    return this.device.countTokens(prompt, {
+      system,
+      images: options.images,
+      documents: options.documents,
+      history,
+      tools: tools.builtIn.length > 0 ? tools.builtIn : void 0,
+      functions: tools.functions.length > 0 ? tools.functions : void 0,
+      schema: options.schema === void 0 ? void 0 : resolveSchema(options.schema).json,
+      signal: options.signal
+    });
+  }
+  /**
+   * Load the model assets now so the first real call does not pay for it.
+   * Device tier only; a no-op elsewhere. See `DeviceClient.prewarm` for what it
+   * is actually worth (little, on a warm machine).
+   */
+  async prewarm(system) {
+    await this.ensureReady();
+    if (this.resolved === "device") await this.device.prewarm(system ?? this.options.system);
+  }
+  /** Release the long-lived helper process. Safe to call more than once. */
+  close() {
+    this.device?.close();
+    this.cloud?.close();
+  }
+  /** `using llm = new AppleLLM()` closes it at the end of the block. */
+  [Symbol.dispose]() {
+    this.close();
+  }
+  /** `await using llm = new AppleLLM()` closes it at the end of the block. */
+  async [Symbol.asyncDispose]() {
+    this.close();
+  }
+};
+var Conversation = class {
+  constructor(llm, sessionId, defaults = {}) {
+    this.llm = llm;
+    this.sessionId = sessionId;
+    this.defaults = defaults;
+  }
+  llm;
+  sessionId;
+  defaults;
+  with(options) {
+    return { ...options, system: options.system ?? this.defaults.system, sessionId: this.sessionId };
+  }
+  async text(prompt, options = {}) {
+    return this.llm.text(prompt, this.with(options));
+  }
+  stream(prompt, options = {}) {
+    return this.llm.stream(prompt, this.with(options));
+  }
+  async generate(prompt, options = {}) {
+    return this.llm.generate(prompt, this.with(options));
+  }
+  async json(prompt, options) {
+    return this.llm.json(prompt, this.with(options));
+  }
+  async history() {
+    return this.llm.history(this.sessionId);
+  }
+  async reset() {
+    await this.llm.resetSession(this.sessionId);
+  }
+};
+async function captureScreenshot(mode = "interactive") {
+  const { execFile: execFile5 } = await import("child_process");
+  const { promisify: promisify5 } = await import("util");
+  const { mkdtemp: mkdtemp3, stat: stat3 } = await import("fs/promises");
+  const os4 = await import("os");
+  const path4 = await import("path");
+  const execFileAsync5 = promisify5(execFile5);
+  const dir = await mkdtemp3(path4.join(os4.tmpdir(), "apple-llm-screen-"));
+  const out = path4.join(dir, "screen.png");
+  const args = mode === "interactive" ? ["-i", "-x", out] : mode === "window" ? ["-w", "-x", out] : ["-x", out];
+  try {
+    await execFileAsync5("screencapture", args, { timeout: 12e4 });
+  } catch (err) {
+    throw new AppleLLMError(
+      `Could not capture a screenshot (screencapture failed): ${err instanceof Error ? err.message : String(err)}`,
+      "device"
+    );
+  }
+  try {
+    const st = await stat3(out);
+    if (st.size === 0) throw new Error("empty capture");
+  } catch {
+    throw new AppleLLMError("Screenshot capture was cancelled or produced no image.", "device");
+  }
+  return out;
+}
+
+// src/repl.ts
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+var HELP = `commands:
+  /reset            start over
+  /system <text>    replace the instructions (and start over)
+  /image <path>     attach an image to your next message
+  /tokens           how much of the context window the conversation uses
+  /help             this list
+  /exit             quit (or Ctrl+D)`;
+async function runRepl(llm, options = {}) {
+  const tty = output.isTTY === true;
+  const dim = (s) => tty ? `\x1B[2m${s}\x1B[22m` : s;
+  const rl = createInterface({ input, output, terminal: tty });
+  const lines = rl[Symbol.asyncIterator]();
+  rl.setPrompt(tty ? "\x1B[1myou \u203A\x1B[22m " : "you \u203A ");
+  let system = options.system;
+  let messages = [];
+  let pendingImages = [];
+  let generating;
+  rl.on("SIGINT", () => {
+    if (generating !== void 0) generating.abort();
+    else rl.close();
+  });
+  await llm.ensureReady((p) => output.write(dim(`  ${p.status}
+`)));
+  output.write(dim(`${llm.label} \u2014 ${llm.contextSize ?? "?"} token context. /help for commands, Ctrl+D to quit.
+`));
+  for (; ; ) {
+    if (tty) rl.prompt();
+    const next = await lines.next();
+    if (next.done === true) break;
+    const line = String(next.value).trim();
+    if (!tty) output.write(`you \u203A ${line}
+`);
+    if (line === "") continue;
+    if (line.startsWith("/")) {
+      const [command, ...args] = line.slice(1).split(/\s+/);
+      const rest = args.join(" ");
+      if (command === "exit" || command === "quit") break;
+      if (command === "help") output.write(`${HELP}
+`);
+      else if (command === "reset") {
+        messages = [];
+        output.write(dim("conversation cleared\n"));
+      } else if (command === "system") {
+        system = rest === "" ? void 0 : rest;
+        messages = [];
+        output.write(dim(system === void 0 ? "instructions cleared\n" : "instructions set; conversation cleared\n"));
+      } else if (command === "image") {
+        if (rest === "") output.write("usage: /image <path>\n");
+        else {
+          pendingImages.push(rest);
+          output.write(dim(`attached ${rest} to your next message
+`));
+        }
+      } else if (command === "tokens") {
+        if (messages.length === 0) output.write(dim("nothing yet\n"));
+        else {
+          try {
+            const probe2 = [...messages, { role: "user", content: "" }];
+            const { tokens, contextSize } = await llm.countTokens(probe2, { system });
+            output.write(dim(`${tokens} of ${contextSize} tokens (${Math.round(tokens / contextSize * 100)}%)
+`));
+          } catch (error) {
+            output.write(`${error instanceof Error ? error.message : String(error)}
+`);
+          }
+        }
+      } else output.write(`unknown command /${command}
+${HELP}
+`);
+      continue;
+    }
+    const turn = { role: "user", content: line, ...pendingImages.length > 0 ? { images: pendingImages } : {} };
+    pendingImages = [];
+    generating = new AbortController();
+    output.write(tty ? "\x1B[1mmodel \u203A\x1B[22m " : "model \u203A ");
+    try {
+      const stream = llm.stream([...messages, turn], { ...options.call, system, signal: generating.signal });
+      for await (const delta of stream) output.write(delta);
+      const result = await stream.result;
+      output.write("\n");
+      messages.push(turn, result.message);
+      const notes = [];
+      if (result.trimmedTurns > 0) notes.push(`${result.trimmedTurns} oldest turn(s) dropped to fit`);
+      if (result.finishReason === "length") notes.push("cut off at the token limit");
+      if (result.usage !== void 0) notes.push(`${result.usage.outputTokens} tokens`);
+      notes.push(`${(result.durationMs / 1e3).toFixed(1)}s`);
+      output.write(dim(`  ${notes.join(" \xB7 ")}
+`));
+    } catch (error) {
+      output.write("\n");
+      if (error instanceof AbortError) output.write(dim("  (stopped)\n"));
+      else output.write(`${error instanceof Error ? `${error.name}: ${error.message}` : String(error)}
+`);
+    } finally {
+      generating = void 0;
+    }
+  }
+  rl.close();
+}
+
+// src/server.ts
+import http from "http";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/attachments.ts
+import { mkdtemp as mkdtemp2, rm as rm3, writeFile as writeFile2 } from "fs/promises";
+import os3 from "os";
+import path3 from "path";
+var MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+var EXTENSIONS = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/heic": ".heic",
+  "image/heif": ".heif",
+  "image/tiff": ".tiff",
+  "image/bmp": ".bmp"
+};
+var TempImages = class {
+  dir;
+  count = 0;
+  /** Write one image and return its path. */
+  async add(source, mediaType, signal) {
+    const { bytes, type } = await loadImage(source, mediaType, signal);
+    this.dir ??= await mkdtemp2(path3.join(os3.tmpdir(), "apple-llm-img-"));
+    this.count += 1;
+    const file = path3.join(this.dir, `image${this.count}${EXTENSIONS[type] ?? ".img"}`);
+    await writeFile2(file, bytes);
+    return file;
+  }
+  async dispose() {
+    if (this.dir !== void 0) await rm3(this.dir, { recursive: true, force: true }).catch(() => void 0);
+    this.dir = void 0;
+  }
+};
+async function loadImage(source, mediaType, signal) {
+  if (source instanceof Uint8Array) return { bytes: checked(source), type: mediaType ?? sniff(source) };
+  if (source instanceof ArrayBuffer) {
+    const bytes2 = new Uint8Array(source);
+    return { bytes: checked(bytes2), type: mediaType ?? sniff(bytes2) };
+  }
+  const text = source instanceof URL ? source.href : source;
+  const dataUrl = /^data:([^;,]+)?(;base64)?,(.*)$/s.exec(text);
+  if (dataUrl !== null) {
+    const bytes2 = dataUrl[2] !== void 0 ? Buffer.from(dataUrl[3], "base64") : Buffer.from(decodeURIComponent(dataUrl[3]), "utf8");
+    return { bytes: checked(bytes2), type: dataUrl[1] ?? mediaType ?? sniff(bytes2) };
+  }
+  if (/^https?:\/\//i.test(text)) {
+    const response = await fetch(text, { signal });
+    if (!response.ok) throw new AppleLLMError(`Could not download image ${text}: HTTP ${response.status}`);
+    const declared = Number(response.headers.get("content-length") ?? "0");
+    if (declared > MAX_IMAGE_BYTES) throw tooLarge();
+    const bytes2 = new Uint8Array(await response.arrayBuffer());
+    const type = response.headers.get("content-type")?.split(";")[0]?.trim();
+    return { bytes: checked(bytes2), type: mediaType ?? type ?? sniff(bytes2) };
+  }
+  const bytes = Buffer.from(text, "base64");
+  if (bytes.length === 0) throw new AppleLLMError("Image data is empty or not base64.");
+  return { bytes: checked(bytes), type: mediaType ?? sniff(bytes) };
+}
+function checked(bytes) {
+  if (bytes.length > MAX_IMAGE_BYTES) throw tooLarge();
+  return bytes;
+}
+function tooLarge() {
+  return new AppleLLMError(`Image is larger than ${MAX_IMAGE_BYTES / 1024 / 1024} MB.`);
+}
+function sniff(bytes) {
+  const at = (i) => bytes[i] ?? -1;
+  if (at(0) === 137 && at(1) === 80 && at(2) === 78 && at(3) === 71) return "image/png";
+  if (at(0) === 255 && at(1) === 216) return "image/jpeg";
+  if (at(0) === 71 && at(1) === 73 && at(2) === 70) return "image/gif";
+  if (at(8) === 87 && at(9) === 69 && at(10) === 66 && at(11) === 80) return "image/webp";
+  return "application/octet-stream";
+}
+
+// src/server.ts
+var DEFAULT_PORT = 11436;
+var MODELS = {
+  "apple-on-device": "device",
+  "apple-private-cloud": "cloud"
+};
+function errorResponse(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const make = (status, type, code) => ({
+    status,
+    body: { error: { message, type, code: code ?? null, param: null } }
+  });
+  if (error instanceof ContextLengthError) return make(400, "invalid_request_error", "context_length_exceeded");
+  if (error instanceof SchemaRejectedError || error instanceof SchemaValidationError) {
+    return make(400, "invalid_request_error", "invalid_schema");
+  }
+  if (error instanceof UnsupportedError) return make(400, "invalid_request_error", "unsupported");
+  if (error instanceof RefusalError) return make(400, "invalid_request_error", "content_filter");
+  if (error instanceof QuotaError) return make(429, "rate_limit_error", "quota_exceeded");
+  if (error instanceof TimeoutError) return make(504, "timeout_error");
+  if (error instanceof AbortError) return make(499, "request_cancelled");
+  if (error instanceof ModelBusyError) return make(503, "service_unavailable", "model_busy");
+  if (error instanceof ModelUnavailableError || error instanceof SetupRequiredError) {
+    return make(503, "service_unavailable", "model_unavailable");
+  }
+  if (error instanceof HttpError) return make(error.status, "invalid_request_error");
+  if (error instanceof AppleLLMError) return make(500, "server_error");
+  return make(500, "server_error");
+}
+var HttpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+  }
+  status;
+};
+function textOf(content) {
+  if (typeof content === "string") return content;
+  if (content === null || content === void 0) return "";
+  if (Array.isArray(content)) {
+    return content.filter((p) => p.type === "text" || p.type === "input_text").map((p) => p.text ?? "").join("\n");
+  }
+  return String(content);
+}
+async function toMessages(raw, images, signal) {
+  if (!Array.isArray(raw) || raw.length === 0) throw new HttpError(400, "`messages` must be a non-empty array.");
+  const out = [];
+  for (const message of raw) {
+    switch (message.role) {
+      case "system":
+      case "developer":
+        out.push({ role: "system", content: textOf(message.content) });
+        break;
+      case "user": {
+        const paths = [];
+        if (Array.isArray(message.content)) {
+          for (const part of message.content) {
+            if (part.type === "image_url" && part.image_url !== void 0) {
+              const url = typeof part.image_url === "string" ? part.image_url : part.image_url.url;
+              paths.push(await images.add(url, void 0, signal));
+            } else if (part.type !== "text" && part.type !== "input_text") {
+              throw new HttpError(400, `Content part "${part.type}" is not supported.`);
+            }
+          }
+        }
+        out.push({ role: "user", content: textOf(message.content), ...paths.length > 0 ? { images: paths } : {} });
+        break;
+      }
+      case "assistant":
+        out.push({
+          role: "assistant",
+          content: textOf(message.content),
+          ...message.tool_calls !== void 0 && message.tool_calls.length > 0 ? {
+            toolCalls: message.tool_calls.map((call) => ({
+              id: call.id,
+              name: call.function.name,
+              arguments: parseArguments(call.function.arguments)
+            }))
+          } : {}
+        });
+        break;
+      case "tool":
+        out.push({ role: "tool", toolCallId: String(message.tool_call_id ?? ""), name: message.name, content: textOf(message.content) });
+        break;
+      default:
+        throw new HttpError(400, `Message role "${message.role}" is not supported.`);
+    }
+  }
+  return out;
+}
+function parseArguments(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function openAIToolCalls(calls) {
+  return calls.filter((call) => call.output === void 0).map((call, index) => ({
+    index,
+    id: call.id,
+    type: "function",
+    function: { name: call.name, arguments: JSON.stringify(call.arguments ?? {}) }
+  }));
+}
+function finishReason(result) {
+  return result.finishReason === "tool-calls" ? "tool_calls" : result.finishReason;
+}
+function usageOf(result) {
+  if (result.usage === void 0) return void 0;
+  return {
+    prompt_tokens: result.usage.inputTokens,
+    completion_tokens: result.usage.outputTokens,
+    total_tokens: result.usage.totalTokens
+  };
+}
+async function readBody(req, limit = 32 * 1024 * 1024) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > limit) throw new HttpError(413, "Request body too large.");
+    chunks.push(chunk);
+  }
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (text === "") return {};
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new HttpError(400, "Request body is not valid JSON.");
+  }
+}
+function createServer(options = {}) {
+  const { port: _port, host: _host, tier: defaultTier = "device", apiKey, cors, log, ...llmOptions } = options;
+  const clients = /* @__PURE__ */ new Map();
+  const clientFor = (tier) => {
+    let client = clients.get(tier);
+    if (client === void 0) {
+      client = new AppleLLM({ ...llmOptions, tier });
+      clients.set(tier, client);
+    }
+    return client;
+  };
+  const server = http.createServer((req, res) => {
+    const started = Date.now();
+    const controller = new AbortController();
+    res.on("close", () => {
+      if (!res.writableFinished) controller.abort();
+    });
+    const send = (status, body) => {
+      if (res.headersSent) return;
+      res.writeHead(status, { "content-type": "application/json", ...corsHeaders() });
+      res.end(JSON.stringify(body));
+    };
+    const corsHeaders = () => cors === void 0 ? {} : {
+      "access-control-allow-origin": cors,
+      "access-control-allow-headers": "authorization, content-type",
+      "access-control-allow-methods": "GET, POST, OPTIONS"
+    };
+    const route = async () => {
+      const url = new URL(req.url ?? "/", "http://localhost");
+      const pathname = url.pathname.replace(/\/+$/, "") || "/";
+      if (req.method === "OPTIONS") {
+        res.writeHead(204, corsHeaders());
+        res.end();
+        return void 0;
+      }
+      if (apiKey !== void 0 && req.headers.authorization !== `Bearer ${apiKey}`) {
+        send(401, { error: { message: "Invalid API key.", type: "invalid_request_error", code: "invalid_api_key", param: null } });
+        return void 0;
+      }
+      if (req.method === "GET" && (pathname === "/health" || pathname === "/v1/health")) {
+        const state = await probe();
+        send(state.device.available || state.cloud.available ? 200 : 503, {
+          status: state.device.available || state.cloud.available ? "ok" : "unavailable",
+          device: { available: state.device.available, variant: state.device.variant, contextSize: state.device.contextSize, reason: state.device.reason },
+          cloud: { available: state.cloud.available, quota: state.cloud.quota?.status, reason: state.cloud.reason }
+        });
+        return void 0;
+      }
+      if (req.method === "GET" && pathname === "/v1/models") {
+        const created = Math.floor(Date.now() / 1e3);
+        send(200, {
+          object: "list",
+          data: Object.keys(MODELS).map((id) => ({ id, object: "model", created, owned_by: "apple" }))
+        });
+        return void 0;
+      }
+      if (req.method === "POST" && pathname === "/v1/chat/completions") {
+        const body = await readBody(req);
+        return chatCompletions(body);
+      }
+      send(404, { error: { message: `No route for ${req.method} ${pathname}.`, type: "invalid_request_error", code: "not_found", param: null } });
+      return void 0;
+    };
+    const chatCompletions = async (body) => {
+      const requested = body.model ?? "";
+      const tier = requested in MODELS ? MODELS[requested] : defaultTier;
+      const model = requested in MODELS ? requested : tier === "cloud" ? "apple-private-cloud" : "apple-on-device";
+      if (body.n !== void 0 && body.n !== 1) throw new HttpError(400, "Only n=1 is supported.");
+      const images = new TempImages();
+      try {
+        const messages = await toMessages(body.messages, images, controller.signal);
+        const functions = [];
+        if (body.tool_choice !== "none") {
+          for (const def of body.tools ?? []) {
+            if (def.type !== "function" || def.function === void 0) continue;
+            functions.push(tool({ name: def.function.name, description: def.function.description, parameters: def.function.parameters }));
+          }
+        }
+        let schema;
+        if (body.response_format?.type === "json_schema" && body.response_format.json_schema?.schema !== void 0) {
+          schema = body.response_format.json_schema.schema;
+        } else if (body.response_format?.type === "json_object") {
+          messages.unshift({ role: "system", content: "Reply with a single JSON object and nothing else." });
+        }
+        let sampling;
+        if (body.top_p !== void 0) sampling = { mode: "threshold", p: body.top_p, seed: body.seed };
+        else if (body.seed !== void 0) sampling = { mode: "topK", k: 50, seed: body.seed };
+        const call = {
+          temperature: body.temperature,
+          maxTokens: body.max_completion_tokens ?? body.max_tokens,
+          sampling,
+          tools: functions.length > 0 ? functions : void 0,
+          signal: controller.signal
+        };
+        const client = clientFor(tier);
+        const id = `chatcmpl-${randomUUID2().replace(/-/g, "").slice(0, 24)}`;
+        const created = Math.floor(Date.now() / 1e3);
+        if (body.stream === true) {
+          res.writeHead(200, {
+            "content-type": "text/event-stream",
+            "cache-control": "no-cache",
+            connection: "keep-alive",
+            ...corsHeaders()
+          });
+          const event = (payload) => {
+            if (!res.destroyed) res.write(`data: ${typeof payload === "string" ? payload : JSON.stringify(payload)}
+
+`);
+          };
+          const chunk = (delta, finish = null) => {
+            event({ id, object: "chat.completion.chunk", created, model, choices: [{ index: 0, delta, finish_reason: finish, logprobs: null }] });
+          };
+          chunk({ role: "assistant", content: "" });
+          try {
+            let result2;
+            if (schema === void 0) {
+              const stream = client.stream(messages, call);
+              for await (const delta of stream) chunk({ content: delta });
+              result2 = await stream.result;
+            } else {
+              result2 = await client.generate(messages, { ...call, schema });
+              if (result2.finishReason !== "tool-calls") chunk({ content: result2.text });
+            }
+            const calls2 = openAIToolCalls(result2.toolCalls);
+            if (calls2.length > 0 && result2.finishReason === "tool-calls") chunk({ tool_calls: calls2 });
+            chunk({}, finishReason(result2));
+            if (body.stream_options?.include_usage === true) {
+              event({ id, object: "chat.completion.chunk", created, model, choices: [], usage: usageOf(result2) ?? null });
+            }
+          } catch (error) {
+            event(errorResponse(error).body);
+            if (!res.destroyed) res.end("data: [DONE]\n\n");
+            return `${model} stream failed: ${error instanceof Error ? error.message.split("\n")[0] : String(error)}`;
+          }
+          if (!res.destroyed) res.end("data: [DONE]\n\n");
+          return `${model} stream`;
+        }
+        const result = schema === void 0 ? await client.generate(messages, call) : await client.generate(messages, { ...call, schema });
+        const calls = result.finishReason === "tool-calls" ? openAIToolCalls(result.toolCalls) : [];
+        send(200, {
+          id,
+          object: "chat.completion",
+          created,
+          model,
+          choices: [
+            {
+              index: 0,
+              message: {
+                role: "assistant",
+                content: result.finishReason === "tool-calls" ? null : result.text,
+                ...calls.length > 0 ? { tool_calls: calls.map(({ index: _i, ...rest }) => rest) } : {},
+                refusal: null
+              },
+              finish_reason: finishReason(result),
+              logprobs: null
+            }
+          ],
+          usage: usageOf(result) ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 }
+        });
+        return model;
+      } finally {
+        await images.dispose();
+      }
+    };
+    route().then((what) => {
+      if (what !== void 0) log?.(`${req.method} ${req.url} ${what} ${res.statusCode} ${Date.now() - started}ms`);
+    }).catch((error) => {
+      const { status, body } = errorResponse(error);
+      if (error instanceof ModelBusyError && !res.headersSent) res.setHeader("retry-after", "2");
+      send(status, body);
+      log?.(`${req.method} ${req.url} ${status} ${Date.now() - started}ms ${error instanceof Error ? error.message.split("\n")[0] : ""}`);
+    });
+  });
+  server.on("close", () => {
+    for (const client of clients.values()) client.close();
+  });
+  return server;
+}
+async function serve(options = {}) {
+  const server = createServer(options);
+  const port = options.port ?? DEFAULT_PORT;
+  const host = options.host ?? "127.0.0.1";
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  const bound = typeof address === "object" && address !== null ? address.port : port;
+  return {
+    server,
+    url: `http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${bound}/v1`,
+    close: () => new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections?.();
+    })
+  };
+}
+
+// src/cli.ts
 function parseArgs(argv) {
   const flags = { positional: [], image: [], document: [], tool: [] };
   for (let i = 0; i < argv.length; i += 1) {
@@ -78,6 +3117,21 @@ ${USAGE}`);
       case "--greedy":
         flags.greedy = true;
         break;
+      case "--timeout":
+        flags.timeout = take("--timeout");
+        break;
+      case "--port":
+        flags.port = take("--port");
+        break;
+      case "--host":
+        flags.host = take("--host");
+        break;
+      case "--api-key":
+        flags.apiKey = take("--api-key");
+        break;
+      case "--cors":
+        flags.cors = take("--cors");
+        break;
       default:
         flags.positional.push(arg);
     }
@@ -108,6 +3162,8 @@ var USAGE = `apple-llm \u2014 Apple's on-device and Private Cloud Compute models
   apple-llm probe                        what this machine can do
   apple-llm setup-cloud [--web-search]   install the Shortcut the cloud tier needs
   apple-llm run [options] <prompt|->     one completion ("-" reads stdin)
+  apple-llm chat [options]               interactive conversation, streamed
+  apple-llm serve [options]              OpenAI-compatible API on localhost
   apple-llm count [options] <prompt|->   tokens this prompt costs, before sending
   apple-llm ask-screen [options] <question|->   screenshot, then ask (device tier)
   apple-llm history --session <id>       show a conversation's mirrored turns
@@ -130,6 +3186,19 @@ run options:
   --seed <n>                 reproducible sampling (top-k, seeded)
   --greedy                   greedy decoding (deterministic, but degenerates)
   --web-search               cloud tier only
+  --timeout <seconds>        give up after this long
+  --json                     print the full result: text, usage, tool calls
+                             (with --schema --stream: one partial object per line)
+
+chat options: --tier, --system, --tool, --use-case, --guardrails, --max-tokens.
+  In the chat: /reset, /system <text>, /image <path>, /tokens, /help, /exit.
+
+serve options:
+  --port <n>                 default ${DEFAULT_PORT}
+  --host <addr>              default 127.0.0.1 (0.0.0.0 exposes it to your network)
+  --api-key <key>            require "Authorization: Bearer <key>"
+  --cors <origin>            allow browser clients from this origin
+  --tier device|cloud|auto   for requests not naming a model; default device
 
 ask-screen options: --mode interactive|window|fullscreen (default interactive),
   plus --system, --session, --max-tokens.
@@ -321,10 +3390,64 @@ ${USAGE}`);
 `);
       return 0;
     } finally {
-      const { rm } = await import("fs/promises");
-      await rm(shot, { force: true }).catch(() => void 0);
+      const { rm: rm4 } = await import("fs/promises");
+      await rm4(shot, { force: true }).catch(() => void 0);
+      llm.close();
+    }
+  }
+  if (command === "serve") {
+    const port = flags.port === void 0 ? DEFAULT_PORT : Number(flags.port);
+    if (!Number.isInteger(port) || port < 0 || port > 65535) return usageError(`--port must be a port number (got "${flags.port}").`);
+    if (flags.tier !== void 0 && !["device", "cloud", "auto"].includes(flags.tier)) {
+      return usageError(`--tier must be device, cloud, or auto (got "${flags.tier}").`);
+    }
+    const running = await serve({
+      port,
+      host: flags.host,
+      apiKey: flags.apiKey,
+      cors: flags.cors,
+      tier: flags.tier,
+      log: (line) => process.stderr.write(`  ${line}
+`)
+    });
+    process.stderr.write(
+      `apple-llm serving an OpenAI-compatible API at ${running.url}
+  models: apple-on-device${flags.tier === "cloud" ? " (default: apple-private-cloud)" : ""}, apple-private-cloud
+  try:    curl ${running.url}/chat/completions -H 'content-type: application/json' -d '{"model":"apple-on-device","messages":[{"role":"user","content":"Hello"}]}'
+` + (flags.host === "0.0.0.0" && flags.apiKey === void 0 ? "  warning: listening on every interface with no --api-key; anyone on your network can use it\n" : "")
+    );
+    await new Promise((resolve) => {
+      const stop = () => {
+        void running.close().then(resolve);
+      };
+      process.once("SIGINT", stop);
+      process.once("SIGTERM", stop);
+    });
+    return 0;
+  }
+  if (command === "chat") {
+    if (flags.tier !== void 0 && !["device", "cloud", "auto"].includes(flags.tier)) {
+      return usageError(`--tier must be device, cloud, or auto (got "${flags.tier}").`);
+    }
+    let tools;
+    try {
+      tools = parseTools(flags.tool, usageError);
+    } catch (err) {
+      return usageError(err instanceof Error ? err.message : String(err));
+    }
+    const maxTokens = flags.maxTokens === void 0 ? void 0 : Number(flags.maxTokens);
+    const llm = new AppleLLM({
+      tier: flags.tier ?? "auto",
+      maxTokens,
+      useCase: flags.useCase,
+      guardrails: flags.guardrails
+    });
+    try {
+      await runRepl(llm, { system: flags.system, call: { tools } });
+    } finally {
       llm.close();
     }
+    return 0;
   }
   if (command === "run") {
     const arg = flags.positional[0];
@@ -343,6 +3466,10 @@ ${USAGE}`);
     if (maxTokens !== void 0 && Number.isNaN(maxTokens)) {
       return usageError(`--max-tokens must be a number (got "${flags.maxTokens}").`);
     }
+    const timeoutMs = flags.timeout === void 0 ? void 0 : Number(flags.timeout) * 1e3;
+    if (timeoutMs !== void 0 && (Number.isNaN(timeoutMs) || timeoutMs <= 0)) {
+      return usageError(`--timeout must be a number of seconds (got "${flags.timeout}").`);
+    }
     const seed = flags.seed === void 0 ? void 0 : Number(flags.seed);
     if (seed !== void 0 && Number.isNaN(seed)) {
       return usageError(`--seed must be a number (got "${flags.seed}").`);
@@ -369,6 +3496,7 @@ ${USAGE}`);
       useCase: flags.useCase,
       guardrails: flags.guardrails,
       sampling,
+      timeoutMs,
       onProgress: (p) => process.stderr.write(`  ${p.status}
 `)
     });
@@ -376,12 +3504,9 @@ ${USAGE}`);
     const documents = flags.document.length > 0 ? flags.document : void 0;
     try {
       if (flags.schema !== void 0) {
-        if (flags.stream === true) {
-          return usageError("--stream is text only; schemas need a complete response.");
-        }
         let schemaText;
         try {
-          schemaText = await readFile(flags.schema, "utf8");
+          schemaText = await readFile3(flags.schema, "utf8");
         } catch (err) {
           throw new AppleLLMError(
             `Could not read schema file "${flags.schema}": ${err instanceof Error ? err.message : String(err)}`
@@ -395,7 +3520,7 @@ ${USAGE}`);
             `Schema file "${flags.schema}" is not valid JSON: ${err instanceof Error ? err.message : String(err)}`
           );
         }
-        const out = await llm.json(prompt, {
+        const call = {
           schema,
           system: flags.system,
           webSearch: flags.webSearch,
@@ -403,13 +3528,22 @@ ${USAGE}`);
           documents,
           sessionId: flags.session,
           tools
-        });
-        process.stdout.write(`${JSON.stringify(out, null, 2)}
+        };
+        if (flags.stream === true) {
+          const stream = llm.streamJson(prompt, call);
+          for await (const partial of stream) process.stdout.write(`${JSON.stringify(partial)}
+`);
+          const final = await stream;
+          process.stdout.write(`${JSON.stringify(final)}
+`);
+        } else if (flags.json === true) {
+          process.stdout.write(`${JSON.stringify(await llm.generate(prompt, call), null, 2)}
+`);
+        } else {
+          process.stdout.write(`${JSON.stringify(await llm.json(prompt, call), null, 2)}
 `);
-      } else if (flags.stream === true) {
-        if (tier === "cloud") {
-          return usageError("--stream needs the on-device tier.");
         }
+      } else if (flags.stream === true) {
         const out = await llm.stream(prompt, {
           system: flags.system,
           images,
@@ -421,16 +3555,21 @@ ${USAGE}`);
         process.stdout.write("\n");
         void out;
       } else {
-        const out = await llm.text(prompt, {
+        const call = {
           system: flags.system,
           webSearch: flags.webSearch,
           images,
           documents,
           sessionId: flags.session,
           tools
-        });
-        process.stdout.write(`${out}
+        };
+        if (flags.json === true) {
+          process.stdout.write(`${JSON.stringify(await llm.generate(prompt, call), null, 2)}
 `);
+        } else {
+          process.stdout.write(`${await llm.text(prompt, call)}
+`);
+        }
       }
     } finally {
       llm.close();