mandala-computer-mcp 0.1.1 → 0.3.0

package/dist/cli.js

@@ -20,8 +20,10 @@ Environment
   MANDALA_MODEL_KEY    an Anthropic key; enables the run_agent tool. stdio only
                        — over HTTP each caller sends their own X-Model-Key, and
                        this is ignored rather than spent on their runs
-  MANDALA_NO_LIFECYCLE set to 1 to withhold create_computer, clone_computer,
-                       clone_snapshot, delete_computer and delete_snapshot
+  MANDALA_NO_LIFECYCLE 1, true, yes or on to withhold create_computer,
+                       clone_computer, clone_snapshot, delete_computer and
+                       delete_snapshot. Any other value is refused rather than
+                       read as off, since a typo here would leave them enabled
   PORT, HOST           for --http (default 3000, 127.0.0.1)
   MANDALA_ALLOWED_HOSTS, MANDALA_ALLOWED_ORIGINS
                        comma-separated; which Host and Origin values to answer
@@ -39,6 +41,18 @@ Flags override the environment.`;
  * present, and anything following it is the next argument, not its value.
  */
 const BOOLEAN = new Set(['help', 'h', 'version', 'v', 'http', 'no-lifecycle']);
+/**
+ * The yes-or-no flags whose VALUE is checked against a vocabulary.
+ *
+ * Not all of them, because the argument for refusing an unrecognised spelling
+ * does not reach the other four. `--http` and `--no-lifecycle` decide what the
+ * server exposes, so reading a misspelled no as a yes arms something — a
+ * listener nobody asked for, or the withholding of tools somebody wanted.
+ * `--help` and `--version` print and exit: nothing is armed either way, and
+ * refusing `--help=` would turn the one flag people reach for when they are
+ * already confused into another error. They keep the older, looser reading.
+ */
+const CHECKED = new Set(['http', 'no-lifecycle']);
 const KNOWN = new Set([
     ...BOOLEAN,
     'port',
@@ -51,6 +65,61 @@ const KNOWN = new Set([
 ]);
 /** What `--http=…` may say to mean no. */
 const FALSEY = new Set(['false', '0', 'no', 'off']);
+/** And its mirror, for the environment variables that are a yes-or-no. */
+const TRUTHY = new Set(['true', '1', 'yes', 'on']);
+/**
+ * The value of a yes-or-no FLAG, refusing a spelling it does not know.
+ *
+ * The same vocabulary and the same refusal as {@link envFlag} below, because
+ * `--no-lifecycle=…` and `MANDALA_NO_LIFECYCLE=…` are two spellings of one
+ * control and it would be a poor joke for them to disagree about what `yes`
+ * means. Only the wording of the message differs, since one names a flag and
+ * the other a variable.
+ */
+function boolFlag(name, inline) {
+    const v = inline.trim().toLowerCase();
+    if (TRUTHY.has(v))
+        return true;
+    if (FALSEY.has(v))
+        return false;
+    throw new Error(`--${name}=${inline} is not a yes or a no. Use one of ${[...TRUTHY].join(', ')} to turn it ` +
+        `on — as does --${name} with no value at all — or one of ${[...FALSEY].join(', ')} to ` +
+        'turn it off.');
+}
+/**
+ * A yes-or-no environment variable, refusing a spelling it does not know.
+ *
+ * REFUSED rather than read as no, which is the decision worth recording.
+ * `MANDALA_NO_LIFECYCLE` withholds the tools that create and delete computers,
+ * so it is a safety control, and the two wrong answers do not cost the same: an
+ * unrecognised value read as "no" leaves those tools registered on a server
+ * whose operator believes they are gone, and says nothing. A typo is far more
+ * likely than a deliberate `MANDALA_NO_LIFECYCLE=ture`, and the loud version
+ * costs one clear line at startup.
+ *
+ * Empty is unset, as everywhere else here — the ordinary shape of an unquoted
+ * assignment in a compose file, and `env` has already turned it into undefined.
+ */
+function envFlag(name, raw) {
+    if (raw === undefined)
+        return false;
+    const v = raw.trim().toLowerCase();
+    // Here as well as in `env`, rather than only there. `env` folds an empty
+    // variable to undefined before this sees it, but that is the caller's
+    // behaviour and this reads as a general helper — `lifecycleEnabled` takes its
+    // value as a parameter, so a caller passing `process.env.X` straight in would
+    // otherwise refuse to start over `X=`, which is what an unquoted assignment
+    // in a compose file writes and what plugin.json's `${MANDALA_NO_LIFECYCLE:-}`
+    // expands to when it is unset.
+    if (!v)
+        return false;
+    if (TRUTHY.has(v))
+        return true;
+    if (FALSEY.has(v))
+        return false;
+    throw new Error(`${name}=${raw} is not a yes or a no. Use one of ${[...TRUTHY].join(', ')} to turn it on, ` +
+        `or one of ${[...FALSEY].join(', ')} (or leave it unset) to turn it off.`);
+}
 /**
  * argv into flags.
  *
@@ -89,11 +158,43 @@ export function parse(argv) {
         // `--http=false` has to mean false. It is the one spelling that carries an
         // explicit answer, and reading it as the truthy string "false" would turn
         // the clearest way to say no into a yes.
-        if (BOOLEAN.has(name))
-            flags[name] = inline === undefined ? true : !FALSEY.has(inline.toLowerCase());
+        //
+        // Matched against BOTH vocabularies rather than "anything that is not a no
+        // is a yes", which is what this was and which made a misspelling of a NO
+        // into a YES. `--http=ture` started a network listener the operator was
+        // trying not to start, and `--no-lifecycle=fasle` withheld the tools that
+        // make and destroy computers from someone who meant to keep them. The
+        // second fails safe and the first does not, so the loose reading had to go
+        // (OPL-4515).
+        //
+        // Refused rather than defaulted, which is the same call `envFlag` makes one
+        // screen up for the environment half of the same controls, and the message
+        // is deliberately its twin. An empty `--http=` is refused too: it is
+        // neither a yes nor a no, and `--port=` is already refused for being
+        // neither a number nor absent. Refusing is also the only answer to `--http=`
+        // that neither arms nor disarms — reading it as "off" would let a launcher
+        // template whose variable failed to expand quietly turn a safety control
+        // off, which is the failure this whole change is about.
+        //
+        // Only the flags in CHECKED: `--help` and `--version` arm nothing, so the
+        // argument does not reach them and they keep the looser reading.
+        if (BOOLEAN.has(name)) {
+            flags[name] =
+                inline === undefined
+                    ? true
+                    : CHECKED.has(name)
+                        ? boolFlag(name, inline)
+                        : !FALSEY.has(inline.trim().toLowerCase());
+        }
         else if (inline !== undefined)
             flags[name] = inline;
-        else if (argv[i + 1] && !argv[i + 1].startsWith('--'))
+        // PRESENT, not truthy. `--key ""` is a value token like any other, and a
+        // truthiness test skipped it: the flag became the boolean `true` and the
+        // empty token came round again as a stray argument, so the two spellings of
+        // one flag disagreed — `--key=` is the empty value `str()` documents, while
+        // `--key ""` died with `unexpected argument .`, naming nothing the user
+        // could act on.
+        else if (argv[i + 1] !== undefined && !argv[i + 1].startsWith('--'))
             flags[name] = argv[++i];
         else
             flags[name] = true;
@@ -115,9 +216,13 @@ export const wantsVersion = (flags) => Boolean(flags.version || flags.v);
 export function lifecycleEnabled(flags, configured = env('MANDALA_NO_LIFECYCLE')) {
     // Presence is what establishes precedence. `--no-lifecycle=false` carries a
     // false value deliberately and must not fall through to a true environment.
-    const disabled = Object.hasOwn(flags, 'no-lifecycle')
-        ? Boolean(flags['no-lifecycle'])
-        : configured === '1';
+    // Validated before precedence is applied, and that ordering is the point. A
+    // misspelling is a mistake to report whether or not a flag happens to sit in
+    // front of it: an operator who set MANDALA_NO_LIFECYCLE=ture meaning to
+    // withhold the tools, under a launcher that also passes --no-lifecycle=false,
+    // would otherwise get exactly the silent arming this refusal exists to stop.
+    const fromEnv = envFlag('MANDALA_NO_LIFECYCLE', configured);
+    const disabled = Object.hasOwn(flags, 'no-lifecycle') ? Boolean(flags['no-lifecycle']) : fromEnv;
     return !disabled;
 }
 /**

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -19,6 +19,8 @@ export declare class MandalaError extends Error {
 export declare class APIError extends MandalaError {
     readonly status: number;
     readonly body?: unknown | undefined;
+    /** Parsed Retry-After delay in milliseconds; absent when missing or invalid. */
+    readonly retryAfterMs?: number | undefined;
     name: string;
     /**
      * The platform's own word for what KIND of refusal this is, where it sent
@@ -33,8 +35,42 @@ export declare class APIError extends MandalaError {
      * the caller who arrived a moment earlier heard.
      */
     readonly reason?: string;
-    constructor(message: string, status: number, body?: unknown | undefined);
+    constructor(message: string, status: number, body?: unknown | undefined, 
+    /** Parsed Retry-After delay in milliseconds; absent when missing or invalid. */
+    retryAfterMs?: number | undefined);
 }
+/** Whether waiting can change a classified refusal's answer. */
+export type ReasonKind = 'clears' | 'permanent';
+/**
+ * How a refusal the platform classified behaves, or `undefined` for a word this
+ * version has no opinion about.
+ *
+ * The EXPORTED half of the two the sets above feed, and the split is
+ * deliberate. {@link reasonAdvice} beside it is this server's prose for a
+ * language model, tuned to how a model reads an MCP tool result and rewritten
+ * whenever one reads it wrong; publishing those sentences would make their
+ * wording something this package versions. What an embedder needs from here is
+ * narrower and does not move: whether waiting can change the answer.
+ *
+ * The raw word stays theirs. `APIError.reason` is public, the platform's set is
+ * documented and deliberately open, and switching on it is the supported path —
+ * this only offers the classification of the words this version knows, so an
+ * embedder need not duplicate a table that lives here. A word it has never
+ * heard of is `undefined` rather than a guess, which is the same contract
+ * `reasonAdvice` keeps and the reason "absent means unclassified" exists.
+ *
+ * NOT A RETRY PREDICATE. It classifies the WORD, and an error is more than its
+ * word: {@link isTransient} answers `MoveRequiredError` and
+ * {@link ConnectivityInterruptedError} before it ever looks at `reason`, because
+ * both are subclasses of branches that would otherwise say yes (OPL-3775,
+ * OPL-3855). A move-required 409 whose body also carries `reason: 'contention'`
+ * classifies here as `'clears'` while `isTransient` correctly says no — it is a
+ * decision about the size that was asked for, and it answers the same forever.
+ * So `if (reasonKind(err.reason) !== 'permanent') retry()` is the loop this
+ * sentence exists to prevent; ask {@link isTransient} whether to retry, and ask
+ * this what the platform's word meant.
+ */
+export declare function reasonKind(reason: string | undefined): ReasonKind | undefined;
 /**
  * What to tell a model about a refusal the platform classified, or `undefined`.
  *
@@ -121,7 +157,7 @@ export declare class MoveRequiredError extends ConflictError {
     name: string;
     constructor(message: string, status: number, body: unknown, 
     /** Whether a host in this region could run the size that was asked for. */
-    movePossible: boolean);
+    movePossible: boolean, retryAfterMs?: number);
 }
 /**
  * 416 — the `Range` named no byte the file has.
@@ -141,7 +177,7 @@ export declare class RangeNotSatisfiableError extends APIError {
     name: string;
     constructor(message: string, status: number, body?: unknown, 
     /** The file's real length, off `Content-Range`, when the response sent one. */
-    size?: number | undefined);
+    size?: number | undefined, retryAfterMs?: number);
 }
 /**
  * 429 — the request is valid; the caller has spent a temporary rate budget.
@@ -157,12 +193,10 @@ export declare class RangeNotSatisfiableError extends APIError {
  * how a rate limit becomes a longer one.
  */
 export declare class RateLimitError extends APIError {
-    /** From `Retry-After`, in milliseconds from now, when the response sent one. */
-    readonly retryAfterMs?: number | undefined;
     name: string;
     constructor(message: string, status: number, body?: unknown, 
     /** From `Retry-After`, in milliseconds from now, when the response sent one. */
-    retryAfterMs?: number | undefined);
+    retryAfterMs?: number);
 }
 /** 503 — a hypervisor could not be reached, so an inventory would be short. */
 export declare class UnavailableError extends APIError {
@@ -310,6 +344,27 @@ export declare class GatewayTimeoutError extends APIError {
 export declare class OriginUnreachableError extends APIError {
     name: string;
 }
+/**
+ * A 3xx, which this client answers rather than follows.
+ *
+ * Following one is the tempting default and it is wrong twice over. The bearer
+ * is the smaller half: `fetch` strips `Authorization` across origins but keeps
+ * it on a same-origin hop, so a redirect inside the configured origin carries
+ * the key to a path the operator did not name. The larger half is that a
+ * redirect is a CONFIGURATION fact — a `MANDALA_BASE_URL` missing its trailing
+ * path, an http URL for an https deployment, a tenant that has moved — and
+ * following it silently means the operator never learns the value they set is
+ * not the value in use, while every request pays an extra round trip forever.
+ *
+ * So it is surfaced, and it names the `Location`: the whole point is that the
+ * next thing the operator does is put that in `MANDALA_BASE_URL`. It is an
+ * `APIError` with the real status so {@link isTransientForPoll}'s `>= 500` rule
+ * files it with the 4xx, where it belongs — repeating the request unchanged
+ * cannot change the answer.
+ */
+export declare class RedirectError extends APIError {
+    name: string;
+}
 /**
  * 502, 520 — a proxy had no usable answer from the platform.
  *
@@ -386,7 +441,7 @@ export declare class OriginTLSError extends APIError {
  */
 export declare function platformSaid(body: unknown): string | undefined;
 /** Build the error for a status, with the platform's own message when it sent one. */
-export declare function errorForStatus(status: number, message: string, body?: unknown): APIError;
+export declare function errorForStatus(status: number, message: string, body?: unknown, retryAfterMs?: number): APIError;
 /**
  * Whether an error is worth trying again without changing the request.
  *
@@ -537,6 +592,13 @@ export declare function isTransient(err: unknown): boolean;
  *   SDK found that one; this is the same rule, and it is why all three now say
  *   `>= 500`.
  *
+ *   "Does not follow redirects" is a claim about `#fetch`'s `redirect: 'manual'`
+ *   and is load-bearing HERE, in a way it was not while the default `'follow'`
+ *   silently made it untrue: under `'follow'` a 3xx never reaches this predicate
+ *   at all, so the paragraph above described a case that could not arise and the
+ *   `>= 500` bound rested on nothing. {@link RedirectError} is what a 3xx
+ *   becomes now. Change one and this paragraph is wrong again.
+ *
  * {@link APIError.reason} is deliberately NOT consulted here, and that is the
  * one place this predicate and {@link isTransient} part company (OPL-3898).
  * `unavailable` means the computer is not running, which is a permanent answer
