auto-harness-client 0.3.0 → 0.5.0

package/README.md

@@ -22,6 +22,57 @@ const session = await harness.createSession({
 console.log(session.url);
 ```
 
+`baseUrl` must be `https` whenever `apiKey` is set — the constructor throws otherwise. Pass
+`allowInsecureHttp: true` to opt out, but only for a genuine loopback `baseUrl` (`127.0.0.0/8`,
+`::1`, or `localhost`) — the constructor verifies this itself and throws for any other `http:`
+`baseUrl` even when the flag is set. A private-network address (RFC1918) still crosses real network
+hardware and does not qualify.
+
+## 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 and Command names are server-enforced unique slugs within their respective catalogs on
+create/update, but those checks are read-then-write races rather than atomic constraints, and
+legacy catalog rows are not rewritten.
+Name resolution therefore still checks for more than one match rather than trusting uniqueness.
+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.
+
+## Repository by name
+
+`createSession()` and the principal session drain methods (`startSessionDrain()`,
+`getSessionDrain()`, `releaseSessionDrain()`, `waitForSessionDrain()`) accept a `RepositoryRef` —
+`{ repositoryId }` as before, or `{ repositoryName }` — wherever they take a `repositoryId`
+parameter. `listSessions()`'s `repositoryId` filter and the repository administration methods
+(`pauseRepository()`, `drainRepository()`, `activateRepository()`) remain id-only. Repositories are
+not exposed as a single unpaginated catalog call, so resolving by name pages through
+`listRepositories()` in full before matching. An unresolvable or ambiguous name throws
+`AutoHarnessError` (`code === "UNKNOWN_REPOSITORY_NAME"` or `"AMBIGUOUS_REPOSITORY_NAME"`).
+
+```js
+const session = await harness.createSession({
+  repositoryName: "voucha/filaments",
+  prompt: "Review the latest changes",
+  target: { providerId: "codex" },
+  timeout: 1_800,
+});
+```
+
 ## Request deadlines
 
 Every request has a deadline that includes receiving and consuming the JSON response body.
@@ -45,10 +96,13 @@ while (page.nextCursor) {
 
 ## Principal session drains
 
-An automation principal can atomically stop admitting only its own sessions for one repository,
-then wait for the control plane to cancel and settle that exact scope. This is not repository or
-host drain. 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.
+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", {
@@ -60,14 +114,37 @@ while (progress.status === "draining") {
   await new Promise((resolve) => setTimeout(resolve, 5_000));
   progress = await harness.getSessionDrain("repo-1", drain.operationId);
 }
-if (progress.status !== "succeeded") throw new Error(`Drain failed: ${progress.failureCode}`);
+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.
 
+`waitForSessionDrain(repositoryId, operationId, { pollIntervalMs, timeoutMs })` replaces the manual
+poll loop above: it resolves `repositoryId`, then polls `getSessionDrain()` until a terminal status,
+clamping every request — including each page fetched to resolve a `repositoryName` — to the time
+remaining before `timeoutMs`. It resolves with the terminal `SessionDrain` for any status, including
+`"failed"` and `"released"` — callers classify success themselves — and rejects with
+`AutoHarnessDrainWaitTimeoutError` (`code === "DRAIN_WAIT_TIMEOUT"`) when the overall `timeoutMs`
+budget elapses — including when a clamped request is the thing that times out at that same instant
+— or with `AutoHarnessRequestTimeoutError` (`code === "REQUEST_TIMEOUT"`) if an individual request
+times out while budget still remains.
+
+```js
+const progress = await harness.waitForSessionDrain("repo-1", drain.operationId, {
+  pollIntervalMs: 5_000,
+  timeoutMs: 300_000,
+});
+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}`);
+```
+
 ## Resume a session
 
 Resume re-runs a previously assigned session. It initially prefers the source host and its stored
@@ -102,3 +179,22 @@ while (page.nextCursor) {
   sessions.push(...page.items);
 }
 ```
+
+## `auto-harness-client/actions`
+
+Dependency-free helpers for authoring a GitHub Action that dispatches Auto Harness sessions from
+`INPUT_*` env vars: `requiredEnvironmentValue`, `parseInteger`, `parseRequiredLabels`,
+`parseConcurrencyId`, `parseMetadata`, `parseHarnessApiOrigin`, `parseHarnessTarget`,
+`parseHarnessFallbacks`, `TARGET_SPEC_KEYS`, `HarnessDispatchError`, and `writeOutputs` (for
+`GITHUB_OUTPUT`/`GITHUB_STEP_SUMMARY`/`::notice` reporting). These parse the same env-var contract
+that `auto-harness`'s own
+[`actions/dispatch`](https://github.com/jonathanong/auto-harness/blob/main/actions/dispatch) action
+uses, so a consuming
+workflow's inline script and a bundled composite action stay in sync with the same validation.
+
+```js
+import { parseHarnessTarget, requiredEnvironmentValue } from "auto-harness-client/actions";
+
+const target = parseHarnessTarget(process.env.HARNESS_TARGET);
+const apiKey = requiredEnvironmentValue(process.env, "HARNESS_API_KEY");
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-harness-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Dependency-free client for the Auto Harness automation API",
   "repository": {
     "type": "git",
@@ -17,6 +17,14 @@
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
+    },
+    "./actions": {
+      "types": "./src/actions/index.d.ts",
+      "import": "./src/actions/index.js"
+    },
+    "./loopback": {
+      "types": "./src/loopback.d.ts",
+      "import": "./src/loopback.js"
     }
   },
   "publishConfig": {

package/src/actions/env.js

@@ -0,0 +1,7 @@
+import { HarnessDispatchError } from "./errors.js";
+
+export function requiredEnvironmentValue(environment, key) {
+  const value = environment[key]?.trim();
+  if (!value) throw new HarnessDispatchError("MISSING_ENVIRONMENT_VALUE", `${key} is required`);
+  return value;
+}

package/src/actions/errors.js

@@ -0,0 +1,6 @@
+export class HarnessDispatchError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}

