@rackbops/ac-plugin-contract 2.0.0-alpha.59 → 2.0.0-alpha.62

package/AUTHORING.md

@@ -198,7 +198,12 @@ is never left open). Register last whatever must not exist when a later step fai
 
 - **Route** — `host.routes.register(method, path, handler)`. The handler is a web-standard
   `(request: Request) => Response | Promise<Response>`, mounted at `/api/x/<id><path>`. You may only register a
-  `(method, path)` you declared in `contributes.routes` — an undeclared route throws. **Never answer `502` or
+  `(method, path)` you declared in `contributes.routes` — an undeclared route throws.
+  `operator: true` on the route (#867): With the admin kill switch off (`admin_enabled = false`), the host
+  refuses this route for its declared method with `403 admin disabled`, as it refuses the admin plugin's own
+  surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run
+  route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration.
+  Additive; a host released before this field refuses a manifest that declares it. **Never answer `502` or
   `504` yourself** (#474): the production console is reached through Cloudflare, and Cloudflare's own
   documentation says it "returns a Cloudflare-branded HTTP 502 or 504 error when your origin web server responds
   with a standard HTTP 502 bad gateway or 504 gateway timeout error" — so on the production console (default
@@ -237,6 +242,11 @@ is never left open). Register last whatever must not exist when a later step fai
   same action again while that locked modal is up reuses it and does not re-run it. After a failed result the
   primary is enabled again and a retry runs, so a double-click whose first run fails fast can run the action
   twice (the second a retry): an action whose failure may have partly applied should tolerate that.
+  `operator: true` (#867): With the admin kill switch off (`admin_enabled = false`), the host refuses this
+  action (`POST /api/actions/<plugin>/<id>`) with `403 admin disabled`, as it refuses the admin plugin's own
+  surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run
+  route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration.
+  Additive; a host released before this field refuses a manifest that declares it.
   `confirm` stays a valid manifest flag, so an existing manifest keeps loading, but neither the modal nor the
   palette acts on it.
 - **Job** — implement `runJob(ctx)` and dispatch on `ctx.jobId`. The host runs only jobs you declared in
@@ -1053,6 +1063,14 @@ the machine asleep or off the network, a reboot, a lost NAT mapping) settles `fa
 after the last byte on the console's Linux host; a machine asleep for longer than that mid-job reads
 `failed` even if the job finishes after it wakes.
 
+A host restart mid-job is the one end the relay cannot report from inside the new process (#911): the
+host records each relay it opens and forgets it when the relay sees its end, and
+`host.agent.unfinishedStreams?()` (optional, like `finished`) returns, once, the calling plugin's relays
+that an earlier host process opened and never saw end, each `{ taskId, jobId, machineId, machineName,
+label, openedAt }` (the `taskId` is the earlier process's and no longer exists). Call it once in
+`activate()` and report each run as ended with an unknown outcome; `plugins/claude-runner` emits
+`claude.run` `status: "unknown"` for each. `ac jobs run` keeps no record and returns none.
+
 ```ts
 const { jobId } = await execResult // however the plugin's own verb call started the job
 const { taskId, finished } = await host.agent.streamJob(machineId, jobId, { label: `code: ${prompt}` })
@@ -1089,7 +1107,7 @@ interface AttentionItem {
   href?: string                // an external link; wins over `target` when both are set. Linked only
                                // when its scheme is http:, https:, mailto: or tel: (#722); any other
                                // href is not linked and `target` is used instead
-  target?: string               // an in-app destination: "widget:<cardId>" or "panel:<pluginId>"
+  target?: string               // an in-app destination: "widget:<cardId>" (a home card: scrolls to and flashes it; text when the card is not on the page) or "panel:<pluginId>"
   hint?: string                  // the exact command to run, or the reason -- shown as a tooltip/expander
   action?: { kind: "issue"; repo?: string; title: string; body: string }  // opens provider-github's issue.create, seeded
 }
@@ -1225,9 +1243,9 @@ what it's for.
 |---|---|---|
 | Panel | `panels[]` (`id`, `title`, `route`, `export`, `nav?`, `order?`, `isolation?`) | a component export in `ui.js` |
 | Card | `cards[]` (`id`, `title`, `sizes`, `export`) | a component export in `ui.js` |
-| Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `fields?`) | `host.actions.register({ id, run })` |
+| Action | `actions[]` (`id`, `scope`, `title?`, `confirm?`, `danger?`, `operator?`, `fields?`) | `host.actions.register({ id, run })` |
 | Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`, `minAgentVersion?`, `capabilities?`) | `runJob(ctx)` dispatching on `ctx.jobId` |
-| Route | `routes[]` (`method`, `path`) | `host.routes.register(method, path, handler)` |
+| Route | `routes[]` (`method`, `path`, `operator?`) | `host.routes.register(method, path, handler)` |
 | Setting | `settings[]` (`key`, `type`, `default?`) | read via `host.settings.get/set` |
 | Attention | `attention: true` | `host.routes.register("GET", "/attention", handler)` -> `{ ok: true, items }` |
 
@@ -1293,6 +1311,9 @@ bound for a slot, or `null` when none is. It throws unless the plugin's own mani
 `{slot, version}` in `contributes.consumes`, and an installed plugin may not resolve `auth` at all. Call
 it at request time (inside a route handler or job), never in `activate()`: providers bind during
 activation in load order, so a consumer that activates first would read `null` there for good.
+`host.slots.providerId?.(slot, version)` (#866, optional: a host older than #866 has none) answers the id of the
+plugin bound to a slot, or `null`, without the provider itself and without a `consumes` entry; an installed
+plugin may not read `auth`'s.
 `ac-artifacts-weft` (`artifacts@1`) is the reference consumer: the second plugin to declare `consumes`
 for it, after `artifacts`, which reads `provider-artifacts`' HTTP routes from the browser, and the first to
 call `resolve`. `hello` contributes none of the six points above via a slot (nor `attention` -- its own manifest

package/dist/attention.d.ts

@@ -39,8 +39,9 @@ export interface AttentionItem {
      *  custom scheme, one that does not parse) renders no link, and the row uses `target` instead, as
      *  if `href` were absent. */
     href?: string;
-    /** An in-app destination: `widget:<cardId>` flashes/scrolls to a sibling card on Overview,
-     *  `panel:<pluginId>` navigates to that plugin's panel (its first panel route, or `/<pluginId>`
+    /** An in-app destination: `widget:<cardId>` scrolls to the home card whose `data-card-id` is
+     *  `<cardId>` or ends `:<cardId>`, and flashes it (when no such card is on the page the row is
+     *  plain text), `panel:<pluginId>` navigates to that plugin's panel (its first panel route, or `/<pluginId>`
      *  when the console knows none). A value that is not a string is ignored. */
     target?: string;
     /** The exact command to run, or the reason, shown as a tooltip/expander (1.x's `hint`). */

package/dist/host-api.d.ts

@@ -81,7 +81,9 @@ export interface JobDeclaration {
 export interface EventsService {
     /** Calls every subscriber of `type` synchronously, in subscription order, and never awaits one.
      *  A subscriber that throws, or returns a promise that rejects, is logged by the host and stops
-     *  neither the others nor the emitter (#728). */
+     *  neither the others nor the emitter (#728). An event a plugin emits while plugins are still
+     *  activating also reaches, once every plugin has activated, a subscriber that registered after
+     *  it, so a handler registered in `activate()` does not depend on load order (#1061). */
     emit(type: string, payload: unknown): void;
     /** Subscribe; returns an unsubscribe function. The handler may be `async` (#728): when it
      *  returns a promise (or any thenable) the host attaches a rejection handler, so a rejection is
@@ -98,7 +100,10 @@ export interface GithubService {
     /** The one shared Octokit REST client — consumers make all GitHub calls through this. It
      *  authenticates with the console's PAT (`AC_GITHUB_TOKEN`), and `octokit().auth()` returns that
      *  token to whichever plugin asks: no `env[]` declaration is needed, and nothing hides it (#784;
-     *  in-process plugins are trusted code, not sandboxed). */
+     *  in-process plugins are trusted code, not sandboxed). Since #753 the client caps requests at 10 in
+     *  flight, retries a GET's 5xx (GraphQL and writes are POSTs and are not) and a short secondary limit once, gives each attempt 20 s, and rejects a
+     *  request at once with `GitHub rate limit exhausted until <ISO>` while a 403/429 has reported that
+     *  request's budget spent. */
     octokit(): Octokit;
     /** Remaining primary-rate-limit budget from the last response whose three `x-ratelimit-*` headers
      *  are all finite numbers (and the reset a valid time), a failed response's included (#784: a 403 or
@@ -180,6 +185,22 @@ export interface AgentService {
             reason: string;
         }>;
     }>;
+    /**
+     * The relays this plugin opened with `streamJob` in an earlier host process whose end that process
+     * never saw (#911): a host restart mid-job. Each is returned once, then forgotten. A process that
+     * keeps no relay record (`ac jobs run`) and a host older than #911 return none or lack the method.
+     * `taskId` is the earlier process's task id, which no longer exists.
+     */
+    unfinishedStreams?(): Promise<UnfinishedStream[]>;
+}
+/** A `streamJob` relay whose end an earlier host process never saw (#911). */
+export interface UnfinishedStream {
+    taskId: string;
+    jobId: string;
+    machineId: string;
+    machineName: string;
+    label: string;
+    openedAt: string;
 }
 /** Proxy to a sidecar plugin's HTTP surface (the host handles health + base URL). */
 export interface SidecarService {
@@ -229,7 +250,8 @@ export type ActionInputErrorName = "ActionInputError";
  * know their callers' payload shapes either. Two providers for the same `slot@version` is a boot
  * error (auth/notify are singletons) -- surfaced by the host-side registry `provide` throws from, not
  * this interface, since this is the plugin's OWN scoped view (pre-bound to its id, so the error can
- * name the real offending plugin without a pluginId parameter here). */
+ * name the real offending plugin without a pluginId parameter here). `providerId` (#866) reads which
+ * plugin holds a binding without exposing it (the admin Security card reads `auth@1`'s). */
 export interface SlotRegistry {
     /** Register this plugin's provider instance for `slot@version`. Throws if that slot already has a
      *  provider (from this plugin or another) -- auth/notify are singletons, never a last-write-wins. */
@@ -244,6 +266,13 @@ export interface SlotRegistry {
      *  during activation in load order, so a consumer that activates before its provider would read `null`
      *  there for good (#97). */
     resolve<T = unknown>(slot: string, version: number): T | null;
+    /** The id of the plugin bound to `slot@version`, or `null` when nothing is bound (#866). Never the
+     *  provider itself, so it opens no way to the impl. Unlike `resolve` it needs no `contributes.consumes`
+     *  entry. An installed plugin may not read the `auth` slot's (it throws, naming the plugin), as it may
+     *  not resolve it. Optional: a host older than #866 has no such method, so check for it before calling
+     *  (`host.slots.providerId?.(slot, version)`). Call it at request time, never in `activate()`, for the
+     *  same load-order reason as `resolve`. */
+    providerId?(slot: string, version: number): string | null;
 }
 /** A logger prefixed with the plugin id. A plain-object first arg is the line's structured fields; an
  *  `Error` first arg is logged as its own enumerable properties (`code`, `status`, ...) plus
@@ -294,6 +323,11 @@ export interface HostApi {
     /** #506: see `ConsoleSettingsService`. Optional so an out-of-repo plugin's own test fake still
      *  compiles. */
     consoleSettings?: ConsoleSettingsService;
+    /** #875: `true` only in the process that serves HTTP and owns the plugins' on-disk state (`main.ts`);
+     *  absent in a one-shot CLI process (`ac jobs run`), which loads every plugin too. Work that must run
+     *  once per server boot, and must never run beside a live server (clearing a stale lock file under a
+     *  git clone, say), is gated on it. Optional so an out-of-repo plugin's own test fake still compiles. */
+    serving?: boolean;
 }
 /**
  * The context the host passes to `Plugin.runJob` for one job run (#31). `jobId` selects which

package/dist/manifest.d.ts

@@ -103,6 +103,14 @@ export interface ActionContribution {
      *  asks for a second click. */
     confirm?: boolean;
     danger?: boolean;
+    /**
+     * With the admin kill switch off (`admin_enabled = false`), the host refuses this action (`POST /api/actions/<plugin>/<id>`) with
+     * `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator
+     * would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the
+     * store on the operator's behalf, or changes the console's configuration. Additive; a host released before
+     * this field refuses a manifest that declares it (#867).
+     */
+    operator?: true;
     /** The form the shell builds the action's modal from; omit for a no-input action. */
     fields?: ActionField[];
 }
