@engenty/wizards-runtime 0.0.0-stage → 0.7.5

package/apps/runtime/dist/harness/apple.js

@@ -0,0 +1,270 @@
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { release } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { langOf, SPEECH_LOCALES } from "@engenty-wizards/shared/definition";
+import { nanoid } from "nanoid";
+import { env } from "../env.js";
+import { ffmpeg, hasFfmpeg } from "../media/ffmpeg.js";
+import { ModelUnavailableError, NotedError } from "../model-errors.js";
+import { HarnessModel, lastJson, runClient, } from "./model.js";
+/**
+ * Apple Intelligence on this Mac as a model: the on-device foundation model of macOS 26, run
+ * through `wizards-apple` (apps/runtime/apple/main.swift) — one process per call, as every
+ * installed AI client is run. Nothing leaves the machine and nothing is signed in. It is offered
+ * where it can run: a Mac with Apple silicon on macOS 26 or later with the helper built, and it
+ * answers once Apple Intelligence is switched on. The model is small (about 3B parameters,
+ * 4,096 tokens for prompt and answer together): a way for the Classifier and Standard classes,
+ * not for research, long documents or code. `apple:default` is the model; `apple:tagging` is
+ * Apple's adapter for tagging and extraction.
+ */
+/** The helper: built into dist/apple by `scripts/build-apple.mjs`, or named by the environment. */
+export const APPLE_BIN = process.env.WIZARDS_APPLE_BIN?.trim() ||
+    resolve(dirname(fileURLToPath(import.meta.url)), "../../dist/apple/wizards-apple");
+export const APPLE = { id: "apple", name: "Apple Intelligence" };
+/** Darwin 25 is macOS 26: the first system with the Foundation Models framework. */
+const DARWIN_OF_MACOS_26 = 25;
+/** What this machine is, before the helper is asked: a Mac with Apple silicon on macOS 26 or later. */
+export function appleMachine(platform = process.platform, arch = process.arch, darwin = release()) {
+    if (platform !== "darwin" || arch !== "arm64") {
+        return "device";
+    }
+    return Number.parseInt(darwin, 10) >= DARWIN_OF_MACOS_26 ? null : "os";
+}
+/** The helper's reason, as the status names it. */
+export function appleReasonOf(helper) {
+    switch (helper) {
+        case "appleIntelligenceNotEnabled":
+            return "off";
+        case "modelNotReady":
+            return "loading";
+        default:
+            return "device";
+    }
+}
+/**
+ * Without instructions the model refuses guided calls as "likely unsafe" (seen on macOS 26.5
+ * with a billing complaint); any instruction settles it. A step always brings its own.
+ */
+const DEFAULT_INSTRUCTIONS = "Answer what the prompt asks, precisely and briefly.";
+const helperEnv = () => ({
+    PATH: process.env.PATH ?? "/usr/bin:/bin",
+    HOME: process.env.HOME ?? "",
+    LANG: process.env.LANG ?? "en_US.UTF-8",
+});
+let detected = null;
+/** Apple Intelligence as it is now; asked again after a minute — the person may switch it on meanwhile. */
+export async function appleStatus(force = false) {
+    if (!force && detected && Date.now() - detected.at < 60_000) {
+        return detected.value;
+    }
+    const value = await detectApple();
+    detected = { at: Date.now(), value };
+    return value;
+}
+async function detectApple() {
+    const machine = appleMachine();
+    if (machine) {
+        return { supported: false, available: false, reason: machine };
+    }
+    if (!existsSync(APPLE_BIN)) {
+        return { supported: false, available: false, reason: "missing" };
+    }
+    try {
+        const { stdout } = await runClient(APPLE_BIN, ["status"], {
+            cwd: process.cwd(),
+            env: helperEnv(),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const status = lastJson(stdout);
+        if (!status) {
+            return { supported: true, available: false, reason: "missing" };
+        }
+        return status.available
+            ? { supported: true, available: true, reason: null }
+            : { supported: true, available: false, reason: appleReasonOf(status.reason) };
+    }
+    catch {
+        return { supported: true, available: false, reason: "missing" };
+    }
+}
+/** What to tell the person when Apple Intelligence cannot answer, as a note of `RUN_NOTES`. */
+export function appleUnavailableNote(status) {
+    switch (status.reason) {
+        case "off":
+            return { code: "appleOff" };
+        case "loading":
+            return { code: "appleLoading" };
+        case "missing":
+            return { code: "appleMissing" };
+        case "os":
+            return { code: "appleOs" };
+        default:
+            return { code: "appleDevice" };
+    }
+}
+/**
+ * The failure the helper reports, as the person should read it: a note, so a run shows it in the
+ * wizard's language.
+ */
+export function appleFailure(error) {
+    switch (error.kind) {
+        case "unavailable":
+            return new ModelUnavailableError(appleUnavailableNote({
+                supported: true,
+                available: false,
+                reason: appleReasonOf(error.message),
+            }));
+        case "rateLimited":
+            return new ModelUnavailableError({ code: "appleBusy" });
+        case "contextWindow":
+            return new NotedError({ code: "appleTooLong" });
+        case "guardrail":
+        case "refusal":
+            return new NotedError({ code: "appleRefused" });
+        case "language":
+            return new NotedError({ code: "appleLanguage" });
+        case "schema":
+            return new NotedError({ code: "appleFormat", params: { detail: error.message } });
+        default:
+            return appleFailed(error.message);
+    }
+}
+/** Anything else the helper says, in its own words. */
+function appleFailed(detail) {
+    return new NotedError({ code: "appleFailed", params: { detail: detail.slice(0, 480) } });
+}
+class AppleModel extends HarnessModel {
+    provider = "apple";
+    /** The model keeps to the schema itself (guided generation). */
+    nativeSchema = true;
+    /** The helper calls no tools: a call with tools answers from the prompt alone. */
+    usesTools = false;
+    searchesWeb = false;
+    async invoke(call) {
+        const { stdout, stderr, code } = await runClient(APPLE_BIN, ["generate"], {
+            cwd: call.dir,
+            env: helperEnv(),
+            signal: call.signal,
+            stdin: JSON.stringify({
+                system: call.system || DEFAULT_INSTRUCTIONS,
+                prompt: call.prompt,
+                schema: call.schema,
+                useCase: this.modelId === "tagging" ? "tagging" : "general",
+            }),
+        });
+        const answer = lastJson(stdout);
+        if (!answer) {
+            throw appleFailed(stderr.trim() || `exit ${code}`);
+        }
+        if (answer.error) {
+            throw appleFailure(answer.error);
+        }
+        return { text: answer.text ?? "" };
+    }
+}
+/** `apple:default` or `apple:tagging` as a language model. */
+export function appleModel(alias) {
+    return new AppleModel(APPLE, alias || "default");
+}
+/** The Mac's own language: what a voice note is most likely in, unless the call names one. */
+function systemLocale() {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale;
+    return /^[a-z]{2}-[A-Z]{2}$/.test(locale) ? locale : SPEECH_LOCALES[langOf(locale) ?? "en"];
+}
+/** What AVAudioFile reads as it is; a browser's WebM or Ogg (Opus) is turned into WAV first. */
+function audioExtension(mediaType) {
+    const type = mediaType.split(";")[0].trim().toLowerCase();
+    if (/mp4|m4a|aac/.test(type)) {
+        return { ext: "m4a", native: true };
+    }
+    if (/wav/.test(type)) {
+        return { ext: "wav", native: true };
+    }
+    if (/aiff/.test(type)) {
+        return { ext: "aiff", native: true };
+    }
+    if (/mpeg|mp3/.test(type)) {
+        return { ext: "mp3", native: true };
+    }
+    if (/ogg|opus/.test(type)) {
+        return { ext: "ogg", native: false };
+    }
+    return { ext: "webm", native: false };
+}
+/**
+ * `apple:transcribe`: a voice note written down on this Mac by SpeechAnalyzer (macOS 26). It
+ * needs no Apple Intelligence, only the language's assets, which the system installs on the
+ * first call. The recording goes through a file of its own, deleted afterwards; what the
+ * system cannot read (a browser's WebM) becomes WAV through ffmpeg on the way.
+ */
+class AppleTranscriptionModel {
+    specificationVersion = "v3";
+    provider = "apple";
+    modelId = "transcribe";
+    async doGenerate(options) {
+        const dir = join(env.dataDir, "harness", nanoid(10));
+        mkdirSync(dir, { recursive: true });
+        const { ext, native } = audioExtension(options.mediaType);
+        const given = join(dir, `note.${ext}`);
+        const locale = options.providerOptions?.apple?.locale ?? systemLocale();
+        try {
+            writeFileSync(given, typeof options.audio === "string" ? Buffer.from(options.audio, "base64") : options.audio);
+            let path = given;
+            if (!native) {
+                if (!(await hasFfmpeg())) {
+                    throw new NotedError({ code: "appleNoFfmpeg", params: { type: options.mediaType } });
+                }
+                path = join(dir, "note.wav");
+                const { code, stderr } = await ffmpeg([
+                    "-y",
+                    "-i",
+                    given,
+                    "-ac",
+                    "1",
+                    "-ar",
+                    "16000",
+                    path,
+                ]);
+                if (code !== 0) {
+                    throw new NotedError({
+                        code: "appleNotConverted",
+                        params: { detail: stderr.slice(-300) },
+                    });
+                }
+            }
+            const { stdout, stderr, code } = await runClient(APPLE_BIN, ["transcribe", path, locale], {
+                cwd: dir,
+                env: helperEnv(),
+                signal: options.abortSignal,
+            });
+            const answer = lastJson(stdout);
+            if (!answer) {
+                throw appleFailed(stderr.trim() || `exit ${code}`);
+            }
+            if (answer.error) {
+                throw appleFailure(answer.error);
+            }
+            return {
+                text: answer.text ?? "",
+                segments: [],
+                language: locale.slice(0, 2),
+                durationInSeconds: undefined,
+                warnings: [],
+                response: { timestamp: new Date(), modelId: this.modelId, headers: undefined },
+            };
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new ModelUnavailableError(appleUnavailableNote({ supported: false, available: false, reason: "missing" }));
+            }
+            throw err;
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}
+export function appleTranscriptionModel() {
+    return new AppleTranscriptionModel();
+}

package/apps/runtime/dist/harness/claude.js

@@ -0,0 +1,147 @@
+import { note } from "@engenty-wizards/shared/run";
+import { resolveEnv, run } from "./env.js";
+import { failureOf, HarnessModel, lastJson, runClient, } from "./model.js";
+/**
+ * Claude Code: `claude -p` answers on the person's sign-in — the client's keychain, or the key
+ * or token their login shell sets. Tools go over MCP; structured output is validated by the
+ * client (`--json-schema`); web search is its own tool.
+ */
+export const CLAUDE_BIN = process.env.CLAUDE_BIN?.trim() || "claude";
+const CLASSES = {
+    classifier: "haiku",
+    standard: "sonnet",
+    high: "opus",
+    highest: "opus",
+};
+const spec = {
+    id: "claude",
+    passThrough: /^(ANTHROPIC_|CLAUDE_CODE_OAUTH_TOKEN$|CLAUDE_CODE_USE_|CLAUDE_CONFIG_DIR$|AWS_(PROFILE|REGION|DEFAULT_REGION|ACCESS_KEY_ID|SECRET_ACCESS_KEY|SESSION_TOKEN)$|GOOGLE_APPLICATION_CREDENTIALS$|CLOUD_ML_REGION$)/,
+    keyVars: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"],
+    async auth(env) {
+        try {
+            const { stdout } = await run(CLAUDE_BIN, ["auth", "status", "--json"], {
+                timeout: 15_000,
+                env,
+            });
+            const status = JSON.parse(stdout.trim());
+            if (!status.loggedIn) {
+                return "none";
+            }
+            return status.authMethod === "api_key" ? "api_key" : "subscription";
+        }
+        catch {
+            return "none";
+        }
+    },
+};
+export async function claudeEnv() {
+    return (await resolveEnv(spec)).env;
+}
+/** The client's result as the model call wants it: text (or the structured output as JSON) and usage. */
+export function claudeAnswer(event) {
+    const u = event.usage ?? {};
+    const cacheRead = u.cache_read_input_tokens ?? 0;
+    const cacheWrite = u.cache_creation_input_tokens ?? 0;
+    return {
+        text: event.structured_output !== undefined
+            ? JSON.stringify(event.structured_output)
+            : typeof event.result === "string"
+                ? event.result
+                : JSON.stringify(event.result ?? ""),
+        usage: {
+            input: (u.input_tokens ?? 0) + cacheRead + cacheWrite,
+            cacheRead,
+            cacheWrite,
+            output: u.output_tokens ?? 0,
+        },
+        meta: { costUsd: event.total_cost_usd ?? 0, turns: event.num_turns ?? 1 },
+        sessionId: event.session_id,
+        stopReason: event.stop_reason,
+    };
+}
+class ClaudeCodeModel extends HarnessModel {
+    provider = "claude-code";
+    nativeSchema = true;
+    async invoke(call) {
+        const builtin = [];
+        if (call.files.length) {
+            builtin.push("Read");
+        }
+        if (call.webSearch) {
+            builtin.push("WebSearch");
+        }
+        const args = [
+            "-p",
+            "--output-format",
+            "json",
+            "--model",
+            this.modelId,
+            "--tools",
+            builtin.join(","),
+            "--strict-mcp-config",
+            "--setting-sources",
+            "",
+            "--disable-slash-commands",
+            "--no-session-persistence",
+        ];
+        if (call.system) {
+            args.push("--system-prompt", call.system);
+        }
+        if (call.effort) {
+            args.push("--effort", call.effort);
+        }
+        if (call.schema) {
+            args.push("--json-schema", JSON.stringify(call.schema));
+        }
+        if (call.bridgeUrl) {
+            args.push("--mcp-config", JSON.stringify({ mcpServers: { step: { type: "http", url: call.bridgeUrl } } }));
+        }
+        const allowed = [...builtin, ...(call.bridgeUrl ? ["mcp__step"] : [])];
+        if (allowed.length) {
+            args.push("--allowedTools", allowed.join(","));
+        }
+        if (call.files.length) {
+            args.push("--add-dir", call.dir);
+        }
+        const { stdout, stderr, code } = await runClient(CLAUDE_BIN, args, {
+            cwd: call.dir,
+            env: await claudeEnv(),
+            signal: call.signal,
+            stdin: call.prompt,
+        });
+        const event = lastJson(stdout);
+        if (!event) {
+            throw failureOf(this.harness, stderr.trim() || `exit ${code}`);
+        }
+        if (event.is_error) {
+            // A failed run carries no result, only why (subtype) and sometimes what (errors).
+            const why = [
+                typeof event.result === "string" ? event.result : "",
+                event.subtype ?? "",
+                ...(event.errors ?? []).map((e) => (typeof e === "string" ? e : JSON.stringify(e))),
+                event.num_turns ? `after ${event.num_turns} turns` : "",
+            ].filter(Boolean);
+            console.warn("[claude] the client failed:", JSON.stringify(event).slice(0, 2000));
+            throw failureOf(this.harness, why.join(" – ") || "error");
+        }
+        return claudeAnswer(event);
+    }
+}
+export const claude = {
+    ...spec,
+    name: "Claude Code",
+    bin: CLAUDE_BIN,
+    classes: CLASSES,
+    async version(env) {
+        try {
+            const { stdout } = await run(CLAUDE_BIN, ["--version"], { timeout: 5000, env });
+            return stdout.trim().split(/\s+/)[0] || stdout.trim();
+        }
+        catch {
+            return null;
+        }
+    },
+    login: { args: ["auth", "login"], interactive: false },
+    model: (alias, effort) => new ClaudeCodeModel(claude, alias || "sonnet", effort),
+    exhausted: note("anthropicAccountClaudeCode"),
+};

package/apps/runtime/dist/harness/codex.js

@@ -0,0 +1,229 @@
+import { existsSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { note } from "@engenty-wizards/shared/run";
+import { resolveEnv, run } from "./env.js";
+import { failureOf, HarnessImageModel, HarnessModel, runClient, } from "./model.js";
+/**
+ * Codex: `codex exec` answers on the ChatGPT sign-in kept in CODEX_HOME. The person's own
+ * config is left out so none of their MCP servers start for a call; tools go over MCP through
+ * a config override; structured output is validated by the client (`--output-schema`).
+ */
+export const CODEX_BIN = process.env.CODEX_BIN?.trim() || "codex";
+/**
+ * Models a ChatGPT sign-in runs (checked 2026-10-04): Luna for small calls, Sol as the
+ * workhorse, Astra for the hardest work. A binding `codex/<model>` names another;
+ * `codex/default` = the model the client picks itself.
+ */
+const CLASSES = {
+    classifier: "gpt-6-luna",
+    standard: "gpt-6.1-sol",
+    high: "gpt-6.1-sol",
+    highest: "gpt-6-astra",
+};
+const spec = {
+    id: "codex",
+    passThrough: /^CODEX_HOME$/,
+    keyVars: [],
+    async auth(env) {
+        try {
+            const { stdout, stderr } = await run(CODEX_BIN, ["login", "status"], {
+                timeout: 15_000,
+                env,
+            });
+            const text = `${stdout}\n${stderr}`;
+            if (/not logged in/i.test(text)) {
+                return "none";
+            }
+            if (/api key/i.test(text)) {
+                return "api_key";
+            }
+            return /logged in/i.test(text) ? "subscription" : "none";
+        }
+        catch {
+            return "none";
+        }
+    },
+};
+/** The events of one run as the model call wants them: the last agent message and the usage. */
+export function codexAnswer(stdout) {
+    let text = null;
+    let usage;
+    let failure = null;
+    let sessionId;
+    for (const line of stdout.split("\n")) {
+        let event;
+        try {
+            event = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (event.type === "thread.started") {
+            sessionId = event.thread_id;
+        }
+        else if (event.type === "item.completed" && event.item?.type === "agent_message") {
+            text = event.item.text ?? "";
+        }
+        else if (event.type === "turn.completed") {
+            const u = event.usage ?? {};
+            usage = {
+                input: u.input_tokens ?? 0,
+                cacheRead: u.cached_input_tokens ?? 0,
+                cacheWrite: u.cache_write_input_tokens ?? 0,
+                output: u.output_tokens ?? 0,
+            };
+        }
+        else if (event.type === "turn.failed" || event.type === "error") {
+            failure =
+                typeof event.error === "string"
+                    ? event.error
+                    : (event.error?.message ?? event.message ?? "error");
+        }
+    }
+    return {
+        answer: text === null ? null : { text, usage, sessionId },
+        failure,
+    };
+}
+class CodexModel extends HarnessModel {
+    provider = "codex";
+    nativeSchema = true;
+    async invoke(call) {
+        const args = [
+            "exec",
+            "-",
+            "--json",
+            "--ephemeral",
+            "--skip-git-repo-check",
+            "--ignore-user-config",
+            "-s",
+            "read-only",
+            "-C",
+            call.dir,
+            "-c",
+            'approval_policy="never"',
+            "-c",
+            `web_search="${call.webSearch ? "live" : "disabled"}"`,
+        ];
+        if (this.modelId !== "default") {
+            args.push("-m", this.modelId);
+        }
+        if (call.effort) {
+            args.push("-c", `model_reasoning_effort="${call.effort}"`);
+        }
+        if (call.system) {
+            // A JSON string is a TOML basic string: the instructions travel as one config value.
+            args.push("-c", `developer_instructions=${JSON.stringify(call.system)}`);
+        }
+        if (call.bridgeUrl) {
+            args.push("-c", `mcp_servers.step.url="${call.bridgeUrl}"`, "-c", "mcp_servers.step.startup_timeout_sec=30", "-c", "mcp_servers.step.tool_timeout_sec=600", 
+            // The tools are this runtime's own: they run without the client asking anyone.
+            "-c", 'mcp_servers.step.default_tools_approval_mode="approve"');
+        }
+        if (call.schema) {
+            const file = join(call.dir, "schema.json");
+            writeFileSync(file, JSON.stringify(call.schema));
+            args.push("--output-schema", file);
+        }
+        const { stdout, stderr, code } = await runClient(CODEX_BIN, args, {
+            cwd: call.dir,
+            env: (await resolveEnv(spec)).env,
+            signal: call.signal,
+            stdin: call.prompt,
+        });
+        const { answer, failure } = codexAnswer(stdout);
+        if (failure || !answer) {
+            throw failureOf(this.harness, failure ?? stderr.trim() ?? `exit ${code}`);
+        }
+        return answer;
+    }
+}
+/**
+ * Images: `codex exec` with the built-in image tool, the reference photos attached with `-i`.
+ * Codex keeps what it made under CODEX_HOME/generated_images/<thread>; the file is read from
+ * there and that folder removed. `codex/image` runs the tool on the standard model.
+ */
+class CodexImageModel extends HarnessImageModel {
+    provider = "codex";
+    async invoke(call) {
+        const prompt = [
+            call.prompt,
+            call.files.length
+                ? "Work from the attached image(s): edit them as described, keeping what is not to change."
+                : "",
+            call.aspectRatio ? `Aspect ratio: ${call.aspectRatio}.` : "",
+            "Make exactly one image with your image generation tool. Write no files yourself and run no commands. Reply only with: done",
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+        const args = [
+            "exec",
+            "-",
+            "--json",
+            "--ephemeral",
+            "--skip-git-repo-check",
+            "--ignore-user-config",
+            "-s",
+            "read-only",
+            "-C",
+            call.dir,
+            "-c",
+            'approval_policy="never"',
+            "-c",
+            'web_search="disabled"',
+            "-m",
+            this.modelId === "image" ? CLASSES.standard : this.modelId,
+        ];
+        for (const file of call.files) {
+            args.push("-i", file);
+        }
+        const { env } = await resolveEnv(spec);
+        const { stdout, stderr, code } = await runClient(CODEX_BIN, args, {
+            cwd: call.dir,
+            env,
+            signal: call.signal,
+            stdin: prompt,
+        });
+        const { answer, failure } = codexAnswer(stdout);
+        if (failure || !answer?.sessionId) {
+            throw failureOf(this.harness, failure ?? stderr.trim() ?? `exit ${code}`);
+        }
+        const folder = join(env.CODEX_HOME?.trim() || join(homedir(), ".codex"), "generated_images", answer.sessionId);
+        try {
+            const made = existsSync(folder)
+                ? readdirSync(folder)
+                    .filter((f) => /\.(png|jpe?g|webp)$/i.test(f))
+                    .map((f) => join(folder, f))
+                    .sort((a, b) => statSync(b).mtimeMs - statSync(a).mtimeMs)
+                : [];
+            if (!made[0]) {
+                throw new Error(`Codex made no image: ${answer.text.slice(0, 300)}`);
+            }
+            return new Uint8Array(readFileSync(made[0]));
+        }
+        finally {
+            rmSync(folder, { recursive: true, force: true });
+        }
+    }
+}
+export const codex = {
+    ...spec,
+    name: "Codex",
+    bin: CODEX_BIN,
+    classes: CLASSES,
+    async version(env) {
+        try {
+            const { stdout } = await run(CODEX_BIN, ["--version"], { timeout: 5000, env });
+            const words = stdout.trim().split(/\s+/);
+            return words[words.length - 1] || null;
+        }
+        catch {
+            return null;
+        }
+    },
+    login: { args: ["login"], interactive: false },
+    model: (alias, effort) => new CodexModel(codex, alias || "default", effort),
+    image: { alias: "image", model: (alias) => new CodexImageModel(codex, alias || "image") },
+    exhausted: note("chatgptAccountCodexSigned"),
+};