package/src/actions/index.d.ts

@@ -0,0 +1,68 @@
+import type { TargetSpec } from "../index.js";
+
+/** Dependency-free env→`CreateSessionInput` adapter for GitHub Actions consumers of Auto Harness. */
+
+export type ActionEnvironment = Record<string, string | undefined>;
+
+export class HarnessDispatchError extends Error {
+  code: string;
+  constructor(code: string, message: string);
+}
+
+export function requiredEnvironmentValue(environment: ActionEnvironment, key: string): string;
+
+export function parseInteger(
+  value: string | undefined,
+  key: string,
+  minimum: number,
+): number | undefined;
+
+/** Parses `HARNESS_REQUIRED_LABELS`-shaped input; `fieldName` customizes the error message only. */
+export function parseRequiredLabels(value: string | undefined, fieldName?: string): string[];
+
+export function parseConcurrencyId(
+  value: string | undefined,
+  options?: { fieldName?: string; optional?: boolean; allowAnyCharacters?: boolean },
+): string | undefined;
+
+export function parseMetadata(
+  value: string | undefined,
+  fieldName?: string,
+): Record<string, string | number | boolean | null>;
+
+/**
+ * Validates a raw URL string is an exact origin, optionally suffixed with `/api/v1`
+ * (accepted and stripped, so an API-relative origin round-trips unchanged). Requires https
+ * unless `allowHttp` is set.
+ */
+export function parseApiOrigin(
+  rawUrl: string,
+  options?: { fieldName?: string; allowHttp?: boolean },
+): URL;
+
+/** Validates `HARNESS_URL` is an exact `https://host` origin (no path/query/hash/credentials). */
+export function parseHarnessApiOrigin(environment: ActionEnvironment): URL;
+
+export const TARGET_SPEC_KEYS: readonly ["providerId", "providerName", "commandId", "commandName"];
+
+export function parseHarnessTarget(value: string, fieldName?: string): TargetSpec;
+
+export function parseHarnessFallbacks(value: string | undefined, fieldName?: string): TargetSpec[];
+
+export type DispatchResult = {
+  id: string;
+  url: string;
+  created: boolean;
+};
+
+/**
+ * Writes `session-id`/`session-url`/`created` to `GITHUB_OUTPUT`, a summary table to
+ * `GITHUB_STEP_SUMMARY`, and a `::notice` annotation — each only when its env var is set.
+ * `route` is the resolved provider/command chain used for this dispatch, if any; omit it for a
+ * dispatch that retained an existing session's target.
+ */
+export function writeOutputs(
+  environment: ActionEnvironment,
+  result: DispatchResult,
+  route?: TargetSpec[],
+): void;