@@ -149,6 +157,14 @@ export interface RouteContribution {
     method: HttpMethod;
     /** Path under the plugin's namespace, e.g. "/feed". */
     path: string;
+    /**
+     * With the admin kill switch off (`admin_enabled = false`), the host refuses this route for its declared method with
+     * `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator
+     * would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the
+     * store on the operator's behalf, or changes the console's configuration. Additive; a host released before
+     * this field refuses a manifest that declares it (#867).
+     */
+    operator?: true;
 }
 /** JSON scalar type of a plugin setting (rendered by Admin). */
 export type SettingType = "string" | "integer" | "number" | "boolean";

package/dist/views.d.ts

@@ -82,6 +82,10 @@ export type PluginOrigin = "bundled" | "installed";
 export interface PluginView {
     id: string;
     enabled: boolean;
+    /** The enable state the next restart applies, when it differs from `enabled` (#767): an operator's persisted
+     *  choice (`POST /api/plugins/:id/enabled`) not yet applied, with `AC_PLUGINS_FORCE_ENABLED` winning as it does
+     *  at boot. Absent when the two agree. Additive. */
+    pendingEnabled?: boolean;
     /** Required even on an errored entry — it is a property of where the plugin came from, not of loading. */
     origin: PluginOrigin;
     error?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.59",
+  "version": "2.0.0-alpha.62",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",

package/schema.json

@@ -235,6 +235,11 @@
         "danger": {
           "type": "boolean"
         },
+        "operator": {
+          "type": "boolean",
+          "const": true,
+          "description": "With the admin kill switch off (`admin_enabled = false`), the host refuses this action (`POST /api/actions/<plugin>/<id>`) with `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration. Additive; a host released before this field refuses a manifest that declares it (#867)."
+        },
         "fields": {
           "type": "array",
           "items": {
@@ -394,6 +399,11 @@
         "path": {
           "type": "string",
           "description": "Path under the plugin's namespace, e.g. \"/feed\"."
+        },
+        "operator": {
+          "type": "boolean",
+          "const": true,
+          "description": "With the admin kill switch off (`admin_enabled = false`), the host refuses this route for its declared method with `403 admin disabled`, as it refuses the admin plugin's own surface. Mark an action or route an operator would expect the switch to shut: one that runs a job the job-run route refuses, writes to GitHub or the store on the operator's behalf, or changes the console's configuration. Additive; a host released before this field refuses a manifest that declares it (#867)."
         }
       },
       "required": [