auto-harness-client 0.1.0 → 0.4.0

package/README.md

@@ -9,13 +9,125 @@ import { AutoHarnessClient } from "auto-harness-client";
 const harness = new AutoHarnessClient({
   baseUrl: process.env.AUTO_HARNESS_URL,
   apiKey: process.env.AUTO_HARNESS_API_KEY,
+  requestTimeoutMs: 30_000,
 });
 
 const session = await harness.createSession({
   repositoryId: "repo-1",
   prompt: "Review the latest changes",
   target: { providerId: "codex" },
+  timeout: 1_800,
   concurrencyId: `github-${process.env.GITHUB_RUN_ID}`,
 });
 console.log(session.url);
 ```
+
+## Target by provider or command name
+
+`target` and `fallbacks` accept a `providerId`/`commandId` as before, or a human-readable
+`providerName`/`commandName`. `createSession()` resolves each name to an id via
+`listProviders()`/`listCommands()` before sending the request — at most one list call per catalog,
+regardless of how many refs need it, and none at all when every ref is already id-based.
+
+```js
+const session = await harness.createSession({
+  repositoryId: "repo-1",
+  prompt: "Review the latest changes",
+  target: { providerName: "codex" },
+  fallbacks: [{ commandName: "claude-print-plan" }],
+  timeout: 1_800,
+});
+```
+
+Provider names are normally unique — server-enforced on create/update — but that check is a
+read-then-write race, not an atomic constraint, so `providerName` resolution still checks for
+more than one match rather than trusting uniqueness. Command names are **not** server-enforced
+unique at all. Either way, an unresolvable or ambiguous name throws `AutoHarnessError`
+(`code === "UNKNOWN_PROVIDER_NAME"`, `"UNKNOWN_COMMAND_NAME"`, `"AMBIGUOUS_PROVIDER_NAME"`, or
+`"AMBIGUOUS_COMMAND_NAME"`); the ambiguous-name message never includes the matched ids.
+
+## Request deadlines
+
+Every request has a deadline that includes receiving and consuming the JSON response body.
+`requestTimeoutMs` defaults to `30_000` and must be a finite positive number no greater than
+`300_000`. On expiry, the client throws `AutoHarnessRequestTimeoutError`, with
+`code === "REQUEST_TIMEOUT"` and the configured `timeoutMs`. The client never retries requests
+automatically; reuse an idempotency key where an ambiguous `POST` may safely be retried.
+
+## Repository listing
+
+Repository listings are bounded pages. Pass the returned cursor to load the next page:
+
+```js
+let page = await harness.listRepositories({ limit: 50 });
+const repositories = [...page.items];
+while (page.nextCursor) {
+  page = await harness.listRepositories({ limit: 50, cursor: page.nextCursor });
+  repositories.push(...page.items);
+}
+```
+
+## Principal session drains
+
+Cancels this principal's own queued and running sessions for one repository, then fences new
+admission from that same principal until the fence is explicitly released. **Not** repository
+drain or host drain — see
+[Principal session drains](https://github.com/jonathanong/auto-harness/blob/main/docs/api.md#principal-session-drains)
+for the full disambiguation and server-side guarantees. Use a stable idempotency key when retries
+may be ambiguous, poll the durable operation, and release the fence explicitly only after
+recording its terminal result.
+
+```js
+const drain = await harness.startSessionDrain("repo-1", {
+  idempotencyKey: `deploy-${process.env.GITHUB_RUN_ID}`,
+});
+
+let progress = drain;
+while (progress.status === "draining") {
+  await new Promise((resolve) => setTimeout(resolve, 5_000));
+  progress = await harness.getSessionDrain("repo-1", drain.operationId);
+}
+const failed = progress.status !== "succeeded";
+if (failed) console.error(`Drain failed: ${progress.failureCode}`);
+await harness.releaseSessionDrain("repo-1", drain.operationId);
+if (failed) throw new Error(`Drain failed: ${progress.failureCode}`);
+```
+
+When create, clone, or resume loses to the fence, `AutoHarnessError` has `code === "DRAINING"`
+plus the durable `operationId` and API-relative `statusUrl`; follow that operation rather than
+reimplementing pagination or cancellation reconciliation.
+
+## Resume a session
+
+Resume re-runs a previously assigned session. It initially prefers the source host and its stored
+native command/account route, using a native CLI resume where the provider supports it. If that
+route becomes unavailable or its pin expires, the control plane clears the pin and falls back to a
+fresh run through the normal target/fallback chain, which may land on another host. The source
+session must have been assigned at least once, must not still be queued or running, and must not
+be a scheduled session — sessions with `type: "scheduled"` are rejected with `409 CONFLICT`, since
+only prompt sessions support resume.
+
+```js
+const resumed = await harness.resumeSession("session-1", { prompt: "Address the review comments" });
+console.log(resumed.status);
+```
+
+## List sessions
+
+Session listings are bounded pages with the same cursor shape as repository listings, plus
+filters for status, repository, host, origin, sort order, concurrency identity, and schedule
+provenance:
+
+```js
+let page = await harness.listSessions({ repositoryId: "repo-1", status: "running", limit: 50 });
+const sessions = [...page.items];
+while (page.nextCursor) {
+  page = await harness.listSessions({
+    repositoryId: "repo-1",
+    status: "running",
+    limit: 50,
+    cursor: page.nextCursor,
+  });
+  sessions.push(...page.items);
+}
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-harness-client",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "Dependency-free client for the Auto Harness automation API",
   "repository": {
     "type": "git",

package/src/errors.js

@@ -0,0 +1,20 @@
+export class AutoHarnessError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = "AutoHarnessError";
+    this.status = options.status;
+    this.code = options.code;
+    this.retryAfter = options.retryAfter;
+    this.operationId = options.operationId;
+    this.statusUrl = options.statusUrl;
+  }
+}
+
+export class AutoHarnessRequestTimeoutError extends Error {
+  constructor(timeoutMs) {
+    super(`Auto Harness request timed out after ${timeoutMs}ms`);
+    this.name = "AutoHarnessRequestTimeoutError";
+    this.code = "REQUEST_TIMEOUT";
+    this.timeoutMs = timeoutMs;
+  }
+}

