@grida/fx 0.0.0-stage → 0.1.0-alpha.2

package/dist/binary.js

@@ -0,0 +1,119 @@
+/**
+ * Finding the engine, the `grida-fx` binary. The `grida-fx` command this package installs and
+ * every function of the SDK find it the same way:
+ *
+ * 1. `GRIDA_FX_BIN`, when set and not empty: the path of a binary (relative to the working
+ *    directory). It must be a file.
+ * 2. The engine package for this machine (`@grida/fx-darwin-arm64`, …; see `platforms.ts`), an
+ *    optional dependency of `@grida/fx`: its `bin/grida-fx`.
+ *
+ * Nothing else: the command never looks on `PATH`, where it would find itself.
+ */
+import { statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { FxError } from "./errors.js";
+import { platformFor, unsupportedReason } from "./platforms.js";
+/** The environment variable naming the binary to use. */
+export const BINARY_VARIABLE = "GRIDA_FX_BIN";
+/**
+ * The engine's path, as the module comment says; throws an {@link FxError} that says what to do
+ * when there is none.
+ */
+export function findEngine(lookup) {
+    const configured = lookup.env[BINARY_VARIABLE];
+    if (configured) {
+        const path = resolve(lookup.cwd, expandHome(configured));
+        if (!lookup.isFile(path)) {
+            throw new FxError(`${BINARY_VARIABLE} is ${configured}, which is not a file`);
+        }
+        return path;
+    }
+    const platform = platformFor(lookup.os, lookup.cpu);
+    if (platform === null) {
+        throw new FxError(`${unsupportedReason(lookup.os, lookup.cpu)} Set ${BINARY_VARIABLE} to a grida-fx binary ` +
+            `to use one built for this machine.`);
+    }
+    let packageJson = null;
+    try {
+        packageJson = lookup.resolvePackageJson(`${platform.package}/package.json`);
+    }
+    catch {
+        packageJson = null;
+    }
+    if (packageJson !== null) {
+        const engine = join(dirname(packageJson), "bin", "grida-fx");
+        if (lookup.isFile(engine)) {
+            return engine;
+        }
+        throw new FxError(`${platform.package} is installed without its engine (${engine} is missing): reinstall ` +
+            `@grida/fx, or set ${BINARY_VARIABLE} to a grida-fx binary`);
+    }
+    if (platform.libc === "glibc" && lookup.isMusl()) {
+        throw new FxError(`the preview of grida-fx needs glibc 2.28 or later on Linux, and this system's C library ` +
+            `is musl (Alpine Linux, for one), so npm left out ${platform.package}. Use a glibc-based ` +
+            `system or image (Debian, Ubuntu, …), or set ${BINARY_VARIABLE} to a grida-fx binary.`);
+    }
+    throw new FxError(`the engine package ${platform.package} is not installed. npm installs it with @grida/fx, ` +
+        `as an optional dependency, on ${platform.label}; it is left out when optional ` +
+        `dependencies are omitted (--omit=optional, --no-optional, or a lockfile made without ` +
+        `them). Reinstall @grida/fx with optional dependencies, or set ${BINARY_VARIABLE} to a ` +
+        `grida-fx binary.`);
+}
+/** The `grida-fx` binary the SDK drives, found as the module comment says. */
+export function binary(options = {}) {
+    return findEngine(machineLookup(mergeEnvironment(options.env), options.cwd ?? process.cwd()));
+}
+/** The lookup of this machine and this installation of `@grida/fx`. */
+export function machineLookup(env, cwd) {
+    const require = createRequire(import.meta.url);
+    return {
+        env,
+        os: process.platform,
+        cpu: process.arch,
+        cwd,
+        resolvePackageJson: (name) => require.resolve(name),
+        isFile,
+        isMusl,
+    };
+}
+/** `process.env` with `overrides` over it; a variable given `undefined` is removed. */
+export function mergeEnvironment(overrides) {
+    const merged = {};
+    for (const [name, value] of Object.entries(process.env)) {
+        if (value !== undefined) {
+            merged[name] = value;
+        }
+    }
+    for (const [name, value] of Object.entries(overrides ?? {})) {
+        if (value === undefined) {
+            delete merged[name];
+        }
+        else {
+            merged[name] = value;
+        }
+    }
+    return merged;
+}
+function isFile(path) {
+    try {
+        return statSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Whether the running Node was built against musl: its report names no glibc version. */
+function isMusl() {
+    try {
+        const report = process.report?.getReport();
+        return report?.header !== undefined && report.header.glibcVersionRuntime === undefined;
+    }
+    catch {
+        return false;
+    }
+}
+function expandHome(path) {
+    return path === "~" || path.startsWith("~/") ? homedir() + path.slice(1) : path;
+}

package/dist/cli.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The `grida-fx` command that `@grida/fx` installs: it finds the engine (`binary.ts`) and runs it
+ * with this process's arguments, standard streams and working directory, and ends as the engine
+ * ended: with its exit status, or by the same signal.
+ *
+ * Signals. On Unix the engine runs in a process group (and session) of its own, so a signal meant
+ * for the command reaches the engine exactly once, through this process: SIGINT, SIGTERM, SIGHUP
+ * and SIGQUIT are passed on. The engine reads a second interruption as "end now", so the same
+ * signal arriving again within {@link REPEAT_MS} is passed on once: a launcher such as `npm exec`
+ * forwards the terminal's Ctrl-C to a process that already received it. Ctrl-Z (SIGTSTP) stops
+ * the engine and then this process; SIGCONT continues both. The engine never reads standard
+ * input, so it does not need the terminal's foreground group.
+ */
+import { type ChildProcess } from "node:child_process";
+/** Signals passed on to the engine. */
+export declare const FORWARDED: readonly ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+/** The same signal again within this many milliseconds is a repeat of one interruption. */
+export declare const REPEAT_MS = 250;
+/** Runs the engine with `argv` (the arguments after the command's name) and ends this process as
+ * the engine ended. */
+export declare function main(argv: readonly string[]): void;
+/** Passes signals on to `child` (module comment); `remove` stops. */
+export declare function forwardSignals(child: ChildProcess, unix: boolean): {
+    remove(): void;
+};

package/dist/cli.js

@@ -0,0 +1,114 @@
+/**
+ * The `grida-fx` command that `@grida/fx` installs: it finds the engine (`binary.ts`) and runs it
+ * with this process's arguments, standard streams and working directory, and ends as the engine
+ * ended: with its exit status, or by the same signal.
+ *
+ * Signals. On Unix the engine runs in a process group (and session) of its own, so a signal meant
+ * for the command reaches the engine exactly once, through this process: SIGINT, SIGTERM, SIGHUP
+ * and SIGQUIT are passed on. The engine reads a second interruption as "end now", so the same
+ * signal arriving again within {@link REPEAT_MS} is passed on once: a launcher such as `npm exec`
+ * forwards the terminal's Ctrl-C to a process that already received it. Ctrl-Z (SIGTSTP) stops
+ * the engine and then this process; SIGCONT continues both. The engine never reads standard
+ * input, so it does not need the terminal's foreground group.
+ */
+import { spawn } from "node:child_process";
+import { constants } from "node:os";
+import { binary } from "./binary.js";
+/** Signals passed on to the engine. */
+export const FORWARDED = ["SIGINT", "SIGTERM", "SIGHUP", "SIGQUIT"];
+/** The same signal again within this many milliseconds is a repeat of one interruption. */
+export const REPEAT_MS = 250;
+/** The exit status of the command's own failures (no engine for this machine, …). */
+const FAILED = 1;
+/** Runs the engine with `argv` (the arguments after the command's name) and ends this process as
+ * the engine ended. */
+export function main(argv) {
+    let engine;
+    try {
+        engine = binary();
+    }
+    catch (error) {
+        process.stderr.write(`grida-fx: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.exit(FAILED);
+    }
+    const unix = process.platform !== "win32";
+    const child = spawn(engine, [...argv], { stdio: "inherit", detached: unix });
+    const listeners = forwardSignals(child, unix);
+    child.once("error", (error) => {
+        listeners.remove();
+        process.stderr.write(`grida-fx: could not start the engine (${engine}): ${error.message}\n`);
+        process.exit(FAILED);
+    });
+    child.once("exit", (status, signal) => {
+        listeners.remove();
+        if (signal !== null) {
+            raise(signal);
+            return;
+        }
+        process.exit(status ?? FAILED);
+    });
+    // Should this process end some other way first, the engine is not left running alone.
+    process.once("exit", () => {
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill("SIGTERM");
+        }
+    });
+}
+/** Passes signals on to `child` (module comment); `remove` stops. */
+export function forwardSignals(child, unix) {
+    const last = new Map();
+    const handlers = new Map();
+    const pass = (signal) => {
+        const now = Date.now();
+        const before = last.get(signal);
+        last.set(signal, now);
+        if (before !== undefined && now - before < REPEAT_MS) {
+            return;
+        }
+        if (child.exitCode === null && child.signalCode === null) {
+            child.kill(signal);
+        }
+    };
+    for (const signal of FORWARDED) {
+        if (!unix && signal !== "SIGINT" && signal !== "SIGTERM") {
+            continue;
+        }
+        handlers.set(signal, () => pass(signal));
+    }
+    if (unix) {
+        handlers.set("SIGTSTP", () => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGSTOP");
+            }
+            process.kill(process.pid, "SIGSTOP");
+        });
+        handlers.set("SIGCONT", () => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGCONT");
+            }
+        });
+    }
+    for (const [signal, handler] of handlers) {
+        process.on(signal, handler);
+    }
+    return {
+        remove() {
+            for (const [signal, handler] of handlers) {
+                process.removeListener(signal, handler);
+            }
+        },
+    };
+}
+/** Ends this process by `signal`, as the engine ended; by status 128 + its number when this
+ * process outlives it (Node itself handles a few signals). */
+function raise(signal) {
+    const number = constants.signals[signal] ?? 0;
+    process.removeAllListeners(signal);
+    try {
+        process.kill(process.pid, signal);
+    }
+    catch {
+        // Fall through to the exit status.
+    }
+    setTimeout(() => process.exit(128 + number), 100);
+}

package/dist/documents.d.ts

@@ -0,0 +1,213 @@
+/**
+ * The JSON documents the engine prints, as TypeScript types: written by hand from `spec/schemas/`
+ * (fx-graph-v1, fx-run-events-v1) and the command line (`price`, `identity`, `project`,
+ * `inspect --json`). Their fields keep the contracts' `lower_snake_case`. They cover what a
+ * program reads; the schemas are complete.
+ */
+import type { JsonValue } from "./workflow.js";
+/** A problem that refuses a plan. */
+export interface Problem {
+    where: string;
+    message: string;
+}
+/** An amount range in US dollars. */
+export interface PriceRange {
+    low_usd: number;
+    high_usd: number;
+}
+/** A with-value of the graph: a plain value, or `{ pending: [<instance ids>] }` while it waits on
+ * what runs before it. */
+export type WithValue = JsonValue;
+/** One step instance of the expanded graph. */
+export interface GraphInstance {
+    /** The instance id, e.g. `draw#1` or `entity['ada'].draw#1`. */
+    id: string;
+    /** The step path, with repeat keys. */
+    path: string;
+    /** The declared step's path, without repeat keys. */
+    step: string;
+    /** One take per regenerating level, outermost first. */
+    take: number[];
+    uses: string;
+    /** The type identity; null when the type could not be resolved. */
+    type: string | null;
+    with: {
+        [name: string]: WithValue;
+    };
+    /** Each capability the type calls, with the route bound to it. */
+    routes: {
+        [capability: string]: {
+            route: string;
+            fingerprint: string;
+        };
+    };
+    state: "planned" | "maybe" | "absent" | "blocked" | "failed" | "done";
+    /** The step identity; null while a with-value is pending. */
+    identity: string | null;
+    phase: number;
+    key: string | null;
+    judges: string | null;
+    judged_by: string[];
+    waiting_on: string[];
+    needs: string[];
+    reads: string[];
+    price: PriceRange;
+    view?: boolean | string;
+    [field: string]: unknown;
+}
+/** `grida-fx expand`, and `plan --json`: the expanded graph (fx-graph-v1). */
+export interface Graph {
+    kind: "fx-graph-v1";
+    workflow: {
+        id: string;
+        title: string;
+        description?: string;
+        file?: string;
+    };
+    /** Each distinct `uses`, with its type identity (and a project type's source digests). */
+    types?: {
+        [uses: string]: {
+            identity: string;
+            source?: {
+                files: {
+                    [label: string]: string;
+                };
+                resources: {
+                    [path: string]: string;
+                };
+            };
+        };
+    };
+    instances: GraphInstance[];
+    /** Repeats whose instances a later phase expands, with their worst case. */
+    pending: {
+        path: string;
+        max: number;
+        phase: number;
+        high_usd: number;
+    }[];
+    estimate: PriceRange & {
+        ceiling_usd: number | null;
+    };
+    /** Why the plan is refused; empty when it is not. */
+    problems: Problem[];
+    [field: string]: unknown;
+}
+/** `grida-fx identity`: each live instance's identity, null while it is pending. */
+export type Identities = {
+    [instanceId: string]: string | null;
+};
+/** One phase of {@link Price}. */
+export interface PricePhase extends PriceRange {
+    phase: number;
+    steps: number;
+    /** The fewest and the most provider calls. */
+    calls: [number, number];
+    /** What the phase leaves to later phases (repeats over a run-time list). */
+    then: string[];
+}
+/** `grida-fx price`: the plan's price by phase. */
+export interface Price {
+    phases: PricePhase[];
+    estimate: PriceRange;
+    ceiling_usd: number | null;
+}
+/** A file in a run's record: by digest. */
+export interface FileRef {
+    digest: string;
+    /** The file kind (`image/png`, `json`, …). */
+    kind: string;
+    name: string;
+    size: number;
+    /** A collection item's key. */
+    key?: string;
+}
+/** A value in a run's record (fx-run-events-v1 `encoded`). */
+export type Encoded = {
+    file: FileRef;
+} | {
+    collection: [string, Encoded][];
+} | {
+    list: Encoded[];
+} | {
+    none: true;
+} | {
+    value: JsonValue;
+};
+/** One event of a run's `events.jsonl` (fx-run-events-v1), without `kind`; only the common fields
+ * are typed. */
+export interface RunEvent {
+    event: string;
+    plan?: string;
+    [field: string]: unknown;
+}
+/** The `run_finished` event. */
+export interface RunFinished extends RunEvent {
+    event: "run_finished";
+    ok: boolean;
+    incomplete: boolean;
+    stopped: string | null;
+    charged_usd: number;
+    failed: string[];
+    outputs: {
+        [name: string]: Encoded;
+    };
+}
+/** One instance in {@link Projection}. */
+export interface ProjectedInstance {
+    state: "running" | "succeeded" | "failed" | "skipped";
+    path: string;
+    /** Succeeded: whether its result came from the cache. */
+    cache?: "hit" | "miss" | null;
+    /** Succeeded: the facts its body reported. */
+    facts?: {
+        [name: string]: JsonValue;
+    };
+    /** Failed or skipped: why. */
+    error?: string | null;
+}
+/** `grida-fx project <run>`: a run's record projected to its state. */
+export interface Projection {
+    instances: {
+        [instanceId: string]: ProjectedInstance;
+    };
+    run: {
+        run_started?: RunEvent;
+        run_finished?: RunFinished;
+        run_cancelled?: RunEvent & {
+            reason?: string;
+            charged_usd?: number;
+        };
+    };
+}
+/** One step of {@link Inspection}. */
+export interface InspectedStep {
+    id: string;
+    path: string;
+    state: "succeeded" | "failed" | "skipped" | "running" | "pending";
+    error?: string;
+    cache?: "hit" | "miss";
+    /** Its files, where the run placed them: paths relative to the run folder. */
+    files: {
+        path: string;
+        digest: string;
+        size: number;
+    }[];
+}
+/** `grida-fx inspect <run> --json`: a run's summary. */
+export interface Inspection {
+    run: {
+        workflow: string;
+        /** The run folder, as it was named. */
+        folder: string;
+        state: "planned" | "unfinished" | "succeeded" | "failed" | "cancelled";
+        /** What the run was charged; null before it ended. */
+        charged_usd: number | null;
+        steps: InspectedStep[];
+    };
+    /** With `verify`: whether every placed file still matches its record. */
+    verification?: {
+        verified: boolean;
+        problems: string[];
+    };
+}

package/dist/documents.js

@@ -0,0 +1,7 @@
+/**
+ * The JSON documents the engine prints, as TypeScript types: written by hand from `spec/schemas/`
+ * (fx-graph-v1, fx-run-events-v1) and the command line (`price`, `identity`, `project`,
+ * `inspect --json`). Their fields keep the contracts' `lower_snake_case`. They cover what a
+ * program reads; the schemas are complete.
+ */
+export {};

package/dist/engine.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Running the engine and reading what it prints.
+ *
+ * The engine runs in the caller's process group, so a Ctrl-C at the terminal reaches it as it
+ * reaches the caller, and it stops a run as it would on its own: do not also abort the call on
+ * that Ctrl-C (a second interruption makes the engine end at once). An `AbortSignal` stops it from
+ * code: the engine gets SIGINT, and SIGKILL if it has not exited 10 seconds later.
+ *
+ * A call ends when the engine exits, not when the last holder of its pipes closes them: a process
+ * a node body started may outlive the engine on purpose.
+ */
+import { type Environment } from "./binary.js";
+import { FxError } from "./errors.js";
+/** Options every call takes. */
+export interface CallOptions {
+    /** The engine's working directory (default: the process's). Relative paths start here. */
+    readonly cwd?: string;
+    /** Variables over `process.env` for the engine (`undefined` removes one), e.g.
+     * `GRIDA_FX_PYTHON`. `GRIDA_FX_BIN` here also chooses the binary. */
+    readonly env?: Environment;
+    /** Stops the engine (SIGINT, then SIGKILL after 10 seconds); the call rejects with the
+     * signal's reason once it has exited. */
+    readonly signal?: AbortSignal;
+}
+/** How a call ended. */
+export interface Exit {
+    /** The exit status; null when a signal ended the engine. */
+    readonly status: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly args: readonly string[];
+}
+/** The exit status of an unreadable input or a usage mistake. */
+export declare const USAGE_OR_ERROR = 2;
+/** The exit status of an interrupted command. */
+export declare const INTERRUPTED = 130;
+/** Runs the engine with `args` and collects what it prints. */
+export declare function call(args: readonly string[], options?: CallOptions): Promise<Exit>;
+/** The error of a call that did not end as `verb` should. */
+export declare function failure(verb: string, done: Exit): FxError;
+/** The JSON document a verb prints, read when it exits with one of `statuses`. */
+export declare function document<T>(verb: string, args: readonly string[], options: CallOptions, statuses?: readonly number[]): Promise<T>;

package/dist/engine.js

@@ -0,0 +1,130 @@
+/**
+ * Running the engine and reading what it prints.
+ *
+ * The engine runs in the caller's process group, so a Ctrl-C at the terminal reaches it as it
+ * reaches the caller, and it stops a run as it would on its own: do not also abort the call on
+ * that Ctrl-C (a second interruption makes the engine end at once). An `AbortSignal` stops it from
+ * code: the engine gets SIGINT, and SIGKILL if it has not exited 10 seconds later.
+ *
+ * A call ends when the engine exits, not when the last holder of its pipes closes them: a process
+ * a node body started may outlive the engine on purpose.
+ */
+import { spawn } from "node:child_process";
+import { findEngine, machineLookup, mergeEnvironment } from "./binary.js";
+import { FxError } from "./errors.js";
+/** The exit status of an unreadable input or a usage mistake. */
+export const USAGE_OR_ERROR = 2;
+/** The exit status of an interrupted command. */
+export const INTERRUPTED = 130;
+/** How long a stopped engine has to exit before it is killed. */
+const STOP_GRACE_MS = 10_000;
+/** How long the pipes are still read once the engine has exited. */
+const DRAIN_MS = 500;
+/** How the engine prefixes an error on stderr. */
+const ERROR_PREFIX = "grida-fx: ";
+/** Runs the engine with `args` and collects what it prints. */
+export async function call(args, options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const env = mergeEnvironment(options.env);
+    const engine = findEngine(machineLookup(env, cwd));
+    options.signal?.throwIfAborted();
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn(engine, [...args], {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        let killTimer;
+        const onAbort = () => {
+            if (child.exitCode === null && child.signalCode === null) {
+                child.kill("SIGINT");
+                killTimer = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+            }
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        const finish = () => {
+            options.signal?.removeEventListener("abort", onAbort);
+            if (killTimer !== undefined) {
+                clearTimeout(killTimer);
+            }
+        };
+        child.once("error", (error) => {
+            finish();
+            reject(new FxError(`grida-fx could not be started (${engine}): ${error.message}`, {
+                args,
+                cause: error,
+            }));
+        });
+        child.once("exit", (status, signal) => {
+            finish();
+            // What the engine wrote before it exited is in the pipes: read it, then stop reading.
+            const closed = new Promise((done) => child.once("close", () => done()));
+            const drained = new Promise((done) => setTimeout(done, DRAIN_MS).unref());
+            void Promise.race([closed, drained]).then(() => {
+                child.stdout.destroy();
+                child.stderr.destroy();
+                if (options.signal?.aborted) {
+                    reject(options.signal.reason);
+                    return;
+                }
+                resolvePromise({
+                    status,
+                    signal,
+                    stdout: Buffer.concat(stdout).toString("utf8"),
+                    stderr: Buffer.concat(stderr).toString("utf8"),
+                    args,
+                });
+            });
+        });
+    });
+}
+/** The error of a call that did not end as `verb` should. */
+export function failure(verb, done) {
+    const details = {
+        exitCode: done.status,
+        signal: done.signal,
+        stdout: done.stdout,
+        stderr: done.stderr,
+        args: done.args,
+    };
+    if (done.status === USAGE_OR_ERROR) {
+        let text = done.stderr.trim() || done.stdout.trim();
+        if (text.startsWith(ERROR_PREFIX)) {
+            text = text.slice(ERROR_PREFIX.length);
+        }
+        return new FxError(text || `grida-fx exited with status ${done.status}`, details);
+    }
+    if (done.status === INTERRUPTED) {
+        return new FxError(`grida-fx ${verb} was interrupted`, details);
+    }
+    const how = done.signal !== null ? `was ended by ${done.signal}` : `exited with status ${done.status}`;
+    const tail = (done.stderr.trim() || done.stdout.trim()).slice(-2000);
+    return new FxError(`grida-fx ${verb} ${how}${tail ? `: ${tail}` : ""}`, details);
+}
+/** The JSON document a verb prints, read when it exits with one of `statuses`. */
+export async function document(verb, args, options, statuses = [0, 1]) {
+    const done = await call([verb, ...args], options);
+    if (done.status === null || !statuses.includes(done.status)) {
+        throw failure(verb, done);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(done.stdout);
+    }
+    catch {
+        throw failure(verb, done);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new FxError(`grida-fx ${verb} printed no JSON object`, {
+            exitCode: done.status,
+            stdout: done.stdout,
+            stderr: done.stderr,
+            args: done.args,
+        });
+    }
+    return parsed;
+}

package/dist/errors.d.ts

@@ -0,0 +1,33 @@
+/** Errors of `@grida/fx`. */
+/** What the engine left behind when it failed. */
+export interface FxErrorDetails {
+    /** The engine's exit status; `null` when it never started or ended by a signal. */
+    readonly exitCode?: number | null;
+    /** The signal that ended the engine, if one did. */
+    readonly signal?: string | null;
+    /** What the engine wrote on stderr. */
+    readonly stderr?: string;
+    /** What the engine wrote on stdout. */
+    readonly stdout?: string;
+    /** The arguments the engine was given (after the binary). */
+    readonly args?: readonly string[];
+    readonly cause?: unknown;
+}
+/**
+ * The engine stopped with an error (exit status 2: unreadable input or a usage mistake), would
+ * not run (`refused: …`), was interrupted (130), or could not be found or started. `message` is
+ * the engine's own message, without its `grida-fx: ` prefix.
+ */
+export declare class FxError extends Error {
+    /** The engine's exit status; `null` when it never started or ended by a signal. */
+    readonly exitCode: number | null;
+    /** The signal that ended the engine, if one did. */
+    readonly signal: string | null;
+    /** What the engine wrote on stderr. */
+    readonly stderr: string;
+    /** What the engine wrote on stdout. */
+    readonly stdout: string;
+    /** The arguments the engine was given (after the binary). */
+    readonly args: readonly string[];
+    constructor(message: string, details?: FxErrorDetails);
+}