auto-harness-client 0.1.0 → 0.3.0

package/README.md

@@ -9,13 +9,96 @@ import { AutoHarnessClient } from "auto-harness-client";
 const harness = new AutoHarnessClient({
   baseUrl: process.env.AUTO_HARNESS_URL,
   apiKey: process.env.AUTO_HARNESS_API_KEY,
+  requestTimeoutMs: 30_000,
 });
 
 const session = await harness.createSession({
   repositoryId: "repo-1",
   prompt: "Review the latest changes",
   target: { providerId: "codex" },
+  timeout: 1_800,
   concurrencyId: `github-${process.env.GITHUB_RUN_ID}`,
 });
 console.log(session.url);
 ```
+
+## Request deadlines
+
+Every request has a deadline that includes receiving and consuming the JSON response body.
+`requestTimeoutMs` defaults to `30_000` and must be a finite positive number no greater than
+`300_000`. On expiry, the client throws `AutoHarnessRequestTimeoutError`, with
+`code === "REQUEST_TIMEOUT"` and the configured `timeoutMs`. The client never retries requests
+automatically; reuse an idempotency key where an ambiguous `POST` may safely be retried.
+
+## Repository listing
+
+Repository listings are bounded pages. Pass the returned cursor to load the next page:
+
+```js
+let page = await harness.listRepositories({ limit: 50 });
+const repositories = [...page.items];
+while (page.nextCursor) {
+  page = await harness.listRepositories({ limit: 50, cursor: page.nextCursor });
+  repositories.push(...page.items);
+}
+```
+
+## 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.
+
+```js
+const drain = await harness.startSessionDrain("repo-1", {
+  idempotencyKey: `deploy-${process.env.GITHUB_RUN_ID}`,
+});
+
+let progress = drain;
+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}`);
+await harness.releaseSessionDrain("repo-1", drain.operationId);
+```
+
+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.
+
+## Resume a session
+
+Resume re-runs a previously assigned session. It initially prefers the source host and its stored
+native command/account route, using a native CLI resume where the provider supports it. If that
+route becomes unavailable or its pin expires, the control plane clears the pin and falls back to a
+fresh run through the normal target/fallback chain, which may land on another host. The source
+session must have been assigned at least once, must not still be queued or running, and must not
+be a scheduled session — sessions with `type: "scheduled"` are rejected with `409 CONFLICT`, since
+only prompt sessions support resume.
+
+```js
+const resumed = await harness.resumeSession("session-1", { prompt: "Address the review comments" });
+console.log(resumed.status);
+```
+
+## List sessions
+
+Session listings are bounded pages with the same cursor shape as repository listings, plus
+filters for status, repository, host, origin, sort order, concurrency identity, and schedule
+provenance:
+
+```js
+let page = await harness.listSessions({ repositoryId: "repo-1", status: "running", limit: 50 });
+const sessions = [...page.items];
+while (page.nextCursor) {
+  page = await harness.listSessions({
+    repositoryId: "repo-1",
+    status: "running",
+    limit: 50,
+    cursor: page.nextCursor,
+  });
+  sessions.push(...page.items);
+}
+```

package/package.json

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

package/src/index.d.ts

@@ -2,6 +2,18 @@ export type TargetRef =
   | { commandId: string; providerId?: never }
   | { providerId: string; commandId?: never };
 
+/** Values accepted for a session metadata entry. */
+export type SessionMetadataValue = string | number | boolean | null;
+
+/** Whether a session was created directly or fired by a schedule. */
+export type SessionType = "prompt" | "scheduled";
+
+/** Origin that requested the session. */
+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;
   prompt: string;
@@ -10,44 +22,172 @@ export type CreateSessionInput = {
   ref?: string;
   concurrencyId?: string;
   queueTtlSeconds?: number;
-  timeout?: number;
+  timeout: number;
   priority?: number;
   requiredLabels?: string[];
-  metadata?: Record<string, unknown>;
+  metadata?: Record<string, SessionMetadataValue>;
+  /** Defaults to `"api"`; `"ui"`/`"webhook"` pass through, anything else becomes `"api"`. */
+  source?: CreatableSessionSource;
 };
 
