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

package/AUTHORING.md

@@ -864,8 +864,9 @@ console before the console gives up and reports a bare `network` timeout instead
 A capability whose verb starts a long-running agent job (`exec/claude`'s `{ jobId }`, #54) doesn't
 need to poll or parse SSE itself -- `host.agent.streamJob(machineId, jobId, { label })` opens the
 agent's `GET /v1/jobs/:jobId/events` (which serves `claude` jobs only since #675: a toolchain-upgrade
-job's stream is `GET /v1/toolchain/upgrade/:jobId/events`, under its own capability, and is not
-reachable through `streamJob` until the console's PR 2 for #675 adds an optional path) through the same
+job's stream is `GET /v1/toolchain/upgrade/:jobId/events`, under its own capability, which `streamJob`
+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
@@ -880,7 +881,10 @@ const { taskId } = await host.agent.streamJob(machineId, jobId, { label: `code:
 ```
 
 `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.
+then `streamJob` and return the task id, never touching SSE framing themselves. 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`.
 
 ## 8. The needs-attention rail (#78)
 

package/dist/host-api.d.ts

@@ -116,9 +116,16 @@ export interface AgentService {
      * 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.
+     *
+     * `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).
      */
     streamJob(machineId: string, jobId: string, opts: {
         label: string;
+        path?: string;
     }): Promise<{
         taskId: string;
     }>;

package/dist/views.d.ts

@@ -244,7 +244,8 @@ export type AgentCallOutcome<T> = {
 /**
  * `POST /api/agents/:id/preflight` (#55): the agent's own `GET /v1/preflight` report, relayed
  * verbatim by the host. `missing`/`broken` on a `required: true` row means the install isn't
- * finished; on an optional one (`chromium`) it just degrades one output. `off-path` is installed
+ * finished; on an optional one (`docker`, `cloudflared`, `chromium`) it is no failed preflight, only a tool
+ * this machine does not have or cannot run (for `chromium`, one output degrades). `off-path` is installed
  * but invisible to a service-started agent (a version-manager node, say) -- a PATH fix, not a
  * reinstall. `unauthenticated` is `gh`-only: present and running, but `gh auth status` failed.
  * Independently defined here from the agent's own (identically-shaped) internal type -- the host

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rackbops/ac-plugin-contract",
-  "version": "2.0.0-alpha.54",
+  "version": "2.0.0-alpha.56",
   "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.",