auto-harness-client 0.6.0 → 0.8.0

package/src/index.js

@@ -1,3 +1,4 @@
+/* eslint-disable max-lines -- one small client class covering every REST method is the published surface. */
 import {
   AutoHarnessDrainWaitTimeoutError,
   AutoHarnessError,
@@ -5,7 +6,7 @@ import {
 } from "./errors.js";
 import { assertSecureTransport } from "./loopback.js";
 import { resolveRepositoryId } from "./resolve-repository.js";
-import { resolveCreateSessionTargets } from "./resolve-target.js";
+import { resolveCreateSessionTargets, resolveTargetSpecs } from "./resolve-target.js";
 
 export { AutoHarnessDrainWaitTimeoutError, AutoHarnessError, AutoHarnessRequestTimeoutError };
 
@@ -64,6 +65,7 @@ export class AutoHarnessClient {
             retryAfter: response.headers.get("retry-after") ?? undefined,
             operationId: error?.operationId,
             statusUrl: error?.statusUrl,
+            details: error,
           },
         );
       }
@@ -85,15 +87,42 @@ export class AutoHarnessClient {
     return this.request(`/sessions/${encodeURIComponent(id)}`);
   }
 
+  createChildSession(parentId, input) {
+    return this.request(`/sessions/${encodeURIComponent(parentId)}/children`, {
+      method: "POST",
+      body: JSON.stringify(input),
+    });
+  }
+
+  listChildSessions(parentId, 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
+        ? `/sessions/${encodeURIComponent(parentId)}/children?${suffix}`
+        : `/sessions/${encodeURIComponent(parentId)}/children`,
+    );
+  }
+
   cancelSession(id) {
     return this.request(`/sessions/${encodeURIComponent(id)}/cancel`, { method: "POST" });
   }
 
