@grida/fx 0.1.0-alpha.2 → 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

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,16 +22,22 @@ 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
-as `image.resize`): those projects also need `pip install --pre grida`, or `GRIDA_FX_PYTHON`
+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>;