@folsom/fuse 0.36.0 → 0.41.0

package/dist/index.js

@@ -6,7 +6,9 @@ var ErrorCode = {
   InvalidArgument: "invalid_argument",
   Unavailable: "unavailable",
   Internal: "internal",
-  Unauthorized: "unauthorized"
+  Unauthorized: "unauthorized",
+  Forbidden: "forbidden",
+  Locked: "locked"
 };
 var STATUS_TEXT = {
   400: "bad request",
@@ -14,6 +16,7 @@ var STATUS_TEXT = {
   403: "forbidden",
   404: "not found",
   409: "conflict",
+  423: "locked",
   500: "internal server error",
   502: "bad gateway",
   503: "service unavailable"
@@ -47,6 +50,44 @@ var FuseApiError = class _FuseApiError extends Error {
     Object.setPrototypeOf(this, _FuseApiError.prototype);
   }
 };
+var ForbiddenReason = {
+  MissingScope: "missing_scope",
+  EnvScope: "env_scope",
+  SelfApproval: "self_approval",
+  ActorRequired: "actor_required",
+  ActorMismatch: "actor_mismatch",
+  ActorNotAllowed: "actor_not_allowed",
+  MintEscalation: "mint_escalation",
+  /** A hitl deny gate (or the exec allowlist in deny mode) refused the
+   * action. The message is the gate's reason; details.gate names the gate. */
+  HitlDenied: "hitl_denied"
+};
+var ForbiddenError = class _ForbiddenError extends FuseApiError {
+  reason;
+  scope;
+  constructor(init) {
+    super(init);
+    this.name = "ForbiddenError";
+    this.reason = init.details?.reason ?? "";
+    this.scope = init.details?.scope;
+    Object.setPrototypeOf(this, _ForbiddenError.prototype);
+  }
+};
+var LockedError = class _LockedError extends FuseApiError {
+  interventionId;
+  /** "takeover" or "stall". */
+  kind;
+  constructor(init) {
+    super(init);
+    this.name = "LockedError";
+    this.interventionId = init.details?.intervention_id ?? "";
+    this.kind = init.details?.kind ?? "";
+    Object.setPrototypeOf(this, _LockedError.prototype);
+  }
+};
+function isLocked(err) {
+  return err instanceof LockedError;
+}
 var FuseError = class _FuseError extends Error {
   constructor(message, options) {
     super(message, options);
@@ -54,6 +95,39 @@ var FuseError = class _FuseError extends Error {
     Object.setPrototypeOf(this, _FuseError.prototype);
   }
 };
+var PendingInterventionError = class _PendingInterventionError extends Error {
+  intervention;
+  constructor(intervention) {
+    super(
+      `held by hitl gate ${intervention.gate ?? ""}: waiting on intervention ${intervention.id}`
+    );
+    this.name = "PendingInterventionError";
+    this.intervention = intervention;
+    Object.setPrototypeOf(this, _PendingInterventionError.prototype);
+  }
+};
+var InterventionRejectedError = class _InterventionRejectedError extends Error {
+  intervention;
+  constructor(intervention) {
+    super(
+      `intervention ${intervention.id} ${intervention.state}: ${intervention.decision?.reason ?? ""}`
+    );
+    this.name = "InterventionRejectedError";
+    this.intervention = intervention;
+    Object.setPrototypeOf(this, _InterventionRejectedError.prototype);
+  }
+};
+var HeldActionError = class _HeldActionError extends Error {
+  intervention;
+  constructor(intervention) {
+    super(
+      `approved action of intervention ${intervention.id} failed: ${intervention.result?.error ?? ""}`
+    );
+    this.name = "HeldActionError";
+    this.intervention = intervention;
+    Object.setPrototypeOf(this, _HeldActionError.prototype);
+  }
+};
 function isFuseApiError(err) {
   return err instanceof FuseApiError;
 }
@@ -69,6 +143,12 @@ function isConflict(err) {
 function isUnauthorized(err) {
   return hasCode(err, ErrorCode.Unauthorized);
 }
+function isForbidden(err) {
+  return err instanceof ForbiddenError;
+}
+function isHitlDenied(err) {
+  return isForbidden(err) && err.reason === ForbiddenReason.HitlDenied;
+}
 function isInvalidArgument(err) {
   return hasCode(err, ErrorCode.InvalidArgument);
 }
@@ -81,14 +161,17 @@ function parseApiError(status, requestId, body) {
       const env = JSON.parse(body);
       const e = env?.error;
       if (e && (e.code || e.message)) {
-        return new FuseApiError({
+        const init = {
           status,
           code: e.code,
           message: e.message,
           details: e.details,
           requestId,
           body
-        });
+        };
+        if (e.code === ErrorCode.Forbidden) return new ForbiddenError(init);
+        if (e.code === ErrorCode.Locked) return new LockedError(init);
+        return new FuseApiError(init);
       }
     } catch {
     }
@@ -112,6 +195,8 @@ async function errorFromResponse(res) {
 
 // src/transport.ts
 var REQUEST_ID_HEADER2 = "X-Request-ID";
+var ACTOR_HEADER = "Fuse-Actor";
+var ACTOR_NAME_HEADER = "Fuse-Actor-Name";
 function combineSignals(signals) {
   const active = signals.filter((s) => s != null);
   if (active.length === 0) return { cleanup: () => {
@@ -146,6 +231,10 @@ var Transport = class {
   requestId;
   timeoutMs;
   defaultHeaders;
+  actor;
+  /** The client's hitl wait options. */
+  hitlNoWait;
+  onHeld;
   constructor(cfg) {
     if (!cfg.baseUrl) {
       throw new FuseError("base url is required");
@@ -162,6 +251,9 @@ var Transport = class {
     this.requestId = cfg.requestId;
     this.timeoutMs = cfg.timeoutMs;
     this.defaultHeaders = cfg.headers;
+    this.actor = cfg.actor;
+    this.hitlNoWait = cfg.hitlNoWait ?? false;
+    this.onHeld = cfg.onHeld;
     const provided = cfg.fetch;
     if (provided) {
       this.fetchImpl = provided;
@@ -184,6 +276,53 @@ var Transport = class {
       cleanup();
     }
   }
+  /**
+   * Perform a call a hitl gate may hold. A 202 answers with the held
+   * intervention; anything else 2xx with the action's own (possibly empty)
+   * body.
+   */
+  async gated(method, path, spec = {}) {
+    const { signal: combined, cleanup } = this.withTimeout(spec.signal);
+    try {
+      const res = await this.execute(method, path, spec, combined);
+      if (!res.ok) throw await errorFromResponse(res);
+      if (res.status === 202) return { held: await this.decodeHeld(res) };
+      return { value: await this.decodeJson(res) };
+    } finally {
+      cleanup();
+    }
+  }
+  /** Like noContent for a call a hitl gate may hold: it resolves to the held
+   * intervention of a 202, or undefined when the action itself answered. */
+  async gatedNoContent(method, path, spec = {}) {
+    const { signal: combined, cleanup } = this.withTimeout(spec.signal);
+    try {
+      const res = await this.execute(method, path, spec, combined);
+      if (!res.ok) throw await errorFromResponse(res);
+      if (res.status === 202) return await this.decodeHeld(res);
+      await res.body?.cancel().catch(() => {
+      });
+      return void 0;
+    } finally {
+      cleanup();
+    }
+  }
+  /** Perform a request and return the response body as text. */
+  async text(method, path, spec = {}) {
+    const { signal: combined, cleanup } = this.withTimeout(spec.signal);
+    try {
+      const res = await this.execute(method, path, spec, combined);
+      if (!res.ok) throw await errorFromResponse(res);
+      return await res.text();
+    } finally {
+      cleanup();
+    }
+  }
+  async decodeHeld(res) {
+    const body = await this.decodeJson(res);
+    if (!body?.intervention?.id) throw new FuseError("decode held response");
+    return body.intervention;
+  }
   /** Perform a request that returns no body (e.g. 204 actions). */
   async noContent(method, path, spec = {}) {
     const { signal: combined, cleanup } = this.withTimeout(spec.signal);
@@ -246,6 +385,10 @@ var Transport = class {
       if (id) headers[REQUEST_ID_HEADER2] = id;
     }
     if (accept) headers["Accept"] = accept;
+    if (this.actor?.id) {
+      headers[ACTOR_HEADER] = this.actor.id;
+      if (this.actor.name) headers[ACTOR_NAME_HEADER] = this.actor.name;
+    }
     return headers;
   }
   async decodeJson(res) {
@@ -266,15 +409,14 @@ var Transport = class {
   }
 };
 
-// src/validate.ts
-function requireArg(value, name) {
-  if (!value) {
-    throw new FuseError(`${name} is required`);
-  }
-  return value;
-}
-
 // src/types.ts
+var HitlScope = {
+  Read: "hitl:read",
+  Decide: "hitl:decide",
+  Secret: "hitl:secret",
+  Takeover: "hitl:takeover",
+  ActAs: "hitl:act-as"
+};
 var State = {
   Provisioning: "provisioning",
   Running: "running",
@@ -296,6 +438,90 @@ var HealthState = {
    * ended. */
   Failing: "failing"
 };
+var AuditEvent = {
+  Raised: "raised",
+  Decided: "decided",
+  Expired: "expired",
+  Cancelled: "cancelled",
+  InviteMinted: "invite_minted",
+  InviteUsed: "invite_used",
+  GrantCreated: "grant_created",
+  GrantUsed: "grant_used",
+  SecretAnswered: "secret_answered",
+  TakeoverStarted: "takeover_started",
+  TakeoverEnded: "takeover_ended",
+  TakeoverSession: "takeover_session"
+};
+var HitlKind = {
+  Ask: "ask",
+  Exec: "exec",
+  Lifecycle: "lifecycle",
+  Computer: "computer",
+  Review: "review",
+  Secret: "secret",
+  Takeover: "takeover",
+  Stall: "stall",
+  Expiry: "expiry"
+};
+var GateMode = {
+  Ask: "ask",
+  Notify: "notify",
+  Deny: "deny"
+};
+var DeciderVerdict = {
+  Allow: "allow",
+  Deny: "deny",
+  Ask: "ask"
+};
+var ACTOR_SOURCE_DECIDER = "decider";
+var ReviewFormat = {
+  Text: "text",
+  Diff: "diff"
+};
+var TakeoverVia = {
+  Terminal: "terminal",
+  Desktop: "desktop"
+};
+var LifecycleAction = {
+  Destroy: "destroy",
+  Fork: "fork",
+  Migrate: "migrate",
+  Drain: "drain",
+  Snapshot: "snapshot",
+  RotateToken: "rotate-token"
+};
+var ALLOWLIST_GATE = "exec.allowlist";
+var InterventionState = {
+  Pending: "pending",
+  Approved: "approved",
+  Rejected: "rejected",
+  Expired: "expired",
+  Cancelled: "cancelled"
+};
+var InterventionOutcome = {
+  Approve: "approve",
+  Reject: "reject"
+};
+function isInterventionTerminal(i) {
+  return !!i && !!i.state && i.state !== InterventionState.Pending;
+}
+function isInterventionApproved(i) {
+  return i?.decision?.outcome === InterventionOutcome.Approve;
+}
+function isInterventionSettled(i) {
+  if (!i || !isInterventionTerminal(i)) return false;
+  if (i.decision?.decided_by?.source === ACTOR_SOURCE_DECIDER) return true;
+  const runs = i.mode === GateMode.Ask && (!!i.payload?.exec || !!i.payload?.lifecycle || !!i.payload?.computer);
+  return !runs || !isInterventionApproved(i) || !!i.result;
+}
+
+// src/validate.ts
+function requireArg(value, name) {
+  if (!value) {
+    throw new FuseError(`${name} is required`);
+  }
+  return value;
+}
 
 // src/events.ts
 var DATA_PREFIX = "data:";
@@ -365,8 +591,182 @@ function parseEventStream(res, signal) {
   };
 }
 
-// src/environments.ts
+// src/interventions.ts
 var MAX_PAGE_LIMIT = 200;
+var WAIT_POLL = "30s";
+var InterventionsService = class {
+  constructor(t) {
+    this.t = t;
+  }
+  t;
+  /** List every intervention matching options, oldest first, walking every
+   * page. */
+  async list(options = {}, opts = {}) {
+    const out = [];
+    let cursor = options.cursor;
+    for (; ; ) {
+      const page = await this.listPage(
+        { ...options, limit: MAX_PAGE_LIMIT, cursor },
+        opts
+      );
+      out.push(...page.interventions);
+      if (!page.nextCursor) break;
+      cursor = page.nextCursor;
+    }
+    return out;
+  }
+  /** List one page of interventions matching options. */
+  async listPage(options = {}, opts = {}) {
+    const out = await this.t.json("GET", "/v1/interventions", {
+      query: {
+        env: options.envId,
+        state: options.state,
+        actor: options.actor,
+        limit: options.limit ? String(options.limit) : void 0,
+        cursor: options.cursor
+      },
+      signal: opts.signal
+    });
+    return { interventions: out.interventions ?? [], nextCursor: out.next_cursor };
+  }
+  /** List every hitl audit row matching options, oldest first, walking every
+   * page. */
+  async audit(options = {}, opts = {}) {
+    const out = [];
+    let cursor = options.cursor;
+    for (; ; ) {
+      const page = await this.auditPage(
+        { ...options, limit: MAX_PAGE_LIMIT, cursor },
+        opts
+      );
+      out.push(...page.entries);
+      if (!page.nextCursor) break;
+      cursor = page.nextCursor;
+    }
+    return out;
+  }
+  /** List one page of the hitl audit log matching options. */
+  async auditPage(options = {}, opts = {}) {
+    const out = await this.t.json("GET", "/v1/hitl/audit", {
+      query: {
+        env: options.envId,
+        actor: options.actor,
+        since: options.since,
+        limit: options.limit ? String(options.limit) : void 0,
+        cursor: options.cursor
+      },
+      signal: opts.signal
+    });
+    return { entries: out.entries ?? [], nextCursor: out.next_cursor };
+  }
+  /** Fetch a takeover session's recording (an AuditEntry's recording_id):
+   * asciinema v2 cast text for a terminal session, json (an input-action log
+   * plus screenshots) for a desktop one. Needs the hitl:read scope. */
+  async getRecording(recordingId, opts = {}) {
+    requireArg(recordingId, "recording id");
+    return this.t.text("GET", `/v1/hitl/recordings/${encodeURIComponent(recordingId)}`, {
+      signal: opts.signal
+    });
+  }
+  /** Fetch one intervention without waiting. */
+  async get(id, opts = {}) {
+    return getIntervention(this.t, id, void 0, opts);
+  }
+  /**
+   * Block until the intervention settles: resolved, and for an approved gated
+   * action, performed, with the outcome on result. Every intervention has a deadline,
+   * so this always returns eventually. A dropped connection or an
+   * orchestrator restart is survived by polling again; the server, not the
+   * connection, holds the state. Pass `opts.signal` to stop early.
+   */
+  async wait(id, opts = {}) {
+    return waitIntervention(this.t, id, opts);
+  }
+  /** Resolve a pending intervention as approved. For a held exec or
+   * lifecycle action, the orchestrator then performs it (optionally with
+   * body.editedArgv, or granting repeats with body.grant); wait on the id for
+   * its result. Requires the master token. */
+  async approve(id, body = {}, opts = {}) {
+    return this.decide(id, "approve", body, opts);
+  }
+  /** Resolve a pending intervention as rejected. Requires the master token. */
+  async reject(id, body = {}, opts = {}) {
+    return this.decide(id, "reject", { reason: body.reason }, opts);
+  }
+  /**
+   * Answer a pending secret request. The value is written into the guest at
+   * the declared target and dropped; fuse never stores, logs or returns it.
+   * Needs the hitl:secret scope.
+   */
+  async answerSecret(id, value, opts = {}) {
+    requireArg(id, "intervention id");
+    return this.t.json(
+      "POST",
+      `/v1/interventions/${encodeURIComponent(id)}`,
+      { query: { action: "secret" }, body: { value }, signal: opts.signal }
+    );
+  }
+  async decide(id, action, body, opts) {
+    requireArg(id, "intervention id");
+    return this.t.json(
+      "POST",
+      `/v1/interventions/${encodeURIComponent(id)}`,
+      {
+        query: { action },
+        body: {
+          answer: body.answer || void 0,
+          reason: body.reason || void 0,
+          edited_argv: body.editedArgv?.length ? body.editedArgv : void 0,
+          edited_text: body.editedText,
+          grant: body.grant || void 0,
+          extend_seconds: body.extendSeconds || void 0
+        },
+        signal: opts.signal
+      }
+    );
+  }
+};
+async function waitIntervention(t, id, opts = {}) {
+  for (; ; ) {
+    const i = await getIntervention(t, id, WAIT_POLL, opts);
+    if (isInterventionSettled(i)) return i;
+    opts.signal?.throwIfAborted();
+  }
+}
+function getIntervention(t, id, wait, opts) {
+  requireArg(id, "intervention id");
+  return t.json("GET", `/v1/interventions/${encodeURIComponent(id)}`, {
+    query: { wait },
+    signal: opts.signal
+  });
+}
+
+// src/gates.ts
+async function settleHeld(t, held, o, opts) {
+  const onHeld = o.onHeld ?? t.onHeld;
+  onHeld?.(held);
+  if (o.wait === false || t.hitlNoWait) throw new PendingInterventionError(held);
+  const i = await waitIntervention(t, held.id, opts);
+  if (!isInterventionApproved(i)) throw new InterventionRejectedError(i);
+  if (i.result?.error) throw new HeldActionError(i);
+  return i;
+}
+
+// src/takeover.ts
+async function retryLocked(t, call, wait, opts) {
+  for (; ; ) {
+    try {
+      return await call();
+    } catch (err) {
+      if (wait === false || !isLocked(err) || !err.interventionId) throw err;
+      await waitIntervention(t, err.interventionId, opts);
+      opts.signal?.throwIfAborted();
+    }
+  }
+}
+
+// src/environments.ts
+var MAX_PAGE_LIMIT2 = 200;
 var EnvironmentsService = class {
   constructor(t) {
     this.t = t;
@@ -380,7 +780,7 @@ var EnvironmentsService = class {
     let cursor = options.cursor;
     for (; ; ) {
       const page = await this.listPage(
-        { ...options, limit: MAX_PAGE_LIMIT, cursor },
+        { ...options, limit: MAX_PAGE_LIMIT2, cursor },
         opts
       );
       out.push(...page.environments);
@@ -419,14 +819,18 @@ var EnvironmentsService = class {
       signal: opts.signal
     });
   }
-  /** Fork an environment into a new one; returns the new environment. */
+  /** Fork an environment into a new one; returns the new environment. When a
+   * hitl gate holds the fork, it waits for the decision and returns the
+   * environment the orchestrator then forked. */
   async fork(vmId, body = {}, opts = {}) {
     requireArg(vmId, "vm id");
-    return this.t.json(
+    const out = await this.t.gated(
       "POST",
       `/v1/environments/${encodeURIComponent(vmId)}`,
       { query: { action: "fork" }, body, signal: opts.signal }
     );
+    if (!out.held) return out.value;
+    return this.heldEnvironment(out.held, opts);
   }
   /**
    * Migrate an environment to another host; returns the new environment. The
@@ -434,11 +838,22 @@ var EnvironmentsService = class {
    */
   async migrate(vmId, body = {}, opts = {}) {
     requireArg(vmId, "vm id");
-    return this.t.json(
+    const out = await this.t.gated(
       "POST",
       `/v1/environments/${encodeURIComponent(vmId)}`,
       { query: { action: "migrate" }, body, signal: opts.signal }
     );
+    if (!out.held) return out.value;
+    return this.heldEnvironment(out.held, opts);
+  }
+  /** heldEnvironment waits out a held fork or migrate and returns the
+   * environment it produced. */
+  async heldEnvironment(held, opts) {
+    const i = await settleHeld(this.t, held, {}, opts);
+    if (!i.result?.env_id) {
+      throw new FuseError(`intervention ${i.id} settled without an environment`);
+    }
+    return this.get(i.result.env_id, opts);
   }
   /**
    * Run a command inside a running environment's guest and return its exit code
@@ -449,6 +864,16 @@ var EnvironmentsService = class {
    *
    * Exec requires the master token.
    *
+   * When a hitl gate holds the exec, exec waits for the decision (bounded
+   * only by `opts.signal`); the orchestrator runs the approved (possibly
+   * edited) argv and exec returns its result. A rejection throws an
+   * InterventionRejectedError, a deny gate an error isHitlDenied matches.
+   * `wait: false` throws a PendingInterventionError at once instead.
+   *
+   * While a human holds a takeover (or an ask-mode stall is pending) the
+   * server answers 423; exec waits for that intervention to settle and runs
+   * the command then. `wait: false` throws a LockedError at once instead.
+   *
    * @example
    * const out = await client.environments.exec(id, { cmd: ["ls", "-l"] });
    * if (out.exit_code !== 0) console.error(out.stderr);
@@ -463,11 +888,23 @@ var EnvironmentsService = class {
     if (hasCmd && hasShell) {
       throw new FuseError("cmd and shell are mutually exclusive");
     }
-    return this.t.json(
-      "POST",
-      `/v1/environments/${encodeURIComponent(vmId)}`,
-      { query: { action: "exec" }, body, signal: opts.signal }
+    const { wait, onHeld, ...wire } = body;
+    const out = await retryLocked(
+      this.t,
+      () => this.t.gated("POST", `/v1/environments/${encodeURIComponent(vmId)}`, {
+        query: { action: "exec" },
+        body: wire,
+        signal: opts.signal
+      }),
+      wait,
+      opts
     );
+    if (!out.held) return out.value;
+    const i = await settleHeld(this.t, out.held, { wait, onHeld }, opts);
+    if (!i.result?.exec) {
+      throw new FuseError(`intervention ${i.id} settled without an exec result`);
+    }
+    return i.result.exec;
   }
   /**
    * Relay one computer-use action to the environment's desktop and return the
@@ -475,6 +912,13 @@ var EnvironmentsService = class {
    * booted from a desktop image; on any other image the server answers 503
    * with a reason.
    *
+   * Like exec, it waits out a takeover or a pending stall (a 423) and then
+   * acts; `opts.wait: false` throws a LockedError at once instead. When a
+   * computer gate holds the action (a 202), it waits for the decision and
+   * returns what the orchestrator got performing it (with the human's edited
+   * text, if any); a rejection throws an InterventionRejectedError, and
+   * `opts.wait: false` throws a PendingInterventionError at once instead.
+   *
    * @example
    * const res = await client.environments.computer(id, {
    *   action: "left_click",
@@ -484,11 +928,7 @@ var EnvironmentsService = class {
   async computer(vmId, action, opts = {}) {
     requireArg(vmId, "vm id");
     requireArg(action?.action, "action");
-    return this.t.json(
-      "POST",
-      `/v1/environments/${encodeURIComponent(vmId)}/computer`,
-      { body: action, signal: opts.signal }
-    );
+    return this.postComputer(vmId, action, opts);
   }
   /**
    * Execute one computer tool_use against the environment and shape the
@@ -499,7 +939,7 @@ var EnvironmentsService = class {
    * An action the environment refuses (a malformed coordinate, a display
    * that is not up) resolves to `is_error` content rather than throwing: the
    * agent loop should feed it to the model, which is the party that can
-   * correct it. A throw is reserved for failures the model cannot fix —
+   * correct it. So does a hitl deny gate or a human rejecting a held action. A throw is reserved for failures the model cannot fix —
    * transport, auth, an unknown environment.
    *
    * @example
@@ -521,18 +961,22 @@ var EnvironmentsService = class {
     }
     let res;
     try {
-      res = await this.t.json(
-        "POST",
-        `/v1/environments/${encodeURIComponent(vmId)}/computer`,
-        { body: input, signal: opts.signal }
-      );
+      res = await this.postComputer(vmId, input, opts);
     } catch (err) {
-      if (isFuseApiError(err) && (err.status === 400 || err.status === 409 || err.status === 503)) {
+      if (isFuseApiError(err) && (err.status === 400 || err.status === 409 || err.status === 503 || isHitlDenied(err))) {
         return {
           is_error: true,
           content: [{ type: "text", text: err.message || "the computer action failed" }]
         };
       }
+      if (err instanceof InterventionRejectedError) {
+        return {
+          is_error: true,
+          content: [
+            { type: "text", text: `a human rejected this action: ${err.message}` }
+          ]
+        };
+      }
       throw err;
     }
     const content = [];
@@ -550,6 +994,137 @@ var EnvironmentsService = class {
     if (content.length === 0) content.push({ type: "text", text: "done" });
     return { content };
   }
+  async postComputer(vmId, body, opts) {
+    const out = await retryLocked(
+      this.t,
+      () => this.t.gated(
+        "POST",
+        `/v1/environments/${encodeURIComponent(vmId)}/computer`,
+        { body, signal: opts.signal }
+      ),
+      opts.wait,
+      opts
+    );
+    if (!out.held) return out.value;
+    const i = await settleHeld(
+      this.t,
+      out.held,
+      { wait: opts.wait, onHeld: opts.onHeld },
+      opts
+    );
+    if (!i.result?.computer) {
+      throw new FuseError(`intervention ${i.id} settled without a computer result`);
+    }
+    return i.result.computer;
+  }
+  /**
+   * Ask a human for something the environment's hitl policy declares. By
+   * default it waits (by long-polling) until the intervention resolves
+   * (answered, rejected, expired or cancelled); read the result off the
+   * returned intervention's decision. Pass `wait: false` to get the pending
+   * handle instead. Pass `opts.signal` to stop waiting early.
+   *
+   * @example
+   * const res = await client.environments.requestHuman(id, {
+   *   question: "deploy to prod?",
+   *   choices: ["yes", "no"],
+   * });
+   * if (isInterventionApproved(res)) console.log(res.decision?.answer);
+   */
+  async requestHuman(vmId, req, opts = {}) {
+    requireArg(vmId, "vm id");
+    const pending = await this.t.json(
+      "POST",
+      `/v1/environments/${encodeURIComponent(vmId)}`,
+      {
+        query: { action: "request" },
+        body: {
+          kind: req.kind || "ask",
+          question: req.question || void 0,
+          choices: req.choices,
+          target: req.target || void 0,
+          message: req.message || void 0,
+          via: req.via || void 0,
+          reason: req.reason || void 0,
+          path: req.path || void 0,
+          content: req.content || void 0,
+          format: req.format || void 0,
+          timeout_seconds: req.timeoutSeconds || void 0
+        },
+        signal: opts.signal
+      }
+    );
+    if (req.wait === false) return pending;
+    return waitIntervention(this.t, pending.id, opts);
+  }
+  /**
+   * Submit a guest file or a text/diff blob for a human to approve or reject
+   * with comments, and wait for the verdict. Needs hitl.requests.review.
+   * With `wait: false` it returns at once with the pending intervention and
+   * approved false.
+   *
+   * @example
+   * const r = await client.environments.requestReview(id, {
+   *   content: diff,
+   *   format: ReviewFormat.Diff,
+   * });
+   * if (!r.approved) console.log(r.comments);
+   */
+  async requestReview(vmId, req, opts = {}) {
+    const i = await this.requestHuman(
+      vmId,
+      {
+        kind: HitlKind.Review,
+        path: req.path,
+        content: req.content,
+        format: req.format,
+        message: req.message,
+        timeoutSeconds: req.timeoutSeconds,
+        wait: req.wait
+      },
+      opts
+    );
+    return {
+      approved: isInterventionApproved(i),
+      comments: i.decision?.reason ?? "",
+      intervention: i
+    };
+  }
+  /**
+   * Take over the environment as a human: claims the agent's pending
+   * takeover request if there is one, else opens a new one. While held, the
+   * agent's exec and computer calls wait. Returns the held intervention.
+   * Needs the hitl:takeover scope; a conflict when someone else holds it.
+   */
+  async takeover(vmId, body = {}, opts = {}) {
+    requireArg(vmId, "vm id");
+    return this.t.json(
+      "POST",
+      `/v1/environments/${encodeURIComponent(vmId)}`,
+      {
+        query: { action: "takeover" },
+        body: { via: body.via || void 0, reason: body.reason || void 0 },
+        signal: opts.signal
+      }
+    );
+  }
+  /**
+   * End a takeover and hand the environment back to the agent. The note is
+   * the takeover's answer. Returns the approved intervention; a conflict when
+   * nothing is held.
+   */
+  async release(vmId, body = {}, opts = {}) {
+    requireArg(vmId, "vm id");
+    return this.t.json(
+      "POST",
+      `/v1/environments/${encodeURIComponent(vmId)}`,
+      {
+        query: { action: "release" },
+        body: { note: body.note || void 0 },
+        signal: opts.signal
+      }
+    );
+  }
   /** Report whether the environment has a live display and at what geometry.
    * up is false with a reason on an image with no desktop. */
   async computerDisplay(vmId, opts = {}) {
@@ -563,31 +1138,42 @@ var EnvironmentsService = class {
   /**
    * Phase-1 only: quiesces the guest workload and moves the environment to
    * "draining" so you can inspect its output, but does not destroy it. Call
-   * destroy() afterward to remove it - a drained environment left
-   * undestroyed keeps running (and billing) forever.
+   * destroy() afterward to remove it. A drained environment left
+   * undestroyed keeps running (and billing) until the orchestrator's
+   * draining timeout (5m30s by default) passes, and then the orchestrator
+   * destroys it.
    */
   async drain(vmId, opts = {}) {
     requireArg(vmId, "vm id");
-    return this.t.json(
+    const out = await this.t.gated(
       "POST",
       `/v1/environments/${encodeURIComponent(vmId)}`,
       { query: { action: "drain" }, signal: opts.signal }
     );
+    if (!out.held) return out.value;
+    await settleHeld(this.t, out.held, {}, opts);
+    return this.get(vmId, opts);
   }
   /** Rotate the per-VM credentials and push them to the guest. */
   async rotateToken(vmId, opts = {}) {
     requireArg(vmId, "vm id");
-    await this.t.noContent("POST", `/v1/environments/${encodeURIComponent(vmId)}`, {
-      query: { action: "rotate-token" },
-      signal: opts.signal
-    });
+    const held = await this.t.gatedNoContent(
+      "POST",
+      `/v1/environments/${encodeURIComponent(vmId)}`,
+      { query: { action: "rotate-token" }, signal: opts.signal }
+    );
+    if (held) await settleHeld(this.t, held, {}, opts);
   }
-  /** Forcefully destroy an environment. Idempotent. */
+  /** Forcefully destroy an environment. Idempotent. When a hitl gate holds
+   * the destroy, it waits for the decision. */
   async destroy(vmId, opts = {}) {
     requireArg(vmId, "vm id");
-    await this.t.noContent("DELETE", `/v1/environments/${encodeURIComponent(vmId)}`, {
-      signal: opts.signal
-    });
+    const held = await this.t.gatedNoContent(
+      "DELETE",
+      `/v1/environments/${encodeURIComponent(vmId)}`,
+      { signal: opts.signal }
+    );
+    if (held) await settleHeld(this.t, held, {}, opts);
   }
   /**
    * Open the SSE event stream for an environment. The returned promise rejects
@@ -608,7 +1194,7 @@ var EnvironmentsService = class {
 };
 
 // src/snapshots.ts
-var MAX_PAGE_LIMIT2 = 200;
+var MAX_PAGE_LIMIT3 = 200;
 var SnapshotsService = class {
   constructor(t) {
     this.t = t;
@@ -623,14 +1209,23 @@ var SnapshotsService = class {
    * be `"disk"` even for a `live: true` request that reached a host too old to
    * honour it. A caller that depends on the memory being there should check
    * it. `live: true` against a backend with no live-snapshot support throws a
-   * 501 `unimplemented`, not a conflict. */
+   * 501 `unimplemented`, not a conflict.
+   *
+   * When a hitl gate holds the snapshot, create waits for the decision and
+   * returns the snapshot the orchestrator then took. */
   async create(vmId, body = {}, opts = {}) {
     requireArg(vmId, "vm id");
-    return this.t.json(
+    const out = await this.t.gated(
       "POST",
       `/v1/environments/${encodeURIComponent(vmId)}/snapshots`,
       { body, signal: opts.signal }
     );
+    if (!out.held) return out.value;
+    const i = await settleHeld(this.t, out.held, {}, opts);
+    if (!i.result?.snapshot_id) {
+      throw new FuseError(`intervention ${i.id} settled without a snapshot`);
+    }
+    return this.get(i.result.snapshot_id, opts);
   }
   /** List snapshots, optionally filtered. Transparently walks every result
    * page. For explicit single-page control (e.g. a cursor from a previous
@@ -640,7 +1235,7 @@ var SnapshotsService = class {
     let cursor = options.cursor;
     for (; ; ) {
       const page = await this.listPage(
-        { ...options, limit: MAX_PAGE_LIMIT2, cursor },
+        { ...options, limit: MAX_PAGE_LIMIT3, cursor },
         opts
       );
       out.push(...page.snapshots);
@@ -718,7 +1313,7 @@ var SnapshotsService = class {
 };
 
 // src/hosts.ts
-var MAX_PAGE_LIMIT3 = 200;
+var MAX_PAGE_LIMIT4 = 200;
 var HostsService = class {
   constructor(t) {
     this.t = t;
@@ -735,7 +1330,7 @@ var HostsService = class {
     const out = [];
     let cursor;
     for (; ; ) {
-      const page = await this.listPage({ limit: MAX_PAGE_LIMIT3, cursor }, opts);
+      const page = await this.listPage({ limit: MAX_PAGE_LIMIT4, cursor }, opts);
       out.push(...page.hosts);
       if (!page.nextCursor) break;
       cursor = page.nextCursor;
@@ -791,12 +1386,19 @@ var ApiKeysService = class {
   }
   t;
   /**
-   * Issue a new API key. The raw secret is returned once in `key` and is
-   * unrecoverable afterward.
+   * Issue a new API key. Pass a label, or options for a scoped key. The raw
+   * secret is returned once in `key` and is unrecoverable afterward.
    */
-  async create(label, opts = {}) {
+  async create(labelOrOptions, opts = {}) {
+    const o = typeof labelOrOptions === "string" ? { label: labelOrOptions } : labelOrOptions ?? {};
     return this.t.json("POST", "/v1/api-keys", {
-      body: label ? { label } : {},
+      body: {
+        label: o.label || void 0,
+        scopes: o.scopes,
+        env_id: o.envId || void 0,
+        ttl_seconds: o.ttlSeconds || void 0,
+        actor: o.actor
+      },
       signal: opts.signal
     });
   }
@@ -817,15 +1419,18 @@ var ApiKeysService = class {
 };
 
 // src/version.ts
-var VERSION = "0.36.0";
+var VERSION = "0.41.0";
 
 // src/client.ts
-var FuseClient = class {
+var FuseClient = class _FuseClient {
   environments;
   snapshots;
   hosts;
   apiKeys;
+  interventions;
+  options;
   constructor(options) {
+    this.options = options;
     const transport = new Transport({
       baseUrl: options.baseUrl,
       token: options.token,
@@ -833,15 +1438,26 @@ var FuseClient = class {
       userAgent: options.userAgent ?? `fuse-ts/${VERSION}`,
       requestId: options.requestId,
       timeoutMs: options.timeoutMs,
-      headers: options.headers
+      headers: options.headers,
+      actor: options.actor,
+      hitlNoWait: options.hitlNoWait,
+      onHeld: options.onHeld
     });
     this.environments = new EnvironmentsService(transport);
     this.snapshots = new SnapshotsService(transport);
     this.hosts = new HostsService(transport);
     this.apiKeys = new ApiKeysService(transport);
+    this.interventions = new InterventionsService(transport);
+  }
+  /**
+   * withActor returns a copy of this client, with the same options otherwise,
+   * that sends `actor` as the Fuse-Actor headers. This client is unchanged.
+   */
+  withActor(actor) {
+    return new _FuseClient({ ...this.options, actor });
   }
 };
 
-export { ApiKeysService, EnvironmentsService, ErrorCode, FuseApiError, FuseClient, FuseError, HealthState, HostsService, SnapshotsService, State, VERSION, isConflict, isFuseApiError, isInvalidArgument, isNotFound, isTerminalState, isUnauthorized, isUnavailable };
+export { ACTOR_SOURCE_DECIDER, ALLOWLIST_GATE, ApiKeysService, AuditEvent, DeciderVerdict, EnvironmentsService, ErrorCode, ForbiddenError, ForbiddenReason, FuseApiError, FuseClient, FuseError, GateMode, HealthState, HeldActionError, HitlKind, HitlScope, HostsService, InterventionOutcome, InterventionRejectedError, InterventionState, InterventionsService, LifecycleAction, LockedError, PendingInterventionError, ReviewFormat, SnapshotsService, State, TakeoverVia, VERSION, isConflict, isForbidden, isFuseApiError, isHitlDenied, isInterventionApproved, isInterventionSettled, isInterventionTerminal, isInvalidArgument, isLocked, isNotFound, isTerminalState, isUnauthorized, isUnavailable };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map