VFX-E-1504¶

Title¶

RunOptionUnavailable

Explanation¶

run_suite accepts two options whose behaviour this server cannot deliver yet: wait: false (start the run and return immediately, polling its status afterwards) and keepEnvironment: true (leave the containers up after the run so you can poke at them). Both are accepted on the wire — they are part of the tool's declared input, not unknown fields — and both are refused with this code when you actually ask for them.

Being refused rather than quietly re-interpreted is the point. The alternative for wait: false would be to block anyway and return a finished run to a caller that asked for a handle; the alternative for keepEnvironment: true would be to tear the environment down after all, destroying the very thing you kept it up to inspect. Either would be a silent lie about what the call did, so the server says no instead.

What is blocking each. Async execution needs stable, engine-issued run identifiers and a detached run with its own status/cancel surface — upstream work item U4. keepEnvironment needs a corresponding flag on the engine CLI: measured against the pinned engine (vouchfx run --help, v1.0.0-rc.4), there is none, so there is nothing for this server to forward. This server deliberately will not implement a teardown policy of its own — the 30-minute auto-teardown described in the specification is the engine's behaviour, and a second, competing timer living here is exactly the kind of drift between the CLI and this server that the project forbids.

The default for both options is the behaviour that works: wait defaults to true and keepEnvironment to false. Omitting them entirely is the same as sending those defaults, and sending them explicitly with those values is accepted, not refused.

This error is not retryable. Nothing about the identical call changes between attempts — what unblocks these options is a new engine version and a new ENGINE_PIN, which is a different server, not a later retry.

Common causes¶

• wait: false was sent to start a run in the background and poll it afterwards.
• keepEnvironment: true was sent to leave containers running for debugging after the suite finished.
• A host built its arguments from the full specification's RunScenarioInput shape, which describes both options, without checking which of them this server implements today.
• An agent copied a call example from documentation describing the eventual, post-U4 behaviour.

Fixes¶

• Drop the option and call run_suite normally: it blocks until the run completes and returns the verdict, which is the only mode implemented today.
• Send wait: true (or omit it) — the blocking call already returns the runId, so nothing is lost except the ability to do other work while it runs.
• Send keepEnvironment: false (or omit it) and reproduce the environment separately when you need to inspect it — for example by running the same suite through the vouchfx CLI directly.
• Use the run's JSON Lines event stream (explain_run, diagnose_run) for post-mortem detail instead of a live environment; it carries the step timeline, observations, and environment errors the run produced.
• If your orchestration genuinely needs a non-blocking run, cap the call with timeoutSeconds and treat the tool call itself as the handle until upstream ask U4 lands.