package/src/actions/index.js

@@ -0,0 +1,12 @@
+export { requiredEnvironmentValue } from "./env.js";
+export { HarnessDispatchError } from "./errors.js";
+export {
+  parseApiOrigin,
+  parseConcurrencyId,
+  parseHarnessApiOrigin,
+  parseInteger,
+  parseMetadata,
+  parseRequiredLabels,
+} from "./parse.js";
+export { TARGET_SPEC_KEYS, parseHarnessFallbacks, parseHarnessTarget } from "./parse-target.js";
+export { writeOutputs } from "./write-outputs.js";

package/src/actions/parse-target.js

@@ -0,0 +1,53 @@
+import { HarnessDispatchError } from "./errors.js";
+
+export const TARGET_SPEC_KEYS = ["providerId", "providerName", "commandId", "commandName"];
+
+function parseTargetRefValue(parsed, key) {
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new HarnessDispatchError("INVALID_TARGET", `${key} must be a JSON object`);
+  }
+  const rest = Object.keys(parsed).filter((field) => !TARGET_SPEC_KEYS.includes(field));
+  if (rest.length > 0) {
+    throw new HarnessDispatchError(
+      "INVALID_TARGET",
+      `${key} must only contain providerId, providerName, commandId, or commandName`,
+    );
+  }
+  const presentKeys = TARGET_SPEC_KEYS.filter((field) => field in parsed);
+  if (presentKeys.length !== 1) {
+    throw new HarnessDispatchError(
+      "INVALID_TARGET",
+      `${key} must be exactly one of providerId, providerName, commandId, or commandName`,
+    );
+  }
+  const field = presentKeys[0];
+  const fieldValue = parsed[field];
+  if (typeof fieldValue !== "string" || fieldValue === "") {
+    throw new HarnessDispatchError("INVALID_TARGET", `${key}.${field} must be a non-empty string`);
+  }
+  return { [field]: fieldValue };
+}
+
+export function parseHarnessTarget(value, fieldName = "HARNESS_TARGET") {
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new HarnessDispatchError("INVALID_TARGET", `${fieldName} must be valid JSON`);
+  }
+  return parseTargetRefValue(parsed, fieldName);
+}
+
+export function parseHarnessFallbacks(value, fieldName = "HARNESS_FALLBACKS") {
+  if (!value?.trim()) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new HarnessDispatchError("INVALID_FALLBACKS", `${fieldName} must be valid JSON`);
+  }
+  if (!Array.isArray(parsed)) {
+    throw new HarnessDispatchError("INVALID_FALLBACKS", `${fieldName} must be a JSON array`);
+  }
+  return parsed.map((entry, index) => parseTargetRefValue(entry, `${fieldName}[${index}]`));
+}

package/src/actions/parse.js

