apple-llm 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1667 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AppleLLM: () => AppleLLM,
+  AppleLLMError: () => AppleLLMError,
+  CLOUD_CONTEXT_TOKENS: () => CLOUD_CONTEXT_TOKENS,
+  CLOUD_SHORTCUT_NAME: () => CLOUD_SHORTCUT_NAME,
+  CLOUD_SHORTCUT_NAME_WEB: () => CLOUD_SHORTCUT_NAME_WEB,
+  CloudClient: () => CloudClient,
+  ContextLengthError: () => ContextLengthError,
+  Conversation: () => Conversation,
+  DEFAULT_MAX_TOKENS: () => DEFAULT_MAX_TOKENS,
+  DEFAULT_TEMPERATURE: () => DEFAULT_TEMPERATURE,
+  DeviceClient: () => DeviceClient,
+  ModelUnavailableError: () => ModelUnavailableError,
+  QuotaError: () => QuotaError,
+  RefusalError: () => RefusalError,
+  SchemaRejectedError: () => SchemaRejectedError,
+  SetupRequiredError: () => SetupRequiredError,
+  TimeoutError: () => TimeoutError,
+  assertTools: () => assertTools,
+  cacheDir: () => cacheDir,
+  captureScreenshot: () => captureScreenshot,
+  cloudSetupHint: () => cloudSetupHint,
+  ensureBinary: () => ensureBinary,
+  extractJsonSpan: () => extractJsonSpan,
+  fingerprint: () => fingerprint,
+  helperSource: () => helperSource,
+  hostTarget: () => hostTarget,
+  installCloudShortcut: () => installCloudShortcut,
+  isAppleSiliconMac: () => isAppleSiliconMac,
+  parseImageFlag: () => parseImageFlag,
+  parseLlmJson: () => parseLlmJson,
+  probe: () => probe,
+  probeCloud: () => probeCloud,
+  probeDevice: () => probeDevice,
+  shortcutDefinition: () => shortcutDefinition,
+  stripCodeFences: () => stripCodeFences,
+  targetTripleFrom: () => targetTripleFrom,
+  toAppleSchema: () => toAppleSchema,
+  withDocuments: () => withDocuments
+});
+module.exports = __toCommonJS(index_exports);
+
+// node_modules/tsup/assets/cjs_shims.js
+var getImportMetaUrl = () => typeof document === "undefined" ? new URL(`file:${__filename}`).href : document.currentScript && document.currentScript.tagName.toUpperCase() === "SCRIPT" ? document.currentScript.src : new URL("main.js", document.baseURI).href;
+var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
+
+// src/cloud.ts
+var import_node_child_process2 = require("child_process");
+var import_promises = require("fs/promises");
+var import_node_os = __toESM(require("os"), 1);
+var import_node_path = __toESM(require("path"), 1);
+var import_node_util2 = require("util");
+
+// src/errors.ts
+var AppleLLMError = class extends Error {
+  constructor(message, tier) {
+    super(message);
+    this.tier = tier;
+    this.name = new.target.name;
+  }
+  tier;
+};
+var ModelUnavailableError = class extends AppleLLMError {
+  constructor(message, reason, tier) {
+    super(message, tier);
+    this.reason = reason;
+  }
+  reason;
+};
+var SchemaRejectedError = class extends AppleLLMError {
+};
+var ContextLengthError = class extends AppleLLMError {
+  constructor(message, tier, contextSize) {
+    super(message, tier);
+    this.contextSize = contextSize;
+  }
+  contextSize;
+};
+var QuotaError = class extends AppleLLMError {
+  constructor(message, tier, resetDate) {
+    super(message, tier);
+    this.resetDate = resetDate;
+  }
+  resetDate;
+};
+var TimeoutError = class extends AppleLLMError {
+};
+var SetupRequiredError = class extends AppleLLMError {
+  constructor(message, step, tier) {
+    super(message, tier);
+    this.step = step;
+  }
+  step;
+};
+var RefusalError = class extends AppleLLMError {
+};
+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
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.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: stat2 } = await import("fs/promises");
+  try {
+    await stat2("/usr/bin/swiftc");
+    return { command: "/usr/bin/swiftc", prefixArgs: [] };
+  } catch {
+    return null;
+  }
+}
+
+// src/cloud.ts
+var execFileAsync2 = (0, import_node_util2.promisify)(import_node_child_process2.execFile);
+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 (0, import_promises.mkdtemp)(import_node_path.default.join(import_node_os.default.tmpdir(), "apple-llm-shortcut-"));
+  try {
+    const jsonPath = import_node_path.default.join(dir, "definition.json");
+    const unsignedPath = import_node_path.default.join(dir, "unsigned.shortcut");
+    const signedPath = import_node_path.default.join(dir, `${name}.shortcut`);
+    await (0, import_promises.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 (0, import_promises.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;
+  /**
+   * 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;
+  }
+  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 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 prompt = request.system ? `${request.system}
+
+${request.prompt}` : request.prompt;
+    const dir = await (0, import_promises.mkdtemp)(import_node_path.default.join(import_node_os.default.tmpdir(), "apple-llm-cloud-"));
+    try {
+      const inPath = import_node_path.default.join(dir, "prompt.txt");
+      const outPath = import_node_path.default.join(dir, "reply.txt");
+      await (0, import_promises.writeFile)(inPath, prompt, "utf8");
+      try {
+        await execFileAsync2("shortcuts", ["run", name, "-i", inPath, "-o", outPath], {
+          timeout: CALL_TIMEOUT_MS,
+          killSignal: "SIGKILL"
+        });
+      } catch (error) {
+        throw describeRunFailure(error, name);
+      }
+      let reply;
+      try {
+        reply = await (0, import_promises.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 (0, import_promises.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() {
+  }
+};
+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
+var import_node_child_process5 = require("child_process");
+var import_node_util4 = require("util");
+
+// src/compile.ts
+var import_node_child_process3 = require("child_process");
+var import_promises2 = require("fs/promises");
+var import_node_crypto = require("crypto");
+var import_node_os2 = __toESM(require("os"), 1);
+var import_node_path2 = __toESM(require("path"), 1);
+var import_node_url = require("url");
+var import_node_util3 = require("util");
+var execFileAsync3 = (0, import_node_util3.promisify)(import_node_child_process3.execFile);
+function cacheDir() {
+  return import_node_path2.default.join(import_node_os2.default.homedir(), "Library", "Caches", "apple-llm", "bin");
+}
+function fingerprint(source, triple) {
+  return (0, import_node_crypto.createHash)("sha256").update(`${source}
+${triple}`, "utf8").digest("hex").slice(0, 12);
+}
+var cachedSource;
+async function helperSource() {
+  if (cachedSource !== void 0) return cachedSource;
+  const here = import_node_path2.default.dirname((0, import_node_url.fileURLToPath)(importMetaUrl));
+  const candidates = [
+    import_node_path2.default.join(here, "..", "swift", "helper.swift"),
+    import_node_path2.default.join(here, "swift", "helper.swift")
+  ];
+  for (const candidate of candidates) {
+    try {
+      cachedSource = await (0, import_promises2.readFile)(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 (0, import_promises2.stat)(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 = import_node_path2.default.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 (0, import_promises2.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: writeFile2 } = await import("fs/promises");
+  await writeFile2(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 (0, import_promises2.chmod)(staging, 493);
+    await (0, import_promises2.rename)(staging, target);
+  } catch (err) {
+    await (0, import_promises2.rm)(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 (0, import_promises2.rm)(sourcePath, { force: true });
+  }
+  onProgress?.({ status: "helper built" });
+  return target;
+}
+
+// src/protocol.ts
+var import_node_child_process4 = require("child_process");
+var defaultSpawner = (binary, args) => (0, import_node_child_process4.spawn)(binary, args, { stdio: ["pipe", "pipe", "pipe"] });
+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();
+  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 = "";
+    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 === "") continue;
+        const head = this.queue[0];
+        if (head === void 0) continue;
+        if (head.streaming === true) {
+          let parsedOk = false;
+          let parsedDone = false;
+          let parsedDelta = "";
+          try {
+            const parsed = JSON.parse(line);
+            parsedOk = parsed.ok === true;
+            parsedDone = parsed.done === true;
+            parsedDelta = typeof parsed.delta === "string" ? parsed.delta : "";
+          } catch {
+          }
+          if (parsedOk && !parsedDone) {
+            clearTimeout(head.timer);
+            head.timer = setTimeout(() => this.timeOut(head), this.timeoutMs);
+            try {
+              head.onDelta?.(parsedDelta);
+            } catch {
+            }
+            continue;
+          }
+          this.queue.shift();
+          clearTimeout(head.timer);
+          head.resolve(line);
+          continue;
+        }
+        const pending = this.queue.shift();
+        if (pending === void 0) continue;
+        clearTimeout(pending.timer);
+        pending.resolve(line);
+      }
+    });
+    const fail = (err) => {
+      this.child = void 0;
+      const pending = this.queue;
+      this.queue = [];
+      for (const p of pending) {
+        clearTimeout(p.timer);
+        p.reject(err);
+      }
+    };
+    child.on("error", (err) => fail(err instanceof Error ? err : new Error(String(err))));
+    child.on("close", (code) => fail(new Error(`Apple helper exited with code ${code}`)));
+    child.stdin?.on("error", () => {
+    });
+    const killer = () => {
+      if (child.exitCode === null) child.kill();
+    };
+    process.once("exit", killer);
+    child.once("close", () => process.removeListener("exit", killer));
+    return child;
+  }
+  timeOut(entry) {
+    const index = this.queue.findIndex((p) => p.timer === entry.timer);
+    if (index < 0) return;
+    this.queue.splice(index, 1);
+    this.stop();
+    const err = new TimeoutError(
+      `Apple on-device generation timed out after ${this.timeoutMs / 1e3}s.`,
+      "device"
+    );
+    entry.reject(err);
+  }
+  send(payload) {
+    const run = async () => {
+      const child = this.start();
+      return await new Promise((resolve, reject) => {
+        const entry = { resolve, reject, timer: void 0 };
+        entry.timer = setTimeout(() => {
+          const index = this.queue.findIndex((p) => p.timer === entry.timer);
+          if (index >= 0) this.queue.splice(index, 1);
+          this.stop();
+          reject(new TimeoutError(`Apple on-device generation timed out after ${this.timeoutMs / 1e3}s.`, "device"));
+        }, this.timeoutMs);
+        this.queue.push(entry);
+        child.stdin?.write(`${payload.replace(/\n/g, " ")}
+`);
+      });
+    };
+    const next = this.chain.then(run, run);
+    this.chain = next.catch(() => void 0);
+    return next;
+  }
+  /**
+   * Streaming request. The helper emits N delta lines plus a final done:true
+   * line; each delta is forwarded to onDelta as it arrives and the promise
+   * resolves with the final line. Serialised against send() through the same
+   * chain, so a stream never interleaves with another request.
+   */
+  stream(payload, onDelta) {
+    const run = async () => {
+      const child = this.start();
+      return await new Promise((resolve, reject) => {
+        const entry = {
+          resolve,
+          reject,
+          timer: void 0,
+          streaming: true,
+          onDelta,
+          parts: []
+        };
+        entry.timer = setTimeout(() => this.timeOut(entry), this.timeoutMs);
+        this.queue.push(entry);
+        child.stdin?.write(`${payload.replace(/\n/g, " ")}
+`);
+      });
+    };
+    const next = this.chain.then(run, run);
+    this.chain = next.catch(() => void 0);
+    return next;
+  }
+  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 target = key === "oneOf" ? "anyOf" : key;
+        out[target] = value.map(
+          (entry) => isPlainObject(entry) ? convertNode(entry, name, ctx).schema : entry
+        );
+      }
+    } 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");
+    nullable = nonNull.length !== rawType.length;
+    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 isObject = out.type === "object" || converted.size > 0;
+  if (isObject) {
+    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;
+  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);
+  return convertNode(schema, rootName, ctx).schema;
+}
+
+// src/device.ts
+var execFileAsync4 = (0, import_node_util4.promisify)(import_node_child_process5.execFile);
+var DEFAULT_TEMPERATURE = 0.4;
+var DEFAULT_MAX_TOKENS = 2048;
+var CALL_TIMEOUT_MS2 = 12e4;
+var BUILT_IN_TOOLS = /* @__PURE__ */ new Set(["ocr", "barcode", "spotlight"]);
+function assertTools(tools) {
+  if (tools === void 0) return;
+  for (const tool of tools) {
+    if (!BUILT_IN_TOOLS.has(tool)) {
+      throw new AppleLLMError(
+        `Unknown tool "${tool}" (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) {
+  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");
+    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");
+    default:
+      throw new AppleLLMError(`Apple on-device generation failed: ${detail}`, "device");
+  }
+}
+var DeviceClient = class {
+  constructor(options = {}) {
+    this.options = options;
+  }
+  options;
+  binary;
+  probeResult;
+  server;
+  get label() {
+    const variant = this.probeResult?.variant;
+    return variant ? `apple on-device (${variant})` : "apple on-device";
+  }
+  get contextSize() {
+    return this.probeResult?.contextSize;
+  }
+  async ensureReady(onProgress) {
+    if (this.probeResult?.available === true) return;
+    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)` : ""}`
+    });
+  }
+  getProbe() {
+    return this.probeResult;
+  }
+  /** Send one envelope and return the parsed reply, raising a typed error on failure. */
+  async exchange(envelope) {
+    await this.ensureReady();
+    const binary = this.binary ?? await ensureBinary();
+    this.server ??= new HelperServer(binary, { timeoutMs: CALL_TIMEOUT_MS2 });
+    const raw = await this.server.send(JSON.stringify(envelope));
+    let response;
+    try {
+      response = JSON.parse(raw);
+    } catch {
+      throw new AppleLLMError(`Apple helper returned an unreadable envelope: ${raw.slice(0, 200)}`, "device");
+    }
+    if (response.ok !== true) raiseFor(response, raw);
+    return response;
+  }
+  /** One request. Returns the helper's `content` string, unparsed. */
+  async complete(request) {
+    assertTools(request.tools);
+    const prompt = await withDocuments(request.prompt, request.documents);
+    const response = await this.exchange({
+      instructions: request.system ?? "",
+      prompt,
+      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,
+      tools: request.tools,
+      images: request.images,
+      useCase: request.useCase ?? this.options.useCase,
+      guardrails: request.guardrails ?? this.options.guardrails,
+      sampling: request.sampling
+    });
+    if (typeof response.content !== "string") {
+      throw new AppleLLMError("Apple helper returned no content.", "device");
+    }
+    return response.content;
+  }
+  /**
+   * Streaming text. Deltas arrive via onDelta as the model generates; the
+   * promise resolves with the full text. Text only: the helper rejects
+   * schema+stream, because partial JSON is not a usable delta.
+   */
+  async stream(prompt, options = {}) {
+    assertTools(options.tools);
+    const { onDelta, documents, ...rest } = options;
+    const fullPrompt = await withDocuments(prompt, documents);
+    await this.ensureReady();
+    const binary = this.binary ?? await ensureBinary();
+    this.server ??= new HelperServer(binary, { timeoutMs: CALL_TIMEOUT_MS2 });
+    const envelope = {
+      op: "stream",
+      instructions: rest.system ?? "",
+      prompt: fullPrompt,
+      schema: null,
+      temperature: rest.temperature ?? DEFAULT_TEMPERATURE,
+      maxTokens: rest.maxTokens ?? DEFAULT_MAX_TOKENS,
+      reuseSession: rest.reuseSession ?? false,
+      sessionId: rest.sessionId,
+      tools: rest.tools,
+      images: rest.images,
+      useCase: rest.useCase ?? this.options.useCase,
+      guardrails: rest.guardrails ?? this.options.guardrails,
+      sampling: rest.sampling
+    };
+    const raw = await this.server.stream(JSON.stringify(envelope), (delta) => {
+      if (delta !== "") onDelta?.(delta);
+    });
+    let response;
+    try {
+      response = JSON.parse(raw);
+    } catch {
+      throw new AppleLLMError(`Apple helper returned an unreadable envelope: ${raw.slice(0, 200)}`, "device");
+    }
+    if (response.ok !== true) raiseFor(response, raw);
+    if (typeof response.content !== "string") {
+      throw new AppleLLMError("Apple helper returned no content.", "device");
+    }
+    return response.content;
+  }
+  /**
+   * Conversation history for a named session: the mirrored turns the helper
+   * persisted, oldest first. Survives helper restarts; the native transcript
+   * does not, so treat a restart as a context break, not a loss.
+   */
+  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 prompt 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 the instructions too, since they share the window.
+   */
+  async countTokens(prompt, options = {}) {
+    const response = await this.exchange({
+      op: "countTokens",
+      instructions: options.system ?? "",
+      prompt: await withDocuments(prompt, void 0),
+      images: options.images,
+      tools: options.tools
+    });
+    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 JSON.parse(content);
+    } 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;
+  }
+};
+async function withDocuments(prompt, documents) {
+  if (documents === void 0 || documents.length === 0) return prompt;
+  const { readFile: readFile3, stat: stat2 } = await import("fs/promises");
+  const parts = [prompt];
+  for (const doc of documents) {
+    let size = 0;
+    try {
+      size = (await stat2(doc)).size;
+    } catch {
+      throw new AppleLLMError(`Document not found: ${doc}`, "device");
+    }
+    if (size > 512e3) {
+      throw new AppleLLMError(`Document too large to inline (>${512e3} bytes): ${doc}`, "device");
+    }
+    let text;
+    try {
+      text = await readFile3(doc, "utf8");
+    } catch {
+      throw new AppleLLMError(`Document is not readable text: ${doc}`, "device");
+    }
+    if (text.includes("\uFFFD")) {
+      throw new AppleLLMError(`Document is not readable text: ${doc}`, "device");
+    }
+    parts.push(`
+
+--- Document: ${doc} ---
+${text}`);
+  }
+  return parts.join("");
+}
+function parseImageFlag(value) {
+  const sep = value.lastIndexOf("::");
+  if (sep > 0) {
+    const path3 = value.slice(0, sep);
+    const label = value.slice(sep + 2).trim();
+    if (path3 !== "" && label !== "") return { path: path3, label };
+  }
+  return value;
+}
+
+// src/index.ts
+async function probe(onProgress) {
+  const [device, cloud] = await Promise.all([probeDevice(onProgress), probeCloud()]);
+  if (device.cloud !== void 0) cloud.quota = device.cloud;
+  return { device, cloud };
+}
+var AppleLLM = class {
+  device;
+  cloud;
+  /** Which tier `auto` settled on, once resolved. */
+  resolved;
+  options;
+  constructor(options = {}) {
+    this.options = options;
+  }
+  /** Per-call device settings, falling back to the constructor defaults. */
+  deviceDefaults(options) {
+    return {
+      temperature: options.temperature ?? this.options.temperature,
+      maxTokens: options.maxTokens ?? this.options.maxTokens,
+      images: options.images,
+      documents: options.documents,
+      sessionId: options.sessionId,
+      tools: options.tools,
+      useCase: options.useCase ?? this.options.useCase,
+      guardrails: options.guardrails ?? this.options.guardrails,
+      sampling: options.sampling ?? this.options.sampling
+    };
+  }
+  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})`;
+  }
+  /**
+   * 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.
+   */
+  async ensureReady(onProgress) {
+    const progress = onProgress ?? this.options.onProgress;
+    if (this.resolved !== void 0) return;
+    if (this.tier === "device") {
+      this.device ??= new DeviceClient({
+        useCase: this.options.useCase,
+        guardrails: this.options.guardrails
+      });
+      await this.device.ensureReady(progress);
+      this.resolved = "device";
+      return;
+    }
+    if (this.tier === "cloud") {
+      this.cloud ??= new CloudClient();
+      await this.cloud.ensureReady(progress);
+      this.cloud.setQuota((await probeDevice().catch(() => void 0))?.cloud);
+      this.resolved = "cloud";
+      return;
+    }
+    this.device ??= new DeviceClient({
+      useCase: this.options.useCase,
+      guardrails: this.options.guardrails
+    });
+    try {
+      await this.device.ensureReady(progress);
+      this.resolved = "device";
+      return;
+    } catch (deviceError) {
+      this.cloud ??= new CloudClient();
+      try {
+        await this.cloud.ensureReady(progress);
+        this.cloud.setQuota((await probeDevice().catch(() => void 0))?.cloud);
+        this.resolved = "cloud";
+        return;
+      } 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"
+        );
+      }
+    }
+  }
+  async text(prompt, options = {}) {
+    await this.ensureReady();
+    if (this.resolved === "cloud") {
+      if (options.images !== void 0 && options.images.length > 0) {
+        throw new AppleLLMError("images needs the on-device tier", "cloud");
+      }
+      if (options.sessionId !== void 0) {
+        throw new AppleLLMError("sessionId needs the on-device tier", "cloud");
+      }
+      if (options.tools !== void 0 && options.tools.length > 0) {
+        throw new AppleLLMError("tools needs the on-device tier", "cloud");
+      }
+      if (options.documents !== void 0 && options.documents.length > 0) {
+        throw new AppleLLMError("documents needs the on-device tier", "cloud");
+      }
+      return this.cloud.text({ system: options.system, prompt, webSearch: options.webSearch });
+    }
+    return this.device.text(prompt, { system: options.system, ...this.deviceDefaults(options) });
+  }
+  /**
+   * Streaming text (device tier only). Deltas arrive via onDelta as the model
+   * generates; the promise resolves with the full text. The Siri-app shape:
+   * partials first, final answer at the end.
+   */
+  async stream(prompt, options = {}) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new AppleLLMError("stream needs the on-device tier.", "cloud");
+    }
+    const { onDelta, ...rest } = options;
+    return this.device.stream(prompt, {
+      system: rest.system,
+      onDelta,
+      ...this.deviceDefaults(rest)
+    });
+  }
+  /** Conversation history for a named session (device tier only). */
+  async history(sessionId) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new AppleLLMError("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: text/stream calls sharing one native transcript,
+   * like one thread in the Siri app. History persists across helper restarts;
+   * the native transcript does not (treated as a context break, not a loss).
+   */
+  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."
+    });
+  }
+  async summarize(text, options = {}) {
+    const { length, ...rest } = options;
+    return this.text(`Summarize the following text in ${length ?? "one short paragraph"}.
+
+---
+${text}`, {
+      ...rest,
+      guardrails: rest.guardrails ?? "permissive",
+      system: rest.system ?? "You summarize text tersely."
+    });
+  }
+  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 AppleLLMError("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: rm3 } = await import("fs/promises");
+      await rm3(shot, { force: true }).catch(() => void 0);
+    }
+  }
+  /**
+   * Ask for JSON. On device the schema is *guaranteed* by constrained decoding.
+   * On cloud it is requested in the prompt and recovered from the reply — the
+   * cloud tier has no constrained decoding, so a bad shape is possible there.
+   */
+  async json(prompt, options) {
+    await this.ensureReady();
+    if (this.resolved === "cloud") {
+      if (options.images !== void 0 && options.images.length > 0) {
+        throw new AppleLLMError("images needs the on-device tier", "cloud");
+      }
+      return this.cloud.json({
+        system: options.system,
+        prompt,
+        schema: options.schema,
+        webSearch: options.webSearch
+      });
+    }
+    return this.device.json(prompt, {
+      system: options.system,
+      schema: options.schema,
+      ...this.deviceDefaults(options)
+    });
+  }
+  /**
+   * api-scribe's `LlmClient` shape, so it can drop its four files and depend on
+   * this instead. Not used internally.
+   */
+  async completeJson(system, user, schema) {
+    return this.json(user, { system, schema });
+  }
+  /**
+   * How many tokens a prompt 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.
+   */
+  async countTokens(prompt, options = {}) {
+    await this.ensureReady();
+    if (this.resolved !== "device") {
+      throw new AppleLLMError("countTokens needs the on-device tier.", "cloud");
+    }
+    return this.device.countTokens(prompt, options);
+  }
+  /**
+   * 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);
+  }
+  /** Release the long-lived helper process. Safe to call more than once. */
+  close() {
+    this.device?.close();
+    this.cloud?.close();
+  }
+};
+var Conversation = class {
+  constructor(llm, sessionId, defaults = {}) {
+    this.llm = llm;
+    this.sessionId = sessionId;
+    this.defaults = defaults;
+  }
+  llm;
+  sessionId;
+  defaults;
+  async text(prompt, options = {}) {
+    return this.llm.text(prompt, {
+      system: options.system ?? this.defaults.system,
+      ...options,
+      sessionId: this.sessionId
+    });
+  }
+  async stream(prompt, options = {}) {
+    return this.llm.stream(prompt, {
+      system: options.system ?? this.defaults.system,
+      ...options,
+      sessionId: this.sessionId
+    });
+  }
+  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: mkdtemp2, stat: stat2 } = await import("fs/promises");
+  const os3 = await import("os");
+  const path3 = await import("path");
+  const execFileAsync5 = promisify5(execFile5);
+  const dir = await mkdtemp2(path3.join(os3.tmpdir(), "apple-llm-screen-"));
+  const out = path3.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 stat2(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;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AppleLLM,
+  AppleLLMError,
+  CLOUD_CONTEXT_TOKENS,
+  CLOUD_SHORTCUT_NAME,
+  CLOUD_SHORTCUT_NAME_WEB,
+  CloudClient,
+  ContextLengthError,
+  Conversation,
+  DEFAULT_MAX_TOKENS,
+  DEFAULT_TEMPERATURE,
+  DeviceClient,
+  ModelUnavailableError,
+  QuotaError,
+  RefusalError,
+  SchemaRejectedError,
+  SetupRequiredError,
+  TimeoutError,
+  assertTools,
+  cacheDir,
+  captureScreenshot,
+  cloudSetupHint,
+  ensureBinary,
+  extractJsonSpan,
+  fingerprint,
+  helperSource,
+  hostTarget,
+  installCloudShortcut,
+  isAppleSiliconMac,
+  parseImageFlag,
+  parseLlmJson,
+  probe,
+  probeCloud,
+  probeDevice,
+  shortcutDefinition,
+  stripCodeFences,
+  targetTripleFrom,
+  toAppleSchema,
+  withDocuments
+});