package/src/index.d.ts

@@ -2,53 +2,262 @@ export type TargetRef =
   | { commandId: string; providerId?: never }
   | { providerId: string; commandId?: never };
 
+/** A provider target, by id or by `name` — normally unique, checked defensively either way. */
+export type ProviderRef =
+  | { providerId: string; providerName?: never; commandId?: never; commandName?: never }
+  | { providerName: string; providerId?: never; commandId?: never; commandName?: never };
+
+/** A command target, by id or by `name` — command names are not required to be unique. */
+export type CommandRef =
+  | { commandId: string; commandName?: never; providerId?: never; providerName?: never }
+  | { commandName: string; commandId?: never; providerId?: never; providerName?: never };
+
+/**
+ * Input-only target shape for `createSession()`: an id (as `TargetRef`) or a name.
+ * `createSession()` resolves a name to its id via `listProviders()`/`listCommands()` before
+ * sending the request; a name throws on no match or on more than one match sharing that name.
+ */
+export type TargetSpec = ProviderRef | CommandRef;
+
+/** Values accepted for a session metadata entry. */
+export type SessionMetadataValue = string | number | boolean | null;
+
+/** Whether a session was created directly or fired by a schedule. */
+export type SessionType = "prompt" | "scheduled";
+
+/** Origin that requested the session. */
+export type SessionSource = "api" | "ui" | "webhook" | "schedule";
+
+/** `source` values `POST /sessions` honors; anything else collapses to `"api"`. */
+export type CreatableSessionSource = "api" | "ui" | "webhook";
+
 export type CreateSessionInput = {
   repositoryId: string;
   prompt: string;
-  target: TargetRef;
-  fallbacks?: TargetRef[];
+  target: TargetSpec;
+  fallbacks?: TargetSpec[];
   ref?: string;
   concurrencyId?: string;
   queueTtlSeconds?: number;
-  timeout?: number;
+  timeout: number;
   priority?: number;
   requiredLabels?: string[];
-  metadata?: Record<string, unknown>;
+  metadata?: Record<string, SessionMetadataValue>;
+  /** Defaults to `"api"`; `"ui"`/`"webhook"` pass through, anything else becomes `"api"`. */
+  source?: CreatableSessionSource;
 };
 