@@ -0,0 +1,144 @@
+import { requiredEnvironmentValue } from "./env.js";
+import { HarnessDispatchError } from "./errors.js";
+
+const MAX_CONCURRENCY_ID_CHARACTERS = 128;
+// Mirrors the control plane's own limit (modules/shared/src/validation.ts's
+// MAX_CONCURRENCY_ID_BYTES), which allows any byte sequence up to this length.
+const MAX_CONCURRENCY_ID_BYTES = 2_048;
+const MAX_METADATA_BYTES = 8192;
+
+export function parseInteger(value, key, minimum) {
+  if (value === undefined || value === "") return undefined;
+  if (!/^\d+$/u.test(value) || Number(value) < minimum || !Number.isSafeInteger(Number(value))) {
+    throw new HarnessDispatchError(
+      "INVALID_INTEGER",
+      `${key} must be a ${minimum === 1 ? "positive" : "non-negative"} integer`,
+    );
+  }
+  return Number(value);
+}
+
+export function parseRequiredLabels(value, fieldName = "HARNESS_REQUIRED_LABELS") {
+  if (!value) return [];
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new HarnessDispatchError("INVALID_REQUIRED_LABELS", `${fieldName} must be valid JSON`);
+  }
+  if (
+    !Array.isArray(parsed) ||
+    !parsed.every((label) => typeof label === "string" && label !== "")
+  ) {
+    throw new HarnessDispatchError(
+      "INVALID_REQUIRED_LABELS",
+      `${fieldName} must be a JSON array of strings`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * `allowAnyCharacters` widens validation to the control plane's own contract — any byte
+ * sequence up to `MAX_CONCURRENCY_ID_BYTES` — for callers (like the dispatch Action) whose
+ * concurrency-id may already contain characters the default charset rejects, e.g. a `/`-bearing
+ * `${{ github.ref }}`. The default stays narrower (a safe-for-URLs-and-shells charset) for
+ * callers with no such existing contract to preserve.
+ */
+export function parseConcurrencyId(
+  value,
+  { fieldName = "HARNESS_CONCURRENCY_ID", optional = false, allowAnyCharacters = false } = {},
+) {
+  const concurrencyId = value?.trim();
+  if (!concurrencyId) {
+    if (optional) return undefined;
+    throw new HarnessDispatchError("INVALID_CONCURRENCY_ID", `${fieldName} is required`);
+  }
+  if (allowAnyCharacters) {
+    if (Buffer.byteLength(concurrencyId, "utf8") > MAX_CONCURRENCY_ID_BYTES) {
+      throw new HarnessDispatchError(
+        "INVALID_CONCURRENCY_ID",
+        `${fieldName} exceeds ${MAX_CONCURRENCY_ID_BYTES} bytes`,
+      );
+    }
+    return concurrencyId;
+  }
+  if (concurrencyId.length > MAX_CONCURRENCY_ID_CHARACTERS) {
+    throw new HarnessDispatchError("INVALID_CONCURRENCY_ID", `${fieldName} exceeds 128 characters`);
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9:._-]*$/u.test(concurrencyId)) {
+    throw new HarnessDispatchError(
+      "INVALID_CONCURRENCY_ID",
+      `${fieldName} contains unsupported characters`,
+    );
+  }
+  return concurrencyId;
+}
+
+export function parseMetadata(value, fieldName = "HARNESS_METADATA") {
+  if (!value) return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new HarnessDispatchError("INVALID_METADATA", `${fieldName} must be valid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw new HarnessDispatchError("INVALID_METADATA", `${fieldName} must be a JSON object`);
+  }
+  for (const [key, fieldValue] of Object.entries(parsed)) {
+    const isValidScalar =
+      ["string", "boolean"].includes(typeof fieldValue) ||
+      fieldValue === null ||
+      (typeof fieldValue === "number" && Number.isFinite(fieldValue));
+    if (!isValidScalar) {
+      throw new HarnessDispatchError(
+        "INVALID_METADATA",
+        `${fieldName}.${key} must be a string, finite number, boolean, or null`,
+      );
+    }
+  }
+  if (Buffer.byteLength(JSON.stringify(parsed), "utf8") > MAX_METADATA_BYTES) {
+    throw new HarnessDispatchError("INVALID_METADATA", `${fieldName} exceeds 8192 bytes`);
+  }
+  return parsed;
+}
+
+/**
+ * Validates a raw URL string is an exact origin, optionally suffixed with `/api/v1`
+ * (accepted and stripped, so an API-relative origin round-trips unchanged). Requires https
+ * unless `allowHttp` is set, for callers whose control plane may be reached over plain http
+ * (e.g. a local or self-hosted deployment without TLS termination).
+ */
+export function parseApiOrigin(rawUrl, { fieldName = "HARNESS_URL", allowHttp = false } = {}) {
+  let apiUrl;
+  try {
+    apiUrl = new URL(rawUrl);
+  } catch {
+    throw new HarnessDispatchError("INVALID_HARNESS_URL", `${fieldName} must be a valid URL`);
+  }
+  const protocolLabel = allowHttp ? "http or https" : "https";
+  if (apiUrl.protocol !== "https:" && !(allowHttp && apiUrl.protocol === "http:")) {
+    throw new HarnessDispatchError("INVALID_HARNESS_URL", `${fieldName} must use ${protocolLabel}`);
+  }
+  const { origin } = apiUrl;
+  if (
+    apiUrl.username !== "" ||
+    apiUrl.password !== "" ||
+    apiUrl.search !== "" ||
+    apiUrl.hash !== "" ||
+    ![origin, `${origin}/`, `${origin}/api/v1`, `${origin}/api/v1/`].includes(rawUrl)
+  ) {
+    throw new HarnessDispatchError(
+      "INVALID_HARNESS_URL",
+      `${fieldName} must be an exact ${protocolLabel} origin, optionally suffixed with /api/v1`,
+    );
+  }
+  return new URL(origin);
+}
+
+export function parseHarnessApiOrigin(environment) {
+  return parseApiOrigin(requiredEnvironmentValue(environment, "HARNESS_URL"), {
+    fieldName: "HARNESS_URL",
+  });
+}

package/src/actions/write-outputs.js

@@ -0,0 +1,42 @@
+import { appendFileSync } from "node:fs";
+
+function formatTargetRef(ref) {
+  if ("providerId" in ref) return `\`${ref.providerId}\``;
+  if ("providerName" in ref) return `\`${ref.providerName}\``;
+  if ("commandId" in ref) return `\`${ref.commandId}\``;
+  return `\`${ref.commandName}\``;
+}
+
+export function writeOutputs(environment, result, route) {
+  if (environment.GITHUB_OUTPUT) {
+    appendFileSync(
+      environment.GITHUB_OUTPUT,
+      `session-id=${result.id}\nsession-url=${result.url}\ncreated=${result.created}\n`,
+      "utf8",
+    );
+  }
+  if (environment.GITHUB_STEP_SUMMARY) {
+    const routeText = route?.length
+      ? route.map(formatTargetRef).join(" → ")
+      : "retained from the existing session";
+    const concurrencyId = environment.HARNESS_CONCURRENCY_ID?.trim();
+    appendFileSync(
+      environment.GITHUB_STEP_SUMMARY,
+      [
+        "## Auto Harness dispatch",
+        "",
+        `- Session: [${result.id}](${result.url})`,
+        `- Created: ${result.created ? "yes" : "no"}`,
+        ...(concurrencyId ? [`- Concurrency: \`${concurrencyId}\``] : []),
+        `- Provider route: ${routeText}`,
+        "",
+      ].join("\n"),
+      "utf8",
+    );
+  }
+  if (environment.GITHUB_ACTIONS === "true") {
+    process.stdout.write(
+      `::notice title=Auto Harness session::${result.id} ${result.created ? "created" : "reused"} ${result.url}\n`,
+    );
+  }
+}

package/src/catalog-types.d.ts

@@ -0,0 +1,41 @@
+/** 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. New and renamed names are catalog-unique slugs. */
+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;
+};

package/src/errors.js

@@ -0,0 +1,31 @@
+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;
+  }
+}
+
+export class AutoHarnessDrainWaitTimeoutError extends Error {
+  constructor(repositoryId, operationId, timeoutMs) {
+    super(`Auto Harness session drain wait timed out after ${timeoutMs}ms`);
+    this.name = "AutoHarnessDrainWaitTimeoutError";
+    this.code = "DRAIN_WAIT_TIMEOUT";
+    this.repositoryId = repositoryId;
+    this.operationId = operationId;
+    this.timeoutMs = timeoutMs;
+  }
+}