@@ -544,8 +606,11 @@ export declare function isTransient(err: unknown): boolean;
  * may not be, since a computer coming up passes through it. The same generosity
  * as every unmapped 5xx below, for the same reason: this only ever replays a
  * read, and the loops above return a refusal of their own the moment the status
- * they are watching says stopped or suspended. mandala-computer-python's
- * `_is_transient_for_poll` draws the line in the same place.
+ * they are watching says stopped or suspended AND the platform says it is
+ * holding nothing for the machine — the qualification OPL-4631 added, because
+ * a start that has been admitted reads as stopped or suspended until its guest
+ * process exists. mandala-computer-python's `_is_transient_for_poll` draws the
+ * line in the same place.
  *
  * Everything at 5xx polls through, 502 and 520-523 included: they mean the
  * outcome is unknown, and a read whose outcome is unknown can simply be read

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,qBAAa,YAAa,SAAQ,KAAK;IAC5B,IAAI,SAAkB;CAChC;AAED,qBAAa,QAAS,SAAQ,YAAY;IAiBtC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO;IACvB,gFAAgF;IAChF,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM;IAnBvB,IAAI,SAAc;IAC3B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEvB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,YAAA;IACvB,gFAAgF;IACvE,YAAY,CAAC,EAAE,MAAM,YAAA;CAKjC;AAiBD,gEAAgE;AAChE,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEhD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAK7E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAoB3E;AAkBD,uDAAuD;AACvD,qBAAa,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,SAAyB;CACvC;AAED,iEAAiE;AACjE,qBAAa,cAAe,SAAQ,QAAQ;IACjC,IAAI,SAAoB;CAClC;AAED,qEAAqE;AACrE,qBAAa,qBAAsB,SAAQ,QAAQ;IACxC,IAAI,SAA2B;CACzC;AAED,kDAAkD;AAClD,qBAAa,aAAc,SAAQ,QAAQ;IAChC,IAAI,SAAmB;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IAChC,IAAI,SAAmB;CACjC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAMhD,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,OAAO;IANvB,IAAI,SAAuB;gBAElC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;IACb,2EAA2E;IAClE,YAAY,EAAE,OAAO,EAC9B,YAAY,CAAC,EAAE,MAAM;CAIxB;AAoBD;;;;;;;;;;;GAWG;AACH,qBAAa,wBAAyB,SAAQ,QAAQ;IAMlD,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM;IANf,IAAI,SAA8B;gBAEzC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO;IACd,+EAA+E;IACtE,IAAI,CAAC,EAAE,MAAM,YAAA,EACtB,YAAY,CAAC,EAAE,MAAM;CAIxB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IACjC,IAAI,SAAoB;gBAG/B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO;IACd,gFAAgF;IAChF,YAAY,CAAC,EAAE,MAAM;CAIxB;AAED,+EAA+E;AAC/E,qBAAa,gBAAiB,SAAQ,QAAQ;IACnC,IAAI,SAAsB;CACpC;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,cAAe,SAAQ,YAAY;IACrC,IAAI,SAAoB;CAClC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,iBAAkB,SAAQ,YAAY;IACxC,IAAI,SAAuB;CACrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,4BAA6B,SAAQ,iBAAiB;IACxD,IAAI,SAAkC;CAChD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,SAAyB;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,sBAAuB,SAAQ,QAAQ;IACzC,IAAI,SAA4B;CAC1C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,aAAc,SAAQ,QAAQ;IAChC,IAAI,SAAmB;CACjC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,mBAAoB,SAAQ,QAAQ;IACtC,IAAI,SAAyB;CACvC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,cAAe,SAAQ,QAAQ;IACjC,IAAI,SAAoB;CAClC;AAwKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAI9D;AAED,sFAAsF;AACtF,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE,OAAO,EACd,YAAY,CAAC,EAAE,MAAM,GACpB,QAAQ,CA2CV;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAuCjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAUxD"}

