auto-harness-client 0.6.0 → 0.8.0

package/src/cli/commands/whoami.js

@@ -0,0 +1,22 @@
+import { allowlistPrincipal, formatWhoami } from "../allowlist.js";
+import { parseFlags } from "../args.js";
+import { CliUsageError } from "../cli-errors.js";
+import { createClient, GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "../config.js";
+
+/** `GET /auth/me`, printing only the allowlisted principal fields (see allowlist.js for why the
+ * response shape is not trusted). */
+export async function runWhoami(argv, io) {
+  const { flags, positionals } = parseFlags(argv, {
+    valueFlags: GLOBAL_VALUE_FLAGS,
+    booleanFlags: [...GLOBAL_BOOLEAN_FLAGS, "--json"],
+  });
+  if (positionals.length > 0) {
+    throw new CliUsageError(`whoami takes no arguments; received: ${positionals.join(" ")}`);
+  }
+  const client = await createClient(flags, io);
+  const principal = allowlistPrincipal(await client.request("/auth/me"));
+  io.stdout.write(
+    flags["--json"] ? `${JSON.stringify(principal, null, 2)}\n` : formatWhoami(principal),
+  );
+  return 0;
+}

package/src/cli/config.js

@@ -0,0 +1,96 @@
+import { AutoHarnessClient } from "../index.js";
+import { checkAdminLoginUsage, loginAsAdmin } from "./admin-login.js";
+import { CliConfigError } from "./cli-errors.js";
+
+export const GLOBAL_VALUE_FLAGS = ["--api-url", "--api-key-file", "--admin-username"];
+export const GLOBAL_BOOLEAN_FLAGS = ["--allow-insecure-http", "--admin-password-stdin"];
+
+/** A flag that is present wins, even with an empty value — `--api-url=` or
+ * `--api-key-file "$UNSET"` is an explicit choice that went wrong, not an absent flag. Falling
+ * back to the environment would silently use a different URL, or authenticate as a different
+ * principal, than the one the command line asked for. So an empty value is a config error. */
+function explicitFlag(flags, name) {
+  if (!Object.hasOwn(flags, name)) return undefined;
+  if (flags[name].trim() === "") throw new CliConfigError(`${name} was given an empty value`);
+  return flags[name];
+}
+
+/** `--api-url`, else `HARNESS_API_URL`, else `HARNESS_API_HTTP` (the host daemon's own alias —
+ * operators already have one of these two set). Missing entirely is a config error naming both. */
+export function resolveApiUrl(flags, env) {
+  const url = explicitFlag(flags, "--api-url") ?? (env.HARNESS_API_URL || env.HARNESS_API_HTTP);
+  if (!url) {
+    throw new CliConfigError(
+      "no API base URL configured: set --api-url, or the HARNESS_API_URL environment " +
+        "variable (alias: HARNESS_API_HTTP)",
+    );
+  }
+  return url;
+}
+
+/**
+ * Precedence: an explicit `--api-key-file` flag wins outright — it is the most specific,
+ * most intentional signal an operator can give on any one invocation. Failing that, the direct
+ * `HARNESS_API_KEY` value wins over the indirect `HARNESS_API_KEY_FILE` pointer, since a plain
+ * env var is one less level of indirection to reason about. Any consistent order satisfies the
+ * spec here; this one mirrors "flag beats env" from `resolveApiUrl` above.
+ */
+export async function resolveApiKey(flags, env, readFile) {
+  const keyFile = explicitFlag(flags, "--api-key-file");
+  if (keyFile !== undefined) return readApiKeyFile(keyFile, readFile);
+  if (env.HARNESS_API_KEY) return env.HARNESS_API_KEY.trim();
+  if (env.HARNESS_API_KEY_FILE) return readApiKeyFile(env.HARNESS_API_KEY_FILE, readFile);
+  return undefined;
+}
+
+async function readApiKeyFile(path, readFile) {
+  let contents;
+  try {
+    contents = await readFile(path, "utf8");
+  } catch (error) {
+    throw new CliConfigError(`could not read API key file ${path}: ${error.message}`);
+  }
+  const trimmed = contents.trim();
+  if (!trimmed) throw new CliConfigError(`API key file ${path} is empty`);
+  return trimmed;
+}
+
+/**
+ * `--admin-password-stdin` replaces the whole apiKey identity with an admin username/password
+ * login, so its usage checks run here — unconditionally, for every command — before either an
+ * apiKey is resolved or (in `createClient`) the login request is made.
+ */
+export async function resolveConfig(flags, io) {
+  const baseUrl = resolveApiUrl(flags, io.env);
+  checkAdminLoginUsage(flags, io.env);
+  const allowInsecureHttp = Boolean(flags["--allow-insecure-http"]);
+  if (flags["--admin-password-stdin"]) {
+    const adminUsername = explicitFlag(flags, "--admin-username") ?? "admin";
+    return { baseUrl, allowInsecureHttp, adminMode: true, adminUsername };
+  }
+  const apiKey = await resolveApiKey(flags, io.env, io.readFile);
+  return { baseUrl, apiKey, allowInsecureHttp };
+}
+
+/** Builds the real `AutoHarnessClient`; a constructor rejection (e.g. plaintext http with an
+ * apiKey set against a non-loopback host) is a configuration problem, not an API failure, so it
+ * is re-thrown as `CliConfigError` (exit 2) rather than surfacing as a generic exit-1 error. A
+ * failed admin login (a bad password, an unreachable server) is deliberately *not* wrapped this
+ * way — it is reported as a plain error (exit 1), matching a rejected API key rather than a
+ * usage/config problem. */
+export async function createClient(flags, io) {
+  const config = await resolveConfig(flags, io);
+  const fetchFn = config.adminMode
+    ? (await loginAsAdmin(io, config.baseUrl, config.adminUsername, config.allowInsecureHttp)).fetch
+    : io.fetch;
+  try {
+    return new AutoHarnessClient({
+      baseUrl: config.baseUrl,
+      apiKey: config.apiKey,
+      fetch: fetchFn,
+      allowInsecureHttp: config.allowInsecureHttp,
+    });
+  } catch (error) {
+    throw new CliConfigError(error.message);
+  }
+}

package/src/cli/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+
+import { main } from "./main.js";
+
+// A thin wrapper: every dependency on the outside world is injected here, so `main()` and
+// everything it calls stay unit-testable without spawning a process or touching the network.
+const io = {
+  env: process.env,
+  fetch: globalThis.fetch,
+  stdout: process.stdout,
+  stderr: process.stderr,
+  stdin: process.stdin,
+  readFile,
+  // O_CREAT | O_EXCL ("wx") — never overwrites an existing file. Used only for
+  // `service-account create --key-file`, where a plaintext API key is written to disk exactly
+  // once and mode 0600 (passed by the caller) keeps it readable only by its owner.
+  writeFileExclusive: (path, data, options) => writeFile(path, data, { flag: "wx", ...options }),
+};
+
+process.exitCode = await main(process.argv.slice(2), io);

package/src/cli/main.js

@@ -0,0 +1,71 @@
+import { runApi } from "./commands/api.js";
+import { runDoctor } from "./commands/doctor.js";
+import { runHost } from "./commands/host.js";
+import { runRepo } from "./commands/repo.js";
+import { runServiceAccount } from "./commands/service-account.js";
+import { runSession } from "./commands/session.js";
+import { runWhoami } from "./commands/whoami.js";
+import { GLOBAL_BOOLEAN_FLAGS, GLOBAL_VALUE_FLAGS } from "./config.js";
+import { reportError } from "./report-error.js";
+import { usage } from "./usage.js";
+
+const HELP_TOKENS = new Set(["help", "--help", "-h"]);
+
+/**
+ * A global flag (`--admin-password-stdin`, `--api-url`, ...) is recognized wherever it appears,
+ * not only after the command name — `auto-harness --admin-password-stdin service-account create`
+ * reads the same as `auto-harness service-account create --admin-password-stdin`. This walks
+ * only the *leading* run of `--flag` tokens (an unknown leading flag, e.g. a mistyped one or the
+ * rejected `--api-key`, is left in place and falls through to the usage/exit-2 path below,
+ * exactly as an unrecognized command would), moves each one after the command name, and hands
+ * the rest of `argv` to the matched subcommand's own `parseFlags` untouched.
+ */
+function hoistLeadingGlobalFlags(argv) {
+  const hoisted = [];
+  let index = 0;
+  while (index < argv.length && argv[index].startsWith("--")) {
+    const arg = argv[index];
+    const equals = arg.indexOf("=");
+    const name = equals === -1 ? arg : arg.slice(0, equals);
+    if (GLOBAL_BOOLEAN_FLAGS.includes(name) && equals === -1) {
+      hoisted.push(arg);
+      index += 1;
+    } else if (GLOBAL_VALUE_FLAGS.includes(name) && equals !== -1) {
+      hoisted.push(arg);
+      index += 1;
+    } else if (GLOBAL_VALUE_FLAGS.includes(name) && index + 1 < argv.length) {
+      hoisted.push(arg, argv[index + 1]);
+      index += 2;
+    } else {
+      break;
+    }
+  }
+  return { command: argv[index], rest: [...argv.slice(index + 1), ...hoisted] };
+}
+
+/**
+ * Runs the CLI end to end and resolves to a process exit code — 0 on success, 1 for an
+ * API/HTTP failure or a failed `doctor` check, 2 for a usage or configuration error. Every
+ * dependency on the outside world (env, fetch, the standard streams, file reads) is injected
+ * through `io` so this never spawns a process or touches the real network in tests.
+ */
+export async function main(argv, io) {
+  const { command, rest } = hoistLeadingGlobalFlags(argv);
+  if (command === undefined || HELP_TOKENS.has(command)) {
+    io.stdout.write(usage());
+    return 0;
+  }
+  try {
+    if (command === "api") return await runApi(rest, io);
+    if (command === "whoami") return await runWhoami(rest, io);
+    if (command === "doctor") return await runDoctor(rest, io);
+    if (command === "host") return await runHost(rest, io);
+    if (command === "repo") return await runRepo(rest, io);
+    if (command === "service-account") return await runServiceAccount(rest, io);
+    if (command === "session") return await runSession(rest, io);
+    io.stderr.write(usage());
+    return 2;
+  } catch (error) {
+    return reportError(error, io);
+  }
+}

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/session-format.js

@@ -0,0 +1,15 @@
+/**
+ * One-line human summary shared by `session create --wait`, `session get`, and `session cancel`:
+ * id, status, and (only when present) exit code, error code, and error message. Session records
+ * use `errorCode`/`errorMessage` (never `error`) and have no top-level `summary` — see
+ * `SessionRecord` in services/api/src/db/types.ts.
+ */
+export function formatSessionLine(session) {
+  const parts = [session.id, session.status];
+  if (session.exitCode !== undefined && session.exitCode !== null) {
+    parts.push(`exitCode=${session.exitCode}`);
+  }
+  if (session.errorCode !== undefined) parts.push(`errorCode=${session.errorCode}`);
+  if (session.errorMessage !== undefined) parts.push(`errorMessage=${session.errorMessage}`);
+  return `${parts.join("  ")}\n`;
+}

package/src/cli/usage.js

@@ -0,0 +1,83 @@
+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 add <hostId> <repositoryId> --path <path> [--worktree <id>=<path>]...
+    [--default-branch <branch>] [--dry-run] [--json]
+  auto-harness host repo rm <hostId> <repositoryId> [--dry-run] [--json]
+  auto-harness host smoke <hostId> --repo-path <path> --provider <id|name>
+    [--provider <id|name>]... [--timeout <seconds>] [--json]
+  auto-harness repo add --name <name> --url <url> [--default-branch <branch>] [--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 session create --repo <repositoryId> (--provider <id|name> | --command <id|name>) --prompt <text>
+    [--timeout <seconds>] [--ref <ref>] [--concurrency-id <id>] [--wait [--wait-timeout <seconds>]] [--json]
+  auto-harness session get <sessionId> [--json]
+  auto-harness session logs <sessionId> [--limit N] [--cursor C] [--json]
+  auto-harness session cancel <sessionId> [--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 add host-1 repo-1 --path /repos/repo-1
+  auto-harness host repo rm host-1 repo-1 --dry-run
+  auto-harness host smoke host-1 --repo-path /repos/repo-1 --provider claude
+  auto-harness repo add --name org/repo --url https://github.com/org/repo
+  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
+  auto-harness session create --repo repo-1 --command claude-print --prompt "Review the diff" --wait
+  auto-harness session get session-1
+  auto-harness session logs session-1 --limit 200
+  auto-harness session cancel session-1
+`;
+}

package/src/cli/wait-for-session.js

@@ -0,0 +1,46 @@
+// Copied from `TERMINAL_SESSION_STATUSES` in modules/shared/src/constants.ts — this package is
+// dependency-free (no `@auto-harness/shared` import), so the list is duplicated here rather than
+// imported. Keep in sync if the shared list ever changes.
+const TERMINAL_SESSION_STATUSES = ["completed", "failed", "cancelled", "timed_out"];
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Polls `client.getSession(id)` until it reports a terminal status (see
+ * `TERMINAL_SESSION_STATUSES` above), or until `timeoutMs` elapses while the session is still
+ * active. The first fetch always happens, before the budget is even checked, so an
+ * already-terminal session resolves correctly even with a tiny `timeoutMs`. `onStatus(status,
+ * session)` fires once per *change* in status, including the first observed one — never on every
+ * poll — so a caller can stream progress (e.g. to stderr) without duplicate lines.
+ *
+ * Resolves — never rejects on a timeout — to `{ timedOut: false, session }` once terminal, or
+ * `{ timedOut: true, session }` (the last fetched, still-active record) once the budget elapses.
+ * This never cancels the session itself; the caller decides what a timeout means. A `getSession`
+ * rejection (a real API/network failure) propagates as-is.
+ *
+ * `sleep`/`now` are injectable so tests never really wait; `intervalMs` is clamped to the time
+ * remaining before `timeoutMs` on the final poll.
+ */
+export async function waitForSession(
+  client,
+  id,
+  { timeoutMs, intervalMs, sleep = defaultSleep, now = Date.now, onStatus } = {},
+) {
+  const deadline = now() + timeoutMs;
+  let lastStatus;
+  for (;;) {
+    const session = await client.getSession(id);
+    if (session.status !== lastStatus) {
+      lastStatus = session.status;
+      onStatus?.(session.status, session);
+    }
+    if (TERMINAL_SESSION_STATUSES.includes(session.status)) {
+      return { timedOut: false, session };
+    }
+    const remainingMs = deadline - now();
+    if (remainingMs <= 0) return { timedOut: true, session };
+    await sleep(Math.min(intervalMs, remainingMs));
+  }
+}

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