coreci-executor: add SPEC v0.1 (per-agent instantiation; naming convention §4)
This commit is contained in:
@@ -0,0 +1,143 @@
|
||||
# coreci-executor — Tool SPEC v0.1
|
||||
|
||||
> **Status:** v0.1 (proposed, 2026-09-26). Canonical definition lives at
|
||||
> `coreci/executor-config/tools/coreci-executor/SPEC.md`. Agents re-fetch
|
||||
> from this path at onboarding and after any tool-loss event.
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
A capability broker that routes agent requests to CoreCI infrastructure
|
||||
(Gitea, Proxmox, OpenWebUI, etc.) through a single governed choke point.
|
||||
Replaces unreliable globally-scoped tool bindings with **per-agent
|
||||
instances** bound from this canonical source.
|
||||
|
||||
## 2. Endpoints
|
||||
|
||||
| Endpoint | Method | Purpose |
|
||||
| ------------------------------ | ------ | ------------------------------------------ |
|
||||
| `/health` | GET | Liveness probe (no auth) |
|
||||
| `/submit_request` | POST | Submit a credential-free pack |
|
||||
| `/request_status?request_id=…` | GET | Poll job status (Bearer) |
|
||||
| `/audit` | GET | Read durable audit trail (Bearer, scoped) |
|
||||
|
||||
## 3. Auth envelope schema
|
||||
|
||||
```json
|
||||
{
|
||||
"agent": "coreci-<role>",
|
||||
"kind": "bash_pack",
|
||||
"targets": ["<owner>/<repo>"],
|
||||
"content": "<credential-free bash>",
|
||||
"credentials": {
|
||||
"<name>": { "user": "<from agent KB>", "secret": "<from agent KB>" }
|
||||
},
|
||||
"justification": "<what + why>"
|
||||
}
|
||||
```
|
||||
|
||||
Credentials are injected as env vars `CRED_<NAME>_USER` /
|
||||
`CRED_<NAME>_SECRET` inside the job. They **never** appear in pack
|
||||
content (fail-closed regex check at submission).
|
||||
|
||||
## 4. Naming convention (mandatory)
|
||||
|
||||
**`agent` field = Gitea username = KB username = allowlist key.**
|
||||
|
||||
Format: `coreci-<role>`. Examples currently in the allowlist:
|
||||
|
||||
- `coreci-coo` → `coreci-coo/home`
|
||||
- `coreci-cairo` → `coreci-cairo/home`
|
||||
- `coreci-cpo` → `coreci-cpo/home`
|
||||
- `coreci-executor` → `coreci/executor-config`
|
||||
|
||||
Rationale: one canonical identifier across audit, allowlist, KB, and
|
||||
submission envelope. Eliminates the ambiguity class where short-form
|
||||
agent names (`coo`) drifted from KB usernames (`coreci-coo`).
|
||||
|
||||
Audit history is durable and preserves any pre-canonicalization rows
|
||||
unchanged. All new submissions must use the canonical form.
|
||||
|
||||
## 5. Classification
|
||||
|
||||
| Class | When | Behavior |
|
||||
| ----------------- | ----------------------------------------------------------------- | ------------------------- |
|
||||
| `AUTO_RUN` | Agent's own home repo is in `allowlist.yaml` `auto_run_targets` | Runs immediately |
|
||||
| `NEEDS_APPROVAL` | Cross-repo, scope-bound, first run on a target | Parks; CEO approves in UI |
|
||||
| `NEVER` | Provisioning jobs, agent-definition edits | Refused at submission |
|
||||
|
||||
## 6. Capabilities registry (current)
|
||||
|
||||
| Capability | Endpoints | Notes |
|
||||
| ----------- | -------------------------------------------------- | -------------------------------------- |
|
||||
| `gitea` | repo CRUD, contents, raw, branches, issues | SSO via vault |
|
||||
| `proxmox` | VM/cluster ops, snapshots, ISO mgmt | API-token auth |
|
||||
| `openwebui` | KB, notes, knowledge ops | session cookie from form-encoded signin |
|
||||
| `notify` | user-channel push (e.g. pushover/slack) | CEO notification path |
|
||||
|
||||
## 7. Audit contract
|
||||
|
||||
Every job leaves a row in `executor /audit`. Fields: `request_id`,
|
||||
`agent`, `decision`, `targets`, `submitter`, `submitter_ip`, `status`,
|
||||
`exit_code`, `started_at`, `finished_at`. Agents can **read but not
|
||||
delete**. Entries are durable across executor restarts.
|
||||
|
||||
## 8. Failure decoder
|
||||
|
||||
| Symptom | Meaning | Recovery |
|
||||
| ------------------------------------ | ------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `401` | bad/missing `EXECUTOR_API_KEY` | re-read KB |
|
||||
| `400 "credential-free only"` | literal credential in `content` | rebuild URL at runtime from split parts |
|
||||
| `"tool not found"` in agent palette | tool toggle off or rollback | re-fetch this SPEC, re-bind the tool |
|
||||
| Palette flicker mid-session | platform glitch | per-agent binding survives; reload the tool if missing |
|
||||
| `NEEDS_APPROVAL` parked | target not in own scope | notify CEO; await approval |
|
||||
| `/raw/branch/<ref>/<path>` returns 404 | only the bare `/raw/<path>` form works on this fork | use `/api/v1/repos/<o>/<r>/raw/<path>` (gitea-access skill note is wrong here) |
|
||||
|
||||
## 9. Per-agent instantiation (resilience core)
|
||||
|
||||
Each agent, at onboarding and after any tool-loss event:
|
||||
|
||||
1. Fetch this SPEC from `coreci/executor-config/tools/coreci-executor/SPEC.md`.
|
||||
2. Bind a local `coreci-executor` function/tool whose calls go to
|
||||
`/submit_request` (and poll `/request_status`).
|
||||
3. Handshake: `GET /health` → `200` = bound.
|
||||
4. Smoke test: submit a 1-line echo ping → receive `request_id`
|
||||
round-trip → log the `request_id` to `coreci-<agent>/home/ONBOARDING.md`.
|
||||
5. On tool loss mid-session: re-fetch the SPEC from the canonical repo,
|
||||
re-bind.
|
||||
|
||||
## 10. Onboarding (agent lifecycle)
|
||||
|
||||
A new agent must, before any rail submission:
|
||||
|
||||
- Have an allowlist entry in `coreci/executor-config/allowlist.yaml` for
|
||||
its home repo (CEO approval required to add).
|
||||
- Have a KB file set: `git.coreci.dev.txt`, `executor.coreci.dev.txt`,
|
||||
plus per-capability `<cap>.txt` for any scoped capability.
|
||||
- Complete the §9 instantiation steps.
|
||||
- Record `ONBOARDING.md` in `coreci-<agent>/home/` with: SPEC version
|
||||
fetched, handshake timestamp, smoke-test `request_id`, allowlist
|
||||
entry verified.
|
||||
|
||||
## 11. Mailbox convention (cross-reference)
|
||||
|
||||
Inter-agent messages (proposals, escalations, replies) live in each
|
||||
agent's home repo under `coreci-<agent>/home/mailbox/{outbox,inbox,INDEX.md}`.
|
||||
Mailbox writes are **always `AUTO_RUN`** because they target the
|
||||
sender's own home. See `coreci/company/standards/mailbox-convention.md`.
|
||||
|
||||
## 12. Resilience rules
|
||||
|
||||
- Per-agent binding survives global toggle flicker (this is the entire
|
||||
reason this tool exists).
|
||||
- This SPEC is canonical — never per-agent edited. Propose changes via
|
||||
PR to `coreci/executor-config`.
|
||||
- Audit log is append-only by agents; deletion requires a CEO-class
|
||||
request.
|
||||
- First-run on any new capability = `NEEDS_APPROVAL`.
|
||||
|
||||
## 13. Versioning
|
||||
|
||||
Semver. Breaking changes bump major. Agents must check `SPEC.md` version
|
||||
at re-bind and warn (non-blocking) if newer than what they were built
|
||||
against. Patches (clarifications, decoder rows) are silent.
|
||||
|
||||
Reference in New Issue
Block a user