-export type Session = CreateSessionInput & {
+export type Session = {
   id: string;
+  repositoryId: string;
+  prompt: string;
+  target: TargetRef;
+  fallbacks?: TargetRef[];
+  ref?: string;
+  concurrencyId?: string;
+  queueTtlSeconds?: number;
+  timeout?: number;
+  priority?: number;
+  requiredLabels?: string[];
+  metadata?: Record<string, SessionMetadataValue>;
   status: string;
+  /** Absent on sessions persisted before this field existed. */
+  type?: SessionType;
+  /** Absent on sessions persisted before this field existed. */
+  source?: SessionSource;
   createdAt: string;
   url: string;
   created?: boolean;
 };
 
+/** Body accepted by `POST /sessions/:id/resume`. */
+export type ResumeSessionInput = {
+  prompt?: string;
+  concurrencyId?: string;
+  timeout?: number;
+  priority?: number;
+};
+
+/** `status` filter accepted by `GET /sessions`. */
+export type SessionStatusFilter =
+  | "all"
+  | "queued"
+  | "running"
+  | "completed"
+  | "failed"
+  | "cancelled"
+  | "timed_out";
+
+export type SessionListSort = "latest" | "oldest" | "priority_desc" | "priority_asc";
+
+export type ListSessionsOptions = {
+  status?: SessionStatusFilter;
+  repositoryId?: string;
+  hostId?: string;
+  source?: SessionSource;
+  sort?: SessionListSort;
+  /** Number of sessions to return (1–100, default 50). */
+  limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
+  concurrencyId?: string;
+  scheduleId?: string;
+};
+
+export type SessionPage = {
+  items: Session[];
+  nextCursor: string | null;
+};
+
 export type Repository = {
   id: string;
   name: string;
   url: string;
   defaultBranch: string;
+  createdAt?: string;
+  updatedAt?: string;
+  sessionCount?: number;
+  worktreeCount?: number;
+  scheduleCount?: number;
   admissionState?: "active" | "paused" | "draining";
   admissionStateChangedAt?: string;
   drainRequestedAt?: string;
   drainCompletedAt?: string;
 };
 
+export type ListRepositoriesOptions = {
+  /** Number of repositories to return (1–100, default 50). */
+  limit?: number;
+  /** Opaque cursor returned by a previous page. */
+  cursor?: string;
+};
+
+export type RepositoryPage = {
+  items: Repository[];
+  nextCursor: string | null;
+};
+
+export type SessionDrainStatus = "draining" | "succeeded" | "failed" | "released";
+
+/** Bounded, durable progress for the authenticated principal's repository session drain. */
+export type SessionDrain = {
+  operationId: string;
+  repositoryId: string;
+  status: SessionDrainStatus;
+  /** API-relative URL for polling this same operation. */
+  statusUrl: string;
+  requestedAt: string;
+  updatedAt: string;
+  deadlineAt: string;
+  queuedCount: number;
+  runningCount: number;
+  cancelledCount: number;
+  completedAt?: string;
+  releasedAt?: string;
+  failureCode?: string;
+};
+
 export class AutoHarnessError extends Error {
   status: number;
   code: string;
   retryAfter?: string;
-  constructor(message: string, options: { status: number; code: string; retryAfter?: string });
+  /** Present when a 409 DRAINING admission response identifies its durable drain. */
+  operationId?: string;
+  /** API-relative URL for the drain that fenced this request. */
+  statusUrl?: string;
+  constructor(
+    message: string,
+    options: {
+      status: number;
+      code: string;
+      retryAfter?: string;
+      operationId?: string;
+      statusUrl?: string;
+    },
+  );
 }
 
+export class AutoHarnessRequestTimeoutError extends Error {
+  code: "REQUEST_TIMEOUT";
+  timeoutMs: number;
+  constructor(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;
+};
+
 export class AutoHarnessClient {
-  constructor(options: { baseUrl: string; apiKey?: string; fetch?: typeof fetch });
+  constructor(options: AutoHarnessClientOptions);
   createSession(input: CreateSessionInput): Promise<Session & { created: boolean }>;
   getSession(id: string): Promise<Session>;
   cancelSession(id: string): Promise<Session>;
-  listRepositories(): Promise<{ items: Repository[] }>;
+  resumeSession(id: string, input?: ResumeSessionInput): Promise<Session & { created: boolean }>;
+  listSessions(options?: ListSessionsOptions): Promise<SessionPage>;
+  startSessionDrain(
+    repositoryId: string,
+    options?: { idempotencyKey?: string },
+  ): Promise<SessionDrain>;
+  getSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
+  releaseSessionDrain(repositoryId: string, operationId: string): Promise<SessionDrain>;
+  listRepositories(options?: ListRepositoriesOptions): Promise<RepositoryPage>;
   pauseRepository(id: string): Promise<Repository>;
   drainRepository(id: string): Promise<Repository>;
   activateRepository(id: string): Promise<Repository>;

package/src/index.js

@@ -5,36 +5,83 @@ export class AutoHarnessError extends Error {
     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 AutoHarnessClient {
   constructor(options) {
     if (!options?.baseUrl) throw new TypeError("baseUrl is required");
+    const requestTimeoutMs =
+      options.requestTimeoutMs === undefined ? 30_000 : options.requestTimeoutMs;
+    if (!Number.isFinite(requestTimeoutMs) || requestTimeoutMs <= 0 || requestTimeoutMs > 300_000) {
+      throw new TypeError(
+        "requestTimeoutMs must be a finite positive number no greater than 300000",
+      );
+    }
     this.baseUrl = options.baseUrl.replace(/\/$/, "").replace(/\/api\/v1$/, "");
     this.apiKey = options.apiKey;
     this.fetch = options.fetch ?? globalThis.fetch;
     if (!this.fetch) throw new TypeError("fetch is required");
+    this.requestTimeoutMs = requestTimeoutMs;
   }
 
   async request(path, init = {}) {
     const headers = { accept: "application/json", ...init.headers };
     if (init.body !== undefined) headers["content-type"] = "application/json";
     if (this.apiKey) headers.authorization = `Bearer ${this.apiKey}`;
-    const response = await this.fetch(`${this.baseUrl}/api/v1${path}`, { ...init, headers });
-    const body = response.status === 204 ? undefined : await response.json().catch(() => undefined);
-    if (!response.ok) {
-      const error = body?.error;
-      throw new AutoHarnessError(
-        error?.message ?? `Auto Harness request failed (${response.status})`,
-        {
-          status: response.status,
-          code: error?.code ?? "HTTP_ERROR",
-          retryAfter: response.headers.get("retry-after") ?? undefined,
-        },
-      );
+    const controller = new AbortController();
+    const timeoutError = new AutoHarnessRequestTimeoutError(this.requestTimeoutMs);
+    let timeoutId;
+    const timeout = new Promise((_, reject) => {
+      timeoutId = setTimeout(() => {
+        controller.abort();
+        reject(timeoutError);
+      }, this.requestTimeoutMs);
+    });
+    const request = (async () => {
+      const response = await this.fetch(`${this.baseUrl}/api/v1${path}`, {
+        ...init,
+        headers,
+        signal: controller.signal,
+      });
+      const body =
+        response.status === 204
+          ? undefined
+          : await response.json().catch((error) => {
+              if (controller.signal.aborted) throw error;
+              return undefined;
+            });
+      if (!response.ok) {
+        const error = body?.error;
+        throw new AutoHarnessError(
+          error?.message ?? `Auto Harness request failed (${response.status})`,
+          {
+            status: response.status,
+            code: error?.code ?? "HTTP_ERROR",
+            retryAfter: response.headers.get("retry-after") ?? undefined,
+            operationId: error?.operationId,
+            statusUrl: error?.statusUrl,
+          },
+        );
+      }
+      return body;
+    })();
+    try {
+      return await Promise.race([request, timeout]);
+    } finally {
+      clearTimeout(timeoutId);
     }
-    return body;
   }
 
   createSession(input) {
@@ -49,8 +96,63 @@ export class AutoHarnessClient {
     return this.request(`/sessions/${encodeURIComponent(id)}/cancel`, { method: "POST" });
   }
 
-  listRepositories() {
-    return this.request("/repositories");
+  /** Resume a previously assigned session on its pinned host, native CLI resume where supported. */
+  resumeSession(id, input) {
+    return this.request(`/sessions/${encodeURIComponent(id)}/resume`, {
+      method: "POST",
+      ...(input === undefined ? {} : { body: JSON.stringify(input) }),
+    });
+  }
+
+  listSessions(options = {}) {
+    const query = new URLSearchParams();
+    if (options.status !== undefined) query.set("status", options.status);
+    if (options.repositoryId !== undefined) query.set("repositoryId", options.repositoryId);
+    if (options.hostId !== undefined) query.set("hostId", options.hostId);
+    if (options.source !== undefined) query.set("source", options.source);
+    if (options.sort !== undefined) query.set("sort", options.sort);
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.cursor !== undefined) query.set("cursor", options.cursor);
+    if (options.concurrencyId !== undefined) query.set("concurrencyId", options.concurrencyId);
+    if (options.scheduleId !== undefined) query.set("scheduleId", options.scheduleId);
+    const suffix = query.toString();
+    return this.request(suffix ? `/sessions?${suffix}` : "/sessions");
+  }
+
+  /**
+   * 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`, {
+      method: "POST",
+      ...(options.idempotencyKey === undefined
+        ? {}
+        : { headers: { "idempotency-key": options.idempotencyKey } }),
+    });
+  }
+
+  /** Get bounded durable progress or terminal proof for one principal session drain. */
+  getSessionDrain(repositoryId, operationId) {
+    return this.request(
+      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}`,
+    );
+  }
+
+  /** Explicitly reopen admission after a succeeded or failed principal session drain. */
+  releaseSessionDrain(repositoryId, operationId) {
+    return this.request(
+      `/repositories/${encodeURIComponent(repositoryId)}/session-drains/${encodeURIComponent(operationId)}/release`,
+      { method: "POST" },
+    );
+  }
+
+  listRepositories(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 ? `/repositories?${suffix}` : "/repositories");
   }
 
   pauseRepository(id) {