@defrex/autobuild 0.11.0 → 0.13.0

package/skills/guide/references/operator-api.md

@@ -6,17 +6,48 @@ Every request must send `X-Autobuild-Version`,
 `X-Autobuild-Protocol-Version: 3`, and `Authorization: Bearer …`. Identity is
 checked before authentication or resource lookup.
 
-Mint a token offline; the signed user is used as the human actor on every write:
+Project credentials are opaque `abp_1_<id>_<secret>` bearer values bound to one
+registered normalized repository. The service stores only a SHA-256 digest of
+the random secret, plus project, creator, creation time, last use, expiry and
+revocation metadata. It checks credential status and project registration on
+every request. Revocation takes effect on the next request without affecting
+other credentials. Unknown, expired or revoked credentials receive `401 auth`;
+removed projects receive `403 auth` with `project not registered`.
+
+The deployment owner runs these commands locally with database access:
 
 ```sh
-AB_STORE_SECRET='…' bun packages/hosted-store-service/src/bin.ts mint operator \
-  --user 'Ada Lovelace' --ttl-seconds 3600
+ab-hosted-store credentials issue https://github.com/acme/app --user owner@example.com
+ab-hosted-store credentials list https://github.com/acme/app
+ab-hosted-store credentials revoke https://github.com/acme/app --id ID --user owner@example.com
 ```
 