package/src/index.d.ts

@@ -1,7 +1,32 @@
+import type { Command, Provider } from "./catalog-types.js";
+export type { Command, Provider, ResumeRefCapture, UsageRates } from "./catalog-types.js";
+
 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` — checked defensively for legacy/racy duplicates. */
+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;
+
+/** A repository target, by id or by unique `name` — checked defensively for legacy/racy duplicates. */
+export type RepositoryRef =
+  | { repositoryId: string; repositoryName?: never }
+  | { repositoryName: string; repositoryId?: never };
+
 /** Values accepted for a session metadata entry. */
 export type SessionMetadataValue = string | number | boolean | null;
 
@@ -14,11 +39,10 @@ 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;
+export type CreateSessionInput = RepositoryRef & {
   prompt: string;
-  target: TargetRef;
-  fallbacks?: TargetRef[];
+  target: TargetSpec;
+  fallbacks?: TargetSpec[];
   ref?: string;
   concurrencyId?: string;
   queueTtlSeconds?: number;
@@ -122,7 +146,7 @@ export type RepositoryPage = {
 
 export type SessionDrainStatus = "draining" | "succeeded" | "failed" | "released";
 
-/** Bounded, durable progress for the authenticated principal's repository session drain. */
+/** 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;
@@ -140,6 +164,13 @@ export type SessionDrain = {
   failureCode?: string;
 };
 
+/**
+ * Thrown for a failed HTTP response, and also, with `status: 400`, when `createSession()` (or a
+ * drain method) cannot resolve a `TargetSpec` or `RepositoryRef` name: `code ===
+ * "UNKNOWN_PROVIDER_NAME"` / `"UNKNOWN_COMMAND_NAME"` / `"UNKNOWN_REPOSITORY_NAME"` for no match,
+ * `"AMBIGUOUS_PROVIDER_NAME"` / `"AMBIGUOUS_COMMAND_NAME"` / `"AMBIGUOUS_REPOSITORY_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;
@@ -166,12 +197,35 @@ export class AutoHarnessRequestTimeoutError extends Error {
   constructor(timeoutMs: number);
 }
 
