Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
0fe3caa175 | ||
|
|
83d57ec6a2 | ||
|
|
e762f15844 | ||
|
|
1539fdc560 | ||
|
|
0e37a0f536 | ||
|
|
de32542c00 | ||
|
|
c1673e43fb | ||
|
|
a9233755c3 | ||
|
|
7ca81dc85a | ||
|
|
457da2e97d | ||
|
|
656d21520f | ||
|
|
92eabbed17 | ||
|
|
28acf2a8db | ||
|
|
c02852d87f | ||
|
|
ab86442156 | ||
|
|
bfb909a93a | ||
|
|
894fffc63b | ||
|
|
c94be59952 | ||
|
|
04d0495f12 | ||
|
|
9ccb6e2418 | ||
|
|
cd878f3c4d | ||
|
|
b650a8c156 | ||
|
|
4241429620 | ||
|
|
cc83c9aea2 | ||
|
|
1f0cb9f318 | ||
|
|
19520a63e5 | ||
|
|
ef203ce30a | ||
|
|
ff3f80e4c1 | ||
|
|
3da407e410 | ||
|
|
4e5b91d791 | ||
|
|
12b59a046d | ||
|
|
af1b9855ab | ||
|
|
3e878464f9 | ||
|
|
216be98652 | ||
|
|
f77baecb00 | ||
|
|
394c76b4cc | ||
|
|
b6defc5f31 | ||
|
|
5e1623f82f | ||
|
|
0544fa58fc | ||
|
|
057a4a8614 | ||
|
|
2a1ed36a26 | ||
|
|
605988e0a9 | ||
|
|
06e0a87a62 | ||
|
|
1d2fcec69e | ||
|
|
f5fbec6371 | ||
|
|
a9f441042e | ||
|
|
a8a04929af | ||
|
|
1e1f51af55 | ||
|
|
3c2b1f6654 | ||
|
|
e10d862f6a | ||
|
|
721968eeff | ||
|
|
446d94681b | ||
|
|
04dedde52c | ||
|
|
a4abafe0ad | ||
|
|
6bf24d73db | ||
|
|
20b4595a95 | ||
|
|
2341c6df36 | ||
|
|
eaabc254be | ||
|
|
68a17aed91 | ||
|
|
4f01b1604d | ||
|
|
bea1c69210 | ||
|
|
7f51f1c39e | ||
|
|
3c32b63066 | ||
|
|
829fc44cbc | ||
|
|
6b4049c9f5 | ||
|
|
934ba16c72 | ||
|
|
9f1dc44673 | ||
|
|
24258e215f | ||
|
|
793eec6e51 | ||
|
|
6785750729 | ||
|
|
72fa043f47 | ||
|
|
cc7397787b | ||
|
|
cef476aca3 | ||
|
|
f50444594f | ||
|
|
275d337032 | ||
|
|
b314470281 | ||
|
|
eb3add5b89 | ||
|
|
c126d5a24a | ||
|
|
1a3e79502d | ||
|
|
fcc6a7974e | ||
|
|
f4ed542b00 | ||
|
|
d06be5ca32 | ||
|
|
8d48a08b13 | ||
|
|
f6ee43bf55 | ||
|
|
268f99051a | ||
|
|
60a09e7def | ||
|
|
bf1dc2e33e | ||
|
|
f34714ea07 | ||
|
|
c2cfba1129 | ||
|
|
cea8bfee98 | ||
|
|
2f8107d5ca | ||
|
|
a67a142139 | ||
|
|
48416af5bc | ||
|
|
cca80ac2e8 | ||
|
|
52d267683b | ||
|
|
0b00682fac | ||
|
|
d1b8bff5ce | ||
|
|
ae8f0d42ef | ||
|
|
39b61a0340 | ||
|
|
06334ca3f9 | ||
|
|
f9e97b561f | ||
|
|
d7f6f502a8 | ||
|
|
54e36ff8b7 | ||
|
|
a1c69c5b28 | ||
|
|
bf68866dca | ||
|
|
87d52938b5 | ||
|
|
90a4189db4 | ||
|
|
013fcd0919 | ||
|
|
00209ebe87 | ||
|
|
96e54e963f | ||
|
|
2f05ed81b1 | ||
|
|
822f8b63d4 | ||
|
|
e0ec9b87e6 | ||
|
|
27bad9f1fa | ||
|
|
403ace1cef | ||
|
|
761a1271a4 | ||
|
|
c5a8942976 | ||
|
|
fb0424b729 | ||
|
|
52b8b6dcca | ||
|
|
d7178250ae | ||
|
|
9b282177e0 | ||
|
|
59273c9544 | ||
|
|
86e706dff7 | ||
|
|
ad5caf88a6 | ||
|
|
a7efb9bb00 | ||
|
|
34f47a4bd0 | ||
|
|
d60fcad18f | ||
|
|
8124c5af54 | ||
|
|
bfc8d4b1b7 | ||
|
|
0b8e9ae7f1 | ||
|
|
662a5ee336 | ||
|
|
8cbbdb20b5 | ||
|
|
cadbc6d1ca | ||
|
|
64128645c2 | ||
|
|
8155cc915a | ||
|
|
150dde5a7d | ||
|
|
a65f558d35 | ||
|
|
0dff130682 | ||
|
|
2d1d4ed632 | ||
|
|
67c5447ebc | ||
|
|
db6e8d321e | ||
|
|
cbeab6afd2 | ||
|
|
ed698fced1 | ||
|
|
081ee4a8ba | ||
|
|
5de07fac0e | ||
|
|
03335f49c1 | ||
|
|
d0d759d216 | ||
|
|
67ead19dd9 | ||
|
|
f7c646163b | ||
|
|
8d05f99526 | ||
|
|
625ead95b3 | ||
|
|
0acc922d9a | ||
|
|
595956cc75 | ||
|
|
929784667b | ||
|
|
d4e254b349 | ||
|
|
89c5f8e2ad | ||
|
|
2ffe924a44 | ||
|
|
c9f677f35b | ||
|
|
d60f024e74 | ||
|
|
1fa3acdbe9 | ||
|
|
d10b070a2e | ||
|
|
b93909c5aa | ||
|
|
42a4e2465d | ||
|
|
608403c1f9 | ||
|
|
e9e52c1f1f | ||
|
|
fc5d24c9f7 | ||
|
|
0b82f1c9a5 | ||
|
|
cdc3e83740 | ||
|
|
807d1dfc15 | ||
|
|
dbaa7284a3 | ||
|
|
5734e194c9 | ||
|
|
e16ba86b30 | ||
|
|
a2650eb5e9 | ||
|
|
1686fba12b | ||
|
|
519604405a | ||
|
|
2aea3ce0dc | ||
|
|
e7b21b9e5d | ||
|
|
e992d4256e | ||
|
|
41823ab336 | ||
|
|
fe2a3a7565 | ||
|
|
36981c2024 | ||
|
|
2bcfc19837 | ||
|
|
416df69b00 | ||
|
|
6c405333b7 | ||
|
|
3f0071e27b | ||
|
|
c07c04e45a | ||
|
|
a6ab4ef538 | ||
|
|
2604cd4cf4 | ||
|
|
cc6d606de4 | ||
|
|
de47bf2398 | ||
|
|
b8f5d0fc3d | ||
|
|
64cc0a5e29 | ||
|
|
d6f33ddd11 | ||
|
|
1e669b4a9f | ||
|
|
c3175c6939 | ||
|
|
7a38d9b79f | ||
|
|
b6357c8fd4 | ||
|
|
5f5494893c | ||
|
|
2c4d8af59e | ||
|
|
ce7478664a | ||
|
|
d1cba5c1ab | ||
|
|
a83b9afdce | ||
|
|
6f0e889bcf | ||
|
|
02328c1880 | ||
|
|
ea39923248 | ||
|
|
9c5eeba281 | ||
|
|
68e6dc0229 | ||
|
|
9219252bd4 | ||
|
|
3de20cdf9e | ||
|
|
e6a5a9d3d8 | ||
|
|
e9fe50b364 | ||
|
|
257a1fbf1f | ||
|
|
e720d3dcd8 | ||
|
|
ca3b53bccd | ||
|
|
3b04ac1196 | ||
|
|
9c053def88 | ||
|
|
4c3d4f94e4 | ||
|
|
fd6b568fa4 | ||
|
|
49c44b4a03 | ||
|
|
3827561ab0 | ||
|
|
0a05a30df0 | ||
|
|
4040e42d2b | ||
|
|
2a03741929 | ||
|
|
fb49ebd268 | ||
|
|
17465f240b | ||
|
|
78833a9c2c | ||
|
|
5ca398d0d9 | ||
|
|
d42731e5ae | ||
|
|
3186184964 | ||
|
|
0c14c4b892 | ||
|
|
82dc7641fe | ||
|
|
fcc9322237 | ||
|
|
62e9e9cb28 | ||
|
|
d6e24e1f81 | ||
|
|
643d2ed665 | ||
|
|
9b581a1326 | ||
|
|
93e96b8de5 | ||
|
|
4242d94676 | ||
|
|
1358c3d759 | ||
|
|
585df0f81e | ||
|
|
a8c8dfbd7d | ||
|
|
bc215e8daa | ||
|
|
0d042b72d9 | ||
|
|
5507ded2d5 | ||
|
|
7a54db0cc6 | ||
|
|
4067949ce8 | ||
|
|
92a9eca12c | ||
|
|
30211478c2 | ||
|
|
4e9b30d712 | ||
|
|
f7bfd78d5f | ||
|
|
4f62ce5dfc | ||
|
|
845b192a89 | ||
|
|
8ba0b90861 | ||
|
|
7b86dd6cfe | ||
|
|
419334dfa2 | ||
|
|
093e677ad8 | ||
|
|
235b9c1a87 | ||
|
|
37d913c5fd | ||
|
|
8274ecbc53 | ||
|
|
2657b18be7 | ||
|
|
8c7ee60270 | ||
|
|
54ade9713a | ||
|
|
e307efe77d | ||
|
|
6143d17caf | ||
|
|
b54aa00a24 | ||
|
|
08d5df9b11 | ||
|
|
5b6572bcea | ||
|
|
606e87d11c | ||
|
|
0b24dc8ff0 | ||
|
|
e7611903a8 | ||
|
|
19e110e68c | ||
|
|
f747ff87d0 | ||
|
|
486d5574b3 | ||
|
|
71435c2bb6 | ||
|
|
9b16c0fd64 | ||
|
|
4fc06b5d7d | ||
|
|
78dd50d60b | ||
|
|
77a479e99a | ||
|
|
6bc7a85404 | ||
|
|
a7edc0a5cd | ||
|
|
1cf2742f54 | ||
|
|
0f6cb5b8a6 | ||
|
|
fca30d6445 | ||
|
|
a98ca2c8e9 | ||
|
|
22d36fef75 | ||
|
|
f74827795d | ||
|
|
ca8d189f96 | ||
|
|
2ee7043daf | ||
|
|
bbc39897de | ||
|
|
6ba43bbf21 | ||
|
|
ff77612bfd | ||
|
|
4426c0e685 | ||
|
|
9627bc411c | ||
|
|
01c98088ae | ||
|
|
86d4f62bfe | ||
|
|
6f2b55960f | ||
|
|
dce3c925c2 | ||
|
|
f7074d357f | ||
|
|
41e5ab32f9 | ||
|
|
e44b5398c7 | ||
|
|
6dcb04c7c0 | ||
|
|
d025d4c5be | ||
|
|
7555b80f31 | ||
|
|
ceed8b055a | ||
|
|
f3f3ca90f1 | ||
|
|
0bc27ea6da | ||
|
|
049bbf2a7d | ||
|
|
b5c98a0ccc | ||
|
|
c327f17c35 | ||
|
|
081e5bbfd9 | ||
|
|
b1a5954594 | ||
|
|
9639e7041e | ||
|
|
5b06f0b42a | ||
|
|
7d37750d40 | ||
|
|
7095a583b8 | ||
|
|
cb6b902f97 | ||
|
|
74aaf39be9 | ||
|
|
4690e822d8 | ||
|
|
90e222b8ec | ||
|
|
1bb52fe8c7 | ||
|
|
e3bf3b7584 | ||
|
|
6d8fe247a7 | ||
|
|
464ccf83fa | ||
|
|
067d365f84 | ||
|
|
e12aeb8493 | ||
|
|
7577ae66a7 | ||
|
|
8fea8e8686 | ||
|
|
49d7527f1c | ||
|
|
81862273c0 | ||
|
|
07d5a7a3cc | ||
|
|
bb3e7b76e8 | ||
|
|
cc33dfea54 | ||
|
|
73e718dea4 | ||
|
|
d01a3c4647 | ||
|
|
55ad93e8e3 | ||
|
|
459bbcd5fc | ||
|
|
a4d98786a1 | ||
|
|
aa24551d98 | ||
|
|
cacf25039e | ||
|
|
35dd7489dd | ||
|
|
be1b3aa6a1 | ||
|
|
065606b2a5 |
No files matched your search
@@ -66,6 +66,14 @@ packages the moment it merged; formatting and lint drifted the same way, and onl
|
||||
the repository gate saw it. Both failures are paid for inside the lane when the
|
||||
gate runs the build and the linter, and at merge when it does not.
|
||||
|
||||
Gate the **candidate** before `main` moves. Check the merge candidate out
|
||||
detached — or gate the lane branch — and advance the ref only on a green result:
|
||||
gating after a fast-forward lands the failure on the branch of record and leaves
|
||||
only fix-forward or reset as exits. The lane brief must name the linter as well,
|
||||
`golangci-lint run ./<package>/...` beside the scoped tests, because a scoped
|
||||
test run cannot see a complexity or style limit and `task check` is where that
|
||||
failure otherwise surfaces — once it is already merged.
|
||||
|
||||
A copy of the script under `.pi/control-plane-run/` is that run's disposable
|
||||
state and may lag the skill's version. The skill's copy is the one to trust.
|
||||
|
||||
@@ -126,6 +134,36 @@ ln -sfn /work/apps/archie-core/.pi/agents /work/apps/cp-<lane>/.pi/agents
|
||||
`.pi/` is gitignored, so the worktree stays clean and the symlink cannot reach a
|
||||
commit. This costs an hour to rediscover.
|
||||
|
||||
## Peer sessions over intercom
|
||||
|
||||
A fleet here can also run as **sibling sessions** coordinated over `intercom` —
|
||||
a peer per lane — rather than pi-subagents children under one orchestrator.
|
||||
These facts are peer-specific, and each has cost a real run.
|
||||
|
||||
- **Name the channel in the brief.** A peer's knowledge of how to report lives in
|
||||
its context, not its configuration. Write "report to <peer> over intercom" as
|
||||
an instruction; a convention that is only assumed evaporates.
|
||||
- **A compaction erases conventions, not just facts.** A peer that compacts
|
||||
mid-task keeps its task state and loses its transport: it reverts to
|
||||
addressing its operator, and the coordinator reads that as idleness or death.
|
||||
**Peer silence is not evidence of either** — ask for a one-line ack over the
|
||||
channel before concluding anything. Re-priming restores the channel; the
|
||||
transport itself survives compaction intact.
|
||||
- **Match the task's shape to the session's window, not its strength.** A sweep
|
||||
over hundreds of items needs the largest window available; a bounded hard
|
||||
artifact (a PRD, a conformance review, a design decision) belongs in a smaller,
|
||||
reasoning-strong session. A wide task in a small window stalls the task — too
|
||||
wide is not the same as too hard, and it is the coordinator's assignment error,
|
||||
not the peer's failure.
|
||||
- **Checkpoint at ~70%, never compact mid-task.** A terse ledger sent to the
|
||||
coordinator before the window fills survives; one reconstructed afterwards
|
||||
loses exactly the identifiers — bead IDs, exact counts — that made it worth
|
||||
having. Instruct every long-running peer to report and stop there.
|
||||
- **One writer per resource.** Exactly one session writes the tracker. Two
|
||||
writers produce double-closes, contradictory verdicts, and counts nobody can
|
||||
reconcile. When a sweep changes hands, the successor re-derives them rather
|
||||
than inheriting the predecessor's ledger as fact.
|
||||
|
||||
## Traps worth carrying
|
||||
|
||||
- **`touch` does not invalidate a Task source.** Task hashes file _content_, so a
|
||||
@@ -136,11 +174,48 @@ commit. This costs an hour to rediscover.
|
||||
file checksum can invalidate: an empty commit moves the stamp while `task
|
||||
build` still reports the binary up to date, shipping the old value. Tracked as
|
||||
`archie-core-pdq2`.
|
||||
- **The lane gate cannot see `tools/` or the contract schema.** `tools/` is
|
||||
a separate Go module that reaches `internal/` through `docsgen`, and
|
||||
`docs/data/generated/contracts.json` is generated from wire types such as
|
||||
`agentexec.Request`. A lane that adds an import to a package `tools/`
|
||||
reaches, or changes a wire type, passes its own gate and fails
|
||||
`task check` on a missing `tools/go.sum` entry or a stale schema. Such a
|
||||
lane runs `go -C tools mod tidy` and `task docs:generate` and commits both.
|
||||
Adding or editing a page under `docs/` — a PRD included — changes
|
||||
`docs/data/generated/dev-docs.json`, which gains or loses a page: regenerate it
|
||||
and commit it in the same commit, or `docs:artifact:check` fails. That failure
|
||||
lands on `main`, not in the lane, if the ref moves first.
|
||||
- **Untracked files in the shared checkout are other sessions'.** prdlint
|
||||
scratch (`docs/prds/rules.jsonl`), editor state, and gate-written artifacts
|
||||
appear and vanish under a lane. Never chase, add, stage or commit them: a
|
||||
merge train's scope is its own lanes' files, and nothing else.
|
||||
|
||||
## codegraph answers symbol questions cheaply
|
||||
|
||||
The maintainer's `codegraph` MCP server indexes this repository. Prefer it to
|
||||
grep or whole-file reading for "who calls X", "is this dead", "what does this
|
||||
change touch": it enumerates call sites that a grep only summarises, and labels
|
||||
each caller's confidence so interface fan-out is not mistaken for direct calls.
|
||||
|
||||
- **`pr_impact <base> <head>`** lists changed symbols with per-symbol caller and
|
||||
test counts. Read `interface_dispatch` and the inferred tests alongside
|
||||
`test_count`: a method reached through an interface reports a low direct test
|
||||
count while many indirect tests reach it, and the compact line alone invites
|
||||
the wrong conclusion.
|
||||
- **It is a derived cache.** `scip-go` and tree-sitter rebuild it, and a query
|
||||
indexes the revisions it names, so a cold query is slow and losing the index
|
||||
costs a rebuild rather than data. `list_repositories` reports the indexed
|
||||
revision — compare it with the tree before trusting a default-revision answer.
|
||||
- **Stagger heavy queries.** Concurrent sessions share one instance, and
|
||||
**name-based** `symbol_context` is what locks: it returns `database is locked`
|
||||
or times out, while the same symbol **by id** returns immediately. Query
|
||||
serially and retry rather than assuming a hang.
|
||||
- **Report problems one line at a time** in
|
||||
`/work/apps/codegraph/data/feedback.jsonl` — one JSON object per line, keys
|
||||
`date`, `repo`, `task`, `tools`, `helped`, `missed`, `wrong`, `slow`. A raw
|
||||
newline inside a string makes the line invalid and breaks every reader; a
|
||||
multi-line entry corrupted that file once. Validate, append, never rewrite.
|
||||
|
||||
## Tracker conventions
|
||||
|
||||
`bd` is the only tracker; no markdown TODO lists, no local trackers.
|
||||
|
||||
@@ -107,7 +107,7 @@ Do not expose these helper flags as daemon settings.
|
||||
| Keys | Default, validation, and consumer | Status |
|
||||
| -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
|
||||
| `work_dir`, `state_dir` | Derive from `$XDG_DATA_HOME/archie`, else `$HOME/.local/share/archie`; explicit `~` paths are home-expanded. `state_dir` holds the embedded NATS store and endpoint file, task logs and the readiness disk target. | production-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. | partially-wired |
|
||||
| `skills_dir` | Empty falls back to `work_dir` for startup workflow registry. Also the skills store `kitrun.Launcher` mounts read-only at a Kit's `agent-skills@1` path, read live per launch; empty withholds the mount. | partially-wired |
|
||||
| `plugin_dir` | Empty disables daemon plugin loading; configured directory loaded in `internal/app/archied`. | production-wired |
|
||||
| `poll_interval` | Default `60s`; root poll loop uses it, identities may override only interval. | production-wired |
|
||||
| `label` | No default or validation; used for `dispatch.trigger = "label"` or `"either"`. | production-wired |
|
||||
@@ -120,6 +120,7 @@ Do not expose these helper flags as daemon settings.
|
||||
| `models.<role>` | Workflow stages read requested role then fall back to `builder`; triage judge falls back `triage` to `planner`. | production-wired |
|
||||
| `providers.<name>.class`, `api_key_env`, `base_url` | Builds ai-sdk catalogue. `base_url` rejects parse errors, userinfo, query, and fragment. | production-wired |
|
||||
| `budgets.max_steps`, `max_tokens`, `wall_clock`, `gate_max_failures` | No loader defaults; `Budgets` documents zero as disabling. | production-wired |
|
||||
| `review.precision_gate`, `review.approve_before_post` | 2026-10-02: one control-plane resource `review-settings` (`internal/app/controlplane/review_settings.go`), seeded from `[review]`; the stored document outranks the file, layers field-by-field into `cfg.Review` (`runtimeConfigFrom`), and is watched live (`archie/control_plane.go`). Reaches a run through `Daemon.configFor` → `ForTask` → `TaskContext.Cfg`; the dashboard writes it on the Review settings page. | production-wired |
|
||||
| `diff_cap_lines` | Zero replaced by `400` in `finalize`; `StageDiffCap` treats `<= 0` as disabled. TOML zero cannot disable; negative value does. | production-wired |
|
||||
| `web.listen` | Empty becomes `127.0.0.1:8484`; literal `off` disables. No authentication. | production-wired |
|
||||
| `notify.webhook` | Empty disables; feasibility workflow POSTs human-decision notifications when set. | production-wired |
|
||||
@@ -169,12 +170,16 @@ looking at before reporting one:
|
||||
|
||||
| Key | Effective behaviour |
|
||||
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
|
||||
| `image` | Required only when enabled. |
|
||||
| `max_concurrency` | Zero means no limit; used by general task dispatcher and container pool. |
|
||||
| `max_uptime` | Default `60m` only when enabled; caps container lifetime. |
|
||||
| `volume_ttl` | Default `72h` only when enabled; negative rejected. |
|
||||
| `pull_policy` | Default `missing` when enabled. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. |
|
||||
| `network` | Empty uses best-effort self-network detection. Repository overlay pins `archie-core_default`. |
|
||||
| `image` | Required at boot. Read by the container pool on every acquire (`containerLiveSettings` -> `Pool.current`, archie-core-zfb0.2), so a stored change applies without a restart. |
|
||||
| `max_concurrency` | Zero means no limit. Read by the pool per acquire and applied to the daemon's running task dispatcher on publish (`ResizeTaskDispatcher`). |
|
||||
| `max_uptime` | Default `60m` at boot; caps container lifetime. Read by the pool per acquire, so a stored change reaps the next container under the new cap. |
|
||||
| `volume_ttl` | Default `72h` only when enabled; negative rejected. Re-read per cleanup cycle. |
|
||||
| `pull_policy` | Default `missing` at boot. Pool code recognises `missing` and `always`; other strings silently skip pre-pull. Read by the pool per acquire. |
|
||||
| `registry_auth` | `SecretRef` (file-owned, `json:"-"`). Resolved at boot by `archied`'s `resolveRegistryAuth` and passed to `container.Config.RegistryAuth`; the pool base64url-encodes it into the `X-Registry-Auth` header (`internal/container/pool.go`'s `registryAuthHeader`). Zero ref = anonymous pull. Unresolvable/empty credential or an unencodable one warns and pulls anonymously rather than failing the pool. A half-named ref is refused by `configuration.validateContainers`. `container-runtime-policies` cannot carry a secret ref, so this stays boot-resolved and requires-restart, unlike `image`/`pull_policy`. |
|
||||
| `network` | Empty uses best-effort self-network detection at boot; the repository overlay pins `archie-core_default`. Read by the pool per acquire, falling back to the boot-resolved network when the live value is empty. |
|
||||
| `profiles` | Named agent execution environments (image or Kit); resolved per task dispatch (`ContainerConfig.Profile`). Own control-plane resource `agent-profiles` (`json:"-"` on the field so `container-runtime-policies` never carries it), `ApplyMode: live`. |
|
||||
| `credentials` | Maps a Kit `credential@1` service to a secret (`config.CredentialBinding`). Own control-plane resource `credential-bindings`, `ApplyMode: live`, `json:"-"` on the field. `kitrun.Launcher` reads it fresh from the live `config.Holder` on every `Launch`, never a value captured at boot -- see `internal/infrastructure/kitrun/launcher.go`'s `resolveCredentials`. A binding alone grants nothing; see `org`/`granted_credentials` below. |
|
||||
| `org` / `granted_credentials` (root and per-identity) | An identity's org and the `credentials` service names it may resolve. `daemon.runKitTask` reads both fresh per dispatch (`d.configFor(task)`) and passes them to `kitrun.Request`; `config.ContainerConfig.BoundCredentials` computes the declared (Kit) ∩ granted (identity) ∩ org-matched intersection -- neither declared nor granted widens the other. |
|
||||
|
||||
### Channel settings
|
||||
|
||||
@@ -190,6 +195,13 @@ looking at before reporting one:
|
||||
Telegram `/restart` re-runs same TOML overlay load, then replaces only gateway
|
||||
token and allowed-user list. Every other file setting is startup-only.
|
||||
|
||||
A stored `channel-settings` change is reconciled live by `archie-messaging`:
|
||||
on a new version it re-resolves the file, layers the store over it, and restarts
|
||||
only the channel whose transport settings changed (Telegram token/allowlist,
|
||||
email relay, webhook route/secret). `chat.email.listen_addr` and
|
||||
`chat.webhook_addr` are bound listen addresses, so those changes, and enabling
|
||||
or disabling a channel, are reported outstanding and take effect on restart.
|
||||
|
||||
## Treat multi-identity as partially wired
|
||||
|
||||
`finalize` requires each identity's `name`, `bot_user`, non-empty repos, forge
|
||||
@@ -213,8 +225,9 @@ Classify multi-identity changes field by field. Never label aggregate
|
||||
|
||||
## Preserve worker and secret boundaries
|
||||
|
||||
`Config.ForTask` creates a detached root snapshot: models, budgets, dispatch,
|
||||
diff cap, notification, and forge host. `TaskConfig.ToConfig` reconstructs
|
||||
`Config.ForTask` creates a detached root snapshot: models, budgets, the
|
||||
retry/remediation cap (`MaxRetries`), dispatch, diff cap, notification, and
|
||||
forge host. `TaskConfig.ToConfig` reconstructs
|
||||
only those fields. Forge tokens, provider values, NATS credential references,
|
||||
repos, and infrastructure settings do not enter `TaskConfig`.
|
||||
|
||||
|
||||
@@ -14,7 +14,19 @@ Not editorial, not marketing, not playful. Every rule below serves that.
|
||||
- Vue 3 SFCs + TypeScript, Vite, Pinia, vue-router.
|
||||
- Tailwind CSS v4 via `@tailwindcss/vite`; `@custom-variant dark` keyed on the
|
||||
`[data-theme]` attribute; shadcn-vue + reka-ui for primitives;
|
||||
`@lucide/vue` for icons; `@fontsource-variable/geist` is the typeface.
|
||||
`@lucide/vue` for icons; IBM Plex Sans for UI, IBM Plex Mono for every
|
||||
machine value (Graphite theme, `docs/design/ui-redesign/`).
|
||||
- `ui/src/components/ui/` is CLI-installed only; never hand-edit it. Order of
|
||||
preference for a missing component: stock shadcn-vue (`npx shadcn-vue add`;
|
||||
reka-ui names differ, e.g. chip input is Tags input), another shadcn-vue
|
||||
registry (e.g. inspira-ui), then a new item in the sibling
|
||||
`archie-component-registry` repo, installed from its `public/r/<item>.json`.
|
||||
The CLI prompts to overwrite stock primitives an item depends on: answer no.
|
||||
To update an installed registry item, delete its `components/ui/<item>/`
|
||||
folder and add it again; never pass `--overwrite`, which also rewrites the
|
||||
stock components listed in its `registryDependencies`.
|
||||
If `npm install` fails with `EALLOWSCRIPTS`, run the CLI with
|
||||
`NPM_CONFIG_USERCONFIG=/dev/null`.
|
||||
- Features live in `ui/src/<feature>/` with colocated `.js`/`.css`. Extract a
|
||||
helper to `ui/src/base/` only on the **second distinct consumer**.
|
||||
- `ui/dist/` is committed and generated — never hand-edit it, never ignore it
|
||||
@@ -86,5 +98,5 @@ decisions into SFCs using shadcn-vue primitives and existing tokens. Mock data
|
||||
in a prototype proves nothing — verify the pattern against real task/log/diff
|
||||
shapes before building around it. A prototype proposing new information
|
||||
architecture (e.g. splitting the task view into a master-detail pane) is an
|
||||
open design question: it needs a decisive 1-page doc in `docs/prds/` before
|
||||
structural work lands, per AGENTS.md.
|
||||
open design question for the maintainer. Web UI design is not tracked in
|
||||
`docs/prds/`; record the decision on the bead and in `docs/design/`.
|
||||
@@ -72,6 +72,22 @@ jobs:
|
||||
- name: Install protobuf tools
|
||||
run: bash tools/proto.sh install
|
||||
|
||||
# The backup/restore tests shell out to pg_dump/pg_restore against a
|
||||
# postgres:18 testcontainer; the runner's stock client is older and
|
||||
# refuses the server version.
|
||||
- name: Install PostgreSQL 18 client
|
||||
run: |
|
||||
sudo install -d /usr/share/postgresql-common/pgdg
|
||||
sudo curl --fail --silent --show-error --location \
|
||||
https://www.postgresql.org/media/keys/ACCC4CF8.asc \
|
||||
--output /usr/share/postgresql-common/pgdg/apt.postgresql.org.asc
|
||||
. /etc/os-release
|
||||
echo "deb [signed-by=/usr/share/postgresql-common/pgdg/apt.postgresql.org.asc] https://apt.postgresql.org/pub/repos/apt ${VERSION_CODENAME}-pgdg main" \
|
||||
| sudo tee /etc/apt/sources.list.d/pgdg.list
|
||||
sudo apt-get update
|
||||
sudo apt-get install -y --no-install-recommends postgresql-client-18
|
||||
echo "/usr/lib/postgresql/18/bin" >> $GITHUB_PATH
|
||||
|
||||
- name: Ensure contract baseline ref
|
||||
run: |
|
||||
if ! git show-ref --verify --quiet refs/heads/main; then
|
||||
@@ -305,7 +321,7 @@ jobs:
|
||||
# ran on with a dead Telegram bot and no error anywhere
|
||||
# (archie-core-1c01). TestDistZipShipsEveryHostCommand fails if this
|
||||
# list and the copy list below stop matching the commands in cmd/.
|
||||
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }}"
|
||||
ldflags="-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary -X github.com/samcharles93/archie-core/internal/buildinfo.Version=${{ steps.version.outputs.version }} -X github.com/samcharles93/archie-core/internal/buildinfo.Runtime=${{ steps.version.outputs.version }}"
|
||||
mkdir -p dist
|
||||
for cmd in archied archie-gateway archie-state-store archie-ui archie-messaging archie-playbooks; do
|
||||
go build -ldflags "$ldflags" -o "dist/$cmd" "./cmd/$cmd"
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
# Generated output: only its generator writes it, and the gate byte-checks it.
|
||||
docs/data/generated/
|
||||
internal/contracts/
|
||||
ui/dist/
|
||||
+288
@@ -5,6 +5,294 @@ release's per-component sections are labelled beneath its heading.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [1.46.0] - 2026-10-02
|
||||
|
||||
### archied
|
||||
|
||||
- feat(workflow): declared workflow outputs for wait:true callers
|
||||
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
|
||||
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
|
||||
- feat(prreview): the gate records the review it holds and posts the operator's answer
|
||||
- feat(taskactions): one approval path answers the review gate from every surface
|
||||
- feat(webui): the dashboard answers the review gate, including a re-review's instructions
|
||||
- feat(daemon): resolve the producing identity's org before publishing work
|
||||
- feat(webui): block invalid settings and show a field's former value
|
||||
- fix(workflow): derive a declared output's captures need for profile selection
|
||||
- fix(storepkg): validate every declared authority grant at the package descriptor
|
||||
- feat(archied): refresh the model catalog at runtime
|
||||
- feat(mcp): answer server-initiated sampling from the chat model
|
||||
- feat(container): send registry auth on image pull
|
||||
- feat(messaging): retract ephemeral replies after their TTL
|
||||
- feat(messaging): transcribe Telegram voice notes
|
||||
- fix(egress): take a run's credential kind from its binding, not the Kit
|
||||
- feat(webui): a live-apply setting reads as applied, never as a restart
|
||||
- feat(webui): the dashboard reads harness bindings and opens the setup terminal
|
||||
- feat(gateway): list the harness page in the dashboard page registry
|
||||
- feat(webui): the harness settings page and its setup terminal
|
||||
- fix(workflow): park environment gate failures without dispatching a builder
|
||||
- feat(messaging): adapter-facing clarify, picker and approval contract
|
||||
- feat(gateway): gate admin slash commands by sender policy
|
||||
- feat(plugins): load plugin and secret-engine files without a restart
|
||||
- fix(workflow): deliver the feasibility PRD to the forge issue
|
||||
- fix(messaging): report the daemon version this process was built from
|
||||
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
|
||||
- fix(daemon): resume a retry whose worktree is gone
|
||||
- fix(archied): omit the max-token bound on reasoning-class models
|
||||
- fix(logging): file a task log record under its own event time
|
||||
- fix(control-plane): unify validation for the domain-managed kinds
|
||||
- feat(webui): let the operator choose the retry worktree mode
|
||||
- feat(agent): seed a starter SOUL and upgrade only untouched templates
|
||||
- feat(controlplane): add the writable review-settings resource
|
||||
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
|
||||
- fix(messaging): gate the boundary on config reads, not only package links
|
||||
- feat(messaging): restart only the channel whose settings changed
|
||||
- feat(container): apply container-runtime-policies live
|
||||
- feat(tools): reconcile MCP servers and tool settings live
|
||||
- feat(messaging): add a per-turn interactive carrier for clarify and picker
|
||||
- feat(gateway): offer ask_user when the turn's channel can carry a question
|
||||
- feat(telegram): carry clarify and picker through the text fallback
|
||||
- fix(webui): pin the dashboard validators to the control plane's
|
||||
- refactor(agent): drop the SOUL upgrade branch with no shipped template
|
||||
- feat(agentworker): answer MCP sampling from the task's model
|
||||
- fix(workflow): bind the remediate worktree before the builder runs
|
||||
- fix(config): carry max_retries into the worker TaskConfig snapshot
|
||||
- fix(agentworker): supply the guardrail engine to every task run
|
||||
|
||||
### archie-agent
|
||||
|
||||
- feat(workflow): declared workflow outputs for wait:true callers
|
||||
- feat(prreview): the operator-approval gate is PRReview's own stage-list entry
|
||||
- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write
|
||||
- feat(prreview): the gate records the review it holds and posts the operator's answer
|
||||
- feat(taskactions): one approval path answers the review gate from every surface
|
||||
- fix(workflow): derive a declared output's captures need for profile selection
|
||||
- fix(storepkg): validate every declared authority grant at the package descriptor
|
||||
- feat(mcp): answer server-initiated sampling from the chat model
|
||||
- feat(container): send registry auth on image pull
|
||||
- feat(messaging): retract ephemeral replies after their TTL
|
||||
- feat(messaging): transcribe Telegram voice notes
|
||||
- fix(egress): take a run's credential kind from its binding, not the Kit
|
||||
- fix(workflow): park environment gate failures without dispatching a builder
|
||||
- feat(messaging): adapter-facing clarify, picker and approval contract
|
||||
- feat(plugins): load plugin and secret-engine files without a restart
|
||||
- fix(workflow): deliver the feasibility PRD to the forge issue
|
||||
- fix(messaging): carry an inbound attachment's bytes to the gateway turn
|
||||
- fix(daemon): resume a retry whose worktree is gone
|
||||
- fix(logging): file a task log record under its own event time
|
||||
- fix(control-plane): unify validation for the domain-managed kinds
|
||||
- feat(webui): let the operator choose the retry worktree mode
|
||||
- fix(messaging): transcribe voice notes on the model-owning side of the boundary
|
||||
- feat(messaging): restart only the channel whose settings changed
|
||||
- feat(container): apply container-runtime-policies live
|
||||
- feat(tools): reconcile MCP servers and tool settings live
|
||||
- feat(messaging): add a per-turn interactive carrier for clarify and picker
|
||||
- feat(agentworker): answer MCP sampling from the task's model
|
||||
- fix(workflow): bind the remediate worktree before the builder runs
|
||||
- fix(config): carry max_retries into the worker TaskConfig snapshot
|
||||
- fix(agentworker): supply the guardrail engine to every task run
|
||||
|
||||
## [1.45.0] - 2026-09-30
|
||||
|
||||
### archied
|
||||
|
||||
- fix(eda): reject a result map missing a field or needing a conversion
|
||||
- feat(eda): per-org workflow enable/disable gating bindings
|
||||
- feat(telegram): carry inbound media through the chat turn
|
||||
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
|
||||
- feat(store): key control-plane resources by (org, kind)
|
||||
- fix(store): refuse resource keys the audit key cannot disambiguate
|
||||
- fix(daemon): resume the task branch before container acquisition
|
||||
- feat(webui): show attachment metadata in the session transcript
|
||||
- feat(webui): name a workflow's declared inputs on the work-request form
|
||||
- feat(controlplane): carry the caller org from the request principal
|
||||
- fix(webui): the workflow handlers act in the caller's org
|
||||
- feat(kitrun): render the OAuth credential file with sentinels
|
||||
- feat(store): record accepted package authority against the pin
|
||||
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
|
||||
- feat(gateway): a TTL-bounded dedup gate for redelivered platform messages
|
||||
- feat(egress): capture the OAuth scope set and carry it to the harness secret
|
||||
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
|
||||
- feat(store): project installed package contributions into org resources
|
||||
- feat(gateway): coalesce rapid-fire text events into one turn
|
||||
- fix(config): expand plugin, module and skills dirs like every other operator path
|
||||
- fix(webui): drop the config schema's editability advert
|
||||
- feat(webui): events counts, YAML reading, log rows and dashboard filters
|
||||
|
||||
### archie-agent
|
||||
|
||||
- feat(eda): per-org workflow enable/disable gating bindings
|
||||
- feat(telegram): carry inbound media through the chat turn
|
||||
- fix(prsource): use a CodeQL-recognised containment guard when extracting archives
|
||||
- feat(store): key control-plane resources by (org, kind)
|
||||
- feat(controlplane): carry the caller org from the request principal
|
||||
- feat(kitrun): render the OAuth credential file with sentinels
|
||||
- feat(store): record accepted package authority against the pin
|
||||
- fix(workflow): the own-PR flow no longer parks on the operator-approval gate
|
||||
- feat(egress): capture the OAuth scope set and carry it to the harness secret
|
||||
- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key
|
||||
- feat(store): project installed package contributions into org resources
|
||||
|
||||
## [1.44.1] - 2026-09-29
|
||||
|
||||
### archied
|
||||
|
||||
Two fixes to tasks that could not get past their workflow definition.
|
||||
|
||||
- **Approving a task no longer parks it again.** A task requeued under a
|
||||
different workflow kept the previous run's definition pinned, so the worker
|
||||
refused to compile the dispatch — it named `feasibility` while the row named
|
||||
`implement` — and the task parked immediately, identically on every further
|
||||
approval, which left `decline` as the only working operator action.
|
||||
The daemon now re-pins whenever the pinned definition's id disagrees with the
|
||||
task's workflow. A pin that is present, digest-valid and id-consistent is
|
||||
still a strict no-op, so an operator's own definition override survives a
|
||||
dispatch unchanged.
|
||||
- **A shipped workflow definition now reaches an existing install.** A stored
|
||||
seed was consulted only for a resource the store did not already hold, so a
|
||||
document that changed in the build never reached a database an earlier
|
||||
release had seeded. For workflow definitions that is a total outage rather
|
||||
than a stale setting: the collection validates as one document, so a stored
|
||||
step type this build no longer has failed every task's pin, whatever workflow
|
||||
the task named — and the documented recovery, removing the resource and
|
||||
restarting, wrote nothing either, because the store answered the seed's known
|
||||
request ID from a history that outlives the resource. A seed now refreshes a
|
||||
kind it wrote the newest revision of and re-creates a resource that is gone,
|
||||
while an operator's own replacement is never undone.
|
||||
|
||||
### archie-agent
|
||||
|
||||
The runtime image is rebuilt with this release and links the shared workflow
|
||||
package carrying the definition-id helper above. Hosts that run agent
|
||||
containers need `docker compose pull agent` after updating to pick it up.
|
||||
|
||||
## [1.44.0] - 2026-09-29
|
||||
|
||||
### archied
|
||||
|
||||
Archie can now review pull requests.
|
||||
|
||||
- **Reviews on request and by watch.** Ask in chat or on the dashboard work form, add a repository to the watch list, or just let archie review its own PRs before it opens them. Review intensity follows a depth dial (quick/standard/deep) classified from the size of the change, and every finished review passes a verification layer — coverage-gap and cross-finding consistency checks — before it is produced.
|
||||
- **No forge credential reaches the review sandbox.** The daemon prefetches the pull request's data and rebuilds its source snapshot over the forge's HTTP API, so the agent container works from an isolated copy with no read access to the repository's credentials.
|
||||
- **Reviews stop at the operator gate before posting.** `review.precision_gate` / `approve_before_post` decide whether a finished review posts itself or parks for operator approval. With this release the parked state is a stop sign, not a checkpoint: the approve/reject/re-review responses behind the gate are not wired yet, and the gate's settings are not yet editable in the dashboard (configure them in `config.toml`). A parked review sits until that follow-up lands.
|
||||
- The adversarial self-review pass archie previously ran before opening its own PRs is superseded by this pipeline and has been removed.
|
||||
- Hardened harness input handling: harness identifiers are bounded to integer types.
|
||||
|
||||
### archie-agent
|
||||
|
||||
The runtime image is rebuilt with this release; it links the shared pr-review workflow packages behind the reviews above. Hosts that run agent containers need `docker compose pull agent` after updating to pick it up.
|
||||
|
||||
## [1.43.0] - 2026-09-28
|
||||
|
||||
### archied
|
||||
|
||||
- **Organisations.** Tasks, identities and settings now belong to an org. An
|
||||
existing install is upgraded into a default org when the State Store first
|
||||
starts; the upgrade resumes if interrupted. Task de-duplication is scoped
|
||||
per org and identity.
|
||||
- **Access policies are enforced** at the dashboard, the API and task
|
||||
dispatch, with shipped roles and a rule that nothing crosses between orgs.
|
||||
Denials are recorded and reported on the health page. If a policy locks
|
||||
you out, `archied access reset --org <org>` (or `--instance`) on the State
|
||||
Store host restores the shipped defaults.
|
||||
- **Workflows can call workflows** with a `workflow.call` step. Inputs and
|
||||
call cycles are checked when the workflow is saved, and the caller waits
|
||||
on the callee's result.
|
||||
- **Runs record each step.** A run's stages and agent calls are stored as
|
||||
steps, the task detail page reads them, and stopping a task or archiving
|
||||
it goes through one cancel path. After a crash, steps left running are
|
||||
marked interrupted. Archiving a task removes its worktree.
|
||||
- **Model roles, repositories, scheduling policy, providers and agent
|
||||
profiles apply without a restart.**
|
||||
- **Kit harness profiles:**
|
||||
- `kit` is now one digest-pinned reference, a workload Kit or a published
|
||||
Kit set, not a list. **Rewrite `kit = [...]` in `config.toml` or the
|
||||
agent-profiles settings as the single reference**; a list no longer
|
||||
loads. Compose mixins by publishing a Kit set.
|
||||
- OAuth logins are handled on the host: the egress proxy refreshes tokens,
|
||||
stores them encrypted, and gives the container only placeholders.
|
||||
- A Kit's skills request mounts `skills_dir` read-only, and its
|
||||
instructions file (such as `CLAUDE.md`) is written beside the workspace,
|
||||
which is now `/archie/workspace`.
|
||||
- A run still cannot be granted the credential a Kit needs, so a Kit that
|
||||
requires one is refused at launch.
|
||||
- Rate-limited webhook deliveries get `429`.
|
||||
- `archie-gateway` and `archie-state-store` report ready to systemd.
|
||||
|
||||
### archie-agent
|
||||
|
||||
- Runs workflow calls, records its steps and agent calls, and runs Kit
|
||||
harness stages under the profile's Kit.
|
||||
|
||||
## [1.42.0] - 2026-09-26
|
||||
|
||||
### archied
|
||||
|
||||
- **The dashboard is rebuilt on a new Graphite theme.** Settings moved to its
|
||||
own sidebar with one save flow across every page (Channels, Tools & MCP,
|
||||
Scheduling policy, Personas and Schedules, Identities, Plugins, Container
|
||||
runtime, and a History of past changes). The top bar, Dashboard, Workflows,
|
||||
task detail, the New task dialog and the Events page are all new: Dashboard
|
||||
leads with what needs you, a run's stage rail and detail panels sit
|
||||
side by side, Workflows shows per-workflow stats including completed runs,
|
||||
and Events states capture status with a copyable capture endpoint. Live
|
||||
updates share one stream and reopen after a drop instead of going quiet.
|
||||
- **Settings changes are audited.** A field-level audit table records who
|
||||
changed what, with a view on each settings page.
|
||||
- **A task can carry a whole-run wall-clock limit**, separate from a stage's
|
||||
own budget.
|
||||
- **A run that makes no changes now ends as completed and its worktree is
|
||||
cleaned up**, rather than left in a state Workflows didn't count.
|
||||
- **Abandoning a task no longer closes its forge issue.** Only the workflow's
|
||||
own terminal outcomes do that now.
|
||||
- **A task whose container exits before the worker replies is parked**
|
||||
instead of left running with no way to finish.
|
||||
- **A worktree still holding uncommitted work is kept**, rather than reset,
|
||||
when its task reaches a terminal state.
|
||||
- **A provider's stored settings no longer get corrupted with a process-local
|
||||
placeholder in place of your configured secret reference**, and archied
|
||||
rejects a stored value shaped like one on the way back in.
|
||||
- **Kit v3 harness profiles.** A `[containers.profiles.<name>]` entry can now
|
||||
name a Kit v3 image (`kit = [...]`, pinned by digest) instead of a plain
|
||||
container image, running the task's agent stages on an external CLI --
|
||||
Claude Code, Codex, Pi, OMP or GitHub Copilot CLI -- inside an isolated
|
||||
sandbox network. This release lands the daemon-side plumbing (egress
|
||||
proxy, sandbox network, credential injection points); it does not yet ship
|
||||
a way to grant a run's identity the credential a Kit needs, so a Kit
|
||||
requiring one is refused at launch until a later release adds it.
|
||||
- `task dev` now starts the State Store and waits for it before the rest of
|
||||
the stack.
|
||||
- Every service binary the installer builds is stamped with its version.
|
||||
|
||||
### archie-agent
|
||||
|
||||
- Carries the same task-lifecycle fixes as archied above (no-change runs,
|
||||
parking on an early container exit, and the abandon/forge-issue fix), plus
|
||||
the Kit v3 harness runner: a stage can now drive an external CLI
|
||||
headlessly, read output from Claude Code, Codex, Pi, OMP or GitHub Copilot
|
||||
CLI, and serve it capture tools over MCP.
|
||||
- Claude's cached tokens are counted as prompt tokens, matching the built-in
|
||||
agent loop's accounting.
|
||||
|
||||
## [1.41.2] - 2026-09-25
|
||||
|
||||
### archied
|
||||
|
||||
- **`/update` no longer offers an old runtime.** The runtime has shipped under
|
||||
the release version since the version streams merged, but the update check
|
||||
still read the retired runtime tags, so a current host was offered runtime
|
||||
1.35.0 as an update. Do not approve that offer on 1.41.1; update to 1.41.2
|
||||
instead.
|
||||
- **`/version` reports the runtime version.** Binaries from the release zip
|
||||
showed `Runtime: dev`.
|
||||
|
||||
## [1.41.1] - 2026-09-25
|
||||
|
||||
### archied
|
||||
|
||||
- **First published build of 1.41.0.** The 1.41.0 tag produced no release
|
||||
artifacts; 1.41.1 carries everything listed under 1.41.0 below, including
|
||||
the PostgreSQL 18 requirement and the removed config keys.
|
||||
|
||||
## [1.41.0] - 2026-09-25
|
||||
|
||||
### archied
|
||||
|
||||
@@ -35,7 +35,18 @@ plugin engine, satisfy
|
||||
|
||||
Before changing an area (frontend UI, agent, workflows, daemon, State Store,
|
||||
control plane), read its page in `docs/development/`: it names every layer the
|
||||
change must reach.
|
||||
change must reach. This is not optional colour reading -- archie-core is built
|
||||
as an extensible, customisable surface, not a fixed product, so a change that
|
||||
looks complete inside one package routinely is not: a new setting that never
|
||||
reaches the control-plane schema descriptor and dashboard parses but never
|
||||
renders, is never editable, and never live-applies, exactly like a config
|
||||
field with no consumer. The dev-docs page for the area is where that
|
||||
cross-layer reach is written down; read it before starting, not after
|
||||
something downstream turns out silently unwired. This applies whether the
|
||||
work is yours directly or handed to a subagent or crew worker -- carry the
|
||||
relevant docs/development page into their prompt, the same way a bead ID is
|
||||
carried; "figure out what else needs updating" left implicit is exactly the
|
||||
gap this note exists to close.
|
||||
|
||||
## Scope Discipline
|
||||
|
||||
@@ -78,8 +89,10 @@ domain migration.
|
||||
reload of `nats.url` logs an error requiring restart to prevent split-brain
|
||||
delivery.
|
||||
- **Container pull policy:** `containers.pull_policy` must be `"missing"`
|
||||
(default) or `"always"`. Private registries return 401 on `"always"` because
|
||||
no auth is sent. Refresh explicitly via `docker compose pull agent`.
|
||||
(default) or `"always"`. Private registries need `containers.registry_auth`
|
||||
(a `SecretRef` resolving to a `registry.AuthConfig` JSON document); without it
|
||||
the pull is anonymous and a private registry answers 401. Refresh explicitly
|
||||
via `docker compose pull agent`.
|
||||
- **Docker Compose:** `docker-compose.yml` carries optional external NATS and
|
||||
the `agent` build stanza. The agent uses a `build` profile so `up -d nats`
|
||||
never starts it as a persistent service.
|
||||
@@ -288,6 +301,29 @@ StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
|
||||
Verify the failure originates from test assertions, not compilation errors.
|
||||
Do not write tests that restate an assignment or a constant: a test that
|
||||
cannot fail for an interesting reason is noise in the gate.
|
||||
- **A test is a maintenance liability, not free insurance.** Every test
|
||||
added is code the project now carries forever: it must compile, it must
|
||||
keep passing as the code around it changes, and someone reads it during
|
||||
every future change to that area. Write one because a real regression
|
||||
would slip through without it, not because the function was touched.
|
||||
- **Never pin a literal end-user config value, database row, or settings
|
||||
document as the thing under test.** Test the validation rule, the
|
||||
migration's shape, or the round-trip contract -- not one operator's
|
||||
specific `config.toml` value, a hand-picked DB fixture that mirrors real
|
||||
data, or a setting's current default. Those change for reasons that have
|
||||
nothing to do with a regression, and a test pinned to one breaks on
|
||||
every such change, which is cost with no signal.
|
||||
- **Test-only helpers, fakes and fixtures live in `_test.go` files (or a
|
||||
package no production `.go` file imports), never in a file the binary
|
||||
ships.** `go build` does not compile `_test.go` files into the binary,
|
||||
but an exported "test helper" living in a regular source file compiles
|
||||
into every binary that imports the package, whether or not a test ever
|
||||
runs. If a helper must be shared across packages, put it behind a
|
||||
build-tagged or `_test.go`-suffixed file in an `xtest`-style package,
|
||||
not behind a normal export.
|
||||
- **Coverage is not the goal.** A codebase that grows mostly because tests
|
||||
multiplied faster than the feature they cover is a symptom, not
|
||||
progress -- prefer fewer, sharper tests over one per line changed.
|
||||
2. **Green (Implementation):** Implement minimal code to satisfy the failing
|
||||
tests.
|
||||
3. **Quality Gate:** Run `task check`.
|
||||
@@ -307,10 +343,12 @@ StateStoreGrantIssuer` (`staterpc.GrantIssuer`) registers a fresh
|
||||
separate fresh-context reviewer pass on every change as a matter of course.
|
||||
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
|
||||
opt-in per request — ask before running one. This is the rule for a human or
|
||||
agent _contributor_. Separately, archied runs the same adversarial review
|
||||
automatically on the PRs it opens (gated per repo by `repo.review_enabled`)
|
||||
— see `docs/architecture/adversarial-review.md`. The two paths are distinct:
|
||||
you run one when asked; archied runs one before it opens a PR.
|
||||
agent _contributor_. Separately, archied runs its own PR review pipeline
|
||||
(`docs/prds/pr-review-agent.md`) before it opens a PR of its own — see that
|
||||
PRD's Triggers section ("archie's own PRs"). It supersedes the older
|
||||
single-reviewer stage `docs/architecture/adversarial-review.md` described
|
||||
(`repo.review_enabled` no longer exists). The two paths are distinct: you
|
||||
run a manual pass when asked; archied runs its own before it opens a PR.
|
||||
6. **Linter Guard:**
|
||||
|
||||
- When using `errorlint` fixes, ensure boolean predicates (e.g.
|
||||
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -0,0 +1,19 @@
|
||||
NOTICE
|
||||
|
||||
This product includes software derived from PR-AF
|
||||
(https://github.com/Agent-Field/pr-af), Copyright AgentField,
|
||||
licensed under the Apache License, Version 2.0.
|
||||
|
||||
Derived portions: internal/domain/workflow/prreview -- the unified diff
|
||||
parser, change clustering, blast radius, evidence extraction, scoring,
|
||||
deduplication, line mapping and review-event selection.
|
||||
|
||||
PR-AF declares the Apache License, Version 2.0 in its pyproject.toml and
|
||||
ships no license file. A copy of the License is available at
|
||||
https://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
This product includes software from the Cedar project
|
||||
(https://github.com/cedar-policy/cedar), Copyright Amazon.com, Inc. or its
|
||||
affiliates, licensed under the Apache License, Version 2.0, as implemented by
|
||||
github.com/cedar-policy/cedar-go, which declares the same license in its
|
||||
repository. This repository links the library; it derives no source from it.
|
||||
@@ -177,3 +177,7 @@ but systemd is optional.
|
||||
|
||||
Contributions should follow [AGENTS.md](AGENTS.md), including its testing,
|
||||
generated-file, and commit rules.
|
||||
|
||||
## License
|
||||
|
||||
Copyright 2026 Sam Catlow. Licensed under the [Apache License, Version 2.0](LICENSE). Third-party attributions are in [NOTICE](NOTICE).
|
||||
+34
-8
@@ -153,6 +153,11 @@ tasks:
|
||||
cmds:
|
||||
- bash tools/webhook-send.sh {{.CLI_ARGS}}
|
||||
|
||||
bench:prreview:
|
||||
desc: Review or rescore the Martian benchmark (-- -review-model PROVIDER/MODEL -classification-model PROVIDER/MODEL; --help for flags)
|
||||
cmds:
|
||||
- go run ./cmd/archie-prbench {{.CLI_ARGS}}
|
||||
|
||||
dev:
|
||||
desc: Run development services and Vite at http://localhost:5173
|
||||
deps: [dev:daemon, dev:gateway, dev:state-store, dev:dashboard, dev:ui]
|
||||
@@ -164,7 +169,7 @@ tasks:
|
||||
- |
|
||||
set -eu
|
||||
for _ in $(seq 1 60); do
|
||||
status=$(docker inspect --format '{{.State.Health.Status}}' "$(docker compose ps -q postgres)" 2>/dev/null || true)
|
||||
status=$(docker inspect --format '{{`{{.State.Health.Status}}`}}' "$(docker compose ps -q postgres)" 2>/dev/null || true)
|
||||
if [ "$status" = "healthy" ]; then
|
||||
exit 0
|
||||
fi
|
||||
@@ -176,6 +181,14 @@ tasks:
|
||||
dev:daemon:
|
||||
desc: Run archied with live reload
|
||||
cmds:
|
||||
- |
|
||||
# The daemon and Gateway read their settings from the State Store at
|
||||
# boot and exit if it is not up yet; it starts only once PostgreSQL
|
||||
# is healthy, so wait for its port ([services.state] in
|
||||
# deployments/dev.toml) first.
|
||||
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
|
||||
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
|
||||
exit 1
|
||||
- air -build.args_bin="-config-overlay,deployments/dev.toml"
|
||||
|
||||
dev:dashboard:
|
||||
@@ -192,6 +205,14 @@ tasks:
|
||||
dev:gateway:
|
||||
desc: Run the development Gateway
|
||||
cmds:
|
||||
- |
|
||||
# The daemon and Gateway read their settings from the State Store at
|
||||
# boot and exit if it is not up yet; it starts only once PostgreSQL
|
||||
# is healthy, so wait for its port ([services.state] in
|
||||
# deployments/dev.toml) first.
|
||||
for _ in $(seq 1 120); do nc -z 127.0.0.1 9091 && exit 0; sleep 1; done
|
||||
echo "state store did not come up on 127.0.0.1:9091 within 120s" >&2
|
||||
exit 1
|
||||
- go run ./cmd/archie-gateway -config-overlay deployments/dev.toml
|
||||
|
||||
dev:ui:
|
||||
@@ -222,8 +243,14 @@ tasks:
|
||||
build:
|
||||
desc: Build archie services and agent binaries
|
||||
vars:
|
||||
GATEWAY_VERSION: dev
|
||||
RUNTIME_VERSION: dev
|
||||
GATEWAY_VERSION: '{{.GATEWAY_VERSION | default "dev"}}'
|
||||
RUNTIME_VERSION: '{{.RUNTIME_VERSION | default "dev"}}'
|
||||
SERVICE_LDFLAGS: >-
|
||||
-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Version={{.GATEWAY_VERSION}}
|
||||
-X github.com/samcharles93/archie-core/internal/buildinfo.Runtime={{.RUNTIME_VERSION}}
|
||||
sources:
|
||||
- "**/*.go"
|
||||
- go.mod
|
||||
@@ -237,11 +264,10 @@ tasks:
|
||||
- "{{.BIN_DIR}}/archie-messaging"
|
||||
- "{{.BIN_DIR}}/archie-agent"
|
||||
cmds:
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/app/archied.runtimeVersion={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archied ./cmd/archied
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/archied.gatewayVersion={{.GATEWAY_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-gateway ./cmd/archie-gateway
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-state-store ./cmd/archie-state-store
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-ui ./cmd/archie-ui
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-messaging ./cmd/archie-messaging
|
||||
# One flag set for every service, matching scripts/archie-update-install
|
||||
# and the release workflow, so each binary reports the same version.
|
||||
- for: [archied, archie-gateway, archie-state-store, archie-ui, archie-messaging]
|
||||
cmd: go build -ldflags "{{.SERVICE_LDFLAGS}}" -o {{.BIN_DIR}}/{{.ITEM}} ./cmd/{{.ITEM}}
|
||||
- go build -ldflags "-X github.com/samcharles93/archie-core/internal/app/agentworker.version={{.RUNTIME_VERSION}} -X github.com/samcharles93/archie-core/internal/installtype.buildType=binary" -o {{.BIN_DIR}}/archie-agent ./cmd/archie-agent
|
||||
|
||||
test:
|
||||
|
||||
@@ -53,6 +53,8 @@ func TestCommandBoundary(t *testing.T) {
|
||||
"run": true,
|
||||
"runCommand": true,
|
||||
"natsConnectionSettings": true,
|
||||
"runRelay": true,
|
||||
"runMCP": true,
|
||||
}
|
||||
for _, declaration := range file.Decls {
|
||||
function, ok := declaration.(*ast.FuncDecl)
|
||||
|
||||
@@ -8,8 +8,10 @@ import (
|
||||
"fmt"
|
||||
"io"
|
||||
"log/slog"
|
||||
"net"
|
||||
"os"
|
||||
"os/signal"
|
||||
"strings"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/agentworker"
|
||||
@@ -26,6 +28,12 @@ func run() int {
|
||||
}
|
||||
|
||||
func runCommand(args []string, getenv func(string) string, stderr io.Writer, runWorker workerRunner) int {
|
||||
if len(args) > 0 && args[0] == "relay" {
|
||||
return runRelay(args[1:], stderr, agentworker.RunRelay)
|
||||
}
|
||||
if len(args) > 0 && args[0] == "mcp" {
|
||||
return runMCP(args[1:], stderr, agentworker.RunCaptureMCP)
|
||||
}
|
||||
flags := flag.NewFlagSet("archie-agent", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
natsURLFlag := flags.String("nats-url", "", "NATS server URL (defaults to NATS_URL)")
|
||||
@@ -81,3 +89,78 @@ func natsConnectionSettings(flagURL string, getenv func(string) string) (url, to
|
||||
}
|
||||
return url, getenv("NATS_TOKEN")
|
||||
}
|
||||
|
||||
type relayServer func(ctx context.Context, forwards map[string]string) error
|
||||
|
||||
// runRelay is the sandbox egress relay: the container on both a sandbox's
|
||||
// isolated network and the host-reachable one, forwarding a fixed set of
|
||||
// ports to the proxy, NATS and the State Store.
|
||||
func runRelay(args []string, stderr io.Writer, serve relayServer) int {
|
||||
flags := flag.NewFlagSet("archie-agent relay", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
forwards := map[string]string{}
|
||||
flags.Func("forward", "listen=target: forward connections on listen to target (repeatable)", func(v string) error {
|
||||
listen, target, ok := strings.Cut(v, "=")
|
||||
if !ok || listen == "" || target == "" {
|
||||
return fmt.Errorf("%q is not listen=target", v)
|
||||
}
|
||||
if _, _, err := net.SplitHostPort(listen); err != nil {
|
||||
return fmt.Errorf("listen address %q: %w", listen, err)
|
||||
}
|
||||
if _, _, err := net.SplitHostPort(target); err != nil {
|
||||
return fmt.Errorf("target %q: %w", target, err)
|
||||
}
|
||||
if _, dup := forwards[listen]; dup {
|
||||
return fmt.Errorf("listen address %q is forwarded twice", listen)
|
||||
}
|
||||
forwards[listen] = target
|
||||
return nil
|
||||
})
|
||||
if err := flags.Parse(args); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return 0
|
||||
}
|
||||
return 2
|
||||
}
|
||||
if len(forwards) == 0 {
|
||||
fmt.Fprintln(stderr, "error: at least one -forward is required")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := serve(ctx, forwards); err != nil {
|
||||
fmt.Fprintln(stderr, "error:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
type mcpServer func(ctx context.Context, specPath, capturesPath string) error
|
||||
|
||||
// runMCP serves a stage's capture tools to a harness over stdio. The
|
||||
// harness starts it, so it runs as the harness user and holds no secrets.
|
||||
func runMCP(args []string, stderr io.Writer, serve mcpServer) int {
|
||||
flags := flag.NewFlagSet("archie-agent mcp", flag.ContinueOnError)
|
||||
flags.SetOutput(stderr)
|
||||
spec := flags.String("spec", "", "JSON file listing the stage's capture tools")
|
||||
captures := flags.String("captures", "", "file accepted capture calls are appended to")
|
||||
if err := flags.Parse(args); err != nil {
|
||||
if errors.Is(err, flag.ErrHelp) {
|
||||
return 0
|
||||
}
|
||||
return 2
|
||||
}
|
||||
if *spec == "" || *captures == "" {
|
||||
fmt.Fprintln(stderr, "error: -spec and -captures are required")
|
||||
flags.Usage()
|
||||
return 1
|
||||
}
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if err := serve(ctx, *spec, *captures); err != nil {
|
||||
fmt.Fprintln(stderr, "error:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"context"
|
||||
"maps"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestRunRelay(t *testing.T) {
|
||||
noServe := func(t *testing.T) relayServer {
|
||||
return func(context.Context, map[string]string) error {
|
||||
t.Error("the relay served despite a usage error")
|
||||
return nil
|
||||
}
|
||||
}
|
||||
for name, args := range map[string][]string{
|
||||
"no forward": {},
|
||||
"a forward with no =": {"-forward", "127.0.0.1:0"},
|
||||
"a forward with no port": {"-forward", "=172.17.0.1:3129"},
|
||||
"one listen address used": {"-forward", ":3128=a:1", "-forward", ":3128=b:2"},
|
||||
} {
|
||||
t.Run(name+" is a usage error", func(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
if code := runRelay(args, &stderr, noServe(t)); code == 0 {
|
||||
t.Fatalf("exit 0, want a usage error; stderr %q", stderr.String())
|
||||
}
|
||||
})
|
||||
}
|
||||
t.Run("every forward is served", func(t *testing.T) {
|
||||
var got map[string]string
|
||||
serve := func(_ context.Context, forwards map[string]string) error {
|
||||
got = forwards
|
||||
return nil
|
||||
}
|
||||
args := []string{"-forward", ":3128=172.17.0.1:3129", "-forward", ":4222=172.17.0.1:4222"}
|
||||
if code := runRelay(args, &bytes.Buffer{}, serve); code != 0 {
|
||||
t.Fatalf("exit %d, want 0", code)
|
||||
}
|
||||
want := map[string]string{":3128": "172.17.0.1:3129", ":4222": "172.17.0.1:4222"}
|
||||
if !maps.Equal(got, want) {
|
||||
t.Fatalf("served %v, want %v", got, want)
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
func TestRelaySubcommandRoutes(t *testing.T) {
|
||||
var stderr bytes.Buffer
|
||||
code := runCommand([]string{"relay"}, func(string) string { return "" }, &stderr, nil)
|
||||
if code != 1 || !strings.Contains(stderr.String(), "-forward") {
|
||||
t.Fatalf("relay subcommand exit %d stderr %q; want the relay's own usage error", code, stderr.String())
|
||||
}
|
||||
}
|
||||
@@ -57,6 +57,14 @@ var deletionGate = []bannedCategory{
|
||||
{"gateway runtime", []string{
|
||||
modulePath + "internal/gateway",
|
||||
}},
|
||||
// The PRD names "Direct LLM providers, model runtimes" among what the
|
||||
// Messaging Service must not own or link. These are the in-module
|
||||
// infrastructure packages that construct one; building either here means
|
||||
// a model-provider credential is in the messaging process.
|
||||
{"model providers", []string{
|
||||
modulePath + "internal/infrastructure/transcription",
|
||||
modulePath + "internal/infrastructure/embedding",
|
||||
}},
|
||||
{"dashboard", []string{
|
||||
modulePath + "internal/webui",
|
||||
}},
|
||||
@@ -92,13 +100,8 @@ func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
|
||||
if excepted(importPath, linked) {
|
||||
continue
|
||||
}
|
||||
for _, category := range deletionGate {
|
||||
for _, prefix := range category.prefixes {
|
||||
if !under(importPath, prefix) {
|
||||
continue
|
||||
}
|
||||
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category.name)
|
||||
}
|
||||
if category, banned := bannedLink(importPath); banned {
|
||||
t.Errorf("archie-messaging links %s (%s); the Messaging Service reaches that capability over a contract, never in-process (docs/prds/messaging-service-boundary.md, deletion gate)", importPath, category)
|
||||
}
|
||||
}
|
||||
for _, exception := range gateExceptions {
|
||||
@@ -113,6 +116,40 @@ func TestMessagingProcessLinksNoRuntimeItOnlyDials(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// bannedLink reports the deletion-gate category importPath falls under, or
|
||||
// ("", false). Classifying a single package is the rule the unit test below
|
||||
// pins, so the gate can be exercised without a live `go list`.
|
||||
func bannedLink(importPath string) (category string, banned bool) {
|
||||
for _, c := range deletionGate {
|
||||
for _, prefix := range c.prefixes {
|
||||
if under(importPath, prefix) {
|
||||
return c.name, true
|
||||
}
|
||||
}
|
||||
}
|
||||
return "", false
|
||||
}
|
||||
|
||||
// TestDeletionGateBansModelProviderCapabilities pins the PRD category that the
|
||||
// voice-transcription violation slipped past: the link gate would not flag
|
||||
// anything merely because the process built an LLM client, so the capability
|
||||
// packages are named explicitly. gatewayrpc is checked as the negative, since
|
||||
// it is the permitted contract and must not be swept up by the internal/
|
||||
// infrastructure/ prefix.
|
||||
func TestDeletionGateBansModelProviderCapabilities(t *testing.T) {
|
||||
for _, pkg := range []string{
|
||||
modulePath + "internal/infrastructure/transcription",
|
||||
modulePath + "internal/infrastructure/embedding",
|
||||
} {
|
||||
if _, banned := bannedLink(pkg); !banned {
|
||||
t.Errorf("bannedLink(%q) = not banned; the Messaging Service must not construct a model-provider capability in-process", pkg)
|
||||
}
|
||||
}
|
||||
if category, banned := bannedLink(modulePath + "internal/infrastructure/gatewayrpc"); banned {
|
||||
t.Errorf("bannedLink(gatewayrpc) = %q; the Gateway contract is permitted", category)
|
||||
}
|
||||
}
|
||||
|
||||
// excepted reports whether importPath sits under an excepted package, recording
|
||||
// the ones actually linked so a stale exception fails.
|
||||
func excepted(importPath string, linked map[string]bool) bool {
|
||||
|
||||
@@ -0,0 +1,433 @@
|
||||
// The link gate in architecture_test.go measures which packages the Messaging
|
||||
// binary links. It cannot see a process that links nothing new but still reads
|
||||
// a decoded configuration value it is not allowed to own -- which is exactly
|
||||
// how voice transcription was wired into the Messaging Service while a green
|
||||
// link gate watched: internal/app/archiemessaging/config.go built an LLM
|
||||
// transcriber from [models].transcription and [providers.*], both of which
|
||||
// docs/prds/messaging-service-boundary.md reserves to the model-owning process.
|
||||
//
|
||||
// This file closes that shape of hole: it scans the Messaging Service's own
|
||||
// production sources for a read of a top-level config section the PRD forbids,
|
||||
// so re-adding the projection field fails here rather than shipping green.
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
"go/ast"
|
||||
"go/parser"
|
||||
"go/token"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// messagingAppDir is the Messaging Service's application package, relative to
|
||||
// this package's directory (go test runs with the package dir as cwd).
|
||||
const messagingAppDir = "../../internal/app/archiemessaging"
|
||||
|
||||
// bannedConfigFields are the top-level config.Config fields the Messaging
|
||||
// Service must never read, by Go field name. The PRD's "Configuration
|
||||
// Ownership" section permits [chat.*], [services.*], [secrets] and the
|
||||
// path/identity keys the process needs to locate itself; every entry here is a
|
||||
// capability another process owns. internal/config's field names are the
|
||||
// concrete keys, because that is what a Go read names.
|
||||
var bannedConfigFields = map[string]bool{
|
||||
"Forge": true, // [forge]
|
||||
"Repos": true, // [repos]
|
||||
"Models": true, // [models]
|
||||
"Providers": true, // [providers]
|
||||
"Containers": true, // [containers]
|
||||
"NATS": true, // [nats]
|
||||
// [runners] has no top-level field in internal/config today; if one is
|
||||
// added its own name must be listed here with it.
|
||||
}
|
||||
|
||||
// configReadOffenders returns the banned "<holder>.<Field>" config reads in
|
||||
// src, in source order. A holder is anything the file gives the
|
||||
// internal/config.Config type: an explicitly typed parameter, var, receiver or
|
||||
// struct field, a short variable declaration or inferred var whose right-hand
|
||||
// side resolves to one ("cfg := doc.Config"), or a range variable over a slice
|
||||
// of them. The type is tracked by name because a name is what a Go read
|
||||
// selects on. A config value returned by a call this file does not declare is
|
||||
// outside a syntactic rule and stays untracked.
|
||||
func configReadOffenders(src []byte) []string {
|
||||
fset := token.NewFileSet()
|
||||
file, err := parser.ParseFile(fset, "config.go", src, parser.SkipObjectResolution)
|
||||
if err != nil {
|
||||
// A file that does not parse is reported as an offender rather than
|
||||
// ignored: silently skipping it would make this gate blind exactly
|
||||
// when the tree is broken.
|
||||
return []string{"parse error: " + err.Error()}
|
||||
}
|
||||
kinds := configKinds(file)
|
||||
|
||||
var offenders []string
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
sel, ok := n.(*ast.SelectorExpr)
|
||||
if !ok || !bannedConfigFields[sel.Sel.Name] {
|
||||
return true
|
||||
}
|
||||
switch base := sel.X.(type) {
|
||||
case *ast.Ident:
|
||||
if kinds[base.Name] == configValue {
|
||||
offenders = append(offenders, base.Name+"."+sel.Sel.Name)
|
||||
}
|
||||
case *ast.SelectorExpr:
|
||||
// doc.Config, or the config-typed struct field h.cfg. Config is
|
||||
// named by configuration.Document in another package, so it
|
||||
// cannot come out of the kinds map; treat a selected Config as
|
||||
// a config holder unconditionally.
|
||||
if base.Sel.Name == "Config" || kinds[base.Sel.Name] == configValue {
|
||||
offenders = append(offenders, base.Sel.Name+"."+sel.Sel.Name)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return offenders
|
||||
}
|
||||
|
||||
// configKind is how an identifier or expression reaches a config.Config value.
|
||||
type configKind int
|
||||
|
||||
const (
|
||||
notConfig configKind = iota // not a config value
|
||||
configValue // config.Config
|
||||
configSlice // []config.Config, [N]config.Config or map[K]config.Config
|
||||
)
|
||||
|
||||
// configKinds resolves the identifiers in file that hold a config.Config, in
|
||||
// two passes because an inferred holder's source must be classified before the
|
||||
// holder's own name can be.
|
||||
func configKinds(file *ast.File) map[string]configKind {
|
||||
kinds := map[string]configKind{}
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
switch node := n.(type) {
|
||||
case *ast.FuncDecl:
|
||||
classifyFields(node.Recv, kinds)
|
||||
classifyFields(node.Type.Params, kinds)
|
||||
case *ast.ValueSpec:
|
||||
classifyNames(node.Type, node.Names, kinds)
|
||||
case *ast.StructType:
|
||||
for _, field := range node.Fields.List {
|
||||
classifyNames(field.Type, field.Names, kinds)
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
// Inferred holders: a single source-order pass suffices because Go
|
||||
// requires a name to be declared before it is referenced.
|
||||
ast.Inspect(file, func(n ast.Node) bool {
|
||||
switch node := n.(type) {
|
||||
case *ast.AssignStmt:
|
||||
if node.Tok != token.DEFINE {
|
||||
return true
|
||||
}
|
||||
classifyValues(node.Lhs, node.Rhs, kinds)
|
||||
case *ast.ValueSpec:
|
||||
// An explicit type was handled above; here only "var cfg =
|
||||
// doc.Config", which infers the same way a := does.
|
||||
if node.Type != nil {
|
||||
return true
|
||||
}
|
||||
names := make([]ast.Expr, len(node.Names))
|
||||
for i, name := range node.Names {
|
||||
names[i] = name
|
||||
}
|
||||
classifyValues(names, node.Values, kinds)
|
||||
case *ast.RangeStmt:
|
||||
if exprKind(node.X, kinds) != configSlice {
|
||||
return true
|
||||
}
|
||||
if id, ok := node.Value.(*ast.Ident); ok {
|
||||
kinds[id.Name] = configValue
|
||||
}
|
||||
}
|
||||
return true
|
||||
})
|
||||
return kinds
|
||||
}
|
||||
|
||||
// classifyValues records each lhs identifier that resolves to a config kind of
|
||||
// the rhs expression in the same position. A shorter lhs or rhs is fine;
|
||||
// position is what pairs a name with its value.
|
||||
func classifyValues(lhs, rhs []ast.Expr, kinds map[string]configKind) {
|
||||
for i, target := range lhs {
|
||||
if i >= len(rhs) {
|
||||
return
|
||||
}
|
||||
id, ok := target.(*ast.Ident)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
if kind := exprKind(rhs[i], kinds); kind != notConfig {
|
||||
kinds[id.Name] = kind
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// classifyFields records every named field in fields whose type holds a
|
||||
// config.Config.
|
||||
func classifyFields(fields *ast.FieldList, kinds map[string]configKind) {
|
||||
if fields == nil {
|
||||
return
|
||||
}
|
||||
for _, field := range fields.List {
|
||||
classifyNames(field.Type, field.Names, kinds)
|
||||
}
|
||||
}
|
||||
|
||||
// classifyNames records names as holding the config kind of typ.
|
||||
func classifyNames(typ ast.Expr, names []*ast.Ident, kinds map[string]configKind) {
|
||||
kind := typeKind(typ)
|
||||
if kind == notConfig {
|
||||
return
|
||||
}
|
||||
for _, name := range names {
|
||||
kinds[name.Name] = kind
|
||||
}
|
||||
}
|
||||
|
||||
// exprKind resolves the config kind of an expression from the identifiers
|
||||
// already classified in kinds.
|
||||
func exprKind(expr ast.Expr, kinds map[string]configKind) configKind {
|
||||
switch e := expr.(type) {
|
||||
case *ast.Ident:
|
||||
return kinds[e.Name]
|
||||
case *ast.SelectorExpr:
|
||||
// doc.Config of a configuration.Document, or a struct field the file
|
||||
// declared as config.Config.
|
||||
if e.Sel.Name == "Config" {
|
||||
return configValue
|
||||
}
|
||||
return kinds[e.Sel.Name]
|
||||
case *ast.CompositeLit:
|
||||
return typeKind(e.Type)
|
||||
case *ast.StarExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.UnaryExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.ParenExpr:
|
||||
return exprKind(e.X, kinds)
|
||||
case *ast.IndexExpr:
|
||||
if exprKind(e.X, kinds) == configSlice {
|
||||
return configValue
|
||||
}
|
||||
}
|
||||
return notConfig
|
||||
}
|
||||
|
||||
// typeKind reports the config kind a type expression names: config.Config, or
|
||||
// a slice, array or map whose element is one.
|
||||
func typeKind(expr ast.Expr) configKind {
|
||||
switch t := expr.(type) {
|
||||
case *ast.ArrayType:
|
||||
if isConfigType(t.Elt) {
|
||||
return configSlice
|
||||
}
|
||||
case *ast.MapType:
|
||||
// A map's range value is its element; classify the map itself as a
|
||||
// slice-like source so a range over it yields config values.
|
||||
if isConfigType(t.Value) {
|
||||
return configSlice
|
||||
}
|
||||
case *ast.StarExpr:
|
||||
return typeKind(t.X)
|
||||
case *ast.ParenExpr:
|
||||
return typeKind(t.X)
|
||||
}
|
||||
if isConfigType(expr) {
|
||||
return configValue
|
||||
}
|
||||
return notConfig
|
||||
}
|
||||
|
||||
// isConfigType reports whether expr names internal/config's Config type,
|
||||
// directly or behind a pointer.
|
||||
func isConfigType(expr ast.Expr) bool {
|
||||
switch t := expr.(type) {
|
||||
case *ast.SelectorExpr:
|
||||
id, ok := t.X.(*ast.Ident)
|
||||
return ok && id.Name == "config" && t.Sel.Name == "Config"
|
||||
case *ast.StarExpr:
|
||||
return isConfigType(t.X)
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// TestMessagingReadsNoBannedConfigSection is the live gate: every production
|
||||
// source file in the Messaging Service's application package is scanned, and a
|
||||
// read of a PRD-forbidden section fails the build.
|
||||
func TestMessagingReadsNoBannedConfigSection(t *testing.T) {
|
||||
entries, err := os.ReadDir(messagingAppDir)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", messagingAppDir, err)
|
||||
}
|
||||
scanned := 0
|
||||
for _, entry := range entries {
|
||||
name := entry.Name()
|
||||
if entry.IsDir() || !strings.HasSuffix(name, ".go") || strings.HasSuffix(name, "_test.go") {
|
||||
continue
|
||||
}
|
||||
src, err := os.ReadFile(filepath.Join(messagingAppDir, name))
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", name, err)
|
||||
}
|
||||
scanned++
|
||||
for _, offender := range configReadOffenders(src) {
|
||||
t.Errorf("%s reads %s; the Messaging Service must not read or decode that section (docs/prds/messaging-service-boundary.md, Configuration Ownership) -- the capability belongs to the model-owning process, reached over a contract", name, offender)
|
||||
}
|
||||
}
|
||||
// A gate that read no files would pass silently. Pin that it scanned the
|
||||
// package it names.
|
||||
if scanned == 0 {
|
||||
t.Fatalf("no production .go files found in %s: the gate asserted nothing", messagingAppDir)
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleCatchesTheOldWiring proves the rule fails on a synthetic
|
||||
// copy of the shape that shipped: a projection built by reading
|
||||
// [models].transcription and [providers.*]. Without this, the live gate's rule
|
||||
// could rot into a no-op and still report a pass.
|
||||
func TestConfigReadRuleCatchesTheOldWiring(t *testing.T) {
|
||||
const reverted = `package archiemessaging
|
||||
|
||||
import (
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/transcription"
|
||||
)
|
||||
|
||||
func project(cfg config.Config) projection {
|
||||
return projection{
|
||||
models: cfg.Models,
|
||||
providers: cfg.Providers,
|
||||
}
|
||||
}
|
||||
|
||||
func setupTranscriber(cfg config.Config) {
|
||||
_, _ = transcription.New(cfg.Models, cfg.Providers, transcription.Options{})
|
||||
}
|
||||
`
|
||||
got := configReadOffenders([]byte(reverted))
|
||||
want := []string{"cfg.Models", "cfg.Providers", "cfg.Models", "cfg.Providers"}
|
||||
if strings.Join(got, ",") != strings.Join(want, ",") {
|
||||
t.Fatalf("configReadOffenders() = %v, want %v", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleCatchesInferredHolders covers the holder shapes the first
|
||||
// cut of this rule missed. It only saw a config.Config written out as a
|
||||
// parameter or var type, so a value reached through an inferred short
|
||||
// variable declaration ("cfg := doc.Config") or held in a struct field
|
||||
// ("h.cfg.Models") left the forbidden [models]/[providers] read intact while
|
||||
// the rule saw no holder to blame. Each case here fails red against that rule:
|
||||
// the live gate would have reported a pass with the violation still shipping.
|
||||
func TestConfigReadRuleCatchesInferredHolders(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
src string
|
||||
want []string
|
||||
}{
|
||||
{
|
||||
name: "short var decl from a Document's Config field",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
|
||||
func f(doc configuration.Document) {
|
||||
cfg := doc.Config
|
||||
_ = cfg.Models
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
{
|
||||
name: "inferred var without an explicit type",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
|
||||
func f(doc configuration.Document) {
|
||||
var cfg = doc.Config
|
||||
_ = cfg.Models
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
{
|
||||
name: "short var decl inherits config type from another holder",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func f(cfg config.Config) {
|
||||
other := cfg
|
||||
_ = other.Providers
|
||||
}
|
||||
`,
|
||||
want: []string{"other.Providers"},
|
||||
},
|
||||
{
|
||||
name: "config held in a struct field",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
type holder struct {
|
||||
cfg config.Config
|
||||
}
|
||||
|
||||
func f(h holder) {
|
||||
_ = h.cfg.Providers
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Providers"},
|
||||
},
|
||||
{
|
||||
name: "range variable over a slice of config",
|
||||
src: `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func f(cfgs []config.Config) {
|
||||
for _, cfg := range cfgs {
|
||||
_ = cfg.Models
|
||||
}
|
||||
}
|
||||
`,
|
||||
want: []string{"cfg.Models"},
|
||||
},
|
||||
}
|
||||
for _, tc := range cases {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
got := configReadOffenders([]byte(tc.src))
|
||||
if strings.Join(got, ",") != strings.Join(tc.want, ",") {
|
||||
t.Fatalf("configReadOffenders() = %v, want %v", got, tc.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
// TestConfigReadRuleAllowsThePermittedKeys proves the rule is not a blanket
|
||||
// ban on config access: the sections the PRD does permit keep passing, and a
|
||||
// nested chat field is not mistaken for a top-level one.
|
||||
func TestConfigReadRuleAllowsThePermittedKeys(t *testing.T) {
|
||||
const permitted = `package archiemessaging
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
func project(cfg config.Config) projection {
|
||||
return projection{
|
||||
telegram: cfg.Chat.Telegram,
|
||||
email: cfg.Chat.Email,
|
||||
gateway: cfg.Services.Get("gateway").Target,
|
||||
workDir: cfg.WorkDir,
|
||||
botUser: cfg.BotUser,
|
||||
healthURL: cfg.Health.URL(),
|
||||
}
|
||||
}
|
||||
`
|
||||
if got := configReadOffenders([]byte(permitted)); len(got) != 0 {
|
||||
t.Fatalf("configReadOffenders(permitted) = %v, want none", got)
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,48 @@
|
||||
// Command archie-prbench scores the PR reviewer on the Martian
|
||||
// Code-Review-Bench problems. See docs/prds/pr-review-agent.md, Verification.
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"fmt"
|
||||
"os"
|
||||
"os/signal"
|
||||
"strings"
|
||||
"syscall"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/prbench"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
)
|
||||
|
||||
func main() { os.Exit(run()) }
|
||||
|
||||
func run() int {
|
||||
var opts prbench.Options
|
||||
var problems string
|
||||
flag.StringVar(&opts.Config, "config", configuration.DefaultConfigPath(), "configuration file whose providers serve the reviewer and judge")
|
||||
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to rescore; omit to review live")
|
||||
flag.StringVar(&opts.ReviewModel, "review-model", "", "provider/model for the review role in live runs")
|
||||
flag.StringVar(&opts.ClassifyModel, "classification-model", "", "provider/model for the classification role in live runs")
|
||||
flag.StringVar(&opts.JudgeModel, "judge-model", "anthropic/claude-sonnet-4.6", "provider/model of the independent judge")
|
||||
flag.StringVar(&opts.Out, "out", "bin/prbench-results", "directory for per-problem results and summary.json")
|
||||
flag.StringVar(&opts.Resume, "resume", "", "reuse complete results from a previous run with the same models")
|
||||
flag.StringVar(&problems, "problems", "", "comma-separated problem ids (default: all)")
|
||||
flag.IntVar(&opts.Concurrency, "concurrency", 4, "problems judged at once")
|
||||
flag.Parse()
|
||||
opts.GitHubToken = os.Getenv("GH_TOKEN")
|
||||
if opts.GitHubToken == "" {
|
||||
opts.GitHubToken = os.Getenv("GITHUB_TOKEN")
|
||||
}
|
||||
if problems != "" {
|
||||
opts.Problems = strings.Split(problems, ",")
|
||||
}
|
||||
|
||||
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
|
||||
defer stop()
|
||||
if _, err := prbench.Run(ctx, opts, os.Stdout); err != nil {
|
||||
fmt.Fprintln(os.Stderr, "archie-prbench:", err)
|
||||
return 1
|
||||
}
|
||||
return 0
|
||||
}
|
||||
@@ -338,6 +338,7 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeConfigWithServiceListen(t, dir)
|
||||
@@ -355,7 +356,7 @@ func TestStateStoreRealProcessSmoke(t *testing.T) {
|
||||
// Combined task/event/capture view: a task, an event on that task, and an
|
||||
// unrelated capture written through one consumer, read back across all
|
||||
// three surfaces in a single pass (the dashboard/observability read path).
|
||||
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "")
|
||||
task, err := cl.EnqueueChatTask(ctx, "acme", "widget", "verify state store", "body", "implement", "", nil)
|
||||
if err != nil || task == nil {
|
||||
t.Fatalf("EnqueueChatTask = %+v, %v", task, err)
|
||||
}
|
||||
@@ -453,6 +454,7 @@ func TestStateStoreRealProcessDeadline(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
@@ -479,13 +481,14 @@ func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
|
||||
first := startStateStoreProcess(t, bin, cfg)
|
||||
s1 := dial(t, first.addr)
|
||||
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "")
|
||||
task, err := s1.EnqueueChatTask(t.Context(), "acme", "widget", "survive restart", "body", "implement", "", nil)
|
||||
if err != nil || task == nil {
|
||||
t.Fatalf("first EnqueueChatTask = %+v, %v", task, err)
|
||||
}
|
||||
@@ -525,6 +528,7 @@ func TestStateStoreRealProcessTokenProtectedCaptureStream(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
const token = "operator-secret-token"
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
@@ -572,6 +576,7 @@ func TestStateStoreRealProcessRemoteSurfaces(t *testing.T) {
|
||||
if testing.Short() {
|
||||
t.Skip("real-process smoke test builds and execs the binary; skip under -short")
|
||||
}
|
||||
t.Parallel()
|
||||
dir := t.TempDir()
|
||||
bin := buildBinary(t, dir)
|
||||
cfg := writeMinimalConfig(t, dir)
|
||||
|
||||
@@ -52,7 +52,7 @@ func recoveryFixture(t *testing.T) (string, *pgstore.TaskDB) {
|
||||
// seedTask writes one task so the database holds more than its settings.
|
||||
func seedTask(t *testing.T, st *pgstore.TaskDB, title string) {
|
||||
t.Helper()
|
||||
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", ""); err != nil {
|
||||
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", title, "body", "implement", "", nil); err != nil {
|
||||
t.Fatalf("seed task %q: %v", title, err)
|
||||
}
|
||||
}
|
||||
@@ -259,7 +259,7 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
|
||||
if !strings.Contains(stdout, controlplane.ModelRoleAssignmentsKind) {
|
||||
t.Errorf("rollback must name the resource it replayed; stdout = %q", stdout)
|
||||
}
|
||||
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
|
||||
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -269,7 +269,7 @@ func TestRecoveryRollbackReplaysTheRevisionThroughReplace(t *testing.T) {
|
||||
if resource.Version != 3 {
|
||||
t.Errorf("resource version = %d, want a new revision (3) rather than a rewrite of the old one", resource.Version)
|
||||
}
|
||||
history, err := st.ResourceHistory(t.Context(), controlplane.ModelRoleAssignmentsKind, 0)
|
||||
history, err := st.ResourceHistory(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind, 0)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -293,7 +293,7 @@ func TestRecoveryRollbackRestoresANamedRevision(t *testing.T) {
|
||||
if code != 0 {
|
||||
t.Fatalf("rollback exited %d: %s", code, stderr)
|
||||
}
|
||||
resource, err := st.Resource(t.Context(), controlplane.ModelRoleAssignmentsKind)
|
||||
resource, err := st.Resource(t.Context(), storecontract.DefaultOrgID, controlplane.ModelRoleAssignmentsKind)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -463,7 +463,7 @@ func storedResourceCount(t *testing.T, stdout string) int {
|
||||
// a silent no-op.
|
||||
func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
|
||||
t.Helper()
|
||||
current, err := st.Resource(t.Context(), kind)
|
||||
current, err := st.Resource(t.Context(), storecontract.DefaultOrgID, kind)
|
||||
expected := int64(0)
|
||||
if err == nil {
|
||||
expected = current.Version
|
||||
@@ -477,7 +477,8 @@ func seedResource(t *testing.T, st *pgstore.TaskDB, kind, value, label string) {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if _, err := st.PutResource(t.Context(), storecontract.ResourceWrite{
|
||||
Kind: kind, Value: encoded, Actor: label, Source: "test",
|
||||
OrgID: storecontract.DefaultOrgID,
|
||||
Kind: kind, Value: encoded, Actor: label, Source: "test",
|
||||
RequestID: fmt.Sprintf("%s-%d", label, expected+1), ExpectedVersion: expected,
|
||||
}); err != nil {
|
||||
t.Fatalf("seed resource %s: %v", kind, err)
|
||||
|
||||
@@ -131,11 +131,11 @@ func (f *fakeGateway) Cancel(context.Context, string) (messaging.ChatCancellatio
|
||||
|
||||
func (f *fakeGateway) SetPersona(context.Context, string, string) (bool, error) { return false, nil }
|
||||
|
||||
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action) (messaging.TaskActionResult, error) {
|
||||
func (f *fakeGateway) ApplyTaskAction(context.Context, string, int64, taskstate.Action, taskactions.ActionPayload) (messaging.TaskActionResult, error) {
|
||||
return messaging.TaskActionResult{}, nil
|
||||
}
|
||||
|
||||
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action) (messaging.TaskActionResult, error) {
|
||||
func (f *fakeGateway) ApplyOperatorTaskAction(_ context.Context, actor taskactions.Actor, id int64, action taskstate.Action, _ taskactions.ActionPayload) (messaging.TaskActionResult, error) {
|
||||
f.mu.Lock()
|
||||
defer f.mu.Unlock()
|
||||
f.actions = append(f.actions, fmt.Sprintf("%d:%s", id, action))
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"os"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/archied"
|
||||
@@ -15,5 +16,10 @@ func main() {
|
||||
if archied.IsSetupArgs(args) {
|
||||
os.Exit(archied.RunSetup(args[1:], os.Stdin, os.Stdout, os.Stderr))
|
||||
}
|
||||
// The access recovery command runs before the daemon's flags are parsed:
|
||||
// it is a State Store host operation, not a daemon run.
|
||||
if archied.IsAccessResetArgs(args) {
|
||||
os.Exit(archied.RunAccessReset(context.Background(), args[2:], os.Stderr))
|
||||
}
|
||||
os.Exit(archied.Run())
|
||||
}
|
||||
+36
-4
@@ -34,6 +34,8 @@ label = "archie"
|
||||
bot_user = "vectis-labs-archie"
|
||||
# 0 switches the cap off; omit the key to take the built-in default (400).
|
||||
diff_cap_lines = 400
|
||||
# org = "acme" # empty means the default org (a single-operator install's one identity)
|
||||
# granted_credentials = ["openai"] # credential@1 services the root identity may resolve (see [containers.credentials])
|
||||
|
||||
# how many operator-triggered retries a parked task gets
|
||||
# before it moves to dead (global default; set per-repo to
|
||||
@@ -75,6 +77,8 @@ token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN" }
|
||||
# name = "personal" # required; namespaces logs/events/NATS subjects
|
||||
# bot_user = "your-bot" # required
|
||||
# forge = { type = "github", host = "https://github.com", token = { engine = "env", key = "ARCHIE_GITHUB_TOKEN_PERSONAL" } }
|
||||
# org = "acme" # empty inherits the shared org (empty = default)
|
||||
# granted_credentials = ["openai"] # credential@1 services this identity may resolve (see [containers.credentials])
|
||||
|
||||
[dispatch]
|
||||
# Can be of "assignee", "label", or "either"
|
||||
@@ -111,6 +115,11 @@ builder = "openai/gpt-5.4"
|
||||
# (curators first). Unset, or a credential that fails to resolve, degrades
|
||||
# to the capability reporting unavailable -- archied still starts.
|
||||
# embedding = "openai/text-embedding-3-small"
|
||||
# `transcription` is optional: it turns Telegram voice notes into text before
|
||||
# the turn is dispatched, behind a "[voice transcription]" marker. Read by
|
||||
# archie-messaging. Unset, or a provider that does not resolve, leaves the
|
||||
# voice note as its media placeholder -- the turn still runs.
|
||||
# transcription = "openai/whisper-1"
|
||||
|
||||
[providers.openai]
|
||||
class = "openai"
|
||||
@@ -308,8 +317,9 @@ listen = "127.0.0.1:8484"
|
||||
|
||||
[budgets]
|
||||
max_steps = 60
|
||||
wall_clock = "30m"
|
||||
wall_clock = "30m" # one agent call
|
||||
gate_max_failures = 5
|
||||
task_wall_clock = "4h" # a whole task run; keep containers.max_uptime at or above it
|
||||
|
||||
# Services selects contract adapters at composition time (see
|
||||
# docs/prds/state-store-contract.md).
|
||||
@@ -437,6 +447,15 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
|
||||
# volume_ttl = "72h" # max age for persistent repo volumes and Git clone caches
|
||||
# pull_policy = "missing" # "missing" or "always"
|
||||
#
|
||||
# A private registry needs a credential the daemon sends on pull (an
|
||||
# anonymous pull always answers 401 there, whatever the policy). The value is
|
||||
# a Docker registry.AuthConfig JSON document -- {"username":"bot","password":"..."}
|
||||
# ("identitytoken"/"registrytoken" are alternatives; "serveraddress" is
|
||||
# optional and defaults to the image's registry). Unset means anonymous pulls,
|
||||
# exactly as before this key existed; a reference that cannot be resolved
|
||||
# warns and pulls anonymously rather than failing the daemon.
|
||||
# registry_auth = { engine = "env", key = "ARCHIE_REGISTRY_AUTH" }
|
||||
#
|
||||
# Agent profiles a workflow selects with `profile: <name>`. A workflow that
|
||||
# names none runs under [containers].image with every tool.
|
||||
# Once the State Store holds container policies, edit profiles in the
|
||||
@@ -444,6 +463,22 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
|
||||
# [containers.profiles.network-investigator]
|
||||
# image = "archie-agent-net:local" # docker compose build agent-net; empty uses [containers].image
|
||||
# tools = [] # allowlist over MCP, script and plugin tools; empty allows all
|
||||
# A Kit profile runs every agent stage on an external CLI packaged as a Kit v3
|
||||
# image: one workload Kit or published Kit set (which merges a workload with
|
||||
# its mixins), pinned by digest.
|
||||
# [containers.profiles.claude]
|
||||
# kit = "docker/claude-code-kit@sha256:<digest>"
|
||||
# adapter = "claude-code" # claude-code, codex, pi, omp or copilot; empty runs without capture tools or usage
|
||||
#
|
||||
# Credential bindings map a Kit's credential@1 service name to a secret. A
|
||||
# binding alone grants nothing -- an identity resolves it only when its own
|
||||
# org matches and the service is in its granted_credentials (see
|
||||
# [[identities]] above). Once the State Store holds it, edit bindings in the
|
||||
# dashboard (Settings, Advanced); a stored set replaces the file's.
|
||||
# [[containers.credentials]]
|
||||
# service = "openai"
|
||||
# org = "acme" # empty means the default org
|
||||
# secret = {engine = "env", key = "OPENAI_API_KEY"}
|
||||
|
||||
# At least one [[repos]] entry is required before archied will poll
|
||||
# anything -- it is deliberately left commented rather than shipped active:
|
||||
@@ -475,9 +510,6 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
|
||||
# # [containers].max_concurrency globally.
|
||||
# # persistent_storage = true # reuse a per-repo Docker volume and Git object cache until volume_ttl
|
||||
# # max_retries = 5 # per-repo override of the global max_retries above
|
||||
# # review_enabled = true # run a fresh adversarial reviewer (no path to the implementer's
|
||||
# # context) after gates pass and before the PR opens. Default false --
|
||||
# # an uncalibrated reviewer that cries wolf is worse than no review.
|
||||
|
||||
# ── Tools ───────────────────────────────────────────────────────────────────
|
||||
# Limits on what a tool may return. These bound how much of the context window
|
||||
|
||||
@@ -125,7 +125,8 @@ func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) {
|
||||
// Naming each one with its reason keeps an omission a decision rather than an
|
||||
// oversight -- which is exactly how archied's channels were lost.
|
||||
var unpackagedCommands = map[string]string{
|
||||
"archie-agent": "runs only inside the Docker image build-and-push publishes, never as a host binary",
|
||||
"archie-agent": "runs only inside the Docker image build-and-push publishes, never as a host binary",
|
||||
"archie-prbench": "a developer benchmark run from the repository with task bench:prreview",
|
||||
}
|
||||
|
||||
// cliOnlyCommands ship in the zip but must never be restarted by the updater:
|
||||
|
||||
@@ -1,6 +1,29 @@
|
||||
# Adversarial self-review
|
||||
|
||||
Archie runs a fresh adversarial review of the diff before it opens a pull
|
||||
> **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system
|
||||
> that no longer exists in the tree.**
|
||||
>
|
||||
> `d73e0748` ("remove the superseded adversarial-self-review system") deleted the
|
||||
> stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`
|
||||
> and `StageReview` are gone from `internal/domain/workflow`, so everything under
|
||||
> "Contract" below describes types that cannot be found.
|
||||
>
|
||||
> The authority is `docs/prds/pr-review-agent.md`, which says so itself: it
|
||||
> "supersedes the reviewer executor and blocking rule in
|
||||
> `docs/architecture/adversarial-review.md`". archied now runs its PR review
|
||||
> pipeline before it opens a pull request; there is no separate adversarial
|
||||
> self-review pass and no `repo.review_enabled` setting.
|
||||
>
|
||||
> The page is kept rather than deleted because PRDs link to it
|
||||
> (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,
|
||||
> `docs/prds/pr-review-agent.md`). Read it as history.
|
||||
>
|
||||
> One section is stale in a second, older way: "Operator-triggered review" below
|
||||
> describes the synchronous `review_pr` (fetch the head, snapshot it, run the
|
||||
> reviewer, return findings), which `archie-core-afbk.14` replaced with a queued
|
||||
> pr-review task.
|
||||
|
||||
Archie ran a fresh adversarial review of the diff before it opened a pull
|
||||
request, so a PR arrives with a findings record rather than an unreviewed
|
||||
claim. The reviewer provably cannot see the implementer's context: it reviews a
|
||||
`.git`-free snapshot of the committed tree, not the worktree, the commit
|
||||
|
||||
@@ -178,13 +178,15 @@ The current `store.Task` lifecycle uses:
|
||||
|
||||
```text
|
||||
queued -> running
|
||||
running -> waiting_human | pr_open | merged | parked | closed_wont_do
|
||||
running -> queued (crash recovery) | waiting_human | pr_open | completed | parked | closed_wont_do
|
||||
waiting_human -> queued | closed_wont_do
|
||||
parked -> queued | dead
|
||||
pr_open -> merged | rejected
|
||||
running after crash -> queued
|
||||
```
|
||||
|
||||
`merged` is reached only from `pr_open`. `completed` is terminal: it means a
|
||||
workflow that opens no pull request finished its work.
|
||||
|
||||
Workflows select and sequence deterministic and agent-run stages. Implement,
|
||||
TDD, feasibility, and bootstrap are current Workflow definitions.
|
||||
Every WorkflowExecution is handed wholesale over core NATS to a task-scoped
|
||||
@@ -309,8 +311,6 @@ implemented in different packages:
|
||||
|
||||
## Current workflow-feature hazards
|
||||
|
||||
- There is no enforced WorkflowExecution state machine. `Store.Transition`
|
||||
ignores the supplied `from` state when updating the row.
|
||||
- State update and transition-history insertion are separate operations, so
|
||||
state and audit can diverge.
|
||||
- Callers frequently discard persistence and transition errors.
|
||||
@@ -325,8 +325,10 @@ implemented in different packages:
|
||||
synthetic issue numbers.
|
||||
- Repository labels currently select workflows and mirror task state, coupling
|
||||
domain transitions to forge presentation.
|
||||
- Failure generally becomes `parked`, but failure classification and
|
||||
retryability are not represented explicitly.
|
||||
- Failure generally becomes `parked`, and the failure's classification is no
|
||||
longer implicit: the persisted execution record carries the class the code
|
||||
that parks recorded (the vocabulary lives in `internal/taskstate`), and
|
||||
retryability is read from it rather than inferred from reason text.
|
||||
- Generic observability events are emitted alongside state changes rather than
|
||||
being the authoritative domain events.
|
||||
|
||||
|
||||
@@ -334,6 +334,34 @@ Two properties matter to anyone changing this area:
|
||||
ones. Workflow execution budgets arrive on a watch rather than in a resource
|
||||
query, so boot records the last published settings and the reload re-applies
|
||||
them from there.
|
||||
- **Live kinds arrive on a watch.** Provider settings, model role assignments,
|
||||
repository policies, scheduling policy, tool settings, plugin settings,
|
||||
review settings, channel settings and container runtime policies are
|
||||
`ApplyMode: live`: the daemon keeps a watch per kind
|
||||
(`boot.startRuntimeResourceWatches`, `runtimeResourceKinds`) and, on a new
|
||||
version, re-runs `boot.runtimeConfig` over the published snapshot and
|
||||
republishes through `config.Holder`. A candidate the layered document cannot
|
||||
run is refused before it is published — last-known-good keeps running and
|
||||
the refusal is reported through apply status. Tool settings reconcile in this
|
||||
process: the daemon diffs the stored MCP server set against the running
|
||||
providers — connecting added servers, disconnecting removed ones and
|
||||
reconnecting changed ones while an unchanged server keeps running — and
|
||||
rebuilds the `web_fetch` and `minimax` entries, whose config was captured at
|
||||
construction (`boot.reconcileToolSettings`). Container runtime policies
|
||||
join the live set because their consumers re-read the published config: the
|
||||
container pool reads image, pull policy, network, max uptime and concurrency
|
||||
cap on every acquire and the daemon resizes its running task dispatcher from
|
||||
the same publish; the fields the document cannot carry, `registry_auth`
|
||||
above all, stay boot-resolved and remain requires-restart. A kind whose
|
||||
consumer lives in another process reconciles there too: `archie-messaging`
|
||||
re-reads the stored channel settings on the apply-status restamp interval
|
||||
and restarts only the channel whose transport settings changed, while the
|
||||
listen addresses it has bound and the set of channels it composed stay
|
||||
process bindings that take effect on restart. A kind joins the live list
|
||||
only with a consumer that re-reads it; one whose startup-built consumer
|
||||
never does stays restart-required, and the model/provider half of the live
|
||||
set also rebuilds the gateway chat runtime's provider set and the chat model
|
||||
list the chat surfaces offer.
|
||||
|
||||
## Completion criteria
|
||||
|
||||
|
||||
@@ -202,13 +202,13 @@ actually owned, not by where it used to be built:
|
||||
|
||||
| Seam | Resolution |
|
||||
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never stamps or infers a build version; `cmd/archie-messaging` deliberately takes no version ldflags, so it cannot report a partial upgrade as a matched one. |
|
||||
| `Version` | Sourced from the Gateway via `ChatSnapshot.Version`. The Messaging Service never renders its own build into `/version`; `cmd/archie-messaging` does carry a `buildinfo` release stamp (added by `archie-core-k94o`, see the amendment below) for the updater's skew check and update verification, but `/version` still shows the Gateway's block so a partially upgraded deployment cannot report itself as matched. |
|
||||
| `Updates` (`/update`) | Built in the Messaging Service from `[chat.telegram].update_check_command` / `update_install_command` — its own configuration. `Enrich` is dropped: `componentInstallTypeEnricher` reads `[nats]`, which this service must not decode, so the check command's own reported install type stands unmodified. |
|
||||
| `UpdateReportPath` | A local state file under `work_dir`, keyed by the same `sha256(bot_user)[:8]` scheme the daemon used, so a pending report is found rather than written afresh. |
|
||||
| `ReleaseAnnouncements` | **Deliberately left nil**, for the same reason as `RunningVersions`. `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only versions this service can obtain are the Gateway's own build stamps, not archied's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
|
||||
| `ReleaseAnnouncements` | **Still left nil**, but no longer for the `RunningVersions` reason (that seam now self-reports — see the amendment below). `releaseannounce.Announcer` announces nothing unless each `Component` carries a parseable version, and the only version this process can vouch for is its own daemon-release stamp, not the agent's. Wiring the announcer without them yields a no-op that reads as configured, so it stays unwired until component self-reporting exists. |
|
||||
| `SetShowToolCalls` | Projected from `[chat].show_tool_calls`. |
|
||||
| `Reload` | Local: re-resolves the token and allowlist from this service's own config file and overlay. Reload was never a daemon fact. |
|
||||
| `RunningVersions` | **Deliberately left nil.** It exists to turn an installer's claim into a checked one, and only a component's own compiled-in build can vouch for it. The Messaging Service knows neither archied's build nor the observed archie-agent version (`daemon.AgentStatus`), and the Gateway's own `gatewayVersion` is a different binary's stamp — reporting it as the daemon's would manufacture exactly the false success the check exists to catch. Update reports therefore relay as unverified claims until a component self-report contract exists. |
|
||||
| `RunningVersions` | **Wired from this process's own release stamp** (`archie-core-ot33`; see the amendment below). `archie-messaging` is one of the processes in the archied release set (the installer's `GATEWAY_SERVICES`), built from the same `archied/v*` tag and stamped with `buildinfo.Version` by every build site, so its compiled-in build is evidence that the release the installer claims actually reached this host. It reports `daemon = buildinfo.Version` and reports nothing for `agent` (task-scoped, observed only through `daemon.AgentStatus`), leaving the agent Unverified. The Gateway's rendered block is deliberately not used: that is a different process's stamp. |
|
||||
| `Dangerous` | Stays nil. No daemon composition ever set it; `/rollback` and `/stop` reported "not configured" before the extraction and still do. |
|
||||
|
||||
The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
|
||||
@@ -217,6 +217,22 @@ The Messaging Service consequently reads `work_dir`, `bot_user`, `[chat]` and
|
||||
polls from outside to confirm an update came back up; the rest of the PRD's
|
||||
prohibition list is untouched.
|
||||
|
||||
**Amended 2026-10-02 (`archie-core-ot33`, Telegram `RunningVersions`).** The
|
||||
2026-09-19 decision left `RunningVersions` nil because it judged this process
|
||||
could obtain only another binary's stamp. That was true when written and stopped
|
||||
being true three days later: `ec0f17a7` (`archie-core-k94o`) gave every host
|
||||
binary, `archie-messaging` included, a `buildinfo.Version` self-report so the
|
||||
updater could detect per-binary skew. `cmd/archie-messaging` now registers
|
||||
`buildinfo`'s `-version`, and every build site (`install.sh`,
|
||||
`scripts/archie-update-install`, `.github/workflows/deploy.yml`, `Taskfile.yml`)
|
||||
stamps it with the same `archied/v*` release as the rest of `GATEWAY_SERVICES`.
|
||||
The messaging process therefore vouches for the `daemon` component from
|
||||
`buildinfo.Version` — its own compiled-in build, never the Gateway's rendered
|
||||
block — and reports nothing for the agent. A relayed update report can now
|
||||
confirm the daemon and still names the agent as unchecked, while a binary the
|
||||
update did not replace reads as drift. `ReleaseAnnouncements` stays nil: it needs
|
||||
a version for every component, and this process can vouch only for itself.
|
||||
|
||||
**Phase 4 messaging severance: what must move, and the decision the PRD does
|
||||
not cover (2026-09-22, `archie-core-1ng1`).** The PRD's deletion gate cannot
|
||||
pass today. `cmd/archie-messaging/architecture_test.go` does not exist, and the
|
||||
@@ -410,7 +426,8 @@ The migration must decide:
|
||||
|
||||
- Workflow definition and version persistence;
|
||||
- the smallest accepted-work-request contract consumed from Work Intake;
|
||||
- the enforced WorkflowExecution state machine;
|
||||
- the enforced WorkflowExecution state machine (proposed in
|
||||
`docs/prds/execution-tree-state-machine.md`);
|
||||
- atomic state and domain-event persistence;
|
||||
- migration of existing task rows and transition history;
|
||||
- disposition of current skill, Yaegi, and stage-plugin implementations;
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
# archied -- design notes
|
||||
|
||||
Archie is a resident daemon that keeps personal projects moving: it polls GitHub for issues labelled
|
||||
`archie`, works each one in an isolated fresh-clone worktree through a routed **workflow**, and opens a
|
||||
pull request for human review. Sam reviews and merges; the machine grinds in between.
|
||||
|
||||
Guiding principle: **environmental constraints over prompt instructions.** Agents don't get asked nicely
|
||||
to write good code -- the quality gate (vet/build/test/lint, configurable per repo and per workflow stage)
|
||||
refuses to let a run succeed until it passes. The gate mechanics live in `ai-sdk/agentloop`; this repo
|
||||
owns orchestration only.
|
||||
|
||||
## Workflows, not a pipeline
|
||||
|
||||
`internal/workflow` is the engine: a Workflow is an ordered list of stages over a shared TaskContext;
|
||||
stages are deterministic steps (worktree, gate, diff cap, PR, comments -- the shared step library in
|
||||
`steps.go`) or agent stages (`agentloop.Run` with a stage-specific mission/toolset/gate). Routing is
|
||||
label-driven (`bug` → tdd, `feature` → feasibility, default → implement), refinable by an LLM triage
|
||||
stage. Adding a workflow must never require touching the engine or reimplementing steps.
|
||||
|
||||
Planned workflows:
|
||||
|
||||
- **bootstrap** (registered): deterministic marker-file PR proving invites/clone/push/PR plumbing.
|
||||
- **implement**: planner (read-only agentloop, plan posted to the issue) → builder (full toolset,
|
||||
repo gate) → diff cap → PR.
|
||||
- **tdd** (bugfixes): analyse → problem surface → write failing repro tests (gate stage with
|
||||
`ExpectFailure`) → fix (gate: suite passes) → PR.
|
||||
- **feasibility** (features): read-only analysis → roadmap fit → won't-do close with reasons, or
|
||||
plan + PRD → email Sam → `waiting_human` → LLM-judged reply → hand off to implement.
|
||||
|
||||
## Task lifecycle
|
||||
|
||||
`queued → running(workflow:stage) → waiting_human | pr_open → merged | parked | rejected | closed_wont_do`
|
||||
|
||||
SQLite (`internal/store`), WAL, one row per issue with a transitions audit table. Crash recovery:
|
||||
`running` tasks re-queue on startup with attempt++. Parks are never silent -- every park comments on the
|
||||
issue with the reason and gate output.
|
||||
|
||||
## Security posture
|
||||
|
||||
- Fine-grained PAT on the bot account only (Contents RW, PRs RW, Issues RW, Metadata R), via
|
||||
`ARCHIE_GITHUB_TOKEN`; git auth through an askpass helper so the token stays out of argv and
|
||||
`.git/config`.
|
||||
- The model never runs git: `internal/worktree` owns all repo operations deterministically.
|
||||
- Agent tools are jailed to the task worktree (toolkit path jail); intended deployment is a dedicated
|
||||
Incus container so the blast radius is environmental, not prompt-negotiated.
|
||||
@@ -1,519 +0,0 @@
|
||||
# archie-core v2 Architecture -- Design Document
|
||||
|
||||
**Author:** Archie
|
||||
**Date:** 2026-07-21 (implementation status updated 2026-07-22)
|
||||
**Status:** Final (substantially implemented -- remaining aspirational items are pluggable storage backends and Layer 2 daemon plugin loader)
|
||||
|
||||
---
|
||||
|
||||
## 0. Implementation status (as of 2026-07-22, updated 2026-07-22)
|
||||
|
||||
This document describes a target end state. The table below is the ground truth; read it before treating any section as already built.
|
||||
|
||||
| Area | Status | What actually exists today (post-e4d11b1) |
|
||||
| --------------------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Daemon/agent binary split | **Implemented** | `cmd/archied` and `cmd/archie-agent` both exist. `archie-agent` is a 189-line NATS-connected per-task worker that subscribes to task subjects, runs the full multi-stage workflow, and reports results. Workflow routing and sequencing (`workflow.Route`, `workflow.Run`) now run inside the agent, not the daemon. Three agent modes: `inprocess`, `subprocess`, `nats`. |
|
||||
| Sandbox / "daemon never runs untrusted code" | **Partial** | Default mode is still `inprocess` for development. Docker sandbox mode (`agent.mode = "nats"` + `containers.enabled = true`) runs each task in an ephemeral Docker container with workspace bind-mounted at `/workspace`. `internal/container/pool.go` manages full lifecycle: pull, create, start, release, orphan recovery. Daemon dispatch and container lifecycle both enforce `max_concurrency`; same-repo tasks remain serialised. |
|
||||
| NATS / JetStream messaging | **Implemented** | `internal/nats/client.go`: JetStream connect, stream creation (WorkQueue retention, file storage), pull consumer (durable, ack-wait 5min, max-deliver 3, dedup by Msg-Id), `PublishTask`, `Fetch`, `NewReplyInbox`, and optional token authentication. Subject hierarchy lives in `internal/nats/subjects.go`; `internal/agentexec/nats.go` implements request/reply agent execution. |
|
||||
| Docker container sandbox | **Implemented** | `internal/container/pool.go` (210 lines): Docker API client, image pull (always/missing/never), container create with workspace bind mount, start, release (stop+remove), orphan recovery on daemon restart. `Dockerfile` at repo root builds archie-agent fat image. `[containers]` config block: enabled, image, max_concurrency, max_uptime, pull_policy. `agent.mode = "nats"` required when containers enabled. |
|
||||
| `/data/` volume, `task.json` | **Partial** | `container.WriteTaskJSON()` writes task payload to the worktree before container acquire. The container pool bind-mounts the isolated task worktree at `/data/worktree`; configured repos also receive a persistent `/data/repo` Docker volume. Task payload travels over NATS as the primary channel; `/data/task.json` is a boot-time brief for the container. |
|
||||
| `[containers]` config block | **Implemented** | `ContainerConfig` struct in config.go: enabled, image, max_concurrency, max_uptime, pull_policy. Validated on load. |
|
||||
| Yaegi extensibility (gates, custom stages, skill scripts) | **Implemented** | Three surfaces: `.archie/gate.go`, `.archie/stages/*.go`, skill scripts via `run_go_script` tool. All in-process via Yaegi with generated symbol tables and panic recovery. Full detail in `docs/prds/yaegi-plugin-system.md`. |
|
||||
| Layer 1: skill-bundled plugins | **Implemented** | `skill.DiscoverPlugins()` scans `.agents/skills/<name>/plugins/*.go`. `skill.Plugin.Run()` executes them via Yaegi. `skillbuild.BuildWorkflow()` constructs `workflow.Workflow` from plugin-defined stages. `TaskContext.SkillPlugins` makes them available during stage execution. `skillbuild.BuildRegistry()` replaces the hardcoded `workflow.Registry` with catalogue-driven construction -- skills define workflows, plugins define stages. |
|
||||
| Layer 2: core daemon plugins | **Partial** | `internal/plugin/plugin.go`: `Plugin` interface (`Name()`, `Version()`), `Registry` type, `LoadDir()` using Yaegi to interpret `.go` files. No `~/.config/archie/plugins/` loader wired into `cmd/archied/main.go` yet -- the interface and registry exist but are not connected to the daemon's startup. |
|
||||
| Skills (agentskills.io spec) | **Implemented** | `internal/skill/skill.go`: parses SKILL.md YAML frontmatter, discovers skills from `.agents/skills/*/SKILL.md`, extracts body. Skills follow `archie-wf-*` naming convention. Progressive disclosure: `Catalog()` (Tier 1 -- frontmatter-only scan, ~100 tokens per entry), `LoadBody()` (Tier 2 -- full body on activation), `Discover()` (Tier 3 -- full parse with plugins). `metadata.archie.workflow` declares skill→workflow affinity. `skill.SkillForWorkflow()` is catalogue-driven, no hardcoded maps. `skillbuild.BuildRegistry()` constructs the daemon's workflow registry from the catalogue. |
|
||||
| Worktree/repo management | **Implemented** | Each issue keeps an isolated worktree. Repos with `persistent_storage = true` use a per-repo bare Git object cache to avoid repeated full network clones; caches and Archie-owned repo volumes expire via `containers.volume_ttl`. |
|
||||
| Config schema | **Closer to sec.4** | `[agent]` block: mode (inprocess/subprocess/nats) + command + env. `[nats]` block: url + token_env. `[containers]` block: enabled, image, max_concurrency, max_uptime, volume_ttl, pull_policy. Per-repo `persistent_storage` is supported as a boolean Docker-volume/Git-cache opt-in. |
|
||||
|
||||
**Net read post-1dca419:** Phases 1, 2, and 3 are substantially implemented. NATS, Docker sandbox, skill parsing, skill-bundled plugins (Layer 1), skill progressive disclosure, and catalogue-driven workflow construction (`skillbuild.BuildRegistry()`) all landed. The remaining aspirational work is Layer 2 daemon plugin loader (interface exists, not wired), pluggable storage backends, and per-worktree dynamic registry augmentation.
|
||||
|
||||
---
|
||||
|
||||
## 1. Binary split
|
||||
|
||||
### archied (daemon)
|
||||
|
||||
The resident orchestrator. Owns:
|
||||
|
||||
- **Task discovery** -- polls configured forges for issues labelled `archie` (or configured label)
|
||||
- **NATS publishing** -- publishes discovered tasks to JetStream subjects
|
||||
- **Container lifecycle** -- spawns Docker containers, kills them after grace period, cleans up volumes
|
||||
- **Message gatekeeping** -- reads agent responses from NATS, reviews them, forwards to human channels
|
||||
- **Core plugin loading** -- loads Yaegi `.go` plugins from `~/.config/archie/plugins/` at startup
|
||||
- **Web dashboard** -- SSE observability endpoint
|
||||
- **Human communication** -- issue comments, labels, PR management, notify webhook
|
||||
|
||||
The daemon never runs untrusted code. Agent containers are the sandbox boundary.
|
||||
|
||||
> **Target state, not current state.** Today, default `[agent] mode = "inprocess"` runs the agent loop (and therefore
|
||||
> all LLM-directed tool calls) directly inside `archied`. `subprocess` mode exists (`internal/agentexec/subprocess.go`)
|
||||
> but its own code comment says: _"This is not an OS security boundary: a same-UID subprocess may still access
|
||||
> daemon-readable host resources."_ This claim becomes true only once the Docker sandbox (sec.4, Phase 2) lands.
|
||||
|
||||
### archie-agent (ephemeral container)
|
||||
|
||||
Spawned per task. Lives in a Docker container. Receives its brief via `/data/task.json` (volume-mounted). Owns:
|
||||
|
||||
- **Workflow execution** -- runs the routed workflow stages (implement, tdd, feasibility, bootstrap)
|
||||
- **LLM orchestration** -- via `ai-sdk/agentloop`, the agent drives LLM calls
|
||||
- **Bundled plugin loading** -- loads Yaegi `.go` plugins from the skill's `plugins/` directory and the `/data/plugins/`
|
||||
volume
|
||||
- **Skill loading** -- reads `.agents/skills/archie-wf-*` from the worktree, follows the agentskills.io progressive
|
||||
disclosure model
|
||||
- **NATS reporting** -- publishes results to `archie.agent.<task_id>.response`, system messages to
|
||||
`archie.agent.<task_id>.system`
|
||||
|
||||
Lifecycle: spawn -> load task -> run workflow -> report -> wait for follow-ups (grace period) -> killed by daemon.
|
||||
|
||||
> **Target state, not current state.** `cmd/archie-agent/main.go` today is 28 lines: read one JSON `Invocation` from
|
||||
> stdin, run one stage via `agentexec.ServeOne`, write one `Response` to stdout, exit. It is a single-stage subprocess
|
||||
> worker invoked by `archied`'s `SubprocessRunner`, not a persistent per-task container process. Workflow routing and
|
||||
> multi-stage sequencing (`workflow.Route`, `workflow.Run`) run entirely inside `archied`
|
||||
> (`internal/daemon/daemon.go:process()`), not inside archie-agent. There is no `/data/task.json`, no bundled-plugin
|
||||
> loading, no `.agents/skills/archie-wf-*` discovery, and no NATS reporting -- see sec.0, sec.2, sec.3, sec.5. The
|
||||
> existing `agentexec.Runner` interface (`InProcessRunner`/`SubprocessRunner`) is, however, deliberately shaped so a
|
||||
> future container-backed runner can be a drop-in swap without changing workflow orchestration.
|
||||
|
||||
---
|
||||
|
||||
## 2. NATS subject hierarchy
|
||||
|
||||
> **Status: aspirational, zero code.** No NATS/JetStream dependency exists anywhere in `go.mod` or the codebase. Today,
|
||||
> task discovery is GitHub-poll-driven (`daemon.Run()` ticks on `PollInterval`, calls `pollIssues()`), distribution is a
|
||||
> SQLite `tasks` table used as a FIFO queue (`store.ClaimNext` atomically claims the oldest `queued` row), and
|
||||
> results/status flow through an in-process `internal/events.Bus` (Go channels, multi-subscriber fan-out,
|
||||
> drop-on-overflow) that already feeds both a SQLite `events` table and the SSE dashboard. `events.Bus` has roughly the
|
||||
> right shape to become the NATS publish path -- same `Event` schema, swap the transport -- which meaningfully de-risks
|
||||
> this phase, but it is currently single-process only with no network transport.
|
||||
|
||||
### Task distribution
|
||||
|
||||
```events
|
||||
archie.task.bug -- TDD workflow tasks
|
||||
archie.task.feature -- Feasibility workflow tasks
|
||||
archie.task.default -- Implement workflow tasks
|
||||
archie.task.bootstrap -- Bootstrap diagnostic tasks
|
||||
```
|
||||
|
||||
Daemon publishes to the appropriate subject based on label routing. Agents subscribe to subjects they're configured to
|
||||
handle.
|
||||
|
||||
### Agent communication (per-task)
|
||||
|
||||
```events
|
||||
archie.agent.<task_id>.response -- Agent output: summaries, PR bodies, results. Daemon reviews before human delivery.
|
||||
archie.agent.<task_id>.system -- Internal comms: log dumps, data requests, health, PII warnings. Never forwarded unprompted.
|
||||
archie.agent.<task_id>.request -- Optional: agent requests additional data from the daemon.
|
||||
```
|
||||
|
||||
The daemon gatekeeps the response channel -- no agent output reaches a human without daemon review.
|
||||
|
||||
### JetStream durability
|
||||
|
||||
Tasks are published with JetStream persistence. On agent container failure, NATS redelivers. The daemon doesn't need
|
||||
retry logic -- NATS handles it.
|
||||
|
||||
---
|
||||
|
||||
## 3. Persistent volume
|
||||
|
||||
> **Status: partially implemented.** `task.json`, `/data/worktree`, optional per-repo `/data/repo` Docker volumes,
|
||||
> ecosystem cache volumes, and TTL cleanup exist. Task worktrees remain isolated by issue, while configured repos use a
|
||||
> per-repo bare Git object cache to seed clones without repeating full network transfers. `session.jsonl`,
|
||||
> `memory.jsonl`, and staged plugin volumes remain unimplemented.
|
||||
|
||||
### /data/ layout
|
||||
|
||||
```tree
|
||||
/data/
|
||||
|---- task.json # Full task payload (owner, repo, issue, title, body, labels, workflow)
|
||||
|---- session.jsonl # Agent session transcript (appended per stage)
|
||||
|---- memory.jsonl # Optional: cross-session memory (persisted per project)
|
||||
|---- plugins/ # Bundled plugins from the skill (daemon-staged, overrides worktree)
|
||||
|---- worktree/ # Read-only mount of the cloned repo (managed by daemon)
|
||||
```
|
||||
|
||||
### task.json
|
||||
|
||||
```json
|
||||
{
|
||||
"id": 42,
|
||||
"owner": "sam",
|
||||
"repo": "example-service",
|
||||
"issue_number": 170,
|
||||
"title": "Add /copy command for messages and session transcripts",
|
||||
"body": "...",
|
||||
"labels": ["enhancement", "archie"],
|
||||
"workflow": "implement",
|
||||
"branch": "archie/issue-170",
|
||||
"plan": "",
|
||||
"config": {
|
||||
"base_branch": "main",
|
||||
"gate": [
|
||||
["gofumpt", "-w", "."],
|
||||
["go", "vet", "./..."],
|
||||
["go", "test", "-race", "./..."]
|
||||
],
|
||||
"protect": ["_templ.go"],
|
||||
"ecosystem": "go",
|
||||
"test_glob": "*_test.go"
|
||||
},
|
||||
"nats": {
|
||||
"url": "nats://archie-core:4222",
|
||||
"response_subject": "archie.agent.42.response",
|
||||
"system_subject": "archie.agent.42.system",
|
||||
"request_subject": "archie.agent.42.request"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The daemon writes `task.json` to the volume before the container starts. The agent reads it on boot.
|
||||
|
||||
### Volume lifecycle
|
||||
|
||||
- Created on task start (persistent per-repo if configured)
|
||||
- Kept until terminal outcome (`pr_open`, `merged`, `rejected`, `closed_wont_do`) OR TTL expiry
|
||||
- Parked tasks keep their volume for inspection and requeue reuse
|
||||
- Cleanup is a daemon responsibility
|
||||
|
||||
---
|
||||
|
||||
## 4. Container management
|
||||
|
||||
> **Status: implemented with a flatter schema than the sketch below.** `[containers]` configures the image,
|
||||
> concurrency, uptime, pull policy, and persistent-storage TTL. `Repo.PersistentStorage` opts a repository into the
|
||||
> per-repo Docker volume and Git object cache. The backend abstraction exists in `internal/storage`; additional storage
|
||||
> types and structured per-backend configuration remain future work.
|
||||
|
||||
### Daemon config
|
||||
|
||||
```toml
|
||||
# Container lifecycle
|
||||
[containers]
|
||||
max_concurrency = 4 # max simultaneous agent containers
|
||||
max_uptime = "30m" # grace period after task completion before kill
|
||||
volume_ttl = "72h" # max volume age before cleanup (overrides terminal wait)
|
||||
|
||||
# Image strategy
|
||||
[containers.image]
|
||||
registry = "ghcr.io/sam/archie-agent:latest" # primary: pull from registry
|
||||
registry_pull = true # allow pulls
|
||||
dockerfile = "./Dockerfile.agent" # fallback: build locally
|
||||
dockerfile_build = true # allow builds
|
||||
|
||||
# Persistent storage
|
||||
[containers.persistent_storage]
|
||||
type = "docker" # docker (volume), bind, s3, sftp, nfs
|
||||
path = "archie-data" # volume name or mount path
|
||||
```
|
||||
|
||||
### Per-repo persistent storage override
|
||||
|
||||
```toml
|
||||
[[repos]]
|
||||
owner = "sam"
|
||||
name = "example-service"
|
||||
persistent_storage = { type = "bind", path = "./archie-core-data/projects/example-service" }
|
||||
```
|
||||
|
||||
When configured, each task for this repo mounts the same bind path. Memory persists across sessions. The agent writes to
|
||||
`MEMORY.md` in this directory.
|
||||
|
||||
### Agent image
|
||||
|
||||
A fat Docker image containing:
|
||||
|
||||
- archie-agent binary
|
||||
- NATS client library
|
||||
- LLM provider SDKs (ai-sdk runtime)
|
||||
- Base tools: git, gh, go, golangci-lint, gofumpt, node, python, ruff, pytest, etc.
|
||||
- esbuild (for TypeScript plugin transpilation)
|
||||
- Yaegi interpreter (bundled in the binary)
|
||||
|
||||
Pre-built and published to a registry. The daemon pulls on startup. Users can provide their own image via config.
|
||||
|
||||
---
|
||||
|
||||
## 5. Extensibility layers
|
||||
|
||||
> **Reconciliation note.** This section describes a two-layer plugin architecture (skill-bundled plugins loaded
|
||||
> per-task, core daemon plugins loaded at startup) that does not exist in code. What _does_ exist -- and is implemented,
|
||||
> tested, and already in production -- is described in the sibling PRD `docs/prds/yaegi-plugin-system.md`, whose three
|
||||
> phases (custom gate functions, custom workflow stages, skill scripts) are marked "implemented" and match disk state
|
||||
> exactly as of commit `d45f21d`. That implementation is narrower and shaped differently than what follows:
|
||||
>
|
||||
> - It has **no skill-bundling concept** -- `.archie/gate.go` and `.archie/stages/*.go` are repo-level, not shipped
|
||||
> inside a skill's `plugins/` directory; skill scripts (`.archie/skills/<skill>/scripts/*.go`) are the closest analog
|
||||
> but none of the five current skills ship a `scripts/` directory yet.
|
||||
> - It has **no daemon-side core plugin registry** -- no `Plugin` interface, no `Register(daemon *Daemon)`, no
|
||||
> `~/.config/archie/plugins/` loader. Yaegi today only interprets small, narrowly-scoped `.go` files (gates, stages,
|
||||
> scripts) in-process inside `archied`, using generated symbol tables (`internal/gate/gateextract`,
|
||||
> `internal/workflow/wfextract`) rather than a general extension-registration interface.
|
||||
> - Custom stages are **auto-discovered and run in filename order**, not routed by name from `config.toml` -- the
|
||||
> workflow engine has no data-driven stage graph today, so the `[[workflows.stages]]` config sketch below does not
|
||||
> correspond to real config.
|
||||
>
|
||||
> Before implementation begins, decide: does Layer 1/Layer 2 as described below _replace_ the existing three Yaegi
|
||||
> surfaces, or does it _extend_ them (e.g., teach the existing loaders to also read from a skill's `plugins/` directory,
|
||||
> and add a genuinely new daemon-side `Plugin` interface as a separate, later addition)? The existing surfaces are
|
||||
> working code with real symbol-table generation and panic recovery -- treat them as the implementation substrate for
|
||||
> Layer 1, not as something to discard.
|
||||
|
||||
### Layer 1: Skills (`archie-wf-*`)
|
||||
|
||||
> **Status: cosmetic only.** Five `SKILL.md` files exist today (`ecosystem-node`, `ecosystem-python`, `go-quality-gate`,
|
||||
> `security-audit`, `tdd-bugfix`) at `.archie/skills/<name>/SKILL.md` -- a single flat repo-relative location, no
|
||||
> worktree-vs-user-level split, no `archie-wf-*` naming. Each has a `metadata.archie` block with only `tools` and
|
||||
> `engine` keys (no `plugins`, no `budget_usd`). **No Go code parses SKILL.md frontmatter, discovers skills, or does
|
||||
> progressive disclosure** -- grepping for a skill loader, catalog, or frontmatter parser across the repo returns
|
||||
> nothing. The workflow `Mission` strings that drive agent behavior today are hand-written Go string literals in
|
||||
> `internal/workflow/{implement,tdd,feasibility}.go`, not content injected from SKILL.md. The stage names described in
|
||||
> the PRD's SKILL.md prose closely mirror the hardcoded Go stage names (one drift found: `tdd-bugfix/SKILL.md` says the
|
||||
> last stage is "deliver"; the code calls it `open-pr`) -- these read as retrofitted documentation of existing v1
|
||||
> behavior wearing v2-flavored frontmatter, not a functioning specification the daemon consumes.
|
||||
|
||||
Skills are Markdown documents following the [agentskills.io](https://agentskills.io/specification) specification with
|
||||
archie-specific extensions.
|
||||
|
||||
#### Discovery
|
||||
|
||||
```tree
|
||||
.agents/skills/archie-wf-tdd/SKILL.md (worktree -- highest precedence)
|
||||
.agents/skills/archie-wf-implement/SKILL.md
|
||||
.agents/skills/archie-wf-feasibility/SKILL.md
|
||||
~/.archie/skills/archie-wf-default/SKILL.md (user-level -- fallback)
|
||||
```
|
||||
|
||||
The agent discovers skills at workflow start. The skill matching the task's workflow type is loaded first. If absent,
|
||||
falls back to `archie-wf-default`. If that's absent too, the agent works from AGENTS.md conventions and best practices.
|
||||
|
||||
#### Extended agentskills.io format
|
||||
|
||||
Skills follow the standard spec (`name`, `description`, `version`, `SKILL.md` body) with archie-specific metadata:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: archie-wf-tdd
|
||||
description: >
|
||||
Test-driven bugfix workflow for archie-core. Reproduce the bug with failing tests, prove the repro, fix the code
|
||||
without touching tests.
|
||||
version: 1.0.0
|
||||
metadata:
|
||||
archie:
|
||||
plugins: # bundled Yaegi plugins shipped with this skill
|
||||
- plugins/custom-gate.go # repo-specific gate logic
|
||||
- plugins/gosec-check.go # security scanner integration
|
||||
tools: [go, golangci-lint, gofumpt, task]
|
||||
engine: any
|
||||
budget_usd: 2.00
|
||||
---
|
||||
```
|
||||
|
||||
#### Progressive disclosure
|
||||
|
||||
Per the agentskills.io spec:
|
||||
|
||||
1. **Catalogue** (~100 tokens): `name` + `description` loaded at workflow start
|
||||
2. **Instructions** (<5000 tokens): Full `SKILL.md` body when the skill is activated
|
||||
3. **Resources** (as needed): References, scripts, and bundled plugins loaded on demand
|
||||
|
||||
#### Bundled plugins
|
||||
|
||||
A skill's `plugins/` directory contains Yaegi `.go` files. These are loaded by the agent at workflow start alongside the
|
||||
skill instructions. The daemon copies them to `/data/plugins/` before the container starts.
|
||||
|
||||
If `/data/plugins/` already has a plugin with the same name (from persistent project storage), the volume version wins.
|
||||
Conflicts are logged by the daemon.
|
||||
|
||||
### Layer 2: Core plugins
|
||||
|
||||
> **Status: aspirational, zero code.** No `Plugin` interface, no plugin registry, no `~/.config/archie/plugins/` loader
|
||||
> exists anywhere in the repo (confirmed by grep for `Plugin`, plugin registry, and `Register(daemon` -- zero matches).
|
||||
> Yaegi is a real dependency (`traefik/yaegi v0.16.1`) and is genuinely wired up, but only for the three narrow surfaces
|
||||
> in sec.5's reconciliation note above, all interpreted in-process inside `archied` -- not for extending the daemon with
|
||||
> new forge/ticketing/storage/secrets/notify implementations as described below.
|
||||
|
||||
Core plugins live at `~/.config/archie/plugins/` and extend the daemon itself:
|
||||
|
||||
```tree
|
||||
~/.config/archie/plugins/
|
||||
|---- forge-gitea.go # Gitea forge implementation
|
||||
|---- forge-gitlab.go # GitLab forge implementation
|
||||
|---- ticketing-jira.go # Jira ticketing integration
|
||||
|---- ticketing-linear.go # Linear ticketing integration
|
||||
|---- storage-s3.go # S3 persistent storage backend
|
||||
|---- vault-secrets.go # HashiCorp Vault integration
|
||||
|---- notify-servicenow.go # ServiceNow integration
|
||||
```
|
||||
|
||||
#### Loading
|
||||
|
||||
Loaded by the daemon at startup via Yaegi. Each plugin registers itself with the daemon's extension registry:
|
||||
|
||||
```go
|
||||
// Plugin interface (Go, interpreted via Yaegi)
|
||||
type Plugin interface {
|
||||
Name() string
|
||||
Version() string
|
||||
Register(daemon *Daemon) error
|
||||
}
|
||||
```
|
||||
|
||||
The daemon discovers `.go` files, evaluates them, extracts the plugin symbol, and calls `Register()`. Failed plugins are
|
||||
logged and skipped -- the daemon starts with remaining plugins.
|
||||
|
||||
#### What core plugins can do
|
||||
|
||||
- **Forges** -- implement the `forge.Forge` interface. Register themselves as available forge types.
|
||||
- **Ticketing** -- implement a ticketing interface. Poll external systems, format issues into the standard `forge.Issue`
|
||||
struct.
|
||||
- **Storage backends** -- implement a storage interface. Provide volume population and cleanup.
|
||||
- **Secrets** -- implement a vault interface. Inject credentials into `/data/secrets/` before agent start.
|
||||
- **Notifications** -- implement a notify interface. Deliver PRDs, status updates beyond the built-in webhook.
|
||||
|
||||
---
|
||||
|
||||
## 6. Task lifecycle (v2)
|
||||
|
||||
> **Status: implemented.** NATS JetStream is now the task distribution path (`internal/nats/client.go`, `internal/daemon/daemon.go:drainNATS()`). Docker containers spawn per task (`internal/container/pool.go`). The flow below matches the running code post-e4d11b1.
|
||||
|
||||
```
|
||||
Discover -> Publish to JetStream -> Agent consumes -> running(workflow:stage)
|
||||
v
|
||||
pr_open -> merged | rejected
|
||||
v
|
||||
waiting_human -> (approved) -> requeue
|
||||
v
|
||||
parked
|
||||
```
|
||||
|
||||
### Detailed flow
|
||||
|
||||
1. **Discover** -- daemon polls forges for labelled/assigned issues
|
||||
2. **Publish** -- daemon publishes task to `archie.task.<workflow_type>` JetStream subject
|
||||
3. **Spawn** -- daemon creates task volume, writes `task.json`, stages bundled plugins
|
||||
4. **Start container** -- `docker run` with volume mounts, network (NATS), resource limits
|
||||
5. **Agent boots** -- reads `task.json` from `/data/`, connects to NATS, discovers skills, loads bundled plugins
|
||||
6. **Run workflow** -- agent executes routed workflow stages. Reports progress to system channel. Result to response
|
||||
channel.
|
||||
7. **Daemon reviews** -- reads agent response. Forwards to human channels (issue comment, label update, PR). System
|
||||
messages stay internal.
|
||||
8. **Grace period** -- agent stays alive for `max_uptime`. Handles follow-ups (gate re-runs, human replies forwarded by
|
||||
daemon).
|
||||
9. **Kill** -- daemon kills container. Volume cleaned up on terminal outcome or TTL expiry.
|
||||
|
||||
---
|
||||
|
||||
## 7. Agent -> daemon -> human flow
|
||||
|
||||
```flow
|
||||
,---------, response ,---------, reviewed ,----------,
|
||||
| Agent |------------ -> | Daemon |------------ -> | Human |
|
||||
| | system | | queried | channels |
|
||||
| |------------ -> | |<-------------| |
|
||||
|------------ |------------ |-------------
|
||||
|
|
||||
|---- Issue comments (parked, PR, waiting)
|
||||
|---- Label updates (archie:queued -> archie:working -> archie:pr)
|
||||
|---- Notify webhook (feasibility PRD delivered)
|
||||
|---- SSE dashboard (real-time observability)
|
||||
```
|
||||
|
||||
The agent writes whatever it wants to `response`. The daemon reviews it. No agent output reaches a human unprompted. The
|
||||
`system` channel is purely internal -- the daemon reads it for observability and debugging, never forwards it.
|
||||
|
||||
---
|
||||
|
||||
## 8. Implementation phases
|
||||
|
||||
> Updated 2026-07-24 against actual repo state (see sec.0). Items marked **done** exist in the current tree; nothing else in
|
||||
> this document is implemented beyond them. Phase ordering below is unchanged from the original sketch except Phase 3,
|
||||
> which now builds on top of existing Yaegi work instead of assuming a blank slate.
|
||||
|
||||
### Phase 1: Binary split + NATS
|
||||
|
||||
- ~~Split `archied` into daemon binary~~ -- **done**, `cmd/archied` exists
|
||||
- ~~Create `archie-agent` binary~~ -- **done, but partial**: `cmd/archie-agent` exists and executes one workflow _stage_
|
||||
per invocation over a versioned stdin/stdout JSON protocol (`internal/agentexec`, protocol v1). Still needed: promote
|
||||
it from a single-stage subprocess worker to the PRD's per-task process, and move workflow routing/sequencing
|
||||
(`workflow.Route`/`workflow.Run`) out of `archied` and into it.
|
||||
- ~~Add NATS to both (JetStream for task queue, request-reply for comms)~~ -- **done**. `[nats]` is optional, supports
|
||||
anonymous local mode and token authentication via `token_env`, and leaves `internal/events.Bus` as the local
|
||||
observability fan-out.
|
||||
- ~~Daemon publishes, agent consumes, results return via NATS~~ -- **done**. Task discovery uses JetStream work-queue
|
||||
subjects; autonomous stages use JetStream requests plus core NATS reply inboxes.
|
||||
- Current single-process mode preserved for development (`--local` flag) -- effectively already true: `inprocess`
|
||||
`[agent] mode` is the _default_, not an opt-in fallback, so this constraint is satisfied but should be revisited once
|
||||
subprocess/container modes are the default.
|
||||
|
||||
### Phase 2: Docker sandbox
|
||||
|
||||
- Docker agent image (fat, with tools) -- not started
|
||||
- Daemon container lifecycle: spawn, volume create, env inject, kill -- not started
|
||||
- ~~Persistent volumes with TTL~~ -- **done**: configured repos receive a persistent Docker volume plus a per-repo Git
|
||||
object cache; both are automatically reaped using `containers.volume_ttl`.
|
||||
- ~~`max_concurrency` enforcement~~ -- **done**: SQLite and NATS drains dispatch different repositories concurrently
|
||||
up to `[containers].max_concurrency`; same-repo tasks remain serialised by default.
|
||||
- Grace period `max_uptime` -- not started
|
||||
- **Groundwork already in place:** `agentexec.Runner` (`InProcessRunner`/`SubprocessRunner`) is an interface designed,
|
||||
per its own doc comments, to be swapped for a container-backed runner without touching workflow orchestration --
|
||||
implement `ContainerRunner` against this interface rather than redesigning the execution boundary.
|
||||
|
||||
### Phase 3: Skills + bundled plugins
|
||||
|
||||
- agentskills.io spec implementation (progressive disclosure) -- not started; current SKILL.md files are unparsed
|
||||
documentation (see sec.5)
|
||||
- `archie-wf-*` skill discovery from worktree and user paths -- not started; current skills live at a single flat
|
||||
`.archie/skills/` path with different naming
|
||||
- Bundled plugin loading via Yaegi from skill's `plugins/` directory -- not started, but **has a working substrate to
|
||||
extend**: `internal/gate/gateeval`, `internal/workflow/wfeval`, and `internal/skillscript` already interpret `.go`
|
||||
files via Yaegi with generated symbol tables and panic recovery (see `docs/prds/yaegi-plugin-system.md`, Phases 1--3,
|
||||
done). This phase should teach those loaders to also discover files from a skill's `plugins/` directory, not build a
|
||||
second Yaegi integration from scratch.
|
||||
- Volume-staged plugins with conflict resolution -- not started, and depends on Phase 2's volume work existing first
|
||||
|
||||
### Phase 4: Core plugins
|
||||
|
||||
- Yaegi plugin loader for `~/.config/archie/plugins/` -- not started (no `Plugin` interface, no registry, no loader
|
||||
exist today)
|
||||
- Plugin registry in daemon -- not started
|
||||
- Gitea forge as first core plugin (proof of concept) -- not started (current `internal/forge` only implements GitHub
|
||||
REST polling)
|
||||
- Linear ticketing as second core plugin -- not started
|
||||
|
||||
### Phase 5: Pluggable storage
|
||||
|
||||
- Docker volume backend (built-in) -- not started
|
||||
- Bind mount backend (built-in) -- not started
|
||||
- S3, SFTP, NFS backends as core plugins -- not started
|
||||
|
||||
---
|
||||
|
||||
## 9. Open questions
|
||||
|
||||
1. **Agent image versioning:** Use tagged versions (`:v1.2.3`) with a "never repoint tags" policy. `:latest` is for dev
|
||||
only, not the config default. No digest complexity needed -- archie-core is self-hosted, not a public registry.
|
||||
|
||||
2. **NATS auth:** Anonymous for single-node deployments (daemon + NATS + agents on same host). Credentials required for
|
||||
multi-node/cluster. Add an optional `[nats]` config block (default: anonymous, validated only when present).
|
||||
|
||||
3. **Worktree ownership:** ~~Answered by current implementation.~~ Fresh `git clone` per task attempt, no shared cache.
|
||||
This is fine for v2. Revisit if concurrent agents on the same repo become a bottleneck.
|
||||
|
||||
4. **Grace period interaction:** Reset `max_uptime` on human reply -- the agent just did useful work. But cap total
|
||||
lifetime with `max_total_uptime` (e.g. 4 hours) to prevent infinite hanging. `max_uptime` = grace after inactivity,
|
||||
`max_total_uptime` = absolute kill switch.
|
||||
|
||||
5. **Concurrent agents on the same repo:** ~~Resolved.~~ Serialised by default (dispatcher chains tasks per
|
||||
`owner/repo`). `[[repos]]` now supports `allow_concurrent = true` (`config.Repo.AllowConcurrent`) to opt a repo out
|
||||
of that serialisation; the global `[containers].max_concurrency` slot limit still applies. Worktrees are already
|
||||
keyed per issue number (`worktree.Manager.Dir`), so opted-in repos don't collide on disk.
|
||||
|
||||
6. **Plugin architecture reconciliation:** Extend the existing Yaegi surfaces (`internal/gate/gateeval`,
|
||||
`internal/workflow/wfeval`, `internal/skillscript`) rather than building a parallel `Plugin.Register(daemon)`
|
||||
interface. Core plugins follow the same pattern: `Eval()` a `.go` file, extract known symbols. Settled before Phase
|
||||
3/4.
|
||||
|
||||
7. **Skill loading scope:** "Parse frontmatter, inject body into system prompt" is sufficient for v2. The gap is that
|
||||
nothing reads SKILL.md today -- closing that gap is the value. Full progressive disclosure (catalogue -> activate ->
|
||||
resources) is deferred to a later phase.
|
||||
@@ -1,389 +0,0 @@
|
||||
# archie-core Skills System -- PRD
|
||||
|
||||
**Author:** Archie
|
||||
**Date:** 2026-07-18
|
||||
**Status:** Draft
|
||||
|
||||
---
|
||||
|
||||
## What archie-core is
|
||||
|
||||
arcie-core is an LLM coding agent that responds to issues, queries, and commands on connected interfaces. The current MVP runs on GitHub: it receives issue assignments, analyses scope and requirements, implements changes in isolated worktrees, runs quality gates, and opens pull requests.
|
||||
|
||||
The skills system extends this with reusable playbooks that tell archie-core **how** to work on any given project.
|
||||
|
||||
---
|
||||
|
||||
## 1. The workflow file (`archie.yaml`)
|
||||
|
||||
Every project can ship an `archie.yaml` that defines how archie-core should behave when working on that codebase. Without one, archie-core uses sensible defaults (read files, run bash, open PRs). With one, it knows the exact gates to pass, tools available, commit format, and which skills are relevant.
|
||||
|
||||
### 1.1 Discovery
|
||||
|
||||
```
|
||||
.archie.yaml (root of repo -- highest precedence)
|
||||
archie.yaml (repo root)
|
||||
.archie/archie.yaml (subdirectory, one level deep)
|
||||
```
|
||||
|
||||
### 1.2 Schema
|
||||
|
||||
```yaml
|
||||
# archie.yaml
|
||||
version: "1"
|
||||
|
||||
# Project identity
|
||||
project:
|
||||
name: my-go-service
|
||||
language: go
|
||||
repo: github.com/sam/my-go-service
|
||||
|
||||
# How archie-core connects to this project
|
||||
connection:
|
||||
interfaces:
|
||||
- github # respond to assigned issues
|
||||
- linear # respond to labelled tickets
|
||||
- webhook # respond to HTTP POSTs
|
||||
github:
|
||||
repo: sam/my-go-service
|
||||
issue_labels:
|
||||
ready: "archie:ready" # issues with this label get claimed
|
||||
claimed: "archie:claimed" # archie sets this when working
|
||||
done: "archie:done" # archie sets this after PR
|
||||
pr:
|
||||
base: main
|
||||
draft: false
|
||||
|
||||
# Skills -- playbooks archie-core loads to know how to work
|
||||
skills:
|
||||
paths:
|
||||
- .archie/skills/ # project-local skills
|
||||
- ~/.archie/skills/ # per-user skills
|
||||
remotes:
|
||||
- github.com/sam/archie-skills@v1 # shared skill library
|
||||
|
||||
# Sandbox -- what's available in the container
|
||||
sandbox:
|
||||
image: ghcr.io/sam/archie-sandbox:latest
|
||||
tools:
|
||||
- go
|
||||
- golangci-lint
|
||||
- gofumpt
|
||||
- task
|
||||
- gh
|
||||
- docker
|
||||
env:
|
||||
GOFLAGS: "-mod=readonly"
|
||||
|
||||
# Gates -- archie-core must pass these before committing
|
||||
gates:
|
||||
test:
|
||||
run: go test -race -count=1 ./...
|
||||
timeout: 300
|
||||
lint:
|
||||
run: golangci-lint run ./...
|
||||
timeout: 120
|
||||
format:
|
||||
run: gofumpt -w . && git diff --exit-code
|
||||
deadcode:
|
||||
run: task deadcode
|
||||
optional: true
|
||||
|
||||
# Quality pipeline -- which gates run when
|
||||
quality:
|
||||
pre_commit: [test, lint, format]
|
||||
pre_push: [deadcode]
|
||||
|
||||
# Commit conventions
|
||||
commit:
|
||||
format: conventional
|
||||
signoff: false
|
||||
|
||||
# Branch conventions
|
||||
branch:
|
||||
format: "{type}/cat-{number}-{kebab-description}"
|
||||
types:
|
||||
feat: "Feature work"
|
||||
fix: "Bug fixes"
|
||||
test: "Test additions"
|
||||
chore: "Maintenance"
|
||||
refactor: "Code restructuring"
|
||||
docs: "Documentation"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Skills (playbooks)
|
||||
|
||||
Skills are Markdown documents that tell archie-core **how** to perform specific tasks. They follow the [agentskills.io](https://agentskills.io/specification) format, making them portable across compatible LLM coding agents.
|
||||
|
||||
### 2.1 Format
|
||||
|
||||
```
|
||||
go-testing/
|
||||
├── SKILL.md # Required: frontmatter + instructions
|
||||
├── references/ # Optional: supplementary docs
|
||||
│ └── coverage.md
|
||||
├── scripts/ # Optional: executable helpers
|
||||
│ └── bench.sh
|
||||
└── assets/ # Optional: templates
|
||||
└── test.vscode.code-snippets
|
||||
```
|
||||
|
||||
### 2.2 SKILL.md
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: go-quality-gate
|
||||
description: >
|
||||
Run the full Go quality pipeline:
|
||||
gofumpt, go fix, golangci-lint, go test -race, and task deadcode.
|
||||
Use before any commit in a Go project.
|
||||
version: 1.0.0
|
||||
metadata:
|
||||
archie:
|
||||
# Which gates this skill covers
|
||||
gates: [test, lint, format, deadcode]
|
||||
# Required sandbox tools
|
||||
tools: [go, golangci-lint, gofumpt, task]
|
||||
# Preferred engine (if multiple available)
|
||||
engine: any
|
||||
# Max spend for this skill
|
||||
budget_usd: 2.00
|
||||
---
|
||||
|
||||
# Go Quality Gate
|
||||
|
||||
## When to use
|
||||
|
||||
Before committing any Go change. After implementing a feature or fix.
|
||||
|
||||
## Procedure
|
||||
|
||||
Run in this exact order. If any step fails, fix the issue before continuing.
|
||||
|
||||
1. `gofumpt -w .`
|
||||
2. `go fix ./...`
|
||||
3. `golangci-lint run ./...`
|
||||
4. `go test -race -count=1 ./...`
|
||||
5. `task deadcode`
|
||||
|
||||
## Verification
|
||||
|
||||
All five steps must exit 0. If `task deadcode` fails on unrelated packages,
|
||||
scope it to only changed packages: `golangci-lint run --tests=false --enable-only=unused,staticcheck ./changed/pkg/...`
|
||||
|
||||
## Common failures
|
||||
|
||||
- `golangci-lint`: unused function -- remove it or add `//nolint:unused` comment
|
||||
- `go test -race`: data race -- protect with mutex or channel
|
||||
- `task deadcode`: pre-existing dead code in unrelated package -- scope to changed packages
|
||||
```
|
||||
|
||||
### 2.3 Skill metadata (arcie-specific)
|
||||
|
||||
Skills carry archie-specific metadata under `metadata.archie`:
|
||||
|
||||
| Field | Purpose |
|
||||
| ------------ | ------------------------------------------------ |
|
||||
| `gates` | Which gates from `archie.yaml` this skill covers |
|
||||
| `tools` | Sandbox tools this skill needs |
|
||||
| `engine` | Preferred execution engine |
|
||||
| `model` | Preferred model for this skill |
|
||||
| `budget_usd` | Max spend ceiling |
|
||||
| `timeout` | Max seconds |
|
||||
| `worktree` | Whether to create isolated worktree |
|
||||
|
||||
### 2.4 Progressive disclosure
|
||||
|
||||
Following the skills.sh model to keep context lean:
|
||||
|
||||
1. **Advertise** (~100 tokens per skill): `name` + `description` loaded at startup
|
||||
2. **Activate** (<5000 tokens): Full SKILL.md body loaded when skill is relevant
|
||||
3. **Resources** (as needed): References, scripts, assets loaded on demand
|
||||
|
||||
---
|
||||
|
||||
## 3. How archie-core processes an issue
|
||||
|
||||
This is the core loop. When an issue lands with the configured label:
|
||||
|
||||
### 3.1 Analyse
|
||||
|
||||
1. Read issue title, body, labels, comments
|
||||
2. Load relevant skills from the project's `archie.yaml`
|
||||
3. Determine scope: which packages, files, and gates are in play
|
||||
4. Determine branch type (`feat/`, `fix/`, `test/`, etc.) from issue labels or conventional commit prefix
|
||||
|
||||
### 3.2 Claim
|
||||
|
||||
1. Set issue label to `archie:claimed`
|
||||
2. Comment: "Archie claimed this. Branch: `<branch>`"
|
||||
3. Create isolated worktree from `main`
|
||||
|
||||
### 3.3 Implement
|
||||
|
||||
1. Load full skill bodies for each relevant skill
|
||||
2. Read project source and tests in the affected area
|
||||
3. Implement changes, writing tests first where applicable
|
||||
4. Run targeted tests iteratively
|
||||
|
||||
### 3.4 Gate
|
||||
|
||||
1. Run all gates from the quality pipeline in order
|
||||
2. Fix any failures, re-running from the failing gate
|
||||
3. Audit diff for secrets, unrelated changes, attribution
|
||||
|
||||
### 3.5 Deliver
|
||||
|
||||
1. Commit with conventional format: `feat(scope): description`
|
||||
2. Push branch
|
||||
3. Open PR to `main` with:
|
||||
- Summary of changes
|
||||
- Acceptance criteria addressed
|
||||
- Gate results
|
||||
- Link back to source issue/Linear ticket
|
||||
4. Set issue label to `archie:done`
|
||||
5. Comment with PR URL
|
||||
|
||||
### 3.6 On failure
|
||||
|
||||
If any gate fails irrecoverably:
|
||||
|
||||
1. Leave issue as `archie:claimed`
|
||||
2. Comment with exact blocker, failed command, and worktree path
|
||||
3. Preserve worktree for inspection
|
||||
4. Do not open a broken PR
|
||||
|
||||
---
|
||||
|
||||
## 4. Engine abstraction
|
||||
|
||||
arcie-core can delegate implementation to different LLM engines. The workflow file declares preference order; archie-core resolves the first available engine at runtime.
|
||||
|
||||
```yaml
|
||||
engines:
|
||||
- type: claude # Claude Code CLI -- full agent loop
|
||||
model: sonnet
|
||||
budget_usd: 5.00
|
||||
- type: codex # OpenAI Codex CLI
|
||||
model: gpt-5.1-codex-max
|
||||
- type: raw # Direct LLM -- no agent loop, single prompt
|
||||
model: gpt-4o-mini
|
||||
```
|
||||
|
||||
Each engine provides the same interface:
|
||||
|
||||
```
|
||||
Engine:
|
||||
- Run(prompt, tools, budget, timeout) -> Result
|
||||
- Skills() -> []SkillName
|
||||
- Capabilities() -> {streaming, reasoning, vision, agentic}
|
||||
```
|
||||
|
||||
For skills that need a specific engine, the skill metadata overrides:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
archie:
|
||||
engine: claude # this skill only works with Claude
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Skills in practice
|
||||
|
||||
### 5.1 Shared skill library
|
||||
|
||||
```yaml
|
||||
# archie.yaml
|
||||
skills:
|
||||
remotes:
|
||||
- github.com/sam/archie-skills@v1
|
||||
```
|
||||
|
||||
Skills from the shared library are available alongside project-local skills. The agent loads them on demand when an issue references relevant concepts.
|
||||
|
||||
### 5.3 Skill that wraps an external tool
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: trivy-scan
|
||||
description: >
|
||||
Scan container images and filesystems for vulnerabilities using Trivy.
|
||||
Use when asked about security scanning, CVEs, or container hardening.
|
||||
metadata:
|
||||
archie:
|
||||
tools: [docker, trivy]
|
||||
engine: any
|
||||
---
|
||||
## Procedure
|
||||
1. `trivy image --severity HIGH,CRITICAL <image>`
|
||||
2. If findings exist, report each CVE with package, version, and fixed version
|
||||
3. If no findings, report clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Comparison: archie-core vs existing systems
|
||||
|
||||
| | archie-core | Claude Code | Codex CLI | GitHub Actions | External Agent |
|
||||
| ------------------------ | ---------------------------------------------- | ------------------------------- | ------------------------------- | ---------------------------------- | ------------------------------- |
|
||||
| **How it receives work** | GitHub issue assignment, Linear label, webhook | Chat, slash commands | Chat, slash commands | YAML triggers (push, PR, schedule) | Chat, cron, webhooks |
|
||||
| **What it does** | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Analyse → implement → gate → PR | Run arbitrary shell commands | Analyse → implement → gate → PR |
|
||||
| **Skills** | SKILL.md (agentskills.io) | SKILL.md (native) | SKILL.md (agentskills.io) | Composite actions | SKILL.md (native) |
|
||||
| **Gates** | Named checkpoints in archie.yaml | Ad-hoc (CLAUDE.md + lint) | Ad-hoc | Steps in jobs | Skills with gates |
|
||||
| **Engine pluggable** | Yes | No (fixed to Claude) | No (fixed to Codex) | No (fixed to GitHub) | Yes (provider config) |
|
||||
| **Worktree isolation** | Yes | Yes (`--worktree`) | No | No (ephemeral runner) | No |
|
||||
| **Blueprint/cron** | Export externally | No | No | Schedule trigger | Native |
|
||||
| **Where it runs** | Docker sandbox | Host | Host or sandbox | GitHub runner | Host, Docker, Modal, SSH |
|
||||
|
||||
---
|
||||
|
||||
## 7. Implementation phases
|
||||
|
||||
### Phase 1: Workflow file and gates (current MVP)
|
||||
|
||||
- `archie.yaml` parser
|
||||
- Gate runner executing shell commands and checking exit codes
|
||||
- Skill discovery from project and user paths
|
||||
- GitHub interface: claim issues, create worktrees, open PRs
|
||||
|
||||
### Phase 2: Skills
|
||||
|
||||
- SKILL.md progressive disclosure (advertise → activate → resources)
|
||||
- archie-specific metadata parsing
|
||||
- Skill chaining: skills that depend on other skills
|
||||
- `archie skills list/install` CLI
|
||||
|
||||
### Phase 3: Engine abstraction
|
||||
|
||||
- Engine interface definition
|
||||
- Claude Code adapter
|
||||
- Raw LLM adapter
|
||||
- Engine fallback chain
|
||||
- Per-skill engine preferences
|
||||
|
||||
### Phase 4: Advanced features
|
||||
|
||||
- Gate overrides per skill
|
||||
- Skill templates for project scaffolding (`archie init --skill go-service`)
|
||||
- Remote skill libraries (git repos as skill sources)
|
||||
- Blueprint export to an external scheduler
|
||||
|
||||
### Phase 5: Additional interfaces
|
||||
|
||||
- Linear webhook integration
|
||||
- Generic webhook interface for arbitrary sources
|
||||
- CLI command interface (`archie run <command>`)
|
||||
|
||||
---
|
||||
|
||||
## 8. Open questions
|
||||
|
||||
1. **Claim protocol:** Single-claim (arcie takes one issue at a time) or queue-based (claims N issues, works through them sequentially)?
|
||||
2. **Concurrent worktrees:** Allow multiple archie-core instances working on different issues simultaneously?
|
||||
3. **PR merging:** Should archie-core ever auto-merge, or always require human review?
|
||||
4. **Skill registry:** Self-host on git.catlow.cloud, use agentskills.io, or both?
|
||||
5. **Engine budget enforcement:** Per-issue, per-skill, or monthly cap?
|
||||
6. **Sandbox building:** Pre-built Docker images vs. project-defined Dockerfiles vs. Nix shells?
|
||||
@@ -1,400 +0,0 @@
|
||||
# archie-core Workflows & Skills -- Product Requirements Document
|
||||
|
||||
**Author:** Archie
|
||||
**Date:** 2026-07-18
|
||||
**Status:** Draft
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
This PRD defines a workflow and skills system for archie-core. Workflow files declare gates, tool availability, execution engines, and skill references. Skills are reusable playbook documents the agent loads on demand. Together they enable any project to define how agents work within their sandbox and select an available execution engine.
|
||||
|
||||
---
|
||||
|
||||
## 1. Workflow Files (`archie.yaml`)
|
||||
|
||||
### 1.1 Discovery
|
||||
|
||||
A project declares its workflow in `archie.yaml` at the project root. archie-core discovers it the same way Task (Taskfile) and devcontainers do:
|
||||
|
||||
```
|
||||
.archie.yaml (root of repo -- highest precedence)
|
||||
archie.yaml (repo root)
|
||||
.archie/archie.yaml (subdirectory, one level deep)
|
||||
```
|
||||
|
||||
If no file is found, archie-core uses built-in defaults (read, write, bash).
|
||||
|
||||
### 1.2 Schema
|
||||
|
||||
```yaml
|
||||
# archie.yaml -- complete schema
|
||||
version: "1"
|
||||
|
||||
# Project identity
|
||||
project:
|
||||
name: my-go-service
|
||||
language: go
|
||||
|
||||
# Available skills (directories or individual files)
|
||||
skills:
|
||||
paths:
|
||||
- .archie/skills/ # project-local skills
|
||||
- ~/.archie/skills/ # per-user skills
|
||||
- github.com/org/shared-skills@v1 # remote skill repo
|
||||
skills:
|
||||
- go-testing # named skill from any path
|
||||
- security-audit
|
||||
|
||||
# Execution engines in preference order
|
||||
engines:
|
||||
- type: claude # Claude Code CLI
|
||||
model: sonnet
|
||||
- type: codex # OpenAI Codex
|
||||
- type: pi # Pi agent harness
|
||||
- type: raw # Direct LLM without agent wrapper
|
||||
|
||||
# Sandbox definition (what the Docker container provides)
|
||||
sandbox:
|
||||
image: ghcr.io/samcharles93/archie-sandbox:latest
|
||||
tools:
|
||||
- go
|
||||
- golangci-lint
|
||||
- gofumpt
|
||||
- task
|
||||
- gh
|
||||
- docker
|
||||
mounts:
|
||||
- source: /var/run/docker.sock
|
||||
target: /var/run/docker.sock
|
||||
env:
|
||||
GOFLAGS: "-mod=readonly"
|
||||
CGO_ENABLED: "0"
|
||||
|
||||
# Gates -- ordered checkpoints that must pass
|
||||
gates:
|
||||
test:
|
||||
run: go test -race -count=1 ./...
|
||||
timeout: 300
|
||||
description: "All tests must pass"
|
||||
lint:
|
||||
run: golangci-lint run ./...
|
||||
timeout: 120
|
||||
description: "Zero lint issues"
|
||||
format:
|
||||
run: gofumpt -w . && git diff --exit-code
|
||||
description: "No formatting drift"
|
||||
vet:
|
||||
run: go vet ./...
|
||||
description: "No vet warnings"
|
||||
deadcode:
|
||||
run: task deadcode
|
||||
optional: true # non-blocking gate
|
||||
description: "Dead code check (advisory)"
|
||||
|
||||
# Quality pipeline -- ordered sequence of gate groups
|
||||
quality:
|
||||
pre_commit:
|
||||
- test
|
||||
- lint
|
||||
- format
|
||||
- vet
|
||||
pre_push:
|
||||
- deadcode
|
||||
|
||||
# Commit conventions
|
||||
commit:
|
||||
format: conventional # conventional commits
|
||||
signoff: false
|
||||
template: "feat({scope}): {description}"
|
||||
|
||||
# PR conventions
|
||||
pr:
|
||||
template: .github/PULL_REQUEST_TEMPLATE.md
|
||||
checks:
|
||||
- test
|
||||
- lint
|
||||
|
||||
# Project-specific commands (what `archie run <name>` executes)
|
||||
commands:
|
||||
build:
|
||||
run: go build -o bin/app ./cmd/server
|
||||
description: "Build the binary"
|
||||
serve:
|
||||
run: go run ./cmd/server
|
||||
description: "Start dev server"
|
||||
test:
|
||||
run: go test ./...
|
||||
description: "Run all tests"
|
||||
lint:
|
||||
run: golangci-lint run ./...
|
||||
description: "Run linter"
|
||||
all:
|
||||
run:
|
||||
- gofumpt -w .
|
||||
- go fix ./...
|
||||
- golangci-lint run ./...
|
||||
- go test -race ./...
|
||||
- task deadcode
|
||||
description: "Full quality pipeline"
|
||||
```
|
||||
|
||||
### 1.3 Design decisions (with rationale)
|
||||
|
||||
| Decision | Rationale |
|
||||
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
|
||||
| YAML over TOML/JSON | Already dominant in CI (GitHub Actions, GitLab CI, Taskfile). Human-readable with comments. |
|
||||
| Single file over multi-file | Task discovery (like `Taskfile.yml`), devcontainer conventions. Avoids directory sprawl. |
|
||||
| Gates as named checkpoints | GitHub Actions job model. Gates can be composed into quality pipelines, selected individually, or skipped with `--skip`. |
|
||||
| Engines as ordered preference list | Supports deterministic fallback between available engines. Each engine declares its own tool surface. |
|
||||
| Skills as paths + references | Matches devcontainer features (paths resolve to directories) and skills.sh (namespaced references). |
|
||||
| Commands section for direct invocation | Arnie can `archie run test` without an agent turn. Thin wrapper over the sandbox. |
|
||||
| Quality pipeline groups gates | Pre-commit vs pre-push vs pre-merge distinction. Some gates are required, some advisory. |
|
||||
|
||||
---
|
||||
|
||||
## 2. Skills
|
||||
|
||||
### 2.1 Format
|
||||
|
||||
Skills follow the [agentskills.io](https://agentskills.io/specification) specification:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # Required: YAML frontmatter + Markdown instructions
|
||||
├── scripts/ # Optional: executable helpers
|
||||
├── references/ # Optional: longer docs, checklists
|
||||
└── assets/ # Optional: templates, configs
|
||||
```
|
||||
|
||||
**SKILL.md frontmatter:**
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: go-testing
|
||||
description: >
|
||||
Run Go tests with race detection, coverage, and benchmark analysis.
|
||||
Use when asked to test Go code, run the test suite, or check coverage.
|
||||
version: 1.0.0
|
||||
metadata:
|
||||
archie:
|
||||
gates: [test] # gates this skill requires
|
||||
tools: [go, golangci-lint] # sandbox tools it needs
|
||||
engine: any # engine preference
|
||||
compatibility: Requires Go 1.22+
|
||||
---
|
||||
```
|
||||
|
||||
### 2.2 Progressive disclosure
|
||||
|
||||
Following the skills.sh and Claude Code patterns:
|
||||
|
||||
1. **Advertise** (~100 tokens): `name` + `description` loaded at session start
|
||||
2. **Load** (<5000 tokens recommended): Full SKILL.md body when skill activates
|
||||
3. **Resources** (as needed): Scripts, references, assets loaded on demand
|
||||
|
||||
### 2.3 archie-specific metadata
|
||||
|
||||
Skills can carry archie-specific frontmatter under `metadata.archie`:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
archie:
|
||||
gates: [test, lint] # must-pass gates before skill runs
|
||||
tools: [go, docker] # sandbox tools required
|
||||
engine: any # preferred engine
|
||||
model: gpt-4o # preferred model
|
||||
budget_usd: 2.00 # max spend ceiling
|
||||
timeout: 600 # max seconds
|
||||
worktree: true # create isolated worktree
|
||||
```
|
||||
|
||||
### 2.4 Skill sources (inspired by devcontainer features + Dagger modules)
|
||||
|
||||
```
|
||||
skills:
|
||||
paths:
|
||||
- .archie/skills/ # project-local (committed)
|
||||
- ~/.archie/skills/ # per-user (personal)
|
||||
skills:
|
||||
- go-testing # by name from any path
|
||||
remotes:
|
||||
- github.com/samcharles93/archie-skills@v1 # tagged git repo
|
||||
- https://agentskills.io/registry # community registry
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Execution Engine Model
|
||||
|
||||
### 3.1 Engine abstraction
|
||||
|
||||
Each engine provides the same interface. The workflow file declares preference order; archie-core resolves the first available engine at runtime.
|
||||
|
||||
```
|
||||
Engine interface:
|
||||
- Run(prompt, tools[], budget, timeout) -> Result
|
||||
- Tools() -> []ToolSchema
|
||||
- Capabilities() -> {streaming, reasoning, vision, agentic}
|
||||
```
|
||||
|
||||
### 3.2 Supported engines
|
||||
|
||||
| Engine | Type | What it provides |
|
||||
| -------- | ---------------- | ------------------------------------------------------ |
|
||||
| `claude` | Claude Code CLI | Full agent loop, tool use, worktrees, subagents |
|
||||
| `codex` | OpenAI Codex CLI | Agentic coding with sandbox |
|
||||
| `pi` | Pi agent harness | Minimalist coding agent, stdio protocol |
|
||||
| `raw` | Direct LLM call | Single-turn prompt, no agent loop. For simple scripts. |
|
||||
|
||||
### 3.3 Engine selection logic
|
||||
|
||||
```yaml
|
||||
engines:
|
||||
- type: claude
|
||||
model: sonnet
|
||||
budget_usd: 5.00
|
||||
- type: raw
|
||||
model: gpt-4o-mini
|
||||
```
|
||||
|
||||
arcie-core tries engines in order and selects the first available,
|
||||
authenticated engine. Each engine declares its budget ceiling.
|
||||
|
||||
---
|
||||
|
||||
## 4. Additional Features
|
||||
|
||||
### 4.1 Worktree isolation (`worktree: true`)
|
||||
|
||||
Inspired by Claude Code's `--worktree` flag. When a skill or command sets `worktree: true`, archie-core:
|
||||
|
||||
1. Creates an isolated git worktree at `.archie/worktrees/<skill-name>-<timestamp>/`
|
||||
2. Runs all gates and implementation in that worktree
|
||||
3. Cleans up on success, preserves on failure for inspection
|
||||
|
||||
This prevents concurrent agent sessions from conflicting and enables parallel agent execution.
|
||||
|
||||
### 4.2 Skill chaining and composition
|
||||
|
||||
Skills can declare dependencies, forming a DAG:
|
||||
|
||||
```yaml
|
||||
---
|
||||
name: full-ci
|
||||
description: Complete CI pipeline including security audit
|
||||
metadata:
|
||||
archie:
|
||||
requires: [go-testing, security-audit]
|
||||
run_sequential: true
|
||||
---
|
||||
```
|
||||
|
||||
arcie-core resolves the dependency graph and runs skills in order (parallel where possible, respecting `run_sequential`). This is conceptually similar to GitHub Actions `needs` and Taskfile `deps`.
|
||||
|
||||
### 4.3 Gate overrides per skill
|
||||
|
||||
A skill can override project-level gates:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
archie:
|
||||
gates:
|
||||
test:
|
||||
run: go test -short ./... # override: faster test for this skill
|
||||
lint: skip # skip lint for this skill
|
||||
```
|
||||
|
||||
Three override modes: `override` (replace command), `skip` (omit gate), `add` (add new gate requirement).
|
||||
|
||||
### 4.4 Skill templates (scaffolding)
|
||||
|
||||
Skills can carry an `assets/` directory with templates. When archie-core initialises a new project, it can apply skill templates:
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md
|
||||
└── assets/
|
||||
├── .archie.yaml.tmpl # Template workflow file
|
||||
├── Taskfile.yml.tmpl # Template task runner
|
||||
└── .golangci.yml.tmpl # Template linter config
|
||||
```
|
||||
|
||||
`archie init --skill go-service` scaffolds a new project with the go-service skill's templates applied.
|
||||
|
||||
### 4.5 Blueprint export (external cron integration)
|
||||
|
||||
Any archie-core workflow can be exported as an automation blueprint:
|
||||
|
||||
```yaml
|
||||
metadata:
|
||||
archie:
|
||||
blueprint:
|
||||
schedule: "every 6h"
|
||||
deliver: telegram
|
||||
name: "CI monitor"
|
||||
```
|
||||
|
||||
The export produces a `SKILL.md` with scheduler metadata. The blueprint's prompt is the archie workflow's quality pipeline.
|
||||
|
||||
---
|
||||
|
||||
## 5. Comparison to Existing Systems
|
||||
|
||||
| Feature | archie-core | GitHub Actions | Dagger | Taskfile | devcontainer | External Skills |
|
||||
| ---------------------- | ------------------- | ----------------- | -------------- | ---------- | ----------------- | --------------- |
|
||||
| Language | YAML | YAML | Go/Python/TS | YAML | JSON | Markdown |
|
||||
| Gates | Named + composable | Steps in jobs | Functions | Tasks | Lifecycle scripts | N/A |
|
||||
| Engine abstraction | First-class | GitHub only | Dagger Engine | Shell only | None | Provider |
|
||||
| Skills | agentskills.io spec | Composite actions | Dagger Modules | Includes | Features | SKILL.md |
|
||||
| Worktree isolation | Built-in | No | Containers | No | Container | No |
|
||||
| Blueprint export | To external cron | No | No | No | No | Native |
|
||||
| Multi-engine fallback | Yes (ordered list) | No | No | No | No | Provider config |
|
||||
| Progressive disclosure | Yes (skill spec) | No | No | No | Feature metadata | Yes |
|
||||
|
||||
---
|
||||
|
||||
## 6. Implementation Phases
|
||||
|
||||
### Phase 1: Core workflow file
|
||||
|
||||
- `archie.yaml` parser and schema validation
|
||||
- Gate runner (test, lint, format, vet)
|
||||
- `archie run <command>` CLI
|
||||
- Sandbox Docker integration
|
||||
|
||||
### Phase 2: Skills
|
||||
|
||||
- SKILL.md discovery and progressive disclosure
|
||||
- Skill metadata with gate/tool/engine requirements
|
||||
- `archie skills list/install/search`
|
||||
|
||||
### Phase 3: Engine abstraction
|
||||
|
||||
- Engine interface definition
|
||||
- Claude Code adapter
|
||||
- Raw LLM adapter
|
||||
- Engine fallback chain
|
||||
|
||||
### Phase 4: Advanced features
|
||||
|
||||
- Worktree isolation
|
||||
- Skill chaining (dependency DAG)
|
||||
- Gate overrides
|
||||
- Blueprint export
|
||||
|
||||
### Phase 5: Ecosystem
|
||||
|
||||
- Public skill registry
|
||||
- `archie init --skill <name>` scaffolding
|
||||
- Community skill contributions
|
||||
|
||||
---
|
||||
|
||||
## 7. Open Questions
|
||||
|
||||
1. **Skill registry hosting:** Self-hosted on git.catlow.cloud, or use agentskills.io?
|
||||
2. **External integration:** Should archie-core be exposed as a tool, a skill, or standalone?
|
||||
3. **Budget enforcement:** Per-skill budget vs. per-workflow budget vs. monthly cap?
|
||||
4. **Sandbox image building:** Pre-built images vs. Dockerfile in each skill?
|
||||
File diff suppressed because it is too large.
Load diff
@@ -1,220 +0,0 @@
|
||||
# Archie Design Decisions
|
||||
|
||||
Record of architectural choices, reversals, and lessons learned during
|
||||
development. Each entry has a date, a decision, the reasoning, and the
|
||||
context that led to it. This document is the first thing to read before
|
||||
changing anything that contradicts a prior decision.
|
||||
|
||||
---
|
||||
|
||||
## 2026-08-24 -- Turn continuation is never output-volume or token gated
|
||||
|
||||
**Decision**: A turn is never stopped because an aggregate token count or
|
||||
aggregate tool-result character count was reached. `max_tokens` and
|
||||
`turn_budget_chars` are not runtime continuation controls. Tool output is
|
||||
bounded only per invocation with `max_result_chars`; oversized individual
|
||||
results are spilled when a workspace-readable spill directory is configured,
|
||||
or explicitly truncated otherwise.
|
||||
|
||||
**Reasoning**: Aggregate caps discard useful work and caused the model to emit
|
||||
repeated `turn budget exceeded (200000 chars)` tool failures instead of
|
||||
finishing. Model context/output accounting and tool-result volume are distinct:
|
||||
provider output limits may describe one model response, but they must never be
|
||||
used to terminate the multi-step turn.
|
||||
|
||||
**Context**: GitHub #604 showed full file and module listings followed by four
|
||||
identical read failures and a shell failure at the old 200,000-character cap.
|
||||
The renderer now summarises those legacy events for replay, while current
|
||||
dispatch never creates them. Find and grep are confined to the active
|
||||
workspace/worktree; the Go module cache remains readable only by explicit
|
||||
path, not by discovery.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- Forge-agnostic issue creation via CreateIssue
|
||||
|
||||
**Decision**: Add `CreateIssue(ctx, owner, repo, title, body, labels)
|
||||
(int, error)` to the `forge.Forge` interface. Every forge backend
|
||||
(Gitea, GitHub, future beads) implements it.
|
||||
|
||||
**Reasoning**: Agents discover out-of-scope findings during planning
|
||||
and building. These should be filed as tickets immediately rather than
|
||||
lost. Making `CreateIssue` part of the Forge interface means the agent
|
||||
calls one method regardless of the underlying ticketing system.
|
||||
|
||||
**Future**: A `beads` forge backend will implement `CreateIssue` by
|
||||
calling `bd create`. This makes beads the internal/default issue tracker
|
||||
while Gitea/GitHub are external forges. The agent doesn't know which
|
||||
it's talking to -- the daemon resolves the forge from repo config.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- Dolt and Beads for agent-native issue tracking
|
||||
|
||||
**Decision**: Install dolt (version-controlled SQL) and beads (`bd`,
|
||||
a graph-based issue tracker for AI agents) as the foundation for
|
||||
multi-repo scaling and multi-agent coordination.
|
||||
|
||||
**Reasoning**: Beads provides persistent memory across sessions, first-
|
||||
class dependency tracking, JSON output for programmatic use, and hash-
|
||||
based IDs that prevent merge conflicts in multi-agent workflows. It's
|
||||
built on Dolt which gives cell-level merge, native branching, and
|
||||
remote sync -- the same primitives git gives code but applied to issues.
|
||||
|
||||
**Context**: Gas Town (`~/gt/`) is cloned for reference -- it implements
|
||||
a multi-agent workspace on top of beads. The archie-core scaling
|
||||
strategy will follow a similar model: a coordinator daemon with per-repo
|
||||
agents, all sharing a beads-backed task graph.
|
||||
|
||||
**Current state**: dolt 2.2.2, beads 1.1.0 installed. Beads initialised
|
||||
in archie-core (`.beads/`). Six issues seeded for the scaling roadmap.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- Token budgets must be generous, not predictive
|
||||
|
||||
> **Superseded by the 2026-08-24 decision above.** There is no configured
|
||||
> aggregate token cap; model token usage remains accounting only.
|
||||
|
||||
**Decision**: Set `max_tokens` to 100,000,000 (100M). Do not attempt to
|
||||
predict what a task needs without data. Lower limits later based on
|
||||
actual per-workflow/per-repo metrics.
|
||||
|
||||
**Reasoning**: An agent killed mid-task at 1M tokens wastes every token
|
||||
it already consumed. There is no compaction or checkpointing yet, so a
|
||||
killed agent is a total loss. Long-running agents regularly use 160+ steps and
|
||||
hundreds of thousands of tokens per request. Large repositories need
|
||||
proportionally more.
|
||||
|
||||
**Context**: The planner burned 357K tokens just to discover a fix
|
||||
already existed. The builder hit 1M at step 25 of 90. Neither task was
|
||||
unreasonable -- they were just exploring a large codebase.
|
||||
|
||||
**Future**: Track actual token consumption per workflow/stage/repo. Use
|
||||
that data to set informed limits. Build compaction or checkpointing so
|
||||
a killed agent can resume rather than restart.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- baseline-fix: auto-repair pre-existing gate failures
|
||||
|
||||
**Decision**: When `StageBaselineGate` detects a red gate (gofumpt, go
|
||||
vet, etc. failing on clean main), launch the builder to fix the
|
||||
failures via TDD rather than parking. Only park if the builder cannot
|
||||
fix them.
|
||||
|
||||
**Reasoning**: A red baseline means the repo was broken before archie
|
||||
touched it. Parking creates an infinite loop -- the next retry hits the
|
||||
same failure. The agent should fix pre-existing issues, not fail on them.
|
||||
|
||||
**Implementation**: `StageBaselineGate` now calls `tc.Agent.Run()` with
|
||||
a TDD mission when the gate fails. Uses the same builder agent. Note:
|
||||
this required wiring `tc.Agent` (the runner) through the stage context.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- No hardcoded MaxSteps in workflow stages
|
||||
|
||||
**Decision**: Remove all hardcoded `MaxSteps` values from workflow
|
||||
stages. Every stage inherits from `[budgets].max_steps` in the config.
|
||||
|
||||
**Reasoning**: Hardcoded values (15 for plan, 15 for TDD analyse, 15
|
||||
for feasibility assess, 20 for PRD) were arbitrary and broke on large
|
||||
repos. The config should be the single source of truth.
|
||||
|
||||
**Files affected**: `implement.go`, `tdd.go`, `feasibility.go`.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- No-op detection: close issues when build has 0 changes
|
||||
|
||||
**Decision**: When the builder completes with `StatusPassed` and 0 file
|
||||
changes, close the issue with a comment rather than parking on "worktree
|
||||
has no changes to commit".
|
||||
|
||||
**Reasoning**: A builder that passes with 0 changes means the fix
|
||||
already exists or the issue is a no-op. The old behaviour parked in an
|
||||
infinite loop (commit-push fails because nothing changed, task re-queues,
|
||||
builder runs again, same result).
|
||||
|
||||
**Implementation**: `TaskContext.BuildNoChanges` is set in the build
|
||||
stage's `OnResult` when `Status == Passed && len(Changes) == 0`.
|
||||
`StageCommitPush` checks this flag and calls `Forge.CloseIssue()` +
|
||||
sets `Outcome = Merged` to stop the workflow.
|
||||
|
||||
**Test**: `TestStageCommitPushClosesIssueWhenBuildNoChanges` in
|
||||
`implement_test.go`.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- assignee trigger over label trigger
|
||||
|
||||
**Decision**: Default to `trigger = "assignee"` instead of `trigger =
|
||||
"label"`. The daemon only claims issues explicitly assigned to the bot
|
||||
user.
|
||||
|
||||
**Reasoning**: Codex created 80+ issues with the `archie` label, and
|
||||
the daemon auto-claimed every one. Label-based triggering is too
|
||||
promiscuous for repos shared between humans and agents.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-23 -- DeepSeek v4 Pro as primary model
|
||||
|
||||
**Decision**: Use `deepseek/deepseek-v4-pro` as the planner and builder
|
||||
model. Qwythos-9B (local llama.cpp) is the fallback for offline/cheap
|
||||
tasks.
|
||||
|
||||
**Reasoning**: Qwythos couldn't complete a representative large-repository
|
||||
plan stage before timing out. DeepSeek completed it in 21 iterations. Large
|
||||
repositories need a larger model.
|
||||
|
||||
**Provider setup**: `class = "deepseek"`, API key via `DEEPSEEK_API_KEY`
|
||||
env var from Bitwarden Secrets Manager (bws).
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-22 -- v1.0.0 tagged
|
||||
|
||||
**Decision**: Tagged `v1.0.0` at commit incorporating the daemon/agent
|
||||
split, NATS JetStream, Docker sandbox, Yaegi plugins, agentskills.io
|
||||
skills, and Gitea forge support.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-22 -- Docker Compose stack with NATS + containers
|
||||
|
||||
**Decision**: The production deployment uses `docker-compose.yml` with
|
||||
NATS, archied, and archie-agent containers. Config at `config.docker.toml`.
|
||||
|
||||
**Key fixes**:
|
||||
|
||||
- NATS healthcheck uses `wget localhost:8222/healthz` (not `nats-server check`)
|
||||
- `host.docker.internal:host-gateway` extra_hosts for Linux
|
||||
- Config mount path: `config.docker.toml` → `/etc/archie/config.toml`
|
||||
- No stale `image:` tag on archied service (forces local build)
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-22 -- Worktree Prepare before Container Acquire
|
||||
|
||||
**Decision**: Clone the worktree (`Trees.Prepare()`) before acquiring
|
||||
a Docker container. Made `Prepare()` idempotent -- skips if `.git`
|
||||
already exists.
|
||||
|
||||
**Reasoning**: Docker bind-mounts fail with "bind source path does not
|
||||
exist" if the worktree hasn't been cloned yet. The old code acquired
|
||||
the container first, then the prepare stage cloned into a path that
|
||||
didn't exist on the host.
|
||||
|
||||
---
|
||||
|
||||
## 2026-07-22 -- Gofumpt and Go tools must be on PATH
|
||||
|
||||
**Decision**: The daemon's `exec.Command` for gate checks inherits the
|
||||
process PATH. `~/go/bin` (where `gofumpt`, `golangci-lint`, etc. live)
|
||||
must be in the PATH before starting the daemon.
|
||||
|
||||
**Symptom**: `baseline red -- gofumpt -w . fails` but manual run passes.
|
||||
Root cause: `which gofumpt` returns nothing because `~/go/bin` isn't on
|
||||
PATH in external agent sessions.
|
||||
@@ -1,235 +0,0 @@
|
||||
# Multi-Agent Collaboration -- PRD
|
||||
|
||||
**Status:** Draft (discovery interview complete, 2026-07-25)
|
||||
**Author:** Discovery interview (archie-core-abg.1), synthesised from Sam's answers
|
||||
**Parent epic:** archie-core-abg
|
||||
|
||||
---
|
||||
|
||||
## 0. Framing
|
||||
|
||||
Today, "running multiple agents" means running multiple independent `archied`
|
||||
processes on the same host (`carina`): `archie` (bot_user=archie, multiple
|
||||
repositories, deepseek models) and `winter` (bot_user=winter, a restricted
|
||||
repository set, local llama.cpp models). Confirmed by diffing
|
||||
`~/.config/archie/config.toml` and `~/.config/archie/winter.toml` on carina:
|
||||
they differ in `bot_user`, `[[repos]]` list, and `[models]`/`[providers]` --
|
||||
not just identity. `Config.BotUser` is a single global field, so one process
|
||||
= one identity today.
|
||||
|
||||
The goal stated for archie-core overall is to become a fully extensible
|
||||
agentic workhorse. This PRD
|
||||
scopes the "multi-agent" slice of that: what it takes to go from N processes
|
||||
to one daemon that can do what N processes do, plus the surrounding
|
||||
capabilities (chat channels, plugins, memory) needed to reach that bar.
|
||||
|
||||
## 1. Scope (confirmed in interview)
|
||||
|
||||
All of the following are **in scope** for the epic (not necessarily the first
|
||||
implementation slice -- see section 6):
|
||||
|
||||
1. **Daemon-side concurrency** -- one daemon process running multiple bot
|
||||
identities concurrently, replacing N separate `archied` processes.
|
||||
2. **Cross-repo / cross-config flexibility** -- identities are not statically
|
||||
bound to one repo list at process startup; repo/model/provider
|
||||
configuration varies per identity within a single daemon.
|
||||
3. **Agent-to-agent collaboration on a single task** -- one agent's output
|
||||
feeding another (e.g. plan -> implement -> review handoff), not just N
|
||||
identities running in parallel unaware of each other.
|
||||
4. **Conversational access** -- chat channels (Telegram, web UI, more via
|
||||
plugins) where Sam talks to archie directly, outside the Gitea
|
||||
issue-driven flow. Confirmed requirement: **full parity** with the
|
||||
issue-driven flow -- chat is an alternate entry point into the same
|
||||
triage/planner/builder dispatch pipeline, not a separate toy Q&A surface.
|
||||
Chat must be able to: answer questions read-only, spawn/control real work
|
||||
(start an agent, check status, approve/reject a PR, cancel a run), and
|
||||
drive the same pipeline Gitea assignment drives today.
|
||||
5. **General extensibility** -- plugins/channels/integrations should be
|
||||
addable, not hardcoded:
|
||||
- Additional forges beyond GitHub/Gitea (e.g. GitLab) via the existing
|
||||
`forge.Forge` interface, as Layer 2 core plugins (see
|
||||
`docs/prds/archie-core-v2-architecture.md` sec.5).
|
||||
- MCP server connections (archie as an MCP client, to consume external
|
||||
tools/data sources).
|
||||
- SSH / remote execution as an agent capability.
|
||||
- Arbitrary API integrations, callable by agents as tools.
|
||||
- Additional chat channels beyond Telegram/web UI, as plugins.
|
||||
6. **Memory systems for multi-session chat** -- conversations with archie
|
||||
need to persist across sessions (distinct from the existing per-task
|
||||
`/data/memory.jsonl` sketch in the v2 PRD, which is task/project scoped,
|
||||
not conversation scoped).
|
||||
7. **Slash-command capabilities** in chat channels (e.g. `/status`, `/spawn`,
|
||||
`/approve`) for direct channel interaction.
|
||||
8. **Multi-user support**, as a capability the architecture should not
|
||||
foreclose -- "if I want to extend my agent to multiple people, I should be
|
||||
able to." Not required to ship in the first slice (see section 5), but
|
||||
the identity/session model must not assume single-operator forever.
|
||||
|
||||
## 2. Explicitly out of scope (for now)
|
||||
|
||||
- **Voice/audio interfaces.** Text-based chat only.
|
||||
- **Building GitHub support** -- it already exists (`internal/forge`
|
||||
implements GitHub REST polling per `ARCHITECTURE.md`).
|
||||
- Anything not listed in section 1 that isn't a natural extension of the
|
||||
plugin/forge/channel interfaces below.
|
||||
|
||||
Note: multi-user auth and GitLab support are **in scope as capabilities the
|
||||
architecture must support**, but are not committed to the first
|
||||
implementation slice -- see section 5.
|
||||
|
||||
## 3. Constraints from existing architecture
|
||||
|
||||
From `ARCHITECTURE.md` and `docs/prds/archie-core-v2-architecture.md`
|
||||
(read in full before implementation; summarised here):
|
||||
|
||||
- **`Config.BotUser` is a single global field** (`internal/config`) -- the
|
||||
root blocker for daemon-side multi-identity. Becomes a per-identity field
|
||||
in a new config shape (see section 4).
|
||||
- **NATS/JetStream task distribution is implemented**: `internal/nats`
|
||||
publishes tasks to `archie.task.<workflow_type>` subjects; agents
|
||||
(in-process, subprocess, or Docker containers per `internal/container`)
|
||||
consume and report back over `archie.agent.<task_id>.{response,system,request}`.
|
||||
This subject hierarchy is a natural fit for routing by identity too
|
||||
(e.g. `archie.<identity>.task.<type>`) but that's a design decision, not
|
||||
yet made.
|
||||
- **Dispatch is `daemon.Run()` polling per configured forge/repo list**,
|
||||
serialised per `owner/repo` by default (`AllowConcurrent` opts out).
|
||||
Multi-identity daemon means multiple poll loops (or one loop iterating
|
||||
multiple identity configs) feeding the same NATS/container dispatch
|
||||
machinery.
|
||||
- **Layer 2 core plugins (`~/.config/archie/plugins/`, Yaegi-loaded,
|
||||
`Plugin.Register(daemon)`) are designed but not wired** -- interface
|
||||
exists (`internal/plugin/plugin.go`), no loader in `cmd/archied/main.go`.
|
||||
This is the natural extension point for new forges, MCP client
|
||||
connections, and chat channel plugins. Building the multi-agent epic on
|
||||
top of an unwired plugin layer means **wiring Layer 2 is a prerequisite**,
|
||||
not parallel work.
|
||||
- **No chat/messaging code exists today** -- no Telegram, no web UI beyond
|
||||
the read-only SSE dashboard (`internal/webui`). This is greenfield.
|
||||
- **The daemon gatekeeps all agent output** -- "no agent output reaches a
|
||||
human without daemon review" (`archie-core-v2-architecture.md` sec.7).
|
||||
Chat channels must respect this: a chat message that triggers a spawn goes
|
||||
through the same review/labelling machinery PRs and comments do today, not
|
||||
a side channel that bypasses it.
|
||||
- **Environmental constraints over prompt rules** (`ARCHITECTURE.md` design
|
||||
decision #1) -- chat-triggered actions (spawn, approve, cancel) should be
|
||||
enforced by code (permission checks, rate limits), not by asking the LLM
|
||||
nicely.
|
||||
|
||||
## 4. Identity model (design direction, not yet finalized)
|
||||
|
||||
Confirmed requirement: within one daemon, identities differ by bot identity,
|
||||
repo list, _and_ model/provider config (per the archie/winter diff). Proposed
|
||||
shape -- **not yet approved, needs a follow-up design pass before
|
||||
implementation**:
|
||||
|
||||
```toml
|
||||
# ~/.config/archie/config.toml (sketch)
|
||||
[[identities]]
|
||||
name = "archie"
|
||||
bot_user = "archie"
|
||||
forge = { type = "gitea", host = "...", token_env = "..." }
|
||||
models = { triage = "...", planner = "...", builder = "..." }
|
||||
repos = [ ... ]
|
||||
|
||||
[[identities]]
|
||||
name = "winter"
|
||||
bot_user = "winter"
|
||||
forge = { type = "gitea", host = "...", token_env = "..." }
|
||||
models = { triage = "...", planner = "...", builder = "..." }
|
||||
repos = [ ... ]
|
||||
```
|
||||
|
||||
```
|
||||
|
||||
**Design answer (2026-07-25): per-identity goroutine, shared infrastructure.**
|
||||
|
||||
Each identity gets its own goroutine running an independent poll loop with
|
||||
its own forge client, worktree manager, and NATS subject namespace
|
||||
(`archie.<identity>.task.<type>`). They share only the infrastructure
|
||||
pieces where isolation adds cost without benefit:
|
||||
|
||||
| Shared (one instance for all identities) | Per-identity (one per goroutine) |
|
||||
|---|---|
|
||||
| SQLite store (`internal/store`) | Forge client (different token per identity) |
|
||||
| NATS connection (`internal/nats`) | Worktree manager (different `BotUser` per identity) |
|
||||
| Container pool (`internal/container`) | Config subset: forge, repos, models, providers, dispatch, poll_interval, bot_user, bot_email |
|
||||
| Event bus (`internal/events`) | NATS subject namespace: `archie.<identity>.task.<type>` |
|
||||
| Web UI (`internal/webui`) | Poll loop goroutine |
|
||||
| Plugin registry (`internal/plugin`) | |
|
||||
| Gateway router (`internal/gateway`) | |
|
||||
|
||||
Decision rationale: per-identity goroutines guarantee failure isolation (one
|
||||
identity's forge outage cannot block another's poll tick), each identity
|
||||
gets its own forge rate-limit domain, and the existing `Daemon` struct maps
|
||||
cleanly -- each goroutine holds a thin `Identity` value (forge client + config
|
||||
subset + worktree manager + NATS subject prefix) and dispatches tasks with
|
||||
an `identity_name` column on the task row. The shared NATS connection
|
||||
multiplexes subjects by identity prefix; the shared store already handles
|
||||
concurrent ClaimNext via SQLite's serialized writes. NATS subjects carry
|
||||
the identity name so agent containers (which consume from NATS) route
|
||||
responses back to the correct daemon identity.
|
||||
|
||||
This design resolves the open question in section 4 of the original PRD
|
||||
draft (per-identity goroutine vs single loop iterating identities -- the
|
||||
former, for failure isolation).
|
||||
|
||||
## 5. Priority / phasing
|
||||
|
||||
Sam deferred ordering to this PRD (interview answer: "let the interview
|
||||
settle scope, I'll decide after seeing it written up"). Proposed
|
||||
dependency-ordered phases, for Sam to confirm or reorder:
|
||||
|
||||
**Phase A -- Foundation (blocks everything else)**
|
||||
- Wire Layer 2 core plugin loading (`~/.config/archie/plugins/`,
|
||||
`Plugin.Register(daemon)`) into `cmd/archied/main.go`. Currently designed,
|
||||
unwired -- both chat channels and new forges depend on this existing.
|
||||
|
||||
**Phase B -- Multi-identity daemon core**
|
||||
- Replace single `Config.BotUser` with the `[[identities]]` shape (section
|
||||
4, after design confirmation).
|
||||
- Multi-identity poll/dispatch, still issue-driven (Gitea only, no chat yet).
|
||||
- Migrate the two carina processes (archie, winter) onto one daemon as a
|
||||
real-world validation.
|
||||
|
||||
**Phase C -- Chat channel foundation**
|
||||
- Chat channel plugin interface (parallel to `forge.Forge`).
|
||||
- Telegram channel plugin: read-only Q&A against task/daemon state first,
|
||||
then spawn/control actions gated through the same review pipeline as
|
||||
issue-driven dispatch.
|
||||
- Web UI: extend `internal/webui` from read-only SSE dashboard to
|
||||
bidirectional chat.
|
||||
- Multi-session conversation memory (distinct persistence from per-task
|
||||
`/data/memory.jsonl`).
|
||||
- Slash commands (`/status`, `/spawn`, `/approve`, `/cancel`).
|
||||
|
||||
**Phase D -- Agent-to-agent collaboration**
|
||||
- Plan -> implement -> review handoff within a single task's workflow
|
||||
(builds on existing `workflow.Stage` sequencing -- this may already be
|
||||
close given the `implement` workflow's plan/build stage split; needs
|
||||
investigation into how much is genuinely new vs. reframing).
|
||||
|
||||
**Phase E -- Extended integrations (as needed, each is an independent
|
||||
plugin, no fixed order)**
|
||||
- GitLab forge plugin.
|
||||
- MCP client capability (archie consuming external MCP servers as tools).
|
||||
- SSH / remote execution tool.
|
||||
- Additional chat channels.
|
||||
- Multi-user support (identity/session model extended beyond
|
||||
single-operator -- needs its own design pass; not blocking Phase A-D).
|
||||
|
||||
Sam's explicit instruction was to identify next requirements **and begin
|
||||
work**, not just deliver a document. Phase A (wiring the Layer 2 plugin
|
||||
loader) is the correct starting point: it's small, well-specified already in
|
||||
`docs/prds/archie-core-v2-architecture.md` sec.5, and unblocks both the chat
|
||||
channel work and new forge plugins that everything else in this PRD depends
|
||||
on.
|
||||
|
||||
## 6. Acceptance criteria for this PRD
|
||||
|
||||
- [x] Reflects Sam's actual interview answers, not assumptions.
|
||||
- [x] Confirms the archie/winter config diff (repo lists differ, not just
|
||||
identity).
|
||||
- [ ] Broken into scoped, dependency-ordered beads issues under
|
||||
`archie-core-abg`, the way the 5zh epic was. (Next step, this session.)
|
||||
```
|
||||
@@ -1,461 +0,0 @@
|
||||
# archie-core TypeScript Plugin Engine -- PRD
|
||||
|
||||
**Author:** Archie
|
||||
**Date:** 2026-07-21
|
||||
**Status:** Draft
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
A TypeScript-based plugin engine that lets repositories ship interpreted, dynamically-loaded workflow extensions. Plugins are `.ts` files placed in `.archie/workflows/`. archie-core discovers them on its next poll cycle, transpiles them to JavaScript via esbuild, and executes them in an embedded [goja](https://github.com/dop251/goja) runtime -- a pure-Go ECMAScript interpreter with zero CGO dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Why TypeScript + goja
|
||||
|
||||
### TypeScript as the plugin language
|
||||
|
||||
TypeScript is the most widely understood language among developers writing automation, CI, and workflow scripts. It already ships in most projects. Gate authors already know it. The ecosystem for linting, formatting, and type-checking is mature and free.
|
||||
|
||||
Having a TypeScript-native plugin engine means:
|
||||
|
||||
- Plugin authors get familiar syntax, type safety, and IDE support
|
||||
- No separate toolchain -- just `.ts` files in a folder
|
||||
- Skills, gates, and workflow stages share the same language
|
||||
|
||||
### Why goja
|
||||
|
||||
| Competitor | Problem |
|
||||
| ------------------ | -------------------------------------------------------------------- |
|
||||
| V8 CGO bindings | Requires CGO, ~50MB static libraries, platform-specific builds |
|
||||
| QuickJS CGO | Requires CGO, smaller than V8 but still a C dependency |
|
||||
| QJS (Wazero) | Pure Go WASM, but sandboxed -- can't expose Go functions efficiently |
|
||||
| Ramune | Heavy dependency, bundles an entire TypeScript 7 compiler |
|
||||
| Node.js subprocess | Process overhead per execution, IPC serialisation cost |
|
||||
|
||||
goja is a pure-Go ECMAScript 5.1+ interpreter at ~20k lines. It:
|
||||
|
||||
- Has **zero CGO** -- cross-compiles everywhere Go does
|
||||
- Passes nearly all TC39 Test262 tests for ES5.1 + significant ES6 coverage
|
||||
- Can run Babel and the TypeScript compiler itself (proven capability)
|
||||
- Provides direct Go↔JS interop via `Set()`/`Get()`/`Runtime.RunString()`
|
||||
- Has a companion `goja_nodejs` package for `require()`, `setTimeout`, and `console`
|
||||
- Is used in production by k6 (Grafana's load testing tool, 30k+ stars)
|
||||
|
||||
### How TypeScript becomes JavaScript
|
||||
|
||||
arcie-core bundles esbuild via `go:embed`. On plugin load, TypeScript source is transpiled to ES2017 JavaScript in-process:
|
||||
|
||||
```
|
||||
.archie/workflows/security-gate.ts → esbuild.Transform() → goja.Runtime.RunString()
|
||||
```
|
||||
|
||||
esbuild is pure Go, takes ~3ms for typical gate scripts, and strips type annotations without type-checking (the plugin author does that in their editor). If the transpilation fails, the plugin is skipped with a diagnostic comment on the issue.
|
||||
|
||||
---
|
||||
|
||||
## Design
|
||||
|
||||
### Plugin discovery
|
||||
|
||||
During the poll cycle, archie-core scans each repo's worktree for `.archie/workflows/*.ts`:
|
||||
|
||||
```
|
||||
.archie/workflows/
|
||||
├── custom-gate.ts # gate functions: exported `check()`
|
||||
├── db-migration.ts # custom stage: exported `stage()`
|
||||
└── notify-slack.ts # skill script: exported `run()`
|
||||
```
|
||||
|
||||
Each file is a self-contained module. No `package.json`, no `node_modules`, no external imports. If you need external deps, they need to be exposed via archie-core's Go→JS bridge.
|
||||
|
||||
### Plugin types
|
||||
|
||||
A plugin declares its role via an exported symbol:
|
||||
|
||||
| Export | Role | When called |
|
||||
| ---------------------------------------------------- | -------------- | --------------------------------------------- |
|
||||
| `export function check(ctx: GateContext): Finding[]` | Gate function | After shell-based gate, before commit |
|
||||
| `export function stage(): Stage` | Workflow stage | When a workflow references the stage name |
|
||||
| `export function run(ctx: ScriptContext): void` | Skill script | When a skill's instructions invoke the script |
|
||||
|
||||
arcie-core discovers the role by checking which exports exist. A file can export multiple roles.
|
||||
|
||||
### Gate functions
|
||||
|
||||
```typescript
|
||||
// .archie/workflows/custom-gate.ts
|
||||
|
||||
interface GateContext {
|
||||
diff: string; // unified diff of changes
|
||||
changedFiles: string[]; // list of changed file paths
|
||||
dir: string; // absolute worktree path
|
||||
repo: string; // "owner/name"
|
||||
baseRef: string; // "origin/main"
|
||||
}
|
||||
|
||||
interface Finding {
|
||||
level: "error" | "warn";
|
||||
file?: string;
|
||||
line?: number;
|
||||
message: string;
|
||||
}
|
||||
|
||||
interface Block {
|
||||
name: string;
|
||||
message: string;
|
||||
}
|
||||
|
||||
export function check(ctx: GateContext): Finding[] {
|
||||
const findings: Finding[] = [];
|
||||
|
||||
// Rule: no new panic() calls
|
||||
for (const line of ctx.diff.split("\n")) {
|
||||
if (line.startsWith("+") && !line.startsWith("+++")) {
|
||||
if (line.includes("panic(")) {
|
||||
findings.push({
|
||||
level: "error",
|
||||
message: "new panic() call -- use error returns instead",
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Rule: no time.Sleep in non-test files
|
||||
for (const file of ctx.changedFiles) {
|
||||
if (file.endsWith("_test.go")) continue;
|
||||
const content = archie.readFile(`${ctx.dir}/${file}`);
|
||||
if (content.includes("time.Sleep")) {
|
||||
findings.push({
|
||||
level: "warn",
|
||||
file: file,
|
||||
message: "time.Sleep in non-test code -- use time.Ticker instead",
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return findings;
|
||||
}
|
||||
```
|
||||
|
||||
After transpilation and execution, archie-core calls `check(ctx)` via goja. Error-level findings park the task. Warn-level findings are logged.
|
||||
|
||||
### Custom workflow stages
|
||||
|
||||
```typescript
|
||||
// .archie/workflows/run-migrations.ts
|
||||
|
||||
export function stage(): Stage {
|
||||
return {
|
||||
name: "db-migration",
|
||||
run: (ctx: TaskContext): string | null => {
|
||||
// Check if migrations directory exists
|
||||
const hasMigrations = archie.fileExists(`${ctx.dir}/migrations`);
|
||||
if (!hasMigrations) return null; // nothing to do
|
||||
|
||||
// Run migration tests
|
||||
const result = archie.exec("go", ["test", "./migrations/..."]);
|
||||
if (result.exitCode !== 0) {
|
||||
return `migration tests failed: ${result.stderr}`;
|
||||
}
|
||||
return null; // success
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
### Skill scripts
|
||||
|
||||
```typescript
|
||||
// .archie/workflows/security-audit.ts
|
||||
|
||||
export function run(ctx: ScriptContext): void {
|
||||
const result = archie.exec("gitleaks", ["detect", "--no-git"]);
|
||||
if (result.exitCode !== 0) {
|
||||
archie.log("warn", `gitleaks found secrets:\n${result.stdout}`);
|
||||
}
|
||||
archie.log("info", "security audit complete");
|
||||
}
|
||||
```
|
||||
|
||||
### archie Go→JS bridge
|
||||
|
||||
arcie-core exposes a `archie` global in the goja runtime:
|
||||
|
||||
```typescript
|
||||
interface Archie {
|
||||
// File operations (scoped to worktree)
|
||||
readFile(path: string): string;
|
||||
fileExists(path: string): boolean;
|
||||
listDir(path: string): string[];
|
||||
walkDir(path: string): string[];
|
||||
|
||||
// Shell execution
|
||||
exec(command: string, args?: string[]): ExecResult;
|
||||
|
||||
// Logging
|
||||
log(level: string, message: string): void;
|
||||
|
||||
// Path utilities
|
||||
resolve(...parts: string[]): string;
|
||||
ext(path: string): string;
|
||||
|
||||
// Environment
|
||||
env(key: string): string;
|
||||
|
||||
// HTTP (optional, gated)
|
||||
fetch(url: string, options?: FetchOptions): FetchResult;
|
||||
}
|
||||
|
||||
interface ExecResult {
|
||||
stdout: string;
|
||||
stderr: string;
|
||||
exitCode: number;
|
||||
}
|
||||
```
|
||||
|
||||
All file operations are **jailed to the worktree**. `archie.readFile("/etc/passwd")` fails. The bridge enforces this in Go before passing the path to the OS.
|
||||
|
||||
### Reload cycle
|
||||
|
||||
Plugins are loaded fresh on every poll cycle -- archie-core already fresh-clones per task. No hot-reload complexity, no cache invalidation. The worktree is the source of truth.
|
||||
|
||||
For the rare case where a plugin errors at parse/transpile time, archie-core comments on the issue with the diagnostic and parks the task. The plugin author fixes the `.ts` file and requeues.
|
||||
|
||||
---
|
||||
|
||||
## Implementation
|
||||
|
||||
### Architecture
|
||||
|
||||
```
|
||||
internal/plugins/
|
||||
├── loader.go # scan .archie/workflows/, transpile, evaluate
|
||||
├── runtime.go # goja runtime pool management
|
||||
├── bridge.go # archie global (file I/O, exec, log, fetch)
|
||||
├── types.go # GateContext, Finding, Stage, TaskContext → JS types
|
||||
├── loader_test.go
|
||||
└── testdata/
|
||||
└── workflows/
|
||||
├── gate.ts # test gate plugin
|
||||
└── stage.ts # test stage plugin
|
||||
```
|
||||
|
||||
### goja runtime pool
|
||||
|
||||
Workflow stages and gates need a clean goja runtime per execution. Creating a new runtime per call is slow (~50ms for stdlib setup). A pool of pre-warmed runtimes solves this:
|
||||
|
||||
```go
|
||||
type Pool struct {
|
||||
warm chan *goja.Runtime
|
||||
}
|
||||
|
||||
func NewPool(size int) *Pool {
|
||||
p := &Pool{warm: make(chan *goja.Runtime, size)}
|
||||
for i := 0; i < size; i++ {
|
||||
rt := goja.New()
|
||||
installBridge(rt) // register the `archie` global
|
||||
installStdlib(rt) // console, setTimeout, etc.
|
||||
p.warm <- rt
|
||||
}
|
||||
return p
|
||||
}
|
||||
|
||||
func (p *Pool) Run(ctx context.Context, src string, globals map[string]any) (goja.Value, error) {
|
||||
rt := <-p.warm
|
||||
defer func() { p.warm <- rt }()
|
||||
// Set per-execution globals
|
||||
for k, v := range globals {
|
||||
rt.Set(k, v)
|
||||
}
|
||||
return rt.RunString(src)
|
||||
}
|
||||
```
|
||||
|
||||
### Transpile pipeline
|
||||
|
||||
```go
|
||||
func (l *Loader) transpile(filename string, ts []byte) (string, error) {
|
||||
result := l.esbuild.Transform(string(ts), api.TransformOptions{
|
||||
Loader: api.LoaderTS,
|
||||
Target: api.ES2017,
|
||||
Sourcefile: filename,
|
||||
})
|
||||
if len(result.Errors) > 0 {
|
||||
return "", fmt.Errorf("transpile %s: %v", filename, result.Errors)
|
||||
}
|
||||
return string(result.Code), nil
|
||||
}
|
||||
```
|
||||
|
||||
### load pipeline
|
||||
|
||||
```go
|
||||
func (l *Loader) LoadPlugins(worktreeDir string) ([]Plugin, error) {
|
||||
dir := filepath.Join(worktreeDir, ".archie", "workflows")
|
||||
entries, err := os.ReadDir(dir)
|
||||
if os.IsNotExist(err) {
|
||||
return nil, nil // no plugins -- not an error
|
||||
}
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
var plugins []Plugin
|
||||
for _, e := range entries {
|
||||
if !strings.HasSuffix(e.Name(), ".ts") {
|
||||
continue
|
||||
}
|
||||
path := filepath.Join(dir, e.Name())
|
||||
src, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
js, err := l.transpile(e.Name(), src)
|
||||
if err != nil {
|
||||
l.log.Warn("plugin transpile failed", "file", e.Name(), "err", err)
|
||||
continue
|
||||
}
|
||||
rt := l.pool.Acquire()
|
||||
_, err = rt.RunString(js)
|
||||
l.pool.Release(rt)
|
||||
if err != nil {
|
||||
l.log.Warn("plugin eval failed", "file", e.Name(), "err", err)
|
||||
continue
|
||||
}
|
||||
plugins = append(plugins, discover(rt, e.Name())...)
|
||||
}
|
||||
return plugins, nil
|
||||
}
|
||||
```
|
||||
|
||||
### Export discovery
|
||||
|
||||
```go
|
||||
func discover(rt *goja.Runtime, filename string) []Plugin {
|
||||
var out []Plugin
|
||||
if check := rt.Get("check"); check != nil {
|
||||
out = append(out, Plugin{Kind: "gate", Name: filename, Func: check})
|
||||
}
|
||||
if stage := rt.Get("stage"); stage != nil {
|
||||
out = append(out, Plugin{Kind: "stage", Name: filename, Func: stage})
|
||||
}
|
||||
if run := rt.Get("run"); run != nil {
|
||||
out = append(out, Plugin{Kind: "script", Name: filename, Func: run})
|
||||
}
|
||||
return out
|
||||
}
|
||||
```
|
||||
|
||||
### Wiring into the daemon
|
||||
|
||||
In `daemon.process()`:
|
||||
|
||||
```go
|
||||
// After worktree prepare, before gate stage:
|
||||
plugins, err := d.Plugins.LoadPlugins(tc.Dir)
|
||||
if err != nil {
|
||||
d.Log.Warn("plugin load failed", "err", err)
|
||||
}
|
||||
tc.Plugins = plugins // available to all stages via TaskContext
|
||||
|
||||
// In the gate stage:
|
||||
if gatePlugin := tc.Plugins.Gate(); gatePlugin != nil {
|
||||
findings := callGatePlugin(gatePlugin, gateContext(tc))
|
||||
for _, f := range findings {
|
||||
if f.Level == "error" {
|
||||
// park the task
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
### goja's ECMAScript coverage
|
||||
|
||||
goja natively supports ES5.1 with significant ES6 features. Modern syntax like `async/await`, `??`, `?.`, or `class` fields may not parse. The transpile step (esbuild targeting ES2017) handles most of this, but there will be edge cases:
|
||||
|
||||
| Feature | Status |
|
||||
| ----------------- | -------------------------------------- |
|
||||
| Arrow functions | ✅ via transpile |
|
||||
| Template literals | ✅ via transpile |
|
||||
| Destructuring | ✅ via transpile |
|
||||
| `const`/`let` | ✅ via transpile |
|
||||
| `async/await` | ❌ not supported (goja is synchronous) |
|
||||
| `Promise` | ❌ requires `goja_nodejs` event loop |
|
||||
| Generators | ❌ not supported |
|
||||
| `Proxy` | ❌ not supported |
|
||||
|
||||
For gate scripts, this is fine -- gates are synchronous by nature. If async is genuinely needed later, the Bun backend (via `tsgo`) is the escape hatch.
|
||||
|
||||
### Performance
|
||||
|
||||
Gate scripts run once per task. Even a 100ms transpile+eval overhead is negligible compared to the LLM calls in the workflow. If a plugin becomes hot-path, it should be promoted to a compiled Go stage.
|
||||
|
||||
### No external imports
|
||||
|
||||
Plugins can't `import` from npm or other files. They're self-contained modules. Complexity that needs external deps should be a compiled Go stage, not a plugin. The `archie` global provides filesystem and shell access, which covers the common cases.
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Yaegi vs goja
|
||||
|
||||
| | Yaegi (Go) | goja + esbuild (TypeScript) |
|
||||
| -------------------- | ----------------------------------------------------------- | --------------------------------------------------------- |
|
||||
| **Language** | Go | TypeScript |
|
||||
| **Pure Go** | ✅ | ✅ (goja + esbuild both pure Go) |
|
||||
| **CGO** | None | None |
|
||||
| **Transpile step** | None (interpreted directly) | esbuild TS→JS (~3ms) |
|
||||
| **Author audience** | Go developers | Anyone who knows TypeScript |
|
||||
| **Type annotations** | N/A (Go is typed) | Stripped by esbuild (no type-check at runtime) |
|
||||
| **Interop** | Direct Go↔Go via `Use()` | Bridge via `archie` global |
|
||||
| **Performance** | Interpreted Go (~10x slower than compiled) | Interpreted JS (~50x slower than V8, fine for gates) |
|
||||
| **Maturity** | 8k stars, used by Traefik for plugins | 7k stars, used by k6, goja is battle-tested |
|
||||
| **File extension** | `.go` | `.ts` |
|
||||
| **Plugin folder** | `.archie/workflows/` | `.archie/workflows/` |
|
||||
| **Best for** | Custom stages needing Go's stdlib, tight daemon integration | Custom gates and scripts where author familiarity matters |
|
||||
|
||||
**Recommendation: support both.** They solve different problems. Yaegi for repo owners who want full Go power in their custom stages. goja for repo owners who want to write gates and scripts in TypeScript. Both load from `.archie/workflows/` -- archie-core discovers which engine to use by file extension (`.go` → Yaegi, `.ts` → goja+esbuild).
|
||||
|
||||
---
|
||||
|
||||
## Implementation phases
|
||||
|
||||
### Phase 1: goja runtime + esbuild
|
||||
|
||||
- Add `github.com/dop251/goja` and `github.com/evanw/esbuild` as dependencies
|
||||
- Build `internal/plugins/` with loader, runtime pool, bridge
|
||||
- Wire gate plugin discovery into the implement and TDD workflows
|
||||
- Gate plugins run after shell-based gate, before commit
|
||||
|
||||
### Phase 2: Custom stages
|
||||
|
||||
- Stage plugins discovered and registered alongside built-in stages
|
||||
- `config.toml` can reference plugin stages by name
|
||||
- TaskContext exposed to JS plugins
|
||||
|
||||
### Phase 3: Skill scripts
|
||||
|
||||
- Skill SKILL.md can reference `scripts/security-audit.ts`
|
||||
- archie-core loads, transpiles, and evaluates when the skill activates
|
||||
- Script stdout captured and returned to the agent as tool output
|
||||
|
||||
### Phase 4: Yaegi side-by-side
|
||||
|
||||
- Go plugin files (`.go`) loaded via Yaegi from the same `.archie/workflows/` directory
|
||||
- Same discovery pattern, different interpreter
|
||||
- archie-core chooses engine by file extension
|
||||
|
||||
---
|
||||
|
||||
## Open questions
|
||||
|
||||
1. **Jailing:** How strict should the `archie` bridge be? File I/O jailed to worktree, no network access by default? Or trust the repo author?
|
||||
2. **Error UX:** When a plugin fails to transpile, should archie-core comment on the issue with the specific error, or just park silently?
|
||||
3. **Runtime pool sizing:** 4 warmed runtimes? Dynamic?
|
||||
4. **Plugin versioning:** Do plugins get a `version` export? Or is the git commit the version?
|
||||
5. **TypeScript type definitions:** Ship a `.d.ts` file for the `archie` global so plugin authors get IntelliSense?
|
||||
@@ -1,337 +0,0 @@
|
||||
# archie-core Yaegi Plugin System -- PRD
|
||||
|
||||
**Author:** Archie
|
||||
**Date:** 2026-07-21
|
||||
**Status:** Draft
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Embed the [Yaegi](https://github.com/traefik/yaegi) Go interpreter to let
|
||||
archie-core load and execute `.go` files at runtime. This enables three things
|
||||
that shell commands can't do: **custom gates with deep worktree inspection**,
|
||||
**custom workflow stages defined per-repo**, and **skill scripts written in Go
|
||||
instead of shell**.
|
||||
|
||||
---
|
||||
|
||||
## Why Yaegi
|
||||
|
||||
### The problem with shell-only gates
|
||||
|
||||
`[[repos.gate]]` is command lists. That's fine for standard tooling (`go vet`,
|
||||
`golangci-lint`), but it can't express project-specific rules:
|
||||
|
||||
- "No new `panic()` calls in the diff"
|
||||
- "No new dependencies in `go.mod` without justification"
|
||||
- "All public functions in `pkg/api/` must be documented"
|
||||
- "No `time.Sleep` in production code paths"
|
||||
|
||||
These are rules that need to read the diff, parse Go ASTs, or walk the worktree
|
||||
-- things shell scripts can do but shouldn't have to.
|
||||
|
||||
### Why not shell scripts?
|
||||
|
||||
Shell scripts for gates are fine until they're not. They can't import the
|
||||
archie-core types, can't use the Go parser, and are a second language to
|
||||
maintain alongside the daemon. Yaegi runs Go -- the same language as the daemon,
|
||||
the same language as the repos archie-core works on.
|
||||
|
||||
### Why not Go's native `plugin` package?
|
||||
|
||||
Go's `plugin` package (`.so` files) requires:
|
||||
|
||||
- Exact same Go version and deps as the host binary
|
||||
- Linux/macOS only
|
||||
- No unload
|
||||
- Painful distribution
|
||||
|
||||
Yaegi interprets `.go` source files directly -- no compilation step, portable
|
||||
everywhere, loads from filesystem paths.
|
||||
|
||||
### Production precedent
|
||||
|
||||
- **Traefik:** 200+ community plugins via Yaegi, loaded from plugins.traefik.io
|
||||
- **Vikunja:** Adopted Yaegi for plugin system (see PR #2178), loads plugins
|
||||
from `plugins/` directory
|
||||
|
||||
---
|
||||
|
||||
## Design
|
||||
|
||||
### Three extension surfaces
|
||||
|
||||
| Surface | Location | When loaded | What it does |
|
||||
| -------------------------- | ------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------- |
|
||||
| **Custom gate functions** | `.archie/gate.go` | During the gate stage (after shell commands) | Returns `[]Finding` -- each finding has severity, message, file, line |
|
||||
| **Custom workflow stages** | `.archie/stages/<name>.go` | When the workflow references the stage name | Returns a `workflow.Stage` implementation |
|
||||
| **Skill scripts** | `.archie/skills/<skill>/scripts/*.go` | When the parent skill is activated | Called by the skill's instructions |
|
||||
|
||||
### Gate functions (`.archie/gate.go`)
|
||||
|
||||
The most important extension surface. After the shell-based gate passes,
|
||||
archie-core loads and evaluates `.archie/gate.go` in the worktree directory. The
|
||||
script exposes a `Check` function:
|
||||
|
||||
```go
|
||||
// .archie/gate.go -- per-repo gate rules interpreted at runtime
|
||||
package gate
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// GateContext carries everything the gate checker can inspect.
|
||||
type GateContext struct {
|
||||
Diff string // unified diff of all changes
|
||||
ChangedFiles []string // list of changed file paths (repo-relative)
|
||||
Dir string // absolute worktree path
|
||||
BaseRef string // base branch (e.g. "origin/main")
|
||||
Repo string // "owner/name"
|
||||
}
|
||||
|
||||
// Finding is one gate violation.
|
||||
type Finding struct {
|
||||
Level string // "error" (blocks commit) or "warn" (advisory)
|
||||
File string // optional file path
|
||||
Line int // optional line number
|
||||
Message string
|
||||
}
|
||||
|
||||
// Block defines a named rule that can prevent passing.
|
||||
type Block struct {
|
||||
Name string
|
||||
Message string
|
||||
}
|
||||
|
||||
// Check returns findings for the gate. Return nil for a clean gate.
|
||||
func Check(ctx GateContext) []Finding {
|
||||
var findings []Finding
|
||||
|
||||
// Rule: no new panic() calls in committed code
|
||||
for _, line := range strings.Split(ctx.Diff, "\n") {
|
||||
if strings.HasPrefix(line, "+") && !strings.HasPrefix(line, "+++") {
|
||||
if strings.Contains(line, "panic(") {
|
||||
findings = append(findings, Finding{
|
||||
Level: "error",
|
||||
Message: "new panic() call -- use error returns instead",
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Rule: no time.Sleep in non-test files
|
||||
for _, f := range ctx.ChangedFiles {
|
||||
if strings.HasSuffix(f, "_test.go") {
|
||||
continue
|
||||
}
|
||||
path := filepath.Join(ctx.Dir, f)
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
if strings.Contains(string(b), "time.Sleep") {
|
||||
findings = append(findings, Finding{
|
||||
Level: "warn",
|
||||
File: f,
|
||||
Message: "time.Sleep in non-test code -- use time.Ticker or context.WithTimeout instead",
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
return findings
|
||||
}
|
||||
```
|
||||
|
||||
The daemon:
|
||||
|
||||
1. Reads `.archie/gate.go` from the worktree
|
||||
2. Creates a Yaegi interpreter with `GateContext` and `Finding` types pre-loaded
|
||||
via `Use()`
|
||||
3. Evaluates the file
|
||||
4. Calls `Check(ctx)` via `Eval("gate.Check")` + `Interface()`
|
||||
5. Logs findings and blocks the gate if any have `Level: "error"`
|
||||
|
||||
### Custom workflow stages (`.archie/stages/`)
|
||||
|
||||
A repo can define custom pipeline stages that archie-core discovers and makes
|
||||
routable:
|
||||
|
||||
```go
|
||||
// .archie/stages/run-migrations.go
|
||||
package stages
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/workflow"
|
||||
|
||||
func Stage() workflow.Stage {
|
||||
return workflow.Stage{
|
||||
Name: "db-migration",
|
||||
Run: func(ctx context.Context, tc *workflow.TaskContext) error {
|
||||
// Check if go.mod contains migration tools
|
||||
// Run migration tests
|
||||
// Verify schema compatibility
|
||||
return nil
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Registered stages appear alongside built-in stages. A workflow in `config.toml`
|
||||
can reference them by name:
|
||||
|
||||
```toml
|
||||
[[workflows.stages]]
|
||||
name = "db-migration" # matches the .go file
|
||||
source = "repo" # loaded from .archie/stages/
|
||||
```
|
||||
|
||||
### Skill scripts (`.archie/skills/<skill>/scripts/`)
|
||||
|
||||
Skills can ship Go scripts that archie-core interprets:
|
||||
|
||||
```go
|
||||
// .archie/skills/security-audit/scripts/gitleaks.go
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os/exec"
|
||||
"context"
|
||||
)
|
||||
|
||||
func main() {
|
||||
ctx := context.Background()
|
||||
cmd := exec.CommandContext(ctx, "gitleaks", "detect", "--no-git", "--verbose")
|
||||
out, _ := cmd.CombinedOutput()
|
||||
fmt.Println(string(out))
|
||||
}
|
||||
```
|
||||
|
||||
Skills reference these scripts naturally in their instructions: "Run
|
||||
`scripts/gitleaks.go` to scan for secrets."
|
||||
|
||||
---
|
||||
|
||||
## API surface archie-core exposes to Yaegi
|
||||
|
||||
Via `i.Use()`, the daemon pre-loads symbols that interpreted code can import:
|
||||
|
||||
| Package | What's exposed |
|
||||
| ------------------------------- | ----------------------------------------- |
|
||||
| `archie-core/internal/workflow` | `Stage`, `TaskContext`, `Outcome` |
|
||||
| `archie-core/internal/gate` | `GateContext`, `Finding`, `Block` |
|
||||
| `stdlib` | Full Go standard library (stdlib.Symbols) |
|
||||
|
||||
Generated with `yaegi extract` -- same approach Traefik and Vikunja use. A
|
||||
`//go:generate yaegi extract ...` line in the source triggers symbol table
|
||||
generation during `go generate`.
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
From Yaegi's own docs:
|
||||
|
||||
- **No assembly files** (`.s` not supported)
|
||||
- **No CGo** (can't call C code -- the daemon is pure Go, so this doesn't
|
||||
matter)
|
||||
- **No compiler/linker directives** (no `//go:embed`, etc. -- fine for gate
|
||||
scripts)
|
||||
- **Interfaces from pre-compiled code can't be added dynamically** -- the daemon
|
||||
must pre-compile wrapper types for any interface interpreted code needs to
|
||||
implement
|
||||
- **Slower than compiled code** -- gate scripts run once per commit, not in hot
|
||||
paths; negligible impact
|
||||
|
||||
The Vikunja PR documents a specific Yaegi quirk: **typed factory functions
|
||||
required.** You can't do `v.Interface().(MyInterface)` on a value returned from
|
||||
interpreted code. Each interface needs its own factory:
|
||||
|
||||
```go
|
||||
func NewGate() Gate { return &MyGate{} }
|
||||
func NewReportable() Reportable { return &MyGate{} }
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Implementation phases
|
||||
|
||||
### Phase 1: Gate functions -- implemented
|
||||
|
||||
- `yaegi` added as a dependency
|
||||
- Symbol table for `GateContext`, `Finding` generated via `yaegi extract` into
|
||||
`internal/gate/gateextract` (a separate package from `internal/gate` itself,
|
||||
avoiding the self-import cycle extracting a package's own symbols creates)
|
||||
- `internal/gate/gateeval.Evaluate`: loads `.archie/gate.go` from the worktree,
|
||||
interprets it, calls `Check()`; panics are recovered
|
||||
- Wired in as `workflow.StageYaegiGate`, run after the final commit in both the
|
||||
`implement` and `tdd` workflows
|
||||
- Error findings park the task; warn findings are logged only
|
||||
|
||||
### Phase 2: Custom stages -- implemented
|
||||
|
||||
- Symbol table for `workflow.Stage`/`TaskContext`/`Outcome` generated into
|
||||
`internal/workflow/wfextract`
|
||||
- `internal/workflow/wfeval.Discover` scans `.archie/stages/*.go` in filename
|
||||
order and calls each file's exported `Stage()` function
|
||||
- `TaskContext.CustomStages` is an injected `func(dir string) ([]Stage, error)`
|
||||
-- the composition root (`cmd/archied`) wires it to `wfeval.Discover`, keeping
|
||||
`internal/workflow` decoupled from its own generated symbol table
|
||||
- `workflow.StageRepoStages` runs discovered stages in order right after the
|
||||
worktree is prepared, in both `implement` and `tdd`
|
||||
- Simplification vs. the original sketch: stages are auto-discovered and always
|
||||
run (like `.archie/gate.go`) rather than referenced by name from `config.toml`
|
||||
-- the workflow engine has no data-driven stage graph today, so wiring
|
||||
arbitrary named stages into arbitrary positions would need a larger
|
||||
config-driven rework. Auto-run-in-order covers the PRD's actual use case (a
|
||||
repo-defined pre-flight/setup hook) without it.
|
||||
|
||||
### Phase 3: Skill scripts -- implemented
|
||||
|
||||
- `internal/skillscript.Run` interprets a `.go` file via `i.EvalPath`, which
|
||||
(like `go run`) evaluates and calls its `main()`; stdout/stderr are captured
|
||||
via `interp.Options`
|
||||
- Uses `stdlib.Symbols` + `stdlib/unrestricted.Symbols` (not just `stdlib`) --
|
||||
`os/exec` lives in the unrestricted set, and the PRD's own example script
|
||||
shells out via `os/exec`
|
||||
- No archie-core-specific symbol table needed here -- skill scripts only touch
|
||||
the Go standard library
|
||||
- Exposed to the agent loop as a new `run_go_script` tool
|
||||
(`internal/agentexec/inprocess.go`), available in every agent stage; path is
|
||||
validated to stay inside the workspace
|
||||
- This is how "the skill's instructions reference a script" cashes out
|
||||
concretely: the agent calls `run_go_script` with the path instead of needing a
|
||||
Go toolchain in the sandbox
|
||||
|
||||
### Phase 4: Hot reload -- not needed, by construction
|
||||
|
||||
- All three loaders (`gate.Evaluate`, `wfeval.Discover`, `skillscript.Run`) read
|
||||
their `.go` source from disk on every call -- no in-memory cache exists
|
||||
anywhere in the implementation
|
||||
- Every task additionally gets a fresh `git clone` (`worktree.Manager.Prepare`
|
||||
removes and re-clones the worktree directory per task)
|
||||
- Consequently every stage already re-reads `.archie/gate.go`,
|
||||
`.archie/stages/*.go`, and skill scripts fresh, every run -- there is no stale
|
||||
state a file watcher would ever need to invalidate
|
||||
- A file-watching daemon-runtime reload mechanism would add machinery with
|
||||
nothing to do given this architecture; revisit only if the daemon starts
|
||||
reusing long-lived worktrees across tasks
|
||||
|
||||
---
|
||||
|
||||
## Open questions
|
||||
|
||||
1. **Symbol table generation:** Run `yaegi extract` as a `go generate` step, or
|
||||
generate on daemon startup?
|
||||
2. **Error handling:** If the interpreted gate panics or times out, park the
|
||||
task? Or fall back to shell-only gate?
|
||||
3. **Budget:** Interpreted gate scripts run in the gate stage -- should they
|
||||
have their own timeout/step budget?
|
||||
4. **Template system:** Should archie-core ship with common gate templates (e.g.
|
||||
`go: no panic, no Sleep, no hardcoded paths`)?
|
||||
5. **Remote gates:** Could `.archie/gate.go` be pulled from a shared remote
|
||||
registry, like skills?
|
||||
@@ -26,6 +26,10 @@
|
||||
"gate": {
|
||||
"$ref": "#/schemas/Gate"
|
||||
},
|
||||
"harness": {
|
||||
"$ref": "#/schemas/HarnessSpec",
|
||||
"description": "Harness, when set, runs the stage on an external coding-agent CLI\ninstead of the built-in loop. The worker in a Kit container is the\ndaemon's own archie-agent build, so it always understands this field."
|
||||
},
|
||||
"mission": {
|
||||
"type": "string"
|
||||
},
|
||||
@@ -137,7 +141,14 @@
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": ["version", "task_id", "attempt", "stage", "status", "usage"],
|
||||
"required": [
|
||||
"version",
|
||||
"task_id",
|
||||
"attempt",
|
||||
"stage",
|
||||
"status",
|
||||
"usage"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Budget": {
|
||||
@@ -196,7 +207,9 @@
|
||||
"type": "object"
|
||||
}
|
||||
},
|
||||
"required": ["name"],
|
||||
"required": [
|
||||
"name"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Command": {
|
||||
@@ -216,7 +229,10 @@
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["name", "argv"],
|
||||
"required": [
|
||||
"name",
|
||||
"argv"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Gate": {
|
||||
@@ -235,10 +251,72 @@
|
||||
},
|
||||
"type": "object"
|
||||
},
|
||||
"HarnessSpec": {
|
||||
"additionalProperties": false,
|
||||
"description": "HarnessSpec is how to drive a Kit's agent headlessly: its launch argv (image entrypoint and cmd) and the agent-sessions@1 verb tails appended to it.",
|
||||
"properties": {
|
||||
"adapter": {
|
||||
"description": "Adapter names the output adapter reading the CLI's stream; empty is\na CLI with none.",
|
||||
"type": "string"
|
||||
},
|
||||
"continue": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"env": {
|
||||
"description": "Env is the invocation's entire environment. Nothing is inherited from\nthe worker, whose environment carries its credentials.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"launch": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"mcp_config": {
|
||||
"description": "MCPConfig registers archie's MCP server with the CLI: an argv tail\ncarrying {{.MCPConfig}}, the path of a standard mcpServers config.\nA stage with capture tools needs it.",
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"prompt": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"resume": {
|
||||
"items": {
|
||||
"type": "string"
|
||||
},
|
||||
"type": "array"
|
||||
},
|
||||
"user": {
|
||||
"description": "User is the Kit's user, a name or \"uid[:gid]\", that every invocation\nruns as. It is never root: the worker's credentials live in the same\ncontainer, readable only by the worker's user.",
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"launch",
|
||||
"prompt"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"MediaAttachment": {
|
||||
"additionalProperties": false,
|
||||
"description": "MediaAttachment describes a file attached to a message.",
|
||||
"properties": {
|
||||
"data": {
|
||||
"contentEncoding": "base64",
|
||||
"description": "Data carries the attachment bytes in-process. An inbound path sets\nit after downloading the file; outbound senders never set it and\nread Path or URL instead. It crosses the wire in one direction only:\nthe inbound request from a channel frontend to the Gateway process\nthat runs the turn, because that process never holds the platform\ncredential. It is never persisted, and the stored-history and\noutbound-event directions strip it.",
|
||||
"type": "string"
|
||||
},
|
||||
"duration": {
|
||||
"description": "Duration is the play time in seconds for audio and video.",
|
||||
"type": "integer"
|
||||
@@ -272,7 +350,7 @@
|
||||
"type": "object"
|
||||
},
|
||||
"type": {
|
||||
"description": "Type is \"image\", \"video\", \"audio\", or \"document\".",
|
||||
"description": "Type is \"image\", \"video\", \"audio\", \"voice\", or \"document\".",
|
||||
"type": "string"
|
||||
},
|
||||
"url": {
|
||||
@@ -284,7 +362,10 @@
|
||||
"type": "integer"
|
||||
}
|
||||
},
|
||||
"required": ["type", "file_id"],
|
||||
"required": [
|
||||
"type",
|
||||
"file_id"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"MessageEvent": {
|
||||
@@ -343,7 +424,12 @@
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["type", "channel_id", "platform", "sender_id"],
|
||||
"required": [
|
||||
"type",
|
||||
"channel_id",
|
||||
"platform",
|
||||
"sender_id"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"PluginSpec": {
|
||||
@@ -357,7 +443,10 @@
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": ["name", "src"],
|
||||
"required": [
|
||||
"name",
|
||||
"src"
|
||||
],
|
||||
"type": "object"
|
||||
},
|
||||
"Protection": {
|
||||
|
||||
@@ -10,13 +10,13 @@
|
||||
"url": "/dev/architecture/adversarial-review/",
|
||||
"title": "Adversarial self-review",
|
||||
"section": "Architecture",
|
||||
"body": "# Adversarial self-review\n\nArchie runs a fresh adversarial review of the diff before it opens a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## Operator-triggered review\n\nThe same reviewer runs against an *existing* PR via the channel-neutral\n`review_pr` chat command: fetch the PR's head, snapshot it, run the isolated\nreviewer, and return the structured findings. Authorisation is identity-scoped\nto the operator's configured repositories; duplicate or concurrent reviews of\nthe same PR are deduplicated.\n"
|
||||
"body": "# Adversarial self-review\n\n\u003e **Removed, not shipped (2026-09-28, `d73e0748`). This page records a system\n\u003e that no longer exists in the tree.**\n\u003e\n\u003e `d73e0748` (\"remove the superseded adversarial-self-review system\") deleted the\n\u003e stage and its contract: `workflow.Reviewer`, `ReviewRequest`, `ReviewReport`\n\u003e and `StageReview` are gone from `internal/domain/workflow`, so everything under\n\u003e \"Contract\" below describes types that cannot be found.\n\u003e\n\u003e The authority is `docs/prds/pr-review-agent.md`, which says so itself: it\n\u003e \"supersedes the reviewer executor and blocking rule in\n\u003e `docs/architecture/adversarial-review.md`\". archied now runs its PR review\n\u003e pipeline before it opens a pull request; there is no separate adversarial\n\u003e self-review pass and no `repo.review_enabled` setting.\n\u003e\n\u003e The page is kept rather than deleted because PRDs link to it\n\u003e (`docs/prds/adversarial-self-review.md`, `docs/prds/inline-review.md`,\n\u003e `docs/prds/pr-review-agent.md`). Read it as history.\n\u003e\n\u003e One section is stale in a second, older way: \"Operator-triggered review\" below\n\u003e describes the synchronous `review_pr` (fetch the head, snapshot it, run the\n\u003e reviewer, return findings), which `archie-core-afbk.14` replaced with a queued\n\u003e pr-review task.\n\nArchie ran a fresh adversarial review of the diff before it opened a pull\nrequest, so a PR arrives with a findings record rather than an unreviewed\nclaim. The reviewer provably cannot see the implementer's context: it reviews a\n`.git`-free snapshot of the committed tree, not the worktree, the commit\nhistory, or the implementer's transcript.\n\nPromoted from `docs/prds/adversarial-self-review.md` (the design decision;\n`archie-core-h019`). Describes the stage as shipped.\n\n## Contract (`internal/domain/workflow`)\n\nThe workflow domain owns the contract and the blocking decision; it never names\nthe executor.\n\n- `Reviewer.Review(ctx, ReviewRequest) ReviewReport` — the interface the\n workflow stage consumes.\n- `ReviewRequest` is the reviewer's entire input: `SnapshotDir` (a `.git`-free\n export of the reviewed commit), `Diff` (base...head), `IssueText` (the\n originating issue title/body), and `MaxSteps`.\n- `ReviewFinding` / `ReviewReport` are the structured result. The load-bearing\n rule is `Blocking() == (Verdict == confirmed \u0026\u0026 Level == error)`: only a\n confirmed error-level finding blocks; a plausible finding never blocks\n however severe it claims to be.\n\n`ReviewReport` distinguishes `not_run`, `skipped`, and `completed` (zero\nfindings) structurally, so \"ran and found nothing\" is not the same as \"never\nran\" — collapsing them would make an outage indistinguishable from a clean\nreview.\n\n## Execution (`internal/app/agentworker`)\n\nThe executor is an ai-sdk `agent.Subagent`: a nested synchronous generation in\nthe same worker process, with its own model, system prompt, toolset and step\nbudget.\n\n- **Conversation isolation is structural.** `Subagent.Run` sends only a prompt\n string, never the implementer's message history.\n- **Workspace isolation is the `.git`-free snapshot.** The reviewer's toolset is\n read-only (`read`, `grep`, `find`) and rooted at `SnapshotDir` — never the\n worker's own toolset, which carries the `worktreerpc` publication grant.\n- **Findings return through a typed capture tool** (`record_finding`), validated\n on the way in, so the reviewer reports through the contract rather than free\n text the caller regexes.\n- **Fail-closed.** A reviewer that errors, truncates, or reaches no conclusion\n yields `ReviewStatusNotRun`, which the stage treats as a park — never a silent\n \"PR opened unreviewed\".\n\n## Lifecycle effect\n\n`StageReview` runs in the implement workflow after the deterministic gates and\nbefore `StageOpenPR`, gated by `repo.review_enabled` (opt-in, default off). A\nsurviving blocking finding — or a review that failed to run — parks the task\n(`StatusParked`, not `waiting_human`) with the findings rendered into the park\nreason; `StageOpenPR` never runs. Warn/plausible findings and the zero-finding\ncase leave the outcome unset, so the PR opens with a findings section rendered\nonto its body. `StagePostReviewComments` then runs after `StageOpenPR` and posts\nthe **line-anchored** findings as inline review comments, carrying a one-click\nsuggestion on a confirmed finding the reviewer could state a fix for. That stage\nis best-effort — a comment that fails to post is logged, never a park — because\nthe body section already lists every finding, and it is the record a whole-file\nfinding (no line to anchor to) only ever appears in.\n\n## Model and budget\n\nThe reviewer model is `models.reviewer`, falling back to `models.builder`.\nEffort is the per-stage `MaxSteps` budget, mapped onto `Subagent.MaxSteps`\n(default 10).\n\n## OperatorLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/agent-system/",
|
||||
"title": "Agent System",
|
||||
"section": "Architecture",
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
|
||||
"body": "# Agent System\n\n**Status:** Current-state investigation in progress \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Domain framing\n\nThe domain is the Agent System.\n\n`Task` is not a core Agent System concept. Forge tasks, forge issues, Jira\nissues, email, Telegram messages, webhooks, and future external inputs are\nchannel-specific messages. Channels translate those messages into requests to\nthe Agent System; external issue or task models MUST NOT shape execution state.\n\nThe current `store.Task` is a persisted workflow execution. Treating that row as\na task-domain aggregate would incorrectly turn Archie into an agentic issue\nboard.\n\n## Canonical agent interaction model\n\nAn **Agent** is a persistent assistant selected for an interaction. It is not a\nmodel invocation and is not a WorkflowExecution.\n\nEach Agent has its own:\n\n- immutable acting `IdentityID` for ownership and audit;\n- durable memory and learned information about the user;\n- perspective, specialisation, instructions, and communication behaviour;\n- conversation history and channel bindings;\n- available tools, capabilities, and policy;\n- continuity across model or provider changes.\n\nThe underlying model is a replaceable runtime dependency. Changing a model,\nprovider, or model version MUST NOT create a new Agent, discard its memory, or\nchange ownership of its history.\n\nA user MAY create multiple Agents. Each Agent develops its own memory and view\nof the user from the interactions and responsibilities assigned to it. Memories\nMUST NOT be silently pooled merely because Agents belong to the same user or\napplication.\n\nAgent and Identity are separate aggregates. Every Agent references exactly one\nacting IdentityID, and no two Agents share an agent identity. User, system, and\nservice-account identities may exist without an Agent.\n\nAn action initiated through an Agent records the Agent's acting IdentityID and,\nwhen applicable, the initiating user's IdentityID. A future fully automated\nWorkflowExecution MAY use an explicitly selected service-account identity for a\nconcrete unattended use case; this is not the default execution identity.\n\n## Workflow execution identity\n\nA Workflow is owned by an IdentityID. By default, every WorkflowExecution acts\nas the Workflow owner's identity.\n\nFuture delegated execution MAY add an explicit `RunAsIdentityID` assignment to a\nWorkflow. This allows a Workflow owner to select another user or service-account\nidentity for execution without changing Workflow ownership. Until that\ncapability is deliberately introduced, owner identity and execution identity are\nthe same.\n\nWorkflowExecution audit records MUST preserve the Workflow owner, effective\nexecution identity, initiating user when one exists, and any explicit delegation\nthat selected a different run-as identity.\n\n## Memory scopes\n\nThe Agent System requires four distinct durable memory scopes:\n\n- **global shared memory**: information intentionally available across the\n Archie application;\n- **agent-wide memory**: general expertise, operating knowledge, and perspective\n owned by one Agent and safe for that Agent to use across users;\n- **user-wide memory**: information associated with one user and available to\n authorised Agents serving that user;\n- **Agent-user relationship memory**: private history and learned context from\n one particular Agent's relationship with one particular user.\n\nAgent-wide memory is private to its owning Agent by default. Another Agent MUST\nNOT read, inherit, search, or mutate it implicitly.\n\nAgent-user relationship memory is addressed by both AgentID and User IdentityID.\nNeither another Agent serving the same user nor another user speaking to the\nsame Agent may access it implicitly.\n\nArchie is a multi-user system even when initially deployed for one person.\nMultiple users, including family members, may interact with the same configured\nAgents. Per-user memory is therefore an isolation and personalisation boundary,\nnot merely an attribution tag on the primary user's records.\n\nAn Agent MUST resolve the initiating user before assembling memory context.\nMemory belonging to one user MUST NOT become visible to another user merely\nbecause both users interact with the same Agent.\n\nShared memory does not erase provenance. Every memory record retains its scope,\nauthor or acting identity, originating user when applicable, source, and\nrevision history. The rules for selecting a write scope, granting access\nto global and user-wide memory, and authorising explicit cross-scope sharing are\nsettled by [`docs/prds/memory-engine-unification.md`](/dev/prds/memory-engine-unification/)\nand recorded in [`migration-decisions.md`](/dev/architecture/migration-decisions/#5-memory-placement-and-storage)\nsection 5.\n\nAn Agent interaction may answer conversationally, use a tool or capability, read\norLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/bindings/",
|
||||
@@ -28,7 +28,7 @@
|
||||
"url": "/dev/architecture/configuration/",
|
||||
"title": "Configuration",
|
||||
"section": "Architecture",
|
||||
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
|
||||
"body": "# Configuration\n\n**Status:** Approved; existing-type assignment is ongoing \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Ownership\n\nConfiguration has two separate responsibilities:\n\n1. `internal/infrastructure/configuration` loads files, environment variables,\n secret references, overlays, and compatibility representations.\n2. Each domain and plugin owns the typed runtime settings required for its\n behaviour.\n\n`internal/app` translates external input into those settings, validates\ncross-capability combinations, and supplies each component only its own\nsettings.\n\nThe following are prohibited:\n\n- passing complete application configuration into a domain;\n- making a domain depend on TOML, YAML, environment-variable names, secret\n references, or a configuration library;\n- defining a central runtime configuration type imported across the system;\n- placing plugin options in an unrelated global configuration model.\n\n## Private input document\n\n`internal/infrastructure/configuration` MAY use a complete decoded document\nwhile discovering files, decoding sections, and applying overlays. It is an\ninput-boundary DTO only.\n\nThe document:\n\n- remains private to the configuration infrastructure;\n- is composed from separately defined feature sections;\n- is immediately translated by application composition;\n- is never returned as the application's runtime model;\n- is never passed through runtime components.\n\nExternal DTOs and domain runtime settings are separate types.\n\nPlugins supply external configuration definitions through a narrow extension\ncontract. The core loader MUST NOT gain a field or recognised filename for every\nplugin.\n\nInvalid configuration input MUST NOT replace active valid settings or terminate\nunaffected capabilities. Configuration changes use the candidate validation,\npromotion, audit, and recovery requirements in\n[safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/).\n\n## Dissolution of `internal/config`\n\n`internal/config` has no target location. It MUST be dissolved and MUST NOT\nsurvive as a shared package, configuration domain, or renamed global model.\n\nIts loading behaviour moves to `internal/infrastructure/configuration`. Existing\ntypes and methods are reassigned by behaviour. Repository execution policy,\ndispatch policy, retry policy, ecosystem defaults, tool policy, memory settings,\nprovider settings, and channel settings move to their\nrespective owners.\n\n## Repository settings\n\nThe existing `config.Repo` MUST NOT move intact into a repository domain or\nshared settings package. A managed repository is an application association:\n\n- work intake owns which repository references an identity monitors;\n- task execution owns gates, preflight, test protection, ecosystem behaviour,\n and change limits;\n- task lifecycle owns retry behaviour;\n- scheduling owns concurrency policy;\n- workspace management owns base branch and persistent-storage requirements.\n\nApplication composition correlates these settings by repository reference. No\ndomain receives a universal repository profile.\n\n## Documentation\n\nGenerated configuration reference describes external sections and their owning\ncapabilities. It MUST NOT establish a global Go configuration structure as the\npublic contract.\n\n## Value classification rule\n\nEvery value that controls behaviour MUST have an explicit owner and MUST be\nclassified as exactly one of:\n\n1. **Invariant** — changing it changes the meaning of the program, a wire\n protocol, or a domain concept. It may be a Go constant.\n2. **Runtime setting** — an operator, identity, domain, plugin, or deployment\n may legitimately choose a different value. It is typed configuration owned by\n the affected capability.\n3. **Policy value** — it expresses what is allowed, limited, routed, retried,\n protected, or gated. Its typed definition belongs to the owning domain and it\n is evaluated through the policy system.\n4. **Derived value** — it is computed from other settings and is not\n independently mutable.\n5. **Runtime state** — it changes as the application operates, such as the\n active model for a conversation. It is changed by a domain command and is not\n configuration merely because it can be changed.\n\nAn unclassified behavioural literal is a defect.\n\n`const` MUST NOT be used merely because a value currently has one default.\nConstants are reserved for actual invariants: enum discriminants, protocol\nversions, fixed compatibility tokens, and values whose alteration would change\nthe program's semantics rather than configure an installation.\n\nIn Go, a constant is a compile-time value and does not represent mutable runtime\nstorage. It generally has no address that can be observed or changed.\nArchitecturally, a constant therefore asserts that the value cannot change for\nthe lifetiLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/dashboard-agent-tools/",
|
||||
@@ -46,13 +46,13 @@
|
||||
"url": "/dev/architecture/generated-documentation/",
|
||||
"title": "Generated Documentation",
|
||||
"section": "Architecture",
|
||||
"body": "# Generated Documentation\n\n**Status:** Data generation lives here; rendering and publishing live in the external Astro website\n**Date:** 2026-07-28 (revised 2026-09-25)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalises documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the external Astro website consumes generated data and serves the public\n documentation at `offloaded.dev/docs/`.\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — external Astro website\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\nThe Astro website is maintained outside this repository. This repository owns\nthe Markdown source and generated JSON artifacts; it does not build, preview, or\ndeploy the site. The external site owns page rendering, navigation, and\npublishing.\n\nThe current boundaries are:\n\n| Concern | Owner |\n| --- | --- |\n| Reference-page rendering and publishing | External Astro website |\n| Documentation source and generated data | This repository |\n| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |\n| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |\n\nChanges to an artifact contract must be coordinated with the external Astro\nconsumer. This repository does not validate the website's rendered links or\nroutes.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalised documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalised JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalisation and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n generated/\n catalog.json\n contracts.json\n docs.json\n dev-docs.json\n cli.json\n configuration.json\n messaging.json\n agents.json\n workflows.json\n policies.json\n plugins.json\n tools.json\n public/\n schemas/\n asyncapi-header.yaml\n archie.yaml\n .tmp/\n```\n\nAllLine truncated
|
||||
"body": "# Generated Documentation\n\n**Status:** Data generation lives here; rendering and publishing live in the external Astro website\n**Date:** 2026-07-28 (revised 2026-09-25)\n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie's documentation-generation approach is:\n\n- production Go code, registries, configuration, and CLI behaviour remain the\n source of truth for published contracts;\n- a repository-local Go generator extracts and normalises documentation data;\n- the generator writes deterministic JSON/data files and protocol schemas;\n- the external Astro website consumes generated data and serves the public\n documentation at `offloaded.dev/docs/`.\n\nHugo is not part of the target architecture.\n\nThe documentation system is rooted at:\n\n```text\ntools/\n go.mod\n go.sum\n docsgen/\n main.go\ndocs/\n data/generated/\n public/schemas/\n *.md\n```\n\n### Rendering and publishing — external Astro website\n\nSuperseded 2026-09-12. The repository previously carried a VitePress site\n(`docs/.vitepress/config.mts`, `docs/package.json`, a 1620-line\n`docs/pnpm-lock.yaml`, `docs/pnpm-workspace.yaml`) built and deployed to GitHub\nPages by `.github/workflows/docs.yml`. It was removed as an unnecessary build\nstep: the published site was never stood up, and the Pages target is not\nconfigured.\n\nThe Astro website is maintained outside this repository. This repository owns\nthe Markdown source and generated JSON artifacts; it does not build, preview, or\ndeploy the site. The external site owns page rendering, navigation, and\npublishing.\n\nThe current boundaries are:\n\n| Concern | Owner |\n| --------------------------------------- | -------------------------------------------------------------------- |\n| Reference-page rendering and publishing | External Astro website |\n| Documentation source and generated data | This repository |\n| Generated-data drift detection | `task docs:check`, `task docs:artifact:check`, and `task news:check` |\n| Navigation data | `docs/data/generated/docs.json` and `dev-docs.json` |\n\nChanges to an artifact contract must be coordinated with the external Astro\nconsumer. This repository does not validate the website's rendered links or\nroutes.\n\n## Single source of truth\n\nEvery published capability has one authoritative machine-readable definition\nowned by its domain or application boundary. Generated documentation derives\nfrom those definitions.\n\nGenerated reference includes:\n\n- domain commands and events;\n- Messages and typed message content;\n- Agent and Workflow contracts;\n- WorkflowSteps and Workflow plugin capability contracts;\n- policies and their typed inputs and outcomes;\n- tools and capabilities;\n- CLI commands, arguments, flags, defaults, and help;\n- runtime settings, types, defaults, validation, and secret metadata;\n- public worker and transport contracts;\n- indexes of registered functionality;\n- deprecation information.\n\nHandwritten documents contain:\n\n- architecture decisions and rationale;\n- tutorials and operational guides;\n- examples and walkthroughs;\n- migration guidance;\n- conceptual explanations.\n\nHandwritten documents link to generated reference rather than copying\nauthoritative tables.\n\n## Target generation architecture\n\n`tools/docsgen` is Archie's documentation extractor and normalizer. It produces\nstructured documentation data and protocol specifications. It does not own\npage layout and MUST NOT generate Markdown pages or fragments.\n\nThe generator is divided internally into reusable stages:\n\n```text\nload registries and types\n -\u003e normalize documentation model\n -\u003e validate ownership and identifiers\n -\u003e serialize data and protocol artifacts\n -\u003e compare or write output\n```\n\nThe normalised documentation model prevents each output renderer from\nindependently interpreting Go types. It contains stable documentation IDs,\nowners, names, descriptions, source references, versions, deprecations, fields,\ndefaults, validation, secret classifications, and relationships.\n\nInitial generator targets:\n\n```text\ndocsgen data\ndocsgen asyncapi\ndocsgen all\ndocsgen check\n```\n\n- `data` writes the normalised JSON reference data.\n- `asyncapi` writes protocol schemas and envelopes.\n- `all` generates every committed artifact.\n- `check` generates into a temporary directory and fails on drift.\n\nThe command may use subcommands or an equivalent explicit `--target` flag. It\nMUST retain one normalisation and validation path.\n\n## Target output\n\nDuring adaptation, `docs` remains the staging site. Generated outputs live in\na visibly owned subtree:\n\n```text\ndocs/\n data/\n geLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/identity/",
|
||||
"title": "Identity",
|
||||
"section": "Architecture",
|
||||
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry. It does not change the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or reLine truncated
|
||||
"body": "# Identity\n\n**Status:** Approved foundation; lifecycle details are deferred \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nIdentity answers which persistent actor owns or performed an action. It supplies\nstable cross-domain attribution and lifecycle semantics.\n\nIdentity kinds include:\n\n- the Archie system identity, such as `System` or `archied`;\n- agent or bot identities;\n- service-account identities;\n- future user identities.\n\nA user is another kind of identity rather than a separate foundation concept.\n\n## Ownership\n\n`internal/domain/identity` owns:\n\n- immutable canonical `IdentityID` values;\n- identity kind;\n- lifecycle state;\n- ownership and attribution semantics;\n- identity-related commands and events.\n\nDomains may record an identity reference on their own state and events when\nownership or attribution is required. They MUST NOT receive a complete\nper-identity application configuration bundle.\n\nPersona and communication style are separate from identity.\n\nEvery Agent has its own immutable acting `IdentityID`. Agent actions use that\nidentity for ownership and attribution in the same way an organisation records\nwhich user accessed a resource, changed a permission, or performed another\nauditable action.\n\nAgent and Identity remain separate aggregates. Identity supplies the stable\nactor reference; Agent owns assistant behaviour, memory, specialisation,\nconversations, and capability context.\n\nAgent identities MUST NOT be shared between Agents. Automated WorkflowExecutions\nMAY eventually act through a dedicated service-account identity when a specific\nunattended automation requires it. Such use is an explicit execution decision\nand audit principal, not the default for Agents or a substitute for recording\nthe initiating user when one exists.\n\nA Workflow is owned by an IdentityID and executes as its owner by default.\nFuture delegated execution MAY explicitly assign a different `RunAsIdentityID`,\nincluding a user or service-account identity. Ownership, effective execution\nidentity, initiating identity, and delegation provenance remain distinct audit\nfacts.\n\n## Canonical identity\n\nEvery identity has an immutable `IdentityID`. It is the only value used for\ncross-domain ownership, attribution, routing, persistence, commands, and events.\n\nIdentity kind is explicit:\n\n- system;\n- bot;\n- service account;\n- user.\n\nDisplay names are mutable and MUST NOT be used as identifiers. Forge usernames,\nchannel bot names, Git authors, provider account names, and other external\nidentifiers are bindings associated with an identity rather than identity\nitself.\n\n`System` is represented by a real identity and `IdentityID`. The empty string\nMUST NOT retain special meaning as a legacy system identity.\n\nConfiguration refers to identities by `IdentityID` and supplies external\nbindings and capability settings separately. Renaming an identity or changing an\nexternal account MUST NOT change ownership or historical attribution.\n\nSecret-bearing channel bindings remain configuration concerns rather than\nidentity data. In particular, `[chat.telegram].token` is a\n`secret.SecretRef` resolved by the application through the configured secret\nregistry. It does not change the identity that owns or performs a chat action.\n\n## Persistence\n\nIdentity records are durable domain state. The Identity domain's repository is\nthe source of truth; infrastructure implements its persistence contract.\n\nConfiguration MAY bootstrap a missing identity through an explicit, audited\ncreation operation and MAY propose runtime capability bindings for an existing\n`IdentityID`. Configuration is not the identity registry.\n\nOmitting an identity from configuration stops assembling the omitted runtime\ncapabilities. It MUST NOT delete the identity record, erase history, or make\nhistorical references unresolvable.\n\nDisabling or retiring an identity requires an explicit Identity-domain command.\nRetired identities remain resolvable for historical attribution. A failed\nexternal binding affects capability availability without destroying or silently\nreplacing the identity.\n\n## Lifecycle\n\nIdentity lifecycle is deliberately small:\n\n- `active`: may participate in runtime composition;\n- `suspended`: deliberately prevented from initiating new work while ownership\n and history remain;\n- `retired`: terminal, unable to initiate work, and permanently retained for\n attribution.\n\nAllowed transitions are:\n\n```text\ncreate -\u003e active\nactive -\u003e suspended\nsuspended -\u003e active\nactive -\u003e retired\nsuspended -\u003e retired\n```\n\n`retired` has no outgoing transition.\n\nCapability health is separate from identity lifecycle. Forge, model, channel,\nworkspace, and other bindings report health independently. An active identity\nmay be partially degraded without becoming suspended or reLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/messaging-and-work-intake/",
|
||||
@@ -64,13 +64,13 @@
|
||||
"url": "/dev/architecture/migration-decisions/",
|
||||
"title": "Architecture Migration Decisions",
|
||||
"section": "Architecture",
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
"body": "# Architecture Migration Decisions\n\n**Status:** Active migration inventory \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nThis document records what remains to be decided before Archie's current\nimplementation can be migrated into the approved domain-oriented structure.\n\nThe product and core domain model are not being redesigned. Existing Archie\nbehaviour and the existing session implementation are the migration\nbaseline. Remaining decisions MUST be grounded in current packages, consumers,\ntests, persistence, and runtime wiring.\n\n## Confirmed domain packages\n\n```text\ninternal/domain/\n identity/ (approved, not yet materialised as a package)\n agent/ (approved, not yet materialised as a package)\n workflow/\n messaging/ (canonical Message/Conversation types only; gateway migration pending, see section 2)\n workintake/\n plugin/ (approved, not yet materialised as a package)\n curator/\n mapping/\n scheduling/\n```\n\n- `identity` owns persistent actors, lifecycle, ownership, attribution, and\n audit identity.\n- `agent` owns persistent assistants, specialisation, instructions,\n model-independent continuity, capability context, and associations with\n identity and memory.\n- `workflow` is a separate domain. It owns reusable, versioned Workflow\n definitions, WorkflowSteps, WorkflowExecutions, StepExecutions, Attempts,\n outcomes, and typed Workflow plugin contracts.\n- `messaging` owns canonical Messages, Conversations, branches, channel and\n source correlation, replies, acknowledgements, delivery attempts, events, and\n projections.\n- `workintake` owns admission, validation, deterministic routing, and accepted\n work requests for the optional transition into durable workflow-backed\n execution.\n- `plugin` owns generic plugin identity, discovery, compatibility, and lifecycle\n mechanics. It remains metadata-only; capability semantics and typed\n registration belong to the owning domain.\n- `curator` owns the curator engine family: long-running agent loops that\n reason over memory and perform maintenance tasks on a declared shape\n (check-in interval, tool set, attached memory engine). See epic\n archie-core-yp9.\n- `mapping` owns the payload field-mapping vocabulary: binding named fields to\n JSON paths inside a captured webhook payload, and detecting drift. See\n `docs/prds/payload-field-mapping.md`.\n- `scheduling` owns the ticker engine: deciding when a scheduled job runs and\n with what concurrency. It declares `JobSource`/`Runner` contracts and owns\n no storage or delivery. See epic archie-core-1786637496320-249-be6d9a20.\n\n**Reconciliation (2026-08-31):** `curator`, `mapping`, and `scheduling` existed\nin the tree without being added to this list when their epics landed. They are\nconfirmed as legitimate, narrowly-scoped domains under the same rules as the\noriginal six — each owns one capability family, declares typed contracts, and\nhas no cross-domain reach. This list was out of date, not the tree.\n\nConversely, `identity`, `agent`, `messaging`, and `plugin` are approved target\ndomains that do not yet exist as packages. Their behaviour currently lives in\npre-migration packages (see \"Complete package destination map\" below for the\nfull inventory). Do **not** create empty stub packages for them ahead of an\nactual migration PR — an unused stub is dead code and gives no test coverage.\nEach materialises when its corresponding migration decision below is resolved\nand implemented in the same change.\n\nMemory's final package placement remains undecided pending focused review of the\nexisting implementation.\n\nThe following are approved shared or composition packages, not domains:\n\n```text\ninternal/eventbus/\ninternal/policy/\ninternal/infrastructure/\ninternal/app/archied/\ninternal/app/agentworker/\n```\n\n## Remaining migration decisions\n\n### 1. Complete package destination map\n\nEvery current package MUST receive one explicit disposition:\n\n- move into a confirmed domain;\n- move under infrastructure as an implementation of a domain-owned contract;\n- move into application composition;\n- merge with an identified duplicate;\n- remain as an approved shared application contract;\n- move to a plugin, extra, deployment, example, or generated artifact;\n- be deleted after its replacement is proven.\n\nThe largest unreviewed areas include memory, tools and capabilities, workspace\nand worktree behaviour, gates, storage, events, web UI, containers, RPC\npackages, release management, and scheduling.\n\nThe destination matrix MUST name the behaviour owner, target path, dependencies\nto remove, state and contracts to preserve, migration prerequisites, and\ndeletion criteria.\n\n**`internal/webui` / UI Service — RATIFIED Phase 3 disposition (2026-09-07).**\nThe current owner is the in-process HTTP/SSE dashboard: SPA hosting, operator\nauthLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/observability/",
|
||||
"title": "Task Observability",
|
||||
"section": "Architecture",
|
||||
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — *\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"* — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see *why*\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
|
||||
"body": "# Task Observability\n\n**Status:** Implemented. The per-run detail surface was added on 2026-09-18 and\nis described below.\n**Date:** 2026-08-09 (revised 2026-09-18)\n\n## Historical problem\n\narchied's own daemon logging (`internal/logging/`) was already solid: a\nrotating file sink, a live `Feed` the dashboard subscribes to, and a reader\nthe `/api/logs` endpoint serves from. Before this implementation, none of\nthat reached inside a task.\n\nA task's actual work happens in a task-scoped `archie-agent` container,\ndispatched as one complete workflow over NATS.\nBefore this design was implemented, five things destroyed the evidence of what\nthat container did:\n\n1. **Worker startup** constructed an stderr-only logger and never replaced its\n handler after discovering a dedicated boot task, so runtime records could\n not leave the container.\n2. **`internal/container/pool.go`** creates every task container with\n `AutoRemove: true`. The container — and its stderr — is gone at exit,\n success or failure alike.\n3. **`internal/domain/workflow/implement.go`, `StageBaselineGate`** captures\n `go build`/`go vet`/`go test` output via `cmd.CombinedOutput()`, then\n clips it to 200 characters into a `Warn` log line and discards the rest.\n The eventual park reason is built from `res.Status` alone — the actual\n compiler error is never persisted anywhere a human or Archie's own chat\n tools can read it back.\n4. **`agentexec.Result`** (`internal/agentexec/protocol.go`) carries only\n `Summary`/`Detail` — no step-by-step transcript (tool calls, durations,\n errors). There is no transcript to recover even in principle.\n5. **`agentexec.SubjectForSystem`** is documented as the return channel for\n exactly this — _\"log dumps, health, and PII warnings... the daemon reads\n these for observability and never forwards them\"_ — but has no publisher\n and no consumer anywhere in the codebase except a subject-format\n assertion in `nats_test.go`. The designed return path was never wired.\n\nThe practical consequence: a task parks with\n`stage baseline: baseline red -- go build ./... fails and builder could not\nauto-fix (status: parked)` and there is no way — not from the dashboard, not\nfrom Telegram chat, not by SSH'ing into the deployment host — to see _why_\n`go build` failed. The container that knew is already gone.\n\nThis matters beyond debugging convenience: supported deployments can combine\na resident daemon with ephemeral Docker containers that run unattended for\nweeks between operator logins, and the system is\nintended to be usable by people other than the original operator. A system\nthat is only debuggable by an operator who happens to be watching `docker ps`\nin real time does not meet that bar.\n\n## Decision: NATS is the sole autonomous handoff\n\nThe agent image must reach NATS in every deployment, because the broker is the\nonly autonomous task handoff and the only channel carrying task results back\nto the daemon. `archied` has no workflow runner or host fallback. A container\nthat dies before establishing a NATS connection is a distinct, narrower\nfailure (connectivity/config) from the one this document addresses (a connected\ncontainer's own output being unrecoverable), and is out of scope here.\n\n## Implemented design\n\nThe key property: **logs leave the container while it is alive**, so its\ndeath at `AutoRemove` no longer matters. Persistence happens in the daemon\nprocess, which already owns durable state.\n\n### Sink: extend `internal/logging`, not a new package\n\n`internal/logging` already owns its on-disk format end to end per\n`organisation.md` (\"a package owns its own format end to end\"). Add a\ntask-scoped writer producing the same `logging.Entry` JSONL shape at\n`\u003cstate_dir\u003e/logs/tasks/\u003ctask_id\u003e/attempt-\u003cn\u003e.jsonl`. `logging.Tail`,\n`logging.Query`, and `logging.Components` operate on this unchanged;\n`internal/webui/api_logs.go` stays transport-only, as it does today.\n\n### Agent side: make the designed subject real\n\n`internal/app/agentworker` replaces the stderr-only `slog.Handler` with one\nthat tees to stderr (kept for container-level operator debugging when a\nshell is attached) and publishes each record to\n`agentexec.SubjectForSystem(taskID)`, which already exists for this purpose.\nThe application layer obtains only a narrow publisher from\n`internal/infrastructure/agenttransport/nats`; raw core-NATS types remain in\ninfrastructure. `internal/infrastructure/agentboot.TaskID` reads the task ID\nfrom `\u003cworktree\u003e/.git/task.json` per the container/pool.go trap documented in\n`CLAUDE.md`. Publishing is fire-and-forget: log shipping must never block or\nfail the run it is reporting on.\n\n### Daemon side\n\n`cmd/archied/main.go` registers `subscribeSystemLogs` once at startup on\n`agentexec.SubjectSystemWildcard`. It demultiplexes by task ID, appends to that task's\nsink, and pLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/organisation/",
|
||||
@@ -82,7 +82,7 @@
|
||||
"url": "/dev/architecture/package-review/",
|
||||
"title": "Domain and Feature Review Procedure",
|
||||
"section": "Architecture",
|
||||
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n|---|---|\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
|
||||
"body": "# Domain and Feature Review Procedure\n\n**Status:** Active \n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchitecture work proceeds one domain or feature at a time. Before any design\nquestion, the selected area is researched across its complete live\nimplementation, consumers, tests, state, configuration, and runtime wiring.\n\nExisting packages are evidence, not the unit that drives the interview.\nPlacement follows behaviour and ownership, not the existing directory name.\n\nNo restructuring implementation begins until the relevant package decisions\nare agreed and recorded in the focused domain or requirement document.\n\n## Required research\n\nBefore design questions, the current-state report MUST identify:\n\n- entry points and runtime composition;\n- state, persistence, and lifecycle;\n- public and internal contracts;\n- commands, events, and policy enforcement;\n- configuration and defaults;\n- all consumers and cross-domain interactions;\n- process and infrastructure boundaries;\n- tests, failure behaviour, and known invariants;\n- duplicated or conflicting implementations;\n- documentation that disagrees with live code.\n\nDiscoverable facts MUST be investigated rather than presented to the user as\ndesign questions.\n\n## Required decisions\n\nEach package review records:\n\n| Decision | Required result |\n| --------------------- | ---------------------------------------------------------------- |\n| Owned behaviour | The cohesive job the code performs |\n| Domain ownership | The owner of the behaviour and vocabulary |\n| Final location | Its target path |\n| Public contracts | The smallest interfaces, commands, and events exposed |\n| Required services | Domain-defined interfaces implemented by infrastructure |\n| State ownership | The owner of each mutable record and transition |\n| Dependencies | Allowed imports and dependencies to remove |\n| Duplication | Code to consolidate, delete, or keep separate |\n| Plugin status | Core domain, shared contract, infrastructure, plugin, or extra |\n| Process boundary | In-process, or the concrete reason for isolation |\n| Configuration | Settings owned by the domain or plugin |\n| Policy | Definitions, evaluators, consequences, and shared mechanics used |\n| Documentation | Authoritative definitions and generated reference |\n| Migration constraints | Behaviour and data that must remain correct |\n\n## Interview method\n\nFor every selected domain or feature:\n\n1. Declare the single area under review.\n2. Complete the current-state research.\n3. Explain actual behaviour in plain technical language.\n4. Separate facts from design decisions and concerns.\n5. Resolve obvious consequences directly and ask only questions whose answer\n materially changes behaviour or structure.\n6. Record each confirmed decision in its focused document.\n7. Complete that area's handoff before selecting another.\n8. Keep unrelated domains outside the implementation scope.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/architecture/plugins-and-extensions/",
|
||||
@@ -100,13 +100,13 @@
|
||||
"url": "/dev/architecture/safe-change-and-recovery/",
|
||||
"title": "Safe Change and Recovery",
|
||||
"section": "Architecture",
|
||||
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure | Boot behaviour | Where the operator sees it |\n| --- | -Line truncated
|
||||
"body": "# Safe Change and Recovery\n\n**Status:** Requirements approved; mechanics are under design. Database-backed settings are implemented through the control plane (2026-09): see the degrade/recovery section below, which records a gap rather than a solution. The full runtime-supervision protocol (bounded observation, versioned audit trail) remains under design.\n**Date:** 2026-07-28 \n**Tracking issue:** [#73](https://github.com/samcharles93/archie-core/issues/73)\n\n## Purpose\n\nArchie is built and improved by agents as well as humans. The architecture MUST\nmake a change easy to locate, understand, test, audit, extend, and reverse\nwithout requiring its author to understand unrelated parts of the application.\n\nSeparation of concerns is therefore an operational safety boundary, not only a\ncode-organisation preference.\n\n## Required outcomes\n\n- An agent can improve a focused feature without receiving authority over\n unrelated domains.\n- Every event, function, action, setting, and policy has an identifiable owner\n and provenance.\n- Source and runtime changes pass deterministic checks outside the actor making\n the change.\n- A rejected or unhealthy candidate cannot replace the last known working\n version.\n- Invalid user configuration does not terminate an otherwise healthy\n application.\n- Configuration and service failures are observable, attributed, and eligible\n for bounded remediation or rollback.\n- The application continues serving unaffected capabilities when one\n capability is misconfigured or unhealthy.\n- Recovery failure is reported and contained rather than hidden in an\n unbounded retry loop.\n\n## Source changes\n\nAgent-authored source changes occur through the task-execution boundary in an\nisolated workspace. The agent does not directly mutate the running\ninstallation.\n\nPromotion is controlled by deterministic repository-owned policy, including\ntests, generated-reference drift checks, protected paths, change scope, and\nother required gates. The actor proposing a change cannot waive these checks.\n\nRepository and domain separation SHOULD allow a task to load and modify only\nthe governing requirements and code for its declared scope.\n\n## Runtime changes\n\nConfiguration and other runtime changes are proposed as candidates rather than\nmutating the active state in place.\n\nThe affected domain owns:\n\n- the command describing the semantic change;\n- validation of its typed settings;\n- health signals that demonstrate correct operation;\n- domain-specific remediation and rollback consequences.\n\nShared policy supplies consistent evaluation, evidence, and audit mechanics.\nIdentity supplies actor attribution. Infrastructure supplies external\nconfiguration storage, service control, and other operational adapters.\n\n## Runtime change protocol\n\nLast-known-good preservation and candidate promotion are the universal runtime\nchange protocol.\n\n1. An identity proposes an immutable candidate version.\n2. Infrastructure parses it without changing active state.\n3. Each affected domain validates its typed settings.\n4. Shared policy evaluates cross-cutting constraints.\n5. Each affected capability prepares the candidate without destroying its\n active instance.\n6. Capability-specific health checks prove the candidate works.\n7. Runtime supervision atomically promotes the candidate.\n8. A bounded observation period watches for delayed failure.\n9. Failure restores the last-known-good version and records the reason,\n evidence, actor, and involved versions.\n10. Repeated remediation failure stops retrying, isolates the capability, and\n reports the fault.\n\nThe affected domain owns the semantic change command, typed validation, health\nsignals, and remediation consequences. Shared runtime supervision owns the\npromotion transaction. Infrastructure performs storage and service-control\noperations.\n\nThe protocol's exact Go contracts, storage model, atomicity boundary, and\nobservation rules require a focused runtime-supervision design pass.\n\n## Failure isolation\n\nInvalid input MUST leave the active valid configuration unchanged and produce a\ndiagnostic record.\n\nA capability that cannot start or reload SHOULD fail independently where its\nabsence does not violate a declared application invariant. Unaffected\ncapabilities continue operating.\n\nRemediation MUST be bounded, observable, and policy-driven. Recovery MUST NOT\nsilently oscillate between versions or retry forever.\n\n## Database settings: degrade paths and recovery (2026-09)\n\nThe control plane owns runtime-tunable settings and stores them in the State\nStore's PostgreSQL database.\nThis replaced a dashboard overlay store that degraded to file config on any\nfailure and had three documented ways back. The replacement has none, and the\nposture is the opposite: **the daemon fails closed.**\n\n### Degrade paths\n\n| Failure Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/",
|
||||
"title": "Development guides",
|
||||
"section": "Development",
|
||||
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| --- | --- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` also adds linter-tool lines to `go.sum`\n (bead 1e37); restore `go.sum` before committing unless you changed a\n dependency.\n- A change to `docs/prds/` or `docs/architecture/` carries the regenerated\n `docs/data/generated/dev-docs.json`, and PRD edits follow\n `docs/prds/RULES.md` and pass `task docs:prds`.\n"
|
||||
"body": "# Development guides\n\nChecklists for changing Archie, one page per area. Each names every place a\nchange must reach, so a feature that works in one layer does not silently stop\nat the next. A change that spans areas starts on the page for the area it\nbegins in, which points to the others. The pages point at the documents that\nown the design (`docs/architecture/`, the PRDs, `CLAUDE.md`) rather than\nrestating them.\n\n| Area | Covers |\n| ---------------------------------------------- | -------------------------------------------------------------------------------- |\n| [Frontend UI](/dev/development/frontend-ui/) | Anything under `ui/`, and the dashboard's API routes |\n| [Agent](/dev/development/agent/) | The agent container, its image, profiles, tools and workspace |\n| [Workflows](/dev/development/workflows/) | Workflow definitions and step types |\n| [Daemon](/dev/development/daemon/) | Task statuses, fields and the brief; sources, event types, mappings and bindings |\n| [State Store](/dev/development/state-store/) | Stored fields, tables, RPCs and errors |\n| [Control plane and settings](/dev/development/control-plane/) | Settings in `config.toml` or the dashboard |\n| [Processes and wiring](/dev/development/wiring/) | Where code goes, processes, plugin engines, channels, NATS subjects |\n| [Merging work](/dev/development/merging-work/) | Merging a lane or a branch |\n\n## Every change\n\n- Write the failing test first for anything with logic, branching or a\n contract, and check it fails on an assertion, not a compile error.\n- Test through the path production uses. A test that sets a value directly on\n the consumer proves nothing about the layers that normally deliver it.\n- Run `task check` and let its exit status decide the commit:\n `task check \u0026\u0026 git commit ...`. `task test` passes `-short`, which skips the\n process and Postgres tests, so run `go test -count=1 ./cmd/... ./internal/...`\n too when a change crosses a process or the database.\n- Regenerate, never hand-edit, generated output: `task proto:generate`,\n `go -C tools tool sqlc generate -f $PWD/internal/infrastructure/postgres/sqlc.yaml`,\n `task ui`, `task docs:artifact`. `task proto:check` compares against the git\n index, so stage regenerated contracts before running it.\n- Stage by path, or read `git status` before `git add -A`. Tests that start\n embedded NATS or write logs must use `t.TempDir()`; anything they leave in the\n tree gets committed. `task check` writes no module file on a consistent tree,\n root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):\n a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or\n `updates to go.mod needed`, rather than being repaired. Only a global\n `GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the\n `go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run\n `go mod tidy` and commit the result on its own.\n- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**\n carries the regenerated `docs/data/generated/dev-docs.json`: run\n `task docs:artifact` (not `task docs:check`, which checks contracts only).\n PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/agent/",
|
||||
@@ -118,31 +118,31 @@
|
||||
"url": "/dev/development/control-plane/",
|
||||
"title": "Control plane and settings",
|
||||
"section": "Development",
|
||||
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator.\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the struct the resource's `Document` names in\n `internal/app/controlplane/operational_settings.go`. The resource's JSON\n schema and the dashboard's Advanced settings editor are generated from that\n type, so no UI work is needed for the editor itself.\n2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).\n Give the field no `json` tag unless its neighbours have one.\n3. A map or a nested struct needs its layering checked. `json.Unmarshal`\n merges into an existing map, so a stored map would add to the file's rather\n than replace it. A field the stored document omits keeps the file's value\n (a document stored before the field existed). Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved through the secret registry. Never inspect\n a resolved value, even in a test.\n- Reject a configuration that sets a field with no consumer rather than\n accepting and ignoring it (per-identity `forge.intake` is the precedent).\n"
|
||||
"body": "# Control plane and settings\n\nAuthority: `docs/architecture/configuration.md`. The wiring matrix, the\ndecoded-but-unwired ledger and the three shapes an unwired field takes are in\n`.agents/skills/archie-config-and-flags`.\n\nA field that parses is not a field that works. Before adding one, name the code\nthat reads it and the path the value takes to get there.\n\n## Decide what kind of setting it is\n\n- **Bootstrap-only** (read once at process start: `database_url`, `state_dir`,\n `work_dir`). It stays in the file, is checked by `validateBootstrap` in\n `internal/infrastructure/configuration/validate.go`, and the runtime overlay\n refuses changes to it.\n- **Database-owned** (repository policies, scheduling, tools, plugins,\n channels, containers). The file only seeds it. Once the State Store holds the\n control-plane resource, the stored document is layered over the file\n (`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is\n checked by `validateDatabaseOwned` and by the resource's validator. A stored\n value is refreshed from the file only when the store has no value for the kind\n at all; a kind that ships a document of its own (workflow definitions,\n personas) is refreshed whenever the seed itself wrote the stored copy, since\n that copy is a previous release's document rather than an operator's\n (`controlplane.Server.seedKind`).\n- **Worker-carried.** A value the agent container needs travels in\n `config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it\n as an environment variable the daemon did not already define, and never carry\n a secret this way.\n\n## Adding a database-owned field\n\n1. Add it to the wire-shape type the resource's `Document` names — a dedicated\n struct in `internal/app/controlplane/` with explicit snake_case json tags\n (`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the\n precedents), never the internal config struct itself. A struct fed straight\n into the document falls back to Go field names (`Window`, `MaxRequests`),\n and a bare `time.Duration` marshals as nanoseconds — both render unusable\n in the Web UI. The resource's JSON schema and the dashboard's Advanced\n settings editor are generated from that type, so no UI work is needed for\n the editor itself.\n2. Map to and from the internal config type at the resource boundary (`Seed`,\n the layering in `runtime_config.go`, and the validator all use the same\n mapping). Durations in the document are a string-marshalling type\n (`config.Duration` or a document-local one), never a bare `time.Duration`.\n3. A document stored before the shape existed carries Go-cased keys. Read them\n with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the\n wire type) while keeping `DisallowUnknownFields` — dropping unknown keys\n would decode a misspelling as \"unset\" — and register a `Normalize` on the\n `Definition` that re-encodes the document, so a legacy document converges\n the next time it is written. A map or a nested struct needs its layering\n checked: a stored map replaces the file's, not merges into it, and a field\n the stored document omits keeps the file's value. Add a case to\n `internal/app/controlplane/runtime_config_test.go` for both.\n4. Validate it in one function both sides call, and add a case to\n `TestResourceValidatorsRejectWhatEffectiveValidationRejects` in\n `validators_agree_test.go`, so the file and the resource cannot disagree.\n5. Decide whether it reloads: it does only if every consumer re-reads it from\n `config.Holder`. The allowlist is `internal/app/archied/reload.go`; anything\n not on it requires a restart.\n6. If the settings page shows it as a plain field, add it to\n `internal/webui/config_schema.go` and the view in `api_config.go`.\n7. A generic catalog resource (`replace` command, not domain-managed, no\n query service) is watched **once per archie-ui process** by `webui.RunLive`,\n then published to every browser through `/api/stream`. Do not add an\n EventSource per resource to a settings store or a gRPC Watch per HTTP client.\n The control-plane server polls `Resource` every 250ms per upstream Watch;\n verify watch count is independent of client count and that late clients get\n the hub's current value (`internal/webui/live_hub_test.go`, real server over\n bufconn). Reopens resume after the last delivered version and charge failed\n attempts; accepting a gRPC stream does not establish its health.\n\n## Every new field\n\n- Test through the layering: build the effective config the way boot does,\n not by setting the field on the consumer.\n- Add a commented example to `config.example.toml`. Touch `deployments/*.toml`\n only when a profile there needs a value different from the default.\n- Update the wiring matrix in `.agents/skills/archie-config-and-flags`.\n- Secrets are `SecretRef`s resolved throLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/daemon/",
|
||||
"title": "Daemon",
|
||||
"section": "Development",
|
||||
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue needs its own statement (as\n`StampTaskBinding` does for binding provenance and inputs).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
|
||||
"body": "# Daemon\n\nThe daemon claims and runs tasks, and turns captured events into tasks through\nbindings. This page covers both.\n\n## Task lifecycle\n\nAuthority: `docs/architecture/agent-system.md`. The status vocabulary lives in\n`internal/taskstate`, which imports no internal package.\n\n### Adding a status\n\n1. Add the constant to `internal/taskstate/taskstate.go` and place it in\n `Terminal`, `Actions` and `Statuses`. Its value is stored, so renaming it\n later is a migration.\n2. Alias it in `internal/domain/workflow/task/task.go` and\n `internal/domain/workflow/task_aliases.go`.\n3. Add it to the default catalogue in `ui/src/lib/task-meta.ts`. The server\n catalogue replaces the defaults when it loads, but the defaults render first.\n4. Find every hand-written status list in SQL:\n `grep -rn \"'merged'\" internal/infrastructure/postgres/queries`.\n `ClearTerminalTasks` must match `taskstate.Terminal`, which\n `TestClearTerminalTasksMatchesTaskstate` enforces. The stats queries count\n outcomes by name; decide whether the new status counts.\n5. Extend the table in `taskstate_test.go`.\n\n### Adding a task field\n\nFollow [State Store](/dev/development/state-store/) for the\ncolumn and the wire. Then decide who writes it: `UpdateTask` writes a fixed\ncolumn set, so a field set at enqueue belongs in the insert that creates the\nrow (as `InsertChatTask` does for inputs), or in its own statement when only\nsome producers set it (as `StampTaskBinding` does for binding provenance).\n\n### Changing what the agent receives\n\n- The task brief is `container.TaskPayload`, written to\n `\u003cworkspace\u003e/.git/task.json` by `WriteTaskJSON`. Never write it to the\n workspace root: the commit stage stages everything there.\n- The run request is `taskrun.Request`. `Validate` rejects a request that\n cannot run; a new requirement goes there.\n- Parking always carries a class (`taskstate.ParkTransient`,\n `ParkNeedsHuman`, `ParkTerminal`) chosen by the code that parks. Pick the one\n that says what an operator must do.\n- A task with no repository (`Task.HasRepository`) runs in a scratch workspace\n with no worktree grant. Code that assumes an owner and repo must check first.\n\n## Event automation\n\nAuthority: `docs/prds/event-automation.md` (the model: source, event type,\nmapping, binding, workflow, profile) and `docs/architecture/bindings.md`\n(threat model).\n\n### Where each check lives\n\nA binding is checked twice, and a new rule usually belongs in both places:\n\n- **On save**, in `checkedBinding` (`internal/webui/api_binding.go`), so the\n operator sees the problem while editing. It calls the domain checks\n `binding.Validate`, `binding.CompileFilter` and `Binding.CheckWorkflow`.\n- **At dispatch**, in `dispatchOneBinding` and `resolveBindingTarget`\n (`internal/daemon`), because the workflow or mapping may have changed since\n the save. A refusal is recorded with `recordDispatchFailure` and starts no\n task.\n\nPut the rule itself in `internal/domain/binding` or\n`internal/domain/workflow/task` and call it from both, rather than writing it\ntwice.\n\n### Adding a binding field\n\n1. Domain type and `Validate` in `internal/domain/binding`.\n2. Column, queries, store mapping, wire field, `newColumns`\n ([State Store](/dev/development/state-store/)).\n3. The request type and `checkedBinding` in `api_binding.go`.\n4. The draft, payload and editor in `ui/src/bindings/`\n ([Frontend UI](/dev/development/frontend-ui/)).\n5. Its effect at dispatch, with a case in\n `internal/daemon/dispatch_inputs_test.go` or `dispatch_bindings_test.go`.\n\n### Rules that must hold\n\n- Signing belongs to the source. Intake verifies the HMAC against the source's\n secret before the payload is parsed.\n- An event must be identified as an event type before anything dispatches it,\n and a binding applies only to its mapping's event type. Dispatch test\n fixtures therefore create an event type before inserting captures.\n- The dispatch ledger is claimed before the task is enqueued (at most once).\n- Anything an event supplies that selects what the agent acts on, such as a\n repository, must be checked against configuration. An event never widens\n what an agent can reach.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/frontend-ui/",
|
||||
"title": "Frontend UI",
|
||||
"section": "Development",
|
||||
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it.\n\n## Adding an API route\n\n1. The handler goes in the `internal/webui/api_\u003cconcern\u003e.go` file for its\n concern. Check the request fully on the server; the UI's checks are only a\n convenience.\n2. A mutation calls `authorizeTaskMutation` first.\n3. A route whose store is not configured answers 503, and\n `internal/app/archieui/degraded_routes_test.go` pins what each route\n returns without its contract. Add the route there.\n4. The dashboard runs in its own process (`archie-ui`) and must not link the\n daemon or the workflow engine (`cmd/archie-ui/architecture_test.go`). Reach\n stored data through `storecontract` interfaces wired in\n `internal/app/archieui/compose.go`.\n5. Settings that live in a control-plane resource need no new route: the\n Advanced settings page edits every resource from its generated schema.\n"
|
||||
"body": "# Frontend UI\n\nAuthority: `.agents/skills/archie-web-ui` (stack facts, design-system rules,\ntone and accessibility). This page covers what a change must reach, not how it\nshould look.\n\n## Adding or changing a feature\n\n1. The feature lives in `ui/src/\u003cfeature\u003e/`. Move a helper to `ui/src/base/`\n only when a second feature needs it.\n2. Keep wire shapes, draft state and payload building in a plain `.ts` module\n beside the components (`ui/src/bindings/binding-draft.ts` is the pattern),\n and test it in `ui/test/*.test.ts`. Components stay thin.\n3. Every mutation goes through `api.*` in `ui/src/lib/api`, which sends the\n CSRF and Content-Type headers the server's mutation guard requires. A bare\n `fetch` is refused.\n4. A value the server also describes (task statuses, actions, workflow inputs)\n comes from the server. Keep a local default only so the first render works,\n and keep it in step (`ui/src/lib/task-meta.ts`).\n5. Run `task ui`, `task test:ui` and `cd ui \u0026\u0026 npm run typecheck`. Commit the\n regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has\n no ignored `ui/node_modules`: run `cd ui \u0026\u0026 npm ci` before these commands.\n6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only\n `new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume\n topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE\n stream. Logs alone opt in while mounted, replacing that same EventSource\n with `?topics=logs\u0026since=\u003clast cursor\u003e`; a browser's `Last-Event-ID` only\n survives its own automatic reconnect, not a newly constructed EventSource.\n Task and log topics resume by cursor; control-plane, identity and apply-status\n topics replay the latest snapshot. Test a fetch and same-origin navigation\n after visiting Settings and Logs: the UI process serves HTTP/1.1 and six\n persistent streams can starve every later browser request.\n\n## Testing the dashboard\n\nAuthority: the runner itself is `ui/package.json`'s `test` script: `node --test\n--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs\npure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,\nno second dependency beyond what the app already carries. That is the standard,\nand a decision record for when it is deliberately not enough:\n\n- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,\n draft state, copy conditions, filters and payload building live in plain\n `.ts` files beside the components and are tested in `ui/test/`. Components\n stay thin, so there is normally nothing in an SFC that is archie logic.\n- **A dashboard rule that mirrors a server rule is pinned by a shared\n fixture, not two independent tests.** `ui/src/settings/validation.ts`\n hand-mirrors three control-plane validators, and the model-role rule had\n already drifted because nothing tied the two sides together. Each case now\n lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:\n a Go test in that package runs the real server validators over it, and\n `ui/test/control-plane-validator-parity.test.ts` runs the real dashboard\n validators over the same cases. Changing one rule alone fails the other\n side's test. Add a case to the fixture, never to one side only.\n- **Installed primitives are upstream-tested, not re-tested here.**\n `reka-ui` (2.10.5 here) maintains colocated tests per component in its own\n repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the\n arrow-navigation composables). The npm package ships none of those files, so\n this coverage is inherited through the version bound, not the tarball —\n `grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local\n mount tests would test a dependency.\n- **A `.vue` import cannot run under the module runner.** `node --test` fails\n such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no\n built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is\n therefore a broken test, not a weak one.\n- **If a DOM mount harness is ever needed** (a page-level accessibility\n contract, cross-component interaction, focus behaviour): `happy-dom` +\n `@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the\n module runner for everything else. Measured on the ui tree (vitest 5.0.2,\n happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level\n `node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount\n suite (role=radiogroup vs role=switch, aria-label, click activation against\n the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and\n `vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner\n alternative (absorbing the existing suite into vitest) was measured\n infeasible as-is: all 29 existing files impLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/merging-work/",
|
||||
"title": "Merging work",
|
||||
"section": "Development",
|
||||
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n"
|
||||
"body": "# Merging work\n\nParallel lanes (see `.agents/skills/archie-agent-fleet`) merge into an\nintegration branch before `main`. Each merge is a change in its own right and\npasses the same gate.\n\n## Resolving conflicts\n\n- **Generated files** (`*.pb.go`, `postgresdb/*.go`, `ui/dist/`,\n `docs/data/generated/*.json`): take either side, then regenerate. Never merge\n them by hand.\n- **One side deletes a file, the other edits it**: the deletion wins when the\n deleting lane replaced the thing the file served. Move the other side's\n change onto its replacement.\n- **One side changes how code is built (a new store, renamed packages), the\n other what it does**: take the behaviour side's version and reapply the\n mechanical change to it. That is usually cleaner than merging line by line.\n- **Error sentinels** are rows in `wireErrors`, not switch cases.\n\n## After resolving\n\n1. Search for leftovers of anything the other side removed: the old package\n path, the old type, and comments describing the old behaviour.\n2. Tests written against one side's semantics may pass there and fail after\n the merge. A test that used to pass on the old store may be asserting a rule\n the other side deliberately changed. Fix the test's setup to the merged\n rule; do not loosen the rule to the test.\n3. Run the full suite without `-short`, then `task check`, then commit. Check\n `git status` for files a test wrote into the tree before staging.\n4. **A merge can surface a bug neither lane's own tests exposed alone.** Two\n real cases from 2026-09-26: a test that dialled no NATS URL passed on a\n machine with an ambient dev server running and failed the moment it landed\n on a clean CI runner (start an ephemeral server per test, never rely on a\n default port resolving to something); and a cycle-detector that walked a\n Go map in range order reported the same cycle two different ways from run\n to run, invisible until enough fresh (uncached) runs hit the unlucky\n ordering. Both looked like \"the merge broke a passing test\" but were\n latent defects the merge only had the opportunity to expose. Fix the\n defect the failure is pointing at, not the assertion that caught it — see\n CLAUDE.md's test-quality bar before writing the replacement.\n5. `go test`'s cache reuses a package's last result when nothing in its\n dependency graph changed. A merge that touches one package can leave a\n sibling's flaky test silently cached \"pass\" locally while CI runs it\n fresh. `task check` passing on your machine is not proof a merge is\n clean — rerun anything nondeterminism-prone with `-count=1` before\n trusting it, and let CI's from-scratch run be the tiebreaker it is.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/state-store/",
|
||||
"title": "State Store",
|
||||
"section": "Development",
|
||||
"body": "# State Store\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n"
|
||||
"body": "# State Store\n\nAuthority: `docs/prds/state-store-contract.md` and the State Store section of\n`CLAUDE.md`. All persistence is PostgreSQL behind the standalone State Store\nprocess; nothing else opens the database.\n\n## Adding a column\n\n1. Write the next migration in `internal/infrastructure/postgres/migrations/`\n (`00NN_name.sql`, goose Up and Down). Give the column a `NOT NULL DEFAULT`\n that is correct for existing rows.\n2. Update the queries in `internal/infrastructure/postgres/queries/` and\n regenerate with sqlc. A query that lists columns (`ListTaskSummaries`, the\n binding selects) does not pick the new one up; `SELECT *` queries do.\n3. Map it in the store (`taskFromRow`, `bindingValue` and friends). If the\n column holds encoded data, the package that owns the type owns the encoding\n (`task.EncodeInputs`), and the store and the wire both use it.\n4. Carry it over the wire (next section) if any process other than the State\n Store reads it.\n\n## Adding a field to a wire message\n\n1. Add it to `proto/state/v1/state.proto` with a new field number. Never reuse\n a number; retire one with `deprecated = true`.\n2. `task proto:generate`, then map it both ways in\n `internal/infrastructure/staterpc/values.go`.\n3. `TestTaskProtoCarriesEveryDomainField` fills every `task.Task` field and\n fails on one the mapping forgets. If it cannot fill the field's kind, extend\n it. Other messages have no such test, so add a round trip to\n `conformance_test.go`.\n\n## Adding an RPC or a store method\n\n1. Put the Go method on the narrow consumer interface in\n `internal/domain/storecontract` (keep each at eight methods or fewer) and add\n the matching RPC. A Go method without an RPC does not cross the process.\n2. Implement it in the Postgres store, in `staterpc.Client` (with its `var _`\n assertion) and in `staterpc.server`. A missing dependency answers\n `codes.Unavailable`, never a fabricated default.\n3. Wire the dependency in every composition that serves or consumes it:\n `stateStoreDeps` in `internal/app/archied/state_store.go`, the daemon's\n assertions in `bootstrap.go`, and `internal/app/archieui/compose.go` for the\n dashboard process.\n4. Task-scoped tokens may call only `Update`, `Transition` and `InsertEvent` on\n their own task (`staterpc.TaskGrants`). A new RPC is admin-only unless it is\n added there deliberately.\n5. Add it to `conformance_test.go`, which runs every surface over a real gRPC\n connection.\n\n## Adding an error sentinel\n\nAdd the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and\na case to `error_test.go`. The canonical message is part of the wire contract:\nchanging it breaks `errors.Is` on the client silently.\n\n## Harness OAuth secrets\n\n`HarnessSecretStore` stores token sets by org and credential service through\nadmin-only State Store RPCs. The EDA store seals them with the binding cipher's\nkeyring and a separate `HarnessSecretDomain`. OAuth writes require a configured\nbinding encryption key; the legacy binding plaintext fallback does not apply.\nThe daemon's egress proxy (`internal/infrastructure/egress/oauth.go`) is the\nonly daemon consumer: for a run granted the service it swaps sentinels for the\nstored tokens and writes every refresh back. The setup terminal is a separate\nharness slice.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/development/wiring/",
|
||||
@@ -154,13 +154,13 @@
|
||||
"url": "/dev/development/workflows/",
|
||||
"title": "Workflows",
|
||||
"section": "Development",
|
||||
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n"
|
||||
"body": "# Workflows\n\nAuthority: `docs/architecture/agent-system.md` for the lifecycle,\n`docs/prds/event-automation.md` for inputs, repository modes and profiles.\n\nWorkflow definitions are YAML stored as a control-plane resource. The State\nStore validates them and the agent compiles them, each against the step\nvocabulary it registers, so both must see the same step types.\n\n## Adding a step type\n\n1. Write the factory in `internal/domain/workflow` as a `StepType`. It decodes\n and validates its settings and returns an error for anything it cannot\n honour. The factory runs when a definition is saved and again when it is\n compiled, so a bad definition is refused on save.\n2. Register it through a provider in\n `internal/infrastructure/workflowsteps/workflowsteps.go`. That one list is\n what every process registers, which is how the validating and executing\n sides agree.\n3. An agent-driven step builds on `AgentStage`; do not start a second path to\n the agent runner.\n4. A step that needs no repository goes in `repoFreeStepTypes` in\n `definition.go`, or workflows declaring `repository: none` or `optional`\n cannot use it. A step that needs one may assume `tc.Dir` holds a worktree\n only when the workflow's repository is `required`.\n5. A step that ends the workflow sets `tc.Outcome`. A workflow that runs out of\n steps without an outcome is parked as a definition bug.\n6. Add a parse test (settings accepted and refused) and a run test with fake\n `Trees` and agent runner.\n\n## Retiring a step type\n\nA step word cannot simply be deleted. A stored or pinned definition is\nvalidated as a whole collection, so one unknown word fails EVERY workflow's\ndefinition to decode and the workflow-definitions resource becomes unreadable.\nRetire a stage by removing it from its workflow's `Stages` and adding it to\n`retiredSteps` in `definition.go`, which keeps the word resolving as an inert\nstage. The retired stage must do nothing: the behaviour it used to perform now\nbelongs to whatever layer took it over (the remediate workflow's in-container\nresume moved to daemon worktree preparation, `archie-core-866m`; the workflow\nstill binds the daemon-prepared directory and the PR branch in a `prepare`\nstage before any agent work).\n\n## Changing the definition format\n\n- The fields a caller needs without the engine (inputs, repository, profile)\n live in `task.WorkflowInterface`, because the dashboard process must not\n import the workflow engine (`cmd/archie-ui/architecture_test.go`). Anything a\n binding or the dashboard checks goes there.\n- The YAML decoder rejects unknown keys. Existing stored definitions must keep\n parsing, so a new key is optional with a default that preserves today's\n behaviour.\n- A declared `outputs:` entry is written through a capture tool, so it forces\n the captures need: `task.WorkflowInterface.Needs` resolves that from the\n declaration rather than the author also writing `needs.captures`. A Kit\n profile whose harness serves no capture tools is refused before dispatch.\n- Examples in `examples/workflows/` are parsed against the registered\n vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.\n\n## Enabling and disabling\n\nThe `workflow-enablement` control-plane resource lists, per org, the workflows\nthat org has disabled; anything unlisted is enabled. Its readers are the\ndaemon's binding dispatch (a disabled workflow's binding is skipped like an\nunarmed one), the dashboard's binding save (refused) and binding list\n(`workflow_disabled`), and work requests. A new reader of \"may this org run\nthis workflow\" goes through `task.WorkflowEnablement.Enabled`, never a second\nlist. The dashboard acts in the default org until access resolves a caller's\nown.\n\n## Starting a workflow from chat\n\n`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards\ninputs through the task creation contract; it does not interpret individual\nworkflows. The daemon checks inputs against the pinned `WorkflowInterface`\nbefore acquiring a container and parks invalid requests with the reason.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/01-project-management/",
|
||||
"title": "Architecture Decision Index",
|
||||
"section": "PRDs",
|
||||
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
|
||||
"body": "# Architecture Decision Index\n\n**Status:** Approved \n**Date:** 2026-07-28 \n**Beads issue:** `archie-core-5d7`\n\n## Purpose\n\nThis file is the navigation point for Archie's target architecture. It is\ndeliberately short. Architectural decisions are separated by domain or\nrequirement so an implementation task can load only the rules governing its\nscope.\n\nImplementers MUST read the decision document for the domain or requirement they\nare changing. They MUST NOT infer permission to change neighbouring domains from\na broader restructuring objective.\n\n## Global invariants\n\n- Organise code around cohesive application responsibilities, not generic\n technical mechanisms.\n- Domains own their behaviour, vocabulary, state, commands, events, policy\n implementations, runtime settings, and required service contracts.\n- Domains do not depend on infrastructure or manipulate another domain.\n- `internal/app` owns composition; `cmd/*` remains thin.\n- Cross-domain work uses an explicitly owned command, event, or approved shared\n contract.\n- Process boundaries are deployment choices and do not determine source-code\n ownership.\n- Existing package names and boundaries have no presumption of survival.\n\nThe words **MUST**, **MUST NOT**, **SHOULD**, and **MAY** are normative.\n\n## Decision documents\n\n| Scope | Authoritative document |\n| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| Repository layout, domains, composition, deployments, and optional material | [architecture/organisation.md](/dev/architecture/organisation/) |\n| Dependency direction, domain contracts, infrastructure, commands, events, and wire contracts | [architecture/dependencies-and-contracts.md](/dev/architecture/dependencies-and-contracts/) |\n| External configuration, runtime settings, and dissolution of `internal/config` | [architecture/configuration.md](/dev/architecture/configuration/) |\n| Persistent actor identity, ownership, lifecycle, and attribution | [architecture/identity.md](/dev/architecture/identity/) |\n| Agent definitions, workflows, workflow executions, tools, and worker boundaries | [architecture/agent-system.md](/dev/architecture/agent-system/) |\n| Personal-assistant interactions, messaging channels, and optional promotion into durable work | [architecture/messaging-and-work-intake.md](/dev/architecture/messaging-and-work-intake/) |\n| Shared policy evaluation and domain-owned policy semantics | [architecture/policy.md](/dev/architecture/policy/) |\n| Safe source/configuration changes, health supervision, and recovery | [architecture/safe-change-and-recovery.md](/dev/architecture/safe-change-and-recovery/) |\n| Plugin framework, plugin implementations, and extension isolation | [architecture/plugins-and-extensions.md](/dev/architecture/plugins-and-extensions/) |\n| Generated references, deprecations, and changelog generation | [architecture/generated-documentation.md](/dev/architecture/generated-documentation/) |\n| Remaining package destinations, data migrations, runtime cutover, and completion criteria | [architecture/migration-decisions.md](/dev/architecture/migration-decisions/) |\n| Domain/feature research, design interview, and required handoff | [architecture/package-review.md](/dev/architecture/package-review/) |\n\n## Deferred decisions\n\nThe remaining package-placement, data-migration, shared-mechanics, process-\nboundary, and cutover decisions are maintained in\n[architecture/migration-decisions.md](/dev/architecture/migration-decisions/).\n\nEach decision is made in its focused document after code-grounded review.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/RULES/",
|
||||
@@ -178,19 +178,19 @@
|
||||
"url": "/dev/prds/adversarial-self-review/",
|
||||
"title": "Adversarial self-review stage -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n*Conversation isolation is structural, and free.* `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n*Workspace isolation is still ours to build.* A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe *implementer's* model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
|
||||
"body": "# Adversarial self-review stage -- decision\n\n**Status:** Finalised\n**Authority:** `docs/architecture/adversarial-review.md` describes the stage and is authoritative. This PRD remains the design-decision record.\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-h019.1`, blocks `h019.2/.3/.4/.5`\n\n\u003e **Section 1 is superseded by the decision below.**\n\u003e The original execution mechanism assumed daemon-owned in-process execution\n\u003e and a daemon-side second `Pool.Acquire`; `archie-core-q15y` removed both\n\u003e call sites, leaving one open question: how a fresh reviewer receives an\n\u003e isolated snapshot from inside the task-scoped worker, without a host\n\u003e executor or a nested container lifecycle. Section 1 below now answers it\n\u003e with `agent.Subagent`. Sections 2-5 were never invalidated and still hold;\n\u003e section 3's contract shipped as `archie-core-h019.2`.\n\nAnswers the five questions in `h019.1`'s description against the actual\nimplement workflow, not designed from scratch: the gate pattern, the\ncontainer pool, and the workflow engine's `Outcome` mechanism already answer\nmost of this.\n\n## 1. Where it runs: `agent.Subagent`, inside the task worker\n\nThe implement workflow's stage list\n(`internal/domain/workflow/implement.go`) already has the right slot:\nafter `StageDiffCap()`, before `StageOpenPR()` -- gates\nhave passed, the diff is final, and nothing has told the forge about this\nchange yet.\n\n**The reviewer is an `agent.Subagent` run, not a second container.** ai-sdk\n`v0.1.22` (already the pinned version) added `agent/subagent.go`: a nested,\nsynchronous `core.GenerateText` call in the same process, with its own model,\nsystem prompt, toolset and step budget. That is what makes this feature\nbuildable at all after `q15y` -- the reviewer runs inside the task-scoped\n`archie-agent` worker that is already executing the workflow, so there is no\nhost executor, no second `Pool.Acquire`, and no nested container lifecycle.\n\n**Two isolations are needed, and Subagent only provides one of them.**\n\n_Conversation isolation is structural, and free._ `Subagent.Run`\n(`agent/subagent.go`) calls `GenerateText` with `Prompt` set and\n`Messages` never populated. The implementer's history has no code path into\nthe nested run; only the prompt string crosses, and only text comes back.\nThis is the literal form of \"environmental enforcement over prompt rules\":\nthe reviewer is not told to ignore the implementer's reasoning, because\nnothing hands it any. `h019.3`'s required test asserts this as a construction\nfact.\n\n_Workspace isolation is still ours to build._ A sub-agent shares the parent's\nprocess, working directory and credentials. So the `.git`-free snapshot from\nthe original decision survives unchanged and is load-bearing: export the\nreviewed commit (`git archive \u003ccommit\u003e | tar -x`) into a fresh scratch\ndirectory beside, not inside, the task worktree, and write `diff.patch` (the\ndiff already computed for `StageYaegiGate`'s `Trees.Diff()`) and `issue.md`\n(the originating issue's title and body, nothing else) alongside it. Stripping\n`.git` is what makes commit messages, branch name and reflog -- the actual\nchannel a multi-commit implementer's reasoning leaks through -- structurally\nunreachable rather than merely undisclosed.\n\n`Subagent.Tools` therefore takes a **distinct read-only toolset rooted at the\nsnapshot**. Never the worker's own toolset: it carries the `worktreerpc`\npublication grant, so a reviewer holding it could push the branch it exists to\nblock.\n\n**Call `Run()`, not `Tool()`.** `Tool()` would register delegation as a tool\nthe _implementer's_ model may choose to invoke -- self-certification by the\nimplementer, which is the exact failure this feature exists to prevent. The\nstage calls `Run()` unconditionally. That also sidesteps both of `Tool()`'s\ndocumented footguns: the parent's two-step minimum and the recursion risk of\npassing a toolset back to itself.\n\n**Findings return through a closure, not the return value.** `Run` yields only\nfinal text, so section 3's structured contract cannot ride the return. Because\nthe sub-agent is in-process, the capture tool's Go implementation appends\ndirectly to a `[]workflow.ReviewFinding` the stage owns. This preserves the\n\"cannot end its turn without calling a typed tool\" property, and it defeats\n`Subagent`'s documented \"no partial results on failure\" limitation: findings\nalready captured survive an error return, so **the stage reads the captured\nslice even when `Run` returns an error**. A reviewer that logged three defects\nand then hit its step limit still yields those three.\n\n## 2. What it's given, and what it must never be given\n\n**Given:** the clean file-content snapshot (so the reviewer can read whole\nfiles -- follow an import, check interface satisfaction, see a call site --\nnot just diff hunks, which the manual-read checklist in CLAUDE.md rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/agent2agent-protocol/",
|
||||
"title": "Agent2Agent as archie's agent-to-agent protocol — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the *client* must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
|
||||
"body": "# Agent2Agent as archie's agent-to-agent protocol — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** the A2A Protocol Specification v1.0.0 (`a2a-protocol.org`) for the\nprotocol, `docs/architecture/organisation.md` for package placement, and\n`docs/architecture/migration-decisions.md` §2 for session and messaging design.\n\n## Decision\n\nA2A is the protocol archie speaks to other agents. It carries agent-to-agent\nwork: discovery of what a remote agent offers, delegation of a unit of work to it,\nprogress on that work, and the artifacts it produces.\n\n## Layers\n\n**MCP stays the tool layer.** MCP connects a model to tools and data; A2A connects\nagents to agents. They are complementary and archie runs both:\n`internal/tools/provider` registers MCP providers as optional capabilities, so an\nA2A call and an MCP tool call are different kinds of traffic with different\nowners.\n\n**A2A rides archie's existing transports.** A2A's canonical data model is\nProtocol Buffer messages and it defines a gRPC binding, so archie speaks A2A over\nthe gRPC and NATS it already runs. A second wire format, a second broker, or a\nbespoke protocol for agent-to-agent traffic is a requirement not to introduce.\n\n## Where A2A stops\n\nA2A is not a general replacement for either of the two protocols archie already\nhas, and each boundary is a requirement rather than a preference.\n\n- **`internal/domain/messaging` stays the human and channel layer.** A\n Conversation is a ChannelID and a ThreadID, its participants are people on\n Telegram, email, webhook and the dashboard, and its records are what a curator\n reads. An A2A peer is not a channel participant and does not address a\n Conversation.\n- **`internal/agentexec` stays the daemon-to-worker execution protocol.** It\n carries a Request, a Result, gate and budget policy, and capture tools between\n the daemon and the agent container it owns. An A2A peer never receives that\n protocol, and A2A never carries gate, budget or protection policy.\n\nA2A is therefore an edge protocol: it exchanges work with peers outside archie's\nown process boundary, and it composes with the two protocols above rather than\nreplacing or abstracting them.\n\n## A2A Task mapping\n\n**Decision: archie's work lifecycle is mapped to A2A's, not expressed in it. An\nA2A Task is a view over archie's own task, and archie's status remains the record\nof truth.**\n\nThis is the load-bearing decision, because A2A's Task carries its own state\nmachine and archie's lifecycle is the on-disk format of its task store, whose\nstatus strings a rename migrates rather than changes.\n\nThe mapping is partial, and each gap is a case where archie knows something A2A's\nstates do not carry:\n\n- **Completion by another system.** A2A's terminal states describe what the agent\n did (`completed`, `failed`, `canceled`, `rejected`). archie's `merged` and\n `rejected` describe what a forge did to a pull request after archie finished\n its work. There is no A2A state for \"an external system accepted this\", so a\n completed A2A task cannot express the outcome that matters most to the caller.\n- **Handing work to a reviewer.** archie's `pr_open` means the work left\n archie's hands for human review. A2A's `input-required` is the nearest state,\n but it means the _client_ must send more input, and a reviewer is not the\n client.\n- **Operator decisions.** `declined`, `parked` and `dead` are outcomes of\n archie's own policy and operator actions. A2A has no state for \"the operator\n refused this\" or \"a budget ran out and an operator must decide\".\n\nA WorkflowExecution is the unit an A2A task maps onto, because it is the attempt\nthat runs, streams and produces artifacts, and a follow-up attempt is a new\nexecution. A2A's own model agrees that a task is immutable once terminal and that\na refinement is a new task sharing the `contextId`, which is why archie's\nper-attempt executions and A2A's per-request tasks correspond.\n\n**Requirement:** the A2A state a peer sees is derived from archie's status by one\nmapping, and archie's status is carried on the task so a peer can read what the\nderivation lost. The mapping is total in the direction that matters -- every\narchie status has an A2A state -- and deliberately not injective, because the\ngaps above are facts A2A cannot hold.\n\n**Requirement:** adopting A2A's state names as archie's persisted task status is\nrejected. It would migrate the task store, and it would drop the forge outcomes\nthat tell a caller whether the work was accepted.\n\n## What an A2A agent is\n\n**An A2A agent is an archie Identity.** The Agent Card describes a durable,\naddressable actor with an endpoint, capabilities and authentication requirements,\nand an Identity is the actor archie persists, versions, suspends and scopes\ncredentials to.\n\nAn `agent.Persona` is not an A2A agent: a persona is prompt text selected for a\nturn, and it has no endpLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/artifact-sender/",
|
||||
"title": "Artifact sender",
|
||||
"section": "PRDs",
|
||||
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback."
|
||||
"body": "# Artifact sender\n\n**Status:** Approved\n**Revision:** 1\n**Authority:** this document\n\n## Purpose\n\narchie-core publishes artifacts — design documents, review reports, research briefs,\nrunnable pages — to the offloaded.dev collaborative editor. A person reads the\nartifact, comments on it, and the artifact page is the shared surface for iteration.\n\nThe receiving contract is owned by the editor: `POST /api/artifacts` with a bearer\nservice token, a closed field set, and server-side idempotency on `requestId` plus\nlast-write-wins on `sentAt`. This document owns only what archie-core sends.\n\n## Scope\n\nVersion one publishes one-way: archie-core sends, the editor receives. The first\nproducer is the pull-request adversarial review: a completed `ReviewReport` is\nrendered to markdown and published after the review completes.\n\nChat-surface tools (`create_artifact`, `update_artifact`), comment read-back, share\ntokens, and runnable-format producers (`html`, `react`, `vue`) are later slices. The\nreceiving contract already carries them; version one does not exercise them.\n\n## Configuration\n\n- New `[artifacts]` section: `base_url` (site origin), `token` (`SecretRef`) with\n `token_env` fallback naming `WORKSPACE_INGEST_TOKEN`.\n- An empty `base_url` disables the sender: no client is constructed, nothing is\n registered, and publishing degrades to a log line.\n- The token is runtime configuration. It is never baked at build time.\n\n## Sender\n\n- New package `internal/infrastructure/artifactsync` exposing one method,\n `Publish(ctx, Artifact) (string, error)`, where the string is the artifact URL.\n One-method injected seam, concrete client constructed by the boot path when the\n configuration resolves — the `crondelivery.Courier` posture.\n- The client POSTs the frozen contract body. Each publish sends the complete\n source: versions of record are full snapshots, never diffs.\n- A `503` response is retried three times with backoff. `401` and `400` are not\n retried; they are logged with the field reason the response names.\n- `requestId` is `artifact:\u003ctask-id\u003e:\u003cversion\u003e` when the producer is task-backed,\n otherwise `artifact:\u003cidentity\u003e:\u003csentAt-utc\u003e`. Sending the same `requestId` with\n an equal or older `sentAt` must be a server-side no-op, which makes sender-side\n retry safe.\n\n## Report rendering\n\n- `ReviewReport` gains a pure markdown renderer in `internal/domain/workflow`:\n the summary as the lede, one finding per subsection with file, line, verdict,\n level and the failure scenario, and the verified properties as a \"checked\n clean\" list. Findings carry their disposition when present.\n- The renderer performs no I/O and imports no infrastructure.\n\n## Attribution\n\n- `actor`: the producing identity. The reviewer publishes as `system:pr-reviewer`\n when no task identity resolves; otherwise the task's identity name.\n- `source`: the producing subsystem, `pr-review` for version one.\n- `task`: owner, repository and issue number from the task when one exists.\n\n## Failure behaviour\n\n- Publishing never fails the producing work. A failed publish is logged with its\n status and reason; the artifact is republished on the next production of the\n same artifact.\n- A successful publish records the artifact URL in the run report, so the PR\n description or task log links to the readable artifact.\n- The published URL is the editor deep link for the artifact, keyed on its\n immutable id. archie-core never mints share links; sharing is an\n account-holder decision made in the editor.\n\n## Verification\n\n- Client tests against a test server cover 201, 401, 400 with a field reason,\n and 503 retry behaviour.\n- The report renderer test covers a report with findings, checks, dispositions\n and a not-run status.\n- Configuration tests cover the disabled case, the `SecretRef` path and the\n `token_env` fallback.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/binding-secret-encryption/",
|
||||
@@ -208,43 +208,43 @@
|
||||
"url": "/dev/prds/code-graph-mcp/",
|
||||
"title": "Code graph over MCP (`tools/codegraph`)",
|
||||
"section": "PRDs",
|
||||
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --- | --- |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.ValueOf` table reports zero `prod`\n references and one `dynamic`, and names the table in `dynamic_edges`.\n4. A generated file's references land in `generated`, not `prod`.\n\nMutation-verify eachLine truncated
|
||||
"body": "# Code graph over MCP (`tools/codegraph`)\n\n**Status:** Draft\n**Supersedes:** `symbol-reference-index.md`, which scoped only the data layer.\n\n## The problem\n\nEstablishing what a change touches costs an agent eight to fifteen\ngreps, and the answers are wrong in specific ways. `grep -rn \"Register(\"`\ncannot separate `plugin.Registry.Register` from `captureintake.Receiver.Register`\nfrom `forgerpc.Server.Register`, all of which exist here. It also matches the\nsibling checkouts under `.worktrees/`, which are near-complete copies of the\nmodule, so every count is silently inflated.\n\nThat cost lands hardest in investigation, triage and the TDD loop, where the\nfirst question is always \"what does this touch\".\n\n## Decision: exact analysis, not semantic retrieval\n\nTools like Greptile parse with tree-sitter, summarise each node, embed the\nsummaries, and retrieve semantically. That design exists because they must\nserve any language. This repository is one Go module, and Go's type checker is\nground truth:\n\n| Question | Source of truth |\n| --------------------------- | ------------------------------------------------ |\n| Who references this symbol? | `go/packages` + `go/types`, resolved by identity |\n| What calls what? | `callgraph` RTA over SSA |\n| What imports what? | `go list -deps` |\n\nNo vector database, no embedding cost, no edges invented by a summary that\ndrifted from the code. For a single-language repository this is both cheaper\nand strictly more accurate. Copy the interface those tools expose, not their\narchitecture.\n\n**A code graph does not power a documentation chatbot.** It answers structural\nquestions about Go symbols. Answering \"how do I configure a second identity\"\nmeans retrieving prose from markdown, which needs chunking, embedding and\nsimilarity search over a different corpus entirely. That remains a separate\ncapability with its own design. Conflating the two would build one system that\ndoes neither well.\n\n## Interface: an MCP server\n\n`archied` already consumes MCP as a client (`internal/app/agentworker`\nstarts providers) and serves none. Exposing the graph over MCP reaches Claude\nCode, pi, codex and Archie's own agents through one surface, with no coupling\nto the daemon: it is configured like any other entry in `[[mcp_servers]]`.\n\nFour tools, each returning JSON with file:line citations:\n\n- `references(symbol)` — every reference site, classified `prod` / `test` /\n `generated` / `dynamic`\n- `callers(symbol, depth)` — inbound call edges\n- `callees(symbol, depth)` — outbound call edges\n- `blast_radius(file | symbol)` — the transitive neighbourhood a change reaches,\n which is the single call meant to replace the grep sequence\n\nDiagrams are deliberately not a tool. A model given an accurate subgraph writes\nits own Mermaid; a diagram endpoint would only fix the rendering of something\nthe model already has.\n\n## Decisions\n\n**Every answer declares what it could not see.** RTA over-approximates\ninterface dispatch, and reflection is invisible: every `reflect.ValueOf` entry\nin `wfextract`, `gateextract`, `pluginextract`, `secretextract` and\n`logextract` makes a symbol look reachable whether or not anything calls it.\nEach response carries a `dynamic_edges` field naming those boundaries. An agent\ntrusting a confident wrong graph is worse off than one that greps, so the graph\nstates its own limits rather than implying completeness.\n\n**Warm in memory, keyed on HEAD, never persisted to disk.** `deadcode` does\nwhole-program RTA in under seven seconds; this does less work. The server\nrebuilds when HEAD changes and refuses its cache outright when the tree is\ndirty. Nothing is written to disk, because a persisted index becomes a rendered\nview that outlives its evidence. That is the failure that made `STATUS.md`\nreport 90 of 91 findings re-verified while most statuses were 77 commits stale,\nand the same one that made `reachaudit` serve a previous tree's analysis from\n`/tmp` until its cache was keyed on HEAD.\n\n**`tools/codegraph`, not `internal/`.** It is developer tooling, not daemon\nruntime, so it belongs beside `docsgen`, `contractaudit` and `reachaudit` in\nthe `tools` module, which `task test:tools` already covers. Start as a single\nGo file; split only when it earns it.\n\n**No new dependency.** `golang.org/x/tools` is already in `go.sum` at v0.49.0.\n\n## How it is verified\n\nRed first. Table-driven tests against small fixture modules built in\n`t.TempDir()`, asserting the behaviour that distinguishes this from grep:\n\n1. Two methods spelled `Register` on different types resolve to two separate\n records, and a reference to one does not increment the other.\n2. A symbol referenced only from `_test.go` reports zero `prod` references.\n3. A symbol referenced only from a `reflect.VLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/config-example-drift/",
|
||||
"title": "Example-config and generated-config drift — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be *generated*, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active *and* commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a *different* binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
|
||||
"body": "# Example-config and generated-config drift — decision\n\n**Status:** Approved\n**Date:** 2026-09-15\n**Closes:** the checked-in-config half of audit findings `config-1` and\n`repo-root-deployment-2`; strengthens `doc-drift` findings generally.\n**Authority:** extends `docs/architecture/generated-documentation.md` and\n`docs/prds/config-schema.md`; does not replace either.\n\n## Question\n\nShould `config.example.toml` and `deployments/*.toml` be _generated_, so they\ncannot drift from the config code?\n\n## Decision\n\n**No — do not generate them. Gate them instead.** Neither file is a projection\nof the schema, and generating either would destroy the thing that makes it\nuseful. Three verified reasons, in order of weight:\n\n1. **`config.example.toml`'s value is its comments.** It documents **137 keys**\n (measured: active _and_ commented-out), and those hand-written comments are\n the file's purpose — `docs/architecture/configuration.md` states outright\n that \"`config.example.toml` carries documentation users are meant to\n hand-edit\". TOML round-tripping does not preserve comments, which is exactly\n why `tomlwrite` does line-oriented edits rather than decode/encode. A\n generator would emit a correct file with the documentation deleted.\n2. **`docs/prds/config-schema.md` forbids building on `config.Config`.** That PRD\n rejects \"a reflection-based schema over `config.Config`\" because the struct is\n \"scheduled for dissolution\". A generator deriving the example from its struct\n tags would build on a foundation this repo has already decided to remove.\n3. **`docs/architecture/generated-documentation.md` prohibits it.** \"Adding\n another hardcoded type list to `docsgen` is prohibited\" — so any generator\n must consume a domain-owned registry, which does not exist for configuration\n yet. Creating one is the config-domain migration's job, not this change's.\n\nThe deployment profiles are also not a projection: they set **3-46 keys** against\nthe example's 137, and they are curated overlays (\"a complete config, not an\noverlay\", per their own headers), not near-duplicates. Generating them would add\nmachinery to remove duplication that largely is not there.\n\n## The gap that is real\n\n**Unknown config keys are silently ignored.** Verified at\n`internal/infrastructure/configuration/decode.go`:\n\n```go\nif _, err := toml.DecodeFile(path, target); err != nil {\n```\n\nThere is no `MetaData.Undecoded()` check, so a typo — `max_concurrancy = 4` —\nparses clean, validates clean, and does nothing. That is the same failure shape\nthis repo's audit found repeatedly: a setting that looks applied and is not. It\nis also detectable **without any hand-maintained list**, because `BurntSushi/toml`\nreports exactly which keys the target did not consume.\n\nNote the second, separate gap already admitted in writing:\n`generated-documentation.md` — \"`task check` does not run `docs:check`, so\ngenerated drift is ungated.\"\n\n## What to build\n\n**1. Unknown-key detection at the loader (behaviour).** Decode with metadata and\ncollect `Undecoded()`. Report it as a warning at startup listing the offending\nkeys, and expose it so tests can assert emptiness.\n\n**Deliberately a warning, not a fatal error.** `configuration.md`'s settled\nstartup policy is \"a missing credential disables a capability; only an invalid\nconfig stops the daemon\". A stray key is far more likely to be an operator typo\nin a file they are otherwise happy with than a reason to refuse to boot, and\n`[web]` is documented as landing in a _different_ binary\n(`internal/app/archieui`), so a key unknown to one process is legitimately known\nto another. Failing closed here would break working deployments on upgrade.\n\n**2. A checked-in-config contract test (gate).** Load `config.example.toml` and\nevery `deployments/*.toml` through the real loader and assert `Undecoded()` is\nempty, with an explicit allowlist for keys another binary owns. This is the\nmechanism that would have caught a renamed key left behind in an example, and it\nneeds no inventory.\n\n**3. Gate generated data in `task check`.** Done. `task docs:check` runs in the\ngate, closing the admitted \"generated drift is ungated\" hole. The\ncheck mode did not exist when this was written; it was added for issue #855,\nwhich also made the check non-destructive so the gate can never rewrite the\nartifact it is judging.\n\n**4. Explicitly NOT now: a generated key inventory.** `configuration.md`'s\ncompletion criteria want \"generated documentation lists every external key,\ndefault, constraint, mutability class, owner\". That is a real target and it is\nthe config domain's, once a domain-owned registry exists — the prohibition above\nmeans it cannot be bootstrapped from a list inside `docsgen`. Recorded as\ndeferred, not rejected.\n\n## Non-goals\n\n- No generation of `config.example.toml` or `deployments/*.toml`.\n- No reflection-baLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/config-schema/",
|
||||
"title": "Backend-owned configuration schema for the webui -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalogue, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter(f =\u003e f.type !== \"structured\")\n .map(f =\u003e row(f.label, f.value, {\n key: f.key, type: f.type, options: f.options,\n locked: f.locked_reason, overridden: f.overridden,\n restartRequired: f.restart_required,\n }));\n // structured fields render through their dedicated editor (b6ew.4)\Line truncated
|
||||
"body": "# Backend-owned configuration schema for the webui -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-b6ew` (epic), with children `.1`-`.5`\n\n## Decision\n\nThe dashboard's Configuration page keeps reading a secret-free,\nhand-picked view of `config.Config` -- that allowlist is a safety\nboundary and stays exactly as it is. What changes is who defines the\npage around it: `ui/src/settings/settings.js` and\n`config-row.js` hardcode every row's label, section, type, and\neditability by hand; after this, the backend attaches that metadata to\neach field it already allows through, and the frontend renders\nsections and fields generically from what the backend sends.\n\nThis is **not** a reflection-based schema over `config.Config`.\n`internal/config/config.go`'s own package doc states it is \"scheduled\nfor dissolution: its types and methods are to be reassigned to the\ndomains whose behaviour they describe\" -- building a generic\nschema-from-struct-tags mechanism over a struct on its way out would be\nbuilding on a foundation this repo has already decided to remove.\nInstead, every field already in `ConfigView` (`internal/webui/api_config.go`)\ngot there because someone deliberately vetted it as safe to show; the\nschema adds a hand-authored descriptor to that same deliberate act,\nnot a new mechanism that re-derives safety automatically.\n\n## Why now\n\nTask #6's investigation (`/9/26`) found the concrete failure this\nproduces: `Repo.AllowConcurrent` and `Repo.MaxRetries` already reach\n`GET /api/config` (`RepoView` in `api_config.go`), but the\nrepositories card renders a static read-only table that never shows\nthem, so the fix for \"why isn't a second agent running\" required an\nagent tracing Go source instead of a checkbox on the dashboard.\n`Repo.ReviewEnabled` is worse: it never reaches the API at all. Both\nare symptoms of the same root cause -- the frontend decides what a\nfield means and whether it's shown, and nothing keeps that in sync\nwith what the backend actually allows.\n\n## Shape\n\n```go\n// internal/webui/config_schema.go (new)\n\ntype ConfigFieldType string\n\nconst (\n FieldString ConfigFieldType = \"string\"\n FieldInt ConfigFieldType = \"int\"\n FieldBool ConfigFieldType = \"bool\"\n FieldDuration ConfigFieldType = \"duration\"\n FieldEnum ConfigFieldType = \"enum\"\n FieldStructured ConfigFieldType = \"structured\" // repositories, models, providers\n)\n\ntype ConfigField struct {\n Key string `json:\"key\"` // dotted path, matches UpdateConfig's key space\n Label string `json:\"label\"`\n Description string `json:\"description,omitempty\"`\n Type ConfigFieldType `json:\"type\"`\n Value any `json:\"value\"`\n Editable bool `json:\"editable\"`\n LockedReason string `json:\"locked_reason,omitempty\"`\n Overridden bool `json:\"overridden\"`\n Options []string `json:\"options,omitempty\"` // enum only\n RestartRequired bool `json:\"restart_required\"`\n}\n\ntype ConfigSection struct {\n ID string `json:\"id\"`\n Label string `json:\"label\"`\n Fields []ConfigField `json:\"fields\"`\n}\n```\n\n`handleConfig` builds `[]ConfigSection` from the existing per-field\nvalues it already assembles, plus `overlay.DeniedKeys` for\n`LockedReason` and the existing `Overridden` list -- both already\ncomputed just re-attached per field instead of returned as\nside-channel maps the frontend cross-references by key string.\n`Locked`/`Overridden`/`Reload`/`Provenance` stay as top-level\n`ConfigView` fields; they describe runtime state (what happened on\nthe last reload, which keys the overlay refuses), not the field\ncatalogue, and duplicating that logic per-field would be the same drift\nrisk this change exists to remove.\n\n`FieldStructured` fields (repositories, models, providers) carry\n`Value` as structured JSON and are rendered by dedicated\neditors, not the generic renderer -- see \"What this does not do\".\n\n## Sections\n\nMatches the cards the settings page already has: `identity`,\n`repositories`, `models`, `providers`, `budgets`, `storage`,\n`containers`, `web`. No new sections; this is metadata on existing\nrows, not new configuration surface.\n\n## Frontend\n\n`config-row.js`'s `row(label, value, opts)` becomes the renderer's\nprivate implementation detail, called generically:\n\n```js\nfor (const section of schema.sections) {\n const rows = section.fields\n .filter((f) =\u003e f.type !== \"structured\")\n .map((f) =\u003e\n row(f.label, f.value, {\n key: f.key,\n type: f.type,\n options: f.options,\n locked: f.locked_reason,\n overridden: f.overridden,\n restartRequired: f.restart_required,\n }),\n );\n // structured fLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/contract-conformance-audit/",
|
||||
"title": "Contract conformance audit — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — *is this code\nin a shipped binary?* — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| --- | --- | --- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| --- | --- | --- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`broken`.\"** Wrong.\n Every raw call site passed `res.status` to `ApiError`, so `classifyActionError`\n already mapped 401 to `session-expired`; the chat stream never classified at\n all. The real defect in that area was different (below).\n- **A five-surface \"Shape\" naming `surface.go`, `generated.go`,\n `declarations.go`, and `testdata/`.** None were written. The real files are\n `main.go`, `audit.go`, `proto.go`, `webui.go`.\n\n## The two gaps this was aimed at\n\n**1. `docsgen check` is documented and does not exist.** Closed by issue #855.\n(issue #855 / `archie-core-5gzx`). `tools/docsgen` now has a `check` subcommanLine truncated
|
||||
"body": "# Contract conformance audit — decision\n\n**Status:** Finalised\n**Scope:** an **advisory** report, deliberately **not** part of `task check`.\n**Date:** 2026-09-15\n**Authority:** sibling to `archie-core-06ag` (standing reachability audit) and\n`docs/architecture/dependencies-and-contracts.md`. Replaces neither.\n**Open:** withdraw it, or rebuild it structurally. See \"Open decision\" — not to\nbe resolved by hardening the regexes.\n\n## Question\n\nDoes every declared contract surface have a consumer, or an explicit declaration\nthat it has none?\n\nReachability (`tools/reachaudit`) asks the complementary question — _is this code\nin a shipped binary?_ — and cannot see a capability that is **reachable and\nunconsumed**. `ratelimit` was in the binary closure and called by nothing\n(`archie-core-6wxb`); reachability would not have found that.\n\n## Decision\n\nYes, as an advisory survey. `tools/contractaudit` classifies each subject of each\nsurface:\n\n| Classification | Meaning | Fails `--strict`? |\n| ----------------------- | ----------------------------------------------------------------------------- | ----------------- |\n| `CONSUMED` | a call site exercises it | no |\n| `DECLARED-UNCONSUMED` | allowlisted in `docs/contract-declarations.json`, with a reason and a tracker | no |\n| `UNDECLARED-UNCONSUMED` | nobody reaches it, nobody declared it | **yes** |\n| `STALE-DECLARATION` | an allowlist entry that is no longer true | **yes** |\n\nThere are **four** classes and **two** of them fail. The allowlist must match\nreality exactly, and it fails in both directions: a missing entry is a finding,\nand an entry that outlived its subject is a finding, because a stale allowlist is\nhow a check quietly stops checking anything.\n\n**Not gated.** `task contract` is advisory and `task check` does not run it,\nmatching `tools/reachaudit`. The surfaces are discovered by scanning source text,\nso a rename or a reformat elsewhere in the tree can change the output with nothing\nactually wrong. It has already produced 16 false \"unconsumed\" readings once, when\nthe dashboard's request helper was renamed. A check that can fail for reasons\nunrelated to what it measures must not be able to break a build.\n\n## Surfaces actually built — three, not five\n\n| Surface | Subjects | \"Consumed\" means |\n| ------------------------------------ | ------------- | -------------------------------------------------------- |\n| `proto/state/v1` `StateStoreService` | **45 RPCs** | an adapter body calls `client.\u003cRpc\u003e(...)` |\n| `proto/gateway/v1` `ChatService` | **21 RPCs** | same |\n| `internal/webui` dashboard routes | **49 routes** | a path literal appears as a call argument under `ui/src` |\n\nConsumption for the gRPC surfaces is established by **scanning adapter source\ntext** for calls through the generated client, not by reflection. See the errata\nbelow: the first revision of this document claimed reflection, and the first\nimplementation did use it, but the shipped mechanism is a regex and the document\nwas not updated to match.\n\n## What this audit has actually found\n\n**Nothing actionable.** On the current tree it reports 0 undeclared and 0 stale.\nIts only allowlisted entries are two RPCs superseded by their streaming variants\n(`ListCaptures`, `ListUndispatchedCaptures`), which were already known from the\nsource comment on `staterpc.Client.ListCaptures`.\n\nEvery real defect found in the session that produced this tool was found by other\nmeans:\n\n- the three 415 refusals, by reading `authorizeTaskMutation` and reproducing the\n browser's exact headers against the real handler;\n- the dashboard client's duplicated request plumbing, by reading the module.\n\nRecorded plainly because a survey that has never found anything is evidence about\nthe survey, not about the tree.\n\n## Errata — claims in the first revision of this document that were false\n\n- **\"RPC coverage is derived by reflection over the exported client type.\"**\n It is not. `proto.go` regex-scans adapter bodies for `client.Method(` calls.\n The reflection version was replaced and the document was not updated. The unused\n `google.golang.org/grpc` family in `tools/go.mod` was residue from that\n iteration; `go mod tidy` removed it on 2026-09-15.\n- **Surface sizes of \"43 / 12 / 52\".** The real counts are 45 / 21 / 49.\n- **\"Three classifications, and the third is the only finding.\"** Four classes,\n two of which fail.\n- **\"Raw `fetch()` calls caused 401s to render as `refused`/`brokLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/control-plane-apply-status/",
|
||||
"title": "Control-plane apply status",
|
||||
"section": "PRDs",
|
||||
"body": "# Control-plane apply status\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Tracking:** `archie-core-pskb`, and `archie-core-nwa0` which depends on it\n\n## Outcome\n\nAn operator who edits a control-plane resource can see which processes are\nrunning that version, which are still on an older one, which rejected it, and\nwhich have stopped reporting.\n\n`docs/prds/runtime-control-plane.md` requires this and does not say where the\nreport goes. This decides that.\n\n## Where the report goes\n\nApply status is a State Store contract surface. `ControlPlaneService` is the\nsurface for editing a resource, and a status report is not an edit. The\nprecedent is the config snapshot pair: a process publishes what it knows, the\nUI process reads it, and both RPCs are administrative, so a task-scoped grant\nreaches neither. That denial needs no new rule: `authorizesTaskScopedCall`\nnames three methods and denies everything else.\n\n`docs/prds/state-store-contract.md` gains the pair in its inventory, and its\nRPC count at two places moves from 45 to 47.\n\nThe read returns all records as a list, including an empty one. The\n`found=false` convention for absent single rows does not apply.\n\n## What is reported\n\nOne record per process and resource kind, replaced in place. It holds the\nprocess name, the resource kind, the version applied, the error if the process\ncould not apply it, and the time it reported.\n\nEach process re-stamps its records every 30 seconds. A record is stale once it\nis older than 90 seconds, and a stale record means the process that wrote it is\nno longer running. The report time is therefore a liveness signal, not only a\nwrite timestamp.\n\nA process reports at the point it applies a resource, so the record says what\nhappened rather than what was intended. Nothing probes.\n\nProcess names come from one shared constant naming `archied`, `archie-gateway`\nand `archie-messaging`. A deployment runs at most one of each. Writer and\nreader are bound to that constant by test, because a drifted name is\nindistinguishable from a process that never reported.\n\n## Which processes report\n\n- `archied` and `archie-gateway` apply every restart-required kind through\n `boot.runtimeConfig`, at boot and on SIGHUP.\n- `archied` also applies the live kinds it watches, and reports each update it\n applies.\n- `archie-messaging` applies channel settings at startup and reports that kind.\n\n## What can be reported, and what cannot\n\nA process reaches its apply point only after the State Store has answered it.\nWhen the State Store is unreachable, the process exits or refuses to start and\nwrites no record. An unreachable store is never reported as a failure by the\nprocess it affected. A record carries the other failure: the store answered,\nand the value would not validate.\n\nAbsence has two meanings and the UI never collapses them: no process applies\nthis kind, or a process that applies other kinds has not reported this one.\n\n## Relationship to the reload status\n\nApply status covers control-plane resource kinds. `ReloadStatus` covers the\nfile document and stays the only report for a SIGHUP that failed to resolve or\nvalidate it. Neither is derived from the other.\n\nWriting a record is best-effort. On the SIGHUP path it takes its own bounded\ncontext, separate from the budget the reload spends reading the control plane,\nand a failed write is logged rather than turned into a failed reload.\n\n## What the UI shows\n\nThe settings page shows, per resource, the stored version beside each process's\napplied version, error, and report time. A process on an older version of a\nrestart-required resource is pending a restart. A process with an error is\nfailed, with the error beside it. A process whose record is stale is unknown,\nnever current.\n\n## A record outlives the process that wrote it\n\nRecords are replaced in place, so a process that applies a version and then\nstops would otherwise leave a record asserting that version indefinitely, and\nthe settings page would show a dead process as current.\n`docs/prds/status-health-surface.md` faced the same choice and stamped the start\nof a poll pass so a wedged poller reads as stale rather than healthy.\n\nSettled: the re-stamp above. The alternatives considered were\ncarrying the instance identity generated at process start, which detects a\nrestart but not a death, and accepting the limitation with the page saying so.\n\n## Verification\n\n- A process that applies a resource writes a record carrying that version.\n- A process whose apply fails validation writes a record carrying the error and\n no new version.\n- A reload that fails leaves the previously applied version recorded.\n- A record written under a process name outside the shared constant fails the\n test binding writer to reader.\n- A task-scoped credential is refused by both RPCs.\n- A failed report does not fail the reload that produced it.\n- A record that stops being re-Line truncated
|
||||
"body": "# Control-plane apply status\n\n**Status:** Approved\n**Date:** 2026-09-21\n**Tracking:** `archie-core-pskb`, and `archie-core-nwa0` which depends on it\n\n## Outcome\n\nAn operator who edits a control-plane resource can see which processes are\nrunning that version, which are still on an older one, which rejected it, and\nwhich have stopped reporting.\n\n`docs/prds/runtime-control-plane.md` requires this and does not say where the\nreport goes. This decides that.\n\n## Where the report goes\n\nApply status is a State Store contract surface. `ControlPlaneService` is the\nsurface for editing a resource, and a status report is not an edit. The\nprecedent is the config snapshot pair: a process publishes what it knows, the\nUI process reads it, and both RPCs are administrative, so a task-scoped grant\nreaches neither. That denial needs no new rule: `authorizesTaskScopedCall`\nnames three methods and denies everything else.\n\n`docs/prds/state-store-contract.md` gains the pair in its inventory, and its\nRPC count at two places moves from 45 to 47.\n\nThe read returns all records as a list, including an empty one. The\n`found=false` convention for absent single rows does not apply.\n\n## What is reported\n\nOne record per process and resource kind, replaced in place. It holds the\nprocess name, the resource kind, the version applied, the error if the process\ncould not apply it, and the time it reported.\n\nEach process re-stamps its records every 30 seconds. A record is stale once it\nis older than 90 seconds, and a stale record means the process that wrote it is\nno longer running. The report time is therefore a liveness signal, not only a\nwrite timestamp.\n\nA process reports at the point it applies a resource, so the record says what\nhappened rather than what was intended. Nothing probes.\n\nProcess names come from one shared constant naming `archied`, `archie-gateway`\nand `archie-messaging`. A deployment runs at most one of each. Writer and\nreader are bound to that constant by test, because a drifted name is\nindistinguishable from a process that never reported.\n\n## Which processes report\n\n- `archied` and `archie-gateway` apply every restart-required kind through\n `boot.runtimeConfig`, at boot and on SIGHUP.\n- `archied` also applies the live kinds it watches, and reports each update it\n applies.\n- `archie-messaging` applies channel settings at startup and reports that kind.\n\n## What can be reported, and what cannot\n\nA process reaches its apply point only after the State Store has answered it.\nAt startup, when the State Store is unreachable, the process exits or refuses\nto start and writes no record. A live watcher that loses its established\ncontrol-plane stream reports the connection failure against its last applied\nversion while it retries. Re-establishing the stream clears that outage record\nwithout clearing a versioned document rejection. A transport failure is not a\ndocument rejection; it reports that live delivery is unavailable.\n\nAbsence has two meanings and the UI never collapses them: no process applies\nthis kind, or a process that applies other kinds has not reported this one.\n\n## Relationship to the reload status\n\nApply status covers control-plane resource kinds. `ReloadStatus` covers the\nfile document and stays the only report for a SIGHUP that failed to resolve or\nvalidate it. Neither is derived from the other.\n\nWriting a record is best-effort. On the SIGHUP path it takes its own bounded\ncontext, separate from the budget the reload spends reading the control plane,\nand a failed write is logged rather than turned into a failed reload.\n\n## What the UI shows\n\nThe settings page shows, per resource, the stored version beside each process's\napplied version, error, and report time. A process on an older version of a\nrestart-required resource is pending a restart. A process with an error is\nfailed, with the error beside it. A process whose record is stale is unknown,\nnever current.\n\n## A record outlives the process that wrote it\n\nRecords are replaced in place, so a process that applies a version and then\nstops would otherwise leave a record asserting that version indefinitely, and\nthe settings page would show a dead process as current.\n`docs/prds/status-health-surface.md` faced the same choice and stamped the start\nof a poll pass so a wedged poller reads as stale rather than healthy.\n\nSettled: the re-stamp above. The alternatives considered were\ncarrying the instance identity generated at process start, which detects a\nrestart but not a death, and accepting the limitation with the page saying so.\n\n## Verification\n\n- A process that applies a resource writes a record carrying that version.\n- A process whose apply fails validation writes a record carrying the error and\n no new version.\n- A live watch outage is reported against the last applied version until the\n stream is re-established; re-establishment preserves any outstanLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/curator-sampler-wave1/",
|
||||
"title": "Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a *proxy*:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
|
||||
"body": "# Curator sampler wave 1: `Sampler` interface + four cheap strategies -- decision\n\n**Status:** Approved\n**Date:** 2026-09-05\n**Beads issue:** bead `archie-core-1786637500776-416-600a66e5` / GitHub #437\ncovers the embedding-backed follow-on strategy only. This PRD covers the\nprerequisite interface and the cheap strategies.\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n**Depends on:** nothing shipped (this is itself a prerequisite)\n**Blocks:** the embedding-backed surprisal strategy (GitHub #437), which\nimplements this same interface once the embeddings capability\n(`internal/domain/embedding`, this change) lands\n\n## Problem\n\nA future curator that reviews a large body of content (memories, sessions,\nskills) cannot always afford to run its agentic budget over every candidate\nevery pass. It needs to pick a bounded subset first. GitHub #437's acceptance\ncriteria requires that subset-picking to sit \"behind a `Sampler` interface\nthat wave 1 of the curator epic ships (cheap strategies: recency, random,\nall, staleness proxy)\" and that the embedding-backed strategy implement \"the\nsame interface\" later. No such interface, and none of the four cheap\nstrategies, exist anywhere in the codebase (bead 434e5bb9's closure\nwithout a linked PR was the tracker being wrong, not the code existing) --\nthis PRD is the one-page settled design for it, per this repo's Scope\nDiscipline rule.\n\n## Decision\n\nA `Sampler` is a pure, call-scoped selection function: given a fixed slice of\ncandidates and a request, it returns a subset. No lifecycle, no host access,\nno I/O for the four wave-1 strategies -- they are computation only, so they\nlive directly in `internal/domain/sampling` (a domain package, not\n`internal/infrastructure/*`) alongside the contract, the same way\n`curator/activity.go`'s pure ring buffer sits next to `curator/contract.go`\nrather than in an infrastructure package.\n\n```go\n// Package sampling is the curator sampler family: given a bounded set of\n// candidates, pick a subset to spend a curator pass's agentic budget on.\n// See docs/prds/curator-sampler-wave1.md.\npackage sampling\n\n// Candidate is one item eligible for sampling. It is deliberately narrow:\n// an opaque identifier, the timestamp the timestamp-based strategies score\n// against, and an open Metadata bag for whatever a future strategy needs\n// (e.g. the embedding-backed surprisal strategy's vector) without widening\n// this struct for every strategy that comes after wave 1.\ntype Candidate struct {\n ID string\n At time.Time\n Metadata map[string]any\n}\n\n// Request carries the knobs every strategy shares: a selection cap and a\n// deterministic seed. Both are optional -- Cap 0 means unlimited (the \"all\"\n// strategy relies on this), Seed 0 is a valid seed, not \"unset\".\ntype Request struct {\n Cap int\n Seed int64\n}\n\n// Sampler selects a subset of candidates to spend a curator pass's agentic\n// budget on. Every implementation -- the four here and the future\n// embedding-backed surprisal strategy (GitHub #437) -- must be\n// deterministic given the same candidates and Request: same inputs, same\n// output, every time. That is what makes a pass reproducible and testable,\n// and is GitHub #437's stated acceptance criterion for the strategy it\n// adds behind this same interface.\ntype Sampler interface {\n // Name identifies the strategy for logging/attribution (e.g.\n // \"recency\", \"random\", \"all\", \"staleness\", later \"surprisal\").\n Name() string\n // Sample selects from candidates per req. Implementations must not\n // mutate candidates or rely on anything but candidates and req --\n // determinism depends on that.\n Sample(ctx context.Context, candidates []Candidate, req Request) ([]Candidate, error)\n}\n```\n\n### The four wave-1 strategies\n\nAll four are `internal/domain/sampling` types constructed with `NewX(...)`,\neach implementing `Sampler`:\n\n- **`recency`** (`NewRecency()`): sorts candidates newest-`At`-first (stable\n sort, ties keep input order so output is deterministic even when two\n candidates share a timestamp), then truncates to `req.Cap` (0 = all).\n- **`staleness`** (`NewStaleness()`): the mirror of recency -- sorts oldest-\n `At`-first, then truncates to `req.Cap`. This is explicitly a _proxy_:\n \"hasn't been touched in the longest time\" using whatever timestamp the\n caller populated `Candidate.At` with (created, updated, or\n last-reviewed -- the caller's choice, not this package's), never the\n embedding-based surprisal calculation GitHub #437 owns.\n- **`all`** (`NewAll()`): no filtering. Returns candidates in input order,\n truncated to `req.Cap` (0 = every candidate). Input order is the only\n order this strategy has an opinion about, and preserving it is what makes\n it deterministic.\n- **`random`** (`NewRandom()`): a uniform-random subset, sized to\n `req.Cap` (0 = every canLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-aware-chat-navigation/",
|
||||
"title": "Dashboard-aware chat: Archie sees the page, and points the operator there",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has *open*, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is *evidence* it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: *\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"* The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
|
||||
"body": "# Dashboard-aware chat: Archie sees the page, and points the operator there\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Compound:** the \"chat available on any page\" surface work (global chat presence)\n\n## Decision\n\nMake the web chat **dashboard-aware**: the agent is told which dashboard page\nthe operator has _open_, knows what each page is for, and can **point**\nthe operator to the relevant page with a **clickable destination chip** the UI\nrenders and follows - Option B (context + navigate), not just \"tell me in text.\"\n\nThree seams, each an existing extension point, one new tool and one message field:\n\n1. **Current page, into the prompt.** The browser sends its route with every\n chat message; the gateway threads it into the system prompt's runtime-metadata\n env block. Archie always knows where the operator is looking.\n2. **Page index.** A page_index tool lists the dashboard pages and what each one\n shows, so Archie knows what to point at - the agent \"has the map\".\n3. **Navigate.** A dashboard_navigate tool returns a structured path/label; the web\n UI renders it as a clickable chip that routes the operator there. This is the\n \"plenty of resources\" the requirement named.\n\nWe deliberately keep the agent's answer honest: the chip is _evidence_ it can\nvalidly produce because dashboard_navigate is a real tool whose result is\nrendered, not a markdown link the model invents.\n\n## Why now\n\nThis is the natural next step of the \"chat on any page\" work, and the original\nrequest named it explicitly: _\"archie should be able to see what page you're on\ntoo. and point out where to go. so it needs plenty of resources.\"_ The chat\nis a full-page route with no knowledge of the rest of the dashboard; the agent\ncannot see which page the operator is on and cannot reliably direct them anywhere.\nThe critique of the chat UI already identified \"chat is not available on any page\"\nas the largest structural gap (P1). This design is the capability that makes that\ngap worth closing.\n\n## Shape of the API\n\n### Message field (gateway.go)\n\nAdd Page to Message:\n\n```go\n// Page is the dashboard route the operator is on when they sent this message\n// (e.g. \"/tasks\", \"/logs\"). Empty for non-web channels, which have no page\n// context. It is per-message, not per-session: the operator navigates freely\n// while a conversation stays open.\nPage string\n```\n\n### Web request (api_chat.go)\n\nchatMessageRequest gains Page, decoded into Message.Page in decodeChatMessage.\n\n### System prompt config (prompt.go)\n\nSystemPromptConfig gains Page; BuildSystemPrompt passes it through to the template.\nThe env block of archie.md.tpl renders the current page when set.\n\n### Page index (dashboard_tools.go, new)\n\nA package-level registry mapping route to {Label, Description}. page_index returns\nthe list so the model knows what each page shows:\n\n```go\ntype DashboardPage struct {\n\tPath string // \"/tasks\"\n\tLabel string // \"Tasks\"\n\tDescription string // \"Issues Archie picked up, and where they stand.\"\n}\n```\n\n### Navigation tool (dashboard_tools.go)\n\ndashboard_navigate validates its path against the registry and returns the resolved\npath/label. Unknown path means a clear error, not a guess. The model must call the\ntool (not invent a link) to produce a chip, so the chip is honest.\n\n### Tool wiring (turn.go)\n\nextraTools already merges TaskTools + SessionTools. Add the dashboard tools alongside\nthem, gated on the channel being the web UI. The tool list is built from the same\nregistry the prompt's page line comes from, so the agent never points at a page it\nwas not told about.\n\n### Web UI (chat-render.js, chat-tools.js)\n\nA dashboard_navigate tool call renders as a **clickable chip**: an anchor with\nhref=\"/tasks\" and the label. The chip is a\nreal link that works from any page once the chat is a global presence. The chip is\nstyled as an action, not a code line, so it visibly invites a click.\n\n### Route transfer (chat.js)\n\nEach sendMessage includes the current location.hash route as page in the stream\nrequest body, so the backend gets the operator's live position.\n\n## What we deliberately do NOT do\n\n- **No navigation from a markdown link.** The model must use dashboard_navigate; a\n bare \"click here\" is not rendered as a trusted route.\n- **No full-page route hijack from the chat.** The chip sets location.hash.\n- **No page index for non-web channels.** Telegram/discord have no dashboard.\n- **No automatic history annotation.** Page is per-message from the browser.\n- **No change to the dangerous-action approval flow.** Separately tracked.\n\n## Acceptance criteria\n\n1. Chat messages from any page carry the current page to the agent's prompt.\n2. page_index returns every dashboard page with a plain-language description.\n3. dashboard_navigate renders a clickable chip that routes to the target page.\n4. dashboard_navLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-live-state/",
|
||||
@@ -252,77 +252,83 @@
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard live state\n\n**Status:** Approved\n\n## Decision\n\nThe dashboard must not require passive **Refresh** buttons. One app-wide Pinia\nstore owns the existing `/api/stream` EventSource and translates backend events\ninto resource revision counters. Pages load their authoritative HTTP projection\non entry and re-read it when the relevant revision changes. Event payloads are\ninvalidation signals, not substitute read models.\n\nSSE remains the transport. Dashboard updates are server-to-client only, and the\nexisting stream already provides replay, reconnect, and persisted ordering; a\nWebSocket would add a second transport without adding a capability.\n\nThe first slice covers resources for which the backend already emits a truthful\nsignal:\n\n- task events invalidate the dashboard, task board, workflow statistics, and\n the matching task-run page;\n- capture events invalidate the capture list;\n- curator events invalidate curator status, and curator actions also invalidate\n the skill catalogue;\n- update reports invalidate System status;\n- opening a page always loads its resource, and reopening the SSE stream\n invalidates mounted projections after a connection loss.\n\nLogs retain their dedicated SSE tail. Local mutations continue to re-read their\nown resource after success. Configuration, channels, and catalogues that have no\nbackend change event load on route entry; future write contracts must emit an\nowner-specific event rather than introduce polling or restore a button.\n\n## Boundaries\n\nThe Pinia store owns browser connection state and invalidation only. It does not\nbecome an alternate backend cache or copy domain state into a generic global\nobject. Existing feature modules continue to own their DTOs and API reads.\n\nOperational commands are not refresh controls. Channel **Reload** remains an\nexplicit adapter lifecycle action. Authentication recovery is also not a data\nrefresh: a 401 moves the application into shared authentication state; reloading\nthe same URL cannot restore Archie's missing or rotated token and must not be\noffered as a fix.\n\n## Verification\n\n- No passive page action renders the label **Refresh** or **Retry** for a read.\n- Only one shared `/api/stream` EventSource is opened by the application.\n- Resource classification tests distinguish task, capture, curator, skill, and\n update invalidations.\n- UI tests, type checking, generated asset freshness, and `task check` pass.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-navigation-groups/",
|
||||
"title": "Dashboard navigation groups + Configuration split -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard navigation groups + Configuration split -- decision\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads issue:** `archie-core-ocfm`\n**Related:** `archie-core-gl96` (Logs absent from the nav -- subsumed here),\n`archie-core-ggqo` (Configuration's page width -- moot once it splits)\n\n## Problem\n\n`ui/src/main.jsx` declares eleven navigable routes in one flat bar. Three of\nthem (Skills, Curators, Channels) are capability-gated and hidden on the\nreference deployment, so the eight items normally visible are the best case,\nnot the worst: a composition that serves every section wraps the bar. Logs is\ndeclared but was never given a nav entry at all, reachable only from a\ndashboard link.\n\nThe labels compound it. \"Event inspector\", \"Field mappings\" and \"Playbook\nbindings\" are three long labels for three faces of one subject, and they sit\nbeside \"Dashboard\" and \"Tasks\" as though they were peers of equal weight.\n\nConfiguration is the other half. One route renders roughly ten sections --\nupdate status, work lifecycle, identity, budgets, storage, listen address,\nrepositories, models and providers, configuration sources, plus the operator\ncards rehomed in `archie-core-tf20` -- in a 4021px page with no in-page\nnavigation. There is no way to send someone to Repositories.\n\n## Decision\n\nFive top-level nav items. Dashboard is a link; the rest are dropdowns.\n\n| Group | Items |\n|---|---|\n| Dashboard | (link, `/`) |\n| Work | Tasks, Workflows |\n| Agent | Skills, Curators |\n| Events | Inspector, Mappings, Bindings |\n| System | Status, Logs, Appearance; **Settings:** Task settings, Models, Repositories, Channels, Advanced |\n\nItems are renamed because the group now carries the context: \"Event inspector\"\nbecomes \"Inspector\" under Events, and so on. A group renders only if at least\none of its children survives capability gating, and a group left with one\nchild still renders as a dropdown -- a bar whose shape changes per deployment\nis harder to learn than one with a predictable skeleton.\n\nThe System dropdown has two narratives. Status, Logs and Appearance describe\nthe running dashboard and sit first. A separator and visible **Settings** label\nintroduce Task settings, Models, Repositories, Channels and Advanced; those are\nconfiguration destinations, not awkward phrases such as \"System Models\" or\n\"System Advanced\".\n\n### Route map\n\nConfiguration dissolves into real routes. Anchors into one long page were\nrejected: they leave the 4021px page intact and a deep link lands the reader\nmid-scroll with no context above it.\n\n| Was | Becomes | Content |\n|---|---|---|\n| `/settings` | `/system/status` | Update status, configuration sources, daemon listen address |\n| -- | `/system/appearance` | Theme, and the density/motion preferences that follow it |\n| `/settings` | `/system/tasks` | Work lifecycle: statuses, operator actions, budgets |\n| `/settings` | `/system/models` | Model roles, providers |\n| `/settings` | `/system/repos` | Repositories and their per-repo gate overrides |\n| `/settings` | `/system/advanced` | Identity, storage and sandboxing, dangerous actions |\n| `/captures` | `/captures` | unchanged; label becomes \"Inspector\" |\n| `/mappings` | `/mappings` | unchanged; label becomes \"Mappings\" |\n| `/bindings` | `/bindings` | unchanged; label becomes \"Bindings\" |\n\n`/settings` is kept as a permanent redirect to `/system/status`. It is the URL\nin existing bookmarks, in `dashboardPages` (`internal/gateway/dashboard_tools.go`,\nwhich the chat agent navigates by), and in prior conversation history; breaking\nit to save one route entry is not a trade worth making.\n\n`dashboardPages` gains the new routes in the same change. That registry is\nguarded by `TestDashboardPagesRegistryCoversEveryRoute`, so a route added here\nand forgotten there fails the build -- which is how the deleted `/chat` entry\nwas caught.\n\n### Dropdown behaviour\n\nEach item carries a one-line description shown as a hover tooltip, using\nshadcn-vue's `Tooltip` rather than the `title` attribute, so it is keyboard\nreachable on focus and styled with the rest of the menu. Touch gets no tooltip,\nso no item may depend on one to be identifiable.\n\nThe menu is shadcn-vue's `DropdownMenu` (Reka UI underneath), which already\nsupplies the roving focus, ArrowDown/ArrowUp movement, Escape-closes-and-\nrestores-focus, and outside-pointerdown behaviour this would otherwise hand-\nroll. It opens on click, never on hover -- hover-opened menus on a control\nplane are a misclick away from a destructive page. The trigger keeps\n`aria-current` styling when any of its children is the active route, so the bar\nstill says where you are.\n\nThis section was written against the Preact dashboard; the decisions above\nsurvive the Vue migration unchanged, only the primitive supplying them\nchanged.\n\n### Scope boundaries\n\n- The daemon-backed configuration pages move sections between rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-port-brief/",
|
||||
"title": "Dashboard port: what the agent delivers",
|
||||
"section": "PRDs",
|
||||
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item),\n`docs/prds/dashboard-navigation-groups.md` (the approved nav design)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
|
||||
"body": "# Dashboard port: what the agent delivers\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)\n**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item)\n\nThis is the standard the port is held to. The checklist says what to port; this\nsays how, and what counts as done. It exists because the first attempt ported\nthe flat topbar verbatim and invented a palette, both of which had already been\ndecided elsewhere.\n\n## The deliverable\n\nThe Preact dashboard, rebuilt in Vue 3 with shadcn-vue, feature complete\nagainst the checklist, gate clean, with `ui/dist` rebuilt and committed in the\nsame commit as the source it was built from.\n\n## Non-negotiables\n\n- **Vue 3 + shadcn-vue (Reka UI, Tailwind v4, Lucide).** A component that\n exists in shadcn-vue is not hand-rolled. Add it with the CLI\n (`npx shadcn-vue@latest add \u003cname\u003e`), do not paste it in.\n- **History routing.** `createWebHistory`, `base: \"/\"`. No hash routing.\n `src/legacy-hash-redirect.ts` handles old `#/path` links and stays.\n- **No test port.** 43 Preact test files are deliberately dropped.\n `task test:ui` is a `vue-tsc` typecheck. Write a test when there is a real\n failure to pin, not to re-assert a port.\n- **Do not downgrade TypeScript.** The target is TS 7 native, not TS 5.\n- **`ui/dist` is law.** Never hand-edit it, never omit it, never revert it.\n- **`task check` is the gate.** Not an assembled substitute for it.\n- **Beads, not markdown TODOs**, for anything that outlives the change.\n- **Conventional commits**, scoped `feat(webui):`. Commit gate-clean work\n without asking. Do not push without being told.\n\n## Componentisation\n\nOne component, one job, one file. A surface is composed from named components,\nnot assembled inside a single large file. The topbar is the worked example and\nthe required shape:\n\n```\ncomponents/topbar/\n Topbar.vue composes the header, owns nothing else\n Brand.vue Logo + BrandName, links to /\n Logo.vue\n BrandName.vue\n Nav.vue reads the nav model, renders links and groups\n NavTrigger.vue the shared top-level control, link or dropdown trigger\n NavGroup.vue one dropdown\n NavItem.vue one item inside a dropdown, with its tooltip\n SearchBar.vue\n SupportLink.vue\n ThemeToggle.vue\n ProfileDropdown.vue\n```\n\nThe same rule applies to every page ported after it. If a file is doing the\nwork of four named things, it is four files. Data and behaviour that more than\none component needs lives in `src/lib/`, not passed down through a chain of\nprops.\n\n## Ordering\n\nBuild the navigation restructure during the port, not after it. Porting the\nflat eleven-item bar first and restructuring later means writing the topbar\ntwice and touching the Go route registry twice. The approved design is five\ntop-level items (Dashboard, Work, Agent, Events, System), items renamed because\ntheir group carries the context, per-item descriptions shown as hover tooltips,\nConfiguration split into `/system/*`, `/settings` kept as a redirect, and Logs\nfinally given a nav entry.\n\n## Design authority\n\n- The approved documents win. Where a document decides something, implement it\n rather than re-deciding it.\n- **Do not invent a visual direction.** Palette, typography and density are the\n maintainer's call. A palette change is its own request, never a side effect\n of a port.\n- Contrast is AA against every surface the foreground lands on, hover states\n included. The corrected values (`--fg-subtle`, the dark\n `--primary-foreground`) came from a measured failure and must survive.\n- `color-scheme` follows the theme so the UA paints controls, scrollbars and\n overscroll to match.\n\n## Code style\n\nComment the non-obvious why: an invariant, a trap, a measurement, a contract\nanother file depends on. Do not narrate what the code plainly does, do not\nexplain a choice that was never in question, and do not write migration phase\nhistory into a diff. That history belongs in the commit message.\n\n## Done, per surface\n\n1. Renders with real data against `task dev`, not just typechecks.\n2. Keyboard reachable, focus visible, and the nav announces where you are.\n3. Works at 1440x900 and at 720px wide, with nothing clipped and no horizontal\n page scroll.\n4. Empty, loading, failed and unconfigured (501) states all say something true.\n A section that cannot load says so; it does not render blank.\n5. `task check` passes, `ui/dist` rebuilt, committed together.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dashboard-vocabulary/",
|
||||
"title": "One source for the dashboard's server vocabularies",
|
||||
"section": "PRDs",
|
||||
"body": "# One source for the dashboard's server vocabularies\n\n**Status:** Finalised\n\n## Problem\n\nThe dashboard kept its own copies of two vocabularies the daemon owns:\n\n- the changed-file statuses (`added`, `modified`, `deleted`, `renamed`,\n `typechange`), which are the `Change*` constants in\n `internal/domain/workflow/task`;\n- the schema stamp on a `config_captured` payload, `events.ConfigCapturedSchema`.\n\nNothing derived one side from the other, while `/api/task-meta` already served\nthe status and action vocabularies for exactly this reason.\n\n## Decision\n\n`GET /api/task-meta` also serves `change_statuses` (id and label) and\n`config_schema`. `buildTaskMeta` in `internal/webui/api_task_meta.go` takes the\nids from the `Change*` constants and the stamp from `events.ConfigCapturedSchema`.\n\nThe dashboard renders `ui/src/lib/task-meta-snapshot.ts` until the served\ncatalogue arrives, or when archied is unreachable. `loadTaskMeta` replaces only\nthe keys the payload carries, so a server without the new keys leaves the\nsnapshot in place. `changeStatusLabel` and `configSchema` in\n`ui/src/lib/task-meta.ts` are the only readers; an unknown status renders as\nits id.\n\n## Verification\n\n- `TestTaskMetaPayloadMatchesFixture` requires the handler to serve\n `internal/webui/testdata/task_meta.json` byte for byte. Regenerate it with\n `go test ./internal/webui -run TestTaskMetaPayloadMatchesFixture -update`.\n- `ui/test/task-meta-snapshot.test.ts` requires the snapshot to equal that\n fixture.\n- `TestTaskMetaChangeStatusesAreDeliberate` fails when a `Change*` constant is\n added without a label.\n\nA rename on one side therefore fails a test on the other.\n\n## Rejected\n\nDeleting `/api/task-meta` and accepting hand-copied constants. The endpoint is\nlive, and deleting it would still leave the two copies this document removes.\n"
|
||||
"body": "# One source for the dashboard's server vocabularies\n\n**Status:** Finalised\n\n## Problem\n\nThe dashboard kept its own copies of two vocabularies the daemon owns:\n\n- the changed-file statuses (`added`, `modified`, `deleted`, `renamed`,\n `typechange`), which are the `Change*` constants in\n `internal/domain/workflow/task`;\n- the schema stamp on a `config_captured` payload, `events.ConfigCapturedSchema`.\n\nNothing derived one side from the other, while `/api/task-meta` already served\nthe status and action vocabularies for exactly this reason.\n\n## Decision\n\n`GET /api/task-meta` also serves `change_statuses` (id and label) and\n`config_schema`. `buildTaskMeta` in `internal/webui/api_task_meta.go` takes the\nids from the `Change*` constants and the stamp from `events.ConfigCapturedSchema`.\n\nThe dashboard renders `ui/src/lib/task-meta-snapshot.ts` until the served\ncatalogue arrives, or when archied is unreachable. `loadTaskMeta` replaces only\nthe keys the payload carries, so a server without the new keys leaves the\nsnapshot in place. `changeStatusLabel` and `configSchema` in\n`ui/src/lib/task-meta.ts` are the only readers; an unknown status renders as\nits id.\n\n## Verification\n\n- `TestTaskMetaChangeStatusesAreDeliberate` fails when a `Change*` constant is\n added without a label.\n\nA rename on one side therefore fails a test on the other.\n\n## Rejected\n\nDeleting `/api/task-meta` and accepting hand-copied constants. The endpoint is\nlive, and deleting it would still leave the two copies this document removes.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/deep-research-capability/",
|
||||
"title": "Deep research capability — design",
|
||||
"section": "PRDs",
|
||||
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs *one* mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** | `internal/agentexec/toolset.go` `ToolLimits{MaxResultChars,SpillDir}`, applied in `toolExecute` via `tools.CapPayload` (`limit.go`); no **aggregate** turn cap by design (`toolset.go`). `config.ToolPolicy.SpillDir`; default cap 50k chars, spill dir deliberately not defaulted |\n| Tool guardrails (repeat-failure / no-progress) | **Implemented, not on the call path** | `internal/tools/guardrail.go` engine exists. Its only non-test caller is `dispatchOne` — which is itself unreachable — so **the chat path never consults it**, and the agent path only records per *stage* (`domain/workflow/agent.go`) |\n| Structured capture tools (model reports into a typed store, not prose) | **Implemented** | `internal/app/agentworker/review.go` `record_finding` / `record_checked` — `core.NewTypedTool` appending to a caller-owned slice. This is the pattern a research source ledger should reuse |\n| Curator engine (interval, declared tool set, lifecycle) | **Implemented, tools broken** | `internal/domain/curator`; a curator declaring tools is **refused** at registration (`registry.go`, no `ToolBuilder` implementation) and `curatorLLMRunner` (`internal/app/archied/main.go`) drops `ChatRequest.Tools`. Budgets are time+concurrency only (`runtime.go`) — **no token budget** |\n| Cron / scheduling + delivery router | **Implemented, wired into the daemon** | `internal/domain/scheduling` (ticker engine), `internal/infrastructure/cronstore` (schema v2, `Kind` discriminator), and `internal/infrastructure/crondelivery`; `internal/app/archied/scheduling.go` composes them and `main.go` starts the engine. |\n| Workflow engines (multi-stage, resumable) | **Implemented, worktree-bound** | `internal/domain/workflow` — every non-triage workflow opens with `StagePrepareWorktree()` and mounts `tc.Dir` into a container; the task persists after every stage (`workflow.go`). `triage.go` documents there is \"no cheaper directory-less classification primitive\" |\n| Long-running chat-initiated work with progress | **Partial** | Chat turns run **once, synchronously**, inline in the channel's turn runner (`internal/gateway/turn.go`). Chat can spawn a *workflow task* (`task_spawn`) which is asynchronous — but that path is worktree/PR-shaped |\n| **Operator-push delivery of an async result** | **Aspirational — zero code** | Nothing pushes a finished result to a chat. No channel subscribes to the event bus (Telegram only *publishes* `KindTurnCompleted`); `crondelivery.Courier` is the intended seam but has **no implementation and no caller**; `send_file` works only inside the live turn. The one out-of-band notification in the tree is feasibility's n8n webhook (`feasibility.go`) |\n| Citation storage / sourLine truncated
|
||||
"body": "# Deep research capability — design\n\n**Status:** Draft\n**Date:** 2026-09-14\n**Scope:** A deep-research capability in archie-core: an orchestrator that\nspawns 1..N subagents to explore and research in parallel, collates their\nfindings, and returns one cited report. Grounded in web search and web fetch.\n**Beads issue:** none yet (this document is the input to it)\n**Depends on:** nothing shipped for slice 1; slice 2 depends on slice 1.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| ---------------------------------------------------------------------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `web_fetch` tool (URL → readable text) | **Implemented** | `internal/tools/webfetch/{tool.go,webfetch.go}`; registered in `internal/app/archied/bootstrap.go` `registerStandaloneTools`, disabled-by-config returns `nil` |\n| **Web search** (query → result list) | **Aspirational — zero code** | No search provider, no search tool, no config block anywhere in the tree or in `ai-sdk` v0.1.32 |\n| `agent.Subagent` — nested agent in a fresh context window | **Implemented** (dependency) | `github.com/samcharles93/ai-sdk@v0.1.32/agent/subagent.go`. Synchronous, non-streaming, own model/system/toolset, `MaxSteps` defaults to 10, nesting depth capped at 5, returns final text only |\n| Subagent used in production | **Implemented, one consumer** | `internal/app/agentworker/review.go` — the adversarial reviewer. That is the only non-test use of `Subagent` in the repo |\n| A **delegate/subagent tool** on the chat surface | **Aspirational — zero code** | No `subagent`/`delegate` tool name is registered anywhere |\n| **Fan-out orchestration** (N missions, one collator) | **Aspirational — zero code** | `agentloop`'s package doc states it runs _one_ mission: \"orchestration across missions lives with the caller\". No caller does this yet |\n| Parallel-safe tool execution | **Aspirational — zero code** | The unreachable `internal/tools/dispatch.go` dispatch/gating engine (`ExecutionClass`, `DispatchSequential`/`DispatchConcurrent`/`ClassifyEntry`) was deleted as dead code (tools-core-1); live concurrency is ai-sdk's `GenerateOptions.MaxParallelToolCalls`, which archie-core never sets |\n| Per-result caps + spill-to-disk | **Implemented** Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dynamic-curators/",
|
||||
"title": "Dynamically-defined curators -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n|---|---|---|\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `internal/config/config.go` |\n| Store/API as definition authority | **Aspirational -- zero code** | No curator persistence of any kind |\n| No live-path defaults for interval/cooldown/tools/model/memory engine | **Partial** | `skillcurator.DefaultInterval` / `sessioncurator.DefaultInterval` are Go consts read at registration; `curator.NewRuntime(..., RuntimeConfig{})` uses code defaults for pass timeout and concurrency |\n| Idle curators are observable in logs | **Partial** | `runtime.go` logs nothing when `Check` reports not-due; the session-memory curator's hourly pass is the only curator activity ever logged |\n| Sampler family | **Implemented** | `internal/domain/sampling`, shipped; no curator consumes a `Sampler` yet |\n| Forge/issue reach from chat | **Implemented** (via `shell`) | No dedicated issue tool exists, but the chat agent's `shell` is unconfined (`chat.unrestricted_filesystem = true`), so `gh issue edit|comment|create|close` works. Dedicated tools (#161) are convenience, not a blocker |\n\n\u003e **Target state, not current state.** Everything below marked aspirational is\n\u003e design, not a description of the daemon as it runs.\n\n## Problem\n\nA curator exists only if a Go package implements `curator.CuratorEngine`\nand `bootstrap.go/1025` names it in a `Register` call. Nothing about a\ncurator is definable as data. Worse, no curator can declare a tool set at all:\nthe `ToolBuilder` interface has no implementation in the repo, so the registry\nrefuses (correctly, fail-closed) any curator that declares tools -- and the\ndaemon's model adapter drops the tools even if it were bound. The curator family\ntherefore has exactly one shape (cheap, tool-less maintenance pass) and its only\nextension point is compiling Go.\n\nSam's requirement is the opposite: *\"Curators should be dynamically created and\ndefined, in addition to being able to be defined in code/config/webui\"* and *\"No\nconfiguration should ever be hard-coded.\"* The motivating consumer is a\nproject/orchestrator curator -- declared as data, given forge issue tools, and\npointed at a repo to review, refine, and propose issues.\n\n## Decision\n\n**A curator definition is data: a persisted entity whose declared shape is\nexactly `curator.Manifest` plus identity, free-form instructions, and an enabled\nflag. One generic engine interprets any definition.** The shape is not a second\ninvention -- `MLine truncated
|
||||
"body": "# Dynamically-defined curators -- decision\n\n**Status:** Approved\n**Date:** 2026-09-12\n**GitHub epic:** [#789](https://github.com/samcharles93/archie-core/issues/789)\n**Parent epic (curator engine):** [#435](https://github.com/samcharles93/archie-core/issues/435) (closed)\n**Depends on:** nothing shipping; this resolves the open question that epic #435's\n\"registered and configured declaratively, not hardcoded\" criterion left open.\n\n## §0 Implementation status\n\nEvery claim in this document is mapped to what exists in the tree.\n\n| Claim | Status | Where it stands |\n| --------------------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| Curator engine family: typed contract, owning registry, start/health/stop, narrow host access | **Implemented** | `internal/domain/curator/{contract,registry,runtime,registrar,activity,wake}.go` |\n| Curator declared shape (`Manifest`: interval, cooldown, on_input, tools, skills, memory engine, conversations, model) | **Implemented** | `internal/domain/curator/contract.go`; `Validate()` requires `Interval \u003e 0` |\n| Two reference curators run through the registry | **Implemented** | `internal/infrastructure/skillcurator`, `internal/infrastructure/sessioncurator` |\n| Curator definitions as persisted, API-editable data | **Aspirational -- zero code** | No table, no entity, no RPC, no config block |\n| Generic definition-driven engine that executes a declared tool set + free-form instructions | **Aspirational -- zero code** | Only the two code-registered curators exist |\n| `Registrar.Tools` (`ToolBuilder`) resolved and bound at registration | **Partial** | Interface declared (`registrar.go`); **no implementation anywhere**; `bootstrap.go` builds the `Registrar` with no `Tools` field |\n| A curator can declare tools at all | **Partial** | `Manifest.Tools` exists, but `registry.go` fails registration with `\"curator manifest: declares tools but the registrar has no ToolBuilder\"` |\n| Curator passes that actually reach a model with tools | **Cosmetic only** | `curator.ChatRequest` carries `Tools`/`MaxSteps`; `curatorLLMRunner` (`internal/app/archied/main.go`) drops both and returns `ChatResult{Text}` only |\n| Dynamic registration / removal (no restart) | **Aspirational -- zero code** | `Registry` has `Register`, no `Unregister`; `Runtime` has `Start`/`Nudge`/`Stop`, no `Add`/`Remove`; `Start()` snapshots membership |\n| Curator definition CRUD over REST | **Partial** | `GET /api/curators` read-only (`internal/webui/server.go`); no write routes |\n| Curator definition config | **Aspirational -- zero code** | No `[curator]` block in `intLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/dynamic-workflow-triage/",
|
||||
"title": "Dynamic workflow triage",
|
||||
"section": "PRDs",
|
||||
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabelled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: *\"workflow: … Omit to let the\ndaemon route it\"* (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output *correctly* concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labelled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognised) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be *directionally* right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `rLine truncated
|
||||
"body": "# Dynamic workflow triage\n\n**Status:** Finalised\n\nEpic: archie-core-enfj. Scope: give `workflow.Route()` a real, content-aware\nfallback instead of unconditionally defaulting every unlabelled task to the\nheaviest workflow.\n\n## Problem\n\n`Route()` (`internal/domain/workflow/workflow.go`) has exactly two real\nsignals: an explicit `t.Workflow`, and label matches via\n`workflowForLabels` (`routing.go`, `bug`→tdd, `feature`→feasibility,\nbootstrap→bootstrap). Anything else — which is every chat-spawned task,\nsince `task_spawn` rarely sets labels — falls straight through to\n`reg[\"implement\"]`, the full `prepare → baseline → plan → build →\ncommit-push → review → open-pr` pipeline, regardless of what the task\nactually asks for.\n\n`task_spawn`'s own tool schema overpromises: _\"workflow: … Omit to let the\ndaemon route it\"_ (`internal/gateway/task_tools.go`) implies real\nrouting exists. It doesn't — \"route\" means \"check labels, then\ngive up and run the heaviest workflow anyway.\"\n\nConfirmed in production: a chat-spawned task whose\nentire content was \"this is just a test, close it when you receive it\" ran\nthe full `implement` pipeline end to end — 669,421 tokens, ~7 minutes —\nwhen nothing about the request needed a worktree-driven build at all. The\n`plan` stage's own LLM output _correctly_ concluded no code change was\nneeded, but that conclusion arrives two expensive stages (`baseline`,\n`plan`) too late to save anything.\n\n## Decision\n\nAdd a **`triage` workflow**: cheap, classifies once, then either closes the\ntask immediately or hands off to the workflow the task actually needs.\n`Route()`'s final fallback (`reg[\"implement\"]`) becomes\n`reg[\"triage\"]` when a `triage` entry is registered, else the existing\n`implement` fallback — a two-line change, fully backward compatible when\n`triage` isn't wired up.\n\nTriage does **not** replace label-based routing. A labelled task\n(`bug`/`feature`/bootstrap) already has a free, reliable signal and goes\nstraight to its known workflow unchanged — spending a classification\ncall there would be pure waste. Triage only fires in the gap that\ndefaults to `implement` blindly: no explicit workflow, no label match.\n\n### Triage workflow shape\n\n```\nStagePrepareWorktree() -- still needed: AgentStage mounts tc.Dir into the\n agent container: internal/domain/workflow/agent.go:74\n passes tc.Dir straight through. No cheaper\n primitive exists in this codebase for a\n directory-less classification call.\nAgentStage \"classify\" -- ReadOnly, ONE cheap agent turn, no exploration\n tools required beyond what ReadOnly already\n grants. Mirrors feasibility.go's decideCaptureTools\n pattern: a structured capture tool, called\n exactly once, MaxCalls: 1.\n```\n\nMission: read the task's title/body/labels (already in `taskPromptBlock`)\nand decide, via a captured `decide` tool call:\n\n```json\n{\"needs_code_change\": bool, \"workflow\": \"implement\" | \"tdd\" | \"feasibility\", \"reasons\": \"...\"}\n```\n\n`needs_code_change: false` → close path: reuse `closeNoChangesIssue`\n(`steps.go`) directly — issue closed if forge-backed, task marked\n`StatusMerged`/`\"completed -- no changes required\"` otherwise. No baseline,\nno plan, no build, no commit, no PR. This is the actual fix for the\nproduction incident: a no-op request now costs one classification call\n(low thousands of tokens) instead of 669,421.\n\n`needs_code_change: true` → sets `tc.Task.Workflow` to the classifier's\nchosen workflow (`implement`/`tdd`/`feasibility`, defaulting to\n`implement` if the field is missing or unrecognised) and an Outcome that\nrequeues the task under it, the same requeue mechanism\n`chatTaskControllerAdapter.ApproveChatTask` already uses\n(`main.go`, `requeue(ctx, taskID, fromStatus, workflow)`). The task then\nre-enters `Route()` on its next claim with `t.Workflow` now set, and takes\nthe normal path for that workflow from there — triage never runs its\nclassification twice for the same task.\n\n### Non-goals (v1)\n\n- Full bug/feature intent classification quality — the classifier only\n needs to be _directionally_ right; a wrong `tdd` vs `implement` call\n still produces a working PR, just via a slightly less-tailored pipeline.\n Tightening this is a follow-up, not a blocker.\n- Any change to label-based routing, `Route()`'s explicit-workflow branch,\n or `Bootstrap()`/`Feasibility()`/`TDD()` themselves.\n- Triage for forge-sourced (real GitHub issue) tasks with no labels —\n in scope structurally (same fallback branch), but the dominant case this\n fixes is chat-spawned tasks, which essentially never carry labels.\n\n## Testing\n\n- `workflow_test.go`: `Route()` picks `rLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/eda-playbook-engine/",
|
||||
"title": "EDA playbook engine -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one *named* built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalises its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalogue, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends througLine truncated
|
||||
"body": "# EDA playbook engine -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Beads epic:** `archie-core-t2db`\n\n## Problem\n\n\"Which workflow runs for which trigger\" is hardcoded Go: a literal\nlabel vocabulary (`workintake.labelKinds`) and a literal label-\u003eworkflow map\n(`workflow/routing.go`), extended only by adding a Go case or shipping a\nskill whose `metadata.archie.workflow` overrides one _named_ built-in\nworkflow. Extending the system to a new trigger, a new action, or a new\nevent source means a feature branch, a code change in a hardcoded\npath, and new Go tests -- for every addition. That is the barrier this\ndocument exists to remove.\n\nThe goal: triggers, the actions they run, and the\nconditions that connect them should be **drop-in and load**, not **drop-in\nand touch application code**. Yaegi-evaluated Go is the unit of imperative\n\"do a thing\" logic; YAML playbooks are pure orchestration data -- no logic,\njust \"on this event, with this data, call these actions, in this order,\nunder these conditions.\" The daemon's event coordinator doesn't know what a\n`bugfix` or `image-gen` action does, it resolves the name against a\nregistry and pipes typed data through.\n\nThis is explicitly **not** scoped to code-generation workflows. A playbook\naction can be any registered capability -- run a codegen workflow, send a\nmessage on a channel, open something on a forge, generate an image -- so\nlong as it's implemented behind one of the typed engine families below.\n\n## Relationship to existing decisions\n\n- `docs/prds/event-sources-and-reactions.md` ruled\n that reactions in the two epics it covers are **producer-only** (no veto,\n no mutation of in-flight work) and explicitly rejected a single generic\n `Source` interface as \"the untyped-hook shape the plugin engine rule\n exists to prevent.\" **This document extends that scope**: playbooks can\n dispatch to multiple typed action kinds, not just \"produce a\n `TaskEnvelope`.\" It does not relitigate producer-only-ness (still no\n veto/mutation of in-flight work here) and it does not introduce one\n generic interface -- see \"Typed positions, not one generic hook\" below,\n which is how it stays compliant with the plugin engine rule instead of\n reopening that document's #4.\n- `docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`\n governs every extension point\n introduced here. Every position below is a typed domain contract with an\n owning registry, not a generic callback map. This is a hard constraint,\n confirmed against the existing rule text before writing this doc.\n- Yaegi is already a proven in-process extension mechanism\n (`internal/plugin`, `internal/domain/workflow/wfeval/yaegi.go`,\n `internal/gate/gateeval/yaegi.go`, `internal/skill/plugin.go`) -- this\n design generalises its existing role, it does not introduce a new\n execution mechanism.\n- `internal/domain/workflow/skillbuild.BuildRegistry` already composes a\n `workflow.Registry` from a skills catalogue, plugin-defined overriding\n built-in. The playbook loader described here supersedes label routing\n specifically; it does not replace `skillbuild`'s workflow-composition role,\n it becomes an additional input the daemon composes at startup.\n- Webhook event intake is a separate design. This\n document defines the router each webhook-sourced event should be able to\n reach; it does not redesign webhook receipt itself.\n\n## Shape: four logic positions, each a typed engine family\n\nEvery entrypoint kind (mechanism, action, loop, schedule, route, trigger) is itself a schema emitter: defining a new kind produces the\ngenerated contract downstream tooling consumes. The kinds slot into a fixed\nhierarchy of logic positions:\n\n```\nWorkflow -\u003e Module -\u003e Channel (telegram/whatsapp/email/...)\n -\u003e Forge (GitHub/Gitea/GitLab/...)\n```\n\nEach position is its own typed engine family per the plugin engine rule:\nidentity + capability-specific operations, an owning `Registry`/`Manager`,\nexplicit lifecycle where the implementation owns resources, narrow host\naccess. Concretely:\n\n- **Workflow** -- already exists (`internal/domain/workflow`). A playbook\n action of kind `workflow` invokes a registered `workflow.Registry` entry\n by name, unchanged from the existing execution path.\n- **Module** -- the new general-purpose action position. A `Module` is a\n Yaegi-evaluated implementation of a generated interface (args in, typed\n result out) for one declared action kind (e.g. `image-gen`, `notify`,\n `open-pr-comment`). This is the position that makes actions \"not\n restricted to code-generation.\" Full design (schema-per-kind, the\n registry shape, the trust boundary, the recommended first slice):\n `docs/prds/module-position.md`.\n- **Channel** -- already exists as `channels.Channel` (telegram, email,\n webhook). A playbook action of kind `channel` sends througLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/embedded-nats/",
|
||||
"title": "Embedded NATS execution -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| --- | --- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
|
||||
"body": "# Embedded NATS execution -- decision\n\n**Status:** Finalised\n\n**Date:** 2026-08-24\n\n**Beads epic:** `archie-core-q15y`\n\nThis decision supersedes the position that embedded NATS was only a\ndistribution mechanism and could not be an agent-execution topology. That was\ntrue only because the embedded listener was unauthenticated loopback. It left a\nsecond production architecture in which `archied` ran autonomous workflows in\nits own process, weakening the isolation boundary that managed task containers\nexist to provide.\n\n## One execution architecture, two broker deployments\n\nEvery autonomous repository workflow is handed over as one complete task via\nNATS and runs in a task-scoped `archie-agent` container. `archied` remains a\nnative, long-lived orchestration and interactive-chat process; its operator\nconfigured host filesystem access is unchanged. It owns task admission,\nstate, forge and worktree operations, container lifecycle, and the broker when\nthe embedded deployment is selected. It does not run an autonomous model loop.\n\nNATS has two supported deployment shapes:\n\n| mode | meaning |\n| ---------- | --------------------------------------------------------- |\n| `embedded` | `archied` owns an in-process JetStream server (default). |\n| `external` | `archied` and workers connect to the configured NATS URL. |\n\nBoth shapes have identical task semantics: one container and one full-task\nrequest per workflow. Broker placement must not select a different executor.\nThe legacy `agent` section and `containers.enabled` key remain decode-only\nmigration inputs. `nats.mode = \"off\"`, per-stage NATS, in-process execution,\nand subprocess execution are not production choices.\n\nSQLite remains authoritative for task state. NATS is the sole autonomous work\nhandoff. SQLite recovery may identify work that needs republishing, but it must\nnot cause `archied` to call `workflow.Run` locally.\n\n## Embedded reachability and authentication\n\nAn embedded listener uses a cryptographically random bearer token generated for\neach daemon start. The token exists only in process memory and the environment\nof managed worker containers; it is never written to config or logs.\n\nFor a native daemon with managed containers, startup resolves the Docker bridge\nthe workers will join. The listener binds only to that bridge's host gateway\naddress on a random port. Both the native daemon and workers use that same\nreachable endpoint, and every client supplies the generated token. Binding a\nDocker bridge address keeps the listener off ordinary LAN interfaces without\npublishing a host port. A configured user bridge is respected; otherwise the\nDocker default bridge is used. A network without a usable local IPv4 gateway is\na startup error for autonomous execution.\n\nIf Docker is unavailable, interactive chat may still start and embedded NATS\nmay remain loopback-only, but autonomous tasks park with an explicit container\ncapability failure. They never fall back to host execution.\n\n## Ownership and lifecycle\n\n- `internal/infrastructure/eventbus/nats` owns the authenticated embedded\n server and exposes its runtime endpoint, not the server implementation.\n- `internal/container` resolves the worker bridge and gateway and owns task\n container lifecycle.\n- `internal/app` composition selects embedded or external broker deployment,\n freezes the connected runtime endpoint for worker environments, and wires the\n full-task handoff.\n- `cmd/archied` remains process input only as the domain migration reaches this\n composition path.\n\nThe daemon starts the embedded server before its client, closes clients before\nthe server, and keeps JetStream data beneath the daemon data directory. NATS URL\nand token are startup-built values: a reload cannot send new workers to a broker\ndifferent from the one the daemon is using.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/event-automation/",
|
||||
"title": "Event automation: identified events, typed parameters, purpose-built agents",
|
||||
"section": "PRDs",
|
||||
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools)\n repo) profile)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another woLine truncated
|
||||
"body": "# Event automation: identified events, typed parameters, purpose-built agents\n\n**Status:** Approved\n**Date:** 2026-09-23\n**Parent:** epic `archie-core-t2db`\n\n## Why this exists\n\nArchie is an event-driven automation system. Any system that can send a\nwebhook (a forge, an error tracker, a firewall, a monitoring stack) should be\nable to start an agent built for that job. The shape this replaces cannot:\n\n- A binding matches only the URL segment an event was posted to, and a source\n may have one binding. Two kinds of event from one sender cannot go to\n different workflows.\n- A mapping is a list of JSON paths written against one example payload.\n Nothing recognises what kind of event arrived.\n- Mapped values reach the task only as `key=value` lines in its body text.\n- Every task needs a repository and runs in a git worktree.\n- Every agent runs the same image with the same forwarded keys.\n\n## The model\n\n```\nsource ─▶ event type ─▶ mapping ─▶ binding ─▶ workflow ─▶ agent profile\n (identified) (params) (+ filter, (inputs, (image, tools)\n repo) profile)\n```\n\n### Sources\n\nA source is the endpoint one sender posts to. Its path is a generated UUIDv7\n(`/webhooks/capture/0199…`), so an endpoint cannot be guessed or collide. The\noperator may replace it with a custom path for a sender that cannot use that\nformat; a custom path must be unique and URL-safe, and is refused otherwise.\nA source owns the signing setting:\n\n- **Signed** (default). Archie generates the secret. Only events with a valid\n `X-Hub-Signature-256` or `X-Signature-256` HMAC are dispatched.\n- **Unsigned.** The operator turns signing off for a sender that cannot sign.\n The source and every event from it are marked unsigned in the inspector,\n the binding list and the task timeline. Turning signing off needs the same\n approval as arming a binding.\n\nUnauthenticated events on a signed source are captured and never\ndispatched.\n\n### Event types\n\nAn event type is a named kind of event from one source, such as\n`github / pull_request.opened` or `firewall / blocked_connection`. It is\ndefined by a match rule:\n\n- header equality (`X-GitHub-Event = pull_request`), and\n- payload conditions (`action = \"opened\"`, or a path being present).\n\nAn event type can be created two ways:\n\n- **From an example payload.** The operator pastes a payload (and optionally\n its headers), and archie converts it to the type's schema. No event needs to\n have arrived.\n- **From captures.** Archie proposes types from what has arrived, as below.\n\nEither way, archie infers the schema, not the operator:\n\n- Each capture gets a structural signature: the set of JSON paths with their\n value types, plus the headers that look like discriminators (`*-Event`,\n `*-Type`, `Content-Type`).\n- Captures from one source that share a signature are grouped. The inspector\n shows each group as a proposed event type, with its inferred schema, its\n number of events and a sample, until the operator names it or dismisses it.\n- The proposed match rule is the set of discriminators that separates the\n group from its siblings. The operator can edit it before saving.\n- A capture that matches no named type is shown as unidentified. It is never\n dispatched.\n\nTwo event types on one source whose rules can match the same event are\nrefused when the second one is saved.\n\n### Mappings\n\nA mapping belongs to an event type. It maps payload paths to named, typed\nparameters, and it is checked against the type's inferred schema, so a path\nthe type does not have is refused when the mapping is saved. Any number of\nbindings may reuse one mapping.\n\nEach mapping shows how many events it has matched, with the time of the most\nrecent, so an operator can see which mappings are live and which have never\nfired.\n\n### Workflows declare inputs\n\nA workflow definition declares its inputs:\n\n```yaml\nid: firewall-investigate\ninputs:\n src_ip: { type: string, required: true }\n severity: { type: string }\nrepository: none # none | optional | required\nprofile: network-investigator\nsteps: ...\n```\n\n- `repository: none` runs the agent in a scratch workspace with no clone.\n `required`, the default, gives the agent a worktree of the task's\n repository. `optional` gives it a worktree when the binding names a\n repository and a scratch workspace when it does not.\n- A workflow whose `repository` is not `required` may use only steps that need\n no repository. `agent.run` is one: it runs one agent mission and finishes\n the task as done, with no pull request.\n- The declared inputs reach the agent as structured data in the task brief\n and in the agent's context. They are not body text.\n- A workflow may declare `outputs`, the structured result it returns when it\n finishes.\n\n### Workflows call workflows\n\nA workflow step can call another workflow.Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/event-capture-storage/",
|
||||
"title": "Event capture storage -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n|-----------------|---------|-------------------------------------------------|\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n *Not* keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sender\n bypass the limit by rotating the segment every request (a fresh key\n always starts with a full burst) and grow the bucket map without bounLine truncated
|
||||
"body": "# Event capture storage -- decision\n\n**Status:** Finalised\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.1`\n\n`webhook-intake-security.md` decided points 1-5 (auth split, approval gate,\nrate limits, blast radius, retention/redaction) and explicitly left the\nstorage mechanism open, forward-pointing at \"`7d5u.2`, embedded NATS.\" That\npointer predates `7d5u.3`'s 2026-08-22 narrowing, which assigned capture\nstorage to this bead by name and told it to decide NATS-vs-SQLite itself\nrather than inherit an answer. This document is that decision.\n\n## Decision: SQLite, not NATS JetStream\n\nCaptured events are stored in archied's existing SQLite database, in a new\n`captured_events` table following the same shape as `internal/store/events.go`\n(`internal/store`, `*Store`, SQL migrations inline in Go). No JetStream\nstream is introduced for capture.\n\n### Why\n\n**NATS availability does not make capture a broker concern.** NATS is now\nunconditional for autonomous workflow handoff, including embedded mode, but\ncapture is also used by deployments with no repository workflow configured.\nSQLite is guaranteed present because it backs daemon state, and keeps\ncapture inspection independent of broker retention and consumer lifecycle.\nThe original version of this decision cited optional NATS as an additional\nreason; that premise was superseded by `archie-core-q15y`, while the storage\nfit and independence arguments remain.\n\n**Capture's access pattern doesn't need what JetStream is for.** JetStream\nearns its complexity for reaction delivery (`7d5u.2`) because multiple\nindependent consumers need fan-out, at-least-once redelivery, and Ack/Nak\nsemantics -- exactly the trap `CLAUDE.md` documents about `WorkQueuePolicy`\nand overlapping consumers. Capture has exactly one writer (the HTTP handler)\nand one reader (a human via the dashboard inspector, `t2db.2`). There is no\ncompeting-consumer problem to solve and no redelivery semantics to get right,\nso JetStream's core value proposition doesn't apply here. A bounded SQL\ntable is a better fit on the merits, not merely as a fallback.\n\n**Reusing `7d5u.2`'s stream, once it exists, would still be wrong.** That\nstream is provisioned for fan-out reaction delivery with its own retention\npolicy decision. Capture's retention need -- age- and count-bounded, prune\non write, no replay -- is a different shape. Building a second stream just\nfor capture, gated on an unrelated bead landing first, would trade a small\namount of duplication now for a hard dependency on `7d5u.2`'s timeline that\nthis bead's own acceptance criteria say not to accrue by accident.\n\nThis does not foreclose NATS later. If cross-daemon capture sharing or\ndurable replay becomes a real requirement, that is a new decision made\nagainst a real need, not now against a speculative one.\n\n## Storage shape\n\n`captured_events` table (`internal/store/captures.go`, mirrors\n`internal/store/events.go`'s pattern):\n\n| column | type | notes |\n| ------------- | ------- | ------------------------------------------------------------------ |\n| id | INTEGER | primary key, autoincrement |\n| received_at | TEXT | RFC3339Nano |\n| source | TEXT | opaque path segment chosen by the sender's operator |\n| remote_addr | TEXT | `RemoteAddr` at capture time |\n| content_type | TEXT | `Content-Type` header |\n| headers | TEXT | JSON, redacted |\n| body | TEXT | JSON, redacted (`webhookguard.RedactPayload`) |\n| authenticated | INTEGER | 0/1; always 0 until a source registers a secret (future: `t2db.4`) |\n\nIndexed on `(source, id)` for per-source listing and pruning, and `id` alone\nfor the global cap.\n\n## Disk-bound mechanics\n\nThree independent bounds, composed, per `webhook-intake-security.md` point 5\nand this bead's own \"capture cannot exhaust disk\" criterion:\n\n1. **Per-request size cap.** The HTTP handler reads the body through\n `http.MaxBytesReader` (256 KiB default, configurable). A single oversized\n POST is rejected (413) before redaction or storage sees it.\n2. **Per-remote-address rate limit.** `webhookguard.RateLimiter`, keyed by\n the request's remote address, applied before the body is even read.\n _Not_ keyed by the `source` path segment: `RateLimiter`'s own doc comment\n states its bucket map assumes a bounded, operator-registered key space,\n never evicted. `source` is exactly the opposite here -- an unregistered,\n attacker-chosen URL segment, since capturing senders with no registration\n yet is this endpoint's entire purpose. Keying on it would let one sendLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/event-sources-and-reactions/",
|
||||
"title": "Event sources and reactions -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterised: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an *in-flight* task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
|
||||
"body": "# Event sources and reactions -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-7d5u.1`, blocks `7d5u.2/.3/.4/.5`\n\nAnswers the four questions in `7d5u.1`'s description. Investigated against\nthe actual tree, not designed from scratch: three mechanisms already in this\ncodebase answer most of this, and the job here is picking the right one for\neach question and saying which packages change.\n\n## 1. In-process typed families, not out-of-process dispatch\n\nArchie has no out-of-process extension mechanism. The plugin engine\nrule (`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`,\nmechanically checked by\n`internal/plugin/architecture_test.go`) keeps every capability family\nin-process behind a narrow typed registrar; NATS RPC exists for\ndaemon\u003c-\u003eagentexec, a different actor with a different trust boundary (task\nexecution, not third-party extension code), not a precedent for generic\nplugin dispatch. Neither epic's near-term payoff -- react to a labelled\nissue, bind a captured webhook to a workflow -- needs extension code in\nanother language or process. Building out-of-process dispatch now would be\ndesigning for a requirement neither epic states.\n\n`docs/architecture/plugins-and-extensions.md` does **not** need amending.\nThe line that looked like a blanket ban on hooks (`archie-core-7d5u`'s notes\nrecord the correction) is scoped to Workflow semantics specifically, and\nnothing decided here touches Workflow's ownership of its own contracts.\n\n## 2. Reaction delivery: `internal/eventbus`'s contract, a NEW stream\n\n`internal/eventbus.Publisher`/`Consumer` already has everything a reaction\nneeds: `PublishUnique(subject, idempotencyKey, payload)` for at-least-once\nwithout duplicate enqueue, `Ack`/`Nak` with \"a handler returning an error\ncauses redelivery.\" Do not design new delivery semantics; use this contract.\n\n**Do not reuse the existing `nats.Client` as-is.** `Config.StreamName` and\n`Config.Subjects` are already composition-supplied (\"the bus must not know\nwhich subjects belong to which domain,\" `config.go`), but the\nretention policy is not parameterised: `New` hardcodes\n`Retention: jetstream.WorkQueuePolicy` (`client.go`), the competing-consumer\npolicy correct for `ARCHIE_TASKS` task distribution -- one message, claimed by\nexactly one consumer -- and wrong for reactions. Two independent reactions\nboth wanting to see the same event under `WorkQueuePolicy` hit exactly the\ntrap `CLAUDE.md` already documents: overlapping filter subjects on a\nwork-queue stream mean the second consumer silently gets nothing. Reactions\nneed fan-out, not claim-once, so the client needs retention made a `Config`\nfield (defaulting to `WorkQueuePolicy` so `ARCHIE_TASKS` is\nunaffected), and a second stream (`ARCHIE_REACTIONS` or similar) configured\nunder a fan-out-capable policy, alongside the existing task-distribution\nstream -- not instead of it.\n\nThis is where `7d5u.2`'s embedded-vs-external axis attaches: whichever NATS\ninstance backs `ARCHIE_TASKS` also backs the reaction stream. NATS is not\noptional as a technology -- the choice is only\nwhether it runs as an external server or embedded in-process\n(`github.com/nats-io/nats-server/v2` is already a direct, test-proven\ndependency, just never wired into production startup). `7d5u.2` wires that;\nthis document does not re-decide it.\n\n## 3. Reactions in these two epics are producer-only\n\nNo veto, no mutation of in-flight work. Two existing shapes cover everything\neither epic actually needs, and neither is a hook that can block something\nelse:\n\n- **Cheap wake, no payload.** `internal/domain/curator/wake.go`'s\n `WakeOnPrimaryInput` subscribes to the lossy `events.Bus` and nudges a\n runtime to check sooner; a dropped event only delays a check-in, never\n loses work, because the trigger decision is a deterministic state read at\n pass time, not the event payload. Model any \"check something sooner\"\n reaction on this, unchanged.\n- **Produce new work, real payload.** `daemon.go`'s existing `pollNATS` -\u003e\n `publishTask` path is already exactly a reaction that observes forge state\n and produces a `workintake.TaskEnvelope`. A webhook source is a second\n producer into the same path, not a new capability -- see question 4.\n\nA reaction that can veto or mutate an _in-flight_ task (block a PR from\nopening, alter a running stage) is a different, harder problem with its own\nordering and failure semantics, and belongs to `archie-core-h019` (adversarial\nself-review) if and when that epic needs one -- not here. Do not build a\ngeneral block-capable hook mechanism for either epic; nothing in their stated\nscope requires it, and it would duplicate whatever h019 eventually needs.\n\n## 4. No single generic intake interface; each domain keeps its own\n\nA `Source` interface generic enough to cover a forge issue, a chat message,\nand a cron tick wouldLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/execution-tree-state-machine/",
|
||||
"title": "Execution tree and enforced state machine",
|
||||
"section": "PRDs",
|
||||
"body": "# Execution tree and enforced state machine\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);\nsettles the \"enforced WorkflowExecution state machine\" item in\n`docs/architecture/migration-decisions.md` section 4.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),\n`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).\n\n## Decision\n\nA WorkflowExecution becomes the root of a tree of StepExecutions. Every stage\nrun, and every agent call a stage makes, is its own durable record with a\nparent, an attempt, a status and an outcome. Both levels move only through a\ndeclared transition table, enforced by the State Store in the same transaction\nthat writes the audit row and the domain event.\n\n## Problem\n\n- A run is one `tasks` row. The only per-step record is the mutable `stage`\n column, overwritten as `workflow.Run` advances, plus observability events.\n A failed attempt cannot say which step failed or what its children did\n without replaying the event stream.\n- `Store.Transition` guards on the expected `from` status, but any `from` to\n any `to` is accepted. A `queued` to `merged` write succeeds.\n- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says\n which work was in flight, so an agent call that outlives its stage (a\n reviewer, a container) is invisible to the store.\n- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits\n `KindStageStart` separately. State and events can diverge.\n\n## Model\n\n```text\nWorkflowExecution (tasks row, id E)\n└── attempt N\n ├── StepExecution stage \"plan\" depth 0\n ├── StepExecution stage \"implement\" depth 0\n │ └── StepExecution agent \"implement\" depth 1\n └── StepExecution stage \"review\" depth 0\n ├── StepExecution agent \"review:1\" depth 1\n └── StepExecution agent \"review:2\" depth 1\n```\n\n- A StepExecution belongs to exactly one WorkflowExecution and one attempt.\n `parent_id` is null for a stage and names the enclosing StepExecution\n otherwise. Depth is derived from the parent, never supplied by the caller.\n- `kind` is `stage`, `agent` or `call`. A new kind needs a named consumer\n before it is added.\n- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call`\n StepExecution in the caller's tree. The callee is its own\n WorkflowExecution, with its own tree, acting as its own identity, and the\n `call` step records the callee's execution ID. Trees never nest across\n executions, so each run's tree stays inside that run's authority.\n- A retry starts a new attempt. Earlier attempts' StepExecutions are never\n rewritten.\n\n## Transition tables\n\nWorkflowExecution statuses are the existing `taskstate` constants, persisted\nstrings unchanged. `taskstate` gains the one table every writer checks:\n\n| From | To |\n| --------------- | ---------------------------------------------------------- |\n| `queued` | `running`, `closed_wont_do` |\n| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |\n| `waiting_human` | `queued` (approve), `closed_wont_do` |\n| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |\n| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |\n| terminal | none |\n\nStepExecution statuses:\n\n| From | To |\n| --------- | ------------------------------------------------------ |\n| `pending` | `running`, `cancelled` |\n| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |\n| terminal | none |\n\n`interrupted` means the process running the step died or shut down. It is\ndistinct from `cancelled`, which an operator or a parent asked for, and from\n`failed`, which the step reported.\n\nA StepExecution cannot reach `running` while its WorkflowExecution is not\n`running`, and cannot start under a terminal parent.\n\n## Enforcement\n\n- The table lives in `taskstate` (no dependencies), so the store, daemon and\n gateway share one copy.\n- Every store method that changes `tasks.status` checks the table and writes\n the audit and event rows, not only `Transition`. That includes the claim,\n `ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`\n paths, several of which change status without an audit row.\n- The State Store rejects an illegal transition with a new sentinel,\n `ErrIllegalTransition`, carried across the wire through `mapError` like\n `ErrStaleTransition`. ALine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/extensions-center/",
|
||||
"title": "Extensions centre",
|
||||
"section": "PRDs",
|
||||
"body": "# Extensions centre\n\n**Status:** Draft\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions centre\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disableable\" property\nenforced structurally rathLine truncated
|
||||
"body": "# Extensions centre\n\n**Status:** Draft\n\n\u003e Superseded by `docs/prds/store.md`.\n\nEpic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` (\"Replace Skills\nwith a bundled Extensions centre\").\n\nSkills, Workflows, and Tools/MCP already exist as separate, working\ninventories with their own APIs (`api_skills.go`, `api_workflows.go`,\nconfig-driven MCP servers) and their own family-owned controller pattern\n(`curator.Registry`, `health.Registry`, `image.Registry`,\n`workflow.Registry` all already prove this shape). `plugin.Plugin`\n(`internal/plugin/plugin.go`) is already metadata-only, per\n`docs/architecture/plugins-and-extensions.md`. None of that is rebuilt here.\nWhat's missing, confirmed by grep, is: any config schema for enabling or\ndisabling a capability, any \"pending restart\" state tracking, and any single\ninventory that reconciles configured/bundled/discovered/active state across\nfamilies. This document decides those three things and the UI surface that\npresents them. It extends `plugins-and-extensions.md` rather than replacing\nit — that doc's decisions (metadata-only `Plugin`, typed capability\nfamilies, no generic dispatch) are unchanged.\n\nOut of scope: any remote or arbitrary-URL plugin installation path (the\nepic's own acceptance criteria forbid this, and `plugin.LoadDir`\n(`plugin.go`) already only reads `~/.config/archie/plugins/*.go` — this\ndocument does not add a fetch-by-URL variant to it).\n\n## Problem\n\n`internal/config/config.go`'s `MCPServer` and `ToolsConfig` structs have no\n`enabled` field (confirmed by the investigation grep). `api_config.go`'s\n`UpdateConfig`/`handleConfigUpdate` seam persists changes but has no state\ndistinguishing \"saved, takes effect now\" from \"saved, needs restart\" — the\nonly existing reload path (`ReloadChannel`, `server.go`) is\nchannel-specific and explicitly does not cover plugins or MCP servers.\n`server.go` already wires five separate optional inventories\n(Workflows, Skills, Curators, Channels, Captures/Mappings/Bindings) as\nindependent fields with no unifying type — an operator has no single\nplace to see \"what's available, what's enabled, what's actually running,\nand what's degraded\" across all of them. `ui/src/` has `settings/`,\n`skills/`, and `workflows/` directories already; there is no\n`ui/src/extensions/`.\n\n## Design\n\n### Unified inventory type\n\n```go\npackage extensions // internal/domain/extensions — new, app-level aggregator\n\ntype State string\n\nconst (\n StateAvailable State = \"available\" // bundled, not configured\n StateEnabled State = \"enabled\" // configured on, not yet live\n StateActive State = \"active\" // configured on and running\n StateDegraded State = \"degraded\" // active but unhealthy\n StateSkipped State = \"skipped\" // optional, disabled by config\n StatePendingRestart State = \"pending_restart\" // config changed, not yet live\n)\n\ntype Entry struct {\n Family string // \"skill\" | \"workflow\" | \"tool\" | \"plugin\" | \"integration\"\n Name string\n Core bool // non-disableable\n State State\n Health string // reuses whatever the family's own registry already reports\n}\n\ntype Inventory interface {\n List(ctx context.Context) ([]Entry, error)\n}\n```\n\n**Decision.** `extensions.Inventory` is a read-only aggregator, not a new\ndomain that owns state. It queries each family's existing registry\n(`curator.Registry`, `health.Registry`, `workflow.Registry`, the MCP client\nset, `plugin.LoadDir`'s result) for live state, and compares that against\nthe config-desired state (below) to compute `StatePendingRestart` — the diff\nis computed on read, not persisted, so there is no new durable state to keep\nconsistent with the registries themselves. This follows\n`migration-decisions.md`'s rule that cross-cutting aggregation composes\nexisting domain-owned contracts rather than duplicating their state.\n\n**Call site.** New package `internal/domain/extensions/inventory.go`.\nComposed in `internal/app/archied` (wherever `server.go`'s other optional\nfields — Workflows, Skills, Curators — are wired) since it needs\nreferences to every family's registry, which only application-layer\ncomposition has.\n\n### Config-backed enablement\n\n**Decision.** Add `enabled bool` (default `true` for pre-existing configured\nentries, so no upgrade silently disables anything already configured) to\neach family's config element: `MCPServer.Enabled`, and equivalent fields on\nwhatever config types back skills/workflows/plugins if they don't already\nhave an on/off switch. Core capabilities (identity, workflow engine, State\nStore connectivity — named in `organisation.md`'s cross-cutting packages)\nhave no `enabled` field at all; a config value can't be added to something\nthat doesn't expose the toggle, which is the \"non-disaLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/external-agent-harness/",
|
||||
"title": "External agent harnesses",
|
||||
"section": "PRDs",
|
||||
"body": "# External agent harnesses\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md` (agent execution as a data\nboundary); settles the harness non-goal deferred by\n`docs/prds/service-decomposition.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness\nrun is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`\n(the at-rest envelope reused for harness credentials).\n\n## Decision\n\nA workflow stage can run on an external coding-agent CLI instead of the\nbuilt-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any\nother CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API\nkey or the operator's subscription login, and can carry the operator's own\nskills, plugins, subagents and instructions.\n\nTwo boundaries hold regardless of what the harness does:\n\n- **The real credential never enters the container.** The container sees\n sentinel values; archie's egress proxy substitutes the real credential on\n outbound requests and performs OAuth refresh on the host.\n- **Archie's workflow guarantees are enforced outside the harness.** Git,\n protected paths, read-only stages, gates and budgets are checked by archie\n around the process and against the worktree afterwards.\n\n## Kits\n\nA harness is packaged as a Kit v3 image: an OCI image whose\n`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the\nharness needs. Archie reads descriptors with the published\n`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain\nits own descriptor format. Published Kits run unmodified.\n\nArchie is a partial Kit runtime. It implements these capability types:\n\n| Type | Archie behaviour |\n| ------------------- | ----------------------------------------------------------------------------------------- |\n| `credential@1` | Proxy-managed only, described below. |\n| `network-policy@1` | Enforced by the egress proxy. |\n| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |\n| `lifecycle@1` | Install and startup hooks run on container create. |\n| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |\n| `agent-skills@1` | The operator's skills store (`skills_dir`), mounted read-only whatever the Kit asks. |\n| `agent-context@1` | The workload's profile file beside the workspace, indexing each Kit's guidance. |\n| `resources@1` | Container CPU and memory limits. |\n\nEvery other type fails closed: a required entry refuses the launch, an\noptional one is skipped and recorded on the step. `credential@1` with\n`passthrough: true` and any credential for a forge service are refused.\n\nThe operator's own setup (plugins, subagents, instructions, settings) is a\nmixin Kit, published with the harness Kit as a Kit set: the set merges their\nlayers into one image. It is versioned image content, rewritten on every\ncreate, never state a run can modify.\n\n## Contract\n\nA harness run is a second implementation of `agentexec.Runner`. It takes the\nsame `Request` and returns the same `Result`, so workflows, the daemon and\nthe State Store do not know which runner ran a stage.\n\n`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an\noutput adapter that translates the CLI's JSON output stream into\n`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can\nrun stages with no capture tools, reporting no usage; its token budget falls\nback to wall clock.\n\nWorkflow definition validation rejects, at load time, a stage whose needs the\nselected harness cannot meet: capture tools without an adapter, or a gate\nretry without a `resume` verb.\n\n## Selection\n\nA harness is an agent profile. `docs/prds/event-automation.md` defines a\nprofile as the execution environment a workflow selects; a harness profile\nnames one Kit pinned by digest, a workload Kit or a published Kit set, in\nplace of a container image. Archie runs that Kit's image and composes no Kits\nitself; a bare mixin is refused. Everything else about profiles\nholds: a workflow names its profile, a stage may name a different one, and a\nprofile holds no secrets.\n\n`archie-agent` builds the stage's runner from the stage's profile: the\nai-sdk agent loop for an image profile, the harness runner for a Kit\nprofile. Image profiles, and every workflow already written against them,\nare unchanged. A Kit profile named by no workflow is a validation error.\n\nA stage naming a different profile than its workflow's is a separate run,\nnot a mid-container runnLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/identity-decision/",
|
||||
@@ -334,43 +340,43 @@
|
||||
"url": "/dev/prds/image-capability-contract/",
|
||||
"title": "Image capability contract and configuration",
|
||||
"section": "PRDs",
|
||||
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
|
||||
"body": "# Image capability contract and configuration\n\n**Status:** Approved\n\nEpic: archie-core-1786748942120-1-6636e629 / GitHub #496 (\"Image generation\ncapability: hosted API baseline plus local GPU workflows\").\n\nThe contract and configuration (#497) shipped first and is settled — see\n\"Package: `internal/domain/image`\" below. This document now covers the full\nfeature set: hosted provider (#498), local GPU provider (#499), `/image`\nrouting and clarification (#500), delivery through channels and web (#501).\nDocumentation (#502) and the cross-cutting test matrix (#503) are execution\nwork against the design below, not open design questions, so they are not\ngiven their own sections — each preceding section states its own test\nobligations inline.\n\n## Problem\n\nArchie needs a provider-neutral boundary for image generation/editing so a\nhosted API (gpt-image-2-class) and a future local GPU backend can both\nimplement it without either one leaking into the domain contract. Nothing\nin the repo defines this (`grep -ri image` over `internal/domain` and\n`internal/config` returns nothing image-specific).\n\n## Design\n\nFollows the plugin engine family shape already established by\n`internal/domain/curator` and `internal/domain/memory`\n(`docs/architecture/plugins-and-extensions.md#plugin-engine-rule-strict`): a\ntyped contract with real domain operations,\nan owning `Registry` (register/get/names, no start/stop lifecycle — see\nbelow), and narrow host access via a `Registrar`.\n\n### Package: `internal/domain/image`\n\n**Why no `Lifecycle` (`Start/Health/Stop`)**: curator and memory engines are\nlong-running — they hold a background cadence or a persistent connection\nworth health-checking. An image provider is call-scoped: it either serves a\n`Generate`/`Edit` request or it does not. Health here means \"is this\nprovider usable at call time\", which is exactly what `Generate`/`Edit`\nreturning a typed `ErrUnavailable` already communicates — a separate\n`Health()` poll would just duplicate that. `Registry` still owns\nregistration and lookup, so provider selection is testable with fakes per\nthe acceptance criteria, but there is no `Start`/`Stop` to orchestrate.\n\n```go\n// Capability declares what one provider supports, discoverable before a\n// request is built so a caller can reject an unsupported combination (e.g.\n// edit-with-mask on a generate-only provider) instead of sending it and\n// parsing a provider-specific error back out.\ntype Capability struct {\n Generate bool\n Edit bool // edit requires at least one input image\n Mask bool // edit supports a mask restricting the edited region\n MaxInputs int // 0 = Edit unsupported\n Sizes []string // provider-declared output sizes, e.g. \"1024x1024\"\n}\n\n// Provider is the typed contract every image backend implements — hosted\n// (gpt-image-2-class) or local (GPU recipe). No Lifecycle: a provider is\n// call-scoped, not long-running (see design doc rationale).\ntype Provider interface {\n Name() string\n // Class distinguishes hosted (spends money/quota per call) from local\n // (spends host GPU/time). Selection logic and config validation key off\n // this, never off Name, so a new provider cannot silently slip through\n // the hosted-cost gate under an unrecognized name.\n Class() ProviderClass\n Capability() Capability\n Generate(ctx context.Context, req GenerateRequest) (Result, error)\n Edit(ctx context.Context, req EditRequest) (Result, error)\n}\n\ntype ProviderClass string\n\nconst (\n ClassHosted ProviderClass = \"hosted\"\n ClassLocal ProviderClass = \"local\"\n)\n```\n\nRequest/result types (provider-neutral, no OpenAI types):\n\n```go\ntype GenerateRequest struct {\n Prompt string\n Size string // \"\" = provider default\n N int // number of images; 0 = 1\n Options map[string]string // provider-specific overflow (e.g. \"quality\"),\n // deliberately untyped so the contract does not\n // grow a field per provider\n}\n\ntype EditRequest struct {\n Prompt string\n Inputs []ImageData // 1..Capability.MaxInputs\n Mask *ImageData // nil unless Capability.Mask\n Size string\n N int\n Options map[string]string\n}\n\n// ImageData carries image bytes in-process, never a path or URL: the\n// domain layer must not assume a filesystem or a fetchable location (mirrors\n// why curator's Registrar never receives *daemon.Daemon — no ambient host\n// access smuggled in through a \"just a string\" field).\ntype ImageData struct {\n Bytes []byte\n MIMEType string\n}\n\ntype Result struct {\n Images []ImageData\n Provider string\n Model string\n CreatedAt time.Time\n}\n```\n\n### Error taxonomy\n\n```go\nvar (\n ErrUnavailable = errors.New(\"image provider unavailable\") // missing credential, backLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/inline-review/",
|
||||
"title": "Inline review -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): `` - `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e ``. That is a report *about* the code, not a review *of* it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n *conversation* (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\Line truncated
|
||||
"body": "# Inline review -- decision\n\n**Status:** Finalised\n**Beads issue:** `archie-core-q9au`\n**Builds on:** `archie-core-h019` (adversarial self-review), `docs/architecture/adversarial-review.md`\n\n## Problem\n\nFindings reach the operator only as a flat list in the PR body\n(`renderPRReviewSection`, h019.6): ``- `file.go` (confirmed, error): \u003cdefect\u003e\n— \u003cscenario\u003e``. That is a report _about_ the code, not a review _of_ it. A real\nreviewer anchors each finding to the line it is about, so the author sees it in\ncontext — and, when the fix is mechanical, attaches the replacement so it can be\napplied in one click.\n\nBoth halves are missing:\n\n- **No line-anchored comment.** `forge.Forge.Comment` posts to the PR\n _conversation_ (`Issues.CreateComment`); nothing creates a review comment at\n `path` + `line`.\n- **No suggested fix.** `ReviewFinding` carries `File`/`Line`/`Defect`/\n `FailureScenario`/`Verdict`/`Level`/`Category` — no replacement code, so even\n an anchored comment could only describe the fix, not offer it.\n\n## Decisions\n\n### 1. A narrow, type-asserted write surface\n\nThe set of comments travels in one call, so a forge that can only carry them on\na submitted review needs one request rather than one per finding:\n\n```go\ntype ReviewCommentWriter interface {\n CreateReviewComments(ctx context.Context, owner, repo string, number int,\n comments []InlineReviewComment) error\n}\n```\n\nType-asserted like `PullRequestReader`/`PullRequestReviewReader`, so a forge\nthat cannot do it is skipped rather than faked. The stage reaches it through\n`workflow.Forger`, whose production implementation is `forgerpc.Client` — the\nworker holds no forge credentials, so the daemon's forgerpc server type-asserts\n`forge.ReviewCommentWriter` and answers an incapable forge with an error the\nbest-effort stage logs.\n\nThe comment's line is anchored to the pull request's **current head revision**,\nresolved inside each implementation rather than passed in by the caller: it is\nthe revision the comments are attached to, and the caller that produced the line\nnumbers holds no forge credentials to read it. The caller does pass the revision\nthose line numbers were **measured on** (`TaskContext.ReviewedHeadSHA`,\nrecorded when `StageOpenPR` opens the pull request), and the implementation\nposts only while the head it read still matches it — see §4.\n\nPer-forge reality, verified against the SDKs:\n\n- **GitHub** — direct: `PullRequests.CreateComment` with\n `{Body, Path, Line, Side: \"RIGHT\", CommitID}`.\n- **Gitea** — no direct inline-comment call. Inline comments ride on a submitted\n review (`CreatePullReview` with `Comments` and a `COMMENT` state). The Gitea\n implementation therefore submits a single `COMMENT`-state review carrying the\n findings, or the capability is simply absent (the type assertion skips it).\n Decided: implement Gitea as a `COMMENT`-state review; do not block the feature\n on it.\n\n### 2. `Suggestion`, and only on confirmed findings\n\n`ReviewFinding` gains an optional `Suggestion string` — the replacement text for\nthe anchored line, rendered as a fenced `suggestion` block (GitHub's one-click\n\"Commit suggestion\").\n\n**Only `confirmed` findings may carry one.** A wrong suggestion is a\none-click path to breaking code a reviewer then has to notice; `confirmed` is by\ndefinition the verdict the reviewer traced and can state the failure for. A\n`plausible` finding is a worry, and a worry gets a sentence, not a patch. This is\nthe h019.5 calibration rule reused, not a new one.\n\n`Suggestion` replaces the anchored line exactly, and is only rendered when\n`Verdict == confirmed`. Single-line only in this cut;\nmulti-line (GitHub's `StartLine`/`StartSide`) is a follow-up, because a\nmulti-line suggestion that is off by one line silently corrupts the file. The\nrule is enforced in `ReviewFinding.Validate` — an embedded newline is rejected\nthere, so the `record_finding` tool refuses it with feedback the model can act\non, rather than the renderer silently posting a fence that applies only its\nfirst line.\n\n### 3. Which findings are posted inline\n\nOnly findings that are **line-anchored** (`Line \u003e 0`). A whole-file finding\n(`Line == 0`, e.g. \"README.md is stale\") has no line to attach to and stays in\nthe PR-body list. The body section keeps listing everything, so it remains the\ncomplete record and the fallback.\n\nFindings that block never reach this path: a surviving blocking finding parks\nthe task before `StageOpenPR`, so there is no PR to comment on. Inline comments\nare the non-blocking, line-anchored subset — which is exactly the set that would\notherwise be a body-only list the author has to map back to lines by hand.\n\n### 4. A best-effort stage after `StageOpenPR`\n\nNew `StagePostReviewComments`, after `StageOpenPR`:\n\n1. Read the report stashed by `StageReview` (`tc.ReviewReport`, h019.6).\n2Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/mcp-tool-completion/",
|
||||
"title": "MCP client and tool-guardrail completion",
|
||||
"section": "PRDs",
|
||||
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a\nparallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n|---|---|\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the mutex for\nthat server's `Client` instance entirely and let the caller's own\nconcurrency (already proven by the closed concurrent-dispatch bead, `#183`)\nhandle it. This is additive — no server's behaviour changes unless an operator\nopts in.\n\n**Call site.** `internal/config/config.go` (struct field),\n`internal/tools/mcp/client.go` (make the mutex conditional on the\nfield), and wherever `MCPServer` configs are turned into `Client` instances\nat daemon startup (the constructor that reads `internal/config`'s MCP block).\n`config.example.toml`'s commented MCP block gets the new field documented\nwith its default.\n\n**Testing.** Unit test asserting two concurrent `Call`s to the same\n`Client` block on each other when the flag is false and don't when true —\nfakeable with a slow fake transport. `task check`.\n\n## Sandboxed MCP tool servers for the chat agent (`#178`) and Firecracker subLine truncated
|
||||
"body": "# MCP client and tool-guardrail completion\n\n**Status:** Approved\n\nEpic: `archie-core-1786637493439-140-2cee2e9b` / GitHub `#161` (\"[EPIC] Tools:\ncentral registry, MCP client, guardrails\").\n\nThis document is scoped to five sub-features of that epic: MCP\nserver-initiated sampling, the per-server parallel-tool-calls flag, sandboxed\nMCP tool servers, a Firecracker sandbox backend, and sequential dispatch with\nper-result previews.\n\nOut of scope, and not to be touched: the central registry\n(`internal/tools/registry.go`), all three MCP transports (stdio/HTTP/SSE,\n`internal/tools/mcp/transport*.go`), reconnect-with-backoff\n(`transport.go`), guardrail loop detection\n(`internal/tools/guardrail.go`), idempotent/mutating classification\n(`internal/tools/classification.go`), concurrent tool dispatch (`#183`), and\nprogressive disclosure wiring (`internal/app/archied`). These are settled and\nproduction-wired.\n\n## Problem\n\n`bd search \"MCP client\"` shows five closed transport beads and one open:\nserver-initiated sampling (`#151`). `internal/tools/mcp/client.go`\nholds a single `callMu *sync.Mutex` that serialises every `tools/call`\nregardless of server — `ParallelToolCalls` does not exist on the `MCPServer`\nconfig struct (`internal/config/config.go`), confirming `#177` is a\nreal gap, not a stale bead. `#178` (wire MCP tool servers for the chat agent,\nsandboxed) and `#179` (Firecracker substrate) have no corresponding code —\nMCP servers run as whatever the config's `Command`/`Args` launches,\nunsandboxed. `#182` (sequential tool dispatch with per-result previews) is\nopen; concurrent dispatch (`#183`) is closed, so there are two dispatch paths\nand this PRD decides how they coexist.\n\n## Design\n\nSub-features are independent; there is no new shared type this document\nintroduces. Each section below stands alone.\n\n## MCP server-initiated sampling (`#151`)\n\n**Decision.** Implement as a callback on `mcp.Client`, not a second\ntransport. The MCP spec's `sampling/createMessage` request flows server→client\nover the same connection each transport already maintains\n(`transport.go`'s stdio/HTTP/SSE all multiplex request and response frames).\nAdd a `SamplingHandler func(context.Context, SamplingRequest) (SamplingResult, error)`\nfield to the client's config struct next to the existing transport fields,\ndefaulting to nil (server sampling requests get a JSON-RPC \"not supported\"\nerror when unset — never a silent drop).\n\n**Call site.** `internal/tools/mcp/client.go` — add the handler field and a\ndispatch branch in whatever function demuxes incoming server\nmessages by method name (the same switch that already routes\n`notifications/*`). Wire a concrete handler in\n`internal/app/archied/main.go` that routes the sampling request through the\nsame chat-model call path `chatGenerateOptions` already uses, so a\nserver-initiated sample gets the daemon's configured model, not a second\nprovider client. The agent worker hosts the same configured MCP servers on the\ntask path and runs its own model runtime, so `internal/app/agentworker` wires\nthe same seam from the task's builder model: a server that samples succeeds\ninside a chat turn and inside a task, never one and not the other. The message\nmapping and the token bound are shared (`internal/agentexec`, next to the\nruntime both paths call models through) so both paths bound a sample\nidentically.\n\n**Reuse check.** The chat model invocation path already exists\n(`chatGenerateOptions`, `main.go`) and the task model path already exists\n(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both\nrather than adding a parallel model-calling path for MCP sampling.\n\n**Failure mapping.**\n\n| condition | contract error |\n| ------------------------------- | ------------------------------------------------------------------------------------------ |\n| no `SamplingHandler` configured | JSON-RPC method-not-found, per spec |\n| handler returns error | JSON-RPC internal error, message from handler |\n| handler timeout | JSON-RPC timeout error; use the transport's existing request-timeout config, not a new one |\n\n**Testing.** Fakeable entirely — a stub `SamplingHandler` and a fake\ntransport that emits a `sampling/createMessage` frame. No real backend\nneeded; belongs in `task check`.\n\n## Per-server parallel-tool-calls flag (`#177`)\n\n**Decision.** `ParallelToolCalls bool` (default `false`) goes on `MCPServer`\nin `internal/config/config.go`, next to `Transport`/`Command`. The\nmutex in `client.go` becomes per-server: when `ParallelToolCalls` is\nfalse (default, and the only behaviour), keep the single `callMu`\nserialising that server's calls exactly as now; when true, drop the muLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/memory-engine-unification/",
|
||||
"title": "Memory engine unification: four scopes, CRUD, and one write path -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n|---|---|---|---|\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n *does* have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\n string`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_postgres.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `ScopeAgent{a}` and\n`ScopeAgent{b}` are different storage keys.\n\n`ScopeGlobal` is never model-writable. Writing it is an operator action; nothing\nproduces one yet, but the contract models it because the read set includes it.\n\n### 2. CRUD, with revisions retained\n\n```go\ntype Store interface {\n Create(ctx context.Context, in NewRecord) (Record, error)\n Get(ctx context.ContexLine truncated
|
||||
"body": "# Memory engine unification: four scopes, CRUD, and one write path -- decision\n\n**Status:** Approved\n**Date:** 2026-09-16\n**Findings:** `memory-4` and its dependants in the adversarial sweep\n(`.local/issue-tracker`); the real defect is the split described below, for\nwhich `memory-4` is a symptom\n**Supersedes:** the draft `memory-turn-context.md` (its synchronous-read\nargument survives and is reused; its `Manager` method and consumer-owned port do\nnot)\n**Settles:** four open items in `docs/architecture/migration-decisions.md#5`\n(listed at the end)\n\n## Problem\n\nThere are **two live memory stores for one assistant**, split by which component\nwrites them, and the chat turn reads neither.\n\n| Family | Written by | Root | Format |\n| ----------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------- | ----------------------- |\n| `internal/memory` (`Manager`, `builtin.Provider`) | the chat agent's `memory_edit` tool via `memorytoolprovider` (`bootstrap.go`) | `\u003cworkDir\u003e/memory` | `MEMORY.md` / `USER.md` |\n| `internal/domain/memory` + `internal/infrastructure/memory` | the session curator (`sessioncurator.go`) | `\u003cworkDir\u003e/memory-engine` | identity-keyed blocks |\n\nThey share no code, no format and no scope vocabulary. Neither reaches a prompt:\n`Manager.SystemPromptBlock` (`internal/memory/manager.go`) has no production\ncaller anywhere, so the agent can write memory through a tool and never read it\nback.\n\nThree further defects fall out of the same split:\n\n1. **The engine's contract is not CRUD.** `Store` is `Write`/`Query`/`List`/\n `Forget` — create, read, delete, and **no Update**. The retired file provider\n _does_ have `handleAdd`/`handleReplace`/`handleRemove`, so the family being\n deleted is operationally richer than its replacement.\n2. **There is no scope model.** The contract carries one opaque `Identity\nstring`, and the curator fills it with a **session id** (`sessioncurator.go`)\n — which is none of the four scopes `docs/architecture/agent-system.md`\n requires, and stops meaning anything when the session ends.\n3. **The chat turn has no user identity on half the channels.** Telegram and\n email populate `SenderID` with a person; the dashboard populates it with\n nothing, and a webhook populates it with nothing either — a route path names\n a source, not a person, so `webhook.go` leaves `SenderID` empty and carries\n the route in `Inbound.BudgetKey` for rate limiting. `sender_id` is persisted\n (`session_store_postgres.go`), so whatever a channel puts there reaches the\n consumers that read it.\n\n`agent-system.md` says the write-scope selection and cross-scope sharing\nrules \"require a focused memory design decision\". This is that decision.\n\n## Decision\n\n### 1. One engine, addressed by four typed scopes\n\n`internal/domain/memory` is the only memory engine. `Observation.Identity`,\n`Query.Identity`, `Record.Identity` and `List(identity)` are deleted, not\nextended: a field whose meaning depends on the caller cannot carry a scope.\n\n```go\ntype ScopeKind string\n\nconst (\n ScopeGlobal ScopeKind = \"global\" // shared across the application\n ScopeAgent ScopeKind = \"agent\" // private to one Agent\n ScopeUser ScopeKind = \"user\" // one user, across their Agents\n ScopeAgentUser ScopeKind = \"agent-user\" // one Agent's relationship with one user\n)\n\ntype Scope struct {\n Kind ScopeKind\n Agent AgentID // required for ScopeAgent, ScopeAgentUser\n User IdentityID // required for ScopeUser, ScopeAgentUser\n}\n\nfunc (s Scope) Validate() error // rejects a component present where it is not required\nfunc (s Scope) Key() string // canonical, collision-free storage key\n```\n\n`AgentID` and `IdentityID` are opaque. This package never resolves or\ncanonicalises them.\n\nA turn's resolved identity is one value:\n\n```go\ntype Subject struct {\n AgentID AgentID\n UserID IdentityID // \"\" when the channel carries no per-person identity\n}\n\nfunc (s Subject) Scopes() []Scope // readable, most specific first\nfunc (s Subject) WritableScopes() []Scope // never includes ScopeGlobal\n```\n\n**Access control is naming a scope, and nothing else.** The read path names\nexactly the scopes of the resolved `Subject`; the engine never unions beyond what\nit is handed and applies no policy of its own. An engine that enforced policy\nwould need to know about channels, sessions and bindings, and every backend would\nreimplement it. \"Agent-wide is private to its owning Agent by default\"\n(`agent-system.md`) falls out mechanically, because `SLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/messaging-service-boundary/",
|
||||
"title": "Messaging Service boundary and transport design",
|
||||
"section": "PRDs",
|
||||
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behaviour, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n|---|---|---|---|\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n1. **Telegram long-polling**: Must call `dropPendingUpdates(ctx, b)` before `b.Start(ctx)` and on `/restart`.\n2. **Telegram command menus**: Must register command menus simultaneously to `default`, `all_private_chats`, and `all_group_chats` via `commands.go` to prevent menu shadowing.\n3. **No UI detour**: Turns and task actions route directly to Gateway's `ChatContract`; no HTTP request may ever be sent to `archie-ui` or `internal/webui`.\n4. **Sender Confinement**: Telegram sender checks against `allowed_user_ids` must continue to fail closed before initiating any turn dispatch.\n\n## Configuration Ownership\n\n`cmd/archie-messaging` reads only:\n- `[services.gateway].target` and `[services.gateway].target_token` (or CLI flags).\n- `[chLine truncated
|
||||
"body": "# Messaging Service boundary and transport design\n\n**Status:** Approved\n**Revision:** 1 \n**Date:** 2026-09-19 \n**Beads issue:** `archie-core-8cda.6.1` \n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/) \n**Prerequisites:** Gateway contract extraction (Phase 1), State Store extraction (Phase 2), UI extraction (Phase 3)\n\nThis document is the authoritative specification for Phase 4: Messaging Service extraction. It fixes the process boundary, configuration ownership, client contracts, security posture, readiness behaviour, channel invariants, and deletion criteria required by `archie-core-8cda.6` and its child tasks.\n\n## Decision\n\nThe Messaging Service (`cmd/archie-messaging`, composed via `internal/app/archiemessaging`) owns external channel connections (Telegram, email, webhook) and dispatches inbound messages and commands to the standalone Gateway Service over gRPC via `messaging.ChatContract`.\n\nIt is a peer service to the UI Service and the daemon:\n\n- It serves external chat participants across configured communication platforms.\n- It consumes Gateway's `messaging.ChatContract` exclusively for chat turn execution, streaming, session queries, cancellation, persona selection, and task control actions.\n- It holds no direct database connections, owns no LLM execution or model provider credentials, and has no dependency on the daemon runtime or the UI HTTP server.\n\n## Boundary and Ownership\n\n| Concern | Messaging Service owns | Messaging Service consumes | Messaging Service must not own or link |\n| ---------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------ |\n| **Channel transports** | Telegram bot long-polling, Email IMAP/SMTP loops, Inbound Webhook HTTP listener | Gateway `ChatContract` | Direct LLM providers, model runtimes, tokenizer libraries |\n| **Turn dispatch** | Inbound message packaging, typing indicators, live streaming updates | `ChatContract.Route`, `ChatContract.Stream` | `gateway.Router`, `runtime.Runtime`, agent prompt builders |\n| **Sessions \u0026 History** | Platform-to-session key mapping, conversation thread ID translation | `ChatContract.GetSession`, `RecentMessages`, `RecentTurns` | store implementations, `SessionStore` database handles |\n| **Control \u0026 Actions** | Platform command parsing (`/status`, `/tasks`, `/cancel`, `/stop`, `/persona`) | `ChatContract.Snapshot`, `ApplyTaskAction`, `Cancel`, `SetPersona` | `daemon.Daemon`, workflow execution engine, worktree operations |\n| **Task Approvals** | Channel interactive keyboards, approval callbacks | `ChatContract.ApplyTaskAction` | Direct task status mutations, forge comment posters |\n| **Configuration** | Platform bot tokens, allowed sender/user IDs, webhook listen ports | `[chat.*]` channel configs, Gateway target/token | `config.Holder`, forge tokens, repo configs, agent container specs |\n| **Readiness** | Messaging process liveness, channel connectivity, Gateway probe | Gateway `ChatContract.Snapshot` | Internal daemon subsystem probes |\n\n## Target Service Shape\n\n1. **Binary entry point**: `cmd/archie-messaging/main.go` parses CLI flags (`-config`, `-config-overlay`, `-gateway-target`, `-gateway-token`) and hands execution to `internal/app/archiemessaging.Run`.\n2. **Application composition**: `internal/app/archiemessaging/` wires:\n - Config loading scoped strictly to `[chat.*]` and `[services.gateway]`.\n - Secret resolution for channel credentials (e.g. Telegram bot token).\n - Gateway gRPC client (`internal/infrastructure/gatewayrpc.Client`).\n - Channel lifecycle managers (`internal/channels/status`).\n - Channel instances (`internal/channels/telegram`, `email`, `webhook`).\n3. **Turn and Stream Execution**:\n - Channels adapt inbound platform messages to `messaging.Inbound`.\n - Streaming channels (Telegram) consume `ChatContract.Stream(ctx, inbound)` which returns `\u003c-chan messaging.ChatEvent`, mapping `started`, `delta`, `tool`, `media`, `done`, and `error` events directly to live message frames.\n - Non-streaming channels (email, synchronous webhooks) consume `ChatContract.Route(ctx, inbound)`.\n\n## Load-Bearing Channel Invariants\n\nThe Messaging Service preserves existing invariants defined in `AGENTS.md` and channel documentation:\n\n1. **Telegram long-polliLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/module-position/",
|
||||
"title": "Module position -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalise the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n|---|---|---|---|\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterised by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *ModuleRegistry) Register(kind string, dir string) error // discovers \u003ckind\u003e.go, resolves against that kind's generated symbols\nfunc (r *ModuleRegistry) Invoke(ctx context.Context, kind string, rawArgs map[string]any) (map[string]aLine truncated
|
||||
"body": "# Module position -- design\n\n**Status:** Draft\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n\n## Problem\n\n`eda-playbook-engine.md` names four logic positions a playbook action can\ntarget: Workflow, Module, Channel, Forge. Workflow (`t2db.9`/`.10`/`.11`)\nand the standalone lint tool (`t2db.12`) are shipped. Module -- the\nposition that makes an action \"not restricted to code-generation\" -- has\nnot started, because it needs a schema-generation mechanism the parent\ndoc deliberately deferred: \"This document does not attempt to design the\nfull generator.\" This is that design.\n\n## Do not invent a new mechanism -- generalise the one used three times\n\nYaegi-interpreted extension code with a fixed, resolved-by-name exported\nfunction already exists in this codebase for three surfaces, and all three\nfollow the identical shape:\n\n| Surface | Fixed signature | Export path | Symbol table |\n| ----------------------------------------- | --------------------------------------- | -------------- | --------------------- |\n| Custom gate (`internal/gate/gateeval`) | `func(gate.GateContext) []gate.Finding` | `\"gate.Check\"` | `gateextract.Symbols` |\n| Workflow stage plugin (`skillbuild`) | stage-specific | skill-declared | `wfextract.Symbols` |\n| Skill plugin (`internal/skill/plugin.go`) | `func(string) string` | `\"main.Run\"` | none (stdlib only) |\n\nEach is: read a `.go` file -\u003e `yaegiutil.New` with that surface's symbol\ntable -\u003e `yaegiutil.Resolve[T](i, src, exportPath)` -\u003e call the resolved\nfunction wrapped in `yaegiutil.Safe` for panic recovery. **Module is a\nfourth instance of this same shape**, parameterised by action kind instead\nof hardcoded to one fixed signature. No new interpreter construction, no\nnew panic-recovery mechanism, no new symbol-table generation tool --\n`go generate ... yaegi extract` is already how `wfextract`/`gateextract`\nare produced that way (see their `//go:generate` directives), and Module\nschema generation reuses that exact command.\n\n## No generic `Module` interface -- one typed contract per action kind\n\nThe plugin engine rule's invariant 1 requires \"real capability-specific\noperations,\" and invariant 5 forbids adding capability methods to a\ngeneric interface. A single `Module` interface with `Run(args any) (any,\nerror)` would be exactly the untyped hook the rule (and\n`event-sources-and-reactions.md`'s rejection of a generic `Source`\ninterface) exists to prevent -- restating the mistake the whole EDA\ndocument was written to move away from (`wfextract`'s hardcoded\n`reflect.ValueOf(workflow.Implement)` table is what a closed, un-typed-per-\ncase system already looks like in this repo).\n\nInstead, **each action kind is its own tiny package with its own\ngenerated contract**, exactly like `gate.GateContext`/`gate.Finding` are\none hand-written Go file that `gateextract` turns into a Yaegi symbol\ntable:\n\n```go\n// internal/domain/eda/module/notify/types.go (hand-written, the schema source)\npackage notify\n\n// SchemaVersion is independent of a playbook's own workflow_version, per\n// eda-playbook-engine.md's schema-versioning point.\nconst SchemaVersion = 1\n\ntype Args struct {\n Channel string\n Message string\n}\n\ntype Result struct {\n Delivered bool\n}\n\n//go:generate go run github.com/traefik/yaegi/cmd/yaegi extract -name notifyextract github.com/samcharles93/archie-core/internal/domain/eda/module/notify\n```\n\nA Yaegi module implementing this kind exports a fixed function name\nagainst these generated types, resolved the same way `gate.Check` is:\n\n```go\n// operator's notify.go, interpreted at load\npackage notify\n\nfunc Run(a notify.Args) notify.Result { ... }\n```\n\n`internal/domain/eda/module/notify` is the schema; `notifyextract.Symbols`\nis its generated Yaegi bridge; the operator's file is the implementation.\nThis is the same three-way split `internal/gate` / `gateextract` /\n`.archie/gate.go` already has.\n\n## The registry: `ModuleRegistry`, keyed by kind, not a service locator\n\nPer invariant 2 (owning family manager) and invariant 4 (narrow host\naccess): a `ModuleRegistry` in `internal/domain/eda/module` maps a kind\nname (`\"notify\"`, `\"image-gen\"`) to a resolved, type-erased invoker --\nthe same `map[string]reflect.Value`-shaped erasure `wfextract.Symbols`\nalready uses to bridge Yaegi and Go, not a new pattern and not exposed as\nthe plugin's contract with the daemon (the plugin still writes and is\nchecked against a fully typed `func(Args) Result`; the registry's\ninternal storage is the only place erasure appears, exactly as it already\ndoes inside `wfextract`).\n\n```go\ntype ModuleRegistry struct {\n // kind -\u003e (validate args against generated schema, invoke, marshal result)\n}\n\nfunc (r *MoLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/multi-action-playbooks/",
|
||||
"title": "Multi-action playbooks and typed action results",
|
||||
"section": "PRDs",
|
||||
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
|
||||
"body": "# Multi-action playbooks and typed action results\n\n**Status:** Approved\n**Date:** 2026-09-22\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-nx30` (unblocks `archie-core-t2db.27` and `archie-core-t2db.31`)\n\n## Why this exists\n\n`eda-playbook-engine.md`'s hard boundary rejects any playbook that is not\nexactly one `workflow` action, so the parent document's data-flow, Module and\nChannel/Forge decisions have no loadable shape to attach to. The boundary's own\nstated condition is now met: both execution-time gaps are resolved\n(`eda-playbook-engine.md`, \"Execution-time gaps\"; the `playbook_dispatches`\nledger). This document designs the relaxation.\n\n## A playbook is one of two shapes\n\n- A **workflow playbook** is exactly one `workflow` action. Unchanged: it names\n a workflow definition and is routed by the daemon's definition pin.\n- An **action playbook** is one or more `module` actions in order. Each action\n has an optional `id`, a `kind` naming a registered Module kind, `args`, and an\n optional `when`.\n\nOne playbook does not mix the two shapes.\n\n```yaml\ntrigger: { kind: bug }\nactions:\n - id: build\n position: module\n kind: log\n args: { message: '\"build started\"' }\n - id: done\n position: module\n kind: log\n args: { message: '\"done: \" + string(actions.build.result.written)' }\n when: actions.build.result.written == true\n```\n\nThe first Module kind is the side-effect-free `log` kind\n(`module-position.md`, \"Recommended first slice\"). A Module kind with an\nexternal side effect, and the Channel and Forge positions, are out of scope.\n\n## A result type is the kind's generated Result struct\n\nEach Module kind owns a hand-written `Args` and `Result` struct\n(`internal/domain/eda/module/log` is the worked example); `ModuleRegistry.Invoke`\nreturns the result as a flat `map[string]any`. `ModuleRegistry.DecodeResult`\n(`internal/domain/eda/module`) is the single site that converts that map into\nthe kind's `Result` struct before a later expression reads it, so the value the\nchecker validates and the value the run reads have one definition.\n\n`actions.\u003cid\u003e` is typed by the kind of the action that declares `\u003cid\u003e`:\n`{ result: \u003cKindResult\u003e }`. `event` stays `dyn` (J4,\n`playbook-expression-syntax.md`).\n\n## Reject-at-load, preserved\n\nRelaxing the boundary must not make a bad reference resolvable. The load fails,\nnaming the playbook and the offending action, for:\n\n- an `id` missing where a later action references it, duplicated, or outside\n its shape's grammar: a workflow action id keeps the shared\n stable-identifier grammar (J1, already enforced), while a module action id\n must be a lowercase CEL field name writable as `actions.\u003cid\u003e` (so a CEL\n keyword such as `in`, `true`, `false`, or `null` is rejected at load);\n- an `actions.\u003cid\u003e` read of an id no earlier action declares;\n- an `actions` read that is not statically resolvable to an id (any map index,\n literal or dynamic, `in`, a comprehension): the typed `actions` root is an\n object type, so only field selection `actions.\u003cid\u003e` resolves and the\n `actions[\"id\"]` spelling is not accepted;\n- a `result` field the referenced kind's `Result` does not define;\n- a reference to an earlier action that produces no result;\n- an unknown `position`, an unknown `kind`, or a `module` action with no `kind`;\n- a field belonging to the other shape (`kind` on a `workflow` action, or\n `workflow` on a `module` action);\n- an arg KEY the kind's `Args` schema does not define;\n- an arg value whose checked CEL type cannot fill its `Args` field (`'123'`\n for a string field). A `dyn` value, such as an `event` read, passes: its\n type is known only per event, and the module decode refuses a bad one at\n run.\n\nDeclaring the kind's `Result` schema to CEL at load makes a result-field typo a\nload failure rather than a dispatch failure. Matching arg keys against the\nkind's `Args` schema makes an arg-key typo or a wrongly typed value a load\nfailure.\n\n## The environment is per playbook\n\nResult typing depends on the ids a playbook declares and the kind each id runs,\nso the CEL environment is built from one playbook's action list rather than once\nper `Store`, and `expr.NewEnv` takes that list: each declared id becomes a field\nof the `actions` object typed by its kind's `Result`.\n\n## Running an action playbook is out of scope\n\nThis document makes an action playbook load and its references type-check.\nRunning one is designed in `docs/prds/action-playbook-run.md`.\n\n## Decisions\n\n**D1 — dispatch before `t2db.31`.** Superseded by\n`docs/prds/action-playbook-run.md`. Was: an action playbook loads and\nvalidates but is not routed; the definition-pin dispatch reports no match for it,\nand the daemon logs a visible warning naming it.\n\n**D2 — mixing positions.*Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/news-and-releases/",
|
||||
@@ -382,79 +388,103 @@
|
||||
"url": "/dev/prds/operator-pr-review/",
|
||||
"title": "Operator-triggered PR review",
|
||||
"section": "PRDs",
|
||||
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an *existing* PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\n BaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\n baseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorisation.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
|
||||
"body": "# Operator-triggered PR review\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.8`\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nThis PRD reuses the adversarial-self-review contract\n(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /\n`workflow.ReviewReport` types from `internal/domain/workflow`. It decides\nonly what is new: how an operator asks for a review of an _existing_ PR, and\nhow that PR's content reaches the reviewer.\n\n## Problem\n\nThe adversarial reviewer (`StageReview`) runs automatically before `StageOpenPR`\nand reviews the task's own worktree HEAD. There is no way to review a PR that\nalready exists: one archie opened, a human opened, or one whose findings the\noperator wants re-checked after a push.\n\n## Shape\n\nOne channel-neutral command — `review_pr` — accepts a repository and PR number\nand returns the structured `ReviewReport`. The Web UI chat and Telegram invoke\nthe same command; neither duplicates review behaviour. The reviewer model is\n`models.reviewer` (falling back to `models.builder`), already the rule the\nworkflow stage uses, so an operator configures it independently of\nplanner/builder.\n\n## Decisions\n\n1. **Forge read.** `GetPullRequest(owner, repo, number)` returns a\n forge-neutral `PullRequest{Number, Title, Body, HeadRef, BaseRef, HeadSHA,\nBaseSHA, State}`. Declared as a narrow `PullRequestReader` interface,\n implemented by GitHub and Gitea; the noop forge does not implement it, so\n the composition root type-asserts and refuses review with \"forge does not support PR\n review\". Adding to the fat `Forge` interface would churn every test fake for\n a capability the noop forge cannot honestly provide.\n\n2. **Materialisation.** `worktree.Manager.CheckoutPR(owner, repo, headRef,\nbaseRef)` clones the repository fully and checks out `origin/\u003cheadRef\u003e`.\n `Diff(dir, baseRef)` and `Snapshot(dir, destDir)` then work unchanged:\n `Diff` resolves `origin/\u003cbaseRef\u003e` via the existing `resolveBase`, and\n `Snapshot` strips `.git` exactly as the workflow stage does. The head must\n already be pushed to the same repository — archie's own PRs always are; a\n cross-repo or deleted head is refused with that reason, not half-reviewed.\n\n3. **Reviewer reuse.** `agentworker.NewOperatorReviewer(models, providers)`\n builds the same `subagentReviewer` the stage uses, from daemon-level config\n rather than a `taskrun.Request`. It drops only the `Repo.ReviewEnabled`\n gate (the operator asked explicitly) and the task-run scaffolding.\n\n4. **Command.** A gateway tool `review_pr` (toolset `tasks`) bound to the\n channel's identity at construction — the model never names an identity,\n matching `task_spawn`/`task_action`. The Gateway process serves it: it\n composes the worktree manager it needs to materialise the PR head, and the\n composition root supplies `ChatPRReviewer`, a narrow gateway interface\n whose adapter maps `workflow.ReviewReport` into a gateway-owned result\n shape (gateway states what it needs, the composition root adapts — the\n `ChatTaskActor` pattern).\n\n5. **Authorisation.** Identity-scoped repository allow-list, the\n `task_spawn` rule: a chat identity may only review a repo in its\n `TaskProfile.Repos`. `identity == nil` denotes an authenticated dashboard\n operator who may review any configured repository.\n\n6. **Determinism.** One review per (owner, repo, number) at a time: the\n Gateway holds an in-flight set; a concurrent request for the same PR returns\n \"review already in progress\" rather than launching a second reviewer and\n racing on the snapshot.\n\n## Files\n\n- `internal/forge/forge.go`, `github.go`, `gitea.go` — `PullRequest`,\n `PullRequestReader`, `GetPullRequest`.\n- `internal/worktree/worktree.go` — `CheckoutPR`.\n- `internal/app/agentworker/review.go` — `NewOperatorReviewer`.\n- `internal/gateway/review_tools.go` — `ChatPRReviewer`, result shape, `review_pr`.\n- `internal/gateway/turn.go`, `gateway.go` — tool wiring into the turn.\n- `internal/app/archied/pr_review.go` — the `ChatPRReviewer` adapter.\n- `internal/app/archied/{bootstrap.go,gateway.go,main.go}` — composition.\n\n## Not in scope\n\n- Surfacing findings on the PR body or the dashboard (h019.6).\n- Reviewer model per-invocation override: configuration via `models.reviewer`\n is the selection surface; a per-call override is a later knob.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/orgs-and-access/",
|
||||
"title": "Orgs, workspaces and access control",
|
||||
"section": "PRDs",
|
||||
"body": "# Orgs, workspaces and access control\n\n**Status:** Approved\n**Date:** 2026-09-24\n**Parent:** `docs/prds/event-automation.md`, epic `archie-core-t2db`\n\n## Why this exists\n\nArchie has no tenant boundary and no access control: one operator, one shared\ntoken, and no org on any record. The event automation design needs orgs to own\nsources, bindings, workflows and agents, and an agent's reach must be decided\nby the policies over it, never by the event that started it.\n\n## Concepts\n\n- **Org.** The tenant boundary. An instance admin creates an org and adds its\n first owner. An owner or admin adds further members by the sign-in\n provider's subject or email.\n- **Workspace.** A division of an org, named freely (`networking-prd`,\n `service-desk-dev`), with an optional `environment` attribute (any string)\n that policies can test. Sources, event types, mappings, bindings and runs\n belong to a workspace.\n- **Identity.** Every principal is an identity (`internal/domain/identity`):\n - a person is an identity of kind `user`, bound to the sign-in provider\n through the existing subject binding;\n - an agent is an identity of kind `bot` or `service_account`, assigned to\n one org and granted access, secrets and permissions the way a user is.\n\n Signing in and verifying credentials stay separate from identity; identity\n is who acts. Memberships, roles, grants and audit records all reference the\n identity ID.\n- **Instance admin.** Operates the installation: orgs, the sign-in provider,\n instance policies. Instance admins see an org's resources only as members\n of it.\n\n## What belongs where\n\n| Level | Owns |\n|---|---|\n| Instance | the shipped workflow catalogue, instance policies |\n| Org | members, identities and their grants, secrets, agent profiles, workspaces, org workflows and their enabled state |\n| Workspace | sources, event types, mappings, bindings, runs, captures, run events and logs, chat sessions, memory |\n\nEvery owned record carries its `org_id`, and workspace records also carry their\n`workspace_id`. An identity, secret or profile is used in a workspace only\nafter the org grants it to that workspace.\n\nA secret is granted to an identity. An agent profile holds the container\nimage, tools and network access, and no secrets; this supersedes the secret\nreferences in `event-automation.md`'s agent profiles.\n\nA workflow names the identity it runs as. A workflow called by another runs\nas its own identity, and the caller's identity must be permitted `run` on it.\n\n## Access decisions\n\n### Where it lives\n\n- `internal/domain/access` owns the policy schema, the action list, how\n principals and resources are turned into policy entities, and the\n `Authorizer` contract.\n- The Cedar implementation, using `github.com/cedar-policy/cedar-go`, lives in\n `internal/infrastructure/access`; `internal/app` wires it.\n- Exactly two places call the `Authorizer`: the dashboard and API request\n path, and dispatch. Every other service verifies a credential and never\n evaluates policy.\n\n### The model\n\n- **Principal:** an identity, with its memberships, roles and grants.\n- **Resource:** the record acted on, with its workspace and org as parents,\n its type, owner and state.\n- **Action:** one of `read`, `create`, `update`, `delete`, `approve`, `run`,\n `read_logs`, `read_secret`, `manage_members`, `manage_identities`,\n `manage_policies`.\n- **Context:** the event's signature result, the address it came from, the\n time, and the run and step when the principal is an agent.\n\n### The policy chain\n\n```\ninstance (+ network rules) ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object\n```\n\n- **Instance** policies hold across every org. They include network rules:\n which addresses may deliver events to any source on the instance.\n- **Object** policies attach to one object (an event source, a secret, an\n identity, a binding, a workflow): \"only `soc-responder` may read this\n secret\", \"this source accepts events only from 10.20.0.0/16\".\n- A request is allowed only if every level with policies for it permits it. A\n lower level narrows and never widens; a forbid at any level wins; with no\n permit the request is denied.\n- The shipped role policies mean the org level always has policies, so an\n object or workspace policy alone can never grant access.\n- Archie ships an instance policy, which no org can remove, forbidding any\n principal to act on a resource outside the orgs it belongs to.\n\n### Storing and changing policies\n\n- Policies are stored in the State Store per level, versioned, and every\n change is an audit event naming who made it.\n- A policy is checked against the current schema when it is saved, and every\n stored policy is checked again when archie starts. An invalid org, workspace\n or object policy makes its level deny everything and is reported as a health\n issue naming the policy and the errLine truncated
|
||||
"body": "# Orgs, workspaces and access control\n\n**Status:** Approved\n**Date:** 2026-09-24\n**Parent:** `docs/prds/event-automation.md`, epic `archie-core-t2db`\n\n## Why this exists\n\nArchie has no tenant boundary and no access control: one operator, one shared\ntoken, and no org on any record. The event automation design needs orgs to own\nsources, bindings, workflows and agents, and an agent's reach must be decided\nby the policies over it, never by the event that started it.\n\n## Concepts\n\n- **Org.** The tenant boundary. An instance admin creates an org and adds its\n first owner. An owner or admin adds further members by the sign-in\n provider's subject or email.\n- **Workspace.** A division of an org, named freely (`networking-prd`,\n `service-desk-dev`), with an optional `environment` attribute (any string)\n that policies can test. Sources, event types, mappings, bindings and runs\n belong to a workspace.\n- **Identity.** Every principal is an identity (`internal/domain/identity`):\n - a person is an identity of kind `user`, bound to the sign-in provider\n through the existing subject binding;\n - an agent is an identity of kind `bot` or `service_account`, assigned to\n one org and granted access, secrets and permissions the way a user is.\n\n Signing in and verifying credentials stay separate from identity; identity\n is who acts. Memberships, roles, grants and audit records all reference the\n identity ID.\n\n- **Instance admin.** Operates the installation: orgs, the sign-in provider,\n instance policies. Instance admins see an org's resources only as members\n of it.\n\n## What belongs where\n\n| Level | Owns |\n| --------- | ---------------------------------------------------------------------------------------------------------------- |\n| Instance | the shipped workflow catalogue, instance policies |\n| Org | members, identities and their grants, secrets, agent profiles, workspaces, org workflows and their enabled state |\n| Workspace | sources, event types, mappings, bindings, runs, captures, run events and logs, chat sessions, memory |\n\nEvery owned record carries its `org_id`, and workspace records also carry their\n`workspace_id`. An identity, secret or profile is used in a workspace only\nafter the org grants it to that workspace.\n\nA secret is granted to an identity. An agent profile holds the container\nimage, tools and network access, and no secrets; this supersedes the secret\nreferences in `event-automation.md`'s agent profiles.\n\nA workflow names the identity it runs as. A workflow called by another runs\nas its own identity, and the caller's identity must be permitted `run` on it.\n\n## Access decisions\n\n### Where it lives\n\n- `internal/domain/access` owns the policy schema, the action list, how\n principals and resources are turned into policy entities, and the\n `Authorizer` contract.\n- The Cedar implementation, using `github.com/cedar-policy/cedar-go`, lives in\n `internal/infrastructure/access`; `internal/app` wires it.\n- Exactly two places call the `Authorizer`: the dashboard and API request\n path, and dispatch. Every other service verifies a credential and never\n evaluates policy.\n\n### The model\n\n- **Principal:** an identity, with its memberships, roles and grants.\n- **Resource:** the record acted on, with its workspace and org as parents,\n its type, owner and state.\n- **Action:** one of `read`, `create`, `update`, `delete`, `approve`, `run`,\n `read_logs`, `read_secret`, `manage_members`, `manage_identities`,\n `manage_policies`.\n- **Context:** the event's signature result, the address it came from, the\n time, and the run and step when the principal is an agent.\n\n### The policy chain\n\n```\ninstance (+ network rules) ─▶ org ─▶ workspace ─▶ identity + workflow ─▶ object\n```\n\n- **Instance** policies hold across every org. They include network rules:\n which addresses may deliver events to any source on the instance.\n- **Object** policies attach to one object (an event source, a secret, an\n identity, a binding, a workflow): \"only `soc-responder` may read this\n secret\", \"this source accepts events only from 10.20.0.0/16\".\n- A request is allowed only if every level with policies for it permits it. A\n lower level narrows and never widens; a forbid at any level wins; with no\n permit the request is denied.\n- The shipped role policies mean the org level always has policies, so an\n object or workspace policy alone can never grant access.\n- Archie ships an instance policy, which no org can remove, forbidding any\n principal to act on a resource outside the orgs it belongs to.\n\n### Storing and changing policies\n\n- Policies are stored in the State Store per level, versioned, and every\n changeLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/payload-field-mapping/",
|
||||
"title": "Payload field mapping -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n+ mapping + workflow) is out of scope -- this bead ships the mapping\nconcept and its preview only, as a standalone entity `t2db.4` will later\nreference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n*is* the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any non-emptyLine truncated
|
||||
"body": "# Payload field mapping -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.3`, depends on `t2db.1`, blocks `t2db.4`\n\nAnswers what a \"mapping\" is, where it lives, and what \"resolve against a\nreal event\" means precisely enough to implement. `t2db.4` (binding: matcher\n\n- mapping + workflow) is out of scope -- this bead ships the mapping\n concept and its preview only, as a standalone entity `t2db.4` will later\n reference by ID.\n\n## Decision: a new `internal/domain/mapping` package, SQLite storage\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\n`internal/domain/mapping` owns the mapping vocabulary and the pure\nresolve/preview rule; `internal/store` persists it (mirrors\n`captures.go`'s shape exactly -- inline schema const, narrow store\ninterface, `*store.Store` implementation); `internal/webui/api_mapping.go`\nis the transport. This follows `docs/prds/event-capture-storage.md`'s own\nplacement precedent: `internal/store` is where this daemon's persistence\nalready lives, not `internal/infrastructure` (that layer holds\ncross-domain services -- config, eventbus, modelcatalog -- not this\ndaemon's primary store).\n\n### Why a domain package and not just a store table\n\nResolving a path against a payload and deciding \"missing vs null vs\ntype-changed\" is a rule, not a query -- CLAUDE.md's domain layer owns\n\"language, state, rules, operations\" precisely so this logic is testable\nwithout a database and reusable by `t2db.4`'s runtime trigger path without\neither package importing the other's transport concerns.\n\n## Mapping shape\n\n```go\ntype Mapping struct {\n\tID int64\n\tName string\n\tSourceHint string // free-text label (e.g. \"sentry\"), organisational only -- not enforced against Capture.Source\n\tFields []Field\n\tCreatedAt time.Time\n\tUpdatedAt time.Time\n}\n\ntype Field struct {\n\tName string // the name the workflow receives\n\tPath string // dot/bracket path into the payload, see below\n\tType FieldType // expected type, checked at resolve time\n\tRequired bool // Required=false + missing is not a failure; Required=false + wrong type still is\n}\n\ntype FieldType string // \"string\" | \"number\" | \"bool\" | \"object\" | \"array\" | \"any\"\n```\n\n`SourceHint` is advisory only: an operator authors a mapping by clicking\nthrough one example capture, but the mapping is not pinned to that\ncapture's exact source string, because `t2db.4`'s matcher (not this bead)\ndecides which events a binding applies to. Pinning here would duplicate\nthat decision in the wrong layer.\n\n## Path syntax\n\nDot-separated keys with `[N]` for array indices: `data.items[0].id`. No\nwildcards, no filters, no external library -- the grammar is exactly what a\nclick-through UI needs to express (this key, then this key, then this\nindex), and every path in a mapping was generated by clicking a value in a\nreal payload, never hand-written against a spec. A hand-rolled parser\n(~30 lines: split on `.`, strip `[N]` suffixes) is less risk than a new\ndependency for a grammar this small.\n\n## Resolve semantics (the preview AND the future runtime path)\n\n```go\nfunc Resolve(fields []Field, payload []byte) (values map[string]any, failures []Failure)\n\ntype Failure struct {\n\tFieldName string\n\tPath string\n\tReason string // \"missing\" | \"null\" | \"type_mismatch\"\n}\n```\n\nDecode with `json.Decoder.UseNumber()` (matches `webhookguard.RedactPayload`'s\nexisting convention) so int/float distinction survives for type checking.\nWalk each field's path independently -- one field's failure does not stop\nresolution of the others, because the whole point of preview is showing\nthe operator every problem at once, not the first one.\n\n- Path segment doesn't exist, or indexes past an array's length -\u003e `missing`\n- Path resolves to JSON `null` -\u003e `null`\n- Path resolves to a value whose JSON type doesn't match `Field.Type`\n (`\"any\"` always matches) -\u003e `type_mismatch`\n- `Required: false` suppresses `missing` only, never `null` or\n `type_mismatch` -- a field that's present but the wrong shape is always\n worth surfacing, since silently coercing it is exactly the \"agent\n confabulates around a blank field\" failure this bead exists to prevent.\n\n**This is the same function both consumers use.** `t2db.3`'s preview calls\nit against an operator-picked capture and renders every result, pass or\nfail, in the UI -- that satisfies this bead's \"fail loudly\" acceptance\ncriterion, because at this stage the only runtime consumer of a mapping\n_is_ the human previewing it. `t2db.4` will call the identical function\nwhen a live event triggers a binding and turn any nonLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/playbook-expression-syntax/",
|
||||
"title": "Playbook data-flow and condition syntax",
|
||||
"section": "PRDs",
|
||||
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\nUnbuilt decisions: `archie-core-t2db.25` (J1 action ids),\n`archie-core-t2db.26` (J2 args as CEL),\n`archie-core-t2db.27` (Result schemas declared to CEL).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a\ncondition deciding whether the action runs; (b) a later action's `args`\nvalues referencing an earlier action's `Result` and the triggering\nevent's fields. Both are **CEL expressions**, evaluated against one\nevaluation context. There is no separate interpolation syntax: CEL\nreads nested maps and fields natively, so `args` values that need data\nare written as CEL, and only plain literal args remain plain YAML\nscalars.\n\nBoth halves are read-only: expressions may read context values and\ncompute a result from them, never mutate, never call host functions,\nnever perform I/O. CEL enforces this structurally (no side effects,\nlinear evaluation when macros are bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: 'actions.build.result.written == true'\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged**\n-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`\n(module-position.md's trust-boundary section): loaded from a configured\ndirectory at startup, never from a webhook body or task worktree. The\nschema-by-example flow uses live events to *design against*; the saved\nplaybook is operator-authored file content in an operator-configured\nlocation.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not\n attacker input; no sandboxing against a hostile expression string is\n required. If a future playbook source is less trusted (auto-generated\n bindings from unauthenticated captures), that is the playbook-file\n trust tier moving -- the loader's acceptance check is the right\n place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook\n body, prior results through the same pipeline). Robustness against\n hostile data is required: no panic on wrong-typed/missing fields,\n no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL\n provides this structurally (cost limits, linear non-Turing-complete\n evaluation, error values instead of panics -- verified in the\n vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go\n(`.archie/gate.go`) as the repo's conditional-logic precedent. That is\nthe wrong precedent for playbook conditions because this document's\npremise is: **YAML is pure orchestration data; Yaegi is where\nimperative logic lives** (Problem section; module-position.md's\n\"no generic hook\" section). Yaegi snippets in YAML would move\nimperative logic into the data layer -- the inversion this design\nexists to prevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data,\nnot programs**. CEL is non-Turing-complete and side-effect-free, so it\ncannot become a program; a condition that needs real logic gets a\nModule kind (Yaegi), referenced by the action, not a stronger\nexpression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an\n`any` payload; it exists to keep static implementation contracts\ntyped. Evaluating CEL against runtime `map[string]any` is **not the\nsame problem**: the rule concerns *implementation contracts* (static\noperations a capability family exposes), not *runtime data values*\n(legitimately dynamic -- an event payload's shape is unknown until it\narrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the\nplaybook engine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch\ntime:\n\n| Name | Type | Source |\n|---|---|---|\n| `event` | `map(string, dyn)` | The triggering event's decoded payload (webhook body / forge issue / schedule tick). Field access via `event.\u003cfield\u003e`, map access via `event[\"field\"]`, presence via `has(eventLine truncated
|
||||
"body": "# Playbook data-flow and condition syntax\n\n**Status:** Approved\n**Date:** 2026-09-03\n**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`\n**Beads issue:** `archie-core-t2db.14` (expression environment).\n\n**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression\nmechanism covers both an action's `when` condition and its `args` values.\n\n## The requirement, stated directly\n\nA playbook action is gated and parametrised by runtime data: (a) a condition\ndeciding whether the action runs; (b) a later action's `args` values referencing\nan earlier action's `Result` and the triggering event's fields. Both are **CEL\nexpressions**, evaluated against one evaluation context. There is no separate\ninterpolation syntax: CEL reads nested maps and fields natively, so `args`\nvalues that need data are written as CEL, and only plain literal args remain\nplain YAML scalars.\n\nBoth halves are read-only: expressions may read context values and compute a\nresult from them, never mutate, never call host functions, never perform I/O.\nCEL enforces this structurally (no side effects, linear evaluation when macros\nare bounded, cost-limited).\n\n```yaml\nactions:\n - id: build\n position: module\n kind: log\n args:\n message: '\"build finished\"' # literal\n when: 'event.label == \"bugfix\"' # gate on event field\n - position: module\n kind: log\n args:\n message: '\"done: \" + string(actions.build.result.written)'\n when: \"actions.build.result.written == true\"\n```\n\n## Trust boundary of the expression\n\nA playbook YAML is **operator-installed, in-process, daemon-privileged** -- the\nsame tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's\ntrust-boundary section): loaded from a configured directory at startup, never\nfrom a webhook body or task worktree. The schema-by-example flow uses live\nevents to _design against_; the saved playbook is operator-authored file content\nin an operator-configured location.\n\nTwo consequences:\n\n1. The expression string is **trusted**. Operator-authored config, not attacker\n input; no sandboxing against a hostile expression string is required. If a\n future playbook source is less trusted (auto-generated bindings from\n unauthenticated captures), that is the playbook-file trust tier moving -- the\n loader's acceptance check is the right place, not the evaluator.\n2. The **data the expression reads is NOT trusted** (decoded webhook body, prior\n results through the same pipeline). Robustness against hostile data is\n required: no panic on wrong-typed/missing fields, no unbounded cost on\n deep/cyclic maps, bounded evaluation time. CEL provides this structurally\n (cost limits, linear non-Turing-complete evaluation, error values instead of\n panics -- verified in the vetting record below).\n\n## The gate precedent is deliberately NOT copied\n\n`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)\nas the repo's conditional-logic precedent. That is the wrong precedent for\nplaybook conditions because this document's premise is: **YAML is pure\norchestration data; Yaegi is where imperative logic lives** (Problem section;\nmodule-position.md's \"no generic hook\" section). Yaegi snippets in YAML would\nmove imperative logic into the data layer -- the inversion this design exists to\nprevent -- and make playbooks un-lintable.\n\nThe line: conditions are **declarative predicates over runtime data, not\nprograms**. CEL is non-Turing-complete and side-effect-free, so it cannot become\na program; a condition that needs real logic gets a Module kind (Yaegi),\nreferenced by the action, not a stronger expression body.\n\n## Plugin-engine-rule interaction\n\nThe plugin engine rule forbids a generic `Module` interface with an `any`\npayload; it exists to keep static implementation contracts typed. Evaluating CEL\nagainst runtime `map[string]any` is **not the same problem**: the rule concerns\n_implementation contracts_ (static operations a capability family exposes), not\n_runtime data values_ (legitimately dynamic -- an event payload's shape is\nunknown until it arrives). The Module contract stays fully typed (generated\n`Args`/`Result` schemas); CEL is a read-only data reader under the playbook\nengine family, not a new capability contract. Stated once.\n\n## Minimum viable evaluation context (what expressions see)\n\nOne flat context, namespaced from the playbook run, built at dispatch time:\n\n| Name | Type | Source |\n| --------- | ------------------------ | ---------------------------------------------------------------------------------Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/plugin-settings-live/",
|
||||
"title": "Plugin settings reconcile live",
|
||||
"section": "PRDs",
|
||||
"body": "# Plugin settings reconcile live\n\n**Status:** Draft\n**Revision:** 2\n**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)\n**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how\nits changes take effect; `docs/architecture/plugins-and-extensions.md` owns the\nplugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply\nreports go.\n\n## Outcome\n\nAn operator drops a plugin, module or secret-engine file into a configured\ndirectory while archied runs, and the daemon loads it without a restart. An\nedit to an installed file replaces what is running. A delete never stops running\ncode; apply status says so. A stored `plugin-settings` change applies live for\n`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is\nrefused.\n\n## Triggers\n\n`PluginSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes\n`live` in `internal/app/controlplane/operational_settings.go`.\n\nA poller reconciles on the apply-status restamp interval, so a dropped file\nloads without a filesystem watch. Each tick re-runs both halves the boot path\nruns, against the directories in the running config: the directory loads\n(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the\nlayering (`boot.runtimeConfig`), which re-resolves provider credentials. A\nprovider disabled at boot for an unresolvable engine is re-resolved on the first\ntick that finds it; a changed directory retargets the next tick without a\nrestart.\n\n## Rules\n\n- Adding and changing load; removing never unloads. Yaegi interpreters are not\n reclaimed while a caller still exists and there is no unload path; the running\n set can only grow. A removal stays outstanding in the apply-status error until\n the process restarts.\n- Each file is loaded through a fresh interpreter (the boot pattern) and\n content-hashed, so only new and changed files load.\n- A file that fails to load is skipped and reported; already-running code keeps\n running, the degrade-and-skip convention `plugin.LoadDir` and\n `Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule\n for the module directory; a broken file at runtime skips without aborting.\n- A directory that does not exist reconciles to an empty set.\n\n## The three registries\n\n- **Secret engines** (`internal/secret`). Reconciliation re-runs\n `Registry.LoadDir` against the live directory. `Register` replaces by name, so\n an edited engine takes effect for the next resolution and a dropped engine\n resolves on the next tick. A deleted engine stays registered: existing\n references keep resolving through it until restart. Engines are stateless\n resolvers, so a swap needs no lifecycle step.\n- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs\n `ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves\n through the registry at invoke time, so the swap reaches a running playbook\n store unchanged; a deleted file leaves the old invoker in place, running.\n- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside\n `Register`, `Start` and `Stop`, and `Register` keeps its rule that\n registration is allowed only before the first `Start`, so these are new host\n methods rather than a relaxed `Register`. One adds a single module while the\n host is running: inserted in dependency order, started alone, and rolled back\n alone on failure, leaving every previously started module running. The other\n replaces a module whose manifest id matches: stop it, start the new one, and\n restart the old one when the new start fails; replacing a module another\n running module depends on is refused. A module's `Start` is its only check\n (`plugin.Module` has no probe, and one manifest id cannot be registered\n twice), so a replacement checks by starting and keeps a rollback rather than\n switching first. These operations obey the plugin engine rule: the host\n invokes start and stop itself and isolates the failure to one module. A\n deleted file makes no host call: the module runs on.\n\n## `skills_dir`\n\n`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`\ndocument whose `skills_dir` differs from the value in force. The check is a\npre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in\n`internal/app/archied/control_plane.go`), not an addition to\n`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,\nwhich stays value-agnostic per the #1143 decision recorded there: a\nchange-immutability rule needs the running config, and #1143's validates-nothing\nstill holds for values. The write lands, the store keeps the version, the daemon\npublishes nothing, the refusal is reported against that stored versLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/pr-review-agent/",
|
||||
"title": "PR review agent",
|
||||
"section": "PRDs",
|
||||
"body": "# PR review agent\n\n**Status:** Approved\n**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer\nexecutor and blocking rule in `docs/architecture/adversarial-review.md`, and\nthe designs in `docs/prds/operator-pr-review.md` and\n`docs/prds/review-calibration.md`.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent\ncall is a StepExecution), `docs/prds/external-agent-harness.md` (any agent\nstep may run on a harness), `docs/prds/inline-review.md` (posting),\n`docs/prds/pr-review-remediation.md` (consumes the findings).\n\n## Decision\n\nArchie ships a pull request reviewer as its first end-to-end product. It\nreviews any pull request on a watched repository, a PR an operator names, and\narchie's own PRs before they open.\n\nThe reviewer is a fixed pipeline, not a single agent. The review strategy is\ngenerated per PR: three lens agents propose review dimensions from the PR's\ncontent, one reviewer definition runs once per dimension, and later agents\nverify, challenge and combine the findings. Everything that can be computed\nis code: diff parsing, clustering, blast radius, evidence extraction,\nscoring, deduplication, line mapping and the review event.\n\nThe pipeline is **recall-first**. It posts every evidenced finding above the\nconfidence threshold, up to the comment cap. A precision gate exists as an\noperator dial and is off by default.\n\nAcceptance is measured, not asserted: see Verification.\n\n## Pipeline\n\nEach numbered phase is a stage of the `pr-review` workflow. Each agent call is\nan `agent` StepExecution; fan-out phases record one child per call.\n\n1. **Intake.** Code reads the PR metadata and diff statistics: type,\n complexity, languages, areas touched, risk signals. Depth comes from lines\n changed: under 100 is `quick` (at most 3 dimensions), under 500 is\n `standard` (6), otherwise `deep` (12). An operator may set depth\n explicitly.\n2. **Anatomy.** Code parses the diff into files and hunks, clusters related\n files, and computes the blast radius: unchanged files that import or are\n imported by changed files. One agent writes the PR narrative, risk\n surfaces, changes that do not fit the narrative, and gaps between the\n description and the diff.\n3. **Dimension selection.** Three lens agents run in parallel over the intake\n (including its machine-written score), anatomy and diff, each able to read\n the repository. A PR that intake scores as likely machine-written adds a\n hallucination-check dimension: claims, citations and behaviour the diff\n does not actually implement.\n - **behaviour:** where the old and new code diverge for any input; API\n contracts, concurrency and state, security, error handling, data flow;\n - **mechanics:** whether the code runs at the language and framework\n level; types, signatures and every caller, decorators and middleware,\n framework contracts, imports;\n - **fit:** patterns, complexity, abstraction, test adequacy, documentation\n that no longer matches, dependencies, migration completeness.\n\n Each lens returns review dimensions: a name, a reviewer prompt written for\n this PR, target files, context files and a priority. Code merges them,\n drops duplicates and keeps the highest-priority dimensions up to the\n depth's cap.\n4. **Review.** One reviewer definition runs once per dimension, in parallel,\n at most 8 at a time. Each reads its target and context files and may\n follow references. Each finding carries file, line range, severity\n (`critical`, `important`, `suggestion`, `nitpick`), title, body, an\n optional suggested fix, quoted evidence, confidence and tags. A reviewer\n that exhausts its turn cap or deadline before its terminal tool call\n records a distinct StepExecution status from a reviewer that completed\n and found nothing; synthesis and the posted review treat the two\n differently (the former is unreviewed, the latter is reviewed-clean).\n5. **Verification layer**, over the review findings:\n - code extracts an evidence package per finding: the code at the cited\n lines and snippets from its callers;\n - an evidence verifier checks high-priority findings against their\n packages;\n - an adversary confirms or challenges each finding, looks for issues every\n reviewer missed, and is more sceptical when intake scores the PR as\n likely machine-written;\n - a compound agent looks, within each cluster of confirmed findings, for\n defects that only exist in combination.\n6. **Coverage and consistency**, in parallel:\n - a coverage gate checks every cluster and high-exposure blast-radius file\n was reviewed, and runs gap reviewers for what was not, at most 2 rounds;\n - consistency verification lists every cross-location obligation the\n changed code creates (what must be true elsewhere for this line to be\n correct), then verifies each by reading both endLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/pr-review-operator-response/",
|
||||
"title": "PR review: the operator's answer to the approval gate",
|
||||
"section": "PRDs",
|
||||
"body": "# PR review: the operator's answer to the approval gate\n\n**Status:** Draft\n**Authority:** `docs/prds/pr-review-agent.md` (\"Operator approval\") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.\n**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).\n\n## Decision 1 — where the operator answers\n\nThe dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.\n\n`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.\n\nThe path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.\n\nA requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as \"keep the task's\", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as \"keep the task's\".\n\n### The review the operator answers\n\nThe gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.\n\nThe operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.\n\nThis record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, \"post the selected findings\" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.\n\n## Decision 2 — the cap\n\nThe cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.\n\n`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.\n\n- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.\n- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.\n\n`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.\n\nThe write crosses the State Store. A goose migration adds the column; `Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/pr-review-remediation/",
|
||||
"title": "PR review comment remediation -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened *and still owns*.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyLine truncated
|
||||
"body": "# PR review comment remediation -- decision\n\n**Status:** Approved\n**Date:** 2026-09-10, amended and ratified 2026-09-19\n**Beads issue:** (filed as `archie-core-…`, parent: `archie-core-7d5u` event sources and typed reactions)\n\nAnswers: how archie reacts to review comments on a PR it opened, from a human\nor from another review bot, and remediates them. Built on two settled decisions — the adversarial review\nepic's isolation contract (`docs/prds/adversarial-self-review.md`) and the\nevent-sources decision (`docs/prds/event-sources-and-reactions.md`) — plus the\nwebhook intake security contract (`docs/prds/webhook-intake-security.md`).\nNothing here re-decides those; it names the one concrete reaction each one's\nmachinery was built to carry.\n\n## Problem\n\nArchie opens a PR (`pr_open`) and then never learns what a human said about\nit. `forge.Forge` has no method to list PR reviews or review comments; the\ndaemon poll loop finds only new issues; the forge webhook receiver\n(`internal/forge/webhook/receiver.go`) decodes only `issues` events and\nexplicitly ignores `pull_request` events. A \"requested changes\" review, or an\ninline comment on a line, is invisible work.\n\n## Decisions\n\n### 1. Read surface: a narrow `PullRequestReviewReader`, type-asserted\n\nA new forge interface, implemented by GitHub and Gitea, not folded into the\nfat `Forge` interface (the h019.8 `PullRequestReader` precedent — the noop\nforge cannot honestly provide it):\n\n```go\ntype ReviewComment struct { ID int64; Author, Body, Path string; Line int; InReplyTo int64; CreatedAt time.Time }\ntype Review struct { ID int64; Author, State string /* requested_changes | approved | commented | dismissed */; SubmittedAt time.Time }\n\ntype PullRequestReviewReader interface {\n ListReviews(ctx, owner, repo string, number, sinceID int64) ([]Review, error)\n ListReviewComments(ctx, owner, repo string, number, sinceID int64) ([]ReviewComment, error)\n // ReplyToReview posts a reply to a review or comment thread.\n ReplyToReview(ctx, owner, repo string, number, inReplyTo int64, body string) error\n}\n```\n\nGitHub: `pulls/{n}/reviews` + `pulls/{n}/comments`; reply via\n`pulls/{n}/comments/{id}/replies`. Gitea: `pulls/{n}/reviews` +\n`pulls/{n}/comments`; reply via `pulls/{n}/comments/{id}`. `sinceID` is the\ncursor for both poll and webhook dedup.\n\n### 2. Event source: webhook first, poll as the universal backstop\n\n- **Webhook (GitHub, low latency):** extend `receiver.go` to also decode\n `pull_request_review` and `pull_request_review_comment` events, behind the\n existing HMAC verification, producing the same reaction as the poller. The\n receiver stays a forge-intake surface — not the generic chat webhook, not a\n new generic receiver (7d5u decision 4).\n- **Poll (both forges, no webhook dependency):** a periodic scan of `pr_open`\n tasks calls `ListReviews`/`ListReviewComments` with a persisted `sinceID`\n cursor per task. This is the Gitea path and the deployment-without-webhook\n path; it must stay first-class, not a legacy fallback (the repo's own\n webhook-intake rule). It is **one shared scan over all `pr_open` tasks**,\n not a scan inside each identity's poll loop, and it calls the forge client\n the scanned task's own identity owns. This is `reconcilePRs`'s shape\n exactly (`internal/daemon/daemon.go`: `Store.OpenPRs` then `forgeFor(\u0026t)`).\n A per-identity scan would call one identity's forge client against another\n identity's PR.\n\nBoth paths emit the **same** typed reaction, so `PublishUnique` dedups them\nfor free — the `TaskEnvelope.IdempotencyKey` pattern (7d5u decision 4) applied\nto reviews.\n\n### 3. Reaction contract: producer-only, resolves to an existing task\n\nA new `workintake.ReviewCommentEnvelope{Owner, Repo, PRNumber, Kind, CommentID,\nReviewID, Author, State, Body, Path, Line}`. Idempotency key is\n`owner/repo/pr-number/kind/id` — source-independent, so a webhook delivery\nand a poll of the same comment collapse.\n\n`Kind` (`review` or `comment`) is part of the key because a review ID and a\nreview-comment ID come from independent forge sequences. Keying on the bare id\nlets a review and an inline comment on the same PR collide, silently dropping\none of the two. This is a producer-only reaction\n(7d5u decision 3): it never vetoes or mutates in-flight work; the target task\nis idle (`pr_open`).\n\nThe daemon resolves `PRNumber` → the task that owns it. An unmatched PR (not\nan archie task) is dropped with a counter — a public webhook must not be able\nto start an agent against an arbitrary repository. A PR whose task is merged,\nclosed or archived is dropped through the same counter: the reaction is only\never work against a PR archie itself opened _and still owns_.\n\nThat lookup does not exist. `pr_number` is written by\n`internal/infrastructure/postgres/store.go` and never read in a `WHERE` clause, so this needs a\n`TaskStore` method keyLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/progressive-tool-disclosure/",
|
||||
"title": "Progressive tool disclosure (bridge tools) — wiring",
|
||||
"section": "PRDs",
|
||||
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n+ `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n**never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\nreferenced only in `disclosure_test.go`. This task is therefore a **wiring**\ntask, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` — `PreLine truncated
|
||||
"body": "# Progressive tool disclosure (bridge tools) — wiring\n\n**Status:** Finalised\n**Date:** 2026-08-15\n**Compound:** the \"keep the LLM tool schema small, give full access on demand\" work (issue #167)\n\n## Decision\n\nThe bridge-tool pattern is **implemented and tested** in\n`internal/tools/disclosure.go` (`tool_search`, `tool_describe`, `tool_call`\n\n- `ContextPressureGate` + `DisclosureMode`, section 17.14/17.15) — but it is\n **never wired into the daemon**. `BridgeTools` and `ContextPressureGate` are\n referenced only in `disclosure_test.go`. This task is therefore a **wiring**\n task, not a feature build.\n\nWire the existing bridge into the per-chat-turn toolset:\n\n1. **Compose a per-turn registry** seeded from the base registry plus the\n per-turn extra tools, register the bridge tools into it, and hand it to both\n the bridge handlers and the `ContextPressureGate`.\n2. **Run the gate in `chatGenerateOptions`** (`internal/app/archied/main.go`)\n so it decides full-vs-bridge disclosure per turn, and build the\n `core.ToolSet` from the gate's filtered output.\n3. **Thread the model's context window** into the preparation seam so the gate\n has a real `ContextWindowSize` (it disables itself at 0, falling back to\n full disclosure).\n\n## Why the naive \"register extras into the base registry\" is wrong\n\n`BuildToolSetFrom` (`internal/agentexec/toolset.go`) documents the invariant:\n\n\u003e the task tools carry the calling gateway's identity, so there is one set of\n\u003e them per gateway and they **cannot live in the process-wide registry**.\n\nThis is confirmed by wiring: gateways are per-channel\n(`telegram_setup.go` build a `TurnRunner` per channel), and the extra\ntools (`task_*`, `session_*`, `dashboard_*`) close over that channel's identity\nvia `TurnRunnerConfig` (`turn.go`). Registering them into `b.toolReg` would\nlet channel A's session/identity-bound tools be invoked by channel B — a real\ncross-channel privilege bug. The bridge handlers iterate `reg.All()`\n(`disclosure.go`), so the extras must be discoverable; the fix is a\n**per-turn composed registry**, not a mutation of the process-wide one.\n\n## Shape of the change\n\n### 1. Per-turn composed registry + gate inside `chatGenerateOptions`\n\nReplace the current base-set + extra-set merge (`main.go`) with a single\ncomposed-registry pass:\n\n```go\n// new helper, in internal/tools/disclosure.go or the archied wiring package\nfunc ComposeForTurn(reg *tools.Registry, extra []tools.ToolEntry) (*tools.Registry, error) {\n composed := tools.NewRegistry()\n for _, e := range reg.All() {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n for _, e := range extra {\n if err := composed.Register(e); err != nil { return nil, err }\n }\n if _, err := composed.RegisterBatch(tools.BridgeTools(composed)); err != nil {\n return nil, err\n }\n return composed, nil\n}\n```\n\n`chatGenerateOptions` then:\n\n```go\ncomposed, err := ComposeForTurn(registry, extra)\n// ...\ngate := tools.NewContextPressureGate(contextWindow)\ngate.SetAlwaysVisible(...) // e.g. session/session_resume, task/task_list\ndisclosed := gate.FilterTools(composed)\ntoolSet, err := agentexec.BuildToolSetFrom(disclosed, toolOpts)\n```\n\n`FilterTools` (`disclosure.go`) already returns `all` in full mode and\n`bridge + always-visible` in bridge mode, and `BuildToolSetFrom` re-applies\navailability/approval/schema rules, so the two layers compose cleanly.\n\n### 2. Thread context window through the preparation seam\n\n`ContextPressureGate` disables at `ContextWindowSize == 0`. The model context\nwindow is resolved in `TurnRunner.prepareTurn` (`turn.go`) but is not\npassed to `TurnModel.Prepare`. Extend the seam:\n\n```go\ntype TurnPrepareContext struct {\n Model string\n Extra []tools.ToolEntry\n ContextWindow int // model's context window in tokens; 0 = gate disabled\n}\n```\n\n`TurnModel.Prepare(ctx, context TurnPrepareContext)`; `prepareTurn` fills\n`ContextWindow` from `modelDetails.ContextWindow`. This touches one interface\n(`turn.go`), one production impl (`chat_turn_model.go`), and the test\nmock (`turn_test.go`).\n\n### 3. Bridge-handler parity note\n\n`bridgeCallHandler` calls `e.Handler` directly (`disclosure.go`), bypassing\n`toolExecute` — so a `tool_call` invocation does **not** apply `CapPayload` /\n`MaxResultSizeChars` spilling or `OnToolCall` reporting, and it pre-refuses\n`RequiresApproval` tools (`disclosure.go`). This is acceptable for the\nfirst wiring (the bridge is read-discover/describe plus a guarded call), but a\nlater hardening should route the invoked tool through the same\ncap/approval path the model's direct call uses. Recorded as a follow-up, not a\nblocker for this task.\n\n## Files touched\n\n- `internal/app/archied/main.go` — `chatGenerateOptions` composes + gates.\n- `internal/app/archied/chat_turn_model.go` Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/public-and-dev-docs/",
|
||||
"title": "Public and development documentation -- design",
|
||||
"section": "PRDs",
|
||||
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n|---|---|---|---|\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
|
||||
"body": "# Public and development documentation -- design\n\n**Status:** Draft\n**Date:** 2026-09-22\n\n## Problem\n\nOne published set carries both kinds of document. A reader who wants to know\nwhat Archie is and how to point an event at it lands in a sidebar that also\nholds the repository organisation rules, the migration decision register, the\npackage review procedure and five PRDs. The PRDs are there for a reason that\nhas nothing to do with the reader: settled architecture cites them, and the\ngenerator refuses a link whose target it holds back, so publishing them was the\nonly way to keep those citations alive.\n\nMixing them is not an exposure problem. Every one of these documents can be\npublic. It is a navigation problem: a customer reading the site meets\ncontributor material with no signal that it is not for them.\n\n## Decision\n\nOne source tree, two published sets, two artifacts, two URL bases.\n\n| Set | Holds | Served under | Artifact |\n| ----------- | ------------------------ | ------------ | ----------------------------------- |\n| Public | `index.md`, `guides/` | `/docs/` | `docs/data/generated/docs.json` |\n| Development | `architecture/`, `prds/` | `/dev/` | `docs/data/generated/dev-docs.json` |\n\n`archive/`, `inspiration/`, `news/` and `github-token.md` stay out of both, for\nthe reasons the generator already records.\n\nThe two artifacts have the same shape. A renderer reads a second file and\nserves it under a second base; it needs no new field and no set discriminator,\nbecause the file a page arrived in is the set it belongs to.\n\n## Consequences the design depends on\n\n**Every PRD publishes.** Selective PRD publication existed to keep citations\nfrom settled architecture working. With both cited and citing documents in the\ndevelopment set, that pressure is gone, and the rule that produced it goes with\nit: `prds/` is a development tree, not a list of exceptions.\n\n**Cross-set links resolve.** A link from a public page to an architecture page\nrewrites to the development set's absolute path, and the reverse works the same\nway. Both sets are generated in one pass over one url map, so a link and its\ntarget cannot disagree about where the target lives. The generator's refusal\nstill fires, now only for a target genuinely in neither set.\n\n**Assets keep the public base.** `docs/public/` is one file set, referenced\nfrom either set, and serving one file under two paths would invent a second\nlocation for it.\n\n**The sidebar stays derived from the directory layout**, per set. A page added\nunder a directory appears without a second edit, which is the property the\ncurrent generator has and the reason its tree mirrors the tree on disk.\n\n## The public set is thin, and that is the honest state\n\nTwo pages: the landing page and the playbook guide. Nothing is lost by the\nsplit, because a reader was never served by the seventeen architecture pages\nnext to them. The pages a public site needs (installation, configuration\nreference, the event sources, the actions a playbook can run) are written into\n`guides/` and a `reference/` tree as they are written, and each lands in the\npublic set with no generator change.\n\n## Verification\n\n- `task docs:artifact` writes both files; `task docs:artifact:check` fails on a\n stale copy of either, without touching the tree.\n- A link from the public set to a development page, and a link the other way,\n each resolve to the other set's base path in the generated body.\n- A link to a page in neither set fails the generator, naming the file, the\n line and the target.\n- `docsgen` accounts for both artifacts, so neither tool reports the other's\n file as unowned.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/release-stream-and-commit-rules/",
|
||||
"title": "One release stream, one page per version, and commit rules — decision",
|
||||
"section": "PRDs",
|
||||
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
|
||||
"body": "# One release stream, one page per version, and commit rules — decision\n\n**Status:** Draft\n**Date:** 2026-09-22\n**Authority:** `RELEASING.md` for the process this changes, `AGENTS.md` for the\ncommit rules it enforces, and `tools/newsgen` for the artifact shape.\n\n**Supersedes:** `docs/prds/news-and-releases.md`, sections \"Source of truth\" and\n\"Two components\" — one changelog replaces two, and one page per version replaces\none page per component. Its remaining decisions stand.\n\n## Decision\n\n**A release is one version covering whatever changed.** One changelog holds every\nrelease section, one generated page holds every version's notes, and an operator\ncutting a release names one version.\n\n## One changelog\n\nEvery release section lives in `CHANGELOG.md`, newest first. `CHANGELOG.archied.md`\nand `CHANGELOG.archie.md` are deleted, and `CHANGELOG.md` stops being a pointer to\nthem. The changelog is the only source of release prose, and tags are not a source:\nCI and deployment check out shallow, so tags are absent from a site build while the\nchangelog is always present.\n\n### The merged history\n\nTwo version streams become one file, so a version that both components released\ncarries one heading and one date: **the newest date among that version's sections**,\nbecause a version's date is when the last part of it shipped. Where a component's own\ndate differs from it, that component's section label carries its own date, so the\nper-component fact survives the merge rather than being collapsed into the heading.\n\nThe merged history holds 65 versions: 33 that both components released, 31 only\n`archied`, and one only `archie`, from 64 and 34 sections respectively, so 98\npublished pages become 65. `## [Unreleased]` is not a release -- it carries no\nversion and gets no page -- but it stays at the top of the file, because it is\nthe one place unfinished work is recorded. Counting `##` headings rather than\nreleases overcounts by one.\n\nThis ambiguity is historical only. One version stream with one tag gives a version\nexactly one date, so the rule represents the merged past rather than a design that has\nto hold.\n\nThe merge is verified by content, not by the generator succeeding: the section count\nper source, the merged version set equal to the union of both sources with nothing\nextra, and every section title still present. A generator that agrees with the file it\njust wrote is evidence of nothing.\n\n## One version stream\n\n**`GATEWAY` and `RUNTIME` stop being release inputs.** `release:prepare` and\n`release:tag` take one version, and `tools/release.sh` loses the two flags.\n\nThey may stay as build-time stamps, because a binary must still report what it\ncontains. A release that must name three versions forces an operator to pass skip\nvalues for components that did not change, and that ceremony is what this decision\nremoves — along with the drift it allows, where two components' tags fall a release\napart.\n\n**Per-component detail stays, as sections inside the release.** A reader still needs\nto know whether `archied` or the agent changed; what goes away is the separate\nnumbers and the separate pages, not the information.\n\n**History is not re-tagged.** Existing tags keep their names, because tags are not a\nsource and nothing reads them to build a page. A future reader must not \"fix\" the\nunified changelog by rewriting tags to match it.\n\n## One release page per version\n\n`docs/news/\u003cversion\u003e.md` replaces `docs/news/\u003ccomponent\u003e/\u003cversion\u003e.md`, carrying the\nrelease's per-component sections inside it.\n\n**Every release URL already published keeps working.** `/news/archied/\u003cversion\u003e` and\n`/news/archie/\u003cversion\u003e` route to the unified page for that version. The generator\nemits the redirect table beside the pages so it cannot drift from them; if the\nrenderer needs the table in its own repository, that is a change in that repository\nrather than a hand-maintained list here.\n\n## The reviewer runs between prepare and tag\n\nRelease notes are prose, and the review agent exists to review prose. **`release:tag`\nrefuses to tag when the review has not been run for that version, or when it reports\nat the level.**\n\nThe invocation is verified rather than assumed. `tl rules --lint` reports `corpus ok`\nand exits 0. `tl review \u003cpath\u003e --deadline \u003cms\u003e --max-turns \u003cn\u003e` reports\n`0 findings (0 high, 0 medium) · 1/1 files reviewed · clean` and exits 0 on\n`docs/news/archied/1.36.0.md`.\n\n**`--fail-on` must be passed explicitly.** It defaults to `never`, so an invocation\nwithout it cannot refuse anything and the step would be decorative. `--fail-on high`\nis the level: a medium finding in a release note is worth acting on, and it should not\nstop a release on its own.\n\n**The rule is stated once.** It belongs in the reviewer's own rule set, which\n`tl rules --from-doc` can draft frLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/review-calibration/",
|
||||
"title": "Review calibration -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report *nothing*\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
|
||||
"body": "# Review calibration -- decision\n\n**Status:** Draft\n**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)\n\n\u003e Superseded by `docs/prds/pr-review-agent.md`.\n\nDecides the half of calibration `docs/prds/adversarial-self-review.md` left\nopen: \"the adversarial-confirmation mechanism that keeps a finding from\nsurfacing on a single reviewer's say-so.\"\n\n## The problem, precisely\n\nThe shipped contract (`internal/domain/workflow/review_findings.go`, h019.2)\nalready makes only a **confirmed** error-level finding block\n(`Blocking() == Verdict == confirmed \u0026\u0026 Level == error`), and a zero-finding\nreview is already distinguishable from one that never ran (`ReviewStatus`).\nWhat is missing is the other half: a reviewer can report _nothing_\nand say only \"I found nothing\" in free text. The operator cannot tell \"I\nchecked the five things that matter and they are clean\" from \"I did not look.\"\nThat is the failure the epic names -- a findings surface that consumes attention\nwithout earning trust.\n\n## Decisions\n\n### 1. \"Checked and cleared\" becomes structured, not prose\n\n`ReviewReport` gains `Checked []ReviewCheck`:\n\n```go\ntype ReviewCheck struct {\n Property string // what was verified clean, e.g. \"nil-safety of Foo callers\"\n Evidence string // how it was verified, e.g. \"read all 4 callers; each nil-checks\"\n}\n```\n\n`Evidence` is required, for the same reason `ReviewFinding.FailureScenario` is:\na check without evidence is an assertion, and the whole point is to separate a\nverified property from an unexamined one. A zero-finding review is credible\nonly when it lists what it checked.\n\n### 2. Report checks through a typed tool, like findings\n\nThe reviewer calls a new capture tool `record_checked` (mirroring\n`record_finding`) once per property it verified clean. The same environmental\nargument as findings applies: the reviewer cannot end its turn having silently\nskipped the checklist. `ReviewReport.Summary` stays as the human overview.\n\n### 3. Style nits are out of contract\n\nA finding must describe wrong behaviour or a crash. Style, formatting, naming,\nand preference nits are explicitly out of contract -- they are the padding that\ntrains the operator to skim. Stated in the reviewer prompt and in the\n`ReviewFinding` type's own documentation. Not machine-enforced: deciding \"is\nthis a style nit\" from free text is unreliable, and a wrong rejection is worse\nthan a tolerated one. The category enum already has no style bucket; the rule\ncloses the gap that would otherwise let one hide under `other`.\n\n### 4. Surfacing\n\nThe PR-body findings section lists the cleared properties alongside findings,\nso \"ran and found nothing\" arrives with its evidence. (Park reasons keep\nrendering only blocking findings -- what a human needs to act on, not the full\nchecklist.)\n\n## What this does not decide\n\n- Adding a second, independent reviewer pass. The verdict distinction plus the\n recorded checks is the confirmation mechanism; a second model pass is a\n separate, heavier decision and nothing in `h019.5` requires it.\n- How many findings can survive before `MaxSteps` is exhausted (a budget\n question, already satisfied by the per-stage budget).\n\n## Packages this touches\n\n- `internal/domain/workflow` -- `ReviewCheck`, `ReviewReport.Checked`, validation.\n- `internal/app/agentworker` -- `record_checked` tool, prompt rules.\n- `internal/domain/workflow/review.go` -- render cleared properties on the PR body.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/review-settings-resource/",
|
||||
"title": "Review settings resource",
|
||||
"section": "PRDs",
|
||||
"body": "# Review settings resource\n\n**Status:** Draft\n**Beads issue:** `archie-core-0ry6`\n**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,\n`docs/architecture/configuration.md` for ownership, and\n`docs/prds/pr-review-agent.md` for what the two dials do.\n\n## Decision\n\n`review.precision_gate` and `review.approve_before_post` are one control-plane\nresource, `review-settings`. The file's `[review]` section seeds it, the stored\ndocument outranks the file from then on, and the dashboard writes it through the\nsame settings machinery as every other resource.\n\nThe resource is deployment-wide, like every definition the State Store seeds\n(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.\n\n## Why its own kind\n\nThe two dials are pr-review policy — what a review may post, and whether a human\ndecides — not a limit on a task run. The document that carries task limits\nbelongs to that feature. `runtime-control-plane.md` splits settings by feature\nand refuses documents unrelated features share; `configuration.md` puts a typed\nruntime setting with the domain whose behaviour it describes. One document per\nfeature is the rule, not one document per settings page.\n\nA new kind also has no legacy documents. Its first value is the seed derived\nfrom the file, so \"the store outranks the file\" begins from an explicit copy of\nboth fields rather than from a document that predates them.\n\n## Document\n\nNew file `internal/app/controlplane/review_settings.go`:\n\n```go\nconst ReviewSettingsKind = \"review-settings\"\n\ntype reviewSettings struct {\n PrecisionGate bool `json:\"precision_gate\"`\n ApproveBeforePost bool `json:\"approve_before_post\"`\n}\n```\n\nIts `Definition` sets `ApplyMode: \"live\"`, `Document: reviewSettings{}`, and a\n`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,\nand a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field\nrule, so the validator is a named place to put one rather than an inline no-op\n(`validatePluginSettings` is the precedent). No `Normalize`, because the kind\nhas no second wire shape to converge.\n\n## Seeding\n\n`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,\nso a deployment that never edited the dials runs the values in `[review]`. Once\na document is stored, the file key stops mattering, which is the rule for every\ndatabase-owned setting.\n\n## Apply\n\n`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the\nstored document over the file's `Review`, assigning `out.Review.PrecisionGate`\nand `out.Review.ApproveBeforePost` field by field. Field-by-field, not\n`out.Review = ...`: a field added to `config.Review` later keeps the file's value\nuntil the document carries it.\n\n`ReviewSettingsKind` joins `runtimeResourceKinds` in\n`internal/app/archied/control_plane.go`, so a new stored version re-runs the\nlayering and republishes through `config.Holder`. Live rather than\nrestart-required, because every consumer re-reads it: `Review` is on\n`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a\nrun through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →\n`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`\nread. The next task run uses the new value; a run in flight keeps the value it\nstarted with.\n\n## Projection and page\n\n`BuildConfigView` gains a plain `Review` field carrying both values out of\n`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published\nconfig snapshot tells any reader what is in force. The Review page renders the\ntwo toggles from the control-plane store's draft for `review-settings` — the\nshape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows\nthe projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry\n(`ui/src/stores/control-plane.ts`) bind the page to the kind.\n\nNothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`\ngain no `review.*` row: the config catalog's generic renderer was deleted, so a\ndescriptor row adds a field nothing can edit, which is the shape `becb0b5e`\nremoved.\n\n## What the test proves\n\n`internal/app/controlplane/runtime_config_test.go` adds the round trip that\nbuilds the effective config the way boot does: seed the kind from a file config\nwith both dials set one way, store a document with both flipped, layer it\nthrough `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the\nstored document. A second case covers the absent kind, where the file's values\nstay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`\ncarries into the two stages — not on a struct the test set directly.\n`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The\nvalidator needs no `validators_agree_test.goLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/runtime-control-plane/",
|
||||
"title": "Runtime control plane",
|
||||
"section": "PRDs",
|
||||
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten. After migration, settings in TOML are\nignored and cannot block State Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nPlugins can add step types. Each run keeps the workflow version it started with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a Pinia-backed editor in the Web UI;\n- a messaging command using the same API;\n- migration of existing `[budgets]` values;\n- an end-to-end restart test.\n\nRunning tasks keep the limits they started with. New tasks use the latest applied\nversion. This replaces the old settings overlay instead of extending it.\n\n## Not included in the first implementation\n\n- Moving bootstrap or secret values into normal settings.\n- A generic JSON editor.\n- Rebuilding every settings screen at once.\n- Changing the limits of a running task.\n"
|
||||
"body": "# Runtime control plane\n\n**Status:** Approved \n**Date:** 2026-09-20 \n**Tracking:** `archie-core-j28m`, `archie-core-1786637498420-327-bacadaae`\n\n## Outcome\n\nArchie can be managed from the Web UI or a messaging channel. Both use the same\nAPI.\n\n## Model\n\nEach feature owns its settings and commands. The database stores them. There is\nno global configuration document.\n\nThis includes:\n\n- workflows;\n- identities and bindings;\n- providers and models;\n- repository policies;\n- channels and schedules;\n- capture mappings and bindings;\n- tool settings;\n- prompts and personas;\n- plugin settings.\n\nPlugin code remains installed code. Only its settings are stored in the\ndatabase.\n\nEach feature defines its data, validation, permissions, editor fields, and how\nchanges take effect. Each feature also defines its allowed actions. For example,\nidentities can be created, suspended, and retired.\n\nRepository and identity settings remain separate. They are not stored as large\nrecords that unrelated features must share.\n\nThe State Store process hosts the control-plane API on its existing gRPC server.\nNo new process is added. Feature code validates changes. Storage code only\nwrites versions and audit records.\n\nEvery write records who made it, where it came from, a request ID, and the\nversion being edited. The API layer sets the actor; the request body cannot.\nThe server validates the change, then writes it with its audit record. It rejects\nedits to an old version.\n\nThe request ID is the write's idempotency key, and it is scoped per org and\nper kind, never global. The key is `(org_id, kind, request_id)` — the unique\nindex `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)\n— so replaying a request ID is the same org's prior write of the same kind, and\na request ID reused across orgs or across kinds is a separate write. This is the\nsame scoping as the task idempotency key `org/identity/owner/repo/number`\n(`docs/prds/orgs-and-access.md`).\n\n## API\n\nThe API has four operations:\n\n1. **Catalogue** tells clients what can be viewed or changed and how to edit it.\n2. **Query** reads data and versions without exposing secrets.\n3. **Command** asks the owning feature to make a change.\n4. **Watch** streams changes and errors to clients.\n\nComplex features can use custom screens. They still use the same commands.\n\nA dashboard session or channel sender must map to an Archie identity before it\ncan run a command. Messaging syntax maps to the same commands as the Web UI.\n\n`archie-ui` receives only an API client. It does not receive a database handle,\ndaemon pointer, global configuration object, or secret value.\n\nThe database stores the requested settings. Each process reports the version it\nis using or why it failed. The UI shows both.\n\nSome changes require a restart. The UI shows them as pending. When a live change\nreplaces a running component, Archie starts and checks the new one before\nswitching. If the check fails, the old one keeps running.\n\n## Bootstrap, migration, and recovery\n\nBootstrap contains only the database path, listen addresses, credentials, TLS,\nand encryption-key references. State Store and control-plane RPCs use the same\nendpoint.\n\nWhen upgraded, existing instances are migrated to the database. Existing\ndatabase values are not overwritten, with one exception: a resource whose\ndocument the build ships is refreshed when the seed itself wrote the stored\ncopy, because that copy is a previous release's document rather than an\noperator's. After migration, settings in TOML are ignored and cannot block\nState Store startup.\n\nThe Web UI remains available when `archied` or Gateway is down. It shows failed\nchanges and can correct or roll them back.\n\nOffline commands can back up, restore, validate, and roll back the database.\nRecovery does not require `archied` or the Web UI. The database stores secret\nreferences, not secret values.\n\n## Workflows\n\nUsers create and edit workflows in the Web UI. Workflows are stored as versioned\nYAML. Built-in workflows can be overridden and restored.\n\nA workflow is a list of steps. Each step has a known type and its own settings.\nA step type is part of the build's step vocabulary, contributed as a provider at\nthe composition root; interpreted plugins contribute none\n(`docs/prds/workflow-step-vocabulary.md`). Each run keeps the workflow version it\nstarted with.\n\nYaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful\nbehaviour must first be available as normal workflow steps.\n\n## First implementation\n\nThe first implementation makes task limits editable: maximum model steps,\nmaximum runtime, and maximum consecutive gate failures.\n\nIt includes:\n\n- validated task-limit fields;\n- version history and audit records;\n- the four API operations;\n- authenticated Web UI and messaging access;\n- live updates and apply status;\n- a PiLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/self-update-transaction/",
|
||||
"title": "Self-update: artifact install, topology migration, journaled transaction",
|
||||
"section": "PRDs",
|
||||
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update *contract* (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the *next* update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology *observer* to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
|
||||
"body": "# Self-update: artifact install, topology migration, journaled transaction\n\n**Status:** Draft\n\nEpic: `archie-core-hj1t` / GitHub `#804` (\"[EPIC] Self-update: artifact\ninstall, topology migration, journaled transaction\").\n\nThe update _contract_ (`internal/releaseupdate`: `Catalog.Check`,\n`Installer.Install`, plus defer/watchdog/verify) is settled and unchanged by\nthis document — it stays a thin Go interface shelling out to\n`CommandCatalog`/`CommandInstaller`. This document decides what the reference\nadapter scripts (`scripts/archie-update-{check,install,watchdog}`) and\n`install.sh` do behind that contract, and settles the one thing the epic's\nown description got wrong: the dist-zip **is** already attached to GitHub\nReleases (`.github/workflows/deploy.yml`, `gh release upload`), not\nActions-artifact-only. Artifact install is therefore a smaller change than\nthe epic assumed — pointing the installer at an existing asset, not standing\nup new CI publishing. Topology migration and the journaled transaction are\ngenuinely greenfield: no topology-detection or transaction-journal code\nexists anywhere in the tree.\n\nOut of scope: rewriting the `internal/releaseupdate` Go interfaces\nthemselves, and any UI for triggering updates (channel dispatch, e.g.\nTelegram `/update`, is unaffected — this only changes what happens once an\ninstall is triggered).\n\n## Problem\n\n`scripts/archie-update-install:139-160` clones and compiles from source on\nevery update — the only path that exists. `deploy.yml` already publishes a\nper-platform archive plus (implicitly) checksums as a release asset, so the\nscript not using it is a missed-reuse gap, not a missing-CI gap.\n`install.sh:414-445` writes only `archied.service` while every shipped\ndeployment profile (`deployments/*.toml`) declares `[services.state]` and\n`[services.gateway]` sections needing their own units — a fresh install\nalready reproduces the broken single-unit shape `deployment_contract_test.go`\ndoesn't even catch, because that test only checks profile\nsyntax, not installed topology. No code anywhere enumerates which systemd\nunits exist on a host or compares that against what a release requires — the\ndaemon fails at `bootstrap.go`'s `[services.state].target` check with no\nprior diagnosis. The self-refresh trap is confirmed at\n`scripts/archie-update-install:195-199`: new adapter copies land on disk but\nbash keeps executing the in-memory copy, so a pre-flight check added to the\nscript only protects the _next_ update.\n\n## Design\n\n### Artifact install (`#804` item 1)\n\n**Decision.** `CommandInstaller`'s default script downloads the per-platform\narchive plus `SHA256SUMS` from the GitHub Release that `Catalog.Check`\nresolved (the same release `deploy.yml` already publishes to), verifies the\nchecksum, and stages it — it does not clone/compile. Source build\n(`scripts/archie-update-install`'s current clone+compile body) is kept as an\nopt-in path selected by an explicit `--from-source` flag or\n`ARCHIE_UPDATE_SOURCE_BUILD=1` env var, never the default, since a compile-on\nevery-host update is strictly slower and has a larger failure surface than\ndownloading a signed asset that CI already produced.\n\n**Call site.** `scripts/archie-update-install` — replace the clone+compile\nbody with a download-and-verify step; move the existing\nclone+compile body behind the opt-in flag rather than deleting it.\n`internal/releaseupdate/command.go` (`CommandInstaller`) is unchanged —\nit already just shells out.\n\n**Reuse check.** `deploy.yml` already builds and publishes the\narchive and uploads it as both an Actions artifact and a release asset; no\nnew CI work is needed, only pointing the installer at what exists.\n\n**Testing.** Checksum-verification logic is a shell function, testable with\na fixture archive + `SHA256SUMS` pair — add to whatever test harness already\ncovers `scripts/`. Full download-from-real-release is a manual smoke command\n(document the exact `archie-update-check`/`--dry-run` invocation once built),\nnot `task check`.\n\n### Topology migration (`#804` item 2)\n\n**Decision.** Add a topology _observer_ to the daemon, not the shell\nadapter — CLAUDE.md's own \"known trap\" note says the shell copy is defence\nin depth only, and the daemon is what \"knows the deployment and holds the\napproved snapshot.\" The observer inspects which systemd user units exist\n(`systemctl --user list-unit-files 'archie*.service'` or equivalent) and\nwhich config sections are present (`[services.state]`, `[services.gateway]`,\nUI service config), producing an `ObservedTopology` value with one field per\nunit: present/absent, and the config sections backing it. Each release's\n`release.json` (already produced by `deploy.yml` per the artifact-install\nwork above) gains a `required_topology` field naming the units and config\nsections that release's binaries need. `Catalog.Check` compares observed\nagainst requireLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/service-decomposition/",
|
||||
"title": "Service decomposition -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the *processes* running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n|---|---|---|\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/infrastructure/postgres` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n + EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHEL / Ansible Automation Platform\nmodel: one architecture, sold both ways. This PRD does not decide the\nbusiness model; it decides that the architecture must not foreclose\neither shape.\n\n## Why this shape\n\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`\nestablished that Archie's existing domain split already does what AWX's\nservice-decomposition post argues for -- boundaries exist. What didn't\nexist was deployability: `internal/webui` was not a passive frontend. The\nre-baselined coupling inventory is below, and the ratified boundary is\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/).\n\n- Telegram task actions now call Gateway's `ChatContract` directly through\n `chatTaskActorAdapter`; the old Telegram-to-webui HTTP detour is historical.\n- `internal/webui/api_chat.go` now holds `gateway.ChatContract`; direct\n `SessionStore`, `Router`, and `TurnHistory` access is historical.\n- The third coupling is closed. UI extraction shipped (`archie-core-8cda.5`,\n closed 2026-09-11): `cmd/archie-ui` serves the dashboard against remote\n Gateway and State StoreLine truncated
|
||||
"body": "# Service decomposition -- decision\n\n**Status:** Draft\n**Date:** 2026-09-05\n**Beads epic:** archie-core-8cda\n**Prior art:** `docs/inspiration/2026-09-05-awx-service-decomposition-and-ansible-task-model.md`,\n`docs/inspiration/module-reference-awx-decomposition-vs-archie.md`,\n`docs/inspiration/service-discovery-research-2026-09-05.md`,\n`/work/artefacts/archie-core-current-state-archify.html`,\n`/work/artefacts/archie-core-ideal-state-archify.html`\n\nThe Phase 3 UI boundary and configuration decision is ratified in\n[`ui-service-boundary.md`](/dev/prds/ui-service-boundary/). That focused document is\nthe implementation authority for `archie-core-8cda.5.2`; this parent remains\nthe broader service-distribution proposal.\n\n## Decision\n\narchie-core moves from one Go binary (`archied`) hosting every domain\nin-process to a set of independently deployable services, each exposing\nexactly one typed contract. Consumers depend on the contract; they never\nreach into another service's internal types, session state, or config.\ngRPC is the synchronous transport; NATS remains for asynchronous fan-out\n(status, telemetry) rather than being replaced.\n\nThis is a **distribution decision**, not a rewrite of Archie's domain\nmodel. The six-domain split already approved in\n`docs/architecture/index.md` and `docs/architecture/organisation.md`\n(Identity, Agent, Messaging, Workflow, Work Intake, Plugin) is unchanged;\nthis PRD is about how the _processes_ running that domain logic get\npackaged, contracted, and discovered -- not about redrawing domain\nboundaries.\n\n### Target services\n\n| Service | Contract it owns | Existing code it replaces/wraps |\n| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |\n| UI Service | thin client only; talks to Gateway and State Store contracts | `internal/webui` (SPA hosting stays; API surface becomes typed contract clients, not a peer with direct access) |\n| Gateway Service | routing / turn / session contract | `internal/gateway` |\n| Messaging Service | channel-plugin contract (Telegram, email, Discord, Teams, ...) | `internal/channels` |\n| Curator Service | curator contract; **optional**, installs as a Gateway plugin | `internal/domain/curator` |\n| Scheduler Service | cron/ticker contract | `internal/domain/scheduling` |\n| Execution Environment | execution-dispatch contract | `internal/domain/workflow`, task dispatch paths |\n| Runner | isolated worktree/container execution | `internal/container`, `internal/agentexec`, `internal/worktree` |\n| State Store | state-access contract | `internal/infrastructure/postgres` |\n\n### Discovery\n\nPer `docs/inspiration/service-discovery-research-2026-09-05.md`:\n\n- **Primary:** Kubernetes-native discovery (Service + headless-Service/DNS\n - EndpointSlice, served by CoreDNS), delivered as a Helm chart + Operator,\n on k3s for single-host installs and a real cluster for multi-host or a\n hosted offering.\n- **Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV\n registry) for no-K8s single-host installs, with a custom gRPC resolver\n reading `host:port` from the KV bucket.\n- Both implementations sit behind one internal interface:\n\n ```go\n type ServiceRegistry interface {\n Resolve(service string) []Endpoint\n Watch(service string) \u003c-chan Event // join/leave\n }\n ```\n\n- An optional service (Curator; others later) that is not installed\n must resolve to a distinct `NotInstalled` outcome, never a `Down`/\n `Unhealthy` one. Under K8s this falls out of DNS returning no record;\n under the NATS fallback it requires an explicit \"installed\" marker in the\n KV registry, not just absence-implies-down.\n\n### Distribution model this supports\n\nBoth self-hosted (customer runs the Helm chart or the NATS-fallback\nbinaries themselves) and a managed/hosted offering (we run the same Helm\nchart) are in scope -- this is the RHELine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/service-registry/",
|
||||
"title": "Service registry — one declaration per service",
|
||||
"section": "PRDs",
|
||||
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n|---|---|---|\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\n- A typo'd `[services.gatway]` is **reported** (`UnknownKeys = [services.gatway,\n services.gatway.target]`), because the struct form leaves it in `toml.MetaData.Undecoded()`.\n A map decodes any section, so preserving that is a requirement, not an optional extra:\n `unregisteredServiceKeys` asks the registry which names exist. This costs nothing in\n extensibility, because the answer comes from registration data rather than a fixed list.\n TheLine truncated
|
||||
"body": "# Service registry — one declaration per service\n\n**Status:** Draft\n**Supersedes:** `state-store-contract.md` §10's `State ServiceConnection`\nstruct-field instruction.\n\n**Base:** the `listen` field, `internal/app/archied/listen.go`, and the listen defaults cited\nbelow exist on `feat/attempt-attribution`, not on `main`. This design therefore lands on top of\nthat branch: `RegisterService`'s `listen` argument has nothing to carry without it.\n\n## Problem\n\nA service is already one Go type, `config.ServiceConnection`. What is duplicated is its\n**name**, in three layers:\n\n| Layer | Location | What is hard-coded |\n| ----------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |\n| Declaration | `internal/config/services.go` | `Gateway` and `State` as struct fields |\n| Defaulting | `internal/infrastructure/configuration/defaults.go` | three `if cfg.Services.X.Y == \"\"` branches |\n| Consumption | `internal/app/archied/{bootstrap.go,state_store.go,gateway.go}`, `internal/app/archieui/config.go` | `cfg.Services.State` / `cfg.Services.Gateway` field access |\n\nAdding a service means editing all three. The drift this permits is already visible:\n`stateStoreResolvedToken` (`state_store_client.go`) and `gatewayResolvedToken`\n(`chat_service.go`) are byte-identical apart from the env var name, and\n`gateway.Target` is defaulted while `state.Target` is a startup error, with nothing\nstating that asymmetry in one place.\n\n`resolveServiceListen(service, flagValue, configured)` (`listen.go`) is already\nname-parameterised. It is the shape the rest should follow.\n\n## Decision\n\n**Key services by name, and carry per-service asymmetry as registration data.**\n\n### 1. Declaration collapses to a map\n\n```go\n// internal/config/services.go\ntype Services map[string]ServiceConnection\n```\n\n`ServiceConnection` is unchanged. The TOML shape is unchanged, so no deployment profile,\n`config.example.toml`, or `install.sh` edit is required. An unrecognised `[services.foo]`\ndecodes without a code edit, satisfying criterion 5.\n\n### 2. Registration is the single entry point\n\n```go\n// internal/config/servicespec.go\nfunc RegisterService(context, name, target, listen, tokenEnv string)\n```\n\nregistered once per service, at package init in `internal/config`:\n\n```go\nRegisterService(\"both\", \"gateway\", \"127.0.0.1:8585\", \"127.0.0.1:8585\", \"GATEWAY_TOKEN\")\nRegisterService(\"client\", \"state\", \"\", \"127.0.0.1:9090\", \"STATE_STORE_TOKEN\")\n```\n\nPositional, five strings, as the story specifies. Each argument is data the current code\nstates in prose or in a branch:\n\n- `context` is `client`, `server`, or `both`, and decides which fields must resolve\n non-empty. `RegisterService` enforces it: an unknown context, or a hosted service with\n no default `listen`, panics at registration. Registrations come from this repository's\n own `init()`, never from operator input, so an invalid one is a programming error with\n no caller positioned to handle an error return. A documented-but-unread `Context` would\n be worse than no field at all.\n- `target` is the **default**, and an empty default means the operator must supply one.\n That single convention replaces the `state.target` required / `gateway.target` defaulted\n asymmetry with no branch: `state` registers `\"\"`, `gateway` registers an address.\n- `listen` is the default listen address, feeding the existing\n flag → `[services.\u003cname\u003e].listen` → default precedence unchanged.\n- `tokenEnv` names the fallback env var, replacing the two copied resolvers with one.\n\n### 3. Defaulting and consumption become loops and lookups\n\n`applyDefaults` iterates the registry instead of naming services. Consumers read\n`cfg.Services.Get(\"state\")`, returning a `ServiceConnection` plus the spec, so\n`stateStoreResolvedToken` and `gatewayResolvedToken` collapse into\n`Services.ResolvedToken(name, secrets)`.\n\n## Criteria satisfied\n\n1. Declared once, in the `RegisterService` call.\n2. No second location can contradict it; the map has no per-service fields to disagree with.\n3. Registration is the entry point, with the five fields a service has.\n4. A new service is one `RegisterService` line: no field, no default branch, no consumer edit.\n5. The set of services is registry data, not a struct definition.\n\n## Scope and risk\n\n- `state-store-contract.md` §10 must be revised in the same change, or the tree contradicts\n its own ratified authority. Its summary (`:7`) already says `[services.\u003cname\u003e]`.\nLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/session-memory-curator/",
|
||||
@@ -466,55 +496,85 @@
|
||||
"url": "/dev/prds/skill-curator/",
|
||||
"title": "Skill curator (reference implementation) -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is *reporting*\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval Line truncated
|
||||
"body": "# Skill curator (reference implementation) -- decision\n\n**Status:** Approved\n**Date:** 2026-09-02\n**Beads issue:** `archie-core-1786637499206`\n**Parent epic:** `archie-core-1786637500725` (curator engine)\n\n## Decision\n\nThe skill curator's v1 scope is **mechanical validation and safe\nnormalisation only** -- it never rewrites skill prose, never deletes a\nskill, and never calls the model. Each pass:\n\n1. Lists every skill under one configured root.\n2. Reads each `SKILL.md` and attempts to parse its frontmatter\n (`internal/skill.Parse`).\n3. Records an `Action` for any structural problem: a parse failure, or a\n missing `name`/`description` in the frontmatter that parsed.\n4. Normalises trivial whitespace (trailing whitespace per line, exactly\n one trailing newline) and writes back **only** when normalisation\n actually changes the bytes, recording an `Action` for that write.\n\nNothing here needs judgement. \"Review, prune, and improve\" -- the epic's\nframing -- is real for v1 but deliberately narrow: review is structural\nvalidation, improve is whitespace normalisation, and prune is _reporting_\na problem, never removing a skill. `Manifest.Skills = true` still marks\nthis curator agentic (existing `agentic()` rule), so it receives model\naccess from the registrar -- unused but nothing about the contract\nor the runtime needs to change to let a later version reason about\ncontent quality using it.\n\n## Why this scope, not more\n\nAn autonomous process that rewrites or deletes a user's skill content\nis a real risk with no undo path (no draft/approval flow for\ncurator writes exists yet, unlike the workflow engine's PR-based review).\nThe epic's own stated purpose for this issue is proving the curator\ncontract holds for a second, structurally different consumer than the\nsession-memory curator (files-as-skills vs. observations-as-memory), not\nsolving \"what makes a skill good.\" Mechanical validation is real,\nuseful, safe to run unattended, and fully exercises\nList/Read/Write -- every method `curator.SkillStore` declares except\n`Delete`, which this curator's Pass never has a safe reason to call in\nv1 (kept implemented on the store adapter regardless, since the\ninterface requires it and a future consumer may).\n\n## Why `internal/skill` isn't `curator.SkillStore` directly\n\n`internal/skill.Discover` parses every `SKILL.md` under a root and\nreturns an error for the **whole** call if any one of them fails to\nparse -- the read side was built for \"load the catalogue to start the\ndaemon,\" where one bad skill failing the whole boot is arguably correct,\nnot for \"review each skill and report what's wrong with it\nindividually.\" A per-skill parse failure must become one `Action`, not\nabort the pass before any skill is reviewed. So\n`internal/infrastructure/skillcurator` gets its own thin store adapter\nthat lists raw directory names and reads/writes raw `SKILL.md` bytes\nper name; the skill curator itself calls `internal/skill.Parse` on each\none, isolated per skill.\n\n## Root scope\n\nOne root only, resolved the same way `loadWorkflows` already resolves\n`skillsBase` (`cfg.SkillsDir`, falling back to `cfg.WorkDir`) -- not\nevery root `skill.CatalogRoots`/`DefaultRoots` would read for a model\n(which layers a shared dir over the per-profile one). Write and Delete\nneed one unambiguous target; a curator that could write into a shared,\nmulti-tenant skills directory is a bigger decision than this issue\ncovers. The model still sees the full multi-root catalogue through the\nexisting read path -- this curator only maintains the local one.\n\n## Shape\n\n### `internal/infrastructure/skillcurator/store.go`\n\n```go\n// Store implements curator.SkillStore over one root directory's\n// .agents/skills/*/SKILL.md files, tolerating a per-skill parse failure\n// as the curator's problem to report rather than this store's problem\n// to abort on.\ntype Store struct { root string }\n\nfunc NewStore(root string) *Store\n\nfunc (s *Store) List(ctx context.Context) ([]curator.SkillRef, error)\nfunc (s *Store) Read(ctx context.Context, name string) (curator.Skill, error)\nfunc (s *Store) Write(ctx context.Context, sk curator.Skill) error\nfunc (s *Store) Delete(ctx context.Context, name string) error\n```\n\n`Read` best-effort parses frontmatter for `Skill.Description` (empty on\nparse failure -- not this method's job to report that; `Pass` does, via\nits own `skill.Parse` call on `Skill.Content`). `Write` rejects a name\nthat does not already exist as a directory (this store curates existing\nskills; creating a new one is out of scope). `Delete` removes the whole\nskill directory, matching \"delete a skill,\" not just `SKILL.md`.\n\n### `internal/infrastructure/skillcurator/skillcurator.go`\n\n```go\n// Curator implements domain/curator.CuratorEngine. See\n// docs/prds/skill-curator.md for what a pass does and why.\ntype Curator struct { /* unexported: registrar view, interval *Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/soul/",
|
||||
"title": "SOUL: an agent's user-authored personality",
|
||||
"section": "PRDs",
|
||||
"body": "# SOUL: an agent's user-authored personality\n\n**Status:** Draft\n**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;\n`docs/prds/orgs-and-access.md` for identity and org ownership.\n\n## Decision\n\nSOUL supplies an agent's name, register and warmth. It belongs to the agent's\nimmutable `IdentityID`, not its session, model, installation or container\nprofile. Rename preserves it; changing a profile does not change who acts.\nSOUL never changes attribution, credentials, grants or identity lifecycle.\n`config.AgentProfile` remains an execution environment, not another identity.\n\nUse the existing three layers: invariants, user-authored SOUL, and curator-derived\nrepresentation. Curators may propose SOUL changes but never apply them.\n\n## Files and ownership\n\nThe config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory\nof an explicitly selected config file. The default/root agent uses `SOUL.md`\ndirectly there; additional agents use `agents/\u003cidentity-id\u003e/SOUL.md`. The root is\nthe identity selected by application composition, never the initiating user or\na session's personality selection. No file creates or selects an identity.\n\nThe common case keeps a human-friendly filename; additional agents get separate\nasset directories, following `.agents/skills/\u003cname\u003e/SKILL.md` without confusing\nthese directories with `[containers.profiles.\u003cname\u003e]`. Reject display-name or\nslug directories: rename and same-name agents across orgs would require another\nname-resolution rule. Immutable IDs avoid both problems without an org directory.\n\nWhen a file-owned agent's file is absent, create the shipped default with\nexclusive creation. Never overwrite an existing file, including an empty one.\nA creation failure still permits the turn using the embedded shipped default.\nShip that document independently of `agent.ShippedPersonas`, so deleting personas\ncannot delete the fallback.\n\nResolve once at the start of every new generation:\n\n1. A stored SOUL entry for the acting identity is authoritative.\n2. Without an entry, read that identity's file again.\n3. An absent, empty, unreadable or invalid selected source uses the shipped default.\n\nThe first explicit dashboard/API save takes ownership permanently. Thereafter\nfile edits are ignored: emit one ownership notice and show the owning stored\nversion in the dashboard. Restoring the shipped default writes a stored value;\nit does not remove ownership. Refuse writes that remove an owned entry.\n\nThis ownership boundary is the design's one stateful rule. Files seed the\neditable value, not an automatic durable import. Reject seed-once import because\nit breaks next-message file editing; reject file-always-wins because it makes\ndashboard saves ineffective. Neither a restart nor an upgrade overwrites an\nowned value, following the precedence of `controlplane.AgentProfileKind` without\ncopying its startup import timing.\n\n## Prompt and failure contract\n\nKeep `archie.md.tpl`'s XML-escaped\n`\u003csoul purpose=\"identity_and_style\" trust=\"data\"\u003e` block before\n`\u003cinstruction_precedence\u003e`. SOUL is style reference data; the invariant sections,\ntool inventory and runtime metadata remain authoritative and uneditable.\nPreserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.\n\nAccept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds\npersonality to a small prompt contribution; count the complete rendered prompt\nin the turn's context budget and never truncate invariant sections. Bound file\nreads before decoding; reject oversize input rather than truncating instructions.\nFile and stored writes use the same validator; an invalid save leaves the stored\nversion unchanged. The shipped default must pass that validator.\n\nRead and creation errors never fail a turn. Log once per identity/source failure\nepisode, retry on the next turn, and allow a new warning after recovery. If the\nstore cannot establish whether an owned entry exists, use the shipped default,\nnot a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved\nsnapshot; edits affect the next generation without restart or SIGHUP.\n\n## Cross-layer delivery\n\n- `internal/domain/agent` owns SOUL content validation and the identity-keyed read\n contract; `internal/domain/identity` remains the actor/lifecycle authority.\n- The configuration infrastructure resolves the config directory and handles\n file discovery, exclusive default creation and bounded per-turn reads.\n Application composition resolves the acting `IdentityID` through the existing\n identity repository/bindings and supplies it to the gateway.\n- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor\n and an org-scoped document mapping identity IDs to `{text}`. Persist it through\n the State Store's existing resource/history contracts, not a new table,\nLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/state-store-contract/",
|
||||
"title": "State Store — contract boundary \u0026 transport (ratification)",
|
||||
"section": "PRDs",
|
||||
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalise\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Storage superseded.** The store behind this contract is PostgreSQL:\n\u003e `internal/infrastructure/postgres` implements the producer-owned interfaces in\n\u003e `internal/domain/storecontract` and `workflow.Store`, over the database\n\u003e `database_url` names. `internal/store`, the SQLite file and the local adapter\n\u003e are gone; where this document says `archie.db`, `*store.Store` or\n\u003e `internal/store`, read the State Store's PostgreSQL database and\n\u003e `internal/infrastructure/postgres`. The contract, ownership split, error\n\u003e semantics and cutover rules stand.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n\u003e 4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\n\u003e migration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\n\u003e StepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's *layer*, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consuLine truncated
|
||||
"body": "# State Store — contract boundary \u0026 transport (ratification)\n\n**Status:** Approved\n**Revision:** 2e\n**Date:** 2026-09-06\n\nThis is the pre-implementation design document that Phase 2 subtasks `.4.2` (generalise\n`storerpc` as the State Store gRPC contract) and `.4.3` (stand up `archie-state-store`)\nimplement against.\n**Beads milestone:** archie-core-8cda.4.1\n**Parent:** `docs/prds/service-decomposition.md` (open-question Q4 **RESOLVED**)\n\nThis document fixes the **contract boundary** and **transport** for the State Store service.\nIt does not redesign Archie's domain model, does not invent a second store, and does **not**\nsplit `archie.db`. It records method ownership, DTO/wire representation, error semantics,\nlimits, mode/config shape, local-adapter compatibility, and cutover/deletion rules so that\n`.4.2` and `.4.3` have exactly one authoritative surface to build against.\n\n\u003e **Storage superseded.** The store behind this contract is PostgreSQL:\n\u003e `internal/infrastructure/postgres` implements the producer-owned interfaces in\n\u003e `internal/domain/storecontract` and `workflow.Store`, over the database\n\u003e `database_url` names. `internal/store`, the SQLite file and the local adapter\n\u003e are gone; where this document says `archie.db`, `*store.Store` or\n\u003e `internal/store`, read the State Store's PostgreSQL database and\n\u003e `internal/infrastructure/postgres`. The contract, ownership split, error\n\u003e semantics and cutover rules stand.\n\n\u003e **Current state — read before `.4.2` starts.** The §12 step 2 relocation (`archie-core-8cda.\n4.8`) has landed: `Task`/`Status*`/`Source*` and the 3-method `workflow.Store` now live in\n\u003e `internal/domain/workflow`, the six production workflow files import no `internal/store`\n\u003e symbol, and `storerpc`/the NATS transport assert against `workflow.Store` instead of\n\u003e `store.WorkflowStore`. The broader Phase 2 acceptance criterion (State Store as its own\n\u003e service behind gRPC) is still open — that is what `.4.2`/`.4.3` build next.\n\n\u003e **Relationship to migration-decisions §4 — not replaced.** `docs/architecture/\nmigration-decisions.md` §4 (`store.Task → WorkflowExecution`, `mutable Stage →\nStepExecution history`, `RetryCount/Attempt → Attempt records`, versioned Workflow defs)\n\u003e **remains the authoritative, open document for the long-term Workflow migration.** This PRD\n\u003e does **not** replace it. It only pulls the minimal `Task`/`Status`/`Source` type + interface\n\u003e relocation forward as a Phase 2 prerequisite (because the acceptance criterion requires it);\n\u003e the rest of §4 stays its own migration and stays open.\n\n---\n\n## 1. Decision (the invariant everything follows)\n\nArchie is composed such that a single **`archie-state-store`** service owns the one existing\nSQLite file (`archie.db`) and exposes it over **gRPC behind narrow typed contracts**. There is\nexactly one store, one file, one service. No database-per-service, no distributed\ntransactions, no second store abstraction.\n\nTwo adapter families satisfy the contract interfaces:\n\n- **Local adapter** — `*store.Store` (the in-process SQLite implementation).\n- **Remote adapter** — `*staterpc.Client` (wraps the generated gRPC client).\n\nEach adapter carries an explicit compile-time assertion against the contract interfaces it\nserves. Composition picks local vs. remote by the presence of `[services.state].target`\n(empty = local; set = dial the gRPC service). Default is **local** (the State Store is not yet\nextracted), which is the PRD §3 posture; it differs from the gateway's remote-default only\nbecause the gateway is already a separate deployment and the State Store is not.\n\n\u003e **Contract-ownership fork, decided (rev. 2c — resolves the domain contradiction).**\n\u003e Ownership splits by the consumer's _layer_, per the dependency contract's rule #2\n\u003e (\"a domain defines the smallest interfaces required to perform its work\") and rule #7\n\u003e (\"database rows … MUST NOT leak into domain models\"):\n\u003e\n\u003e - The **workflow domain** (`internal/domain/workflow`) is the only domain-layer consumer of\n\u003e store state. It defines its own **consumer-owned** narrow `Store` interface\n\u003e (Update/Transition/InsertEvent) and its own **domain-owned** `Task` type plus\n\u003e `Status`/`Source` vocabulary. It imports **zero** `internal/store` symbols — satisfying the\n\u003e Phase 2 acceptance criterion. This is the minimal bound of migration-decisions §4\n\u003e (`store.Task → WorkflowExecution`), pulled forward **because** the acceptance criterion\n\u003e requires it.\n\u003e - The **daemon / webui / intake** store surfaces (`TaskStore`, `CaptureStore`,\n\u003e `MappingStore`, `BindingStore`, `BindingDispatcher`, `BindingTaskCreator`) stay\n\u003e **producer-owned** in `internal/store`, because those consumers are application Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/status-health-surface/",
|
||||
"title": "/status health surface",
|
||||
"section": "PRDs",
|
||||
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemised per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favour of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass *began*; both poll paths (`poll` for sLine truncated
|
||||
"body": "# /status health surface\n\n**Status:** Finalised\n**Beads issue:** `archie-core-wp9s`\n\nA reported field must have a truthful source. `/status` reports broker\nconnectivity and the last chat-model call; the container pool, last poll and\nchannel state have no source in the process that answers the command, so they\nare left out rather than faked.\n\n## Background\n\n`archie-core-wp9s` (\"/status and /tasks have the wrong division of labour\")\nasked for two things: `/tasks` owning the live per-task work view, and\n`/status` owning daemon health -- \"broker connectivity, provider\nreachability, channel state, container pool, queue depth, last poll,\nversion\" -- with neither duplicating the other or static config available\nelsewhere (`/model` already lists active provider/model).\n\n## Phase 1\n\n- `/tasks`: new command, `gateway.ChatTaskSummary` extended with\n `Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on\n `store.Task`, zero new instrumentation), sorted actionable-first.\n- `/status`: itemised per-status task counts replaced with one aggregate\n `Queue: N in flight (...)` line (running/waiting/parked only -- queued and\n terminal states excluded as not a health concern). Runtime\n (provider/model) is temporarily left in place; see \"Runtime (provider/model)\"\n under Phase 2's \"Truthful or absent\" for where that stands now.\n\nNot touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,\npre-existing command that already has the right shape for \"list active\nwork\" but is never wired to a real implementation in any composition-root\ncall site (`bootstrap.go`, `telegram_setup.go`) -- it always answers \"Agent\nlisting is not configured.\" in production. That is a standalone bug\n(`archie-core-mxls`), not folded into this work: deciding whether to wire\nit, repurpose it, or delete it in favour of `/tasks` is Sam's call, not\nsomething to resolve by implication here.\n\n## Phase 2 -- health checks, verified against the actual tree\n\nEach bullet below was checked against real code before being called cheap\nor not; nothing here is guessed. Both open questions were settled (see \"The two\ndecisions\"). The health section reports the broker connection and the last\nchat-model call; the three facts the answering process cannot see are covered\nunder \"Truthful or absent\".\n\n### Verified as cheap against the tree\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`\n already exposes `CoreConn() (*nats.Conn, error)`\n (`client.go`). The underlying `nats.Conn` (nats.go) has its own\n `Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few\n lines.\n- **Container pool.** `container.Pool` already tracks `active int` under\n its own mutex (`pool.go`) but has no public accessor. A\n `Pool.Active() int` getter is a few lines.\n- **Last poll.** Nothing tracks this. The daemon's poll loop\n (`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or\n mutex-guarded, matching the pool's own pattern) set at the top of each\n poll tick, with a getter.\n- **Queue depth.** Covered by Phase 1.\n\n### The two decisions\n\n- **Provider reachability is last-known outcome, never a live probe.** A chat\n command must not perform a blocking network call in its handler, and a probe\n reports the probe's reachability rather than the daemon's. `/status` therefore\n prints what actually happened -- the last chat-model call's model, age and\n error, or \"no calls attempted yet\" when there has been none. Implemented as\n `providerOutcomeRecorder`, written once in `sendChatTurn` (the single point\n every chat-model call in the process passes through) and read back by\n `newStatusHealth`. Nothing on this path dials a provider. The existing live\n model reachability check (`readiness.go`'s `modelReachProbe`) is unchanged and\n stays where it belongs: on `/health/detailed`, off the chat path.\n- **Channel state comes from the existing ChannelManager.** `/status` reads\n `status.Manager.Snapshot()` -- the same ledger the dashboard and the readiness\n probe already use -- rather than re-deriving channel health from each adapter.\n No method was added to the `Channel`/`Gateway` contract.\n\n### Phase 2\n\n- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client` gained\n `Connected() bool`, which reads the connection the process already holds. The\n standalone Gateway (which dials NATS itself for task actions) reports the same\n fact from that connection.\n- **Container pool.** `container.Pool.Active()` and `Pool.Cap()` read the pool's\n own counter and configured `max_concurrency` -- not a Docker listing, which\n would include containers this pool does not own. A cap of zero means\n unlimited, so `/status` renders the count alone rather than \"1/0 active\".\n- **Last poll.** `daemon.Daemon.LastPollAt()` reports when the most recent poll\n pass _began_; both poll paths (`poll` for sLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/store/",
|
||||
"title": "Store",
|
||||
"section": "PRDs",
|
||||
"body": "# Store\n\n**Status:** Approved\n**Authority:** `docs/architecture/plugins-and-extensions.md`; supersedes\n`docs/prds/extensions-center.md`, whose installed-inventory states are\nadopted below.\n**Compounds with:** `docs/prds/external-agent-harness.md` (harness Kits),\n`docs/prds/pr-review-agent.md` (the first package).\n\n## Decision\n\nOperators get capabilities from a store: browse, install, update and remove\npackages from the dashboard, with no config file editing. A package is an\nOCI image in a registry. A store catalogue is a list of package references.\nInstalling pins a digest. Every package declares the authority it needs, and\nan update that asks for more stops for the operator's approval.\n\n## Packages\n\nTwo kinds, both ordinary OCI images:\n\n- **Harness Kits.** Kit v3 images, resolved as\n `docs/prds/external-agent-harness.md` decides. Their authority is their\n Kit permission surface.\n- **Archie packages.** An image whose manifest annotation\n `dev.archie.package.v1` carries the descriptor and whose single layer\n carries files. A package contributes any of: workflow definitions,\n prompts, skills, MCP server definitions, and default settings for them.\n\nArchie packages are declarative. They carry no Go, Yaegi or script code that\narchie executes on the host. Anything that runs code ships as a Kit and runs\nin a sandbox. An archie package that references a Kit names it by digest,\nand installing the package installs the Kit.\n\nThe descriptor declares: display name, description, version, the families\nit contributes, the packages it requires, and its authority.\n\n## Authority\n\nA package's authority is the set of grants it needs to work:\n\n- credential services (from its Kits and MCP servers);\n- egress hosts (from its Kits);\n- forge permissions its workflows use: read, comment, review, push, open\n pull request;\n- triggers it registers: watched-repository events, schedules;\n- tools it enables for agents.\n\nInstall shows this list and records the operator's acceptance against the\ndigest. An update whose authority is equal or narrower applies under the\npackage's update policy. An update whose authority is wider waits for\napproval, showing only what widened. Nothing a package does at runtime can\nexceed its accepted authority: archie checks forge actions, triggers and\ntool grants against it, and the egress proxy enforces the Kit's grants.\n\n## Catalogues\n\nA catalogue is an OCI artifact listing package references with digests,\nsigned by the catalogue's key. Archie ships with the default catalogue and\nits public key configured. An operator can add catalogues, for example a\nprivate registry, by reference and public key. A catalogue without a key is\nrefused unless the operator marks it unsigned, which the dashboard shows on\nevery package it supplies.\n\nInstall and update verify the catalogue signature and the package digest.\nArchie never installs a tag it has not resolved to a digest through a\nverified catalogue.\n\n## Organisations\n\n`docs/prds/orgs-and-access.md` is the boundary, and the store follows its\nsplit between the instance and each org.\n\n- **Instance.** Catalogues and their keys are instance configuration, set by\n instance admins. Every org browses the same catalogues.\n- **Org.** Installing, updating, removing, accepting authority and setting the\n update policy are org actions. An installed package, its pinned digest and\n its accepted authority belong to one org. Two orgs can run different\n versions of one package.\n- **Contributions** become org resources: workflows are org workflows,\n profiles are org profiles, and credential bindings name org secrets. A\n workspace uses them only once the org grants them to it.\n- **Authority is an upper bound, not a grant.** Accepting a package's\n authority permits the package to ask; the workflow's identity must still\n hold each grant. A package never creates, grants to or widens an identity.\n- Install and authority acceptance are the `create` and `approve` actions on\n the package, decided by the Authorizer. Org approval policy decides who may\n accept, and no member accepts authority they asked for.\n\n## Install, update, remove\n\n- Installed packages, their pinned digests, accepted authority and update\n policy are org resources in the State Store. They apply without a restart.\n- **Update policy** per package: `manual` (default) or `auto`. `auto` applies\n non-widening updates when the catalogue lists them; widening updates always\n wait.\n- **Setup.** A package whose authority includes a credential with no binding\n installs as `needs_setup`, and links to the binding form or the harness\n setup terminal. Its triggers do not fire until setup completes.\n- **Remove** stops its triggers, removes its contributions, and leaves any\n credential bindings for the operator to delete. A package another\n installed package requires cannot be removed first.\n- Rolling back reinLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/task-logs-pagination/",
|
||||
"title": "task_logs pagination and bounded retrieval -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a *cursor-paginated, filterable* bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
|
||||
"body": "# task_logs pagination and bounded retrieval -- decision\n\n**Status:** Approved\n**Date:** 2026-08-26\n**Beads issue:** `archie-core-vq92`\n**Compounds with:** `archie-core-p1bl` (errors serialise as `{}`)\n\n## Decision\n\n`task_logs` becomes a _cursor-paginated, filterable_ bounded read, not a\none-shot head-of-file window. The reader in `internal/logging` gains a\nsecond entry point (`Page`) that walks the file forward from a byte\noffset; the tool schema in `internal/gateway/task_tools.go` surfaces\nlevel, time-range and cursor parameters; the response carries an explicit\n\"more available\" signal so a model can either keep paging or hand the\nrest to `send_file` when the operator wants a complete archive.\n\nWe do NOT add an unbounded read path. A single response is still capped at\n`MaxTailLines` (2000) entries. What changes is that pagination makes the\ncap reachable in practice instead of silently terminal.\n\n## Why now\n\n`archie-core-vq92` is the right place to fix this: the chat tool is the\nuser-visible failure mode, but the same defect propagates to every caller\nof `internal/logging.Tail` (`internal/webui/api_logs.go` and the\n`chatTaskLogReaderAdapter` in `cmd/archied/main.go`). Patching the\nreader and the tool together is one change in two layers, not two\nchanges; CLAUDE.md's \"package owns its format end-to-end\" rule means the\nreader is the right place for cursor support regardless.\n\nThe compound with `p1bl` matters: a truncated window of uninformative\nerrors leaves an operator with nothing. Cursor pagination lets the model\nwalk the whole file when a level filter does not narrow enough, and the\nresponse's \"more available\" signal means it can honestly say \"I read N of\nM and stopped there\" instead of presenting the head as complete.\n\n## Shape of the API\n\n### Reader (`internal/logging`)\n\nAdd a second entry point next to `Tail`:\n\n```go\n// Page walks the log forward from cursor (a byte offset; 0 starts at\n// the beginning of the scanned window), applying the same filters as\n// Tail. PageResult.Cursor is the file offset just past the last line\n// the walk returned; pass it back as Cursor to continue, and stop when\n// MoreAvailable is false.\nfunc Page(path string, q Query, cursor int64) (PageResult, error)\n```\n\n`PageResult` carries `Entries`, `Truncated` (the existing meaning --\nolder entries exist that were not examined within `maxScanBytes`),\n`Cursor` (the byte offset the next page should resume from), and\n`MoreAvailable` (true iff the scan saw more matching entries beyond the\nreturned page within the same call).\n\n`Cursor` is a byte offset rather than an entry ID for two reasons.\nFirst, `TaskSink` writes JSONL through `slog.NewJSONHandler` directly --\nwithout routing through `FeedHandler` -- so the on-disk entries carry no\n`id` field and a per-task attempt monotonic counter would require\neither a sink-side change or a reader-side reconstruction that is\nbrittle against rotation. Second, the byte offset uniquely identifies\n\"the next unread position\" in a sequential scan, which is exactly what\nthe call pattern needs. A cursor that points at or past the file's\ncurrent size is treated as end-of-stream (empty page, `MoreAvailable`\nfalse).\n\nThe implementation is `readWindow` (reads the tail-most `maxScanBytes`\ninto a single in-memory buffer) plus `readLines` (clamps the cursor into\nthe window, drops a partial first line on the size-cap seek, then\ndelegates) plus `walkWindow` (walks the buffer line-by-line by exact\nslice offset). Offsets are into one contiguous buffer, so they are\ntrivially correct -- unlike an incremental reader over the file, whose\n`bufio.Reader` buffer-ahead would make its underlying file position\nunusable as a cursor.\n\n`Tail` is NOT a wrapper over `Page`: it keeps its legacy ring-buffer\nsemantics (newest `Limit` matches, oldest dropped, `Truncated` set on\nring overflow). They share `readWindow`/`walkWindow` but stay separate\nentry points precisely so Tail's established behaviour is unchanged.\n\n### `Query` gains two optional fields\n\n```go\nSince time.Time // inclusive lower bound on entry.Time\nUntil time.Time // inclusive upper bound on entry.Time\n```\n\n`Levels`, `Component`, `Contains`, `Limit` are unchanged. The existing\nfilter logic and tests move unchanged.\n\n### Tool schema (`internal/gateway/task_tools.go`)\n\n`ChatTaskLogQuery` gains three fields:\n\n- `Level []string` (forwarded to `Query.Levels`)\n- `Since time.Time` / `Until time.Time` (forwarded as `Query.Since/Until`)\n- `AfterID int64` (the cursor; 0 to start at the beginning)\n\n`ChatTaskLogResult` gains two fields:\n\n- `Cursor int64` -- highest ID in this page; pass back as `AfterID` to continue\n- `MoreAvailable bool` -- true iff the scan saw more matching entries that\n did not fit in this page\n\nThe tool description is updated to teach the model the pagination\nprotocol in one sentence: \"pass the previous `cursor` back as `Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/task-run-detail/",
|
||||
"title": "Per-run task detail: attempts, stages, changes, config, debug",
|
||||
"section": "PRDs",
|
||||
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --- | --- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted as the `events.attempt` column\n(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstructure is exactly the false fidelity this surface exists to avoid; a column\nis durable, queryable and ordered by construction.\n\n**`0` means \"not attributable\".** It is every row written before this change\nplus the deliberately task-agnostic producers. It is not an attempt number and\nis never rendered as one. The attempts endpoint reports the count of\nunattributed events so the page can say so instead of presenting old history as\nattempt 1.\n\n## Migration against an existing `archie.db`\n\n\u003e Storage superseded: every store now lives in PostgreSQL behind\n\u003e `internal/domain/storecontract`, implemented in `internal/infrastructure/postgres`\n\u003e (`docs/prds/state-store-contract.md`). SQLite names below describe the\n\u003e original design.\n\nThe store's migrator (`migrateTasks` in `internal/store/store.go`) already reads\n`PRAGMA table_info` through `tableColumns` and applies a presence-gated\n`ALTER TABLE ... ADD COLUMN` list. This change adds an `events` arm: a\n`tableColumns(ctx, tx, \"events\")` read beside the other two, and the entry\n`ALTER TABLE events ADD COLUMN attempt INTEGER NOT NULL DEFAULT 0`.\n\nThree consequences a future maintainer must not get wrong:\n\n- `eventsSchema` is `CREATE TABLE IF NOT EXISTS` (`Line truncated
|
||||
"body": "# Per-run task detail: attempts, stages, changes, config, debug\n\n**Status:** Approved\n**Authority:** the surface contract itself is\n`docs/architecture/observability.md`.\n**Date:** 2026-09-18\n**Compounds with:** `docs/prds/task-logs-pagination.md` (a bounded read says\nwhat it does not show), `docs/prds/status-health-surface.md` (no surface that\nanswers something already answered elsewhere).\n\n## Decision\n\nA task gets one detail page that answers \"what did this run actually do?\" per\n**attempt**: an ordered stage rail, the change each commit/push produced, the\neffective configuration the attempt ran under, the attempt's log, and the raw\nrecord behind all of it.\n\nThe single organising idea is **attempt attribution**. The dashboard\nrenders a task's whole event stream as one flat timeline, so a retried task\nreads as one long run with two of everything. Every new panel is scoped to one\nattempt and says which one.\n\nThe second organising idea is **provenance, not re-derivation**. What a run\nproduced is captured at the producer, while the evidence exists, and persisted\ndurably. Nothing in this surface tries to reconstruct a past run from state\nthat has since moved on.\n\n## The requirement set\n\n| # | Requirement | Mechanism |\n| --- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- |\n| R1 | Per-attempt stage rail: stages with name, start, duration, terminal status and error, ordered within one attempt | `GET /api/tasks/{id}/attempts` reads the task's events and groups them by `attempt` |\n| R2 | Events carry an attempt, migrated safely and carried on the wire | `events.attempt` column + presence-gated migrator arm; `Event.attempt = 11` |\n| R3 | Changed files captured at commit/push, persisted per task, exposed, shown with repo/PR links | `changes_captured` durable event written by the commit/push steps; `GET /api/tasks/{id}/changes` |\n| R4 | The effective configuration an attempt ran under, secrets redacted, shown | `config_captured` durable event written once per attempt; read from the events response the page already holds |\n| R5 | Log pane filters by attempt, stage and level; absence stays distinct from an unreadable deployment | `logging.Query.Stage` + `ReadTaskLogRequest.stage = 9`; the pane keeps `disabled` and `found=false` apart |\n| R6 | Retry is reachable from the run view and produces a new attempt shown as a new run | Existing retry action, labelled as a NEW run whose confirm states the previous attempt's commits are discarded |\n| R7 | Raw JSON of the task record and its events for the selected attempt | `GET /api/tasks/{id}/debug` |\n| R8 | Deep-linkable, reload-safe per-task detail page that keeps existing URLs working | `/tasks/{id}` route beside the existing `/tasks?task=N` and `/tasks?status=...` |\n| R9 | Design polish: hierarchy, tokens, both themes, responsive rail, a11y, loading/empty/error states | UI lane; measured at 480px and 700px in both themes |\n| R10 | Documentation of record | This document plus `docs/architecture/observability.md` |\n| R11 | Red-first tests for every new behaviour, full gate, `task ui`, forced `go build ./...`, `go test -race` on touched packages | Per lane; the anti-cost-cutting requirement lives here |\n\n## Attempt attribution: a column, not a guess\n\n`events.Event.Attempt`, persisted as the `events.attempt` column\n(`internal/infrastructure/postgres/migrations/0001_state_store.sql`), is a real column,\n`NOT NULL DEFAULT 0`. It was chosen over segmenting the stream on `task_queued` /\n`task_retried` because a fold would have to guess which side of a boundary an\nevent belongs to when the daemon restarts mid-attempt, when `RecoverStale`\nrequeues, or when two attempts interleave across a crash. A guess rendered as\nstrucLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/task-run-master-detail/",
|
||||
"title": "Task run detail as a master-detail split pane",
|
||||
"section": "PRDs",
|
||||
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources."
|
||||
"body": "# Task run detail as a master-detail split pane\n\n**Status:** Approved\n**Authority:** the panel contracts stay as ratified in\n`docs/prds/task-run-detail.md`; this document changes only the run page's\narrangement of them.\n**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution, the\nlog stage filter, the per-panel honesty rules).\n\n## Decision\n\nThe run page's five tabs become two panes. The stage rail is the **master**,\nalways visible on the left. The four context panels — log, changed files,\nconfiguration, debug — are the **inspector** on the right, and their tab bar\nmoves into the inspector. The \"Stages\" tab stops existing.\n\nSelecting a stage switches the inspector to the log tab and sets the log\npane's stage filter to that stage. Changing the filter afterwards is the\noperator's choice and is not overridden; rail selection never touches the\nlevel filter. Clicking the selected stage again returns the filter to all\nstages. A stage with no name is rendered but not selectable.\n\nSwitching attempts resets the stage filter to all stages: a selection was\ncommanded on the attempt it was made on, and a different attempt presents a\ndifferent stage list. Changed files, configuration and debug stay\nattempt-scoped; a stage selection never scopes them.\n\n## What does not change\n\n- No new endpoint, RPC, table or configuration field. Every read is one the\n page already makes.\n- The URL contract: `tab` and `attempt` ride in the query string and survive\n a reload. Log filters are not part of the URL; a reload returns the log to\n all stages. `tab=stages` stays a valid URL and renders the log tab; the\n page never generates it again.\n- Attempt attribution, the log stage filter's coverage limit and every\n honesty rule in `task-run-detail.md` still apply: each pane states what it\n cannot show under that document's rendering rules.\n- The task header and the attempt selector sit above both panes.\n\n## Arrangement\n\n- Left pane: fixed-width rail (20rem) with the attempt's stage rows. Status,\n duration, error, the stage's agent report, the attempt's status badge and\n start time, and the attempt-attribution footnotes render in the rail.\n- Right pane: the inspector's tab bar plus the selected panel, filling the\n remaining width.\n- Below the shell's 900px frame breakpoint the rail stacks above the\n inspector; neither pane is hidden.\n- Keyboard: the rail keeps its list semantics and each stage row is a real\n button, so selection and deselection work without a pointer; the inspector\n keeps the WAI-ARIA tabs pattern the tab bar already provides.\n\n## Acceptance\n\n1. The rail is visible without opening any tab, and no \"Stages\" trigger exists.\n2. Clicking a stage opens the log filtered to that stage; clicking it again\n shows all stages.\n3. After a stage selection, a filter change made by the operator is kept, and\n the level filter survives the selection.\n4. Switching attempts resets the stage filter to all stages, and no rail row\n on the new attempt renders as selected unless the operator selected it\n there.\n5. `tab=stages` loads and renders the log tab.\n6. Every inspector tab and attempt deep-link survives a reload.\n7. A stage is selectable and deselectable by keyboard, and the selection\n mirrors the log pane's stage filter.\n8. Below 900px the rail stacks above the inspector.\n9. `task check` passes clean and `ui/dist` matches the sources.\n"
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/ui-service-boundary/",
|
||||
"title": "UI Service boundary and configuration ownership",
|
||||
"section": "PRDs",
|
||||
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behaviour, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n|---|---|---|---|\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviourally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status |\n|---|---|---|\n| `/api/chat/*` | Gateway `ChatContract` and its versioned client | contract seam exists; DTO and stream parity remain |\n| `/api/tasks/*`, `/api/workflows`, `/api/setup` | State Store read/action contracts plus an explicit execution/admin action contract | State Store adapter exists; UI-facing narrow surface remains |\n| `/events` | State Store `EventsSince`, polled by one UI-process pump feeding `Server.Broadcast` | RESOLVED (`archie-core-za9f`): see migration-decisions, \"Dashboard live event delivery\". No new RPC; replay cursor and drop-recovery are the existing `since` watermark in `sse.go` |\n| `/api/logs`, `/api/logs/stream` | daemon diagnostic feed, host-local | unresolved: `logging.Feed` is in-process on the daemon host and has no contract. The per-task log routes moved off this row: see `/api/tasks/*` above |\n| `/api/tasks/{id}/logs`, `/api/tasks/{id}/logs/download` | State Store task-log read contract (`TaskLogStore`: `ReadTaskLog` + `StreamTaskLogContent`), read by the UI process from the service that owns the state directory | RESOLVED (`archie-core-iaqx`): the UI process composes `TaskLogStore` from its own State Store client and serves the attempLine truncated
|
||||
"body": "# UI Service boundary and configuration ownership\n\n**Status:** Approved\n**Revision:** 1\n**Date:** 2026-09-07\n**Beads issue:** `archie-core-8cda.5.1`\n**Parent:** [`service-decomposition.md`](/dev/prds/service-decomposition/)\n**Prerequisites:** Gateway contract extraction and State Store contract ratification\n\nThis document is the authority for Phase 3 UI Service implementation. It fixes\nthe process boundary, configuration ownership, client contracts, security\nposture, readiness behaviour, and migration evidence required by\n`archie-core-8cda.5.2` and later UI extraction work.\n\n## Decision\n\nThe UI Service owns the operator-facing HTTP surface and the compiled SPA. It\nserves `ui/dist` and exposes UI-specific JSON DTOs for dashboard views and\nactions. It does not own conversations, task state, workflow execution,\nchannel lifecycle, forge access, or the daemon's runtime configuration.\n\nThe UI Service consumes two typed remote capabilities:\n\n- Gateway's `gateway.ChatContract` through the versioned Gateway gRPC\n contract, for chat snapshots, messages, turns, streaming, persona changes,\n cancellation, and Gateway task actions.\n- State Store's narrow read/write contracts through the versioned State Store\n gRPC contract, for task views, events, captures, mappings, bindings, and\n configuration data explicitly projected for the dashboard.\n\nThe UI process may compose local adapters during the migration seam, but the\nadapter implements the same wire-safe contract as the remote client. The\nproduction extraction cutover removes the in-process adapter in the same\nchange; a dual-live UI authority is not permitted.\n\n## Boundary and ownership\n\n| Concern | UI Service owns | UI Service may consume | UI Service must not own or receive |\n| ------------------ | -------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------ |\n| HTTP and SPA | routes, auth middleware, UI DTOs, assets, HTTP lifecycle | contract results and health snapshots | domain entities or infrastructure handles |\n| Chat | request validation and response projection | Gateway `ChatContract` | `gateway.Router`, `SessionStore`, turn runner, model/provider runtime |\n| Task dashboard | query/action DTOs and HTTP status mapping | State Store narrow contracts and explicitly ratified task-action contract | `*store.Store`, SQL connections, workflow registry, daemon pointer |\n| Configuration page | secret-free view and update request validation | a UI configuration contract owned by the configuration/application boundary | `config.Config`, `config.Holder`, secret registry, reload implementation |\n| Readiness | UI process liveness and dependency readiness aggregation | bounded health results from Gateway and State Store | direct probing of private databases or providers |\n\nEvery value crossing the process boundary is a versioned DTO or scalar contract\nvalue. `internal/webui` may retain temporary Go-side adapters while the\nmigration is in progress, but handlers must map Gateway/State Store values to\nUI-owned response types at the HTTP edge. A constructor accepting a concrete\nGateway, State Store, daemon, or `config.Holder` is not an approved final\nboundary.\n\nThe existing UI routes remain behaviourally compatible during extraction,\nincluding task actions, SSE event delivery, config views, chat streaming,\ncapture intake, mappings, bindings, update reporting, and health endpoints.\nCompatibility preserves status codes, authentication requirements, redaction,\npagination/limits, event ordering, and failure degradation unless a separately\nratified contract changes them.\n\nThe route families have these target owners. This is the required inventory for\nthe implementation children; a route without an owner is not eligible for\ncutover.\n\n| Route family | Target owner consumed by UI | Migration status Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/vue-migration-checklist/",
|
||||
"title": "Preact → Vue 3 + shadcn-vue migration checklist",
|
||||
"section": "PRDs",
|
||||
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
|
||||
"body": "# Preact → Vue 3 + shadcn-vue migration checklist\n\n**Status:** Approved\n**Date:** 2026-09-20\n**Bead:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation restructure)\n**Bootstrap commit:** `e18fb8b2`\n\nThe Preact dashboard was deleted, not ported incrementally. This is the list of\nwhat has to exist again, what must not be lost on the way, and the contracts\nthat break silently if missed.\n\nDeleted source is recoverable at `git show e18fb8b2^:ui/src/\u003cpath\u003e`. Every\nclaim below was cross-checked against that tree; where a number is a live\nmeasurement rather than something recoverable from git, it says so.\n\n## Invariants that outlive the framework\n\nThese are not features; they are things other processes depend on. Breaking one\ndoes not show up as a broken page.\n\n- [ ] **Embed contract.** `ui/embed.go` embeds a committed `ui/dist`. The build\n must keep unhashed `assets/index.{js,css}`: dist/ lives in git, and\n hashed names orphan a file on every rebuild.\n- [ ] **Route registry.** `internal/gateway/dashboard_tools.go` hand-copies the\n route table and `TestDashboardPagesRegistryCoversEveryRoute` parses\n `ui/src/router/index.ts` to hold them in step. The parser needs\n `const routes = [` on its own line, `path: \"...\"` on a single line per\n route, and `nav: false` on any entry the registry should skip. That guard\n caught a stale `/chat` entry earlier.\n- [ ] **Mutation headers.** Every POST/PATCH/DELETE must send **both**\n `X-Archie-CSRF: 1` and `Content-Type: application/json`. The server\n returns 403 without the first and 415 without the second\n (`internal/webui/api_tasks.go`, `authorizeTaskMutation`). GET sends\n neither. This is the single most likely thing to silently break every\n write after the port.\n- [x] **History routing.** `createWebHistory`, `base: \"/\"`. Legacy `#/path`\n links are rewritten by `src/legacy-hash-redirect.ts`. The chat navigate\n chip should emit `/tasks`; the Go side already stores bare paths.\n- [ ] **Capability gating.** `GET /api/capabilities`\n (`internal/webui/api_capabilities.go`) returns a `sections` map of ten\n booleans: chat, logs, skills, curators, channels, captures, mappings,\n bindings, and workflows/settings which are always true. A route whose\n section is false must be hidden, not rendered empty. **Fail open**: on a\n failed or null response hide nothing — the old client used a bare\n `.catch(() =\u003e {})` for exactly this. A page that says \"unavailable\" is\n recoverable; a nav entry that vanished is not.\n- [ ] **`LOG_LEVELS`** in `base/log-row.jsx` is a wire contract, not a display\n list: the CSV level filter is matched server-side by `splitCSV` in\n `internal/webui/api_tasks_logs.go`. A value mismatch breaks filtering\n with no error.\n- [ ] **SSE lifecycle.** Three streams, all `id: \u003cn\u003e\\ndata: \u003cjson\u003e\\n\\n` except\n chat which omits the id:\n `/events` (task lifecycle, `sse.go`, supports `?since=` and\n `Last-Event-ID` resume), `/api/logs/stream` (`api_logs.go`, same\n resume protocol), `/api/chat/stream` (`api_chat.go`, frames typed\n delta/tool/media/navigate). Each must be closed on unmount or the app\n leaks a connection per navigation. Preact used an `archie:teardown`\n event; Vue should use `onUnmounted`.\n\n\u003e **On tests.** Per Sam's call, the 43-file suite was not ported and tests\n\u003e return when there is behaviour worth pinning. Flagging one exception for when\n\u003e that moment comes: the deleted `ui/test/api-client.test.js` classified every\n\u003e API method as mutation/read/stream/url and asserted the right headers per\n\u003e class. It is the only cheap guard on the CSRF contract above. (It did **not**\n\u003e text-scan for a second `fetch()` — that check was deliberately removed\n\u003e upstream for testing the file's wording rather than its behaviour.)\n\n## Phase 1 — Foundation\n\n- [x] **Theme.** `css/tokens.css` was a complete two-theme semantic token set\n (`--fg-subtle`, `--accent`, `--ok/warn/danger`, surfaces, shadows). Mapped\n onto Tailwind v4's `@theme` in `src/style.css`; the second system was not\n kept.\n- [x] **`color-scheme`.** `[data-theme=\"dark\"] { color-scheme: dark }` and the\n light equivalent. Without it the UA paints light scrollbars and light\n native controls inside the dark app. Fixed; trivially lost.\n- [x] **Contrast values.** The violet palette moved these off the values pinned\n here, so they were recomputed against its own backgrounds instead of\n carried: `--fg-subtle` `#A99DBD` dark (7.67:1, AAA) / `#6E6577` light\n (4.87:1, AA), and `--fg-muted` `#B9AECB` / `#635B6B` (9.28:1 and 5.70:1).\n The invariant the pin existed for holds; the values are the palette's.\n- [x] **API client** (`base/api.jsx` → `src/lib/api.tLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/webhook-intake-security/",
|
||||
"title": "Webhook intake security -- decision",
|
||||
"section": "PRDs",
|
||||
"body": "# Webhook intake security -- decision\n\n**Status:** Approved\n**Date:** 2026-08-22\n**Beads issue:** `archie-core-t2db.5`, blocks `archie-core-t2db.4`\n\n## Why this is decided ahead of the code it constrains\n\n`archie-core-t2db` (no-code playbooks) and `archie-core-7d5u` (typed event\nsources) both land a public intake surface whose eventual output is an agent\nwith tool access and a repo. Neither capture (`t2db.1`) nor the intake family\n(`7d5u.3`) has shipped yet, so this decision exists to be a contract the two\nepics build against, not a retrofit once the surface exists. A webhook URL\nthat can start an agent is remote code execution with extra steps if any of\nthe five points below is missing on day one.\n\n## 1. Per-source authentication\n\nReuse the per-route HMAC-SHA256 scheme already in\n`internal/channels/webhook/webhook.go` (`validateHMAC`), unchanged: a source\nregisters with a shared secret; the signature is checked against the raw\nbody. Do not invent a second scheme for intake.\n\n**Capture and triggering split at the signature, not at a separate flag.** An\nevent with a missing or invalid signature is still captured (visible in the\ninspector, marked unauthenticated) so an operator can diagnose a\nmisconfigured sender -- but an unauthenticated event can never be matched\nagainst a binding. Authentication is what promotes an event from \"something\narrived\" to \"something that can run a workflow.\"\n\n## 2. Human approval before a binding arms\n\nA binding has three states: `draft -\u003e pending_approval -\u003e armed`. Only\n`armed` bindings are evaluated against incoming events. Creating or editing a\nbinding's matcher, mapping, or target workflow always sets it to\n`pending_approval`, including edits to an already-armed binding -- an edit is\nnot silently re-armed, or the approval gate is decorative. Approval requires\nan authenticated dashboard session; there is no unattended approval path.\n\nModel: `internal/channels/telegram`'s dangerous-command approval flow\n(`dangerousAction` / `pendingApproval` in `dangerous.go` / `approval.go`) is\nthe existing precedent for \"a human decision gates code from running\" in this\ncodebase -- follow its shape rather than designing a new approval primitive.\n\n## 3. Rate and volume limits, per source\n\nA token-bucket limiter keyed by source ID, not global -- one noisy or hostile\nsender must not exhaust another source's capture budget. Precedent for\nper-key volume capping: `internal/pairing/store.go`'s `MaxPendingPerPlatform`.\n\nOn limit exceeded, the request is rejected (HTTP 429), not silently dropped.\nA silently dropped event is indistinguishable from a sender that never fired\n-- the same invisible-failure shape the update-verification work\n(`archie-core-522`) exists to prevent. The rejection itself is observable in\nthe inspector as a distinct outcome from \"not received.\"\n\n## 4. Blast radius bounded by code, not by prompt wording\n\nA playbook-triggered task runs through exactly the same enforcement as every\nother task: the `[[repos.gate]]` quality gate, `diff_cap_lines`, the\nsandboxed per-task container (`internal/container`), worktree isolation, and\n\"the model never runs git.\" No new relaxation is introduced for\nplaybook-triggered work, and none is needed -- the existing constraints are\nthe control.\n\nMapped payload fields are treated as ordinary user-controlled text inside an\nagent prompt, exactly like an inbound chat message never as trusted\ninstructions. \"The agent should ignore instructions in the payload\" is not a\ncontrol and must not appear as one anywhere in this feature -- per the\nenvironmental-enforcement principle (`docs/architecture/agent-system.md`,\n\"Existing invariants to preserve\"), the boundary is the gate and the sandbox,\nnot a sentence in the system prompt.\n\n## 5. Retention and redaction of captured payloads\n\n**Retention:** captured events (bound or not) are purged after 7 days,\nconfigurable per deployment. Unbound events exist to be mapped against; nothing\njustifies keeping them indefinitely once that window has passed, and an\nunbounded capture store is the same disk-exhaustion risk item 3 addresses at\nthe request-rate level.\n\n**Redaction:** before a captured payload is persisted, apply the same\nkey-name heuristic `internal/gateway/stream.go`'s `sensitiveParameterKey`\nalready uses for tool-call parameters (matches `token`, `secret`, `password`,\n`passwd`, `api_key`, `apikey`, `authorization`, `credential`, `cookie`,\n`private_key` against normalised JSON keys) and replace matching values with\nthe same `[redacted]` marker. This is best-effort, not a guarantee -- a\nsender that names a secret field something the heuristic misses will still\nhave it captured. Document that limitation where captured payloads are\ndisplayed, rather than implying the redaction is complete.\n\n**Visibility:** captured payloads, redacted or not, are visible only to an\nauthenticated dashboarLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/workflow-call-outputs/",
|
||||
"title": "Declared outputs of a workflow run",
|
||||
"section": "PRDs",
|
||||
"body": "# Declared outputs of a workflow run\n\n**Status:** Draft\n**Date:** 2026-09-30\n**Bead:** `archie-core-t2db.43`\n**Authority:** `docs/prds/event-automation.md` for what a declared output is,\n`docs/prds/workflow-calls.md` for the call and its grants,\n`docs/prds/state-store-contract.md` for the State Store contract the wire\nchange must satisfy.\n**Supersedes:** `docs/prds/workflow-calls.md`, \"Waiting on the callee\": the\ncallee's transition detail is the human summary, not the stand-in for\nstructured outputs.\n\nA workflow declares named, typed outputs. A run writes each one once. A\n`wait: true` caller receives them, and may publish one as its own.\n\n## Where outputs are declared\n\n`outputs:` on the workflow definition, beside `inputs:`, decoded into\n`task.WorkflowInterface.Outputs map[string]OutputSpec` where\n`OutputSpec{Type, Required}`:\n\n```yaml\nid: firewall-contain\noutputs:\n contained: { type: bool, required: true }\n summary: { type: string }\n```\n\nNames and types are the input grammar: the same identifier shape, the same\ntype set, and the same check in `WorkflowInterface.Validate`, which both\n`ParseDefinition` and `ParseWorkflowInterface` call.\n\n**Forced by:** `ParseDefinition` decodes with `KnownFields(true)`, so a key no\ndecoded struct declares is refused — the declaration must live on\n`WorkflowInterface` for an author to write it at all, and that is where\n`docs/development/workflows.md` puts every field a process without the engine\nmust read. The type set is the shared value vocabulary: `TypeAccepts` and\n`ValueType` already check a mapped parameter and an input with it. `required`\ndefaults to false, and the generated YAML for a builtin that declares no\noutputs is unchanged, because a definition's digest pins a run.\n\n**Rejected:** outputs per step, or per call step, because a workflow returns a\nresult as itself rather than as one of its stages. Also `task.Definition`\ngaining outputs: no reader needs them — a binding offers inputs, and a call's\noutputs assignment is checked against the callee's YAML in the same\ncollection — and a declared field with no reader parses and does nothing.\n\n## How a run writes one\n\nEach declared output is offered to the run's agent stages as a capture tool\nnamed after the output, whose arguments are `{\"value\": ...}`; the accepted\ncall's `value` member is the output's value. The engine holds the accepted\nvalues on the task context and writes them into its own task row in the\n`Store.Update` call the run already makes. A deterministic stage may set the\nsame values in Go, and the run's finish check validates them identically.\n\n**Forced by:** a run's only structured results are capture calls\n(`agentexec.CaptureTool`, `Result.Captures`), and the workflow interface\nalready declares when a stage needs them (`task.WorkflowNeeds.Captures`).\n`WorkflowInterface.Needs` reports `captures` for a non-empty `Outputs`, so\ndeclaring an output alone requires the capability and a Kit profile that\nserves no capture tools is refused before dispatch.\nDeriving the tools from the declaration means an output cannot be written\nunder a name nobody declared, and it keeps one route to structured agent\noutput rather than adding a second beside the capture path. The row write is\nthe run's existing write: the task row is where a run's own state lives, and\nthe container already holds `Update` on its own row.\n\nThe tool is offered with `MaxCalls: 1`, and a stage is not offered an output\nthe run has written, so a run writes each output once: a repeat within a stage\nis answered with the tool's rejection and the agent carries on, and a later\nstage cannot overwrite a value. A stage's own capture tool may not share a\nname with a declared output, because the value would otherwise be ambiguous.\n\n**Rejected:** a `workflow.output` step type, because assigning the run's\nresult from a step needs a grammar for \"the previous stage's result\" that does\nnot exist, and a step that reaches the agent would be the second path\n`docs/development/workflows.md` forbids. Also a write RPC of its own: the\ncontainer's `Update` already reaches its own row, and a second write verb for\none column is a second thing to keep in step.\n\n## How a caller receives one\n\nOn a successful `wait: true` call the caller's stage holds the callee's\noutputs as a `map[string]any`. A call step's `outputs:` setting publishes one\nas one of the caller's own outputs:\n\n```yaml\nsteps:\n - type: workflow.call\n workflow: firewall-contain\n wait: true\n inputs: { src_ip: inputs.src_ip }\n outputs: { contained: outputs.contained }\n```\n\nThe key names the callee's declared name; the value names one of the caller's\nown with the prefix the call's `inputs:` already uses. A published value joins\nthe caller's output set for its run, so a caller returns its callee's result to\nits own caller, and a run may publish a callee's output and write its own\notheLine truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/workflow-calls/",
|
||||
"title": "Workflows calling workflows",
|
||||
"section": "PRDs",
|
||||
"body": "# Workflows calling workflows\n\n**Status:** Draft\n**Date:** 2026-09-26\n**Bead:** `archie-core-t2db.41`\n**Extends:** `docs/prds/event-automation.md` (workflow/binding/profile model), `docs/prds/state-store-contract.md` (two new RPCs), `docs/prds/execution-tree-state-machine.md` (call kind)\n\n## The call, end to end\n\n```\ncaller run (in agent container)\n workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)\n │ callee task row: org/identity/owner/repo\n │ derived from the caller row server-side\n ▼\n callee task (queued, org of the caller)\n │ daemon claims, pins the callee's OWN\n │ definition → its OWN agent profile\n ▼\n callee run (its own container, own tree)\n wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)\n wait: false ──continue\n```\n\nA `workflow.call` step starts the callee as a first-class task and, with\n`wait: true`, waits for its terminal state. The callee is never run \"inside\"\nthe caller: it gets its own task row, its own pinned definition, its own\nprofile, its own container, and its own outcome on its own run\n(`execution-tree-state-machine.md`).\n\n## Save-time checks (the collection is the authority)\n\nAll semantic checks run in `workflow.ValidateDefinitionCollection`, the gate\nevery save and load of the `workflow-definitions` resource passes through.\nA single-definition parse cannot see callees, so it validates shape only.\n\n- **Callee exists.** A call to a workflow outside the collection is refused.\n- **Inputs checked.** A call value is a literal or a reference\n (`inputs.\u003cname\u003e`) to the calling workflow's declared input. References must\n name a declared input; the resolved type must satisfy the callee's declared\n type; unknown callee inputs are refused; a required callee input must be\n assigned.\n- **Self-calls refused.** The call graph over the collection is walked from\n every workflow; a workflow that reaches itself, directly or through other\n workflows, is refused with the cycle path. (Cycles can otherwise deadlock:\n `wait: true` callers hold their containers.)\n- **Repository.** `workflow.call` needs no repository, so it is legal in a\n `repository: none` workflow: the callee inherits the caller's task record\n (owner/repo/identity/org), and the callee's own `repository` mode decides\n whether its run clones.\n- **Org enablement** (bead `archie-core-t2db.42`): the single\n instance-wide collection the current model serves is what \"enabled for\n the caller's org\" resolves against — an undefined callee parks. The\n callee's org is derived from the caller's row, so a callee is never\n visible outside its caller's org. The per-org enable/disable catalogue\n lands with `archie-core-t2db.42` and becomes the one source of this\n predicate.\n\n## Runtime\n\n**Depth limit.** `workflow.MaxCallDepth` (5). The calling stage refuses a call\nthat would exceed it; the store re-checks on insert (callee depth = caller\ndepth + 1), so no path can enqueue past the limit.\n\n**Starting the callee.** The caller runs inside a container whose task-scoped\nState Store grant authorizes only `Update`/`Transition`/`InsertEvent` on its\nown task — it can neither enqueue a task nor read another one. One new\ncontract RPC starts the callee:\n\n- `EnqueueCallTask(caller_task_id, workflow, inputs_json) → task`\n — the store reads the caller row, refuses a caller that is not `running`,\n refuses past the depth limit, and inserts the callee row deriving org,\n workspace, identity, owner, repo and a fresh synthetic issue number from\n the caller (the same org COALESCE `EnqueueIssue`/`InsertChatTask` use). The\n callee row carries `call_parent_task_id` and `call_depth`.\n\n**Waiting on the callee.** One new read RPC returns a call's callee:\n\n- `WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)` — the\n handler verifies `call_parent_task_id` matches, so a caller reads only its\n own callees, and returns the callee's status plus its latest transition\n detail (the callee's summary — the wait:true \"outputs\" until a structured\n outputs model lands).\n\nBoth RPCs are admitted to task-scoped grants on `caller_task_id == granted\ntask ID` (`authorizesTaskScopedCall` gains two request-shape cases). This is\nthe one sanctioned widening of a task grant: the callee is the caller's child,\nand starting it is the mechanism by which one event becomes several runs. The\nwidenings stay request-shape checks; the parent-child authorization is a\nhandler-side row check, so the interceptor never reads the database.\n\n**Schema.** `tasks` gains Line truncated
|
||||
},
|
||||
{
|
||||
"url": "/dev/prds/workflow-step-vocabulary/",
|
||||
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
|
||||
"section": "PRDs",
|
||||
"body": "# Workflow step vocabulary: what a step type is and how binaries agree on it\n\n**Status:** Draft\n**Date:** 2026-09-29\n**Beads:** `archie-core-m7oc` (agreement between separately deployed binaries), `archie-core-ze7y` (the deleted `.archie/stages/*.go` equivalent)\n**Extends:** `docs/architecture/plugins-and-extensions.md` (plugin engine rule), `docs/prds/event-automation.md` (the workflow model step types serve)\n\n**Authority:** `docs/architecture/plugins-and-extensions.md` — the workflow step vocabulary is a Workflow capability family, and its extension point follows the plugin engine rule.\n\n## Decision\n\nA workflow step type is a named Go factory: the word a YAML workflow writes in\na step's `type` field, plus the factory that builds its stage. The name is a\nstable identifier; the identity also declares what plugin family claims it,\nso a contribution that shadows a shipped stage is refused instead of\noverriding it.\n\nThe Workflow domain owns the typed family contract — `StepTypeProvider` for a\ncontribution and `Manager` as the owning registry. A provider contributes a\nwhole set of step types under its own stable-identifier name; the manager\nvalidates the entire contribution before applying any of it (named provider,\nwell-formed step-type names, non-nil factories, no step type claimed twice,\nno claim on a name another provider holds) and applies it atomically. The\ngeneric `plugin.Plugin` contract stays metadata-only.\n\nThe vocabulary is a compiled-in, closed set. `internal/infrastructure/workflowsteps`\nis the one place a step type is bundled into any binary that resolves one: the\nshipped workflow stages, the repository-hook replacements (`gate.diff-rules`)\nand the repository-free event steps each arrive as one provider, and adding a\nstep type means adding a provider to that set. Interpreted plugin sources\ncannot contribute step types: the Yaegi plugin host satisfies only the\nmetadata contract, and no bridge to `StepFactory` exists.\n\nEvery binary that resolves a step type builds its manager from that same\nprovider set at its composition root, before its first resolution, and\ninjects the manager everywhere it resolves definitions. Agreement is per\nbuild: the State Store, the daemon's workflow-definitions client and the agent\nworker built from the same source register identical vocabularies by\nconstruction; binaries built from different sources can disagree, and only a\nmatching deploy fixes that.\n\nAn unknown step type is refused twice, and never degraded. The validator\n`ParseDefinition` refuses a definition naming an unregistered type at save\ntime, on the validating side the composition root built (the State Store's\nworkflow-definitions resource validates there before anything is stored). The\ncompiler refuses the same definition at run, so a binary handed a definition\nwritten against a vocabulary it does not have fails that run loudly instead of\nsilently skipping steps. Both checks live in the Workflow domain against the\ninjected manager, which is why no binary can opt out of the check by\nsubstituting its own registry.\n\n## Relationship between the questions\n\n`archie-core-ze7y` is the same question seen from the deleted\nrepository-authored stages: those `.archie/stages/*.go` files held arbitrary\nstages, and their gate half landed as `gate.diff-rules` settings rather\nthan interpreted Go. Their stage half has no replacement and does not get one\nthat approximates it: no interpreted-Go stage type is built, and no command\nstep type is created by this decision to stand in for them. The refusal of\n`.archie/stages/*.go` stays until the maintainer's trust decision\n(`archie-core-ndm8`) says otherwise.\n\nIf that decision ever allows a command step type, it arrives as a provider in\nthe compiled-in set under the rules above — a new contributor of exactly one\nstep type at a named provider. It is not a plugin contribution mechanism, and\nit does not change any answer in this document.\n\n## Rejected alternatives\n\n- **A vocabulary version or hash on the wire.** The executing side already\n refuses an unknown step type at its first compile, which is the mismatch\n detector, and it fails closed. A wire field would only narrow the\n deploy-skew window that a matching deploy closes, at the cost of a new\n contract field.\n- **A Yaegi-plugin-to-`StepFactory` bridge.** It would run repository-supplied\n interpreted code inside the daemon's process with daemon privileges. The\n trust boundary invariant requires repository-authored code to run in the\n task container, not in an interpreter embeddable into any binary.\n- **A package-level process-global registrar.** Global mutable registry state\n is unreadable at the composition root, collides with itself when one\n process builds the vocabulary twice, and is what made the first attempt at\n this question worse instead of better.\n- **Degrading on an unknown step type.** A run that skips steps iLine truncated
|
||||
}
|
||||
],
|
||||
"nav": [
|
||||
@@ -693,10 +753,6 @@
|
||||
"title": "Dashboard live state",
|
||||
"url": "/dev/prds/dashboard-live-state/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard navigation groups + Configuration split -- decision",
|
||||
"url": "/dev/prds/dashboard-navigation-groups/"
|
||||
},
|
||||
{
|
||||
"title": "Dashboard port: what the agent delivers",
|
||||
"url": "/dev/prds/dashboard-port-brief/"
|
||||
@@ -737,10 +793,18 @@
|
||||
"title": "Event sources and reactions -- decision",
|
||||
"url": "/dev/prds/event-sources-and-reactions/"
|
||||
},
|
||||
{
|
||||
"title": "Execution tree and enforced state machine",
|
||||
"url": "/dev/prds/execution-tree-state-machine/"
|
||||
},
|
||||
{
|
||||
"title": "Extensions centre",
|
||||
"url": "/dev/prds/extensions-center/"
|
||||
},
|
||||
{
|
||||
"title": "External agent harnesses",
|
||||
"url": "/dev/prds/external-agent-harness/"
|
||||
},
|
||||
{
|
||||
"title": "Identity for users, agents and external agents — decision",
|
||||
"url": "/dev/prds/identity-decision/"
|
||||
@@ -793,6 +857,18 @@
|
||||
"title": "Playbook data-flow and condition syntax",
|
||||
"url": "/dev/prds/playbook-expression-syntax/"
|
||||
},
|
||||
{
|
||||
"title": "Plugin settings reconcile live",
|
||||
"url": "/dev/prds/plugin-settings-live/"
|
||||
},
|
||||
{
|
||||
"title": "PR review agent",
|
||||
"url": "/dev/prds/pr-review-agent/"
|
||||
},
|
||||
{
|
||||
"title": "PR review: the operator's answer to the approval gate",
|
||||
"url": "/dev/prds/pr-review-operator-response/"
|
||||
},
|
||||
{
|
||||
"title": "PR review comment remediation -- decision",
|
||||
"url": "/dev/prds/pr-review-remediation/"
|
||||
@@ -813,6 +889,10 @@
|
||||
"title": "Review calibration -- decision",
|
||||
"url": "/dev/prds/review-calibration/"
|
||||
},
|
||||
{
|
||||
"title": "Review settings resource",
|
||||
"url": "/dev/prds/review-settings-resource/"
|
||||
},
|
||||
{
|
||||
"title": "Runtime control plane",
|
||||
"url": "/dev/prds/runtime-control-plane/"
|
||||
@@ -837,6 +917,10 @@
|
||||
"title": "Skill curator (reference implementation) -- decision",
|
||||
"url": "/dev/prds/skill-curator/"
|
||||
},
|
||||
{
|
||||
"title": "SOUL: an agent's user-authored personality",
|
||||
"url": "/dev/prds/soul/"
|
||||
},
|
||||
{
|
||||
"title": "State Store — contract boundary \u0026 transport (ratification)",
|
||||
"url": "/dev/prds/state-store-contract/"
|
||||
@@ -845,6 +929,10 @@
|
||||
"title": "/status health surface",
|
||||
"url": "/dev/prds/status-health-surface/"
|
||||
},
|
||||
{
|
||||
"title": "Store",
|
||||
"url": "/dev/prds/store/"
|
||||
},
|
||||
{
|
||||
"title": "task_logs pagination and bounded retrieval -- decision",
|
||||
"url": "/dev/prds/task-logs-pagination/"
|
||||
@@ -868,6 +956,18 @@
|
||||
{
|
||||
"title": "Webhook intake security -- decision",
|
||||
"url": "/dev/prds/webhook-intake-security/"
|
||||
},
|
||||
{
|
||||
"title": "Declared outputs of a workflow run",
|
||||
"url": "/dev/prds/workflow-call-outputs/"
|
||||
},
|
||||
{
|
||||
"title": "Workflows calling workflows",
|
||||
"url": "/dev/prds/workflow-calls/"
|
||||
},
|
||||
{
|
||||
"title": "Workflow step vocabulary: what a step type is and how binaries agree on it",
|
||||
"url": "/dev/prds/workflow-step-vocabulary/"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -11,6 +11,12 @@
|
||||
"title": "Building your first playbook binding",
|
||||
"section": "Guides",
|
||||
"body": "# Building your first playbook binding\n\nThis walks through the whole no-code path the event-capture epic promises:\npoint an external app's webhook at archie, see the real payload it sends,\nmap the fields you care about, bind them to a workflow, and watch the next\nmatching event turn into a task -- no code, no redeploy, no restart. See\n`docs/architecture/bindings.md` for the model and threat model behind each\nstep below.\n\n## 1. Send a test event\n\nPoint whatever external app you want archie to react to at:\n\n```\nPOST http://\u003cyour-archied-host\u003e:8484/webhooks/capture/\u003csource\u003e\n```\n\n`\u003csource\u003e` is a name you choose for this sender (e.g. `sentry`, `github-ci`,\n`stripe`) -- it's just a URL path segment, not a preset list. Send one real\nevent however is easiest for a first test, e.g.:\n\n```bash\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -d '{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\n```\n\nThis event isn't signed yet, so it's captured but marked **unauthenticated**\n-- visible for you to design against, but incapable of triggering anything\n(`docs/architecture/bindings.md`'s threat-model section explains why: an\nunauthenticated event can never match a binding, no matter how it looks).\n\n## 2. Inspect the captured payload\n\nOpen the dashboard's **Event inspector** (`/captures`). Your test event\nappears there with its real body -- this is schema-by-example: you're\nlooking at an actual payload from the actual sender, not guessing at a\nschema in advance.\n\n## 3. Map the fields you care about\n\nOpen **Field mappings** (`/mappings`) → **New mapping**. Pick your captured\nevent from the dropdown, then click through its payload tree on the right --\nevery key and value is clickable. Clicking a value binds it as a field\n(name, JSON path, and an inferred type you can change). Add whichever fields\nyour workflow needs (e.g. the issue title), mark the ones that must be\npresent as **Required**, hit **Preview** to confirm they resolve correctly\nagainst the real payload, then **Save**.\n\n## 4. Create the binding\n\nOpen **Playbook bindings** (`/bindings`) → **New binding**:\n\n- **Name** -- anything descriptive.\n- **Source** -- the same `\u003csource\u003e` segment from step 1 (e.g. `sentry`).\n- **Field mapping** -- the one you just saved.\n- **Workflow** -- which registered workflow should run on a match.\n- **Repo pin** (optional) -- leave both blank to use the single configured\n repo; set owner/repo explicitly if you run a multi-repo deployment.\n- **Shared secret** -- a real secret (16+ bytes), never `test1234`. The\n sender signs every request body with this via HMAC-SHA256 so archie can\n tell a genuine event from anyone who finds the URL.\n\nSave. The binding starts in **draft** -- nothing fires yet.\n\n## 5. Approve it\n\nA **draft** or freshly-**edited** binding needs an explicit human approval\nbefore it can ever match a live event -- this is deliberate, not a missing\nstep: an operator authoring a binding is a considered act, an event arriving\nis not, and nothing should self-arm (`docs/architecture/bindings.md`'s\nthreat-model section, point 2). Click **Approve**. Status becomes **armed**.\n\n## 6. Fire it for real\n\nSend the same kind of event again, this time **signed** with the binding's\nsecret:\n\n```bash\nBODY='{\"issue\": {\"title\": \"NullPointerException in checkout\"}, \"level\": \"error\"}'\nSECRET=\"the-secret-you-set-in-step-4\"\nSIG=$(printf '%s' \"$BODY\" | openssl dgst -sha256 -hmac \"$SECRET\" | sed 's/^.* //')\n\ncurl -X POST http://localhost:8484/webhooks/capture/sentry \\\n -H \"Content-Type: application/json\" \\\n -H \"X-Hub-Signature-256: sha256=$SIG\" \\\n -d \"$BODY\"\n```\n\nThis event is captured as **authenticated**, matched against your armed\nbinding, and dispatched into a new task through the exact same\ngate/worktree/sandbox pipeline every other task goes through -- see\n`docs/architecture/messaging-and-work-intake.md`'s \"Intake provenance\". Check\nthe **Tasks** page; a new task should appear, its body built from the fields\nyour mapping resolved.\n\n## Editing a live binding\n\nAny edit to an armed binding -- even a typo fix -- drops it back to\n**pending_approval** automatically. This can't be bypassed by editing; it\nhas to be re-approved. When editing, leave the **Shared secret** field blank\nto keep the existing secret; only fill it in if you're deliberately\nrotating it.\n"
|
||||
},
|
||||
{
|
||||
"url": "/docs/guides/pr-review-benchmark/",
|
||||
"title": "PR review benchmark",
|
||||
"section": "Guides",
|
||||
"body": "# PR review benchmark\n\nRun `scripts/pr-review-benchmark.sh` with `PRBENCH_REVIEW_MODEL` and\n`PRBENCH_CLASSIFICATION_MODEL` set to configured `provider/model` references.\nThe judge defaults to `anthropic/claude-sonnet-4.6`; set\n`PRBENCH_JUDGE_MODEL` to another configured model when needed. The script uses\n`~/.config/archie/config.toml` for providers and `GH_TOKEN` or `GITHUB_TOKEN`\nfor read access to the benchmark pull requests. It posts no forge review.\n\nThe default run reviews the 38 runnable Martian pull requests once each at\n`deep`, judges the comments against 102 golden comments, and writes\n`bin/prbench-results/run.json`, `summary.json`, and one JSON result per pull\nrequest. That output directory is ignored by git. A completed full run fails\nwhen any problem fails or golden micro-recall is below 0.70. Golden-only\nprecision is reported alongside recall. Set `PRBENCH_OUT` to keep separate\nruns; `-problems ID` limits a smoke run to one pull request. Completed results\nare saved as each PR finishes. Pass `-resume DIR` to reuse completed results\nfrom a run with the same models; each reused problem must match the current\nbenchmark entry, and failed problems are rerun.\nA smoke run alone is not the acceptance run.\n\nThe benchmark passes only each problem's ID and pull request URL to the\nreviewer. The judge receives the golden comments after the review has ended.\nThe runner uses the production decision phases through the merge gate,\nincluding scoring and the 25-comment cap, then stops before polish and forge\nposting. A reviewer that fails to finish makes that problem fail. The results\nrecord budget-skipped phases and the selected models. Model substitutions do\nnot satisfy the PRD's named-model criterion even if recall clears the threshold.\n"
|
||||
}
|
||||
],
|
||||
"nav": [
|
||||
@@ -24,6 +30,10 @@
|
||||
{
|
||||
"title": "Building your first playbook binding",
|
||||
"url": "/docs/guides/first-playbook/"
|
||||
},
|
||||
{
|
||||
"title": "PR review benchmark",
|
||||
"url": "/docs/guides/pr-review-benchmark/"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,34 @@
|
||||
# Prompt for Claude Code
|
||||
|
||||
Unzip this bundle into the repo at `docs/design/ui-redesign/`, then paste the prompt below.
|
||||
|
||||
---
|
||||
|
||||
The design handoff for the Archie UI redesign is in `docs/design/ui-redesign/`. It covers a new theme, a new
|
||||
top-level navigation, the Settings pages (Channels moves in there), and the Dashboard, Task detail, Workflows,
|
||||
New task dialog and Events pages.
|
||||
|
||||
Read `README.md` in full, then look at every PNG in `screenshots/`. The `00-current-*.png` files show how the
|
||||
pages look today; `P0-navigation-map.png` shows what moves where. The static HTML in `mockups/` has the exact
|
||||
CSS if you need it. `tokens/tokens.css` holds the colours, fonts and sizes.
|
||||
|
||||
Treat the spec as a hypothesis to check against the code, not a spec to copy exactly.
|
||||
|
||||
Before changing anything:
|
||||
1. Find how the UI is built: framework, router, component library, where styles and theme colours live,
|
||||
and where the purple comes from.
|
||||
2. Map today's routes and the Work / System menus to the proposed navigation in README §2. List every
|
||||
page that isn't covered and where you'd put it.
|
||||
3. For Settings and Channels: find how each section loads and saves config, how "Restart required",
|
||||
"Version", "History" and the audit log work, and where "Connecting" comes from. Map every field in
|
||||
README §5 to its real config key and type.
|
||||
4. Answer the backend questions in README §5.2 and §9.
|
||||
5. Check what data the Dashboard, Task detail and Workflows pages already get, and list anything the
|
||||
mockups show that isn't available.
|
||||
|
||||
Then write a short migration plan using the PR sequence in README §8. Adjust it to what you found and
|
||||
list anything the mockups assume that the backend doesn't support. Stop and show me the plan before you
|
||||
write code.
|
||||
|
||||
When I approve, do PR 1 only (theme tokens across the whole app, no layout changes) on a new branch, with
|
||||
before/after screenshots of each page.
|
||||
@@ -0,0 +1,277 @@
|
||||
# Archie UI Redesign — Handoff
|
||||
|
||||
A redesign of the Archie web UI:
|
||||
|
||||
- a calmer **"Graphite" theme** that replaces the purple
|
||||
- a **new navigation**: five top-level places, with all configuration moved under Settings
|
||||
- new layouts for **Settings** (every section, plus Channels moved in), the **Dashboard**,
|
||||
**Task detail**, **Workflows**, a **New task** dialog and **Events**
|
||||
|
||||
This folder is self-contained. Read this file first, then look at the screenshots.
|
||||
|
||||
```
|
||||
README.md ← this spec (read it all before planning)
|
||||
CLAUDE_PROMPT.md ← the prompt to paste into Claude Code
|
||||
tokens/tokens.css ← theme as CSS custom properties (source of truth)
|
||||
tokens/tokens.json ← same values as JSON (for Tailwind / JS themes)
|
||||
screenshots/
|
||||
00-current-*.png ← how each page looks TODAY
|
||||
P0-navigation-map ← today → proposed navigation, and what moves where
|
||||
P1…P5 ← app pages: dashboard, task detail, workflows, new task, events
|
||||
S1…S5 ← settings: sidebar + rows, personas, tools & MCP, review drawer, channels
|
||||
T-theme-components ← palette, type, buttons, pills, toggles, inputs
|
||||
mockups/*.html ← static HTML of each screenshot; open in a browser, inspect for exact CSS
|
||||
source/*.dc.html ← original design-canvas sources (reference only, needs a runtime that isn't included)
|
||||
```
|
||||
|
||||
> **How to treat this.** The mockups are a target, not a pixel spec. They are static HTML
|
||||
> written by hand; the app's framework, component library, router and data model win. Where the
|
||||
> mockups assume something the backend doesn't have, flag it rather than faking it.
|
||||
> Text in `[square brackets]` in a mockup is a placeholder for real data.
|
||||
|
||||
---
|
||||
|
||||
## 1. Problems being fixed (all pages)
|
||||
|
||||
1. **Purple everywhere.** Purple-tinted backgrounds, borders, buttons, checkboxes, bars and links all compete for attention.
|
||||
2. **Repeated chrome.** Every settings card has its own "Connecting" pill, "Restart required" pill, "Version 1",
|
||||
"Save changes" and "History". Workflows and Channels repeat the pattern.
|
||||
3. **Raw config shapes leak through.** Durations as Go strings (`1h0m0s`, `0s`), bytes as `2000000`,
|
||||
maps as key/value boxes, secret refs as two separate Engine/Key text fields, booleans as bare checkboxes with no explanation.
|
||||
4. **No descriptions.** Almost no field says what it does.
|
||||
5. **Things live in the wrong place.** Channels (configuration) sits under Work; "Start work" sits inside the
|
||||
workflow editor page; the Channels audit table only covers Channels; workflow analytics mix every workflow together.
|
||||
6. **The most important information isn't first.** The Dashboard opens with quality gates; the "3 need you" count is a small button.
|
||||
|
||||
## 2. Navigation (screenshot `P0-navigation-map.png`)
|
||||
|
||||
**Top bar (every page):** logo · **Dashboard · Tasks · Workflows · Events · Settings** · spacer ·
|
||||
"Jump to…" search (⌘K) · **New task** button · connection pill · account avatar.
|
||||
The Work and System dropdowns go away. The floating chat button stays, restyled (neutral fill, accent icon).
|
||||
|
||||
| Place | Job | Contains |
|
||||
|---|---|---|
|
||||
| Dashboard | What needs me right now | Needs-you queue, live activity, health (quality gates, tokens) |
|
||||
| Tasks | The work | Task list (filter by state), task detail |
|
||||
| Workflows | How work runs | List with runs/success/cost, definition editor, Performance and Runs tabs |
|
||||
| Events | What comes in | Inspector, Mappings, Bindings |
|
||||
| Settings | Everything you configure | **Agents:** Personas, Schedules, Scheduling policy · **Integrations:** Channels, Tools & MCP, Plugins · **Runtime:** Container runtime · **History** |
|
||||
|
||||
What moves:
|
||||
|
||||
| What | Moves to | Why |
|
||||
|---|---|---|
|
||||
| Start work card (Workflows page) | **New task** dialog from the top bar and ⌘K | Starting work isn't editing a workflow |
|
||||
| Channels (Work menu) | Settings › Integrations › Channels | It's configuration; gets the shared setting rows and save flow |
|
||||
| Audit table (Channels page) | Settings › History, filterable by section | One change log for all settings; replaces per-card History links |
|
||||
| Per workflow table | Columns in the Workflows list | Stats next to the workflow you're about to open |
|
||||
| Slowest stages · Most failures | Workflow › Performance tab | Scoped to the selected workflow |
|
||||
| Connecting / Version pills on every card | One connection status in the top bar | Connection is global |
|
||||
| Settings "Managed elsewhere" row | Removed; those are the Events tabs | They already live there |
|
||||
| Task "Attempt 2 is not recorded" column | Attempts list in the task side rail | Shows every attempt and its outcome |
|
||||
|
||||
The dropdown contents of today's Work and System menus were inferred from screenshots. **Check the router** and
|
||||
place any page not covered here using the same rule: configure → Settings, act on → where the work is.
|
||||
|
||||
## 3. Theme
|
||||
|
||||
All values are in `tokens/tokens.css`. Rules that matter more than the hex values:
|
||||
|
||||
- **One accent, used sparingly.** Default sage `#86b5a0`. Only for: active nav/list item (2px inset left bar + raised background),
|
||||
active tab underline, focus borders/rings, "edited" dots and counts, toggle "on" track, primary button fill, success text,
|
||||
the "live"/"running"/"connected" dot, and positive bars. Never for backgrounds, headings or borders at rest.
|
||||
- Keep the accent a **single variable** so it can be swapped (sage / steel `#8aa4c2` / sand `#d4a373` / muted violet `#a397c9`).
|
||||
- **Neutral, slightly warm greys**, no hue tint on surfaces and no background gradients. Hierarchy comes from surface steps and borders.
|
||||
- **Amber = needs attention** (parked, awaiting reply, applies after restart, connecting). **Red = failed / destructive / risky**
|
||||
(errors, delete, unrestricted filesystem). No other hues except the agent state swatches in the tokens.
|
||||
- **Fonts:** IBM Plex Sans for UI; **IBM Plex Mono for every machine value**: config values, IDs, keys, env var names,
|
||||
image refs, durations, paths, event names, task numbers, log lines, counts in tables.
|
||||
- Text contrast: `--text-3` is the dimmest text allowed, and only for hints and captions.
|
||||
|
||||
## 4. Components (screenshot `T-theme-components.png`)
|
||||
|
||||
Build these once and reuse everywhere. Heights are 36px unless noted.
|
||||
|
||||
| Component | Spec |
|
||||
|---|---|
|
||||
| **Button** | primary (accent fill, `--text-on-accent`), secondary (`--raised` + `--border-button`), ghost (transparent, `--text-2`), destructive (red text, transparent). 13px/500, radius 6. Small variant 30px/12px. **One primary per view.** |
|
||||
| **Text input** | `--bg` fill, `--border-input`, radius 6, mono 13px. Focus: accent border + 3px `--accent-ring`. Invalid: red border + 12px red message. |
|
||||
| **Input with unit** | input + attached suffix (`MB`, `sec`, `chars`) or unit `<select>`. |
|
||||
| **Duration input** | number + unit select. Convert to/from Go durations (`30s`, `1m0s`, `72h0m0s`) only at the API boundary. |
|
||||
| **Byte size input** | number + `MB`; store bytes (2,000,000 bytes = 2 MB, decimal). |
|
||||
| **Stepper** | − / value / + for small integers. |
|
||||
| **Toggle** | 36×20 track. On = accent (or red for risky settings), off = `--border-input`. Always labelled; risky ones sit in a bordered row with a one-line consequence. Real checkbox / `role="switch"` underneath. |
|
||||
| **Segmented control** | 2–4 exclusive options, radiogroup with arrow keys. Selected segment `--raised-2`. |
|
||||
| **Tabs** | 44px, 13px, `--text-3`; active = `--text` + 2px accent underline. Left-aligned, sized to content (not stretched full width). Optional mono count chip. |
|
||||
| **Secret reference** | one row: lock icon · engine (mono, dim) · `/` · key (mono) · "Change". Status line below: accent ✓ "Credential resolved by Archie" or red "Credential not found". Replaces separate Engine/Key inputs and the "Credential configured" checkbox. |
|
||||
| **Chip input** | for lists of IDs (Telegram allowed users): mono chips with × plus an inline input. |
|
||||
| **Status pill** | radius 999, 12px. Neutral with coloured dot (connection, running, listening), warn (parked, awaiting reply, applies after restart), accent outline (edited count, default), danger (invalid). |
|
||||
| **Card** | `--surface`, `--border-card`, radius 10. Header row: optional 32px icon tile · title (15px/500) + hint · right-side status/action. |
|
||||
| **Stat strip** | one card split into equal cells by 1px dividers: label (12px dim), value (30px/600), sub (12px dim). |
|
||||
| **Data table** | uppercase 11px headers, 13px rows, 1px `--border-subtle` dividers, mono for machine values, long text truncates with ellipsis. |
|
||||
| **Progress bar** | 4–6px track `--raised-2`, fill accent (good) or red (failing). |
|
||||
| **Empty state** | icon tile + title + one-line hint + the action (a button, or a copyable value). |
|
||||
| **Alert banner** | amber or red tinted box: icon · title · mono detail · one action on the right. |
|
||||
| **Nav item** (sidebars) | 34–36px, radius 6, 13px `--text-2`. Active: `--raised` + 2px inset accent bar. |
|
||||
| **Dialog** | 640px, `--surface-2`, radius 12, header (title + hint + close), body, footer (shortcut hint · Cancel · primary). Dim backdrop. |
|
||||
|
||||
Icons: 2px-stroke line icons. Use the app's existing icon set if it has one (e.g. Lucide).
|
||||
|
||||
## 5. Settings
|
||||
|
||||
### 5.1 Settings shell (`S1-settings-sidebar-setting-rows*.png`)
|
||||
- **Left sidebar (248–264px)** with grouped nav: AGENTS (Personas, Schedules, Scheduling policy), INTEGRATIONS (Channels, Tools & MCP, Plugins),
|
||||
RUNTIME (Container runtime), divider, History. Optional mono counts (Personas `6`). A section with unsaved edits shows an accent dot.
|
||||
- **Content column** max ~920–980px. Section header: 24px title, 14px description, amber "Applies after restart" pill when relevant.
|
||||
- **Groups** inside a section: 13px uppercase eyebrow.
|
||||
- **Setting row:** 2-column grid `260–280px | 1fr`, gap 32px, 16–20px vertical padding, 1px top border.
|
||||
Left: label (13px/500) + hint (12px dim). Right: the control.
|
||||
- Sidebar items are links (route or hash per section).
|
||||
|
||||
### 5.2 Save model (`S1` save bar + `S4-settings-review-drawer.png`)
|
||||
Replace every per-card Save button with one page-level flow:
|
||||
1. Track edits per field against the loaded config. Edited inputs get an accent border and a "was `old`" hint.
|
||||
2. When anything is dirty, a **sticky save bar** appears: accent dot · "N unsaved change(s)" · field names · **Discard** · primary
|
||||
**"Save & restart"** if any dirty field needs a restart, otherwise **"Save"**.
|
||||
3. The primary button opens the **Review drawer** (480px, right, dim backdrop): "Review N changes", "Saved together as config version N+1",
|
||||
amber restart callout (optionally with running agent count), changes grouped by section as cards with **Revert** and a mono diff
|
||||
(red `− old`, green `+ new`), footer Discard all · Save only · Save & restart.
|
||||
4. Personas keep their own save footer in the editor panel but still feed the page dirty state.
|
||||
|
||||
**Backend questions to answer first:** can several sections be saved atomically (or will saves be sequential with partial-failure handling)?
|
||||
Is "restart required" known per field or per section? Is there a restart action? If not, "Save & restart" becomes "Save" plus a
|
||||
persistent "Restart pending" banner.
|
||||
|
||||
### 5.3 Personas (`S2-settings-personas.png`)
|
||||
- Left: filter + New; list rows = name + one-line prompt; default persona has an accent-outline **default** pill; selected row = raised + accent bar.
|
||||
- Right: editor. Header: name + default pill · Duplicate · Delete. Body: Name (mono) and **Default persona** toggle; **System prompt** as a large
|
||||
mono textarea with "N chars · ~N tokens". Footer: "Saved · version N · History" · Discard · Save persona.
|
||||
- The old separate "Default" field becomes the per-persona toggle (setting one unsets the others).
|
||||
- The "try this persona" preview row is optional/future.
|
||||
- The mockup uses **top tabs** for section navigation; that's the narrow-width fallback. Use the sidebar shell on desktop.
|
||||
|
||||
### 5.4 Schedules
|
||||
Not mocked. Card empty state ("No schedules yet" + "Add schedule"); populated = list rows like Personas.
|
||||
|
||||
### 5.5 Scheduling policy (`S1`)
|
||||
- DISPATCH: *Trigger* segmented Assignee / Label (show the Label input only when Label is chosen); *Ack reaction* mono input.
|
||||
- STATE LABELS: bordered table `STATE | LABEL | ⌫` with coloured state swatch, mono label input, trash button, "+ Add state".
|
||||
Today's UI shows display name ("Dead"), key (`dead`) and value (`agent:dead`); the mockup merges name and key.
|
||||
If the key must stay editable, keep a small mono input in the State column.
|
||||
- RETRIES & POLLING: *Max retries* stepper; *Poll interval* duration input.
|
||||
|
||||
### 5.6 Channels (moved from Work; `S5-settings-channels.png`, today `00-current-channels.png`)
|
||||
- One card per channel. **Configured** channels are expanded with setting rows; **unconfigured** ones collapse to a single row
|
||||
(icon · name · one-line purpose · "Not set up" pill · **Set up** button that expands the fields).
|
||||
- **Telegram** (running): header status pill "Running" (accent). Rows: *Bot token* = secret reference (`env / HEYARCHIE_TELEGRAM_BOT_TOKEN`) + resolved line;
|
||||
*Allowed users* = chip input of numeric IDs, hint "Everyone else is ignored."
|
||||
- **Email** (collapsed): expands to *Listen address*, *Relay address*.
|
||||
- **Webhook** (collapsed): expands to *Deliver to*, *Path*, *Template*, *Signing secret* (secret reference), and *Webhook address*
|
||||
(today's top-level "Webhook addr" belongs here if it only serves the webhook channel; confirm).
|
||||
- **CHAT SESSION DEFAULTS · ALL CHANNELS** card with setting rows: *Workspace* (mono path), *Filesystem access* (Unrestricted filesystem toggle in a
|
||||
**red** bordered row: "On: agents can read and write anywhere this user can."), *Show tool calls* toggle, *Max steps*
|
||||
("0 = no limit": **confirm the real semantics**), *Rate limit* as "[n] requests per [n] [unit]" ("Off while either value is 0": confirm),
|
||||
*Models*, *Operator*.
|
||||
- Footer line: "Version N · N fields set by `actor` N ago · View in History". The audit table itself moves to Settings › History.
|
||||
- Channel status (running / stopped / error) must come from the backend, not from whether it's configured.
|
||||
|
||||
### 5.7 Tools & MCP (`S3-settings-tools-mcp.png`)
|
||||
- Header action **Add MCP server**. MCP servers card (full width): empty state offering "stdio command" / "HTTP / SSE endpoint"
|
||||
(only the transports the backend supports); populated rows = name, transport, enabled toggle, edit/delete.
|
||||
- **MiniMax** card: header "Enabled" toggle; API key as secret reference (`bws / MINIMAX_API_KEY`) + resolved line.
|
||||
- **Web fetch** card: "Enabled" toggle; *Max download* (bytes as MB); *Timeout* (duration, sec); *Allow private networks* as a bordered
|
||||
toggle row. Disable the fields when the card is off.
|
||||
- **Tool output policy** card: *Max result length* (`chars`, hint "About N tokens per tool call", ~4 chars/token), *Spill directory*.
|
||||
|
||||
### 5.8 Plugins
|
||||
Not mocked. Setting rows for *Module dir*, *Plugin dir*, *Secret engine dir*, *Skills dir* (mono, placeholder = effective default if exposed).
|
||||
|
||||
### 5.9 Container runtime (left side of `S4`)
|
||||
*Image* (full width, mono), *Max concurrency* (stepper), *Max uptime* (duration), *Network* (mono),
|
||||
*Pull policy* (select: If missing / Always / Never → `missing` / `always` / `never`), *Volume TTL* (duration), *Profiles* (mono).
|
||||
|
||||
### 5.10 History (new, not mocked)
|
||||
The Channels audit table generalised to all settings: When · Section · Field (mono) · Old → New (mono, truncated, expandable) ·
|
||||
Version · Changed by. Filters: section, actor, date. Every "History" link elsewhere deep-links here with the section filter applied.
|
||||
|
||||
## 6. App pages
|
||||
|
||||
### 6.1 Dashboard (`P1-dashboard.png`, today `00-current-dashboard.png`)
|
||||
- Header: "Good morning" + a one-line summary that **names the action** ("Nothing is running. 3 tasks need you." with the count in amber). Logs button on the right.
|
||||
- **Stat strip**: Working now / Needs you (amber value) / Delivered / Tokens used, with the same subtitles as today.
|
||||
- Two columns: main (1fr) and right rail (380px).
|
||||
- Main, first: **Needs you** card (count pill). One row per task: state pill (Parked / Awaiting reply) · title (link) ·
|
||||
mono meta line (`repo #issue · workflow · reason or last message`, truncated) · **Open** (ghost) + the next action
|
||||
(**Start new run** for parked, **Reply** for awaiting). "All tasks" link in the header.
|
||||
- Main, second: **Live activity** table: Event (mono, small colour square by kind, `×N` chip when consecutive identical events are grouped) · Task (mono) ·
|
||||
Detail (truncated) · When. Header: live pill + segmented filter All / Tasks / System.
|
||||
- Right rail: **Quality gates** (big pass rate, one row per gate with `passed / runs` and a bar: red when failing, accent when passing) and
|
||||
**Token outlook** (Today, "Next 30 days at this rate", a 7-day mini bar chart, and a note when history is shorter than a week).
|
||||
Today's full-width purple bar that shows nothing is removed.
|
||||
|
||||
### 6.2 Task detail (`P2-task-detail.png`, today `00-current-task-detail.png`)
|
||||
- Breadcrumb `Tasks / #1`, title, meta row: status pill · workflow (mono) · `repo #issue` link. Actions: **Archive** (ghost), **Start a new run** (primary).
|
||||
- **Alert banner** for parked/failed tasks: plain-language title ("Parked: couldn't prepare the worktree"), mono error detail, "Jump to log line".
|
||||
- Two columns: main card with tabs **Log · Changed files (count) · Configuration · Debug**; right rail (320px).
|
||||
- Log tab: toolbar = level select, stage select, search, Download. Log lines in mono: time · level (ERROR in red) · message with tag chips
|
||||
(`component=daemon`, `task=1`). Error lines get a faint red background and red left border. Footer "End of attempt N · N lines".
|
||||
- Right rail: **Attempts** list (dot colour = outcome; selected attempt highlighted; unrecorded attempts shown dimmed) and
|
||||
**Details** list (Status, Workflow link, Repository, Issue ↗, plus Persona, Tokens, Started if available).
|
||||
|
||||
### 6.3 Workflows (`P3-workflows.png`, today `00-current-workflows.png`)
|
||||
- Header: title + description ("Success rate is merged tasks over all runs"), **Restore shipped** (ghost), **New workflow**.
|
||||
- Left (420px): list = name + id (mono) · runs · success (`n of m` + bar) · avg tokens (compact: 4.7M, 282k). Selected = raised + accent bar.
|
||||
- Right: editor card. Header: name + origin pill (e.g. "shipped · edited"; derive from the real origin field) + run count.
|
||||
Tabs **Definition · Performance · Runs**.
|
||||
- Definition: *ID* input; *Steps* read-only preview (mono step chips joined by arrows, parsed from YAML);
|
||||
*YAML* editor with line numbers, mono, light syntax colouring, live "✓ Valid" / error indicator.
|
||||
Footer: "Version N · History" · Remove (destructive ghost) · Restore this workflow · **Validate & save**.
|
||||
- Performance (not mocked): today's **Slowest stages** and **Most failures**, filtered to this workflow.
|
||||
- Runs (not mocked): tasks that used this workflow, linking to Task detail.
|
||||
- The **Start work** card leaves this page (see 6.4).
|
||||
|
||||
### 6.4 New task dialog (`P4-new-task-dialog.png`)
|
||||
Replaces the Start work card. Opened from the top bar button, ⌘K, and optionally from a workflow ("Start task with this workflow").
|
||||
- Fields: *Repository* (mono, hint with recent repos), *Workflow* as a 3-column card radiogroup showing each workflow's runs and merge rate,
|
||||
*Title*, *Instructions* (textarea), and **Identity** tucked into an "Advanced · run as identity" disclosure.
|
||||
- Footer: "⌘↵ to start" · Cancel · **Start task**. On success, go to the new task's detail page.
|
||||
|
||||
### 6.5 Events (`P5-events.png`, today `00-current-events.png`)
|
||||
- Header with description ("Webhooks come in, get mapped to event types, and bindings turn them into work.") and a **Listening** pill.
|
||||
- Left-aligned tabs **Inspector · Mappings · Bindings** with count chips. (Reordered to follow the flow; keep the old order if you prefer.)
|
||||
- Inspector: a 3-step strip **Capture → Map → Bind** with counts; then **Recent captures** (empty state with the copyable endpoint
|
||||
`/webhooks/capture/<source>` and a Copy button) and **Event types** ("From payload" action, empty state explaining proposals).
|
||||
|
||||
## 7. Behaviour and accessibility
|
||||
|
||||
- Real `<button>`, `<a href>`, `<input>`, `<select>`, `<label for>`; icon-only buttons get `aria-label`. Toggles use checkbox/`role="switch"`.
|
||||
Segmented controls and workflow cards are radiogroups with arrow-key support. Dialogs trap focus and close on Esc.
|
||||
- Visible focus everywhere (accent ring). Touch targets ≥36px (44px on mobile).
|
||||
- Validate on blur; invalid fields block Save and are listed in the save bar.
|
||||
- Unsaved-changes guard on route leave.
|
||||
- Skeleton rows while loading; the top-bar connection pill reflects the socket/API state (Connecting amber, Connected accent, Disconnected red).
|
||||
- Live tables (activity, captures) insert new rows without layout jump; group consecutive identical events.
|
||||
- Narrow widths (<960px): settings sidebar → top tabs; two-column layouts stack; drawers and dialogs go full-width.
|
||||
|
||||
## 8. Suggested PR sequence
|
||||
|
||||
1. **Theme tokens only.** Swap purple for Graphite across the whole app. No layout changes. *Done when no purple remains.*
|
||||
2. **Shared components** from §4.
|
||||
3. **Top bar + navigation** (§2): new top-level items, New task button (can open the existing Start work form at first), one connection pill, route moves/redirects.
|
||||
4. **Settings shell** (sidebar groups, setting rows) and move Channels into it. Sections still save the old way.
|
||||
5. **Settings sections**: Scheduling policy, Plugins, Container runtime, Tools & MCP, Channels, Personas.
|
||||
6. **Unified save bar + review drawer + Settings › History** (needs the §5.2 backend decisions). Remove per-card save buttons and pills.
|
||||
7. **Dashboard.**
|
||||
8. **Task detail.**
|
||||
9. **Workflows** (list + editor + Performance tab) and **New task dialog**; remove the Start work card.
|
||||
10. **Events.**
|
||||
|
||||
Each PR: before/after screenshots and a note of anything deferred or unsupported.
|
||||
|
||||
## 9. Open questions / out of scope
|
||||
|
||||
- Real meaning of `max_steps = 0` and a zero rate limit (the mockup assumes "no limit" / "off").
|
||||
- Whether "Webhook addr" is webhook-channel-only or global.
|
||||
- Where the Dashboard's Needs-you reasons and last agent message come from.
|
||||
- Persona preview, light theme, user-facing accent picker (nice to have).
|
||||
- Atomic multi-section save and "restart now" (see §5.2).
|
||||
@@ -0,0 +1,95 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Proposed navigation</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.node{display:flex;align-items:baseline;gap:10px;font-size:14px;font-weight:500}
|
||||
.sub{font-size:12px;color:#8f8c85;font-weight:400}
|
||||
.kid{margin:6px 0 0 18px;padding-left:14px;border-left:1px solid #2e3034;display:flex;flex-direction:column;gap:6px;font-size:13px;color:#a6a39b}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.tbl{width:100%;border-collapse:collapse;font-size:13px}
|
||||
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 14px;border-bottom:1px solid #2a2c30}
|
||||
.tbl td{padding:10px 14px;border-bottom:1px solid #202225;vertical-align:top;line-height:1.45}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1120px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 28px">
|
||||
<div>
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Navigation: today → proposed</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Five top-level places, each with one job. Anything you configure lives in Settings; anything you act on lives where the work is.</p>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 380px minmax(0, 1fr); gap: 24px">
|
||||
<section class="card" style="padding: 24px; display: flex; flex-direction: column; gap: 16px">
|
||||
<div class="eyebrow">Today</div>
|
||||
<div class="node" style="color: #a6a39b">Dashboard</div>
|
||||
<div><div class="node" style="color: #a6a39b">Work <span class="sub">dropdown</span></div>
|
||||
<div class="kid"><span>Tasks</span><span>Workflows <span class="sub">editor + start work + stats</span></span><span>Channels <span class="sub">settings + audit</span></span></div></div>
|
||||
<div><div class="node" style="color: #a6a39b">Events</div>
|
||||
<div class="kid"><span>Inspector · Bindings · Mappings</span></div></div>
|
||||
<div><div class="node" style="color: #a6a39b">System <span class="sub">dropdown</span></div>
|
||||
<div class="kid"><span>Advanced <span class="sub">6 cards, 6 save buttons</span></span></div></div>
|
||||
<p class="hint" style="margin: 8px 0 0">Dropdown contents are inferred from the screenshots; confirm against the router.</p>
|
||||
</section>
|
||||
|
||||
<section class="card" style="padding: 24px">
|
||||
<div class="eyebrow" style="margin-bottom: 16px; color: #86b5a0">Proposed</div>
|
||||
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px 32px">
|
||||
<div><div class="node">Dashboard <span class="sub">what needs me</span></div>
|
||||
<div class="kid"><span>Needs you queue</span><span>Live activity</span><span>Health: gates, tokens</span></div></div>
|
||||
<div><div class="node">Tasks <span class="sub">the work</span></div>
|
||||
<div class="kid"><span>Task list <span class="sub">filter by state</span></span><span>Task detail <span class="sub">log · files · config · debug</span></span><span>Attempts in a side rail</span></div></div>
|
||||
<div><div class="node">Workflows <span class="sub">how work runs</span></div>
|
||||
<div class="kid"><span>List with success + cost</span><span>Definition editor</span><span>Performance tab <span class="sub">stages, failures</span></span></div></div>
|
||||
<div><div class="node">Events <span class="sub">what comes in</span></div>
|
||||
<div class="kid"><span>Inspector</span><span>Bindings</span><span>Mappings</span></div></div>
|
||||
<div style="grid-column: span 2"><div class="node">Settings <span class="sub">everything you configure, one save flow</span></div>
|
||||
<div class="kid" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px 24px">
|
||||
<span><span style="color: #e8e6e1">Agents</span><br>Personas · Schedules · Scheduling policy</span>
|
||||
<span><span style="color: #e8e6e1">Integrations</span><br>Channels · Tools & MCP · Plugins</span>
|
||||
<span><span style="color: #e8e6e1">Runtime</span><br>Container runtime · History</span>
|
||||
</div></div>
|
||||
</div>
|
||||
<div style="margin-top: 24px; padding-top: 16px; border-top: 1px solid #232529; display: flex; gap: 24px; font-size: 13px; color: #a6a39b">
|
||||
<span><span style="color: #e8e6e1; font-weight: 500">Always in the top bar:</span> New task · ⌘K Jump to · connection status</span>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<section class="card" style="overflow: hidden">
|
||||
<table class="tbl">
|
||||
<thead><tr><th style="width: 290px">What</th><th style="width: 280px">Moves to</th><th>Why</th></tr></thead>
|
||||
<tbody>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Start work card (Workflows)</td><td><span style="color: #86b5a0">→</span> New task dialog, from the top bar</td><td style="color: #a6a39b">Starting work is not editing a workflow. One entry point from any page, and from ⌘K.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Channels (Work menu)</td><td><span style="color: #86b5a0">→</span> Settings › Integrations › Channels</td><td style="color: #a6a39b">It is configuration. It gets the same setting rows, secret fields and save flow as the rest.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Audit table (Channels page)</td><td><span style="color: #86b5a0">→</span> Settings › History</td><td style="color: #a6a39b">One change log for every setting, filterable by section. Replaces six History links.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Per workflow table</td><td><span style="color: #86b5a0">→</span> Workflows list columns</td><td style="color: #a6a39b">Runs, success and cost sit next to the workflow you are about to open.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Slowest stages · Most failures</td><td><span style="color: #86b5a0">→</span> Workflow › Performance tab</td><td style="color: #a6a39b">Scoped to the selected workflow instead of mixing every workflow in one table.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Connecting · Version pills on every card</td><td><span style="color: #86b5a0">→</span> One status in the top bar</td><td style="color: #a6a39b">Connection is global. Version shows once per page, in History.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Settings "Managed elsewhere" row</td><td><span style="color: #86b5a0">→</span> Events tabs</td><td style="color: #a6a39b">Captured events, mappings and bindings already live there.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Task "Attempt 2 is not recorded" column</td><td><span style="color: #86b5a0">→</span> Attempts list in the task side rail</td><td style="color: #a6a39b">Shows every attempt with its outcome; the empty column goes away.</td></tr>
|
||||
|
||||
<tr><td style="color: #e8e6e1">Dashboard stat cards and health</td><td><span style="color: #86b5a0">→</span> Stat strip + right rail</td><td style="color: #a6a39b">"Needs you" becomes the first thing on the page, with actions inline.</td></tr>
|
||||
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,187 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Dashboard</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:15px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tbl{width:100%;border-collapse:collapse;font-size:13px}
|
||||
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 20px;border-bottom:1px solid #2a2c30}
|
||||
.tbl td{padding:10px 20px;border-bottom:1px solid #202225;vertical-align:middle}
|
||||
.chip{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:1px 6px;margin-left:6px}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#" class="on">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
|
||||
<div style="display: flex; align-items: flex-end; gap: 16px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Good morning</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Nothing is running. <span style="color: #d9a45b">3 tasks need you.</span></p>
|
||||
</div>
|
||||
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h10M4 18h13"></path></svg>Logs</button>
|
||||
</div>
|
||||
|
||||
<section class="card" style="flex-direction: row">
|
||||
|
||||
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<div class="hint">Working now</div>
|
||||
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">0</div>
|
||||
<div class="hint" style="margin-top: 2px">0 waiting to start</div>
|
||||
</div>
|
||||
|
||||
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<div class="hint">Needs you</div>
|
||||
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #d9a45b">3</div>
|
||||
<div class="hint" style="margin-top: 2px">Parked or awaiting a reply</div>
|
||||
</div>
|
||||
|
||||
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<div class="hint">Delivered</div>
|
||||
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">1</div>
|
||||
<div class="hint" style="margin-top: 2px">25% of all tasks</div>
|
||||
</div>
|
||||
|
||||
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<div class="hint">Tokens used</div>
|
||||
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: #e8e6e1">14.5M</div>
|
||||
<div class="hint" style="margin-top: 2px">Across 1 day</div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 380px; gap: 24px; min-height: 0; flex-grow: 1">
|
||||
<div style="display: flex; flex-direction: column; gap: 24px; min-width: 0">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Needs you</span><span class="pill warn">3</span><div style="flex-grow: 1"></div><a href="#" class="hint" style="text-decoration: underline">All tasks</a></div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
|
||||
<span class="pill warn" style="justify-self: start">Parked</span>
|
||||
<div style="min-width: 0">
|
||||
<a href="#" style="font-size: 14px; font-weight: 500">changes_captured key-set validation is top-level only</a>
|
||||
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archie-core #868 · tdd · worktree prepare failed: fetch origin: http transport…</div>
|
||||
</div>
|
||||
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Start new run</button></div>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
|
||||
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
|
||||
<div style="min-width: 0">
|
||||
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
|
||||
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
|
||||
</div>
|
||||
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
|
||||
<span class="pill warn" style="justify-self: start">Awaiting reply</span>
|
||||
<div style="min-width: 0">
|
||||
<a href="#" style="font-size: 14px; font-weight: 500">[Task title]</a>
|
||||
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">[repo #issue] · [workflow] · [last agent message]</div>
|
||||
</div>
|
||||
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">Reply</button></div>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
<section class="card" style="flex-grow: 1; overflow: hidden">
|
||||
<div class="card-h"><span class="card-t">Live activity</span><span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>live</span><div style="flex-grow: 1"></div>
|
||||
<div role="radiogroup" aria-label="Filter activity" style="display: inline-flex; padding: 2px; border: 1px solid #2e3034; border-radius: 7px"><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">All</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Tasks</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">System</button></div>
|
||||
</div>
|
||||
<table class="tbl">
|
||||
<thead><tr><th>Event</th><th style="width: 70px">Task</th><th>Detail</th><th style="width: 110px">When</th></tr></thead>
|
||||
<tbody>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run</td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">19 mins ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>task_archive_requested</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">archive requested with no recorded actor</td><td class="hint">1 hr ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #d9776b"></span>task_abandoned</td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">abandoned with no recorded actor</td><td class="hint">1 hr ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #6f6c66"></span>curator_run<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">—</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">session-memory</td><td class="hint">1 hr ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×4</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#5</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">1 hr ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×5</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">7 hrs ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Problem surface for samcharles93/archie-core issue 836 ("Updater cannot detect o…</td><td class="hint">7 hrs ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #86b5a0"></span>agent_finish</td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">Root cause</td><td class="hint">7 hrs ago</td></tr>
|
||||
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: #8aa4c2"></span>stage_start<span class="chip">×6</span></td><td class="mono" style="font-size: 12px; color: #a6a39b">#4</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis"></td><td class="hint">8 hrs ago</td></tr>
|
||||
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 24px">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Quality gates</span><div style="flex-grow: 1"></div><span class="hint">last 4 runs</span></div>
|
||||
<div style="padding: 20px; display: flex; flex-direction: column; gap: 16px">
|
||||
<div style="display: flex; align-items: baseline; gap: 10px"><span style="font-size: 30px; font-weight: 600">25%</span><span class="hint">pass rate</span></div>
|
||||
|
||||
<div>
|
||||
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">tdd</span><span style="margin-left: auto; color: #a6a39b" class="mono">0 / 3</span></div>
|
||||
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 2%; background: #d9776b"></div></div>
|
||||
</div>
|
||||
|
||||
<div>
|
||||
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">triage</span><span style="margin-left: auto; color: #a6a39b" class="mono">1 / 1</span></div>
|
||||
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: 100%; background: #86b5a0"></div></div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Token outlook</span></div>
|
||||
<div style="padding: 20px; display: flex; flex-direction: column; gap: 14px">
|
||||
<div style="display: flex; gap: 24px">
|
||||
<div><div class="hint">Today</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">14.5M</div></div>
|
||||
<div><div class="hint">Next 30 days at this rate</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">≈ 434M</div></div>
|
||||
</div>
|
||||
<div aria-label="Tokens per day, last 7 days" style="display: flex; align-items: flex-end; gap: 6px; height: 64px">
|
||||
<div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">M</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">W</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">T</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 48px; border-radius: 3px; background: #86b5a0"></div><span class="mono" style="font-size: 10px; color: #8f8c85">F</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: 3px; border-radius: 3px; background: #26282c"></div><span class="mono" style="font-size: 10px; color: #8f8c85">S</span></div>
|
||||
</div>
|
||||
<div class="hint">Only 1 day of history. The projection steadies after a week of runs.</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<button aria-label="Chat with Archie" style="position: absolute; right: 24px; bottom: 24px; width: 48px; height: 48px; border-radius: 50%; border: 1px solid #34373c; background: #1e2023; color: #86b5a0; display: flex; align-items: center; justify-content: center; box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a8 8 0 0 1-11.6 7.1L4 20l1-4.6A8 8 0 1 1 21 12Z"></path></svg></button>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,127 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Task detail</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:14px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:14px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.sel{height:32px;box-sizing:border-box;padding:0 10px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:13px 'IBM Plex Sans',sans-serif}
|
||||
.kv{display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px;font-size:13px;padding:8px 0;border-bottom:1px solid #202225}
|
||||
.kv dt{color:#8f8c85}.kv dd{margin:0}
|
||||
.tag{font:11px 'IBM Plex Mono',monospace;color:#a6a39b;background:#1e2023;border-radius:4px;padding:1px 6px}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1000px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#" class="on">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 24px 48px 32px; display: flex; flex-direction: column; gap: 20px; min-height: 0">
|
||||
<div>
|
||||
<div class="hint"><a href="#" style="color: #a6a39b">Tasks</a> / <span class="mono">#1</span></div>
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px; margin-top: 8px">
|
||||
<div style="flex-grow: 1; min-width: 0">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">changes_captured key-set validation is top-level only</h1>
|
||||
<div style="display: flex; align-items: center; gap: 12px; margin-top: 8px; font-size: 13px; color: #a6a39b">
|
||||
<span class="pill warn"><span class="dot" style="background: #d9a45b"></span>Parked</span>
|
||||
<span class="mono">tdd</span><span style="color: #4a4c50">·</span>
|
||||
<a href="#" class="mono" style="color: #a6a39b; text-decoration: underline">samcharles93/archie-core #868</a>
|
||||
</div>
|
||||
</div>
|
||||
<button class="btn btn-ghost">Archive</button>
|
||||
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>Start a new run</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div role="alert" style="display: flex; gap: 12px; padding: 14px 16px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25)">
|
||||
<svg style="flex-shrink: 0; margin-top: 2px" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#d9a45b" stroke-width="2"><path d="M12 3 2 20h20L12 3Z"></path><path d="M12 10v4M12 17h.01"></path></svg>
|
||||
<div style="min-width: 0; flex-grow: 1">
|
||||
<div style="font-size: 14px; font-weight: 500; color: #e3c08f">Parked: couldn’t prepare the worktree</div>
|
||||
<div class="mono" style="font-size: 12px; color: #a6a39b; margin-top: 4px; line-height: 1.6; word-break: break-all">fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
|
||||
</div>
|
||||
<button class="btn btn-sm" style="align-self: flex-start">Jump to log line</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 24px; flex-grow: 1; min-height: 0">
|
||||
<section class="card" style="overflow: hidden">
|
||||
<nav style="display: flex; gap: 28px; padding: 0 20px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Log</a>
|
||||
<a class="tab" href="#">Changed files <span class="hint" style="margin-left: 6px">0</span></a>
|
||||
<a class="tab" href="#">Configuration</a>
|
||||
<a class="tab" href="#">Debug</a>
|
||||
</nav>
|
||||
<div style="display: flex; align-items: center; gap: 8px; padding: 12px 20px; border-bottom: 1px solid #232529">
|
||||
<select aria-label="Level" class="sel"><option>All levels</option></select>
|
||||
<select aria-label="Stage" class="sel"><option>All stages</option></select>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 32px; width: 260px; padding: 0 10px; box-sizing: border-box; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Search log" placeholder="Search log" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%"></label>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-sm btn-ghost"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 4v11M7 10l5 5 5-5M5 20h14"></path></svg>Download</button>
|
||||
</div>
|
||||
<div class="mono" style="font-size: 12px; line-height: 1.7; flex-grow: 1; background: #121314">
|
||||
<div style="display: grid; grid-template-columns: 72px 56px minmax(0, 1fr); gap: 12px; padding: 10px 20px; background: rgba(217,119,107,0.06); border-left: 2px solid #d9776b">
|
||||
<span style="color: #8f8c85">08:38:49</span>
|
||||
<span style="color: #e0a39a">ERROR</span>
|
||||
<div style="min-width: 0">
|
||||
<div style="word-break: break-all">task parked: worktree prepare failed: fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
|
||||
<div style="display: flex; gap: 6px; margin-top: 6px"><span class="tag">component=daemon</span><span class="tag">task=1</span></div>
|
||||
</div>
|
||||
</div>
|
||||
<div style="padding: 16px 20px; color: #8f8c85; font-family: 'IBM Plex Sans', sans-serif; font-size: 12px">End of attempt 1 · 1 line</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<aside style="display: flex; flex-direction: column; gap: 20px">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Attempts</span></div>
|
||||
<div style="padding: 8px 12px">
|
||||
<a href="#" style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; border-radius: 6px; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
|
||||
<span class="dot" style="background: #d9a45b"></span><span style="font-size: 13px; flex-grow: 1">Attempt 1</span><span class="hint">parked · 08:38</span></a>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; color: #8f8c85">
|
||||
<span class="dot" style="background: transparent; border: 1px dashed #4a4c50; box-sizing: border-box"></span><span style="font-size: 13px; flex-grow: 1">Attempt 2</span><span class="hint">not recorded</span></div>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Details</span></div>
|
||||
<dl style="margin: 0; padding: 4px 20px 12px">
|
||||
<div class="kv"><dt>Status</dt><dd style="color: #d9a45b">Parked</dd></div>
|
||||
<div class="kv"><dt>Workflow</dt><dd><a href="#" class="mono" style="text-decoration: underline">tdd</a></dd></div>
|
||||
<div class="kv"><dt>Repository</dt><dd class="mono" style="font-size: 12px">samcharles93/archie-core</dd></div>
|
||||
<div class="kv"><dt>Issue</dt><dd><a href="#" style="text-decoration: underline">#868</a> ↗</dd></div>
|
||||
<div class="kv"><dt>Persona</dt><dd class="mono" style="font-size: 12px">[persona]</dd></div>
|
||||
<div class="kv"><dt>Tokens</dt><dd class="mono" style="font-size: 12px">[tokens]</dd></div>
|
||||
<div class="kv" style="border: 0"><dt>Started</dt><dd>[date · time]</dd></div>
|
||||
</dl>
|
||||
</section>
|
||||
</aside>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,152 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Workflows</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.step{font:12px 'IBM Plex Mono',monospace;padding:6px 10px;border:1px solid #2e3034;border-radius:6px;background:#121314;white-space:nowrap}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#" class="on">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
|
||||
<div style="display: flex; align-items: flex-end; gap: 12px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Workflows</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">The step sequences agents follow. Success rate is merged tasks over all runs.</p>
|
||||
</div>
|
||||
<button class="btn btn-ghost"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"></path><path d="M3 3v5h5"></path></svg>Restore shipped</button>
|
||||
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New workflow</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 420px minmax(0, 1fr); gap: 24px; flex-grow: 1; min-height: 0">
|
||||
<section class="card" style="overflow: hidden">
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; padding: 10px 16px; font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: #8f8c85; border-bottom: 1px solid #2a2c30"><span>Workflow</span><span>Runs</span><span>Success</span><span style="text-align: right">Avg tok</span></div>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">Bootstrap</span><span class="mono" style="font-size: 11px; color: #8f8c85">bootstrap</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">Feasibility check</span><span class="mono" style="font-size: 11px; color: #8f8c85">feasibility</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">Implement</span><span class="mono" style="font-size: 11px; color: #8f8c85">implement</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">Remediate</span><span class="mono" style="font-size: 11px; color: #8f8c85">remediate</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">0</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">—</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 0%; background: #86b5a0"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">—</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">TDD</span><span class="mono" style="font-size: 11px; color: #8f8c85">tdd</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">3</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">0 of 3</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 2%; background: #d9776b"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">4.7M</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: transparent; box-shadow: none">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">Triage</span><span class="mono" style="font-size: 11px; color: #8f8c85">triage</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">1</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">1 of 1</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: 100%; background: #86b5a0"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">282k</span>
|
||||
</a>
|
||||
|
||||
</section>
|
||||
|
||||
<section class="card" style="overflow: hidden">
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px 0">
|
||||
<h2 style="margin: 0; font-size: 18px; font-weight: 600">Bootstrap</h2>
|
||||
<span class="pill">shipped · edited</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<span class="hint">0 runs yet</span>
|
||||
</div>
|
||||
<nav style="display: flex; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Definition</a>
|
||||
<a class="tab" href="#">Performance</a>
|
||||
<a class="tab" href="#">Runs</a>
|
||||
</nav>
|
||||
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px; flex-grow: 1; min-height: 0">
|
||||
<div style="display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 24px">
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="wid">ID</label><input id="wid" class="inp" value="bootstrap"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Steps</span>
|
||||
<div style="display: flex; align-items: center; gap: 6px; height: 36px; flex-wrap: nowrap; overflow: hidden">
|
||||
<span class="step">prepare</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">apply</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">commit-push</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">diff-cap</span><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg><span class="step">open-pr</span>
|
||||
</div></div>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px; flex-grow: 1; min-height: 0">
|
||||
<div style="display: flex; align-items: baseline"><span class="lbl">YAML</span><span class="hint" style="margin-left: auto; color: #86b5a0">✓ Valid</span></div>
|
||||
<div class="mono" style="flex-grow: 1; display: grid; grid-template-columns: 44px minmax(0, 1fr); border: 1px solid #2e3034; border-radius: 8px; background: #121314; font-size: 13px; line-height: 1.75; overflow: hidden">
|
||||
<div style="padding: 14px 0; text-align: right; padding-right: 12px; color: #4f5156; border-right: 1px solid #232529; background: #141517; white-space: pre-line">1
|
||||
2
|
||||
3
|
||||
4
|
||||
5
|
||||
6
|
||||
7</div>
|
||||
<div style="padding: 14px 16px; white-space: pre"><span style="color: #a6a39b">id:</span> bootstrap
|
||||
<span style="color: #a6a39b">steps:</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.prepare</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.apply</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.commit-push</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.diff-cap</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: #86b5a0">bootstrap.open-pr</span></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #2a2c30; background: #17181a">
|
||||
<span class="hint">Version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-ghost" style="color: #d9776b">Remove</button>
|
||||
<button class="btn">Restore this workflow</button>
|
||||
<button class="btn btn-primary">Validate & save</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,77 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>New task dialog</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.inp{box-sizing:border-box;height:38px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.opt{display:flex;flex-direction:column;gap:2px;padding:10px 12px;border:1px solid #2e3034;border-radius:8px;cursor:pointer}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; position: relative; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-sm" style="border-color: #86b5a0"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
</header>
|
||||
<div style="padding: 32px 48px"><div style="font-size: 28px; font-weight: 600; color: #3a3c40">Good morning</div></div>
|
||||
|
||||
<div style="position: absolute; inset: 0; background: rgba(8,9,10,0.6)"></div>
|
||||
|
||||
<section role="dialog" aria-modal="true" aria-labelledby="nt-title" style="position: absolute; left: 50%; top: 88px; transform: translateX(-50%); width: 640px; box-sizing: border-box; background: #17181a; border: 1px solid #2a2c30; border-radius: 12px; box-shadow: 0 24px 64px rgba(0,0,0,0.5); display: flex; flex-direction: column">
|
||||
<div style="display: flex; align-items: flex-start; padding: 22px 24px 18px; border-bottom: 1px solid #232529">
|
||||
<div style="flex-grow: 1"><h2 id="nt-title" style="margin: 0; font-size: 18px; font-weight: 600">New task</h2><div class="hint" style="margin-top: 2px">Goes into Archie’s normal task queue.</div></div>
|
||||
<button aria-label="Close" style="width: 32px; height: 32px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
|
||||
</div>
|
||||
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px">
|
||||
<div class="field"><label class="lbl" for="repo">Repository</label><input id="repo" class="inp" value="samcharles93/archie-core"><span class="hint">owner/repository · recent: archie-core</span></div>
|
||||
<div class="field"><span class="lbl">Workflow</span>
|
||||
<div role="radiogroup" aria-label="Workflow" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px">
|
||||
|
||||
<label class="opt" style="border-color: #86b5a0; background: #1e2023"><span style="font-size: 13px; font-weight: 500">TDD</span><span class="hint">3 runs · 0% merged</span></label>
|
||||
|
||||
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Triage</span><span class="hint">1 run · 100% merged</span></label>
|
||||
|
||||
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Implement</span><span class="hint">no runs yet</span></label>
|
||||
|
||||
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Remediate</span><span class="hint">no runs yet</span></label>
|
||||
|
||||
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Feasibility check</span><span class="hint">no runs yet</span></label>
|
||||
|
||||
<label class="opt" style="border-color: #2e3034; background: transparent"><span style="font-size: 13px; font-weight: 500">Bootstrap</span><span class="hint">no runs yet</span></label>
|
||||
|
||||
</div></div>
|
||||
<div class="field"><label class="lbl" for="ttl">Title</label><input id="ttl" class="inp" placeholder="What should Archie do?" style="font-family: 'IBM Plex Sans', sans-serif"></div>
|
||||
<div class="field"><label class="lbl" for="ins">Instructions</label><textarea id="ins" placeholder="Context, acceptance criteria, files to look at…" style="min-height: 120px; box-sizing: border-box; padding: 12px; background: #121314; border: 1px solid #2e3034; border-radius: 6px; color: #e8e6e1; font: 13px/1.6 'IBM Plex Sans', sans-serif; resize: vertical; outline: none"></textarea></div>
|
||||
<details style="font-size: 13px; color: #a6a39b"><summary style="cursor: pointer">Advanced · run as identity</summary></details>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #232529">
|
||||
<span class="hint"><span class="mono" style="padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘↵</span> to start</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-ghost">Cancel</button>
|
||||
<button class="btn btn-primary">Start task</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,102 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Events</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:15px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;gap:8px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.count{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:0 6px}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 900px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#" class="on">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px">
|
||||
<div>
|
||||
<div style="display: flex; align-items: flex-end; gap: 12px">
|
||||
<div style="flex-grow: 1"><h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Events</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Webhooks come in, get mapped to event types, and bindings turn them into work.</p></div>
|
||||
<span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>Listening</span>
|
||||
</div>
|
||||
<nav style="display: flex; gap: 28px; margin-top: 16px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Inspector</a>
|
||||
<a class="tab" href="#">Mappings <span class="count">0</span></a>
|
||||
<a class="tab" href="#">Bindings <span class="count">0</span></a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<section class="card" style="flex-direction: row">
|
||||
|
||||
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">1</span>
|
||||
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Capture</div><div class="hint">Webhooks received</div></div>
|
||||
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
|
||||
</div>
|
||||
|
||||
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">2</span>
|
||||
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Map</div><div class="hint">Payloads → event types</div></div>
|
||||
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
|
||||
</div>
|
||||
|
||||
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">3</span>
|
||||
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">Bind</div><div class="hint">Event types → work</div></div>
|
||||
<span class="mono" style="font-size: 20px; color: #8f8c85">0</span>
|
||||
</div>
|
||||
|
||||
</section>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 24px">
|
||||
<section class="card">
|
||||
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Recent captures</div><div class="hint">Headers and payloads are redacted before they’re stored.</div></div></div>
|
||||
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 12px; text-align: center">
|
||||
<div style="width: 40px; height: 40px; border-radius: 10px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="M22 12h-6l-2 3h-4l-2-3H2"></path><path d="M5.5 5h13L22 12v6a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-6Z"></path></svg></div>
|
||||
<div style="font-size: 14px; font-weight: 500">No captures yet</div>
|
||||
<div class="hint">Point a webhook at this endpoint and it shows up here live.</div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 4px 4px 4px 14px; border: 1px solid #2e3034; border-radius: 8px; background: #121314">
|
||||
<span class="mono" style="font-size: 13px">/webhooks/capture/<span style="color: #86b5a0"><source></span></span>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="8" width="12" height="12" rx="2"></rect><path d="M16 8V5a1 1 0 0 0-1-1H5a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h3"></path></svg>Copy</button>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Event types</div><div class="hint">Named shapes that mappings produce.</div></div>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9l-6-6Z"></path><path d="M12 12v6M9 15h6"></path></svg>From payload</button></div>
|
||||
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 8px; text-align: center">
|
||||
<div style="font-size: 14px; font-weight: 500">No event types or proposals</div>
|
||||
<div class="hint">Paste a sample payload and Archie proposes a type for it. Proposals from real captures appear here too.</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,176 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – sidebar layout</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
|
||||
.inp:focus{border-color:var(--accent)}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.icon-btn{width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:6px;border:1px solid transparent;background:transparent;color:#8f8c85;cursor:pointer}
|
||||
.icon-btn:hover{background:#1e2023;color:#e8e6e1}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
.row{display:grid;grid-template-columns:280px minmax(0,1fr);gap:32px;padding:20px 0;border-top:1px solid #232529}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;margin-top:4px;line-height:1.5}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; position: relative; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: #d9a45b"></span>
|
||||
Connecting to archie-core…
|
||||
</div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 240px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
|
||||
<input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%">
|
||||
<span style="font-family: 'IBM Plex Mono', monospace; font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span>
|
||||
</label>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 264px; flex-shrink: 0; box-sizing: border-box; padding: 24px 16px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">6</span></a>
|
||||
<a class="nav-item" href="#">Schedules<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">0</span></a>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Scheduling policy<span style="margin-left: auto; width: 6px; height: 6px; border-radius: 50%; background: #86b5a0" title="Unsaved changes"></span></a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#">Channels</a>
|
||||
<a class="nav-item" href="#">Tools & MCP</a>
|
||||
<a class="nav-item" href="#">Plugins</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#">History</a>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="font-size: 12px; color: #8f8c85; padding: 12px; line-height: 1.5; border: 1px solid #232529; border-radius: 8px">Config version 1 · last saved by <span style="color: #a6a39b">admin</span><br><a href="#" style="color: #86b5a0">View history</a></div>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; overflow: hidden; padding: 40px 56px 120px">
|
||||
<div style="max-width: 920px">
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Scheduling policy</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">How Archie picks up work items and labels them as they move through states.</p>
|
||||
</div>
|
||||
<span style="display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #d9a45b; background: rgba(217,164,91,0.1); border: 1px solid rgba(217,164,91,0.25); padding: 4px 10px; border-radius: 999px">
|
||||
<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
|
||||
Applies after restart</span>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Dispatch</h2>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Trigger</div><div class="hint">What causes a work item to be dispatched to an agent.</div></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 12px">
|
||||
<div role="radiogroup" aria-label="Trigger" style="display: inline-flex; align-self: flex-start; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
|
||||
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 13px 'IBM Plex Sans', sans-serif">Assignee</button>
|
||||
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 13px 'IBM Plex Sans', sans-serif">Label</button>
|
||||
</div>
|
||||
<div class="hint" style="margin: 0">Dispatches when Archie is assigned. Choose <span style="color: #a6a39b">Label</span> to set a trigger label instead.</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="ack">Ack reaction</label><div class="hint">Reaction posted when a work item is picked up.</div></div>
|
||||
<div><input id="ack" class="inp" value="eyes" style="width: 220px"></div>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">State labels</h2>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Labels by state</div><div class="hint">Label applied to the ticket as the agent moves between states.</div></div>
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; padding: 8px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85; background: #17181a; border-bottom: 1px solid #2a2c30"><span>State</span><span>Label</span><span></span></div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8f8c85"></span>queued</span>
|
||||
<input class="inp" aria-label="queued label" value="agent:queued" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove queued"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #8aa4c2"></span>working</span>
|
||||
<input class="inp" aria-label="working label" value="agent:working" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove working"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9a45b"></span>waiting</span>
|
||||
<input class="inp" aria-label="waiting label" value="agent:waiting" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove waiting"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #86b5a0"></span>pr</span>
|
||||
<input class="inp" aria-label="pr label" value="agent:pr" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove pr"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #6f6c66"></span>parked</span>
|
||||
<input class="inp" aria-label="parked label" value="agent:parked" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove parked"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: #d9776b"></span>dead</span>
|
||||
<input class="inp" aria-label="dead label" value="agent:dead" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove dead"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
|
||||
<button style="display: flex; align-items: center; gap: 6px; width: 100%; height: 38px; padding: 0 12px; border: 0; background: transparent; color: #a6a39b; font: 500 13px 'IBM Plex Sans', sans-serif; cursor: pointer"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add state</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Retries & polling</h2>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="retries">Max retries</label><div class="hint">Attempts before an item is labelled dead.</div></div>
|
||||
<div style="display: inline-flex; align-self: flex-start; border: 1px solid #2e3034; border-radius: 6px; overflow: hidden; width: fit-content">
|
||||
<button class="icon-btn" aria-label="Decrease" style="border-radius: 0">−</button>
|
||||
<input id="retries" class="inp" value="3" style="width: 56px; border: 0; border-radius: 0; text-align: center; border-left: 1px solid #2e3034; border-right: 1px solid #2e3034">
|
||||
<button class="icon-btn" aria-label="Increase" style="border-radius: 0">+</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="poll">Poll interval</label><div class="hint">How often the tracker is checked for new work.</div></div>
|
||||
<div style="display: flex; align-items: center; gap: 10px">
|
||||
<div style="display: flex">
|
||||
<input id="poll" class="inp" value="30" style="width: 80px; border-radius: 6px 0 0 6px; border-color: #86b5a0">
|
||||
<select aria-label="Poll unit" class="inp" style="border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>seconds</option><option>minutes</option></select>
|
||||
</div>
|
||||
<span style="font-size: 12px; color: #8f8c85">was <span style="font-family: 'IBM Plex Mono', monospace; text-decoration: line-through">1m0s</span></span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<div style="position: absolute; left: 264px; right: 0; bottom: 0; height: 72px; box-sizing: border-box; padding: 0 56px; display: flex; align-items: center; gap: 12px; background: #17181a; border-top: 1px solid #2a2c30">
|
||||
<span style="width: 8px; height: 8px; border-radius: 50%; background: #86b5a0"></span>
|
||||
<span style="font-size: 13px">1 unsaved change</span>
|
||||
<span style="font-size: 13px; color: #8f8c85">· Poll interval</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,154 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – personas</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.tab{height:44px;display:flex;align-items:center;padding:0 2px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: #86b5a0"></span>
|
||||
Connected · v1
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div style="padding: 32px 48px 0; border-bottom: 1px solid #232529; flex-shrink: 0">
|
||||
<div style="font-size: 12px; color: #8f8c85">System / Advanced</div>
|
||||
<h1 style="margin: 6px 0 20px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
|
||||
<nav style="display: flex; gap: 28px">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: #86b5a0">Personas</a>
|
||||
<a class="tab" href="#">Schedules</a>
|
||||
<a class="tab" href="#">Scheduling policy</a>
|
||||
<a class="tab" href="#">Tools & MCP</a>
|
||||
<a class="tab" href="#">Plugins</a>
|
||||
<a class="tab" href="#">Container runtime</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0; padding: 32px 48px 40px; gap: 32px">
|
||||
<section aria-label="Persona list" style="width: 340px; flex-shrink: 0; display: flex; flex-direction: column; gap: 12px">
|
||||
<div style="display: flex; align-items: center; gap: 8px">
|
||||
<label style="flex-grow: 1; display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
|
||||
<input aria-label="Filter personas" placeholder="Filter personas" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%">
|
||||
</label>
|
||||
<button class="btn" aria-label="New persona" style="padding: 0 12px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New</button>
|
||||
</div>
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 10px; overflow: hidden; background: #16171a">
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: #1e2023; box-shadow: inset 2px 0 0 #86b5a0">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">archie
|
||||
<span style="font-size: 11px; font-weight: 500; color: #86b5a0; border: 1px solid #86b5a0; border-radius: 999px; padding: 1px 8px">default</span>
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are Archie, a capable coding and project assistant. Be direct without being brusque…</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">helpful
|
||||
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a helpful, friendly AI assistant.</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">concise
|
||||
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a concise assistant. Keep responses brief and to the point.</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">technical
|
||||
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a technical expert. Provide detailed, accurate technical information.</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">creative
|
||||
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a creative assistant. Think outside the box and offer innovative solutions.</span>
|
||||
</a>
|
||||
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: transparent; box-shadow: none">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">teacher
|
||||
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">You are a patient teacher. Explain concepts clearly with examples.</span>
|
||||
</a>
|
||||
|
||||
</div>
|
||||
<div class="hint">Personas are system prompts an agent can adopt. The default is used when a work item doesn't specify one.</div>
|
||||
</section>
|
||||
|
||||
<section aria-label="Edit persona" style="flex-grow: 1; display: flex; flex-direction: column; border: 1px solid #2a2c30; border-radius: 10px; background: #16171a; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px; border-bottom: 1px solid #2a2c30">
|
||||
<h2 style="margin: 0; font-size: 18px; font-weight: 600">archie</h2>
|
||||
<span style="font-size: 11px; color: #86b5a0; border: 1px solid #86b5a0; border-radius: 999px; padding: 1px 8px">default</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent">Duplicate</button>
|
||||
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 24px; padding: 24px; flex-grow: 1">
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<label class="lbl" for="pname">Name</label>
|
||||
<input id="pname" class="inp" value="archie">
|
||||
<span class="hint">Lowercase, used as the persona key.</span>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<span class="lbl">Default persona</span>
|
||||
<label style="display: flex; align-items: center; gap: 10px; height: 36px; font-size: 13px; color: #a6a39b">
|
||||
<span style="width: 36px; height: 20px; border-radius: 999px; background: #86b5a0; position: relative; display: inline-block"><span style="position: absolute; right: 2px; top: 2px; width: 16px; height: 16px; border-radius: 50%; background: #121314"></span></span>
|
||||
Use when no persona is specified
|
||||
</label>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px; flex-grow: 1">
|
||||
<div style="display: flex; align-items: baseline"><label class="lbl" for="prompt">System prompt</label><span class="hint" style="margin-left: auto; font-family: 'IBM Plex Mono', monospace">312 chars · ~70 tokens</span></div>
|
||||
<textarea id="prompt" style="flex-grow: 1; min-height: 320px; box-sizing: border-box; padding: 16px; background: #121314; border: 1px solid #2e3034; border-radius: 8px; color: #e8e6e1; font: 400 13px/1.7 'IBM Plex Mono', monospace; resize: vertical; outline: none">You are Archie, a capable coding and project assistant. Be direct without being brusque, grounded in the actual workspace state, and use available tools when asked. Do not claim tools, files, memories, actions, or results you have not verified. Do not impersonate another assistant, provider, or vendor.</textarea>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 14px 16px; border: 1px dashed #2e3034; border-radius: 8px">
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M4 12h12M12 6l6 6-6 6"></path></svg>
|
||||
<span style="font-size: 13px; color: #a6a39b; flex-grow: 1">Try this persona against a sample message before saving</span>
|
||||
<button class="btn">Open preview</button>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30; background: #17181a">
|
||||
<span style="font-size: 12px; color: #8f8c85">Saved · version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn btn-primary">Save persona</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,144 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – tools and MCP</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:18px 20px;border-bottom:1px solid #232529}
|
||||
.card-b{padding:20px;display:flex;flex-direction:column;gap:18px}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: #86b5a0"></span>
|
||||
Connected · v1
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 232px; flex-shrink: 0; box-sizing: border-box; padding: 24px 12px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas</a>
|
||||
<a class="nav-item" href="#">Schedules</a>
|
||||
<a class="nav-item" href="#">Scheduling policy</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#">Channels</a>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Tools & MCP</a>
|
||||
<a class="nav-item" href="#">Plugins</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#">History</a>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; padding: 36px 48px; overflow: hidden">
|
||||
<div style="display: flex; align-items: flex-end; gap: 16px; margin-bottom: 28px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Tools & MCP</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">External tools, model providers and fetch limits available to agents.</p>
|
||||
</div>
|
||||
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add MCP server</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px">
|
||||
|
||||
<section class="card" style="grid-column: span 2">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><rect x="3" y="4" width="18" height="6" rx="1"></rect><rect x="3" y="14" width="18" height="6" rx="1"></rect><path d="M7 7h.01M7 17h.01"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MCP servers</div><div class="hint">Model Context Protocol servers agents can call.</div></div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 20px; padding: 28px 20px">
|
||||
<div style="flex-grow: 1">
|
||||
<div style="font-size: 14px; color: #e8e6e1">No MCP servers yet</div>
|
||||
<div class="hint" style="margin-top: 4px">Add a stdio command or an HTTP endpoint. Agents see its tools on next restart.</div>
|
||||
</div>
|
||||
<button class="btn">stdio command</button>
|
||||
<button class="btn">HTTP / SSE endpoint</button>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center; font: 600 13px 'IBM Plex Mono', monospace; color: #a6a39b">Mx</div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MiniMax</div><div class="hint">Model provider</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span></label>
|
||||
</div>
|
||||
<div class="card-b">
|
||||
<div class="field">
|
||||
<span class="lbl">API key</span>
|
||||
<div style="display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws</span>
|
||||
<span style="color: #4a4c50">/</span>
|
||||
<span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="height: 28px; padding: 0 10px; font-size: 12px; background: transparent">Change</button>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: #86b5a0"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Web fetch</div><div class="hint">Let agents download pages and files</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span></label>
|
||||
</div>
|
||||
<div class="card-b">
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px">
|
||||
<div class="field"><label class="lbl" for="mb">Max download</label><div style="display: flex"><input id="mb" class="inp" value="2" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">MB</span></div></div>
|
||||
<div class="field"><label class="lbl" for="to">Timeout</label><div style="display: flex"><input id="to" class="inp" value="30" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">sec</span></div></div>
|
||||
</div>
|
||||
<label style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid #2a2c30; border-radius: 8px">
|
||||
<span class="sw" style="background: #2e3034; margin-top: 2px"><i style="left: 2px; background: #8f8c85"></i></span>
|
||||
<span><span class="lbl">Allow private networks</span><span class="hint" style="display: block">Off: requests to 10.x, 192.168.x and localhost are blocked.</span></span>
|
||||
</label>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card" style="grid-column: span 2">
|
||||
<div class="card-h">
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Tool output policy</div><div class="hint">Large tool results are truncated or spilled to disk.</div></div>
|
||||
</div>
|
||||
<div class="card-b" style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
|
||||
<div class="field"><label class="lbl" for="mrc">Max result length</label><div style="display: flex"><input id="mrc" class="inp" value="50,000" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85; white-space: nowrap">chars</span></div><span class="hint">About 12k tokens per tool call.</span></div>
|
||||
<div class="field"><label class="lbl" for="spill">Spill directory</label><input id="spill" class="inp" placeholder="Not set — results over the limit are truncated"><span class="hint">Full output is written here and the agent gets a path.</span></div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,124 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – review changes</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.acc{display:flex;align-items:center;gap:14px;padding:16px 20px;border:1px solid #2a2c30;border-radius:10px;background:#16171a}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.sum{font:12px 'IBM Plex Mono',monospace;color:#8f8c85}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.chev{color:#8f8c85}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
<main style="width: 880px; padding: 36px 0 0 64px; display: flex; flex-direction: column; gap: 12px">
|
||||
<h1 style="margin: 0 0 4px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
|
||||
<p style="margin: 0 0 16px; font-size: 14px; color: #a6a39b">Collapsed sections show their current values at a glance.</p>
|
||||
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Personas</span><span class="sum" style="flex-grow: 1">6 personas · default archie</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Schedules</span><span class="sum" style="flex-grow: 1">none</span></div>
|
||||
<div class="acc" style="border-color: #3a3f3c"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Scheduling policy</span><span class="sum" style="flex-grow: 1">trigger assignee · 3 retries · poll 30s</span><span style="font-size: 11px; color: #86b5a0">1 edited</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Tools & MCP</span><span class="sum" style="flex-grow: 1">0 MCP · MiniMax on · web fetch on</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Plugins</span><span class="sum" style="flex-grow: 1">all directories default</span></div>
|
||||
|
||||
<section style="border: 1px solid #3a3f3c; border-radius: 10px; background: #16171a">
|
||||
<div style="display: flex; align-items: center; gap: 14px; padding: 16px 20px; border-bottom: 1px solid #232529">
|
||||
<svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"></path></svg>
|
||||
<span class="lbl" style="flex-grow: 1">Container runtime</span>
|
||||
<span style="font-size: 11px; color: #86b5a0">2 edited</span>
|
||||
</div>
|
||||
<div style="padding: 20px; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px 24px">
|
||||
<div class="field" style="grid-column: span 2"><label class="lbl" for="img">Image</label><input id="img" class="inp" value="ghcr.io/samcharles93/archie-agent:latest"></div>
|
||||
<div class="field"><label class="lbl" for="mc">Max concurrency</label><input id="mc" class="inp" value="6" style="border-color: #86b5a0"></div>
|
||||
<div class="field"><label class="lbl" for="mu">Max uptime</label><input id="mu" class="inp" value="2h" style="border-color: #86b5a0"></div>
|
||||
<div class="field"><label class="lbl" for="net">Network</label><input id="net" class="inp" value="archie-core_default"></div>
|
||||
<div class="field"><label class="lbl" for="pp">Pull policy</label><select id="pp" class="inp" style="font-family: 'IBM Plex Sans', sans-serif"><option>If missing</option><option>Always</option><option>Never</option></select></div>
|
||||
<div class="field"><label class="lbl" for="vt">Volume TTL</label><input id="vt" class="inp" value="72h"></div>
|
||||
<div class="field"><label class="lbl" for="pr">Profiles</label><input id="pr" class="inp" placeholder="None"></div>
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
|
||||
<div style="position: absolute; left: 0; top: 56px; right: 0; bottom: 0; background: rgba(8,9,10,0.55)"></div>
|
||||
|
||||
<aside aria-label="Review changes" style="position: absolute; top: 56px; right: 0; bottom: 0; width: 480px; box-sizing: border-box; background: #17181a; border-left: 1px solid #2a2c30; display: flex; flex-direction: column; box-shadow: -24px 0 48px rgba(0,0,0,0.35)">
|
||||
<div style="display: flex; align-items: center; padding: 20px 24px; border-bottom: 1px solid #2a2c30">
|
||||
<div style="flex-grow: 1"><h2 style="margin: 0; font-size: 17px; font-weight: 600">Review 3 changes</h2><div class="hint" style="margin-top: 2px">Saved together as config version 2</div></div>
|
||||
<button aria-label="Close" style="width: 36px; height: 36px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
|
||||
</div>
|
||||
<div style="flex-grow: 1; padding: 20px 24px; display: flex; flex-direction: column; gap: 20px">
|
||||
<div style="display: flex; gap: 10px; padding: 12px 14px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25); color: #e3c08f; font-size: 13px; line-height: 1.5">
|
||||
<svg style="flex-shrink: 0; margin-top: 2px" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
|
||||
<span>All three need an archie-core restart. 2 agents are running; they'll finish before the restart.</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">Scheduling policy</div>
|
||||
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Poll interval</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
|
||||
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
|
||||
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 1m0s</div>
|
||||
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 30s</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">Container runtime</div>
|
||||
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Max concurrency</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
|
||||
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
|
||||
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 4</div>
|
||||
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 6</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">Max uptime</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
|
||||
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
|
||||
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− 1h0m0s</div>
|
||||
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ 2h0m0s</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30">
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard all</button>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn">Save only</button>
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
</div>
|
||||
</aside>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,155 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – channels</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:34px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.row{display:grid;grid-template-columns:260px minmax(0,1fr);gap:32px;padding:16px 20px;border-top:1px solid #232529}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.icon{width:32px;height:32px;border-radius:8px;background:#1e2023;display:flex;align-items:center;justify-content:center;flex-shrink:0}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 1300px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="#86b5a0" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#" class="on">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 248px; flex-shrink: 0; box-sizing: border-box; padding: 24px 14px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div class="eyebrow" style="padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas</a><a class="nav-item" href="#">Schedules</a><a class="nav-item" href="#">Scheduling policy</a>
|
||||
<div class="eyebrow" style="padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 #86b5a0">Channels<span class="dot" style="margin-left: auto; background: #86b5a0" title="1 running"></span></a>
|
||||
<a class="nav-item" href="#">Tools & MCP</a><a class="nav-item" href="#">Plugins</a>
|
||||
<div class="eyebrow" style="padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>History</a>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; padding: 36px 56px; display: flex; flex-direction: column; gap: 24px; min-width: 0">
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px; max-width: 980px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Channels</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Where you talk to Archie, and how chat sessions behave.</p>
|
||||
</div>
|
||||
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,.3); background: rgba(217,164,91,.08)">Applies after restart</span>
|
||||
</div>
|
||||
|
||||
<div style="max-width: 980px; display: flex; flex-direction: column; gap: 16px">
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="m22 3-9.5 18-2.5-8-8-2.5L22 3Z"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Telegram</div><div class="hint">Talk to Archie and approve its work from your phone.</div></div>
|
||||
<span class="pill" style="color: #86b5a0; border-color: #86b5a0"><span class="dot" style="background: #86b5a0"></span>Running</span>
|
||||
</div>
|
||||
<div class="row" style="border-top: 0">
|
||||
<div><div class="lbl">Bot token</div><div class="hint">Secret reference for the Telegram bot.</div></div>
|
||||
<div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; height: 38px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span class="mono" style="font-size: 12px; color: #8f8c85">env</span><span style="color: #4a4c50">/</span><span class="mono" style="font-size: 13px">HEYARCHIE_TELEGRAM_BOT_TOKEN</span>
|
||||
<div style="flex-grow: 1"></div><button class="btn btn-sm" style="height: 26px; background: transparent">Change</button>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: #86b5a0; margin-top: 6px"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Allowed users</div><div class="hint">Telegram user IDs that may talk to Archie. Everyone else is ignored.</div></div>
|
||||
<div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 6px; border: 1px solid #2e3034; border-radius: 6px; background: #121314; min-height: 38px; box-sizing: border-box">
|
||||
<span style="display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 6px 0 10px; border-radius: 4px; background: #1e2023; font: 12px 'IBM Plex Mono', monospace">1312197967<button aria-label="Remove 1312197967" style="width: 20px; height: 20px; border: 0; background: transparent; color: #8f8c85; cursor: pointer">×</button></span>
|
||||
<input aria-label="Add user ID" placeholder="Add user ID…" style="flex-grow: 1; min-width: 140px; background: transparent; border: 0; outline: none; color: #e8e6e1; font: 12px 'IBM Plex Mono', monospace">
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
|
||||
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
|
||||
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M3 6h18v12H3zM3 6l9 7 9-7"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Email</div><div class="hint">Listen for mail and relay replies.</div></div>
|
||||
<span class="pill">Not set up</span>
|
||||
<button class="btn btn-sm">Set up</button>
|
||||
</section>
|
||||
|
||||
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
|
||||
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Webhook</div><div class="hint">Deliver agent output to a URL, with a signing secret and template.</div></div>
|
||||
<span class="pill">Not set up</span>
|
||||
<button class="btn btn-sm">Set up</button>
|
||||
</section>
|
||||
|
||||
|
||||
<div class="eyebrow" style="margin-top: 16px">Chat session defaults · all channels</div>
|
||||
<section class="card">
|
||||
<div class="row" style="border-top: 0">
|
||||
<div><label class="lbl" for="ws">Workspace</label><div class="hint">Directory chat sessions start in.</div></div>
|
||||
<input id="ws" class="inp" value="/home/sam">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Filesystem access</div><div class="hint">Outside the workspace.</div></div>
|
||||
<div style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid rgba(217,119,107,.35); background: rgba(217,119,107,.06); border-radius: 8px">
|
||||
<span class="sw" style="background: #d9776b; margin-top: 2px"><i style="right: 2px; background: #121314"></i></span>
|
||||
<span><span class="lbl">Unrestricted filesystem</span><span class="hint" style="display: block; color: #e0a39a">On: agents can read and write anywhere this user can.</span></span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Show tool calls</div><div class="hint">Post each tool call into the chat.</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span>On</label>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="ms">Max steps</label><div class="hint">Per chat turn. 0 = no limit.</div></div>
|
||||
<input id="ms" class="inp" value="0" style="width: 120px">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Rate limit</div><div class="hint">Off while either value is 0.</div></div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><input aria-label="Max requests" class="inp" value="0" style="width: 90px"> requests per <input aria-label="Window" class="inp" value="0" style="width: 80px"><select aria-label="Window unit" class="inp" style="width: 110px; font-family: 'IBM Plex Sans', sans-serif"><option>minutes</option></select></div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="md">Models</label><div class="hint">Models chat sessions may use.</div></div>
|
||||
<input id="md" class="inp" placeholder="Default">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="op">Operator</label><div class="hint">Who Archie treats as its operator.</div></div>
|
||||
<input id="op" class="inp" placeholder="Not set">
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-size: 12px; color: #8f8c85">
|
||||
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>
|
||||
Version 1 · 11 fields set by <span class="mono">system:migration</span> 8 hrs ago · <a href="#" style="color: #a6a39b; text-decoration: underline">View in History</a>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,138 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Theme and components</title>
|
||||
<!-- Static snapshot of the design mockup (accent = sage #86b5a0). Generated from the matching file in source/. -->
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.h{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#8f8c85;margin:0 0 14px;font-weight:500}
|
||||
.panel{border:1px solid #2a2c30;border-radius:10px;background:#16171a;padding:24px}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid}
|
||||
.dot{width:7px;height:7px;border-radius:50%}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div style="--accent: #86b5a0; width: 1440px; height: 980px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 24px">
|
||||
<div>
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Graphite theme</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Warm neutral greys carry the page; one low-chroma accent marks the active item, focus and primary action.</p>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px">
|
||||
|
||||
<section class="panel">
|
||||
<h2 class="h">Palette</h2>
|
||||
<div style="display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px">
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #121314; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Ground</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#121314</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #16171a; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Surface</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#16171a</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #1e2023; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Raised</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#1e2023</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #2a2c30; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Border</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#2a2c30</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #e8e6e1; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Text</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#e8e6e1</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #8f8c85; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Muted</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#8f8c85</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #86b5a0; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Accent</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#86b5a0</span>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: #d9a45b; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">Warn</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">#d9a45b</span>
|
||||
</div>
|
||||
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Type</h2>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<span style="font-size: 24px; font-weight: 600">IBM Plex Sans 600 · 24</span>
|
||||
<span style="font-size: 14px; color: #a6a39b">IBM Plex Sans 400 · 14 body</span>
|
||||
<span style="font: 13px 'IBM Plex Mono', monospace">IBM Plex Mono · values, keys, durations</span>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="panel">
|
||||
<h2 class="h">Buttons</h2>
|
||||
<div style="display: flex; gap: 10px; flex-wrap: wrap">
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
<button class="btn">Secondary</button>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Status</h2>
|
||||
<div style="display: flex; gap: 8px; flex-wrap: wrap">
|
||||
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #86b5a0"></span>Connected</span>
|
||||
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #d9a45b"></span>Connecting…</span>
|
||||
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,0.3); background: rgba(217,164,91,0.08)">Applies after restart</span>
|
||||
<span class="pill" style="color: #86b5a0; border-color: #86b5a0">2 edited</span>
|
||||
<span class="pill" style="color: #e0a39a; border-color: rgba(217,119,107,0.35); background: rgba(217,119,107,0.08)">Invalid duration</span>
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Toggles & choice</h2>
|
||||
<div style="display: flex; align-items: center; gap: 20px">
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span class="sw" style="background: #86b5a0"><i style="right: 2px; background: #121314"></i></span>On</label>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #2e3034"><i style="left: 2px; background: #8f8c85"></i></span>Off</label>
|
||||
<div style="display: inline-flex; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
|
||||
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">Assignee</button>
|
||||
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Label</button>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="panel" style="display: flex; flex-direction: column; gap: 16px">
|
||||
<h2 class="h" style="margin: 0">Inputs</h2>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c1">Text</label><input id="c1" class="inp" value="archie-core_default"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c2">Focused</label><input id="c2" class="inp" value="ghcr.io/…/archie-agent:latest" style="border-color: #86b5a0; box-shadow: 0 0 0 3px rgba(134,181,160,0.15)"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c3">Duration with unit</label>
|
||||
<div style="display: flex"><input id="c3" class="inp" value="72" style="border-radius: 6px 0 0 6px"><select aria-label="Unit" class="inp" style="width: 110px; border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>hours</option></select></div></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c4">Error</label><input id="c4" class="inp" value="1hr" style="border-color: #d9776b"><span style="font-size: 12px; color: #e0a39a">Use a number and a unit, e.g. 1h or 90m</span></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Secret reference</span>
|
||||
<div style="display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px">
|
||||
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws /</span><span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
|
||||
<span style="margin-left: auto; font-size: 12px; color: #86b5a0">resolved</span>
|
||||
</div></div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,103 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Proposed navigation</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.node{display:flex;align-items:baseline;gap:10px;font-size:14px;font-weight:500}
|
||||
.sub{font-size:12px;color:#8f8c85;font-weight:400}
|
||||
.kid{margin:6px 0 0 18px;padding-left:14px;border-left:1px solid #2e3034;display:flex;flex-direction:column;gap:6px;font-size:13px;color:#a6a39b}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.tbl{width:100%;border-collapse:collapse;font-size:13px}
|
||||
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 14px;border-bottom:1px solid #2a2c30}
|
||||
.tbl td{padding:10px 14px;border-bottom:1px solid #202225;vertical-align:top;line-height:1.45}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1120px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 28px">
|
||||
<div>
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Navigation: today → proposed</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Five top-level places, each with one job. Anything you configure lives in Settings; anything you act on lives where the work is.</p>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 380px minmax(0, 1fr); gap: 24px">
|
||||
<section class="card" style="padding: 24px; display: flex; flex-direction: column; gap: 16px">
|
||||
<div class="eyebrow">Today</div>
|
||||
<div class="node" style="color: #a6a39b">Dashboard</div>
|
||||
<div><div class="node" style="color: #a6a39b">Work <span class="sub">dropdown</span></div>
|
||||
<div class="kid"><span>Tasks</span><span>Workflows <span class="sub">editor + start work + stats</span></span><span>Channels <span class="sub">settings + audit</span></span></div></div>
|
||||
<div><div class="node" style="color: #a6a39b">Events</div>
|
||||
<div class="kid"><span>Inspector · Bindings · Mappings</span></div></div>
|
||||
<div><div class="node" style="color: #a6a39b">System <span class="sub">dropdown</span></div>
|
||||
<div class="kid"><span>Advanced <span class="sub">6 cards, 6 save buttons</span></span></div></div>
|
||||
<p class="hint" style="margin: 8px 0 0">Dropdown contents are inferred from the screenshots; confirm against the router.</p>
|
||||
</section>
|
||||
|
||||
<section class="card" style="padding: 24px">
|
||||
<div class="eyebrow" style="margin-bottom: 16px; color: {{accent}}">Proposed</div>
|
||||
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px 32px">
|
||||
<div><div class="node">Dashboard <span class="sub">what needs me</span></div>
|
||||
<div class="kid"><span>Needs you queue</span><span>Live activity</span><span>Health: gates, tokens</span></div></div>
|
||||
<div><div class="node">Tasks <span class="sub">the work</span></div>
|
||||
<div class="kid"><span>Task list <span class="sub">filter by state</span></span><span>Task detail <span class="sub">log · files · config · debug</span></span><span>Attempts in a side rail</span></div></div>
|
||||
<div><div class="node">Workflows <span class="sub">how work runs</span></div>
|
||||
<div class="kid"><span>List with success + cost</span><span>Definition editor</span><span>Performance tab <span class="sub">stages, failures</span></span></div></div>
|
||||
<div><div class="node">Events <span class="sub">what comes in</span></div>
|
||||
<div class="kid"><span>Inspector</span><span>Bindings</span><span>Mappings</span></div></div>
|
||||
<div style="grid-column: span 2"><div class="node">Settings <span class="sub">everything you configure, one save flow</span></div>
|
||||
<div class="kid" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 6px 24px">
|
||||
<span><span style="color: #e8e6e1">Agents</span><br>Personas · Schedules · Scheduling policy</span>
|
||||
<span><span style="color: #e8e6e1">Integrations</span><br>Channels · Tools & MCP · Plugins</span>
|
||||
<span><span style="color: #e8e6e1">Runtime</span><br>Container runtime · History</span>
|
||||
</div></div>
|
||||
</div>
|
||||
<div style="margin-top: 24px; padding-top: 16px; border-top: 1px solid #232529; display: flex; gap: 24px; font-size: 13px; color: #a6a39b">
|
||||
<span><span style="color: #e8e6e1; font-weight: 500">Always in the top bar:</span> New task · ⌘K Jump to · connection status</span>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<section class="card" style="overflow: hidden">
|
||||
<table class="tbl">
|
||||
<thead><tr><th style="width: 290px">What</th><th style="width: 280px">Moves to</th><th>Why</th></tr></thead>
|
||||
<tbody>
|
||||
<sc-for list="{{moves}}" as="m" hint-placeholder-count="9">
|
||||
<tr><td style="color: #e8e6e1">{{m.what}}</td><td><span style="color: {{accent}}">→</span> {{m.to}}</td><td style="color: #a6a39b">{{m.why}}</td></tr>
|
||||
</sc-for>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1120}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return {
|
||||
accent: this.props.accent ?? '#86b5a0',
|
||||
moves: [
|
||||
{ what: 'Start work card (Workflows)', to: 'New task dialog, from the top bar', why: 'Starting work is not editing a workflow. One entry point from any page, and from ⌘K.' },
|
||||
{ what: 'Channels (Work menu)', to: 'Settings › Integrations › Channels', why: 'It is configuration. It gets the same setting rows, secret fields and save flow as the rest.' },
|
||||
{ what: 'Audit table (Channels page)', to: 'Settings › History', why: 'One change log for every setting, filterable by section. Replaces six History links.' },
|
||||
{ what: 'Per workflow table', to: 'Workflows list columns', why: 'Runs, success and cost sit next to the workflow you are about to open.' },
|
||||
{ what: 'Slowest stages · Most failures', to: 'Workflow › Performance tab', why: 'Scoped to the selected workflow instead of mixing every workflow in one table.' },
|
||||
{ what: 'Connecting · Version pills on every card', to: 'One status in the top bar', why: 'Connection is global. Version shows once per page, in History.' },
|
||||
{ what: 'Settings "Managed elsewhere" row', to: 'Events tabs', why: 'Captured events, mappings and bindings already live there.' },
|
||||
{ what: 'Task "Attempt 2 is not recorded" column', to: 'Attempts list in the task side rail', why: 'Shows every attempt with its outcome; the empty column goes away.' },
|
||||
{ what: 'Dashboard stat cards and health', to: 'Stat strip + right rail', why: '"Needs you" becomes the first thing on the page, with actions inline.' }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,172 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Dashboard</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:15px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tbl{width:100%;border-collapse:collapse;font-size:13px}
|
||||
.tbl th{text-align:left;font-weight:500;font-size:11px;letter-spacing:.06em;text-transform:uppercase;color:#8f8c85;padding:10px 20px;border-bottom:1px solid #2a2c30}
|
||||
.tbl td{padding:10px 20px;border-bottom:1px solid #202225;vertical-align:middle}
|
||||
.chip{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:1px 6px;margin-left:6px}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#" class="on">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
|
||||
<div style="display: flex; align-items: flex-end; gap: 16px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Good morning</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Nothing is running. <span style="color: #d9a45b">3 tasks need you.</span></p>
|
||||
</div>
|
||||
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 6h16M4 12h10M4 18h13"></path></svg>Logs</button>
|
||||
</div>
|
||||
|
||||
<section class="card" style="flex-direction: row">
|
||||
<sc-for list="{{stats}}" as="s" hint-placeholder-count="4">
|
||||
<div style="flex: 1 1 0; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<div class="hint">{{s.label}}</div>
|
||||
<div style="font-size: 30px; font-weight: 600; margin-top: 6px; color: {{s.color}}">{{s.value}}</div>
|
||||
<div class="hint" style="margin-top: 2px">{{s.sub}}</div>
|
||||
</div>
|
||||
</sc-for>
|
||||
</section>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 380px; gap: 24px; min-height: 0; flex-grow: 1">
|
||||
<div style="display: flex; flex-direction: column; gap: 24px; min-width: 0">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Needs you</span><span class="pill warn">3</span><div style="flex-grow: 1"></div><a href="#" class="hint" style="text-decoration: underline">All tasks</a></div>
|
||||
<sc-for list="{{needs}}" as="n" hint-placeholder-count="3">
|
||||
<div style="display: grid; grid-template-columns: 120px minmax(0, 1fr) auto; gap: 16px; align-items: center; padding: 14px 20px; border-bottom: 1px solid #202225">
|
||||
<span class="pill warn" style="justify-self: start">{{n.state}}</span>
|
||||
<div style="min-width: 0">
|
||||
<a href="#" style="font-size: 14px; font-weight: 500">{{n.title}}</a>
|
||||
<div class="mono" style="font-size: 12px; color: #8f8c85; margin-top: 3px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{n.meta}}</div>
|
||||
</div>
|
||||
<div style="display: flex; gap: 8px"><button class="btn btn-sm btn-ghost">Open</button><button class="btn btn-sm">{{n.action}}</button></div>
|
||||
</div>
|
||||
</sc-for>
|
||||
</section>
|
||||
|
||||
<section class="card" style="flex-grow: 1; overflow: hidden">
|
||||
<div class="card-h"><span class="card-t">Live activity</span><span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>live</span><div style="flex-grow: 1"></div>
|
||||
<div role="radiogroup" aria-label="Filter activity" style="display: inline-flex; padding: 2px; border: 1px solid #2e3034; border-radius: 7px"><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">All</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Tasks</button><button style="height: 26px; padding: 0 10px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">System</button></div>
|
||||
</div>
|
||||
<table class="tbl">
|
||||
<thead><tr><th>Event</th><th style="width: 70px">Task</th><th>Detail</th><th style="width: 110px">When</th></tr></thead>
|
||||
<tbody>
|
||||
<sc-for list="{{activity}}" as="a" hint-placeholder-count="8">
|
||||
<tr><td class="mono" style="font-size: 12px"><span style="display: inline-block; width: 7px; height: 7px; border-radius: 2px; margin-right: 8px; background: {{a.color}}"></span>{{a.event}}<sc-if value="{{a.count}}" hint-placeholder-val="{{false}}"><span class="chip">×{{a.count}}</span></sc-if></td><td class="mono" style="font-size: 12px; color: #a6a39b">{{a.task}}</td><td style="color: #a6a39b; max-width: 0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{a.detail}}</td><td class="hint">{{a.when}}</td></tr>
|
||||
</sc-for>
|
||||
</tbody>
|
||||
</table>
|
||||
</section>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-direction: column; gap: 24px">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Quality gates</span><div style="flex-grow: 1"></div><span class="hint">last 4 runs</span></div>
|
||||
<div style="padding: 20px; display: flex; flex-direction: column; gap: 16px">
|
||||
<div style="display: flex; align-items: baseline; gap: 10px"><span style="font-size: 30px; font-weight: 600">25%</span><span class="hint">pass rate</span></div>
|
||||
<sc-for list="{{gates}}" as="g" hint-placeholder-count="2">
|
||||
<div>
|
||||
<div style="display: flex; font-size: 13px; margin-bottom: 6px"><span class="mono">{{g.name}}</span><span style="margin-left: auto; color: #a6a39b" class="mono">{{g.score}}</span></div>
|
||||
<div style="height: 6px; border-radius: 3px; background: #26282c"><div style="height: 6px; border-radius: 3px; width: {{g.pct}}; background: {{g.color}}"></div></div>
|
||||
</div>
|
||||
</sc-for>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Token outlook</span></div>
|
||||
<div style="padding: 20px; display: flex; flex-direction: column; gap: 14px">
|
||||
<div style="display: flex; gap: 24px">
|
||||
<div><div class="hint">Today</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">14.5M</div></div>
|
||||
<div><div class="hint">Next 30 days at this rate</div><div style="font-size: 22px; font-weight: 600; margin-top: 2px">≈ 434M</div></div>
|
||||
</div>
|
||||
<div aria-label="Tokens per day, last 7 days" style="display: flex; align-items: flex-end; gap: 6px; height: 64px">
|
||||
<sc-for list="{{days}}" as="d" hint-placeholder-count="7"><div style="flex: 1 1 0; display: flex; flex-direction: column; align-items: center; gap: 4px"><div style="width: 100%; height: {{d.h}}; border-radius: 3px; background: {{d.color}}"></div><span class="mono" style="font-size: 10px; color: #8f8c85">{{d.label}}</span></div></sc-for>
|
||||
</div>
|
||||
<div class="hint">Only 1 day of history. The projection steadies after a week of runs.</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
|
||||
<button aria-label="Chat with Archie" style="position: absolute; right: 24px; bottom: 24px; width: 48px; height: 48px; border-radius: 50%; border: 1px solid #34373c; background: #1e2023; color: {{accent}}; display: flex; align-items: center; justify-content: center; box-shadow: 0 8px 24px rgba(0,0,0,.4); cursor: pointer"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a8 8 0 0 1-11.6 7.1L4 20l1-4.6A8 8 0 1 1 21 12Z"></path></svg></button>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
const accent = this.props.accent ?? '#86b5a0';
|
||||
const sys = '#6f6c66', task = '#8aa4c2', bad = '#d9776b', ok = accent;
|
||||
return {
|
||||
accent,
|
||||
stats: [
|
||||
{ label: 'Working now', value: '0', sub: '0 waiting to start', color: '#e8e6e1' },
|
||||
{ label: 'Needs you', value: '3', sub: 'Parked or awaiting a reply', color: '#d9a45b' },
|
||||
{ label: 'Delivered', value: '1', sub: '25% of all tasks', color: '#e8e6e1' },
|
||||
{ label: 'Tokens used', value: '14.5M', sub: 'Across 1 day', color: '#e8e6e1' }
|
||||
],
|
||||
needs: [
|
||||
{ state: 'Parked', title: 'changes_captured key-set validation is top-level only', meta: 'archie-core #868 · tdd · worktree prepare failed: fetch origin: http transport…', action: 'Start new run' },
|
||||
{ state: 'Awaiting reply', title: '[Task title]', meta: '[repo #issue] · [workflow] · [last agent message]', action: 'Reply' },
|
||||
{ state: 'Awaiting reply', title: '[Task title]', meta: '[repo #issue] · [workflow] · [last agent message]', action: 'Reply' }
|
||||
],
|
||||
activity: [
|
||||
{ event: 'curator_run', task: '—', detail: 'session-memory', when: '19 mins ago', color: sys, count: 0 },
|
||||
{ event: 'task_archive_requested', task: '#5', detail: 'archive requested with no recorded actor', when: '1 hr ago', color: task, count: 0 },
|
||||
{ event: 'task_abandoned', task: '#5', detail: 'abandoned with no recorded actor', when: '1 hr ago', color: bad, count: 0 },
|
||||
{ event: 'curator_run', task: '—', detail: 'session-memory', when: '1 hr ago', color: sys, count: 6 },
|
||||
{ event: 'stage_start', task: '#5', detail: '', when: '1 hr ago', color: task, count: 4 },
|
||||
{ event: 'stage_start', task: '#4', detail: '', when: '7 hrs ago', color: task, count: 5 },
|
||||
{ event: 'agent_finish', task: '#4', detail: 'Problem surface for samcharles93/archie-core issue 836 ("Updater cannot detect o…', when: '7 hrs ago', color: ok, count: 0 },
|
||||
{ event: 'agent_finish', task: '#4', detail: 'Root cause', when: '7 hrs ago', color: ok, count: 0 },
|
||||
{ event: 'stage_start', task: '#4', detail: '', when: '8 hrs ago', color: task, count: 6 }
|
||||
],
|
||||
gates: [
|
||||
{ name: 'tdd', score: '0 / 3', pct: '2%', color: '#d9776b' },
|
||||
{ name: 'triage', score: '1 / 1', pct: '100%', color: accent }
|
||||
],
|
||||
days: ['M','T','W','T','F','S','S'].map((l, i) => ({ label: l, h: i === 4 ? '48px' : '3px', color: i === 4 ? accent : '#26282c' }))
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,138 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Task detail</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:14px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:14px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.warn{color:#d9a45b;border-color:rgba(217,164,91,.3);background:rgba(217,164,91,.08)}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.sel{height:32px;box-sizing:border-box;padding:0 10px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:13px 'IBM Plex Sans',sans-serif}
|
||||
.kv{display:grid;grid-template-columns:96px minmax(0,1fr);gap:10px;font-size:13px;padding:8px 0;border-bottom:1px solid #202225}
|
||||
.kv dt{color:#8f8c85}.kv dd{margin:0}
|
||||
.tag{font:11px 'IBM Plex Mono',monospace;color:#a6a39b;background:#1e2023;border-radius:4px;padding:1px 6px}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1000px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#" class="on">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 24px 48px 32px; display: flex; flex-direction: column; gap: 20px; min-height: 0">
|
||||
<div>
|
||||
<div class="hint"><a href="#" style="color: #a6a39b">Tasks</a> / <span class="mono">#1</span></div>
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px; margin-top: 8px">
|
||||
<div style="flex-grow: 1; min-width: 0">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">changes_captured key-set validation is top-level only</h1>
|
||||
<div style="display: flex; align-items: center; gap: 12px; margin-top: 8px; font-size: 13px; color: #a6a39b">
|
||||
<span class="pill warn"><span class="dot" style="background: #d9a45b"></span>Parked</span>
|
||||
<span class="mono">tdd</span><span style="color: #4a4c50">·</span>
|
||||
<a href="#" class="mono" style="color: #a6a39b; text-decoration: underline">samcharles93/archie-core #868</a>
|
||||
</div>
|
||||
</div>
|
||||
<button class="btn btn-ghost">Archive</button>
|
||||
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>Start a new run</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div role="alert" style="display: flex; gap: 12px; padding: 14px 16px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25)">
|
||||
<svg style="flex-shrink: 0; margin-top: 2px" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#d9a45b" stroke-width="2"><path d="M12 3 2 20h20L12 3Z"></path><path d="M12 10v4M12 17h.01"></path></svg>
|
||||
<div style="min-width: 0; flex-grow: 1">
|
||||
<div style="font-size: 14px; font-weight: 500; color: #e3c08f">Parked: couldn’t prepare the worktree</div>
|
||||
<div class="mono" style="font-size: 12px; color: #a6a39b; margin-top: 4px; line-height: 1.6; word-break: break-all">fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
|
||||
</div>
|
||||
<button class="btn btn-sm" style="align-self: flex-start">Jump to log line</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 320px; gap: 24px; flex-grow: 1; min-height: 0">
|
||||
<section class="card" style="overflow: hidden">
|
||||
<nav style="display: flex; gap: 28px; padding: 0 20px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Log</a>
|
||||
<a class="tab" href="#">Changed files <span class="hint" style="margin-left: 6px">0</span></a>
|
||||
<a class="tab" href="#">Configuration</a>
|
||||
<a class="tab" href="#">Debug</a>
|
||||
</nav>
|
||||
<div style="display: flex; align-items: center; gap: 8px; padding: 12px 20px; border-bottom: 1px solid #232529">
|
||||
<select aria-label="Level" class="sel"><option>All levels</option></select>
|
||||
<select aria-label="Stage" class="sel"><option>All stages</option></select>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 32px; width: 260px; padding: 0 10px; box-sizing: border-box; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Search log" placeholder="Search log" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%"></label>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-sm btn-ghost"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 4v11M7 10l5 5 5-5M5 20h14"></path></svg>Download</button>
|
||||
</div>
|
||||
<div class="mono" style="font-size: 12px; line-height: 1.7; flex-grow: 1; background: #121314">
|
||||
<div style="display: grid; grid-template-columns: 72px 56px minmax(0, 1fr); gap: 12px; padding: 10px 20px; background: rgba(217,119,107,0.06); border-left: 2px solid #d9776b">
|
||||
<span style="color: #8f8c85">08:38:49</span>
|
||||
<span style="color: #e0a39a">ERROR</span>
|
||||
<div style="min-width: 0">
|
||||
<div style="word-break: break-all">task parked: worktree prepare failed: fetch origin: http transport: Get "https://github.com/samcharles93/archie-core.git/info/refs?service=git-upload-pack": terminated signal received</div>
|
||||
<div style="display: flex; gap: 6px; margin-top: 6px"><span class="tag">component=daemon</span><span class="tag">task=1</span></div>
|
||||
</div>
|
||||
</div>
|
||||
<div style="padding: 16px 20px; color: #8f8c85; font-family: 'IBM Plex Sans', sans-serif; font-size: 12px">End of attempt 1 · 1 line</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<aside style="display: flex; flex-direction: column; gap: 20px">
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Attempts</span></div>
|
||||
<div style="padding: 8px 12px">
|
||||
<a href="#" style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; border-radius: 6px; background: #1e2023; box-shadow: inset 2px 0 0 {{accent}}">
|
||||
<span class="dot" style="background: #d9a45b"></span><span style="font-size: 13px; flex-grow: 1">Attempt 1</span><span class="hint">parked · 08:38</span></a>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 10px 8px; color: #8f8c85">
|
||||
<span class="dot" style="background: transparent; border: 1px dashed #4a4c50; box-sizing: border-box"></span><span style="font-size: 13px; flex-grow: 1">Attempt 2</span><span class="hint">not recorded</span></div>
|
||||
</div>
|
||||
</section>
|
||||
<section class="card">
|
||||
<div class="card-h"><span class="card-t">Details</span></div>
|
||||
<dl style="margin: 0; padding: 4px 20px 12px">
|
||||
<div class="kv"><dt>Status</dt><dd style="color: #d9a45b">Parked</dd></div>
|
||||
<div class="kv"><dt>Workflow</dt><dd><a href="#" class="mono" style="text-decoration: underline">tdd</a></dd></div>
|
||||
<div class="kv"><dt>Repository</dt><dd class="mono" style="font-size: 12px">samcharles93/archie-core</dd></div>
|
||||
<div class="kv"><dt>Issue</dt><dd><a href="#" style="text-decoration: underline">#868</a> ↗</dd></div>
|
||||
<div class="kv"><dt>Persona</dt><dd class="mono" style="font-size: 12px">[persona]</dd></div>
|
||||
<div class="kv"><dt>Tokens</dt><dd class="mono" style="font-size: 12px">[tokens]</dd></div>
|
||||
<div class="kv" style="border: 0"><dt>Started</dt><dd>[date · time]</dd></div>
|
||||
</dl>
|
||||
</section>
|
||||
</aside>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1000}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return { accent: this.props.accent ?? '#86b5a0' };
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,142 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Workflows</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.step{font:12px 'IBM Plex Mono',monospace;padding:6px 10px;border:1px solid #2e3034;border-radius:6px;background:#121314;white-space:nowrap}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#" class="on">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px; min-height: 0">
|
||||
<div style="display: flex; align-items: flex-end; gap: 12px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Workflows</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">The step sequences agents follow. Success rate is merged tasks over all runs.</p>
|
||||
</div>
|
||||
<button class="btn btn-ghost"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 12a9 9 0 1 0 3-6.7L3 8"></path><path d="M3 3v5h5"></path></svg>Restore shipped</button>
|
||||
<button class="btn"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New workflow</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: 420px minmax(0, 1fr); gap: 24px; flex-grow: 1; min-height: 0">
|
||||
<section class="card" style="overflow: hidden">
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; padding: 10px 16px; font-size: 11px; letter-spacing: .06em; text-transform: uppercase; color: #8f8c85; border-bottom: 1px solid #2a2c30"><span>Workflow</span><span>Runs</span><span>Success</span><span style="text-align: right">Avg tok</span></div>
|
||||
<sc-for list="{{flows}}" as="f" hint-placeholder-count="6">
|
||||
<a href="#" style="display: grid; grid-template-columns: minmax(0, 1fr) 56px 110px 72px; gap: 12px; align-items: center; padding: 14px 16px; border-bottom: 1px solid #202225; background: {{f.bg}}; box-shadow: {{f.shadow}}">
|
||||
<span><span style="font-size: 14px; font-weight: 500; display: block">{{f.name}}</span><span class="mono" style="font-size: 11px; color: #8f8c85">{{f.id}}</span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b">{{f.runs}}</span>
|
||||
<span style="display: flex; flex-direction: column; gap: 4px"><span class="mono" style="font-size: 12px">{{f.rate}}</span><span style="height: 4px; border-radius: 2px; background: #26282c; width: 100%"><span style="display: block; height: 4px; border-radius: 2px; width: {{f.pct}}; background: {{f.barColor}}"></span></span></span>
|
||||
<span class="mono" style="font-size: 12px; color: #a6a39b; text-align: right">{{f.tokens}}</span>
|
||||
</a>
|
||||
</sc-for>
|
||||
</section>
|
||||
|
||||
<section class="card" style="overflow: hidden">
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px 0">
|
||||
<h2 style="margin: 0; font-size: 18px; font-weight: 600">Bootstrap</h2>
|
||||
<span class="pill">shipped · edited</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<span class="hint">0 runs yet</span>
|
||||
</div>
|
||||
<nav style="display: flex; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Definition</a>
|
||||
<a class="tab" href="#">Performance</a>
|
||||
<a class="tab" href="#">Runs</a>
|
||||
</nav>
|
||||
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px; flex-grow: 1; min-height: 0">
|
||||
<div style="display: grid; grid-template-columns: 280px minmax(0, 1fr); gap: 24px">
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="wid">ID</label><input id="wid" class="inp" value="bootstrap"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Steps</span>
|
||||
<div style="display: flex; align-items: center; gap: 6px; height: 36px; flex-wrap: nowrap; overflow: hidden">
|
||||
<sc-for list="{{steps}}" as="s" hint-placeholder-count="5"><span class="step">{{s.name}}</span><sc-if value="{{s.more}}" hint-placeholder-val="{{true}}"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#4a4c50" stroke-width="2"><path d="M5 12h14M13 6l6 6-6 6"></path></svg></sc-if></sc-for>
|
||||
</div></div>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px; flex-grow: 1; min-height: 0">
|
||||
<div style="display: flex; align-items: baseline"><span class="lbl">YAML</span><span class="hint" style="margin-left: auto; color: {{accent}}">✓ Valid</span></div>
|
||||
<div class="mono" style="flex-grow: 1; display: grid; grid-template-columns: 44px minmax(0, 1fr); border: 1px solid #2e3034; border-radius: 8px; background: #121314; font-size: 13px; line-height: 1.75; overflow: hidden">
|
||||
<div style="padding: 14px 0; text-align: right; padding-right: 12px; color: #4f5156; border-right: 1px solid #232529; background: #141517; white-space: pre-line">{{lineNos}}</div>
|
||||
<div style="padding: 14px 16px; white-space: pre"><span style="color: #a6a39b">id:</span> bootstrap
|
||||
<span style="color: #a6a39b">steps:</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.prepare</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.apply</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.commit-push</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.diff-cap</span>
|
||||
- <span style="color: #a6a39b">type:</span> <span style="color: {{accent}}">bootstrap.open-pr</span></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #2a2c30; background: #17181a">
|
||||
<span class="hint">Version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-ghost" style="color: #d9776b">Remove</button>
|
||||
<button class="btn">Restore this workflow</button>
|
||||
<button class="btn btn-primary">Validate & save</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
const accent = this.props.accent ?? '#86b5a0';
|
||||
const rows = [
|
||||
['Bootstrap', 'bootstrap', '0', '—', '0%', '—'],
|
||||
['Feasibility check', 'feasibility', '0', '—', '0%', '—'],
|
||||
['Implement', 'implement', '0', '—', '0%', '—'],
|
||||
['Remediate', 'remediate', '0', '—', '0%', '—'],
|
||||
['TDD', 'tdd', '3', '0 of 3', '2%', '4.7M'],
|
||||
['Triage', 'triage', '1', '1 of 1', '100%', '282k']
|
||||
];
|
||||
const steps = ['prepare', 'apply', 'commit-push', 'diff-cap', 'open-pr'];
|
||||
return {
|
||||
accent,
|
||||
flows: rows.map(([name, id, runs, rate, pct, tokens], i) => ({
|
||||
name, id, runs, rate, pct, tokens,
|
||||
barColor: rate === '0 of 3' ? '#d9776b' : accent,
|
||||
bg: i === 0 ? '#1e2023' : 'transparent',
|
||||
shadow: i === 0 ? 'inset 2px 0 0 ' + accent : 'none'
|
||||
})),
|
||||
steps: steps.map((name, i) => ({ name, more: i < steps.length - 1 })),
|
||||
lineNos: '1\n2\n3\n4\n5\n6\n7'
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,83 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>New task dialog</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.inp{box-sizing:border-box;height:38px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.opt{display:flex;flex-direction:column;gap:2px;padding:10px 12px;border:1px solid #2e3034;border-radius:8px;cursor:pointer}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 900px; box-sizing: border-box; position: relative; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-sm" style="border-color: {{accent}}"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
</header>
|
||||
<div style="padding: 32px 48px"><div style="font-size: 28px; font-weight: 600; color: #3a3c40">Good morning</div></div>
|
||||
|
||||
<div style="position: absolute; inset: 0; background: rgba(8,9,10,0.6)"></div>
|
||||
|
||||
<section role="dialog" aria-modal="true" aria-labelledby="nt-title" style="position: absolute; left: 50%; top: 88px; transform: translateX(-50%); width: 640px; box-sizing: border-box; background: #17181a; border: 1px solid #2a2c30; border-radius: 12px; box-shadow: 0 24px 64px rgba(0,0,0,0.5); display: flex; flex-direction: column">
|
||||
<div style="display: flex; align-items: flex-start; padding: 22px 24px 18px; border-bottom: 1px solid #232529">
|
||||
<div style="flex-grow: 1"><h2 id="nt-title" style="margin: 0; font-size: 18px; font-weight: 600">New task</h2><div class="hint" style="margin-top: 2px">Goes into Archie’s normal task queue.</div></div>
|
||||
<button aria-label="Close" style="width: 32px; height: 32px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
|
||||
</div>
|
||||
<div style="padding: 20px 24px; display: flex; flex-direction: column; gap: 18px">
|
||||
<div class="field"><label class="lbl" for="repo">Repository</label><input id="repo" class="inp" value="samcharles93/archie-core"><span class="hint">owner/repository · recent: archie-core</span></div>
|
||||
<div class="field"><span class="lbl">Workflow</span>
|
||||
<div role="radiogroup" aria-label="Workflow" style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 8px">
|
||||
<sc-for list="{{flows}}" as="f" hint-placeholder-count="6">
|
||||
<label class="opt" style="border-color: {{f.border}}; background: {{f.bg}}"><span style="font-size: 13px; font-weight: 500">{{f.name}}</span><span class="hint">{{f.sub}}</span></label>
|
||||
</sc-for>
|
||||
</div></div>
|
||||
<div class="field"><label class="lbl" for="ttl">Title</label><input id="ttl" class="inp" placeholder="What should Archie do?" style="font-family: 'IBM Plex Sans', sans-serif"></div>
|
||||
<div class="field"><label class="lbl" for="ins">Instructions</label><textarea id="ins" placeholder="Context, acceptance criteria, files to look at…" style="min-height: 120px; box-sizing: border-box; padding: 12px; background: #121314; border: 1px solid #2e3034; border-radius: 6px; color: #e8e6e1; font: 13px/1.6 'IBM Plex Sans', sans-serif; resize: vertical; outline: none"></textarea></div>
|
||||
<details style="font-size: 13px; color: #a6a39b"><summary style="cursor: pointer">Advanced · run as identity</summary></details>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; padding: 14px 24px; border-top: 1px solid #232529">
|
||||
<span class="hint"><span class="mono" style="padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘↵</span> to start</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn btn-ghost">Cancel</button>
|
||||
<button class="btn btn-primary">Start task</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":900}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
const accent = this.props.accent ?? '#86b5a0';
|
||||
const list = [['TDD', '3 runs · 0% merged'], ['Triage', '1 run · 100% merged'], ['Implement', 'no runs yet'], ['Remediate', 'no runs yet'], ['Feasibility check', 'no runs yet'], ['Bootstrap', 'no runs yet']];
|
||||
return {
|
||||
accent,
|
||||
flows: list.map(([name, sub], i) => ({ name, sub, border: i === 0 ? accent : '#2e3034', bg: i === 0 ? '#1e2023' : 'transparent' }))
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,108 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Events</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.card-t{font-size:15px;font-weight:500}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.tab{height:44px;display:flex;align-items:center;gap:8px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.count{font:11px 'IBM Plex Mono',monospace;color:#8f8c85;background:#1e2023;border-radius:4px;padding:0 6px}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 900px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#" class="on">Events</a><a href="#">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<main style="flex-grow: 1; padding: 32px 48px; display: flex; flex-direction: column; gap: 24px">
|
||||
<div>
|
||||
<div style="display: flex; align-items: flex-end; gap: 12px">
|
||||
<div style="flex-grow: 1"><h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Events</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Webhooks come in, get mapped to event types, and bindings turn them into work.</p></div>
|
||||
<span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>Listening</span>
|
||||
</div>
|
||||
<nav style="display: flex; gap: 28px; margin-top: 16px; border-bottom: 1px solid #232529">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Inspector</a>
|
||||
<a class="tab" href="#">Mappings <span class="count">0</span></a>
|
||||
<a class="tab" href="#">Bindings <span class="count">0</span></a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<section class="card" style="flex-direction: row">
|
||||
<sc-for list="{{flow}}" as="f" hint-placeholder-count="3">
|
||||
<div style="flex: 1 1 0; display: flex; align-items: center; gap: 14px; padding: 18px 22px; border-right: 1px solid #232529">
|
||||
<span class="mono" style="width: 28px; height: 28px; border-radius: 50%; border: 1px solid #34373c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b; flex-shrink: 0">{{f.n}}</span>
|
||||
<div style="flex-grow: 1"><div style="font-size: 14px; font-weight: 500">{{f.title}}</div><div class="hint">{{f.sub}}</div></div>
|
||||
<span class="mono" style="font-size: 20px; color: #8f8c85">{{f.count}}</span>
|
||||
</div>
|
||||
</sc-for>
|
||||
</section>
|
||||
|
||||
<div style="display: grid; grid-template-columns: minmax(0, 3fr) minmax(0, 2fr); gap: 24px">
|
||||
<section class="card">
|
||||
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Recent captures</div><div class="hint">Headers and payloads are redacted before they’re stored.</div></div></div>
|
||||
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 12px; text-align: center">
|
||||
<div style="width: 40px; height: 40px; border-radius: 10px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="M22 12h-6l-2 3h-4l-2-3H2"></path><path d="M5.5 5h13L22 12v6a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2v-6Z"></path></svg></div>
|
||||
<div style="font-size: 14px; font-weight: 500">No captures yet</div>
|
||||
<div class="hint">Point a webhook at this endpoint and it shows up here live.</div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; margin-top: 6px; padding: 4px 4px 4px 14px; border: 1px solid #2e3034; border-radius: 8px; background: #121314">
|
||||
<span class="mono" style="font-size: 13px">/webhooks/capture/<span style="color: {{accent}}"><source></span></span>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="8" y="8" width="12" height="12" rx="2"></rect><path d="M16 8V5a1 1 0 0 0-1-1H5a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h3"></path></svg>Copy</button>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h"><div style="flex-grow: 1"><div class="card-t">Event types</div><div class="hint">Named shapes that mappings produce.</div></div>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M14 3H6a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9l-6-6Z"></path><path d="M12 12v6M9 15h6"></path></svg>From payload</button></div>
|
||||
<div style="padding: 40px 32px; display: flex; flex-direction: column; align-items: center; gap: 8px; text-align: center">
|
||||
<div style="font-size: 14px; font-weight: 500">No event types or proposals</div>
|
||||
<div class="hint">Paste a sample payload and Archie proposes a type for it. Proposals from real captures appear here too.</div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":900}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return {
|
||||
accent: this.props.accent ?? '#86b5a0',
|
||||
flow: [
|
||||
{ n: '1', title: 'Capture', sub: 'Webhooks received', count: '0' },
|
||||
{ n: '2', title: 'Map', sub: 'Payloads → event types', count: '0' },
|
||||
{ n: '3', title: 'Bind', sub: 'Event types → work', count: '0' }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,167 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – sidebar layout</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
|
||||
.inp:focus{border-color:var(--accent)}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.icon-btn{width:36px;height:36px;display:flex;align-items:center;justify-content:center;border-radius:6px;border:1px solid transparent;background:transparent;color:#8f8c85;cursor:pointer}
|
||||
.icon-btn:hover{background:#1e2023;color:#e8e6e1}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
.row{display:grid;grid-template-columns:280px minmax(0,1fr);gap:32px;padding:20px 0;border-top:1px solid #232529}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;margin-top:4px;line-height:1.5}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; position: relative; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: #d9a45b"></span>
|
||||
Connecting to archie-core…
|
||||
</div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 240px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
|
||||
<input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%">
|
||||
<span style="font-family: 'IBM Plex Mono', monospace; font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span>
|
||||
</label>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 264px; flex-shrink: 0; box-sizing: border-box; padding: 24px 16px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">6</span></a>
|
||||
<a class="nav-item" href="#">Schedules<span style="margin-left: auto; font-family: 'IBM Plex Mono', monospace; font-size: 11px; color: #8f8c85">0</span></a>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Scheduling policy<span style="margin-left: auto; width: 6px; height: 6px; border-radius: 50%; background: {{accent}}" title="Unsaved changes"></span></a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#">Channels</a>
|
||||
<a class="nav-item" href="#">Tools & MCP</a>
|
||||
<a class="nav-item" href="#">Plugins</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#">History</a>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="font-size: 12px; color: #8f8c85; padding: 12px; line-height: 1.5; border: 1px solid #232529; border-radius: 8px">Config version 1 · last saved by <span style="color: #a6a39b">admin</span><br><a href="#" style="color: {{accent}}">View history</a></div>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; overflow: hidden; padding: 40px 56px 120px">
|
||||
<div style="max-width: 920px">
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Scheduling policy</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">How Archie picks up work items and labels them as they move through states.</p>
|
||||
</div>
|
||||
<span style="display: inline-flex; align-items: center; gap: 6px; font-size: 12px; color: #d9a45b; background: rgba(217,164,91,0.1); border: 1px solid rgba(217,164,91,0.25); padding: 4px 10px; border-radius: 999px">
|
||||
<svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
|
||||
Applies after restart</span>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Dispatch</h2>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Trigger</div><div class="hint">What causes a work item to be dispatched to an agent.</div></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 12px">
|
||||
<div role="radiogroup" aria-label="Trigger" style="display: inline-flex; align-self: flex-start; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
|
||||
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 13px 'IBM Plex Sans', sans-serif">Assignee</button>
|
||||
<button style="height: 30px; padding: 0 14px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 13px 'IBM Plex Sans', sans-serif">Label</button>
|
||||
</div>
|
||||
<div class="hint" style="margin: 0">Dispatches when Archie is assigned. Choose <span style="color: #a6a39b">Label</span> to set a trigger label instead.</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="ack">Ack reaction</label><div class="hint">Reaction posted when a work item is picked up.</div></div>
|
||||
<div><input id="ack" class="inp" value="eyes" style="width: 220px"></div>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">State labels</h2>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Labels by state</div><div class="hint">Label applied to the ticket as the agent moves between states.</div></div>
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; padding: 8px 12px; font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85; background: #17181a; border-bottom: 1px solid #2a2c30"><span>State</span><span>Label</span><span></span></div>
|
||||
<sc-for list="{{labels}}" as="l" hint-placeholder-count="6">
|
||||
<div style="display: grid; grid-template-columns: 140px minmax(0, 1fr) 44px; gap: 12px; align-items: center; padding: 6px 12px; border-bottom: 1px solid #202225">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span style="width: 8px; height: 8px; border-radius: 2px; background: {{l.color}}"></span>{{l.state}}</span>
|
||||
<input class="inp" aria-label="{{l.state}} label" value="{{l.label}}" style="width: 100%; height: 32px">
|
||||
<button class="icon-btn" aria-label="Remove {{l.state}}"><svg width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8"><path d="M4 7h16M10 11v6M14 11v6M6 7l1 13h10l1-13M9 7V4h6v3"></path></svg></button>
|
||||
</div>
|
||||
</sc-for>
|
||||
<button style="display: flex; align-items: center; gap: 6px; width: 100%; height: 38px; padding: 0 12px; border: 0; background: transparent; color: #a6a39b; font: 500 13px 'IBM Plex Sans', sans-serif; cursor: pointer"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add state</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<h2 style="margin: 36px 0 4px; font-size: 13px; font-weight: 600; color: #a6a39b; text-transform: uppercase; letter-spacing: 0.06em">Retries & polling</h2>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="retries">Max retries</label><div class="hint">Attempts before an item is labelled dead.</div></div>
|
||||
<div style="display: inline-flex; align-self: flex-start; border: 1px solid #2e3034; border-radius: 6px; overflow: hidden; width: fit-content">
|
||||
<button class="icon-btn" aria-label="Decrease" style="border-radius: 0">−</button>
|
||||
<input id="retries" class="inp" value="3" style="width: 56px; border: 0; border-radius: 0; text-align: center; border-left: 1px solid #2e3034; border-right: 1px solid #2e3034">
|
||||
<button class="icon-btn" aria-label="Increase" style="border-radius: 0">+</button>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="poll">Poll interval</label><div class="hint">How often the tracker is checked for new work.</div></div>
|
||||
<div style="display: flex; align-items: center; gap: 10px">
|
||||
<div style="display: flex">
|
||||
<input id="poll" class="inp" value="30" style="width: 80px; border-radius: 6px 0 0 6px; border-color: {{accent}}">
|
||||
<select aria-label="Poll unit" class="inp" style="border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>seconds</option><option>minutes</option></select>
|
||||
</div>
|
||||
<span style="font-size: 12px; color: #8f8c85">was <span style="font-family: 'IBM Plex Mono', monospace; text-decoration: line-through">1m0s</span></span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
|
||||
<div style="position: absolute; left: 264px; right: 0; bottom: 0; height: 72px; box-sizing: border-box; padding: 0 56px; display: flex; align-items: center; gap: 12px; background: #17181a; border-top: 1px solid #2a2c30">
|
||||
<span style="width: 8px; height: 8px; border-radius: 50%; background: {{accent}}"></span>
|
||||
<span style="font-size: 13px">1 unsaved change</span>
|
||||
<span style="font-size: 13px; color: #8f8c85">· Poll interval</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
</div>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1040}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return {
|
||||
accent: this.props.accent ?? '#86b5a0',
|
||||
labels: [
|
||||
{ state: 'queued', label: 'agent:queued', color: '#8f8c85' },
|
||||
{ state: 'working', label: 'agent:working', color: '#8aa4c2' },
|
||||
{ state: 'waiting', label: 'agent:waiting', color: '#d9a45b' },
|
||||
{ state: 'pr', label: 'agent:pr', color: '#86b5a0' },
|
||||
{ state: 'parked', label: 'agent:parked', color: '#6f6c66' },
|
||||
{ state: 'dead', label: 'agent:dead', color: '#d9776b' }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,146 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – personas</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.tab{height:44px;display:flex;align-items:center;padding:0 2px;font-size:13px;color:#8f8c85;border-bottom:2px solid transparent}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1040px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: {{accent}}"></span>
|
||||
Connected · v1
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div style="padding: 32px 48px 0; border-bottom: 1px solid #232529; flex-shrink: 0">
|
||||
<div style="font-size: 12px; color: #8f8c85">System / Advanced</div>
|
||||
<h1 style="margin: 6px 0 20px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
|
||||
<nav style="display: flex; gap: 28px">
|
||||
<a class="tab" href="#" style="color: #e8e6e1; border-bottom-color: {{accent}}">Personas</a>
|
||||
<a class="tab" href="#">Schedules</a>
|
||||
<a class="tab" href="#">Scheduling policy</a>
|
||||
<a class="tab" href="#">Tools & MCP</a>
|
||||
<a class="tab" href="#">Plugins</a>
|
||||
<a class="tab" href="#">Container runtime</a>
|
||||
</nav>
|
||||
</div>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0; padding: 32px 48px 40px; gap: 32px">
|
||||
<section aria-label="Persona list" style="width: 340px; flex-shrink: 0; display: flex; flex-direction: column; gap: 12px">
|
||||
<div style="display: flex; align-items: center; gap: 8px">
|
||||
<label style="flex-grow: 1; display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; color: #8f8c85">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg>
|
||||
<input aria-label="Filter personas" placeholder="Filter personas" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: 13px 'IBM Plex Sans', sans-serif; width: 100%">
|
||||
</label>
|
||||
<button class="btn" aria-label="New persona" style="padding: 0 12px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New</button>
|
||||
</div>
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 10px; overflow: hidden; background: #16171a">
|
||||
<sc-for list="{{personas}}" as="p" hint-placeholder-count="6">
|
||||
<a href="#" style="display: flex; flex-direction: column; gap: 4px; padding: 14px 16px; border-bottom: 1px solid #222428; background: {{p.bg}}; box-shadow: {{p.shadow}}">
|
||||
<span style="display: flex; align-items: center; gap: 8px; font-size: 14px; font-weight: 500">{{p.name}}
|
||||
<sc-if value="{{p.isDefault}}" hint-placeholder-val="{{false}}"><span style="font-size: 11px; font-weight: 500; color: {{accent}}; border: 1px solid {{accent}}; border-radius: 999px; padding: 1px 8px">default</span></sc-if>
|
||||
</span>
|
||||
<span style="font-size: 12px; color: #8f8c85; white-space: nowrap; overflow: hidden; text-overflow: ellipsis">{{p.prompt}}</span>
|
||||
</a>
|
||||
</sc-for>
|
||||
</div>
|
||||
<div class="hint">Personas are system prompts an agent can adopt. The default is used when a work item doesn't specify one.</div>
|
||||
</section>
|
||||
|
||||
<section aria-label="Edit persona" style="flex-grow: 1; display: flex; flex-direction: column; border: 1px solid #2a2c30; border-radius: 10px; background: #16171a; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 18px 24px; border-bottom: 1px solid #2a2c30">
|
||||
<h2 style="margin: 0; font-size: 18px; font-weight: 600">archie</h2>
|
||||
<span style="font-size: 11px; color: {{accent}}; border: 1px solid {{accent}}; border-radius: 999px; padding: 1px 8px">default</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent">Duplicate</button>
|
||||
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 24px; padding: 24px; flex-grow: 1">
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<label class="lbl" for="pname">Name</label>
|
||||
<input id="pname" class="inp" value="archie">
|
||||
<span class="hint">Lowercase, used as the persona key.</span>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<span class="lbl">Default persona</span>
|
||||
<label style="display: flex; align-items: center; gap: 10px; height: 36px; font-size: 13px; color: #a6a39b">
|
||||
<span style="width: 36px; height: 20px; border-radius: 999px; background: {{accent}}; position: relative; display: inline-block"><span style="position: absolute; right: 2px; top: 2px; width: 16px; height: 16px; border-radius: 50%; background: #121314"></span></span>
|
||||
Use when no persona is specified
|
||||
</label>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px; flex-grow: 1">
|
||||
<div style="display: flex; align-items: baseline"><label class="lbl" for="prompt">System prompt</label><span class="hint" style="margin-left: auto; font-family: 'IBM Plex Mono', monospace">312 chars · ~70 tokens</span></div>
|
||||
<textarea id="prompt" style="flex-grow: 1; min-height: 320px; box-sizing: border-box; padding: 16px; background: #121314; border: 1px solid #2e3034; border-radius: 8px; color: #e8e6e1; font: 400 13px/1.7 'IBM Plex Mono', monospace; resize: vertical; outline: none">You are Archie, a capable coding and project assistant. Be direct without being brusque, grounded in the actual workspace state, and use available tools when asked. Do not claim tools, files, memories, actions, or results you have not verified. Do not impersonate another assistant, provider, or vendor.</textarea>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 14px 16px; border: 1px dashed #2e3034; border-radius: 8px">
|
||||
<svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="M4 12h12M12 6l6 6-6 6"></path></svg>
|
||||
<span style="font-size: 13px; color: #a6a39b; flex-grow: 1">Try this persona against a sample message before saving</span>
|
||||
<button class="btn">Open preview</button>
|
||||
</div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30; background: #17181a">
|
||||
<span style="font-size: 12px; color: #8f8c85">Saved · version 1 · <a href="#" style="color: #a6a39b; text-decoration: underline">History</a></span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn btn-primary">Save persona</button>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1040}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
const accent = this.props.accent ?? '#86b5a0';
|
||||
const list = [
|
||||
['archie', 'You are Archie, a capable coding and project assistant. Be direct without being brusque…', true],
|
||||
['helpful', 'You are a helpful, friendly AI assistant.', false],
|
||||
['concise', 'You are a concise assistant. Keep responses brief and to the point.', false],
|
||||
['technical', 'You are a technical expert. Provide detailed, accurate technical information.', false],
|
||||
['creative', 'You are a creative assistant. Think outside the box and offer innovative solutions.', false],
|
||||
['teacher', 'You are a patient teacher. Explain concepts clearly with examples.', false]
|
||||
];
|
||||
return {
|
||||
accent,
|
||||
personas: list.map(([name, prompt, isDefault], i) => ({
|
||||
name, prompt, isDefault,
|
||||
bg: i === 0 ? '#1e2023' : 'transparent',
|
||||
shadow: i === 0 ? 'inset 2px 0 0 ' + accent : 'none'
|
||||
}))
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,155 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – tools and MCP</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:18px 20px;border-bottom:1px solid #232529}
|
||||
.card-b{padding:20px;display:flex;flex-direction:column;gap:18px}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:36px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Tasks</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Workflows</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">Settings</a>
|
||||
</nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<div style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b; padding: 6px 10px; border: 1px solid #2a2c30; border-radius: 999px">
|
||||
<span style="width: 7px; height: 7px; border-radius: 50%; background: {{accent}}"></span>
|
||||
Connected · v1
|
||||
</div>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 232px; flex-shrink: 0; box-sizing: border-box; padding: 24px 12px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas</a>
|
||||
<a class="nav-item" href="#">Schedules</a>
|
||||
<a class="nav-item" href="#">Scheduling policy</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#">Channels</a>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Tools & MCP</a>
|
||||
<a class="nav-item" href="#">Plugins</a>
|
||||
<div style="font-size: 11px; letter-spacing: 0.08em; text-transform: uppercase; color: #8f8c85; padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#">History</a>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; padding: 36px 48px; overflow: hidden">
|
||||
<div style="display: flex; align-items: flex-end; gap: 16px; margin-bottom: 28px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Tools & MCP</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">External tools, model providers and fetch limits available to agents.</p>
|
||||
</div>
|
||||
<button class="btn btn-primary"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>Add MCP server</button>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 20px">
|
||||
|
||||
<section class="card" style="grid-column: span 2">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><rect x="3" y="4" width="18" height="6" rx="1"></rect><rect x="3" y="14" width="18" height="6" rx="1"></rect><path d="M7 7h.01M7 17h.01"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MCP servers</div><div class="hint">Model Context Protocol servers agents can call.</div></div>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 20px; padding: 28px 20px">
|
||||
<div style="flex-grow: 1">
|
||||
<div style="font-size: 14px; color: #e8e6e1">No MCP servers yet</div>
|
||||
<div class="hint" style="margin-top: 4px">Add a stdio command or an HTTP endpoint. Agents see its tools on next restart.</div>
|
||||
</div>
|
||||
<button class="btn">stdio command</button>
|
||||
<button class="btn">HTTP / SSE endpoint</button>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center; font: 600 13px 'IBM Plex Mono', monospace; color: #a6a39b">Mx</div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">MiniMax</div><div class="hint">Model provider</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span></label>
|
||||
</div>
|
||||
<div class="card-b">
|
||||
<div class="field">
|
||||
<span class="lbl">API key</span>
|
||||
<div style="display: flex; align-items: center; gap: 10px; height: 40px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws</span>
|
||||
<span style="color: #4a4c50">/</span>
|
||||
<span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn" style="height: 28px; padding: 0 10px; font-size: 12px; background: transparent">Change</button>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: {{accent}}"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div style="width: 32px; height: 32px; border-radius: 8px; background: #1e2023; display: flex; align-items: center; justify-content: center"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M3 12h18M12 3c3 3 3 15 0 18M12 3c-3 3-3 15 0 18"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Web fetch</div><div class="hint">Let agents download pages and files</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 12px; color: #a6a39b">Enabled<span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span></label>
|
||||
</div>
|
||||
<div class="card-b">
|
||||
<div style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 16px">
|
||||
<div class="field"><label class="lbl" for="mb">Max download</label><div style="display: flex"><input id="mb" class="inp" value="2" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">MB</span></div></div>
|
||||
<div class="field"><label class="lbl" for="to">Timeout</label><div style="display: flex"><input id="to" class="inp" value="30" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85">sec</span></div></div>
|
||||
</div>
|
||||
<label style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid #2a2c30; border-radius: 8px">
|
||||
<span class="sw" style="background: #2e3034; margin-top: 2px"><i style="left: 2px; background: #8f8c85"></i></span>
|
||||
<span><span class="lbl">Allow private networks</span><span class="hint" style="display: block">Off: requests to 10.x, 192.168.x and localhost are blocked.</span></span>
|
||||
</label>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="card" style="grid-column: span 2">
|
||||
<div class="card-h">
|
||||
<div style="flex-grow: 1"><div class="lbl" style="font-size: 15px">Tool output policy</div><div class="hint">Large tool results are truncated or spilled to disk.</div></div>
|
||||
</div>
|
||||
<div class="card-b" style="display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 24px">
|
||||
<div class="field"><label class="lbl" for="mrc">Max result length</label><div style="display: flex"><input id="mrc" class="inp" value="50,000" style="border-radius: 6px 0 0 6px"><span style="display: flex; align-items: center; padding: 0 12px; border: 1px solid #2e3034; border-left: 0; border-radius: 0 6px 6px 0; font-size: 12px; color: #8f8c85; white-space: nowrap">chars</span></div><span class="hint">About 12k tokens per tool call.</span></div>
|
||||
<div class="field"><label class="lbl" for="spill">Spill directory</label><input id="spill" class="inp" placeholder="Not set — results over the limit are truncated"><span class="hint">Full output is written here and the agent gets a path.</span></div>
|
||||
</div>
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return { accent: this.props.accent ?? '#86b5a0' };
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,123 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – review changes</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.acc{display:flex;align-items:center;gap:14px;padding:16px 20px;border:1px solid #2a2c30;border-radius:10px;background:#16171a}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.sum{font:12px 'IBM Plex Mono',monospace;color:#8f8c85}
|
||||
.field{display:flex;flex-direction:column;gap:6px}
|
||||
.chev{color:#8f8c85}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1080px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden; position: relative">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 28px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px">
|
||||
<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>
|
||||
Archie
|
||||
</div>
|
||||
<nav style="display: flex; gap: 4px; font-size: 13px">
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Dashboard</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Work</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #a6a39b">Events</a>
|
||||
<a href="#" style="padding: 8px 12px; color: #e8e6e1; background: #1e2023; border-radius: 6px">System</a>
|
||||
</nav>
|
||||
</header>
|
||||
|
||||
<main style="width: 880px; padding: 36px 0 0 64px; display: flex; flex-direction: column; gap: 12px">
|
||||
<h1 style="margin: 0 0 4px; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Advanced settings</h1>
|
||||
<p style="margin: 0 0 16px; font-size: 14px; color: #a6a39b">Collapsed sections show their current values at a glance.</p>
|
||||
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Personas</span><span class="sum" style="flex-grow: 1">6 personas · default archie</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Schedules</span><span class="sum" style="flex-grow: 1">none</span></div>
|
||||
<div class="acc" style="border-color: #3a3f3c"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Scheduling policy</span><span class="sum" style="flex-grow: 1">trigger assignee · 3 retries · poll 30s</span><span style="font-size: 11px; color: {{accent}}">1 edited</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Tools & MCP</span><span class="sum" style="flex-grow: 1">0 MCP · MiniMax on · web fetch on</span></div>
|
||||
<div class="acc"><svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 6 6 6-6 6"></path></svg><span class="lbl" style="width: 180px">Plugins</span><span class="sum" style="flex-grow: 1">all directories default</span></div>
|
||||
|
||||
<section style="border: 1px solid #3a3f3c; border-radius: 10px; background: #16171a">
|
||||
<div style="display: flex; align-items: center; gap: 14px; padding: 16px 20px; border-bottom: 1px solid #232529">
|
||||
<svg class="chev" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m6 9 6 6 6-6"></path></svg>
|
||||
<span class="lbl" style="flex-grow: 1">Container runtime</span>
|
||||
<span style="font-size: 11px; color: {{accent}}">2 edited</span>
|
||||
</div>
|
||||
<div style="padding: 20px; display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 18px 24px">
|
||||
<div class="field" style="grid-column: span 2"><label class="lbl" for="img">Image</label><input id="img" class="inp" value="ghcr.io/samcharles93/archie-agent:latest"></div>
|
||||
<div class="field"><label class="lbl" for="mc">Max concurrency</label><input id="mc" class="inp" value="6" style="border-color: {{accent}}"></div>
|
||||
<div class="field"><label class="lbl" for="mu">Max uptime</label><input id="mu" class="inp" value="2h" style="border-color: {{accent}}"></div>
|
||||
<div class="field"><label class="lbl" for="net">Network</label><input id="net" class="inp" value="archie-core_default"></div>
|
||||
<div class="field"><label class="lbl" for="pp">Pull policy</label><select id="pp" class="inp" style="font-family: 'IBM Plex Sans', sans-serif"><option>If missing</option><option>Always</option><option>Never</option></select></div>
|
||||
<div class="field"><label class="lbl" for="vt">Volume TTL</label><input id="vt" class="inp" value="72h"></div>
|
||||
<div class="field"><label class="lbl" for="pr">Profiles</label><input id="pr" class="inp" placeholder="None"></div>
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
|
||||
<div style="position: absolute; left: 0; top: 56px; right: 0; bottom: 0; background: rgba(8,9,10,0.55)"></div>
|
||||
|
||||
<aside aria-label="Review changes" style="position: absolute; top: 56px; right: 0; bottom: 0; width: 480px; box-sizing: border-box; background: #17181a; border-left: 1px solid #2a2c30; display: flex; flex-direction: column; box-shadow: -24px 0 48px rgba(0,0,0,0.35)">
|
||||
<div style="display: flex; align-items: center; padding: 20px 24px; border-bottom: 1px solid #2a2c30">
|
||||
<div style="flex-grow: 1"><h2 style="margin: 0; font-size: 17px; font-weight: 600">Review 3 changes</h2><div class="hint" style="margin-top: 2px">Saved together as config version 2</div></div>
|
||||
<button aria-label="Close" style="width: 36px; height: 36px; border: 0; background: transparent; color: #8f8c85; cursor: pointer"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M6 6l12 12M18 6 6 18"></path></svg></button>
|
||||
</div>
|
||||
<div style="flex-grow: 1; padding: 20px 24px; display: flex; flex-direction: column; gap: 20px">
|
||||
<div style="display: flex; gap: 10px; padding: 12px 14px; border-radius: 8px; background: rgba(217,164,91,0.08); border: 1px solid rgba(217,164,91,0.25); color: #e3c08f; font-size: 13px; line-height: 1.5">
|
||||
<svg style="flex-shrink: 0; margin-top: 2px" width="15" height="15" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 12a9 9 0 1 1-3-6.7L21 8"></path><path d="M21 3v5h-5"></path></svg>
|
||||
<span>All three need an archie-core restart. 2 agents are running; they'll finish before the restart.</span>
|
||||
</div>
|
||||
<sc-for list="{{groups}}" as="g" hint-placeholder-count="2">
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<div style="font-size: 11px; text-transform: uppercase; letter-spacing: 0.06em; color: #8f8c85">{{g.section}}</div>
|
||||
<sc-for list="{{g.items}}" as="c" hint-placeholder-count="2">
|
||||
<div style="border: 1px solid #2a2c30; border-radius: 8px; overflow: hidden">
|
||||
<div style="display: flex; align-items: center; padding: 10px 14px; font-size: 13px; font-weight: 500"><span style="flex-grow: 1">{{c.field}}</span><a href="#" style="font-size: 12px; font-weight: 400; color: #8f8c85; text-decoration: underline">Revert</a></div>
|
||||
<div style="font: 12px/1.9 'IBM Plex Mono', monospace; border-top: 1px solid #232529">
|
||||
<div style="padding: 0 14px; background: rgba(217,119,107,0.08); color: #e0a39a">− {{c.from}}</div>
|
||||
<div style="padding: 0 14px; background: rgba(134,181,160,0.10); color: #a9d1bf">+ {{c.to}}</div>
|
||||
</div>
|
||||
</div>
|
||||
</sc-for>
|
||||
</div>
|
||||
</sc-for>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 12px; padding: 16px 24px; border-top: 1px solid #2a2c30">
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard all</button>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<button class="btn">Save only</button>
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
</div>
|
||||
</aside>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1080}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return {
|
||||
accent: this.props.accent ?? '#86b5a0',
|
||||
groups: [
|
||||
{ section: 'Scheduling policy', items: [{ field: 'Poll interval', from: '1m0s', to: '30s' }] },
|
||||
{ section: 'Container runtime', items: [
|
||||
{ field: 'Max concurrency', from: '4', to: '6' },
|
||||
{ field: 'Max uptime', from: '1h0m0s', to: '2h0m0s' }
|
||||
] }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,165 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Settings – channels</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
a{color:#e8e6e1;text-decoration:none}a:hover{color:#ffffff}
|
||||
.btn{height:36px;padding:0 14px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px;white-space:nowrap}
|
||||
.btn-sm{height:30px;padding:0 10px;font-size:12px}
|
||||
.btn-ghost{background:transparent;border-color:transparent;color:#a6a39b}
|
||||
.card{border:1px solid #2a2c30;border-radius:10px;background:#16171a;display:flex;flex-direction:column;min-width:0}
|
||||
.card-h{display:flex;align-items:center;gap:12px;padding:16px 20px;border-bottom:1px solid #232529}
|
||||
.hint{font-size:12px;color:#8f8c85;line-height:1.5}
|
||||
.lbl{font-size:13px;font-weight:500}
|
||||
.eyebrow{font-size:11px;letter-spacing:.08em;text-transform:uppercase;color:#8f8c85;font-weight:500}
|
||||
.mono{font-family:'IBM Plex Mono',monospace}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:2px 9px;border-radius:999px;border:1px solid #2e3034;color:#a6a39b;white-space:nowrap}
|
||||
.dot{width:7px;height:7px;border-radius:50%;display:inline-block;flex-shrink:0}
|
||||
.nav a{padding:8px 12px;color:#a6a39b;border-radius:6px}
|
||||
.nav a.on{color:#e8e6e1;background:#1e2023}
|
||||
.nav-item{display:flex;align-items:center;gap:10px;height:34px;padding:0 12px;border-radius:6px;color:#a6a39b;font-size:13px}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.row{display:grid;grid-template-columns:260px minmax(0,1fr);gap:32px;padding:16px 20px;border-top:1px solid #232529}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block;flex-shrink:0}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.icon{width:32px;height:32px;border-radius:8px;background:#1e2023;display:flex;align-items:center;justify-content:center;flex-shrink:0}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 1300px; box-sizing: border-box; display: flex; flex-direction: column; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; overflow: hidden">
|
||||
|
||||
<header style="height: 56px; flex-shrink: 0; display: flex; align-items: center; gap: 24px; padding: 0 24px; border-bottom: 1px solid #232529; background: #151618">
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-weight: 600; font-size: 15px"><svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="{{accent}}" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M4 20 12 4l8 16"></path><path d="M8 14h8"></path></svg>Archie</div>
|
||||
<nav class="nav" style="display: flex; gap: 2px; font-size: 13px"><a href="#">Dashboard</a><a href="#">Tasks</a><a href="#">Workflows</a><a href="#">Events</a><a href="#" class="on">Settings</a></nav>
|
||||
<div style="flex-grow: 1"></div>
|
||||
<label style="display: flex; align-items: center; gap: 8px; height: 34px; width: 220px; padding: 0 12px; box-sizing: border-box; border: 1px solid #2a2c30; border-radius: 6px; color: #8f8c85; font-size: 13px"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="11" cy="11" r="7"></circle><path d="m20 20-3.5-3.5"></path></svg><input aria-label="Jump to" placeholder="Jump to…" style="background: transparent; border: 0; outline: none; color: #e8e6e1; font: inherit; width: 100%"><span class="mono" style="font-size: 11px; padding: 1px 5px; border: 1px solid #2e3034; border-radius: 4px">⌘K</span></label>
|
||||
<button class="btn btn-sm"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 5v14M5 12h14"></path></svg>New task</button>
|
||||
<span class="pill"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span aria-label="Account" style="width: 28px; height: 28px; border-radius: 50%; background: #26282c; display: flex; align-items: center; justify-content: center; font-size: 12px; color: #a6a39b">A</span>
|
||||
</header>
|
||||
|
||||
<div style="display: flex; flex-grow: 1; min-height: 0">
|
||||
<aside style="width: 248px; flex-shrink: 0; box-sizing: border-box; padding: 24px 14px; border-right: 1px solid #232529; display: flex; flex-direction: column; gap: 2px">
|
||||
<div class="eyebrow" style="padding: 0 12px 8px">Agents</div>
|
||||
<a class="nav-item" href="#">Personas</a><a class="nav-item" href="#">Schedules</a><a class="nav-item" href="#">Scheduling policy</a>
|
||||
<div class="eyebrow" style="padding: 18px 12px 8px">Integrations</div>
|
||||
<a class="nav-item" href="#" style="background: #1e2023; color: #e8e6e1; box-shadow: inset 2px 0 0 {{accent}}">Channels<span class="dot" style="margin-left: auto; background: {{accent}}" title="1 running"></span></a>
|
||||
<a class="nav-item" href="#">Tools & MCP</a><a class="nav-item" href="#">Plugins</a>
|
||||
<div class="eyebrow" style="padding: 18px 12px 8px">Runtime</div>
|
||||
<a class="nav-item" href="#">Container runtime</a>
|
||||
<div style="height: 1px; background: #232529; margin: 16px 12px"></div>
|
||||
<a class="nav-item" href="#"><svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>History</a>
|
||||
</aside>
|
||||
|
||||
<main style="flex-grow: 1; padding: 36px 56px; display: flex; flex-direction: column; gap: 24px; min-width: 0">
|
||||
<div style="display: flex; align-items: flex-start; gap: 16px; max-width: 980px">
|
||||
<div style="flex-grow: 1">
|
||||
<h1 style="margin: 0; font-size: 24px; font-weight: 600; letter-spacing: -0.01em">Channels</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Where you talk to Archie, and how chat sessions behave.</p>
|
||||
</div>
|
||||
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,.3); background: rgba(217,164,91,.08)">Applies after restart</span>
|
||||
</div>
|
||||
|
||||
<div style="max-width: 980px; display: flex; flex-direction: column; gap: 16px">
|
||||
<section class="card">
|
||||
<div class="card-h">
|
||||
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#a6a39b" stroke-width="2"><path d="m22 3-9.5 18-2.5-8-8-2.5L22 3Z"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">Telegram</div><div class="hint">Talk to Archie and approve its work from your phone.</div></div>
|
||||
<span class="pill" style="color: {{accent}}; border-color: {{accent}}"><span class="dot" style="background: {{accent}}"></span>Running</span>
|
||||
</div>
|
||||
<div class="row" style="border-top: 0">
|
||||
<div><div class="lbl">Bot token</div><div class="hint">Secret reference for the Telegram bot.</div></div>
|
||||
<div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; height: 38px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px; background: #121314">
|
||||
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span class="mono" style="font-size: 12px; color: #8f8c85">env</span><span style="color: #4a4c50">/</span><span class="mono" style="font-size: 13px">HEYARCHIE_TELEGRAM_BOT_TOKEN</span>
|
||||
<div style="flex-grow: 1"></div><button class="btn btn-sm" style="height: 26px; background: transparent">Change</button>
|
||||
</div>
|
||||
<div style="display: flex; align-items: center; gap: 6px; font-size: 12px; color: {{accent}}; margin-top: 6px"><svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2"><path d="m5 12 5 5 9-10"></path></svg>Credential resolved by Archie</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Allowed users</div><div class="hint">Telegram user IDs that may talk to Archie. Everyone else is ignored.</div></div>
|
||||
<div style="display: flex; flex-wrap: wrap; align-items: center; gap: 8px; padding: 6px; border: 1px solid #2e3034; border-radius: 6px; background: #121314; min-height: 38px; box-sizing: border-box">
|
||||
<span style="display: inline-flex; align-items: center; gap: 6px; height: 26px; padding: 0 6px 0 10px; border-radius: 4px; background: #1e2023; font: 12px 'IBM Plex Mono', monospace">1312197967<button aria-label="Remove 1312197967" style="width: 20px; height: 20px; border: 0; background: transparent; color: #8f8c85; cursor: pointer">×</button></span>
|
||||
<input aria-label="Add user ID" placeholder="Add user ID…" style="flex-grow: 1; min-width: 140px; background: transparent; border: 0; outline: none; color: #e8e6e1; font: 12px 'IBM Plex Mono', monospace">
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<sc-for list="{{inactive}}" as="c" hint-placeholder-count="2">
|
||||
<section class="card" style="flex-direction: row; align-items: center; gap: 12px; padding: 16px 20px">
|
||||
<div class="icon"><svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><path d="{{c.icon}}"></path></svg></div>
|
||||
<div style="flex-grow: 1"><div style="font-size: 15px; font-weight: 500">{{c.name}}</div><div class="hint">{{c.sub}}</div></div>
|
||||
<span class="pill">Not set up</span>
|
||||
<button class="btn btn-sm">Set up</button>
|
||||
</section>
|
||||
</sc-for>
|
||||
|
||||
<div class="eyebrow" style="margin-top: 16px">Chat session defaults · all channels</div>
|
||||
<section class="card">
|
||||
<div class="row" style="border-top: 0">
|
||||
<div><label class="lbl" for="ws">Workspace</label><div class="hint">Directory chat sessions start in.</div></div>
|
||||
<input id="ws" class="inp" value="/home/sam">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Filesystem access</div><div class="hint">Outside the workspace.</div></div>
|
||||
<div style="display: flex; align-items: flex-start; gap: 12px; padding: 12px; border: 1px solid rgba(217,119,107,.35); background: rgba(217,119,107,.06); border-radius: 8px">
|
||||
<span class="sw" style="background: #d9776b; margin-top: 2px"><i style="right: 2px; background: #121314"></i></span>
|
||||
<span><span class="lbl">Unrestricted filesystem</span><span class="hint" style="display: block; color: #e0a39a">On: agents can read and write anywhere this user can.</span></span>
|
||||
</div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Show tool calls</div><div class="hint">Post each tool call into the chat.</div></div>
|
||||
<label style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span>On</label>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="ms">Max steps</label><div class="hint">Per chat turn. 0 = no limit.</div></div>
|
||||
<input id="ms" class="inp" value="0" style="width: 120px">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><div class="lbl">Rate limit</div><div class="hint">Off while either value is 0.</div></div>
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-size: 13px; color: #a6a39b"><input aria-label="Max requests" class="inp" value="0" style="width: 90px"> requests per <input aria-label="Window" class="inp" value="0" style="width: 80px"><select aria-label="Window unit" class="inp" style="width: 110px; font-family: 'IBM Plex Sans', sans-serif"><option>minutes</option></select></div>
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="md">Models</label><div class="hint">Models chat sessions may use.</div></div>
|
||||
<input id="md" class="inp" placeholder="Default">
|
||||
</div>
|
||||
<div class="row">
|
||||
<div><label class="lbl" for="op">Operator</label><div class="hint">Who Archie treats as its operator.</div></div>
|
||||
<input id="op" class="inp" placeholder="Not set">
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<div style="display: flex; align-items: center; gap: 10px; font-size: 12px; color: #8f8c85">
|
||||
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><circle cx="12" cy="12" r="9"></circle><path d="M12 7v5l3 2"></path></svg>
|
||||
Version 1 · 11 fields set by <span class="mono">system:migration</span> 8 hrs ago · <a href="#" style="color: #a6a39b; text-decoration: underline">View in History</a>
|
||||
</div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":1300}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
return {
|
||||
accent: this.props.accent ?? '#86b5a0',
|
||||
inactive: [
|
||||
{ name: 'Email', sub: 'Listen for mail and relay replies.', icon: 'M3 6h18v12H3zM3 6l9 7 9-7' },
|
||||
{ name: 'Webhook', sub: 'Deliver agent output to a URL, with a signing secret and template.', icon: 'M10 13a5 5 0 0 0 7 0l3-3a5 5 0 0 0-7-7l-1 1M14 11a5 5 0 0 0-7 0l-3 3a5 5 0 0 0 7 7l1-1' }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,120 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
<title>Theme and components</title>
|
||||
<script src="./support.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<x-dc>
|
||||
<helmet>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body{margin:0;background:#121314}
|
||||
.inp{box-sizing:border-box;height:36px;padding:0 12px;background:#121314;border:1px solid #2e3034;border-radius:6px;color:#e8e6e1;font:400 13px 'IBM Plex Mono',monospace;outline:none;width:100%}
|
||||
.btn{height:36px;padding:0 16px;border-radius:6px;font:500 13px 'IBM Plex Sans',sans-serif;cursor:pointer;border:1px solid #34373c;background:#1e2023;color:#e8e6e1;display:inline-flex;align-items:center;gap:8px}
|
||||
.btn-primary{background:var(--accent);border-color:var(--accent);color:#101412}
|
||||
.h{font-size:11px;text-transform:uppercase;letter-spacing:0.08em;color:#8f8c85;margin:0 0 14px;font-weight:500}
|
||||
.panel{border:1px solid #2a2c30;border-radius:10px;background:#16171a;padding:24px}
|
||||
.pill{display:inline-flex;align-items:center;gap:6px;font-size:12px;padding:4px 10px;border-radius:999px;border:1px solid}
|
||||
.dot{width:7px;height:7px;border-radius:50%}
|
||||
.sw{width:36px;height:20px;border-radius:999px;position:relative;display:inline-block}
|
||||
.sw i{position:absolute;top:2px;width:16px;height:16px;border-radius:50%}
|
||||
.lbl{font-size:13px;font-weight:500;color:#e8e6e1}
|
||||
.hint{font-size:12px;color:#8f8c85}
|
||||
</style>
|
||||
</helmet>
|
||||
<div style="--accent: {{accent}}; width: 1440px; height: 980px; box-sizing: border-box; padding: 48px 56px; background: #121314; color: #e8e6e1; font-family: 'IBM Plex Sans', sans-serif; display: flex; flex-direction: column; gap: 24px">
|
||||
<div>
|
||||
<h1 style="margin: 0; font-size: 28px; font-weight: 600; letter-spacing: -0.01em">Graphite theme</h1>
|
||||
<p style="margin: 6px 0 0; font-size: 14px; color: #a6a39b">Warm neutral greys carry the page; one low-chroma accent marks the active item, focus and primary action.</p>
|
||||
</div>
|
||||
|
||||
<div style="display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 24px">
|
||||
|
||||
<section class="panel">
|
||||
<h2 class="h">Palette</h2>
|
||||
<div style="display: grid; grid-template-columns: repeat(4, minmax(0, 1fr)); gap: 10px">
|
||||
<sc-for list="{{swatches}}" as="s" hint-placeholder-count="8">
|
||||
<div style="display: flex; flex-direction: column; gap: 6px">
|
||||
<div style="height: 44px; border-radius: 6px; background: {{s.hex}}; border: 1px solid #2e3034"></div>
|
||||
<span style="font-size: 12px">{{s.name}}</span>
|
||||
<span style="font: 11px 'IBM Plex Mono', monospace; color: #8f8c85">{{s.hex}}</span>
|
||||
</div>
|
||||
</sc-for>
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Type</h2>
|
||||
<div style="display: flex; flex-direction: column; gap: 8px">
|
||||
<span style="font-size: 24px; font-weight: 600">IBM Plex Sans 600 · 24</span>
|
||||
<span style="font-size: 14px; color: #a6a39b">IBM Plex Sans 400 · 14 body</span>
|
||||
<span style="font: 13px 'IBM Plex Mono', monospace">IBM Plex Mono · values, keys, durations</span>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="panel">
|
||||
<h2 class="h">Buttons</h2>
|
||||
<div style="display: flex; gap: 10px; flex-wrap: wrap">
|
||||
<button class="btn btn-primary">Save & restart</button>
|
||||
<button class="btn">Secondary</button>
|
||||
<button class="btn" style="background: transparent; border-color: transparent; color: #a6a39b">Discard</button>
|
||||
<button class="btn" style="background: transparent; color: #d9776b; border-color: #3a2a28">Delete</button>
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Status</h2>
|
||||
<div style="display: flex; gap: 8px; flex-wrap: wrap">
|
||||
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: {{accent}}"></span>Connected</span>
|
||||
<span class="pill" style="color: #a6a39b; border-color: #2e3034"><span class="dot" style="background: #d9a45b"></span>Connecting…</span>
|
||||
<span class="pill" style="color: #d9a45b; border-color: rgba(217,164,91,0.3); background: rgba(217,164,91,0.08)">Applies after restart</span>
|
||||
<span class="pill" style="color: {{accent}}; border-color: {{accent}}">2 edited</span>
|
||||
<span class="pill" style="color: #e0a39a; border-color: rgba(217,119,107,0.35); background: rgba(217,119,107,0.08)">Invalid duration</span>
|
||||
</div>
|
||||
<h2 class="h" style="margin-top: 24px">Toggles & choice</h2>
|
||||
<div style="display: flex; align-items: center; gap: 20px">
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px"><span class="sw" style="background: {{accent}}"><i style="right: 2px; background: #121314"></i></span>On</label>
|
||||
<label style="display: flex; align-items: center; gap: 8px; font-size: 13px; color: #a6a39b"><span class="sw" style="background: #2e3034"><i style="left: 2px; background: #8f8c85"></i></span>Off</label>
|
||||
<div style="display: inline-flex; padding: 3px; background: #121314; border: 1px solid #2e3034; border-radius: 8px">
|
||||
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: #26282c; color: #e8e6e1; font: 500 12px 'IBM Plex Sans', sans-serif">Assignee</button>
|
||||
<button style="height: 28px; padding: 0 12px; border: 0; border-radius: 5px; background: transparent; color: #8f8c85; font: 500 12px 'IBM Plex Sans', sans-serif">Label</button>
|
||||
</div>
|
||||
</div>
|
||||
</section>
|
||||
|
||||
<section class="panel" style="display: flex; flex-direction: column; gap: 16px">
|
||||
<h2 class="h" style="margin: 0">Inputs</h2>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c1">Text</label><input id="c1" class="inp" value="archie-core_default"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c2">Focused</label><input id="c2" class="inp" value="ghcr.io/…/archie-agent:latest" style="border-color: {{accent}}; box-shadow: 0 0 0 3px rgba(134,181,160,0.15)"></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c3">Duration with unit</label>
|
||||
<div style="display: flex"><input id="c3" class="inp" value="72" style="border-radius: 6px 0 0 6px"><select aria-label="Unit" class="inp" style="width: 110px; border-radius: 0 6px 6px 0; border-left: 0; font-family: 'IBM Plex Sans', sans-serif"><option>hours</option></select></div></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><label class="lbl" for="c4">Error</label><input id="c4" class="inp" value="1hr" style="border-color: #d9776b"><span style="font-size: 12px; color: #e0a39a">Use a number and a unit, e.g. 1h or 90m</span></div>
|
||||
<div style="display: flex; flex-direction: column; gap: 6px"><span class="lbl">Secret reference</span>
|
||||
<div style="display: flex; align-items: center; gap: 8px; height: 36px; padding: 0 12px; border: 1px solid #2e3034; border-radius: 6px">
|
||||
<svg width="13" height="13" viewBox="0 0 24 24" fill="none" stroke="#8f8c85" stroke-width="2"><rect x="4" y="10" width="16" height="10" rx="2"></rect><path d="M8 10V7a4 4 0 0 1 8 0v3"></path></svg>
|
||||
<span style="font: 12px 'IBM Plex Mono', monospace; color: #8f8c85">bws /</span><span style="font: 13px 'IBM Plex Mono', monospace">MINIMAX_API_KEY</span>
|
||||
<span style="margin-left: auto; font-size: 12px; color: {{accent}}">resolved</span>
|
||||
</div></div>
|
||||
</section>
|
||||
</div>
|
||||
</div>
|
||||
</x-dc>
|
||||
<script type="text/x-dc" data-dc-script data-props='{"accent":{"editor":"color","default":"#86b5a0","options":["#86b5a0","#8aa4c2","#d4a373","#a397c9"]},"$preview":{"width":1440,"height":980}}'>
|
||||
class Component extends DCLogic {
|
||||
renderVals() {
|
||||
const accent = this.props.accent ?? '#86b5a0';
|
||||
return {
|
||||
accent,
|
||||
swatches: [
|
||||
{ name: 'Ground', hex: '#121314' },
|
||||
{ name: 'Surface', hex: '#16171a' },
|
||||
{ name: 'Raised', hex: '#1e2023' },
|
||||
{ name: 'Border', hex: '#2a2c30' },
|
||||
{ name: 'Text', hex: '#e8e6e1' },
|
||||
{ name: 'Muted', hex: '#8f8c85' },
|
||||
{ name: 'Accent', hex: accent },
|
||||
{ name: 'Warn', hex: '#d9a45b' }
|
||||
]
|
||||
};
|
||||
}
|
||||
}
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,84 @@
|
||||
/*
|
||||
* Archie "Graphite" theme tokens.
|
||||
* Warm neutral greys carry the page; ONE low-chroma accent marks the active
|
||||
* nav item, focus rings, "edited" markers and the primary action. Nothing else
|
||||
* uses the accent. Map these onto whatever styling system the app already uses
|
||||
* (Tailwind theme, CSS modules, styled-components…) rather than adding a
|
||||
* parallel system.
|
||||
*/
|
||||
@import url("https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;500&family=IBM+Plex+Sans:wght@400;500;600&display=swap");
|
||||
|
||||
:root {
|
||||
/* Surfaces (darkest → lightest) */
|
||||
--bg: #121314; /* page ground, input fill */
|
||||
--bg-header: #151618; /* app top bar */
|
||||
--surface: #16171a; /* cards, panels, list containers */
|
||||
--surface-2: #17181a; /* sticky save bar, drawer, table header */
|
||||
--raised: #1e2023; /* active nav item, secondary button, hover */
|
||||
--raised-2: #26282c; /* selected segment in a segmented control */
|
||||
|
||||
/* Lines */
|
||||
--border-subtle: #202225; /* row dividers inside tables */
|
||||
--border: #232529; /* section dividers, header/sidebar edges */
|
||||
--border-card: #2a2c30; /* card and panel outlines */
|
||||
--border-input: #2e3034; /* inputs, toggles off-track */
|
||||
--border-button: #34373c; /* secondary button outline */
|
||||
--border-edited: #3a3f3c; /* outline of a section with unsaved edits */
|
||||
|
||||
/* Text */
|
||||
--text: #e8e6e1; /* primary */
|
||||
--text-2: #a6a39b; /* secondary, nav items, descriptions of sections */
|
||||
--text-3: #8f8c85; /* hints, captions, placeholders, table headers (≥4.5:1 on --surface) */
|
||||
--text-on-accent:#101412; /* text on accent-filled buttons */
|
||||
|
||||
/* Accent — one at a time. Default sage; alternatives kept for a theme picker. */
|
||||
--accent: #86b5a0; /* sage (default) */
|
||||
--accent-ring: rgba(134, 181, 160, 0.15); /* focus halo */
|
||||
/* --accent: #8aa4c2; steel */
|
||||
/* --accent: #d4a373; sand */
|
||||
/* --accent: #a397c9; muted violet (closest to the old purple) */
|
||||
|
||||
/* Status */
|
||||
--warn: #d9a45b; /* "applies after restart", "connecting" dot */
|
||||
--warn-text: #e3c08f;
|
||||
--warn-bg: rgba(217, 164, 91, 0.08);
|
||||
--warn-border: rgba(217, 164, 91, 0.25);
|
||||
--danger: #d9776b; /* delete, invalid input border, dead state */
|
||||
--danger-text: #e0a39a;
|
||||
--danger-bg: rgba(217, 119, 107, 0.08);
|
||||
--danger-border: #3a2a28;
|
||||
--diff-add-bg: rgba(134, 181, 160, 0.10);
|
||||
--diff-add-text: #a9d1bf;
|
||||
--diff-del-bg: rgba(217, 119, 107, 0.08);
|
||||
--diff-del-text: #e0a39a;
|
||||
|
||||
/* Agent state colours (label table swatches, and anywhere states are shown) */
|
||||
--state-queued: #8f8c85;
|
||||
--state-working: #8aa4c2;
|
||||
--state-waiting: #d9a45b;
|
||||
--state-pr: #86b5a0;
|
||||
--state-parked: #6f6c66;
|
||||
--state-dead: #d9776b;
|
||||
|
||||
/* Type */
|
||||
--font-sans: "IBM Plex Sans", system-ui, sans-serif;
|
||||
--font-mono: "IBM Plex Mono", ui-monospace, monospace; /* ALL config values, keys, durations, image refs */
|
||||
--fs-page-title: 24px; /* weight 600, letter-spacing -0.01em */
|
||||
--fs-card-title: 15px; /* weight 500 */
|
||||
--fs-body: 14px;
|
||||
--fs-control: 13px; /* inputs, buttons, nav, labels (label weight 500) */
|
||||
--fs-hint: 12px; /* line-height 1.5 */
|
||||
--fs-eyebrow: 11px; /* uppercase, letter-spacing 0.06–0.08em, --text-3 */
|
||||
|
||||
/* Shape & spacing */
|
||||
--radius-sm: 4px; /* kbd hints */
|
||||
--radius: 6px; /* inputs, buttons, nav items */
|
||||
--radius-md: 8px; /* segmented control, callouts, diff cards */
|
||||
--radius-lg: 10px; /* cards, panels */
|
||||
--radius-pill: 999px;
|
||||
--control-h: 36px; /* inputs, buttons, nav items */
|
||||
--header-h: 56px;
|
||||
--sidebar-w: 264px;
|
||||
--content-max: 920px;
|
||||
--row-label-w: 280px; /* left column of a setting row */
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
{
|
||||
"name": "Archie Graphite",
|
||||
"color": {
|
||||
"bg": "#121314",
|
||||
"bgHeader": "#151618",
|
||||
"surface": "#16171a",
|
||||
"surface2": "#17181a",
|
||||
"raised": "#1e2023",
|
||||
"raised2": "#26282c",
|
||||
"borderSubtle": "#202225",
|
||||
"border": "#232529",
|
||||
"borderCard": "#2a2c30",
|
||||
"borderInput": "#2e3034",
|
||||
"borderButton": "#34373c",
|
||||
"borderEdited": "#3a3f3c",
|
||||
"text": "#e8e6e1",
|
||||
"text2": "#a6a39b",
|
||||
"text3": "#8f8c85",
|
||||
"textOnAccent": "#101412",
|
||||
"accent": "#86b5a0",
|
||||
"accentRing": "rgba(134,181,160,0.15)",
|
||||
"accentAlternatives": { "sage": "#86b5a0", "steel": "#8aa4c2", "sand": "#d4a373", "mutedViolet": "#a397c9" },
|
||||
"warn": "#d9a45b",
|
||||
"warnText": "#e3c08f",
|
||||
"warnBg": "rgba(217,164,91,0.08)",
|
||||
"warnBorder": "rgba(217,164,91,0.25)",
|
||||
"danger": "#d9776b",
|
||||
"dangerText": "#e0a39a",
|
||||
"dangerBg": "rgba(217,119,107,0.08)",
|
||||
"dangerBorder": "#3a2a28",
|
||||
"diffAddBg": "rgba(134,181,160,0.10)",
|
||||
"diffAddText": "#a9d1bf",
|
||||
"diffDelBg": "rgba(217,119,107,0.08)",
|
||||
"diffDelText": "#e0a39a",
|
||||
"state": { "queued": "#8f8c85", "working": "#8aa4c2", "waiting": "#d9a45b", "pr": "#86b5a0", "parked": "#6f6c66", "dead": "#d9776b" }
|
||||
},
|
||||
"font": {
|
||||
"sans": "\"IBM Plex Sans\", system-ui, sans-serif",
|
||||
"mono": "\"IBM Plex Mono\", ui-monospace, monospace",
|
||||
"size": { "pageTitle": 24, "cardTitle": 15, "body": 14, "control": 13, "hint": 12, "eyebrow": 11 },
|
||||
"weight": { "regular": 400, "medium": 500, "semibold": 600 }
|
||||
},
|
||||
"radius": { "sm": 4, "base": 6, "md": 8, "lg": 10, "pill": 999 },
|
||||
"size": { "controlHeight": 36, "headerHeight": 56, "sidebarWidth": 264, "contentMax": 920, "rowLabelWidth": 280 }
|
||||
}
|
||||
@@ -17,7 +17,12 @@ that reads it and the path the value takes to get there.
|
||||
channels, containers). The file only seeds it. Once the State Store holds the
|
||||
control-plane resource, the stored document is layered over the file
|
||||
(`controlplane.Client.RuntimeConfig`) and the file key stops mattering. It is
|
||||
checked by `validateDatabaseOwned` and by the resource's validator.
|
||||
checked by `validateDatabaseOwned` and by the resource's validator. A stored
|
||||
value is refreshed from the file only when the store has no value for the kind
|
||||
at all; a kind that ships a document of its own (workflow definitions,
|
||||
personas) is refreshed whenever the seed itself wrote the stored copy, since
|
||||
that copy is a previous release's document rather than an operator's
|
||||
(`controlplane.Server.seedKind`).
|
||||
- **Worker-carried.** A value the agent container needs travels in
|
||||
`config.TaskConfig` (`Config.ForTask`) or on `taskrun.Request`. Never pass it
|
||||
as an environment variable the daemon did not already define, and never carry
|
||||
@@ -25,16 +30,27 @@ that reads it and the path the value takes to get there.
|
||||
|
||||
## Adding a database-owned field
|
||||
|
||||
1. Add it to the struct the resource's `Document` names in
|
||||
`internal/app/controlplane/operational_settings.go`. The resource's JSON
|
||||
schema and the dashboard's Advanced settings editor are generated from that
|
||||
type, so no UI work is needed for the editor itself.
|
||||
2. Stored documents use Go field names as keys (`Image`, `MaxConcurrency`).
|
||||
Give the field no `json` tag unless its neighbours have one.
|
||||
3. A map or a nested struct needs its layering checked. `json.Unmarshal`
|
||||
merges into an existing map, so a stored map would add to the file's rather
|
||||
than replace it. A field the stored document omits keeps the file's value
|
||||
(a document stored before the field existed). Add a case to
|
||||
1. Add it to the wire-shape type the resource's `Document` names — a dedicated
|
||||
struct in `internal/app/controlplane/` with explicit snake_case json tags
|
||||
(`channel_settings.go`, `tool_settings.go`, `container_settings.go` are the
|
||||
precedents), never the internal config struct itself. A struct fed straight
|
||||
into the document falls back to Go field names (`Window`, `MaxRequests`),
|
||||
and a bare `time.Duration` marshals as nanoseconds — both render unusable
|
||||
in the Web UI. The resource's JSON schema and the dashboard's Advanced
|
||||
settings editor are generated from that type, so no UI work is needed for
|
||||
the editor itself.
|
||||
2. Map to and from the internal config type at the resource boundary (`Seed`,
|
||||
the layering in `runtime_config.go`, and the validator all use the same
|
||||
mapping). Durations in the document are a string-marshalling type
|
||||
(`config.Duration` or a document-local one), never a bare `time.Duration`.
|
||||
3. A document stored before the shape existed carries Go-cased keys. Read them
|
||||
with `controlplanerpc.DecodeRenamingLegacyKeys` (an `UnmarshalJSON` on the
|
||||
wire type) while keeping `DisallowUnknownFields` — dropping unknown keys
|
||||
would decode a misspelling as "unset" — and register a `Normalize` on the
|
||||
`Definition` that re-encodes the document, so a legacy document converges
|
||||
the next time it is written. A map or a nested struct needs its layering
|
||||
checked: a stored map replaces the file's, not merges into it, and a field
|
||||
the stored document omits keeps the file's value. Add a case to
|
||||
`internal/app/controlplane/runtime_config_test.go` for both.
|
||||
4. Validate it in one function both sides call, and add a case to
|
||||
`TestResourceValidatorsRejectWhatEffectiveValidationRejects` in
|
||||
@@ -44,6 +60,15 @@ that reads it and the path the value takes to get there.
|
||||
not on it requires a restart.
|
||||
6. If the settings page shows it as a plain field, add it to
|
||||
`internal/webui/config_schema.go` and the view in `api_config.go`.
|
||||
7. A generic catalog resource (`replace` command, not domain-managed, no
|
||||
query service) is watched **once per archie-ui process** by `webui.RunLive`,
|
||||
then published to every browser through `/api/stream`. Do not add an
|
||||
EventSource per resource to a settings store or a gRPC Watch per HTTP client.
|
||||
The control-plane server polls `Resource` every 250ms per upstream Watch;
|
||||
verify watch count is independent of client count and that late clients get
|
||||
the hub's current value (`internal/webui/live_hub_test.go`, real server over
|
||||
bufconn). Reopens resume after the last delivered version and charge failed
|
||||
attempts; accepting a gRPC stream does not establish its health.
|
||||
|
||||
## Every new field
|
||||
|
||||
|
||||
@@ -28,8 +28,9 @@ Authority: `docs/architecture/agent-system.md`. The status vocabulary lives in
|
||||
|
||||
Follow [State Store](state-store.md) for the
|
||||
column and the wire. Then decide who writes it: `UpdateTask` writes a fixed
|
||||
column set, so a field set at enqueue needs its own statement (as
|
||||
`StampTaskBinding` does for binding provenance and inputs).
|
||||
column set, so a field set at enqueue belongs in the insert that creates the
|
||||
row (as `InsertChatTask` does for inputs), or in its own statement when only
|
||||
some producers set it (as `StampTaskBinding` does for binding provenance).
|
||||
|
||||
### Changing what the agent receives
|
||||
|
||||
|
||||
@@ -18,7 +18,71 @@ should look.
|
||||
comes from the server. Keep a local default only so the first render works,
|
||||
and keep it in step (`ui/src/lib/task-meta.ts`).
|
||||
5. Run `task ui`, `task test:ui` and `cd ui && npm run typecheck`. Commit the
|
||||
regenerated `ui/dist/`; the Go binaries embed it.
|
||||
regenerated `ui/dist/`; the Go binaries embed it. A fresh git worktree has
|
||||
no ignored `ui/node_modules`: run `cd ui && npm ci` before these commands.
|
||||
6. **One long-lived browser connection:** `ui/src/lib/api.ts` has the only
|
||||
`new EventSource`, owned by `stores/live-updates.ts`. Feature stores consume
|
||||
topics with `live.subscribe(topic, callback)`; do not open a page-owned SSE
|
||||
stream. Logs alone opt in while mounted, replacing that same EventSource
|
||||
with `?topics=logs&since=<last cursor>`; a browser's `Last-Event-ID` only
|
||||
survives its own automatic reconnect, not a newly constructed EventSource.
|
||||
Task and log topics resume by cursor; control-plane, identity and apply-status
|
||||
topics replay the latest snapshot. Test a fetch and same-origin navigation
|
||||
after visiting Settings and Logs: the UI process serves HTTP/1.1 and six
|
||||
persistent streams can starve every later browser request.
|
||||
|
||||
## Testing the dashboard
|
||||
|
||||
Authority: the runner itself is `ui/package.json`'s `test` script: `node --test
|
||||
--experimental-strip-types test/*.test.ts` over `ui/test/*.test.ts`. It runs
|
||||
pure TypeScript modules with `node`'s type stripping — no SFC loader, no DOM,
|
||||
no second dependency beyond what the app already carries. That is the standard,
|
||||
and a decision record for when it is deliberately not enough:
|
||||
|
||||
- **Test archie's logic in a module; leave SFC wiring alone.** Wire shapes,
|
||||
draft state, copy conditions, filters and payload building live in plain
|
||||
`.ts` files beside the components and are tested in `ui/test/`. Components
|
||||
stay thin, so there is normally nothing in an SFC that is archie logic.
|
||||
- **A dashboard rule that mirrors a server rule is pinned by a shared
|
||||
fixture, not two independent tests.** `ui/src/settings/validation.ts`
|
||||
hand-mirrors three control-plane validators, and the model-role rule had
|
||||
already drifted because nothing tied the two sides together. Each case now
|
||||
lives once in `internal/app/controlplane/testdata/dashboard-validators.json`:
|
||||
a Go test in that package runs the real server validators over it, and
|
||||
`ui/test/control-plane-validator-parity.test.ts` runs the real dashboard
|
||||
validators over the same cases. Changing one rule alone fails the other
|
||||
side's test. Add a case to the fixture, never to one side only.
|
||||
- **Installed primitives are upstream-tested, not re-tested here.**
|
||||
`reka-ui` (2.10.5 here) maintains colocated tests per component in its own
|
||||
repo (Vitest/jsdom + axe: Switch, TagsInput, NumberField, Select, the
|
||||
arrow-navigation composables). The npm package ships none of those files, so
|
||||
this coverage is inherited through the version bound, not the tarball —
|
||||
`grep -l test node_modules/reka-ui` finds nothing. Duplicating them as local
|
||||
mount tests would test a dependency.
|
||||
- **A `.vue` import cannot run under the module runner.** `node --test` fails
|
||||
such a module with `ERR_UNKNOWN_FILE_EXTENSION: .vue` and the runner has no
|
||||
built-in loader for SFCs. A file under `ui/test/` that imports a `.vue` is
|
||||
therefore a broken test, not a weak one.
|
||||
- **If a DOM mount harness is ever needed** (a page-level accessibility
|
||||
contract, cross-component interaction, focus behaviour): `happy-dom` +
|
||||
`@vue/test-utils` + `vitest` scoped to a separate DOM test glob, keeping the
|
||||
module runner for everything else. Measured on the ui tree (vitest 5.0.2,
|
||||
happy-dom 20.14.5, @vue/test-utils 2.5.1): they add 24 top-level
|
||||
`node_modules` entries and 27 MB on a 296 MB install, a working 2-test mount
|
||||
suite (role=radiogroup vs role=switch, aria-label, click activation against
|
||||
the real SFCs) runs in 1.2 s on top of the current 0.5 s module suite, and
|
||||
`vue-tsc` (7.4 s) dominates `task test:ui` either way. The single-runner
|
||||
alternative (absorbing the existing suite into vitest) was measured
|
||||
infeasible as-is: all 29 existing files import `node:test`, which vitest
|
||||
cannot collect ("No test suite found in file" for every one), so it would be
|
||||
a rewrite of the whole suite, and its runtime was not measured. Nothing in
|
||||
`ui/dist` or CI changes either way; happy-dom is pure JS, no browser binary.
|
||||
- **What the module standard does not verify:** whether a call site passes an
|
||||
`aria-label` or which `v-if` branch shows. Those live in SFC templates and
|
||||
are only visible with a mount. If a page's accessible-name wiring is the
|
||||
risk, say so in the page's task and reach for the harness decision above
|
||||
rather than quietly growing mount tests. Never suppress a lint rule or a
|
||||
test to keep SFC behaviour out of the gate.
|
||||
|
||||
## Adding an API route
|
||||
|
||||
@@ -35,3 +99,10 @@ should look.
|
||||
`internal/app/archieui/compose.go`.
|
||||
5. Settings that live in a control-plane resource need no new route: the
|
||||
Advanced settings page edits every resource from its generated schema.
|
||||
6. For a new live topic, add one process-wide producer to `internal/webui`'s
|
||||
`RunLive` and fan it through the `/api/stream` hub; `internal/app/archieui/run.go`
|
||||
starts the producers with the process context. Never create an upstream
|
||||
watch or poller in an HTTP handler. A slow client must reconnect for cursor
|
||||
and snapshot repair rather than silently lose an update. Prove the producer
|
||||
with several browser clients against the real peer, not just a scripted
|
||||
stream; `live_hub_test.go` is the example.
|
||||
@@ -34,9 +34,14 @@ restating them.
|
||||
index, so stage regenerated contracts before running it.
|
||||
- Stage by path, or read `git status` before `git add -A`. Tests that start
|
||||
embedded NATS or write logs must use `t.TempDir()`; anything they leave in the
|
||||
tree gets committed. `task check` also adds linter-tool lines to `go.sum`
|
||||
(bead 1e37); restore `go.sum` before committing unless you changed a
|
||||
dependency.
|
||||
- A change to `docs/prds/` or `docs/architecture/` carries the regenerated
|
||||
`docs/data/generated/dev-docs.json`, and PRD edits follow
|
||||
`docs/prds/RULES.md` and pass `task docs:prds`.
|
||||
tree gets committed. `task check` writes no module file on a consistent tree,
|
||||
root or `tools/` (verified at HEAD with `GOFLAGS` unset and with `-mod=mod`):
|
||||
a stale `go.mod` or `go.sum` fails it, with `missing go.sum entry` or
|
||||
`updates to go.mod needed`, rather than being repaired. Only a global
|
||||
`GOFLAGS=-mod=mod` in `go env` re-enables that repair, which is why the
|
||||
`go -C tools` steps pass `-mod=readonly`; if `go.sum` goes dirty, run
|
||||
`go mod tidy` and commit the result on its own.
|
||||
- A change to `docs/prds/`, `docs/architecture/` **or `docs/development/`**
|
||||
carries the regenerated `docs/data/generated/dev-docs.json`: run
|
||||
`task docs:artifact` (not `task docs:check`, which checks contracts only).
|
||||
PRD edits also follow `docs/prds/RULES.md` and pass `task docs:prds`.
|
||||
@@ -27,3 +27,20 @@ passes the same gate.
|
||||
rule; do not loosen the rule to the test.
|
||||
3. Run the full suite without `-short`, then `task check`, then commit. Check
|
||||
`git status` for files a test wrote into the tree before staging.
|
||||
4. **A merge can surface a bug neither lane's own tests exposed alone.** Two
|
||||
real cases from 2026-09-26: a test that dialled no NATS URL passed on a
|
||||
machine with an ambient dev server running and failed the moment it landed
|
||||
on a clean CI runner (start an ephemeral server per test, never rely on a
|
||||
default port resolving to something); and a cycle-detector that walked a
|
||||
Go map in range order reported the same cycle two different ways from run
|
||||
to run, invisible until enough fresh (uncached) runs hit the unlucky
|
||||
ordering. Both looked like "the merge broke a passing test" but were
|
||||
latent defects the merge only had the opportunity to expose. Fix the
|
||||
defect the failure is pointing at, not the assertion that caught it — see
|
||||
CLAUDE.md's test-quality bar before writing the replacement.
|
||||
5. `go test`'s cache reuses a package's last result when nothing in its
|
||||
dependency graph changed. A merge that touches one package can leave a
|
||||
sibling's flaky test silently cached "pass" locally while CI runs it
|
||||
fresh. `task check` passing on your machine is not proof a merge is
|
||||
clean — rerun anything nondeterminism-prone with `-count=1` before
|
||||
trusting it, and let CI's from-scratch run be the tiebreaker it is.
|
||||
@@ -52,3 +52,14 @@ process; nothing else opens the database.
|
||||
Add the sentinel to `storecontract`, a row to `wireErrors` in `values.go`, and
|
||||
a case to `error_test.go`. The canonical message is part of the wire contract:
|
||||
changing it breaks `errors.Is` on the client silently.
|
||||
|
||||
## Harness OAuth secrets
|
||||
|
||||
`HarnessSecretStore` stores token sets by org and credential service through
|
||||
admin-only State Store RPCs. The EDA store seals them with the binding cipher's
|
||||
keyring and a separate `HarnessSecretDomain`. OAuth writes require a configured
|
||||
binding encryption key; the legacy binding plaintext fallback does not apply.
|
||||
The daemon's egress proxy (`internal/infrastructure/egress/oauth.go`) is the
|
||||
only daemon consumer: for a run granted the service it swaps sentinels for the
|
||||
stored tokens and writes every refresh back. The setup terminal is a separate
|
||||
harness slice.
|
||||
@@ -28,6 +28,19 @@ vocabulary it registers, so both must see the same step types.
|
||||
6. Add a parse test (settings accepted and refused) and a run test with fake
|
||||
`Trees` and agent runner.
|
||||
|
||||
## Retiring a step type
|
||||
|
||||
A step word cannot simply be deleted. A stored or pinned definition is
|
||||
validated as a whole collection, so one unknown word fails EVERY workflow's
|
||||
definition to decode and the workflow-definitions resource becomes unreadable.
|
||||
Retire a stage by removing it from its workflow's `Stages` and adding it to
|
||||
`retiredSteps` in `definition.go`, which keeps the word resolving as an inert
|
||||
stage. The retired stage must do nothing: the behaviour it used to perform now
|
||||
belongs to whatever layer took it over (the remediate workflow's in-container
|
||||
resume moved to daemon worktree preparation, `archie-core-866m`; the workflow
|
||||
still binds the daemon-prepared directory and the PR branch in a `prepare`
|
||||
stage before any agent work).
|
||||
|
||||
## Changing the definition format
|
||||
|
||||
- The fields a caller needs without the engine (inputs, repository, profile)
|
||||
@@ -37,5 +50,27 @@ vocabulary it registers, so both must see the same step types.
|
||||
- The YAML decoder rejects unknown keys. Existing stored definitions must keep
|
||||
parsing, so a new key is optional with a default that preserves today's
|
||||
behaviour.
|
||||
- A declared `outputs:` entry is written through a capture tool, so it forces
|
||||
the captures need: `task.WorkflowInterface.Needs` resolves that from the
|
||||
declaration rather than the author also writing `needs.captures`. A Kit
|
||||
profile whose harness serves no capture tools is refused before dispatch.
|
||||
- Examples in `examples/workflows/` are parsed against the registered
|
||||
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
|
||||
|
||||
## Enabling and disabling
|
||||
|
||||
The `workflow-enablement` control-plane resource lists, per org, the workflows
|
||||
that org has disabled; anything unlisted is enabled. Its readers are the
|
||||
daemon's binding dispatch (a disabled workflow's binding is skipped like an
|
||||
unarmed one), the dashboard's binding save (refused) and binding list
|
||||
(`workflow_disabled`), and work requests. A new reader of "may this org run
|
||||
this workflow" goes through `task.WorkflowEnablement.Enabled`, never a second
|
||||
list. The dashboard acts in the default org until access resolves a caller's
|
||||
own.
|
||||
|
||||
## Starting a workflow from chat
|
||||
|
||||
`task_spawn` accepts `workflow` and an `inputs` object. The gateway forwards
|
||||
inputs through the task creation contract; it does not interpret individual
|
||||
workflows. The daemon checks inputs against the pinned `WorkflowInterface`
|
||||
before acquiring a container and parks invalid requests with the reason.
|
||||
@@ -0,0 +1,28 @@
|
||||
# PR review benchmark
|
||||
|
||||
Run `scripts/pr-review-benchmark.sh` with `PRBENCH_REVIEW_MODEL` and
|
||||
`PRBENCH_CLASSIFICATION_MODEL` set to configured `provider/model` references.
|
||||
The judge defaults to `anthropic/claude-sonnet-4.6`; set
|
||||
`PRBENCH_JUDGE_MODEL` to another configured model when needed. The script uses
|
||||
`~/.config/archie/config.toml` for providers and `GH_TOKEN` or `GITHUB_TOKEN`
|
||||
for read access to the benchmark pull requests. It posts no forge review.
|
||||
|
||||
The default run reviews the 38 runnable Martian pull requests once each at
|
||||
`deep`, judges the comments against 102 golden comments, and writes
|
||||
`bin/prbench-results/run.json`, `summary.json`, and one JSON result per pull
|
||||
request. That output directory is ignored by git. A completed full run fails
|
||||
when any problem fails or golden micro-recall is below 0.70. Golden-only
|
||||
precision is reported alongside recall. Set `PRBENCH_OUT` to keep separate
|
||||
runs; `-problems ID` limits a smoke run to one pull request. Completed results
|
||||
are saved as each PR finishes. Pass `-resume DIR` to reuse completed results
|
||||
from a run with the same models; each reused problem must match the current
|
||||
benchmark entry, and failed problems are rerun.
|
||||
A smoke run alone is not the acceptance run.
|
||||
|
||||
The benchmark passes only each problem's ID and pull request URL to the
|
||||
reviewer. The judge receives the golden comments after the review has ended.
|
||||
The runner uses the production decision phases through the merge gate,
|
||||
including scoring and the 25-comment cap, then stops before polish and forge
|
||||
posting. A reviewer that fails to finish makes that problem fail. The results
|
||||
record budget-skipped phases and the selected models. Model substitutions do
|
||||
not satisfy the PRD's named-model criterion even if recall clears the threshold.
|
||||
@@ -1,149 +0,0 @@
|
||||
# Sam's message, verbatim (2026-09-05)
|
||||
|
||||
Source: chat message pasting an AWX forum post (AWX modernisation series,
|
||||
"Refactoring AWX into a Pluggable, Service-Oriented Architecture") plus a
|
||||
terminal transcript and a follow-up message including Ansible's
|
||||
`ansible/playbook/task.py`. Preserved verbatim below for later reference.
|
||||
Image attachment (`AAP Pluggable Architecture` diagram) is described, not
|
||||
reproduced, since this file is text-only.
|
||||
|
||||
---
|
||||
|
||||
[01:09:53] sam@helix /work/clones
|
||||
|
||||
> git clone https://github.com/ansible/ansible.git
|
||||
> Cloning into 'ansible'...
|
||||
> remote: Enumerating objects: 644471, done.
|
||||
> remote: Counting objects: 100% (21/21), done.
|
||||
> remote: Compressing objects: 100% (21/21), done.
|
||||
> remote: Total 644471 (delta 5), reused 2 (delta 0), pack-reused 644450 (from 3)
|
||||
> Receiving objects: 100% (644471/644471), 251.86 MiB | 9.60 MiB/s, done.
|
||||
> Resolving deltas: 100% (427812/427812), done.
|
||||
> [01:12:50] sam@helix /work/clones
|
||||
> git clone https://github.com/ansible/awx.git
|
||||
> Cloning into 'awx'...
|
||||
> remote: Enumerating objects: 331428, done.
|
||||
> remote: Counting objects: 100% (399/399), done.
|
||||
> remote: Compressing objects: 100% (256/256), done.
|
||||
> remote: Total 331428 (delta 259), reused 153 (delta 143), pack-reused 331029 (from 3)
|
||||
> Receiving objects: 100% (331428/331428), 346.81 MiB | 12.94 MiB/s, done.
|
||||
> Resolving deltas: 100% (254095/254095), done.
|
||||
> [01:14:59] sam@helix /work/clones
|
||||
|
||||
---
|
||||
|
||||
[Image #2]
|
||||
|
||||
Hi folks,
|
||||
|
||||
In our previous post, we discussed the upcoming changes we're making to the AWX project. Today, we'd like to dive deeper into one of the most significant changes: refactoring AWX into a pluggable, service-oriented architecture.
|
||||
Current State of AWX
|
||||
|
||||
AWX is currently structured as a monolithic Django application. It consists of several entry points, each running as individual processes, including our API, Job Dispatcher, Event Processor, and Websocket subsystem. Alongside these, AWX relies on various ancillary processes such as Redis, Rsyslog, Receptor, Nginx, Uwsgi, and Daphne.
|
||||
Challenges with the Current Architecture
|
||||
|
||||
Over time, it has become increasingly challenging to implement changes due to the large, self-contained nature of the application. This monolithic structure has not only slowed down our development process but also made it difficult to ensure efficient code reuse across our other applications. Consequently, this impacts both our development efficiency and the ability to quickly iterate on features and fixes. As we continue to extend capabilities across Ansible Automation Platform we cannot afford these challenges and maintain upstream projects the way they are currently structured.
|
||||
Proposed Changes
|
||||
|
||||
To address these challenges, we are beginning to transition AWX towards a more pluggable, service-oriented architecture. By breaking down the monolithic structure into smaller, modular services, we aim to enhance both flexibility and maintainability. This shift will enable us to make changes more swiftly and efficiently in AWX while also improving our ability to reuse code across various projects leveraged by Ansible Automation Platform.
|
||||
Implementation Plan
|
||||
|
||||
Our implementation plan involves several key steps:
|
||||
|
||||
Identifying Modular Services: We will start by identifying the core functionalities that can be extracted into individual plugins and/or services.
|
||||
Creating a Communication Framework: Establish a robust communication framework to ensure seamless interaction between these services.
|
||||
Gradual Transition: Implement the new architecture in phases to allow for continuous feedback and improvement.
|
||||
Community Collaboration: Engage with our community throughout the process to gather feedback and ensure the new architecture meets the needs of our users.
|
||||
|
||||
Future-Looking Architecture
|
||||
|
||||
1316×628 38.8 KB
|
||||
|
||||
Expected Outcomes
|
||||
|
||||
By refactoring AWX into a service-oriented architecture, we expect several positive outcomes:
|
||||
|
||||
Improved Flexibility: Easier to implement changes and add new features.
|
||||
Enhanced Maintainability: Simplified codebase with clear service boundaries.
|
||||
Better Code Reuse: More efficient reuse of code across different projects.
|
||||
Active Community Participation: Greater opportunity for community members to contribute and shape the project.
|
||||
|
||||
Call to Action
|
||||
|
||||
We invite feedback and collaboration with us on this significant transformation by replying to this forum post.
|
||||
|
||||
Join the discussions on our forum, share your thoughts, and help shape the future of awx .
|
||||
Conclusion
|
||||
|
||||
These architectural changes are a crucial step towards a more modern and scalable AWX. We look forward to your participation and support as we embark on this journey together.
|
||||
|
||||
Stay updated by joining The Forum, following the
|
||||
News & Announcements and
|
||||
awx tags.
|
||||
|
||||
Thank you for your continued support.
|
||||
Links in this AWX update series
|
||||
|
||||
Blog: Upcoming Changes to the AWX Project
|
||||
Streamlining AWX Releases
|
||||
Refactoring AWX into a Pluggable, Service-Oriented Architecture (this post)
|
||||
Upcoming changes to AWX Operator installation methods
|
||||
AWX UI and credential types transitioning to the new pluggable architecture
|
||||
AWX modernisation: Moving forward
|
||||
AWX modernisation: Ansible UI
|
||||
AWX modernisation: Ansible Jewel
|
||||
|
||||
Useful links
|
||||
|
||||
2024-05-30 Blog: Upcoming Changes to the AWX Project
|
||||
2024-07-01 Streamlining AWX Releases
|
||||
The Forum: AWX topics
|
||||
The Forum: Newsletter Category
|
||||
|
||||
---
|
||||
|
||||
Taking a look at this, How could we reframe ourselves to capture some of this market?
|
||||
|
||||
Archie is already a beast of a project, I think that it would be an excellent idea to think about cleaning up, simplifying, and unifying many of it's layers down to cleaner interfaces and even if it's starting at the most basic layers such as splitting the UI from the backend, turning the agent into a core runner, or even having 2 separate agent definitions, an AI agent and an agent runner. or. even better, an agent runner which utilises an open source project like Pi as the AI harness instead of having to code our own one.
|
||||
|
||||
I have Pi running now, with an immensely fast and capable model (deepseek-v4-flash-vision-exp) which is absolutely able to perform many actions at great speed, and that could assist us to getting this chunk of work done.
|
||||
|
||||
the idea of everything being pluggable services - making the entire solution modular, is exactly the goal I've had from the start. and it's already heading that way, but it's missing some guidance, assistance and care. I believe that a multi-agent system could help me get there, where I talk to an agent like claude, which spawns subagents to start implementation in isolation, and another agent monitors the work, assists, and carefully merges as the migration is in progress.
|
||||
|
||||
[01:23:10] sam@helix /work/apps/archie-core
|
||||
|
||||
> tree
|
||||
> (directory tree of archie-core omitted here -- see repository working tree at
|
||||
> the time of writing for the full listing; top-level shape was: AGENTS.md,
|
||||
> ARCHITECTURE.md, cmd/{archie-agent,archied,archie-playbooks}, deployments/,
|
||||
> docs/{architecture,archive,data,guides,prds,public}, examples/, extras/,
|
||||
> internal/{agentexec,app,channels,config,container,daemon,domain,eventbus,
|
||||
> events,forge,forgerpc,gate,gateway,indexing,infrastructure,installtype,
|
||||
> logging,memory,natsrpc,pairing,plugin,ratelimit,releaseannounce,
|
||||
> releaseupdate,secret,skill,skillscript,storage,store,storerpc,taskrun,
|
||||
> taskstate,tools,webhookguard,webui,worktree,worktreerpc,yaegiutil}, scripts/,
|
||||
> tools/, ui/{dist,src,test})
|
||||
> [01:23:12] sam@helix /work/apps/archie-core
|
||||
|
||||
---
|
||||
|
||||
One other thing I've grabbed inspiration from the Ansible project and I'm hoping to splice in - is the task.py (and likely more items) definitions; I think that being able to use existing ansible playbooks (and eventually roles/etc) within archie, would be astoundingly benefitial for engagement.
|
||||
|
||||
(ansible/playbook/task.py, GPLv3, Michael DeHaan et al. -- full file pasted in
|
||||
chat; omitted here as reference-only source code, not reproduced verbatim in
|
||||
this repository. It defines Ansible's `Task` class: FieldAttribute-based
|
||||
declarative fields such as `args`, `action`, `loop`, `register`,
|
||||
`changed_when`/`failed_when`/`until`, `delay`/`poll`/`retries`,
|
||||
`loop_control`; `preprocess_data` which runs `ModuleArgsParser` to resolve the
|
||||
legacy free-form task shape into `(action, args, delegate_to)`; `post_validate`
|
||||
which templates fields through Jinja2 (`TemplateEngine`); parent-chain
|
||||
attribute inheritance (`_get_parent_attribute` walking up through Block /
|
||||
TaskInclude / Play); and `_resolve_conditional` for `when:` evaluation.)
|
||||
|
||||
---
|
||||
|
||||
Attached image: "AAP Pluggable Architecture" diagram -- a decomposition tree
|
||||
with "AWX Decomposition" as root, branching to: Credentials, Subscription/
|
||||
Billing, Auth (children: RBAC, SSO, Policy/ABAC), Communication (child:
|
||||
Inter Service, and Execution (mesh) linked back into Runtime), Telemetry,
|
||||
Inventory, Runtime (child: Scheduler), Content (child: Projects).
|
||||
@@ -1,127 +0,0 @@
|
||||
# Module reference: AWX decomposition / Ansible task model vs. Archie
|
||||
|
||||
Status: exploratory reference, not a design decision. Nothing here is
|
||||
authoritative -- `docs/architecture/` stays the source of truth. This exists
|
||||
so a later PRD (if one gets written) doesn't have to re-derive "what do we
|
||||
already have vs. what AWX/Ansible are describing." See
|
||||
[[2026-09-05-awx-service-decomposition-and-ansible-task-model]] for the
|
||||
source material this is built from.
|
||||
|
||||
Two follow-on artifacts extend this line of exploration:
|
||||
|
||||
- Two Archify diagrams contrasting current vs. an ideal service-oriented
|
||||
shape: `/work/artefacts/archie-core-current-state-archify.html` and
|
||||
`/work/artefacts/archie-core-ideal-state-archify.html`. The current-state
|
||||
diagram is grounded in verified coupling (webui's task-action path routes
|
||||
through its own HTTP handler in-process; direct `gateway.SessionStore` /
|
||||
`Router` / `TurnHistory` access; a shared `config.Holder`) -- not the
|
||||
"already split" claim this document's earlier draft mistakenly made.
|
||||
- [[service-discovery-research-2026-09-05]] -- externally researched
|
||||
comparison of service-discovery mechanisms for the ideal-state's "install
|
||||
a service, the fleet auto-aligns" requirement. Recommends Kubernetes-native
|
||||
discovery as primary (Helm chart + Operator on k3s / a real cluster) with
|
||||
NATS-based discovery (already a hard dependency) as the built-in fallback
|
||||
for no-K8s single-host installs, both behind one `ServiceRegistry`
|
||||
interface.
|
||||
|
||||
## Reading the two source ideas separately
|
||||
|
||||
The AWX post and the Ansible `Task` paste are two different asks and should
|
||||
stay two different tracks:
|
||||
|
||||
1. **AWX's decomposition tree** is an argument for splitting a monolith
|
||||
along service boundaries (Auth, Comms, Runtime, Content, ...) with a
|
||||
pluggable communication mesh between them. Archie's six-domain split
|
||||
(`docs/architecture/index.md`) already **is** that argument, applied
|
||||
earlier and at a different grain (domain boundaries in one Go module +
|
||||
NATS transport, not separate deployable services). The gap isn't "do we
|
||||
need boundaries," it's "are the boundaries clean and are they enforced."
|
||||
2. **Ansible's `Task`/module system** is a request for a _content_ format:
|
||||
let users write YAML tasks against a stable action vocabulary and have
|
||||
Archie interpret them, the way Ansible interprets `- name: ... action:
|
||||
module: args`. Archie has the skeleton of this already (EDA playbook
|
||||
engine, Module action position) but it's deliberately narrow today.
|
||||
|
||||
## AWX decomposition tree -> Archie's existing domains
|
||||
|
||||
| AWX node | Archie equivalent today | Location |
|
||||
| ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
|
||||
| Auth (RBAC / SSO / Policy-ABAC) | `internal/domain/binding` (task-to-identity/config binding) + `internal/policy` (cross-cutting, zero internal imports) + forge/channel auth (Telegram pairing, webhook HMAC) | `internal/domain/binding/`, `internal/policy/`, `internal/pairing/`, `internal/webhookguard/` |
|
||||
| Communication / Inter-Service | NATS (`ARCHIE_TASKS` JetStream work queue, core-NATS RPC via `_INBOX.*`) | `internal/infrastructure/eventbus/nats/`, `internal/natsrpc/`, `internal/eventbus/` (contract, zero internal imports) |
|
||||
| Execution (mesh) | Container pool running isolated agent worktrees over NATS, not a mesh of remote execution nodes (Ansible's Receptor equivalent doesn't exist -- Archie's "remote execution" is a Docker container, not a fleet) | `internal/container/pool.go`, `internal/agentexec/`, `internal/worktree/` |
|
||||
| Runtime / Scheduler | `internal/domain/scheduling` (ticker contract) + cron-driven work intake | `internal/domain/scheduling/`, `internal/infrastructure/cronstore/` |
|
||||
| Content / Projects | Nearest analogue is the **EDA playbook + module system** (below) plus `internal/skill` (skill catalogue) -- Archie has no "project" = git-checkout-of-automation-content concept the way AWX does | `internal/domain/eda/playbook/`, `internal/domain/eda/module/`, `internal/skill/` |
|
||||
| Telemetry | `internal/logging` (task sink, feed, registry) + `internal/events` | `internal/logging/`, `internal/events/` |
|
||||
| Inventory | No direct equivalent. Closest is forge-side repo/identity config (`[[identities]]`, `internal/forge`) -- Archie targets one identity acting across a small set of forge repos, not a dynamic inventory of managed hosts | `internal/forge/`, `internal/config/` |
|
||||
| Credentials | `internal/secret` (engine host, env/age/sops/vault engines) | `internal/secret/`, `internal/secret/enginehost/` |
|
||||
| Subscription/Billing | No equivalent -- Archie is self-hosted, single-tenant; this AWX node doesn't map to anything and shouldn't | -- |
|
||||
| UI split from backend | Already true: `internal/webui` (Go API server) serves a separately built SPA from `ui/dist` (Vite/React-ish, `ui/src/<feature>/`) over HTTP/SSE. There is no shared-process coupling to undo. | `internal/webui/`, `ui/src/` |
|
||||
|
||||
**Read on "reframe to capture market":** the honest gap next to AWX/AAP isn't
|
||||
domain boundaries -- Archie already has those, arguably cleaner (env-enforced
|
||||
gates, one dependency direction, contracts with zero internal imports). The
|
||||
gap is (a) no content/inventory layer letting non-programmers hand Archie
|
||||
declarative automation the way an Ansible playbook does, and (b) everything
|
||||
still ships as one Go binary + one container image, not independently
|
||||
deployable/upgradable services. (a) is the more differentiated, more
|
||||
buildable opportunity given a one-person team; (b) is expensive AWX-style
|
||||
service splitting with limited payoff at Archie's current scale and should
|
||||
not be pursued for its own sake.
|
||||
|
||||
## Ansible `Task` model -> Archie's EDA playbook/module system
|
||||
|
||||
Ansible's `task.py` is the runtime representation of one YAML task after
|
||||
`ModuleArgsParser` resolves the legacy free-form shape and `TemplateEngine`
|
||||
renders Jinja2. Archie's nearest shipped analogue is the EDA playbook engine,
|
||||
which is **intentionally much narrower right now**:
|
||||
|
||||
| Ansible concept | Archie's current shape | Gap / what porting the idea would mean |
|
||||
| --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `Task` (one step, `action` + `args`) | `playbook.Action` (`internal/domain/eda/playbook/playbook.go`) -- but **exactly one action per playbook, position must be `"workflow"`**, hard-rejected at load otherwise | Multi-action, multi-position playbooks are the literal ask ("use existing ansible playbooks... within archie") but are explicitly blocked today on unresolved execution-time gaps: mid-run failure semantics, idempotency for non-workflow actions (see the package doc comment and `docs/architecture/plugins-and-extensions.md`'s Event sources section). This is a known, named boundary, not an oversight. |
|
||||
| Module (`ansible.builtin.*`, arbitrary Python) | `module.Kind` registry, Yaegi-interpreted `.go` files against a generated per-kind symbol table (`internal/domain/eda/module/`) -- **one shipped kind: `log`** | Ansible modules are dynamically loaded from a huge ecosystem; Archie's Module position is closed-registry-of-named-kinds, each with its own hand-written contract package (`internal/domain/eda/module/<kind>`). Adding "run a shell command," "call a forge API," "send a channel message" module kinds is possible under the existing pattern but each is new work, not automatic from having the mechanism. |
|
||||
| `when:` conditional | `Action.When`, compiled CEL (`internal/domain/eda/expr`), not Jinja2 | Already decided: CEL over Jinja2 (open question 1 in the playbook engine PRD, resolved). Don't reopen. |
|
||||
| `register` / fact accumulation across tasks | Not present -- `DispatchInput.Event` is a flat map exposed to CEL, there's no cross-action result chaining because there's only one action | Needed before multi-action playbooks are meaningful; tracked implicitly by the same "unresolved execution-time gaps" blocker above. |
|
||||
| `loop` / `until`/`retries`/`delay` | Not present | Same -- follows from allowing more than one action per playbook. |
|
||||
| Field-attribute inheritance (task -> block -> play) | No block/parent chain -- a playbook is flat: one `Trigger` + one `Action` | Ansible's play/block/role hierarchy has no Archie counterpart yet; would only matter once multi-action/roles are in scope. |
|
||||
| Roles (reusable task bundles) | Nearest is `internal/skill` (skill catalogue, frontmatter, tool defs) -- conceptually closer to Claude Skills than Ansible roles | Not a role system; skills are agent-facing capability bundles, not declarative task sequences. |
|
||||
| Channel / Forge action positions | Named and designed but explicitly **not implemented** (`docs/architecture/plugins-and-extensions.md`: "Channel and Forge action positions are designed but not yet implemented," open investigation `archie-core-t2db.19`) | This is the direct next step toward "playbooks that do things," independent of the Ansible-compatibility idea. |
|
||||
|
||||
**What porting real Ansible playbooks would actually require**, in rough
|
||||
dependency order, if this becomes a real proposal later:
|
||||
|
||||
1. Lift the playbook engine's hard boundary: multi-action playbooks, which
|
||||
needs the mid-run failure/idempotency semantics the doc comment flags as
|
||||
the blocker today.
|
||||
2. A result-passing mechanism between actions (Ansible's `register`) --
|
||||
currently nothing carries one action's output into the next action's
|
||||
`when`/`args`.
|
||||
3. Loop/retry primitives per action.
|
||||
4. A much larger Module `Kind` registry, or a deliberate decision to accept
|
||||
a narrower "Archie automation language inspired by Ansible's shape" rather
|
||||
than "runs unmodified Ansible YAML" -- the latter also drags in Jinja2,
|
||||
the module_utils Python runtime, and inventory/host-targeting concepts
|
||||
Archie has no use for (Archie targets git repos and forge issues, not
|
||||
fleets of managed hosts). Recommend treating "Ansible-_inspired_ syntax,
|
||||
not Ansible-_compatible_ execution" as the working assumption if/when a
|
||||
PRD gets written -- it avoids importing Ansible's inventory/host model,
|
||||
which doesn't fit Archie's single-repo-per-task execution shape at all.
|
||||
|
||||
## On the multi-agent / Pi-harness-as-runner idea
|
||||
|
||||
Out of scope for this reference doc (it's an operating-model question, not a
|
||||
module-mapping one) but noted since it was raised alongside the above: this
|
||||
is a `migration-decisions.md`-track question (agent execution as a strict
|
||||
data boundary is a named invariant in `ARCHITECTURE.md`), not something to
|
||||
back into via the EDA/module work. Flag separately if it's worth pursuing.
|
||||
|
||||
## Bottom line
|
||||
|
||||
- No code changes implied by this document. It's a map, not a proposal.
|
||||
- The two ideas in Sam's message decompose cleanly: AWX's service-split
|
||||
argument is mostly already satisfied by Archie's domain architecture; the
|
||||
Ansible-playbook-content idea is a real, currently-blocked extension of
|
||||
the EDA Module/Channel/Forge action positions, gated on the same
|
||||
execution-semantics work already named in `plugins-and-extensions.md`.
|
||||
- If this becomes a real initiative, it belongs in `docs/prds/` as a
|
||||
decisive 1-pager per `AGENTS.md`'s scope-discipline rule -- not as an
|
||||
elaboration of this file.
|
||||
@@ -1,868 +0,0 @@
|
||||
# Service decomposition open questions: research for #1–#5
|
||||
|
||||
Status: research pass that resolves all five blocking open questions in
|
||||
[[service-decomposition]] (the Proposed-status PRD). It extends — it does
|
||||
not replace — that PRD and [[service-discovery-research-2026-09-05]].
|
||||
Questions #2 (contract definition mechanism) and #3 (in-process vs
|
||||
out-of-process during migration) were resolved in a later pass; Q1's
|
||||
Phase 0 dependency on #2's contract-definition mechanism (buf + grpc-go,
|
||||
committed generated code) is now satisfied.
|
||||
|
||||
Produced by an agent research pass against primary sources: a
|
||||
supervisor-run set of `deep_search_exa` queries plus direct fetches of
|
||||
the canonical primary texts (Martin Fowler / Zhamak Dehghani's
|
||||
monolith-breaking article, microservices.io's database-per-service
|
||||
pattern, Microsoft's .NET microservices data-sovereignty guidance, the
|
||||
Kubebuilder book, Helm's chart documentation). Every recommendation is
|
||||
grounded in the verified archie-core coupling findings from the PRD and
|
||||
in the code (checked at `internal/app/archied/main.go`,
|
||||
`internal/webui/server.go`, `internal/webui/api_chat.go`,
|
||||
`internal/store/interface.go`, `internal/store/store.go`,
|
||||
`internal/storerpc/storerpc.go`, `internal/gateway/session_store_sqlite.go`,
|
||||
`internal/app/archied/bootstrap.go`). Reproduced close to verbatim as the
|
||||
record; light formatting only.
|
||||
|
||||
Repositioning note: the PRD's own text floats a hypothesis ("Gateway
|
||||
Service's `ChatContract` should exist before UI Service is extracted").
|
||||
This document **confirms that hypothesis with code archaeology and
|
||||
strengthens it**, and it is the single most important finding: archie-core's
|
||||
Gateway is both the _stickiest_ capability and the one with an already-
|
||||
clean seam and already-isolated data. The generic "extract a leaf /
|
||||
read-only thing first" advice does not apply here, and I say so with the
|
||||
reason why.
|
||||
|
||||
---
|
||||
|
||||
## Summary of the five recommendations
|
||||
|
||||
| # | Question | Recommendation (one line) |
|
||||
| --- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 1 | Extraction order | **Gateway Service first**, then State Store, then UI, then Messaging, then Execution/Runner/Scheduler, then Curator (optional) — preceded by an in-process "contract seams" phase (modular monolith) that is #2's real prerequisite. |
|
||||
| 2 | Contract definition mechanism | **buf v2 + protoc-gen-go + protoc-gen-go-grpc** (grpc-go, not connect-go), one committed `proto/<service>/v1/` tree generating into `internal/contracts/<service>/v1/`, directory-versioned, `buf breaking` gated in `task check` and mirrored into CI. |
|
||||
| 3 | In-process vs. out-of-process during migration | **Multiplexed in-process is the migration default**: one wire-safe Go contract interface per service, a local adapter and a generated gRPC client adapter, composition (not `ServiceRegistry`) picks which one, and the flip to a real process is a same-commit deletion of the in-process path — no dual-live window. |
|
||||
| 4 | State Store's contract shape | **One State Store service owns a single SQLite file behind narrow typed contracts** (the existing `internal/store` split already does the ownership; the gap is enforcement). No physical database-per-service at this scale, and no distributed-transaction problem, because there is still one store. Gateway keeps its own already-separate session SQLite. |
|
||||
| 5 | Helm chart / Operator scoping | **Three charts** (a `library` chart of the shared contract templates, one `archie` chart for the 7 core services, one `archie-curator` chart + a Curator Operator) — and the smallest first milestone is a **single Curator CR that the Operator reconciles into a Deployment + Service, with Gateway resolving `curator` via the `ServiceRegistry`**. |
|
||||
|
||||
---
|
||||
|
||||
## Question #1 — Extraction order
|
||||
|
||||
### The question and the hypothesis
|
||||
|
||||
The PRD asks which service is pulled out of the monolith first and what
|
||||
staged sequence follows. Its own text proposes: Gateway Service's
|
||||
`ChatContract` should exist before UI Service is extracted, "since UI is
|
||||
the most entangled consumer today."
|
||||
|
||||
### Verified coupling (the load-bearing facts)
|
||||
|
||||
The PRD's three cited couplings are real; I re-checked the call sites:
|
||||
|
||||
1. **Telegram task-action routes through webui's HTTP handler.** The
|
||||
message path is `chatTaskActorAdapter.ApplyChatTaskAction`
|
||||
(`internal/app/archied/main.go:655`) which the daemon wires and which
|
||||
dispatches into `internal/webui`'s `handleTaskAction`
|
||||
(`internal/webui/api_tasks.go:136`, mounted at
|
||||
`server.go:294`). Messaging Service (the Telegram adapter) has no
|
||||
direct route to the gateway today — it must detour through a UI HTTP
|
||||
handler to apply a pause/resume/abandon action.
|
||||
2. **UI reaches directly into gateway internals.**
|
||||
`internal/webui/api_chat.go`'s `ChatService` is _literally_ `Router
|
||||
*gateway.Router`, `Sessions gateway.SessionStore`, `Turns
|
||||
*gateway.Turns` plus `Models gateway.ModelManager` and `Personas
|
||||
*gateway.PersonaRegistry`, and it calls `chat.Sessions.(gateway.TurnHistory)`
|
||||
at line 198 and `chat.Router.Route`/`ResolveSessionKey` at 256/261.
|
||||
This is not "a UI calling a Gateway API" — it is the UI holding the
|
||||
Gateway's internal objects and calling their methods in-process.
|
||||
3. **A shared `config.Holder`.** `bootstrap.go:1236` comments explicitly:
|
||||
"web and the daemon must share ONE Holder"; the daemon's live Holder is
|
||||
handed to webui at `bootstrap.go:336` and again where the dashboard
|
||||
mutation path runs.
|
||||
|
||||
Two further facts the PRD does not foreground but that decide the order:
|
||||
|
||||
- **The Gateway is already decoupled from the store.** `main.go:139`
|
||||
and `gateway/tasks.go:44` state it deliberately: gateway does **not**
|
||||
import `internal/store`. It consumes narrow contracts
|
||||
(`StatusReader`, `TaskCreator`, `TaskLister`, `TaskController`,
|
||||
`AgentReader`) that `internal/app/archied` adapts. This is a ready seam.
|
||||
- **The Gateway already owns an isolated session store.**
|
||||
`internal/gateway/session_store_sqlite.go` is a _separate_ SQLite DB
|
||||
(`OpenSQLiteSessionStore`, own `sqliteSessionSchema`) from
|
||||
`internal/store`. Chat session/turn/message data is **already** separate
|
||||
from task/work-intake data.
|
||||
|
||||
### What the research says about sequencing
|
||||
|
||||
The canonical guidance is Fowler / Dehghani's _How to break a Monolith
|
||||
into Microservices_. Its explicit sequencing principles are: **warm up
|
||||
with a simple and fairly decoupled capability**; **minimise dependency
|
||||
back to the monolith**; **split sticky capabilities early**; **decouple
|
||||
vertically and release the data early**; **decouple what is important to
|
||||
the business and changes frequently**; **go macro first, then micro**;
|
||||
**migrate in atomic evolutionary steps**. The popular-strangler-fig
|
||||
commentary (YuSMP, Md Sanwar Hossain, CloudRPS) adds a pragmatic
|
||||
variant: improve the monolith into a _modular monolith_ first, create a
|
||||
routing facade, extract the **low-coupling / leaf / read-heavy** context
|
||||
first, defer auth and the core "sticky" engines to later, and treat the
|
||||
first extraction as an **operations dry-run** (build pipeline, contract
|
||||
testing, observability, rollback) rather than maximising value.
|
||||
|
||||
There is a real tension here. The bulk of the practitioner advice says
|
||||
"extract the least-coupled leaf first." But that advice is calibrated for
|
||||
large, team-owned, revenue-critical systems where a first extraction
|
||||
regression is a production incident and where the team has not yet found
|
||||
its seams. Two of its own authors note the counterweight: Fowler's
|
||||
**"split sticky capabilities early"** explicitly warns against deferring
|
||||
the tangled capability, on the theory that the longer you wait the more
|
||||
sticky and expensive it becomes; and StackAuthority's blueprint sorts by
|
||||
**data coupling and change velocity**, not pure ease — "order matters more
|
||||
than most teams realise."
|
||||
|
||||
### Why the generic "leaf first" is wrong here
|
||||
|
||||
archie-core is not the enterprise monolith those guides assume. It is
|
||||
already a **modular monolith with clean domain boundaries**
|
||||
(`organisation.md` is enforced; `internal/domain/*` owns one cohesive
|
||||
job; the six-domain split is settled). It has **no** organisational
|
||||
blast-radius to protect (solo maintainer's daemon, not a payment path),
|
||||
and its **actual** cost is concentrated in the process-packaging tangle,
|
||||
not in undiscovered seams. It also has what the "seam-finding" guides
|
||||
tell you to look for but rarely find: a capability that is **sticky and
|
||||
already has a clean contract seam and already-isolated data**.
|
||||
|
||||
So the deciding question is not "which is the safest to cut first?" It is
|
||||
"which capability, if cut, releases the most entangled consumer and
|
||||
stands up the product's primary contract?" The answer is the Gateway.
|
||||
|
||||
This **confirms** the PRD hypothesis, and adds a reason the PRD did not
|
||||
state: the Gateway is extractable _now_, on its own, with zero store
|
||||
migration, because it is already store-decoupled and already owns its
|
||||
session DB. UI is **not** extractable first — it is trapped behind the
|
||||
Gateway's internals and can only become a thin client once
|
||||
`ChatContract` exists. Extracting Gateway first is therefore also the
|
||||
cheapest way to unblock UI (the most entangled consumer), which is the
|
||||
PRD's ultimate goal.
|
||||
|
||||
### Decision: the ordered phase list
|
||||
|
||||
This is a **phase list** (each phase is a stable, working, independently
|
||||
releasable step; it is not a task breakdown). Each phase is one "atomic
|
||||
evolutionary step" per Fowler.
|
||||
|
||||
**Phase 0 — Contract seams (still a modular monolith, no process split).**
|
||||
Introduce, in-process, the seams that make later extraction a swap of
|
||||
transport rather than a rewrite: a `ChatContract` interface owned by the
|
||||
Gateway (aligning `Router`/`SessionStore`/`Turns`/`ModelManager`/
|
||||
`PersonaRegistry` behind it, so `webui` depends on the contract type, not
|
||||
on the Gateway's structs); the `ServiceRegistry` interface from the
|
||||
discovery research; and the State Store's already-narrow interfaces
|
||||
(`TaskStore`/`CaptureStore`/`MappingStore`/`BindingStore`) ratified as the
|
||||
State Store contract. **Dependency:** this is where #2's contract
|
||||
definition mechanism (`proto/` tree, codegen) lands; the seam is a
|
||||
prerequisite for the process split but #2 owns its mechanism. No network
|
||||
hop yet — this is the "modular monolith first" safe step.
|
||||
|
||||
**Phase 1 — Extract the Gateway Service (first real extraction).**
|
||||
Stand up `archie-gateway` as its own binary serving `ChatContract` over
|
||||
gRPC, using its existing isolated session SQLite and its existing
|
||||
store-adapters. Migrate consumers (UI, and the Messaging/Telegram
|
||||
task-action path) to call `ChatContract` over gRPC rather than holding
|
||||
`gateway.Router` in a struct or HTTP-detouring through webui. **Why
|
||||
here:** stickiest capability (everything routes through it) → Fowler's
|
||||
"split sticky capabilities early"; already store-decoupled → "minimise
|
||||
dependency back to the monolith" is already satisfied; highest-value
|
||||
contract (the PRD calls gRPC sync the product's primary contract); and it
|
||||
directly dissolves coupling #1 (Telegram→webui detour) and #2
|
||||
(webui→gateway internals) at their root. This is the operations
|
||||
dry-run — prove the GCP/gRPC/discovery playbook on the thing the whole
|
||||
product runs through.
|
||||
|
||||
**Phase 2 — Extract the State Store Service.**
|
||||
Expose `internal/store` as its own service behind its narrow contracts
|
||||
over gRPC (this is the generalisation we already have the seed for —
|
||||
`internal/storerpc` today proxies `store.WorkflowStore` to the agent over
|
||||
NATS; see Q4). Migrate the direct store imports in `internal/webui`,
|
||||
`internal/domain/workflow`, and the intake/binding paths onto the
|
||||
contract. **Why here:** "release the data early" (Fowler); UI and Workflow
|
||||
both read store state **directly** today, so neither can become a peer
|
||||
until that path is a contract call; and it is the lowest-risk data move
|
||||
because per Q4 it stays one SQLite file behind an API. Leaves a working
|
||||
system: Gateway on gRPC, everything else in the monolith but reading
|
||||
state via contract.
|
||||
|
||||
**Phase 3 — Extract the UI Service.**
|
||||
Now a genuinely thin client: serves the SPA from `ui/dist` and calls
|
||||
Gateway's `ChatContract` and State Store's read contracts. The
|
||||
`config.Holder` sharing and store/gateway internal access are gone. This
|
||||
closes the last verified coupling (#3 — shared Holder) and the last of the
|
||||
webui-entanglement list.
|
||||
|
||||
**Phase 4 — Extract the Messaging Service.**
|
||||
Telegram/email/webhook adapters become a peer service that calls
|
||||
Gateway's `ChatContract` directly (no UI HTTP detour). Now every async
|
||||
channel is a first-class peer; the webui is no longer in any message path.
|
||||
|
||||
**Phase 5 — Extract Execution Environment + Runner + Scheduler.**
|
||||
`internal/domain/workflow` dispatch, `internal/container/pool.go`,
|
||||
`internal/agentexec`, `internal/worktree` become the Execution Environment /
|
||||
Runner services (consuming State Store's `WorkflowStore` contract and the
|
||||
existing container contract); `internal/domain/scheduling` +
|
||||
`internal/infrastructure/cronstore` become the Scheduler. These are the
|
||||
heaviest and most store-coupled, so they go last; by here the facade
|
||||
(Gateway) and the data seam (State Store) are already proven.
|
||||
|
||||
**Phase 6 — Curator Service (the optional one, last).**
|
||||
Install as a Gateway plugin (its current shape is already a contract /
|
||||
registrar / registry family) and prove the latest-order discovery path +
|
||||
the optional-service `NotInstalled` semantic. This is deliberately last:
|
||||
it is the proof-of-optionality and the Q5 exercise, not a load-bearing
|
||||
first step. (The K8s Operator to _deploy_ it is Q5's concern and can be
|
||||
built on the Q1 timeline once the base chart exists.)
|
||||
|
||||
### What this doesn't settle
|
||||
|
||||
- **#2 and #3.** The phase list assumes #2 (proto/codegen) and #3
|
||||
(multiplexed in-process) are resolved consistently: Phase 0 is the
|
||||
modular-monolith with in-process seams, and Phase 1 is the first true
|
||||
process split. If #3 decides against in-process multiplexing, Phase 0
|
||||
collapses into Phase 1 for the Gateway.
|
||||
- **Whether Gateway should also host a "chat gateway" that owns the
|
||||
Session Store contract** vs. delegating chat state to a future concern.
|
||||
Decided _not_ to move session data into State Store here — it is already
|
||||
isolated and Gateway-owned; moving it would be churn with no benefit.
|
||||
- **Exact cadence / whether Curator can be extracted earlier.** It _can_,
|
||||
but only as the operator/optionality exercise; keeping it last avoids
|
||||
spending the "warm-up learning budget" on an optional component when the
|
||||
base services are not yet on the contract.
|
||||
|
||||
---
|
||||
|
||||
<a id="2"></a>
|
||||
|
||||
## Question #2 — Contract definition mechanism
|
||||
|
||||
### The question
|
||||
|
||||
Protobuf/gRPC service definitions need a home: a toolchain, a directory
|
||||
layout, a versioning scheme, a committed-vs-build-time-generation call, and
|
||||
codegen wiring into `Taskfile.yml` and CI.
|
||||
|
||||
### Toolchain: buf v2 + protoc-gen-go + protoc-gen-go-grpc (grpc-go)
|
||||
|
||||
**Decision: buf v2, driving `protoc-gen-go` and `protoc-gen-go-grpc`,
|
||||
targeting grpc-go.** Raw `protoc` is rejected — it has no lint, no
|
||||
breaking-change detection, and no managed mode for `go_package` paths, all
|
||||
of which buf provides directly. **connect-go is rejected too**, despite
|
||||
being a popular modern choice: its generated client is `net/http`-based,
|
||||
and its own README states it adds "no new name resolution or load
|
||||
balancing APIs." That is a direct conflict with the service-discovery
|
||||
research's design, which relies on grpc-go's resolver plumbing (a custom
|
||||
resolver for K8s DNS and a custom resolver reading the NATS JetStream KV
|
||||
registry — see `docs/inspiration/service-discovery-research-2026-09-05.md`
|
||||
and the `ServiceRegistry` interface at
|
||||
`internal/servicediscovery/servicediscovery.go:72`). connect-go would push
|
||||
K8s discovery onto `bufbuild/httplb` plus headless-Service DNS instead of
|
||||
grpc-go's resolver, which is a second discovery mechanism this repo does
|
||||
not want. `google.golang.org/grpc` becomes a direct dependency; today
|
||||
`go.mod:59` carries only `google.golang.org/protobuf v1.36.10 // indirect`.
|
||||
|
||||
### Layout: one committed `proto/<service>/v1/` tree, generated code committed to `internal/contracts/`
|
||||
|
||||
**Decision: a single top-level `proto/` tree**, one buf module, laid out as
|
||||
`proto/<service>/v1/*.proto` — per-service buf modules were considered and
|
||||
rejected as unnecessary ceremony at this scale (~7 services, one repo, one
|
||||
maintainer). The directory name is the canonical service name and must
|
||||
match the registry/DNS/chart name used elsewhere (`ServiceRegistry`,
|
||||
Helm chart service names). Generated Go is **committed** at
|
||||
`internal/contracts/<service>/v1/`, produced via buf's managed mode
|
||||
(`go_package_prefix`) plus `paths=source_relative`. This satisfies
|
||||
`docs/architecture/dependencies-and-contracts.md:55`'s "Wire contracts and
|
||||
generation" rule — wire contracts are partitioned per owning domain, never
|
||||
centralised in a generic schema package.
|
||||
|
||||
### Versioning: directory versioning, enforced by `buf breaking`
|
||||
|
||||
**Decision: directory versioning** (`v1`, Go package `<service>.v1`). A
|
||||
breaking change gets a new `vN` directory; a published version is never
|
||||
edited in place. Enforcement is `buf breaking --against
|
||||
'.git#branch=main,subdir=proto'` wired into the gate. This was verified
|
||||
against a real git ref in a scratch toolchain run (see Evidence below): it
|
||||
correctly flagged a deleted RPC, a renamed field, and a field deletion,
|
||||
exiting 100.
|
||||
|
||||
### Committed vs. build-time generation: committed
|
||||
|
||||
**Decision: commit the generated Go**, with a regenerate-and-diff-fail
|
||||
freshness check in CI, following the existing "generated assets are LAW"
|
||||
precedent (`ui/dist`, `task ui`, per `AGENTS.md`) and the committed Yaegi
|
||||
`*extract` tables (`internal/domain/workflow/wfextract/wfextract.go`).
|
||||
This keeps `task build` / `task test` hermetic — neither ever invokes
|
||||
`buf` — while still catching drift between `.proto` sources and checked-in
|
||||
Go via a `git diff --exit-code` step.
|
||||
|
||||
### Taskfile / CI wiring
|
||||
|
||||
New `task proto:generate`, `task proto:lint`, and `task proto:check`
|
||||
(regenerate, then `git diff --exit-code -- internal/contracts`) tasks,
|
||||
inserted into `task check` after `go fix ./...` and before `vet`/`lint`/
|
||||
`build`. This **must also be mirrored into
|
||||
`.github/workflows/deploy.yml`'s "Quality gate" step** — CI does not
|
||||
invoke `task check` today; it runs `gofumpt`, `go fix`, `vet`, `build`, and
|
||||
`test` directly, so the proto gate needs the same direct treatment or it
|
||||
will silently never run in CI. A shallow checkout (the default `actions/
|
||||
checkout` behaviour) breaks `buf breaking --against` because there is no
|
||||
local `main` ref to diff against; CI needs `fetch-depth: 0` or an explicit
|
||||
`git fetch origin main` step.
|
||||
|
||||
### What this doesn't settle
|
||||
|
||||
- **Per-plugin/toolchain version pinning for CI.** The repo currently does
|
||||
`go install ...@latest` for `gofumpt`; whether `buf` and the protoc
|
||||
plugins get the same treatment or pinned versions is an implementation
|
||||
detail for whoever wires the Taskfile/CI entries, not a design decision.
|
||||
- **Whether a headless/SRV Service variant changes anything about the
|
||||
generated Go.** It doesn't — the wire contract is transport-agnostic;
|
||||
discovery is a separate concern owned by `ServiceRegistry`.
|
||||
|
||||
---
|
||||
|
||||
<a id="3"></a>
|
||||
|
||||
## Question #3 — In-process vs. out-of-process during migration
|
||||
|
||||
### The question
|
||||
|
||||
Whether services can run multiplexed inside one binary behind the same
|
||||
contract during a transition period (so extraction is incremental and
|
||||
testable), or whether each service must be a separate binary from day one.
|
||||
|
||||
### Decision: multiplexed in-process is the migration default — this is the architecture's stated default, not a lean
|
||||
|
||||
`docs/architecture/organisation.md:70-77` ("Process boundaries") already
|
||||
states this as policy, verbatim: "Archie begins as a modular monolith even
|
||||
when capabilities run in separate processes. A domain becomes a separately
|
||||
deployed service only for a concrete need such as security isolation,
|
||||
independent scaling, failure containment, or independent operation.
|
||||
Possible future extraction does not justify premature network protocols or
|
||||
duplicated service scaffolding." Question #3 asks whether to follow that
|
||||
rule for this migration; the answer is yes, and it was already decided
|
||||
architecture-wide.
|
||||
|
||||
### Mechanism (six parts)
|
||||
|
||||
1. **Wire-safe Go contract interfaces.** Each per-service contract is a
|
||||
plain Go interface whose method signatures could cross the wire as-is:
|
||||
values and streams only. No callbacks (e.g. Gateway's
|
||||
`LLMStreamResponder`), no `*sql.Tx`, no object identity leaking through
|
||||
the interface. If a type can't become a proto message, it can't appear
|
||||
in the contract signature.
|
||||
2. **Two adapters per contract.** A **local adapter** (in-process, calls
|
||||
straight through, zero serialisation — not a test fake, a real
|
||||
production adapter) and a **generated gRPC client adapter**. Both
|
||||
satisfy the same interface, verified with a compile-time assertion in
|
||||
the existing repo idiom: `var _ store.WorkflowStore = (*Client)(nil)`
|
||||
(`internal/storerpc/storerpc.go:136`). The one-contract-two-transports
|
||||
shape is already in production today for the agent container over NATS
|
||||
(`internal/storerpc`, `internal/forgerpc`, `internal/worktreerpc`, wired
|
||||
at `internal/infrastructure/agenttransport/nats/transport.go:101,111`).
|
||||
3. **Composition chooses; `ServiceRegistry` stays network-only.**
|
||||
`ServiceRegistry.Resolve` never returns an in-process shim — a linked,
|
||||
in-process service is not in the registry at all. The registry models
|
||||
the network view only; `internal/app` composition wiring is the local
|
||||
view. Reasons: registry implementations should only ever observe real
|
||||
endpoints; `ErrNotInstalled` is an installability semantic
|
||||
(`internal/servicediscovery/servicediscovery.go:8-14`) that cannot
|
||||
arise for a module that's simply linked into the binary; and having one
|
||||
authoritative selection path (composition, not a registry call)
|
||||
eliminates a class of mixed-mode races. Concretely: a per-service
|
||||
`mode = "inproc" | "remote"` config value, defaulting to `inproc`.
|
||||
4. **Per-contract conformance suite.** Reuse the existing conformance-test
|
||||
idiom — `runSessionStoreSuite(t, newStore func(t *testing.T)
|
||||
SessionStore)` at `internal/gateway/sessionstore_conformance_test.go:65`
|
||||
— and run it against both the local adapter and a real gRPC server over
|
||||
`bufconn`. This is the "always test the wire shape" discipline, kept for
|
||||
tests only; production traffic in `inproc` mode never touches gRPC.
|
||||
5. **The flip trigger is the service's own extraction phase**, not a
|
||||
separate migration step: a new `cmd/archie-<service>` binary plus a
|
||||
same-commit deletion of the in-process serving path, with consumers
|
||||
flipped to `mode = "remote"` in that same commit. One commit, one
|
||||
authoritative implementation, no dual-live window. A Fowler-style
|
||||
dual-live cutover (old and new both serving, gradually shifted traffic)
|
||||
was considered and rejected at this scale: with two consumers in one
|
||||
repo and one release cadence, a dual-live window buys nothing but drift
|
||||
risk, concentrated exactly where the PRD's verified couplings already
|
||||
are. Rollback is a release-level revert — an accepted, honest trade for
|
||||
a solo maintainer, not a gap.
|
||||
6. **Failure semantics.** In `inproc` mode there is nothing new to reason
|
||||
about — a direct call either succeeds or panics like any other in-
|
||||
process call. In `remote` mode, a dial failure fails fast; per
|
||||
`ServiceRegistry`'s existing doc comment,
|
||||
`ErrNotInstalled` means "disabled," never "broken," for optional
|
||||
services (mirrors `internal/installtype/installtype.go`'s existing
|
||||
precedent that deployment-shape facts are baked/stated, not
|
||||
runtime-probed).
|
||||
|
||||
### Consequence for the resolved extraction order (Gateway first)
|
||||
|
||||
This directly satisfies Q1's Phase 0 dependency (see "What this doesn't
|
||||
settle" under Question #1, above): Phase 0 — introducing the `ChatContract`
|
||||
seam, its local adapter, the `.proto` definition, and the bufconn
|
||||
conformance suite — ships as an in-process module first, with nothing
|
||||
listening on a TCP port; the network protocol stays out of the production
|
||||
path until Phase 1. Phase 1 (extracting the Gateway) then becomes a wiring
|
||||
change only: add `cmd/archie-gateway`, delete the in-process serving path,
|
||||
flip `mode` to `remote` for its consumers. No amendment to Q1's phase list
|
||||
was needed — Q1 already anticipated exactly this shape.
|
||||
|
||||
### What this doesn't settle
|
||||
|
||||
- **Whether `mode` is a per-service config value or a build tag.** Decided
|
||||
here as runtime config (`mode = "inproc" | "remote"`), consistent with
|
||||
`internal/installtype`'s precedent of stating deployment shape rather
|
||||
than probing for it; a compile-time split was not considered necessary.
|
||||
- **The exact bufconn test harness plumbing.** Follows the existing
|
||||
`runSessionStoreSuite` idiom; the concrete harness is an implementation
|
||||
detail for whoever lands the first contract (Gateway's `ChatContract`).
|
||||
|
||||
### Sources used for Q2 and Q3
|
||||
|
||||
- `google.golang.org/protobuf v1.36.10 // indirect` — `go.mod:59` (today's
|
||||
only proto-adjacent dependency; confirms grpc-go is not yet a direct
|
||||
dependency).
|
||||
- `docs/architecture/organisation.md:70-77` — "Process boundaries" (the
|
||||
architecture's standing, Approved answer for #3).
|
||||
- `docs/architecture/dependencies-and-contracts.md:55` — "Wire contracts
|
||||
and generation" (per-domain ownership of wire contracts; no generic
|
||||
schema package).
|
||||
- `internal/servicediscovery/servicediscovery.go:8-14,71-81` —
|
||||
`ErrNotInstalled` semantics and the `ServiceRegistry` interface.
|
||||
- `internal/storerpc/storerpc.go:136` — `var _ store.WorkflowStore =
|
||||
(*Client)(nil)`, the compile-time contract-conformance idiom reused for
|
||||
the local/remote adapter pair; `internal/forgerpc`, `internal/worktreerpc`,
|
||||
and `internal/infrastructure/agenttransport/nats/transport.go:101,111`
|
||||
as the existing one-contract-two-transports precedent in production.
|
||||
- `internal/gateway/sessionstore_conformance_test.go:65` —
|
||||
`runSessionStoreSuite`, the conformance-test idiom reused for
|
||||
local-vs-remote adapter testing.
|
||||
- `internal/webui/api_chat.go:22-26` — `ChatService`'s struct fields
|
||||
(`Router *gateway.Router`, `Sessions gateway.SessionStore`, `Turns
|
||||
*gateway.Turns`, `Models gateway.ModelManager`, `Personas
|
||||
*gateway.PersonaRegistry`) — the concrete seam Q2/Q3's `ChatContract`
|
||||
needs to cross.
|
||||
- `internal/installtype/installtype.go` — precedent that deployment-shape
|
||||
facts are stated config, never runtime-probed.
|
||||
- AGENTS.md "Generated assets are LAW" (`ui/dist`, `task ui`); Yaegi
|
||||
`*extract` tables with post-generation guard tests
|
||||
(`internal/domain/workflow/wfextract/wfextract.go`) — precedent for
|
||||
committing generated code.
|
||||
- `Taskfile.yml` `check:` target vs. `.github/workflows/deploy.yml`
|
||||
"Quality gate" step — confirms CI does not invoke `task check` and so
|
||||
needs the proto gate mirrored in directly.
|
||||
- buf/grpc-go vs. connect-go comparison: connect-go's own README states it
|
||||
adds "no new name resolution or load balancing APIs" — the deciding fact
|
||||
against it, given the discovery research's reliance on grpc-go resolver
|
||||
plumbing.
|
||||
- Scratch toolchain verification (run inside a disposable worktree,
|
||||
discarded at teardown; not committed): `buf --version` → 1.71.0;
|
||||
`protoc --version` → libprotoc 34.0. `buf lint` on a sample
|
||||
`proto/gateway/v1/chat.proto` (package `gateway.v1`, service
|
||||
`ChatService`) passed once request/response types followed the
|
||||
`XRequest`/`XResponse` naming buf's STANDARD lint enforces. `buf
|
||||
generate` (v2, managed `go_package_prefix`, `paths=source_relative`)
|
||||
produced `chat.pb.go` (206 lines) and `chat_grpc.pb.go` (121 lines),
|
||||
which compiled cleanly against `google.golang.org/grpc v1.83.2` in a
|
||||
scratch module. `buf breaking --against
|
||||
'.git#branch=main,subdir=.'` after deleting an RPC and renaming a field
|
||||
correctly reported "Previously present RPC Send deleted," "field 2 user
|
||||
deleted," "field 3 changed name," exit 100 — confirming the mechanism
|
||||
works against a real git ref. A parallel connect-go run (installing
|
||||
`protoc-gen-connect-go` v1.19.1; note the `github.com/connectrpc/
|
||||
connect-go` module path is dead, use `connectrpc.com/connect`) generated
|
||||
a sibling `net/http`-based package, confirming the resolver-plumbing gap
|
||||
cited above. `gofumpt -l` on the freshly generated output was clean, so
|
||||
`task fmt`'s `gofumpt -w .` won't fight regenerated code.
|
||||
|
||||
---
|
||||
|
||||
## Question #4 — State Store's contract shape
|
||||
|
||||
### The question
|
||||
|
||||
Does every extracted service get its **own storage** (full microservice
|
||||
data isolation), or do **several services share one State Store service's
|
||||
contract** (less isolation, less migration risk, avoids a
|
||||
distributed-transactions problem)?
|
||||
|
||||
### Codebase evidence
|
||||
|
||||
- **`internal/store` is one SQLite DB** (`internal/store/store.go`,
|
||||
`Open()`, `sqliteDSN()`, WAL + busy_timeout pragmas) with 7 tables:
|
||||
`tasks`, `transitions` (workflow execution), `events` (observability),
|
||||
`captured_events`, `bindings`, `binding_dispatches` (work intake /
|
||||
binding), `field_mappings` (mapping). It is a single file used by many
|
||||
domains.
|
||||
- **The store is already interface-decomposed, not monolith-shaped.**
|
||||
`internal/store/interface.go` splits a broad `TaskStore` into narrow
|
||||
contracts: `TaskStore`, `WorkflowStore`, `CaptureStore`, `MappingStore`,
|
||||
`BindingStore`, `BindingDispatcher`, `BindingTaskCreator`. Each is
|
||||
deliberately narrow ("the interfacebloat limit").
|
||||
- **A store-as-contract-to-foreign-process pattern already exists and
|
||||
works.** `internal/storerpc/storerpc.go` exposes `store.WorkflowStore`
|
||||
(Update / Transition / InsertEvent) to the `archie-agent` container over
|
||||
NATS request/reply, and its doc comment states the design fact: "archied
|
||||
remains the sole owner of the `store.TaskStore`." This is the exact shape
|
||||
the State Store service needs; it just needs to be generalised from
|
||||
`WorkflowStore` to the full contract set and moved to the sync (gRPC)
|
||||
transport.
|
||||
- **The Gateway already owns a separate session SQLite.** As noted in Q1,
|
||||
`internal/gateway/session_store_sqlite.go` is its own DB with its own
|
||||
schema. So session/chat state is **already** isolated from task/work
|
||||
state — the natural two-owner split is already present in code.
|
||||
|
||||
### Does "every service its own storage" buy anything here?
|
||||
|
||||
The research (microservices.io, Microsoft Learn data-sovereignty, AWS
|
||||
Prescriptive Guidance) is emphatic that the database-per-service pattern is
|
||||
**about ownership and enforcement, not about physically provisioning one
|
||||
database cluster per service.** microservices.io names three ways to keep a
|
||||
service's data private — _private-tables-per-service_,
|
||||
_schema-per-service_, and _database-server-per-service_ — and says the
|
||||
first two have "the lowest overhead," and that a shared MySQL instance with
|
||||
per-service logical databases and per-service credentials is a legitimate
|
||||
instance of the pattern. Microsoft's guidance and the ownership-over-
|
||||
isolation posts (Progressive Robot, DEV's Aditya Pradhan, aakashx) make
|
||||
the same point with a shared framing: **shared write ownership is the real
|
||||
danger, not shared physical infrastructure.** aakashx's maturity ladder
|
||||
(Level 0 shared-DB+shared-tables → Level 3 service-owned DBs → Level 5
|
||||
independent lifecycle) is precisely the "ownership first, physical split
|
||||
only when justified" path.
|
||||
|
||||
The decisive variable everywhere is **team topology**, not technology.
|
||||
DevStarSJ's 2026 comparison gives the rule of thumb: 1–5 engineers →
|
||||
shared DB (monolith is fine); 5–20 → shared DB with strict ownership
|
||||
boundaries; 20–50 → hybrid; 50+ → database per service. The argument,
|
||||
across all sources, is that database-per-service's _benefits_ are team
|
||||
autonomy, independent deploy cadence, and failure blast-radius isolation —
|
||||
three things that are **largely absent for a solo maintainer**. You still
|
||||
pay the full "distributed data tax" (no cross-service joins → sagas or
|
||||
CDC/outbox + read models; eventual consistency; more data stores to
|
||||
operate and back up; a new class of ordering/duplicate events). For a
|
||||
single person shipping one product, that tax buys autonomy you do not
|
||||
have a team boundary to exploit.
|
||||
|
||||
### Decision: one State Store service, single SQLite, narrow contracts, no physical per-service database
|
||||
|
||||
**Recommendation:** archie-core keeps **one State Store service** that
|
||||
owns the existing single SQLite file and exposes its **narrow typed
|
||||
contracts** (`TaskStore`, `CaptureStore`, `MappingStore`, `BindingStore`,
|
||||
`WorkflowStore`, …) over gRPC. Consumers (UI, Workflow, Work Intake,
|
||||
Execution/Runner) call the State Store's contract; they never reach into
|
||||
each other's tables — and because there is **still one store**, there is
|
||||
**no distributed-transactions problem** (the very thing the question's
|
||||
"share one contract" alternative is trying to avoid). The Gateway keeps
|
||||
its own already-separate session SQLite (it is Gateway-private chat state
|
||||
and already isolated; moving it is churn).
|
||||
|
||||
This is "less isolation, less migration risk" chosen deliberately — it is
|
||||
the _honest_ choice for a solo maintainer per the team-topology rule of
|
||||
thumb, and it matches the store's existing interface decomposition (the
|
||||
ownership is already correct — the _enforcement_ is the gap: webui and
|
||||
workflow import `internal/store` directly across a would-be service
|
||||
boundary).
|
||||
|
||||
**Do NOT provision a physical database per service.** The only parts of
|
||||
the PRD's "every service its own storage" framing that buy anything at
|
||||
this scale are the ones that are already true in code: the Gateway owns
|
||||
its session DB, and the interface split gives each domain a narrow
|
||||
contract. Splitting the remaining SQLite file into per-service files
|
||||
would introduce the distributed-data tax — cross-store joins for the
|
||||
dashboard's combined task/event/capture views, sagas for intake→workflow
|
||||
transitions, m×n data-store operations — with no corresponding autonomy
|
||||
gain for a single maintainer. It is also the single most common source of
|
||||
a _distributed monolith_, which the sources call the failure mode to
|
||||
avoid.
|
||||
|
||||
### Concrete migration path from the current single SQLite store
|
||||
|
||||
1. **Ratify the contracts (cheap, already done).** Treat the narrow
|
||||
interfaces in `internal/store/interface.go` as the State Store
|
||||
contract surface. No code change; this is a naming/authority decision.
|
||||
2. **Generalise the store surrogate — this is the step that becomes the
|
||||
State Store service.** `internal/storerpc` currently proxies
|
||||
`WorkflowStore` to the agent over NATS. Broaden it to serve the full
|
||||
narrow contract set, and (per the PRD, gRPC is the sync transport) move
|
||||
it from NATS request/reply to gRPC. The `archie-agent` / `storerpc.Client`
|
||||
that satisfies `store.WorkflowStore` is the template for the client
|
||||
every consumer gets.
|
||||
3. **Swap consumers one contract at a time from direct import to the
|
||||
contract call.** Order by blast radius: start with the low-touch reads
|
||||
(`CaptureStore`, `MappingStore`, `BindingStore`) that a single UI
|
||||
screen uses, then `WorkflowStore` (already proxied), then the
|
||||
`TaskStore` lifecycle surface the daemon uses. Each swap leaves a
|
||||
working binary because the in-process `*store.Store` still backs the
|
||||
contract — this is a pure interface-boundary change, not a data move.
|
||||
4. **Stand up the State Store process.** Once every consumer speaks the
|
||||
contract, run `internal/store` as `archie-state-store` (a gRPC server
|
||||
over the same SQLite file), and delete the in-process imports. The
|
||||
single `archie.db` file is unchanged; only the access path changes.
|
||||
5. **Only split the file if a concrete need appears.** If task-history
|
||||
volume or a specific isolation/security requirement (e.g. a hosted
|
||||
multi-tenant boundary) later justifies it, SQLite makes a per-domain
|
||||
physical split cheap (one file per contract group, e.g.
|
||||
`archie-tasks.db`, `archie-intake.db`). But do **not** pre-split: the
|
||||
sources' consensus is to migrate toward physical separation "only when
|
||||
there is evidence (slow queries, deployment coupling, scaling
|
||||
bottlenecks)."
|
||||
|
||||
### What this doesn't settle
|
||||
|
||||
- **Cross-store reads for reporting.** The dashboard's combined
|
||||
task/event/capture/mapping views are built in one SQLite today. If
|
||||
those are split later, they need an API-composition / read-model path
|
||||
(the sources name CQRS / materialised view). Not a blocker now; it is
|
||||
the cost of a future physical split, which is exactly why the
|
||||
recommendation is to not pre-split.
|
||||
- **Whether the Gateway's session store stays Gateway-owned or moves to
|
||||
State Store.** Decided: stays Gateway-owned (already isolated, high
|
||||
-frequency chat state; moving it has no benefit).
|
||||
- **The exact gRPC contract schema / versioning.** That is #2's
|
||||
mechanism. The contract _surface_ is decided here; the wire schema is
|
||||
not.
|
||||
- **Migration of the `storerpc` NATS path.** The `archie-agent` container
|
||||
still calls `storerpc` today. Under the PRD the Execution/Runner
|
||||
processes are peers too, so the agent's store access should eventually
|
||||
use the same contract. When that moves is an Execution-track question,
|
||||
not a State-Store-shape one.
|
||||
|
||||
---
|
||||
|
||||
## Question #5 — Helm chart / Operator scoping
|
||||
|
||||
### The question
|
||||
|
||||
`service-discovery-research-2026-09-05.md` already commits to
|
||||
Kubernetes-native discovery via a Helm chart + Operator as the primary
|
||||
path. Scope what that actually requires as a first real deliverable: what
|
||||
a first Helm chart for the ~7-service fleet needs to contain, what the
|
||||
Curator Operator's reconciliation loop needs to do, and the smallest real
|
||||
first milestone that proves "install Curator, Gateway discovers it" end
|
||||
to end.
|
||||
|
||||
### What the base Kubernetes discovery needs (from the discovery research)
|
||||
|
||||
The discovery research's Path A (K8s-native) flow is the contract our
|
||||
deliverable has to satisfy: base services deploy as Deployment + Service;
|
||||
a Service's label selector matches the Curator pods; the endpoint
|
||||
controller writes pod IPs into an EndpointSlice; readiness probes gate
|
||||
which pods are ready; CoreDNS serves `curator.<ns>.svc.cluster.local`; the
|
||||
Gateway's gRPC DNS resolver picks up the new endpoint on re-resolution
|
||||
with no redeploy; removal empties the EndpointSlice and the record
|
||||
disappears. Two facts shape the chart design:
|
||||
|
||||
1. **Optional service semantics.** A scaled-to-zero / not-yet-created
|
||||
Curator must resolve to `NotInstalled`, not `Down`. Under K8s that
|
||||
comes from DNS `NXDOMAIN`/empty resolution being treated as "absent,"
|
||||
which requires the Gateway to model "absent" as a distinct resolution
|
||||
outcome on the `ServiceRegistry` interface (already flagged in the
|
||||
research's addendum).
|
||||
2. **Chart count.** Seven services is too many for one monolithic
|
||||
template and too few to justify seven charts. The idiomatic Helm
|
||||
answer is a **library chart** for the shared contract templates plus
|
||||
small per-deployable charts.
|
||||
|
||||
### Decision: three charts (library + core services + Curator-with-Operator)
|
||||
|
||||
- **`archie-library`** — a Helm **library chart** (`type: library`,
|
||||
only `_*.tpl` files). Holds the shared resource templates: the
|
||||
Deployment template, the Service template, readiness/liveness probe
|
||||
helper, container-port naming, the label/selector block
|
||||
(`app.kubernetes.io/name`, `instance`, `managed-by`, `component`), and
|
||||
the `ServiceRegistry`-relevant named ports (`grpc`, `http`, `ssr`,
|
||||
`nats`). This keeps the per-service charts declarative and consistent.
|
||||
- **`archie`** — the chart for the **7 core services**: UI, Gateway,
|
||||
Messaging, Scheduler, Execution Environment, Runner, State Store. One
|
||||
`values.yaml` with a `services:` map; each service resolves to a small
|
||||
template from the library chart. It also lands the base **ConfigMaps
|
||||
/ Secrets** that replace `config.toml` (a phased concern flagged in the
|
||||
discovery research — the chart should _reference_ config as a separate
|
||||
concern, not block on relocating it). It must make each service's
|
||||
`Service` a **named-port** Service so gRPC resolution works, and each
|
||||
a **ClusterIP** Service (no headless needed for the base sync path; a
|
||||
headless/SRV Service is an optional addition the Gateway resolver can
|
||||
consume but is not required for the DNS A-record flow).
|
||||
- **`archie-curator`** — the chart for the **optional Curator**, plus the
|
||||
**Curator Operator**. Operator chart installs the CRD, the
|
||||
controller Deployment (with the ServiceAccount / ClusterRole /
|
||||
ClusterRoleBinding the reconciler needs), and the RBAC markers; the
|
||||
Curator chart installs the sample `Curator` CR. Because Curator is
|
||||
optional, this chart is **not** deployed by default with `archie` — the
|
||||
whole point is that a customer installs it later and the fleet
|
||||
auto-aligns.
|
||||
|
||||
### What the Curator Operator's reconcile loop actually needs to do
|
||||
|
||||
This is a textbook Kubebuilder / Operator-SDK controller. The reconcile
|
||||
loop (per the Kubebuilder book and the multi-resource reconciliation
|
||||
pattern) is **level-triggered, not status-triggered**: it must always
|
||||
converge the _whole_ desired set, never react to a specific event. Per
|
||||
`Curator` CR, the loop:
|
||||
|
||||
1. **Fetch the CR.** `r.Get(ctx, req.NamespacedName, &curator)`; treat
|
||||
`IsNotFound` as a normal "already deleted" outcome (owner references
|
||||
cascade child cleanup), not an error.
|
||||
2. **Build the desired children.** Pure builder functions
|
||||
(`deploymentForCurator`, `serviceForCurator`) produce the Deployment
|
||||
(image, replicas, container port, readiness/liveness probes,
|
||||
`app.kubernetes.io/{name,instance,managed-by,component}` labels, env
|
||||
from a ConfigMap/Secret generated in the same pass) and the Service
|
||||
(label-selector matching the Deployment pods, the gRPC named port).
|
||||
3. **Set owner references** with `controllerutil.SetControllerReference`
|
||||
so deleting the `Curator` CR cascades to its Deployment + Service.
|
||||
4. **Apply idempotently** with `controllerutil.CreateOrUpdate` (or
|
||||
Server-Side Apply) — create if absent, patch toward desired if
|
||||
drifted; a manual `kubectl edit` on the Deployment is corrected on the
|
||||
next reconcile.
|
||||
5. **Watch the children** via `Owns(&appsv1.Deployment{})` and
|
||||
`Owns(&corev1.Service{})` in `SetupWithManager`, so a pod crash or an
|
||||
out-of-band edit enqueues a reconcile of the owning Curator CR. Without
|
||||
`Owns()`, drift correction does not fire.
|
||||
6. **Report status** on the status subresource (the
|
||||
`+kubebuilder:object:root`/`subresource:status` marker): set a `Ready`
|
||||
condition (via `meta.SetStatusCondition` with `ObservedGeneration`,
|
||||
and never hand-set `LastTransitionTime`), reflecting the worst child's
|
||||
readiness, and update only when `Status` changed. This is what the
|
||||
Gateway (or an operator/`kubectl wait --for=condition=Ready`) observes.
|
||||
7. **RBAC** via Kubebuilder markers: full verbs on `curators` and
|
||||
`curators/status`, plus `get;list;watch;create;update;patch;delete` on
|
||||
`deployments` and `services`.
|
||||
|
||||
The reconciler stays a flat, dependency-ordered sequence (Deployment
|
||||
before Service is not strictly required here, but the pattern is
|
||||
dependency-first and idempotent-across-orders).
|
||||
|
||||
### The smallest real first milestone ("install Curator → Gateway discovers it")
|
||||
|
||||
Keep the first milestone as small as possible while proving the whole
|
||||
flow through the `ServiceRegistry` — this is the "warm up on an optional
|
||||
thing with a clean seam" exercise (and it is exactly what the discovery
|
||||
research calls the product story). Concretely:
|
||||
|
||||
**Milestone M1 — "Curator installs and Gateway resolves it, no redeploy."**
|
||||
|
||||
- **CRD + Operator:** a `Curator` CRD and a controller that reconciles
|
||||
one Curator CR into one Deployment + one Service with owner references
|
||||
and a `Ready` status condition. (This is the whole operator; it is two
|
||||
files at its core — the API type and the reconciler.)
|
||||
- **Base chart:** `helm install archie` deploys Gateway + one
|
||||
representative base service (start with Gateway + State Store + UI)
|
||||
behind the `ServiceRegistry`, with Gateway holding a resolver that
|
||||
already knows `curator`.
|
||||
- **Curator chart:** `helm install archie-curator` (or `kubectl apply -f`
|
||||
a `Curator` CR) → the Operator creates the Deployment + `curator`
|
||||
Service → the endpoint controller writes the pod IP into the
|
||||
EndpointSlice → CoreDNS serves `curator` → the Gateway's resolver picks
|
||||
it up on re-resolution.
|
||||
- **Assertion (the real "prove it"):** the Gateway logs / health shows
|
||||
`curator` flipping from `NotInstalled` to `Installed(Requesting)`
|
||||
(ready), and a Gateway-config or Gateway-restart is **not** required. Then
|
||||
`helm uninstall archie-curator` (or delete the CR) → EndpointSlice
|
||||
empties → DNS record goes away → Gateway drops `curator` back to
|
||||
`NotInstalled`. No Gateway redeploy, no code change.
|
||||
|
||||
This milestone deliberately does **not** include: config relocation from
|
||||
`config.toml` to ConfigMaps/Secrets (a separate phased concern), the
|
||||
NATS-fallback `ServiceRegistry` implementation (can be stubbed with a
|
||||
static map for the assertion), auth/mTLS/NetworkPolicy, or the full 7
|
||||
services. It proves the one hard requirement — "install a service, the
|
||||
fleet auto-aligns, no redeploy" — and the optional-service `NotInstalled`
|
||||
semantic, with the smallest surface.
|
||||
|
||||
**What beads-epic + first issues would look like** (filing this directly
|
||||
from here, as the task asks):
|
||||
|
||||
- Epic: `archie-core-k8s` (or the codename already in use) — "K8s-native
|
||||
service discovery: base Helm chart + Curator Operator proving the
|
||||
install→discover flow."
|
||||
- Issue 1: Scaffold the Kubebuilder project and the `Curator` API
|
||||
(`group: archie.samcharles93.io`, `v1alpha1`), CRD, RBAC markers.
|
||||
- Issue 2: Implement the `Curator` reconciler (create/update/delete
|
||||
Deployment + Service, owner refs, `Ready` status condition).
|
||||
- Issue 3: Create `archie-library` chart with the shared Deployment /
|
||||
Service templates and named-ports.
|
||||
- Issue 4: Create `archie` chart deploying Gateway + State Store + UI
|
||||
with per-service `ServiceRegistry`-friendly Services.
|
||||
- Issue 5: Wire the Gateway's `ServiceRegistry` K8s implementation
|
||||
(DNS resolver) to model `NotInstalled` distinctly from `Down/Unhealthy`
|
||||
(the research's addendum requirement).
|
||||
- Issue 6: End-to-end M1 assertion (install Curator CR → Gateway resolves
|
||||
it → uninstall → Gateway drops it), likely as an envtest / kind test.
|
||||
|
||||
### Sources used for Q5
|
||||
|
||||
- Kubebuilder Book — [Getting Started](https://www.kubebuilder.io/getting-started.html),
|
||||
[Resources Managed by the Operator](https://book-v3.book.kubebuilder.io/reference/watching-resources/operator-managed),
|
||||
[Owned Resources](https://kubebuilder.io/reference/watching-resources/secondary-owned-resources)
|
||||
(for the reconcile loop, `Owns()`, owner references, status subresource,
|
||||
RBAC markers).
|
||||
- DEV Community — [Building Your First Kubernetes Operator with
|
||||
Kubebuilder](https://dev.to/tim_derzhavets/building-your-first-kubernetes-operator-with-kubebuilder-from-zero-to-production-4ipm)
|
||||
and [GoLinuxCloud — Kubernetes Operator Multi-Resource Reconciliation
|
||||
Patterns](https://www.golinuxcloud.com/multi-resource-reconciliation/)
|
||||
(level-triggered reconcile, idempotent `CreateOrUpdate`, dependency
|
||||
order, per-child status aggregation).
|
||||
- Helm — [Charts](https://helm.sh/docs/topics/charts/) (the chart file
|
||||
structure; `Chart.yaml`; template dirs; the library-chart use of
|
||||
`_*.tpl` and `type: library`).
|
||||
|
||||
### What this doesn't settle
|
||||
|
||||
- **Config relocation.** The charts reference ConfigMaps/Secrets but the
|
||||
actual move of `config.toml` semantics into them is its own
|
||||
phased decision (flagged in the discovery research) and is out of scope
|
||||
for the first milestone. The base chart should degrade gracefully with
|
||||
an in-cluster config so M1 works before the relocation is done.
|
||||
- **The NATS-fallback `ServiceRegistry` implementation.** M1 uses a K8s
|
||||
DNS resolver; the NATS KV implementation is a later, separate issue.
|
||||
- **Auth / mTLS / NetworkPolicy / cert-manager.** Called out as a
|
||||
separate concern in the discovery research; not in the first milestone.
|
||||
- **Operator SDK vs raw Kubebuilder/controller-runtime.** The loop is
|
||||
identical; the choice of kubebuilder scaffolding vs. Operator SDK is a
|
||||
tooling preference that does not change the M1 scope. Kubebuilder is the
|
||||
documented norm and is assumed here.
|
||||
- **Whether the Operator should manage the _base_ services too.** The
|
||||
first milestone only has an Operator for Curator (the optional one).
|
||||
A "fleet Operator" that reconciles all services is a larger, later
|
||||
idea; the base services can be plain chart templates for now.
|
||||
|
||||
---
|
||||
|
||||
## Sources (primary, fetched during this pass)
|
||||
|
||||
- Zhamak Dehghani, _How to break a Monolith into Microservices_ (Martin
|
||||
Fowler site) — https://martinfowler.com/articles/break-monolith-into-microservices.html
|
||||
- microservices.io, _Pattern: Database per service_ —
|
||||
https://microservices.io/patterns/data/database-per-service.html
|
||||
- Microsoft Learn, _.NET microservices: Data sovereignty per microservice_ —
|
||||
https://learn.microsoft.com/en-us/dotnet/architecture/microservices/architect-microservice-container-applications/data-sovereignty-per-microservice
|
||||
- Kubebuilder Book, _Getting Started_ —
|
||||
https://www.kubebuilder.io/getting-started.html
|
||||
- Kubebuilder Book, _Resources Managed by the Operator_ —
|
||||
https://book-v3.book.kubebuilder.io/reference/watching-resources/operator-managed
|
||||
- Kubebuilder Book, _Owned Resources_ —
|
||||
https://kubebuilder.io/reference/watching-resources/secondary-owned-resources
|
||||
- Helm, _Charts_ — https://helm.sh/docs/topics/charts/
|
||||
- (Supporting synthesis from the deep-search lanes: YuSMP strangler-fig
|
||||
guide, Md Sanwar Hossain strangler-fig, CloudRPS strangler-fig,
|
||||
Mobisoft first-microservice-to-extract, StackAuthority
|
||||
monolith-to-services blueprint, DevStarSJ database-per-service-vs-shared
|
||||
2026, Progressive Robot / DEV Aditya Pradhan database-per-service
|
||||
ownership-not-isolation, aakashx database ownership in microservices,
|
||||
AWS Prescriptive Guidance data persistence, DEV Tim Derzhavets building
|
||||
a Kubebuilder operator, GoLinuxCloud operator SDK tutorial and
|
||||
multi-resource reconciliation, Codelooru how to write a Kubernetes
|
||||
operator. These consulted sources corroborate the primary texts; the
|
||||
primary texts are cited for the load-bearing claims.)
|
||||
|
||||
Code evidence cited throughout is the archie-core tree at the time of
|
||||
writing (see the file list at the top of this document).
|
||||
@@ -1,291 +0,0 @@
|
||||
# Service discovery research for the archie-core service decomposition
|
||||
|
||||
Status: exploratory research, not a settled decision. This backs the "ideal
|
||||
state" service-oriented sketch in
|
||||
[[module-reference-awx-decomposition-vs-archie]] and its two Archify diagrams
|
||||
(`/work/artefacts/archie-core-current-state-archify.html`,
|
||||
`/work/artefacts/archie-core-ideal-state-archify.html`). Nothing here commits
|
||||
the codebase to anything; if the service decomposition itself gets approved,
|
||||
this is the input to the actual `docs/architecture/migration-decisions.md` entry
|
||||
and/or a `docs/prds/` design doc, not a substitute for either.
|
||||
|
||||
Produced by an external research pass (Pi subagents plus supervisor-run
|
||||
`deep_search_exa` queries against primary sources: NATS discovery, K8s-native
|
||||
discovery, Consul operational footprint, gRPC/xDS/mesh weight). The K8s lane
|
||||
detached mid-flight and was recovered via supervisor reply, covered from fetched
|
||||
Kubernetes docs (Service/EndpointSlice/CoreDNS/Operator + k3s Helm). Reproduced
|
||||
here close to verbatim as the record of that research; light formatting only.
|
||||
|
||||
Business framing this research was scoped against, per Sam (2026-09-05): the
|
||||
decomposition is being evaluated as a real product distribution strategy —
|
||||
possibly sold self-hosted, possibly as a managed/hosted offering (the
|
||||
RHEL/Ansible Automation Platform model: same product, sold both ways), not ruled
|
||||
to either shape. Evaluate infrastructure choices on technical merit for that
|
||||
audience, not through the lens of Sam's own homelab deployment preferences (see
|
||||
`feedback_dont_project_homelab_prefs_onto_product` in Claude's project memory).
|
||||
"Cost" in this document means operational complexity, never dollar price —
|
||||
pricing and SaaS-plan questions are explicitly out of scope here.
|
||||
|
||||
---
|
||||
|
||||
## 1. Candidate mechanisms
|
||||
|
||||
| # | Mechanism | Who stands it up | Health-aware endpoints? | "Install → auto-join" mechanics | Single-host fit | Multi-host fit |
|
||||
| --- | -------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 1 | **Kubernetes-native** (Service + EndpointSlice + CoreDNS), delivered via Helm chart + Operator, on k3s (single-node) or a real cluster | A whole (even if small) control plane: api-server, etcd, scheduler, controller-manager, CoreDNS, kube-proxy. k3s packages this into a ~one-command install | Yes, free — readiness probes gate which pods land in an EndpointSlice | Deploy/helm install a Service (or an Operator reconciles a CR) → CoreDNS serves the name → existing services dial it | Strong (k3s is ~½ GB RAM) | Good (real cluster, or k3s server+agents) |
|
||||
| 2 | **NATS-based discovery** (micro `$SRV` announce + JetStream KV registry) | NATS broker — already a hard dependency, so nothing new to stand up | No — only connection liveness; you write heartbeat+TTL for KV | Service connects to the bus on start, publishes/announces → peers observe the join | Excellent | Workable but requires a real NATS cluster / leaf nodes (TLS/NKey/JWT weight) |
|
||||
| 3 | **Consul** (registry + agent + DNS) | A second control plane: 3–5 Raft servers + a client agent on every node | Yes (TCP/HTTP/gRPC/TTL) | Agent registers with server; peers resolve via Consul DNS | OK (one server + agents) | Good (multi-DC, WAN federation) but per-node agent burden |
|
||||
| 4 | **etcd** (discovery substrate) | A Raft KV cluster you operate | Not natively — you own catalogue/health semantics | Lease registration + prefix watch | OK (embeddable) | Good (R3 replication) but you build the semantics |
|
||||
| 5 | **gRPC xDS / service mesh** (Istio/Linkerd/Traffic Director, proxyless gRPC) | A control plane (+ per-pod sidecar if mesh) | Yes (xDS health) | Register with control plane → EDS pushed to subscribed clients | Heavy / overkill | Heavy; K8s-first; sidecar cost (~0.2 vCPU + 60 MB/pod @1k rps in Istio-sidecar-land) |
|
||||
| 6 | **DNS-SRV / mDNS** | Nothing new | No native health; TTL caching breaks fast failover | Register a record | mDNS yes (but link-local); DNS-SRV needs a resolver you control | mDNS fails at the first router/VLAN; DNS-SRV needs your own resolver + a custom gRPC resolver (grpc-go doesn't consume SRV natively) |
|
||||
|
||||
## 2. What this narrows to
|
||||
|
||||
Six candidates surfaced, but the field collapses to two real finalists once
|
||||
three filters specific to archie-core apply: (a) the fleet is ~7 Go services,
|
||||
(b) a gRPC-sync + NATS-async mix is already the working assumption, and (c) the
|
||||
defining requirement is "customer installs a service, the fleet auto-aligns, no
|
||||
redeploy/reconfig."
|
||||
|
||||
- **Consul / etcd are dominated by K8s-native.** Consul adds a whole second
|
||||
control plane (Raft server quorum + a client agent on every node you don't
|
||||
control) — redundant if the fleet lives in K8s (buying a second control plane
|
||||
to replace one you already have), heavy if it doesn't. etcd makes you own
|
||||
catalogue + health semantics, which is exactly what K8s-native and NATS each
|
||||
give for free in different ways. Both remain viable, just not better.
|
||||
- **gRPC xDS / service mesh is the wrong tool at this scale.** Field consensus
|
||||
(multiple 2026 sources): don't adopt a mesh until 20+ services; archie-core is
|
||||
at ~7, single-language (Go), with resilience logic already in Go.
|
||||
xDS/proxyless-gRPC earns its keep only with locality-aware routing / canary /
|
||||
circuit-breaking across hosts, which nothing here signals. The durable
|
||||
takeaway isn't "use xDS"; it's that gRPC is resolver plumbing, not a registry
|
||||
— whatever registry gets picked feeds gRPC through a resolver (DNS resolver,
|
||||
or a custom one).
|
||||
- **DNS-SRV / mDNS are insufficient.** mDNS is link-local (dies at
|
||||
router/VLAN/container boundaries), so it can't span routed multi-host; DNS-SRV
|
||||
has no health and grpc-go's default resolver doesn't consume SRV natively
|
||||
anyway.
|
||||
|
||||
So the genuine decision is K8s-native vs. reuse-NATS.
|
||||
|
||||
## 3. K8s-native vs. NATS: an honest weigh
|
||||
|
||||
**Where K8s-native wins decisively:**
|
||||
|
||||
- The only mechanism that delivers "install a service → the fleet auto-aligns"
|
||||
at the infrastructure layer, with health-filtered endpoints, where the
|
||||
customer's install is a straightforward "apply a Deployment + Service" (or a
|
||||
Helm chart, or an Operator reconciling a CR). This is the single hardest, most
|
||||
product-defining requirement, and K8s solves it natively.
|
||||
- Delivers, as a side effect, almost everything a 7-service fleet needs anyway:
|
||||
health (readiness/liveness probes), orchestration (restart/scale), config
|
||||
(ConfigMaps/Secrets), rollouts, clean external exposure (Ingress/Gateway). Not
|
||||
extra weight for its own sake — buying pieces that would otherwise be
|
||||
hand-built.
|
||||
- The hosted/managed path is free. If the product is ever run for customers (the
|
||||
"sold both ways" shape kept open above), K8s runs anyway. K8s-native discovery
|
||||
makes self-hosted and hosted deployments use identical discovery semantics —
|
||||
one codebase, no divergence. This is the RHEL/Ansible Automation Platform
|
||||
lesson: same product, sold both ways, same internal architecture.
|
||||
|
||||
**Where NATS wins:**
|
||||
|
||||
- Zero new infrastructure. NATS is already a hard dependency and already in the
|
||||
deployment (embedded, or the existing `docker-nats-stack.toml`). For the
|
||||
lowest-end single-host customer who wants "one binary dropped on a box," NATS
|
||||
discovery means no cluster, no K8s — just the bus already running.
|
||||
- Genuinely idiomatic: a service connects, announces via the micro `$SRV` tree
|
||||
(PING/INFO/STATS) or a JetStream KV record, and disappears the moment its
|
||||
connection closes. Re-join = "open the connection and publish." No per-service
|
||||
config, no sidecar, no hand registration.
|
||||
|
||||
**Where NATS genuinely falls short for this product:**
|
||||
|
||||
1. It's a NATS service locator, not a gRPC endpoint registry. The `$SRV`
|
||||
framework and the KV bucket hand you names/responders, not `host:port` gRPC
|
||||
endpoints. Each service's `host:port` has to be carried in metadata/KV and a
|
||||
custom gRPC resolver hand-written; gRPC's built-in resolver/health model
|
||||
won't "just work." Real integration work owned in the sync path — now the
|
||||
product's primary contract.
|
||||
2. No native health. NATS has no last-will or probe. Heartbeat+TTL (KV) must be
|
||||
implemented to distinguish "installed but unhealthy" from "not installed,"
|
||||
and stale entries are your problem. K8s readiness probes do this for free.
|
||||
3. Discovery is coupled to broker availability. If NATS is down, every service
|
||||
looks down (a hard SPOF unless NATS is itself clustered). Multi-host is where
|
||||
the cost shows: a real NATS cluster or leaf nodes, with TLS/NKey/JWT
|
||||
credential management — operator weight, not "just works."
|
||||
|
||||
The balance: NATS is a legitimate fallback and a genuine part of the answer; it
|
||||
is not a substitute for the registry that resolves gRPC endpoints with health.
|
||||
If the product's sync path is gRPC, the registry serving it should be K8s-native
|
||||
(DNS → resolver, headless-Service SRV for ports, EndpointSlice health) rather
|
||||
than a hand-built NATS registry.
|
||||
|
||||
## 4. Recommendation
|
||||
|
||||
**Primary:** Kubernetes-native service discovery (Service +
|
||||
headless-Service/DNS + EndpointSlice, served by CoreDNS), delivered as a Helm
|
||||
chart + Operator, on k3s for single-host customers and a real cluster for
|
||||
multi-host / hosted.
|
||||
|
||||
**Fallback:** NATS-based discovery (micro `$SRV` announce + JetStream KV
|
||||
registry) for no-K8s single-host installs, using a custom gRPC resolver that
|
||||
reads `host:port` from the KV bucket.
|
||||
|
||||
**Rationale, short version:**
|
||||
|
||||
- K8s-native is the only candidate that solves the hardest requirement —
|
||||
"install a service and the rest of the system joins in to align" — at the
|
||||
infrastructure layer with health-filtered endpoints and a
|
||||
customer-comprehensible install. Not extra weight for its own sake; it
|
||||
replaces a stack of pieces a 7-service product needs anyway, and makes the
|
||||
multi-host + hosted paths free from one codebase.
|
||||
- k3s packages the control plane into a ~one-command install a customer can
|
||||
stand up, and the Operator/Helm/CRD pattern is exactly the "install Curator,
|
||||
Gateway picks it up" product story.
|
||||
- NATS is not discarded — it stays in the fleet for async fan-out, and becomes
|
||||
the second discovery implementation so the smallest no-K8s customer keeps "one
|
||||
binary on a box." The fallback is the honest acknowledgment that a full K8s
|
||||
cluster is genuinely heavy for the very smallest single-node customer.
|
||||
|
||||
Why not NATS-only: it's a service locator needing hand-built gRPC endpoint
|
||||
resolution + health, and it couples discovery to broker availability. Why not
|
||||
Consul/etcd: a redundant second control plane (if K8s) or "you own the
|
||||
semantics" (etcd), with per-node agents. Why not a mesh: overkill at ~7 Go
|
||||
services; consensus is 20+.
|
||||
|
||||
### The seam that keeps both shapes on one codebase
|
||||
|
||||
The Gateway (and any service that routes to peers) should talk to discovery
|
||||
through one internal interface —
|
||||
|
||||
```go
|
||||
type ServiceRegistry interface {
|
||||
Resolve(service string) []Endpoint
|
||||
Watch(service string) <-chan Event // join/leave
|
||||
}
|
||||
```
|
||||
|
||||
— with two implementations: a K8s one (DNS / EndpointSlice / custom resolver)
|
||||
and a NATS one (KV / `$SRV`). The rest of the code is registry-agnostic. This is
|
||||
what makes "K8s-native primary, NATS fallback" a coherent architecture rather
|
||||
than a fork: business logic doesn't change, only the registry injection point
|
||||
does.
|
||||
|
||||
## 5. End-to-end: "install Curator, Gateway discovers it"
|
||||
|
||||
**Path A — K8s-native (primary):**
|
||||
|
||||
1. Customer installs the product (`helm install archie`, or pre-provisioned on
|
||||
k3s). Base services (Gateway, UI, Messaging, Scheduler, Execution, State
|
||||
Store) each deploy as a Deployment + Service; Gateway is always up and
|
||||
already holds a resolver for every known service name.
|
||||
2. Customer installs Curator: `helm install archie-curator`, or the Operator
|
||||
watches a `Curator` Custom Resource and reconciles it — creating a Deployment
|
||||
(pods) + a `curator` Service.
|
||||
3. The Service's label selector matches the Curator pods; the endpoint
|
||||
controller writes their IPs into an EndpointSlice. Readiness probes gate
|
||||
which pods are "ready" (a Curator that only registers once healthy won't
|
||||
receive traffic).
|
||||
4. CoreDNS immediately serves `curator.<ns>.svc.cluster.local` (A record; a
|
||||
headless Service additionally gives an SRV record with the port).
|
||||
5. The Gateway resolves `curator.<ns>.svc.cluster.local` through its gRPC DNS
|
||||
resolver (or a K8s-aware resolver). On the next re-resolution/update it picks
|
||||
up the new endpoint. No Gateway redeploy, no Gateway config change — and
|
||||
because it's DNS, the Gateway code doesn't even need to know it's running
|
||||
under K8s.
|
||||
6. Removal: `helm uninstall archie-curator` (or scale to 0 / delete the CR) →
|
||||
EndpointSlice empties → DNS record disappears → Gateway's resolver drops it.
|
||||
Clean.
|
||||
|
||||
**Path B — NATS fallback (single-host, no K8s):**
|
||||
|
||||
1. One NATS (embedded, or external via the existing compose stack) is the shared
|
||||
bus; its URL is part of the base install.
|
||||
2. Every service, on start, connects to that URL and either (a) registers via
|
||||
the micro framework (`AddService("curator", "1.0.0", …)`), appearing on the
|
||||
`$SRV` tree, or (b) writes its `host:port` + version into a JetStream KV
|
||||
bucket (`archie/registry/curator/<id>`) and heartbeats it with a TTL.
|
||||
3. The Gateway holds a live roster (from `$SRV.INFO` or a KV watch) and feeds it
|
||||
into a custom gRPC resolver mapping service-name → `host:port`.
|
||||
4. Customer starts one Curator binary (`archie-curator`, or `docker run` the
|
||||
image) with the same NATS URL in its config. It connects, announces, and
|
||||
heartbeats. The Gateway's roster observes the new entry (within one
|
||||
announce/heartbeat window) and starts routing to it. No Gateway restart, no
|
||||
config change beyond the shared NATS URL already present in the base install.
|
||||
5. Removal: stop Curator → its connection closes → it leaves `$SRV` immediately
|
||||
and its KV record expires via TTL. The Gateway routes that capability to "not
|
||||
installed."
|
||||
|
||||
## 6. Failure-mode honesty
|
||||
|
||||
- **K8s-native:** pod death → readiness fails → dropped from EndpointSlice
|
||||
within seconds, so the gateway stops routing to it (health-aware). DNS TTL
|
||||
caching is mostly harmless because a Service's ClusterIP is stable and all
|
||||
churn lives behind it in the EndpointSlice. If the control plane goes down,
|
||||
already-running pods keep serving and DNS still resolves from cache; only new
|
||||
scheduling/propagation halts. Known gap: cross-cluster and off-cluster
|
||||
consumers (client-side resolvers, a worker fleet on VMs) need ExternalDNS or a
|
||||
bridge. mTLS/auth, if needed, is a separate concern (NetworkPolicy /
|
||||
cert-manager), not the mesh.
|
||||
- **NATS fallback:** service dies → dropped from `$SRV` immediately, KV record
|
||||
lingers until heartbeat-TTL (bounded staleness). Broker unreachable → every
|
||||
service appears down (hard SPOF unless NATS is clustered). Plain subjects
|
||||
aren't a consensus store (split-brain across partitions possible); JetStream
|
||||
KV gives Raft per stream but KV placement across hosts needs its own
|
||||
decisions. Health semantics must be built by hand.
|
||||
|
||||
Both paths are robust against "a service dies"; the difference is who does the
|
||||
health checking — K8s readiness probes do it for free, NATS makes you build it.
|
||||
|
||||
## 7. Addendum — recovered K8s lane, optional-service semantics
|
||||
|
||||
A separately recovered K8s-focused research lane landed independently on the
|
||||
same verdict (K8s-native as the canonical, declarative, self-healing
|
||||
fleet-discovery answer; fits multi-host and the AAP-style "sold both ways" model
|
||||
best) and confirmed the same install → Operator → CoreDNS → resolver flow above.
|
||||
It sharpened one point specific to archie-core's shape:
|
||||
|
||||
**The optional, intermittently-running Curator needs explicit "absent" semantics
|
||||
under K8s.** A scaled-to-zero or not-yet-created Curator has no ready endpoint
|
||||
and no DNS record — the Gateway's gRPC `dns://` resolver gets `NXDOMAIN`/empty
|
||||
resolution, and this must be treated as "Curator is disabled," not "Curator is
|
||||
broken." Concretely:
|
||||
|
||||
- Lazy, on-demand re-resolution — don't pin a dead subchannel as a hard failure.
|
||||
- A distinct `NotInstalled` vs. `Down`/`Unhealthy` state for routing — the same
|
||||
distinction the NATS path needs a KV "installed" marker to express. Under K8s,
|
||||
health comes free (readiness gates the EndpointSlice), but the _presence_ of
|
||||
an optional service still has to be modelled as a resolution outcome, not a
|
||||
failure.
|
||||
|
||||
This is a new implementation requirement on both paths (`ServiceRegistry`'s
|
||||
`Resolve`/`Watch` contract needs a way to express "absent" distinctly from
|
||||
"unhealthy"), not a change to the primary/fallback recommendation.
|
||||
|
||||
Two secondary observations from that lane, noted but not verdict-changing:
|
||||
|
||||
- **Two discovery systems, not one.** Under K8s, sync gRPC is served by cluster
|
||||
DNS/EndpointSlice, while async NATS status/telemetry is served by NATS's own
|
||||
clustering. These should not be conflated — this is exactly why the
|
||||
`ServiceRegistry` seam matters: it isolates the sync path and keeps NATS
|
||||
purely for async fan-out, as already planned.
|
||||
- **Config relocation.** Moving install/run/upgrade from `config.toml` into
|
||||
ConfigMaps/Secrets is a real change to how archie-core is deployed, worth a
|
||||
deliberate PRD/settled-design before committing — a phased concern, not a
|
||||
blocker for the discovery decision.
|
||||
|
||||
## Bottom line
|
||||
|
||||
Treat Kubernetes-native discovery (Helm chart + Operator on k3s / a real
|
||||
cluster) as primary, and reuse NATS as the built-in fallback so single-host
|
||||
no-K8s customers still get "install and auto-join." This is the only ordering
|
||||
that satisfies the hardest requirement at the infrastructure layer, keeps the
|
||||
hosted path free from one codebase, and doesn't force the smallest customer into
|
||||
a full cluster. The two implementations live behind one `ServiceRegistry`
|
||||
interface, so neither is a fork. The one added implementation requirement is the
|
||||
optional-service "absent ≠ down" resolution model on both paths.
|
||||
|
||||
Full recovered K8s-lane transcript, for the record: session path
|
||||
`.../cf1825c4-0c08-4aaa-9ea1-aac40893825f/run-0/session.jsonl` (external to this
|
||||
repository; not reproduced here).
|
||||
@@ -53,6 +53,14 @@
|
||||
"/news/archie/1.4.1/": "/news/1.4.1/",
|
||||
"/news/archie/1.40.0/": "/news/1.40.0/",
|
||||
"/news/archie/1.41.0/": "/news/1.41.0/",
|
||||
"/news/archie/1.41.1/": "/news/1.41.1/",
|
||||
"/news/archie/1.41.2/": "/news/1.41.2/",
|
||||
"/news/archie/1.42.0/": "/news/1.42.0/",
|
||||
"/news/archie/1.43.0/": "/news/1.43.0/",
|
||||
"/news/archie/1.44.0/": "/news/1.44.0/",
|
||||
"/news/archie/1.44.1/": "/news/1.44.1/",
|
||||
"/news/archie/1.45.0/": "/news/1.45.0/",
|
||||
"/news/archie/1.46.0/": "/news/1.46.0/",
|
||||
"/news/archie/1.5.0/": "/news/1.5.0/",
|
||||
"/news/archie/1.6.0/": "/news/1.6.0/",
|
||||
"/news/archie/1.7.0/": "/news/1.7.0/",
|
||||
@@ -123,6 +131,14 @@
|
||||
"/news/archied/1.4.1/": "/news/1.4.1/",
|
||||
"/news/archied/1.40.0/": "/news/1.40.0/",
|
||||
"/news/archied/1.41.0/": "/news/1.41.0/",
|
||||
"/news/archied/1.41.1/": "/news/1.41.1/",
|
||||
"/news/archied/1.41.2/": "/news/1.41.2/",
|
||||
"/news/archied/1.42.0/": "/news/1.42.0/",
|
||||
"/news/archied/1.43.0/": "/news/1.43.0/",
|
||||
"/news/archied/1.44.0/": "/news/1.44.0/",
|
||||
"/news/archied/1.44.1/": "/news/1.44.1/",
|
||||
"/news/archied/1.45.0/": "/news/1.45.0/",
|
||||
"/news/archied/1.46.0/": "/news/1.46.0/",
|
||||
"/news/archied/1.5.0/": "/news/1.5.0/",
|
||||
"/news/archied/1.6.0/": "/news/1.6.0/",
|
||||
"/news/archied/1.7.0/": "/news/1.7.0/",
|
||||
|
||||
@@ -1,4 +1,44 @@
|
||||
[
|
||||
{
|
||||
"version": "1.46.0",
|
||||
"date": "2026-10-02",
|
||||
"body": "### archied\n\n- feat(workflow): declared workflow outputs for wait:true callers\n- feat(prreview): the operator-approval gate is PRReview's own stage-list entry\n- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write\n- feat(prreview): the gate records the review it holds and posts the operator's answer\n- feat(taskactions): one approval path answers the review gate from every surface\n- feat(webui): the dashboard answers the review gate, including a re-review's instructions\n- feat(daemon): resolve the producing identity's org before publishing work\n- feat(webui): block invalid settings and show a field's former value\n- fix(workflow): derive a declared output's captures need for profile selection\n- fix(storepkg): validate every declared authority grant at the package descriptor\n- feat(archied): refresh the model catalog at runtime\n- feat(mcp): answer server-initiated sampling from the chat model\n- feat(container): send registry auth on image pull\n- feat(messaging): retract ephemeral replies after their TTL\n- feat(messaging): transcribe Telegram voice notes\n- fix(egress): take a run's credential kind from its binding, not the Kit\n- feat(webui): a live-apply setting reads as applied, never as a restart\n- feat(webui): the dashboard reads harness bindings and opens the setup terminal\n- feat(gateway): list the harness page in the dashboard page registry\n- feat(webui): the harness settings page and its setup terminal\n- fix(workflow): park environment gate failures without dispatching a builder\n- feat(messaging): adapter-facing clarify, picker and approval contract\n- feat(gateway): gate admin slash commands by sender policy\n- feat(plugins): load plugin and secret-engine files without a restart\n- fix(workflow): deliver the feasibility PRD to the forge issue\n- fix(messaging): report the daemon version this process was built from\n- fix(messaging): carry an inbound attachment's bytes to the gateway turn\n- fix(daemon): resume a retry whose worktree is gone\n- fix(archied): omit the max-token bound on reasoning-class models\n- fix(logging): file a task log record under its own event time\n- fix(control-plane): unify validation for the domain-managed kinds\n- feat(webui): let the operator choose the retry worktree mode\n- feat(agent): seed a starter SOUL and upgrade only untouched templates\n- feat(controlplane): add the writable review-settings resource\n- fix(messaging): transcribe voice notes on the model-owning side of the boundary\n- fix(messaging): gate the boundary on config reads, not only package links\n- feat(messaging): restart only the channel whose settings changed\n- feat(container): apply container-runtime-policies live\n- feat(tools): reconcile MCP servers and tool settings live\n- feat(messaging): add a per-turn interactive carrier for clarify and picker\n- feat(gateway): offer ask_user when the turn's channel can carry a question\n- feat(telegram): carry clarify and picker through the text fallback\n- fix(webui): pin the dashboard validators to the control plane's\n- refactor(agent): drop the SOUL upgrade branch with no shipped template\n- feat(agentworker): answer MCP sampling from the task's model\n- fix(workflow): bind the remediate worktree before the builder runs\n- fix(config): carry max_retries into the worker TaskConfig snapshot\n- fix(agentworker): supply the guardrail engine to every task run\n\n### archie-agent\n\n- feat(workflow): declared workflow outputs for wait:true callers\n- feat(prreview): the operator-approval gate is PRReview's own stage-list entry\n- feat(staterpc): carry the review gate and re-review rounds, with one guarded response write\n- feat(prreview): the gate records the review it holds and posts the operator's answer\n- feat(taskactions): one approval path answers the review gate from every surface\n- fix(workflow): derive a declared output's captures need for profile selection\n- fix(storepkg): validate every declared authority grant at the package descriptor\n- feat(mcp): answer server-initiated sampling from the chat model\n- feat(container): send registry auth on image pull\n- feat(messaging): retract ephemeral replies after their TTL\n- feat(messaging): transcribe Telegram voice notes\n- fix(egress): take a run's credential kind from its binding, not the Kit\n- fix(workflow): park environment gate failures without dispatching a builder\n- feat(messaging): adapter-facing clarify, picker and approval contract\n- feat(plugins): load plugin and secret-engine files without a restart\n- fix(workflow): deliver the feasibility PRD to the forge issue\n- fix(messaging): carry an inbound attachment's bytes to the gateway turn\n- fix(daemon): resume a retry whose worktree is gone\n- fix(logging): file a task log record under its own event time\n- fix(control-plane): unify validation for the domain-managed kinds\n- feat(webui): let the operator choose the retry worktree mode\n- fix(messaging): transcribe Line truncated
|
||||
},
|
||||
{
|
||||
"version": "1.45.0",
|
||||
"date": "2026-09-30",
|
||||
"body": "### archied\n\n- fix(eda): reject a result map missing a field or needing a conversion\n- feat(eda): per-org workflow enable/disable gating bindings\n- feat(telegram): carry inbound media through the chat turn\n- fix(prsource): use a CodeQL-recognised containment guard when extracting archives\n- feat(store): key control-plane resources by (org, kind)\n- fix(store): refuse resource keys the audit key cannot disambiguate\n- fix(daemon): resume the task branch before container acquisition\n- feat(webui): show attachment metadata in the session transcript\n- feat(webui): name a workflow's declared inputs on the work-request form\n- feat(controlplane): carry the caller org from the request principal\n- fix(webui): the workflow handlers act in the caller's org\n- feat(kitrun): render the OAuth credential file with sentinels\n- feat(store): record accepted package authority against the pin\n- fix(workflow): the own-PR flow no longer parks on the operator-approval gate\n- feat(gateway): a TTL-bounded dedup gate for redelivered platform messages\n- feat(egress): capture the OAuth scope set and carry it to the harness secret\n- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key\n- feat(store): project installed package contributions into org resources\n- feat(gateway): coalesce rapid-fire text events into one turn\n- fix(config): expand plugin, module and skills dirs like every other operator path\n- fix(webui): drop the config schema's editability advert\n- feat(webui): events counts, YAML reading, log rows and dashboard filters\n\n### archie-agent\n\n- feat(eda): per-org workflow enable/disable gating bindings\n- feat(telegram): carry inbound media through the chat turn\n- fix(prsource): use a CodeQL-recognised containment guard when extracting archives\n- feat(store): key control-plane resources by (org, kind)\n- feat(controlplane): carry the caller org from the request principal\n- feat(kitrun): render the OAuth credential file with sentinels\n- feat(store): record accepted package authority against the pin\n- fix(workflow): the own-PR flow no longer parks on the operator-approval gate\n- feat(egress): capture the OAuth scope set and carry it to the harness secret\n- feat(kitrun): render the OAuth scopes and omit an uncaptured primary key\n- feat(store): project installed package contributions into org resources"
|
||||
},
|
||||
{
|
||||
"version": "1.44.1",
|
||||
"date": "2026-09-29",
|
||||
"body": "### archied\n\nTwo fixes to tasks that could not get past their workflow definition.\n\n- **Approving a task no longer parks it again.** A task requeued under a\n different workflow kept the previous run's definition pinned, so the worker\n refused to compile the dispatch — it named `feasibility` while the row named\n `implement` — and the task parked immediately, identically on every further\n approval, which left `decline` as the only working operator action.\n The daemon now re-pins whenever the pinned definition's id disagrees with the\n task's workflow. A pin that is present, digest-valid and id-consistent is\n still a strict no-op, so an operator's own definition override survives a\n dispatch unchanged.\n- **A shipped workflow definition now reaches an existing install.** A stored\n seed was consulted only for a resource the store did not already hold, so a\n document that changed in the build never reached a database an earlier\n release had seeded. For workflow definitions that is a total outage rather\n than a stale setting: the collection validates as one document, so a stored\n step type this build no longer has failed every task's pin, whatever workflow\n the task named — and the documented recovery, removing the resource and\n restarting, wrote nothing either, because the store answered the seed's known\n request ID from a history that outlives the resource. A seed now refreshes a\n kind it wrote the newest revision of and re-creates a resource that is gone,\n while an operator's own replacement is never undone.\n\n### archie-agent\n\nThe runtime image is rebuilt with this release and links the shared workflow\npackage carrying the definition-id helper above. Hosts that run agent\ncontainers need `docker compose pull agent` after updating to pick it up."
|
||||
},
|
||||
{
|
||||
"version": "1.44.0",
|
||||
"date": "2026-09-29",
|
||||
"body": "### archied\n\nArchie can now review pull requests.\n\n- **Reviews on request and by watch.** Ask in chat or on the dashboard work form, add a repository to the watch list, or just let archie review its own PRs before it opens them. Review intensity follows a depth dial (quick/standard/deep) classified from the size of the change, and every finished review passes a verification layer — coverage-gap and cross-finding consistency checks — before it is produced.\n- **No forge credential reaches the review sandbox.** The daemon prefetches the pull request's data and rebuilds its source snapshot over the forge's HTTP API, so the agent container works from an isolated copy with no read access to the repository's credentials.\n- **Reviews stop at the operator gate before posting.** `review.precision_gate` / `approve_before_post` decide whether a finished review posts itself or parks for operator approval. With this release the parked state is a stop sign, not a checkpoint: the approve/reject/re-review responses behind the gate are not wired yet, and the gate's settings are not yet editable in the dashboard (configure them in `config.toml`). A parked review sits until that follow-up lands.\n- The adversarial self-review pass archie previously ran before opening its own PRs is superseded by this pipeline and has been removed.\n- Hardened harness input handling: harness identifiers are bounded to integer types.\n\n### archie-agent\n\nThe runtime image is rebuilt with this release; it links the shared pr-review workflow packages behind the reviews above. Hosts that run agent containers need `docker compose pull agent` after updating to pick it up."
|
||||
},
|
||||
{
|
||||
"version": "1.43.0",
|
||||
"date": "2026-09-28",
|
||||
"body": "### archied\n\n- **Organisations.** Tasks, identities and settings now belong to an org. An\n existing install is upgraded into a default org when the State Store first\n starts; the upgrade resumes if interrupted. Task de-duplication is scoped\n per org and identity.\n- **Access policies are enforced** at the dashboard, the API and task\n dispatch, with shipped roles and a rule that nothing crosses between orgs.\n Denials are recorded and reported on the health page. If a policy locks\n you out, `archied access reset --org <org>` (or `--instance`) on the State\n Store host restores the shipped defaults.\n- **Workflows can call workflows** with a `workflow.call` step. Inputs and\n call cycles are checked when the workflow is saved, and the caller waits\n on the callee's result.\n- **Runs record each step.** A run's stages and agent calls are stored as\n steps, the task detail page reads them, and stopping a task or archiving\n it goes through one cancel path. After a crash, steps left running are\n marked interrupted. Archiving a task removes its worktree.\n- **Model roles, repositories, scheduling policy, providers and agent\n profiles apply without a restart.**\n- **Kit harness profiles:**\n - `kit` is now one digest-pinned reference, a workload Kit or a published\n Kit set, not a list. **Rewrite `kit = [...]` in `config.toml` or the\n agent-profiles settings as the single reference**; a list no longer\n loads. Compose mixins by publishing a Kit set.\n - OAuth logins are handled on the host: the egress proxy refreshes tokens,\n stores them encrypted, and gives the container only placeholders.\n - A Kit's skills request mounts `skills_dir` read-only, and its\n instructions file (such as `CLAUDE.md`) is written beside the workspace,\n which is now `/archie/workspace`.\n - A run still cannot be granted the credential a Kit needs, so a Kit that\n requires one is refused at launch.\n- Rate-limited webhook deliveries get `429`.\n- `archie-gateway` and `archie-state-store` report ready to systemd.\n\n### archie-agent\n\n- Runs workflow calls, records its steps and agent calls, and runs Kit\n harness stages under the profile's Kit."
|
||||
},
|
||||
{
|
||||
"version": "1.42.0",
|
||||
"date": "2026-09-26",
|
||||
"body": "### archied\n\n- **The dashboard is rebuilt on a new Graphite theme.** Settings moved to its\n own sidebar with one save flow across every page (Channels, Tools & MCP,\n Scheduling policy, Personas and Schedules, Identities, Plugins, Container\n runtime, and a History of past changes). The top bar, Dashboard, Workflows,\n task detail, the New task dialog and the Events page are all new: Dashboard\n leads with what needs you, a run's stage rail and detail panels sit\n side by side, Workflows shows per-workflow stats including completed runs,\n and Events states capture status with a copyable capture endpoint. Live\n updates share one stream and reopen after a drop instead of going quiet.\n- **Settings changes are audited.** A field-level audit table records who\n changed what, with a view on each settings page.\n- **A task can carry a whole-run wall-clock limit**, separate from a stage's\n own budget.\n- **A run that makes no changes now ends as completed and its worktree is\n cleaned up**, rather than left in a state Workflows didn't count.\n- **Abandoning a task no longer closes its forge issue.** Only the workflow's\n own terminal outcomes do that now.\n- **A task whose container exits before the worker replies is parked**\n instead of left running with no way to finish.\n- **A worktree still holding uncommitted work is kept**, rather than reset,\n when its task reaches a terminal state.\n- **A provider's stored settings no longer get corrupted with a process-local\n placeholder in place of your configured secret reference**, and archied\n rejects a stored value shaped like one on the way back in.\n- **Kit v3 harness profiles.** A `[containers.profiles.<name>]` entry can now\n name a Kit v3 image (`kit = [...]`, pinned by digest) instead of a plain\n container image, running the task's agent stages on an external CLI --\n Claude Code, Codex, Pi, OMP or GitHub Copilot CLI -- inside an isolated\n sandbox network. This release lands the daemon-side plumbing (egress\n proxy, sandbox network, credential injection points); it does not yet ship\n a way to grant a run's identity the credential a Kit needs, so a Kit\n requiring one is refused at launch until a later release adds it.\n- `task dev` now starts the State Store and waits for it before the rest of\n the stack.\n- Every service binary the installer builds is stamped with its version.\n\n### archie-agent\n\n- Carries the same task-lifecycle fixes as archied above (no-change runs,\n parking on an early container exit, and the abandon/forge-issue fix), plus\n the Kit v3 harness runner: a stage can now drive an external CLI\n headlessly, read output from Claude Code, Codex, Pi, OMP or GitHub Copilot\n CLI, and serve it capture tools over MCP.\n- Claude's cached tokens are counted as prompt tokens, matching the built-in\n agent loop's accounting."
|
||||
},
|
||||
{
|
||||
"version": "1.41.2",
|
||||
"date": "2026-09-25",
|
||||
"body": "### archied\n\n- **`/update` no longer offers an old runtime.** The runtime has shipped under\n the release version since the version streams merged, but the update check\n still read the retired runtime tags, so a current host was offered runtime\n 1.35.0 as an update. Do not approve that offer on 1.41.1; update to 1.41.2\n instead.\n- **`/version` reports the runtime version.** Binaries from the release zip\n showed `Runtime: dev`."
|
||||
},
|
||||
{
|
||||
"version": "1.41.1",
|
||||
"date": "2026-09-25",
|
||||
"body": "### archied\n\n- **First published build of 1.41.0.** The 1.41.0 tag produced no release\n artifacts; 1.41.1 carries everything listed under 1.41.0 below, including\n the PostgreSQL 18 requirement and the removed config keys."
|
||||
},
|
||||
{
|
||||
"version": "1.41.0",
|
||||
"date": "2026-09-25",
|
||||
|
||||
@@ -58,10 +58,12 @@ indistinguishable from a process that never reported.
|
||||
## What can be reported, and what cannot
|
||||
|
||||
A process reaches its apply point only after the State Store has answered it.
|
||||
When the State Store is unreachable, the process exits or refuses to start and
|
||||
writes no record. An unreachable store is never reported as a failure by the
|
||||
process it affected. A record carries the other failure: the store answered,
|
||||
and the value would not validate.
|
||||
At startup, when the State Store is unreachable, the process exits or refuses
|
||||
to start and writes no record. A live watcher that loses its established
|
||||
control-plane stream reports the connection failure against its last applied
|
||||
version while it retries. Re-establishing the stream clears that outage record
|
||||
without clearing a versioned document rejection. A transport failure is not a
|
||||
document rejection; it reports that live delivery is unavailable.
|
||||
|
||||
Absence has two meanings and the UI never collapses them: no process applies
|
||||
this kind, or a process that applies other kinds has not reported this one.
|
||||
@@ -101,6 +103,9 @@ restart but not a death, and accepting the limitation with the page saying so.
|
||||
- A process that applies a resource writes a record carrying that version.
|
||||
- A process whose apply fails validation writes a record carrying the error and
|
||||
no new version.
|
||||
- A live watch outage is reported against the last applied version until the
|
||||
stream is re-established; re-establishment preserves any outstanding
|
||||
versioned rejection.
|
||||
- A reload that fails leaves the previously applied version recorded.
|
||||
- A record written under a process name outside the shared constant fails the
|
||||
test binding writer to reader.
|
||||
|
||||
@@ -1,119 +0,0 @@
|
||||
# Dashboard navigation groups + Configuration split -- decision
|
||||
|
||||
**Status:** Approved
|
||||
**Date:** 2026-09-20
|
||||
**Beads issue:** `archie-core-ocfm`
|
||||
**Related:** `archie-core-gl96` (Logs absent from the nav -- subsumed here),
|
||||
`archie-core-ggqo` (Configuration's page width -- moot once it splits)
|
||||
|
||||
## Problem
|
||||
|
||||
`ui/src/main.jsx` declares eleven navigable routes in one flat bar. Three of
|
||||
them (Skills, Curators, Channels) are capability-gated and hidden on the
|
||||
reference deployment, so the eight items normally visible are the best case,
|
||||
not the worst: a composition that serves every section wraps the bar. Logs is
|
||||
declared but was never given a nav entry at all, reachable only from a
|
||||
dashboard link.
|
||||
|
||||
The labels compound it. "Event inspector", "Field mappings" and "Playbook
|
||||
bindings" are three long labels for three faces of one subject, and they sit
|
||||
beside "Dashboard" and "Tasks" as though they were peers of equal weight.
|
||||
|
||||
Configuration is the other half. One route renders roughly ten sections --
|
||||
update status, work lifecycle, identity, budgets, storage, listen address,
|
||||
repositories, models and providers, configuration sources, plus the operator
|
||||
cards rehomed in `archie-core-tf20` -- in a 4021px page with no in-page
|
||||
navigation. There is no way to send someone to Repositories.
|
||||
|
||||
## Decision
|
||||
|
||||
Five top-level nav items. Dashboard is a link; the rest are dropdowns.
|
||||
|
||||
| Group | Items |
|
||||
| --------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Dashboard | (link, `/`) |
|
||||
| Work | Tasks, Workflows |
|
||||
| Agent | Skills, Curators |
|
||||
| Events | Inspector, Mappings, Bindings |
|
||||
| System | Status, Logs, Appearance; **Settings:** Task settings, Models, Repositories, Channels, Advanced |
|
||||
|
||||
Items are renamed because the group now carries the context: "Event inspector"
|
||||
becomes "Inspector" under Events, and so on. A group renders only if at least
|
||||
one of its children survives capability gating, and a group left with one
|
||||
child still renders as a dropdown -- a bar whose shape changes per deployment
|
||||
is harder to learn than one with a predictable skeleton.
|
||||
|
||||
The System dropdown has two narratives. Status, Logs and Appearance describe
|
||||
the running dashboard and sit first. A separator and visible **Settings** label
|
||||
introduce Task settings, Models, Repositories, Channels and Advanced; those are
|
||||
configuration destinations, not awkward phrases such as "System Models" or
|
||||
"System Advanced".
|
||||
|
||||
### Route map
|
||||
|
||||
Configuration dissolves into real routes. Anchors into one long page were
|
||||
rejected: they leave the 4021px page intact and a deep link lands the reader
|
||||
mid-scroll with no context above it.
|
||||
|
||||
| Was | Becomes | Content |
|
||||
| ----------- | -------------------- | ----------------------------------------------------------- |
|
||||
| `/settings` | `/system/status` | Update status, configuration sources, daemon listen address |
|
||||
| -- | `/system/appearance` | Theme, and the density/motion preferences that follow it |
|
||||
| `/settings` | `/system/tasks` | Work lifecycle: statuses, operator actions, budgets |
|
||||
| `/settings` | `/system/models` | Model roles, providers |
|
||||
| `/settings` | `/system/repos` | Repositories and their per-repo gate overrides |
|
||||
| `/settings` | `/system/advanced` | Identity, storage and sandboxing, dangerous actions |
|
||||
| `/captures` | `/captures` | unchanged; label becomes "Inspector" |
|
||||
| `/mappings` | `/mappings` | unchanged; label becomes "Mappings" |
|
||||
| `/bindings` | `/bindings` | unchanged; label becomes "Bindings" |
|
||||
|
||||
`/settings` is kept as a permanent redirect to `/system/status`. It is the URL
|
||||
in existing bookmarks, in `dashboardPages` (`internal/gateway/dashboard_tools.go`,
|
||||
which the chat agent navigates by), and in prior conversation history; breaking
|
||||
it to save one route entry is not a trade worth making.
|
||||
|
||||
`dashboardPages` gains the new routes in the same change. That registry is
|
||||
guarded by `TestDashboardPagesRegistryCoversEveryRoute`, so a route added here
|
||||
and forgotten there fails the build -- which is how the deleted `/chat` entry
|
||||
was caught.
|
||||
|
||||
### Dropdown behaviour
|
||||
|
||||
Each item carries a one-line description shown as a hover tooltip, using
|
||||
shadcn-vue's `Tooltip` rather than the `title` attribute, so it is keyboard
|
||||
reachable on focus and styled with the rest of the menu. Touch gets no tooltip,
|
||||
so no item may depend on one to be identifiable.
|
||||
|
||||
The menu is shadcn-vue's `DropdownMenu` (Reka UI underneath), which already
|
||||
supplies the roving focus, ArrowDown/ArrowUp movement, Escape-closes-and-
|
||||
restores-focus, and outside-pointerdown behaviour this would otherwise hand-
|
||||
roll. It opens on click, never on hover -- hover-opened menus on a control
|
||||
plane are a misclick away from a destructive page. The trigger keeps
|
||||
`aria-current` styling when any of its children is the active route, so the bar
|
||||
still says where you are.
|
||||
|
||||
This section was written against the Preact dashboard; the decisions above
|
||||
survive the Vue migration unchanged, only the primitive supplying them
|
||||
changed.
|
||||
|
||||
### Scope boundaries
|
||||
|
||||
- The daemon-backed configuration pages move sections between routes; this
|
||||
change does not alter their read-only configuration contract.
|
||||
- Appearance preferences remain browser-local; they do not create a daemon
|
||||
configuration path. Theme, density, motion and tooltips apply immediately
|
||||
and persist in local browser storage.
|
||||
- Mobile keeps the existing scrollable row of top-level items; groups expand
|
||||
in place rather than opening a floating menu. Nested floating menus on a
|
||||
phone are a separate problem.
|
||||
|
||||
## Consequences
|
||||
|
||||
The bar goes from eleven items to five, and stops depending on capability
|
||||
gating to fit. Logs gets a home. Configuration becomes six linkable pages, and
|
||||
`archie-core-ggqo`'s question about its page width answers itself, because no
|
||||
single page is long enough for the cap to matter.
|
||||
|
||||
The cost is a real routing change with redirects to maintain, and a nav that
|
||||
now needs keyboard and screen-reader behaviour it did not need as a row of
|
||||
links. Both are paid once.
|
||||
@@ -3,8 +3,7 @@
|
||||
**Status:** Approved
|
||||
**Date:** 2026-09-20
|
||||
**Beads:** `archie-core-tavn` (epic), `archie-core-ocfm` (navigation)
|
||||
**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item),
|
||||
`docs/prds/dashboard-navigation-groups.md` (the approved nav design)
|
||||
**Reads with:** `docs/prds/vue-migration-checklist.md` (the item-by-item)
|
||||
|
||||
This is the standard the port is held to. The checklist says what to port; this
|
||||
says how, and what counts as done. It exists because the first attempt ported
|
||||
|
||||
@@ -29,11 +29,6 @@ its id.
|
||||
|
||||
## Verification
|
||||
|
||||
- `TestTaskMetaPayloadMatchesFixture` requires the handler to serve
|
||||
`internal/webui/testdata/task_meta.json` byte for byte. Regenerate it with
|
||||
`go test ./internal/webui -run TestTaskMetaPayloadMatchesFixture -update`.
|
||||
- `ui/test/task-meta-snapshot.test.ts` requires the snapshot to equal that
|
||||
fixture.
|
||||
- `TestTaskMetaChangeStatusesAreDeliberate` fails when a `Change*` constant is
|
||||
added without a label.
|
||||
|
||||
|
||||
@@ -0,0 +1,200 @@
|
||||
# Execution tree and enforced state machine
|
||||
|
||||
**Status:** Approved
|
||||
**Authority:** `docs/architecture/agent-system.md` (canonical workflow model);
|
||||
settles the "enforced WorkflowExecution state machine" item in
|
||||
`docs/architecture/migration-decisions.md` section 4.
|
||||
**Compounds with:** `docs/prds/task-run-detail.md` (attempt attribution),
|
||||
`docs/prds/state-store-contract.md` (wire contract and task-scoped grants).
|
||||
|
||||
## Decision
|
||||
|
||||
A WorkflowExecution becomes the root of a tree of StepExecutions. Every stage
|
||||
run, and every agent call a stage makes, is its own durable record with a
|
||||
parent, an attempt, a status and an outcome. Both levels move only through a
|
||||
declared transition table, enforced by the State Store in the same transaction
|
||||
that writes the audit row and the domain event.
|
||||
|
||||
## Problem
|
||||
|
||||
- A run is one `tasks` row. The only per-step record is the mutable `stage`
|
||||
column, overwritten as `workflow.Run` advances, plus observability events.
|
||||
A failed attempt cannot say which step failed or what its children did
|
||||
without replaying the event stream.
|
||||
- `Store.Transition` guards on the expected `from` status, but any `from` to
|
||||
any `to` is accepted. A `queued` to `merged` write succeeds.
|
||||
- Stop cancels one context in `daemon.runningTasks`. Nothing persisted says
|
||||
which work was in flight, so an agent call that outlives its stage (a
|
||||
reviewer, a container) is invisible to the store.
|
||||
- `workflow.Run` writes `tc.Store.Update` and discards the error, then emits
|
||||
`KindStageStart` separately. State and events can diverge.
|
||||
|
||||
## Model
|
||||
|
||||
```text
|
||||
WorkflowExecution (tasks row, id E)
|
||||
└── attempt N
|
||||
├── StepExecution stage "plan" depth 0
|
||||
├── StepExecution stage "implement" depth 0
|
||||
│ └── StepExecution agent "implement" depth 1
|
||||
└── StepExecution stage "review" depth 0
|
||||
├── StepExecution agent "review:1" depth 1
|
||||
└── StepExecution agent "review:2" depth 1
|
||||
```
|
||||
|
||||
- A StepExecution belongs to exactly one WorkflowExecution and one attempt.
|
||||
`parent_id` is null for a stage and names the enclosing StepExecution
|
||||
otherwise. Depth is derived from the parent, never supplied by the caller.
|
||||
- `kind` is `stage`, `agent` or `call`. A new kind needs a named consumer
|
||||
before it is added.
|
||||
- A `workflow.call` step (`docs/prds/event-automation.md`) is a `call`
|
||||
StepExecution in the caller's tree. The callee is its own
|
||||
WorkflowExecution, with its own tree, acting as its own identity, and the
|
||||
`call` step records the callee's execution ID. Trees never nest across
|
||||
executions, so each run's tree stays inside that run's authority.
|
||||
- A retry starts a new attempt. Earlier attempts' StepExecutions are never
|
||||
rewritten.
|
||||
|
||||
## Transition tables
|
||||
|
||||
WorkflowExecution statuses are the existing `taskstate` constants, persisted
|
||||
strings unchanged. `taskstate` gains the one table every writer checks:
|
||||
|
||||
| From | To |
|
||||
| --------------- | ---------------------------------------------------------- |
|
||||
| `queued` | `running`, `closed_wont_do` |
|
||||
| `running` | `queued` (crash recovery), `waiting_human`, `pr_open`, `completed`, `parked`, `closed_wont_do` |
|
||||
| `waiting_human` | `queued` (approve), `closed_wont_do` |
|
||||
| `parked` | `queued` (retry), `dead` (abandon), `closed_wont_do` |
|
||||
| `pr_open` | `merged`, `rejected`, `queued` (remediation), `closed_wont_do` |
|
||||
| terminal | none |
|
||||
|
||||
StepExecution statuses:
|
||||
|
||||
| From | To |
|
||||
| --------- | ------------------------------------------------------ |
|
||||
| `pending` | `running`, `cancelled` |
|
||||
| `running` | `succeeded`, `failed`, `cancelled`, `interrupted` |
|
||||
| terminal | none |
|
||||
|
||||
`interrupted` means the process running the step died or shut down. It is
|
||||
distinct from `cancelled`, which an operator or a parent asked for, and from
|
||||
`failed`, which the step reported.
|
||||
|
||||
A StepExecution cannot reach `running` while its WorkflowExecution is not
|
||||
`running`, and cannot start under a terminal parent.
|
||||
|
||||
## Enforcement
|
||||
|
||||
- The table lives in `taskstate` (no dependencies), so the store, daemon and
|
||||
gateway share one copy.
|
||||
- Every store method that changes `tasks.status` checks the table and writes
|
||||
the audit and event rows, not only `Transition`. That includes the claim,
|
||||
`ParkTask`, `Requeue`, `RetryTask`, `BeginRemediation` and `RecoverStale`
|
||||
paths, several of which change status without an audit row.
|
||||
- The State Store rejects an illegal transition with a new sentinel,
|
||||
`ErrIllegalTransition`, carried across the wire through `mapError` like
|
||||
`ErrStaleTransition`. A stale `from` stays `ErrStaleTransition`.
|
||||
- Each transition is one transaction: guarded row update, audit row, domain
|
||||
event row. The events table is written by the store, not emitted beside it.
|
||||
`KindStageStart` and `KindStageFinish` are produced by the step transition
|
||||
and published to the bus after commit.
|
||||
- `workflow.Run` stops discarding persistence errors. A failed step write
|
||||
parks the execution; the step does not run unrecorded.
|
||||
|
||||
## Cancellation
|
||||
|
||||
Stopping a run is one store call, `CancelExecution(E, reason)`. In one
|
||||
transaction it moves every non-terminal StepExecution of the current attempt
|
||||
to `cancelled` and the WorkflowExecution to `closed_wont_do` or `parked`,
|
||||
whichever the operator action names. The daemon then cancels the in-memory
|
||||
context. A worker whose step write returns `ErrStaleTransition` because its
|
||||
step is already `cancelled` stops without writing further.
|
||||
|
||||
Cancelling a caller cancels each callee it is waiting on (`wait: true`),
|
||||
through `CancelExecution` on the callee under the callee's own lifecycle. A
|
||||
callee started with `wait: false` runs on.
|
||||
|
||||
The store is the record of cancellation. The context cancel is the delivery
|
||||
mechanism, so a lost cancel still leaves the store correct and the worker's
|
||||
next write fails.
|
||||
|
||||
## Crash recovery
|
||||
|
||||
`RecoverStale` moves every `running` StepExecution of an interrupted
|
||||
execution to `interrupted` in the same transaction that requeues the
|
||||
execution. The next attempt starts with fresh steps.
|
||||
|
||||
## Wire contract
|
||||
|
||||
New State Store RPCs, each with a matching Go method on a narrow consumer
|
||||
facade:
|
||||
|
||||
- `StartStep(execution, attempt, parent, kind, name) -> step id`
|
||||
- `FinishStep(step, from, to, detail, tokens_used)`
|
||||
- `CancelExecution(execution, reason, to)`
|
||||
- `ListSteps(execution, attempt)`
|
||||
|
||||
The run credential of `docs/prds/orgs-and-access.md` authorises `StartStep`
|
||||
and `FinishStep` on its own execution only, and the container records its own
|
||||
agent calls with it. `CancelExecution` and `ListSteps` are dashboard, API and
|
||||
dispatch actions, decided by the Authorizer: `update` and `read` on the run.
|
||||
|
||||
## Organisations
|
||||
|
||||
`docs/prds/orgs-and-access.md` is the boundary. A StepExecution belongs to its
|
||||
WorkflowExecution's org and workspace and carries their `org_id` and
|
||||
`workspace_id`, like every owned record. The State Store stamps both from the
|
||||
credential on `StartStep` and ignores them in the request. `ListSteps` for an
|
||||
execution in another org returns the store's ordinary not-found error.
|
||||
|
||||
## Storage
|
||||
|
||||
One new table, `step_executions`: `id`, `org_id`, `workspace_id`,
|
||||
`execution_id`, `attempt`, `parent_id`, `depth`, `kind`, `name`,
|
||||
`called_execution_id`, `status`, `detail`, `tokens_used`, `started_at`,
|
||||
`finished_at`. Indexed on `(execution_id, attempt, id)`.
|
||||
Deleting an execution (archive, clearing terminal tasks) deletes its steps.
|
||||
Existing rows gain no backfilled steps. Their history stays in `transitions`
|
||||
and `events`.
|
||||
|
||||
`tasks.stage` is written from the step transition while any reader still uses
|
||||
it, then dropped once the dashboard reads `ListSteps`.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Running sibling steps in parallel. The tree records concurrency; changing
|
||||
the stage runner is separate work.
|
||||
- Cost in currency. `tokens_used` per step is the only usage field.
|
||||
- Workflow definition versioning and the `tasks` to `workflow_executions`
|
||||
rename.
|
||||
- A harness contract for swappable coding agents.
|
||||
|
||||
## Plan
|
||||
|
||||
1. `taskstate` transition tables with table-driven tests covering every
|
||||
legal and a sample of illegal pairs.
|
||||
2. `ErrIllegalTransition` enforced in the Postgres store and mapped over the
|
||||
wire.
|
||||
3. `step_executions` migration, `StartStep`/`FinishStep`, grant rules;
|
||||
`workflow.Run` records stages; events written in the transition
|
||||
transaction.
|
||||
4. Agent-call children recorded from the agent runtime.
|
||||
5. `CancelExecution`; daemon stop and chat/dashboard actions route through it.
|
||||
6. `RecoverStale` interrupts running steps.
|
||||
7. Dashboard run detail reads `ListSteps`; `tasks.stage` dropped.
|
||||
|
||||
## Verification
|
||||
|
||||
- An illegal WorkflowExecution or StepExecution transition returns
|
||||
`ErrIllegalTransition` over gRPC, and `errors.Is` matches on the client.
|
||||
- Killing the daemon mid-stage, then restarting, leaves that stage
|
||||
`interrupted` and the execution `queued` with a new attempt.
|
||||
- Stopping a run during review leaves every review child `cancelled`, and a
|
||||
late `FinishStep` from the container returns `ErrStaleTransition`.
|
||||
- A run credential cannot `StartStep` on another execution, and a member of
|
||||
org A listing steps of an org B execution gets not-found.
|
||||
- Cancelling a caller cancels its `wait: true` callee and leaves a
|
||||
`wait: false` callee running.
|
||||
- For every step transition there is exactly one event row, written in the
|
||||
same transaction.
|
||||
@@ -2,6 +2,8 @@
|
||||
|
||||
**Status:** Draft
|
||||
|
||||
> Superseded by `docs/prds/store.md`.
|
||||
|
||||
Epic: `archie-core-1786637490708-35-38424ead` / GitHub `#56` ("Replace Skills
|
||||
with a bundled Extensions centre").
|
||||
|
||||
|
||||
@@ -0,0 +1,306 @@
|
||||
# External agent harnesses
|
||||
|
||||
**Status:** Approved
|
||||
**Authority:** `docs/architecture/agent-system.md` (agent execution as a data
|
||||
boundary); settles the harness non-goal deferred by
|
||||
`docs/prds/service-decomposition.md`.
|
||||
**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a harness
|
||||
run is one `agent` StepExecution), `docs/prds/binding-secret-encryption.md`
|
||||
(the at-rest envelope reused for harness credentials).
|
||||
|
||||
## Decision
|
||||
|
||||
A workflow stage can run on an external coding-agent CLI instead of the
|
||||
built-in agent loop: Claude Code, Codex, Pi, OMP, GitHub Copilot CLI, or any
|
||||
other CLI packaged as a Docker Sandbox Kit v3. Each authenticates with an API
|
||||
key or the operator's subscription login, and can carry the operator's own
|
||||
skills, plugins, subagents and instructions.
|
||||
|
||||
Two boundaries hold regardless of what the harness does:
|
||||
|
||||
- **The real credential never enters the container.** The container sees
|
||||
sentinel values; archie's egress proxy substitutes the real credential on
|
||||
outbound requests and performs OAuth refresh on the host.
|
||||
- **Archie's workflow guarantees are enforced outside the harness.** Git,
|
||||
protected paths, read-only stages, gates and budgets are checked by archie
|
||||
around the process and against the worktree afterwards.
|
||||
|
||||
## Kits
|
||||
|
||||
A harness is packaged as a Kit v3 image: an OCI image whose
|
||||
`vnd.docker.sandbox.kit.descriptor` manifest annotation declares what the
|
||||
harness needs. Archie reads descriptors with the published
|
||||
`github.com/docker/sandbox-kit-spec/v3/spec` package and does not maintain
|
||||
its own descriptor format. Published Kits run unmodified.
|
||||
|
||||
Archie is a partial Kit runtime. It implements these capability types:
|
||||
|
||||
| Type | Archie behaviour |
|
||||
| ------------------- | ----------------------------------------------------------------------------------------- |
|
||||
| `credential@1` | Proxy-managed only, described below. |
|
||||
| `network-policy@1` | Enforced by the egress proxy. |
|
||||
| `volume@1` | A Docker volume keyed by WorkflowExecution, deleted with it. |
|
||||
| `lifecycle@1` | Install and startup hooks run on container create. |
|
||||
| `agent-sessions@1` | The headless `prompt` and `resume` invocations for the stage. |
|
||||
| `agent-skills@1` | The operator's skills store (`skills_dir`), mounted read-only whatever the Kit asks. |
|
||||
| `agent-context@1` | The workload's profile file beside the workspace, indexing each Kit's guidance. |
|
||||
| `resources@1` | Container CPU and memory limits. |
|
||||
|
||||
Every other type fails closed: a required entry refuses the launch, an
|
||||
optional one is skipped and recorded on the step. `credential@1` with
|
||||
`passthrough: true` and any credential for a forge service are refused.
|
||||
|
||||
The operator's own setup (plugins, subagents, instructions, settings) is a
|
||||
mixin Kit, published with the harness Kit as a Kit set: the set merges their
|
||||
layers into one image. It is versioned image content, rewritten on every
|
||||
create, never state a run can modify.
|
||||
|
||||
## Contract
|
||||
|
||||
A harness run is a second implementation of `agentexec.Runner`. It takes the
|
||||
same `Request` and returns the same `Result`, so workflows, the daemon and
|
||||
the State Store do not know which runner ran a stage.
|
||||
|
||||
`agent-sessions@1` supplies the invocation. Archie supplies, per CLI, an
|
||||
output adapter that translates the CLI's JSON output stream into
|
||||
`ToolCallReporter` calls, `Usage` and a session ID. A CLI with no adapter can
|
||||
run stages with no capture tools, reporting no usage; its token budget falls
|
||||
back to wall clock.
|
||||
|
||||
Workflow definition validation rejects, at load time, a stage whose needs the
|
||||
selected harness cannot meet: capture tools without an adapter, or a gate
|
||||
retry without a `resume` verb.
|
||||
|
||||
## Selection
|
||||
|
||||
A harness is an agent profile. `docs/prds/event-automation.md` defines a
|
||||
profile as the execution environment a workflow selects; a harness profile
|
||||
names one Kit pinned by digest, a workload Kit or a published Kit set, in
|
||||
place of a container image. Archie runs that Kit's image and composes no Kits
|
||||
itself; a bare mixin is refused. Everything else about profiles
|
||||
holds: a workflow names its profile, a stage may name a different one, and a
|
||||
profile holds no secrets.
|
||||
|
||||
`archie-agent` builds the stage's runner from the stage's profile: the
|
||||
ai-sdk agent loop for an image profile, the harness runner for a Kit
|
||||
profile. Image profiles, and every workflow already written against them,
|
||||
are unchanged. A Kit profile named by no workflow is a validation error.
|
||||
|
||||
A stage naming a different profile than its workflow's is a separate run,
|
||||
not a mid-container runner switch: a Kit task runs in one container
|
||||
provisioned for one profile (Container layout), so a stage that needs a
|
||||
different one is its own callee, started the way `workflow.call` already
|
||||
starts one (`docs/prds/event-automation.md` "Workflows call workflows"),
|
||||
with its own agent profile resolved off its own task row. This needs no
|
||||
mechanism beyond `workflow.call` plus per-task profile resolution
|
||||
(`daemon.pinTaskProfile`), both of which already treat every task's
|
||||
profile independently of any caller's -- see
|
||||
`TestWorkflowCallerConformance` (staterpc) for the callee's independent
|
||||
`Workflow` field and `TestWorkflowCallGivesACalleeItsOwnProfile` (daemon)
|
||||
for the Kit-vs-image runner selection that independence produces.
|
||||
|
||||
Profiles are org resources in the State Store, so a Kit profile belongs to
|
||||
one org, is granted to its workspaces like any profile, and applies without
|
||||
a restart.
|
||||
|
||||
## Organisations
|
||||
|
||||
`docs/prds/orgs-and-access.md` is the boundary; a harness adds nothing that
|
||||
crosses it.
|
||||
|
||||
- A Kit profile, its credential bindings and its OAuth tokens belong to one
|
||||
org. No record is shared between orgs.
|
||||
- A harness run is a run like any other: it acts as the workflow's identity,
|
||||
under the run credential issued at dispatch.
|
||||
- The egress proxy injects a credential only when the run credential carries
|
||||
the secret the binding names. A Kit that declares a service the identity is
|
||||
not granted gets no credential: a required one refuses the launch, an
|
||||
optional one is skipped.
|
||||
- A Kit's network policy is what the Kit asks for; the identity's network
|
||||
grants are what the org allows. The proxy enforces the intersection.
|
||||
- Concurrency slots are counted per binding within its org.
|
||||
|
||||
## Credentials
|
||||
|
||||
A credential binding maps a Kit's `credential@1` `service` name to an org
|
||||
secret, which the org grants to identities like any secret. The secret holds
|
||||
one of:
|
||||
|
||||
- **API key:** a value in the org's secret store.
|
||||
- **OAuth:** tokens captured by the setup terminal, stored in the State Store
|
||||
under the at-rest envelope of `binding-secret-encryption.md` with its own
|
||||
domain separator.
|
||||
|
||||
The egress proxy resolves the binding for each request against the run
|
||||
credential. The container gets the Kit's sentinel in the named variable or
|
||||
credential file. OAuth refresh happens at the proxy, which intercepts the
|
||||
Kit's `tokenEndpoint`, so a refreshed token is written to the State Store and
|
||||
never returned to the container.
|
||||
|
||||
Runs sharing an OAuth binding share its subscription's rate limit.
|
||||
`max_concurrent` on the binding (default 1) caps its simultaneous runs. A
|
||||
stage waiting for a slot is `pending`, not `running`.
|
||||
|
||||
## Setup terminal
|
||||
|
||||
The dashboard opens a terminal (xterm.js over a WebSocket to a PTY) into an
|
||||
ephemeral container built from a Kit profile, on the same egress path. The
|
||||
member runs the CLI's own login. The proxy captures the tokens at the token
|
||||
endpoint into the org secret the binding names. The container is removed when
|
||||
the terminal closes. No worktree is mounted into it.
|
||||
|
||||
Opening the terminal is the `update` action on the secret, decided by the
|
||||
Authorizer like any other; the shipped roles give it to org owners and
|
||||
admins. It is the only interactive path into a harness container.
|
||||
|
||||
## Egress
|
||||
|
||||
Only Kit profiles run on the egress path. An image profile keeps the network
|
||||
access its identity is granted, because workflows such as a network
|
||||
investigator need raw DNS, ICMP and arbitrary TCP that no HTTP proxy
|
||||
carries.
|
||||
|
||||
- **Sandbox network.** Each Kit run gets its own internal Docker bridge on
|
||||
which the host holds no address. Host services, including those listening
|
||||
on every interface, are unreachable from it by any address.
|
||||
- **Relay.** One relay container, `archie-agent relay`, sits on the sandbox
|
||||
networks under a fixed alias and on the host-reachable network. It
|
||||
forwards three fixed ports, to the proxy, NATS and the State Store, and can
|
||||
reach nothing else. It holds no secrets.
|
||||
- **Proxy.** The proxy runs inside `archied`, listening on the host gateway
|
||||
of the host-reachable network. It terminates TLS with a per-daemon CA
|
||||
installed into the container at create, identifies the container by a
|
||||
per-run proxy token, and applies that run's network policy and credential
|
||||
inject rules. Upstream dials refuse loopback, and refuse internal addresses
|
||||
unless the policy names the exact IP, so an allowed name cannot resolve
|
||||
back into the host.
|
||||
|
||||
## Container layout
|
||||
|
||||
A Kit task runs in one container, from the Kit composition's image, on the
|
||||
task's sandbox network. The worker and every harness invocation share it;
|
||||
they are separated by user, not by container, so a run's cost scales with
|
||||
the run and not with how many agents it fans out to.
|
||||
|
||||
- **Worker.** Archie mounts its own `archie-agent` binary read-only and runs
|
||||
it as the container's entrypoint, as root. It holds the task's NATS and
|
||||
State Store credentials in its own environment and in root-only files,
|
||||
runs the workflow, and serves `archie-agent mcp`. The Kit image's
|
||||
entrypoint is not PID 1.
|
||||
- **Harness.** Every invocation runs as the Kit's user (the image's `User`,
|
||||
default uid 1000) with an explicit environment: the Kit's variables, the
|
||||
proxy environment and the credential sentinels, and nothing inherited from
|
||||
the worker. That user cannot read the worker's environment or files, or
|
||||
trace it. Sibling invocations in one run share the user and the worktree.
|
||||
- **Hooks.** `lifecycle@1` install and startup hooks run as the user each
|
||||
declares, before the worker accepts work.
|
||||
- **Mounts.** The task worktree at the Kit's workspace directory, owned by the
|
||||
Kit's user, and the read-only skills store. Nothing else from the host.
|
||||
- **Network.** The relay forwards three fixed ports on the sandbox network:
|
||||
the egress proxy, NATS and the State Store. The worker reaches NATS and the
|
||||
State Store with its credentials; a harness can open those ports but holds
|
||||
no credential either accepts.
|
||||
- **Volumes.** `volume@1` paths persist for the life of the
|
||||
WorkflowExecution, which covers session resume across gate iterations and
|
||||
retries. They are not shared between executions.
|
||||
|
||||
## Archie tools inside the harness
|
||||
|
||||
Capture tools, which are how a stage returns structured results, are served
|
||||
by `archie-agent mcp`, a stdio MCP server registered through the Kit's MCP
|
||||
configuration or the adapter's flags. It serves the stage's `CaptureTools`
|
||||
and the central tools the agent profile's `AllowTools` permits, never the
|
||||
`workspace` toolset. The runner's `ToolLimits` bound its results; the
|
||||
harness's own built-in tools are outside archie's limits.
|
||||
|
||||
## Enforcement around the harness
|
||||
|
||||
| Property | Enforcement |
|
||||
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Model never runs git | No forge credential can be bound. Archie records `HEAD` and every ref before the run; any change fails the step (`failed`, policy class). The workflow commits the stage's changes. |
|
||||
| Protected paths | A diff touching a `Protection` path fails the step. |
|
||||
| Read-only stage | Any worktree diff fails the step. |
|
||||
| Gate | Archie runs the stage's gate after the harness exits. On failure it resumes the session with the gate output, up to the stage's iteration budget. |
|
||||
| Budget | Archie kills the process on wall-clock timeout, or when streamed usage passes the token budget. |
|
||||
| Cancellation | Cancelling the step kills the process group, then the container. |
|
||||
| Egress | Only the proxy is reachable; the Kit's network policy decides the rest. |
|
||||
|
||||
Harness settings that deny git or protected paths are added where the CLI
|
||||
supports them, to save wasted turns. They are never the enforcement.
|
||||
|
||||
## Execution tree
|
||||
|
||||
A harness run is one `agent` StepExecution. Subagents the harness spawns
|
||||
internally are not recorded as children. Their usage is included in the
|
||||
step's `tokens_used` when the adapter reports it.
|
||||
|
||||
## Agents never hold a harness
|
||||
|
||||
An Agent reaches a harness only by invoking a Workflow whose stage names it.
|
||||
No Agent tool, chat tool or capability exposes a harness, its setup terminal
|
||||
or its credential. The stage boundary is what carries the container, the git
|
||||
and path checks, the gate and the budget; a harness outside a stage has none
|
||||
of them.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Chat through a harness. The gateway chat loop stays on the built-in
|
||||
runtime.
|
||||
- `network-policy@2` HTTP method and path rules; a Kit requiring it is
|
||||
refused.
|
||||
- Recording the harness's internal subagents as StepExecutions.
|
||||
- Cost in currency.
|
||||
- Choosing a harness automatically per task.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Descriptor resolution with the Kit spec package; capability support
|
||||
table and fail-closed refusal.
|
||||
2. Egress proxy: internal network, per-daemon CA, per-container token,
|
||||
`network-policy@1`.
|
||||
3. `credential@1`: API-key bindings, sentinel rendering, inject rules.
|
||||
4. Harness `Runner`: container create with worktree, volumes, lifecycle
|
||||
hooks and the mounted `archie-agent`; `agent-sessions@1` invocation;
|
||||
worktree checks for git, protected paths and read-only; budget and
|
||||
cancellation.
|
||||
5. Claude Code output adapter; `archie-agent mcp`; gate-and-resume loop.
|
||||
6. Kit profiles, runner selection from the stage's profile, and definition
|
||||
validation.
|
||||
7. OAuth bindings as org secrets: token-endpoint interception, encrypted
|
||||
storage, per-binding concurrency; dashboard setup terminal.
|
||||
8. Output adapters for Codex, Pi, OMP and GitHub Copilot CLI.
|
||||
|
||||
## Verification
|
||||
|
||||
- The same workflow definition completes on `builtin` and on the Claude Code
|
||||
Kit with the same `Result` shape and captures.
|
||||
- After `/login` in the setup terminal, the container's credential file holds
|
||||
only sentinels, the State Store holds the encrypted token, and a task run
|
||||
authenticates.
|
||||
- A real API key or OAuth token never appears in the container environment,
|
||||
filesystem, worktree, task log or event stream.
|
||||
- A request to a host outside the Kit's runtime allow list fails, including a
|
||||
direct connection that bypasses the proxy settings.
|
||||
- A harness instructed to `git commit` fails its step, and the task branch is
|
||||
unchanged.
|
||||
- A harness edit to a protected test file fails the step in a TDD fix stage.
|
||||
- A read-only feasibility stage that writes a file fails.
|
||||
- A file a run writes into a Kit-managed path such as the CLI's settings file
|
||||
is gone on the next execution.
|
||||
- A Kit requiring an unsupported capability is refused at launch with the
|
||||
capability named.
|
||||
- A stage with a failing gate resumes the same session with the gate output,
|
||||
then succeeds or exhausts its iterations.
|
||||
- Two tasks sharing an OAuth binding with `max_concurrent = 1` run one at a
|
||||
time; the second waits as `pending`.
|
||||
- Stopping a run kills the harness process and removes the container.
|
||||
- A harness invocation cannot read the worker's NATS or State Store
|
||||
credential from its environment, its files or `/proc`.
|
||||
- A run fanning out to many agent invocations uses one container.
|
||||
- A Kit profile in org A cannot be selected, and its binding cannot be
|
||||
resolved, by a workflow in org B.
|
||||
- A harness run whose identity is not granted a Kit's required credential is
|
||||
refused at launch; the proxy never injects a secret outside the run
|
||||
credential.
|
||||
- The firewall investigation example runs unchanged on an image profile with
|
||||
direct network access.
|
||||
@@ -56,11 +56,18 @@ messages by method name (the same switch that already routes
|
||||
`internal/app/archied/main.go` that routes the sampling request through the
|
||||
same chat-model call path `chatGenerateOptions` already uses, so a
|
||||
server-initiated sample gets the daemon's configured model, not a second
|
||||
provider client.
|
||||
provider client. The agent worker hosts the same configured MCP servers on the
|
||||
task path and runs its own model runtime, so `internal/app/agentworker` wires
|
||||
the same seam from the task's builder model: a server that samples succeeds
|
||||
inside a chat turn and inside a task, never one and not the other. The message
|
||||
mapping and the token bound are shared (`internal/agentexec`, next to the
|
||||
runtime both paths call models through) so both paths bound a sample
|
||||
identically.
|
||||
|
||||
**Reuse check.** The chat model invocation path already exists
|
||||
(`chatGenerateOptions`, `main.go`); this reuses it rather than adding a
|
||||
parallel model-calling path for MCP sampling.
|
||||
(`chatGenerateOptions`, `main.go`) and the task model path already exists
|
||||
(`agentexec.NewRuntime`, the runtime an agent stage runs on); this reuses both
|
||||
rather than adding a parallel model-calling path for MCP sampling.
|
||||
|
||||
**Failure mapping.**
|
||||
|
||||
@@ -170,7 +177,8 @@ preview callbacks fire in order before the next call starts. `task check`.
|
||||
| MCP client call serialisation | `internal/tools/mcp/client.go` | change (`#177`) |
|
||||
| MCP server config | `internal/config/config.go` | new fields: `ParallelToolCalls`, `Sandboxed` |
|
||||
| Sampling dispatch | `internal/tools/mcp/client.go` | new (`#151`) |
|
||||
| Sampling handler wiring | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
|
||||
| Sampling handler wiring (chat path) | `internal/app/archied/main.go` | new (`#151`), reuses `chatGenerateOptions` |
|
||||
| Sampling handler wiring (task path) | `internal/app/agentworker/mcp_sampling.go`, `mcp_providers.go` | new (`#151`), answers from the task's builder model |
|
||||
| Sandboxed MCP launch | MCP client constructor + `internal/container/pool.go` | new (`#178`/`#179`) |
|
||||
| Concurrent tool dispatch | dispatch entry point (closed `#183`) | none — already handles this |
|
||||
| Sequential tool dispatch + previews | same dispatch entry point | new (`#182`) |
|
||||
@@ -181,7 +189,7 @@ preview callbacks fire in order before the next call starts. `task check`.
|
||||
|
||||
| sub-feature | issue | implementer scope | suggested council lenses | why |
|
||||
| ------------------------------------ | -------------- | ---------------------------------------------------------------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||
| Server-initiated sampling | `#151` | `client.go` dispatch branch, `main.go` handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |
|
||||
| Server-initiated sampling | `#151` | `client.go` dispatch branch, chat-path and task-path handler wiring | `lens-contract` | new JSON-RPC method surface crossing the MCP wire contract |
|
||||
| Parallel-tool-calls flag | `#177` | config field, conditional mutex, constructor wiring | `lens-boundary` | per-server behaviour change must not leak into other servers' serialisation |
|
||||
| Sandboxed MCP + Firecracker deferral | `#178`, `#179` | config field, constructor routing through `ContainerPool`, pool entrypoint variant | `lens-operator`, `lens-deletionist` | operator: sandbox-down failure path; deletionist: keeps `#179` from becoming unused scaffolding |
|
||||
| Sequential dispatch with previews | `#182` | `DispatchMode` enum, sequential branch, preview reuse of streaming seam | `lens-maintainer` | two coexisting dispatch modes need a reader to tell which applies without re-deriving both |
|
||||
|
||||
@@ -118,7 +118,12 @@ typed values are checked at load; `dyn` values are checked by the module decode.
|
||||
|
||||
**D5 — where the result map becomes the `Result` struct.** Settled:
|
||||
`ModuleRegistry` stays schema-agnostic. `ModuleRegistry.DecodeResult`
|
||||
(`internal/domain/eda/module`) is the conversion site.
|
||||
(`internal/domain/eda/module`) is the conversion site. It accepts a value only
|
||||
when it already carries the field's declared type, and a map only when it
|
||||
carries every declared field. A conversion changes the value's representation --
|
||||
a number for a string field is the named case -- and an absent field reads as the
|
||||
zero value, so each is reported rather than becoming a quietly wrong value in a
|
||||
later expression.
|
||||
|
||||
## Verification
|
||||
|
||||
@@ -128,5 +133,8 @@ typed values are checked at load; `dyn` values are checked by the module decode.
|
||||
dynamically indexed `actions` read fails.
|
||||
- An arg KEY the kind's `Args` schema does not define fails the load, and so
|
||||
does `message: '123'` for the `log` kind. `message: event.title` loads.
|
||||
- A result map missing a declared field, and one whose value is not already the
|
||||
field's type, are both reported by the decode; a value that would only be
|
||||
convertible (a number for a string field) is not accepted.
|
||||
- The one-action `workflow` playbook shape, its dispatch, and its existing
|
||||
load-time checks are unchanged.
|
||||
@@ -3,6 +3,8 @@
|
||||
**Status:** Draft
|
||||
**Beads issue:** `archie-core-h019.8`
|
||||
|
||||
> Superseded by `docs/prds/pr-review-agent.md`.
|
||||
|
||||
This PRD reuses the adversarial-self-review contract
|
||||
(`docs/prds/adversarial-self-review.md`) and the `workflow.Reviewer` /
|
||||
`workflow.ReviewReport` types from `internal/domain/workflow`. It decides
|
||||
|
||||
@@ -4,28 +4,24 @@
|
||||
**Date:** 2026-09-03
|
||||
**Parent:** `docs/prds/eda-playbook-engine.md`, epic `archie-core-t2db`
|
||||
**Beads issue:** `archie-core-t2db.14` (expression environment).
|
||||
Unbuilt decisions: `archie-core-t2db.25` (J1 action ids),
|
||||
`archie-core-t2db.26` (J2 args as CEL),
|
||||
`archie-core-t2db.27` (Result schemas declared to CEL).
|
||||
|
||||
**Decision:** CEL via `cel.dev/cel-go` (v0.32.0), pinned. One expression
|
||||
mechanism covers both an action's `when` condition and its `args` values.
|
||||
|
||||
## The requirement, stated directly
|
||||
|
||||
A playbook action is gated and parametrised by runtime data: (a) a
|
||||
condition deciding whether the action runs; (b) a later action's `args`
|
||||
values referencing an earlier action's `Result` and the triggering
|
||||
event's fields. Both are **CEL expressions**, evaluated against one
|
||||
evaluation context. There is no separate interpolation syntax: CEL
|
||||
reads nested maps and fields natively, so `args` values that need data
|
||||
are written as CEL, and only plain literal args remain plain YAML
|
||||
scalars.
|
||||
A playbook action is gated and parametrised by runtime data: (a) a condition
|
||||
deciding whether the action runs; (b) a later action's `args` values referencing
|
||||
an earlier action's `Result` and the triggering event's fields. Both are **CEL
|
||||
expressions**, evaluated against one evaluation context. There is no separate
|
||||
interpolation syntax: CEL reads nested maps and fields natively, so `args`
|
||||
values that need data are written as CEL, and only plain literal args remain
|
||||
plain YAML scalars.
|
||||
|
||||
Both halves are read-only: expressions may read context values and
|
||||
compute a result from them, never mutate, never call host functions,
|
||||
never perform I/O. CEL enforces this structurally (no side effects,
|
||||
linear evaluation when macros are bounded, cost-limited).
|
||||
Both halves are read-only: expressions may read context values and compute a
|
||||
result from them, never mutate, never call host functions, never perform I/O.
|
||||
CEL enforces this structurally (no side effects, linear evaluation when macros
|
||||
are bounded, cost-limited).
|
||||
|
||||
```yaml
|
||||
actions:
|
||||
@@ -44,112 +40,101 @@ actions:
|
||||
|
||||
## Trust boundary of the expression
|
||||
|
||||
A playbook YAML is **operator-installed, in-process, daemon-privileged**
|
||||
-- the same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir`
|
||||
(module-position.md's trust-boundary section): loaded from a configured
|
||||
directory at startup, never from a webhook body or task worktree. The
|
||||
schema-by-example flow uses live events to _design against_; the saved
|
||||
playbook is operator-authored file content in an operator-configured
|
||||
location.
|
||||
A playbook YAML is **operator-installed, in-process, daemon-privileged** -- the
|
||||
same tier as `ModuleDir`/`PluginDir`/`SecretEngineDir` (module-position.md's
|
||||
trust-boundary section): loaded from a configured directory at startup, never
|
||||
from a webhook body or task worktree. The schema-by-example flow uses live
|
||||
events to _design against_; the saved playbook is operator-authored file content
|
||||
in an operator-configured location.
|
||||
|
||||
Two consequences:
|
||||
|
||||
1. The expression string is **trusted**. Operator-authored config, not
|
||||
attacker input; no sandboxing against a hostile expression string is
|
||||
required. If a future playbook source is less trusted (auto-generated
|
||||
bindings from unauthenticated captures), that is the playbook-file
|
||||
trust tier moving -- the loader's acceptance check is the right
|
||||
place, not the evaluator.
|
||||
2. The **data the expression reads is NOT trusted** (decoded webhook
|
||||
body, prior results through the same pipeline). Robustness against
|
||||
hostile data is required: no panic on wrong-typed/missing fields,
|
||||
no unbounded cost on deep/cyclic maps, bounded evaluation time. CEL
|
||||
provides this structurally (cost limits, linear non-Turing-complete
|
||||
evaluation, error values instead of panics -- verified in the
|
||||
vetting record below).
|
||||
1. The expression string is **trusted**. Operator-authored config, not attacker
|
||||
input; no sandboxing against a hostile expression string is required. If a
|
||||
future playbook source is less trusted (auto-generated bindings from
|
||||
unauthenticated captures), that is the playbook-file trust tier moving -- the
|
||||
loader's acceptance check is the right place, not the evaluator.
|
||||
2. The **data the expression reads is NOT trusted** (decoded webhook body, prior
|
||||
results through the same pipeline). Robustness against hostile data is
|
||||
required: no panic on wrong-typed/missing fields, no unbounded cost on
|
||||
deep/cyclic maps, bounded evaluation time. CEL provides this structurally
|
||||
(cost limits, linear non-Turing-complete evaluation, error values instead of
|
||||
panics -- verified in the vetting record below).
|
||||
|
||||
## The gate precedent is deliberately NOT copied
|
||||
|
||||
`internal/gate/gateeval` evaluates arbitrary interpreted Go
|
||||
(`.archie/gate.go`) as the repo's conditional-logic precedent. That is
|
||||
the wrong precedent for playbook conditions because this document's
|
||||
premise is: **YAML is pure orchestration data; Yaegi is where
|
||||
imperative logic lives** (Problem section; module-position.md's
|
||||
"no generic hook" section). Yaegi snippets in YAML would move
|
||||
imperative logic into the data layer -- the inversion this design
|
||||
exists to prevent -- and make playbooks un-lintable.
|
||||
`internal/gate/gateeval` evaluates arbitrary interpreted Go (`.archie/gate.go`)
|
||||
as the repo's conditional-logic precedent. That is the wrong precedent for
|
||||
playbook conditions because this document's premise is: **YAML is pure
|
||||
orchestration data; Yaegi is where imperative logic lives** (Problem section;
|
||||
module-position.md's "no generic hook" section). Yaegi snippets in YAML would
|
||||
move imperative logic into the data layer -- the inversion this design exists to
|
||||
prevent -- and make playbooks un-lintable.
|
||||
|
||||
The line: conditions are **declarative predicates over runtime data,
|
||||
not programs**. CEL is non-Turing-complete and side-effect-free, so it
|
||||
cannot become a program; a condition that needs real logic gets a
|
||||
Module kind (Yaegi), referenced by the action, not a stronger
|
||||
expression body.
|
||||
The line: conditions are **declarative predicates over runtime data, not
|
||||
programs**. CEL is non-Turing-complete and side-effect-free, so it cannot become
|
||||
a program; a condition that needs real logic gets a Module kind (Yaegi),
|
||||
referenced by the action, not a stronger expression body.
|
||||
|
||||
## Plugin-engine-rule interaction
|
||||
|
||||
The plugin engine rule forbids a generic `Module` interface with an
|
||||
`any` payload; it exists to keep static implementation contracts
|
||||
typed. Evaluating CEL against runtime `map[string]any` is **not the
|
||||
same problem**: the rule concerns _implementation contracts_ (static
|
||||
operations a capability family exposes), not _runtime data values_
|
||||
(legitimately dynamic -- an event payload's shape is unknown until it
|
||||
arrives). The Module contract stays fully typed (generated
|
||||
`Args`/`Result` schemas); CEL is a read-only data reader under the
|
||||
playbook engine family, not a new capability contract. Stated once.
|
||||
The plugin engine rule forbids a generic `Module` interface with an `any`
|
||||
payload; it exists to keep static implementation contracts typed. Evaluating CEL
|
||||
against runtime `map[string]any` is **not the same problem**: the rule concerns
|
||||
_implementation contracts_ (static operations a capability family exposes), not
|
||||
_runtime data values_ (legitimately dynamic -- an event payload's shape is
|
||||
unknown until it arrives). The Module contract stays fully typed (generated
|
||||
`Args`/`Result` schemas); CEL is a read-only data reader under the playbook
|
||||
engine family, not a new capability contract. Stated once.
|
||||
|
||||
## Minimum viable evaluation context (what expressions see)
|
||||
|
||||
One flat context, namespaced from the playbook run, built at dispatch
|
||||
time:
|
||||
One flat context, namespaced from the playbook run, built at dispatch time:
|
||||
|
||||
| Name | Type | Source |
|
||||
| --------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `event` | `map(string, dyn)` | The triggering event's decoded payload (webhook body / forge issue / schedule tick). Field access via `event.<field>`, map access via `event["field"]`, presence via `has(event.<field>)`. |
|
||||
| `actions` | per-playbook object type | Previous actions' results, one field per declared action `id` (`actions.<id>`), each field typed `{ result: <KindResult> }` so a later action reads an earlier one's `Result` struct (`actions.<id>.result.<field>`) with field-level checking. The current action and later actions are not present. |
|
||||
|
||||
Expressions may also read literal-only state (numbers, strings,
|
||||
booleans) directly. CEL's `has()` macro covers the missing-key case
|
||||
(`has(event.labels)` -> bool), which replaces any bespoke `has`/
|
||||
`contains` operator.
|
||||
Expressions may also read literal-only state (numbers, strings, booleans)
|
||||
directly. CEL's `has()` macro covers the missing-key case (`has(event.labels)`
|
||||
-> bool), which replaces any bespoke `has`/ `contains` operator.
|
||||
|
||||
`actions.<id>.result` is the kind's hand-written `Result` struct:
|
||||
`ModuleRegistry.DecodeResult` converts `Module.Invoke`'s flat
|
||||
`map[string]any` (`archie-core-t2db.13`) back into that struct before a later
|
||||
expression reads it, so the checker and the run read the same typed value.
|
||||
`ModuleRegistry.DecodeResult` converts `Module.Invoke`'s flat `map[string]any`
|
||||
(`archie-core-t2db.13`) back into that struct before a later expression reads
|
||||
it, so the checker and the run read the same typed value.
|
||||
|
||||
Judgement call J1: `action` id is a required field on every action
|
||||
that later actions reference; ids are validated at load (unique,
|
||||
stable-identifier-shaped), and a `when`/`args` expression referencing
|
||||
an unknown `actions.<id>` is a **load failure**, not a runtime miss --
|
||||
the same reject-at-load rule as collisions (see below).
|
||||
Judgement call J1: `action` id is a required field on every action that later
|
||||
actions reference; ids are validated at load (unique, stable-identifier-shaped),
|
||||
and a `when`/`args` expression referencing an unknown `actions.<id>` is a **load
|
||||
failure**, not a runtime miss -- the same reject-at-load rule as collisions (see
|
||||
below).
|
||||
|
||||
## Load-time validation (consistent with the collision rule)
|
||||
|
||||
The collision-handling rule is: schema defines the accepted message;
|
||||
anything outside it is rejected at load, logged plainly, reported to
|
||||
the caller -- never deferred to runtime. Expressions are validated the
|
||||
same way, at playbook load:
|
||||
The collision-handling rule is: schema defines the accepted message; anything
|
||||
outside it is rejected at load, logged plainly, reported to the caller -- never
|
||||
deferred to runtime. Expressions are validated the same way, at playbook load:
|
||||
|
||||
- **Syntax**: every `when` and every CEL-typed `args` value is parsed
|
||||
and checked by CEL's checker when the playbook is loaded. A syntax
|
||||
or type error is a reported load failure (the playbook is dropped and
|
||||
the error goes to the caller), not a runtime surprise.
|
||||
- **Context conformance**: with the context declared to CEL
|
||||
(`event` as `map(string, dyn)`, `actions` as a per-playbook object type
|
||||
with one typed field per declared id),
|
||||
unknown top-level identifiers are rejected at compile time.
|
||||
Field-level typing inside `dyn` values is deferred to runtime by
|
||||
CEL's design (verified: `data.items.lenght` with `data` dyn compiles
|
||||
clean and errors at eval) -- so the loader declares as much type as
|
||||
the schema provides (the action kinds' generated `Result` structs
|
||||
become CEL type declarations at load, giving field-level rejection
|
||||
for result reads), and `event` stays `dyn` because its shape is
|
||||
unknown by design (schema-by-example).
|
||||
- **Syntax**: every `when` and every CEL-typed `args` value is parsed and
|
||||
checked by CEL's checker when the playbook is loaded. A syntax or type error
|
||||
is a reported load failure (the playbook is dropped and the error goes to the
|
||||
caller), not a runtime surprise.
|
||||
- **Context conformance**: with the context declared to CEL (`event` as
|
||||
`map(string, dyn)`, `actions` as a per-playbook object type with one typed
|
||||
field per declared id), unknown top-level identifiers are rejected at compile
|
||||
time. Field-level typing inside `dyn` values is deferred to runtime by CEL's
|
||||
design (verified: `data.items.lenght` with `data` dyn compiles clean and
|
||||
errors at eval) -- so the loader declares as much type as the schema provides
|
||||
(the action kinds' generated `Result` structs become CEL type declarations at
|
||||
load, giving field-level rejection for result reads), and `event` stays `dyn`
|
||||
because its shape is unknown by design (schema-by-example).
|
||||
- **Names**: unknown `actions.<id>` references and unknown roots are
|
||||
compile-time/lint-visible errors (J1).
|
||||
|
||||
This means the lint tool and the daemon share one checker
|
||||
-- same single-source argument as the playbook loaders.
|
||||
This means the lint tool and the daemon share one checker -- same single-source
|
||||
argument as the playbook loaders.
|
||||
|
||||
## Candidate comparison
|
||||
|
||||
@@ -165,112 +150,108 @@ This means the lint tool and the daemon share one checker
|
||||
|
||||
Source reviewed at HEAD:
|
||||
|
||||
- **Repo hygiene**: clean. No binaries/media in tree (the only
|
||||
non-source artifacts are expected generated protobuf files); 16-line
|
||||
`.gitignore`.
|
||||
- **Hard-boundary correctness**: the place correctness is hard for an
|
||||
expression evaluator is bounding evaluation and surviving hostile
|
||||
input. Dedicated regression tests exist and pass at HEAD:
|
||||
`TestCostLimit`, `TestCostTracking*`, `TestParserRecursionLimit`,
|
||||
and a large conformance suite. Verified by execution: evaluation
|
||||
against a 2000-deep nested map under `CostLimit` completes in ~10
|
||||
microseconds and returns an error value for a missing key -- no
|
||||
panic, no unbounded walk.
|
||||
- **Dependency footprint**: antlr (parser), protobuf + genproto (CEL's
|
||||
type model), `cel.dev/expr` (CEL spec types), yaml.v3. All
|
||||
mainstream, canonical, vendored widely by Google-adjacent projects.
|
||||
No runtime-impure third-party code; the REPL-only deps (readline,
|
||||
tview, tcell) are not in the library import graph.
|
||||
- **Security record**: no advisories on record for `cel.dev/cel-go`
|
||||
(GitHub Advisory Database).
|
||||
- **Module path**: migrated to `cel.dev/cel-go` (v0.32.0 is current);
|
||||
the old `github.com/google/cel-go` path is the pre-migration identity.
|
||||
Pin `cel.dev/cel-go`.
|
||||
- **Binary size cost**: +13.0MB is the largest of the candidates
|
||||
(measured: baseline 2.34MB -> 15.25MB with CEL). Accepted because:
|
||||
the daemon already embeds a large Yaegi runtime; CEL's type model is
|
||||
the load-bearing win (compile-time rejection of result-path typos,
|
||||
matching the reject-at-load rule); and the alternative bespoke
|
||||
grammar would re-implement CEL's checker to get the same guarantee.
|
||||
Flagged for sign-off: if 13MB is unacceptable for a specific
|
||||
deployment target, the fallback is a bespoke grammar with a
|
||||
- **Repo hygiene**: clean. No binaries/media in tree (the only non-source
|
||||
artifacts are expected generated protobuf files); 16-line `.gitignore`.
|
||||
- **Hard-boundary correctness**: the place correctness is hard for an expression
|
||||
evaluator is bounding evaluation and surviving hostile input. Dedicated
|
||||
regression tests exist and pass at HEAD: `TestCostLimit`, `TestCostTracking*`,
|
||||
`TestParserRecursionLimit`, and a large conformance suite. Verified by
|
||||
execution: evaluation against a 2000-deep nested map under `CostLimit`
|
||||
completes in ~10 microseconds and returns an error value for a missing key --
|
||||
no panic, no unbounded walk.
|
||||
- **Dependency footprint**: antlr (parser), protobuf + genproto (CEL's type
|
||||
model), `cel.dev/expr` (CEL spec types), yaml.v3. All mainstream, canonical,
|
||||
vendored widely by Google-adjacent projects. No runtime-impure third-party
|
||||
code; the REPL-only deps (readline, tview, tcell) are not in the library
|
||||
import graph.
|
||||
- **Security record**: no advisories on record for `cel.dev/cel-go` (GitHub
|
||||
Advisory Database).
|
||||
- **Module path**: migrated to `cel.dev/cel-go` (v0.32.0 is current); the old
|
||||
`cel.dev/cel-go/cel` path is the pre-migration identity. Pin `cel.dev/cel-go`.
|
||||
- **Binary size cost**: +13.0MB is the largest of the candidates (measured:
|
||||
baseline 2.34MB -> 15.25MB with CEL). Accepted because: the daemon already
|
||||
embeds a large Yaegi runtime; CEL's type model is the load-bearing win
|
||||
(compile-time rejection of result-path typos, matching the reject-at-load
|
||||
rule); and the alternative bespoke grammar would re-implement CEL's checker to
|
||||
get the same guarantee. Flagged for sign-off: if 13MB is unacceptable for a
|
||||
specific deployment target, the fallback is a bespoke grammar with a
|
||||
re-implemented subset of this checker -- a strictly worse trade.
|
||||
|
||||
## Why bespoke was not sufficient
|
||||
|
||||
A bespoke grammar for the shipped cases (path read + comparison + bool
|
||||
composition) is small, but the load-time-validation requirement makes
|
||||
the comparison: the reject-at-load rule requires _field-level_ static
|
||||
checking of result paths against generated `Result` schemas, which is
|
||||
CEL's type-checker's job. Re-implementing that on a hand-rolled
|
||||
grammar means re-implementing a type system -- more code than the
|
||||
grammar itself, with worse diagnostics, no conformance suite, and no
|
||||
community surface for future expression needs (even declarative ones).
|
||||
The bespoke option only wins on binary size, and the size cost of CEL
|
||||
is measured and bounded.
|
||||
composition) is small, but the load-time-validation requirement makes the
|
||||
comparison: the reject-at-load rule requires _field-level_ static checking of
|
||||
result paths against generated `Result` schemas, which is CEL's type-checker's
|
||||
job. Re-implementing that on a hand-rolled grammar means re-implementing a type
|
||||
system -- more code than the grammar itself, with worse diagnostics, no
|
||||
conformance suite, and no community surface for future expression needs (even
|
||||
declarative ones). The bespoke option only wins on binary size, and the size
|
||||
cost of CEL is measured and bounded.
|
||||
|
||||
## Judgement calls (flagged for sign-off)
|
||||
|
||||
- **J1 -- `id` required on referenced actions, unknown id = load
|
||||
failure.** Matches the reject-at-load rule. Alternative considered: an alternative
|
||||
is positional `actions[0]` access, which breaks on reorder; named is
|
||||
the operator-friendlier shape.
|
||||
- **J2 -- every `args` value is evaluated as a CEL expression.** No
|
||||
split between "literal args" and "expression args": a plain string
|
||||
value is a CEL string literal, a number is a CEL number literal, and
|
||||
any value that reads context data is written in CEL. One mechanism,
|
||||
no interpolation marker, no second syntax to learn. Alternative considered: cEL
|
||||
string literals must be quoted inside YAML (e.g. `message:
|
||||
'"build finished"'`), which is slightly noisy for mostly-literal
|
||||
args; accepted for uniformity -- the linter catches quoting mistakes
|
||||
at load.
|
||||
- **J3 -- condition failure semantics.** A condition that errors at
|
||||
runtime (missing/wrong-typed field) evaluates to **false**: the
|
||||
action is skipped, logged, run continues. This is the simplest
|
||||
candidate consistent with gap 1's bias against clever recovery;
|
||||
gap 1 (`archie-core-t2db.18`) commits
|
||||
stop-on-first-failure, so per-action control is not coming and J3
|
||||
stands. Alternative considered: cEL separates
|
||||
false from error; we treat evaluation error as false + log.
|
||||
- **J4 -- `event` stays `dyn` (schema-by-example).** Load-time we
|
||||
cannot know event field types; declaring them typed would reject
|
||||
valid plays. Result reads get field-level checking via generated
|
||||
schema declarations. Alternative considered: when schema-by-example ships, tighten
|
||||
event field declarations from captured samples.
|
||||
- **J5 -- cost limit default.** A `CostLimit` at load time (e.g.
|
||||
100,000) is applied to every expression; the linter and daemon use
|
||||
the same value so they agree. Alternative considered: exact number is a constant to
|
||||
tune at first use.
|
||||
- **J1 -- `id` required on referenced actions, unknown id = load failure.**
|
||||
Matches the reject-at-load rule. Alternative considered: an alternative is
|
||||
positional `actions[0]` access, which breaks on reorder; named is the
|
||||
operator-friendlier shape.
|
||||
- **J2 -- every `args` value is evaluated as a CEL expression.** No split
|
||||
between "literal args" and "expression args": a plain string value is a CEL
|
||||
string literal, a number is a CEL number literal, and any value that reads
|
||||
context data is written in CEL. One mechanism, no interpolation marker, no
|
||||
second syntax to learn. Alternative considered: cEL string literals must be
|
||||
quoted inside YAML (e.g. `message: '"build finished"'`), which is slightly
|
||||
noisy for mostly-literal args; accepted for uniformity -- the linter catches
|
||||
quoting mistakes at load.
|
||||
- **J3 -- condition failure semantics.** A condition that errors at runtime
|
||||
(missing/wrong-typed field) evaluates to **false**: the action is skipped,
|
||||
logged, run continues. This is the simplest candidate consistent with gap 1's
|
||||
bias against clever recovery; gap 1 (`archie-core-t2db.18`) commits
|
||||
stop-on-first-failure, so per-action control is not coming and J3 stands.
|
||||
Alternative considered: cEL separates false from error; we treat evaluation
|
||||
error as false + log.
|
||||
- **J4 -- `event` stays `dyn` (schema-by-example).** Load-time we cannot know
|
||||
event field types; declaring them typed would reject valid plays. Result reads
|
||||
get field-level checking via generated schema declarations. Alternative
|
||||
considered: when schema-by-example ships, tighten event field declarations
|
||||
from captured samples.
|
||||
- **J5 -- cost limit default.** A `CostLimit` at load time (e.g. 100,000) is
|
||||
applied to every expression; the linter and daemon use the same value so they
|
||||
agree. Alternative considered: exact number is a constant to tune at first
|
||||
use.
|
||||
- **J6 -- `args` failure semantics.** An `args` value that cannot be evaluated
|
||||
aborts its playbook run: the action and every later action in that playbook do
|
||||
not run, because data has no false value to fall back on and an action run
|
||||
without its arguments is a silent one. Other playbooks matching the same event
|
||||
still run, and the task is unaffected: a playbook run never changes routing.
|
||||
The daemon log reports the failure, naming the task, the playbook and the
|
||||
action; no task event is written. Alternative considered: mirroring J3,
|
||||
rejected because a predicate has a meaningful false and data does not.
|
||||
|
||||
## Interaction with the execution-time gaps
|
||||
|
||||
This resolution does not resolve the execution-time gaps (both are
|
||||
resolved separately: gap 1 by `archie-core-t2db.18`, gap 2 by the
|
||||
gap-2 decision). Conditions make gap 1
|
||||
concrete (condition-failure vs. action-failure semantics, J3) and
|
||||
CEL's read-only result access makes gap 2's keying derivation
|
||||
readable (an idempotency key expression can read event fields) -- both
|
||||
flagged as the gaps' first real exercise. Gap 2's exercise is
|
||||
subsequently solved by that decision: the
|
||||
answer is a fixed structural derivation, and idempotency keys are
|
||||
deliberately NOT CEL expressions (see the "No CEL in the key"
|
||||
passage).
|
||||
This resolution does not resolve the execution-time gaps (both are resolved
|
||||
separately: gap 1 by `archie-core-t2db.18`, gap 2 by the gap-2 decision).
|
||||
Conditions make gap 1 concrete (condition-failure vs. action-failure semantics,
|
||||
J3) and CEL's read-only result access makes gap 2's keying derivation readable
|
||||
(an idempotency key expression can read event fields) -- both flagged as the
|
||||
gaps' first real exercise. Gap 2's exercise is subsequently solved by that
|
||||
decision: the answer is a fixed structural derivation, and idempotency keys are
|
||||
deliberately NOT CEL expressions (see the "No CEL in the key" passage).
|
||||
|
||||
## Implementation placement (for the follow-up slice)
|
||||
|
||||
- New `internal/domain/eda/expr` package: builds the CEL environment
|
||||
(context declarations, generated `Result` schema types as CEL type
|
||||
declarations, cost limit), compiles/validates playbook expressions
|
||||
at load, evaluates them at dispatch. Domain layer; no infrastructure
|
||||
imports; owned by the playbook engine family. One new dependency:
|
||||
`cel.dev/cel-go` (pinned), `go.mod` otherwise unchanged.
|
||||
- Consumption: the playbook event coordinator (open question 4's
|
||||
loader) evaluates `when` before dispatch and
|
||||
evaluates `args` values before `Module.Invoke`; the lint tool
|
||||
(`archie-core-t2db.12`) shares the same compile/validate path for author-time
|
||||
diagnostics.
|
||||
- New `internal/domain/eda/expr` package: builds the CEL environment (context
|
||||
declarations, generated `Result` schema types as CEL type declarations, cost
|
||||
limit), compiles/validates playbook expressions at load, evaluates them at
|
||||
dispatch. Domain layer; no infrastructure imports; owned by the playbook
|
||||
engine family. One new dependency: `cel.dev/cel-go` (pinned), `go.mod`
|
||||
otherwise unchanged.
|
||||
- Consumption: the playbook event coordinator (open question 4's loader)
|
||||
evaluates `when` before dispatch and evaluates `args` values before
|
||||
`Module.Invoke`; the lint tool (`archie-core-t2db.12`) shares the same
|
||||
compile/validate path for author-time diagnostics.
|
||||
- Schema integration: action kinds' generated `Result`/`Args` structs
|
||||
(`archie-core-t2db.13`'s `logextract` pattern) are declared to CEL at load so
|
||||
`actions.<id>.result.<field>` type-checks; `args` expressions
|
||||
type-check against the target kind's `Args` schema before the
|
||||
playbook is accepted.
|
||||
`actions.<id>.result.<field>` type-checks; `args` expressions type-check
|
||||
against the target kind's `Args` schema before the playbook is accepted.
|
||||
@@ -0,0 +1,134 @@
|
||||
# Plugin settings reconcile live
|
||||
|
||||
**Status:** Draft
|
||||
**Revision:** 2
|
||||
**Tracking:** GitHub [#1154](https://github.com/samcharles93/archie-core/issues/1154), epic [#998](https://github.com/samcharles93/archie-core/issues/998)
|
||||
**Authority:** `docs/prds/runtime-control-plane.md` decides each feature owns how
|
||||
its changes take effect; `docs/architecture/plugins-and-extensions.md` owns the
|
||||
plugin engine rule; `docs/prds/control-plane-apply-status.md` owns where apply
|
||||
reports go.
|
||||
|
||||
## Outcome
|
||||
|
||||
An operator drops a plugin, module or secret-engine file into a configured
|
||||
directory while archied runs, and the daemon loads it without a restart. An
|
||||
edit to an installed file replaces what is running. A delete never stops running
|
||||
code; apply status says so. A stored `plugin-settings` change applies live for
|
||||
`plugin_dir`, `module_dir` and `secret_engine_dir`; a change to `skills_dir` is
|
||||
refused.
|
||||
|
||||
## Triggers
|
||||
|
||||
`PluginSettingsKind` joins `runtimeResourceKinds` in
|
||||
`internal/app/archied/control_plane.go`, and its descriptor `ApplyMode` becomes
|
||||
`live` in `internal/app/controlplane/operational_settings.go`.
|
||||
|
||||
A poller reconciles on the apply-status restamp interval, so a dropped file
|
||||
loads without a filesystem watch. Each tick re-runs both halves the boot path
|
||||
runs, against the directories in the running config: the directory loads
|
||||
(`secret.Registry.LoadDir`, `ModuleRegistry.Register`, `plugin.LoadDir`) and the
|
||||
layering (`boot.runtimeConfig`), which re-resolves provider credentials. A
|
||||
provider disabled at boot for an unresolvable engine is re-resolved on the first
|
||||
tick that finds it; a changed directory retargets the next tick without a
|
||||
restart.
|
||||
|
||||
## Rules
|
||||
|
||||
- Adding and changing load; removing never unloads. Yaegi interpreters are not
|
||||
reclaimed while a caller still exists and there is no unload path; the running
|
||||
set can only grow. A removal stays outstanding in the apply-status error until
|
||||
the process restarts.
|
||||
- Each file is loaded through a fresh interpreter (the boot pattern) and
|
||||
content-hashed, so only new and changed files load.
|
||||
- A file that fails to load is skipped and reported; already-running code keeps
|
||||
running, the degrade-and-skip convention `plugin.LoadDir` and
|
||||
`Registry.LoadDir` already apply at boot. Boot keeps its reject-at-load rule
|
||||
for the module directory; a broken file at runtime skips without aborting.
|
||||
- A directory that does not exist reconciles to an empty set.
|
||||
|
||||
## The three registries
|
||||
|
||||
- **Secret engines** (`internal/secret`). Reconciliation re-runs
|
||||
`Registry.LoadDir` against the live directory. `Register` replaces by name, so
|
||||
an edited engine takes effect for the next resolution and a dropped engine
|
||||
resolves on the next tick. A deleted engine stays registered: existing
|
||||
references keep resolving through it until restart. Engines are stateless
|
||||
resolvers, so a swap needs no lifecycle step.
|
||||
- **Modules** (`internal/domain/eda/module`). Reconciliation re-runs
|
||||
`ModuleRegistry.Register` for the kind's file. Playbook dispatch resolves
|
||||
through the registry at invoke time, so the swap reaches a running playbook
|
||||
store unchanged; a deleted file leaves the old invoker in place, running.
|
||||
- **Plugins** (`internal/plugin`). `Host` grows running-state operations beside
|
||||
`Register`, `Start` and `Stop`, and `Register` keeps its rule that
|
||||
registration is allowed only before the first `Start`, so these are new host
|
||||
methods rather than a relaxed `Register`. One adds a single module while the
|
||||
host is running: inserted in dependency order, started alone, and rolled back
|
||||
alone on failure, leaving every previously started module running. The other
|
||||
replaces a module whose manifest id matches: stop it, start the new one, and
|
||||
restart the old one when the new start fails; replacing a module another
|
||||
running module depends on is refused. A module's `Start` is its only check
|
||||
(`plugin.Module` has no probe, and one manifest id cannot be registered
|
||||
twice), so a replacement checks by starting and keeps a rollback rather than
|
||||
switching first. These operations obey the plugin engine rule: the host
|
||||
invokes start and stop itself and isolates the failure to one module. A
|
||||
deleted file makes no host call: the module runs on.
|
||||
|
||||
## `skills_dir`
|
||||
|
||||
`skills_dir` is not part of this change. The daemon refuses a `plugin-settings`
|
||||
document whose `skills_dir` differs from the value in force. The check is a
|
||||
pre-layer comparison on the live path (`boot.applyRuntimeResourceUpdate` in
|
||||
`internal/app/archied/control_plane.go`), not an addition to
|
||||
`validatePluginSettings` in `internal/app/controlplane/operational_settings.go`,
|
||||
which stays value-agnostic per the #1143 decision recorded there: a
|
||||
change-immutability rule needs the running config, and #1143's validates-nothing
|
||||
still holds for values. The write lands, the store keeps the version, the daemon
|
||||
publishes nothing, the refusal is reported against that stored version, and
|
||||
last-known-good keeps running.
|
||||
|
||||
The layering assigns all four directories from one document, so a refused
|
||||
`skills_dir` refuses the whole document and the other kinds still layer. That is
|
||||
acceptable: `skills_dir` is the one field with no live consumer, a
|
||||
whole-document refusal is the honest signal that none of it took effect, and an
|
||||
operator changing `skills_dir` alongside another directory writes the two
|
||||
changes separately.
|
||||
|
||||
## Apply status
|
||||
|
||||
One record per process: `archied` on `plugin-settings`, reported against the
|
||||
version the process is running. The record's error field carries the outstanding
|
||||
problem: a deleted file still running, a file that failed to load, the directory
|
||||
failing to read, or a refused replace of a module another running module depends
|
||||
on. A clean reconciliation clears the error. An add that succeeded is live even
|
||||
while a removal is outstanding, and the error says so rather than showing the
|
||||
kind as restart-required.
|
||||
|
||||
`ApplyMode` becomes `live`, so `RestartPendingBanner` no longer names
|
||||
`plugin-settings`. The gateway's lag is shown instead by the per-process
|
||||
applied-version rows on the Plugins page, which read the state
|
||||
`applyStatusForKind` derives from `applied_version < storedVersion` in
|
||||
`ui/src/stores/control-plane.ts`; that derivation is independent of
|
||||
`ApplyMode`.
|
||||
|
||||
`archie-gateway` layers the `plugin-settings` document at boot through
|
||||
`boot.loadRuntimeConfig` and reports it, but never calls `boot.loadPlugins` or
|
||||
`boot.loadModules` and never reads the four directories, so it loads no plugin,
|
||||
module or secret engine. With no live watch its row lags the stored version
|
||||
until restart; that lag is a reporting lag, not a behaviour gap.
|
||||
|
||||
## Verification
|
||||
|
||||
- A plugin, module and secret-engine file dropped while the daemon runs loads on
|
||||
the next tick; an unchanged file is not reloaded.
|
||||
- An edited file replaces the running interpretation; a deleted file leaves the
|
||||
running code running, with the process's error naming it until restart.
|
||||
- A `skills_dir` change refuses the document: the store keeps the version, the
|
||||
record carries that version and the refusal, and the running `skills_dir` is
|
||||
unchanged.
|
||||
- A plugin replacement whose new `Start` fails restarts the old module and
|
||||
reports the failure; a replacement of a depended-on module is refused and the
|
||||
dependent keeps running.
|
||||
- A provider disabled at boot for a missing engine resolves again after the
|
||||
engine file loads and a tick re-layers.
|
||||
- The gateway reports the last version it layered at boot, loads no directory,
|
||||
and its lag appears in its applied-version row rather than the restart banner.
|
||||
@@ -0,0 +1,213 @@
|
||||
# PR review agent
|
||||
|
||||
**Status:** Approved
|
||||
**Authority:** `docs/architecture/agent-system.md`; supersedes the reviewer
|
||||
executor and blocking rule in `docs/architecture/adversarial-review.md`, and
|
||||
the designs in `docs/prds/operator-pr-review.md` and
|
||||
`docs/prds/review-calibration.md`.
|
||||
**Compounds with:** `docs/prds/execution-tree-state-machine.md` (every agent
|
||||
call is a StepExecution), `docs/prds/external-agent-harness.md` (any agent
|
||||
step may run on a harness), `docs/prds/inline-review.md` (posting),
|
||||
`docs/prds/pr-review-remediation.md` (consumes the findings).
|
||||
|
||||
## Decision
|
||||
|
||||
Archie ships a pull request reviewer as its first end-to-end product. It
|
||||
reviews any pull request on a watched repository, a PR an operator names, and
|
||||
archie's own PRs before they open.
|
||||
|
||||
The reviewer is a fixed pipeline, not a single agent. The review strategy is
|
||||
generated per PR: three lens agents propose review dimensions from the PR's
|
||||
content, one reviewer definition runs once per dimension, and later agents
|
||||
verify, challenge and combine the findings. Everything that can be computed
|
||||
is code: diff parsing, clustering, blast radius, evidence extraction,
|
||||
scoring, deduplication, line mapping and the review event.
|
||||
|
||||
The pipeline is **recall-first**. It posts every evidenced finding above the
|
||||
confidence threshold, up to the comment cap. A precision gate exists as an
|
||||
operator dial and is off by default.
|
||||
|
||||
Acceptance is measured, not asserted: see Verification.
|
||||
|
||||
## Pipeline
|
||||
|
||||
Each numbered phase is a stage of the `pr-review` workflow. Each agent call is
|
||||
an `agent` StepExecution; fan-out phases record one child per call.
|
||||
|
||||
1. **Intake.** Code reads the PR metadata and diff statistics: type,
|
||||
complexity, languages, areas touched, risk signals. Depth comes from lines
|
||||
changed: under 100 is `quick` (at most 3 dimensions), under 500 is
|
||||
`standard` (6), otherwise `deep` (12). An operator may set depth
|
||||
explicitly.
|
||||
2. **Anatomy.** Code parses the diff into files and hunks, clusters related
|
||||
files, and computes the blast radius: unchanged files that import or are
|
||||
imported by changed files. One agent writes the PR narrative, risk
|
||||
surfaces, changes that do not fit the narrative, and gaps between the
|
||||
description and the diff.
|
||||
3. **Dimension selection.** Three lens agents run in parallel over the intake
|
||||
(including its machine-written score), anatomy and diff, each able to read
|
||||
the repository. A PR that intake scores as likely machine-written adds a
|
||||
hallucination-check dimension: claims, citations and behaviour the diff
|
||||
does not actually implement.
|
||||
- **behaviour:** where the old and new code diverge for any input; API
|
||||
contracts, concurrency and state, security, error handling, data flow;
|
||||
- **mechanics:** whether the code runs at the language and framework
|
||||
level; types, signatures and every caller, decorators and middleware,
|
||||
framework contracts, imports;
|
||||
- **fit:** patterns, complexity, abstraction, test adequacy, documentation
|
||||
that no longer matches, dependencies, migration completeness.
|
||||
|
||||
Each lens returns review dimensions: a name, a reviewer prompt written for
|
||||
this PR, target files, context files and a priority. Code merges them,
|
||||
drops duplicates and keeps the highest-priority dimensions up to the
|
||||
depth's cap.
|
||||
4. **Review.** One reviewer definition runs once per dimension, in parallel,
|
||||
at most 8 at a time. Each reads its target and context files and may
|
||||
follow references. Each finding carries file, line range, severity
|
||||
(`critical`, `important`, `suggestion`, `nitpick`), title, body, an
|
||||
optional suggested fix, quoted evidence, confidence and tags. A reviewer
|
||||
that exhausts its turn cap or deadline before its terminal tool call
|
||||
records a distinct StepExecution status from a reviewer that completed
|
||||
and found nothing; synthesis and the posted review treat the two
|
||||
differently (the former is unreviewed, the latter is reviewed-clean).
|
||||
5. **Verification layer**, over the review findings:
|
||||
- code extracts an evidence package per finding: the code at the cited
|
||||
lines and snippets from its callers;
|
||||
- an evidence verifier checks high-priority findings against their
|
||||
packages;
|
||||
- an adversary confirms or challenges each finding, looks for issues every
|
||||
reviewer missed, and is more sceptical when intake scores the PR as
|
||||
likely machine-written;
|
||||
- a compound agent looks, within each cluster of confirmed findings, for
|
||||
defects that only exist in combination.
|
||||
6. **Coverage and consistency**, in parallel:
|
||||
- a coverage gate checks every cluster and high-exposure blast-radius file
|
||||
was reviewed, and runs gap reviewers for what was not, at most 2 rounds;
|
||||
- consistency verification lists every cross-location obligation the
|
||||
changed code creates (what must be true elsewhere for this line to be
|
||||
correct), then verifies each by reading both ends. A broken obligation
|
||||
becomes a finding.
|
||||
7. **Synthesis**, code only:
|
||||
- score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:
|
||||
compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely
|
||||
machine-written PR 1.2, blast radius over 10 files 1.2;
|
||||
- drop findings under the severity's confidence floor: critical 0.2,
|
||||
important 0.3, suggestion 0.4, nitpick 0.4;
|
||||
- merge exact duplicates (file, overlapping lines, category) in code, and
|
||||
near-duplicates through a small classification call that keeps both
|
||||
when unsure;
|
||||
- map lines to the diff's coordinates, sort by score, cap at 25 inline
|
||||
comments.
|
||||
8. **Merge gate.** One classification call per finding decides blocking or
|
||||
advisory: blocking only for broken builds, security, data loss, contract
|
||||
breaks and regressions. A failed call means advisory.
|
||||
9. **Output.** One call per comment tightens its wording, running in a
|
||||
bounded pool at most 8 at a time (matching phase 4), keeping the original
|
||||
on failure. The review is posted as one forge review with inline
|
||||
comments. Any blocking finding requests changes; otherwise the review is a
|
||||
comment. Archie never posts an approval.
|
||||
|
||||
## Precision dial
|
||||
|
||||
With `review.precision_gate = true`, a post-worthiness pass runs after phase 4
|
||||
and before the verification layer. It keeps every concrete, evidenced defect
|
||||
and drops nitpicks, style and unverifiable claims, keeping a finding when
|
||||
unsure. It trades recall for precision and cuts verification cost by
|
||||
filtering early.
|
||||
|
||||
## Operator approval
|
||||
|
||||
With `review.approve_before_post = true`, synthesis ends in
|
||||
`waiting_human`. The operator chooses which findings to post, rejects the
|
||||
review, or asks for a re-review with instructions. A re-review reruns phases
|
||||
3 to 8 with the instructions added to the lens and reviewer prompts, at most
|
||||
2 times. A review with no findings posts nothing and does not wait. The gate
|
||||
belongs to the standalone `pr-review` workflow only; archie's own-PR stage list
|
||||
drops it, because a park there would end an implement run before its PR
|
||||
exists (`docs/prds/pr-review-operator-response.md`,
|
||||
"The gate is not reachable from archie's own PRs").
|
||||
|
||||
## Isolation
|
||||
|
||||
Every agent in the pipeline reads a `.git`-free snapshot of the PR head, with
|
||||
read-only tools rooted at it, and never the implementer's worktree or
|
||||
transcript. No pipeline agent holds a forge credential; posting is code.
|
||||
|
||||
## Budget
|
||||
|
||||
A run has a cost cap and a wall-clock cap, split into per-phase shares. A
|
||||
phase whose share is spent is skipped and recorded on its StepExecution. The
|
||||
posted review names every skipped phase, so an exhausted run never reads as a
|
||||
clean one. A run whose review stage fails posts nothing and
|
||||
fails.
|
||||
|
||||
## Triggers
|
||||
|
||||
- **Watched repositories:** a PR opened or updated on a repository with
|
||||
`review.enabled` starts a run. An update cancels the in-flight run for the
|
||||
same PR.
|
||||
- **Operator:** a PR URL from the dashboard or chat starts a run on any
|
||||
repository the identity can read.
|
||||
- **Archie's own PRs:** the implement workflow runs the pipeline before
|
||||
opening its PR. A blocking finding the adversary did not challenge parks
|
||||
the task with the findings. A pipeline that fails parks the task. Advisory
|
||||
findings are posted after the PR opens.
|
||||
|
||||
## Organisations
|
||||
|
||||
The reviewer is a workflow, so `docs/prds/orgs-and-access.md` applies to it
|
||||
unchanged: it runs as the workflow's identity under the run credential, reads
|
||||
only repositories that identity may read, and posts through the forge RPC
|
||||
under that credential. A watched repository belongs to a workspace, and its
|
||||
PR events start reviews through that workspace's bindings. Findings,
|
||||
StepExecutions and the posted review carry the run's org and workspace.
|
||||
|
||||
## Models
|
||||
|
||||
Each agent phase names a model role. Lens, reviewer, verification,
|
||||
adversary, compound and consistency agents use the review role. Intake,
|
||||
coverage, dedup, merge gate and polish calls use the classification role.
|
||||
Either role may run on the built-in runner or a harness.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- SARIF and standalone report formats. The findings are StepExecution outputs
|
||||
and the forge review.
|
||||
- Reviewing a diff without a forge PR.
|
||||
- Self-consistency reruns.
|
||||
|
||||
## Plan
|
||||
|
||||
1. Deterministic core: diff parsing, clustering, blast radius, evidence
|
||||
extraction, scoring, dedup, line mapping, review event. Table-driven tests.
|
||||
2. The benchmark harness (Verification), run against the deterministic core
|
||||
with fixture findings.
|
||||
3. `pr-review` workflow: intake, anatomy, lenses, reviewers, synthesis,
|
||||
output, with the execution tree recording each call.
|
||||
4. Verification layer, coverage loop and consistency verification.
|
||||
5. Merge gate, polish, budget shares and skipped-phase reporting.
|
||||
6. Benchmark acceptance run.
|
||||
7. Triggers: operator, watched repositories, archie's own PRs replacing the
|
||||
single-reviewer stage.
|
||||
8. Precision dial and operator approval.
|
||||
|
||||
## Verification
|
||||
|
||||
- **Benchmark acceptance.** On the 38 runnable PRs of the Martian
|
||||
Code-Review-Bench offline set, one blind run per PR at `deep` with the
|
||||
review and classification roles on GLM-5.2, and an independent judge
|
||||
(`anthropic/claude-sonnet-4.6`) matching posted comments to golden
|
||||
comments: golden micro-recall is at least 0.70. Golden-only precision is
|
||||
reported alongside it. The run is reproducible from a script in the
|
||||
repository.
|
||||
- Scoring, thresholds, dedup and line mapping give identical output for
|
||||
identical findings.
|
||||
- A run whose phase share is exhausted posts a review naming the skipped
|
||||
phase.
|
||||
- An update to a PR under review cancels the running review and its child
|
||||
steps.
|
||||
- No pipeline agent can write to the snapshot, and none can reach a forge
|
||||
credential.
|
||||
- Archie's own PR with an unchallenged blocking finding is parked, not
|
||||
opened.
|
||||
- Archie never submits an approving review.
|
||||
@@ -0,0 +1,69 @@
|
||||
# PR review: the operator's answer to the approval gate
|
||||
|
||||
**Status:** Draft
|
||||
**Authority:** `docs/prds/pr-review-agent.md` ("Operator approval") for the gate, and `docs/prds/state-store-contract.md` (rev. 2e) for every task field that crosses the State Store.
|
||||
**Compounds with:** `docs/prds/execution-tree-state-machine.md` (a run cannot resume partway through its stage list).
|
||||
|
||||
## Decision 1 — where the operator answers
|
||||
|
||||
The dashboard's `POST /api/tasks/{id}/action` (`internal/webui/api_tasks.go`, `handleTaskAction`) is the authoritative surface: the only one that resolves the actor from a credential and can carry a payload. Chat is a shortcut, not a second authority — `/approve` (`internal/gateway/gateway.go`, `Router.handleApprove`) answers the post decision with every offered finding selected, and gains no instruction or selection syntax.
|
||||
|
||||
`taskstate.Action` gains `rereview`, and `taskstate.Actions` returns `approve`, `reject` and `rereview` for `WaitingHuman`. `approve` posts the review, `reject` discards it through the existing terminal decline, `rereview` reruns the review phases with instructions. The action body carries `instructions`, required by `rereview`, and `findings`, the finding keys `approve` posts; an absent selection means all of them.
|
||||
|
||||
The path is `handleTaskAction` → `applyOperatorTaskAction` → `Chat.Contract.ApplyOperatorTaskAction` → the daemon's `LocalChatAdapter` → `taskactions.Client` (NATS `archie.gateway.task-action`) → `taskactions.Service.Apply` → one guarded store write that records the decision and requeues. Chat's `/approve` path (`StoreTaskController.Approve` → `chatTaskControllerAdapter.ApproveChatTask`) must reach that same write through the same function, so the two surfaces cannot record different decisions for one operator intent.
|
||||
|
||||
A requeue resumes the workflow the waiting state names, never a name the handler hardcodes. `taskactions.Service.apply` and `chatTaskControllerAdapter.ApproveChatTask` requeue with an empty workflow, which `Requeue` reads as "keep the task's", so neither surface hardcodes a workflow name: an approval whose wait recorded `pr-review` resumes `pr-review`. The feasibility handoff therefore has to name `implement` on the task before it enters the wait, which is the invariant the handler relies on — the workflow a task carries is the workflow it runs next. `Requeue` treats an empty workflow as "keep the task's".
|
||||
|
||||
### The review the operator answers
|
||||
|
||||
The gate writes the review it is holding onto the task before it ends the run: one JSON column, `review_gate`, a sibling of `review_payload`, holding the scored findings, the head SHA, the pull request's identity and the workflow the wait resumes. The run's existing `Store.Update` persists it. The same column carries the answer back: the response path's guarded write fills in the outcome, the selection and the instructions, and clears the offer for a re-review.
|
||||
|
||||
The operator reads the offer through the existing task read — `taskView.Task` on `GET /api/tasks` and `GET /api/tasks/{id}/debug` — so no new read endpoint is needed.
|
||||
|
||||
This record is load-bearing because the run that computed the findings ends at the gate and the engine cannot resume it partway. Without it, "post the selected findings" cannot mean the findings the operator saw: the resumed run recomputes them with agent calls. An `approve` resume therefore posts the recorded review filtered by the selection, and the review the resumed phases recompute never reaches the output.
|
||||
|
||||
## Decision 2 — the cap
|
||||
|
||||
The cap is a column: `rereview_rounds` on `tasks`, `bigint NOT NULL DEFAULT 0`, read by the response path and incremented in the same guarded write that requeues a re-review. A re-review at the cap is refused with the conflict sentinel the dashboard answers 409 with, and nothing is requeued. Two is a constant in the domain, not a config knob: the PRD fixes it.
|
||||
|
||||
`Task.Attempt` cannot carry the count, because it counts every requeue. The two alternatives are worse.
|
||||
|
||||
- The execution tree measures passes through the gate, not operator requests. A crash recovery (`RecoverStale`) or an operator retry re-runs the pipeline to the gate and would consume the cap; and a stage has no step read (`task.Store` carries none), so this route needs a new interface method anyway.
|
||||
- `Task.Notes` is the agent memory ledger, not scratch. `AgentStage.buildRequest` passes it into every generic agent request, `agentexec` renders it as a prompt section, and `persistAppendedNotes` appends to it. A counter parsed out of a field agents write to is the encoded-state defect this repository rejects, and instructions parked there would reach every unrelated workflow's agents.
|
||||
|
||||
`RemediationRounds` is the precedent: one writer, one reader, one meaning, kept separate from `RetryCount` so unrelated retries cannot draw a budget down.
|
||||
|
||||
The write crosses the State Store. A goose migration adds the column; `internal/infrastructure/postgres/queries/tasks.sql` and its sqlc output carry it; `internal/infrastructure/postgres/store.go` maps it; `proto/state/v1/state.proto` carries it as a new `Task` field with its regenerated contracts and `staterpc/values.go` mapping both ways; `internal/domain/workflow/task/task.go` declares it; `internal/infrastructure/taskactions/store.go` adds it to the `taskactions.Task` projection the response path reads. The write itself is a guarded requeue method beside `RetryTask`, which increments a counter, and `BeginRemediation`, which records a payload in the same transaction: one transition-table guard, one increment and one requeue in one write. It must join every column-listing query, which `docs/development/state-store.md` names.
|
||||
|
||||
Tests that prove it: the guarded write increments for a re-review and for no other requeue; a re-review at the cap is refused and leaves the task waiting; and the field survives the wire, which `TestTaskProtoCarriesEveryDomainField` asserts for every field of the domain task.
|
||||
|
||||
## Decision 3 — how the instructions reach the stages
|
||||
|
||||
The recorded instructions enter the pipeline at phase 3 and phase 4 only, which is what the PRD asks for: a labelled operator-instructions block appended to `runLens`'s mission in `stagePRLenses` and to `runReviewer`'s mission.
|
||||
|
||||
They cannot ride `AgentStage.buildRequest`. Every pr-review stage builds its `agentexec.Request` in `runPRReviewAgentRecorded`, which sets no `Request.Notes`, so nothing the generic path threads reaches these calls. The pipeline restores the instructions from the task record at the same point it restores the review, and the two mission builders read them there.
|
||||
|
||||
## The gate is not reachable from archie's own PRs
|
||||
|
||||
`StagePRReviewAndOpenPR` splices `prReviewDecisionStages()`, the list `PRReview()` uses, so the gate is reachable from the implement workflow too. It must not be. The change is one entry moving: `stagePROperatorApproval()` leaves the shared list for `PRReview()`'s own stage list, immediately before the merge gate, and the own-PR splice keeps taking the shared list unchanged. This is a prerequisite for the response channel and a change of its own.
|
||||
|
||||
Three reasons, the second deciding it alone.
|
||||
|
||||
- The gate's question is which findings to post, and on archie's own PRs there is no pull request to post to at the point the splice reaches the gate. That trigger's human decision point is its park on an unchallenged blocking finding.
|
||||
- Approving a wait inside the implement workflow re-enters that workflow at its first stage against a worktree that already carries the change. A builder that then reports no changes sets `BuildNoChanges`, `StageCommitPush` calls `closeNoChangesIssue`, and the issue is closed with no pull request ever opened. Nothing the gate decides is worth a route to silently closing an issue.
|
||||
- Short-circuiting instead would put a conditional no-op in every stage whose work a wait had completed, which changes the resume semantics of the whole pipeline rather than this gate.
|
||||
|
||||
## What a full restart gives, and what it costs
|
||||
|
||||
A requeue re-runs the workflow's stage list from its first stage; the engine has no partway resume. That satisfies the PRD's "reruns phases 3 to 8" for free, and it is acceptable for the standalone pipeline precisely because that pipeline has no stage that writes and then closes. The costs:
|
||||
|
||||
- Phases 1 and 2 recompute. Both are code except two agent calls — the machine-written score and the anatomy narrative — so those re-run, and a changed score can change whether the hallucination-check dimension is added.
|
||||
- The pull request's snapshot is checked out again.
|
||||
- The run's cost and wall-clock budgets are per attempt, so a re-review starts with a fresh allowance, which the cap bounds.
|
||||
|
||||
## Verification
|
||||
|
||||
- A gate wait on the standalone `pr-review` workflow answered `approve` posts exactly the findings the operator selected, and no finding the resumed phases produced.
|
||||
- A re-review at the cap is refused, the task stays waiting, and the count survives a store round trip.
|
||||
- A re-review's instructions reach the lens and reviewer missions; a first run's do not.
|
||||
- The gate is unreachable from the implement workflow's stage list.
|
||||
@@ -3,6 +3,8 @@
|
||||
**Status:** Draft
|
||||
**Beads issue:** `archie-core-h019.5` (parent `archie-core-h019`)
|
||||
|
||||
> Superseded by `docs/prds/pr-review-agent.md`.
|
||||
|
||||
Decides the half of calibration `docs/prds/adversarial-self-review.md` left
|
||||
open: "the adversarial-confirmation mechanism that keeps a finding from
|
||||
surfacing on a single reviewer's say-so."
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# Review settings resource
|
||||
|
||||
**Status:** Draft
|
||||
**Beads issue:** `archie-core-0ry6`
|
||||
**Authority:** `docs/prds/runtime-control-plane.md` for the resource model,
|
||||
`docs/architecture/configuration.md` for ownership, and
|
||||
`docs/prds/pr-review-agent.md` for what the two dials do.
|
||||
|
||||
## Decision
|
||||
|
||||
`review.precision_gate` and `review.approve_before_post` are one control-plane
|
||||
resource, `review-settings`. The file's `[review]` section seeds it, the stored
|
||||
document outranks the file from then on, and the dashboard writes it through the
|
||||
same settings machinery as every other resource.
|
||||
|
||||
The resource is deployment-wide, like every definition the State Store seeds
|
||||
(`storecontract.DefaultOrgID`): not per-repository, per-identity, or per-run.
|
||||
|
||||
## Why its own kind
|
||||
|
||||
The two dials are pr-review policy — what a review may post, and whether a human
|
||||
decides — not a limit on a task run. The document that carries task limits
|
||||
belongs to that feature. `runtime-control-plane.md` splits settings by feature
|
||||
and refuses documents unrelated features share; `configuration.md` puts a typed
|
||||
runtime setting with the domain whose behaviour it describes. One document per
|
||||
feature is the rule, not one document per settings page.
|
||||
|
||||
A new kind also has no legacy documents. Its first value is the seed derived
|
||||
from the file, so "the store outranks the file" begins from an explicit copy of
|
||||
both fields rather than from a document that predates them.
|
||||
|
||||
## Document
|
||||
|
||||
New file `internal/app/controlplane/review_settings.go`:
|
||||
|
||||
```go
|
||||
const ReviewSettingsKind = "review-settings"
|
||||
|
||||
type reviewSettings struct {
|
||||
PrecisionGate bool `json:"precision_gate"`
|
||||
ApproveBeforePost bool `json:"approve_before_post"`
|
||||
}
|
||||
```
|
||||
|
||||
Its `Definition` sets `ApplyMode: "live"`, `Document: reviewSettings{}`, and a
|
||||
`Seed` returning `reviewSettings{cfg.Review.PrecisionGate, cfg.Review.ApproveBeforePost}`,
|
||||
and a `Validate` wrapping `validateAs`: both fields are free booleans with no cross-field
|
||||
rule, so the validator is a named place to put one rather than an inline no-op
|
||||
(`validatePluginSettings` is the precedent). No `Normalize`, because the kind
|
||||
has no second wire shape to converge.
|
||||
|
||||
## Seeding
|
||||
|
||||
`ImportConfig`/`seededValues` write the seed for a kind the store does not hold,
|
||||
so a deployment that never edited the dials runs the values in `[review]`. Once
|
||||
a document is stored, the file key stops mattering, which is the rule for every
|
||||
database-owned setting.
|
||||
|
||||
## Apply
|
||||
|
||||
`runtimeConfigFrom` in `internal/app/controlplane/runtime_config.go` layers the
|
||||
stored document over the file's `Review`, assigning `out.Review.PrecisionGate`
|
||||
and `out.Review.ApproveBeforePost` field by field. Field-by-field, not
|
||||
`out.Review = ...`: a field added to `config.Review` later keeps the file's value
|
||||
until the document carries it.
|
||||
|
||||
`ReviewSettingsKind` joins `runtimeResourceKinds` in
|
||||
`internal/app/archied/control_plane.go`, so a new stored version re-runs the
|
||||
layering and republishes through `config.Holder`. Live rather than
|
||||
restart-required, because every consumer re-reads it: `Review` is on
|
||||
`reloadableFields` in `internal/app/archied/reload.go`, and the value reaches a
|
||||
run through `Daemon.configFor` → `Config.ForTask` → `TaskConfig.ToConfig` →
|
||||
`TaskContext.Cfg`, which `stagePRPrecisionGate` and `stagePROperatorApproval`
|
||||
read. The next task run uses the new value; a run in flight keeps the value it
|
||||
started with.
|
||||
|
||||
## Projection and page
|
||||
|
||||
`BuildConfigView` gains a plain `Review` field carrying both values out of
|
||||
`cfg.Review`, the way `BudgetsView` carries the layered budgets, so the published
|
||||
config snapshot tells any reader what is in force. The Review page renders the
|
||||
two toggles from the control-plane store's draft for `review-settings` — the
|
||||
shape `SystemTasksPage.vue` uses for `workflow-execution-settings` — and shows
|
||||
the projected value beside them; a Settings route plus a `PAGE_RESOURCES` entry
|
||||
(`ui/src/stores/control-plane.ts`) bind the page to the kind.
|
||||
|
||||
Nothing else re-advertises them. `configFieldDescriptors` and `ConfigView.Schema`
|
||||
gain no `review.*` row: the config catalog's generic renderer was deleted, so a
|
||||
descriptor row adds a field nothing can edit, which is the shape `becb0b5e`
|
||||
removed.
|
||||
|
||||
## What the test proves
|
||||
|
||||
`internal/app/controlplane/runtime_config_test.go` adds the round trip that
|
||||
builds the effective config the way boot does: seed the kind from a file config
|
||||
with both dials set one way, store a document with both flipped, layer it
|
||||
through `runtimeConfigFrom`, and assert the effective `cfg.Review` equals the
|
||||
stored document. A second case covers the absent kind, where the file's values
|
||||
stay in effect. The assertion is on `cfg.Review` — the value `TaskContext.Cfg`
|
||||
carries into the two stages — not on a struct the test set directly.
|
||||
`TestRuntimeResourceKindsApplyLive` gains `review-settings` as live. The
|
||||
validator needs no `validators_agree_test.go` case: it wraps `validateAs` with
|
||||
no rule, because no combination of the two booleans is invalid, and a case that
|
||||
cannot fail is a test the project then carries for nothing.
|
||||
|
||||
## Rejected: extending workflow-execution-settings
|
||||
|
||||
That resource is `workflow.ExecutionSettings`, "the limits captured when a
|
||||
workflow execution starts". Putting review policy in it makes the review feature
|
||||
a field of the limits document, gives a boolean edit a ride on a document whose
|
||||
candidate is validated and swapped as one unit with the budgets, and forces
|
||||
absence-aware pointer fields onto booleans so a document stored before the fields
|
||||
existed does not turn a file's `precision_gate = true` into `false`. It buys one
|
||||
less kind at the cost of the ownership rule the model is built on.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Per-repository, per-identity, or per-workflow review settings. A scope key is
|
||||
a later decision with its own resource shape.
|
||||
- Any other review knob. A field joins the document only with a consumer, the
|
||||
rule every config field carries.
|
||||
- The reviewer pipeline's behaviour. This document places the settings; it does
|
||||
not change what they do.
|
||||
@@ -45,6 +45,14 @@ version being edited. The API layer sets the actor; the request body cannot.
|
||||
The server validates the change, then writes it with its audit record. It rejects
|
||||
edits to an old version.
|
||||
|
||||
The request ID is the write's idempotency key, and it is scoped per org and
|
||||
per kind, never global. The key is `(org_id, kind, request_id)` — the unique
|
||||
index `idx_resource_history_org_kind_request` (migration `0021_resources_per_org.sql`)
|
||||
— so replaying a request ID is the same org's prior write of the same kind, and
|
||||
a request ID reused across orgs or across kinds is a separate write. This is the
|
||||
same scoping as the task idempotency key `org/identity/owner/repo/number`
|
||||
(`docs/prds/orgs-and-access.md`).
|
||||
|
||||
## API
|
||||
|
||||
The API has four operations:
|
||||
@@ -76,8 +84,11 @@ and encryption-key references. State Store and control-plane RPCs use the same
|
||||
endpoint.
|
||||
|
||||
When upgraded, existing instances are migrated to the database. Existing
|
||||
database values are not overwritten. After migration, settings in TOML are
|
||||
ignored and cannot block State Store startup.
|
||||
database values are not overwritten, with one exception: a resource whose
|
||||
document the build ships is refreshed when the seed itself wrote the stored
|
||||
copy, because that copy is a previous release's document rather than an
|
||||
operator's. After migration, settings in TOML are ignored and cannot block
|
||||
State Store startup.
|
||||
|
||||
The Web UI remains available when `archied` or Gateway is down. It shows failed
|
||||
changes and can correct or roll them back.
|
||||
@@ -92,7 +103,10 @@ Users create and edit workflows in the Web UI. Workflows are stored as versioned
|
||||
YAML. Built-in workflows can be overridden and restored.
|
||||
|
||||
A workflow is a list of steps. Each step has a known type and its own settings.
|
||||
Plugins can add step types. Each run keeps the workflow version it started with.
|
||||
A step type is part of the build's step vocabulary, contributed as a provider at
|
||||
the composition root; interpreted plugins contribute none
|
||||
(`docs/prds/workflow-step-vocabulary.md`). Each run keeps the workflow version it
|
||||
started with.
|
||||
|
||||
Yaegi, `.archie/stages/*.go`, and `.archie/gate.go` will be removed. Their useful
|
||||
behaviour must first be available as normal workflow steps.
|
||||
|
||||
@@ -0,0 +1,142 @@
|
||||
# SOUL: an agent's user-authored personality
|
||||
|
||||
**Status:** Draft
|
||||
**Authority:** `docs/architecture/identity.md`, “Three-layer identity model”;
|
||||
`docs/prds/orgs-and-access.md` for identity and org ownership.
|
||||
|
||||
## Decision
|
||||
|
||||
SOUL supplies an agent's name, register and warmth. It belongs to the agent's
|
||||
immutable `IdentityID`, not its session, model, installation or container
|
||||
profile. Rename preserves it; changing a profile does not change who acts.
|
||||
SOUL never changes attribution, credentials, grants or identity lifecycle.
|
||||
`config.AgentProfile` remains an execution environment, not another identity.
|
||||
|
||||
Use the existing three layers: invariants, user-authored SOUL, and curator-derived
|
||||
representation. Curators may propose SOUL changes but never apply them.
|
||||
|
||||
## Files and ownership
|
||||
|
||||
The config directory is `${XDG_CONFIG_HOME:-~/.config}/archie`, or the directory
|
||||
of an explicitly selected config file. The default/root agent uses `SOUL.md`
|
||||
directly there; additional agents use `agents/<identity-id>/SOUL.md`. The root is
|
||||
the identity selected by application composition, never the initiating user or
|
||||
a session's personality selection. No file creates or selects an identity.
|
||||
|
||||
The common case keeps a human-friendly filename; additional agents get separate
|
||||
asset directories, following `.agents/skills/<name>/SKILL.md` without confusing
|
||||
these directories with `[containers.profiles.<name>]`. Reject display-name or
|
||||
slug directories: rename and same-name agents across orgs would require another
|
||||
name-resolution rule. Immutable IDs avoid both problems without an org directory.
|
||||
|
||||
When a file-owned agent's file is absent, create the shipped default with
|
||||
exclusive creation. Never overwrite an existing file, including an empty one.
|
||||
A creation failure still permits the turn using the embedded shipped default.
|
||||
Ship that document independently of `agent.ShippedPersonas`, so deleting personas
|
||||
cannot delete the fallback.
|
||||
|
||||
Resolve once at the start of every new generation:
|
||||
|
||||
1. A stored SOUL entry for the acting identity is authoritative.
|
||||
2. Without an entry, read that identity's file again.
|
||||
3. An absent, empty, unreadable or invalid selected source uses the shipped default.
|
||||
|
||||
The first explicit dashboard/API save takes ownership permanently. Thereafter
|
||||
file edits are ignored: emit one ownership notice and show the owning stored
|
||||
version in the dashboard. Restoring the shipped default writes a stored value;
|
||||
it does not remove ownership. Refuse writes that remove an owned entry.
|
||||
|
||||
This ownership boundary is the design's one stateful rule. Files seed the
|
||||
editable value, not an automatic durable import. Reject seed-once import because
|
||||
it breaks next-message file editing; reject file-always-wins because it makes
|
||||
dashboard saves ineffective. Neither a restart nor an upgrade overwrites an
|
||||
owned value, following the precedence of `controlplane.AgentProfileKind` without
|
||||
copying its startup import timing.
|
||||
|
||||
## Prompt and failure contract
|
||||
|
||||
Keep `archie.md.tpl`'s XML-escaped
|
||||
`<soul purpose="identity_and_style" trust="data">` block before
|
||||
`<instruction_precedence>`. SOUL is style reference data; the invariant sections,
|
||||
tool inventory and runtime metadata remain authoritative and uneditable.
|
||||
Preserve `TestBuildSystemPromptSoulCannotOverrideInvariants`.
|
||||
|
||||
Accept UTF-8 plain Markdown with at most 8 KiB in its XML-escaped body. This bounds
|
||||
personality to a small prompt contribution; count the complete rendered prompt
|
||||
in the turn's context budget and never truncate invariant sections. Bound file
|
||||
reads before decoding; reject oversize input rather than truncating instructions.
|
||||
File and stored writes use the same validator; an invalid save leaves the stored
|
||||
version unchanged. The shipped default must pass that validator.
|
||||
|
||||
Read and creation errors never fail a turn. Log once per identity/source failure
|
||||
episode, retry on the next turn, and allow a new warning after recovery. If the
|
||||
store cannot establish whether an owned entry exists, use the shipped default,
|
||||
not a potentially shadowed file. Do not log SOUL text. Each turn keeps its resolved
|
||||
snapshot; edits affect the next generation without restart or SIGHUP.
|
||||
|
||||
## Cross-layer delivery
|
||||
|
||||
- `internal/domain/agent` owns SOUL content validation and the identity-keyed read
|
||||
contract; `internal/domain/identity` remains the actor/lifecycle authority.
|
||||
- The configuration infrastructure resolves the config directory and handles
|
||||
file discovery, exclusive default creation and bounded per-turn reads.
|
||||
Application composition resolves the acting `IdentityID` through the existing
|
||||
identity repository/bindings and supplies it to the gateway.
|
||||
- Register `SoulKind` (`agent-souls`) in the control plane with a live descriptor
|
||||
and an org-scoped document mapping identity IDs to `{text}`. Persist it through
|
||||
the State Store's existing resource/history contracts, not a new table,
|
||||
process or SOUL RPC. An empty map owns no identity; saves preserve other entries
|
||||
and use expected-version checks. Validate that each key is an agent identity
|
||||
in the resource's org; begin with the default org without inventing org setup.
|
||||
Every save records the authenticated editor's identity, source, request ID and
|
||||
timestamp; file installation records the system identity, not a fictitious user.
|
||||
- Replace `TurnRunnerConfig.Personas` / `PersonaPromptSource` with the per-identity
|
||||
source in `prepareTurn`; name the `SystemPromptConfig` input SOUL. Both normal
|
||||
and streaming turns use this assembly path. Do not add personality to the
|
||||
worker environment, `AgentProfile` or workflow-stage prompts.
|
||||
- On an agent identity's dashboard page, expose its effective SOUL, file/default
|
||||
or stored source, shadowed file path, owning version, and Markdown editing.
|
||||
Save to the control plane, never the host file; show validation/version
|
||||
conflicts and offer restoring shipped content or a history revision as a save.
|
||||
Read effective file/default content and ownership metadata through a gateway
|
||||
query using the turn resolver; the separate UI process never reads the
|
||||
gateway host's files. Apply identity-management access rules and the existing
|
||||
shared live-update hub.
|
||||
- Update `docs/development/agent.md` and `control-plane.md` with this reach and
|
||||
precedence, `frontend-ui.md` with the gateway query, and the config wiring
|
||||
guidance with a copyable file example.
|
||||
|
||||
## Persona removal gate
|
||||
|
||||
SOUL supersedes `PersonaRegistry` and the persona-reconciliation proposal;
|
||||
identity-per-action supersedes personas as an identity mechanism.
|
||||
`PersonaRegistry.GetActive` composes the baseline with one of five styles from
|
||||
`agent.ShippedPersonas`; SOUL replaces the baseline, not that style catalogue.
|
||||
Per-session switching disappears: remove `/personality`, Telegram personality
|
||||
callbacks, the dashboard persona page, and chat wire fields `personas`,
|
||||
`active_personas` and `personas_available` without reusing their field numbers.
|
||||
Do not merge session selections into SOUL or retain a separate style axis.
|
||||
Custom persona text must remain available to copy before deleting its stored
|
||||
resource; no migration guesses one agent's SOUL from several sessions.
|
||||
|
||||
Remove persona loading, selectors and commands only after every chat composition
|
||||
supplies the identity-aware SOUL source, the fallback renders without personas,
|
||||
and the dashboard can edit it. SOUL delivery does not wait for org creation or a
|
||||
new container-profile model.
|
||||
|
||||
## Acceptance
|
||||
|
||||
- Two agents use distinct files and stored entries; renaming one or sharing a
|
||||
container profile does not change or mix their SOULs.
|
||||
- Before ownership, a file edit changes the next normal or streaming prompt;
|
||||
creating defaults never clobbers an existing file.
|
||||
- After a save, conflicting file edits and restarts cannot override the stored
|
||||
value; the ignored file and owning version are visible. Updating one agent
|
||||
preserves the other; stale saves fail and history restores are audited saves.
|
||||
- Missing, empty, unreadable, malformed and oversize selected inputs render the
|
||||
shipped default. Repeated read failures log once, recover on a later turn,
|
||||
and never abort generation.
|
||||
- Hostile markup stays escaped before singular, unchanged invariant blocks;
|
||||
prompt budgeting includes SOUL and cannot drop the rules.
|
||||
- Dashboard edits reach the next generation without restart; persona removal
|
||||
leaves every channel with a nonempty identity slot and preserved custom text.
|
||||
@@ -265,13 +265,15 @@ _view_, not new RPCs — `Update`/`Transition`/`InsertEvent` are shared with
|
||||
| Binding | `InsertBinding`, `GetBinding`, `ListBindings`, `UpdateBinding`, `DeleteBinding`, `ApproveBinding` |
|
||||
| Dispatch | `ArmedBindingsForSource`, `RecordDispatch`, `ListUndispatchedCaptures` |
|
||||
| Playbook | `RecordPlaybookDispatch`, `DeletePlaybookDispatches` |
|
||||
| WorkflowCaller | `EnqueueCallTask`, `WorkflowCallStatus` |
|
||||
| Step executions | `StartStep`, `FinishStep` |
|
||||
| BindingTaskCreator | `EnqueueBindingTask` |
|
||||
| Config snapshot | `PutConfigSnapshot`, `GetConfigSnapshot` |
|
||||
| Apply status | `PutApplyStatus`, `ListApplyStatus` |
|
||||
| Channel status | `PutChannelStatus`, `ListChannelStatus` |
|
||||
| Task log | `ReadTaskLog`, `StreamTaskLogContent` |
|
||||
|
||||
That is **51 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped).
|
||||
That is **55 unique contract RPCs** across one service (the `TaskEvents.Close` method is dropped).
|
||||
`Close()` is **excluded** from the wire (it is server lifecycle, not a client call) — see §11.
|
||||
|
||||
The channel-status pair follows the config snapshot's split for the same reason: the writer is the process that HOSTS the channels -- the Messaging Service, which alone observes whether a channel is starting, running or failed -- and the reader is the UI process. Both RPCs are administrative, so a task-scoped grant reaches neither. A channel's state is runtime state rather than a settings document, which is why it is not a `ControlPlaneService` resource kind: a failed channel is not a document anybody edits. Asking for a reload travels on its own surface rather than through this one; see `docs/architecture/migration-decisions.md`, "Channel state to the dashboard".
|
||||
@@ -306,6 +308,25 @@ condition, and the panel that collapsed them told operators task logging was swi
|
||||
it was not. The Go facade is `storecontract.TaskLogStore` (2 methods), carried by
|
||||
`*staterpc.Client` alongside the rest.
|
||||
|
||||
The step-execution pair was added by the execution tree's plan item 3 (see
|
||||
`docs/prds/execution-tree-state-machine.md`), the surface a task-scoped grant reaches for
|
||||
its own execution beyond the three `task.Store` RPCs and the workflow-caller pair: the
|
||||
container records its stages and its own agent calls with the run credential. Both requests
|
||||
carry the caller's execution ID, which the grant check verifies; `FinishStep` additionally
|
||||
verifies, handler-side, that the step really is that execution's. The store writes each
|
||||
transition's `stage_start`/`stage_finish` event row in the same transaction and returns it
|
||||
for the caller's post-commit bus publish. `called_execution_id` is stored for the `call`
|
||||
kind but not yet carried on the wire: the named consumer is the workflow-call recording
|
||||
that will set it.
|
||||
|
||||
The workflow-caller pair was added by `archie-core-t2db.41` (see everything else from the caller's
|
||||
row and refuses a caller that is not running or a call past the depth limit
|
||||
(`ErrCallCallerNotRunning` / `ErrCallDepthExceeded`), and `WorkflowCallStatus`
|
||||
re-checks the parent-child relation against the row before answering
|
||||
(`ErrCallNotYours`), so the interceptor itself never reads the database. The
|
||||
facade is `workflow/task.Caller` (2 methods), carried by `*staterpc.Client`
|
||||
and the PostgreSQL store alike.
|
||||
|
||||
The playbook pair was added by `archie-core-t2db.17`'s implementation (see
|
||||
`docs/prds/eda-playbook-engine.md`, execution-time gap 2). It is administrative
|
||||
for the same reason as the config-snapshot and apply-status pairs, and
|
||||
@@ -551,9 +572,12 @@ stated explicitly rather than left implicit.
|
||||
cannot leave a grant valid indefinitely.
|
||||
- **Validation and scope (`.4.7`):** a gRPC interceptor (`staterpc.TaskGrants.UnaryInterceptor`)
|
||||
validates the token against the State Store's own issued-grant set; missing/unknown/expired →
|
||||
`codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all ~40
|
||||
RPCs), a task-scoped grant additionally authorises only `Update`/`Transition`/`InsertEvent` on
|
||||
its own task ID — every other RPC, including the streaming capture surface and
|
||||
`codes.Unauthenticated`. Unlike the daemon's own administrative token (full access to all RPCs),
|
||||
a task-scoped grant additionally authorises only `Update`/`Transition`/`InsertEvent` on
|
||||
its own task ID, plus the two workflow-caller RPCs naming that same task ID
|
||||
(`EnqueueCallTask`/`WorkflowCallStatus`, `docs/prds/workflow-calls.md` — the one
|
||||
sanctioned widening: the callee is the caller's child). Every other RPC, including the
|
||||
streaming capture surface and
|
||||
`RegisterTaskGrant`/`RevokeTaskGrant` themselves, is `codes.PermissionDenied` for a task-scoped
|
||||
caller. The token is carried in gRPC metadata, never in a URL.
|
||||
|
||||
|
||||
Loaded 100 of 989 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user