auto-harness-client 0.5.0 → 0.7.0

package/src/cli/path-segment.js

@@ -0,0 +1,20 @@
+import { CliUsageError } from "./cli-errors.js";
+
+/**
+ * Encodes one path segment taken from the command line, such as a host or repository id.
+ *
+ * `encodeURIComponent` leaves `.` untouched, so an id of `.` or `..` survives encoding and the
+ * URL parser then resolves it as a dot segment: `repo rm ..` would send
+ * `DELETE /api/v1/repositories/..`, which is `DELETE /api/v1/`. No real id is `.` or `..`, so
+ * both are rejected. Percent-encoded dots need no check here: encoding turns `%2e` into `%252e`,
+ * which the parser does not treat as a dot segment.
+ *
+ * Call it as soon as the positional is parsed, before `createClient` — in admin mode that makes
+ * a network login, and a bad id should not cost one.
+ */
+export function pathSegment(value, label) {
+  if (value === "." || value === "..") {
+    throw new CliUsageError(`${label} must not be "." or ".."`);
+  }
+  return encodeURIComponent(value);
+}

package/src/cli/read-stdin.js

@@ -0,0 +1,9 @@
+/** Reads an injected `stdin` (any async-iterable of `Buffer`/`string` chunks — the real
+ * `process.stdin`, or a `Readable.from([...])` in tests) fully into a UTF-8 string. */
+export async function readStdin(stream) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+}

package/src/cli/report-error.js

@@ -0,0 +1,34 @@
+import { AutoHarnessError, AutoHarnessRequestTimeoutError } from "../errors.js";
+import { CliConfigError, CliUsageError } from "./cli-errors.js";
+
+/** Writes a one-line error (plus, for an `AutoHarnessError`, any `details` fields beyond
+ * `code`/`message` — e.g. a refused delete's `dependencies`) to `io.stderr` and returns the
+ * process exit code for it: 2 for a usage/config error, 1 for anything else. */
+export function reportError(error, io) {
+  if (error instanceof CliUsageError || error instanceof CliConfigError) {
+    io.stderr.write(`error: ${error.message}\n`);
+    return 2;
+  }
+  if (error instanceof AutoHarnessRequestTimeoutError) {
+    io.stderr.write(`error: ${error.message}\n`);
+    return 1;
+  }
+  if (error instanceof AutoHarnessError) {
+    io.stderr.write(`error: ${error.message} (HTTP ${error.status}, ${error.code})\n`);
+    const extra = extraDetailFields(error.details);
+    if (extra) io.stderr.write(`${JSON.stringify(extra, null, 2)}\n`);
+    return 1;
+  }
+  io.stderr.write(`error: ${error.message}\n`);
+  return 1;
+}
+
+function extraDetailFields(details) {
+  if (!details || typeof details !== "object") return undefined;
+  const extra = {};
+  for (const [key, value] of Object.entries(details)) {
+    if (key === "code" || key === "message") continue;
+    extra[key] = value;
+  }
+  return Object.keys(extra).length > 0 ? extra : undefined;
+}

package/src/cli/service-account-format.js

@@ -0,0 +1,24 @@
+import { allowlistPrincipal } from "./allowlist.js";
+
+/**
+ * `allowlistPrincipal` plus `createdAt`. `GET /auth/service-accounts` items (and the `account`
+ * returned by `POST /auth/service-accounts`) are already server-sanitized (`publicPrincipal`)
+ * plus `name`/`createdAt`, but this is printed through the same allowlist as `whoami`/`doctor`
+ * as defense in depth — `createdAt` is added back on top since it is not part of a bare
+ * principal and so is not in `ALLOWED_PRINCIPAL_FIELDS`.
+ */
+export function allowlistAccount(account) {
+  const allowed = allowlistPrincipal(account);
+  if (account && typeof account === "object" && Object.hasOwn(account, "createdAt")) {
+    allowed.createdAt = account.createdAt;
+  }
+  return allowed;
+}
+
+/** One-line human summary: id, name, role, and (when present) boundHostId/createdAt. */
+export function formatAccountLine(account) {
+  const parts = [account.id, account.name, account.role];
+  if (account.boundHostId) parts.push(account.boundHostId);
+  if (account.createdAt) parts.push(account.createdAt);
+  return parts.join("  ");
+}

package/src/cli/usage.js