+/**
+ * Thrown by `waitForSessionDrain()` when its overall `timeoutMs` budget elapses.
+ *
+ * `repositoryId` echoes back whatever was passed to `waitForSessionDrain()`: a plain
+ * repository id string, or the `RepositoryRef` (e.g. `{ repositoryName }`) that was still
+ * unresolved when the deadline hit.
+ */
+export class AutoHarnessDrainWaitTimeoutError extends Error {
+  code: "DRAIN_WAIT_TIMEOUT";
+  repositoryId: string | RepositoryRef;
+  operationId: string;
+  timeoutMs: number;
+  constructor(repositoryId: string | RepositoryRef, operationId: string, 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;
+  /**
+   * Allows a non-`https` `baseUrl` while `apiKey` is set, but only when `baseUrl`'s host is
+   * genuine loopback (127.0.0.0/8, `::1`, or `localhost`) — see `isLoopbackOrigin()` in
+   * `auto-harness-client/loopback`. The constructor independently verifies this and throws for
+   * any non-loopback `http:` baseUrl even when this is `true`; a private-network address
+   * (RFC1918) still crosses real network hardware and is not loopback. Defaults to `false`.
+   */
+  allowInsecureHttp?: boolean;
 };
 
 export class AutoHarnessClient {
@@ -181,14 +235,34 @@ export class AutoHarnessClient {
   cancelSession(id: string): Promise<Session>;
   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,
+    repositoryId: string | RepositoryRef,
     options?: { idempotencyKey?: string },
   ): Promise<SessionDrain>;
-  getSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
-  releaseSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
+  getSessionDrain(repositoryId: string | RepositoryRef, operationId: string): Promise<SessionDrain>;
+  releaseSessionDrain(
+    repositoryId: string | RepositoryRef,
+    operationId: string,
+  ): Promise<SessionDrain>;
+  /**
+   * Resolves `repositoryId`, then polls `getSessionDrain()` until it reports a terminal status,
+   * clamping every request — including each page fetched to resolve a `repositoryName` — to the
+   * time remaining before `timeoutMs`. Resolves with the terminal `SessionDrain` for any status;
+   * callers classify success themselves. Rejects with `AutoHarnessDrainWaitTimeoutError` when the
+   * overall `timeoutMs` budget elapses — including when a clamped request is the thing that
+   * times out at that same instant — or with `AutoHarnessRequestTimeoutError` if an individual
+   * request times out while budget still remains.
+   */
+  waitForSessionDrain(
+    repositoryId: string | RepositoryRef,
+    operationId: string,
+    options: { pollIntervalMs: number; timeoutMs: number },
+  ): 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,23 +1,13 @@
-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;
-  }
-}
+import {
+  AutoHarnessDrainWaitTimeoutError,
+  AutoHarnessError,
+  AutoHarnessRequestTimeoutError,
+} from "./errors.js";
+import { assertSecureTransport } from "./loopback.js";
+import { resolveRepositoryId } from "./resolve-repository.js";
+import { resolveCreateSessionTargets } from "./resolve-target.js";
 
