Files
archie/docs/prds/store.md
T
sam 486d5574b3 docs(prds): fit harnesses, steps and the store inside the org boundary and profile model
A harness is an agent profile whose environment is a Kit composition, so
image profiles and existing workflows are unchanged and only Kit runs take
the egress path; the relay replaces the claim that containers reach the
proxy directly. Credentials, step records, store installs and reviews are
org-scoped under the run credential and the Authorizer, and workflow calls
are linked across executions rather than nested.
2026-09-26 02:41:02 +10:00

160 lines
7.3 KiB
Markdown

# Store
**Status:** Approved
**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes
`docs/prds/extensions-center.md`, whose installed-inventory states are
adopted below.
**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),
`docs/prds/pr-review-agent.md` (the first package).
## Decision
Operators get capabilities from a store: browse, install, update and remove
packages from the dashboard, with no config file editing. A package is an
OCI image in a registry. A store catalogue is a list of package references.
Installing pins a digest. Every package declares the authority it needs, and
an update that asks for more stops for the operator's approval.
## Packages
Two kinds, both ordinary OCI images:
- **Harness Kits.** Kit v3 images, resolved as
`docs/prds/external-agent-harness.md` decides. Their authority is their
Kit permission surface.
- **Archie packages.** An image whose manifest annotation
`dev.archie.package.v1` carries the descriptor and whose single layer
carries files. A package contributes any of: workflow definitions,
prompts, skills, MCP server definitions, and default settings for them.
Archie packages are declarative. They carry no Go, Yaegi or script code that
archie executes on the host. Anything that runs code ships as a Kit and runs
in a sandbox. An archie package that references a Kit names it by digest,
and installing the package installs the Kit.
The descriptor declares: display name, description, version, the families
it contributes, the packages it requires, and its authority.
## Authority
A package's authority is the set of grants it needs to work:
- credential services (from its Kits and MCP servers);
- egress hosts (from its Kits);
- forge permissions its workflows use: read, comment, review, push, open
pull request;
- triggers it registers: watched-repository events, schedules;
- tools it enables for agents.
Install shows this list and records the operator's acceptance against the
digest. An update whose authority is equal or narrower applies under the
package's update policy. An update whose authority is wider waits for
approval, showing only what widened. Nothing a package does at runtime can
exceed its accepted authority: archie checks forge actions, triggers and
tool grants against it, and the egress proxy enforces the Kit's grants.
## Catalogues
A catalogue is an OCI artifact listing package references with digests,
signed by the catalogue's key. Archie ships with the default catalogue and
its public key configured. An operator can add catalogues, for example a
private registry, by reference and public key. A catalogue without a key is
refused unless the operator marks it unsigned, which the dashboard shows on
every package it supplies.
Install and update verify the catalogue signature and the package digest.
Archie never installs a tag it has not resolved to a digest through a
verified catalogue.
## Organisations
`docs/prds/orgs-and-access.md` is the boundary, and the store follows its
split between the instance and each org.
- **Instance.** Catalogues and their keys are instance configuration, set by
instance admins. Every org browses the same catalogues.
- **Org.** Installing, updating, removing, accepting authority and setting the
update policy are org actions. An installed package, its pinned digest and
its accepted authority belong to one org. Two orgs can run different
versions of one package.
- **Contributions** become org resources: workflows are org workflows,
profiles are org profiles, and credential bindings name org secrets. A
workspace uses them only once the org grants them to it.
- **Authority is an upper bound, not a grant.** Accepting a package's
authority permits the package to ask; the workflow's identity must still
hold each grant. A package never creates, grants to or widens an identity.
- Install and authority acceptance are the `create` and `approve` actions on
the package, decided by the Authorizer. Org approval policy decides who may
accept, and no member accepts authority they asked for.
## Install, update, remove
- Installed packages, their pinned digests, accepted authority and update
policy are org resources in the State Store. They apply without a restart.
- **Update policy** per package: `manual` (default) or `auto`. `auto` applies
non-widening updates when the catalogue lists them; widening updates always
wait.
- **Setup.** A package whose authority includes a credential with no binding
installs as `needs_setup`, and links to the binding form or the harness
setup terminal. Its triggers do not fire until setup completes.
- **Remove** stops its triggers, removes its contributions, and leaves any
credential bindings for the operator to delete. A package another
installed package requires cannot be removed first.
- Rolling back reinstalls the previously accepted digest.
## Inventory
The installed view lists every package and every bundled capability with
one state, computed on read and never persisted:
| State | Meaning |
| ------------- | -------------------------------------------------------- |
| `available` | in a catalogue or bundled, not installed |
| `needs_setup` | installed, waiting for a credential binding |
| `active` | installed and running |
| `degraded` | active, and its family's health check reports a fault |
| `pending` | an update waiting for approval of widened authority |
Core capabilities (identity, workflow engine, State Store) are listed and
cannot be removed.
## Out of scope
- Payment, licensing and paid packages.
- Publishing from the dashboard. Packages are built and pushed with standard
image tooling.
- Ratings and reviews.
## Plan
1. Archie package descriptor and its validation, including declarative-only
content.
2. Installed-package resources, digest pinning, install and remove for
archie packages from a local registry.
3. Authority model: extraction from packages and Kits, acceptance records,
runtime checks for forge actions, triggers and tools.
4. Signed catalogues and verification; the default catalogue.
5. Updates: widening detection, approval, `auto` policy, rollback.
6. Kit packages through the same flow; `needs_setup`.
7. Inventory states across packages and bundled capabilities.
8. The PR review agent published as the first package.
## Verification
- Installing the PR review package from the default catalogue on a fresh
instance, then binding a credential, reviews a PR without editing
configuration.
- An update adding a forge permission or egress host waits as `pending`,
showing only the added grant, and does not apply under `auto`.
- A workflow from a package that tries a forge action outside its accepted
authority fails the step.
- A tampered package digest or an unsigned catalogue refuses to install.
- A package containing executable host code is rejected at validation.
- Rolling back restores the prior digest and its accepted authority.
- A package installed in org A is invisible to org B, and org B's workflows
cannot select its profiles.
- A package whose workflow needs a forge permission the running identity was
never granted fails that step, even though the org accepted the package's
authority.
- A member cannot accept widened authority on an update they requested.