-export type Session = CreateSessionInput & {
+export type Session = {
   id: string;
+  repositoryId: string;
+  prompt: string;
+  target: TargetRef;
+  fallbacks?: TargetRef[];
+  ref?: string;
+  concurrencyId?: string;
+  queueTtlSeconds?: number;
+  timeout?: number;
+  priority?: number;
+  requiredLabels?: string[];
+  metadata?: Record<string, SessionMetadataValue>;
   status: string;
+  /** Absent on sessions persisted before this field existed. */
+  type?: SessionType;
+  /** Absent on sessions persisted before this field existed. */
+  source?: SessionSource;
   createdAt: string;
   url: string;
   created?: boolean;
 };
 
+/** Body accepted by `POST /sessions/:id/resume`. */
+export type ResumeSessionInput = {
+  prompt?: string;
+  concurrencyId?: string;
+  timeout?: number;
+  priority?: number;
+};
+
+/** `status` filter accepted by `GET /sessions`. */
+export type SessionStatusFilter =
+  | "all"
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed_out";
+
+export type SessionListSort = "latest" | "oldest" | "priority_desc" | "priority_asc";
+
+export type ListSessionsOptions = {
+  status?: SessionStatusFilter;
+  repositoryId?: string;
+  hostId?: string;
+  source?: SessionSource;
+  sort?: SessionListSort;
+  /** Number of sessions to return (1–100, default 50). */
+  limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
+  concurrencyId?: string;
+  scheduleId?: string;
+};
+
+export type SessionPage = {
+  items: Session[];
+  nextCursor: string | null;
+};
+
 export type Repository = {
   id: string;
   name: string;
   url: string;
   defaultBranch: string;
+  createdAt?: string;
+  updatedAt?: string;
+  sessionCount?: number;
+  worktreeCount?: number;
+  scheduleCount?: number;
   admissionState?: "active" | "paused" | "draining";
   admissionStateChangedAt?: string;
   drainRequestedAt?: string;
   drainCompletedAt?: string;
 };
 
+export type ListRepositoriesOptions = {
+  /** Number of repositories to return (1–100, default 50). */
+  limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
+};
+
+export type RepositoryPage = {
+  items: Repository[];
+  nextCursor: string | null;
+};
+
+/** Operator-supplied per-token vendor rates; Auto Harness never fetches vendor prices. */
+export type UsageRates = {
+  inputTokenMicros?: string;
+  outputTokenMicros?: string;
+  cachedInputTokenMicros?: string;
+  reasoningTokenMicros?: string;
+  currency: string;
+};
+
+/** Global catalog entry: an AI CLI vendor, keyed by a unique, server-enforced `name`. */
+export type Provider = {
+  id: string;
+  /** e.g. "claude", "codex", "grok" */
+  name: string;
+  defaultCommandId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  usageRates?: UsageRates;
+};
+
+/** Bounded literal-prefix policy used by the agent to extract a native resume reference. */
+export type ResumeRefCapture = {
+  stream: "stdout" | "stderr" | "either";
+  linePrefix: string;
+};
+
+/** Global catalog entry: a named command invocation. `name` is not required to be unique. */
+export type Command = {
+  id: string;
+  /** e.g. "claude-print", "echo hello world" */
+  name: string;
+  argv: string[];
+  appendPrompt: boolean;
+  appendPromptSeparator?: boolean;
+  resumeArgvTemplate?: string[];
+  resumeRefCapture?: ResumeRefCapture;
+  /** FK to Provider, or null for a standalone command that runs anywhere ungated. */
+  providerId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type SessionDrainStatus = "draining" | "succeeded" | "failed" | "released";
+
+/** Bounded, durable progress for a principal session drain: cancels the authenticated principal's own queued/running sessions for one repository (not repository or host drain). */
+export type SessionDrain = {
+  operationId: string;
+  repositoryId: string;
+  status: SessionDrainStatus;
+  /** API-relative URL for polling this same operation. */
+  statusUrl: string;
+  requestedAt: string;
+  updatedAt: string;
+  deadlineAt: string;
+  queuedCount: number;
+  runningCount: number;
+  cancelledCount: number;
+  completedAt?: string;
+  releasedAt?: string;
+  failureCode?: string;
+};
+
+/**
+ * Thrown for a failed HTTP response, and also, with `status: 400`, when `createSession()`
+ * cannot resolve a `TargetSpec` name: `code === "UNKNOWN_PROVIDER_NAME"` /
+ * `"UNKNOWN_COMMAND_NAME"` for no match, `"AMBIGUOUS_PROVIDER_NAME"` /
+ * `"AMBIGUOUS_COMMAND_NAME"` for more than one match sharing a name — that message never
+ * includes the matched ids.
+ */
 export class AutoHarnessError extends Error {
   status: number;
   code: string;
   retryAfter?: string;
-  constructor(message: string, options: { status: number; code: string; retryAfter?: string });
+  /** Present when a 409 DRAINING admission response identifies its durable drain. */
+  operationId?: string;
+  /** API-relative URL for the drain that fenced this request. */
+  statusUrl?: string;
+  constructor(
+    message: string,
+    options: {
+      status: number;
+      code: string;
+      retryAfter?: string;
+      operationId?: string;
+      statusUrl?: string;
+    },
+  );
 }
 
+export class AutoHarnessRequestTimeoutError extends Error {
+  code: "REQUEST_TIMEOUT";
+  timeoutMs: number;
+  constructor(timeoutMs: number);
+}
+
+export type AutoHarnessClientOptions = {
+  baseUrl: string;
+  apiKey?: string;
+  fetch?: typeof fetch;
+  /** Per-request deadline in milliseconds (default 30,000; maximum 300,000). */
+  requestTimeoutMs?: number;
+};
+
 export class AutoHarnessClient {
-  constructor(options: { baseUrl: string; apiKey?: string; fetch?: typeof fetch });
+  constructor(options: AutoHarnessClientOptions);
   createSession(input: CreateSessionInput): Promise<Session & { created: boolean }>;
   getSession(id: string): Promise<Session>;
   cancelSession(id: string): Promise<Session>;
-  listRepositories(): Promise<{ items: Repository[] }>;
+  resumeSession(id: string, input?: ResumeSessionInput): Promise<Session & { created: boolean }>;
+  listSessions(options?: ListSessionsOptions): Promise<SessionPage>;
+  /** Cancels this principal's own queued/running sessions for one repository and fences new admission from it — not repository or host drain. */
+  startSessionDrain(
+    repositoryId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SessionDrain>;
+  getSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
+  releaseSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
+  listRepositories(options?: ListRepositoriesOptions): Promise<RepositoryPage>;
   pauseRepository(id: string): Promise<Repository>;
   drainRepository(id: string): Promise<Repository>;
   activateRepository(id: string): Promise<Repository>;
+  listProviders(): Promise<Provider[]>;
+  listCommands(): Promise<Command[]>;
 }

package/src/index.js

@@ -1,44 +1,76 @@
-export class AutoHarnessError extends Error {
-  constructor(message, options) {
-    super(message);
-    this.name = "AutoHarnessError";
-    this.status = options.status;
-    this.code = options.code;
-    this.retryAfter = options.retryAfter;
-  }
-}
+import { AutoHarnessError, AutoHarnessRequestTimeoutError } from "./errors.js";
+import { resolveCreateSessionTargets } from "./resolve-target.js";
+
+export { AutoHarnessError, AutoHarnessRequestTimeoutError };
 
 export class AutoHarnessClient {
   constructor(options) {
     if (!options?.baseUrl) throw new TypeError("baseUrl is required");
+    const requestTimeoutMs =
+      options.requestTimeoutMs === undefined ? 30_000 : options.requestTimeoutMs;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0 || requestTimeoutMs > 300_000) {
+      throw new TypeError(
+        "requestTimeoutMs must be a finite positive number no greater than 300000",
+      );
+    }
     this.baseUrl = options.baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
     this.apiKey = options.apiKey;
     this.fetch = options.fetch ?? globalThis.fetch;
     if (!this.fetch) throw new TypeError("fetch is required");
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   async request(path, init = {}) {
     const headers = { accept: "application/json", ...init.headers };
     if (init.body !== undefined) headers["content-type"] = "application/json";
     if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
-    const response = await this.fetch(`${this.baseUrl}/api/v1${path}`, { ...init, headers });
-    const body = response.status === 204 ? undefined : await response.json().catch(() => undefined);
-    if (!response.ok) {
-      const error = body?.error;
-      throw new AutoHarnessError(
-        error?.message ?? `Auto Harness request failed (${response.status})`,
-        {
-          status: response.status,
-          code: error?.code ?? "HTTP_ERROR",
-          retryAfter: response.headers.get("retry-after") ?? undefined,
-        },
-      );
+    const controller = new AbortController();
+    const timeoutError = new AutoHarnessRequestTimeoutError(this.requestTimeoutMs);
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        controller.abort();
+        reject(timeoutError);
+      }, this.requestTimeoutMs);
+    });
+    const request = (async () => {
+      const response = await this.fetch(`${this.baseUrl}/api/v1${path}`, {
+        ...init,
+        headers,
+        signal: controller.signal,
+      });
+      const body =
+        response.status === 204
+          ? undefined
+          : await response.json().catch((error) => {
+              if (controller.signal.aborted) throw error;
+              return undefined;
+            });
+      if (!response.ok) {
+        const error = body?.error;
+        throw new AutoHarnessError(
+          error?.message ?? `Auto Harness request failed (${response.status})`,
+          {
+            status: response.status,
+            code: error?.code ?? "HTTP_ERROR",
+            retryAfter: response.headers.get("retry-after") ?? undefined,
+            operationId: error?.operationId,
+            statusUrl: error?.statusUrl,
+          },
+        );
+      }
+      return body;
+    })();
+    try {
+      return await Promise.race([request, timeout]);
+    } finally {
+      clearTimeout(timeoutId);
     }
-    return body;
   }
 
-  createSession(input) {
-    return this.request("/sessions", { method: "POST", body: JSON.stringify(input) });
+  async createSession(input) {
+    const body = await resolveCreateSessionTargets(this, input);
+    return this.request("/sessions", { method: "POST", body: JSON.stringify(body) });
   }
 
   getSession(id) {
@@ -49,8 +81,63 @@ export class AutoHarnessClient {
     return this.request(`/sessions/${encodeURIComponent(id)}/cancel`, { method: "POST" });
   }
 
-  listRepositories() {
-    return this.request("/repositories");
+  /** Resume a previously assigned session on its pinned host, native CLI resume where supported. */
+  resumeSession(id, input) {
+    return this.request(`/sessions/${encodeURIComponent(id)}/resume`, {
+      method: "POST",
+      ...(input === undefined ? {} : { body: JSON.stringify(input) }),
+    });
+  }
+
+  listSessions(options = {}) {
+    const query = new URLSearchParams();
+    if (options.status !== undefined) query.set("status", options.status);
+    if (options.repositoryId !== undefined) query.set("repositoryId", options.repositoryId);
+    if (options.hostId !== undefined) query.set("hostId", options.hostId);
+    if (options.source !== undefined) query.set("source", options.source);
+    if (options.sort !== undefined) query.set("sort", options.sort);
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    if (options.concurrencyId !== undefined) query.set("concurrencyId", options.concurrencyId);
+    if (options.scheduleId !== undefined) query.set("scheduleId", options.scheduleId);
+    const suffix = query.toString();
+    return this.request(suffix ? `/sessions?${suffix}` : "/sessions");
+  }
+
+  /**
+   * Atomically fence this authenticated principal's session admission for one repository and
+   * begin cancelling its existing work. Reuse an idempotency key after an ambiguous retry.
+   */
+  startSessionDrain(repositoryId, options = {}) {
+    return this.request(`/repositories/${encodeURIComponent(repositoryId)}/session-drains`, {
+      method: "POST",
+      ...(options.idempotencyKey === undefined
+        ? {}
+        : { headers: { "idempotency-key": options.idempotencyKey } }),
+    });
+  }
+
+  /** Get bounded durable progress or terminal proof for one principal session drain. */
+  getSessionDrain(repositoryId, operationId) {
+    return this.request(
+      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}`,
+    );
+  }
+
+  /** Explicitly reopen admission after a succeeded or failed principal session drain. */
+  releaseSessionDrain(repositoryId, operationId) {
+    return this.request(
+      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}/release`,
+      { method: "POST" },
+    );
+  }
+
+  listRepositories(options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    const suffix = query.toString();
+    return this.request(suffix ? `/repositories?${suffix}` : "/repositories");
   }
 
   pauseRepository(id) {
@@ -68,4 +155,14 @@ export class AutoHarnessClient {
   repositoryOperation(id, operation) {
     return this.request(`/repositories/${encodeURIComponent(id)}/${operation}`, { method: "POST" });
   }
+
+  async listProviders() {
+    const { items } = await this.request("/providers");
+    return items;
+  }
+
+  async listCommands() {
+    const { items } = await this.request("/commands");
+    return items;
+  }
 }

package/src/resolve-target.js

@@ -0,0 +1,54 @@
+import { AutoHarnessError } from "./errors.js";
+
+async function resolveByName(name, catalog, kind, idKey) {
+  const matches = (await catalog()).filter((entry) => entry.name === name);
+  if (matches.length === 0) {
+    throw new AutoHarnessError(`no ${kind} named "${name}"`, {
+      status: 400,
+      code: `UNKNOWN_${kind.toUpperCase()}_NAME`,
+    });
+  }
+  if (matches.length > 1) {
+    throw new AutoHarnessError(
+      `ambiguous ${kind} name "${name}": ${matches.length} ${kind}s share this name`,
+      { status: 400, code: `AMBIGUOUS_${kind.toUpperCase()}_NAME` },
+    );
+  }
+  return { [idKey]: matches[0].id };
+}
+
+async function resolveRef(ref, providers, commands) {
+  if (ref == null || typeof ref !== "object") return ref;
+  // Checked by value, not `in`: a name ref built by conditional spreading can carry an
+  // explicit `providerId: undefined`, which `in` would treat as already resolved.
+  if (ref.providerId !== undefined || ref.commandId !== undefined) return ref;
+  if (ref.providerName !== undefined) {
+    return resolveByName(ref.providerName, providers, "provider", "providerId");
+  }
+  if (ref.commandName !== undefined) {
+    return resolveByName(ref.commandName, commands, "command", "commandId");
+  }
+  return ref;
+}
+
+/**
+ * Resolves `providerName`/`commandName` entries in `input.target`/`input.fallbacks` to
+ * `providerId`/`commandId` via `client.listProviders()`/`listCommands()`, called at most once
+ * each regardless of how many refs need them. Id-shaped refs pass through untouched, so an
+ * all-id call makes no extra requests. Provider and command names are both resolved defensively
+ * against more than one match — provider names are server-enforced unique today, but the
+ * create/update check is a read-then-write race, not an atomic constraint.
+ */
+export async function resolveCreateSessionTargets(client, input) {
+  let providersPromise;
+  let commandsPromise;
+  const providers = () => (providersPromise ??= client.listProviders());
+  const commands = () => (commandsPromise ??= client.listCommands());
+
+  const target = await resolveRef(input.target, providers, commands);
+  if (input.fallbacks === undefined) return { ...input, target };
+  const fallbacks = await Promise.all(
+    input.fallbacks.map((fallback) => resolveRef(fallback, providers, commands)),
+  );
+  return { ...input, target, fallbacks };
+}