unfazed 0.1.0 → 0.3.0

package/dist/unfazed.js

@@ -1,5 +1,5 @@
 import { UnfazedClient } from "./client.js";
-import { UnfazedConflictError, UnfazedDeployError, UnfazedGraphQLError, UnfazedNotFoundError, looksLikeCASConflict, } from "./errors.js";
+import { DEPLOYMENT_NOT_FOUND, UnfazedConflictError, UnfazedDeployError, UnfazedGraphQLError, UnfazedNotFoundError, UnfazedRunError, WORKSPACE_NOT_FOUND, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, looksLikeCASConflict, } from "./errors.js";
 import * as ops from "./operations.js";
 import { pollWithBackoff, resolveWaitOptions } from "./wait.js";
 /**
@@ -46,10 +46,77 @@ export class Unfazed {
     /**
      * Deletes a workspace and everything anchored to it — deployments, env, and
      * a BOX's persistent data disk. Not recoverable.
+     *
+     * **The cascade is opt-out, not opt-in.** The server refuses to delete a
+     * workspace that has ANY deployment history — including FAILED records, and
+     * including deployments whose alias was long since taken over by something
+     * else — unless the mutation carries `withDeployments`. Since almost every
+     * workspace an agent creates gets deployed at least once, defaulting to
+     * `false` would make this method fail on nearly every real workspace, so it
+     * defaults to **`true`**: the behaviour this docstring has always promised.
+     *
+     * Pass `withDeployments: false` for the strict variant, which refuses rather
+     * than cascading and is the safer choice when you are deleting a workspace
+     * you did not create:
+     *
+     * ```ts
+     * await unfazed.deleteWorkspace(ws.id);                            // cascade
+     * await unfazed.deleteWorkspace(ws.id, { withDeployments: false }); // refuse if deployed
+     * await unfazed.deleteWorkspace(id, { ignoreNotFound: true });      // false, not a throw
+     * ```
+     *
+     * With `ignoreNotFound` a workspace that is absent (or belongs to someone
+     * else — the server returns one indistinguishable sentinel for both, on
+     * purpose) resolves to `false` instead of throwing, which makes teardown in
+     * a `finally` block idempotent.
      */
