@rackbops/ac-plugin-contract 2.0.0-alpha.53 → 2.0.0-alpha.55

package/AUTHORING.md

@@ -451,8 +451,10 @@ the bar collapses. The layout arithmetic and the whole-pixel rounding were measu
 bundling a library the import map does not carry. `plugins/ac-artifacts-weft` inlines
 `@lepid-labs/weft-embed` (a framework-free reader, 1.15 MB) and its stylesheet into `dist/ui.js`, and its
 `rollup.ui.config.mjs` is the reference. (The rollup configs of `issues-classic` and `ac-auth-cf-access`
-inline a dependency into their SERVER bundle, and every other plugin's UI config inlines nothing; none of
-them is a model for this.) What a bundled dependency changes:
+inline a dependency into their SERVER bundle only. `plugins/agents` inlines the small pure-TypeScript
+`@rackbops/toolchain-compare` into its server AND its UI bundle (#694), with no stylesheet; every other plugin's
+UI config inlines nothing. None of them is a model for a frontend dependency with a stylesheet.) What a bundled
+dependency changes:
 
 - **One file.** The host serves exactly the manifest's `frontend` and never a sibling, so a stylesheet is a
   string in the bundle that the panel injects as a `<style>`, once (the config's `inlineCss` plugin turns
@@ -710,8 +712,12 @@ into `dist/server.js` — the image ships a plugin's `package.json` + `dist/*.js
 is the worked example (#312): `tsconfig.build.json` emits the server alone to `dist-tsc/`, and
 `rollup.config.mjs` bundles that into `dist/server.js` with everything except Node's own `node:*` built-ins
 inlined — `yaml` (its `views.yaml` parser) included. `createPlugin` stays pure regardless of how the server is
-built. The **frontend** is never bundled this way (§3 above) — `@ac/host`/`react`/`@rackbops/ui-react` resolve
-through the shell's import map, not a bundle.
+built. (`plugins/agents` is a second example, #694: its server imports the published
+`@rackbops/toolchain-compare`, so `tsconfig.build.json` emits to `dist-tsc/` and its `rollup.config.mjs` bundles that
+into `dist/server.js`; `bundle.test.ts` pins that the file imports nothing but `node:` built-ins.) The
+**frontend** never inlines the import-map specifiers (§3 above) — `@ac/host`/`react`/`@rackbops/ui-react` resolve
+through the shell's import map, not a bundle; a library the map does not carry may be inlined (see "A frontend
+that bundles a dependency").
 
 ## 4. `CHANGELOG.md` — required, and version-matched
 
@@ -857,7 +863,11 @@ 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` through the same pinned client, registers a new host task for
+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, 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
 else -- an invalid `jobId`, an unknown machine, or a non-`200` from the agent (a `404`, a `403`
@@ -871,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/package.json

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