-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;
-  }
-}
+export { AutoHarnessDrainWaitTimeoutError, AutoHarnessError, AutoHarnessRequestTimeoutError };
 
 export class AutoHarnessClient {
   constructor(options) {
@@ -31,6 +21,8 @@ export class AutoHarnessClient {
     }
     this.baseUrl = options.baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
     this.apiKey = options.apiKey;
+    this.allowInsecureHttp = Boolean(options.allowInsecureHttp);
+    assertSecureTransport(this.baseUrl, this.apiKey, this.allowInsecureHttp);
     this.fetch = options.fetch ?? globalThis.fetch;
     if (!this.fetch) throw new TypeError("fetch is required");
     this.requestTimeoutMs = requestTimeoutMs;
@@ -84,8 +76,9 @@ export class AutoHarnessClient {
     }
   }
 
-  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) {
@@ -123,8 +116,9 @@ export class AutoHarnessClient {
    * 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`, {
+  async startSessionDrain(repositoryId, options = {}) {
+    const id = await resolveRepositoryId(this, repositoryId);
+    return this.request(`/repositories/${encodeURIComponent(id)}/session-drains`, {
       method: "POST",
       ...(options.idempotencyKey === undefined
         ? {}
@@ -133,20 +127,78 @@ export class AutoHarnessClient {
   }
 
   /** Get bounded durable progress or terminal proof for one principal session drain. */
-  getSessionDrain(repositoryId, operationId) {
+  async getSessionDrain(repositoryId, operationId) {
+    const id = await resolveRepositoryId(this, repositoryId);
     return this.request(
-      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}`,
+      `/repositories/${encodeURIComponent(id)}/session-drains/${encodeURIComponent(operationId)}`,
     );
   }
 
   /** Explicitly reopen admission after a succeeded or failed principal session drain. */
