@grida/fx 0.1.0 → 0.2.0

package/README.md

@@ -5,10 +5,10 @@ files and to plan, price and run them. Grida FX is a workflow engine for generat
 pipelines: write a workflow file, and FX plans it, prices it before anything is spent, caches
 every paid call by its request, and records the run. It works with your own provider keys.
 
-This is a **preview** (`0.x` pre-releases under the npm tag `next`).
+Stable releases start at `0.1.0` and use npm's default `latest` tag. Prereleases use `next`.
 
 ```sh
-npm install @grida/fx@next     # or: npm install -g @grida/fx@next
+npm install @grida/fx     # or: npm install -g @grida/fx
 npx grida-fx --help
 ```
 
@@ -22,15 +22,21 @@ your machine:
 | Linux on x64, glibc 2.28 or later | `@grida/fx-linux-x64-gnu` |
 | Linux on arm64, glibc 2.28 or later | `@grida/fx-linux-arm64-gnu` |
 
-**Windows is not in the preview**: the engine's runner uses Unix process groups and signals. Use
+**Native Windows is not supported yet**: the engine's runner uses Unix process groups and signals. Use
 WSL 2, which runs the Linux packages. Linux with musl (Alpine) is not supported either. Node 18 or
 later.
 
+FX is also the `fx` verb of the npm `grida` command: a `grida` release that pins this package
+runs its engine as `grida fx <verb>`. For that host this package exports
+its launcher as `@grida/fx/cli` (`launch`, `HOST_CONTRACT`); see
+[spec/distribution.md](https://github.com/gridaco/fx/blob/main/spec/distribution.md). The SDK
+stays `import … from "@grida/fx"`.
+
 `grida-fx` reports what is missing when it finds no engine. If you install with
 `--omit=optional`, or need a binary of your own, set `GRIDA_FX_BIN` to the path of a `grida-fx`
 binary: the command and the SDK use it first.
 
-Some steps run on Python in the preview (your own Python nodes, and the built-in local types such
+Some steps run on Python (your own Python nodes, and the built-in local types such
 as `image.resize`): those projects also need `pip install grida`, or `GRIDA_FX_PYTHON`
 pointing at a Python that has them. A project whose steps are all paid built-ins and `select`
 needs only this package. See [Getting started](https://github.com/gridaco/fx/blob/main/docs/guide/01-getting-started.md).
@@ -58,14 +64,43 @@ const icon = result.outputs.icon; // a RunFile: digest, kind, path, read()
   runs, and reads the run back: `ok`, `incomplete`, `chargedUsd`, `failed`, `outputs`, `steps`.
   A failed step does not reject.
 - `project(runDir)` and `inspect(runOrWorkflowId, { verify })`: a run's record and summary.
+- `loadRun(target, { verify })`: a `RunRecord` with a pinned absolute `runDir` and
+  engine `inspection`. Its `snapshot()`, `events({ after, limit })` and async
+  `follow({ after, pollIntervalMs, signal })` methods use the same public reader as
+  the CLI. Following yields nonempty bounded batches until broken or aborted,
+  including across resumes. It owns no execution process or exit code.
+- `inspectControl(run)` and `cancel(run, { invocation, wait, timeout })`: exact-target local
+  control, independent of viewer/service lifetime. Results keep their `lower_snake_case` wire
+  fields; structured failures raise `RunControlError` with `code` and `result`.
+- `listRuns({ workflow })`: the project's runs, newest first, each with its `folder`, a `runDir`
+  resolved against `cwd`, and `lower_snake_case` wire fields (`state`, `placement`,
+  `charged_usd`, …). `removeRuns(runs, { preview })`: removes exactly the runs given (filter
+  `listRuns` yourself); `preview: true` removes nothing. A refused or partial run is an entry's
+  `outcome`, not a rejection; a RUN that is not a run raises `RunRemovalError` with `code` and
+  `run`, before anything is removed.
 - `binary()` and `engineVersion()`: the engine in use.
 
 A target is a workflow file, a workflow id, or a builder `file.py:function`. Options:
 `inputs` (values), `inputFiles`, `routes`, `args` (a builder's arguments), `maxUsd`, `cwd`,
 `env` (for example `GRIDA_FX_PYTHON`) and `signal` (an `AbortSignal`); `run` also takes `live`,
-`yesUpTo`, `runDir` and `deliver`. Relative paths start at `cwd`. The engine's errors reject with
+`yesUpTo`, `deliver`, and one of `name` (create-only), `resume` (require-existing),
+or `runDir` (explicit-folder create/resume). Relative paths start at `cwd`. The engine's errors reject with
 `FxError`, which carries its `exitCode` and `stderr`.
 
+Aborting a `run` requests graceful cancellation once with SIGTERM and waits for engine cleanup
+before rejecting. There is no automatic runner force timer; stuck cleanup can keep the promise
+pending. Aborting only a control waiter ends that wait without retracting accepted cancellation.
+See [Stopping and continuing a run](../../docs/guide/08-run-control.md) for guarded requests,
+wait timeouts, local completion and unknown remote outcomes. These APIs describe current source;
+check your installed version for availability.
+
+Observation abort stops only its reader. Apply an entire batch before checkpointing
+its opaque cursor; `RunObservationError` keeps a reader's `code` and `document`.
+Inspection and a later snapshot are independent samples. See
+[Working with runs from an SDK](../../docs/guide/09-sdk-runs.md) for saved/named
+records and observing another process. SDK execution still suppresses viewer
+hosting and returns after completion.
+
 ## Writing workflows
 
 ```ts

package/dist/api.d.ts

@@ -90,6 +90,8 @@ export declare class RunResult {
     readonly inspection: Inspection;
     constructor(runDir: string, exit: Exit, projection: Projection, inspection: Inspection);
     private get finished();
+    /** The initialized invocation represented by this result's projection. */
+    get invocationId(): string | null;
     /** Whether every step that had to run succeeded and the run ended normally. */
     get ok(): boolean;
     /** Whether the run stopped before everything ran (running it again continues it). */

package/dist/api.js

@@ -165,6 +165,11 @@ export class RunResult {
     get finished() {
         return this.projection.run?.run_finished;
     }
+    /** The initialized invocation represented by this result's projection. */
+    get invocationId() {
+        const value = this.projection.run?.run_started?.invocation_id;
+        return typeof value === "string" ? value : null;
+    }
     /** Whether every step that had to run succeeded and the run ended normally. */
     get ok() {
         return this.finished?.ok === true;
@@ -234,7 +239,7 @@ export function decode(encoded, placed) {
     throw new FxError(`the run's record holds a value in no known form: ${JSON.stringify(encoded)}`);
 }
 /** The options `run` still takes with a {@link Plan}. */
-const RUN_ONLY = ["live", "yesUpTo", "runDir", "deliver", "signal"];
+const RUN_ONLY = ["live", "yesUpTo", "runDir", "name", "resume", "deliver", "signal"];
 /**
  * Runs `target`, or a plan, after planning it: a plan with problems rejects with
  * {@link PlanRefused} before any folder exists. `live: true` admits paid calls, within a
@@ -261,7 +266,7 @@ export async function run(target, options = {}) {
     if (!planned.ok) {
         throw new PlanRefused(planned);
     }
-    const done = await withInputsFile(request, (inputsFile) => call(["run", ...planningArgs(request, inputsFile), ...own], callOptions(request, signal)));
+    const done = await withInputsFile(request, (inputsFile) => call(["run", ...planningArgs(request, inputsFile), ...own, "--no-view"], callOptions(request, signal)));
     if (done.status === INTERRUPTED) {
         throw new FxError("the run was interrupted", {
             exitCode: done.status,

package/dist/cli.d.ts

@@ -1,7 +1,13 @@
 /**
- * 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.
+ * The command launcher: it finds the engine (`binary.ts`) and runs it with the given arguments,
+ * this process's standard streams and working directory, and ends as the engine ended: with its
+ * exit status, or by the same signal. `@grida/fx`'s own `grida-fx` command is {@link main}; a
+ * host command that carries FX as a verb of its own (the npm `grida` command's `grida fx`) calls
+ * {@link launch} through the `@grida/fx/cli` export (spec/distribution.md).
+ *
+ * The invoker. {@link launch} tells the engine which command started it (`GRIDA_FX_INVOKER`), so
+ * usage, the error prefix and the hints the engine prints name the command as its user types it:
+ * `grida-fx` or `grida fx`. This launcher's own messages use the same name.
  *
  * 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
@@ -12,13 +18,34 @@
  * input, so it does not need the terminal's foreground group.
  */
 import { type ChildProcess } from "node:child_process";
+/**
+ * The version of the contract between `@grida/fx/cli` and a host command: {@link launch}'s
+ * signature and behaviour, the invokers it accepts, and what the engine does with each. A host
+ * pins `@grida/fx` exactly and refuses a contract it was not written for.
+ */
+export declare const HOST_CONTRACT = 1;
+/** The environment variable that tells the engine which command started it. */
+export declare const INVOKER_VARIABLE = "GRIDA_FX_INVOKER";
+/** A command that launches the engine from JavaScript: `@grida/fx`'s `grida-fx`, or `grida`'s
+ * `grida fx`. (`python -m grida.fx` is the Python distribution's.) */
+export type Invoker = "grida-fx" | "grida";
+/** The command each invoker's user types, without the verb. */
+export declare const COMMANDS: Readonly<Record<Invoker, string>>;
+/** Options of {@link launch}. */
+export interface LaunchOptions {
+    /** The command that started the engine (default: `grida-fx`). */
+    readonly invoker?: Invoker;
+}
 /** 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. */
+/** `@grida/fx`'s `grida-fx` command: {@link launch} as the `grida-fx` invoker. */
 export declare function main(argv: readonly string[]): void;
+/** Runs the engine with `argv` (the arguments after the command's name, and after `fx` for
+ * `grida fx`) and ends this process as the engine ended. Throws a `TypeError`, before anything
+ * runs, for an invoker this contract does not know. */
+export declare function launch(argv: readonly string[], options?: LaunchOptions): void;
 /** Passes signals on to `child` (module comment); `remove` stops. */
 export declare function forwardSignals(child: ChildProcess, unix: boolean): {
     remove(): void;

package/dist/cli.js

@@ -1,7 +1,13 @@
 /**
- * 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.
+ * The command launcher: it finds the engine (`binary.ts`) and runs it with the given arguments,
+ * this process's standard streams and working directory, and ends as the engine ended: with its
+ * exit status, or by the same signal. `@grida/fx`'s own `grida-fx` command is {@link main}; a
+ * host command that carries FX as a verb of its own (the npm `grida` command's `grida fx`) calls
+ * {@link launch} through the `@grida/fx/cli` export (spec/distribution.md).
+ *
+ * The invoker. {@link launch} tells the engine which command started it (`GRIDA_FX_INVOKER`), so
+ * usage, the error prefix and the hints the engine prints name the command as its user types it:
+ * `grida-fx` or `grida fx`. This launcher's own messages use the same name.
  *
  * 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
@@ -14,29 +20,54 @@
 import { spawn } from "node:child_process";
 import { constants } from "node:os";
 import { binary } from "./binary.js";
+/**
+ * The version of the contract between `@grida/fx/cli` and a host command: {@link launch}'s
+ * signature and behaviour, the invokers it accepts, and what the engine does with each. A host
+ * pins `@grida/fx` exactly and refuses a contract it was not written for.
+ */
+export const HOST_CONTRACT = 1;
+/** The environment variable that tells the engine which command started it. */
+export const INVOKER_VARIABLE = "GRIDA_FX_INVOKER";
+/** The command each invoker's user types, without the verb. */
+export const COMMANDS = {
+    "grida-fx": "grida-fx",
+    grida: "grida fx",
+};
 /** 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. */
+/** `@grida/fx`'s `grida-fx` command: {@link launch} as the `grida-fx` invoker. */
 export function main(argv) {
+    launch(argv, { invoker: "grida-fx" });
+}
+/** Runs the engine with `argv` (the arguments after the command's name, and after `fx` for
+ * `grida fx`) and ends this process as the engine ended. Throws a `TypeError`, before anything
+ * runs, for an invoker this contract does not know. */
+export function launch(argv, options = {}) {
+    const invoker = options.invoker ?? "grida-fx";
+    if (!Object.hasOwn(COMMANDS, invoker)) {
+        throw new TypeError(`unknown invoker ${JSON.stringify(invoker)}: @grida/fx/cli contract ${HOST_CONTRACT} ` +
+            `knows ${Object.keys(COMMANDS).join(", ")}`);
+    }
+    const command = COMMANDS[invoker];
+    const env = { ...process.env, [INVOKER_VARIABLE]: invoker };
     let engine;
     try {
-        engine = binary();
+        engine = binary({ env });
     }
     catch (error) {
-        process.stderr.write(`grida-fx: ${error instanceof Error ? error.message : String(error)}\n`);
+        process.stderr.write(`${command}: ${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 child = spawn(engine, [...argv], { stdio: "inherit", detached: unix, env });
     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.stderr.write(`${command}: could not start the engine (${engine}): ${error.message}\n`);
         process.exit(FAILED);
     });
     child.once("exit", (status, signal) => {

package/dist/control.d.ts

@@ -0,0 +1,42 @@
+/** Exact-target run control through the engine's public command line (spec/control.md).
+ * The engine resolves and authenticates the owner and verifies cleanup. */
+import { type CallOptions, type Exit } from "./engine.js";
+import { FxError } from "./errors.js";
+/** The engine's fx-run-control-v1 response. Wire fields retain lower_snake_case names. */
+export interface RunControlResult {
+    readonly kind: "fx-run-control-v1";
+    readonly operation: "inspect" | "cancel";
+    readonly invocation_id: string | null;
+    readonly outcome: "inspected" | "accepted" | "already_requested" | "already_terminal" | "finishing" | "completed" | "error";
+    readonly request_status: "accepted" | "not_accepted" | "unknown";
+    readonly recorded_state: "planned" | "unfinished" | "succeeded" | "failed" | "cancelled" | "unknown";
+    readonly cleanup: "pending" | "complete" | "unknown";
+    readonly external_completion: "not_verified";
+    readonly code?: string;
+    readonly message?: string;
+    readonly availability?: "available" | "unavailable" | "unsupported" | "unknown";
+    readonly can_cancel?: boolean;
+}
+/** A structured control failure, retaining its stable code and complete result.
+ * Unsupported binaries and malformed responses reject with ordinary FxError. */
+export declare class RunControlError extends FxError {
+    readonly result: RunControlResult;
+    readonly code: string;
+    constructor(result: RunControlResult, done: Exit);
+}
+/** Options of cancel. Relative targets start at cwd, as on the command line. */
+export interface CancelOptions extends CallOptions {
+    /** Expected-current invocation guard. A successor is refused, never automatically selected. */
+    readonly invocation?: string;
+    /** Verify local completion, with a default timeout of thirty seconds. */
+    readonly wait?: boolean;
+    /** Positive integer followed by s, m or h (e.g. "5s"); requires wait: true. This bounds
+     * waiting only and never terminates the run or retracts an accepted cancellation. */
+    readonly timeout?: string;
+}
+/** Inspect one exact target's invocation and authenticated control availability. A bare
+ * workflow ID is refused by the engine; no latest-run selection is implied. */
+export declare function inspectControl(run: string, options?: CallOptions): Promise<RunControlResult>;
+/** Request cancellation of one invocation. Aborting this control client only ends its wait;
+ * an accepted cancellation remains effective in the separately owned runner. */
+export declare function cancel(run: string, options?: CancelOptions): Promise<RunControlResult>;

package/dist/control.js

@@ -0,0 +1,160 @@
+/** Exact-target run control through the engine's public command line (spec/control.md).
+ * The engine resolves and authenticates the owner and verifies cleanup. */
+import { call, failure } from "./engine.js";
+import { FxError } from "./errors.js";
+/** A structured control failure, retaining its stable code and complete result.
+ * Unsupported binaries and malformed responses reject with ordinary FxError. */
+export class RunControlError extends FxError {
+    result;
+    code;
+    constructor(result, done) {
+        super(result.message ?? `run control failed: ${result.code}`, {
+            exitCode: done.status,
+            signal: done.signal,
+            stdout: done.stdout,
+            stderr: done.stderr,
+            args: done.args,
+        });
+        this.name = "RunControlError";
+        this.result = result;
+        this.code = result.code ?? "";
+    }
+}
+const MAX_RESULT_BYTES = 16 * 1024;
+const REQUIRED = [
+    "kind", "operation", "invocation_id", "outcome", "request_status", "recorded_state",
+    "cleanup", "external_completion",
+];
+const OPTIONAL = ["code", "message", "availability", "can_cancel"];
+const ERROR_STATUS = {
+    unavailable: 1,
+    wait_timeout: 1,
+    owner_lost: 1,
+    acknowledgment_unknown: 1,
+    completion_unverified: 1,
+    invalid_target: 2,
+    ambiguous_target: 2,
+    invocation_mismatch: 2,
+    unsupported_version: 2,
+    unauthorized: 2,
+    record_error: 2,
+};
+const ENUMS = {
+    outcome: ["inspected", "accepted", "already_requested", "already_terminal", "finishing", "completed", "error"],
+    request_status: ["accepted", "not_accepted", "unknown"],
+    recorded_state: ["planned", "unfinished", "succeeded", "failed", "cancelled", "unknown"],
+    cleanup: ["pending", "complete", "unknown"],
+    external_completion: ["not_verified"],
+};
+function target(run) {
+    if (typeof run !== "string" || run === "" || run.startsWith("-") || run.includes("\0")) {
+        throw new TypeError("run is a nonempty explicit run folder or exact WORKFLOW_ID/NAME, without a leading '-' or NUL");
+    }
+    return run;
+}
+function cancelOptions(options) {
+    if (options.wait !== undefined && typeof options.wait !== "boolean") {
+        throw new TypeError("wait is true or false");
+    }
+    const args = ["--source=sdk"];
+    if (options.invocation !== undefined) {
+        if (typeof options.invocation !== "string" || options.invocation === "" || options.invocation.includes("\0")) {
+            throw new TypeError("invocation is a nonempty invocation ID");
+        }
+        args.push(`--invocation=${options.invocation}`);
+    }
+    if (options.wait === true) {
+        args.push("--wait");
+    }
+    if (options.timeout !== undefined) {
+        if (options.wait !== true) {
+            throw new TypeError("timeout requires wait: true");
+        }
+        if (typeof options.timeout !== "string" || !/^[0-9]+[smh]$/.test(options.timeout) || /^0+[smh]$/.test(options.timeout)) {
+            throw new TypeError("timeout is a positive integer followed by s, m or h");
+        }
+        args.push(`--timeout=${options.timeout}`);
+    }
+    return args;
+}
+function parseResult(done, operation, wait) {
+    if (Buffer.byteLength(done.stdout, "utf8") > MAX_RESULT_BYTES) {
+        throw new Error("oversized result");
+    }
+    const value = JSON.parse(done.stdout);
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("not an object");
+    }
+    const data = value;
+    if (!REQUIRED.every((name) => name in data)) {
+        throw new Error("missing fields");
+    }
+    for (const [name, field] of Object.entries(data)) {
+        if (![...REQUIRED, ...OPTIONAL].includes(name))
+            continue;
+        if (name === "can_cancel") {
+            if (typeof field !== "boolean")
+                throw new Error("can_cancel is not boolean");
+        }
+        else if (name !== "invocation_id" || field !== null) {
+            if (typeof field !== "string" || field === "" || field.length > (name === "invocation_id" ? 256 : 4096)) {
+                throw new Error(`invalid ${name}`);
+            }
+        }
+    }
+    if (data.kind !== "fx-run-control-v1" || data.operation !== operation) {
+        throw new Error("incompatible result");
+    }
+    if (Object.entries(ENUMS).some(([name, values]) => !values.includes(data[name]))) {
+        throw new Error("unknown result enum");
+    }
+    if (data.outcome === "completed" && (data.invocation_id === null || data.cleanup !== "complete"
+        || !["succeeded", "failed", "cancelled"].includes(data.recorded_state))) {
+        throw new Error("completion lacks invocation, cleanup or terminal evidence");
+    }
+    if (operation === "inspect") {
+        if (!["available", "unavailable", "unsupported", "unknown"].includes(data.availability) || typeof data.can_cancel !== "boolean") {
+            throw new Error("missing or unknown inspection fields");
+        }
+    }
+    else if ("availability" in data || "can_cancel" in data) {
+        throw new Error("inspection fields on cancellation");
+    }
+    if (data.outcome === "error") {
+        if (ERROR_STATUS[data.code] !== done.status || !("message" in data)) {
+            throw new Error("unknown code or mismatched error status");
+        }
+    }
+    else {
+        const allowed = operation === "inspect" ? ["inspected"] : wait ? ["completed"] : ["accepted", "already_requested", "already_terminal", "finishing"];
+        if (done.status !== 0 || !allowed.includes(data.outcome) || "code" in data || "message" in data) {
+            throw new Error("mismatched success outcome or status");
+        }
+    }
+    return data;
+}
+async function control(operation, run, options, args, wait = false) {
+    const verb = operation === "inspect" ? "inspect" : "cancel";
+    const done = await call([verb, target(run), ...args, "--json"], options);
+    let result;
+    try {
+        result = parseResult(done, operation, wait);
+    }
+    catch {
+        throw failure(verb, done);
+    }
+    if (result.outcome === "error") {
+        throw new RunControlError(result, done);
+    }
+    return result;
+}
+/** Inspect one exact target's invocation and authenticated control availability. A bare
+ * workflow ID is refused by the engine; no latest-run selection is implied. */
+export async function inspectControl(run, options = {}) {
+    return control("inspect", run, options, ["--control"]);
+}
+/** Request cancellation of one invocation. Aborting this control client only ends its wait;
+ * an accepted cancellation remains effective in the separately owned runner. */
+export async function cancel(run, options = {}) {
+    return control("cancel", run, options, cancelOptions(options), options.wait === true);
+}

package/dist/documents.d.ts

@@ -79,12 +79,16 @@ export interface Graph {
         };
     };
     instances: GraphInstance[];
-    /** Repeats whose instances a later phase expands, with their worst case. */
+    /** Repeats whose instances a later phase expands, with their worst case. `step` is the
+     * declared step's path and `waiting_on` what its list needs; both are absent in documents
+     * written before they existed. */
     pending: {
         path: string;
+        step?: string;
         max: number;
         phase: number;
         high_usd: number;
+        waiting_on?: string[];
     }[];
     estimate: PriceRange & {
         ceiling_usd: number | null;

package/dist/engine.d.ts

@@ -4,7 +4,8 @@
  * 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.
+ * code: a run gets one idempotent SIGTERM and retains ownership until engine cleanup ends, without
+ * an automatic force deadline. Other commands retain their ten-second SIGKILL fallback.
  *
  * 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.
@@ -18,8 +19,8 @@ export interface CallOptions {
     /** 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. */
+    /** Interrupts the engine once. A run waits for engine cleanup before rejecting with the
+     * signal's reason; other commands retain a ten-second force fallback. */
     readonly signal?: AbortSignal;
 }
 /** How a call ended. */

package/dist/engine.js

@@ -4,7 +4,8 @@
  * 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.
+ * code: a run gets one idempotent SIGTERM and retains ownership until engine cleanup ends, without
+ * an automatic force deadline. Other commands retain their ten-second SIGKILL fallback.
  *
  * 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.
@@ -16,16 +17,22 @@ import { FxError } from "./errors.js";
 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. */
+/** The stop grace for non-run commands. Run cleanup has no automatic force deadline. */
 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. */
+/** How the engine prefixes an error on stderr: the SDK always runs it as the `grida-fx` invoker
+ * (spec/distribution.md §2), whichever command started this process. */
 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);
+    // A value inherited from a launcher (a node body run under `grida fx`) would change the prefix.
+    env.GRIDA_FX_INVOKER = "grida-fx";
+    if (args[0] === "run") {
+        env.GRIDA_FX_CANCEL_SOURCE = "sdk";
+    }
     const engine = findEngine(machineLookup(env, cwd));
     options.signal?.throwIfAborted();
     return new Promise((resolvePromise, reject) => {
@@ -39,13 +46,21 @@ export async function call(args, options = {}) {
         child.stdout.on("data", (chunk) => stdout.push(chunk));
         child.stderr.on("data", (chunk) => stderr.push(chunk));
         let killTimer;
+        let interrupted = false;
         const onAbort = () => {
-            if (child.exitCode === null && child.signalCode === null) {
-                child.kill("SIGINT");
-                killTimer = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+            if (!interrupted && child.exitCode === null && child.signalCode === null) {
+                interrupted = true;
+                child.kill(args[0] === "run" ? "SIGTERM" : "SIGINT");
+                if (args[0] !== "run") {
+                    killTimer = setTimeout(() => child.kill("SIGKILL"), STOP_GRACE_MS);
+                }
             }
         };
         options.signal?.addEventListener("abort", onAbort, { once: true });
+        // An abort between the initial check and listener registration must still stop this child.
+        if (options.signal?.aborted) {
+            onAbort();
+        }
         const finish = () => {
             options.signal?.removeEventListener("abort", onAbort);
             if (killTimer !== undefined) {

package/dist/index.d.ts

@@ -3,9 +3,12 @@
  * the engine package for the machine); this package drives it: plan, price and run workflows,
  * read their runs, and write workflow documents.
  */
-export declare const version = "0.1.0";
+export declare const version = "0.2.0";
 export { engineVersion, expand, identity, type InspectOptions, inspect, Plan, PlanRefused, plan, price, project, RunFile, RunResult, type RunValue, run, } from "./api.js";
 export { BINARY_VARIABLE, type BinaryOptions, binary, type Environment } from "./binary.js";
+export { cancel, type CancelOptions, inspectControl, RunControlError, type RunControlResult } from "./control.js";
+export { loadRun, type ObservedRunEvent, type RunEventBatch, type RunEventsOptions, type RunFollowOptions, RunObservationError, type RunObservationFailure, type RunReadOptions, RunRecord, type RunSnapshot, RunExportError, type RunExportFailure, type RunExportOptions, type RunExportResult, } from "./record.js";
+export { listRuns, type ListRunsOptions, type RemoveRunsOptions, removeRuns, type RunEntry, type RunPlacement, type RunRemoval, type RunRemovalEntry, RunRemovalError, type RunRemovalFailure, type RunRemovalSkip, type RunState, } from "./runs.js";
 export type { Encoded, FileRef, Graph, GraphInstance, Identities, InspectedStep, Inspection, Price, PricePhase, PriceRange, Problem, ProjectedInstance, Projection, RunEvent, RunFinished, WithValue, } from "./documents.js";
 export type { CallOptions } from "./engine.js";
 export { FxError, type FxErrorDetails } from "./errors.js";

package/dist/index.js

@@ -3,9 +3,12 @@
  * the engine package for the machine); this package drives it: plan, price and run workflows,
  * read their runs, and write workflow documents.
  */
-export const version = "0.1.0";
+export const version = "0.2.0";
 export { engineVersion, expand, identity, inspect, Plan, PlanRefused, plan, price, project, RunFile, RunResult, run, } from "./api.js";
 export { BINARY_VARIABLE, binary } from "./binary.js";
+export { cancel, inspectControl, RunControlError } from "./control.js";
+export { loadRun, RunObservationError, RunRecord, RunExportError, } from "./record.js";
+export { listRuns, removeRuns, RunRemovalError, } from "./runs.js";
 export { FxError } from "./errors.js";
 export { platformFor, platforms } from "./platforms.js";
 export { expr, workflow, } from "./workflow.js";