234 lines
10 KiB
Markdown
234 lines
10 KiB
Markdown
# Event automation: identified events, typed parameters, purpose-built agents
|
|
|
|
**Status:** Approved
|
|
**Date:** 2026-09-23
|
|
**Parent:** epic `archie-core-t2db`
|
|
|
|
## Why this exists
|
|
|
|
Archie is an event-driven automation system. Any system that can send a
|
|
webhook (a forge, an error tracker, a firewall, a monitoring stack) should be
|
|
able to start an agent built for that job. The shape this replaces cannot:
|
|
|
|
- A binding matches only the URL segment an event was posted to, and a source
|
|
may have one binding. Two kinds of event from one sender cannot go to
|
|
different workflows.
|
|
- A mapping is a list of JSON paths written against one example payload.
|
|
Nothing recognises what kind of event arrived.
|
|
- Mapped values reach the task only as `key=value` lines in its body text.
|
|
- Every task needs a repository and runs in a git worktree.
|
|
- Every agent runs the same image with the same forwarded keys.
|
|
|
|
## The model
|
|
|
|
```
|
|
source ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile
|
|
(identified) (params) (+ filter, (inputs, (image, tools)
|
|
repo) profile)
|
|
```
|
|
|
|
### Sources
|
|
|
|
A source is the endpoint one sender posts to. Its path is a generated UUIDv7
|
|
(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The
|
|
operator may replace it with a custom path for a sender that cannot use that
|
|
format; a custom path must be unique and URL-safe, and is refused otherwise.
|
|
A source owns the signing setting:
|
|
|
|
- **Signed** (default). Archie generates the secret. Only events with a valid
|
|
`X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.
|
|
- **Unsigned.** The operator turns signing off for a sender that cannot sign.
|
|
The source and every event from it are marked unsigned in the inspector,
|
|
the binding list and the task timeline. Turning signing off needs the same
|
|
approval as arming a binding.
|
|
|
|
Unauthenticated events on a signed source are captured and never
|
|
dispatched.
|
|
|
|
### Event types
|
|
|
|
An event type is a named kind of event from one source, such as
|
|
`github / pull_request.opened` or `firewall / blocked_connection`. It is
|
|
defined by a match rule:
|
|
|
|
- header equality (`X-GitHub-Event = pull_request`), and
|
|
- payload conditions (`action = "opened"`, or a path being present).
|
|
|
|
An event type can be created two ways:
|
|
|
|
- **From an example payload.** The operator pastes a payload (and optionally
|
|
its headers), and archie converts it to the type's schema. No event needs to
|
|
have arrived.
|
|
- **From captures.** Archie proposes types from what has arrived, as below.
|
|
|
|
Either way, archie infers the schema, not the operator:
|
|
|
|
- Each capture gets a structural signature: the set of JSON paths with their
|
|
value types, plus the headers that look like discriminators (`*-Event`,
|
|
`*-Type`, `Content-Type`).
|
|
- Captures from one source that share a signature are grouped. The inspector
|
|
shows each group as a proposed event type, with its inferred schema, its
|
|
number of events and a sample, until the operator names it or dismisses it.
|
|
- The proposed match rule is the set of discriminators that separates the
|
|
group from its siblings. The operator can edit it before saving.
|
|
- A capture that matches no named type is shown as unidentified. It is never
|
|
dispatched.
|
|
|
|
Two event types on one source whose rules can match the same event are
|
|
refused when the second one is saved.
|
|
|
|
### Mappings
|
|
|
|
A mapping belongs to an event type. It maps payload paths to named, typed
|
|
parameters, and it is checked against the type's inferred schema, so a path
|
|
the type does not have is refused when the mapping is saved. Any number of
|
|
bindings may reuse one mapping.
|
|
|
|
Each mapping shows how many events it has matched, with the time of the most
|
|
recent, so an operator can see which mappings are live and which have never
|
|
fired.
|
|
|
|
### Workflows declare inputs
|
|
|
|
A workflow definition declares its inputs:
|
|
|
|
```yaml
|
|
id: firewall-investigate
|
|
inputs:
|
|
src_ip: { type: string, required: true }
|
|
severity: { type: string }
|
|
repository: none # none | optional | required
|
|
profile: network-investigator
|
|
steps: ...
|
|
```
|
|
|
|
- `repository: none` runs the agent in a scratch workspace with no clone.
|
|
`required`, the default, gives the agent a worktree of the task's
|
|
repository. `optional` gives it a worktree when the binding names a
|
|
repository and a scratch workspace when it does not.
|
|
- A workflow whose `repository` is not `required` may use only steps that need
|
|
no repository. `agent.run` is one: it runs one agent mission and finishes
|
|
the task as done, with no pull request.
|
|
- The declared inputs reach the agent as structured data in the task brief
|
|
and in the agent's context. They are not body text.
|
|
- A workflow may declare `outputs`, the structured result it returns when it
|
|
finishes.
|
|
|
|
### Workflows call workflows
|
|
|
|
A workflow step can call another workflow. The call passes the callee's
|
|
inputs, and the callee runs as its own run with its own agent profile, so one
|
|
event can start an investigator that then calls a containment workflow:
|
|
|
|
```yaml
|
|
steps:
|
|
- type: workflow.call
|
|
workflow: firewall-contain
|
|
inputs: { src_ip: inputs.src_ip }
|
|
wait: true # false starts the callee and continues
|
|
```
|
|
|
|
- With `wait: true` the caller receives the callee's outputs and fails if the
|
|
callee fails. With `wait: false` the caller continues and the callee's
|
|
outcome is reported on its own run.
|
|
- A call's inputs are checked against the callee's declared inputs when the
|
|
calling workflow is saved.
|
|
- A workflow that calls itself, directly or through other workflows, is
|
|
refused when it is saved. Calls are limited to a fixed depth at run time.
|
|
- A callee must be enabled for the caller's org.
|
|
|
|
### Bindings
|
|
|
|
A binding connects an event type to one workflow:
|
|
|
|
- an optional filter on mapped parameters (`severity in ["high", "critical"]`),
|
|
written in the CEL the playbook engine already uses;
|
|
- an assignment of workflow inputs from mapped parameters or constants,
|
|
checked against the workflow's declared inputs when the binding is saved;
|
|
- a repository, when the workflow's `repository` is not `none`: either fixed
|
|
(`acme/api`) or taken from a parameter (the GitHub webhook's
|
|
`repository.full_name`). A repository taken from a parameter must be a
|
|
configured one, or the event does not dispatch.
|
|
|
|
Any number of bindings may use one event type. Approval and re-approval after
|
|
an edit are unchanged. A binding whose workflow input types no longer match is
|
|
refused at dispatch and reported on the binding.
|
|
|
|
### Agent profiles
|
|
|
|
A profile is a named execution environment that a workflow selects:
|
|
|
|
- the container image;
|
|
- an allowlist over the tools Archie adds to the agent: MCP servers,
|
|
repository scripts and skill plugins. The agent's own file tools are always
|
|
present;
|
|
- the secrets injected into it, by reference to the secret store, never
|
|
inline (superseded by `docs/prds/orgs-and-access.md`: secrets are granted to
|
|
identities, and a profile holds no secrets);
|
|
- its network access and forge access (superseded by
|
|
`docs/prds/orgs-and-access.md`: permissions are granted to identities).
|
|
|
|
Profiles are configured under `[containers.profiles.<name>]`. The global
|
|
`[containers].image` becomes the default profile, so existing workflows are
|
|
unchanged. A task whose workflow names an unconfigured profile is parked for
|
|
an operator. A secret or permission is granted to an identity, never to a binding, so an
|
|
event can never widen what an agent can do (`docs/prds/orgs-and-access.md`).
|
|
|
|
### Workflows belong to orgs
|
|
|
|
Archie ships a default workflow catalogue that every org can use. An org can
|
|
add its own workflows, and can enable or disable any workflow, default or its
|
|
own, for itself. A binding can target only a workflow enabled for its org, and
|
|
disabling a workflow stops its bindings dispatching and marks them on the
|
|
binding list.
|
|
|
|
## Delivery order
|
|
|
|
1. Event types: structural signatures, grouping, naming, match rules, and the
|
|
inspector view of proposed and unidentified events.
|
|
2. Mappings per event type, and multiple bindings per source.
|
|
3. Workflow inputs, structured parameters in the task brief, and
|
|
`repository: none | optional | required`.
|
|
4. Agent profiles with image and tools.
|
|
5. Signing as a source setting, with the unsigned option; UUIDv7 source paths
|
|
with a custom-path override.
|
|
6. Workflows calling workflows, with declared outputs.
|
|
7. Org-scoped workflow catalogue, once orgs exist.
|
|
|
|
Each step ships usable on its own. Step 3 is the first where an event that has
|
|
nothing to do with a repository can run a workflow.
|
|
|
|
## Out of scope
|
|
|
|
- How forge-issue playbook triggers (`internal/domain/eda/playbook`) relate to
|
|
event types. They stay as they are until event types exist.
|
|
- Built-in catalogues of event types for known senders.
|
|
- Orgs themselves: membership, access, and how sources and bindings belong to
|
|
one. This design needs only an org to own workflows and their enabled state.
|
|
- Running an agent outside a container.
|
|
|
|
## Verification
|
|
|
|
- Two GitHub webhooks with different `X-GitHub-Event` headers posted to one
|
|
source are grouped into two proposed event types, and a firewall payload
|
|
with a different shape is grouped separately.
|
|
- A capture matching no named type is shown as unidentified and starts
|
|
nothing.
|
|
- A firewall event runs a `repository: none` workflow with its mapped inputs
|
|
readable by the agent as structured data, and no clone is made.
|
|
- A GitHub `pull_request.opened` event runs a PR review workflow against the
|
|
repository named in the payload.
|
|
- An event type created from a pasted payload has that payload's schema, and a
|
|
later matching event is identified as it.
|
|
- A new source gets a UUIDv7 path; a custom path that is already taken is
|
|
refused.
|
|
- A workflow that calls another with `wait: true` receives its outputs; one
|
|
that calls itself through another workflow is refused when saved.
|
|
- A mapping's matched-event count rises by one for each event it resolves.
|
|
- A workflow disabled for an org cannot be targeted, and its existing bindings
|
|
stop dispatching.
|
|
- A binding whose filter excludes an event does not dispatch it.
|
|
- An agent receives only the secrets its identity is granted.
|
|
- An unsigned event on a signed source is captured and not dispatched. An
|
|
event on an unsigned source is dispatched and marked unsigned.
|