package/dist/errors.js

@@ -19,6 +19,7 @@ export class MandalaError extends Error {
 export class APIError extends MandalaError {
     status;
     body;
+    retryAfterMs;
     name = 'APIError';
     /**
      * The platform's own word for what KIND of refusal this is, where it sent
@@ -33,10 +34,13 @@ export class APIError extends MandalaError {
      * the caller who arrived a moment earlier heard.
      */
     reason;
-    constructor(message, status, body) {
+    constructor(message, status, body, 
+    /** Parsed Retry-After delay in milliseconds; absent when missing or invalid. */
+    retryAfterMs) {
         super(message);
         this.status = status;
         this.body = body;
+        this.retryAfterMs = retryAfterMs;
         this.reason = refusalReason(body);
     }
 }
@@ -54,6 +58,44 @@ export class APIError extends MandalaError {
  */
 const REASON_CLEARS = new Set(['contention', 'starting']);
 const REASON_PERMANENT = new Set(['unavailable', 'unsupported']);
+/**
+ * How a refusal the platform classified behaves, or `undefined` for a word this
+ * version has no opinion about.
+ *
+ * The EXPORTED half of the two the sets above feed, and the split is
+ * deliberate. {@link reasonAdvice} beside it is this server's prose for a
+ * language model, tuned to how a model reads an MCP tool result and rewritten
+ * whenever one reads it wrong; publishing those sentences would make their
+ * wording something this package versions. What an embedder needs from here is
+ * narrower and does not move: whether waiting can change the answer.
+ *
+ * The raw word stays theirs. `APIError.reason` is public, the platform's set is
+ * documented and deliberately open, and switching on it is the supported path —
+ * this only offers the classification of the words this version knows, so an
+ * embedder need not duplicate a table that lives here. A word it has never
+ * heard of is `undefined` rather than a guess, which is the same contract
+ * `reasonAdvice` keeps and the reason "absent means unclassified" exists.
+ *
+ * NOT A RETRY PREDICATE. It classifies the WORD, and an error is more than its
+ * word: {@link isTransient} answers `MoveRequiredError` and
+ * {@link ConnectivityInterruptedError} before it ever looks at `reason`, because
+ * both are subclasses of branches that would otherwise say yes (OPL-3775,
+ * OPL-3855). A move-required 409 whose body also carries `reason: 'contention'`
+ * classifies here as `'clears'` while `isTransient` correctly says no — it is a
+ * decision about the size that was asked for, and it answers the same forever.
+ * So `if (reasonKind(err.reason) !== 'permanent') retry()` is the loop this
+ * sentence exists to prevent; ask {@link isTransient} whether to retry, and ask
+ * this what the platform's word meant.
+ */
+export function reasonKind(reason) {
+    if (reason === undefined)
+        return undefined;
+    if (REASON_CLEARS.has(reason))
+        return 'clears';
+    if (REASON_PERMANENT.has(reason))
+        return 'permanent';
+    return undefined;
+}
 /**
  * What to tell a model about a refusal the platform classified, or `undefined`.
  *
@@ -74,7 +116,14 @@ export function reasonAdvice(reason) {
         case 'starting':
             return 'the guest agent is still inside its boot window, so this is worth sending again in a moment';
         case 'unavailable':
-            return 'the computer is not running, and this does NOT clear by waiting — start_computer is the fix, and retrying without it spends a turn every time';
+            // Softened from "does NOT clear by waiting", which was false of exactly
+            // the case OPL-4631 is about and is the sentence a model actually sees:
+            // the platform raises this whenever no guest process is up, so a start
+            // that has been admitted but has not launched yet lands here too, and
+            // telling that caller to start_computer is telling them to start it
+            // twice. This refusal cannot see the reservation — it is a
+            // reason code, not a computer — so it names the call that CAN.
+            return 'the computer is not running; if nothing is starting it this will not clear on its own and start_computer is the fix, and if a start is already under way wait_for_computer says so without starting a second one';
         case 'unsupported':
             return 'this computer cannot do it at all, so do not retry it — the answer is the same forever';
         default:
@@ -168,8 +217,8 @@ export class MoveRequiredError extends ConflictError {
     name = 'MoveRequiredError';
     constructor(message, status, body, 
     /** Whether a host in this region could run the size that was asked for. */
-    movePossible) {
-        super(message, status, body);
+    movePossible, retryAfterMs) {
+        super(message, status, body, retryAfterMs);
         this.movePossible = movePossible;
     }
 }
@@ -210,8 +259,8 @@ export class RangeNotSatisfiableError extends APIError {
     name = 'RangeNotSatisfiableError';
     constructor(message, status, body, 
     /** The file's real length, off `Content-Range`, when the response sent one. */
-    size) {
-        super(message, status, body);
+    size, retryAfterMs) {
+        super(message, status, body, retryAfterMs);
         this.size = size;
     }
 }
@@ -229,13 +278,12 @@ export class RangeNotSatisfiableError extends APIError {
  * how a rate limit becomes a longer one.
  */
 export class RateLimitError extends APIError {
-    retryAfterMs;
     name = 'RateLimitError';
+    // biome-ignore lint/complexity/noUselessConstructor: Preserve the documented public constructor.
     constructor(message, status, body, 
     /** From `Retry-After`, in milliseconds from now, when the response sent one. */
     retryAfterMs) {
-        super(message, status, body);
-        this.retryAfterMs = retryAfterMs;
+        super(message, status, body, retryAfterMs);
     }
 }
 /** 503 — a hypervisor could not be reached, so an inventory would be short. */
@@ -384,6 +432,27 @@ export class GatewayTimeoutError extends APIError {
 export class OriginUnreachableError extends APIError {
     name = 'OriginUnreachableError';
 }
+/**
+ * A 3xx, which this client answers rather than follows.
+ *
+ * Following one is the tempting default and it is wrong twice over. The bearer
+ * is the smaller half: `fetch` strips `Authorization` across origins but keeps
+ * it on a same-origin hop, so a redirect inside the configured origin carries
+ * the key to a path the operator did not name. The larger half is that a
+ * redirect is a CONFIGURATION fact — a `MANDALA_BASE_URL` missing its trailing
+ * path, an http URL for an https deployment, a tenant that has moved — and
+ * following it silently means the operator never learns the value they set is
+ * not the value in use, while every request pays an extra round trip forever.
+ *
+ * So it is surfaced, and it names the `Location`: the whole point is that the
+ * next thing the operator does is put that in `MANDALA_BASE_URL`. It is an
+ * `APIError` with the real status so {@link isTransientForPoll}'s `>= 500` rule
+ * files it with the 4xx, where it belongs — repeating the request unchanged
+ * cannot change the answer.
+ */
+export class RedirectError extends APIError {
+    name = 'RedirectError';
+}
 /**
  * 502, 520 — a proxy had no usable answer from the platform.
  *
@@ -452,11 +521,8 @@ const BY_STATUS = {
     // arriving from anywhere else is still the right class with the platform's
     // own message on it.
     416: RangeNotSatisfiableError,
-    // Reached through errorForStatus only when the response headers were not in
-    // hand — Api.#error builds this one itself, for RangeNotSatisfiableError's
-    // reason: `Retry-After` is on the headers and the number is worth keeping.
-    // The entry is here so a 429 arriving from anywhere else is still the right
-    // class, which is what {@link isTransient} now asks about.
+    // Retry-After is parsed by Api and passed through errorForStatus.
+    // A 429 built without headers still has the same public error class.
     429: RateLimitError,
     // The other status a proxy writes on its own, and it was the one gap left in
     // this range: with no entry it fell through to a bare APIError, so a model
@@ -615,7 +681,7 @@ export function platformSaid(body) {
     return typeof err === 'string' && err.length > 0 ? err : undefined;
 }
 /** Build the error for a status, with the platform's own message when it sent one. */
-export function errorForStatus(status, message, body) {
+export function errorForStatus(status, message, body, retryAfterMs) {
     const Cls = BY_STATUS[status] ?? APIError;
     // The 409 that is an offer, told apart by its body. Before the substitutions
     // below because it never wants one: the platform's sentence here is the whole
@@ -624,7 +690,10 @@ export function errorForStatus(status, message, body) {
     if (Cls === ConflictError) {
         const offer = moveOffer(body);
         if (offer)
-            return new MoveRequiredError(message, status, body, offer.possible);
+            return new MoveRequiredError(message, status, body, offer.possible, retryAfterMs);
+    }
+    if (Cls === RangeNotSatisfiableError) {
+        return new RangeNotSatisfiableError(message, status, body, undefined, retryAfterMs);
     }
     // Substituted for an empty body, which says nothing, and for a proxy's HTML
     // page, which says 500 characters of nothing. NOT for a structured message:
@@ -641,21 +710,21 @@ export function errorForStatus(status, message, body) {
     // that deployment than the generic outage prose here does, and discarding it
     // was the very thing the 504 and 520 guards exist to prevent.
     if (Cls === GatewayTimeoutError && !platformNamed(body)) {
-        return new GatewayTimeoutError(gatewayTimeoutMessage(status), status, body);
+        return new GatewayTimeoutError(gatewayTimeoutMessage(status), status, body, retryAfterMs);
     }
     if (Cls === OriginResponseError && !platformNamed(body)) {
         // 502 and 520 share a class and not a message: one knows the request
         // arrived, the other cannot tell. See BAD_GATEWAY_MESSAGE.
         const said = status === 502 ? BAD_GATEWAY_MESSAGE : ORIGIN_RESPONSE_MESSAGE;
-        return new OriginResponseError(said, status, body);
+        return new OriginResponseError(said, status, body, retryAfterMs);
     }
     if (Cls === OriginTLSError && !platformNamed(body)) {
-        return new OriginTLSError(ORIGIN_TLS_MESSAGE, status, body);
+        return new OriginTLSError(ORIGIN_TLS_MESSAGE, status, body, retryAfterMs);
     }
     if (Cls === OriginUnreachableError && !platformNamed(body)) {
-        return new OriginUnreachableError(ORIGIN_UNREACHABLE_MESSAGE, status, body);
+        return new OriginUnreachableError(ORIGIN_UNREACHABLE_MESSAGE, status, body, retryAfterMs);
     }
-    return new Cls(message, status, body);
+    return new Cls(message, status, body, retryAfterMs);
 }
 /**
  * Whether an error is worth trying again without changing the request.
@@ -730,6 +799,14 @@ export function errorForStatus(status, message, body) {
  * what it can and cannot tell apart.
  */
 export function isTransient(err) {
+    // Preparation requires the original template and a token, and may have failed.
+    // A generic retry of the unchanged create is not the continuation protocol.
+    if (err instanceof APIError &&
+        err.body !== null &&
+        typeof err.body === 'object' &&
+        err.body.code === 'template_image_preparing') {
+        return false;
+    }
     // A move offer is a 409 and is NOT transient — it is a decision about the
     // size that was asked for, and the same request answers the same way forever.
     // First, because it is a subclass of the very branch below that would say yes
@@ -748,9 +825,12 @@ export function isTransient(err) {
     // an arbitrary exception may happen to have a `reason` property, and that is
     // neither this protocol nor retry advice.
     if (err instanceof APIError && err.reason !== undefined) {
-        if (REASON_CLEARS.has(err.reason))
+        // Through the exported classifier rather than the sets directly, so what an
+        // embedder is told and what this server does are one answer and not two.
+        const kind = reasonKind(err.reason);
+        if (kind === 'clears')
             return true;
-        if (REASON_PERMANENT.has(err.reason))
+        if (kind === 'permanent')
             return false;
     }
     return (err instanceof ConflictError ||
@@ -835,6 +915,13 @@ export function isTransient(err) {
  *   SDK found that one; this is the same rule, and it is why all three now say
  *   `>= 500`.
  *
+ *   "Does not follow redirects" is a claim about `#fetch`'s `redirect: 'manual'`
+ *   and is load-bearing HERE, in a way it was not while the default `'follow'`
+ *   silently made it untrue: under `'follow'` a 3xx never reaches this predicate
+ *   at all, so the paragraph above described a case that could not arise and the
+ *   `>= 500` bound rested on nothing. {@link RedirectError} is what a 3xx
+ *   becomes now. Change one and this paragraph is wrong again.
+ *
  * {@link APIError.reason} is deliberately NOT consulted here, and that is the
  * one place this predicate and {@link isTransient} part company (OPL-3898).
  * `unavailable` means the computer is not running, which is a permanent answer
@@ -842,8 +929,11 @@ export function isTransient(err) {
  * may not be, since a computer coming up passes through it. The same generosity
  * as every unmapped 5xx below, for the same reason: this only ever replays a
  * read, and the loops above return a refusal of their own the moment the status
- * they are watching says stopped or suspended. mandala-computer-python's
- * `_is_transient_for_poll` draws the line in the same place.
+ * they are watching says stopped or suspended AND the platform says it is
+ * holding nothing for the machine — the qualification OPL-4631 added, because
+ * a start that has been admitted reads as stopped or suspended until its guest
+ * process exists. mandala-computer-python's `_is_transient_for_poll` draws the
+ * line in the same place.
  *
  * Everything at 5xx polls through, 502 and 520-523 included: they mean the
  * outcome is unknown, and a read whose outcome is unknown can simply be read