-  /** Resume a previously assigned session on its pinned host, native CLI resume where supported. */
-  resumeSession(id, input) {
+  /**
+   * Resume a previously assigned session on its pinned host, native CLI resume where supported.
+   * An optional `target`/`fallbacks` override rebinds the resume to a different Command/Provider
+   * — a repoint applying on the next resume, instead of only to new dispatches — and its
+   * `providerName`/`commandName` sugar is resolved the same way `createSession()` resolves it.
+   * Resolution only runs when `target` is present, so an id-only or bodyless resume makes no
+   * extra `listCommands()`/`listProviders()` requests.
+   */
+  async resumeSession(id, input) {
+    const body = input?.target === undefined ? input : await resolveTargetSpecs(this, input);
     return this.request(`/sessions/${encodeURIComponent(id)}/resume`, {
       method: "POST",
-      ...(input === undefined ? {} : { body: JSON.stringify(input) }),
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
     });
   }
 
@@ -161,37 +190,40 @@ export class AutoHarnessClient {
     if (!Number.isFinite(timeoutMs) || timeoutMs <= 0)
       throw new TypeError("timeoutMs must be a finite positive number");
     const deadline = Date.now() + timeoutMs;
-    const clampedClient = () =>
-      new AutoHarnessClient({
-        baseUrl: this.baseUrl,
-        apiKey: this.apiKey,
-        allowInsecureHttp: this.allowInsecureHttp,
-        fetch: this.fetch,
-        requestTimeoutMs: Math.max(
-          1,
-          Math.ceil(Math.min(this.requestTimeoutMs, deadline - Date.now())),
-        ),
-      });
-    const rejectAtDeadline = (error, idForError) =>
-      error instanceof AutoHarnessRequestTimeoutError && Date.now() >= deadline
+    const clampedClient = () => {
+      const remainingMs = deadline - Date.now();
+      const requestTimeoutMs = Math.max(1, Math.ceil(Math.min(this.requestTimeoutMs, remainingMs)));
+      return {
+        client: new AutoHarnessClient({
+          baseUrl: this.baseUrl,
+          apiKey: this.apiKey,
+          allowInsecureHttp: this.allowInsecureHttp,
+          fetch: this.fetch,
+          requestTimeoutMs,
+        }),
+        clampedToWaitBudget: remainingMs <= this.requestTimeoutMs,
+      };
+    };
+    const rejectAtDeadline = (error, idForError, clampedToWaitBudget) =>
+      error instanceof AutoHarnessRequestTimeoutError &&
+      (clampedToWaitBudget || Date.now() >= deadline)
         ? new AutoHarnessDrainWaitTimeoutError(idForError, operationId, timeoutMs)
         : error;
 
+    const repositoryLookup = clampedClient();
     const id = await resolveRepositoryId(
-      { listRepositories: (listOptions) => clampedClient().listRepositories(listOptions) },
+      { listRepositories: (opts) => repositoryLookup.client.listRepositories(opts) },
       repositoryId,
     ).catch((error) => {
-      throw rejectAtDeadline(error, repositoryId);
+      throw rejectAtDeadline(error, repositoryId, repositoryLookup.clampedToWaitBudget);
     });
     for (;;) {
-      if (deadline - Date.now() <= 0) {
+      if (deadline - Date.now() <= 0)
         throw new AutoHarnessDrainWaitTimeoutError(id, operationId, timeoutMs);
-      }
-      const sessionDrain = await clampedClient()
-        .getSessionDrain(id, operationId)
-        .catch((error) => {
-          throw rejectAtDeadline(error, id);
-        });
+      const { client, clampedToWaitBudget } = clampedClient();
+      const sessionDrain = await client.getSessionDrain(id, operationId).catch((error) => {
+        throw rejectAtDeadline(error, id, clampedToWaitBudget);
+      });
       if (sessionDrain.status !== "draining") return sessionDrain;
       const delayMs = Math.min(pollIntervalMs, deadline - Date.now());
       if (delayMs <= 0) throw new AutoHarnessDrainWaitTimeoutError(id, operationId, timeoutMs);
@@ -224,12 +256,26 @@ export class AutoHarnessClient {
   }
 
   async listProviders() {
-    const { items } = await this.request("/providers");
-    return items;
+    return this.listCatalog("/providers");
   }
 
   async listCommands() {
-    const { items } = await this.request("/commands");
-    return items;
+    return this.listCatalog("/commands");
+  }
+
+  async listCatalog(path) {
+    const items = [];
+    const seen = new Set();
+    let suffix = "?limit=100";
+    for (let page = 0; page < 20; page += 1) {
+      const body = await this.request(`${path}${suffix}`);
+      items.push(...(body.items ?? []));
+      const cursor = body.nextCursor ?? null;
+      if (!cursor) return items;
+      if (seen.has(cursor)) throw new Error(`repeated pagination cursor for ${path}`);
+      seen.add(cursor);
+      suffix = `?limit=100&cursor=${encodeURIComponent(cursor)}`;
+    }
+    throw new Error(`pagination exceeded 20 pages for ${path}`);
   }
 }

package/src/resolve-target.js

@@ -16,31 +16,47 @@ async function resolveRef(ref, providers, commands) {
 }
 
 /**
- * Resolves `providerName`/`commandName` entries in `input.target`/`input.fallbacks`, and
- * `input.repositoryName`, to their ids via `client.listProviders()`/`listCommands()`/
- * `listRepositories()`, each called at most once regardless of how many refs need it. Id-shaped
- * refs pass through untouched, so an all-id call makes no extra requests. Names are resolved
- * defensively against more than one match: create/update checks are read-then-write races rather
- * than atomic constraints, and legacy catalog rows are not rewritten.
+ * Resolves `providerName`/`commandName` entries in `input.target`/`input.fallbacks` to their ids
+ * via `client.listProviders()`/`listCommands()`, each called at most once regardless of how many
+ * refs need it. Id-shaped refs pass through untouched, so an all-id call makes no extra requests.
+ * Names are resolved defensively against more than one match: create/update checks are
+ * read-then-write races rather than atomic constraints, and legacy catalog rows are not rewritten.
+ * Shared by session create and resume — resume has no repository to resolve, so it calls this
+ * directly instead of `resolveCreateSessionTargets`.
  */
-export async function resolveCreateSessionTargets(client, input) {
+export async function resolveTargetSpecs(client, input) {
   let providersPromise;
   let commandsPromise;
   const providers = () => (providersPromise ??= client.listProviders());
   const commands = () => (commandsPromise ??= client.listCommands());
 
   const target = await resolveRef(input.target, providers, commands);
+  const resolved = { ...input, target };
+  if (input.fallbacks === undefined) return resolved;
+  const fallbacks = await Promise.all(
+    input.fallbacks.map((fallback) => resolveRef(fallback, providers, commands)),
+  );
+  return { ...resolved, fallbacks };
+}
+
+/**
+ * Resolves `providerName`/`commandName` entries in `input.target`/`input.fallbacks`, and
+ * `input.repositoryName`, to their ids via `client.listProviders()`/`listCommands()`/
+ * `listRepositories()`.
+ */
+export async function resolveCreateSessionTargets(client, input) {
+  if (Object.hasOwn(input, "setupScript")) {
+    throw new TypeError("setupScript is not accepted; use setupProfileId");
+  }
+  const withTargets = await resolveTargetSpecs(client, input);
+  if (input.repositoryId === null) return withTargets;
   const repositoryId = await resolveRepositoryId(
     client,
     input.repositoryId !== undefined
       ? input.repositoryId
       : { repositoryName: input.repositoryName },
   );
-  const resolved = { ...input, repositoryId, target };
+  const resolved = { ...withTargets, repositoryId };
   delete resolved.repositoryName;
-  if (input.fallbacks === undefined) return resolved;
-  const fallbacks = await Promise.all(
-    input.fallbacks.map((fallback) => resolveRef(fallback, providers, commands)),
-  );
-  return { ...resolved, fallbacks };
+  return resolved;
 }