-  releaseSessionDrain(repositoryId, operationId) {
+  async releaseSessionDrain(repositoryId, operationId) {
+    const id = await resolveRepositoryId(this, repositoryId);
     return this.request(
-      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}/release`,
+      `/repositories/${encodeURIComponent(id)}/session-drains/${encodeURIComponent(operationId)}/release`,
       { method: "POST" },
     );
   }
 
+  /**
+   * Resolves `repositoryId`, then polls `getSessionDrain()` until it reports a terminal status,
+   * clamping every request — including each page fetched to resolve a `repositoryName` — to the
+   * time remaining before `timeoutMs`, recomputed fresh per request, so no single request can
+   * outlive the overall wait. Resolves with the terminal `SessionDrain` for any status, including
+   * "failed" and "released" — callers classify success themselves. Rejects with
+   * `AutoHarnessDrainWaitTimeoutError` when the overall `timeoutMs` budget elapses — including
+   * when a clamped request is the thing that times out at that same instant — or with
+   * `AutoHarnessRequestTimeoutError` if an individual request times out while budget still
+   * remains (e.g. a slow server response, well inside `timeoutMs`).
+   */
+  async waitForSessionDrain(repositoryId, operationId, options = {}) {
+    const { pollIntervalMs, timeoutMs } = options;
+    if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0)
+      throw new TypeError("pollIntervalMs must be a finite positive number");
+    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
+        ? new AutoHarnessDrainWaitTimeoutError(idForError, operationId, timeoutMs)
+        : error;
+
+    const id = await resolveRepositoryId(
+      { listRepositories: (listOptions) => clampedClient().listRepositories(listOptions) },
+      repositoryId,
+    ).catch((error) => {
+      throw rejectAtDeadline(error, repositoryId);
+    });
+    for (;;) {
+      if (deadline - Date.now() <= 0) {
+        throw new AutoHarnessDrainWaitTimeoutError(id, operationId, timeoutMs);
+      }
+      const sessionDrain = await clampedClient()
+        .getSessionDrain(id, operationId)
+        .catch((error) => {
+          throw rejectAtDeadline(error, id);
+        });
+      if (sessionDrain.status !== "draining") return sessionDrain;
+      const delayMs = Math.min(pollIntervalMs, deadline - Date.now());
+      if (delayMs <= 0) throw new AutoHarnessDrainWaitTimeoutError(id, operationId, timeoutMs);
+      await new Promise((resolve) => setTimeout(resolve, delayMs));
+    }
+  }
+
   listRepositories(options = {}) {
     const query = new URLSearchParams();
     if (options.limit !== undefined) query.set("limit", String(options.limit));
@@ -170,4 +222,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/loopback.d.ts

@@ -0,0 +1,5 @@
+/** True when `hostname` (as normalized by `URL#hostname`) is genuine loopback. */
+export function isLoopbackHostname(hostname: string): boolean;
+
+/** Loopback check for a `baseUrl` string; an unparseable URL is treated as non-loopback. */
+export function isLoopbackOrigin(rawUrl: string): boolean;

package/src/loopback.js

@@ -0,0 +1,43 @@
+function isLoopbackIpv4(hostname) {
+  const octets = hostname.split(".");
+  if (
+    octets.length !== 4 ||
+    !octets.every((octet) => /^\d{1,3}$/.test(octet) && Number(octet) <= 255)
+  ) {
+    return false;
+  }
+  return Number(octets[0]) === 127;
+}
+
+/**
+ * True when `hostname` (as normalized by `URL#hostname`, e.g. lowercased, IPv6
+ * bracketed as `[::1]`) can never leave the local machine's kernel: the IPv4
+ * loopback block 127.0.0.0/8, the IPv6 loopback address `::1`, or `localhost`
+ * (RFC 6761 §6.3 reserves this name to always resolve to loopback).
+ *
+ * RFC1918 private addresses and other custom hostnames are deliberately excluded:
+ * they still cross real network hardware (switches, VPN, VPC peering) where
+ * plaintext credentials can be sniffed, and trusting a caller's claim that a
+ * hostname "resolves to loopback" would just reintroduce an unverified bypass.
+ */
+export function isLoopbackHostname(hostname) {
+  return hostname === "localhost" || hostname === "[::1]" || isLoopbackIpv4(hostname);
+}
+
+/** Loopback check for a `baseUrl` string; an unparseable URL is treated as non-loopback. */
+export function isLoopbackOrigin(rawUrl) {
+  try {
+    return isLoopbackHostname(new URL(rawUrl).hostname);
+  } catch {
+    return false;
+  }
+}
+
+/** Throws when `apiKey` would travel over plain HTTP to a non-loopback `baseUrl`. */
+export function assertSecureTransport(baseUrl, apiKey, allowInsecureHttp) {
+  if (!apiKey || baseUrl.startsWith("https://")) return;
+  if (allowInsecureHttp && isLoopbackOrigin(baseUrl)) return;
+  throw new TypeError(
+    "baseUrl must use https when apiKey is set (allowInsecureHttp only permits plain HTTP to a loopback baseUrl, e.g. http://127.0.0.1 or http://localhost)",
+  );
+}

package/src/resolve-by-name.js

@@ -0,0 +1,25 @@
+import { AutoHarnessError } from "./errors.js";
+
+/**
+ * Resolves a unique `name` to its `id` within a catalog loaded by `catalog()`. Catalog rows are
+ * checked defensively for more than one match: create/update name-uniqueness checks are
+ * read-then-write races rather than atomic constraints, and legacy rows are not rewritten.
+ */
+export async function resolveByName(name, catalog, kind) {
+  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 === "repository" ? "repositories" : `${kind}s`
+      } share this name`,
+      { status: 400, code: `AMBIGUOUS_${kind.toUpperCase()}_NAME` },
+    );
+  }
+  return matches[0].id;
+}

package/src/resolve-repository.js

@@ -0,0 +1,23 @@
+import { resolveByName } from "./resolve-by-name.js";
+
+async function listAllRepositories(client) {
+  const items = [];
+  let page = await client.listRepositories();
+  items.push(...page.items);
+  while (page.nextCursor) {
+    page = await client.listRepositories({ cursor: page.nextCursor });
+    items.push(...page.items);
+  }
+  return items;
+}
+
+/**
+ * Resolves a `repositoryId` string or a `RepositoryRef` to a `repositoryId`. Unlike providers and
+ * commands, repositories are not exposed as a single unpaginated catalog call, so resolving by
+ * `repositoryName` pages through `listRepositories()` in full before matching.
+ */
+export async function resolveRepositoryId(client, ref) {
+  if (typeof ref === "string") return ref;
+  if (ref.repositoryId !== undefined) return ref.repositoryId;
+  return resolveByName(ref.repositoryName, () => listAllRepositories(client), "repository");
+}

package/src/resolve-target.js

@@ -0,0 +1,46 @@
+import { resolveByName } from "./resolve-by-name.js";
+import { resolveRepositoryId } from "./resolve-repository.js";
+
+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 { providerId: await resolveByName(ref.providerName, providers, "provider") };
+  }
+  if (ref.commandName !== undefined) {
+    return { commandId: await resolveByName(ref.commandName, commands, "command") };
+  }
+  return ref;
+}
+
+/**
+ * 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.
+ */
+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);
+  const repositoryId = await resolveRepositoryId(
+    client,
+    input.repositoryId !== undefined
+      ? input.repositoryId
+      : { repositoryName: input.repositoryName },
+  );
+  const resolved = { ...input, repositoryId, target };
+  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 };
+}