-    async deleteWorkspace(workspaceId, options) {
-        const data = await this.client.mutate(ops.DeleteWorkspaceDocument, { workspaceID: workspaceId }, options);
-        return data.deleteWorkspace.ok;
+    async deleteWorkspace(workspaceId, options = {}) {
+        const withDeployments = options.withDeployments ?? true;
+        try {
+            const data = await this.client.mutate(ops.DeleteWorkspaceDocument, { workspaceID: workspaceId, withDeployments }, options);
+            return data.deleteWorkspace.ok;
+        }
+        catch (e) {
+            if (options.ignoreNotFound && isNotFound(e, WORKSPACE_NOT_FOUND))
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * Returns the workspace named `name`, creating it only if it does not exist.
+     *
+     * Workspace names are unique per owner, case-insensitively — a second
+     * `createWorkspace("Hello")` after a `createWorkspace("hello")` is an error,
+     * not a second workspace. That makes the bare create a poor fit for any
+     * script that might run twice; this is the re-runnable form.
+     *
+     * ```ts
+     * const ws = await unfazed.ensureWorkspace("greeter");   // safe to re-run
+     * ```
+     *
+     * Costs one list, plus one create only on a miss. The create is still
+     * guarded: if a concurrent caller wins the race, the duplicate-name error is
+     * caught and the now-existing workspace is returned instead of thrown.
+     */
+    async ensureWorkspace(name, options) {
+        const existing = await this.#findWorkspaceByName(name, options);
+        if (existing)
+            return existing;
+        try {
+            return await this.createWorkspace(name, options);
+        }
+        catch (e) {
+            // Lost a create/create race, or the server's case folding is stricter
+            // than ours. Either way the workspace exists now — re-read rather than
+            // failing a script whose intent was "make sure this exists".
+            if (!isDuplicateWorkspaceName(e))
+                throw e;
+            const raced = await this.#findWorkspaceByName(name, options);
+            if (raced)
+                return raced;
+            // The name is taken by something we cannot see. Surface the real error.
+            throw e;
+        }
     }
     /* ------------------------------------------------------------------- files */
     /**
@@ -106,17 +173,36 @@ export class Unfazed {
         const data = await this.client.query(ops.ReadFileDocument, { input: { workspaceID: workspaceId, path, ...input } }, options);
         return data.readWorkspaceFile;
     }
-    /** Deletes a workspace file. */
+    /**
+     * Deletes a workspace file.
+     *
+     * Returns `false` when there was nothing to delete — an absent path is not
+     * an error. See the `ok: false` convention on {@link deleteEnv}.
+     */
     async deleteFile(workspaceId, path, options) {
         const data = await this.client.mutate(ops.DeleteFileDocument, { workspaceID: workspaceId, path }, options);
         return data.deleteWorkspaceFile.ok;
     }
-    /* ----------------------------------------------------------------- deploys */
+    /* ----------------------------------------------------------------- deploys
+     *
+     * Every deploy method here MINTS A NEW RELEASE on every call. There is no
+     * content dedupe: deploying byte-identical files twice produces two distinct
+     * releases with two ids, both real, both counting against retention (which
+     * keeps only the most recent few per alias and prunes the rest). Deploying
+     * in a retry loop is therefore not free — it churns the release history and
+     * can push a release you still wanted to roll back to out of retention.
+     * Check {@link getDeployment} or {@link listReleases} before redeploying if
+     * you only meant to converge.
+     */
     /**
      * Deploys the workspace as a SERVICE (an HTTP server).
      *
      * With `wait: true` this resolves only once the build, VM boot and health
      * probe have all passed.
+     *
+     * Passing the same `alias` again redeploys that alias — a new release that
+     * takes over the alias when it goes READY. Omitting `alias` lets the server
+     * generate one, which means a different app on every call.
      */
     deployService(options) {
         const { workspaceId, alias, runtime, serviceMode, healthPath, cronSchedule, cronPath } = options;
@@ -145,6 +231,25 @@ export class Unfazed {
      * Deploys a BOX: a persistent always-on Linux VM with a data disk that
      * survives stops and redeploys. A dev machine, not an HTTP service. The
      * result's `sshCommand` is how you get in.
+     *
+     * ⚠️ **Omitting `alias` creates a NEW BOX every single call.** There is no
+     * "the workspace's box" to update: with no alias the server generates a
+     * fresh random one, so a script run twice leaves you with two box records,
+     * not one redeployed box.
+     *
+     * The data disk, meanwhile, is keyed by WORKSPACE — one disk, shared by
+     * every box in the workspace, and it is the box's real identity. Since only
+     * one VM can hold that disk read-write, the second box cannot even start
+     * while the first is running (`box data disk for workspace ... is attached
+     * to VM ...; stop it first`). The result is a pile of dead box records
+     * fighting over one disk.
+     *
+     * **Always pass an explicit `alias` in anything re-runnable.** Redeploying
+     * the same alias is the in-place update you actually want.
+     *
+     * ```ts
+     * await unfazed.deployBox({ workspaceId: ws.id, alias: "dev" });   // re-runnable
+     * ```
      */
     deployBox(options) {
         const { workspaceId, alias, resources } = options;
@@ -250,10 +355,23 @@ export class Unfazed {
         const data = await this.client.mutate(ops.StopServiceDocument, { deploymentID: deploymentId }, options);
         return data.stopService;
     }
-    /** Deletes a deployment. */
-    async deleteDeployment(deploymentId, options) {
-        const data = await this.client.mutate(ops.DeleteDeploymentDocument, { deploymentID: deploymentId }, options);
-        return data.deleteDeployment.ok;
+    /**
+     * Deletes a deployment: stops its VM, releases its alias, drops its release.
+     *
+     * With `ignoreNotFound` a deployment that is absent — or belongs to another
+     * tenant, which the server reports identically so ids cannot be probed —
+     * resolves to `false` instead of throwing, making cleanup loops idempotent.
+     */
+    async deleteDeployment(deploymentId, options = {}) {
+        try {
+            const data = await this.client.mutate(ops.DeleteDeploymentDocument, { deploymentID: deploymentId }, options);
+            return data.deleteDeployment.ok;
+        }
+        catch (e) {
+            if (options.ignoreNotFound && isNotFound(e, DEPLOYMENT_NOT_FOUND))
+                return false;
+            throw e;
+        }
     }
     /* ------------------------------------------------------------ env & secrets
      *
@@ -262,12 +380,25 @@ export class Unfazed {
      * deploy time — changing either does not affect a running app until you
      * redeploy that alias. Old releases are immutable, and STATIC gets no env.
      */
-    /** Sets a workspace-default env var. Redeploy the alias to apply it. */
+    /**
+     * Sets a workspace-default env var. Redeploy the alias to apply it.
+     *
+     * A name is either plain or secret, never both: this DELETES a workspace
+     * secret of the same name. {@link setSecret} displaces a plain var the same
+     * way. Last write wins, and the kind flips silently — so re-running a setup
+     * script that calls `setSecret("API_KEY", ...)` after one that called
+     * `setEnv("API_KEY", ...)` quietly converts it, and vice versa.
+     */
     async setEnv(workspaceId, name, value, options) {
         const data = await this.client.mutate(ops.SetWorkspaceEnvDocument, { workspaceID: workspaceId, name, value }, options);
         return data.setWorkspaceEnv.env;
     }
-    /** Sets a workspace-default secret. The value is never readable again. */
+    /**
+     * Sets a workspace-default secret. The value is never readable again.
+     *
+     * Mutually exclusive with {@link setEnv}: this DELETES a plain workspace var
+     * of the same name. See {@link setEnv} for the displacement rule.
+     */
     async setSecret(workspaceId, name, value, options) {
         const data = await this.client.mutate(ops.SetWorkspaceSecretDocument, { workspaceID: workspaceId, name, value }, options);
         return data.setWorkspaceSecret.env;
@@ -277,6 +408,16 @@ export class Unfazed {
      * the same batching trick as {@link writeFiles}.
      *
      * Pass `{ secret: true }` to route them all to `setWorkspaceSecret`.
+     *
+     * It inherits {@link writeFiles}' failure semantics too: the batch is NOT
+     * atomic. GraphQL resolves each aliased field independently, so a rejected
+     * name (over the limit, malformed, whatever) leaves the vars before it
+     * already committed. The thrown {@link UnfazedGraphQLError} carries `data`
+     * with the aliases that succeeded and `errors[].path` naming those that did
+     * not — do not assume "it threw" means "nothing was written".
+     *
+     * Each name still displaces its opposite kind, exactly as {@link setEnv} and
+     * {@link setSecret} do one at a time.
      */
     async setEnvMany(workspaceId, vars, options = {}) {
         const entries = Object.entries(vars);
@@ -296,7 +437,16 @@ export class Unfazed {
         const data = await this.client.mutate(document, variables, options.signal ? { signal: options.signal } : {});
         return entries.map((_, i) => data[`e${i}`].env);
     }
-    /** Deletes a workspace-default env var. */
+    /**
+     * Deletes a workspace-default env var (plain or secret).
+     *
+     * **The `ok: false` convention.** A `false` here does NOT mean failure — it
+     * means "nothing to do, the world is already in the state you asked for".
+     * The var did not exist. Every `ok`-returning mutation in this SDK follows
+     * the rule ({@link deleteFile}, {@link inheritAppEnv}, {@link removeAppEnv}),
+     * so the idempotent-cleanup pattern is simply to ignore the boolean; a real
+     * failure throws.
+     */
     async deleteEnv(workspaceId, name, options) {
         const data = await this.client.mutate(ops.DeleteWorkspaceEnvDocument, { workspaceID: workspaceId, name }, options);
         return data.deleteWorkspaceEnv.ok;
@@ -306,12 +456,24 @@ export class Unfazed {
         const data = await this.client.query(ops.ListWorkspaceEnvDocument, { workspaceID: workspaceId }, options);
         return data.workspaceEnv;
     }
-    /** Sets an env var for ONE alias, overriding the workspace default. */
+    /**
+     * Sets an env var for ONE alias, overriding the workspace default.
+     *
+     * Displaces both of the other states this name could be in for the app: it
+     * deletes an app SECRET of the same name, and it CLEARS a REMOVE mask left
+     * by {@link removeAppEnv}. So setting a value is also the way to un-block a
+     * masked name, and a name is only ever one of plain / secret / masked.
+     */
     async setAppEnv(workspaceId, alias, name, value, options) {
         const data = await this.client.mutate(ops.SetAppEnvDocument, { workspaceID: workspaceId, alias, name, value }, options);
         return data.setAppEnv.env;
     }
-    /** Sets a secret for ONE alias, overriding the workspace default. */
+    /**
+     * Sets a secret for ONE alias, overriding the workspace default.
+     *
+     * Like {@link setAppEnv}, this deletes a plain app var of the same name and
+     * clears a REMOVE mask for it.
+     */
     async setAppSecret(workspaceId, alias, name, value, options) {
         const data = await this.client.mutate(ops.SetAppSecretDocument, { workspaceID: workspaceId, alias, name, value }, options);
         return data.setAppSecret.env;
@@ -320,12 +482,36 @@ export class Unfazed {
      * REMOVE: blocks this name for the app entirely — the app override, the
      * workspace default, and integration enrichment. Not the same as deleting an
      * override; use {@link inheritAppEnv} for that.
+     *
+     * This WRITES A MASK, and the mask is a real, persistent row. Two things
+     * follow that surprise people:
+     *
+     *  - It is written even when nothing was inherited. Masking a name that no
+     *    workspace default and no integration ever provided is not a no-op; it
+     *    leaves a tombstone that keeps blocking the name if a default appears
+     *    later. Clear it with {@link inheritAppEnv}.
+     *  - It COSTS A SLOT. A workspace gets 128 env entries total — that budget
+     *    is shared across the workspace defaults AND every app scope combined,
+     *    not 128 per scope — and masks count toward it just like values do.
+     *    Masking names in a loop can exhaust the workspace's env budget.
+     *
+     * Returns `false` when the exact mask was already present (a second call for
+     * the same name), per the {@link deleteEnv} `ok: false` convention. It
+     * returns `true` when it had something to change — including converting an
+     * existing override into a mask.
      */
     async removeAppEnv(workspaceId, alias, name, options) {
         const data = await this.client.mutate(ops.RemoveAppEnvDocument, { workspaceID: workspaceId, alias, name }, options);
         return data.removeAppEnv.ok;
     }
-    /** INHERIT: clears the app override/mask so workspace and integration values apply again. */
+    /**
+     * INHERIT: clears the app override/mask so workspace and integration values
+     * apply again. This is the undo for both {@link setAppEnv} and
+     * {@link removeAppEnv}.
+     *
+     * Returns `false` when there was no override and no mask to clear — nothing
+     * to do, not a failure. See {@link deleteEnv}.
+     */
     async inheritAppEnv(workspaceId, alias, name, options) {
         const data = await this.client.mutate(ops.InheritAppEnvDocument, { workspaceID: workspaceId, alias, name }, options);
         return data.inheritAppEnv.ok;
@@ -365,11 +551,31 @@ export class Unfazed {
      * ```ts
      * await unfazed.rollback({ alias: "my-app" });              // undo last deploy
      * await unfazed.rollback({ alias: "my-app", to: relId });   // to a specific release
+     * await unfazed.rollback({ alias: "my-app", to: relId, expectedCurrentId: liveId });
      * ```
+     *
+     * ⚠️ **A bare `rollback({ alias })` is a TOGGLE, not an idempotent step.**
+     * It means "restore the most recent READY release that is not the live one",
+     * which is a different release each time the alias moves. Run the same
+     * script twice and the second run rolls back the rollback — A → B → A → B,
+     * forever, with each hop a real alias swap. Nothing errors, because every
+     * individual call did exactly what it was asked.
+     *
+     * In anything re-runnable — a retry loop, a CI job, an agent that might redo
+     * a step — pin the outcome instead:
+     *
+     *  - `to:` names the release you want live, so re-running is a no-op-ish
+     *    convergence rather than a flip (a second run then reports the target
+     *    already holds the alias instead of moving it);
+     *  - `expectedCurrentId:` states what you expect to be live now, so a second
+     *    run fails loudly instead of silently undoing the first.
      */
     async rollback(options) {
-        const { alias, signal } = options;
-        const retries = options.retries ?? 1;
+        const { alias, signal, expectedCurrentId } = options;
+        // A caller-supplied precondition and the CAS retry are mutually exclusive:
+        // retrying re-guards against whatever holds the alias NOW, which is the
+        // one thing `expectedCurrentId` exists to refuse.
+        const retries = expectedCurrentId === undefined ? (options.retries ?? 1) : 0;
         const requestOptions = signal ? { signal } : {};
         let targetId = options.to;
         for (let attempt = 0;; attempt++) {
@@ -381,6 +587,13 @@ export class Unfazed {
             if (!current) {
                 throw new UnfazedNotFoundError(`unfazed: alias "${alias}" has no current release holding the alias`);
             }
+            // The caller's precondition, checked before anything is sent. Failing
+            // here rather than at the server keeps a violated expectation from
+            // costing an alias swap, and reports the holder we actually observed.
+            if (expectedCurrentId !== undefined && current.id !== expectedCurrentId) {
+                throw new UnfazedConflictError(`unfazed: alias "${alias}" is held by ${current.id}, not the expected ` +
+                    `${expectedCurrentId} — it moved since you read it; re-read and decide again`, []);
+            }
             // Pin the target on the first pass so a retry refreshes only the guard.
             if (targetId === undefined) {
                 const previous = releases.find((r) => r.id !== current.id && r.status === "READY");
@@ -421,7 +634,213 @@ export class Unfazed {
             }
         }
     }
+    /* --------------------------------------------------------------- agent runs
+     *
+     * A run is the past-tense counterpart to a deployment: boot a fresh VM off
+     * the box image, hand it a prompt, let a harness work for up to an hour,
+     * keep the transcript, meter what it cost, reap the VM. Deployments answer
+     * "what is running"; runs answer "what happened". Inside a run, `new
+     * Unfazed()` is already authenticated — the platform injects
+     * UNFZ_API_TOKEN / UNFZ_API_URL, at most the parent's scopes, revoked when
+     * the run settles.
+     */
+    /**
+     * Starts an agent run.
+     *
+     * Resolves once the VM has started (status RUNNING) — or, on a boot
+     * failure, once the run has already settled FAILED with `error` set. A
+     * boot failure is a normal return value here, not a thrown error, with or
+     * without `wait`.
+     *
+     * ```ts
+     * const run = await unfazed.createRun({
+     *   workspaceId: ws.id,
+     *   harness: "claude-code",
+     *   prompt: "Fix the failing test in test/foo.test.ts and open a PR.",
+     *   wait: true,
+     * });
+     * console.log(run.status, run.usage.mibSeconds);
+     * ```
+     *
+     * With `wait: true` this additionally polls a RUNNING run through to a
+     * terminal status — see {@link waitForRun} for exactly what "terminal"
+     * means and how a timeout is reported.
+     */
+    async createRun(options) {
+        const { workspaceId, prompt, harness, command, setup, skills, memoryMiB, maxSeconds, metadata, includeFiles, approval, mode, parentRunId, wait, waitOptions, signal, } = options;
+        const requestOptions = signal ? { signal } : {};
+        const data = await this.client.mutate(ops.CreateRunDocument, {
+            input: {
+                workspaceID: workspaceId,
+                ...(prompt === undefined ? {} : { prompt }),
+                ...(harness === undefined ? {} : { harness }),
+                ...(command === undefined ? {} : { command }),
+                ...(setup === undefined ? {} : { setup }),
+                ...(skills === undefined ? {} : { skills }),
+                ...(memoryMiB === undefined ? {} : { memoryMiB }),
+                ...(maxSeconds === undefined ? {} : { maxSeconds }),
+                ...(metadata === undefined ? {} : { metadata }),
+                ...(includeFiles === undefined ? {} : { includeFiles }),
+                ...(approval === undefined ? {} : { approval }),
+                ...(mode === undefined ? {} : { mode }),
+                ...(parentRunId === undefined ? {} : { parentRunID: parentRunId }),
+            },
+        }, requestOptions);
+        const run = data.createRun;
+        // Unlike createDeployment (always BUILDING), createRun can come back
+        // already terminal — a boot failure settles FAILED synchronously. Only
+        // poll when there is actually something to wait for.
+        if (!wait || isTerminalRunStatus(run.status))
+            return run;
+        return this.waitForRun(run.id, {
+            ...waitOptions,
+            ...(signal ? { signal } : {}),
+        });
+    }
+    /**
+     * Polls a run until it leaves QUEUED/RUNNING, throwing only on timeout.
+     *
+     * Terminal is defined negatively — anything that is not QUEUED or RUNNING —
+     * matching the platform's own status machine, so an unknown future status
+     * still ends the wait instead of looping forever. **SUCCEEDED, FAILED and
+     * CANCELLED are all returned normally**: a run that executed and exited
+     * non-zero is a completed answer (read `run.error` / `run.exitCode`), not
+     * an exception the way a FAILED deployment is. Only running out of time
+     * throws, as {@link UnfazedRunError} with `reason: "TIMEOUT"`.
+     */
+    async waitForRun(runId, waitOptions = {}) {
+        const resolved = resolveWaitOptions(waitOptions);
+        const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
+        let last = null;
+        await pollWithBackoff(async () => {
+            const data = await this.client.query(ops.PollRunDocument, { id: runId }, requestOptions);
+            const r = data.run;
+            last = r;
+            if (isTerminalRunStatus(r.status))
+                return { done: true, value: true };
+            return { done: false };
+        }, resolved, () => new UnfazedRunError("TIMEOUT", runId, last, `unfazed: run ${runId} still ${last?.status ?? "QUEUED"} after ${resolved.timeoutMs}ms`));
+        return this.getRun(runId, requestOptions);
+    }
+    /** Reads one run by id. Throws if it does not exist or is not visible to you. */
+    async getRun(runId, options) {
+        const data = await this.client.query(ops.GetRunDocument, { id: runId }, options);
+        return data.run;
+    }
+    /** Your agent runs, newest first, optionally filtered by workspace/status. */
+    async listRuns(filter = {}, options) {
+        const { workspaceId, status, limit, offset } = filter;
+        const data = await this.client.query(ops.ListRunsDocument, {
+            input: {
+                ...(workspaceId === undefined ? {} : { workspaceID: workspaceId }),
+                ...(status === undefined ? {} : { status }),
+                ...(limit === undefined ? {} : { limit }),
+                ...(offset === undefined ? {} : { offset }),
+            },
+        }, options);
+        return data.runs;
+    }
+    /**
+     * Stops a run: a QUEUED run is cancelled at once, a RUNNING run's VM is
+     * killed and the run settles CANCELLED shortly after (`waitForRun` to
+     * observe it). Idempotent on an already-CANCELLED run; a run that has
+     * already SUCCEEDED or FAILED cannot be cancelled and the server rejects
+     * the call (thrown as {@link UnfazedGraphQLError}) — check `status` first
+     * when that is a routine case for you.
+     */
+    async cancelRun(runId, options) {
+        const data = await this.client.mutate(ops.CancelRunDocument, { id: runId }, options);
+        return data.cancelRun;
+    }
+    /**
+     * Continues a FINISHED run with a new instruction: a new run in the same
+     * workspace that inherits the parent's harness (or command), setup, skills
+     * and approval, with the parent's task, outcome and the end of its
+     * transcript prepended to `prompt` as context. This is how a plan is
+     * approved — `createRun({ mode: "plan" })` writes the plan, `followUpRun`
+     * with the go-ahead executes it — and how work continues after a run
+     * exited. The new run carries `parentRunID` and `depth`; chains are capped
+     * server-side. A live run cannot be followed up (the server refuses):
+     * answer it or wait for it.
+     *
+     * ```ts
+     * const plan = await unfazed.createRun({ workspaceId, harness: "claude-code", prompt: "plan the migration", mode: "plan", wait: true });
+     * const done = await unfazed.followUpRun(plan.id, { prompt: "go ahead", wait: true });
+     * ```
+     */
+    async followUpRun(runId, options) {
+        const { prompt, mode, approval, maxSeconds, metadata, wait, waitOptions, signal } = options;
+        const requestOptions = signal ? { signal } : {};
+        const data = await this.client.mutate(ops.FollowUpRunDocument, {
+            input: {
+                runID: runId,
+                prompt,
+                ...(mode === undefined ? {} : { mode }),
+                ...(approval === undefined ? {} : { approval }),
+                ...(maxSeconds === undefined ? {} : { maxSeconds }),
+                ...(metadata === undefined ? {} : { metadata }),
+            },
+        }, requestOptions);
+        const run = data.followUpRun;
+        if (!wait || isTerminalRunStatus(run.status))
+            return run;
+        return this.waitForRun(run.id, { ...waitOptions, ...(signal ? { signal } : {}) });
+    }
+    /**
+     * Answers a BLOCKED run's pending question (`run.question`); the run
+     * resumes with the text. For a question with `options`, answer with one
+     * of them. Only a BLOCKED run accepts an answer — anything else is
+     * refused by the server.
+     *
+     * A run blocks when the agent inside calls `request_human_input`, or when
+     * it was created with `approval: "human"` and its harness asks permission
+     * for a guarded action. `waitForRun` keeps waiting through BLOCKED (it is
+     * not terminal); poll `getRun` and look at `question` to notice one.
+     */
+    async answerRun(runId, answer, options) {
+        const data = await this.client.mutate(ops.AnswerRunDocument, { id: runId, answer }, options);
+        return data.answerRun;
+    }
+    /** A run's own history, oldest first (started, cancel requested, settled). */
+    async runEvents(runId, input = {}, options) {
+        const data = await this.client.query(ops.RunEventsDocument, { runID: runId, limit: input.limit ?? null }, options);
+        return data.runEvents;
+    }
+    /**
+     * The live tail of a RUNNING run's console. Once the run has settled this
+     * comes back empty with `running: false` — read {@link runTranscript}
+     * instead, which is the stored, durable copy.
+     */
+    async runConsole(runId, input = {}, options) {
+        const data = await this.client.query(ops.RunConsoleDocument, { id: runId, tailBytes: input.tailBytes ?? null }, options);
+        return data.runConsole;
+    }
+    /**
+     * The bounded end of a finished run's stored transcript (secrets
+     * redacted). `available` is false until the run settles and the transcript
+     * is copied out of the VM's console file — check `run.transcriptAvailable`
+     * or poll this after {@link waitForRun} resolves.
+     */
+    async runTranscript(runId, input = {}, options) {
+        const data = await this.client.query(ops.RunTranscriptDocument, { id: runId, tailBytes: input.tailBytes ?? null }, options);
+        return data.runTranscript;
+    }
     /* -------------------------------------------------------------- internals */
+    /**
+     * Finds a visible workspace by name, the way the server compares names.
+     *
+     * The server rejects duplicates with Go's `strings.EqualFold`, so matching
+     * must be case-insensitive here too or `ensureWorkspace` would try to create
+     * a "new" workspace the server considers a duplicate. An exact-case hit wins
+     * over a folded one, which only matters if a name ever slipped past the
+     * uniqueness check.
+     */
+    async #findWorkspaceByName(name, options) {
+        const workspaces = await this.listWorkspaces(options);
+        const folded = name.toLowerCase();
+        return (workspaces.find((w) => w.name === name) ??
+            workspaces.find((w) => w.name.toLowerCase() === folded));
+    }
     async #writeBatch(workspaceId, batch, signal) {
         const varDefs = ["$workspaceID: ID!"];
         const fields = [];
@@ -445,6 +864,14 @@ export class Unfazed {
 }
 const FILE_SELECTION = "path sizeBytes size sha256 updatedAt";
 const ENV_SELECTION = "name value secret alias inherited masked updatedAt";
+/**
+ * Terminal = anything but QUEUED or RUNNING, defined negatively exactly like
+ * the platform's own `IsTerminalRunStatus` — so a future status this SDK does
+ * not know about yet still ends a wait instead of polling forever.
+ */
+function isTerminalRunStatus(status) {
+    return status !== "QUEUED" && status !== "RUNNING";
+}
 function normalizeFile(path, content) {
     if (typeof content === "string")
         return { path, kind: "text", content };