-Admin, build, repository, and deployment (`{ "operator": true, … }`) tokens
-have no attributed operator authority. Human-operator tokens have no raw
-`/builds`, `/repos`, `/sessions`, or `/tickets` authority. Encode repository,
-build, session, and artifact kind as separate URL path segments.
+Issue prints the secret once; list contains metadata only. Issue optionally
+accepts `--ttl-seconds N` or `--expires-at ISO-8601`. For administrative/non-interactive issuance, set the returned token as
+`AB_TOKEN`. Interactive project onboarding uses `ab connect <service-url>`;
+it saves the credential outside the repository and commits no secret. Previous `AB_TOKEN` values and `mint operator` / `mint build` are
+retired: the service responds that the credential format changed and points
+to `credentials issue`. Supported old protocol shapes still work with a new
+credential; protocol compatibility does not restore retired authentication.
+
+`mint admin --ttl-seconds N` creates an explicit versioned, attributed owner
+break-glass credential. It can cross project boundaries. Keep it owner-only:
+never give it or `AB_STORE_SECRET` to a dispatcher or build agent.
+
+Owner-purpose project credentials attribute every write to their recorded creator.
+Dispatcher-purpose credentials are refused. Signed-in owners in the dashboard
+and MCP receive short-lived internal signatures with an explicit version,
+selected repository, signed user, expiry and MCP `via`. Only the service holds
+the signing key. These signatures authorize operator routes only and require a
+registered project; replay against another project is refused.
+
+The path project is checked before registry lookup, body parsing and generic
+tool execution. Body repositories and secondary build/session identifiers are
+also checked inside that project. Explicit project mismatches return `403 auth:
+wrong project`; removal returns `403 auth: project not registered`. Encode each
+repository, build, session and artifact kind as a separate URL path segment.
+Registration changes use the database-local `projects list|add|remove` owner
+commands; see [owner workflow](setup.md#connected-projects).
 
 ## Operator sessions
 
@@ -56,6 +87,7 @@ turn runner (a later ticket) is the only producer of turn facts.
 | `GET …/harvest/status` | Harvest gate, runs, steps, recovery, and attention projection. |
 | `GET …/builds/{slug}/artifacts/{kind}?rev=N` | Raw bytes (`application/octet-stream`) plus content-disposition and `X-Autobuild-Artifact-*` metadata headers. Omit `rev` for latest. |
 | `GET …/tickets?state=S&label=L` | `{states,tickets,diagnostics,criteria,triageState,readyState}`. The two lifecycle names come from effective repository configuration (including provider fallback). With no `state`, `criteria.state` is `triageState`; repeated `label` parameters narrow that state with AND filters. An explicit `state` selects that exact backend workflow state. |
+| `GET …/tickets/states` | Full state metadata `{name,tickets,about?}[]`, including empty states (`tickets.states` in MCP). |
 | `GET …/tickets/{id}` | `{ticket,blockers,build}`. Blockers include native `exists`/`resolved` status; `build` prefers an active matching repository build, otherwise the most recently updated one. |
 
 For artifact reads, an absent `rev` selects the latest revision. A supplied value
@@ -66,7 +98,11 @@ supplied forms return `400 validation`.
 Dashboard reads use the latest durable, run-correlated `effectiveConfig`
 repository artifact. Missing, corrupt, or invalid configuration returns a typed
 `409 effective-config-unavailable`; the service never guesses from a checkout.
-Clients poll these reads; streaming is not provided. `triageState`, `readyState`,
+Clients poll these reads — the operator HTTP API exposes no push or long-poll
+event transport. Streaming is provided as a CLI read surface: `ab watch`
+streams build and repository events by polling the same event logs client-side
+(the store protocol's `GET /builds/{slug}/events` and `GET /repos/{repo}/events`
+reads), not as a transport on this API. `triageState`, `readyState`,
 and every entry in `states` are backend state names and must be sent back verbatim
 when used with the move control.
 
@@ -84,6 +120,7 @@ JSON bodies are strict: unknown fields are rejected.
 | `POST …/settings/auto-merge-default/toggle` | Empty body. |
 | `POST …/bulk-control` | `{"action":"pause"\|"resume"}`. The hold fact, intake fact, then eligible build events are written in that order. |
 | `POST …/harvest/control` | `{"action":"toggle-gate"}` or `{"action":"run","run":"…"}`. A run action is bound to that concrete projected run. |
+| `POST …/tickets/states` | `{name,about?}` → `{state,created}`; requires attributed operator identity (`tickets.state.create` in MCP). Hosted duplicate names are refused case-insensitively. |
 | `POST …/tickets` | `{"title":"…","body":"…","labels"?:[],"state"?:"…","blockedBy"?:[]}`; omitted state preserves the backend default. |
 | `PATCH …/tickets/{id}` | Any nonempty subset of `title`, `body`, and complete-replacement `labels`. Body bytes are not normalized. |
 | `POST …/tickets/{id}/move` | `{"state":"backend state name"}`. |
@@ -105,12 +142,25 @@ The retry object is deliberately bare: adding `text` is a `400 validation`
 rather than silently changing the resolution to guidance. A revision object may
 also carry `ceiling` only to receive the shared `incompatible-answer-options`
 refusal; a ceiling and spec revision cannot be performed together.
-
 The hosted service has no ticket-provider credentials. For ticket-origin
 revision, a trusted caller fetches the current ticket body and supplies it; the
 build must still have a recorded ticket. Revision conformance, lazy retry,
 artifact metadata, event ordering, and refusal rules are the same as the CLI.
 
+## The registry's protocol face: `POST …/tools/{tool}`
+
+One generic route executes any entry of the agent tool registry (the same
+closed table `ab mcp` serves over stdio and the hosted `/mcp` endpoint serves
+over Streamable HTTP): the body is the tool's validated input — `repo`
+included and required to equal the URL's repository — and the response is the
+registry result verbatim. The verified operator token supplies the acting
+identity and, when minted with one, the `via` attribution marker; the body
+never does. Failures keep the shared `{kind,error,code?,progress?}` shape:
+validation is `400`, auth `403`, not-found `404`, conflict and refusal `409`,
+internal `500`. The route adds no authority of its own — it is the registry
+behind the token check — so a tool available here is exactly the tool table,
+and the table's contract suite is the single gate.
+
 ### Success results
 
 Build control returns one of:
@@ -157,8 +207,87 @@ headers with a server-minted token that expires after 30 seconds and carries
 the normalized signed-in email. Consequently every durable control event has
 the browser user's human actor while no token or signing secret reaches client
 code. Responses are private/no-store; a 401 sends the application back to sign
-in. Browser clients poll the visible dashboard every two seconds; live transcript
-streaming is not provided. Delegated bearer tokens remain server-side.
+in. Browser clients poll the visible dashboard every two seconds; the browser
+surface offers no streaming of its own — live transcript streaming remains
+absent here, and the streaming read surface is the CLI's `ab watch`, which
+polls the store's event reads client-side. Delegated bearer tokens remain
+server-side.
+
+The API does not expose phase-session commands, runner startup, a push or
+long-poll streaming transport, or a generic event-append operation; event
+streaming is composed client-side by `ab watch`, which polls the store's
+event reads.
+
+
+Dispatcher liveness is also visible through `ab repository status --json`:
+`dispatcher.holder` identifies the unexpired repository lease owner, independently
+of `latestRun`. Heartbeat age measures attributable renewals; tick age measures
+durable progress. Missing historical evidence is null. The liveness query uses
+bounded repository facts first, with a full-history fallback when a later
+invocation hides the holder start or the latest stop. Other state reads retain
+their bounded semantics.
+
+Repository-following `ab watch` additionally emits a read-only `dispatcher.lost`
+observation when an observed lease expires without a matching stop. JSON carries
+`observation` instead of `event`, with run, observedAt, leaseExpiresAt and available
+identity, plus the usual repo/build/state/cursor fields. It invents no durable
+sequence or actor. Retain the cursor to avoid repeat reports across invocations.
+No lease alone is not evidence of death. SIGINT, SIGHUP and SIGTERM drain dispatch,
+record the first signal in the stop fact, and release its lease before exit.
+
+### CLI attention monitoring
+
+The default watch reports actionable conditions only:
+
+- Build `escalation.raised`, or `build.merge-decision`: a finalized open PR
+  with auto-merge off or a current actionable merge-gate deferral. Armed consent
+  awaiting application is silent. One merge decision is reported per build/PR.
+- Repository `harvest.escalated`, `harvest.recovery-exhausted`,
+  `dispatcher.config-rejected`, `dispatcher.config-reloaded` with nonempty
+  `restartRequired`, abnormal `dispatcher.run-stopped`, and `dispatcher.lost`.
+- `dispatcher.ticket-source-persistent`: degradation past its advertised
+  reset time, once a tick started at or after reset has completed or failed
+  with the episode still open; crossing reset alone is silent. Without a reset,
+  the deadline is 15 minutes after onset. Repeated evidence never postpones
+  the deadline; recovery ends the episode.
+- `dispatcher.tick-failure-persistent`: continuously failing completed ticks
+  for five minutes in one run. A successful tick, new run, or matching stop
+  ends the episode. Source grace and cooldown-driven failures do not start
+  this clock; after grace, the first qualifying failure starts a new five-minute
+  interval. Each persistence episode is reported once.
+
+Repository conditions are included with no slugs or with `--repository`.
+Routine outcomes and self-healing failures are silent. Repeatable
+`--event <glob>` replaces the default and selects exactly matching catalog
+events (plus the existing `dispatcher.lost` observation); use explicit globs
+to opt into failures, finalize, merge, or completion events.
+
+Derived records use `observation` instead of `event`, without inventing a
+durable sequence or actor. Merge observations carry `type`, `pr`, `reason`,
+and `observedAt`, plus the build slug and normal reduced state. Persistence
+observations carry source/cause/message/resetAt when advertised (or
+run/firstFailure/error), `episodeSeq`, and `observedAt`; repository records
+have `repo` and null build/state. Source observations also report
+`dependencyLimited`.
+
+Every record carries a cursor, including timer-only records. Resuming suppresses
+delivered merge decisions and persistence episodes even when stream positions
+did not advance. Old v1 cursors remain valid: historical eligible merge
+decisions are treated as consumed; active overdue repository episodes may
+report because old watches had no persistence notification. Fresh attachment
+silently baselines historical direct events and merge decisions, but retains
+active repository timers. Reconcile existing conditions through status after
+arming the watch. Named watches still end when every named build is terminal;
+learn their outcomes from status reconciliation at exit.
+
+`ab wait --for attention` is build-only and uses the same build conditions:
+an open escalation or a merge decision. Existing conditions return immediately,
+even with `--since`; live and backlog matches ignore routine outcomes and
+self-healing failures. A merge match uses the watch observation with
+`condition: "attention"`. Explicit `--event` globs remain event-only.
+Watch and wait preserve each other's cursor notification metadata.
 
-The API does not expose phase-session commands, runner startup, live streaming,
-or a generic event-append operation.
+Hosted ticket tools resolve independent project ticket policy before legacy uploaded
+configuration. Queue, detail, state discovery and mutations work before any build
+or dispatcher run; detail reports a null matching build. Ticket policy publication
+never creates synthetic build or repository history.

package/skills/guide/references/plugin-authoring.md

@@ -40,7 +40,7 @@ should declare an API range containing `^1.5.0`.
 
 Plugin API 1.7 extends the workspace-provider factory context with the
 host-derived seams a store-requiring remote provider needs. Workspace-provider
-factories additionally receive `storeRef` and `storeToken` (guaranteed present
+factories additionally receive `storeRef` and `delegateCredential` (guaranteed present
 when the registration declares `capabilities.storeRequirements`),
 `runtimeReferences` (the host's effective runtime routes; absent at call sites
 that reference no runtimes), and the checkout-less `origin` and
@@ -125,7 +125,7 @@ Every module must default-export one strict `AutobuildPluginManifest`:
   `[tickets]` fields, workspace providers receive `[workspace.config]`, and
   runtime and forge factories currently receive an empty `config` object.
   Workspace providers additionally receive the host-derived seams (API 1.7):
-  `storeRef` and `storeToken` — guaranteed strings when the registration
+  `storeRef` and `delegateCredential` — guaranteed URL and exchange callback when the registration
   declares `capabilities.storeRequirements` — plus `runtimeReferences`,
   `origin`, and `remoteBranchHead`. Each seam is optional and absent when the
   host call site supplies no such value; absent `origin`/`remoteBranchHead`
@@ -369,3 +369,11 @@ policy says otherwise.
 Official npm references: [`package.json` fields](https://docs.npmjs.com/cli/v11/configuring-npm/package-json),
 [`npm pack`](https://docs.npmjs.com/cli/v11/commands/npm-pack), and
 [`npm publish`](https://docs.npmjs.com/cli/v11/commands/npm-publish).
+
+Remote workspace factories must use `delegateCredential(storeRef, undefined,
+target)` to obtain per-resource grants before provisioning or launching guests.
+The callback keeps parent authority in host composition. `storeToken` is retired
+and is never supplied; factory environments also exclude `AB_TOKEN`. Launch
+credentials travel through the separate transient execution-auth argument, never
+through serialized execution identity. Existing plugins that forwarded
+`storeToken` must migrate to this callback and fail closed if it is unavailable.