auto-harness-client 0.3.0 → 0.4.0

package/README.md

@@ -22,6 +22,30 @@ const session = await harness.createSession({
 console.log(session.url);
 ```
 
+## Target by provider or command name
+
+`target` and `fallbacks` accept a `providerId`/`commandId` as before, or a human-readable
+`providerName`/`commandName`. `createSession()` resolves each name to an id via
+`listProviders()`/`listCommands()` before sending the request — at most one list call per catalog,
+regardless of how many refs need it, and none at all when every ref is already id-based.
+
+```js
+const session = await harness.createSession({
+  repositoryId: "repo-1",
+  prompt: "Review the latest changes",
+  target: { providerName: "codex" },
+  fallbacks: [{ commandName: "claude-print-plan" }],
+  timeout: 1_800,
+});
+```
+
+Provider names are normally unique — server-enforced on create/update — but that check is a
+read-then-write race, not an atomic constraint, so `providerName` resolution still checks for
+more than one match rather than trusting uniqueness. Command names are **not** server-enforced
+unique at all. Either way, an unresolvable or ambiguous name throws `AutoHarnessError`
+(`code === "UNKNOWN_PROVIDER_NAME"`, `"UNKNOWN_COMMAND_NAME"`, `"AMBIGUOUS_PROVIDER_NAME"`, or
+`"AMBIGUOUS_COMMAND_NAME"`); the ambiguous-name message never includes the matched ids.
+
 ## Request deadlines
 
 Every request has a deadline that includes receiving and consuming the JSON response body.
@@ -45,10 +69,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,8 +87,10 @@ 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"`

package/package.json

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

package/src/errors.js

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

package/src/index.d.ts

@@ -2,6 +2,23 @@ export type TargetRef =
   | { commandId: string; providerId?: never }
   | { providerId: string; commandId?: never };
 
+/** A provider target, by id or by `name` — normally unique, checked defensively either way. */
+export type ProviderRef =
+  | { providerId: string; providerName?: never; commandId?: never; commandName?: never }
+  | { providerName: string; providerId?: never; commandId?: never; commandName?: never };
+
+/** A command target, by id or by `name` — command names are not required to be unique. */
+export type CommandRef =
+  | { commandId: string; commandName?: never; providerId?: never; providerName?: never }
+  | { commandName: string; commandId?: never; providerId?: never; providerName?: never };
+
+/**
+ * Input-only target shape for `createSession()`: an id (as `TargetRef`) or a name.
+ * `createSession()` resolves a name to its id via `listProviders()`/`listCommands()` before
+ * sending the request; a name throws on no match or on more than one match sharing that name.
+ */
+export type TargetSpec = ProviderRef | CommandRef;
+
 /** Values accepted for a session metadata entry. */
 export type SessionMetadataValue = string | number | boolean | null;
 
@@ -17,8 +34,8 @@ export type CreatableSessionSource = "api" | "ui" | "webhook";
 export type CreateSessionInput = {
   repositoryId: string;
   prompt: string;
-  target: TargetRef;
-  fallbacks?: TargetRef[];
+  target: TargetSpec;
+  fallbacks?: TargetSpec[];
   ref?: string;
   concurrencyId?: string;
   queueTtlSeconds?: number;
@@ -120,9 +137,51 @@ export type RepositoryPage = {
   nextCursor: string | null;
 };
 
+/** Operator-supplied per-token vendor rates; Auto Harness never fetches vendor prices. */
+export type UsageRates = {
+  inputTokenMicros?: string;
+  outputTokenMicros?: string;
+  cachedInputTokenMicros?: string;
+  reasoningTokenMicros?: string;
+  currency: string;
+};
+
+/** Global catalog entry: an AI CLI vendor, keyed by a unique, server-enforced `name`. */
+export type Provider = {
+  id: string;
+  /** e.g. "claude", "codex", "grok" */
+  name: string;
+  defaultCommandId: string | null;
+  createdAt: string;
+  updatedAt: string;
+  usageRates?: UsageRates;
+};
+
+/** Bounded literal-prefix policy used by the agent to extract a native resume reference. */
+export type ResumeRefCapture = {
+  stream: "stdout" | "stderr" | "either";
+  linePrefix: string;
+};
+
+/** Global catalog entry: a named command invocation. `name` is not required to be unique. */
+export type Command = {
+  id: string;
+  /** e.g. "claude-print", "echo hello world" */
+  name: string;
+  argv: string[];
+  appendPrompt: boolean;
+  appendPromptSeparator?: boolean;
+  resumeArgvTemplate?: string[];
+  resumeRefCapture?: ResumeRefCapture;
+  /** FK to Provider, or null for a standalone command that runs anywhere ungated. */
+  providerId: string | null;
+  createdAt: string;
+  updatedAt: string;
+};
+
 export type SessionDrainStatus = "draining" | "succeeded" | "failed" | "released";
 
-/** Bounded, durable progress for 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 +199,13 @@ export type SessionDrain = {
   failureCode?: string;
 };
 
+/**
+ * Thrown for a failed HTTP response, and also, with `status: 400`, when `createSession()`
+ * cannot resolve a `TargetSpec` name: `code === "UNKNOWN_PROVIDER_NAME"` /
+ * `"UNKNOWN_COMMAND_NAME"` for no match, `"AMBIGUOUS_PROVIDER_NAME"` /
+ * `"AMBIGUOUS_COMMAND_NAME"` for more than one match sharing a name — that message never
+ * includes the matched ids.
+ */
 export class AutoHarnessError extends Error {
   status: number;
   code: string;
@@ -181,6 +247,7 @@ 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,
     options?: { idempotencyKey?: string },
@@ -191,4 +258,6 @@ export class AutoHarnessClient {
   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,7 @@
-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 { AutoHarnessError, AutoHarnessRequestTimeoutError } from "./errors.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 { AutoHarnessError, AutoHarnessRequestTimeoutError };
 
 export class AutoHarnessClient {
   constructor(options) {
@@ -84,8 +68,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) {
@@ -170,4 +155,14 @@ export class AutoHarnessClient {
   repositoryOperation(id, operation) {
     return this.request(`/repositories/${encodeURIComponent(id)}/${operation}`, { method: "POST" });
   }
+
+  async listProviders() {
+    const { items } = await this.request("/providers");
+    return items;
+  }
+
+  async listCommands() {
+    const { items } = await this.request("/commands");
+    return items;
+  }
 }

package/src/resolve-target.js

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