@larc-iu/plaid-client 0.2.0-alpha.11 → 0.2.0-alpha.12

package/index.d.ts

@@ -25,6 +25,8 @@ interface ServiceParam {
   min?: number;
   max?: number;
   step?: number;
+  /** `number` only: render as a slider to drag rather than a box to type in. */
+  slider?: boolean;
   /** `string` only. */
   placeholder?: string;
   multiline?: boolean;
@@ -70,14 +72,41 @@ interface ServiceRegistration {
 }
 
 /** Connection-state transitions reported by a service registration. */
-type ServiceStatusEvent = 'registered' | 'reconnected' | 'disconnected';
+type ServiceStatusEvent = "registered" | "reconnected" | "disconnected";
 
 interface ResponseHelper {
-  progress(percent: number, message: string): void;
+  requestId: string;
+  requesterId: string | null;
+  /** True once the requester has asked this request to stop. */
+  readonly cancelled: boolean;
+  /**
+   * Report progress — and a cancellation CHECKPOINT: throws
+   * `ServiceCancelled` once a stop has been asked for, which is what makes a
+   * service that already reports progress cancellable for free.
+   */
+  progress(percent: number, message: string, extra?: Record<string, any>): void;
+  /** Stop here if the requester has asked the request to stop. */
+  raiseIfCancelled(): void;
+  /** Run `fn` as a stretch that must finish once begun, usually the writes. */
+  critical<T>(fn: () => T | Promise<T>): Promise<T>;
   complete(data: any): void;
+  /** End the request because it was asked to stop; result carries `stopped: true`. */
+  stopped(data?: any): void;
   error(error: string | Error): void;
 }
 
+/** Thrown inside a handler when the requester has asked it to stop. */
+export class ServiceCancelled extends Error {
+  constructor(message?: string);
+}
+
+/** The cancellation half of a responseHelper, on its own. */
+export function createCancelScope(isCancelled: () => boolean): {
+  readonly cancelled: boolean;
+  raiseIfCancelled(): void;
+  critical<T>(fn: () => T | Promise<T>): Promise<T>;
+};
+
 interface SSEConnection {
   close(): void;
   getStats(): any;
@@ -267,6 +296,7 @@ interface UsersBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(userId: string, opts?: AuditPageOptions): Promise<Page>;
   get(id: string, asOf?: string): Promise<any>;
   delete(id: string, auditMessage?: string): Promise<any>;
   activate(id: string, auditMessage?: string): Promise<any>;
@@ -313,12 +343,7 @@ interface CommentFilters {
 
 /** Entities that can carry a comment. */
 type CommentableType =
-  | "document"
-  | "text"
-  | "token"
-  | "span"
-  | "relation"
-  | "vocab-item";
+  "document" | "text" | "token" | "span" | "relation" | "vocab-item";
 
 interface Comment {
   id: string;
@@ -446,15 +471,182 @@ interface CreateInviteOptions {
   note?: string;
 }
 
+/** Server limits, as reported by /api/v1/info. An unset limit is absent. */
+interface ServerLimits {
+  mediaFileBytes?: number;
+  jsonBodyBytes?: number;
+  batchOperations?: number;
+  metadataDepth?: number;
+  metadataKeyCount?: number;
+  metadataStringLength?: number;
+  metadataTotalBytes?: number;
+  userDataValueBytes?: number;
+}
+
+interface ServerHealth {
+  ok: boolean;
+  version: string;
+  uptimeMs: number;
+  audit: { dbSizeMb?: number; auditRows?: number; error?: string };
+}
+
+interface DocumentLock {
+  documentId: string;
+  userId: string;
+  expiresAt: number;
+}
+
+interface RateLimitBucket {
+  ip: string;
+  userId?: string;
+  failures: number;
+  limit: number;
+  blocked: boolean;
+}
+
+interface RateLimitSnapshot {
+  windowMs: number;
+  logins: RateLimitBucket[];
+  ips: RateLimitBucket[];
+  invites: RateLimitBucket[];
+}
+
+interface BackupStatus {
+  enabled: boolean;
+  directory: string;
+  retention: number;
+  time: string;
+  backups: Array<{ name: string; bytes: number; modified: string }>;
+  ok?: boolean;
+}
+
+interface ServerReport {
+  version: string;
+  jvm: {
+    uptimeMs: number;
+    startedAt: string;
+    java: string;
+    heapUsed: number;
+    heapMax: number;
+  };
+  database: {
+    path: string | null;
+    bytes: number | null;
+    walBytes: number | null;
+    slowQueryThresholdMs?: number;
+    journalMode?: string;
+    maxPoolSize?: number;
+    tables: Record<string, number | null>;
+  };
+  media: {
+    directory: string;
+    files: number;
+    bytes: number;
+    orphans: number;
+    orphanBytes: number;
+  };
+  backup: BackupStatus;
+  settings: Record<string, any>;
+}
+
+/** Server-level facts. `info` is fetched at most once per client. */
+interface ServerBundle {
+  info(): Promise<{ limits: ServerLimits }>;
+  limits(): Promise<ServerLimits>;
+  health(): Promise<ServerHealth>;
+}
+
+/** Instance-wide operations. Every method requires a global admin. */
+interface AdminBundle {
+  server(): Promise<ServerReport>;
+  backup(): Promise<BackupStatus>;
+  locks(): Promise<{ entries: DocumentLock[] }>;
+  releaseLock(documentId: string): Promise<{ result: string }>;
+  rateLimits(): Promise<RateLimitSnapshot>;
+  clearRateLimits(opts?: {
+    ip?: string;
+    userId?: string;
+  }): Promise<{ result: string }>;
+  logs(opts?: {
+    lines?: number;
+  }): Promise<{ file: string | null; lines: string[]; error?: string }>;
+  userData(opts?: AdminUserDataOptions): Promise<AdminUserDataEntry[]>;
+  userDataPage(
+    opts?: AdminUserDataOptions & { limit?: number; cursor?: string },
+  ): Promise<Page<AdminUserDataEntry>>;
+}
+
+/** Narrowings for the cross-account private-data listing. */
+interface AdminUserDataOptions {
+  /** Only keys starting with this literal head. */
+  prefix?: string;
+  /** Only keys matching this GLOB (`*` any run, `?` one character). */
+  pattern?: string;
+  includeValues?: boolean;
+}
+
+type AdminUserDataEntry = UserDataEntry & { userId: string };
+
+/** Options for a single page of any audit log. */
+interface AuditPageOptions {
+  startTime?: string;
+  endTime?: string;
+  asOf?: string;
+  opTypes?: string[] | string;
+  /** "desc" pages newest-first; a cursor belongs to the direction that made it. */
+  order?: "asc" | "desc";
+  limit?: number;
+  cursor?: string;
+}
+
+/** One user's activity over a scope and window. */
+interface ActivityTallyRow {
+  user: { id: string; displayName?: string };
+  operations: number;
+  changes: number;
+  documents: number;
+  firstTs: string;
+  lastTs: string;
+  byDay?: Array<{ date: string; changes: number }>;
+}
+
+/** Instance-wide audit reads and the per-user aggregate. */
+interface AuditBundle {
+  /** Admin only. */
+  list(opts?: {
+    startTime?: string;
+    endTime?: string;
+    opTypes?: string[] | string;
+  }): Promise<any[]>;
+  /** Admin only. */
+  listPage(opts?: AuditPageOptions): Promise<Page>;
+  /** Admin only. */
+  iterPages(opts?: {
+    startTime?: string;
+    endTime?: string;
+    opTypes?: string[] | string;
+    pageSize?: number;
+  }): AsyncGenerator<any[]>;
+  /** With projectId, open to that project's maintainers; without one, admin only. */
+  tally(opts?: {
+    projectId?: string;
+    startTime?: string;
+    endTime?: string;
+    daily?: boolean;
+  }): Promise<ActivityTallyRow[]>;
+}
+
 interface InvitesBundle {
-  list(opts?: { projectId?: string }): Promise<Invite[]>;
+  list(opts?: { projectId?: string; all?: boolean }): Promise<Invite[]>;
   listPage(opts?: {
     projectId?: string;
+    all?: boolean;
     limit?: number;
     cursor?: string;
   }): Promise<Page>;
   iterPages(opts?: {
     projectId?: string;
+    all?: boolean;
     pageSize?: number;
   }): AsyncGenerator<Invite[]>;
   /** The `code` is returned ONCE and is not recoverable afterward. */
@@ -532,6 +724,7 @@ interface DocumentsBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(documentId: string, opts?: AuditPageOptions): Promise<Page>;
   get(documentId: string, includeBody?: boolean, asOf?: string): Promise<any>;
   delete(documentId: string, auditMessage?: string): Promise<any>;
   update(documentId: string, name: string, auditMessage?: string): Promise<any>;
@@ -541,6 +734,19 @@ interface DocumentsBundle {
     metadata?: any,
     auditMessage?: string,
   ): Promise<any>;
+  /** Copy a document and everything in it into a new document of the same project. */
+  copy(
+    documentId: string,
+    name: string,
+    options?: { includeMedia?: boolean },
+    auditMessage?: string,
+  ): Promise<{ id: string; mediaError?: string }>;
+  restore(
+    documentId: string,
+    asOf: string,
+    options?: { dryRun?: boolean },
+    auditMessage?: string,
+  ): Promise<any>;
 }
 
 interface MessagesBundle {
@@ -567,7 +773,11 @@ interface MessagesBundle {
     serviceInfo: ServiceInfo,
     onServiceRequest: (data: any, responseHelper: ResponseHelper) => void,
     extras?: any,
-    onStatus?: (event: ServiceStatusEvent, projectId: string, detail?: string) => void,
+    onStatus?: (
+      event: ServiceStatusEvent,
+      projectId: string,
+      detail?: string,
+    ) => void,
   ): ServiceRegistration;
   /**
    * Submit work to a service; streams progress to `onProgress`, resolves with
@@ -618,6 +828,7 @@ interface ProjectsBundle {
     endTime?: string,
     asOf?: string,
   ): Promise<any[]>;
+  auditPage(projectId: string, opts?: AuditPageOptions): Promise<Page>;
   linkVocab(id: string, vocabId: string, auditMessage?: string): Promise<any>;
   unlinkVocab(id: string, vocabId: string, auditMessage?: string): Promise<any>;
   get(id: string, asOf?: string): Promise<any>;
@@ -852,6 +1063,9 @@ export declare class PlaidClient {
   apiTokens: ApiTokensBundle;
   userData: UserDataBundle;
   invites: InvitesBundle;
+  server: ServerBundle;
+  admin: AdminBundle;
+  audit: AuditBundle;
   comments: CommentsBundle;
   tokenLayers: TokenLayersBundle;
   documents: DocumentsBundle;
@@ -919,6 +1133,9 @@ export const TASKS: {
   readonly TRANSCRIBE: "transcribe";
   readonly LINK_VOCAB: "link-vocab";
   readonly ANALYZE: "analyze";
+  readonly TRANSLATE: "translate";
+  readonly ASSIST: "assist";
+  readonly DETECT_SPEECH: "detect-speech";
 };
 /** Whether a service serves a task (declared `extras.tasks`, legacy id-prefix fallback). */
 export function servesTask(service: DiscoveredService, task: string): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@larc-iu/plaid-client",
-  "version": "0.2.0-alpha.11",
+  "version": "0.2.0-alpha.12",
   "description": "JavaScript client for the Plaid annotation API",
   "type": "module",
   "repository": {

package/src/index.js

@@ -85,6 +85,31 @@ async function anonymousPost(baseUrl, path, body, options = {}) {
   }
 }
 
+/**
+ * GET a path with no authentication, for the two endpoints a client may need
+ * before it has a session: /health and /api/v1/info.
+ */
+async function anonymousGet(baseUrl, path, options = {}) {
+  const base = baseUrl.replace(/\/$/, "");
+  const url = `${base}${path}`;
+  try {
+    const fetchOptions = { method: "GET" };
+    const signal = timeoutSignal(
+      options.timeout !== undefined ? options.timeout : DEFAULT_TIMEOUT_MS,
+    );
+    if (signal) fetchOptions.signal = signal;
+
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) {
+      throw makeHttpError(response, await parseErrorBody(response), url, "GET");
+    }
+    return transformResponse(await response.json());
+  } catch (error) {
+    if (error.status) throw error;
+    throw makeNetworkError(error, url, "GET");
+  }
+}
+
 /**
  * The server's cap on operations per batch request (plaid.rest-api.v1.batch).
  * A batch queued past it is submitted as consecutive requests.
@@ -633,6 +658,42 @@ class PlaidClient {
         }),
     };
 
+    // Server-level facts. Fetched at most once: the limits cannot change while
+    // the server is up, and a caller asking "will this file be accepted" should
+    // not pay a round trip to find out.
+    let infoPromise = null;
+    this.server = {
+      /**
+       * This server's version and the limits it enforces, e.g.
+       * `{ limits: { mediaFileBytes, jsonBodyBytes, batchOperations, … } }`.
+       * Sizes are in bytes. Unauthenticated.
+       */
+      info: () => {
+        if (!infoPromise) {
+          // bypassBatch: a read belongs to whoever asked for it, not to
+          // whatever batch happens to be open on this shared client.
+          infoPromise = this._request("GET", "/api/v1/info", {
+            bypassBatch: true,
+          }).catch((err) => {
+            // A failure must not be cached: a client that starts before the
+            // server is up would never see the limits at all.
+            infoPromise = null;
+            throw err;
+          });
+        }
+        return infoPromise;
+      },
+      /** Just the limits, which is what a caller almost always wants. */
+      limits: async () => (await this.server.info()).limits,
+      /**
+       * Liveness, version and database size. Unauthenticated, and served
+       * outside the REST router at /health, so it answers even while the API
+       * is refusing requests. Never cached — the point is that it is current.
+       * @returns {Promise<{ok: boolean, version: string, uptimeMs: number, audit: object}>}
+       */
+      health: () => PlaidClient.health(this.baseUrl, { timeout: this.timeout }),
+    };
+
     this.batch = {
       /**
        * Execute multiple API operations atomically. If any operation fails, all
@@ -812,6 +873,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        userId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/users/${userId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * Get a user by ID
        * @param {string} id - The resource ID
@@ -1044,37 +1130,40 @@ class PlaidClient {
        * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        */
-      list: ({ projectId } = {}) =>
+      list: ({ projectId, all } = {}) =>
         listAll(this, "/api/v1/invites", {
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Fetch a single page of invites.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        * @param {number} [opts.limit] - Page size (1..1000; server default 100)
        * @param {string} [opts.cursor] - Opaque cursor from a previous page
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: ({ projectId, limit, cursor } = {}) =>
+      listPage: ({ projectId, all, limit, cursor } = {}) =>
         listPage(this, "/api/v1/invites", {
           limit,
           cursor,
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Async-iterate invites page by page; yields each page's entries array.
        * @param {object} [opts]
        * @param {string} [opts.projectId] - List this project's invites instead of your own
+       * @param {boolean} [opts.all] - List every invite on the server (admin only)
        * @param {number} [opts.pageSize] - Per-request page size
        * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: ({ projectId, pageSize } = {}) =>
+      iterPages: ({ projectId, all, pageSize } = {}) =>
         iterPages(this, "/api/v1/invites", {
           pageSize,
-          query: { "project-id": projectId },
+          query: { "project-id": projectId, all },
         }),
       /**
        * Mint an invite. The returned `code` is shown ONLY here — it is never
@@ -1134,6 +1223,206 @@ class PlaidClient {
         this._request("DELETE", `/api/v1/invites/${id}`, { auditMessage }),
     };
 
+    this.admin = {
+      /**
+       * Everything about the server in one read: version and JVM uptime,
+       * database size and per-table row counts, media directory usage, backup
+       * configuration and the backups on disk, and the settings an operator
+       * gets asked to confirm. Carries no secrets. Runs a count per table and
+       * walks the media directory, so open it, do not poll it. Admin only.
+       * @returns {Promise<{version: string, jvm: object, database: object, media: object, backup: object, settings: object}>}
+       */
+      server: () => this._request("GET", "/api/v1/admin/server"),
+      /**
+       * Take a database backup right now, outside the nightly schedule.
+       * Resolves to the backup block with `ok` reporting whether the snapshot
+       * succeeded. Uses VACUUM INTO, which only reads, so it is safe while
+       * people are working. Admin only.
+       * @returns {Promise<{ok: boolean, directory: string, backups: Array}>}
+       */
+      backup: () => this._request("POST", "/api/v1/admin/backup"),
+      /**
+       * Documents currently held by an editing lock, with who holds each and
+       * when it expires on its own. Admin only.
+       * @returns {Promise<{entries: Array<{documentId: string, userId: string, expiresAt: number}>}>}
+       */
+      locks: () => this._request("GET", "/api/v1/admin/locks"),
+      /**
+       * Drop the lock on a document whoever holds it. Idempotent. For a client
+       * that went away without releasing one. Admin only.
+       * @param {string} documentId - The document ID
+       */
+      releaseLock: (documentId) =>
+        this._request("DELETE", `/api/v1/admin/locks/${documentId}`),
+      /**
+       * Live login and invite rate-limit buckets: the address, the account
+       * where there is one, failures inside the window, the limit, and whether
+       * it is currently blocking. Admin only.
+       * @returns {Promise<{windowMs: number, logins: Array, ips: Array, invites: Array}>}
+       */
+      rateLimits: () => this._request("GET", "/api/v1/admin/rate-limits"),
+      /**
+       * Forget recorded rate-limit failures. With `ip`, clears that address,
+       * narrowed to one account with `userId`. With neither, clears every
+       * bucket. Only ever unblocks. Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.ip] - Clear only this address
+       * @param {string} [opts.userId] - Narrow to one account on that address
+       */
+      clearRateLimits: ({ ip, userId } = {}) =>
+        this._request("DELETE", "/api/v1/admin/rate-limits", {
+          queryParams: { ip, "user-id": userId },
+        }),
+      /**
+       * The tail of the configured log file. Resolves with an `error` string
+       * instead of lines when no log file is configured or it does not exist
+       * yet. Admin only.
+       * @param {object} [opts]
+       * @param {number} [opts.lines] - How many lines (default 200, max 2000)
+       * @returns {Promise<{file: (string|null), lines: string[], error?: string}>}
+       */
+      logs: ({ lines } = {}) =>
+        this._request("GET", "/api/v1/admin/logs", {
+          queryParams: { lines },
+        }),
+      /**
+       * Private user-data entries across every account, each carrying its
+       * `userId`. `/users/:userId/data` has always been owner-or-admin; this
+       * is the same reach across accounts at once. Transparently follows
+       * pagination cursors and returns the full flat array. Admin only.
+       *
+       * Narrow with `prefix` (the literal head of a key) and/or `pattern`, a
+       * GLOB over the whole key (`*` any run, `?` one character) — the way to
+       * ask for a key convention identified by a segment in the middle, e.g.
+       * `igt:assistant:*:meta:*`. Values come only with `includeValues`, and
+       * are recased like any other body (see `userData.put`).
+       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use userDataPage() for a single page in a batch.
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @returns {Promise<Array<{userId: string, key: string, updatedAt: string, value?: *}>>}
+       */
+      userData: ({ prefix, pattern, includeValues } = {}) =>
+        listAll(this, "/api/v1/admin/user-data", {
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
+        }),
+      /**
+       * One page of private user-data entries across accounts, ordered by
+       * (user, key). Admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.prefix] - Only keys starting with this
+       * @param {string} [opts.pattern] - Only keys matching this GLOB
+       * @param {boolean} [opts.includeValues] - Also return each entry's value
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      userDataPage: ({ prefix, pattern, includeValues, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/admin/user-data", {
+          limit,
+          cursor,
+          query: {
+            prefix,
+            pattern,
+            "include-values": includeValues,
+          },
+        }),
+    };
+
+    this.audit = {
+      /**
+       * The audit log across every project, oldest first. Same fold, window
+       * and op-type filter as the per-project read, with the entity scope
+       * dropped. Admin only. Transparently follows pagination cursors and
+       * returns the full flat array.
+       * Cannot be used inside a batch (auto-paginates across requests); throws if called while batching — use listPage() for a single page in a batch.
+       * @param {object} [opts]
+       * @param {string} [opts.startTime] - Only operations at or after this instant
+       * @param {string} [opts.endTime] - Only operations at or before this instant
+       * @param {string[]|string} [opts.opTypes] - Only these op types (e.g.
+       *   `['span-layer/create']`). An entry appears when one of its operations
+       *   matches, carrying only the ones that did.
+       */
+      list: ({ startTime, endTime, opTypes } = {}) =>
+        listAll(this, "/api/v1/audit", {
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * Fetch a single page of the instance-wide audit log. Admin only.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first, which
+       *   is what a feed wants. A cursor belongs to the direction that made it.
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      listPage: ({ startTime, endTime, opTypes, order, limit, cursor } = {}) =>
+        listPage(this, "/api/v1/audit", {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
+      /**
+       * Async-iterate the instance-wide audit log page by page. Admin only.
+       * Cannot be used inside a batch (auto-paginates across requests); throws on first iteration if called while batching — use listPage() for a single page in a batch.
+       * @returns {AsyncGenerator<Array>}
+       */
+      iterPages: ({ startTime, endTime, opTypes, pageSize } = {}) =>
+        iterPages(this, "/api/v1/audit", {
+          pageSize,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "op-types": opTypesParam(opTypes),
+          },
+        }),
+      /**
+       * Per-user activity counts. `changes` is the number of logical actions,
+       * folded the way the audit feed folds them, so one "Confirm word
+       * analysis" counts once however many rows it wrote; `operations` is the
+       * unfolded row count. Only users who did something appear — subtract
+       * from the roster you already hold to find the ones who did not.
+       *
+       * With `projectId`, scoped to that project and open to its maintainers.
+       * Without one, instance-wide and admin only.
+       * @param {object} [opts]
+       * @param {string} [opts.projectId] - Scope to one project
+       * @param {string} [opts.startTime] - Only count at or after this instant
+       * @param {string} [opts.endTime] - Only count at or before this instant
+       * @param {boolean} [opts.daily] - Also return `byDay`, a list of
+       *   `{date, changes}` per user, oldest first, at the cost of a second
+       *   grouped scan
+       * @returns {Promise<Array<{user: object, operations: number, changes: number, documents: number, firstTs: string, lastTs: string, byDay?: object}>>}
+       */
+      tally: async ({ projectId, startTime, endTime, daily } = {}) => {
+        const path = projectId
+          ? `/api/v1/projects/${projectId}/audit/tally`
+          : "/api/v1/audit/tally";
+        const result = await this._request("GET", path, {
+          queryParams: {
+            "start-time": startTime,
+            "end-time": endTime,
+            daily,
+          },
+        });
+        return result.entries;
+      },
+    };
+
     this.tokenLayers = {
       /**
        * Shift a token layer's display order.
@@ -1345,6 +1634,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        documentId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/documents/${documentId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * Restore a document to its state at an earlier time, as one
        * operation: what was deleted since then comes back under its original
@@ -1361,7 +1675,10 @@ class PlaidClient {
        */
       restore: (documentId, asOf, { dryRun } = {}, auditMessage) =>
         this._request("POST", `/api/v1/documents/${documentId}/restore`, {
-          queryParams: { "as-of": asOf, "dry-run": dryRun ? "true" : undefined },
+          queryParams: {
+            "as-of": asOf,
+            "dry-run": dryRun ? "true" : undefined,
+          },
           auditMessage,
         }),
       /**
@@ -1416,6 +1733,25 @@ class PlaidClient {
           auditMessage,
           body: bodyOf({ "project-id": projectId, name, metadata }),
         }),
+      /**
+       * Copy a document and everything in it into a new document of the same
+       * project, as one operation. The copy shares the source's layers and
+       * the vocabulary entries its links name, and holds the source's texts,
+       * tokens, spans, relations and vocab links under fresh ids, with their
+       * metadata. Comments do not travel. The media file does, unless
+       * `includeMedia` is false. Resolves to `{ id }`, plus `mediaError` when
+       * the source had media the copy could not take with it.
+       * @param {string} documentId - The document to copy
+       * @param {string} name - The new document's name
+       * @param {object} [options] - `{ includeMedia }`: false leaves the media
+       *   file behind
+       * @param {string} [auditMessage] - Custom audit message for this operation
+       */
+      copy: (documentId, name, { includeMedia } = {}, auditMessage) =>
+        this._request("POST", `/api/v1/documents/${documentId}/copy`, {
+          auditMessage,
+          body: bodyOf({ name, "include-media": includeMedia }),
+        }),
     };
 
     this.projects = {
@@ -1522,6 +1858,31 @@ class PlaidClient {
             "op-types": opTypesParam(opTypes),
           },
         }),
+      /**
+       * One page of the same log, newest-first with `order: "desc"`. Use this
+       * rather than audit() wherever the caller wants the recent end of a log
+       * that may be long: audit() walks every page before it resolves.
+       * @param {object} [opts]
+       * @param {"asc"|"desc"} [opts.order] - "desc" pages newest-first
+       * @param {number} [opts.limit] - Page size (1..1000; server default 100)
+       * @param {string} [opts.cursor] - Opaque cursor from a previous page
+       * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
+       */
+      auditPage: (
+        projectId,
+        { startTime, endTime, asOf, opTypes, order, limit, cursor } = {},
+      ) =>
+        listPage(this, `/api/v1/projects/${projectId}/audit`, {
+          limit,
+          cursor,
+          query: {
+            "start-time": startTime,
+            "end-time": endTime,
+            "as-of": asOf,
+            "op-types": opTypesParam(opTypes),
+            order,
+          },
+        }),
       /**
        * When the calling user last wrote to each document in a project, as a
        * `{documentId: timestamp}` map. Documents they have never written to
@@ -2163,8 +2524,25 @@ class PlaidClient {
        * @param {Object} [opts] - {requestId, onAccepted}
        * @returns {Promise<any>} The service's result
        */
-      requestService: (projectId, serviceId, data, timeout, onProgress, signal, opts) =>
-        requestService(this, projectId, serviceId, data, timeout, onProgress, signal, opts),
+      requestService: (
+        projectId,
+        serviceId,
+        data,
+        timeout,
+        onProgress,
+        signal,
+        opts,
+      ) =>
+        requestService(
+          this,
+          projectId,
+          serviceId,
+          data,
+          timeout,
+          onProgress,
+          signal,
+          opts,
+        ),
 
       /**
        * Rejoin a service request made earlier and await its result: the
@@ -2180,8 +2558,21 @@ class PlaidClient {
        * @param {AbortSignal} [signal] - Abort to stop waiting
        * @returns {Promise<any>} The service's result
        */
-      attachServiceRequest: (projectId, requestId, timeout, onProgress, signal) =>
-        attachServiceRequest(this, projectId, requestId, timeout, onProgress, signal),
+      attachServiceRequest: (
+        projectId,
+        requestId,
+        timeout,
+        onProgress,
+        signal,
+      ) =>
+        attachServiceRequest(
+          this,
+          projectId,
+          requestId,
+          timeout,
+          onProgress,
+          signal,
+        ),
 
       /**
        * Ask the service to stop a request made earlier. The request still
@@ -2238,7 +2629,11 @@ class PlaidClient {
     // and the server ran the query against the batch's tx Connection, which
     // 500s and rolls back every write in that batch.
     this.query = (body, auditMessage) =>
-      this._request("POST", "/api/v1/query", { auditMessage, body, bypassBatch: true });
+      this._request("POST", "/api/v1/query", {
+        auditMessage,
+        body,
+        bypassBatch: true,
+      });
 
     // Logical-operation groups (audit-log grouping). There is no create: a
     // group row is made lazily by the first write carrying `?group-id=`
@@ -2333,7 +2728,10 @@ class PlaidClient {
        * @param {string} [opts.entityId] - With entityType, one entity's thread
        * @returns {Promise<{entries: Array, nextCursor: (string|null)}>}
        */
-      listPage: (projectId, { limit, cursor, documentId, entityType, entityId } = {}) =>
+      listPage: (
+        projectId,
+        { limit, cursor, documentId, entityType, entityId } = {},
+      ) =>
         listPage(this, `/api/v1/projects/${projectId}/comments`, {
           limit,
           cursor,
@@ -2354,7 +2752,10 @@ class PlaidClient {
        * @param {string} [opts.entityId] - With entityType, one entity's thread
        * @returns {AsyncGenerator<Array>}
        */
-      iterPages: (projectId, { pageSize, documentId, entityType, entityId } = {}) =>
+      iterPages: (
+        projectId,
+        { pageSize, documentId, entityType, entityId } = {},
+      ) =>
         iterPages(this, `/api/v1/projects/${projectId}/comments`, {
           pageSize,
           query: {
@@ -2421,10 +2822,14 @@ class PlaidClient {
        * @returns {Promise<Object<string, number>>}
        */
       countsInVocab: (vocabId, { entityId } = {}) =>
-        this._request("GET", `/api/v1/vocab-layers/${vocabId}/comments/counts`, {
-          queryParams: { "entity-id": entityId },
-          skipResponseTransform: true,
-        }),
+        this._request(
+          "GET",
+          `/api/v1/vocab-layers/${vocabId}/comments/counts`,
+          {
+            queryParams: { "entity-id": entityId },
+            skipResponseTransform: true,
+          },
+        ),
     };
   }
 
@@ -2580,7 +2985,9 @@ class PlaidClient {
       // must not fail on its size alone.
       const results = [];
       for (let i = 0; i < ops.length; i += MAX_BATCH_OPS) {
-        results.push(...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))));
+        results.push(
+          ...(await this._postBatch(url, ops.slice(i, i + MAX_BATCH_OPS))),
+        );
       }
       return results;
     } finally {
@@ -2703,6 +3110,27 @@ class PlaidClient {
    * @param {object} [options] - Client options forwarded to the constructor (e.g. { timeout })
    * @returns {Promise<PlaidClient>} - Authenticated client instance
    */
+  /**
+   * Liveness, version and database size, with NO authentication and no client
+   * instance — for a launcher or status page checking whether a server is up
+   * before anyone logs in.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
+   */
+  static async health(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/health", options);
+  }
+
+  /**
+   * The limits this server enforces, with NO authentication and no client
+   * instance. See the instance method for the shape.
+   * @param {string} baseUrl - The API base URL
+   * @param {object} [options]
+   */
+  static async info(baseUrl, options = {}) {
+    return anonymousGet(baseUrl, "/api/v1/info", options);
+  }
+
   /**
    * Build the link to hand someone for an invite code. The server never sees
    * an app URL, so the app that minted the invite is the one that names it.
@@ -2730,12 +3158,7 @@ class PlaidClient {
    * @returns {Promise<{kind: string, status: string, expiresAt: string, projectName?: string, projectRole?: string, email?: string, grantAdmin: boolean}>}
    */
   static async lookupInvite(baseUrl, code, options = {}) {
-    return anonymousPost(
-      baseUrl,
-      "/api/v1/invite-codes/lookup",
-      { code },
-      options,
-    );
+    return anonymousPost(baseUrl, "/api/v1/invites/lookup", { code }, options);
   }
 
   /**
@@ -2766,7 +3189,7 @@ class PlaidClient {
   ) {
     const data = await anonymousPost(
       baseUrl,
-      "/api/v1/invite-codes/redeem",
+      "/api/v1/invites/redeem",
       bodyOf({ code, email, password, "display-name": displayName }),
       options,
     );
@@ -2831,6 +3254,7 @@ export {
 export {
   PLAID_NAMESPACE,
   ROLE_KEY,
+  PRESERVE_ON_SPLIT_KEY,
   ROLES,
   readRole,
   findByRole,
@@ -2847,6 +3271,11 @@ export {
   buildDefaultValues,
   coerceParamValues,
 } from "./serviceSchema.js";
+// Cooperative cancellation for a service AUTHORED in JS: `progress()` is a
+// checkpoint that throws ServiceCancelled once the requester stops the
+// request, and `critical()` holds that off around writes. See ./services.js
+// and the manual, "Stopping a request".
+export { ServiceCancelled, createCancelScope } from "./services.js";
 // Provenance: the cross-app convention for who made an annotation (flat
 // prov/provSource/provConfirmed metadata; absence = a verifier; 'inferred' =
 // a machine; 'contributed' = a person whose work is reviewed), plus the
@@ -2855,6 +3284,7 @@ export {
   PROV,
   PROV_STATES,
   PROV_CONFIRMED,
+  PROVENANCE_KEYS,
   stampInferred,
   confirmedInferred,
   stampContributed,

package/src/provenance.js

@@ -99,6 +99,25 @@ export const PROV = Object.freeze({
   CONTRIBUTED: 'contributed',
 });
 
+/**
+ * Every provenance key, for a caller that has to name them as a set rather
+ * than read one: what a token layer declares under
+ * `config.plaid.preserveOnSplit` so a token born of a split inherits the
+ * origin of the token it came from, and what a reshape carries by hand.
+ *
+ * Provenance is the one metadata family Plaid itself owns. The user cannot
+ * maintain it, and in a shared project usually cannot even see it, since it
+ * may belong to an app they are not using. Everything else on an entity is
+ * the user's own content and no structural operation should touch it.
+ */
+export const PROVENANCE_KEYS = Object.freeze([
+  PROV.key,
+  PROV.sourceKey,
+  PROV.confirmedKey,
+  PROV.probKey,
+  PROV.detailKey,
+]);
+
 /** The four provenance states returned by provState. */
 export const PROV_STATES = Object.freeze({
   HUMAN: 'human',

package/src/roles.js

@@ -25,6 +25,15 @@ export const PLAID_NAMESPACE = 'plaid';
 export const ROLE_KEY = 'role';
 
 /** The fixed role inventory. */
+/**
+ * Layer config key naming the metadata keys a token born of a SPLIT inherits
+ * from the token it came from. Plaid honors it without knowing what the keys
+ * mean; see the manual's `Metadata Preserved Across a Split`. An app declares
+ * it so that a split in ANY app, including one that has never heard of these
+ * keys, does not silently drop them.
+ */
+export const PRESERVE_ON_SPLIT_KEY = 'preserveOnSplit';
+
 export const ROLES = Object.freeze({
   BASELINE: 'baseline',
   SENTENCE: 'sentence',

package/src/serviceSchema.js

@@ -21,7 +21,7 @@
  *     parameters: [                     // ordered; rendered into a form
  *       { key, label, type, description?, default?, required?,
  *         options?: [{value, label}],   // enum / multiselect
- *         min?, max?, step?,            // number
+ *         min?, max?, step?, slider?,   // number (slider: drag, don't type)
  *         placeholder?, multiline? }    // string
  *     ]
  *   }
@@ -52,7 +52,17 @@ export const TASKS = Object.freeze({
   ANALYZE: "analyze",
   /** Propose a free translation for each sentence. */
   TRANSLATE: "translate",
-  /** A conversational assistant over a project (chat turns; see plaid-igt-agent). */
+  /**
+   * Propose time-aligned speech regions for a recording.
+   *
+   * The odd one out: a detect-speech service RETURNS its regions and writes
+   * nothing, because a time-aligned segment is a stretch of the baseline and
+   * cannot exist without text. The response carries
+   * `{segments: [{timeBegin, timeEnd, speaker?}]}` (seconds), and the app
+   * holds them as proposals until a person types into one.
+   */
+  DETECT_SPEECH: "detect-speech",
+  /** A conversational assistant over a project (chat turns; see plaid-agent). */
   ASSIST: "assist",
 });
 

package/src/services.js

@@ -147,31 +147,63 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
         ? { ...payload.data, requesterId }
         : payload.data;
 
+    const scope = createCancelScope(() => cancelled.get(requestId) === true);
     const responseHelper = {
       requestId,
       requesterId,
       // True once the requester asked for the request to stop.
       get cancelled() {
-        return cancelled.get(requestId) === true;
+        return scope.cancelled;
       },
+      raiseIfCancelled: () => scope.raiseIfCancelled(),
+      critical: (fn) => scope.critical(fn),
       // Extra fields ride in the progress payload (a chat service sends the
       // reply text so far as `text`).
-      progress: (percent, msg, extra) =>
-        reportEvent(requestId, { status: 'progress', progress: { percent, message: msg, ...extra } }),
+      //
+      // This is a CANCELLATION CHECKPOINT: it throws ServiceCancelled if the
+      // requester has stopped the request, so a service that reports progress
+      // through its work is cancellable without doing anything else. Use
+      // `critical()` around writes to hold it off.
+      progress: (percent, msg, extra) => {
+        scope.raiseIfCancelled();
+        return reportEvent(requestId, {
+          status: 'progress',
+          progress: { percent, message: msg, ...extra },
+        });
+      },
       complete: (data) => {
         finished();
         return reportEvent(requestId, { status: 'completed', data });
       },
+      // Asked to stop, and it did. Reported as a result carrying
+      // `stopped: true`, so a client can tell "you stopped it" from "it broke".
+      stopped: (data) => {
+        finished();
+        return reportEvent(requestId, {
+          status: 'completed',
+          data: { ...(data || {}), stopped: true },
+        });
+      },
       error: (error) => {
         finished();
         return reportEvent(requestId, { status: 'error', data: { error: error?.message || error } });
       },
     };
 
+    // A handler may be async, so a rejected promise has to be caught too, or a
+    // cancelled async service would report a failure instead of a stop.
+    const settle = (error) => {
+      if (error instanceof ServiceCancelled || error?.name === 'ServiceCancelled') {
+        responseHelper.stopped();
+      } else {
+        responseHelper.error(error?.message || error);
+      }
+    };
     try {
-      onServiceRequest(data, responseHelper);
+      const maybe = onServiceRequest(data, responseHelper);
+      if (maybe && typeof maybe.catch === 'function') maybe.catch(settle);
     } catch (error) {
-      responseHelper.error(error?.message || error);
+      settle(error);
     }
   };
   const openChannel = () => client.messages.listen(projectId, onChannelEvent, channelPath);
@@ -204,7 +236,7 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  *
  * Streams the service's progress + result back over a single server-mediated
  * response (no broadcast). Rejects if no service is connected (503), if the
- * service reports an error, or on timeout.
+ * service reports an error, or after `timeout` of SILENCE.
  *
  * The request outlives this call: after a timeout, an abort, or a dropped
  * connection the service goes on, and `attachServiceRequest` collects the
@@ -213,11 +245,15 @@ export function serve(client, projectId, serviceInfo, onServiceRequest, extras =
  * to know the id before submitting; submitting an id that names a request
  * you already made rejoins it instead of starting another.
  *
+ * Errors that leave the request alive carry `pending: true`: a timeout, a
+ * stop, a dropped connection. An error without it is the end of the request.
+ *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
  * @param {string} serviceId - Service ID to request
  * @param {any} data - Request payload
- * @param {number} [timeout=10000] - Timeout in ms
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms.
+ *   Every event it sends starts the clock again, so this does not cap a long run
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @param {Object} [opts]
@@ -259,12 +295,14 @@ export function requestService(client, projectId, serviceId, data, timeout = 100
  * the latest progress is replayed, then the result comes, or at once if the
  * request already finished. Rejects with an error whose `status` is 404 when
  * the request is unknown or expired (the server keeps a finished request's
- * result for a while, not forever).
+ * result for a while, not forever). As with `requestService`, `timeout` is
+ * how long the service may be silent, and an error carrying `pending: true`
+ * means the request is still there to rejoin again.
  *
  * @param {Object} client - PlaidClient instance
  * @param {string} projectId - Project UUID
  * @param {string} requestId - The request id (from `onAccepted` or your own)
- * @param {number} [timeout=10000] - Timeout in ms
+ * @param {number} [timeout=10000] - How long the service may say NOTHING, in ms
  * @param {function} [onProgress] - Called with each progress payload {percent, message}
  * @param {AbortSignal} [signal] - Abort to stop waiting; rejects with an AbortError
  * @returns {Promise<any>} The service's result
@@ -293,10 +331,68 @@ export function attachServiceRequest(client, projectId, requestId, timeout = 100
  * @param {string} requestId - The request id
  * @returns {Promise<void>}
  */
+/**
+ * Thrown inside a handler when the requester has asked it to stop.
+ *
+ * Cooperative cancellation: nothing interrupts a handler, so the request ends
+ * at the next point the handler looks. `responseHelper.progress` is that
+ * point, which is why a long service that already reports progress needs no
+ * changes at all. `serve` catches this and ends the request as STOPPED rather
+ * than failed.
+ */
+export class ServiceCancelled extends Error {
+  constructor(message = 'The requester stopped this request') {
+    super(message);
+    this.name = 'ServiceCancelled';
+  }
+}
+
+/**
+ * The cancellation half of a responseHelper: a flag, a depth counter, and one
+ * rule about when a checkpoint may raise. Split from the transport so it can
+ * be reasoned about on its own. Mirrors `CancelScope` in the Python client.
+ */
+export function createCancelScope(isCancelled) {
+  // Depth of nested `critical()` blocks; while non-zero, a checkpoint will
+  // not throw.
+  let criticalDepth = 0;
+  return {
+    get cancelled() {
+      return !!isCancelled();
+    },
+    /** Stop here if the requester has asked the request to stop. */
+    raiseIfCancelled() {
+      if (isCancelled() && criticalDepth === 0) throw new ServiceCancelled();
+    },
+    /**
+     * Run `fn` as a stretch that must finish once begun, usually the writes.
+     * Checkpoints inside do not throw, so a half-written document is never
+     * left behind; cancellation takes effect at the first checkpoint after.
+     */
+    async critical(fn) {
+      criticalDepth++;
+      try {
+        return await fn();
+      } finally {
+        criticalDepth--;
+      }
+    },
+  };
+}
+
 export function cancelServiceRequest(client, projectId, requestId) {
   return client._request('DELETE', `/api/v1/projects/${projectId}/service-requests/${encodeURIComponent(requestId)}`);
 }
 
+/**
+ * Mark an error as one that leaves the request ALIVE on the server: a timeout,
+ * a stop, a dropped connection. The service goes on working and its result
+ * still waits under the request id, so a caller holding that id can rejoin it
+ * with `attachServiceRequest`, and must not forget the id the way it forgets
+ * a request that really ended. An error without `pending` is terminal.
+ */
+const stillRunning = (err) => Object.assign(err, { pending: true });
+
 /**
  * Open a request stream (submit or attach) and read it to its terminal
  * event: `accepted` names the request, `progress` events go to `onProgress`,
@@ -313,10 +409,23 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
       abortController.abort();
       fn(arg);
     };
-    const timer = setTimeout(
-      () => finish(reject, new Error(`${what} timed out after ${timeout}ms`)),
-      timeout,
-    );
+
+    // `timeout` is IDLE time, meaning how long the service may say nothing. It
+    // is not a deadline on the run: every event from the server restarts it,
+    // because a service that is reporting its progress is not hung. As a
+    // deadline on the whole run it killed working transcriptions at the
+    // five-minute default and left their writes to land on a document the page
+    // had already handed back to the user as editable.
+    let timer;
+    const waitAgain = () => {
+      clearTimeout(timer);
+      timer = setTimeout(
+        () =>
+          finish(reject, stillRunning(new Error(`${what} timed out after ${timeout}ms of silence`))),
+        timeout,
+      );
+    };
+    waitAgain();
 
     // An external signal stops waiting on a long request (a UI's Stop button).
     // Reject with an AbortError so a caller can tell a deliberate stop from a
@@ -325,7 +434,7 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
     const stop = () => {
       const err = new Error('The service request was stopped');
       err.name = 'AbortError';
-      finish(reject, err);
+      finish(reject, stillRunning(err));
     };
     if (signal) {
       if (signal.aborted) {
@@ -349,7 +458,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
           signal: abortController.signal,
         });
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, new Error(`${what} could not be sent: ${error.message}`));
+        // The POST may or may not have reached the server. Treat it as alive:
+        // rejoining a request that was never made simply 404s.
+        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} could not be sent: ${error.message}`)));
         return;
       }
 
@@ -386,6 +497,7 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
               dataLine = line.slice(6);
             } else if (line === '' && eventType && dataLine) {
               const payload = transformResponse(JSON.parse(dataLine));
+              waitAgain(); // it spoke, so it is not hung
               if (eventType === 'accepted') {
                 if (onAccepted) { try { onAccepted(payload.requestId); } catch (_) { /* ignore */ } }
               } else if (eventType === 'progress') {
@@ -402,9 +514,9 @@ function streamServiceRequest(client, { url, method, body, onStatus, what }, tim
             }
           }
         }
-        finish(reject, new Error('Service closed the connection without a result'));
+        finish(reject, stillRunning(new Error('Service closed the connection without a result')));
       } catch (error) {
-        if (error.name !== 'AbortError') finish(reject, new Error(`${what} stream error: ${error.message}`));
+        if (error.name !== 'AbortError') finish(reject, stillRunning(new Error(`${what} stream error: ${error.message}`)));
       }
     })();
   });