@@ -0,0 +1,66 @@
+export function usage() {
+  return `auto-harness - operator CLI for the Auto Harness control plane API
+
+A global flag (--api-url, --api-key-file, --allow-insecure-http, --admin-password-stdin,
+--admin-username) is recognized before or after the command name — both
+\`auto-harness --admin-password-stdin whoami\` and \`auto-harness whoami --admin-password-stdin\`
+work the same way.
+
+Usage:
+  auto-harness api <METHOD> <path> [--body <json> | --body-file <path|->]
+  auto-harness whoami [--json]
+  auto-harness doctor
+  auto-harness host list [--online | --offline] [--limit N] [--cursor C] [--all] [--json]
+  auto-harness host drain <hostId> [--json]
+  auto-harness host resume <hostId> [--json]
+  auto-harness host inventory get <hostId> [--json]
+  auto-harness host inventory set <hostId> --file <path|->
+  auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]
+  auto-harness repo list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness repo rm <repositoryId> [--json]
+  auto-harness service-account list [--limit N] [--cursor C] [--all] [--json]
+  auto-harness service-account create --name <name> --role <role> [--bound-host <hostId>]
+    [--repositories <id,id,...>] (--key-file <path> | --print-key) [--json]
+  auto-harness service-account rm <id> [--json]
+  auto-harness help | --help | -h
+
+Configuration:
+  --api-url <url>        Control plane base URL (else HARNESS_API_URL, else HARNESS_API_HTTP)
+  --api-key-file <path>  Read the API key from a file, trimmed (else HARNESS_API_KEY_FILE)
+  --allow-insecure-http  Allow a plain http:// baseUrl (loopback only; local dev)
+
+The API key is never accepted as a command-line flag: it would land in \`ps\` output and shell
+history. Set the HARNESS_API_KEY environment variable, or point --api-key-file /
+HARNESS_API_KEY_FILE at a file holding it.
+
+Admin bootstrap (no API key exists yet):
+  --admin-password-stdin          Log in as an admin (password piped through stdin) instead of
+                                   using an API key; combine with --admin-username (default: admin)
+  --admin-username <name>         Admin username for --admin-password-stdin (default: admin)
+
+--admin-password-stdin reads the password from stdin (one trailing newline stripped), logs in
+once via POST /auth/login, and carries the session cookie on every later request instead of an
+API key — it never touches argv, shell history, or output. It cannot be combined with an API key
+(--api-key-file, HARNESS_API_KEY, or HARNESS_API_KEY_FILE), nor with a command that also reads
+stdin for its own input (\`api --body-file -\`, \`host inventory set --file -\`).
+
+Examples:
+  auto-harness whoami
+  auto-harness api GET /hosts
+  auto-harness api POST /repositories --body '{"name":"org/repo","url":"https://github.com/org/repo"}'
+  auto-harness api DELETE /repositories/repo-1 --body-file -
+  auto-harness doctor
+  auto-harness host list --online
+  auto-harness host drain host-1
+  auto-harness host inventory get host-1 --json > inventory.json
+  auto-harness host repo rm host-1 repo-1 --dry-run
+  auto-harness repo list --all
+  auto-harness repo rm repo-1
+  auto-harness service-account list
+  auto-harness service-account create --name ci --role operator --print-key > /dev/null
+  KEY=$(auto-harness service-account create --name ci --role operator --print-key)
+  aws ssm get-parameter --name /auto-harness/admin-password --with-decryption \\
+    --query Parameter.Value --output text \\
+    | auto-harness --admin-password-stdin service-account create --name ci --role operator --print-key
+`;
+}

package/src/errors.js

@@ -7,6 +7,7 @@ export class AutoHarnessError extends Error {
     this.retryAfter = options.retryAfter;
     this.operationId = options.operationId;
     this.statusUrl = options.statusUrl;
+    this.details = options.details;
   }
 }
 

package/src/index.d.ts

@@ -1,6 +1,17 @@
+/* eslint-disable max-lines -- public client declarations share one compatibility surface. */
 import type { Command, Provider } from "./catalog-types.js";
 export type { Command, Provider, ResumeRefCapture, UsageRates } from "./catalog-types.js";
 
+export type SessionResult = {
+  summary: string;
+  summarySource: "agent" | "harness";
+  summaryTruncated?: true;
+  branch?: string;
+  filesChanged?: string[];
+  filesChangedTruncated?: true;
+  pullRequestUrl?: string;
+};
+
 export type TargetRef =
   | { commandId: string; providerId?: never }
   | { providerId: string; commandId?: never };
