@engenty/wizards-runtime 0.0.0-stage → 0.7.5

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

@@ -0,0 +1,93 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { resolveEnv, run } from "./env.js";
+import { failureOf, HarnessModel, lastJson, runClient, } from "./model.js";
+/**
+ * Cursor Agent: `cursor-agent -p` answers on the Cursor sign-in. The call's folder is its
+ * workspace: the instructions as AGENTS.md, the tools as an MCP server in .cursor/mcp.json.
+ * The answer is asked for as JSON where a schema is wanted.
+ */
+export const CURSOR_BIN = process.env.CURSOR_AGENT_BIN?.trim() || "cursor-agent";
+/** "auto" = the model the client picks itself; a binding `cursor/<model>` names one. */
+const CLASSES = {
+    classifier: "auto",
+    standard: "auto",
+    high: "auto",
+    highest: "auto",
+};
+/** The escape sequences a terminal app draws with. */
+const ANSI = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*[A-Za-z]`, "g");
+const spec = {
+    id: "cursor",
+    passThrough: /^CURSOR_API_KEY$/,
+    keyVars: ["CURSOR_API_KEY"],
+    async auth(env) {
+        try {
+            const { stdout, stderr } = await run(CURSOR_BIN, ["status"], { timeout: 15_000, env });
+            // The client draws on the terminal even here: the control sequences are taken out.
+            const text = `${stdout}\n${stderr}`.replace(ANSI, "");
+            if (/not logged in/i.test(text) || !/logged in/i.test(text)) {
+                return "none";
+            }
+            return env.CURSOR_API_KEY ? "api_key" : "subscription";
+        }
+        catch {
+            return "none";
+        }
+    },
+};
+class CursorModel extends HarnessModel {
+    provider = "cursor-agent";
+    async invoke(call) {
+        if (call.system) {
+            writeFileSync(join(call.dir, "AGENTS.md"), call.system);
+        }
+        if (call.bridgeUrl) {
+            mkdirSync(join(call.dir, ".cursor"), { recursive: true });
+            writeFileSync(join(call.dir, ".cursor", "mcp.json"), JSON.stringify({ mcpServers: { step: { url: call.bridgeUrl } } }));
+        }
+        const args = ["-p", "--output-format", "json", "--workspace", call.dir, "--approve-mcps"];
+        if (this.modelId !== "auto") {
+            args.push("--model", this.modelId);
+        }
+        if (!call.bridgeUrl) {
+            // Nothing to work through: the client answers, it does not edit.
+            args.push("--mode", "ask");
+        }
+        const { stdout, stderr, code } = await runClient(CURSOR_BIN, args, {
+            cwd: call.dir,
+            env: (await resolveEnv(spec)).env,
+            signal: call.signal,
+            stdin: call.prompt,
+        });
+        const event = lastJson(stdout);
+        if (!event) {
+            throw failureOf(this.harness, stderr.trim() || `exit ${code}`);
+        }
+        if (event.is_error) {
+            throw failureOf(this.harness, String(event.result ?? "error"));
+        }
+        return {
+            text: typeof event.result === "string" ? event.result : JSON.stringify(event.result ?? ""),
+            sessionId: event.session_id,
+            meta: { durationMs: event.duration_ms ?? 0 },
+        };
+    }
+}
+export const cursor = {
+    ...spec,
+    name: "Cursor Agent",
+    bin: CURSOR_BIN,
+    classes: CLASSES,
+    async version(env) {
+        try {
+            const { stdout } = await run(CURSOR_BIN, ["--version"], { timeout: 10_000, env });
+            return stdout.trim().split("\n").pop()?.trim() || null;
+        }
+        catch {
+            return null;
+        }
+    },
+    login: { args: ["login"], interactive: false },
+    model: (alias, effort) => new CursorModel(cursor, alias || "auto", effort),
+};

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

@@ -0,0 +1,124 @@
+import { execFile, spawn } from "node:child_process";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { layout } from "../cli/home.js";
+export const run = promisify(execFile);
+let shellEnv = null;
+/** The person's login shell, asked once: a desktop app and a bare dev server start without its variables. */
+export function loginShellEnv() {
+    shellEnv ??= new Promise((done) => {
+        const shell = process.env.SHELL || "/bin/zsh";
+        // In a session of its own, away from the terminal `wizards` runs in: an interactive
+        // shell takes over that terminal for its job control and keeps it when it ends, and Ctrl-C
+        // then reaches nobody. (execFile cannot do this: it drops `detached`.)
+        const child = spawn(shell, ["-l", "-i", "-c", "env"], {
+            detached: true,
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 10_000,
+            env: {
+                HOME: process.env.HOME,
+                USER: process.env.USER,
+                PATH: process.env.PATH,
+                TERM: "dumb",
+            },
+        });
+        let stdout = "";
+        child.stdout.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.on("error", () => done({}));
+        child.on("close", (code) => {
+            const out = {};
+            for (const line of code === 0 ? stdout.split("\n") : []) {
+                const at = line.indexOf("=");
+                if (at > 0) {
+                    out[line.slice(0, at)] = line.slice(at + 1);
+                }
+            }
+            done(out);
+        });
+    });
+    return shellEnv;
+}
+/**
+ * The environment a client gets: its sign-in as the login shell sets it (else as this process
+ * has it), PATH as the shell has it so the client is found from a GUI app too, and nothing else —
+ * no key of ours, no session of a parent client.
+ */
+export function pickEnv(shell, own, passThrough, 
+/** Folders before the shell's PATH: the clients the setup installed. */
+first = []) {
+    const picked = {};
+    const source = Object.keys(shell).length ? shell : own;
+    for (const [key, value] of Object.entries(source)) {
+        if (passThrough.test(key) && value) {
+            picked[key] = value;
+        }
+    }
+    const path = [...first, ...(shell.PATH ?? "").split(":"), ...(own.PATH ?? "").split(":")].filter(Boolean);
+    return {
+        ...picked,
+        PATH: [...new Set(path)].join(":"),
+        HOME: own.HOME,
+        USER: own.USER,
+        LANG: "en_US.UTF-8",
+        TERM: "dumb",
+    };
+}
+export function stripKeys(env, keyVars) {
+    const bare = { ...env };
+    for (const key of keyVars) {
+        delete bare[key];
+    }
+    return bare;
+}
+/** Where the setup installs clients from npm, whoever started this runtime. */
+const installed = () => [join(layout().clients, "bin")];
+const resolved = new Map();
+/**
+ * The environment a client runs in, decided once: the subscription sign-in comes first — it is
+ * what the person installed the client for — so a key the shell sets is held back while the
+ * client is signed in without it, and used only where it is the one way in.
+ */
+export function resolveEnv(spec) {
+    let pending = resolved.get(spec.id);
+    if (!pending) {
+        pending = (async () => {
+            const withKey = pickEnv(await loginShellEnv(), process.env, spec.passThrough, installed());
+            const bare = stripKeys(withKey, spec.keyVars);
+            const own = await spec.auth(bare);
+            if (own !== "none") {
+                return { env: bare, auth: own };
+            }
+            if (spec.keyVars.some((key) => withKey[key])) {
+                const keyed = await spec.auth(withKey);
+                if (keyed !== "none") {
+                    return { env: withKey, auth: "api_key" };
+                }
+            }
+            return { env: bare, auth: "none" };
+        })();
+        resolved.set(spec.id, pending);
+    }
+    return pending;
+}
+/** The environment of a sign-in: the client on its own, without a key of the shell, in a real terminal. */
+export async function loginEnv(spec) {
+    const bare = stripKeys(pickEnv(await loginShellEnv(), process.env, spec.passThrough, installed()), spec.keyVars);
+    return { ...bare, TERM: "xterm-256color", COLORTERM: "truecolor" };
+}
+/** The client's sign-in right now, on its own: asked again and again while the person signs in. */
+export async function freshAuth(spec) {
+    return spec.auth(await loginEnv(spec));
+}
+/** Forgets what was decided: the person may just have signed in or changed their shell. */
+export function forgetEnv(id) {
+    shellEnv = null;
+    if (id) {
+        resolved.delete(id);
+    }
+    else {
+        resolved.clear();
+    }
+}

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

@@ -0,0 +1,95 @@
+import { mkdirSync } from "node:fs";
+import { installCommand } from "../cli/clients.js";
+import { inherited, runtimePath } from "../cli/environment.js";
+import { layout } from "../cli/home.js";
+import { CLIENTS, vendorApp } from "../cli/machine.js";
+import { antigravity } from "./antigravity.js";
+import { claude } from "./claude.js";
+import { codex } from "./codex.js";
+import { cursor } from "./cursor.js";
+import { forgetEnv, loginShellEnv, resolveEnv } from "./env.js";
+export { HarnessModel, notInstalled, signedOut } from "./model.js";
+export { HARNESS_IDS } from "./types.js";
+/**
+ * The AI clients this runtime can run as a model, in the order the setup offers them. The first
+ * one installed is the one the setup recommends.
+ */
+export const HARNESSES = [codex, claude, antigravity, cursor];
+export function harness(id) {
+    return HARNESSES.find((h) => h.id === id) ?? null;
+}
+/** Whether a binding's vendor names a client: `claude/sonnet`, `codex/default`. */
+export function isHarnessVendor(vendor) {
+    return HARNESSES.some((h) => h.id === vendor);
+}
+const detected = new Map();
+/** One client, as it is now; asked again after a minute — it may get installed or signed in meanwhile. */
+export async function detectHarness(id, force = false) {
+    const h = harness(id);
+    if (!h) {
+        return null;
+    }
+    const hit = detected.get(id);
+    if (!force && hit && Date.now() - hit.at < 60_000) {
+        return hit.value;
+    }
+    if (force) {
+        // The person may just have signed in or set a key in their shell.
+        forgetEnv(id);
+    }
+    const client = CLIENTS.find((c) => c.id === id);
+    let value = {
+        id,
+        name: h.name,
+        install: client ? installCommand(client, layout()) : "",
+        app: client ? vendorApp(client) : null,
+        version: null,
+        auth: "none",
+        interactiveLogin: h.login.interactive,
+        images: Boolean(h.image),
+    };
+    try {
+        const { env, auth } = await resolveEnv(h);
+        const version = await h.version(env);
+        if (version) {
+            value = { ...value, version, auth };
+        }
+    }
+    catch {
+        // not installed
+    }
+    detected.set(id, { at: Date.now(), value });
+    return value;
+}
+/** Every client this runtime knows, installed or not. */
+export function detectHarnesses(force = false) {
+    return Promise.all(HARNESSES.map((h) => detectHarness(h.id, force)));
+}
+/**
+ * What the inline terminal runs to install a client: the command the terminal setup runs, shown
+ * first. A client from npm goes into the install's own prefix with the npm of its own Node.
+ */
+export async function installSpec(id) {
+    const client = CLIENTS.find((c) => c.id === id);
+    if (!client) {
+        return null;
+    }
+    const paths = layout();
+    mkdirSync(paths.clients, { recursive: true });
+    const shell = await loginShellEnv();
+    return {
+        bin: "bash",
+        args: [
+            "-c",
+            'printf "\\033[2m$ %s\\033[0m\\n\\n" "$1"; set -o pipefail; eval "$1"',
+            "install",
+            installCommand(client, paths),
+        ],
+        env: {
+            ...inherited(process.env),
+            PATH: runtimePath(paths, { ...process.env, PATH: shell.PATH || process.env.PATH }),
+            TERM: "xterm-256color",
+            COLORTERM: "truecolor",
+        },
+    };
+}

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

@@ -0,0 +1,279 @@
+import { spawn } from "node:child_process";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { note } from "@engenty-wizards/shared/run";
+import { nanoid } from "nanoid";
+import { env } from "../env.js";
+import { openBridge } from "../mcp/bridge.js";
+import { ModelUnavailableError } from "../model-errors.js";
+import { extensionOf, jsonInstruction, parseJsonAnswer, renderPrompt } from "./prompt.js";
+const workDir = join(env.dataDir, "harness");
+export const signedOut = (h) => note("clientNotSignedIn", { name: h.name });
+export const notInstalled = (h) => note("clientNotInstalled", { name: h.name });
+export const notServed = (h) => note("clientAccountNotServed", { name: h.name });
+export const exhausted = (h) => h.exhausted ?? note("clientNoCredit", { name: h.name });
+/** The failure a client reports, as the person should read it. */
+export function failureOf(h, detail) {
+    // The client's own words stay in the log: the sentence below sums them up for the person.
+    console.warn(`[${h.id}] ${detail.replace(/\s+/g, " ").trim().slice(0, 1500)}`);
+    if (/credit balance|billing|too low|usage limit|quota|insufficient|rate.?limit|\b429\b/i.test(detail)) {
+        return new ModelUnavailableError(exhausted(h));
+    }
+    // Signed in, but the vendor no longer serves that account with this client: signing in again
+    // with the same account changes nothing.
+    if (/IneligibleTier|no longer supported|UNSUPPORTED_CLIENT|not eligible/i.test(detail)) {
+        return new ModelUnavailableError(notServed(h));
+    }
+    if (/authenticat|log ?in|logged in|oauth|credential|unauthori[sz]ed|\b401\b|api key/i.test(detail)) {
+        return new ModelUnavailableError(signedOut(h));
+    }
+    return new Error(`${h.name}: ${detail}`.slice(0, 500));
+}
+/** Runs a client once with the prompt on stdin; a client that is not there raises ENOENT. */
+export function runClient(bin, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, {
+            cwd: opts.cwd,
+            stdio: ["pipe", "pipe", "pipe"],
+            signal: opts.signal,
+            env: opts.env,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += String(chunk);
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr = (stderr + String(chunk)).slice(-4000);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => resolve({ stdout, stderr, code }));
+        child.stdin.on("error", () => {
+            // The client went away before reading the prompt; `close` reports it.
+        });
+        child.stdin.end(opts.stdin ?? "");
+    });
+}
+/** The last line of an output that is a JSON object. */
+export function lastJson(stdout) {
+    for (const line of stdout.trim().split("\n").reverse()) {
+        try {
+            const value = JSON.parse(line);
+            if (value && typeof value === "object") {
+                return value;
+            }
+        }
+        catch {
+            // not it
+        }
+    }
+    return null;
+}
+export class HarnessModel {
+    specificationVersion = "v3";
+    modelId;
+    supportedUrls = {};
+    /** Whether the client validates structured output against the schema itself. */
+    nativeSchema = false;
+    /** Whether the client runs a call's tools (over the bridge); else they are left out, with a warning. */
+    usesTools = true;
+    /** Whether the client searches the web with a tool of its own, tools of the call or not. */
+    searchesWeb = true;
+    effort;
+    harness;
+    executors = new Map();
+    constructor(harness, alias, effort) {
+        this.harness = harness;
+        this.modelId = alias;
+        this.effort = effort;
+    }
+    /** The tools a call may name, by the names the agent gives them: the client runs them over the bridge. */
+    attach(tools) {
+        for (const [name, tool] of Object.entries(tools)) {
+            const t = tool;
+            if (typeof t?.execute === "function") {
+                this.executors.set(name, t);
+                if (t.id) {
+                    this.executors.set(t.id, t);
+                }
+            }
+        }
+    }
+    async doGenerate(options) {
+        const dir = join(workDir, nanoid(10));
+        mkdirSync(dir, { recursive: true });
+        const { system, prompt, files, warnings } = renderPrompt(options.prompt, dir);
+        const bridged = [];
+        let webSearch = false;
+        for (const tool of options.tools ?? []) {
+            // The client searches with its own tool; naming `web_search` is what switches it on.
+            if (tool.type === "function" && tool.name === "web_search" && this.searchesWeb) {
+                webSearch = true;
+                continue;
+            }
+            if (tool.type !== "function" || !this.usesTools) {
+                warnings.push({ type: "unsupported", feature: `tool ${tool.name}` });
+                continue;
+            }
+            const executor = this.executors.get(tool.name);
+            if (!executor?.execute) {
+                warnings.push({
+                    type: "unsupported",
+                    feature: `tool ${tool.name}`,
+                    details: "no executor",
+                });
+                continue;
+            }
+            bridged.push({
+                name: tool.name,
+                description: tool.description,
+                inputSchema: tool.inputSchema,
+                execute: (input) => executor.execute(input),
+                toModelOutput: executor.toModelOutput,
+            });
+        }
+        for (const key of ["temperature", "topP", "topK", "seed", "stopSequences"]) {
+            if (options[key] !== undefined) {
+                warnings.push({ type: "unsupported", feature: key });
+            }
+        }
+        const structured = options.responseFormat?.type === "json";
+        const schema = structured && options.responseFormat?.type === "json"
+            ? (options.responseFormat.schema ?? null)
+            : null;
+        const bridge = bridged.length ? openBridge(bridged) : null;
+        try {
+            const answer = await this.invoke({
+                dir,
+                system: structured && !this.nativeSchema
+                    ? [system, jsonInstruction(schema)].filter(Boolean).join("\n\n")
+                    : system,
+                prompt,
+                files,
+                bridgeUrl: bridge?.url ?? null,
+                schema: this.nativeSchema ? schema : null,
+                webSearch,
+                effort: this.effort,
+                signal: options.abortSignal,
+            });
+            const u = answer.usage ?? {};
+            const cacheRead = u.cacheRead ?? 0;
+            const cacheWrite = u.cacheWrite ?? 0;
+            const input = u.input ?? 0;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: structured ? JSON.stringify(parseJsonAnswer(answer.text)) : answer.text,
+                    },
+                ],
+                finishReason: { unified: "stop", raw: answer.stopReason },
+                usage: {
+                    inputTokens: {
+                        total: input,
+                        noCache: Math.max(0, input - cacheRead - cacheWrite),
+                        cacheRead,
+                        cacheWrite,
+                    },
+                    outputTokens: { total: u.output ?? 0, text: u.output ?? 0, reasoning: undefined },
+                    raw: u,
+                },
+                providerMetadata: { [this.provider]: answer.meta ?? {} },
+                response: { id: answer.sessionId, modelId: this.modelId },
+                warnings,
+            };
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new ModelUnavailableError(notInstalled(this.harness));
+            }
+            throw err;
+        }
+        finally {
+            bridge?.close();
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    /** The answer as one piece: the client prints it when it is done. */
+    async doStream(options) {
+        const result = await this.doGenerate(options);
+        const text = result.content.find((c) => c.type === "text");
+        const parts = [
+            { type: "stream-start", warnings: result.warnings },
+            { type: "response-metadata", ...result.response },
+            { type: "text-start", id: "0" },
+            { type: "text-delta", id: "0", delta: text?.type === "text" ? text.text : "" },
+            { type: "text-end", id: "0" },
+            {
+                type: "finish",
+                usage: result.usage,
+                finishReason: result.finishReason,
+                providerMetadata: result.providerMetadata,
+            },
+        ];
+        return {
+            stream: new ReadableStream({
+                start(controller) {
+                    for (const part of parts) {
+                        controller.enqueue(part);
+                    }
+                    controller.close();
+                },
+            }),
+        };
+    }
+}
+/** A client that makes images on the person's sign-in: one client run per image. */
+export class HarnessImageModel {
+    specificationVersion = "v3";
+    modelId;
+    maxImagesPerCall = 1;
+    harness;
+    constructor(harness, alias) {
+        this.harness = harness;
+        this.modelId = alias;
+    }
+    async doGenerate(options) {
+        const dir = join(workDir, nanoid(10));
+        mkdirSync(dir, { recursive: true });
+        const warnings = [];
+        const files = [];
+        for (const file of options.files ?? []) {
+            if (file.type !== "file") {
+                warnings.push({ type: "unsupported", feature: "image url" });
+                continue;
+            }
+            const path = join(dir, `ref-${files.length + 1}.${extensionOf(file.mediaType)}`);
+            writeFileSync(path, typeof file.data === "string" ? Buffer.from(file.data, "base64") : file.data);
+            files.push(path);
+        }
+        for (const key of ["size", "seed", "mask"]) {
+            if (options[key] !== undefined) {
+                warnings.push({ type: "unsupported", feature: key });
+            }
+        }
+        try {
+            const image = await this.invoke({
+                dir,
+                prompt: options.prompt ?? "",
+                files,
+                aspectRatio: options.aspectRatio,
+                signal: options.abortSignal,
+            });
+            return {
+                images: [image],
+                warnings,
+                response: { timestamp: new Date(), modelId: this.modelId, headers: undefined },
+            };
+        }
+        catch (err) {
+            if (err.code === "ENOENT") {
+                throw new ModelUnavailableError(notInstalled(this.harness));
+            }
+            throw err;
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+}