@rackbops/ac-plugin-contract 2.0.0-alpha.56 → 2.0.0-alpha.58

package/AUTHORING.md

@@ -121,7 +121,8 @@ Rules the host enforces, at validation or load time:
   declares. Every other slot, `notify@1` included, is open to an installed plugin.
 - **`hostApiVersion`** must equal the host's `HOST_API_VERSION` (currently `1`); a mismatch is rejected.
 - **`kind: "in-process"`** must declare a `server` entry — the *loader* records an error and skips a plugin that
-  doesn't (the schema itself requires only `id`, `hostApiVersion` and `kind`). `contributes` and every sub-field
+  doesn't, and the install gate (`ac plugins install`, the Admin Plugins card) refuses to stage one (the schema
+  itself requires only `id`, `hostApiVersion` and `kind`). `contributes` and every sub-field
   is optional in the schema — contribute only the points you use; each contribution's own required fields are
   schema-enforced.
 - **Jobs** (#137, #580): a job's **`timeoutSec`** must be at least `1` and at most `2147483` (the schema's
@@ -170,6 +171,13 @@ export const createPlugin: CreatePlugin = (host) => ({
 })
 ```
 
+When loading fails, the plugin is errored and unwound (#785). A `createPlugin` that throws, or that returns
+anything but an object with an `activate()` method, and an `activate()` that throws or has not settled within
+30 seconds (as does an import whose top-level `await` has not), record the plugin's error in `GET /api/plugins`.
+Everything the plugin had already registered is then undone: its routes answer 404, its actions and event
+subscriptions are dropped, and a slot it provided is released (except `auth@1`, which stays bound so the host
+is never left open). Register last whatever must not exist when a later step fails.
+
 - **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
@@ -185,6 +193,15 @@ export const createPlugin: CreatePlugin = (host) => ({
   can act on any status from 400 up — so the check on the deployed console is what proves it. Otherwise a 4xx or
   `500`. `packages/host/src/no-gateway-status.test.ts` scans every bundled plugin's `src/` and the host's, and
   fails naming the file and line (an installed third-party plugin is not covered).
+  The host sends your `Response` as you built it, with one exception (#831): an HTML document (a `Content-Type`
+  of `text/html` or `application/xhtml+xml`) that states no framing policy of its own gets the console pages'
+  default, `X-Frame-Options: SAMEORIGIN` and a `Content-Security-Policy: frame-ancestors 'self'` policy, so no
+  other site can frame it. If you already send a `Content-Security-Policy` without a `frame-ancestors` directive,
+  yours is kept exactly as it is and the framing policy is added beside it as a second policy (the browser
+  enforces each). A route that wants a different framing policy states it, with a `frame-ancestors` directive in
+  its `Content-Security-Policy` or with its own `X-Frame-Options`, and the host then leaves the response exactly
+  as it is, as it does `provider-artifacts`' `GET /render/*` and its stricter policy (#700). Any other content
+  type is never touched.
 - **Action** — `host.actions.register({ id, run })`. The button, `confirm`/`danger` and the modal `fields` all
   come from the manifest; here you supply only `run(input)`. (The action's manifest metadata drives the shell
   UI; registering a `run` for an id the manifest omits simply leaves it without a button.) Opening the modal is
@@ -224,6 +241,17 @@ export const createPlugin: CreatePlugin = (host) => ({
   success, keeping a separate `.../error` key for a failure and throwing the agent's reason verbatim
   so the run is honestly recorded failed -- store, log, throw, in that order, never masking the
   agent's text with a storage error of your own.
+  An agent job that calls a verb declares the capabilities those verbs need in the job's own
+  `capabilities` (#843; each must also be in the plugin's top-level `capabilities` and match the
+  capability grammar `^agent(\.[a-z][a-z0-9-]*)+$`, or the manifest is refused). The host then never dispatches the job to a paired machine that has not granted the plugin
+  every one of them: that machine is still probed, but it is skipped, with no run recorded, no task, no
+  `job.finished` event and no failure notified. Its row on the Admin Scheduled tasks card reads
+  `skipped: not granted: <capability>`; the Overview sched card leaves it out of the job's badge.
+  Absent or empty means every paired machine, as before the field existed, which is right for a job
+  that calls no verb (`hello.machines`). A host released before #843 refuses a manifest that declares
+  the field, with `manifest schema: /contributes/jobs/<n> must NOT have additional properties`, and that
+  refuses the whole plugin, not just the job: declare it only when your plugin requires a host that
+  carries it. See §7.
 - **Setting** — read/write with `host.settings.get(key)` / `host.settings.set(key, value)`. Both are async;
   `get` returns the manifest `default` when unset.
 - **Console settings** (#506) — `host.consoleSettings?.get(key)`, read-only, optional. Unlike `Setting`
@@ -853,11 +881,51 @@ others are the console's problem to describe differently: `unknown-machine` (a s
 reachable this way, whatever the path spelling), `pin` (the agent's certificate changed since
 pairing), `network`, `http` (an unexpected status the console doesn't special-case).
 
+An agent job declares the capabilities its own verbs need, in the job's `capabilities` (#843). Each one
+must also be in the top-level list and match the capability grammar (`agent.` and lowercase segments).
+The host checks them against the machine's grants before it dispatches the job, so a machine that has not
+granted them is skipped rather than refused: no failed run, no `job failed` notification, and the Admin
+Scheduled tasks card reads `skipped: not granted: <capability>` for that machine (the Overview sched card
+leaves the machine out of the job's badge). `plugins/scans` is the example: each of its four jobs calls
+one verb, `POST /v1/scan/<kind>`, and declares exactly the capability that verb needs. A host released
+before #843 refuses a manifest that declares the field, with
+`manifest schema: /contributes/jobs/<n> must NOT have additional properties`, which refuses the whole
+plugin.
+
+```json
+"capabilities": ["agent.scan.context-pressure", "agent.scan.subagent-cost"],
+"contributes": {
+  "jobs": [
+    {
+      "id": "scan.context-pressure",
+      "schedule": "40 3 * * *",
+      "timeoutSec": 990,
+      "runOn": "agent",
+      "capabilities": ["agent.scan.context-pressure"]
+    }
+  ]
+}
+```
+
+List every capability any of the job's verbs needs (a job that reads with `agent.git.read` and pulls with
+`agent.git.pull` lists both). A job that lists too few is dispatched to a machine that then refuses the
+verb, which is the failure this field exists to prevent. A `grant` refusal can still reach your `runJob`
+when a grant is revoked while the run is in flight, so keep handling it.
+
 A verb that can genuinely run long (a scan, a build) needs a fifth, optional `call` argument:
 `host.agent.call(machineId, method, path, body, { timeoutMs })` sets how long the console waits for
 the agent's response *headers* (undici's `headersTimeout`; the default is 300s). Pass the verb's own
 limit plus a margin -- `scans` passes `agent limit + 30s` -- so the agent's own `504` reaches the
-console before the console gives up and reports a bare `network` timeout instead.
+console before the console gives up and reports a bare `network` timeout instead. From a job, also
+pass the run's signal, `{ signal: ctx.signal }` (#701): when the run is timed out the request is
+cancelled, and `call` resolves `{ ok: false, error: { kind: "network", reason } }` instead of waiting
+on the agent. The same goes for GitHub calls through `host.github.octokit()`: pass
+`request: { signal: ctx.signal }` to each call, but not to `octokit.paginate`, which hands its pages
+no `request` options; bind the signal to the route instead,
+`octokit.paginate(route.defaults({ request: { signal: ctx.signal } }), params)` (#701). Unlike
+`agent.call`, which resolves `{ ok: false }`, an aborted Octokit call rejects (the `AbortError`, with
+`status: 500` set on it), and an abort that lands while the body is read resolves with an empty
+`data`, so check `ctx.signal.aborted` after the call too.
 
 ### Streaming a job into the tasks drawer
 
@@ -868,20 +936,41 @@ job's stream is `GET /v1/toolchain/upgrade/:jobId/events`, under its own capabil
 reaches through its optional `path`: `{ label, path: "/v1/toolchain/upgrade/<jobId>/events" }`, a route
 of the shape `/v1/<segments>/<jobId>/events` naming that same `jobId`, anything else rejecting) through the same
 pinned client, registers a new host task for
-`label`, and relays every `line`/`done` frame into it as the job runs; it resolves `{ taskId }` once
-the agent has confirmed the stream is open (a `200`), or rejects (starting no task) on anything
-else -- an invalid `jobId`, an unknown machine, or a non-`200` from the agent (a `404`, a `403`
-refusal, ...), each surfaced the same way `call` surfaces them. The relay itself runs detached from
-that promise, so nothing in a plugin's own code touches the stream at all:
+`label`, and relays every `line`/`done` frame into it as the job runs; it resolves
+`{ taskId, finished }` once the agent has confirmed the stream is open (a `200`), or rejects
+(starting no task) on anything else -- an invalid `jobId`, an unknown machine, or a non-`200` from
+the agent (a `404`, a `403` refusal, ...), each surfaced the same way `call` surfaces them. The relay
+itself runs detached from that promise, so nothing in a plugin's own code touches the stream at all.
+It resolves usually while the job is still running (a job that fails fast can end before its stream
+is opened, and the agent then replays its `done` at once), so it says the job started, not that it
+succeeded. `finished` (#733) is the job's end. It is **optional**: the first host release that
+contains #733 (after 2.0.0-alpha.56) supplies it; 2.0.0-alpha.56 and older do not, so a consumer must
+handle `undefined`. It settles with the end the relay finished the task with, the one the tasks
+drawer shows: `{ status: "done" }` only for the agent's `done` frame with `status: "done"`, and
+`{ status: "failed", reason }` for every other end. `reason` is `job ended with status failed` (or
+`job ended with an unknown status`) when the agent said the job failed, and
+`stream ended before done: <message>`, the drawer's last line without its brackets, when the stream
+closed or errored first or the `done` frame did not parse, so the job's own failure and a lost stream
+read differently. It never rejects. It never settles when the relay sees no end at all: the host
+stopping while the job runs (the relay stops with the process), or a hung job. It does not settle
+while the connection is silently gone, and never if it does not come back (a reboot, a lost NAT
+mapping): no FIN or RST reaches the host, and the stream has no body timeout, no keepalive and no
+agent heartbeat.
 
 ```ts
 const { jobId } = await execResult // however the plugin's own verb call started the job
-const { taskId } = await host.agent.streamJob(machineId, jobId, { label: `code: ${prompt}` })
+const { taskId, finished } = await host.agent.streamJob(machineId, jobId, { label: `code: ${prompt}` })
 // taskId names the task now streaming in the tasks drawer -- the action can simply return it.
+// Don't await `finished` in the action: the modal would wait for the whole job. It is absent on an
+// older host, and a throw in the handler must not become an unhandled rejection.
+void finished
+  ?.then((end) => host.events.emit("my.run", { ...end, taskId }))
+  .catch((err) => host.log.warn(`my.run end not emitted: ${String(err)}`))
 ```
 
 `plugins/claude-runner` (#54) is the reference: `task.code` and `routine.rerun` call `exec/claude`
-then `streamJob` and return the task id, never touching SSE framing themselves. The `agents` plugin's
+then `streamJob` and return the task id, never touching SSE framing themselves, and emit
+`claude.run` `done` or `failed` from `finished` (#733). The `agents` plugin's
 `toolchain.upgrade` action (#675) is the example of a verb with its own events route: it starts the
 job with `host.agent.call`, remembers the job id per machine (the confirm modal's settled event carries no
 result, so a panel cannot read it from there) and relays the stream with `path`.
@@ -901,13 +990,21 @@ interface AttentionItem {
   source: string              // your own plugin id -- the rollup shows it as the row's source
   text: string                 // always a counted sentence: "3 open actions in the ledger", never "some actions"
   badge?: string
-  href?: string                // an external link; wins over `target` when both are set
+  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>"
   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
 }
 ```
 
+The rollup is lenient with a row it cannot use as typed (#722): it drops a row only when the row is not
+an object or its `id` or `text` is not a string. Otherwise it normalises: a missing or non-string
+`source` becomes your plugin id, a `severity` other than the three ranks and renders as `"info"`, a
+number `badge` or `hint` becomes its string, and an object or array one is left out (the row stays).
+A `target` that is not a string is ignored.
+
 **Own the fact, own the row.** The rollup itself derives nothing -- it only merges what contributors
 already computed. If your plugin is the one that KNOWS a fact is wrong (a failed job, a stale scan, a
 stuck push), your plugin is the one that turns it into a row, at the severity and with the hint that
@@ -1033,7 +1130,7 @@ 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 })` |
-| Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`) | `runJob(ctx)` dispatching on `ctx.jobId` |
+| Job | `jobs[]` (`id`, `schedule`, `timeoutSec`, `runOn`, `minAgentVersion?`, `capabilities?`) | `runJob(ctx)` dispatching on `ctx.jobId` |
 | Route | `routes[]` (`method`, `path`) | `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 }` |

package/dist/attention.d.ts

@@ -18,6 +18,12 @@ export interface AttentionAction {
     title: string;
     body: string;
 }
+/** One needs-attention row. The rollup card (`plugins/overview`) is lenient with a contributor's
+ *  JSON (#722): it drops a row only when the row is not an object or its `id` or `text` is not a
+ *  string. Otherwise it normalises: a `source` that is missing or not a string becomes the id of the
+ *  plugin the row was fetched from; a `severity` other than the three ranks and renders as `"info"`;
+ *  a number `badge` or `hint` becomes its string, and an object or array one is left out (the row
+ *  is kept). */
 export interface AttentionItem {
     /** Unique within the contributing plugin; the rollup's dedupe key is `${source}:${id}`. */
     id: string;
@@ -27,15 +33,22 @@ export interface AttentionItem {
     /** Always a counted sentence (1.x's `attCount`, e.g. "1 scheduled job run failed"). */
     text: string;
     badge?: string;
-    /** An external link; wins over `target` when both are present (1.x's own precedence). */
+    /** An external link; wins over `target` when both are present (1.x's own precedence). Resolved
+     *  against the console's page, it is linked only when its scheme is `http:`, `https:`, `mailto:`
+     *  or `tel:` (#722): any other `href` (`javascript:`, `data:`, `blob:`, `vbscript:`, `file:`, a
+     *  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. */
+     *  `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`). */
     hint?: string;
     action?: AttentionAction;
 }
+/** `GET /api/x/<id>/attention`'s answer. Each of `items` is read as `AttentionItem` describes,
+ *  including which malformed rows the rollup drops and which it normalises (#722). */
 export interface AttentionResponse {
     ok: true;
     items: AttentionItem[];

package/dist/host-api.d.ts

@@ -9,7 +9,9 @@
 import type { Octokit } from "@octokit/rest";
 import type { HttpMethod } from "./manifest.js";
 import type { AgentCallOutcome, JobMachineRun, MachineView } from "./views.js";
-/** A typed, per-plugin settings accessor (backed by the host's settings overlay). */
+/** A typed, per-plugin settings accessor: this plugin's own rows in the host's `plugin_settings` table, a
+ *  key with no stored value reading as its manifest `default` (`contributes.settings[]`). Not the
+ *  host-global settings, which `consoleSettings` reads. */
 export interface SettingsService {
     get<T = unknown>(key: string): Promise<T | undefined>;
     set(key: string, value: unknown): Promise<void>;
@@ -19,7 +21,9 @@ export interface SettingsService {
  * distinct from `SettingsService` above, which is per-plugin. Only a key on the editable-settings
  * whitelist (`settings-schema.ts`) is readable here; any other key resolves to `undefined`, so a
  * plugin can never reach an arbitrary host-global key through this surface. The value returned is
- * the EFFECTIVE one (an `AC_<KEY>` env override included), the same value the Settings card shows.
+ * the EFFECTIVE one (an `AC_<KEY>` env override included), the same value the Settings card shows,
+ * except that a whitelisted key with no stored value and no env var resolves to `undefined` here
+ * while the card shows its declared default (an empty string), so treat the two alike.
  */
 export interface ConsoleSettingsService {
     get<T = unknown>(key: string): Promise<T | undefined>;
@@ -33,7 +37,8 @@ export interface StorageService {
 /** Register/trigger the plugin's contributed jobs and read their last result. */
 export interface JobsService {
     /** Run a contributed job now (the manual-trigger endpoint). For a `runOn: "agent"` job this resolves
-     *  once every currently paired machine has either run or been queued. */
+     *  once every currently paired machine has been run, queued, or skipped (a missing grant, #843, or a
+     *  `minAgentVersion` floor). */
     trigger(jobId: string): Promise<void>;
     /** The last run of a job, if it has run — for an agent job, the newest recorded run across every
      *  machine. */
@@ -48,14 +53,14 @@ export interface JobsService {
      *  scoped to the calling plugin's own jobs; this is the needs-attention rollup's in-process read of
      *  every OTHER loaded plugin's job health, so `overview`'s `/attention` route never has to make an
      *  HTTP call back into its own host. Discloses nothing `GET /api/jobs/:pluginId/:jobId/runs`
-     *  doesn't already serve publicly -- just a non-HTTP path to the same data. Optional: only
-     *  `overview` calls it today. */
+     *  doesn't already serve publicly -- just a non-HTTP path to the same data. Optional: `overview`'s
+     *  rollup and `ac-notify-discord`'s digest call it. */
     machineRunsOf?(pluginId: string, jobId: string): Promise<JobMachineRun[]>;
 }
-/** #78: every loaded in-process plugin's own declared jobs -- lets the needs-attention rollup
- *  discover what to poll via `jobs.machineRunsOf` without a second manifest fetch or an HTTP
- *  self-loop. Host-internal discovery only (unlike `PluginView`, never served over HTTP as its own
- *  route); optional on `HostApi` since only `overview` uses it. */
+/** #78: every running in-process plugin's own declared jobs -- lets the needs-attention rollup (and
+ *  `ac-notify-discord`'s digest) discover what to poll via `jobs.machineRunsOf` without a second
+ *  manifest fetch or an HTTP self-loop. Host-internal discovery only (unlike `PluginView`, never served
+ *  over HTTP as its own route); optional on `HostApi`, since only those two use it. */
 export interface PluginJobsService {
     list(): {
         pluginId: string;
@@ -70,19 +75,31 @@ export interface JobDeclaration {
 }
 /** The typed event bus (e.g. `issue.changed`, `job.finished`, `artifact.rendered`). */
 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). */
     emit(type: string, payload: unknown): void;
-    /** Subscribe; returns an unsubscribe function. */
-    on(type: string, handler: (payload: unknown) => void): () => 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
+     *  logged, never unhandled; any other return value is ignored. The return type is `unknown`,
+     *  not `void | Promise<void>`, because only `unknown` still admits every handler the earlier
+     *  `=> void` did (`(p) => list.push(p)` returns a number). */
+    on(type: string, handler: (payload: unknown) => unknown): () => void;
 }
 /** One shared, rate-limit-aware GitHub client (Octokit; PAT from env, #127). Consumers make every
  *  GitHub call through `octokit()` rather than constructing a second client. */
 export interface GithubService {
     /** The authenticated login, cached. */
     viewer(): Promise<string>;
-    /** The one shared Octokit REST client — consumers make all GitHub calls through this. */
+    /** 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). */
     octokit(): Octokit;
-    /** Remaining primary-rate-limit budget from the last response's headers, or undefined before any
-     *  call. */
+    /** 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
+     *  429 carrying `x-ratelimit-remaining: 0` reads as 0 here, not as the last successful count), or
+     *  undefined before any such response. A response with a header missing or malformed changes nothing. */
     rateLimit(): {
         remaining: number;
         limit: number;
@@ -107,27 +124,55 @@ export interface AgentService {
          *  300 s). A long-running verb -- a scan -- passes the verb's own limit plus a margin, so the
          *  agent's own timeout answer arrives before the console gives up. */
         timeoutMs?: number;
+        /** Abandons the call when it aborts (#701): a job passes its run's `ctx.signal`, so a run the
+         *  host has timed out stops waiting on the agent. The request is cancelled on the wire and the
+         *  call resolves `{ ok: false, error: { kind: "network", reason } }`, `reason` being the
+         *  signal's `reason.message` when that reason is an `Error`, else `"aborted"`. */
+        signal?: AbortSignal;
     }): Promise<AgentCallOutcome<T>>;
     /**
      * Open a paired machine's job event stream (`GET /v1/jobs/:jobId/events`, #54) and relay it into a
      * new host task: every agent `line` frame becomes a `task.log`, the `done` frame finishes it --
      * the tasks drawer streams the machine's job with no new UI (decision 12/20). Resolves with the new
-     * task's id once the stream is confirmed open (the agent answered `200`); the relay itself then runs
-     * detached and can never surface here. Rejects (starting no task) on an invalid `jobId`, an unknown
-     * machine, or any non-`200` response from the agent (a `404` unknown job, a `403` refusal, ...) --
-     * the same failure shapes `call` throws for a bad path, surfaced the same way.
+     * task's id once the stream is confirmed open (the agent answered `200`), usually while the job is
+     * still running (a job that fails fast can end before its stream is opened, and the agent then
+     * replays its `done` at once); the relay itself then runs detached, and its failures never reject
+     * here (see `finished`). Rejects (starting no task) on an invalid `jobId`, an unknown machine, or any
+     * non-`200` response from the agent (a `404` unknown job, a `403` refusal, ...) -- the same failure
+     * shapes `call` throws for a bad path, surfaced the same way.
      *
      * `path` (#675) is the events route of a job that does not live under `/v1/jobs`: the toolchain
      * upgrade's is `/v1/toolchain/upgrade/<jobId>/events`, readable only by a plugin holding that verb's own
      * capability. Omitted, it is `/v1/jobs/<jobId>/events` exactly as before. It is not a free path: it must be
      * `/v1/<one or more lowercase segments>/<jobId>/events` with this call's own `jobId`, and carry no query,
      * fragment, escape or dot segment; anything else rejects (starting no task, making no request).
+     *
+     * `finished` (#733) says how the job ended. The first host release that contains #733 (after
+     * 2.0.0-alpha.56) supplies it; 2.0.0-alpha.56 and older do not, so a consumer must handle
+     * `undefined` (it is optional for that reason, and so an out-of-repo plugin's own test fake still
+     * compiles). It settles with the status the relay finished the task with, so it always agrees with
+     * the tasks drawer: `{ status: "done" }` for the agent's `done` frame carrying `status: "done"`, and
+     * `{ status: "failed", reason }` for any other end. `reason` tells the job's own failure apart from
+     * the console losing sight of it: `job ended with status failed` (or `job ended with an unknown
+     * status`) when the agent's `done` frame says so, and `stream ended before done: <message>`, the
+     * tasks drawer's last line without its brackets, when the stream closed or errored before its
+     * `done` frame, or that frame did not parse. It never rejects. It never settles when the relay sees
+     * no end at all: when the host stops while the job runs (the relay stops with the process), or when
+     * the job hangs. It does not settle while the connection is silently gone, and never if it does not
+     * come back (a reboot, a lost NAT mapping): with the machine asleep or the network gone, no FIN or
+     * RST reaches the host, and the stream has no body timeout, no keepalive and no agent heartbeat.
      */
     streamJob(machineId: string, jobId: string, opts: {
         label: string;
         path?: string;
     }): Promise<{
         taskId: string;
+        finished?: Promise<{
+            status: "done";
+        } | {
+            status: "failed";
+            reason: string;
+        }>;
     }>;
 }
 /** Proxy to a sidecar plugin's HTTP surface (the host handles health + base URL). */
@@ -135,7 +180,8 @@ export interface SidecarService {
     /** The base URL the host proxies to for a sidecar plugin. */
     baseUrl(pluginId: string): string;
 }
-/** Register a confirm-gated action; the shell builds its button + modal from the manifest data. */
+/** Register an action's `run`; the shell builds its button + modal from the manifest data, and opening
+ *  the modal is the action's one confirmation (#530). */
 export interface ActionsService {
     register(action: {
         id: string;
@@ -193,13 +239,21 @@ export interface SlotRegistry {
      *  there for good (#97). */
     resolve<T = unknown>(slot: string, version: number): T | null;
 }
-/** A logger prefixed with the plugin id. */
+/** 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
+ *  `{ error: <message>, stack }`; every other arg is kept, in order, under `args` (an `Error` there, or as a
+ *  field's value, as its own properties plus `message` and `stack`); a field named `time`, `level`, `msg`
+ *  or `plugin` is renamed `field_<key>`, so it cannot relabel the line. A call never throws: a value JSON
+ *  cannot write (a `BigInt`, a circular structure, a throwing getter) is logged as a string (#786). */
 export interface LogService {
     info(message: string, ...args: unknown[]): void;
     warn(message: string, ...args: unknown[]): void;
     error(message: string, ...args: unknown[]): void;
 }
-/** Read declared env keys only (the manifest's `env[]`). */
+/** Read declared env keys only (the manifest's `env[]`). This scopes what a plugin reads; it is not a
+ *  secrecy boundary (#784): the plugin writes its own `env[]`, nothing restricts which keys it declares
+ *  (another plugin's, or a host-owned one like `AC_GITHUB_TOKEN`), and in-process plugin code can read
+ *  `process.env` directly. */
 export interface EnvService {
     get(key: string): string | undefined;
 }
@@ -226,7 +280,8 @@ export interface HostApi {
     actions: ActionsService;
     log: LogService;
     env: EnvService;
-    /** #78: see `PluginJobsService`. Optional -- only `overview`'s needs-attention rollup uses it. */
+    /** #78: see `PluginJobsService`. Optional -- `overview`'s rollup and `ac-notify-discord`'s digest use
+     *  it. */
     plugins?: PluginJobsService;
     /** #84: see `SlotRegistry`. */
     slots: SlotRegistry;
@@ -254,6 +309,11 @@ export interface JobRunContext {
 }
 /** A plugin instance. `createPlugin(host)` is pure; I/O only in `activate()` (design §4 lifecycle). */
 export interface Plugin {
+    /** Register routes, actions, subscriptions and slot providers. A plugin whose `activate()` throws, or
+     *  has not settled within the host's load deadline (30 s), is errored and everything it registered is
+     *  undone: its routes answer 404, its actions and subscriptions are dropped, a slot it bound is
+     *  released (except `auth`), #785. The same holds for a `createPlugin` that throws or returns no
+     *  object with an `activate` method. */
     activate(): void | Promise<void>;
     /**
      * Run one of the plugin's contributed jobs, dispatched by `ctx.jobId` (#31's scheduler). Optional —
@@ -323,10 +383,12 @@ export interface BrowserHostApi {
      * rather than followed -- `credentials: "same-origin"` alone would not stop the request itself, or a
      * write's `X-AC-CSRF` token, from reaching a third-party origin. Credentials are included
      * (`same-origin`); a non-GET/HEAD/OPTIONS request carries the `X-AC-CSRF` token fetched once from
-     * `GET /api/config` (#85) and cached -- defense-in-depth alongside the Origin check #85 already
-     * enforces, not itself required yet. Panels read a provider's routes (e.g.
-     * `/api/x/provider-github/…`) through this rather than a bare `fetch`. Returns the raw `Response`;
-     * the caller parses it.
+     * `GET /api/config` (#85) and cached. The host requires that token only where its `requireCsrf`
+     * middleware is mounted (`POST /api/attachments`, `POST`/`DELETE /api/plugins/indexes`, the
+     * `/api/plugins/install/*` writes); every other write, a plugin's own `/api/x/<id>/…` routes
+     * included, has the Origin check #85 enforces on every mutating request as its CSRF defence.
+     * Panels read a provider's routes (e.g. `/api/x/provider-github/…`) through this rather than a
+     * bare `fetch`. Returns the raw `Response`; the caller parses it.
      */
     fetch(path: string, init?: RequestInit): Promise<Response>;
     /**

package/dist/manifest.d.ts

@@ -91,13 +91,16 @@ export interface ActionField {
      */
     optionsFrom?: ActionOptionsSource;
 }
-/** A confirm-gated action; the shell builds its button + modal from these fields (#34). */
+/** An action; the shell builds its button + modal from these fields (#34), and opening the modal is the
+ *  action's one confirmation (#530). */
 export interface ActionContribution {
     id: string;
     /** Button/label text; the shell falls back to `id` when omitted. */
     title?: string;
     /** What the action operates on, e.g. "issue" | "report" | "global". */
     scope: string;
+    /** Accepted, but inert since #530: the modal is the one confirmation, so neither it nor the palette
+     *  asks for a second click. */
     confirm?: boolean;
     danger?: boolean;
     /** The form the shell builds the action's modal from; omit for a no-input action. */
@@ -108,7 +111,12 @@ export type JobRunOn = "host" | "agent";
 /** A scheduled job. */
 export interface JobContribution {
     id: string;
-    /** 5-field cron expression. */
+    /**
+     * 5-field cron expression (the host's `jobs/cron.ts` grammar). Not validated when the plugin loads
+     * (#784): a schedule that does not parse is logged at warn when the scheduler starts and the job is
+     * never scheduled, while the plugin itself loads as usual. Every bundled plugin's schedules are
+     * parsed in CI.
+     */
     schedule: string;
     /**
      * Per-run timeout in seconds. Must be at least 1: a zero or negative value would fire the timeout at
@@ -125,6 +133,14 @@ export interface JobContribution {
      *  `runOn: "host"` job. Additive; absent means every paired machine is always dispatched, as
      *  before this field existed. */
     minAgentVersion?: string;
+    /** The host-agent capabilities this job's verbs need on a machine (#843). A `runOn: "agent"` job is
+     *  not dispatched to a paired machine that has not granted this plugin every one of them. That
+     *  machine's row records `skipped` with reason `not granted: <capability>[, ...]` instead: no run is
+     *  recorded, no `job.finished` is emitted and no failure is notified. Each must be declared in the
+     *  plugin's top-level `capabilities` (the host refuses the manifest otherwise). Ignored for a
+     *  `runOn: "host"` job. Additive: absent or empty dispatches to every paired machine, as before this
+     *  field existed. A host released before this field refuses a manifest that declares it. */
+    capabilities?: string[];
 }
 /** HTTP method for a contributed route. */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
@@ -168,18 +184,27 @@ export interface Contributes {
     /** #78: the plugin serves `GET /api/x/<id>/attention` -> `{ ok: true, items: AttentionItem[] }`
      *  (`attention.ts`). The `overview` plugin's rollup card discovers contributors via
      *  `PluginView.attention` (`views.ts`) rather than a second manifest read. Additive; always `true`
-     *  when present (a boolean, not a route list, since the path is fixed). */
+     *  when present (a boolean, not a route list, since the path is fixed). The plugin must also declare
+     *  that route in `routes` and register it; the host checks neither at load (#784; every bundled
+     *  plugin's is checked in CI), and the rollup counts a contributor whose route fails as not loaded. */
     attention?: true;
 }
-/** A declared environment variable (field names shared verbatim with the discord-bot index). */
+/**
+ * A declared environment variable (field names shared verbatim with the discord-bot index). Declaring
+ * a key is what lets `HostApi.env.get` read it. `format` and `required` are metadata only: the host
+ * checks a value against neither (#784), so a plugin that depends on one checks its own value.
+ */
 export interface EnvVar {
     key: string;
-    /** Anchored regex the value must match, e.g. "^[0-9]+$". */
+    /** Anchored regex the value is expected to match, e.g. "^[0-9]+$". Not enforced by the host; every
+     *  bundled plugin's compiles and is anchored (checked in CI). */
     format?: string;
+    /** Whether the plugin needs a value. Not enforced by the host: a missing value reads `undefined`. */
     required?: boolean;
     secret?: boolean;
 }
-/** A sidecar plugin's image and health path. Present when `kind === "sidecar"`. */
+/** A sidecar plugin's image and health path, expected when `kind === "sidecar"`. The host reads only
+ *  `healthPath` (its health poll) and never `image` (the compose file names the sidecar's image). */
 export interface SidecarSpec {
     image: string;
     healthPath: string;
@@ -199,9 +224,11 @@ export interface AcPluginManifest {
     server?: string;
     /** Frontend ESM entry; omitted by a plugin that contributes no UI. */
     frontend?: string;
-    /** Image + health path; required when `kind: "sidecar"`. */
+    /** Image + health path, expected when `kind: "sidecar"`. Not enforced at load (#784): without it the
+     *  health poll uses `/healthz`. Every bundled sidecar plugin's is checked in CI. */
     sidecar?: SidecarSpec;
-    /** Host-agent capabilities the plugin may use, each granted per machine in Admin (E4). */
+    /** Host-agent capabilities the plugin may use, each granted per machine in Admin (E4). A job's own
+     *  `capabilities` (#843) is a subset of this list. */
     capabilities?: string[];
     contributes?: Contributes;
     env?: EnvVar[];

package/dist/slots.d.ts

@@ -84,7 +84,16 @@ export interface LabelStandard {
     type: Label[];
     exclusive: string[];
 }
-/** `issues@1`: list/search/labels/people/mutate over forge-agnostic records. */
+/**
+ * `issues@1`: list/search/labels/people/mutate over forge-agnostic records.
+ *
+ * Declared, not bound (#784): `provider-github` declares `provides: issues@1`, and that declaration is
+ * what lets its consumers (`issues-board`, `issues-classic`) activate, but it binds no implementation of
+ * this interface, so `host.slots.resolve("issues", 1)` answers `null`. The consumers read
+ * `provider-github`'s HTTP routes (`/api/x/provider-github/…`, through `host.fetch`) instead, which
+ * answer the record shapes above. A plugin that wants this interface in-process gets `null` until a
+ * provider binds one.
+ */
 export interface IssuesProvider {
     /** List issues for a repo in a given state. */
     listIssues(repo: RepoRef, state: "open" | "closed" | "all"): Promise<IssueRecord[]>;
@@ -180,7 +189,9 @@ export interface Identity {
      *  model roles (Cloudflare Access does not); an empty array is an identity that holds none (#102). */
     roles?: string[];
 }
-/** `auth@1`: resolve the identity for a request, or null in open mode. */
+/** `auth@1`: resolve the identity for a request. A bound provider answering `null` makes the host refuse
+ *  the request with a 401 (on every route but `/healthz` and `/api/config`); open mode is the host with
+ *  NO provider bound, not a provider answering `null`. */
 export interface AuthProvider {
     /** Resolve the identity from a request's headers, or null when unauthenticated. */
     identify(headers: Record<string, string | undefined>): Promise<Identity | null>;
@@ -195,6 +206,12 @@ export interface NotifyMessage {
 }
 /** `notify@1`: fan out a message to this provider's channel. */
 export interface NotifyProvider {
-    send(message: NotifyMessage): Promise<void>;
+    /** `opts.signal` (#701) is the caller's abort: a job that posts through its own provider passes its
+     *  run's `ctx.signal`, and a provider should then abandon the send and reject. The host's failure
+     *  fan-out passes none. Optional, so a provider written against `send(message)` alone still
+     *  satisfies this interface. */
+    send(message: NotifyMessage, opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
 }
 //# sourceMappingURL=slots.d.ts.map

package/dist/views.d.ts

@@ -40,9 +40,11 @@ export interface PluginCardView {
     export: string;
 }
 /**
- * A confirm-gated action the shell builds a button + form from (#34). Unlike panels/cards, an action is
+ * An action the shell builds a button + form from (#34); opening its modal is its one confirmation (#530).
+ * Unlike panels/cards, an action is
  * pure data (no `export`), so it is surfaced for any loadable plugin regardless of whether it ships a
- * frontend bundle. `confirm`/`danger` are normalised to booleans and `fields` to an array for the shell.
+ * frontend bundle. `confirm`/`danger` are normalised to booleans and `fields` to an array for the shell (`confirm` is inert
+ * since #530).
  */
 export interface PluginActionView {
     id: string;
@@ -59,9 +61,10 @@ export interface PluginActionView {
  * :pluginId/:jobId/runs`'s response already exposes it per call, and this card's row model
  * (`SchedRow.runOn`) plumbs it through end to end even though its current render doesn't surface it
  * (found in review, round 2 — a candidate for a future small UI addition, not a bug).
- * `timeoutSec`/`minAgentVersion` are deliberately left off instead, independent of that: the runs
- * route's `skipped` reason already reflects a `minAgentVersion` gate as a per-machine fact, so
- * duplicating the threshold itself here would have no reader.
+ * `timeoutSec`/`minAgentVersion`/`capabilities` are deliberately left off instead, independent of
+ * that: the runs route's `skipped` reason already reflects a `minAgentVersion` gate or a missing grant
+ * (#843) as a per-machine fact, so duplicating the threshold or the capability list here would have no
+ * reader.
  */
 export interface PluginJobView {
     id: string;
@@ -72,8 +75,8 @@ export interface PluginJobView {
 /**
  * Where a plugin was discovered from (#183): `bundled` under the image's own `plugins/` dir, `installed`
  * under an operator-installed-plugins dir. Derived from the scan root a plugin was found under, never
- * from the manifest — a plugin cannot declare itself first-party. Until the install path exists (E2's
- * #35 follow-up) every plugin is `bundled`.
+ * from the manifest — a plugin cannot declare itself first-party. `installed` is the operator-installed
+ * root (`AC_INSTALLED_PLUGINS_DIR`, #451), filled by the install path (#452).
  */
 export type PluginOrigin = "bundled" | "installed";
 export interface PluginView {
@@ -173,10 +176,17 @@ export interface JobMachineRun {
         queuedAt: string;
         reason: string;
     };
-    /** This machine's paired agent version compares lower than the job's declared `minAgentVersion`
-     *  (#372, #80) -- computed live from the machine's CURRENT version every call, never persisted, so
-     *  it always reflects "would a dispatch right now skip this machine", not a stale historical fact.
-     *  Independent of `lastRun`/`queued`, which can still be set from before the machine fell behind. */
+    /** A dispatch right now would skip this machine, for one of two causes: it has not granted the
+     *  plugin every capability the job declares (#843; reason `not granted: <capability>[, ...]`, the
+     *  missing ones in declared order), or its paired agent version compares lower than the job's
+     *  declared `minAgentVersion` (#372, #80; reason `agent <version> < <min>`). A missing grant wins
+     *  when both hold. Computed live every call from the machine's CURRENT grants and version, never
+     *  persisted, so it always reflects "would a dispatch right now skip this machine", not a stale
+     *  historical fact. Independent of `lastRun`/`queued`. Either can be set from before the skip
+     *  applied, and a `queued` row with a version cause can also be written WHILE the skip applies: an
+     *  unreachable machine is queued before any floor is judged, since the floor is judged only on a
+     *  version a probe just reported. A grant skip is judged before the unreachable branch, so it never
+     *  writes one and clears any it finds. */
     skipped?: {
         reason: string;
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.56",
+  "version": "2.0.0-alpha.58",
   "private": false,
   "type": "module",
   "description": "The artifact-console plugin ABI for out-of-repo plugin authors: HostApi, the acPlugin manifest contribution points, the generated manifest JSON Schema, and the @ac/host ambient browser declaration.",

package/schema.json

@@ -26,14 +26,14 @@
         },
         "sidecar": {
           "$ref": "#/definitions/SidecarSpec",
-          "description": "Image + health path; required when `kind: \"sidecar\"`."
+          "description": "Image + health path, expected when `kind: \"sidecar\"`. Not enforced at load (#784): without it the health poll uses `/healthz`. Every bundled sidecar plugin's is checked in CI."
         },
         "capabilities": {
           "type": "array",
           "items": {
             "type": "string"
           },
-          "description": "Host-agent capabilities the plugin may use, each granted per machine in Admin (E4)."
+          "description": "Host-agent capabilities the plugin may use, each granted per machine in Admin (E4). A job's own `capabilities` (#843) is a subset of this list."
         },
         "contributes": {
           "$ref": "#/definitions/Contributes"
@@ -76,7 +76,7 @@
         "healthPath"
       ],
       "additionalProperties": false,
-      "description": "A sidecar plugin's image and health path. Present when `kind === \"sidecar\"`."
+      "description": "A sidecar plugin's image and health path, expected when `kind === \"sidecar\"`. The host reads only `healthPath` (its health poll) and never `image` (the compose file names the sidecar's image)."
     },
     "Contributes": {
       "type": "object",
@@ -138,7 +138,7 @@
         "attention": {
           "type": "boolean",
           "const": true,
-          "description": "#78: the plugin serves `GET /api/x/<id>/attention` -> `{ ok: true, items: AttentionItem[] }` (`attention.ts`). The `overview` plugin's rollup card discovers contributors via `PluginView.attention` (`views.ts`) rather than a second manifest read. Additive; always `true` when present (a boolean, not a route list, since the path is fixed)."
+          "description": "#78: the plugin serves `GET /api/x/<id>/attention` -> `{ ok: true, items: AttentionItem[] }` (`attention.ts`). The `overview` plugin's rollup card discovers contributors via `PluginView.attention` (`views.ts`) rather than a second manifest read. Additive; always `true` when present (a boolean, not a route list, since the path is fixed). The plugin must also declare that route in `routes` and register it; the host checks neither at load (#784; every bundled plugin's is checked in CI), and the rollup counts a contributor whose route fails as not loaded."
         }
       },
       "additionalProperties": false,
@@ -229,7 +229,8 @@
           "description": "What the action operates on, e.g. \"issue\" | \"report\" | \"global\"."
         },
         "confirm": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Accepted, but inert since #530: the modal is the one confirmation, so neither it nor the palette asks for a second click."
         },
         "danger": {
           "type": "boolean"
@@ -247,7 +248,7 @@
         "scope"
       ],
       "additionalProperties": false,
-      "description": "A confirm-gated action; the shell builds its button + modal from these fields (#34)."
+      "description": "An action; the shell builds its button + modal from these fields (#34), and opening the modal is the action's one confirmation (#530)."
     },
     "ActionField": {
       "type": "object",
@@ -344,7 +345,7 @@
         },
         "schedule": {
           "type": "string",
-          "description": "5-field cron expression."
+          "description": "5-field cron expression (the host's `jobs/cron.ts` grammar). Not validated when the plugin loads (#784): a schedule that does not parse is logged at warn when the scheduler starts and the job is never scheduled, while the plugin itself loads as usual. Every bundled plugin's schedules are parsed in CI."
         },
         "timeoutSec": {
           "type": "number",
@@ -358,6 +359,13 @@
         "minAgentVersion": {
           "type": "string",
           "description": "A `runOn: \"agent\"` job is not dispatched to a machine whose paired agent version compares lower than this (#372, #80); the run row records the skip with its reason instead. Ignored for a `runOn: \"host\"` job. Additive; absent means every paired machine is always dispatched, as before this field existed."
+        },
+        "capabilities": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The host-agent capabilities this job's verbs need on a machine (#843). A `runOn: \"agent\"` job is not dispatched to a paired machine that has not granted this plugin every one of them. That machine's row records `skipped` with reason `not granted: <capability>[, ...]` instead: no run is recorded, no `job.finished` is emitted and no failure is notified. Each must be declared in the plugin's top-level `capabilities` (the host refuses the manifest otherwise). Ignored for a `runOn: \"host\"` job. Additive: absent or empty dispatches to every paired machine, as before this field existed. A host released before this field refuses a manifest that declares it."
         }
       },
       "required": [
@@ -483,10 +491,11 @@
         },
         "format": {
           "type": "string",
-          "description": "Anchored regex the value must match, e.g. \"^[0-9]+$\"."
+          "description": "Anchored regex the value is expected to match, e.g. \"^[0-9]+$\". Not enforced by the host; every bundled plugin's compiles and is anchored (checked in CI)."
         },
         "required": {
-          "type": "boolean"
+          "type": "boolean",
+          "description": "Whether the plugin needs a value. Not enforced by the host: a missing value reads `undefined`."
         },
         "secret": {
           "type": "boolean"
@@ -496,7 +505,7 @@
         "key"
       ],
       "additionalProperties": false,
-      "description": "A declared environment variable (field names shared verbatim with the discord-bot index)."
+      "description": "A declared environment variable (field names shared verbatim with the discord-bot index). Declaring a key is what lets `HostApi.env.get` read it. `format` and `required` are metadata only: the host checks a value against neither (#784), so a plugin that depends on one checks its own value."
     }
   }
 }