@@ -31,7 +42,7 @@ export type RepositoryRef =
 export type SessionMetadataValue = string | number | boolean | null;
 
 /** Whether a session was created directly or fired by a schedule. */
-export type SessionType = "prompt" | "scheduled";
+export type SessionType = "prompt" | "scheduled" | "workspace";
 
 /** Origin that requested the session. */
 export type SessionSource = "api" | "ui" | "webhook" | "schedule";
@@ -39,7 +50,7 @@ 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 = RepositoryRef & {
+type CreateSessionOptions = {
   prompt: string;
   target: TargetSpec;
   fallbacks?: TargetSpec[];
@@ -52,11 +63,33 @@ export type CreateSessionInput = RepositoryRef & {
   metadata?: Record<string, SessionMetadataValue>;
   /** Defaults to `"api"`; `"ui"`/`"webhook"` pass through, anything else becomes `"api"`. */
   source?: CreatableSessionSource;
+  /** Raw setup scripts are not a session input; select a trusted profile by id. */
+  setupScript?: never;
+};
+
+/** Host-scoped, non-git create-session input. */
+export type WorkspaceSessionInput = CreateSessionOptions & {
+  repositoryId: null;
+  workspacePoolId: string;
+  setupProfileId?: string;
+  destroyWorkspaceAfter?: boolean;
+  type?: "workspace";
+  ref?: never;
+  requiredLabels?: [];
 };
 
+/** Existing repository-backed create-session input, retained unchanged. */
+export type CreateSessionInput =
+  | (RepositoryRef & CreateSessionOptions & { type?: "prompt" | "scheduled" })
+  | WorkspaceSessionInput;
+
 export type Session = {
   id: string;
-  repositoryId: string;
+  repositoryId: string | null;
+  workspacePoolId?: string;
+  workspaceSlotId?: string | null;
+  setupProfileId?: string;
+  destroyWorkspaceAfter?: boolean;
   prompt: string;
   target: TargetRef;
   fallbacks?: TargetRef[];
@@ -75,14 +108,31 @@ export type Session = {
   createdAt: string;
   url: string;
   created?: boolean;
+  /** Present on detail reads and terminal action results when available. */
+  result?: SessionResult;
+  parentSessionId?: string;
+  rootSessionId?: string;
 };
 
-/** Body accepted by `POST /sessions/:id/resume`. */
+export type CreateChildSessionInput = {
+  prompt: string;
+  spawnKey: string;
+  priority?: number;
+  queueTtlSeconds?: number;
+};
+
+export type ListChildSessionsOptions = { limit?: number; cursor?: string };
+
+/** Body accepted by `POST /sessions/:id/resume`. `target`/`fallbacks` are an optional
+ * rebinding override — passing `target` alone clears any inherited `fallbacks`, and
+ * a bare `fallbacks` without `target` is rejected. */
 export type ResumeSessionInput = {
   prompt?: string;
   concurrencyId?: string;
   timeout?: number;
   priority?: number;
+  target?: TargetSpec;
+  fallbacks?: TargetSpec[];
 };
 
 /** `status` filter accepted by `GET /sessions`. */
@@ -179,6 +229,10 @@ export class AutoHarnessError extends Error {
   operationId?: string;
   /** API-relative URL for the drain that fenced this request. */
   statusUrl?: string;
+  /** The complete `body.error` object from the response, when the server returned JSON —
+   * e.g. a refused delete's `dependencies` array. Undefined when the response had no parseable
+   * JSON `error` object. */
+  details?: Record<string, unknown>;
   constructor(
     message: string,
     options: {
@@ -187,6 +241,7 @@ export class AutoHarnessError extends Error {
       retryAfter?: string;
       operationId?: string;
       statusUrl?: string;
+      details?: Record<string, unknown>;
     },
   );
 }
@@ -232,6 +287,11 @@ export class AutoHarnessClient {
   constructor(options: AutoHarnessClientOptions);
   createSession(input: CreateSessionInput): Promise<Session & { created: boolean }>;
   getSession(id: string): Promise<Session>;
+  createChildSession(
+    parentId: string,
+    input: CreateChildSessionInput,
+  ): Promise<Session & { created: boolean }>;
+  listChildSessions(parentId: string, options?: ListChildSessionsOptions): Promise<SessionPage>;
   cancelSession(id: string): Promise<Session>;
   resumeSession(id: string, input?: ResumeSessionInput): Promise<Session & { created: boolean }>;
   listSessions(options?: ListSessionsOptions): Promise<SessionPage>;

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;
 }