Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
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 |
No files matched your search
@@ -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 |
|
||||
@@ -175,6 +175,9 @@ looking at before reporting one:
|
||||
| `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`. |
|
||||
| `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` -- a profile change applies without a restart, unlike the rest of `[containers]`. |
|
||||
| `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
|
||||
|
||||
|
||||
@@ -5,6 +5,64 @@ release's per-component sections are labelled beneath its heading.
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
## [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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -288,6 +299,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 +341,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.
|
||||
@@ -11,3 +11,9 @@ 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).
|
||||
+1
-1
@@ -154,7 +154,7 @@ tasks:
|
||||
- bash tools/webhook-send.sh {{.CLI_ARGS}}
|
||||
|
||||
bench:prreview:
|
||||
desc: Score PR review findings on the Martian benchmark (-- -findings DIR; --help for flags)
|
||||
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}}
|
||||
|
||||
|
||||
@@ -20,13 +20,20 @@ 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 judge model")
|
||||
flag.StringVar(&opts.Fixtures, "findings", "", "directory of <problem id>.json findings to score")
|
||||
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", "prbench-out", "directory for per-problem results and summary.json")
|
||||
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, ",")
|
||||
}
|
||||
|
||||
@@ -355,7 +355,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)
|
||||
}
|
||||
@@ -485,7 +485,7 @@ func TestStateStoreRealProcessRestartRecovery(t *testing.T) {
|
||||
|
||||
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)
|
||||
}
|
||||
|
||||
@@ -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)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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())
|
||||
}
|
||||
+17
-5
@@ -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"
|
||||
@@ -446,10 +450,21 @@ target = "127.0.0.1:9090" # REQUIRED. The State Store gRPC address arch
|
||||
# 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: the workload Kit, then mixins, each pinned by digest.
|
||||
# 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>"]
|
||||
# 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:
|
||||
@@ -481,9 +496,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
|
||||
|
||||
@@ -311,9 +311,6 @@ implemented in different packages:
|
||||
|
||||
## Current workflow-feature hazards
|
||||
|
||||
- There is no enforced WorkflowExecution state machine. `Store.Transition`
|
||||
guards on the supplied `from` state but accepts any `from` to `to` pair. See
|
||||
`docs/prds/execution-tree-state-machine.md`.
|
||||
- State update and transition-history insertion are separate operations, so
|
||||
state and audit can diverge.
|
||||
- Callers frequently discard persistence and transition errors.
|
||||
|
||||
@@ -334,6 +334,18 @@ 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 and scheduling policy are `ApplyMode: live`
|
||||
(archie-core-zfb0.1): the daemon keeps a watch per kind 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. The kinds stay
|
||||
restart-required while a startup-built component still holds their value
|
||||
(tool, plugin, container and channel settings today); a kind joins the live
|
||||
list only with a consumer that re-reads it, and the model/provider half of
|
||||
it also rebuilds the gateway chat runtime's provider set and the chat model
|
||||
list the chat surfaces offer.
|
||||
|
||||
## Completion criteria
|
||||
|
||||
|
||||
@@ -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?
|
||||
@@ -16,7 +16,7 @@
|
||||
"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/",
|
||||
@@ -118,13 +118,13 @@
|
||||
"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`.\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 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.\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 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"
|
||||
},
|
||||
{
|
||||
"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/",
|
||||
@@ -136,13 +136,13 @@
|
||||
"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,7 +154,7 @@
|
||||
"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## 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\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/",
|
||||
@@ -232,7 +232,7 @@
|
||||
"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/",
|
||||
@@ -328,7 +328,7 @@
|
||||
"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, mounted read-only whatever the Kit asks. |\n| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |\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 the operator builds `FROM` or alongside the harness Kit. It is\nversioned image content, rewritten on every create, never state a run can\nmodify.\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 a Kit composition (the workload Kit pinned by digest, and zero or more\nmixin Kits) in place of a container image. 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\nProfiles are org resources in the State Store, so a Kit profile belongs to\none org, is granted to its workspaces like any profile, and applies without\na restart.\n\n## Organisations\n\n`docs/prds/Line truncated
|
||||
"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/",
|
||||
@@ -412,7 +412,7 @@
|
||||
"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 anatomy and diff, each able to read the repository:\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.\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 ends. A broken obligation\n becomes a finding.\n7. **Synthesis**, code only:\n - score = severity weight (1.0, 0.7, 0.3, 0.1) × confidence × multipliers:\n compound 1.5, adversary-confirmed 1.3, adversary-challenged 0.5, likely\n machine-written PR 1.2, blast radius over 10 files 1.2;\n - drop findings under the severity's confidence floor: critical 0.2,\n important 0.3, suggestion 0.4, nitpick 0.4;\n - merge exact duplicates (file, overlapping lines, category) in code, and\n nearLine truncated
|
||||
"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-remediation/",
|
||||
@@ -484,7 +484,7 @@
|
||||
"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.\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
|
||||
"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/",
|
||||
@@ -533,6 +533,12 @@
|
||||
"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-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
|
||||
}
|
||||
],
|
||||
"nav": [
|
||||
@@ -898,6 +904,10 @@
|
||||
{
|
||||
"title": "Webhook intake security -- decision",
|
||||
"url": "/dev/prds/webhook-intake-security/"
|
||||
},
|
||||
{
|
||||
"title": "Workflows calling workflows",
|
||||
"url": "/dev/prds/workflow-calls/"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -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/"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -25,16 +25,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
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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.
|
||||
@@ -39,3 +39,10 @@ vocabulary it registers, so both must see the same step types.
|
||||
behaviour.
|
||||
- Examples in `examples/workflows/` are parsed against the registered
|
||||
vocabulary by `TestExampleWorkflowsParse`. Add one for a new capability.
|
||||
|
||||
## 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.
|
||||
@@ -56,6 +56,8 @@
|
||||
"/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.5.0/": "/news/1.5.0/",
|
||||
"/news/archie/1.6.0/": "/news/1.6.0/",
|
||||
"/news/archie/1.7.0/": "/news/1.7.0/",
|
||||
@@ -129,6 +131,8 @@
|
||||
"/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.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,14 @@
|
||||
[
|
||||
{
|
||||
"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",
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -42,8 +42,8 @@ Archie is a partial Kit runtime. It implements these capability types:
|
||||
| `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, mounted read-only whatever the Kit asks. |
|
||||
| `agent-context@1` | Archie's stage instructions, delivered where the Kit declares. |
|
||||
| `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
|
||||
@@ -51,9 +51,9 @@ 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 the operator builds `FROM` or alongside the harness Kit. It is
|
||||
versioned image content, rewritten on every create, never state a run can
|
||||
modify.
|
||||
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
|
||||
|
||||
@@ -75,8 +75,9 @@ retry without a `resume` verb.
|
||||
|
||||
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 a Kit composition (the workload Kit pinned by digest, and zero or more
|
||||
mixin Kits) in place of a container image. Everything else about profiles
|
||||
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.
|
||||
|
||||
@@ -85,6 +86,19 @@ 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.
|
||||
|
||||
@@ -44,8 +44,11 @@ an `agent` StepExecution; fan-out phases record one child per call.
|
||||
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,
|
||||
anatomy and diff, each able to read the repository:
|
||||
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
|
||||
@@ -62,7 +65,11 @@ an `agent` StepExecution; fan-out phases record one child per call.
|
||||
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.
|
||||
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;
|
||||
@@ -94,8 +101,9 @@ an `agent` StepExecution; fan-out phases record one child per call.
|
||||
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, keeping the
|
||||
original on failure. The review is posted as one forge review with inline
|
||||
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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
|
||||
@@ -0,0 +1,128 @@
|
||||
# Workflows calling workflows
|
||||
|
||||
**Status:** Draft
|
||||
**Date:** 2026-09-26
|
||||
**Bead:** `archie-core-t2db.41`
|
||||
**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)
|
||||
|
||||
## The call, end to end
|
||||
|
||||
```
|
||||
caller run (in agent container)
|
||||
workflow.call step ──StartCall──▶ State Store EnqueueCallTask(caller, workflow, inputs)
|
||||
│ callee task row: org/identity/owner/repo
|
||||
│ derived from the caller row server-side
|
||||
▼
|
||||
callee task (queued, org of the caller)
|
||||
│ daemon claims, pins the callee's OWN
|
||||
│ definition → its OWN agent profile
|
||||
▼
|
||||
callee run (its own container, own tree)
|
||||
wait: true ──poll──▶ State Store WorkflowCallStatus(caller, callee)
|
||||
wait: false ──continue
|
||||
```
|
||||
|
||||
A `workflow.call` step starts the callee as a first-class task and, with
|
||||
`wait: true`, waits for its terminal state. The callee is never run "inside"
|
||||
the caller: it gets its own task row, its own pinned definition, its own
|
||||
profile, its own container, and its own outcome on its own run
|
||||
(`execution-tree-state-machine.md`).
|
||||
|
||||
## Save-time checks (the collection is the authority)
|
||||
|
||||
All semantic checks run in `workflow.ValidateDefinitionCollection`, the gate
|
||||
every save and load of the `workflow-definitions` resource passes through.
|
||||
A single-definition parse cannot see callees, so it validates shape only.
|
||||
|
||||
- **Callee exists.** A call to a workflow outside the collection is refused.
|
||||
- **Inputs checked.** A call value is a literal or a reference
|
||||
(`inputs.<name>`) to the calling workflow's declared input. References must
|
||||
name a declared input; the resolved type must satisfy the callee's declared
|
||||
type; unknown callee inputs are refused; a required callee input must be
|
||||
assigned.
|
||||
- **Self-calls refused.** The call graph over the collection is walked from
|
||||
every workflow; a workflow that reaches itself, directly or through other
|
||||
workflows, is refused with the cycle path. (Cycles can otherwise deadlock:
|
||||
`wait: true` callers hold their containers.)
|
||||
- **Repository.** `workflow.call` needs no repository, so it is legal in a
|
||||
`repository: none` workflow: the callee inherits the caller's task record
|
||||
(owner/repo/identity/org), and the callee's own `repository` mode decides
|
||||
whether its run clones.
|
||||
- **Org enablement** (bead `archie-core-t2db.42`): the single
|
||||
instance-wide collection the current model serves is what "enabled for
|
||||
the caller's org" resolves against — an undefined callee parks. The
|
||||
callee's org is derived from the caller's row, so a callee is never
|
||||
visible outside its caller's org. The per-org enable/disable catalogue
|
||||
lands with `archie-core-t2db.42` and becomes the one source of this
|
||||
predicate.
|
||||
|
||||
## Runtime
|
||||
|
||||
**Depth limit.** `workflow.MaxCallDepth` (5). The calling stage refuses a call
|
||||
that would exceed it; the store re-checks on insert (callee depth = caller
|
||||
depth + 1), so no path can enqueue past the limit.
|
||||
|
||||
**Starting the callee.** The caller runs inside a container whose task-scoped
|
||||
State Store grant authorizes only `Update`/`Transition`/`InsertEvent` on its
|
||||
own task — it can neither enqueue a task nor read another one. One new
|
||||
contract RPC starts the callee:
|
||||
|
||||
- `EnqueueCallTask(caller_task_id, workflow, inputs_json) → task`
|
||||
— the store reads the caller row, refuses a caller that is not `running`,
|
||||
refuses past the depth limit, and inserts the callee row deriving org,
|
||||
workspace, identity, owner, repo and a fresh synthetic issue number from
|
||||
the caller (the same org COALESCE `EnqueueIssue`/`InsertChatTask` use). The
|
||||
callee row carries `call_parent_task_id` and `call_depth`.
|
||||
|
||||
**Waiting on the callee.** One new read RPC returns a call's callee:
|
||||
|
||||
- `WorkflowCallStatus(caller_task_id, call_task_id) → (status, detail)` — the
|
||||
handler verifies `call_parent_task_id` matches, so a caller reads only its
|
||||
own callees, and returns the callee's status plus its latest transition
|
||||
detail (the callee's summary — the wait:true "outputs" until a structured
|
||||
outputs model lands).
|
||||
|
||||
Both RPCs are admitted to task-scoped grants on `caller_task_id == granted
|
||||
task ID` (`authorizesTaskScopedCall` gains two request-shape cases). This is
|
||||
the one sanctioned widening of a task grant: the callee is the caller's child,
|
||||
and starting it is the mechanism by which one event becomes several runs. The
|
||||
widenings stay request-shape checks; the parent-child authorization is a
|
||||
handler-side row check, so the interceptor never reads the database.
|
||||
|
||||
**Schema.** `tasks` gains `call_parent_task_id` (bigint, default 0) and
|
||||
`call_depth` (int, default 0); both cross the wire on the `Task` message.
|
||||
Columns default so existing writers and rows read as depth-0 root runs.
|
||||
|
||||
**The engine capability.** The workflow domain owns a consumer facade,
|
||||
`task.Caller` (2 methods), carried by `*staterpc.Client` and wired into
|
||||
`TaskContext.Calls` by the agent worker's composition root — the same shape
|
||||
as `workflow.Store`. A runner with no `Calls` capability fails a
|
||||
`workflow.call` step with a named error rather than pretending.
|
||||
|
||||
**Semantics.**
|
||||
|
||||
- `wait: false` — start, record a durable `workflow_call_started` event, and
|
||||
continue. The callee's outcome is reported on its own run.
|
||||
- `wait: true` — start, then poll `WorkflowCallStatus` (2 s, bounded by the
|
||||
task's wall clock) until the callee is terminal. `completed`, `pr_open` and
|
||||
`merged` succeed the step; `parked`, `failed`, `rejected`, `dead` and
|
||||
`closed_wont_do` fail it with the callee's detail in the error. A durable
|
||||
`workflow_call_finished` event carries the terminal status and detail.
|
||||
- The caller's own stage/attempt accounting is unchanged: the call is one
|
||||
stage that took as long as its callee.
|
||||
- A callee inherits the caller's task record but is otherwise independent:
|
||||
retry, park and cancel of the callee never rewrite the caller. Cancelling a
|
||||
caller cancels its callees through the operator action on each
|
||||
(`execution-tree-state-machine.md` "Cancellation"); until the tree state
|
||||
machine lands, a caller cancelled while waiting fails its stage and leaves
|
||||
the callee running — the same semantics as `wait: false`.
|
||||
|
||||
## What is deliberately not here
|
||||
|
||||
- **Declared outputs.** `wait: true` receives the callee's terminal detail,
|
||||
not structured outputs; the outputs model is its own bead.
|
||||
- **The StepExecution tree.** The `call` kind is designed for in
|
||||
`execution-tree-state-machine.md`; this design lands the behaviour without
|
||||
the per-step records.
|
||||
- **Per-org enablement** — bead `archie-core-t2db.42`'s catalogue is the
|
||||
source once it exists.
|
||||
@@ -57,8 +57,6 @@ require (
|
||||
github.com/nats-io/jwt/v2 v2.8.2 // indirect
|
||||
github.com/nats-io/nkeys v0.4.16 // indirect
|
||||
github.com/nats-io/nuid v1.0.1 // indirect
|
||||
github.com/opencontainers/go-digest v1.0.0 // indirect
|
||||
github.com/opencontainers/image-spec v1.1.1 // indirect
|
||||
github.com/pjbgf/sha1cd v0.6.0 // indirect
|
||||
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
|
||||
github.com/power-devops/perfstat v0.0.0-20260916203055-22a1a467d9f0 // indirect
|
||||
@@ -90,13 +88,13 @@ require (
|
||||
google.golang.org/genproto/googleapis/rpc v0.0.0-20260921155816-b14227669459 // indirect
|
||||
modernc.org/libc v1.77.1 // indirect
|
||||
modernc.org/sqlite v1.59.0 // indirect
|
||||
oras.land/oras-go/v2 v2.6.2 // indirect
|
||||
)
|
||||
|
||||
require (
|
||||
cel.dev/cel-go v0.32.0
|
||||
code.gitea.io/sdk/gitea v0.25.1
|
||||
github.com/BurntSushi/toml v1.6.0
|
||||
github.com/cedar-policy/cedar-go v1.8.0
|
||||
github.com/coreos/go-oidc/v3 v3.21.0
|
||||
github.com/docker/sandbox-kit-spec/v3 v3.0.0-m.6
|
||||
github.com/go-git/go-billy/v6 v6.0.0-alpha.2
|
||||
@@ -111,6 +109,8 @@ require (
|
||||
github.com/modelcontextprotocol/go-sdk v1.8.0
|
||||
github.com/nats-io/nats-server/v2 v2.15.0
|
||||
github.com/nats-io/nats.go v1.54.0
|
||||
github.com/opencontainers/go-digest v1.0.0
|
||||
github.com/opencontainers/image-spec v1.1.1
|
||||
github.com/pressly/goose/v3 v3.28.0
|
||||
github.com/samcharles93/ai-sdk v0.1.39
|
||||
github.com/testcontainers/testcontainers-go v0.44.0
|
||||
@@ -125,4 +125,5 @@ require (
|
||||
google.golang.org/grpc v1.85.0-dev.0.20260825072537-93e31b48545e
|
||||
google.golang.org/protobuf v1.36.12
|
||||
gopkg.in/yaml.v3 v3.0.1
|
||||
oras.land/oras-go/v2 v2.6.2
|
||||
)
|
||||
@@ -26,6 +26,8 @@ github.com/antlr4-go/antlr/v4 v4.13.1 h1:SqQKkuVZ+zWkMMNkjy5FZe5mr5WURWnlpmOuzYW
|
||||
github.com/antlr4-go/antlr/v4 v4.13.1/go.mod h1:GKmUxMtwp6ZgGwZSva4eWPC5mS6vUAmOABFgjdkM7Nw=
|
||||
github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5 h1:0CwZNZbxp69SHPdPJAN/hZIm0C4OItdklCFmMRWYpio=
|
||||
github.com/armon/go-socks5 v0.0.0-20160902184237-e75332964ef5/go.mod h1:wHh0iHkYZB8zMSxRWpUBQtwG5a7fFgvEO+odwuTv2gs=
|
||||
github.com/cedar-policy/cedar-go v1.8.0 h1:9gcU7EHXwHC2RMdpph68yTAkdB3behTTssC+kt4GoS8=
|
||||
github.com/cedar-policy/cedar-go v1.8.0/go.mod h1:h5+3CVW1oI5LXVskJG+my9TFCYI5yjh/+Ul3EJie6MI=
|
||||
github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
|
||||
github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
|
||||
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
|
||||
|
||||
@@ -41,10 +41,11 @@ func runAsHarnessUser(cmd *exec.Cmd, name string) error {
|
||||
}
|
||||
|
||||
// harnessCredential resolves a user name or "uid[:gid]" to a credential.
|
||||
// Root is refused whichever way it is named.
|
||||
// Root is refused whichever way it is named. IDs are bounded to 31 bits so
|
||||
// they convert to int for os.Chown on every platform.
|
||||
func harnessCredential(name string) (*syscall.Credential, error) {
|
||||
uidText, gidText, hasGid := strings.Cut(name, ":")
|
||||
uid, uidErr := strconv.ParseUint(uidText, 10, 32)
|
||||
uid, uidErr := strconv.ParseUint(uidText, 10, 31)
|
||||
var cred syscall.Credential
|
||||
if uidErr == nil {
|
||||
cred.Uid, cred.Gid = uint32(uid), uint32(uid)
|
||||
@@ -53,18 +54,18 @@ func harnessCredential(name string) (*syscall.Credential, error) {
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("harness user %q: %w", uidText, err)
|
||||
}
|
||||
id, err := strconv.ParseUint(u.Uid, 10, 32)
|
||||
id, err := strconv.ParseUint(u.Uid, 10, 31)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("harness user %q has non-numeric uid %q", uidText, u.Uid)
|
||||
}
|
||||
group, err := strconv.ParseUint(u.Gid, 10, 32)
|
||||
group, err := strconv.ParseUint(u.Gid, 10, 31)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("harness user %q has non-numeric gid %q", uidText, u.Gid)
|
||||
}
|
||||
cred.Uid, cred.Gid = uint32(id), uint32(group)
|
||||
}
|
||||
if hasGid {
|
||||
gid, err := strconv.ParseUint(gidText, 10, 32)
|
||||
gid, err := strconv.ParseUint(gidText, 10, 31)
|
||||
if err != nil {
|
||||
return nil, fmt.Errorf("harness group %q is not numeric", gidText)
|
||||
}
|
||||
|
||||
@@ -388,6 +388,8 @@ func TestHarnessUser(t *testing.T) {
|
||||
{"0", 0, 0, true},
|
||||
{"root", 0, 0, true},
|
||||
{"not-a-user-anywhere", 0, 0, true},
|
||||
{"2147483648", 0, 0, true},
|
||||
{"1000:2147483648", 0, 0, true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
cred, err := harnessCredential(tt.user)
|
||||
|
||||
@@ -6,7 +6,7 @@
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "04acf4c4-0c8d-4dd5-9d3a-a7a6df371224", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "ecbfdcf2-446c-4386-a89f-eeaf43e48b46", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "4c58406e-b5f0-49d7-af88-483c14212e0d", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "c10b3042-e990-49db-8937-954b6fe11570", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "a0cb320b-0bdd-45b5-90b5-451add28d1ed", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "3a3327f8-ad24-46d7-a194-e0ce68f9f871", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "CronCreate", "CronDelete", "CronList", "DesignSync", "Edit", "EnterWorktree", "ExitWorktree", "ListAgents", "ListMcpResourcesTool", "LSP", "Monitor", "NotebookEdit", "PushNotification", "Read", "ReadMcpResourceDirTool", "ReadMcpResourceTool", "RemoteTrigger", "ReportFindings", "ScheduleWakeup", "SendMessage", "Skill", "TaskStop", "ToolSearch", "WebFetch", "WebSearch", "Workflow", "Write", "mcp__claude_ai_Claude_Docs__batch", "mcp__claude_ai_Claude_Docs__create", "mcp__claude_ai_Claude_Docs__delete", "mcp__claude_ai_Claude_Docs__export", "mcp__claude_ai_Claude_Docs__guide", "mcp__claude_ai_Claude_Docs__query", "mcp__claude_ai_Claude_Docs__read", "mcp__claude_ai_Claude_Docs__update", "mcp__claude_ai_Context7__query-docs", "mcp__claude_ai_Context7__resolve-library-id", "mcp__claude_ai_Excalidraw__create_view", "mcp__claude_ai_Excalidraw__read_me", "mcp__claude_ai_Gmail__apply_sensitive_message_label", "mcp__claude_ai_Gmail__apply_sensitive_thread_label", "mcp__claude_ai_Gmail__create_draft", "mcp__claude_ai_Gmail__create_label", "mcp__claude_ai_Gmail__delete_draft", "mcp__claude_ai_Gmail__delete_label", "mcp__claude_ai_Gmail__forward", "mcp__claude_ai_Gmail__get_draft", "mcp__claude_ai_Gmail__get_message", "mcp__claude_ai_Gmail__get_thread", "mcp__claude_ai_Gmail__label_message", "mcp__claude_ai_Gmail__label_thread", "mcp__claude_ai_Gmail__list_drafts", "mcp__claude_ai_Gmail__list_labels", "mcp__claude_ai_Gmail__mark_message_spam", "mcp__claude_ai_Gmail__mark_thread_spam", "mcp__claude_ai_Gmail__reply", "mcp__claude_ai_Gmail__search_threads", "mcp__claude_ai_Gmail__send_message", "mcp__claude_ai_Gmail__trash_message", "mcp__claude_ai_Gmail__trash_thread", "mcp__claude_ai_Gmail__unlabel_message", "mcp__claude_ai_Gmail__unlabel_thread", "mcp__claude_ai_Gmail__unmark_message_spam", "mcp__claude_ai_Gmail__unmark_thread_spam", "mcp__claude_ai_Gmail__untrash_message", "mcp__claude_ai_Gmail__untrash_thread", "mcp__claude_ai_Gmail__update_draft", "mcp__claude_ai_Gmail__update_label", "mcp__claude_ai_Gmail__update_message_labels", "mcp__claude_ai_Google_Calendar__create_event", "mcp__claude_ai_Google_Calendar__delete_event", "mcp__claude_ai_Google_Calendar__get_event", "mcp__claude_ai_Google_Calendar__list_calendars", "mcp__claude_ai_Google_Calendar__list_events", "mcp__claude_ai_Google_Calendar__respond_to_event", "mcp__claude_ai_Google_Calendar__search_events", "mcp__claude_ai_Google_Calendar__suggest_time", "mcp__claude_ai_Google_Calendar__update_event", "mcp__claude_ai_Microsoft_365__chat_message_search", "mcp__claude_ai_Microsoft_365__find_meeting_availability", "mcp__claude_ai_Microsoft_365__get_granted_scopes", "mcp__claude_ai_Microsoft_365__get_me", "mcp__claude_ai_Microsoft_365__outlook_batch_delete_messages", "mcp__claude_ai_Microsoft_365__outlook_batch_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_calendar_search", "mcp__claude_ai_Microsoft_365__outlook_create_draft", "mcp__claude_ai_Microsoft_365__outlook_create_event", "mcp__claude_ai_Microsoft_365__outlook_create_filter", "mcp__claude_ai_Microsoft_365__outlook_create_label", "mcp__claude_ai_Microsoft_365__outlook_create_reply_all_draft", "mcp__claude_ai_Microsoft_365__outlook_create_reply_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_event", "mcp__claude_ai_Microsoft_365__outlook_delete_filter", "mcp__claude_ai_Microsoft_365__outlook_delete_label", "mcp__claude_ai_Microsoft_365__outlook_email_search", "mcp__claude_ai_Microsoft_365__outlook_find_available_time", "mcp__claude_ai_Microsoft_365__outlook_forward_mail", "mcp__claude_ai_Microsoft_365__outlook_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_modify_thread_labels", "mcp__claude_ai_Microsoft_365__outlook_respond_to_event", "mcp__claude_ai_Microsoft_365__outlook_send_draft", "mcp__claude_ai_Microsoft_365__outlook_send_mail", "mcp__claude_ai_Microsoft_365__outlook_set_vacation", "mcp__claude_ai_Microsoft_365__outlook_trash_thread", "mcp__claude_ai_Microsoft_365__outlook_untrash_thread", "mcp__claude_ai_Microsoft_365__outlook_update_draft", "mcp__claude_ai_Microsoft_365__outlook_update_event", "mcp__claude_ai_Microsoft_365__outlook_update_label", "mcp__claude_ai_Microsoft_365__read_resource", "mcp__claude_ai_Microsoft_365__search_people", "mcp__claude_ai_Microsoft_365__sharepoint_copy_item", "mcp__claude_ai_Microsoft_365__sharepoint_create_folder", "mcp__claude_ai_Microsoft_365__sharepoint_delete_item", "mcp__claude_ai_Microsoft_365__sharepoint_folder_search", "mcp__claude_ai_Microsoft_365__sharepoint_move_item", "mcp__claude_ai_Microsoft_365__sharepoint_rename_item", "mcp__claude_ai_Microsoft_365__sharepoint_search", "mcp__claude_ai_Microsoft_365__sharepoint_update_file", "mcp__claude_ai_Microsoft_365__sharepoint_upload_file", "mcp__claude_ai_Microsoft_365__teams_create_chat", "mcp__claLine truncated
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "Edit", "Read", "Write"], "mcp_servers": [], "model": "claude-opus-5-5", "permissionMode": "bypassPermissions", "slash_commands": [], "terminal_slash_commands": [], "apiKeySource": "none", "claude_code_version": "2.1.282", "output_style": "default", "agents": [], "skills": [], "plugins": [], "capabilities": ["interrupt_receipt_v1", "interrupt_cancel_queued_v1", "msg_lifecycle_v1", "mcp_read_resource_v1", "mcp_tool_ui_meta_v1"], "analytics_disabled": false, "product_feedback_disabled": false, "uuid": "0ad7c54e-a817-406b-af22-8f647b4e0021", "memory_paths": {}, "messaging_socket_path": "", "fast_mode_state": "off", "fast_mode_disabled_reason": "sdk_opt_in_required", "per_turn_effort_active": true, "view_mode": "default"}
|
||||
{"type": "assistant", "message": {"model": "claude-opus-5-5", "id": "msg_011CfQYZ2iQ3sZ59vJ9CCae9", "type": "message", "role": "assistant", "content": [{"type": "tool_use", "id": "toolu_01P8qrSZwqH1jjZXfrZETjKz", "name": "Bash", "input": {"command": "echo hello", "description": "Print hello"}, "caller": {"type": "direct"}}], "container": null, "stop_reason": null, "stop_sequence": null, "stop_details": null, "usage": {"input_tokens": 2, "cache_creation_input_tokens": 23584, "cache_read_input_tokens": 10119, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 23584}, "output_tokens": 16, "service_tier": "standard", "inference_geo": "not_available"}, "input_transformations": [], "diagnostics": null, "context_management": null}, "parent_tool_use_id": null, "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "uuid": "b4c3b51e-0a58-4b28-8c5a-20a2ff2aaadb", "timestamp": "2026-09-25T17:22:54.134Z", "request_id": "req_011CfQYZ2Ddp5YubZj8vB9Fb", "wire_tool_inputs": {"toolu_01P8qrSZwqH1jjZXfrZETjKz": {"command": "echo hello", "description": "Print hello"}}}
|
||||
{"type": "rate_limit_event", "rate_limit_info": {"status": "allowed_warning", "resetsAt": 1790377200, "rateLimitType": "seven_day", "utilization": 0.98, "isUsingOverage": false, "surpassedThreshold": 0.75, "unifiedWindows": {"five_hour": {"utilization": 0.76, "resetsAt": 1790366400}, "seven_day": {"utilization": 0.98, "resetsAt": 1790377200}}}, "uuid": "a91b2340-329e-4c73-8e1a-307860859743", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "user", "message": {"role": "user", "content": [{"tool_use_id": "toolu_01P8qrSZwqH1jjZXfrZETjKz", "type": "tool_result", "content": "hello", "is_error": false}]}, "parent_tool_use_id": null, "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "uuid": "6beae671-52a0-499a-b72b-f9321c1d9e14", "timestamp": "2026-09-25T17:22:54.460Z", "tool_use_result": {"stdout": "hello", "stderr": "", "interrupted": false, "isImage": false, "noOutputExpected": false}}
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "04acf4c4-0c8d-4dd5-9d3a-a7a6df371224", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "ecbfdcf2-446c-4386-a89f-eeaf43e48b46", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "4c58406e-b5f0-49d7-af88-483c14212e0d", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "c10b3042-e990-49db-8937-954b6fe11570", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "a0cb320b-0bdd-45b5-90b5-451add28d1ed", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "3a3327f8-ad24-46d7-a194-e0ce68f9f871", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "CronCreate", "CronDelete", "CronList", "DesignSync", "Edit", "EnterWorktree", "ExitWorktree", "ListAgents", "ListMcpResourcesTool", "LSP", "Monitor", "NotebookEdit", "PushNotification", "Read", "ReadMcpResourceDirTool", "ReadMcpResourceTool", "RemoteTrigger", "ReportFindings", "ScheduleWakeup", "SendMessage", "Skill", "TaskStop", "ToolSearch", "WebFetch", "WebSearch", "Workflow", "Write", "mcp__claude_ai_Claude_Docs__batch", "mcp__claude_ai_Claude_Docs__create", "mcp__claude_ai_Claude_Docs__delete", "mcp__claude_ai_Claude_Docs__export", "mcp__claude_ai_Claude_Docs__guide", "mcp__claude_ai_Claude_Docs__query", "mcp__claude_ai_Claude_Docs__read", "mcp__claude_ai_Claude_Docs__update", "mcp__claude_ai_Context7__query-docs", "mcp__claude_ai_Context7__resolve-library-id", "mcp__claude_ai_Excalidraw__create_view", "mcp__claude_ai_Excalidraw__read_me", "mcp__claude_ai_Gmail__apply_sensitive_message_label", "mcp__claude_ai_Gmail__apply_sensitive_thread_label", "mcp__claude_ai_Gmail__create_draft", "mcp__claude_ai_Gmail__create_label", "mcp__claude_ai_Gmail__delete_draft", "mcp__claude_ai_Gmail__delete_label", "mcp__claude_ai_Gmail__forward", "mcp__claude_ai_Gmail__get_draft", "mcp__claude_ai_Gmail__get_message", "mcp__claude_ai_Gmail__get_thread", "mcp__claude_ai_Gmail__label_message", "mcp__claude_ai_Gmail__label_thread", "mcp__claude_ai_Gmail__list_drafts", "mcp__claude_ai_Gmail__list_labels", "mcp__claude_ai_Gmail__mark_message_spam", "mcp__claude_ai_Gmail__mark_thread_spam", "mcp__claude_ai_Gmail__reply", "mcp__claude_ai_Gmail__search_threads", "mcp__claude_ai_Gmail__send_message", "mcp__claude_ai_Gmail__trash_message", "mcp__claude_ai_Gmail__trash_thread", "mcp__claude_ai_Gmail__unlabel_message", "mcp__claude_ai_Gmail__unlabel_thread", "mcp__claude_ai_Gmail__unmark_message_spam", "mcp__claude_ai_Gmail__unmark_thread_spam", "mcp__claude_ai_Gmail__untrash_message", "mcp__claude_ai_Gmail__untrash_thread", "mcp__claude_ai_Gmail__update_draft", "mcp__claude_ai_Gmail__update_label", "mcp__claude_ai_Gmail__update_message_labels", "mcp__claude_ai_Google_Calendar__create_event", "mcp__claude_ai_Google_Calendar__delete_event", "mcp__claude_ai_Google_Calendar__get_event", "mcp__claude_ai_Google_Calendar__list_calendars", "mcp__claude_ai_Google_Calendar__list_events", "mcp__claude_ai_Google_Calendar__respond_to_event", "mcp__claude_ai_Google_Calendar__search_events", "mcp__claude_ai_Google_Calendar__suggest_time", "mcp__claude_ai_Google_Calendar__update_event", "mcp__claude_ai_Microsoft_365__chat_message_search", "mcp__claude_ai_Microsoft_365__find_meeting_availability", "mcp__claude_ai_Microsoft_365__get_granted_scopes", "mcp__claude_ai_Microsoft_365__get_me", "mcp__claude_ai_Microsoft_365__outlook_batch_delete_messages", "mcp__claude_ai_Microsoft_365__outlook_batch_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_calendar_search", "mcp__claude_ai_Microsoft_365__outlook_create_draft", "mcp__claude_ai_Microsoft_365__outlook_create_event", "mcp__claude_ai_Microsoft_365__outlook_create_filter", "mcp__claude_ai_Microsoft_365__outlook_create_label", "mcp__claude_ai_Microsoft_365__outlook_create_reply_all_draft", "mcp__claude_ai_Microsoft_365__outlook_create_reply_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_event", "mcp__claude_ai_Microsoft_365__outlook_delete_filter", "mcp__claude_ai_Microsoft_365__outlook_delete_label", "mcp__claude_ai_Microsoft_365__outlook_email_search", "mcp__claude_ai_Microsoft_365__outlook_find_available_time", "mcp__claude_ai_Microsoft_365__outlook_forward_mail", "mcp__claude_ai_Microsoft_365__outlook_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_modify_thread_labels", "mcp__claude_ai_Microsoft_365__outlook_respond_to_event", "mcp__claude_ai_Microsoft_365__outlook_send_draft", "mcp__claude_ai_Microsoft_365__outlook_send_mail", "mcp__claude_ai_Microsoft_365__outlook_set_vacation", "mcp__claude_ai_Microsoft_365__outlook_trash_thread", "mcp__claude_ai_Microsoft_365__outlook_untrash_thread", "mcp__claude_ai_Microsoft_365__outlook_update_draft", "mcp__claude_ai_Microsoft_365__outlook_update_event", "mcp__claude_ai_Microsoft_365__outlook_update_label", "mcp__claude_ai_Microsoft_365__read_resource", "mcp__claude_ai_Microsoft_365__search_people", "mcp__claude_ai_Microsoft_365__sharepoint_copy_item", "mcp__claude_ai_Microsoft_365__sharepoint_create_folder", "mcp__claude_ai_Microsoft_365__sharepoint_delete_item", "mcp__claude_ai_Microsoft_365__sharepoint_folder_search", "mcp__claude_ai_Microsoft_365__sharepoint_move_item", "mcp__claude_ai_Microsoft_365__sharepoint_rename_item", "mcp__claude_ai_Microsoft_365__sharepoint_search", "mcp__claude_ai_Microsoft_365__sharepoint_update_file", "mcp__claude_ai_Microsoft_365__sharepoint_upload_file", "mcp__claude_ai_Microsoft_365__teams_create_chat", "mcp__claLine truncated
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "Edit", "Read", "Write"], "mcp_servers": [], "model": "claude-opus-5-5", "permissionMode": "bypassPermissions", "slash_commands": [], "terminal_slash_commands": [], "apiKeySource": "none", "claude_code_version": "2.1.282", "output_style": "default", "agents": [], "skills": [], "plugins": [], "capabilities": ["interrupt_receipt_v1", "interrupt_cancel_queued_v1", "msg_lifecycle_v1", "mcp_read_resource_v1", "mcp_tool_ui_meta_v1"], "analytics_disabled": false, "product_feedback_disabled": false, "uuid": "0ad7c54e-a817-406b-af22-8f647b4e0021", "memory_paths": {}, "messaging_socket_path": "", "fast_mode_state": "off", "fast_mode_disabled_reason": "sdk_opt_in_required", "per_turn_effort_active": true, "view_mode": "default"}
|
||||
{"type": "assistant", "message": {"model": "claude-opus-5-5", "id": "msg_011CfQYZ2iQ3sZ59vJ9CCae9", "type": "message", "role": "assistant", "content": [{"type": "tool_use", "id": "toolu_01P8qrSZwqH1jjZXfrZETjKz", "name": "Bash", "input": {"command": "echo hello", "description": "Print hello"}, "caller": {"type": "direct"}}], "container": null, "stop_reason": null, "stop_sequence": null, "stop_details": null, "usage": {"input_tokens": 2, "cache_creation_input_tokens": 23584, "cache_read_input_tokens": 10119, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 23584}, "output_tokens": 16, "service_tier": "standard", "inference_geo": "not_available"}, "input_transformations": [], "diagnostics": null, "context_management": null}, "parent_tool_use_id": null, "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "uuid": "b4c3b51e-0a58-4b28-8c5a-20a2ff2aaadb", "timestamp": "2026-09-25T17:22:54.134Z", "request_id": "req_011CfQYZ2Ddp5YubZj8vB9Fb", "wire_tool_inputs": {"toolu_01P8qrSZwqH1jjZXfrZETjKz": {"command": "echo hello", "description": "Print hello"}}}
|
||||
{"type":"assistant","message":{"content":[{"type":"tool_use"
|
||||
{"type": "rate_limit_event", "rate_limit_info": {"status": "allowed_warning", "resetsAt": 1790377200, "rateLimitType": "seven_day", "utilization": 0.98, "isUsingOverage": false, "surpassedThreshold": 0.75, "unifiedWindows": {"five_hour": {"utilization": 0.76, "resetsAt": 1790366400}, "seven_day": {"utilization": 0.98, "resetsAt": 1790377200}}}, "uuid": "a91b2340-329e-4c73-8e1a-307860859743", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "04acf4c4-0c8d-4dd5-9d3a-a7a6df371224", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "ecbfdcf2-446c-4386-a89f-eeaf43e48b46", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "4c58406e-b5f0-49d7-af88-483c14212e0d", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "c10b3042-e990-49db-8937-954b6fe11570", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "hook_response", "hook_id": "a0cb320b-0bdd-45b5-90b5-451add28d1ed", "hook_name": "SessionStart:startup", "hook_event": "SessionStart", "output": "", "stdout": "", "stderr": "", "exit_code": 0, "outcome": "success", "uuid": "3a3327f8-ad24-46d7-a194-e0ce68f9f871", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "CronCreate", "CronDelete", "CronList", "DesignSync", "Edit", "EnterWorktree", "ExitWorktree", "ListAgents", "ListMcpResourcesTool", "LSP", "Monitor", "NotebookEdit", "PushNotification", "Read", "ReadMcpResourceDirTool", "ReadMcpResourceTool", "RemoteTrigger", "ReportFindings", "ScheduleWakeup", "SendMessage", "Skill", "TaskStop", "ToolSearch", "WebFetch", "WebSearch", "Workflow", "Write", "mcp__claude_ai_Claude_Docs__batch", "mcp__claude_ai_Claude_Docs__create", "mcp__claude_ai_Claude_Docs__delete", "mcp__claude_ai_Claude_Docs__export", "mcp__claude_ai_Claude_Docs__guide", "mcp__claude_ai_Claude_Docs__query", "mcp__claude_ai_Claude_Docs__read", "mcp__claude_ai_Claude_Docs__update", "mcp__claude_ai_Context7__query-docs", "mcp__claude_ai_Context7__resolve-library-id", "mcp__claude_ai_Excalidraw__create_view", "mcp__claude_ai_Excalidraw__read_me", "mcp__claude_ai_Gmail__apply_sensitive_message_label", "mcp__claude_ai_Gmail__apply_sensitive_thread_label", "mcp__claude_ai_Gmail__create_draft", "mcp__claude_ai_Gmail__create_label", "mcp__claude_ai_Gmail__delete_draft", "mcp__claude_ai_Gmail__delete_label", "mcp__claude_ai_Gmail__forward", "mcp__claude_ai_Gmail__get_draft", "mcp__claude_ai_Gmail__get_message", "mcp__claude_ai_Gmail__get_thread", "mcp__claude_ai_Gmail__label_message", "mcp__claude_ai_Gmail__label_thread", "mcp__claude_ai_Gmail__list_drafts", "mcp__claude_ai_Gmail__list_labels", "mcp__claude_ai_Gmail__mark_message_spam", "mcp__claude_ai_Gmail__mark_thread_spam", "mcp__claude_ai_Gmail__reply", "mcp__claude_ai_Gmail__search_threads", "mcp__claude_ai_Gmail__send_message", "mcp__claude_ai_Gmail__trash_message", "mcp__claude_ai_Gmail__trash_thread", "mcp__claude_ai_Gmail__unlabel_message", "mcp__claude_ai_Gmail__unlabel_thread", "mcp__claude_ai_Gmail__unmark_message_spam", "mcp__claude_ai_Gmail__unmark_thread_spam", "mcp__claude_ai_Gmail__untrash_message", "mcp__claude_ai_Gmail__untrash_thread", "mcp__claude_ai_Gmail__update_draft", "mcp__claude_ai_Gmail__update_label", "mcp__claude_ai_Gmail__update_message_labels", "mcp__claude_ai_Google_Calendar__create_event", "mcp__claude_ai_Google_Calendar__delete_event", "mcp__claude_ai_Google_Calendar__get_event", "mcp__claude_ai_Google_Calendar__list_calendars", "mcp__claude_ai_Google_Calendar__list_events", "mcp__claude_ai_Google_Calendar__respond_to_event", "mcp__claude_ai_Google_Calendar__search_events", "mcp__claude_ai_Google_Calendar__suggest_time", "mcp__claude_ai_Google_Calendar__update_event", "mcp__claude_ai_Microsoft_365__chat_message_search", "mcp__claude_ai_Microsoft_365__find_meeting_availability", "mcp__claude_ai_Microsoft_365__get_granted_scopes", "mcp__claude_ai_Microsoft_365__get_me", "mcp__claude_ai_Microsoft_365__outlook_batch_delete_messages", "mcp__claude_ai_Microsoft_365__outlook_batch_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_calendar_search", "mcp__claude_ai_Microsoft_365__outlook_create_draft", "mcp__claude_ai_Microsoft_365__outlook_create_event", "mcp__claude_ai_Microsoft_365__outlook_create_filter", "mcp__claude_ai_Microsoft_365__outlook_create_label", "mcp__claude_ai_Microsoft_365__outlook_create_reply_all_draft", "mcp__claude_ai_Microsoft_365__outlook_create_reply_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_draft", "mcp__claude_ai_Microsoft_365__outlook_delete_event", "mcp__claude_ai_Microsoft_365__outlook_delete_filter", "mcp__claude_ai_Microsoft_365__outlook_delete_label", "mcp__claude_ai_Microsoft_365__outlook_email_search", "mcp__claude_ai_Microsoft_365__outlook_find_available_time", "mcp__claude_ai_Microsoft_365__outlook_forward_mail", "mcp__claude_ai_Microsoft_365__outlook_modify_labels", "mcp__claude_ai_Microsoft_365__outlook_modify_thread_labels", "mcp__claude_ai_Microsoft_365__outlook_respond_to_event", "mcp__claude_ai_Microsoft_365__outlook_send_draft", "mcp__claude_ai_Microsoft_365__outlook_send_mail", "mcp__claude_ai_Microsoft_365__outlook_set_vacation", "mcp__claude_ai_Microsoft_365__outlook_trash_thread", "mcp__claude_ai_Microsoft_365__outlook_untrash_thread", "mcp__claude_ai_Microsoft_365__outlook_update_draft", "mcp__claude_ai_Microsoft_365__outlook_update_event", "mcp__claude_ai_Microsoft_365__outlook_update_label", "mcp__claude_ai_Microsoft_365__read_resource", "mcp__claude_ai_Microsoft_365__search_people", "mcp__claude_ai_Microsoft_365__sharepoint_copy_item", "mcp__claude_ai_Microsoft_365__sharepoint_create_folder", "mcp__claude_ai_Microsoft_365__sharepoint_delete_item", "mcp__claude_ai_Microsoft_365__sharepoint_folder_search", "mcp__claude_ai_Microsoft_365__sharepoint_move_item", "mcp__claude_ai_Microsoft_365__sharepoint_rename_item", "mcp__claude_ai_Microsoft_365__sharepoint_search", "mcp__claude_ai_Microsoft_365__sharepoint_update_file", "mcp__claude_ai_Microsoft_365__sharepoint_upload_file", "mcp__claude_ai_Microsoft_365__teams_create_chat", "mcp__claLine truncated
|
||||
{"type": "system", "subtype": "init", "cwd": "/workspace", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "tools": ["Task", "Bash", "Edit", "Read", "Write"], "mcp_servers": [], "model": "claude-opus-5-5", "permissionMode": "bypassPermissions", "slash_commands": [], "terminal_slash_commands": [], "apiKeySource": "none", "claude_code_version": "2.1.282", "output_style": "default", "agents": [], "skills": [], "plugins": [], "capabilities": ["interrupt_receipt_v1", "interrupt_cancel_queued_v1", "msg_lifecycle_v1", "mcp_read_resource_v1", "mcp_tool_ui_meta_v1"], "analytics_disabled": false, "product_feedback_disabled": false, "uuid": "0ad7c54e-a817-406b-af22-8f647b4e0021", "memory_paths": {}, "messaging_socket_path": "", "fast_mode_state": "off", "fast_mode_disabled_reason": "sdk_opt_in_required", "per_turn_effort_active": true, "view_mode": "default"}
|
||||
{"type": "assistant", "message": {"model": "claude-opus-5-5", "id": "msg_011CfQYZ2iQ3sZ59vJ9CCae9", "type": "message", "role": "assistant", "content": [{"type": "tool_use", "id": "toolu_01P8qrSZwqH1jjZXfrZETjKz", "name": "Bash", "input": {"command": "echo hello", "description": "Print hello"}, "caller": {"type": "direct"}}], "container": null, "stop_reason": null, "stop_sequence": null, "stop_details": null, "usage": {"input_tokens": 2, "cache_creation_input_tokens": 23584, "cache_read_input_tokens": 10119, "cache_creation": {"ephemeral_5m_input_tokens": 0, "ephemeral_1h_input_tokens": 23584}, "output_tokens": 16, "service_tier": "standard", "inference_geo": "not_available"}, "input_transformations": [], "diagnostics": null, "context_management": null}, "parent_tool_use_id": null, "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "uuid": "b4c3b51e-0a58-4b28-8c5a-20a2ff2aaadb", "timestamp": "2026-09-25T17:22:54.134Z", "request_id": "req_011CfQYZ2Ddp5YubZj8vB9Fb", "wire_tool_inputs": {"toolu_01P8qrSZwqH1jjZXfrZETjKz": {"command": "echo hello", "description": "Print hello"}}}
|
||||
{"type": "rate_limit_event", "rate_limit_info": {"status": "allowed_warning", "resetsAt": 1790377200, "rateLimitType": "seven_day", "utilization": 0.98, "isUsingOverage": false, "surpassedThreshold": 0.75, "unifiedWindows": {"five_hour": {"utilization": 0.76, "resetsAt": 1790366400}, "seven_day": {"utilization": 0.98, "resetsAt": 1790377200}}}, "uuid": "a91b2340-329e-4c73-8e1a-307860859743", "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92"}
|
||||
{"type": "user", "message": {"role": "user", "content": [{"tool_use_id": "toolu_01P8qrSZwqH1jjZXfrZETjKz", "type": "tool_result", "content": "hello", "is_error": false}]}, "parent_tool_use_id": null, "session_id": "9c22c15c-80ef-42c6-a503-8d087ec47d92", "uuid": "6beae671-52a0-499a-b72b-f9321c1d9e14", "timestamp": "2026-09-25T17:22:54.460Z", "tool_use_result": {"stdout": "hello", "stderr": "", "interrupted": false, "isImage": false, "noOutputExpected": false}}
|
||||
|
||||
@@ -1,272 +0,0 @@
|
||||
package agentworker
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/samcharles93/ai-sdk/agent"
|
||||
"github.com/samcharles93/ai-sdk/core"
|
||||
"github.com/samcharles93/ai-sdk/runtime"
|
||||
"github.com/samcharles93/ai-sdk/toolkit"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/taskrun"
|
||||
)
|
||||
|
||||
// newReviewerFor builds the workflow.Reviewer for one task run, or nil
|
||||
// when the repo has not opted into review (Repo.ReviewEnabled == false)
|
||||
// or no providers are configured. Model resolution mirrors AgentStage's
|
||||
// own role->"builder" fallback (agent.go): Models["reviewer"], falling
|
||||
// back to Models["builder"].
|
||||
func newReviewerFor(req taskrun.Request) workflow.Reviewer {
|
||||
if !req.Repo.ReviewEnabled {
|
||||
return nil
|
||||
}
|
||||
return NewOperatorReviewer(req.Cfg.Models, req.Providers)
|
||||
}
|
||||
|
||||
// NewOperatorReviewer builds the workflow.Reviewer for an operator-triggered
|
||||
// review, resolved from daemon-level models and providers rather than a task
|
||||
// run. It shares newReviewerFor's role->"builder" model fallback but drops
|
||||
// the Repo.ReviewEnabled gate: the operator asked for the review explicitly,
|
||||
// so "not opted in" is not a reason to refuse. It returns nil when no model
|
||||
// resolves (no reviewer/builder model configured) or no provider runtime
|
||||
// builds, so the caller can report a clear "review not configured" result.
|
||||
func NewOperatorReviewer(models map[string]string, providers map[string]agentexec.Provider) workflow.Reviewer {
|
||||
modelRef := ReviewerModel(models)
|
||||
if modelRef == "" {
|
||||
return nil
|
||||
}
|
||||
rt := agentexec.NewRuntime(providers)
|
||||
if rt == nil {
|
||||
return nil
|
||||
}
|
||||
return newSubagentReviewer(rt, modelRef)
|
||||
}
|
||||
|
||||
// ReviewerModel resolves the reviewer role's model with the builder fallback.
|
||||
// It is the single source of truth for the role->"builder" rule, shared by
|
||||
// the workflow stage (via NewOperatorReviewer/newReviewerFor) and the
|
||||
// operator-triggered review's result reporting so the reported model and the
|
||||
// model actually run cannot diverge.
|
||||
func ReviewerModel(models map[string]string) string {
|
||||
if models["reviewer"] != "" {
|
||||
return models["reviewer"]
|
||||
}
|
||||
return models["builder"]
|
||||
}
|
||||
|
||||
// defaultReviewMaxSteps bounds the reviewer's tool loop when neither
|
||||
// ReviewRequest.MaxSteps nor the repo's configured budget set one.
|
||||
const defaultReviewMaxSteps = 10
|
||||
|
||||
// subagentReviewer implements workflow.Reviewer using ai-sdk's
|
||||
// agent.Subagent: a nested, synchronous generation in this same worker
|
||||
// process, with its own model, system prompt, toolset, and step budget.
|
||||
//
|
||||
// Isolation is two-fold. Conversation isolation is structural: Subagent.Run
|
||||
// only ever sends a prompt string, never the implementer's message
|
||||
// history. Workspace isolation is built by the caller (StageReview via
|
||||
// workflow.Trees.Snapshot): reviewerToolSet is rooted at that snapshot
|
||||
// directory and holds only read-only tools -- never the worker's own
|
||||
// toolset, which carries the worktreerpc publication grant a reviewer must
|
||||
// not be able to reach.
|
||||
type subagentReviewer struct {
|
||||
runtime *runtime.Runtime
|
||||
modelRef string
|
||||
}
|
||||
|
||||
// newSubagentReviewer constructs a Reviewer that runs on modelRef, resolved
|
||||
// through rt (the same provider runtime the worker's own agent runner
|
||||
// uses). rt must be non-nil.
|
||||
func newSubagentReviewer(rt *runtime.Runtime, modelRef string) *subagentReviewer {
|
||||
return &subagentReviewer{runtime: rt, modelRef: modelRef}
|
||||
}
|
||||
|
||||
var _ workflow.Reviewer = (*subagentReviewer)(nil)
|
||||
|
||||
// Review runs one adversarial review. It never returns a Go error: every
|
||||
// failure mode (unresolvable model, a Subagent.Run error, a truncated
|
||||
// run) folds into the returned ReviewReport, per
|
||||
// docs/prds/adversarial-self-review.md section 4's fail-closed contract.
|
||||
func (s *subagentReviewer) Review(ctx context.Context, req workflow.ReviewRequest) workflow.ReviewReport {
|
||||
if s.runtime == nil {
|
||||
return workflow.NewNotRunReviewReport("no provider runtime configured for the reviewer")
|
||||
}
|
||||
provider, model, err := s.runtime.ChatProvider(ctx, s.modelRef)
|
||||
if err != nil {
|
||||
return workflow.NewNotRunReviewReport(fmt.Sprintf("resolve reviewer model %q: %v", s.modelRef, err))
|
||||
}
|
||||
|
||||
var findings []workflow.ReviewFinding
|
||||
var checks []workflow.ReviewCheck
|
||||
tools := reviewerToolSet(req.SnapshotDir, &findings, &checks)
|
||||
|
||||
maxSteps := req.MaxSteps
|
||||
if maxSteps <= 0 {
|
||||
maxSteps = defaultReviewMaxSteps
|
||||
}
|
||||
|
||||
sub := agent.Subagent{
|
||||
Provider: provider,
|
||||
Model: model,
|
||||
System: reviewerSystemPrompt,
|
||||
Tools: tools,
|
||||
MaxSteps: maxSteps,
|
||||
}
|
||||
|
||||
summary, runErr := sub.Run(ctx, reviewerPrompt(req))
|
||||
if runErr != nil {
|
||||
// A truncated or errored run still yields whatever the reviewer
|
||||
// captured before it ran out of budget -- those findings are real
|
||||
// and must not be discarded just because the run's own
|
||||
// conclusion never arrived (docs/prds/adversarial-self-review.md
|
||||
// section 1, "findings return through a closure"). Zero captured
|
||||
// findings on error means the reviewer never got anywhere, which
|
||||
// fail-closed treats as not having run at all.
|
||||
if len(findings) == 0 {
|
||||
return workflow.NewNotRunReviewReport(runErr.Error())
|
||||
}
|
||||
return completedReview(findings, checks, "")
|
||||
}
|
||||
return completedReview(findings, checks, summary)
|
||||
}
|
||||
|
||||
// completedReview builds a completed report carrying the captured findings
|
||||
// and the properties the reviewer verified clean.
|
||||
func completedReview(findings []workflow.ReviewFinding, checks []workflow.ReviewCheck, summary string) workflow.ReviewReport {
|
||||
report := workflow.NewCompletedReviewReport(findings, summary)
|
||||
report.Checked = checks
|
||||
return report
|
||||
}
|
||||
|
||||
// reviewerSystemPrompt instructs the reviewer per CLAUDE.md's own
|
||||
// adversarial-review discipline: assume every line is wrong until proven
|
||||
// correct, work the checklist, report only what a fresh reader can verify
|
||||
// from what it was given.
|
||||
const reviewerSystemPrompt = `You are a fresh adversarial code reviewer. You did not write this change and have no access to how or why it was written -- only what is given to you below.
|
||||
|
||||
Assume every line is wrong until you have verified it is correct. Read whole files with your read tool, not just diff hunks, before concluding a call site or interface is satisfied. Use grep/find to check for other call sites a change affects.
|
||||
|
||||
Check for: dead code, unchecked errors, hardcoded values that should be parameters, interface-satisfaction defects, nil-pointer risk, goroutine leaks, races and unsynchronized shared state.
|
||||
|
||||
For every defect you find, call record_finding with: the file and line, a one-sentence defect statement, a concrete failure scenario (specific inputs or state that produce the wrong output or a crash -- not a hypothetical), a verdict, a level, and a category.
|
||||
|
||||
A finding must describe wrong behaviour or a crash. Style, formatting, naming, and preference nits are out of contract -- do not report them; they are exactly the padding that teaches an operator to skim past a findings list.
|
||||
|
||||
As you clear each checklist property, call record_checked with the property and how you verified it (which files or call sites you read). Record every property you actually checked and found correct, even when you also found defects; a review that reports no findings must still record what it checked, because "I checked and it is fine" and "I did not look" must not read the same.
|
||||
|
||||
Verdict is "confirmed" only when you have traced the actual failure -- read the code paths involved and can state exactly how it goes wrong. Verdict is "plausible" for a real worry you have not fully traced. Only a "confirmed" finding at level "error" blocks the pull request; do not inflate a plausible worry to confirmed/error to make it count -- an unjustified block is worse than a missed one, because it teaches the operator to stop trusting your reports.
|
||||
|
||||
Level is "error" for a defect that blocks; "warn" for something worth knowing but not blocking.
|
||||
|
||||
When a confirmed defect's fix is mechanical, and only then, pass suggestion: the exact text that should replace the anchored line, so the author can apply it in one click. It replaces that line exactly, so include the whole line (indentation included) and nothing else, and never guess -- a wrong one-click fix is worse than none. Do not pass a suggestion for a plausible finding, or for a fix you cannot state as a single line.
|
||||
|
||||
When you have finished checking, reply with a short summary of what you checked and what you found (or that you found nothing). If you find nothing, say so plainly -- reporting zero findings on properties you actually checked is a valid and expected outcome, not a failure to find something.`
|
||||
|
||||
// reviewerPrompt renders the reviewer's mission: the diff and issue text.
|
||||
// The snapshot itself is not embedded here -- it reaches the reviewer only
|
||||
// through its read-only toolset, rooted at SnapshotDir, never as prompt
|
||||
// text the reviewer could mistake for something it already checked.
|
||||
func reviewerPrompt(req workflow.ReviewRequest) string {
|
||||
var b strings.Builder
|
||||
b.WriteString("Review the following change. The full file tree at the reviewed commit is available through your tools; ")
|
||||
b.WriteString("start by reading the files the diff touches, not just the diff itself.\n\n")
|
||||
b.WriteString("<issue>\n")
|
||||
b.WriteString(req.IssueText)
|
||||
b.WriteString("\n</issue>\n\n<diff>\n")
|
||||
b.WriteString(req.Diff)
|
||||
b.WriteString("\n</diff>\n")
|
||||
return b.String()
|
||||
}
|
||||
|
||||
// reviewerToolSet builds the reviewer's read-only toolset, rooted at
|
||||
// snapshotDir, plus the structured capture tools that append directly to
|
||||
// findings and checks. This is a distinct toolset built fresh for each
|
||||
// review -- never the worker's own registry, which holds write/edit/shell
|
||||
// tools and the worktreerpc publication grant.
|
||||
func reviewerToolSet(snapshotDir string, findings *[]workflow.ReviewFinding, checks *[]workflow.ReviewCheck) core.ToolSet {
|
||||
reg := toolkit.NewRegistry()
|
||||
readOnly := []toolkit.Tool{
|
||||
toolkit.NewReadTool(snapshotDir, toolkit.NewReadTracker()),
|
||||
toolkit.NewGrepTool(snapshotDir),
|
||||
toolkit.NewFindTool(snapshotDir),
|
||||
}
|
||||
for _, tool := range readOnly {
|
||||
_ = reg.Register(tool) // names are fixed and distinct; Register cannot fail here
|
||||
}
|
||||
set := reg.CoreToolSet(toolkit.NonInteractiveBridge{})
|
||||
set["record_finding"] = recordFindingTool(findings)
|
||||
set["record_checked"] = recordCheckedTool(checks)
|
||||
return set
|
||||
}
|
||||
|
||||
// checkInput is the reviewer-facing shape of workflow.ReviewCheck.
|
||||
type checkInput struct {
|
||||
Property string `json:"property" jsonschema:"description=The property or code path you verified clean, e.g. 'nil-safety of Foo callers'."`
|
||||
Evidence string `json:"evidence" jsonschema:"description=How you verified it, e.g. 'read all 4 callers; each nil-checks before use'."`
|
||||
}
|
||||
|
||||
// recordCheckedTool builds the typed capture tool the reviewer calls once per
|
||||
// property it verified clean. Without it a zero-finding review reads the same
|
||||
// as a review that never looked; with it, "ran and found nothing" arrives
|
||||
// backed by what was actually checked.
|
||||
func recordCheckedTool(checks *[]workflow.ReviewCheck) *core.Tool {
|
||||
return core.NewTypedTool(
|
||||
"record_checked",
|
||||
"Record one property or code path you verified clean. Call this once per property you actually checked and found correct -- a review that reports no findings must still record what it checked.",
|
||||
func(_ context.Context, in checkInput) (string, error) {
|
||||
check := workflow.ReviewCheck{Property: in.Property, Evidence: in.Evidence}
|
||||
if err := check.Validate(); err != nil {
|
||||
return "record_checked rejected: " + err.Error(), nil //nolint:nilerr // rejection feedback lets the model retry with a valid check
|
||||
}
|
||||
*checks = append(*checks, check)
|
||||
return "check recorded", nil
|
||||
},
|
||||
)
|
||||
}
|
||||
|
||||
// findingInput is the reviewer-facing shape of workflow.ReviewFinding: the
|
||||
// model reports plain strings for Verdict/Level/Category, validated and
|
||||
// converted before being appended.
|
||||
type findingInput struct {
|
||||
File string `json:"file" jsonschema:"description=Repo-relative file path where the defect is located."`
|
||||
Line int `json:"line" jsonschema:"description=Line number where the defect is located."`
|
||||
Defect string `json:"defect" jsonschema:"description=One-sentence statement of the defect."`
|
||||
FailureScenario string `json:"failure_scenario" jsonschema:"description=Concrete inputs or state that produce the wrong output or a crash -- not a hypothetical."`
|
||||
Suggestion string `json:"suggestion,omitempty" jsonschema:"description=Optional. The exact replacement for the anchored line, when the fix is mechanical and you are certain of it -- it is offered as a one-click apply, so an approximate or partial line is worse than none. Only a confirmed finding may carry one; omit it for a plausible finding. Single line only."`
|
||||
Verdict string `json:"verdict" jsonschema:"description=Only 'confirmed' may block. Use 'plausible' for a real worry you have not fully traced.,enum=confirmed|plausible"`
|
||||
Level string `json:"level" jsonschema:"description=error blocks when confirmed; warn is advisory only.,enum=error|warn"`
|
||||
Category string `json:"category" jsonschema:"enum=dead-code|unchecked-error|hardcoded-value|interface-satisfaction|nil-risk|goroutine-leak|race|other"`
|
||||
}
|
||||
|
||||
// recordFindingTool builds the typed capture tool the reviewer must call
|
||||
// to report a defect. Rejecting an invalid finding with a plain-text
|
||||
// message (rather than a Go error) lets the model see what was wrong and
|
||||
// retry, the same environmental-enforcement pattern the rest of the
|
||||
// agent-loop tool contract uses.
|
||||
func recordFindingTool(findings *[]workflow.ReviewFinding) *core.Tool {
|
||||
return core.NewTypedTool(
|
||||
"record_finding",
|
||||
"Report one defect found during review. Call this once per defect; do not summarize multiple defects into one call.",
|
||||
func(_ context.Context, in findingInput) (string, error) {
|
||||
finding := workflow.ReviewFinding{
|
||||
File: in.File,
|
||||
Line: in.Line,
|
||||
Defect: in.Defect,
|
||||
FailureScenario: in.FailureScenario,
|
||||
Suggestion: in.Suggestion,
|
||||
Verdict: workflow.ReviewVerdict(in.Verdict),
|
||||
Level: workflow.ReviewLevel(in.Level),
|
||||
Category: workflow.ReviewCategory(in.Category),
|
||||
}
|
||||
if err := finding.Validate(); err != nil {
|
||||
return "record_finding rejected: " + err.Error(), nil //nolint:nilerr // rejection feedback lets the model retry with a valid finding
|
||||
}
|
||||
*findings = append(*findings, finding)
|
||||
return "finding recorded", nil
|
||||
},
|
||||
)
|
||||
}
|
||||
@@ -1,252 +0,0 @@
|
||||
package agentworker
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"slices"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/ai-sdk/agent"
|
||||
"github.com/samcharles93/ai-sdk/chat"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
)
|
||||
|
||||
// TestReviewerToolSetIsReadOnlyAndHasNoMutationPath asserts, as a
|
||||
// construction fact rather than a prompt claim, that the reviewer's
|
||||
// toolset carries no tool capable of writing, editing, or running a
|
||||
// shell command -- the class of tool that could reach the worktreerpc
|
||||
// publication grant or otherwise mutate anything. Read/grep/find plus the
|
||||
// findings-capture tool are the entire surface.
|
||||
func TestReviewerToolSetIsReadOnlyAndHasNoMutationPath(t *testing.T) {
|
||||
var findings []workflow.ReviewFinding
|
||||
var checks []workflow.ReviewCheck
|
||||
set := reviewerToolSet(t.TempDir(), &findings, &checks)
|
||||
|
||||
names := make([]string, 0, len(set))
|
||||
for name := range set {
|
||||
names = append(names, name)
|
||||
}
|
||||
slices.Sort(names)
|
||||
|
||||
want := []string{"find", "grep", "read", "record_checked", "record_finding"}
|
||||
slices.Sort(want)
|
||||
if !slices.Equal(names, want) {
|
||||
t.Fatalf("reviewer toolset = %v, want exactly %v (no write/edit/shell)", names, want)
|
||||
}
|
||||
}
|
||||
|
||||
// TestReviewerToolSetIsRootedAtTheGivenSnapshot asserts the read tool
|
||||
// cannot read outside the snapshot directory it was constructed with --
|
||||
// it has no path back to the implementer's actual worktree.
|
||||
func TestReviewerToolSetIsRootedAtTheGivenSnapshot(t *testing.T) {
|
||||
snapshot := t.TempDir()
|
||||
if err := os.WriteFile(filepath.Join(snapshot, "in-snapshot.txt"), []byte("ok\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
outside := t.TempDir()
|
||||
if err := os.WriteFile(filepath.Join(outside, "secret.txt"), []byte("nope\n"), 0o644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
var findings []workflow.ReviewFinding
|
||||
var checks []workflow.ReviewCheck
|
||||
set := reviewerToolSet(snapshot, &findings, &checks)
|
||||
readTool := set["read"]
|
||||
if readTool == nil {
|
||||
t.Fatal("reviewer toolset has no read tool")
|
||||
}
|
||||
|
||||
out, err := readTool.Execute(t.Context(), `{"path":"in-snapshot.txt"}`)
|
||||
if err != nil {
|
||||
t.Fatalf("read in-snapshot file: %v", err)
|
||||
}
|
||||
if !containsSubstr(out, "ok") {
|
||||
t.Errorf("read in-snapshot file = %q, want it to contain the file's content", out)
|
||||
}
|
||||
|
||||
// Tool failures are encoded in-band in the returned content, not as a
|
||||
// Go error (toolkit.Registry.CoreToolSet's own contract) -- an escape
|
||||
// attempt must reject there, not succeed.
|
||||
escapeOut, err := readTool.Execute(t.Context(), `{"path":"`+filepath.Join(outside, "secret.txt")+`"}`)
|
||||
if err != nil {
|
||||
t.Fatalf("read outside-snapshot path: %v", err)
|
||||
}
|
||||
if containsSubstr(escapeOut, "nope") {
|
||||
t.Errorf("read tool returned content from outside the snapshot: %q", escapeOut)
|
||||
}
|
||||
if !containsSubstr(escapeOut, "escapes") {
|
||||
t.Errorf("read tool output = %q, want a path-confinement rejection", escapeOut)
|
||||
}
|
||||
}
|
||||
|
||||
// TestRecordFindingToolAppendsToCapturedSlice asserts the capture-tool
|
||||
// contract: findings are recorded via the closure over the findings
|
||||
// slice, not returned from Subagent.Run's text.
|
||||
func TestRecordFindingToolAppendsToCapturedSlice(t *testing.T) {
|
||||
var findings []workflow.ReviewFinding
|
||||
tool := recordFindingTool(&findings)
|
||||
|
||||
input := `{"file":"main.go","line":10,"defect":"nil deref","failure_scenario":"calling Foo(nil) panics","verdict":"confirmed","level":"error","category":"nil-risk"}`
|
||||
if _, err := tool.Execute(t.Context(), input); err != nil {
|
||||
t.Fatalf("record_finding: %v", err)
|
||||
}
|
||||
if len(findings) != 1 {
|
||||
t.Fatalf("captured %d findings, want 1", len(findings))
|
||||
}
|
||||
if !findings[0].Blocking() {
|
||||
t.Error("captured finding is not blocking, want confirmed+error to block")
|
||||
}
|
||||
}
|
||||
|
||||
// TestRecordFindingToolRejectsInvalidVerdictWithoutError asserts an
|
||||
// invalid finding is rejected in-band (so the model can retry) rather
|
||||
// than surfacing as a hard tool error, and is not captured.
|
||||
func TestRecordFindingToolRejectsInvalidVerdictWithoutError(t *testing.T) {
|
||||
var findings []workflow.ReviewFinding
|
||||
tool := recordFindingTool(&findings)
|
||||
|
||||
input := `{"file":"main.go","line":1,"defect":"x","failure_scenario":"y","verdict":"maybe","level":"error","category":"other"}`
|
||||
out, err := tool.Execute(t.Context(), input)
|
||||
if err != nil {
|
||||
t.Fatalf("record_finding returned a Go error for invalid input: %v", err)
|
||||
}
|
||||
if !containsSubstr(out, "rejected") {
|
||||
t.Errorf("record_finding output = %q, want a rejection message", out)
|
||||
}
|
||||
if len(findings) != 0 {
|
||||
t.Errorf("captured %d findings, want 0 for an invalid finding", len(findings))
|
||||
}
|
||||
}
|
||||
|
||||
// TestRecordCheckedToolAppendsToCapturedSlice asserts the calibration capture
|
||||
// contract: a cleared property is recorded through the closure, so a
|
||||
// zero-finding review can report what it actually checked.
|
||||
func TestRecordCheckedToolAppendsToCapturedSlice(t *testing.T) {
|
||||
var checks []workflow.ReviewCheck
|
||||
tool := recordCheckedTool(&checks)
|
||||
|
||||
input := `{"property":"nil-safety of Foo callers","evidence":"read all 4 callers; each nil-checks"}`
|
||||
if _, err := tool.Execute(t.Context(), input); err != nil {
|
||||
t.Fatalf("record_checked: %v", err)
|
||||
}
|
||||
if len(checks) != 1 || checks[0].Property != "nil-safety of Foo callers" {
|
||||
t.Fatalf("captured checks = %+v, want one check for the recorded property", checks)
|
||||
}
|
||||
}
|
||||
|
||||
// TestRecordCheckedToolRejectsMissingEvidence asserts a check without evidence
|
||||
// is rejected in-band and not captured, so "verified clean" cannot be recorded
|
||||
// as a bare assertion.
|
||||
func TestRecordCheckedToolRejectsMissingEvidence(t *testing.T) {
|
||||
var checks []workflow.ReviewCheck
|
||||
tool := recordCheckedTool(&checks)
|
||||
|
||||
out, err := tool.Execute(t.Context(), `{"property":"looks fine","evidence":""}`)
|
||||
if err != nil {
|
||||
t.Fatalf("record_checked returned a Go error for invalid input: %v", err)
|
||||
}
|
||||
if !containsSubstr(out, "rejected") {
|
||||
t.Errorf("record_checked output = %q, want a rejection message", out)
|
||||
}
|
||||
if len(checks) != 0 {
|
||||
t.Errorf("captured %d checks, want 0 for a check with no evidence", len(checks))
|
||||
}
|
||||
}
|
||||
|
||||
// TestCompletedReviewCarriesChecks asserts the report the reviewer returns
|
||||
// carries the captured checks, not just the findings.
|
||||
func TestCompletedReviewCarriesChecks(t *testing.T) {
|
||||
checks := []workflow.ReviewCheck{{Property: "p", Evidence: "e"}}
|
||||
report := completedReview(nil, checks, "summary")
|
||||
if !report.Ran() {
|
||||
t.Fatal("completedReview report did not run")
|
||||
}
|
||||
if len(report.Checked) != 1 || report.Checked[0].Property != "p" {
|
||||
t.Fatalf("report.Checked = %+v, want the captured check", report.Checked)
|
||||
}
|
||||
}
|
||||
|
||||
// TestReviewSubagentConstructionNeverSendsConversationHistory asserts, at
|
||||
// the exact agent.Subagent construction Review performs, that only a
|
||||
// prompt string reaches the model. This exercises the same Subagent{}
|
||||
// shape subagentReviewer.Review builds (provider, model, system prompt,
|
||||
// reviewerToolSet, MaxSteps) directly against a fake chat.Provider, so it
|
||||
// proves the construction fact without needing a full *runtime.Runtime:
|
||||
// Subagent.Run populates GenerateOptions.Prompt and never Messages, so
|
||||
// there is no code path for the implementer's transcript to travel
|
||||
// through.
|
||||
func TestReviewSubagentConstructionNeverSendsConversationHistory(t *testing.T) {
|
||||
captured := &capturingChatProvider{}
|
||||
var findings []workflow.ReviewFinding
|
||||
var checks []workflow.ReviewCheck
|
||||
req := workflow.ReviewRequest{
|
||||
SnapshotDir: t.TempDir(),
|
||||
Diff: "diff --git a/x.go b/x.go\n",
|
||||
IssueText: "some issue text",
|
||||
}
|
||||
|
||||
sub := agent.Subagent{
|
||||
Provider: captured,
|
||||
Model: "fake-model",
|
||||
System: reviewerSystemPrompt,
|
||||
Tools: reviewerToolSet(req.SnapshotDir, &findings, &checks),
|
||||
MaxSteps: defaultReviewMaxSteps,
|
||||
}
|
||||
prompt := reviewerPrompt(req)
|
||||
if _, err := sub.Run(t.Context(), prompt); err != nil {
|
||||
t.Fatalf("Subagent.Run() error = %v", err)
|
||||
}
|
||||
|
||||
if captured.lastRequest == nil {
|
||||
t.Fatal("chat provider was never called")
|
||||
}
|
||||
// The only non-system message the model ever sees is the one
|
||||
// Subagent.Run derives from the prompt string -- there is no code
|
||||
// path here for a second, implementer-authored message to arrive
|
||||
// alongside it.
|
||||
var userMessages int
|
||||
for _, m := range captured.lastRequest.Messages {
|
||||
if m.Role == chat.RoleUser {
|
||||
userMessages++
|
||||
if m.Content != prompt {
|
||||
t.Errorf("user message content = %q, want the review prompt %q", m.Content, prompt)
|
||||
}
|
||||
}
|
||||
}
|
||||
if userMessages != 1 {
|
||||
t.Errorf("chat.Request carried %d user messages, want exactly 1 (the review prompt, no implementer history)", userMessages)
|
||||
}
|
||||
}
|
||||
|
||||
func containsSubstr(s, substr string) bool {
|
||||
return len(substr) == 0 ||
|
||||
(len(s) >= len(substr) && func() bool {
|
||||
for i := 0; i+len(substr) <= len(s); i++ {
|
||||
if s[i:i+len(substr)] == substr {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}())
|
||||
}
|
||||
|
||||
// capturingChatProvider is a minimal chat.Provider fake that records the
|
||||
// last chat.Request it received and returns a fixed, valid completion.
|
||||
type capturingChatProvider struct {
|
||||
lastRequest *chat.Request
|
||||
}
|
||||
|
||||
func (c *capturingChatProvider) Name() string { return "fake" }
|
||||
|
||||
func (c *capturingChatProvider) Chat(_ context.Context, req chat.Request) (chat.Response, error) {
|
||||
r := req
|
||||
c.lastRequest = &r
|
||||
return chat.Response{Content: "no findings", FinishReason: "stop"}, nil
|
||||
}
|
||||
|
||||
func (c *capturingChatProvider) ChatStream(_ context.Context, req chat.Request) (chat.Stream, error) {
|
||||
return nil, errors.New("not implemented")
|
||||
}
|
||||
@@ -15,6 +15,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
"github.com/samcharles93/archie-core/internal/events"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/prsource"
|
||||
"github.com/samcharles93/archie-core/internal/installtype"
|
||||
"github.com/samcharles93/archie-core/internal/storage"
|
||||
"github.com/samcharles93/archie-core/internal/taskrun"
|
||||
@@ -183,6 +184,7 @@ func worktreeOwnerID(env string) int {
|
||||
type taskDependencies struct {
|
||||
forge workflow.Forger
|
||||
store workflow.Store
|
||||
calls task.Caller
|
||||
trees remoteTrees
|
||||
events agentexec.EventPublisher
|
||||
// steps is the workflow step vocabulary pinned definitions are compiled
|
||||
@@ -216,12 +218,11 @@ func applyToolLimits(agent agentexec.Runner, policy config.ToolPolicy, allow []s
|
||||
runner.AllowTools = allow
|
||||
}
|
||||
|
||||
// stageRunners builds the runner every agent stage uses, and the reviewer.
|
||||
func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, log *slog.Logger) (agentexec.Runner, workflow.Reviewer, error) {
|
||||
// stageRunners builds the runner every agent stage uses.
|
||||
func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerFactory, log *slog.Logger) (agentexec.Runner, error) {
|
||||
if req.Harness != nil {
|
||||
// The built-in loop has no route to a model from a Kit container, so
|
||||
// the review stage parks rather than running on it.
|
||||
return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil, nil
|
||||
// The built-in loop has no route to a model from a Kit container.
|
||||
return agentexec.HarnessStages{Runner: agentexec.NewHarnessRunner(nil), Spec: *req.Harness}, nil
|
||||
}
|
||||
var agent agentexec.Runner
|
||||
if mcpSet != nil && mcpSet.registry != nil {
|
||||
@@ -230,10 +231,10 @@ func stageRunners(req taskrun.Request, mcpSet *mcpProviderSet, newRunner runnerF
|
||||
agent = newRunner(req.Providers, log)
|
||||
}
|
||||
if agent == nil {
|
||||
return nil, nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID)
|
||||
return nil, fmt.Errorf("no agent runner configured for task %d", req.Task.ID)
|
||||
}
|
||||
applyToolLimits(agent, req.Cfg.ToolPolicy, req.Tools)
|
||||
return agent, newReviewerFor(req), nil
|
||||
return agent, nil
|
||||
}
|
||||
|
||||
// routeTask remains available for routing-only callers. Production execution
|
||||
@@ -285,7 +286,7 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
|
||||
log.Warn("mcp providers had errors, continuing with available tools", "err", mcpErr)
|
||||
}
|
||||
|
||||
agent, reviewer, err := stageRunners(req, mcpSet, newRunner, log)
|
||||
agent, err := stageRunners(req, mcpSet, newRunner, log)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -309,17 +310,27 @@ func runTask(ctx context.Context, req taskrun.Request, dependencies taskDependen
|
||||
}
|
||||
|
||||
tc := &workflow.TaskContext{
|
||||
Task: req.Task,
|
||||
Repo: req.Repo,
|
||||
Cfg: req.Cfg.ToConfig(),
|
||||
Forge: dependencies.forge,
|
||||
Store: dependencies.store,
|
||||
Trees: trees,
|
||||
Agent: agent,
|
||||
Reviewer: reviewer,
|
||||
Bus: bus,
|
||||
Log: log,
|
||||
Task: req.Task,
|
||||
Repo: req.Repo,
|
||||
Cfg: req.Cfg.ToConfig(),
|
||||
Forge: dependencies.forge,
|
||||
Store: dependencies.store,
|
||||
Calls: dependencies.calls,
|
||||
Trees: trees,
|
||||
Agent: agent,
|
||||
Bus: bus,
|
||||
Log: log,
|
||||
}
|
||||
// pr-review reads an external pull request's data from workDir, which the
|
||||
// daemon already populated before this task started (daemon's
|
||||
// prefetchPRReview, writing under workDir/.archie-pr-review -- the same
|
||||
// host directory Docker bind-mounts at storage.WorktreeMountDir) -- never
|
||||
// over the network, and never with a forge credential in this process.
|
||||
// See docs/development/agent.md, "Giving the agent something new".
|
||||
if req.Task.Workflow == "pr-review" {
|
||||
tc.PRSource = prsource.NewFromMount(filepath.Join(workDir, prsource.PrefetchDirName))
|
||||
}
|
||||
|
||||
if req.Repo.PersistentStorage {
|
||||
memory, readErr := readProjectMemory(storage.MemoryPath)
|
||||
if readErr != nil {
|
||||
|
||||
@@ -382,7 +382,8 @@ func startStateStoreGRPC(t *testing.T, local *pgstore.TaskDB) string {
|
||||
eda := pgstore.EDA(t, nil)
|
||||
staterpc.RegisterServer(server, staterpc.Deps{
|
||||
Tasks: local, Captures: eda, Mappings: eda, Bindings: eda,
|
||||
BindingDispatcher: eda, BindingTaskCreator: local,
|
||||
BindingDispatcher: eda, BindingTaskCreator: local, WorkflowCalls: local,
|
||||
Steps: local, Canceller: local,
|
||||
})
|
||||
go func() { _ = server.Serve(listener) }()
|
||||
t.Cleanup(func() { server.Stop(); _ = listener.Close() })
|
||||
|
||||
@@ -0,0 +1,153 @@
|
||||
package agentworker
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log/slog"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/org"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
workflowtask "github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
|
||||
"github.com/samcharles93/archie-core/internal/taskrun"
|
||||
)
|
||||
|
||||
// stubRunner is the agent runner that lets a test workflow end in an
|
||||
// agent.run tail without an LLM: the call step under test needs no agent,
|
||||
// but the workflow must still end with an outcome.
|
||||
type stubRunner struct{}
|
||||
|
||||
func (stubRunner) Run(_ context.Context, _ string, req agentexec.Request, _ agentexec.ToolCallReporter) (agentexec.Result, error) {
|
||||
return agentexec.Result{
|
||||
Version: agentexec.ProtocolVersion, TaskID: req.TaskID, Attempt: req.Attempt,
|
||||
Stage: req.Stage, Status: agentexec.StatusPassed, Summary: "reported",
|
||||
}, nil
|
||||
}
|
||||
|
||||
// fakeScratchTrees is the Trees for a scratch task: the workspace already
|
||||
// exists (the call step needs none, the agent.run tail works in it), and
|
||||
// nothing publishes.
|
||||
type fakeScratchTrees struct {
|
||||
dir string
|
||||
}
|
||||
|
||||
func (f *fakeScratchTrees) Prepare(context.Context, string, string, string, int, string, string, string) (string, string, error) {
|
||||
return f.dir, "", nil
|
||||
}
|
||||
|
||||
func (*fakeScratchTrees) CommitAll(context.Context, string, string) (bool, error) { return false, nil }
|
||||
func (*fakeScratchTrees) Push(context.Context) error { return nil }
|
||||
func (*fakeScratchTrees) Diff(context.Context, string, string) (string, error) { return "", nil }
|
||||
func (*fakeScratchTrees) ChangedFiles(context.Context, string, string) ([]string, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (*fakeScratchTrees) ChangedLines(context.Context, string, string) (int, error) { return 0, nil }
|
||||
func (*fakeScratchTrees) Snapshot(context.Context, string, string) error { return nil }
|
||||
|
||||
// TestExecuteTaskRequestStartsWorkflowCallCallee proves the engine's
|
||||
// task.Caller wiring end to end: a run of a repository-none workflow carrying
|
||||
// one workflow.call step starts a real callee task row through the same
|
||||
// State Store gRPC contract the production worker dials
|
||||
// (docs/prds/workflow-calls.md), and the caller carries on to its tail.
|
||||
func TestExecuteTaskRequestStartsWorkflowCallCallee(t *testing.T) {
|
||||
ctx := t.Context()
|
||||
st := pgstore.Open(t)
|
||||
|
||||
const callerYAML = "id: caller\nrepository: none\ninputs:\n src_ip: {type: string}\nsteps:\n - type: workflow.call\n settings:\n workflow: callee\n inputs: {src_ip: \"inputs.src_ip\"}\n wait: false\n - type: agent.run\n settings:\n mission: report\n"
|
||||
// A real caller row, claimed and running, so the store's enqueue reads
|
||||
// the same row shape production does.
|
||||
task, err := st.EnqueueChatTask(ctx, "", "", "workflow.call integration", "", "caller", "", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("seed caller task: %v", err)
|
||||
}
|
||||
if err := st.Transition(ctx, task.ID, task.Status, workflow.StatusRunning, "started"); err != nil {
|
||||
t.Fatalf("claim caller: %v", err)
|
||||
}
|
||||
task.Status = workflow.StatusRunning
|
||||
task.Inputs = map[string]any{"src_ip": "10.0.0.9"}
|
||||
task.WorkflowDefinitionYAML = callerYAML
|
||||
task.WorkflowDefinitionDigest = workflow.DigestDefinition(callerYAML)
|
||||
if err := st.Update(ctx, task); err != nil {
|
||||
t.Fatalf("seed caller task: %v", err)
|
||||
}
|
||||
|
||||
natsSrv := startEmbeddedTaskRPCServer(t)
|
||||
transport, err := agentnats.Connect(ctx, agentnats.Config{
|
||||
URL: natsSrv.ClientURL(),
|
||||
StateStoreURL: startStateStoreGRPC(t, st),
|
||||
}, slog.New(slog.DiscardHandler))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
t.Cleanup(transport.Close)
|
||||
|
||||
workDir := t.TempDir()
|
||||
request := taskrun.Request{
|
||||
Task: task,
|
||||
Repo: config.Repo{},
|
||||
Cfg: config.Config{Models: map[string]string{"builder": "p/m"}}.ForTask(),
|
||||
WorkflowDefinition: callerYAML,
|
||||
}
|
||||
dependencies := taskDependencies{
|
||||
store: transport.Store(rpcTimeout),
|
||||
calls: transport.Calls(rpcTimeout),
|
||||
trees: &fakeScratchTrees{dir: workDir},
|
||||
steps: testSteps(t),
|
||||
}
|
||||
fakeRunner := runnerFactory(func(map[string]agentexec.Provider, *slog.Logger) agentexec.Runner { return stubRunner{} })
|
||||
response, err := runTask(ctx, request, dependencies, fakeRunner, workDir, slog.New(slog.DiscardHandler))
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if response.Status != workflow.StatusCompleted {
|
||||
t.Fatalf("response status = %q (park reason %q), want completed", response.Status, response.Task.ParkReason)
|
||||
}
|
||||
|
||||
callee := calleeTaskOf(t, ctx, st, task.ID)
|
||||
if callee.Workflow != "callee" || callee.CallParentTaskID != task.ID || callee.CallDepth != 1 {
|
||||
t.Fatalf("callee = %+v, want workflow callee linked to task %d at depth 1", callee, task.ID)
|
||||
}
|
||||
if callee.Inputs["src_ip"] != "10.0.0.9" {
|
||||
t.Fatalf("callee inputs = %+v, want the call's resolved reference", callee.Inputs)
|
||||
}
|
||||
if callee.Org != org.OrgID("default") {
|
||||
t.Fatalf("callee org = %q, want the caller's %q", callee.Org, task.Org)
|
||||
}
|
||||
}
|
||||
|
||||
// calleeTaskOf reads the one callee task whose call_parent_task_id is
|
||||
// callerTaskID, straight off the pool the test owns.
|
||||
func calleeTaskOf(t *testing.T, ctx context.Context, st *pgstore.TaskDB, callerTaskID int64) *workflow.Task {
|
||||
t.Helper()
|
||||
rows, err := st.Pool.Query(ctx,
|
||||
`SELECT id, workflow, call_parent_task_id, call_depth, org_id, inputs
|
||||
FROM tasks WHERE call_parent_task_id = $1`, callerTaskID)
|
||||
if err != nil {
|
||||
t.Fatalf("callee query: %v", err)
|
||||
}
|
||||
defer rows.Close()
|
||||
var callees []*workflow.Task
|
||||
for rows.Next() {
|
||||
var id, parent, depth int64
|
||||
var wf, orgID, inputs string
|
||||
if err := rows.Scan(&id, &wf, &parent, &depth, &orgID, &inputs); err != nil {
|
||||
t.Fatalf("callee scan: %v", err)
|
||||
}
|
||||
decoded, _ := workflowtask.DecodeInputs(inputs)
|
||||
callees = append(callees, &workflow.Task{
|
||||
ID: id, Workflow: wf, CallParentTaskID: parent, CallDepth: int(depth),
|
||||
Org: org.OrgID(orgID), Inputs: decoded,
|
||||
})
|
||||
}
|
||||
if err := rows.Err(); err != nil {
|
||||
t.Fatalf("callee rows: %v", err)
|
||||
}
|
||||
if len(callees) != 1 {
|
||||
t.Fatalf("callee tasks of %d = %+v, want exactly one", callerTaskID, callees)
|
||||
}
|
||||
return callees[0]
|
||||
}
|
||||
@@ -8,6 +8,7 @@ import (
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/agentboot"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/agentgit"
|
||||
agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats"
|
||||
@@ -50,6 +51,7 @@ type workerTransport interface {
|
||||
SubscribeTasks(context.Context, int64, agentnats.TaskHandler, *slog.Logger) (agentnats.Subscription, error)
|
||||
Forger(string, time.Duration) workflow.Forger
|
||||
Store(time.Duration) workflow.Store
|
||||
Calls(time.Duration) task.Caller
|
||||
Trees(string, string, time.Duration) agentnats.RemoteTrees
|
||||
}
|
||||
|
||||
@@ -152,6 +154,7 @@ func run(ctx context.Context, settings Settings, log *slog.Logger, dependencies
|
||||
type taskServiceTransport interface {
|
||||
Forger(string, time.Duration) workflow.Forger
|
||||
Store(time.Duration) workflow.Store
|
||||
Calls(time.Duration) task.Caller
|
||||
Trees(string, string, time.Duration) agentnats.RemoteTrees
|
||||
EventPublisher() agentexec.EventPublisher
|
||||
}
|
||||
@@ -161,6 +164,7 @@ func executeTaskRequest(ctx context.Context, request taskrun.Request, transport
|
||||
dependencies := taskDependencies{
|
||||
forge: transport.Forger(request.Task.Identity, rpcTimeout),
|
||||
store: transport.Store(rpcTimeout),
|
||||
calls: transport.Calls(rpcTimeout),
|
||||
trees: transport.Trees(request.Task.Identity, request.WorktreeGrant, rpcTimeout),
|
||||
events: transport.EventPublisher(),
|
||||
steps: steps,
|
||||
|
||||
@@ -11,6 +11,7 @@ import (
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
agentnats "github.com/samcharles93/archie-core/internal/infrastructure/agenttransport/nats"
|
||||
)
|
||||
|
||||
@@ -75,6 +76,8 @@ func (*workerTransportStub) Forger(string, time.Duration) workflow.Forger { retu
|
||||
|
||||
func (*workerTransportStub) Store(time.Duration) workflow.Store { return nil }
|
||||
|
||||
func (*workerTransportStub) Calls(time.Duration) task.Caller { return nil }
|
||||
|
||||
func (*workerTransportStub) Trees(string, string, time.Duration) agentnats.RemoteTrees { return nil }
|
||||
|
||||
func TestRunPassesCompleteTransportConfiguration(t *testing.T) {
|
||||
|
||||
@@ -0,0 +1,110 @@
|
||||
// The `archied access reset` command: the locked-out-org and broken-instance
|
||||
// recovery surface (docs/prds/orgs-and-access.md, "Recovering from a
|
||||
// locked-out org"). It restores the shipped role policies for one org and
|
||||
// removes its other org-level policies, or removes the stored instance
|
||||
// policies; the cross-org forbid is engine-enforced and survives any reset.
|
||||
//
|
||||
// It runs only on the State Store host, never over the network, and is
|
||||
// recorded as an audit event. It claims the same store ownership the State
|
||||
// Store holds, so a running store refuses it: stop the store, reset, start
|
||||
// the store.
|
||||
package archied
|
||||
|
||||
import (
|
||||
"context"
|
||||
"flag"
|
||||
"fmt"
|
||||
"io"
|
||||
|
||||
"github.com/jackc/pgx/v5/pgxpool"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/domain/access"
|
||||
"github.com/samcharles93/archie-core/internal/domain/org"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres"
|
||||
)
|
||||
|
||||
// accessResetCommand is the argv selector for the recovery command.
|
||||
const accessResetCommand = "access"
|
||||
|
||||
// IsAccessResetArgs reports whether args selects the access recovery command.
|
||||
func IsAccessResetArgs(args []string) bool {
|
||||
return len(args) > 2 && args[0] == accessResetCommand && args[1] == resetCommand
|
||||
}
|
||||
|
||||
const resetCommand = "reset"
|
||||
|
||||
// RunAccessReset performs the reset and returns the process exit code:
|
||||
// 0 reset, 1 failure, 2 usage.
|
||||
func RunAccessReset(ctx context.Context, args []string, stderr io.Writer) int {
|
||||
fs := flag.NewFlagSet(resetCommand, flag.ContinueOnError)
|
||||
fs.SetOutput(stderr)
|
||||
cfgPath := fs.String("config", configuration.DefaultConfigPath(), "path to a TOML/YAML config file or configuration directory")
|
||||
overlayPath := fs.String("config-overlay", "", "path to a TOML/YAML overlay file or configuration directory applied on top of -config")
|
||||
orgFlag := fs.String("org", "", "org whose access to reset; conflicts with --instance")
|
||||
instance := fs.Bool("instance", false, "reset the stored instance policies")
|
||||
if err := fs.Parse(args); err != nil {
|
||||
return 2
|
||||
}
|
||||
if fs.NArg() > 0 {
|
||||
fmt.Fprintf(stderr, "reset: unexpected argument %q\n", fs.Arg(0))
|
||||
return 2
|
||||
}
|
||||
if (*orgFlag != "" && *instance) || (*orgFlag == "" && !*instance) {
|
||||
fmt.Fprintln(stderr, "reset: give exactly one of --org <org> or --instance")
|
||||
return 2
|
||||
}
|
||||
|
||||
b := newBootstrap()
|
||||
defer b.cleanup()
|
||||
if err := b.loadConfig(ctx, *cfgPath, *overlayPath); err != nil {
|
||||
return 1
|
||||
}
|
||||
if err := b.openStateStorePool(ctx); err != nil {
|
||||
// A running State Store holds the ownership claim; the reset must not
|
||||
// race it. Stop the store, reset, start the store.
|
||||
fmt.Fprintln(stderr, "reset: open the State Store database (stop archie-state-store first)")
|
||||
return 1
|
||||
}
|
||||
resetter, ok := b.st.(access.Resetter)
|
||||
if !ok {
|
||||
fmt.Fprintln(stderr, "reset: the State Store does not support the access reset surface")
|
||||
return 1
|
||||
}
|
||||
var err error
|
||||
switch {
|
||||
case *instance:
|
||||
err = resetter.ResetInstancePolicies(ctx)
|
||||
default:
|
||||
err = resetter.ResetOrgPolicies(ctx, org.OrgID(*orgFlag))
|
||||
}
|
||||
if err != nil {
|
||||
fmt.Fprintf(stderr, "reset: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
if err := recordResetAudit(ctx, b.pg, *orgFlag, *instance); err != nil {
|
||||
fmt.Fprintf(stderr, "reset: audit: %v\n", err)
|
||||
return 1
|
||||
}
|
||||
fmt.Fprintf(stderr, "reset: access policies for %s restored to the shipped set\n", resetTarget(*orgFlag, *instance))
|
||||
return 0
|
||||
}
|
||||
|
||||
// resetTarget names what the reset covered, for the operator's output.
|
||||
func resetTarget(orgID string, instance bool) string {
|
||||
if instance {
|
||||
return "the instance"
|
||||
}
|
||||
return fmt.Sprintf("org %q", orgID)
|
||||
}
|
||||
|
||||
// recordResetAudit writes the one audit row the reset is recorded as. The
|
||||
// policy changes themselves carry their own sys_audit rows; this names the
|
||||
// recovery.
|
||||
func recordResetAudit(ctx context.Context, pool *pgxpool.Pool, orgID string, instance bool) error {
|
||||
key := "reset/instance"
|
||||
if !instance {
|
||||
key = fmt.Sprintf("reset/org/%s", orgID)
|
||||
}
|
||||
return postgres.New(pool).RecordResetAudit(ctx, key)
|
||||
}
|
||||
@@ -0,0 +1,54 @@
|
||||
package archied
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func TestIsAccessResetArgs(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
args []string
|
||||
want bool
|
||||
}{
|
||||
{name: "org reset", args: []string{"access", "reset", "--org", "acme"}, want: true},
|
||||
{name: "instance reset", args: []string{"access", "reset", "--instance"}, want: true},
|
||||
{name: "config first", args: []string{"access", "reset", "-config", "/tmp/config.toml", "--org", "acme"}, want: true},
|
||||
{name: "setup is not a reset", args: []string{"setup"}, want: false},
|
||||
{name: "bare access", args: []string{"access"}, want: false},
|
||||
{name: "other subcommand", args: []string{"access", "grant"}, want: false},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if got := IsAccessResetArgs(tt.args); got != tt.want {
|
||||
t.Fatalf("IsAccessResetArgs(%v) = %v, want %v", tt.args, got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestRunAccessResetUsage(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
args []string
|
||||
wantCode int
|
||||
wantText string
|
||||
}{
|
||||
{name: "no target", args: nil, wantCode: 2, wantText: "exactly one of --org"},
|
||||
{name: "both targets", args: []string{"--org", "acme", "--instance"}, wantCode: 2, wantText: "exactly one of --org"},
|
||||
{name: "unexpected argument", args: []string{"--instance", "extra"}, wantCode: 2, wantText: "unexpected argument"},
|
||||
{name: "unknown flag", args: []string{"--workspace", "net"}, wantCode: 2},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
var stderr strings.Builder
|
||||
code := RunAccessReset(t.Context(), tt.args, &stderr)
|
||||
if code != tt.wantCode {
|
||||
t.Fatalf("RunAccessReset(%v) = %d, want %d (stderr: %s)", tt.args, code, tt.wantCode, stderr.String())
|
||||
}
|
||||
if tt.wantText != "" && !strings.Contains(stderr.String(), tt.wantText) {
|
||||
t.Fatalf("stderr = %q, want it to name %q", stderr.String(), tt.wantText)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -30,6 +30,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/container"
|
||||
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
|
||||
"github.com/samcharles93/archie-core/internal/daemon"
|
||||
"github.com/samcharles93/archie-core/internal/domain/access"
|
||||
"github.com/samcharles93/archie-core/internal/domain/applystatus"
|
||||
"github.com/samcharles93/archie-core/internal/domain/curator"
|
||||
"github.com/samcharles93/archie-core/internal/domain/eda/module"
|
||||
@@ -46,6 +47,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/forge"
|
||||
forgewebhook "github.com/samcharles93/archie-core/internal/forge/webhook"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
infraaccess "github.com/samcharles93/archie-core/internal/infrastructure/access"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
infraembedding "github.com/samcharles93/archie-core/internal/infrastructure/embedding"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/eventbus/nats"
|
||||
@@ -124,6 +126,11 @@ type boot struct {
|
||||
// set. The b.st field remains solely for the standalone archie-state-store
|
||||
// binary, which serves the task store from Postgres.
|
||||
stateStore storecontract.TaskStore
|
||||
// accessChain is the daemon's policy engine, built once from the stored
|
||||
// policies (openAccessChain); accessProblems is what the readiness
|
||||
// surface reports. Both are nil when no policy store is wired.
|
||||
accessChain access.Authorizer
|
||||
accessProblems []infraaccess.Problem
|
||||
// stateStoreGrants issues per-task, scoped State Store credentials for
|
||||
// agent containers (daemon.StateStoreGrantIssuer), wrapping the same
|
||||
// *staterpc.Client as stateStore. Nil when the State Store adapter isn't
|
||||
@@ -213,7 +220,16 @@ type boot struct {
|
||||
kitLauncher daemon.KitLauncher
|
||||
storeBackend storage.Backend
|
||||
|
||||
llm *runtime.Runtime
|
||||
// llm is the chat runtime's provider runtime, held in a pointer the chat
|
||||
// surfaces read through chatLLM at each use. A live provider-settings or
|
||||
// model-role-assignments update swaps it wholesale: ai-sdk's Runtime
|
||||
// caches the provider instances it built, so a changed provider set needs
|
||||
// a new Runtime rather than a mutated one.
|
||||
llm atomic.Pointer[runtime.Runtime]
|
||||
// runtimeVersions records the version of every control-plane kind boot's
|
||||
// layering applied. Set once at boot before the runtime-resource watches
|
||||
// start, which read it as their resume points.
|
||||
runtimeVersions map[string]int64
|
||||
|
||||
// embeddings is nil unless models["embedding"] and a working provider
|
||||
// credential are both configured -- see setupLLMAndChat's "Embeddings
|
||||
@@ -222,15 +238,11 @@ type boot struct {
|
||||
// unrelated call.
|
||||
embeddings domainembedding.Client
|
||||
|
||||
toolReg *tools.Registry
|
||||
chatModels gateway.ModelManager
|
||||
personas *gateway.PersonaRegistry
|
||||
chatTasks gateway.TaskCreator
|
||||
chatController *gateway.StoreTaskController
|
||||
// chatPRReviewer is the operator-triggered PR review capability, built
|
||||
// once and shared by every channel so a review in flight on one channel
|
||||
// is deduplicated against the same request on another (single-flight).
|
||||
chatPRReviewer gateway.ChatPRReviewer
|
||||
toolReg *tools.Registry
|
||||
chatModels *chatModelManager
|
||||
personas *gateway.PersonaRegistry
|
||||
chatTasks gateway.TaskCreator
|
||||
chatController *gateway.StoreTaskController
|
||||
defaultChatIdentity string
|
||||
updateService *releaseupdate.Service
|
||||
|
||||
@@ -279,6 +291,16 @@ func newBootstrap() *boot {
|
||||
return &boot{log: slog.New(slog.NewJSONHandler(os.Stderr, nil)), agentStatus: &daemon.AgentStatus{}}
|
||||
}
|
||||
|
||||
// chatLLM is the provider runtime the chat surfaces read at each use: a turn
|
||||
// resolves it when it starts, so a runtime swapped by a live model-settings
|
||||
// update is the one the turn after it runs on.
|
||||
func (b *boot) chatLLM() *runtime.Runtime { return b.llm.Load() }
|
||||
|
||||
// setLLM replaces the chat runtime. A nil runtime is a legal state: a
|
||||
// deployment whose every provider credential was disabled by a live update
|
||||
// leaves chat turns refused until another update restores one.
|
||||
func (b *boot) setLLM(rt *runtime.Runtime) { b.llm.Store(rt) }
|
||||
|
||||
func (b *boot) addCleanup(fn func()) {
|
||||
b.cleanups = append(b.cleanups, fn)
|
||||
}
|
||||
@@ -416,6 +438,47 @@ func (b *boot) openStateStoreAdapter() error {
|
||||
return nil
|
||||
}
|
||||
|
||||
// openStateStage opens the state-store adapter and its daemon-side surfaces
|
||||
// plus the policy chain, in one step of the composition sequence: the three
|
||||
// are ordered but not interleaved, and any failure fails the boot
|
||||
// (openStateStoreAdapter, openDaemonStateSurfaces, openAccessChain).
|
||||
func (b *boot) openStateStage(ctx context.Context) error {
|
||||
if err := b.openStores(ctx); err != nil {
|
||||
return err
|
||||
}
|
||||
if err := b.openDaemonStateSurfaces(); err != nil {
|
||||
return err
|
||||
}
|
||||
return b.openAccessChain(ctx)
|
||||
}
|
||||
|
||||
// openAccessChain builds the policy chain the daemon dispatches through
|
||||
// (docs/prds/orgs-and-access.md, "Where it lives"): the stored policies over
|
||||
// the wire, compiled once at boot. An invalid instance policy fails the boot;
|
||||
// an invalid org, workspace or object policy is retained as a health problem
|
||||
// and its level denies everything.
|
||||
func (b *boot) openAccessChain(ctx context.Context) error {
|
||||
source, ok := b.stateStore.(access.PolicySource)
|
||||
if !ok {
|
||||
return nil // no policy store wired: the chain is not built
|
||||
}
|
||||
stored, err := source.Policies(ctx)
|
||||
if err != nil {
|
||||
return fmt.Errorf("load stored policies: %w", err)
|
||||
}
|
||||
engine, err := infraaccess.New(stored)
|
||||
if err != nil {
|
||||
return fmt.Errorf("validate stored policies: %w", err)
|
||||
}
|
||||
b.accessChain = engine
|
||||
b.accessProblems = engine.Problems()
|
||||
for _, problem := range b.accessProblems {
|
||||
b.log.Error("stored access policy is invalid and denies its level",
|
||||
"policy", problem.Policy.ID, "level", problem.Policy.Level, "err", problem.Err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// openChatSessions opens the conversation store on its own pool from
|
||||
// database_url. The daemon reads it (session curator) and the Gateway serves
|
||||
// it; only the Gateway claims serve ownership (claimGatewayOwnership).
|
||||
@@ -863,10 +926,10 @@ func (b *boot) loadPlugins() error {
|
||||
|
||||
// buildWorktreeManager composes the process-wide worktree manager from the
|
||||
// resolved primary forge credential and the loaded config. Both process roots
|
||||
// own one: the daemon works tasks in it, and the Gateway materialises a pull
|
||||
// request head in it when an operator asks for a review (boot.prReviewer
|
||||
// refuses to build a reviewer without one, so a Gateway that skips this step
|
||||
// advertises no review_pr). It reads only, so it has nothing to report.
|
||||
// own one: the daemon works tasks in it, and the Gateway used it to
|
||||
// materialise a pull request head for the now-removed synchronous
|
||||
// operator-review path (archie-core-afbk.7). It reads only, so it has
|
||||
// nothing to report.
|
||||
//
|
||||
// Identity managers are not built here: buildTreesAndIdentities builds one per
|
||||
// identity, each in its own WorkDir, because the Gateway must not own daemon
|
||||
@@ -1087,7 +1150,7 @@ func (b *boot) setupCurators(ctx context.Context) {
|
||||
// (TurnRunnerConfig.BotUser), so a fact written here is a fact a later
|
||||
// turn reaches.
|
||||
Conversations: sessioncurator.NewAdapter(b.chatSessionStore, b.cfg.BotUser),
|
||||
LLM: curatorLLMRunner{rt: b.llm, outcomes: b.providerOutcomes},
|
||||
LLM: curatorLLMRunner{llm: b.chatLLM, outcomes: b.providerOutcomes},
|
||||
// b.chatModels.ActiveModel() is the same source sendChatTurn uses
|
||||
// for a real chat turn (telegram_setup.go) -- not
|
||||
// b.defaultChatIdentity, which names a task-routing identity, not
|
||||
@@ -1368,6 +1431,18 @@ func (b *boot) buildDaemon() {
|
||||
if btc, ok := b.stateStore.(storecontract.BindingTaskCreator); ok {
|
||||
b.d.BindingTaskCreator = btc
|
||||
}
|
||||
// Dispatch is the second Authorizer call site: the chain built by
|
||||
// openAccessChain, the principal assembly over the wire, and the denial
|
||||
// record -- wired together or not at all (docs/prds/orgs-and-access.md).
|
||||
b.d.Access = b.accessChain
|
||||
if b.accessChain != nil {
|
||||
if principals, ok := b.stateStore.(access.PrincipalSource); ok {
|
||||
b.d.Principals = principals
|
||||
}
|
||||
if denials, ok := b.stateStore.(access.DenialStore); ok {
|
||||
b.d.Denials = denials
|
||||
}
|
||||
}
|
||||
b.d.PlaybookLedger = playbookLedger(b.stateStore, b.playbooks, b.log)
|
||||
b.setupForgeWebhook()
|
||||
}
|
||||
|
||||
@@ -15,14 +15,29 @@ import (
|
||||
// The configured role-to-model map supplies the available catalog; switching
|
||||
// chat models does not rewrite daemon configuration or affect workflow roles.
|
||||
type chatModelManager struct {
|
||||
mu sync.RWMutex
|
||||
models []string
|
||||
active string
|
||||
mu sync.RWMutex
|
||||
models []string
|
||||
active string
|
||||
// catalogs are the non-role sources the model set is derived from, kept
|
||||
// so SetConfigured can rebuild it after a live settings update without a
|
||||
// caller re-passing them.
|
||||
catalogs [][]string
|
||||
details map[string]gateway.ModelDetails
|
||||
providerNames map[string]string
|
||||
}
|
||||
|
||||
func newChatModelManager(configured map[string]string, catalogs ...[]string) *chatModelManager {
|
||||
// pickChatDefault is the model the manager starts on: the chat role's
|
||||
// assignment, falling back to the builder role's.
|
||||
func pickChatDefault(configured map[string]string) string {
|
||||
if active := strings.TrimSpace(configured["chat"]); active != "" {
|
||||
return active
|
||||
}
|
||||
return strings.TrimSpace(configured["builder"])
|
||||
}
|
||||
|
||||
// mergeModelRefs is the model set the manager offers: the configured role
|
||||
// assignments plus every catalog, unique and sorted.
|
||||
func mergeModelRefs(configured map[string]string, catalogs ...[]string) []string {
|
||||
unique := make(map[string]struct{}, len(configured))
|
||||
for _, ref := range configured {
|
||||
ref = strings.TrimSpace(ref)
|
||||
@@ -44,18 +59,35 @@ func newChatModelManager(configured map[string]string, catalogs ...[]string) *ch
|
||||
models = append(models, ref)
|
||||
}
|
||||
slices.Sort(models)
|
||||
return models
|
||||
}
|
||||
|
||||
active := strings.TrimSpace(configured["chat"])
|
||||
if active == "" {
|
||||
active = strings.TrimSpace(configured["builder"])
|
||||
}
|
||||
func newChatModelManager(configured map[string]string, catalogs ...[]string) *chatModelManager {
|
||||
return &chatModelManager{
|
||||
models: models, active: active,
|
||||
models: mergeModelRefs(configured, catalogs...),
|
||||
active: pickChatDefault(configured),
|
||||
catalogs: append([][]string(nil), catalogs...),
|
||||
details: make(map[string]gateway.ModelDetails),
|
||||
providerNames: make(map[string]string),
|
||||
}
|
||||
}
|
||||
|
||||
// SetConfigured re-derives the model set the manager offers after a live
|
||||
// change to model-role-assignments or provider-settings: the list is built
|
||||
// from the configured roles at construction, so a stored change would leave
|
||||
// the chat surfaces offering refs the runtime can no longer resolve. The
|
||||
// operator's active selection survives when the new roles still carry it; a
|
||||
// removed one falls back the way construction does.
|
||||
func (m *chatModelManager) SetConfigured(configured map[string]string) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
models := mergeModelRefs(configured, m.catalogs...)
|
||||
if !slices.Contains(models, m.active) {
|
||||
m.active = pickChatDefault(configured)
|
||||
}
|
||||
m.models = models
|
||||
}
|
||||
|
||||
func (m *chatModelManager) ApplyModelCatalog(snapshot modelcatalog.Snapshot) {
|
||||
m.mu.Lock()
|
||||
defer m.mu.Unlock()
|
||||
|
||||
@@ -28,8 +28,12 @@ type chatSetup struct {
|
||||
// Cfg is read once per setup function via Get(); the process is not
|
||||
// running yet at this point, so the reload-safe Holder is mostly a
|
||||
// formality, but matching the daemon's API keeps callers honest.
|
||||
Cfg *config.Holder
|
||||
LLM *runtime.Runtime
|
||||
Cfg *config.Holder
|
||||
// LLM resolves the provider runtime at each use: a live provider-settings
|
||||
// or model-role-assignments update swaps the runtime wholesale (ai-sdk's
|
||||
// Runtime caches the provider instances it built), so the pointer cannot
|
||||
// be captured at construction. nil means no model runtime is configured.
|
||||
LLM func() *runtime.Runtime
|
||||
ChatModels gateway.ModelManager
|
||||
ToolReg *tools.Registry
|
||||
Personas *gateway.PersonaRegistry
|
||||
@@ -37,7 +41,6 @@ type chatSetup struct {
|
||||
ChatTaskLister gateway.ChatTaskLister
|
||||
ChatTaskLogs gateway.ChatTaskLogReader
|
||||
ChatTaskActor gateway.ChatTaskActor
|
||||
ChatPRReviewer gateway.ChatPRReviewer
|
||||
DefaultChatIdentity string
|
||||
// Bus carries primary-input events (archie-core-035): a completed
|
||||
// chat turn is published here so input-driven curators can wake. Nil
|
||||
@@ -152,7 +155,7 @@ func makeChatLLMResponder(
|
||||
sessionStore gateway.SessionStore,
|
||||
router *gateway.Router,
|
||||
) (gateway.LLMResponder, gateway.LLMStreamResponder) {
|
||||
if s.LLM == nil {
|
||||
if s.LLM == nil || s.LLM() == nil {
|
||||
return nil, nil
|
||||
}
|
||||
runner := newChatTurnRunner(ctx, channel, s, sessionStore, router)
|
||||
@@ -178,7 +181,6 @@ func newChatTurnRunner(
|
||||
TaskLogs: s.ChatTaskLogs,
|
||||
TaskActor: s.ChatTaskActor,
|
||||
TaskIdentity: s.DefaultChatIdentity,
|
||||
PRReviewer: s.ChatPRReviewer,
|
||||
Bus: s.Bus,
|
||||
BotUser: cfg.BotUser,
|
||||
Channel: channel,
|
||||
@@ -365,7 +367,7 @@ func multimodalMediaRefs(output string) []tools.MediaRef {
|
||||
// untitled and are logged here.
|
||||
type chatTitleGenerator struct {
|
||||
log *slog.Logger
|
||||
llm *runtime.Runtime
|
||||
llm func() *runtime.Runtime
|
||||
chatModels gateway.ModelManager
|
||||
}
|
||||
|
||||
@@ -395,7 +397,11 @@ func (g *chatTitleGenerator) GenerateTitle(ctx context.Context, sessionID, first
|
||||
// broken provider on the strength of a call no user was waiting for.
|
||||
// No tool set and no stream, so no tool call can be reported: this turn
|
||||
// needs no icons.
|
||||
text, err := sendChatTurn(ctx, g.llm, g.chatModels.ActiveModel(),
|
||||
llm := g.llm()
|
||||
if llm == nil {
|
||||
return "", fmt.Errorf("no model runtime is configured")
|
||||
}
|
||||
text, err := sendChatTurn(ctx, llm, g.chatModels.ActiveModel(),
|
||||
core.GenerateOptions{Messages: messages, MaxSteps: 1}, nil, nil, nil)
|
||||
if err != nil {
|
||||
if g.log != nil {
|
||||
|
||||
@@ -3,6 +3,7 @@ package archied
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
|
||||
"github.com/samcharles93/ai-sdk/chat"
|
||||
"github.com/samcharles93/ai-sdk/core"
|
||||
@@ -17,7 +18,9 @@ import (
|
||||
// provider-neutral TurnModel seam. Tool construction remains here because it
|
||||
// depends on runtime registries and configured execution limits.
|
||||
type chatTurnModel struct {
|
||||
llm *runtime.Runtime
|
||||
// llm resolves the provider runtime at each turn, so a runtime swapped by
|
||||
// a live model-settings update is the one the turn after it runs on.
|
||||
llm func() *runtime.Runtime
|
||||
registry *tools.Registry
|
||||
maxSteps int
|
||||
limits agentexec.ToolLimits
|
||||
@@ -26,7 +29,7 @@ type chatTurnModel struct {
|
||||
}
|
||||
|
||||
func newChatTurnModel(
|
||||
llm *runtime.Runtime,
|
||||
llm func() *runtime.Runtime,
|
||||
registry *tools.Registry,
|
||||
maxSteps int,
|
||||
limits agentexec.ToolLimits,
|
||||
@@ -54,7 +57,7 @@ func (m *chatTurnModel) Prepare(
|
||||
return nil, err
|
||||
}
|
||||
return &preparedChatTurnModel{
|
||||
llm: m.llm,
|
||||
llm: m.llm(),
|
||||
model: req.Model,
|
||||
options: options,
|
||||
toolInfo: toolSummaries(options.Tools),
|
||||
@@ -121,5 +124,10 @@ func (m *preparedChatTurnModel) Generate(
|
||||
// This is one provider response's output allowance, not a turn-
|
||||
// continuation budget. Tool loops remain free to continue.
|
||||
options.MaxTokens = request.MaxOutputTokens
|
||||
// A runtime swapped to nil -- a live update that left no usable provider
|
||||
// configured -- is a refused turn, not a panic.
|
||||
if m.llm == nil {
|
||||
return "", fmt.Errorf("llm chat: no model runtime is configured")
|
||||
}
|
||||
return sendChatTurn(ctx, m.llm, m.model, options, stream, m.outcomes, m.icons)
|
||||
}
|
||||
@@ -32,29 +32,3 @@ func TestStartGatewayRuntimeSetsUpMemoryBeforeGatewayChat(t *testing.T) {
|
||||
t.Fatal("startGatewayRuntime wires setupGatewayChat before setupMemoryEngine; the turn runner would capture a nil memory engine")
|
||||
}
|
||||
}
|
||||
|
||||
// TestStartGatewayRuntimeBuildsWorktreeManagerBeforeGatewayChat pins the
|
||||
// Gateway's own worktree-manager ordering. The Gateway owns PR review, so
|
||||
// startGatewayRuntime must compose the process-wide worktree manager before
|
||||
// setupGatewayChat resolves boot.prReviewer: prReviewer returns nil without a
|
||||
// manager, and a nil reviewer omits review_pr from every channel's tool set
|
||||
// (internal/gateway/review_tools.go). The Gateway deliberately does not call
|
||||
// buildTreesAndIdentities -- that also registers daemon identity runners it
|
||||
// must not own -- so nothing at runtime connects the manager to this
|
||||
// composition phase except the call this asserts on.
|
||||
func TestStartGatewayRuntimeBuildsWorktreeManagerBeforeGatewayChat(t *testing.T) {
|
||||
fileset := token.NewFileSet()
|
||||
file, err := parser.ParseFile(fileset, "gateway.go", nil, 0)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
run := methodBody(t, file, "startGatewayRuntime")
|
||||
trees := methodCallPosition(run, "buildWorktreeManager")
|
||||
chat := methodCallPosition(run, "setupGatewayChat")
|
||||
if trees == token.NoPos || chat == token.NoPos {
|
||||
t.Fatalf("startGatewayRuntime call positions: buildWorktreeManager=%v setupGatewayChat=%v, want both present", trees, chat)
|
||||
}
|
||||
if chat < trees {
|
||||
t.Fatal("startGatewayRuntime wires setupGatewayChat before buildWorktreeManager; the Gateway would resolve a nil reviewer and never advertise review_pr")
|
||||
}
|
||||
}
|
||||
@@ -5,8 +5,10 @@ import (
|
||||
"encoding/json"
|
||||
"log/slog"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/configuration"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
|
||||
"github.com/samcharles93/archie-core/internal/webui"
|
||||
@@ -136,3 +138,30 @@ func TestPublishConfigSnapshotWithoutConfiguration(t *testing.T) {
|
||||
t.Fatalf("ConfigSnapshot = (found %v, %v), want nothing published", found, err)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLiveSettingsApplyRepublishesTheConfigSnapshot: the dashboard renders the
|
||||
// published projection, not the daemon's Holder, so a live apply that changes
|
||||
// the running config must republish it or the page keeps showing the old
|
||||
// values until the next reload.
|
||||
func TestLiveSettingsApplyRepublishesTheConfigSnapshot(t *testing.T) {
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
b, _ := newLiveApplyBoot(t, fileConfig())
|
||||
b.stateStore = st
|
||||
if err := b.applyWorkflowExecutionSettings(t.Context(), workflow.ExecutionSettings{MaxModelToolSteps: 25, MaxRuntime: time.Hour, MaxConsecutiveGateFailures: 4}, 2); err != nil {
|
||||
t.Fatalf("live update: %v", err)
|
||||
}
|
||||
|
||||
snapshot, found, err := st.ConfigSnapshot(context.Background())
|
||||
if err != nil || !found {
|
||||
t.Fatalf("ConfigSnapshot = (found %v, %v), want the live apply to publish one", found, err)
|
||||
}
|
||||
var view webui.ConfigView
|
||||
if err := json.Unmarshal(snapshot.Document, &view); err != nil {
|
||||
t.Fatalf("decode published document: %v", err)
|
||||
}
|
||||
if view.Budgets.MaxSteps != 25 || view.Budgets.GateMaxFailures != 4 {
|
||||
t.Errorf("published budgets = %+v, want the live-applied limits", view.Budgets)
|
||||
}
|
||||
}
|
||||
@@ -5,6 +5,7 @@ import (
|
||||
"fmt"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/app/controlplane"
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
@@ -16,10 +17,10 @@ import (
|
||||
// reload re-resolves the file document alone, so republishing that document
|
||||
// as it stands reverts each of these layers to its file value until the
|
||||
// process restarts (archie-core-ju85).
|
||||
func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Config, error) {
|
||||
func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Config, map[string]int64, error) {
|
||||
cfg, versions, err := b.controlPlane.RuntimeConfig(ctx, base)
|
||||
if err != nil {
|
||||
return config.Config{}, err
|
||||
return config.Config{}, nil, err
|
||||
}
|
||||
if settings := b.executionSettings.Load(); settings != nil {
|
||||
applyExecutionBudgets(&cfg, *settings)
|
||||
@@ -27,17 +28,17 @@ func (b *boot) runtimeConfig(ctx context.Context, base config.Config) (config.Co
|
||||
if err := configuration.Validate(&cfg); err != nil {
|
||||
wrapped := fmt.Errorf("validate database settings: %w", err)
|
||||
b.reportApplied(ctx, versions, wrapped)
|
||||
return config.Config{}, wrapped
|
||||
return config.Config{}, nil, wrapped
|
||||
}
|
||||
// The State Store persists source references, while openStores resolved
|
||||
// only the file snapshot. Layering provider-settings restores the source
|
||||
// references, so resolve the effective map before any runtime consumes it.
|
||||
if err := resolveProviderSecrets(&cfg, b.secrets, b.log); err != nil {
|
||||
b.reportApplied(ctx, versions, err)
|
||||
return config.Config{}, err
|
||||
return config.Config{}, nil, err
|
||||
}
|
||||
b.reportApplied(ctx, versions, nil)
|
||||
return cfg, nil
|
||||
return cfg, versions, nil
|
||||
}
|
||||
|
||||
// reportApplied publishes the version of each kind this process just layered
|
||||
@@ -50,12 +51,17 @@ func (b *boot) reportApplied(ctx context.Context, versions map[string]int64, app
|
||||
}
|
||||
|
||||
func (b *boot) loadRuntimeConfig(ctx context.Context) error {
|
||||
cfg, err := b.runtimeConfig(ctx, b.cfg)
|
||||
cfg, versions, err := b.runtimeConfig(ctx, b.cfg)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
b.cfg = cfg
|
||||
b.cfgHolder.Set(cfg)
|
||||
// The versions boot layered in are the resume points the runtime-resource
|
||||
// watches start from: a watch re-established after a version it already
|
||||
// applied neither replays a document this process handled nor skips one
|
||||
// it has not.
|
||||
b.runtimeVersions = versions
|
||||
return nil
|
||||
}
|
||||
|
||||
@@ -75,7 +81,7 @@ func (b *boot) reloadConfig(ctx context.Context, doc *configuration.Document) er
|
||||
// surface as a failed reload rather than a SIGHUP that never returns.
|
||||
queryCtx, cancel := context.WithTimeout(ctx, 10*time.Second)
|
||||
defer cancel()
|
||||
cfg, err := b.runtimeConfig(queryCtx, doc.Config)
|
||||
cfg, _, err := b.runtimeConfig(queryCtx, doc.Config)
|
||||
if err != nil {
|
||||
return fmt.Errorf("runtime settings unavailable: %w", err)
|
||||
}
|
||||
@@ -109,41 +115,45 @@ func (b *boot) startWorkflowExecutionSettings(ctx context.Context) error {
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var lastApplyErr, streamErr error
|
||||
open := func(ctx context.Context, after int64) (<-chan controlplane.AppliedSettings, error) {
|
||||
updates, err := b.controlPlane.WatchWorkflowExecutionSettings(ctx, after)
|
||||
if err == nil {
|
||||
b.applyStatus.Report(ctx, controlplane.WorkflowExecutionSettingsKind, after, lastApplyErr)
|
||||
}
|
||||
return updates, err
|
||||
}
|
||||
go keepWatch(ctx, b.log, controlplane.WorkflowExecutionSettingsKind, version, updates,
|
||||
b.controlPlane.WatchWorkflowExecutionSettings,
|
||||
open,
|
||||
waitFor,
|
||||
func(update controlplane.AppliedSettings) int64 { return update.Version },
|
||||
func(update controlplane.AppliedSettings) {
|
||||
if update.Err != nil {
|
||||
// A refused update arrives here, not through
|
||||
// applyWorkflowExecutionSettings: controlplane.Client decodes every
|
||||
// document it is handed, so a stored value this process cannot run
|
||||
// never reaches the apply call. Report it against the version it
|
||||
// came from -- the reporter keeps the version it last applied --
|
||||
// so the settings page shows the refusal instead of a version this
|
||||
// process never ran (docs/prds/control-plane-apply-status.md).
|
||||
//
|
||||
// A stream failure arrives the same way and must not be reported:
|
||||
// it carries no version at all, because a Recv error is the store
|
||||
// not answering rather than a document, and versions start at 1
|
||||
// (store.PutResource). The rule is
|
||||
// docs/prds/control-plane-apply-status.md, "What can be reported,
|
||||
// and what cannot": a process reaches its apply point only after
|
||||
// the State Store has answered it, and an unreachable store is
|
||||
// never reported as a failure by the process it affected. The
|
||||
// record would not stick of itself -- Report overwrites it on the
|
||||
// next applied version -- but a store that never changes again
|
||||
// leaves the one stamp standing, and the process must not write it
|
||||
// at all. Reporting it would also overwrite the text of a standing
|
||||
// refusal, which is the one message that says what to fix. The
|
||||
// reconnect is the loop's business, not the record's.
|
||||
// A refused document carries its version, while a stream failure
|
||||
// does not. Keep a refusal visible across a transport outage; when
|
||||
// there is no outstanding refusal, the end callback records the
|
||||
// outage until a watch is re-established.
|
||||
if update.Version > 0 {
|
||||
lastApplyErr = update.Err
|
||||
b.applyStatus.Report(ctx, controlplane.WorkflowExecutionSettingsKind, update.Version, update.Err)
|
||||
} else {
|
||||
streamErr = update.Err
|
||||
}
|
||||
b.log.Error("workflow execution settings watch failed", "err", update.Err)
|
||||
return
|
||||
}
|
||||
_ = b.applyWorkflowExecutionSettings(ctx, update.Settings, update.Version)
|
||||
lastApplyErr = b.applyWorkflowExecutionSettings(ctx, update.Settings, update.Version)
|
||||
},
|
||||
func() {
|
||||
if lastApplyErr != nil {
|
||||
return
|
||||
}
|
||||
if streamErr == nil {
|
||||
streamErr = fmt.Errorf("control-plane watch stream ended")
|
||||
}
|
||||
b.applyStatus.Report(ctx, controlplane.WorkflowExecutionSettingsKind, 0,
|
||||
fmt.Errorf("workflow execution settings watch unavailable: %w", streamErr))
|
||||
streamErr = nil
|
||||
})
|
||||
return nil
|
||||
}
|
||||
@@ -206,7 +216,7 @@ func (b *boot) applyWorkflowExecutionSettings(ctx context.Context, settings work
|
||||
return err
|
||||
}
|
||||
b.executionSettings.Store(&candidate.settings)
|
||||
b.cfgHolder.Set(candidate.cfg)
|
||||
b.publishConfig(ctx, candidate.cfg)
|
||||
b.applyStatus.Report(ctx, controlplane.WorkflowExecutionSettingsKind, version, nil)
|
||||
b.log.Info("workflow execution settings applied", "version", version)
|
||||
if limit, uptime := settings.MaxTaskRuntime, candidate.cfg.Containers.MaxUptime.Std(); uptime > 0 && (limit <= 0 || limit > uptime) {
|
||||
@@ -224,3 +234,122 @@ func applyExecutionBudgets(cfg *config.Config, settings workflow.ExecutionSettin
|
||||
cfg.Identities[i].Budgets = cfg.Budgets
|
||||
}
|
||||
}
|
||||
|
||||
// startLiveSettings starts everything a live control-plane update needs
|
||||
// established before Run continues: the workflow-execution-settings watch,
|
||||
// whose limits the layering applies, and one watch per runtime-resource kind
|
||||
// (control_plane.go, runtimeResourceKinds). Both first reads are synchronous,
|
||||
// so a control plane that cannot be watched at all fails the boot that asked
|
||||
// for it rather than leaving the process running settings it can no longer
|
||||
// update.
|
||||
func (b *boot) startLiveSettings(ctx context.Context) error {
|
||||
if err := b.startWorkflowExecutionSettings(ctx); err != nil {
|
||||
return fmt.Errorf("workflow execution settings: %w", err)
|
||||
}
|
||||
if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil {
|
||||
return fmt.Errorf("runtime resource watches: %w", err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// runtimeResourceKinds are the control-plane kinds this process re-layers
|
||||
// live: on a new stored version the watch re-runs the layering a reload runs
|
||||
// (b.runtimeConfig, which applies the execution budgets the settings watch
|
||||
// published) and republishes through config.Holder, so the change takes
|
||||
// effect without a restart. Kinds stay out of this list while a
|
||||
// startup-built component still holds their value -- tool, plugin, container
|
||||
// and channel settings are frozen in components built at boot and remain
|
||||
// restart-required -- and a kind joins it only with a consumer that re-reads
|
||||
// it. Each kind is watched in its own goroutine, exactly the shape the
|
||||
// workflow-execution-settings watch established.
|
||||
var runtimeResourceKinds = []string{
|
||||
controlplane.ProviderSettingsKind,
|
||||
controlplane.ModelRoleAssignmentsKind,
|
||||
controlplane.RepositoryPoliciesKind,
|
||||
controlplane.SchedulingPolicyKind,
|
||||
}
|
||||
|
||||
// startRuntimeResourceWatches keeps a watch per live kind established for the
|
||||
// life of the process. versions carries the resume point each kind starts
|
||||
// from, the versions boot's layering recorded. The first stream per kind is
|
||||
// opened synchronously, so a control plane that cannot be watched at all
|
||||
// fails the boot that asked for it; after that the watch does not return, it
|
||||
// reconnects (see keepWatch, whose backoff rules these watches ride).
|
||||
func (b *boot) startRuntimeResourceWatches(ctx context.Context, versions map[string]int64) error {
|
||||
for _, kind := range runtimeResourceKinds {
|
||||
updates, err := b.controlPlane.WatchResource(ctx, kind, versions[kind])
|
||||
if err != nil {
|
||||
return fmt.Errorf("watch %s: %w", kind, err)
|
||||
}
|
||||
go keepWatch(ctx, b.log, kind, versions[kind], updates,
|
||||
func(ctx context.Context, afterVersion int64) (<-chan controlplane.AppliedResource, error) {
|
||||
return b.controlPlane.WatchResource(ctx, kind, afterVersion)
|
||||
},
|
||||
waitFor,
|
||||
func(update controlplane.AppliedResource) int64 { return update.Version },
|
||||
func(update controlplane.AppliedResource) { b.applyRuntimeResourceUpdate(ctx, kind, update) })
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// applyRuntimeResourceUpdate re-runs the layering a reload runs and
|
||||
// republishes the result through config.Holder. The base is the published
|
||||
// snapshot rather than the boot struct: reloadConfig publishes through the
|
||||
// same holder and does not update the boot config, so the holder is the one
|
||||
// view that is current in every path. The layering reads every kind from the
|
||||
// store over it, so a scheduling-policy document written during this
|
||||
// process's life and every other kind's last stored value land together, and
|
||||
// the merge is idempotent (every kind it reads replaces its fields).
|
||||
//
|
||||
// The published snapshot is replaced only after the same check the reload
|
||||
// and the boot layering pass: on a validation failure nothing is published,
|
||||
// the previous settings keep running (last-known-good), and the failure is
|
||||
// reported through apply status, which keeps the version still live on the
|
||||
// record. A refused update therefore reaches the settings page the way a
|
||||
// refused workflow-execution-settings update does
|
||||
// (docs/prds/control-plane-apply-status.md).
|
||||
func (b *boot) applyRuntimeResourceUpdate(ctx context.Context, kind string, update controlplane.AppliedResource) {
|
||||
if update.Err != nil {
|
||||
// A stream failure carries no version at all (versions start at 1,
|
||||
// store.PutResource), and a process must never report an unreachable
|
||||
// store as its own refusal; the reconnect is keepWatch's business.
|
||||
if update.Version > 0 {
|
||||
b.applyStatus.Report(ctx, kind, update.Version, update.Err)
|
||||
}
|
||||
b.log.Error("runtime settings watch failed", "kind", kind, "err", update.Err)
|
||||
return
|
||||
}
|
||||
base := b.cfgHolder.Get()
|
||||
// Boot publishes before the model catalog is merged in, so the snapshot
|
||||
// this read returns can lack the catalog's model limits and discovered
|
||||
// providers. The merge is idempotent, and reloadConfig re-applies it
|
||||
// before layering for the same reason.
|
||||
applyModelCatalog(&base, b.catalog)
|
||||
cfg, _, err := b.runtimeConfig(ctx, base)
|
||||
if err != nil {
|
||||
// runtimeConfig reported the refusal through apply status for every
|
||||
// kind it layers, keeping the version each of them last applied.
|
||||
b.log.Error("runtime settings update rejected; the running settings stay", "kind", kind, "version", update.Version, "err", err)
|
||||
return
|
||||
}
|
||||
b.publishConfig(ctx, cfg)
|
||||
b.log.Info("runtime settings applied", "kind", kind, "version", update.Version)
|
||||
switch kind {
|
||||
case controlplane.ProviderSettingsKind, controlplane.ModelRoleAssignmentsKind:
|
||||
b.rebuildChatModelRuntime(cfg)
|
||||
}
|
||||
}
|
||||
|
||||
// rebuildChatModelRuntime re-derives the gateway chat runtime's provider set
|
||||
// after a live change to provider-settings or model-role-assignments. The
|
||||
// turn runner reads the runtime through boot.chatLLM, so the swap reaches its
|
||||
// next turn without rebuilding the runner, and the model manager re-derives
|
||||
// the references it offers from the new role assignments.
|
||||
func (b *boot) rebuildChatModelRuntime(cfg config.Config) {
|
||||
if b.chatModels == nil {
|
||||
return // this process serves no chat turns
|
||||
}
|
||||
b.setLLM(agentexec.NewRuntime(executionProviders(cfg)))
|
||||
b.chatModels.SetConfigured(cfg.Models)
|
||||
b.log.Info("chat model runtime rebuilt", "providers", len(cfg.Providers), "models", len(cfg.Models))
|
||||
}
|
||||
@@ -132,7 +132,8 @@ func (*settingsWatchStub) Command(context.Context, *pb.CommandRequest, ...grpc.C
|
||||
panic("unexpected Command")
|
||||
}
|
||||
|
||||
func (s *settingsWatchStub) Watch(context.Context, *pb.WatchRequest, ...grpc.CallOption) (grpc.ServerStreamingClient[pb.WatchResponse], error) {
|
||||
func (s *settingsWatchStub) Watch(ctx context.Context, request *pb.WatchRequest, _ ...grpc.CallOption) (grpc.ServerStreamingClient[pb.WatchResponse], error) {
|
||||
_ = request
|
||||
responses := make([]*pb.WatchResponse, 0, len(s.documents))
|
||||
for i, document := range s.documents {
|
||||
responses = append(responses, &pb.WatchResponse{Resource: &pb.Resource{
|
||||
@@ -141,7 +142,7 @@ func (s *settingsWatchStub) Watch(context.Context, *pb.WatchRequest, ...grpc.Cal
|
||||
ValueJson: []byte(document),
|
||||
}})
|
||||
}
|
||||
return &watchStreamStub{responses: responses}, nil
|
||||
return &watchStreamStub{responses: responses, done: ctx.Done()}, nil
|
||||
}
|
||||
|
||||
// watchStreamStub is the client end of a Watch stream. Recv is the only method
|
||||
@@ -150,15 +151,26 @@ func (s *settingsWatchStub) Watch(context.Context, *pb.WatchRequest, ...grpc.Cal
|
||||
type watchStreamStub struct {
|
||||
grpc.ClientStream
|
||||
responses []*pb.WatchResponse
|
||||
done <-chan struct{}
|
||||
next int
|
||||
// onDeliver, when set, runs as the stream delivers each response, so a
|
||||
// stub standing in for the store can store what it just delivered.
|
||||
onDeliver func()
|
||||
}
|
||||
|
||||
func (s *watchStreamStub) Recv() (*pb.WatchResponse, error) {
|
||||
if s.next >= len(s.responses) {
|
||||
return nil, io.EOF
|
||||
if s.done == nil {
|
||||
return nil, io.EOF
|
||||
}
|
||||
<-s.done
|
||||
return nil, context.Canceled
|
||||
}
|
||||
response := s.responses[s.next]
|
||||
s.next++
|
||||
if s.onDeliver != nil {
|
||||
s.onDeliver()
|
||||
}
|
||||
return response, nil
|
||||
}
|
||||
|
||||
|
||||
@@ -5,6 +5,7 @@ import (
|
||||
"encoding/json"
|
||||
"log/slog"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
@@ -113,22 +114,27 @@ func newReloadBoot(t *testing.T, stub *controlPlaneStub) *boot {
|
||||
return b
|
||||
}
|
||||
|
||||
func TestRuntimeConfigResolvesStoredProviderReference(t *testing.T) {
|
||||
t.Setenv("ARCHIE_TEST_STORED_PROVIDER", "provider-secret")
|
||||
resources := databaseOwnedResources()
|
||||
resources[controlplane.ProviderSettingsKind] = map[string]any{"main": map[string]any{
|
||||
"class": "openai", "api_key_ref": map[string]any{"engine": "env", "key": "ARCHIE_TEST_STORED_PROVIDER"},
|
||||
}}
|
||||
b := newReloadBoot(t, &controlPlaneStub{values: resources})
|
||||
b.secrets = secret.NewRegistry()
|
||||
if err := b.loadRuntimeConfig(t.Context()); err != nil {
|
||||
t.Fatal(err)
|
||||
func TestRuntimeConfigResolvesStoredProviderReferences(t *testing.T) {
|
||||
for _, providerID := range []string{"main", "secondary"} {
|
||||
t.Run(providerID, func(t *testing.T) {
|
||||
refKey := "ARCHIE_TEST_STORED_PROVIDER_" + strings.ToUpper(providerID)
|
||||
t.Setenv(refKey, "provider-secret")
|
||||
resources := databaseOwnedResources()
|
||||
resources[controlplane.ProviderSettingsKind] = map[string]any{providerID: map[string]any{
|
||||
"class": "openai", "api_key_ref": map[string]any{"engine": "env", "key": refKey},
|
||||
}}
|
||||
b := newReloadBoot(t, &controlPlaneStub{values: resources})
|
||||
b.secrets = secret.NewRegistry()
|
||||
if err := b.loadRuntimeConfig(t.Context()); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
got := b.cfgHolder.Get().Providers[providerID]
|
||||
if got.APIKey != (secret.SecretRef{}) || got.APIKeyEnv != providerSecretEnvName("root", providerID) {
|
||||
t.Fatalf("effective provider credential = %+v, want a resolved process-local env name", got)
|
||||
}
|
||||
t.Cleanup(func() { _ = os.Unsetenv(got.APIKeyEnv) })
|
||||
})
|
||||
}
|
||||
got := b.cfgHolder.Get().Providers["main"]
|
||||
if got.APIKey != (secret.SecretRef{}) || got.APIKeyEnv != providerSecretEnvName("root", "main") {
|
||||
t.Fatalf("effective provider credential = %+v, want a resolved process-local env name", got)
|
||||
}
|
||||
t.Cleanup(func() { _ = os.Unsetenv(got.APIKeyEnv) })
|
||||
}
|
||||
|
||||
// TestReloadConfigKeepsDatabaseOwnedSettings is archie-core-ju85. The SIGHUP
|
||||
|
||||
@@ -0,0 +1,242 @@
|
||||
package archied
|
||||
|
||||
import (
|
||||
"context"
|
||||
"encoding/json"
|
||||
"slices"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"google.golang.org/grpc"
|
||||
"google.golang.org/grpc/codes"
|
||||
"google.golang.org/grpc/status"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/app/controlplane"
|
||||
pb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
|
||||
"github.com/samcharles93/archie-core/internal/secret"
|
||||
)
|
||||
|
||||
// resourceWatchStub answers Query with one stored version per kind and Watch
|
||||
// with the documents queued for the watched kind. It is the store end of the
|
||||
// seam the runtime-resource watch meets a live update through, and it is the
|
||||
// store: delivering a document stores it, so the layering the apply runs
|
||||
// reads the update back from Query the way production does. A kind the map
|
||||
// does not carry is answered codes.NotFound, the state a skipped seed leaves
|
||||
// behind.
|
||||
type resourceWatchStub struct {
|
||||
values map[string]any
|
||||
// version is the stored version until a watch delivers an update, which
|
||||
// is the version the store then answers Query with -- the apply the
|
||||
// delivery triggers layers and reports the version the store now holds.
|
||||
version int64
|
||||
// storedVersion, when present, is the version Query answers a kind with.
|
||||
storedVersion map[string]int64
|
||||
// watch queues, per kind, the documents a live write delivers after the
|
||||
// stored version, one per stream: the first open delivers the first
|
||||
// document, the second open the second, and so on.
|
||||
watch map[string][]string
|
||||
// opens counts how often each kind's stream was opened, so queued
|
||||
// documents are delivered in order across the reconnects keepWatch runs.
|
||||
opens map[string]int
|
||||
}
|
||||
|
||||
func (s *resourceWatchStub) versionOf(kind string) int64 {
|
||||
if stored, ok := s.storedVersion[kind]; ok {
|
||||
return stored
|
||||
}
|
||||
return s.version
|
||||
}
|
||||
|
||||
func (*resourceWatchStub) Catalog(context.Context, *pb.CatalogRequest, ...grpc.CallOption) (*pb.CatalogResponse, error) {
|
||||
return &pb.CatalogResponse{}, nil
|
||||
}
|
||||
|
||||
func (s *resourceWatchStub) Query(_ context.Context, request *pb.QueryRequest, _ ...grpc.CallOption) (*pb.QueryResponse, error) {
|
||||
value, ok := s.values[request.Kind]
|
||||
if !ok {
|
||||
return nil, status.Error(codes.NotFound, "resource not found")
|
||||
}
|
||||
encoded, err := json.Marshal(value)
|
||||
return &pb.QueryResponse{Resource: &pb.Resource{Kind: request.Kind, Version: s.versionOf(request.Kind), ValueJson: encoded}}, err
|
||||
}
|
||||
|
||||
func (s *resourceWatchStub) Watch(_ context.Context, request *pb.WatchRequest, _ ...grpc.CallOption) (grpc.ServerStreamingClient[pb.WatchResponse], error) {
|
||||
// One queued document per stream: a stream ends after the document it
|
||||
// carries, and the next one arrives on the reconnect -- the shape a store
|
||||
// whose writes are spaced apart produces, and the shape that keeps the
|
||||
// apply each delivery triggers reading the document back from Query
|
||||
// before the store has moved on to the next one.
|
||||
open := s.opens[request.Kind]
|
||||
s.opens[request.Kind] = open + 1
|
||||
if open >= len(s.watch[request.Kind]) {
|
||||
return &watchStreamStub{}, nil
|
||||
}
|
||||
document := s.watch[request.Kind][open]
|
||||
version := s.version + int64(open) + 1
|
||||
if version <= request.AfterVersion {
|
||||
return &watchStreamStub{}, nil
|
||||
}
|
||||
// The stub is the store: a document is stored when the stream delivers
|
||||
// it, so the apply that delivery triggers layers the document back from
|
||||
// Query.
|
||||
response := &pb.WatchResponse{Resource: &pb.Resource{
|
||||
Kind: request.Kind, Version: version, ValueJson: []byte(document),
|
||||
}}
|
||||
return &watchStreamStub{responses: []*pb.WatchResponse{response}, onDeliver: func() {
|
||||
s.values[request.Kind] = json.RawMessage(document)
|
||||
s.storedVersion[request.Kind] = version
|
||||
}}, nil
|
||||
}
|
||||
|
||||
func (*resourceWatchStub) History(context.Context, *pb.HistoryRequest, ...grpc.CallOption) (*pb.HistoryResponse, error) {
|
||||
panic("unexpected History")
|
||||
}
|
||||
|
||||
func (*resourceWatchStub) Audit(context.Context, *pb.AuditRequest, ...grpc.CallOption) (*pb.AuditResponse, error) {
|
||||
return &pb.AuditResponse{}, nil
|
||||
}
|
||||
|
||||
func (*resourceWatchStub) Command(context.Context, *pb.CommandRequest, ...grpc.CallOption) (*pb.CommandResponse, error) {
|
||||
panic("unexpected Command")
|
||||
}
|
||||
|
||||
// newResourceWatchBoot builds a boot whose apply status lands in a recorder,
|
||||
// with the chat model runtime a provider or role update must rebuild.
|
||||
func newResourceWatchBoot(t *testing.T, stub *resourceWatchStub) (*boot, *applyStatusRecorder) {
|
||||
t.Helper()
|
||||
b, recorder := newLiveApplyBoot(t, fileConfig())
|
||||
b.controlPlane = controlplane.NewRPCClient(stub)
|
||||
b.secrets = secret.NewRegistry()
|
||||
b.chatModels = newChatModelManager(fileConfig().Models)
|
||||
b.setLLM(agentexec.NewRuntime(executionProviders(fileConfig())))
|
||||
return b, recorder
|
||||
}
|
||||
|
||||
// schedulingDocument renders a scheduling-policy document the layering reads
|
||||
// back, so the applied and refused updates in these tests cannot disagree on
|
||||
// what "the stored scheduling policy" is.
|
||||
func schedulingDocument(interval string) string {
|
||||
return `{"poll_interval": "` + interval + `", "max_retries": 7, "dispatch": {"trigger": "assignee"}}`
|
||||
}
|
||||
|
||||
// TestRuntimeResourceWatchReLayersTheStoredChangeAndRepublishes is the live
|
||||
// apply for the four kinds the daemon watches (archie-core-zfb0.1): a new
|
||||
// stored version of scheduling-policy re-runs the layering a reload runs and
|
||||
// republishes through config.Holder, so the change takes effect without a
|
||||
// restart, the apply status records the version that was applied, and every
|
||||
// other database-owned setting the layering read is still in the running
|
||||
// config.
|
||||
func TestRuntimeResourceWatchReLayersTheStoredChangeAndRepublishes(t *testing.T) {
|
||||
values := databaseOwnedResources()
|
||||
stub := &resourceWatchStub{values: values, version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}, watch: map[string][]string{
|
||||
controlplane.SchedulingPolicyKind: {schedulingDocument("5m")},
|
||||
}}
|
||||
b, status := newResourceWatchBoot(t, stub)
|
||||
if err := b.loadRuntimeConfig(t.Context()); err != nil {
|
||||
t.Fatalf("loadRuntimeConfig: %v", err)
|
||||
}
|
||||
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
defer cancel()
|
||||
if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil {
|
||||
t.Fatalf("startRuntimeResourceWatches: %v", err)
|
||||
}
|
||||
// One record for boot's layering, one for the watched update.
|
||||
records := status.awaitCount(t, controlplane.SchedulingPolicyKind, 2)
|
||||
|
||||
cfg := b.cfgHolder.Get()
|
||||
if got := time.Duration(cfg.PollInterval); got != 5*time.Minute {
|
||||
t.Errorf("running PollInterval = %s, want the watched update (5m)", got)
|
||||
}
|
||||
if got := cfg.Repos[0].Name; got != "from-database" {
|
||||
t.Errorf("running Repos[0] = %q, want the other kinds' last values to survive the re-layering", got)
|
||||
}
|
||||
last := records[len(records)-1]
|
||||
if last.AppliedVersion != stub.version+1 {
|
||||
t.Errorf("apply status version = %d, want the delivered version %d", last.AppliedVersion, stub.version+1)
|
||||
}
|
||||
if last.Error != "" {
|
||||
t.Errorf("apply status error = %q, want none for an applied update", last.Error)
|
||||
}
|
||||
}
|
||||
|
||||
// TestRuntimeResourceWatchKeepsLastKnownGoodWhenTheUpdateIsRefused: an update
|
||||
// the layered document cannot run is refused before it is published, the
|
||||
// running config keeps the last version that was applied, and the refusal is
|
||||
// reported through apply status against the version still live.
|
||||
func TestRuntimeResourceWatchKeepsLastKnownGoodWhenTheUpdateIsRefused(t *testing.T) {
|
||||
stub := &resourceWatchStub{values: databaseOwnedResources(), version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}, watch: map[string][]string{
|
||||
controlplane.SchedulingPolicyKind: {schedulingDocument("5m"), schedulingDocument("0s")},
|
||||
}}
|
||||
b, status := newResourceWatchBoot(t, stub)
|
||||
if err := b.loadRuntimeConfig(t.Context()); err != nil {
|
||||
t.Fatalf("loadRuntimeConfig: %v", err)
|
||||
}
|
||||
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
defer cancel()
|
||||
if err := b.startRuntimeResourceWatches(ctx, b.runtimeVersions); err != nil {
|
||||
t.Fatalf("startRuntimeResourceWatches: %v", err)
|
||||
}
|
||||
// One record for boot's layering, one for the applied update, one for the
|
||||
// refusal. The recorder keeps the version that is still live on a refusal,
|
||||
// so the third record carries the second update's version.
|
||||
records := status.awaitCount(t, controlplane.SchedulingPolicyKind, 3)
|
||||
|
||||
if got := time.Duration(b.cfgHolder.Get().PollInterval); got != 5*time.Minute {
|
||||
t.Errorf("running PollInterval = %s, want the last update that validated (5m)", got)
|
||||
}
|
||||
last := records[len(records)-1]
|
||||
if last.AppliedVersion != stub.version+1 {
|
||||
t.Errorf("apply status version = %d, want the version still live (%d)", last.AppliedVersion, stub.version+1)
|
||||
}
|
||||
if !strings.Contains(last.Error, "poll_interval must be positive") {
|
||||
t.Errorf("apply status error = %q, want it to carry the refusal", last.Error)
|
||||
}
|
||||
}
|
||||
|
||||
// TestLiveModelRoleUpdateRebuildsTheChatModelRuntime: providers and model
|
||||
// role assignments also feed the gateway chat runtime, so an update to either
|
||||
// kind swaps the runtime (ai-sdk's Runtime caches the provider instances it
|
||||
// built) and re-derives the model list the chat surfaces offer.
|
||||
func TestLiveModelRoleUpdateRebuildsTheChatModelRuntime(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
kind string
|
||||
}{
|
||||
{"a provider settings update", controlplane.ProviderSettingsKind},
|
||||
{"a model role assignments update", controlplane.ModelRoleAssignmentsKind},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
values := databaseOwnedResources()
|
||||
values[controlplane.ModelRoleAssignmentsKind] = map[string]string{
|
||||
"builder": "main/db-model", "chat": "main/db-model",
|
||||
}
|
||||
stub := &resourceWatchStub{values: values, version: 3, storedVersion: map[string]int64{}, opens: map[string]int{}}
|
||||
b, _ := newResourceWatchBoot(t, stub)
|
||||
if err := b.loadRuntimeConfig(t.Context()); err != nil {
|
||||
t.Fatalf("loadRuntimeConfig: %v", err)
|
||||
}
|
||||
before := b.chatLLM()
|
||||
|
||||
b.applyRuntimeResourceUpdate(t.Context(), tt.kind, controlplane.AppliedResource{Version: 4})
|
||||
|
||||
if after := b.chatLLM(); after == before {
|
||||
t.Error("the chat runtime was not rebuilt; the next turn keeps the previous provider set")
|
||||
}
|
||||
if !slices.Contains(b.chatModels.Models(), "main/db-model") {
|
||||
t.Errorf("chat models = %v, want the new role assignment's reference", b.chatModels.Models())
|
||||
}
|
||||
if got := b.chatModels.ActiveModel(); got != "main/db-model" {
|
||||
t.Errorf("chat active model = %q, want the chat role's model after the update", got)
|
||||
}
|
||||
// The running config carries the update, not just the chat runtime.
|
||||
if got := b.cfgHolder.Get().Models["chat"]; got != "main/db-model" {
|
||||
t.Errorf("running chat role = %q, want the applied assignment", got)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -52,12 +52,10 @@ const controlPlaneWatchHealthyMultiple = 2
|
||||
// re-establishes it in this same goroutine until ctx ends.
|
||||
//
|
||||
// A control-plane watch stream is not permanent. The State Store restarts, the
|
||||
// connection drops, the server closes the stream -- and nothing on the client
|
||||
// side reopens it. A watch that ends on its first end stops applying that kind
|
||||
// for the rest of the process's life: every later stored change is silently
|
||||
// never applied while the last apply-status record keeps re-stamping, so the
|
||||
// settings page reads the process as current, and the process recovers only by
|
||||
// restarting (archie-core-yrmr).
|
||||
// connection drops, or the server closes the stream. keepWatch reopens it in
|
||||
// place; workflow-execution-settings also reports the gap so apply status does
|
||||
// not keep re-stamping the previous successful version as current while no
|
||||
// live updates can arrive (archie-core-1050).
|
||||
//
|
||||
// One goroutine per kind, reconnecting in place: a long outage does not stack
|
||||
// watchers. Reopening resumes after the last version an update carried, so a
|
||||
@@ -129,6 +127,7 @@ func keepWatch[T any](
|
||||
wait func(ctx context.Context, d time.Duration) bool,
|
||||
versionOf func(update T) int64,
|
||||
deliver func(update T),
|
||||
onEnded ...func(),
|
||||
) {
|
||||
stream, backoff := first, controlPlaneWatchRetryMin
|
||||
for {
|
||||
@@ -146,6 +145,9 @@ func keepWatch[T any](
|
||||
if ctx.Err() != nil {
|
||||
return
|
||||
}
|
||||
if len(onEnded) > 0 {
|
||||
onEnded[0]()
|
||||
}
|
||||
backoff = retryDelay(backoff, attemptHealthy(progressed, time.Since(started), backoff))
|
||||
log.Warn("control plane watch stream ended; reconnecting",
|
||||
"kind", kind, "after_version", after, "retry_in", backoff)
|
||||
|
||||
@@ -219,22 +219,22 @@ func TestWorkflowExecutionSettingsWatchIsReEstablishedAfterTheStreamEnds(t *test
|
||||
t.Errorf("watch resumed after %v, want the boot version then the last version handled", got)
|
||||
}
|
||||
|
||||
// Boot's own apply, then the update the re-established stream
|
||||
// delivered. Neither way the stream ends writes a record of its own:
|
||||
// a stream the server closed emits no update at all (controlplane
|
||||
// .Client sends one only for a Recv error), and a Recv failure
|
||||
// carries no version, which is the unreachable store the process must
|
||||
// never report as a failure of its own
|
||||
// (docs/prds/control-plane-apply-status.md, "What can be reported, and
|
||||
// what cannot").
|
||||
records := status.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 2)
|
||||
if len(records) != 2 {
|
||||
t.Fatalf("apply status = %+v, want the boot apply and the recovered one alone", records)
|
||||
// Boot applies version 1, the ended stream reports the outage, the
|
||||
// reopened watch clears it, and the delivered version 2 is applied.
|
||||
records := status.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 4)
|
||||
if len(records) != 4 {
|
||||
t.Fatalf("apply status = %+v, want boot, outage, reconnect, and update reports", records)
|
||||
}
|
||||
if records[0].AppliedVersion != 1 || records[0].Error != "" {
|
||||
t.Errorf("boot report = %+v, want a clean apply of version 1", records[0])
|
||||
}
|
||||
last := records[len(records)-1]
|
||||
if records[1].AppliedVersion != 1 || !strings.Contains(records[1].Error, "watch unavailable") {
|
||||
t.Errorf("outage report = %+v, want version 1 with a watch outage", records[1])
|
||||
}
|
||||
if records[2].AppliedVersion != 1 || records[2].Error != "" {
|
||||
t.Errorf("reconnect report = %+v, want the outage cleared at version 1", records[2])
|
||||
}
|
||||
last := records[3]
|
||||
if last.AppliedVersion != 2 || last.Error != "" {
|
||||
t.Errorf("last apply status = %+v, want the recovered apply of version 2 with the failure cleared", last)
|
||||
}
|
||||
@@ -256,7 +256,7 @@ func TestWorkflowExecutionSettingsWatchIsReEstablishedAfterTheStreamEnds(t *test
|
||||
// point), applystatus.Reporter keeps a standing error and re-stamps it forever,
|
||||
// and the dashboard renders any non-empty error as failed. The process reads as
|
||||
// failed for the rest of its life, after one blip.
|
||||
func TestWatchTransportFailureIsNotReportedAsAFailedApply(t *testing.T) {
|
||||
func TestWatchTransportFailureIsReportedUntilTheWatchRecovers(t *testing.T) {
|
||||
t.Parallel()
|
||||
b, recorder := newLiveApplyBoot(t, fileConfig())
|
||||
stub := &watchStub{
|
||||
@@ -285,23 +285,25 @@ func TestWatchTransportFailureIsNotReportedAsAFailedApply(t *testing.T) {
|
||||
// the loop delivers what ended the stream, then reopens.
|
||||
stub.awaitWatchCalls(t, controlplane.WorkflowExecutionSettingsKind, 2)
|
||||
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 1)
|
||||
if len(records) != 1 {
|
||||
t.Fatalf("apply status = %+v, want the boot apply alone: an unreachable store writes no record", records)
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 3)
|
||||
if len(records) != 3 {
|
||||
t.Fatalf("apply status = %+v, want boot, outage, and recovery reports", records)
|
||||
}
|
||||
if last := records[0]; last.AppliedVersion != 1 || last.Error != "" {
|
||||
t.Errorf("apply status = %+v, want the clean apply of version 1 still standing", last)
|
||||
if records[0].AppliedVersion != 1 || records[0].Error != "" {
|
||||
t.Errorf("boot apply status = %+v, want the clean apply of version 1", records[0])
|
||||
}
|
||||
if records[1].AppliedVersion != 1 || !strings.Contains(records[1].Error, "watch unavailable") {
|
||||
t.Errorf("outage apply status = %+v, want version 1 with a watch outage", records[1])
|
||||
}
|
||||
if records[2].AppliedVersion != 1 || records[2].Error != "" {
|
||||
t.Errorf("recovered apply status = %+v, want version 1 with the outage cleared", records[2])
|
||||
}
|
||||
}
|
||||
|
||||
// TestWatchTransportFailureDoesNotOverwriteARefusal is the other half of the
|
||||
// same rule, and the reason the branch is on the version rather than on the
|
||||
// error: a refused document arrives carrying the version it came from, so it is
|
||||
// the store answering and must be reported; a transport failure carries no
|
||||
// version and must not. Reporting the transport failure against the version
|
||||
// still live overwrites the refusal's text, so a validation error against
|
||||
// version 2 reads "control-plane unavailable: ..." after any blip, and the
|
||||
// operator loses the one message that says what to fix.
|
||||
// TestWatchTransportFailureDoesNotOverwriteARefusal keeps the more useful
|
||||
// versioned rejection visible when a stream drops afterward. Reconnection
|
||||
// restores that rejection instead of clearing it as though a valid update had
|
||||
// arrived.
|
||||
func TestWatchTransportFailureDoesNotOverwriteARefusal(t *testing.T) {
|
||||
t.Parallel()
|
||||
b, recorder := newLiveApplyBoot(t, fileConfig())
|
||||
@@ -332,18 +334,18 @@ func TestWatchTransportFailureDoesNotOverwriteARefusal(t *testing.T) {
|
||||
|
||||
stub.awaitWatchCalls(t, controlplane.WorkflowExecutionSettingsKind, 2)
|
||||
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 2)
|
||||
if len(records) != 2 {
|
||||
t.Fatalf("apply status = %+v, want the boot apply and the refusal alone", records)
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 3)
|
||||
if len(records) != 3 {
|
||||
t.Fatalf("apply status = %+v, want boot, refusal, and the preserved refusal after reconnect", records)
|
||||
}
|
||||
last := records[len(records)-1]
|
||||
last := records[2]
|
||||
if last.AppliedVersion != 1 {
|
||||
t.Errorf("refusal reported against version %d, want the version still live (1)", last.AppliedVersion)
|
||||
}
|
||||
if !strings.Contains(last.Error, "max model/tool steps must not be negative") {
|
||||
t.Errorf("apply status error = %q, want the refusal's own text", last.Error)
|
||||
}
|
||||
if strings.Contains(last.Error, "control-plane unavailable") {
|
||||
if strings.Contains(last.Error, "watch unavailable") {
|
||||
t.Errorf("apply status error = %q, want the transport blip not to have overwritten the refusal", last.Error)
|
||||
}
|
||||
// The refused version is unusable to this build, so the resume point moves
|
||||
@@ -394,13 +396,16 @@ func TestWatchReconnectDoesNotReplayWhatItAlreadyApplied(t *testing.T) {
|
||||
t.Errorf("watch resumed after %v, want the boot version then the last version handled", got)
|
||||
}
|
||||
|
||||
// One report for the boot apply and one for the update: a third would be
|
||||
// the re-served version 1 applied over itself.
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 2)
|
||||
if len(records) != 2 {
|
||||
t.Fatalf("apply status = %+v, want the boot apply and the update alone", records)
|
||||
// The outage and reconnection records sit between boot and version 2; the
|
||||
// re-served version 1 is still filtered out.
|
||||
records := recorder.awaitCount(t, controlplane.WorkflowExecutionSettingsKind, 4)
|
||||
if len(records) != 4 {
|
||||
t.Fatalf("apply status = %+v, want boot, outage, reconnect, and version 2", records)
|
||||
}
|
||||
last := records[len(records)-1]
|
||||
if records[1].AppliedVersion != 1 || !strings.Contains(records[1].Error, "watch unavailable") {
|
||||
t.Errorf("outage report = %+v, want an outage against version 1", records[1])
|
||||
}
|
||||
last := records[3]
|
||||
if last.AppliedVersion != 2 || last.Error != "" {
|
||||
t.Errorf("last apply status = %+v, want the recovered apply of version 2", last)
|
||||
}
|
||||
|
||||
@@ -119,8 +119,21 @@ func RunGateway(ctx context.Context, options GatewayOptions) error {
|
||||
if err != nil {
|
||||
return fmt.Errorf("listen for gateway: %w", err)
|
||||
}
|
||||
return b.serveGatewayListener(ctx, listener, loopback, contract, opts)
|
||||
}
|
||||
|
||||
// serveGatewayListener is the serving tail of RunGateway: the listener is
|
||||
// bound, the process declares itself serving, and the chat contract answers
|
||||
// until ctx ends.
|
||||
func (b *boot) serveGatewayListener(ctx context.Context, listener net.Listener, loopback bool, contract gateway.ChatContract, opts []grpc.ServerOption) error {
|
||||
defer listener.Close()
|
||||
b.log.Info("archie-gateway running", "addr", listener.Addr().String(), "token_required", !loopback)
|
||||
// Boot is over and this listener is about to accept: the same fact
|
||||
// systemd's READY=1 asserts, so the announcement goes out here rather than
|
||||
// from a second notion of "started" (archie-core-1174). Not later: Serve
|
||||
// begins accepting the moment it is called, and a unit whose
|
||||
// TimeoutStartSec expires first would restart a healthy process.
|
||||
b.announceReady()
|
||||
return serveGateway(ctx, listener, contract, b.chatSessionStore, opts)
|
||||
}
|
||||
|
||||
@@ -143,13 +156,14 @@ func (b *boot) startGatewayRuntime(ctx context.Context, actor gateway.ChatTaskAc
|
||||
b.addCleanup(b.bus.Close)
|
||||
b.capabilityHost = plugin.NewHost()
|
||||
b.startRateLimiter(ctx, b.cfg.Chat.RateLimit)
|
||||
// The Gateway owns PR review (docs/prds/operator-pr-review.md §4), so it
|
||||
// composes the process-wide worktree manager before setupGatewayChat
|
||||
// resolves boot.prReviewer: prReviewer returns nil without a manager, and
|
||||
// a nil reviewer omits review_pr from every channel's tool set. The
|
||||
// manager is the only part of the daemon's tree composition the Gateway
|
||||
// takes -- it must not own identity runners, so it does not call
|
||||
// buildTreesAndIdentities.
|
||||
// The Gateway composes the process-wide worktree manager before
|
||||
// setupGatewayChat; nothing in this process reads it today (the old
|
||||
// synchronous operator-review path that did was removed with the
|
||||
// adversarial self-review system, archie-core-afbk.7 -- see that bead's
|
||||
// continuation for the operator trigger's replacement). Kept for the
|
||||
// manager's other consumers; it is the only part of the daemon's tree
|
||||
// composition the Gateway takes -- it must not own identity runners, so
|
||||
// it does not call buildTreesAndIdentities.
|
||||
b.buildWorktreeManager()
|
||||
// setupMemoryEngine must run before setupGatewayChat: setupGatewayChat
|
||||
// constructs the turn runner, which captures b.memEngines at
|
||||
|
||||
@@ -8,6 +8,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/app/controlplane"
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/agent"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/tools"
|
||||
)
|
||||
@@ -21,7 +22,7 @@ func (b *boot) setupChatRuntime(ctx context.Context, cfg config.Config) error {
|
||||
// Created before the router so the LLMResponder can be wired in for
|
||||
// non-command message processing.
|
||||
providers := executionProviders(cfg)
|
||||
b.llm = agentexec.NewRuntime(providers)
|
||||
b.setLLM(agentexec.NewRuntime(providers))
|
||||
b.toolReg = tools.NewRegistry()
|
||||
chatModels := newChatModelManager(cfg.Models, cfg.Chat.Models, b.catalogModels)
|
||||
chatModels.ApplyModelCatalog(b.catalog)
|
||||
@@ -57,10 +58,14 @@ func (b *boot) setupChatRuntime(ctx context.Context, cfg config.Config) error {
|
||||
}
|
||||
b.chatTasks = chatTasks
|
||||
b.defaultChatIdentity = defaultChatIdentity
|
||||
var canceller storecontract.ExecutionCanceller
|
||||
if ec, ok := b.stateStore.(storecontract.ExecutionCanceller); ok {
|
||||
canceller = ec
|
||||
}
|
||||
b.chatController = gateway.NewStoreTaskController(chatTaskControllerAdapter{
|
||||
taskByID: b.stateStore.TaskByID,
|
||||
requeue: b.stateStore.Requeue,
|
||||
transition: b.stateStore.Transition,
|
||||
taskByID: b.stateStore.TaskByID,
|
||||
requeue: b.stateStore.Requeue,
|
||||
cancelExecution: canceller.CancelExecution,
|
||||
})
|
||||
b.updateService = makeUpdateService(chatSetup{Cfg: config.NewHolder(cfg)})
|
||||
return nil
|
||||
@@ -119,11 +124,11 @@ func (b *boot) setupGatewayChat(ctx context.Context, actor gateway.ChatTaskActor
|
||||
configureTaskCommands(router, b.chatTasks, b.chatController, chatTaskListerAdapter{tasks: b.stateStore.Tasks}, b.defaultChatIdentity)
|
||||
router.Health = b.statusHealth
|
||||
setup := chatSetup{
|
||||
Cfg: config.NewHolder(cfg), LLM: b.llm, ChatModels: b.chatModels, ToolReg: b.toolReg,
|
||||
Cfg: config.NewHolder(cfg), LLM: b.chatLLM, ChatModels: b.chatModels, ToolReg: b.toolReg,
|
||||
Personas: b.personas, ChatTasks: b.chatTasks,
|
||||
ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks},
|
||||
ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs},
|
||||
ChatTaskActor: actor, ChatPRReviewer: b.prReviewer(),
|
||||
ChatTaskLister: chatTaskListerAdapter{tasks: b.stateStore.Tasks},
|
||||
ChatTaskLogs: chatTaskLogReaderAdapter{tasks: b.stateStore.TaskByID, taskLogs: b.taskLogs},
|
||||
ChatTaskActor: actor,
|
||||
DefaultChatIdentity: b.defaultChatIdentity,
|
||||
Bus: b.bus, Log: b.log,
|
||||
MemoryEngine: b.memoryStore(),
|
||||
|
||||
@@ -1,6 +1,20 @@
|
||||
package archied
|
||||
|
||||
import "testing"
|
||||
import (
|
||||
"context"
|
||||
"log/slog"
|
||||
"net"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"google.golang.org/grpc"
|
||||
"google.golang.org/grpc/credentials/insecure"
|
||||
|
||||
pb "github.com/samcharles93/archie-core/internal/contracts/gateway/v1"
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
"github.com/samcharles93/archie-core/internal/domain/taskactions"
|
||||
"github.com/samcharles93/archie-core/internal/taskstate"
|
||||
)
|
||||
|
||||
func TestGatewayServerOptsLoopbackIsInsecure(t *testing.T) {
|
||||
opts, loopback, err := gatewayServerOpts("127.0.0.1:8585", "")
|
||||
@@ -36,3 +50,87 @@ func TestGatewayServerOptsMalformedListen(t *testing.T) {
|
||||
t.Fatal("malformed listen address should error")
|
||||
}
|
||||
}
|
||||
|
||||
// stubGatewayContract satisfies messaging.ChatContract with zero values: the
|
||||
// serve test exercises the listener, the READY announcement and one read RPC,
|
||||
// not the chat runtime.
|
||||
type stubGatewayContract struct{}
|
||||
|
||||
func (stubGatewayContract) Snapshot(context.Context) (messaging.ChatSnapshot, error) {
|
||||
return messaging.ChatSnapshot{}, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) GetSession(context.Context, string) (messaging.SessionContext, bool, error) {
|
||||
return messaging.SessionContext{}, false, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) RecentMessages(context.Context, string, int) ([]messaging.Message, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) RecentTurns(context.Context, string, int) ([]messaging.TurnRecord, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) Route(context.Context, messaging.Inbound) (messaging.ChatReply, error) {
|
||||
return messaging.ChatReply{}, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) Stream(context.Context, messaging.Inbound) (<-chan messaging.ChatEvent, error) {
|
||||
return nil, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) Cancel(context.Context, string) (messaging.ChatCancellation, error) {
|
||||
return messaging.ChatCancellation{}, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) SetPersona(context.Context, string, string) (bool, error) {
|
||||
return false, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) ApplyTaskAction(context.Context, string, int64, taskstate.Action) (messaging.TaskActionResult, error) {
|
||||
return messaging.TaskActionResult{}, nil
|
||||
}
|
||||
|
||||
func (stubGatewayContract) ApplyOperatorTaskAction(context.Context, taskactions.Actor, int64, taskstate.Action) (messaging.TaskActionResult, error) {
|
||||
return messaging.TaskActionResult{}, nil
|
||||
}
|
||||
|
||||
// TestGatewayServingAnnouncesReady: archie-gateway run as a Type=notify unit
|
||||
// must send READY=1 at the moment it declares itself serving, or systemd kills
|
||||
// a healthy process once TimeoutStartSec expires (archie-core-1174). The
|
||||
// announcement is judged against the same evidence archied's run loop uses:
|
||||
// the contract answers over the bound listener, so READY asserts a serving
|
||||
// process rather than a bound socket.
|
||||
func TestGatewayServingAnnouncesReady(t *testing.T) {
|
||||
listener := newNotifyListener(t)
|
||||
b := &boot{log: slog.New(slog.DiscardHandler)}
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
defer cancel()
|
||||
|
||||
ln, err := (&net.ListenConfig{}).Listen(ctx, "tcp", "127.0.0.1:0")
|
||||
if err != nil {
|
||||
t.Fatalf("listen: %v", err)
|
||||
}
|
||||
|
||||
serveCh := make(chan error, 1)
|
||||
go func() { serveCh <- b.serveGatewayListener(ctx, ln, true, stubGatewayContract{}, nil) }()
|
||||
|
||||
if !listener.waitForState(t, 5*time.Second, readyState) {
|
||||
t.Fatal("no READY=1 datagram within 5s of the Gateway serving")
|
||||
}
|
||||
|
||||
conn, err := grpc.NewClient("passthrough:///"+ln.Addr().String(), grpc.WithTransportCredentials(insecure.NewCredentials()))
|
||||
if err != nil {
|
||||
t.Fatalf("dial: %v", err)
|
||||
}
|
||||
defer conn.Close()
|
||||
if _, err := pb.NewChatServiceClient(conn).Snapshot(t.Context(), &pb.SnapshotRequest{}); err != nil {
|
||||
t.Fatalf("Snapshot over gRPC: %v", err)
|
||||
}
|
||||
|
||||
cancel()
|
||||
if err := <-serveCh; err != nil {
|
||||
t.Fatalf("serveGatewayListener returned: %v", err)
|
||||
}
|
||||
}
|
||||
@@ -59,9 +59,14 @@ func (b *boot) setupKitLauncher(ctx context.Context) {
|
||||
log.Warn("kit harness runs disabled: egress relay", "err", err)
|
||||
return
|
||||
}
|
||||
// No credential resolver yet (archie-core-egkf.11): a Kit's required
|
||||
// credential is refused at the proxy until run credentials carry secrets.
|
||||
proxy := egress.NewProxy(ca, egress.ProxyOptions{})
|
||||
// grants is the production Resolver: Launch/Release Grant/RevokeGrant it
|
||||
// per run with exactly the declared-and-granted intersection
|
||||
// (docs/prds/external-agent-harness.md, Credentials; archie-core-egkf.11).
|
||||
grants := egress.NewGrantResolver()
|
||||
// Without a harness secret store, Register refuses a Kit with a
|
||||
// required OAuth credential.
|
||||
oauthStore, _ := b.stateStore.(egress.OAuthStore)
|
||||
proxy := egress.NewProxy(ca, egress.ProxyOptions{Resolver: grants, OAuthStore: oauthStore})
|
||||
srv := &http.Server{Handler: proxy, ReadHeaderTimeout: 30 * time.Second}
|
||||
go func() {
|
||||
if err := srv.Serve(ln); err != nil && !errors.Is(err, http.ErrServerClosed) {
|
||||
@@ -76,6 +81,7 @@ func (b *boot) setupKitLauncher(ctx context.Context) {
|
||||
b.kitLauncher = &kitrun.Launcher{
|
||||
Pool: pool, Fetch: fetcher, Proxy: proxy, Networks: networks,
|
||||
AgentBinary: agentBinary, CAFile: egress.CACertPath(caDir),
|
||||
Config: b.cfgHolder, Secrets: b.secrets, Grants: grants,
|
||||
}
|
||||
log.Info("kit harness runs enabled", "proxy", ln.Addr().String())
|
||||
}
|
||||
|
||||
@@ -166,7 +166,6 @@ func (a chatTaskListerAdapter) ListChatTasks(ctx context.Context, identity strin
|
||||
Title: task.Title,
|
||||
Status: task.Status,
|
||||
Workflow: task.Workflow,
|
||||
Stage: task.Stage,
|
||||
PRNumber: task.PRNumber,
|
||||
Attempt: task.Attempt,
|
||||
ParkReason: task.ParkReason,
|
||||
@@ -358,29 +357,19 @@ func Run() int { //nolint:cyclop,funlen // the composition root's setup sequence
|
||||
return 1
|
||||
}
|
||||
|
||||
if err := b.openStores(ctx); err != nil {
|
||||
return 1
|
||||
}
|
||||
// Resolve the State Store surfaces before setupObservability wires the
|
||||
// dashboard's storage surfaces (§10): the shared contract adapter (the
|
||||
// remote *staterpc.Client dialed to [services.state].target; the daemon no
|
||||
// longer owns archie.db in-process, so an empty target is a composition
|
||||
// error, docs/prds/state-store-contract.md §12 step 7) and then, daemon
|
||||
// root only, the workflow-definitions client on this process's step
|
||||
// vocabulary. The daemon resolves step types through that client, so it is
|
||||
// built here -- after the adapter, whose transport it wraps -- and before
|
||||
// buildDaemon captures it. The gateway root shares only the adapter and
|
||||
// resolves no step type, so openDaemonStateSurfaces owns the order and
|
||||
// step_vocabulary_test.go pins the cut.
|
||||
if err := b.openDaemonStateSurfaces(); err != nil {
|
||||
// The state-store adapter, its daemon-side surfaces and the policy chain
|
||||
// dispatch evaluates: one ordered stage of the composition sequence
|
||||
// (openStateStage; docs/prds/state-store-contract.md §12 step 7 and
|
||||
// docs/prds/orgs-and-access.md).
|
||||
if err := b.openStateStage(ctx); err != nil {
|
||||
return 1
|
||||
}
|
||||
if err := b.loadRuntimeConfig(ctx); err != nil {
|
||||
b.log.Error("runtime settings unavailable", "err", err)
|
||||
return 1
|
||||
}
|
||||
if err := b.startWorkflowExecutionSettings(ctx); err != nil {
|
||||
b.log.Error("workflow execution settings unavailable", "err", err)
|
||||
if err := b.startLiveSettings(ctx); err != nil {
|
||||
b.log.Error("live settings unavailable", "err", err)
|
||||
return 1
|
||||
}
|
||||
go b.applyStatus.Run(ctx)
|
||||
@@ -494,7 +483,11 @@ func (s curatorEventSink) Emit(kind, detail string, data map[string]any) {
|
||||
// declared set is converted to a runnable core.ToolSet rather than a
|
||||
// parallel catalogue.
|
||||
type curatorLLMRunner struct {
|
||||
rt *runtime.Runtime
|
||||
// llm resolves the runtime at each call, so a live model-settings update
|
||||
// that swaps it wholesale is the one the next curator run reads; a
|
||||
// snapshot taken at construction would keep curators on the providers
|
||||
// boot started with.
|
||||
llm func() *runtime.Runtime
|
||||
// outcomes records this call for /status alongside sendChatTurn's. A
|
||||
// curator call is a model call this process made, and it does not pass
|
||||
// through sendChatTurn, so without this a daemon whose only recent model
|
||||
@@ -509,7 +502,11 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu
|
||||
// nil *runtime.Runtime panics on the first method call. A curator asking
|
||||
// for a completion on a daemon with no providers is a misconfiguration,
|
||||
// not a reason to take the process down.
|
||||
if r.rt == nil {
|
||||
if r.llm == nil {
|
||||
return curator.ChatResult{}, fmt.Errorf("curator chat: no model runtime is configured")
|
||||
}
|
||||
llm := r.llm()
|
||||
if llm == nil {
|
||||
return curator.ChatResult{}, fmt.Errorf("curator chat: no model runtime is configured")
|
||||
}
|
||||
msgs := make([]chat.Message, 0, len(req.Messages))
|
||||
@@ -521,7 +518,7 @@ func (r curatorLLMRunner) Chat(ctx context.Context, req curator.ChatRequest) (cu
|
||||
r.outcomes.record(req.Model, err)
|
||||
return curator.ChatResult{}, err
|
||||
}
|
||||
res, err := r.rt.Chat(ctx, req.Model, core.GenerateOptions{
|
||||
res, err := llm.Chat(ctx, req.Model, core.GenerateOptions{
|
||||
Messages: msgs,
|
||||
Tools: toolSet,
|
||||
MaxSteps: max(req.MaxSteps, 1),
|
||||
@@ -542,14 +539,16 @@ type chatTaskWriterAdapter struct {
|
||||
enqueue func(
|
||||
ctx context.Context,
|
||||
owner, repo, title, body, workflow, identity string,
|
||||
inputs map[string]any,
|
||||
) (*workflow.Task, error)
|
||||
}
|
||||
|
||||
func (a chatTaskWriterAdapter) EnqueueChatTask(
|
||||
ctx context.Context,
|
||||
owner, repo, title, body, workflow, identity string,
|
||||
inputs map[string]any,
|
||||
) (int64, error) {
|
||||
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity)
|
||||
task, err := a.enqueue(ctx, owner, repo, title, body, workflow, identity, inputs)
|
||||
if err != nil {
|
||||
return 0, err
|
||||
}
|
||||
@@ -560,9 +559,9 @@ func (a chatTaskWriterAdapter) EnqueueChatTask(
|
||||
}
|
||||
|
||||
type chatTaskControllerAdapter struct {
|
||||
taskByID func(context.Context, int64) (*workflow.Task, error)
|
||||
requeue func(context.Context, int64, string, string) error
|
||||
transition func(context.Context, int64, string, string, string) error
|
||||
taskByID func(context.Context, int64) (*workflow.Task, error)
|
||||
requeue func(context.Context, int64, string, string) error
|
||||
cancelExecution func(context.Context, int64, string, string) ([]int64, error)
|
||||
}
|
||||
|
||||
func (a chatTaskControllerAdapter) ChatTaskStatus(ctx context.Context, taskID int64) (gateway.ChatTaskStatus, bool, error) {
|
||||
@@ -595,12 +594,19 @@ func (a chatTaskControllerAdapter) CancelChatTask(ctx context.Context, taskID in
|
||||
return fmt.Errorf("task %d is not chat-originated", taskID)
|
||||
}
|
||||
// An operator declining work lands in the same state whichever surface
|
||||
// they used. This used to record StatusRejected while the dashboard
|
||||
// recorded StatusClosedWontDo, so the same decision showed up as two
|
||||
// different states -- and StatusRejected, which the PR reconciler uses
|
||||
// for "the pull request was closed without merging", stopped meaning one
|
||||
// thing.
|
||||
return a.transition(ctx, taskID, task.Status, workflow.StatusClosedWontDo, reason)
|
||||
// they used, through the one cancel path: the store records the
|
||||
// cancellation -- every non-terminal step of the current attempt plus the
|
||||
// execution's own move (docs/prds/execution-tree-state-machine.md) -- and
|
||||
// this write is what a late worker's next step write fails against. This
|
||||
// used to record StatusRejected while the dashboard recorded
|
||||
// StatusClosedWontDo, so the same decision showed up as two different
|
||||
// states -- and StatusRejected, which the PR reconciler uses for "the
|
||||
// pull request was closed without merging", stopped meaning one thing.
|
||||
if a.cancelExecution == nil {
|
||||
return fmt.Errorf("execution cancellation is unavailable")
|
||||
}
|
||||
_, err = a.cancelExecution(ctx, taskID, reason, workflow.StatusClosedWontDo)
|
||||
return err
|
||||
}
|
||||
|
||||
// chatTaskLogReaderAdapter gives the gateway a read view of a task's
|
||||
|
||||
@@ -567,7 +567,7 @@ func TestManualRequeueTaskRejectsOtherStatuses(t *testing.T) {
|
||||
func TestChatTaskListerAdapterReadsSQLiteIdentity(t *testing.T) {
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer")
|
||||
want, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "identity task", "", "tdd", "reviewer", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -610,13 +610,14 @@ func TestChatTaskWriterAdapter(t *testing.T) {
|
||||
enqueue: func(
|
||||
context.Context,
|
||||
string, string, string, string, string, string,
|
||||
map[string]any,
|
||||
) (*workflow.Task, error) {
|
||||
return tt.result, tt.err
|
||||
},
|
||||
}
|
||||
id, err := adapter.EnqueueChatTask(
|
||||
context.Background(),
|
||||
"owner", "repo", "title", "body", "workflow", "identity",
|
||||
"owner", "repo", "title", "body", "workflow", "identity", nil,
|
||||
)
|
||||
if (err != nil) != tt.wantErr {
|
||||
t.Fatalf("EnqueueChatTask() error = %v, wantErr %t", err, tt.wantErr)
|
||||
@@ -669,16 +670,16 @@ func TestChatTaskControllerAdapterRejectsForgeTask(t *testing.T) {
|
||||
|
||||
func TestChatTaskControllerAdapterTransitions(t *testing.T) {
|
||||
task := &workflow.Task{ID: 42, Source: workflow.SourceChat, Status: workflow.StatusWaitingHuman}
|
||||
var requeueFrom, requeueWorkflow, transitionFrom, transitionTo, transitionDetail string
|
||||
var requeueFrom, requeueWorkflow, cancelReason, cancelTo string
|
||||
adapter := chatTaskControllerAdapter{
|
||||
taskByID: func(context.Context, int64) (*workflow.Task, error) { return task, nil },
|
||||
requeue: func(_ context.Context, _ int64, from, workflow string) error {
|
||||
requeueFrom, requeueWorkflow = from, workflow
|
||||
return nil
|
||||
},
|
||||
transition: func(_ context.Context, _ int64, from, to, detail string) error {
|
||||
transitionFrom, transitionTo, transitionDetail = from, to, detail
|
||||
return nil
|
||||
cancelExecution: func(_ context.Context, _ int64, reason, to string) ([]int64, error) {
|
||||
cancelReason, cancelTo = reason, to
|
||||
return nil, nil
|
||||
},
|
||||
}
|
||||
|
||||
@@ -692,12 +693,12 @@ func TestChatTaskControllerAdapterTransitions(t *testing.T) {
|
||||
t.Fatalf("CancelChatTask(): %v", err)
|
||||
}
|
||||
// Declining from chat lands in the same state as declining from the
|
||||
// dashboard. It used to record StatusRejected, which the PR reconciler
|
||||
// also uses for "the pull request was closed without merging", so the
|
||||
// state could not tell an operator's decision from a forge outcome.
|
||||
if transitionFrom != workflow.StatusWaitingHuman || transitionTo != workflow.StatusClosedWontDo ||
|
||||
transitionDetail != "cancelled by test" {
|
||||
t.Errorf("transition = %q/%q/%q", transitionFrom, transitionTo, transitionDetail)
|
||||
// dashboard, through the one cancel path. It used to record
|
||||
// StatusRejected, which the PR reconciler also uses for "the pull
|
||||
// request was closed without merging", so the state could not tell an
|
||||
// operator's decision from a forge outcome.
|
||||
if cancelReason != "cancelled by test" || cancelTo != workflow.StatusClosedWontDo {
|
||||
t.Errorf("cancel = %q/%q", cancelReason, cancelTo)
|
||||
}
|
||||
}
|
||||
|
||||
@@ -834,9 +835,9 @@ func TestChatTaskCommandsEndToEnd(t *testing.T) {
|
||||
profiles,
|
||||
)
|
||||
controller := gateway.NewStoreTaskController(chatTaskControllerAdapter{
|
||||
taskByID: st.TaskByID,
|
||||
requeue: st.Requeue,
|
||||
transition: st.Transition,
|
||||
taskByID: st.TaskByID,
|
||||
requeue: st.Requeue,
|
||||
cancelExecution: st.CancelExecution,
|
||||
})
|
||||
router := gateway.NewRouter(st, nil, "test")
|
||||
configureTaskCommands(router, creator, controller, chatTaskListerAdapter{tasks: st.Tasks}, defaultIdentity)
|
||||
|
||||
@@ -1,364 +0,0 @@
|
||||
package archied
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log/slog"
|
||||
"os"
|
||||
"strconv"
|
||||
"strings"
|
||||
"sync"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/app/agentworker"
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/forge"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
|
||||
"github.com/samcharles93/archie-core/internal/worktree"
|
||||
)
|
||||
|
||||
// prReviewer implements gateway.ChatPRReviewer for the daemon. It fetches
|
||||
// an existing PR's metadata, materialises its head in a fresh clone, and runs
|
||||
// the same adversarial reviewer the workflow stage uses, all synchronously in
|
||||
// the requesting turn. Authorization is identity-scoped (the task_spawn
|
||||
// repository allow-list) and one review per PR runs at a time.
|
||||
type prReviewer struct {
|
||||
forge forge.PullRequestReader // nil = forge cannot read PRs
|
||||
trees *worktree.Manager
|
||||
models map[string]string
|
||||
providers map[string]agentexec.Provider
|
||||
maxSteps int
|
||||
// artifacts publishes the completed review to the collaborative editor.
|
||||
// nil = publishing is disabled (no [artifacts] base_url configured).
|
||||
artifacts artifactsync.Sender
|
||||
// currentMaxSteps lets the composition root apply live control-plane
|
||||
// versions to reviews that have not started yet. Tests and direct
|
||||
// constructions retain maxSteps as the fallback.
|
||||
currentMaxSteps func() int
|
||||
// allowed maps a chat identity to the "owner/name" repos it may review.
|
||||
// A nil identity is an authenticated dashboard operator, who may review
|
||||
// any configured repository.
|
||||
allowed map[string]map[string]bool
|
||||
log *slog.Logger
|
||||
|
||||
mu sync.Mutex
|
||||
inflight map[string]struct{}
|
||||
}
|
||||
|
||||
var _ gateway.ChatPRReviewer = (*prReviewer)(nil)
|
||||
|
||||
// ReviewPR fetches the PR, runs the isolated reviewer against its head, and
|
||||
// returns the structured findings. It never half-reviews: a missing forge
|
||||
// capability, an unresolvable head/base, or an absent reviewer model returns
|
||||
// an error rather than a fabricated result.
|
||||
func (r *prReviewer) ReviewPR(ctx context.Context, identity *string, repo string, number int) (gateway.PRReviewResult, error) {
|
||||
owner, name, err := splitOwnerRepo(repo)
|
||||
if err != nil {
|
||||
return gateway.PRReviewResult{}, err
|
||||
}
|
||||
if err := r.authorize(identity, owner, name); err != nil {
|
||||
return gateway.PRReviewResult{}, err
|
||||
}
|
||||
|
||||
key := owner + "/" + name + "#" + strconv.Itoa(number)
|
||||
if !r.begin(key) {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("review already in progress for %s", key)
|
||||
}
|
||||
defer r.end(key)
|
||||
|
||||
if r.forge == nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("forge does not support pull request review")
|
||||
}
|
||||
pr, err := r.forge.GetPullRequest(ctx, owner, name, number)
|
||||
if err != nil {
|
||||
return gateway.PRReviewResult{}, err
|
||||
}
|
||||
|
||||
model := agentworker.ReviewerModel(r.models)
|
||||
if model == "" {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("reviewer model is not configured (set models.reviewer, or models.builder as a fallback)")
|
||||
}
|
||||
reviewer := agentworker.NewOperatorReviewer(r.models, r.providers)
|
||||
if reviewer == nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("no provider runtime configured for the reviewer model %q", model)
|
||||
}
|
||||
if r.trees == nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("worktree manager is not configured")
|
||||
}
|
||||
|
||||
dir, cleanup, err := r.trees.CheckoutPR(ctx, owner, name, pr.HeadRef, pr.BaseRef)
|
||||
if err != nil {
|
||||
return gateway.PRReviewResult{}, err
|
||||
}
|
||||
defer cleanup()
|
||||
|
||||
diff, err := r.trees.Diff(ctx, dir, pr.BaseRef)
|
||||
if err != nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("compute PR diff: %w", err)
|
||||
}
|
||||
|
||||
snapshotDir, err := os.MkdirTemp("", "pr-review-snapshot-*")
|
||||
if err != nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("create review snapshot directory: %w", err)
|
||||
}
|
||||
defer os.RemoveAll(snapshotDir)
|
||||
if err := r.trees.Snapshot(ctx, dir, snapshotDir); err != nil {
|
||||
return gateway.PRReviewResult{}, fmt.Errorf("snapshot PR head: %w", err)
|
||||
}
|
||||
|
||||
maxSteps := r.maxSteps
|
||||
if r.currentMaxSteps != nil {
|
||||
maxSteps = r.currentMaxSteps()
|
||||
}
|
||||
report := reviewer.Review(ctx, workflow.ReviewRequest{
|
||||
SnapshotDir: snapshotDir,
|
||||
Diff: diff,
|
||||
IssueText: prIssueText(pr),
|
||||
MaxSteps: maxSteps,
|
||||
})
|
||||
r.logReview(key, model, report)
|
||||
|
||||
result := mapReviewResult(repo, number, model, report)
|
||||
return r.attachArtifact(ctx, result, identity, owner, name, number, report), nil
|
||||
}
|
||||
|
||||
// authorize enforces the identity-scoped repository allow-list. A nil
|
||||
// identity (dashboard operator) may review any configured repository.
|
||||
func (r *prReviewer) authorize(identity *string, owner, repo string) error {
|
||||
full := owner + "/" + repo
|
||||
if identity == nil {
|
||||
for _, set := range r.allowed {
|
||||
if set[full] {
|
||||
return nil
|
||||
}
|
||||
}
|
||||
return fmt.Errorf("repository %q is not configured", full)
|
||||
}
|
||||
set, ok := r.allowed[*identity]
|
||||
if !ok {
|
||||
return fmt.Errorf("identity %q is not configured for PR review", *identity)
|
||||
}
|
||||
if !set[full] {
|
||||
return fmt.Errorf("repository %q is not configured for this identity", full)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func (r *prReviewer) begin(key string) bool {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
if r.inflight == nil {
|
||||
r.inflight = make(map[string]struct{})
|
||||
}
|
||||
if _, ok := r.inflight[key]; ok {
|
||||
return false
|
||||
}
|
||||
r.inflight[key] = struct{}{}
|
||||
return true
|
||||
}
|
||||
|
||||
func (r *prReviewer) end(key string) {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
delete(r.inflight, key)
|
||||
}
|
||||
|
||||
func (r *prReviewer) logReview(key, model string, report workflow.ReviewReport) {
|
||||
if r.log == nil {
|
||||
return
|
||||
}
|
||||
blocking := 0
|
||||
for _, f := range report.Findings {
|
||||
if f.Blocking() {
|
||||
blocking++
|
||||
}
|
||||
}
|
||||
r.log.Info("operator PR review complete",
|
||||
"pr", key, "model", model, "status", string(report.Status),
|
||||
"findings", len(report.Findings), "blocking", blocking)
|
||||
}
|
||||
|
||||
// attachArtifact publishes the report when the sender is configured and
|
||||
// records the editor deep link on the result. Publishing never fails the
|
||||
// review: a failure degrades to an empty URL.
|
||||
func (r *prReviewer) attachArtifact(ctx context.Context, result gateway.PRReviewResult, identity *string, owner, name string, number int, report workflow.ReviewReport) gateway.PRReviewResult {
|
||||
result.ArtifactURL = r.publishArtifact(ctx, reviewActor(identity), owner, name, number, report)
|
||||
return result
|
||||
}
|
||||
|
||||
// reviewActor resolves the attribution: the requesting chat identity when one
|
||||
// exists, else the daemon's operator-reviewer actor.
|
||||
func reviewActor(identity *string) string {
|
||||
if identity != nil && *identity != "" {
|
||||
return *identity
|
||||
}
|
||||
return "system:pr-reviewer"
|
||||
}
|
||||
|
||||
// publishArtifact renders the report and hands it to the collaborative
|
||||
// editor when artifact publishing is configured. It returns the editor deep
|
||||
// link, or "" when publishing is disabled or failed: a publish failure is a
|
||||
// logged degradation, never an error that fails the producing review.
|
||||
func (r *prReviewer) publishArtifact(ctx context.Context, actor, owner, name string, number int, report workflow.ReviewReport) string {
|
||||
if r.artifacts == nil {
|
||||
return ""
|
||||
}
|
||||
title := fmt.Sprintf("Review of %s/%s#%d", owner, name, number)
|
||||
artifact := artifactsync.Artifact{
|
||||
Title: title,
|
||||
Source: report.RenderMarkdown(title),
|
||||
Meta: artifactsync.Meta{
|
||||
Format: "markdown",
|
||||
Category: "pr-review",
|
||||
Visibility: "account-only",
|
||||
Egress: "none",
|
||||
Actor: actor,
|
||||
Origin: "pr-review",
|
||||
RequestID: "artifact:pr-review:" + owner + "/" + name + "#" + strconv.Itoa(number),
|
||||
Version: "r1",
|
||||
SentAt: time.Now().UTC(),
|
||||
Task: &artifactsync.Task{Owner: owner, Repo: name, Number: number},
|
||||
},
|
||||
}
|
||||
url, err := r.artifacts.Publish(ctx, artifact)
|
||||
if err != nil {
|
||||
if r.log != nil {
|
||||
r.log.Warn("artifact publish failed; the review result is unaffected",
|
||||
"artifact", artifact.RequestID(), "err", err)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
if r.log != nil {
|
||||
r.log.Info("artifact published", "artifact", artifact.RequestID(), "url", url)
|
||||
}
|
||||
return url
|
||||
}
|
||||
|
||||
// splitOwnerRepo splits "owner/name" with the same validation the gateway's
|
||||
// task_spawn allow-list uses.
|
||||
func splitOwnerRepo(s string) (owner, repo string, err error) {
|
||||
owner, repo, ok := strings.Cut(s, "/")
|
||||
if !ok || owner == "" || repo == "" {
|
||||
return "", "", fmt.Errorf("repository %q must be owner/name", s)
|
||||
}
|
||||
return owner, repo, nil
|
||||
}
|
||||
|
||||
// prIssueText renders the PR title/body as the review's issue text.
|
||||
func prIssueText(pr forge.PullRequest) string {
|
||||
if pr.Body == "" {
|
||||
return pr.Title
|
||||
}
|
||||
return pr.Title + "\n\n" + pr.Body
|
||||
}
|
||||
|
||||
// mapReviewResult adapts a workflow.ReviewReport into the gateway's
|
||||
// channel-neutral result shape.
|
||||
func mapReviewResult(repo string, number int, model string, report workflow.ReviewReport) gateway.PRReviewResult {
|
||||
out := gateway.PRReviewResult{
|
||||
Repo: repo,
|
||||
Number: number,
|
||||
Model: model,
|
||||
Status: string(report.Status),
|
||||
Summary: report.Summary,
|
||||
Reason: report.SkipReason,
|
||||
Findings: make([]gateway.PRReviewFinding, 0, len(report.Findings)),
|
||||
}
|
||||
for _, f := range report.Findings {
|
||||
out.Findings = append(out.Findings, gateway.PRReviewFinding{
|
||||
File: f.File,
|
||||
Line: f.Line,
|
||||
Defect: f.Defect,
|
||||
FailureScenario: f.FailureScenario,
|
||||
Verdict: string(f.Verdict),
|
||||
Level: string(f.Level),
|
||||
Category: string(f.Category),
|
||||
Blocking: f.Blocking(),
|
||||
})
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// buildReviewAllowlist derives the identity-scoped review allow-list from the
|
||||
// same profiles task_spawn uses, so a chat identity and the review command
|
||||
// agree on which repositories the identity may touch.
|
||||
func buildReviewAllowlist(cfg config.Config) map[string]map[string]bool {
|
||||
profiles, _ := chatTaskProfiles(cfg)
|
||||
out := make(map[string]map[string]bool, len(profiles))
|
||||
for _, p := range profiles {
|
||||
set := make(map[string]bool, len(p.Repos))
|
||||
for _, repo := range p.Repos {
|
||||
set[repo] = true
|
||||
}
|
||||
out[p.Identity] = set
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// prReviewer assembles the operator-triggered review capability, or nil when
|
||||
// the forge cannot read PRs (the noop forge, or a forge with no PR read
|
||||
// support). A review tool that can never run must not be advertised, matching
|
||||
// the TaskTools nil-backend rule.
|
||||
//
|
||||
// The instance is built once and memoized on the boot struct so every channel
|
||||
// shares one in-flight set: a review of the same PR requested concurrently
|
||||
// from the Web UI and Telegram deduplicates instead of running twice.
|
||||
func (b *boot) prReviewer() gateway.ChatPRReviewer {
|
||||
if b.chatPRReviewer != nil {
|
||||
return b.chatPRReviewer
|
||||
}
|
||||
if b.trees == nil {
|
||||
return nil
|
||||
}
|
||||
forgeReader, _ := b.forgeClient.(forge.PullRequestReader)
|
||||
if forgeReader == nil {
|
||||
return nil
|
||||
}
|
||||
maxSteps := b.cfg.Budgets.MaxSteps
|
||||
if b.cfgHolder != nil {
|
||||
maxSteps = b.cfgHolder.Get().Budgets.MaxSteps
|
||||
}
|
||||
review := &prReviewer{
|
||||
forge: forgeReader,
|
||||
trees: b.trees,
|
||||
models: b.cfg.Models,
|
||||
providers: executionProviders(b.cfg),
|
||||
maxSteps: maxSteps,
|
||||
artifacts: b.artifactSender(),
|
||||
allowed: buildReviewAllowlist(b.cfg),
|
||||
log: b.log,
|
||||
}
|
||||
if b.cfgHolder != nil {
|
||||
review.currentMaxSteps = func() int { return b.cfgHolder.Get().Budgets.MaxSteps }
|
||||
}
|
||||
b.chatPRReviewer = review
|
||||
return b.chatPRReviewer
|
||||
}
|
||||
|
||||
// artifactSender builds the collaborative-editor sender when the [artifacts]
|
||||
// section configures one. An empty base_url disables publishing entirely; a
|
||||
// base_url with an unresolvable token is a missing credential, which disables
|
||||
// the capability with a loud warning rather than stopping the daemon
|
||||
// (docs/architecture/configuration.md, "A missing credential disables a
|
||||
// capability").
|
||||
func (b *boot) artifactSender() artifactsync.Sender {
|
||||
cfg := b.cfg.Artifacts
|
||||
if cfg.BaseURL == "" {
|
||||
return nil
|
||||
}
|
||||
token, err := b.secrets.Resolve(cfg.Token)
|
||||
if err != nil {
|
||||
b.log.Warn("artifact publishing disabled: the service credential could not be resolved",
|
||||
"base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine, "err", err)
|
||||
return nil
|
||||
}
|
||||
if token == "" {
|
||||
b.log.Warn("artifact publishing disabled: the service token resolved empty",
|
||||
"base_url", cfg.BaseURL, "token_engine", cfg.Token.Engine)
|
||||
return nil
|
||||
}
|
||||
return artifactsync.NewClient(cfg.BaseURL, token)
|
||||
}
|
||||
@@ -1,317 +0,0 @@
|
||||
package archied
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"log/slog"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow"
|
||||
"github.com/samcharles93/archie-core/internal/forge"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/artifactsync"
|
||||
"github.com/samcharles93/archie-core/internal/tools"
|
||||
"github.com/samcharles93/archie-core/internal/worktree"
|
||||
)
|
||||
|
||||
func TestSplitOwnerRepo(t *testing.T) {
|
||||
tests := []struct {
|
||||
in string
|
||||
owner string
|
||||
repo string
|
||||
wantErr bool
|
||||
}{
|
||||
{"acme/widget", "acme", "widget", false},
|
||||
{"acme/widget/service", "acme", "widget/service", false},
|
||||
{"acme", "", "", true},
|
||||
{"/widget", "", "", true},
|
||||
{"acme/", "", "", true},
|
||||
{"", "", "", true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
owner, repo, err := splitOwnerRepo(tt.in)
|
||||
if tt.wantErr {
|
||||
if err == nil {
|
||||
t.Errorf("splitOwnerRepo(%q) error = nil, want error", tt.in)
|
||||
}
|
||||
continue
|
||||
}
|
||||
if err != nil {
|
||||
t.Errorf("splitOwnerRepo(%q) error = %v", tt.in, err)
|
||||
continue
|
||||
}
|
||||
if owner != tt.owner || repo != tt.repo {
|
||||
t.Errorf("splitOwnerRepo(%q) = (%q, %q), want (%q, %q)", tt.in, owner, repo, tt.owner, tt.repo)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestPRIssueText(t *testing.T) {
|
||||
tests := []struct {
|
||||
name string
|
||||
pr forge.PullRequest
|
||||
want string
|
||||
}{
|
||||
{"title only", forge.PullRequest{Title: "Fix login"}, "Fix login"},
|
||||
{"title and body", forge.PullRequest{Title: "Fix login", Body: "The form 500s."}, "Fix login\n\nThe form 500s."},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
if got := prIssueText(tt.pr); got != tt.want {
|
||||
t.Errorf("prIssueText = %q, want %q", got, tt.want)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestMapReviewResult(t *testing.T) {
|
||||
report := workflow.ReviewReport{
|
||||
Status: workflow.ReviewStatusCompleted,
|
||||
Summary: "checked and cleared",
|
||||
Findings: []workflow.ReviewFinding{
|
||||
{File: "a.go", Line: 3, Defect: "nil deref", FailureScenario: "x", Verdict: workflow.ReviewVerdictConfirmed, Level: workflow.ReviewLevelError, Category: workflow.ReviewCategoryNilRisk},
|
||||
{File: "b.go", Line: 0, Defect: "style", FailureScenario: "y", Verdict: workflow.ReviewVerdictPlausible, Level: workflow.ReviewLevelWarn, Category: workflow.ReviewCategoryOther},
|
||||
},
|
||||
}
|
||||
got := mapReviewResult("acme/widget", 7, "openai/gpt-5", report)
|
||||
|
||||
if got.Repo != "acme/widget" || got.Number != 7 || got.Model != "openai/gpt-5" || got.Status != "completed" || got.Summary != "checked and cleared" {
|
||||
t.Fatalf("result meta = %+v", got)
|
||||
}
|
||||
if len(got.Findings) != 2 {
|
||||
t.Fatalf("findings = %d, want 2", len(got.Findings))
|
||||
}
|
||||
if !got.Findings[0].Blocking {
|
||||
t.Error("confirmed error finding should be blocking")
|
||||
}
|
||||
if got.Findings[1].Blocking {
|
||||
t.Error("plausible warn finding must not be blocking")
|
||||
}
|
||||
if got.Findings[0].Line != 3 {
|
||||
t.Errorf("line = %d, want 3", got.Findings[0].Line)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMapReviewResultNotRunPreservesReason(t *testing.T) {
|
||||
report := workflow.NewNotRunReviewReport("no reviewer model configured")
|
||||
got := mapReviewResult("acme/widget", 7, "", report)
|
||||
if got.Status != "not_run" || got.Reason != "no reviewer model configured" {
|
||||
t.Fatalf("not_run result = %+v, want status not_run and reason preserved", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrReviewerAuthorize(t *testing.T) {
|
||||
r := &prReviewer{allowed: map[string]map[string]bool{
|
||||
"": {"acme/widget": true, "acme/core": true},
|
||||
"archie": {"acme/widget": true},
|
||||
}}
|
||||
archie := "archie"
|
||||
other := "other"
|
||||
|
||||
tests := []struct {
|
||||
name string
|
||||
identity *string
|
||||
owner string
|
||||
repo string
|
||||
wantErr bool
|
||||
}{
|
||||
{"identity own repo", &archie, "acme", "widget", false},
|
||||
{"identity foreign repo", &archie, "acme", "core", true},
|
||||
{"unknown identity", &other, "acme", "widget", true},
|
||||
{"operator any configured", nil, "acme", "core", false},
|
||||
{"operator unconfigured repo", nil, "acme", "other", true},
|
||||
}
|
||||
for _, tt := range tests {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
err := r.authorize(tt.identity, tt.owner, tt.repo)
|
||||
if tt.wantErr && err == nil {
|
||||
t.Errorf("authorize(%v, %s/%s) error = nil, want error", tt.identity, tt.owner, tt.repo)
|
||||
}
|
||||
if !tt.wantErr && err != nil {
|
||||
t.Errorf("authorize(%v, %s/%s) error = %v, want nil", tt.identity, tt.owner, tt.repo, err)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrReviewerSingleflight(t *testing.T) {
|
||||
r := &prReviewer{}
|
||||
key := "acme/widget#7"
|
||||
if !r.begin(key) {
|
||||
t.Fatal("first begin = false, want true")
|
||||
}
|
||||
if r.begin(key) {
|
||||
t.Fatal("concurrent begin = true, want false (deterministic single-flight)")
|
||||
}
|
||||
r.end(key)
|
||||
if !r.begin(key) {
|
||||
t.Fatal("begin after end = false, want true")
|
||||
}
|
||||
}
|
||||
|
||||
func TestBuildReviewAllowlist(t *testing.T) {
|
||||
cfg := config.Config{
|
||||
Identities: []config.IdentityConfig{
|
||||
{Name: "archie", Repos: []config.Repo{{Owner: "acme", Name: "widget"}}},
|
||||
},
|
||||
}
|
||||
allowed := buildReviewAllowlist(cfg)
|
||||
|
||||
if !allowed["archie"]["acme/widget"] {
|
||||
t.Errorf("allowlist missing acme/widget for identity archie: %+v", allowed)
|
||||
}
|
||||
if allowed["archie"]["acme/core"] {
|
||||
t.Errorf("allowlist leaked acme/core to identity archie: %+v", allowed)
|
||||
}
|
||||
if _, ok := allowed["nobody"]; ok {
|
||||
t.Errorf("allowlist contains unknown identity nobody: %+v", allowed)
|
||||
}
|
||||
}
|
||||
|
||||
// reviewCapableForge satisfies both forge.Forge (via embedding) and
|
||||
// forge.PullRequestReader, so boot.prReviewer can be exercised in isolation.
|
||||
type reviewCapableForge struct {
|
||||
forge.Forge
|
||||
}
|
||||
|
||||
func (reviewCapableForge) GetPullRequest(context.Context, string, string, int) (forge.PullRequest, error) {
|
||||
return forge.PullRequest{}, nil
|
||||
}
|
||||
|
||||
// TestPrReviewerIsMemoized pins the cross-channel single-flight fix: every
|
||||
// gateway must share one prReviewer so a review of the same PR requested from
|
||||
// two channels at once deduplicates instead of running twice. The boot must
|
||||
// own a worktree manager: a reviewer without one can never run and must not be
|
||||
// produced (see TestPrReviewerNilWithoutTrees).
|
||||
func TestPrReviewerIsMemoized(t *testing.T) {
|
||||
b := &boot{
|
||||
forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))},
|
||||
trees: &worktree.Manager{},
|
||||
}
|
||||
|
||||
first := b.prReviewer()
|
||||
if first == nil {
|
||||
t.Fatal("prReviewer() = nil, want a reviewer")
|
||||
}
|
||||
if second := b.prReviewer(); first != second {
|
||||
t.Fatal("prReviewer() returned distinct instances; channels would not share the in-flight set")
|
||||
}
|
||||
}
|
||||
|
||||
// TestPrReviewerNilWithoutTrees pins the producer-side invariant: a PR-capable
|
||||
// forge without a worktree manager must yield no reviewer. The standalone
|
||||
// Gateway never builds trees, and the daemon used to capture b.trees before it
|
||||
// was assigned, so both advertised a review_pr tool that always failed.
|
||||
func TestPrReviewerNilWithoutTrees(t *testing.T) {
|
||||
b := &boot{forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))}}
|
||||
|
||||
if got := b.prReviewer(); got != nil {
|
||||
t.Fatalf("prReviewer() with no worktree manager = %T, want nil", got)
|
||||
}
|
||||
}
|
||||
|
||||
// TestReviewPRToolRegisteredOnlyWithWorkingReviewer composes the real boot
|
||||
// wiring (boot.prReviewer -> gateway.ReviewTools) and asserts review_pr is
|
||||
// advertised only when the reviewer can actually run.
|
||||
func TestReviewPRToolRegisteredOnlyWithWorkingReviewer(t *testing.T) {
|
||||
logger := slog.New(slog.DiscardHandler)
|
||||
b := &boot{
|
||||
forgeClient: reviewCapableForge{Forge: forge.NewNoop(logger)},
|
||||
log: logger,
|
||||
}
|
||||
|
||||
if hasReviewPRTool(gateway.ReviewTools(b.prReviewer(), "archie")) {
|
||||
t.Fatal("review_pr advertised with no worktree manager: a tool that cannot run must not be offered")
|
||||
}
|
||||
|
||||
b.trees = &worktree.Manager{}
|
||||
if !hasReviewPRTool(gateway.ReviewTools(b.prReviewer(), "archie")) {
|
||||
t.Fatal("review_pr not advertised with a worktree manager")
|
||||
}
|
||||
}
|
||||
|
||||
// hasReviewPRTool reports whether review_pr is offered. Presence is asserted by
|
||||
// name rather than by entry count: the contract is that this one capability is
|
||||
// offered only when it can run, so adding a sibling review tool must not turn
|
||||
// this red.
|
||||
func hasReviewPRTool(entries []tools.ToolEntry) bool {
|
||||
for _, e := range entries {
|
||||
if e.Name == "review_pr" {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
type fakeArtifactSender struct {
|
||||
calls int
|
||||
url string
|
||||
err error
|
||||
last artifactsync.Artifact
|
||||
}
|
||||
|
||||
func (f *fakeArtifactSender) Publish(_ context.Context, a artifactsync.Artifact) (string, error) {
|
||||
f.calls++
|
||||
f.last = a
|
||||
if f.err != nil {
|
||||
return "", f.err
|
||||
}
|
||||
return f.url, nil
|
||||
}
|
||||
|
||||
func TestPrReviewerPublishesTheCompletedReview(t *testing.T) {
|
||||
fake := &fakeArtifactSender{url: "https://offloaded.dev/collab?document=a_1"}
|
||||
r := &prReviewer{artifacts: fake, log: slog.New(slog.DiscardHandler)}
|
||||
report := workflow.NewCompletedReviewReport([]workflow.ReviewFinding{{
|
||||
File: "handler.go", Line: 42, Defect: "nil deref",
|
||||
FailureScenario: "empty payload crashes", Verdict: workflow.ReviewVerdictConfirmed,
|
||||
Level: workflow.ReviewLevelError,
|
||||
}}, "one finding")
|
||||
report.Checked = []workflow.ReviewCheck{{Property: "p", Evidence: "e"}}
|
||||
|
||||
url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, report)
|
||||
if url != fake.url {
|
||||
t.Fatalf("publishArtifact = %q, want the sender's url %q", url, fake.url)
|
||||
}
|
||||
if fake.calls != 1 {
|
||||
t.Fatalf("Publish called %d times, want 1", fake.calls)
|
||||
}
|
||||
got := fake.last
|
||||
if got.Meta.Format != "markdown" || got.Meta.Category != "pr-review" {
|
||||
t.Fatalf("format/category = %s/%s, want markdown/pr-review", got.Meta.Format, got.Meta.Category)
|
||||
}
|
||||
if got.Meta.Actor != "system:pr-reviewer" || got.Meta.Origin != "pr-review" {
|
||||
t.Fatalf("attribution = %s/%s", got.Meta.Actor, got.Meta.Origin)
|
||||
}
|
||||
if got.Meta.Visibility != "account-only" || got.Meta.Egress != "none" {
|
||||
t.Fatalf("visibility/egress = %s/%s", got.Meta.Visibility, got.Meta.Egress)
|
||||
}
|
||||
if got.Title != "Review of acme/widget#7" {
|
||||
t.Fatalf("title = %q", got.Title)
|
||||
}
|
||||
if got.Meta.RequestID != "artifact:pr-review:acme/widget#7" {
|
||||
t.Fatalf("requestId = %q, want the deterministic artifact key", got.Meta.RequestID)
|
||||
}
|
||||
if got.Meta.Task == nil || got.Meta.Task.Owner != "acme" || got.Meta.Task.Number != 7 {
|
||||
t.Fatalf("task coordinates = %+v", got.Meta.Task)
|
||||
}
|
||||
if !strings.Contains(got.Source, "## Findings") {
|
||||
t.Fatalf("source is not the rendered report:\n%s", got.Source)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrReviewerPublishDegradesOnSenderFailure(t *testing.T) {
|
||||
r := &prReviewer{artifacts: &fakeArtifactSender{err: errors.New("503 exhausted")}, log: slog.New(slog.DiscardHandler)}
|
||||
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
|
||||
t.Fatalf("url = %q, want empty on a failed publish", url)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrReviewerPublishIsANoOpWithoutASender(t *testing.T) {
|
||||
r := &prReviewer{}
|
||||
if url := r.publishArtifact(context.Background(), "system:pr-reviewer", "acme", "widget", 7, workflow.NewCompletedReviewReport(nil, "s")); url != "" {
|
||||
t.Fatalf("url = %q, want empty when the sender is disabled", url)
|
||||
}
|
||||
}
|
||||
@@ -44,6 +44,9 @@ func (b *boot) setupReadinessProbes() {
|
||||
return pingChat(ctx, b.chat)
|
||||
}),
|
||||
}
|
||||
if b.accessProblems != nil {
|
||||
probes = append(probes, readiness.NewProblemProbe("access_policies", b.accessProblems))
|
||||
}
|
||||
b.healthRegistry = health.NewRegistry(probes...)
|
||||
}
|
||||
|
||||
|
||||
@@ -84,13 +84,13 @@ func TestSetupReadinessProbes_WiresEverySubsystem(t *testing.T) {
|
||||
}
|
||||
|
||||
report := b.healthRegistry.Run(context.Background())
|
||||
if len(report.Components) != 5 {
|
||||
t.Fatalf("components = %d, want 5: %+v", len(report.Components), report.Components)
|
||||
got := map[string]int{}
|
||||
for _, c := range report.Components {
|
||||
got[c.Name]++
|
||||
}
|
||||
want := []string{"state_db", "config", "disk", "model", "gateway"}
|
||||
for i, name := range want {
|
||||
if report.Components[i].Name != name {
|
||||
t.Fatalf("component[%d] = %q, want %q", i, report.Components[i].Name, name)
|
||||
for _, name := range []string{"state_db", "config", "disk", "model", "gateway"} {
|
||||
if got[name] != 1 {
|
||||
t.Errorf("component %q registered %d times, want 1: %+v", name, got[name], report.Components)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -117,6 +117,7 @@ var reloadableFields = map[string]bool{
|
||||
"Models": true,
|
||||
"ModelLimits": true,
|
||||
"Notify": true,
|
||||
"Review": true,
|
||||
// BotUser/BotEmail used to be poll-path only; ForTask now carries both
|
||||
// into the task snapshot as well, because the sandboxed worker builds
|
||||
// its own worktree.Manager and signs its own commits (agentworker
|
||||
@@ -148,16 +149,23 @@ var reloadableFields = map[string]bool{
|
||||
|
||||
// reloadableSubFields are sub-fields of structs that are otherwise
|
||||
// startup-built. VolumeTTL is re-read per cycle in cleanupExpiredStorage;
|
||||
// everything else in Containers (Image, MaxConcurrency,
|
||||
// MaxUptime, PullPolicy, Network) is frozen in the startup-built
|
||||
// container pool -- the dispatchers re-read MaxConcurrency but the pool
|
||||
// captures it at construction (container/pool.go:94,163), so a change
|
||||
// only partially applies and must warn requires-restart. Forge.Host is
|
||||
// carried into TaskContext by ForTask (display/link building only); the
|
||||
// forge client itself is startup-built, so Type/Token/TokenEnv stay
|
||||
// requires-restart.
|
||||
// Profiles is resolved fresh per dispatch (daemon.configFor ->
|
||||
// Containers.Profile, called from pinTaskProfile) and is also its own
|
||||
// live-applying control-plane resource (AgentProfileKind), never captured at
|
||||
// container-pool construction -- docs/prds/external-agent-harness.md
|
||||
// "Selection": a Kit profile applies without a restart. Credentials is the
|
||||
// same shape one layer down: kitrun.Launcher reads Config.Get().Containers.
|
||||
// Credentials fresh on every Launch (CredentialBindingsKind), never a slice
|
||||
// captured once when the launcher was built. Everything else in
|
||||
// Containers (Image, MaxConcurrency, MaxUptime, PullPolicy, Network) is
|
||||
// frozen in the startup-built container pool -- the dispatchers re-read
|
||||
// MaxConcurrency but the pool captures it at construction
|
||||
// (container/pool.go:94,163), so a change only partially applies and must
|
||||
// warn requires-restart. Forge.Host is carried into TaskContext by ForTask
|
||||
// (display/link building only); the forge client itself is startup-built, so
|
||||
// Type/Token/TokenEnv stay requires-restart.
|
||||
var reloadableSubFields = map[string]map[string]bool{
|
||||
"Containers": {"VolumeTTL": true},
|
||||
"Containers": {"VolumeTTL": true, "Profiles": true, "Credentials": true},
|
||||
"Forge": {"Host": true},
|
||||
// Policy is carried into TaskConfig by ForTask (config.go); MCPServers,
|
||||
// WebFetch and Minimax are not and stay requires-restart.
|
||||
|
||||
@@ -95,11 +95,20 @@ func sendNotify(addr, state string) error {
|
||||
}
|
||||
|
||||
// announceReady tells systemd the daemon has finished starting. It is called at
|
||||
// the moment the process declares itself serving (runLoop, next to
|
||||
// healthSurface.markServing), which is the same fact READY=1 asserts: boot is
|
||||
// over and the run loop is about to take over.
|
||||
// the moment a process declares itself serving: the daemon's run loop (next to
|
||||
// healthSurface.markServing), and the serve steps of archie-gateway and
|
||||
// archie-state-store (archie-core-1174), which have health surfaces of their
|
||||
// own and would otherwise hang a Type=notify unit until TimeoutStartSec while
|
||||
// perfectly healthy.
|
||||
func (b *boot) announceReady() {
|
||||
newNotifier(os.Getenv, b.log).send(readyState)
|
||||
notifyReady(b.log)
|
||||
}
|
||||
|
||||
// notifyReady is announceReady without the boot: the Gateway's serving tail
|
||||
// runs on a boot it owns, but a free helper keeps the announcement one call
|
||||
// rather than a second notion of "started" on each surface.
|
||||
func notifyReady(log *slog.Logger) {
|
||||
newNotifier(os.Getenv, log).send(readyState)
|
||||
}
|
||||
|
||||
// startWatchdog arms the heartbeat sampler for the daemon's run loop. It does
|
||||
|
||||
@@ -17,6 +17,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/daemon"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgstore"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres/pgtest"
|
||||
)
|
||||
|
||||
// notifyRecorder captures every record at every level. The other recording
|
||||
@@ -119,6 +120,28 @@ func countState(states []string, want string) int {
|
||||
return n
|
||||
}
|
||||
|
||||
// waitForState reads datagrams until one carries want or the window closes.
|
||||
// The states drain above collects a window's worth; a boot-path test waiting
|
||||
// for one state returns as soon as it arrives.
|
||||
func (l *notifyListener) waitForState(t *testing.T, window time.Duration, want string) bool {
|
||||
t.Helper()
|
||||
deadline := time.Now().Add(window)
|
||||
buf := make([]byte, 1024)
|
||||
for time.Now().Before(deadline) {
|
||||
if err := l.conn.SetReadDeadline(time.Now().Add(50 * time.Millisecond)); err != nil {
|
||||
t.Fatalf("set notify read deadline: %v", err)
|
||||
}
|
||||
n, _, err := l.conn.ReadFromUnix(buf)
|
||||
if err != nil {
|
||||
continue
|
||||
}
|
||||
if string(buf[:n]) == want {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// newNotifyTestBoot builds the composition the notify path reads: a boot whose
|
||||
// config holder supplies the run loop's poll cadence, and a real daemon whose
|
||||
// own poll loop stamps the progress marker the heartbeat sampler samples.
|
||||
@@ -363,3 +386,36 @@ func TestNotifySocketFailureIsNotFatal(t *testing.T) {
|
||||
t.Errorf("an unusable notify socket logged %d errors, want none: %v", len(errs), errs)
|
||||
}
|
||||
}
|
||||
|
||||
// TestStateStoreBootAnnouncesReady: archie-state-store run as a Type=notify
|
||||
// unit must send READY=1 once its boot is over and it is serving the contract,
|
||||
// or systemd kills a healthy process once TimeoutStartSec expires
|
||||
// (archie-core-1174). The real RunStateStore composition drives it, over a
|
||||
// real State Store database, the way the provider-seeding boot test does.
|
||||
func TestStateStoreBootAnnouncesReady(t *testing.T) {
|
||||
listener := newNotifyListener(t)
|
||||
url := pgtest.URL(t)
|
||||
path := filepath.Join(t.TempDir(), "config.toml")
|
||||
body := fmt.Sprintf("bot_user = 'archie'\ndatabase_url = %q\n", url)
|
||||
if err := os.WriteFile(path, []byte(body), 0o600); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
ctx, cancel := context.WithCancel(t.Context())
|
||||
defer cancel()
|
||||
errCh := make(chan error, 1)
|
||||
go func() { errCh <- RunStateStore(ctx, StateStoreOptions{Config: path, Listen: "127.0.0.1:0"}) }()
|
||||
|
||||
if !listener.waitForState(t, 15*time.Second, readyState) {
|
||||
select {
|
||||
case bootErr := <-errCh:
|
||||
t.Fatalf("RunStateStore exited before announcing ready: %v", bootErr)
|
||||
default:
|
||||
t.Fatal("no READY=1 datagram within 15s of boot")
|
||||
}
|
||||
}
|
||||
|
||||
cancel()
|
||||
if err := <-errCh; err != nil && !errors.Is(err, context.Canceled) {
|
||||
t.Fatalf("RunStateStore shutdown: %v", err)
|
||||
}
|
||||
}
|
||||
@@ -21,11 +21,17 @@ import (
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/app/controlplane"
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/domain/access"
|
||||
"github.com/samcharles93/archie-core/internal/domain/health"
|
||||
"github.com/samcharles93/archie-core/internal/domain/identity"
|
||||
"github.com/samcharles93/archie-core/internal/domain/org"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storepkg"
|
||||
infraaccess "github.com/samcharles93/archie-core/internal/infrastructure/access"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/postgres"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/readiness"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
|
||||
registry "github.com/samcharles93/archie-core/internal/infrastructure/storepkg"
|
||||
)
|
||||
|
||||
func configuredIdentityNames(cfg config.Config) []string {
|
||||
@@ -66,7 +72,7 @@ type StateStoreOptions struct {
|
||||
// The conversation store belongs to the separate archie-gateway process. The
|
||||
// store service owns its own DB lifecycle, so
|
||||
// b.cleanup() is the sole owner closing b.st here (in-process owner).
|
||||
func RunStateStore(ctx context.Context, options StateStoreOptions) error {
|
||||
func RunStateStore(ctx context.Context, options StateStoreOptions) error { //nolint:cyclop // the composition root's setup sequence is deliberately flat and sequential
|
||||
b := newBootstrap()
|
||||
defer b.cleanup()
|
||||
if err := b.loadConfig(ctx, options.Config, options.Overlay); err != nil {
|
||||
@@ -90,12 +96,26 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error {
|
||||
if err := identityStore.BootstrapIdentities(ctx, legacyNames); err != nil {
|
||||
return fmt.Errorf("bootstrap identities: %w", err)
|
||||
}
|
||||
// The resumable default org/workspace upgrade runs before this process
|
||||
// serves anything: the State Store refuses scoped calls until its upgrade
|
||||
// has finished, rather than serving records with no org
|
||||
// (docs/prds/orgs-and-access.md, "Upgrading existing installs"). A store
|
||||
// without the upgrader is one that owns no tenant boundary yet, so the
|
||||
// absence degrades to "no upgrade" rather than aborting boot.
|
||||
if upgrader, ok := b.st.(org.Upgrader); ok {
|
||||
if err := upgrader.UpgradeDefaultOrg(ctx); err != nil {
|
||||
return fmt.Errorf("upgrade default org: %w", err)
|
||||
}
|
||||
}
|
||||
if err := b.seedAndValidatePolicies(ctx); err != nil {
|
||||
return err
|
||||
}
|
||||
// The validating side's control plane, built here at the composition root
|
||||
// before the first definition is read or replaced.
|
||||
resources, ok := b.st.(controlplane.ResourceStore)
|
||||
if !ok {
|
||||
return fmt.Errorf("state store does not support control-plane resources")
|
||||
}
|
||||
// The validating side's control plane, built here at the composition root
|
||||
// before the first definition is read or replaced.
|
||||
control, err := openStateStoreControlPlane(resources)
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -126,12 +146,66 @@ func RunStateStore(ctx context.Context, options StateStoreOptions) error {
|
||||
if err := b.startOptionalSurfaces(ctx, options); err != nil {
|
||||
return err
|
||||
}
|
||||
// Boot is over and every listener this process serves is bound: the gRPC
|
||||
// contract below and, when -ready-addr asked for one, the readiness HTTP
|
||||
// surface. systemd's READY=1 asserts the same fact, so the announcement
|
||||
// goes out here rather than from a second notion of "started"
|
||||
// (archie-core-1174). Not earlier: a readiness surface that fails to bind
|
||||
// fails the boot, and READY must not precede it. Not later: Serve begins
|
||||
// accepting the moment it is called.
|
||||
b.announceReady()
|
||||
|
||||
deps := b.stateStoreDeps(grants)
|
||||
deps.ControlPlane = control
|
||||
return serveStateStore(ctx, listener, deps, opts)
|
||||
}
|
||||
|
||||
// seedAndValidatePolicies seeds the shipped role policies for every org
|
||||
// that lacks them, grants the agent identities their org's shipped developer
|
||||
// role, and re-validates every stored policy this process serves
|
||||
// (docs/prds/orgs-and-access.md, "Storing and changing policies" and
|
||||
// "Roles"). An invalid org, workspace or object policy is logged here and
|
||||
// named as a problem by the engines the consumers build; an invalid instance
|
||||
// policy fails this boot -- the store stops serving until it is fixed. A
|
||||
// store without the access surfaces degrades: there is no chain to seed.
|
||||
func (b *boot) seedAndValidatePolicies(ctx context.Context) error {
|
||||
policies, ok := b.st.(access.PolicyStore)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
if agents, ok := b.st.(interface {
|
||||
EnsureAgentOrgMembership(context.Context) error
|
||||
}); ok {
|
||||
if err := agents.EnsureAgentOrgMembership(ctx); err != nil {
|
||||
return fmt.Errorf("grant agent org membership: %w", err)
|
||||
}
|
||||
}
|
||||
if orgs, ok := b.st.(org.Repository); ok {
|
||||
list, err := orgs.ListOrgs(ctx)
|
||||
if err != nil {
|
||||
return fmt.Errorf("list orgs for policy seeding: %w", err)
|
||||
}
|
||||
for _, o := range list {
|
||||
if err := policies.EnsureShippedOrgPolicies(ctx, o.ID); err != nil {
|
||||
return fmt.Errorf("seed shipped org policies for %s: %w", o.ID, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
stored, err := policies.ListPolicies(ctx)
|
||||
if err != nil {
|
||||
return fmt.Errorf("load stored policies: %w", err)
|
||||
}
|
||||
engine, err := infraaccess.New(stored)
|
||||
if err != nil {
|
||||
return fmt.Errorf("validate stored policies: %w", err)
|
||||
}
|
||||
for _, problem := range engine.Problems() {
|
||||
b.log.Error("stored access policy is invalid and denies its level",
|
||||
"policy", problem.Policy.ID, "level", problem.Policy.Level, "err", problem.Err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// reportUnseededResources logs every kind ImportConfig could not seed.
|
||||
//
|
||||
// Reported, not fatal: a stale TOML value in a setting the database owns must
|
||||
@@ -214,6 +288,12 @@ func (b *boot) openStateStore(ctx context.Context) error {
|
||||
// degrades that group rather than aborting boot.
|
||||
func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
|
||||
deps := staterpc.Deps{Tasks: b.st, Log: b.log, Grants: grants}
|
||||
if b.pg != nil {
|
||||
deps.Packages = storepkg.Service{
|
||||
Registry: registry.LocalRegistry{},
|
||||
Store: postgres.NewInstalledPackages(b.pg),
|
||||
}
|
||||
}
|
||||
if identities, ok := b.st.(identity.Repository); ok {
|
||||
deps.Identities = identities
|
||||
}
|
||||
@@ -250,6 +330,10 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
|
||||
deps.EventTypes = b.eda
|
||||
deps.Sources = b.eda
|
||||
deps.MappingMatches = b.eda
|
||||
// HarnessSecrets rides the same encrypted-at-rest store as source
|
||||
// webhook secrets (docs/prds/binding-secret-encryption.md), under its
|
||||
// own domain separator (bindingcipher.HarnessSecretDomain).
|
||||
deps.HarnessSecrets = b.eda
|
||||
}
|
||||
// tool_call events project into the tool_calls collection on the same
|
||||
// event-capture store: this process legitimately owns both, so the
|
||||
@@ -263,6 +347,8 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
|
||||
if btc, ok := b.st.(storecontract.BindingTaskCreator); ok {
|
||||
deps.BindingTaskCreator = btc
|
||||
}
|
||||
b.executionDeps(&deps)
|
||||
b.accessDeps(&deps)
|
||||
if css, ok := b.st.(storecontract.ConfigSnapshotStore); ok {
|
||||
deps.ConfigSnapshots = css
|
||||
}
|
||||
@@ -275,6 +361,40 @@ func (b *boot) stateStoreDeps(grants *staterpc.TaskGrants) staterpc.Deps {
|
||||
return deps
|
||||
}
|
||||
|
||||
// executionDeps wires the execution-tree surfaces (workflow calls, step
|
||||
// recording/reading, cancellation) from the same store, degrading each one
|
||||
// independently the store lacks it rather than failing the boot.
|
||||
func (b *boot) executionDeps(deps *staterpc.Deps) {
|
||||
if wc, ok := b.st.(storecontract.WorkflowCaller); ok {
|
||||
deps.WorkflowCalls = wc
|
||||
}
|
||||
if sr, ok := b.st.(storecontract.StepRecorder); ok {
|
||||
deps.Steps = sr
|
||||
}
|
||||
if ec, ok := b.st.(storecontract.ExecutionCanceller); ok {
|
||||
deps.Canceller = ec
|
||||
}
|
||||
if sr, ok := b.st.(storecontract.StepReader); ok {
|
||||
deps.StepReader = sr
|
||||
}
|
||||
}
|
||||
|
||||
// accessDeps wires the policy chain and its denial records from the same
|
||||
// store (docs/prds/orgs-and-access.md). A store without them -- one that owns
|
||||
// no tenant boundary yet -- degrades the access RPCs rather than failing the
|
||||
// boot, the same pattern the other optional surfaces use.
|
||||
func (b *boot) accessDeps(deps *staterpc.Deps) {
|
||||
if ps, ok := b.st.(access.PrincipalSource); ok {
|
||||
deps.Principals = ps
|
||||
}
|
||||
if ps, ok := b.st.(access.PolicyStore); ok {
|
||||
deps.Policies = ps
|
||||
}
|
||||
if ds, ok := b.st.(access.DenialStore); ok {
|
||||
deps.Denials = ds
|
||||
}
|
||||
}
|
||||
|
||||
// serveStateStore registers the StateStore gRPC service and serves it until
|
||||
// ctx ends, draining in-flight calls before returning (mirroring serveGateway
|
||||
// in gateway.go, minus the gateway's session-store argument).
|
||||
|
||||
@@ -17,6 +17,7 @@ type eventCaptureStore interface { //nolint:interfacebloat // composite of the s
|
||||
storecontract.PlaybookDispatcher
|
||||
storecontract.EventTypeStore
|
||||
storecontract.SourceStore
|
||||
storecontract.HarnessSecretStore
|
||||
toolCallWriter
|
||||
}
|
||||
|
||||
|
||||
@@ -175,7 +175,7 @@ func TestStateStoreDataSurvivesRestart(t *testing.T) {
|
||||
if err := first.openStateStore(t.Context()); err != nil {
|
||||
t.Fatalf("first openStateStore: %v", err)
|
||||
}
|
||||
task, err := first.st.EnqueueChatTask(t.Context(), "acme", "widget", "restart check", "body", "implement", "")
|
||||
task, err := first.st.EnqueueChatTask(t.Context(), "acme", "widget", "restart check", "body", "implement", "", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("EnqueueChatTask: %v", err)
|
||||
}
|
||||
|
||||
@@ -16,6 +16,7 @@ import (
|
||||
natsio "github.com/nats-io/nats.go"
|
||||
"github.com/samcharles93/ai-sdk/chat"
|
||||
"github.com/samcharles93/ai-sdk/core"
|
||||
"github.com/samcharles93/ai-sdk/runtime"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/agentexec"
|
||||
"github.com/samcharles93/archie-core/internal/container"
|
||||
@@ -441,7 +442,7 @@ func TestCuratorRunnerRecordsItsOutcome(t *testing.T) {
|
||||
if rt == nil {
|
||||
t.Fatal("NewRuntime returned nil for a configured provider")
|
||||
}
|
||||
runner := curatorLLMRunner{rt: rt, outcomes: recorder}
|
||||
runner := curatorLLMRunner{llm: func() *runtime.Runtime { return rt }, outcomes: recorder}
|
||||
|
||||
_, err := runner.Chat(context.Background(), curator.ChatRequest{Model: "openai/gpt-4o"})
|
||||
if err == nil {
|
||||
@@ -470,7 +471,7 @@ func TestTitleGenerationDoesNotRecordChatModelHealth(t *testing.T) {
|
||||
if rt == nil {
|
||||
t.Fatal("NewRuntime returned nil for a configured provider")
|
||||
}
|
||||
gen := &chatTitleGenerator{llm: rt, chatModels: newChatModelManager(map[string]string{"chat": "openai/gpt-4o"}, nil, nil)}
|
||||
gen := &chatTitleGenerator{llm: func() *runtime.Runtime { return rt }, chatModels: newChatModelManager(map[string]string{"chat": "openai/gpt-4o"}, nil, nil)}
|
||||
|
||||
if _, err := gen.GenerateTitle(context.Background(), "s1", "hello"); err == nil {
|
||||
t.Fatal("GenerateTitle against a closed port returned no error")
|
||||
|
||||
@@ -138,25 +138,27 @@ func TestOnlyTheDaemonRootRegistersAStepVocabulary(t *testing.T) {
|
||||
t.Error("the gateway root file mentions stepVocabulary; the gateway resolves no workflow step type")
|
||||
}
|
||||
|
||||
// The daemon root opens both halves -- the shared adapter and the
|
||||
// daemon-only definitions client -- through one call, so the sequence costs
|
||||
// Run a single branch. The guarantee is the one this pin always held,
|
||||
// relocated to where the sequence now lives: adapter first, then the client
|
||||
// built on its transport, both before buildDaemon captures the client.
|
||||
// The daemon root opens the state stage -- the shared adapter, the
|
||||
// daemon-only definitions client and the access chain -- through one
|
||||
// call, so the sequence costs Run a single branch. The guarantee is the
|
||||
// one this pin always held, relocated to where the sequence now lives:
|
||||
// adapter first, then the client built on its transport, both before
|
||||
// buildDaemon captures the client.
|
||||
run := parsedBody(t, "main.go", "Run")
|
||||
surfaces := methodCallPosition(run, "openDaemonStateSurfaces")
|
||||
stage := methodCallPosition(run, "openStateStage")
|
||||
build := methodCallPosition(run, "buildDaemon")
|
||||
if surfaces == token.NoPos {
|
||||
t.Fatal("Run never opens the daemon's State Store surfaces; every task pin would fall back to the shipped definitions")
|
||||
if stage == token.NoPos {
|
||||
t.Fatal("Run never opens the daemon's state stage; every task pin would fall back to the shipped definitions")
|
||||
}
|
||||
if build == token.NoPos || surfaces > build {
|
||||
t.Errorf("Run opens the daemon's State Store surfaces at %v, after buildDaemon at %v: the daemon would capture no definitions surface", surfaces, build)
|
||||
if build == token.NoPos || stage > build {
|
||||
t.Errorf("Run opens the state stage at %v, after buildDaemon at %v: the daemon would capture no definitions surface", stage, build)
|
||||
}
|
||||
// Neither half may also be opened from Run directly: a second call site
|
||||
// would be a copy of the sequence outside the order asserted below.
|
||||
for _, direct := range []string{"openStateStoreAdapter", "openDaemonWorkflowDefinitions"} {
|
||||
// No half of the stage may also be opened from Run directly: a second
|
||||
// call site would be a copy of the sequence outside the order asserted
|
||||
// below.
|
||||
for _, direct := range []string{"openStateStoreAdapter", "openDaemonWorkflowDefinitions", "openDaemonStateSurfaces", "openAccessChain"} {
|
||||
if pos := methodCallPosition(run, direct); pos != token.NoPos {
|
||||
t.Errorf("Run calls %s directly at %v; the daemon's State Store surfaces open through openDaemonStateSurfaces alone", direct, pos)
|
||||
t.Errorf("Run calls %s directly at %v; the state stage opens through openStateStage alone", direct, pos)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -52,7 +52,7 @@ func TestChatTaskActorAdapterCrossIdentityRefused(t *testing.T) {
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "parked job", "", "", "identity-owner")
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "parked job", "", "", "identity-owner", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -146,7 +146,7 @@ func TestChatTaskActorAdapterRefusesDisallowedStateAction(t *testing.T) {
|
||||
|
||||
for _, tc := range tests {
|
||||
t.Run(tc.name, func(t *testing.T) {
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "test task", "", "", "archie")
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "test task", "", "", "archie", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -251,7 +251,7 @@ func TestChatTaskActorAdapterAppliesActionsToStore(t *testing.T) {
|
||||
|
||||
adapter := newChatTaskActorForTest(t, st, config.Config{MaxRetries: 3})
|
||||
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "actionable task", "", "", "archie")
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "actionable task", "", "", "archie", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
|
||||
@@ -20,6 +20,7 @@ func (b *boot) taskActions() taskactions.Service {
|
||||
b.cancelTask,
|
||||
b.closeIssue,
|
||||
b.removeTaskLogs,
|
||||
b.removeTaskWorktree,
|
||||
b.publishEvent,
|
||||
b.log.Warn,
|
||||
)
|
||||
@@ -46,6 +47,13 @@ func (b *boot) removeTaskLogs(id int64) error {
|
||||
return b.taskLogs.Remove(id)
|
||||
}
|
||||
|
||||
func (b *boot) removeTaskWorktree(task *taskactions.Task) error {
|
||||
if b.d == nil {
|
||||
return nil
|
||||
}
|
||||
return b.d.RemoveWorktree(task.Owner, task.Repo, task.Identity, task.IssueNumber)
|
||||
}
|
||||
|
||||
func (b *boot) publishEvent(e events.Event) {
|
||||
if b.bus != nil {
|
||||
b.bus.Publish(e)
|
||||
|
||||
@@ -48,7 +48,7 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) {
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer")
|
||||
task, err := st.EnqueueChatTask(ctx, "acme", "widget", "decide on me", "", "", "reviewer", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
@@ -76,10 +76,14 @@ func TestDashboardAndChatAgreeOnTerminalStates(t *testing.T) {
|
||||
// controller path and fails the test on error.
|
||||
func runChatAction(t *testing.T, ctx context.Context, st storecontract.TaskStore, action string, taskID int64) {
|
||||
t.Helper()
|
||||
canceller, ok := st.(storecontract.ExecutionCanceller)
|
||||
if !ok {
|
||||
t.Fatal("the task store cannot cancel executions")
|
||||
}
|
||||
controller := gateway.NewStoreTaskController(chatTaskControllerAdapter{
|
||||
taskByID: st.TaskByID,
|
||||
requeue: st.Requeue,
|
||||
transition: st.Transition,
|
||||
taskByID: st.TaskByID,
|
||||
requeue: st.Requeue,
|
||||
cancelExecution: canceller.CancelExecution,
|
||||
})
|
||||
var err error
|
||||
if action == "approve" {
|
||||
|
||||
@@ -6,55 +6,9 @@ import (
|
||||
"testing"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/forge"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/secret"
|
||||
)
|
||||
|
||||
// TestGatewayWorktreeManagerAdvertisesReviewPR composes the Gateway's own
|
||||
// tree step with the reviewer and the review tool: whatever
|
||||
// buildWorktreeManager produces must be enough for boot.prReviewer to yield a
|
||||
// reviewer and for ReviewTools to advertise review_pr. The call-order
|
||||
// assertion in composition_order_test.go proves the Gateway makes this step;
|
||||
// this proves the step is sufficient, so a manager built without the forge
|
||||
// credential or the configured work dir cannot pass as wired.
|
||||
func TestGatewayWorktreeManagerAdvertisesReviewPR(t *testing.T) {
|
||||
const token = "gateway-forge-token"
|
||||
cfg := config.Config{
|
||||
WorkDir: t.TempDir(),
|
||||
BotUser: "archie-bot",
|
||||
BotEmail: "bot@example.test",
|
||||
Forge: config.Forge{Host: "https://forge.example.test"},
|
||||
}
|
||||
b := &boot{
|
||||
cfg: cfg,
|
||||
cfgHolder: config.NewHolder(cfg),
|
||||
token: token,
|
||||
log: slog.New(slog.DiscardHandler),
|
||||
forgeClient: reviewCapableForge{Forge: forge.NewNoop(slog.New(slog.DiscardHandler))},
|
||||
}
|
||||
|
||||
b.buildWorktreeManager()
|
||||
|
||||
if b.trees.WorkDir != cfg.WorkDir {
|
||||
t.Errorf("worktree manager WorkDir = %q, want the configured %q", b.trees.WorkDir, cfg.WorkDir)
|
||||
}
|
||||
if b.trees.BaseURL != cfg.Forge.Host {
|
||||
t.Errorf("worktree manager BaseURL = %q, want the configured forge host %q", b.trees.BaseURL, cfg.Forge.Host)
|
||||
}
|
||||
if b.trees.Token != token {
|
||||
t.Errorf("worktree manager Token = %q, want the resolved forge token %q", b.trees.Token, token)
|
||||
}
|
||||
|
||||
reviewer := b.prReviewer()
|
||||
if reviewer == nil {
|
||||
t.Fatal("prReviewer() = nil after the Gateway's worktree-manager step; review_pr would never be advertised")
|
||||
}
|
||||
if !hasReviewPRTool(gateway.ReviewTools(reviewer, "archie")) {
|
||||
t.Fatal("review_pr not advertised after the Gateway's worktree-manager step")
|
||||
}
|
||||
}
|
||||
|
||||
// TestBuildTreesAndIdentitiesBuildsRootManagerAndIdentityRunners pins the
|
||||
// daemon's tree composition, which the shared buildWorktreeManager must not
|
||||
// change: the daemon still owns the process-wide manager *and* one runner per
|
||||
|
||||
@@ -6,6 +6,7 @@ import (
|
||||
"time"
|
||||
|
||||
controlpb "github.com/samcharles93/archie-core/internal/contracts/controlplane/v1"
|
||||
"github.com/samcharles93/archie-core/internal/domain/access"
|
||||
"github.com/samcharles93/archie-core/internal/domain/health"
|
||||
"github.com/samcharles93/archie-core/internal/domain/identity"
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
@@ -33,6 +34,12 @@ type deps struct {
|
||||
// Login drives the browser sign-in flow, or nil when no provider is
|
||||
// configured for it.
|
||||
Login identity.LoginFlow
|
||||
// Access evaluates the policy chain; Principals assembles the request
|
||||
// principal; Denials records refusals
|
||||
// (docs/prds/orgs-and-access.md). Wired together or not at all.
|
||||
Access access.Authorizer
|
||||
Principals access.PrincipalSource
|
||||
Denials access.DenialStore
|
||||
}
|
||||
|
||||
// compose builds the dashboard server for the UI process. It sets exactly the
|
||||
@@ -83,6 +90,9 @@ func compose(d deps) *webui.Server {
|
||||
if snapshots, ok := d.Store.(storecontract.ConfigSnapshotStore); ok {
|
||||
srv.ConfigSource = webui.RemoteConfigView(snapshots)
|
||||
}
|
||||
if steps, ok := d.Store.(storecontract.StepReader); ok {
|
||||
srv.Steps = steps
|
||||
}
|
||||
// Channel lifecycle follows the same split as the config view: the process
|
||||
// hosting the channels publishes, this one reads. Withholding it left
|
||||
// /api/channels answering with nothing while channels were running
|
||||
@@ -114,6 +124,11 @@ func compose(d deps) *webui.Server {
|
||||
// rather than opening a path (docs/prds/ui-service-boundary.md). Withholding
|
||||
// it would degrade a page that has an owner, and would leave the dashboard
|
||||
// claiming task logging was not enabled -- see wireTaskLogs.
|
||||
// The policy chain: wired together or not at all
|
||||
// (docs/prds/orgs-and-access.md, "Where it lives").
|
||||
srv.Access = d.Access
|
||||
srv.Principals = d.Principals
|
||||
srv.Denials = d.Denials
|
||||
wireTaskLogs(d, srv)
|
||||
wireCaptureSurfaces(d, srv)
|
||||
return srv
|
||||
|
||||
@@ -171,7 +171,7 @@ func composeUIProcess(t *testing.T) (*webui.Server, int64) {
|
||||
}
|
||||
t.Cleanup(closeClient)
|
||||
|
||||
task, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "a task", "body", "implement", "")
|
||||
task, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "a task", "body", "implement", "", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("seed task: %v", err)
|
||||
}
|
||||
@@ -181,6 +181,6 @@ func composeUIProcess(t *testing.T) (*webui.Server, int64) {
|
||||
Options: options,
|
||||
Log: slog.New(slog.DiscardHandler),
|
||||
Store: client,
|
||||
Health: newReadinessRegistry(options, client, nil),
|
||||
Health: newReadinessRegistry(options, client, nil, nil),
|
||||
}), task.ID
|
||||
}
|
||||
@@ -6,6 +6,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/health"
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
infraaccess "github.com/samcharles93/archie-core/internal/infrastructure/access"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/readiness"
|
||||
)
|
||||
|
||||
@@ -17,8 +18,9 @@ import (
|
||||
//
|
||||
// The component names match the daemon dashboard's, so the readiness view
|
||||
// reads the same whichever process serves it.
|
||||
func newReadinessRegistry(o Options, tasks storecontract.TaskStore, chat messaging.ChatContract) *health.Registry {
|
||||
func newReadinessRegistry(o Options, tasks storecontract.TaskStore, chat messaging.ChatContract, problems []infraaccess.Problem) *health.Registry {
|
||||
return health.NewRegistry(
|
||||
readiness.NewProblemProbe("access_policies", problems),
|
||||
readiness.NewContractProbe("state_db", o.DependencyTimeout, func(ctx context.Context) error {
|
||||
_, err := tasks.StatusCounts(ctx)
|
||||
return err
|
||||
|
||||
@@ -10,11 +10,43 @@ import (
|
||||
"os"
|
||||
"slices"
|
||||
|
||||
"google.golang.org/grpc/codes"
|
||||
"google.golang.org/grpc/status"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/domain/access"
|
||||
infraaccess "github.com/samcharles93/archie-core/internal/infrastructure/access"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/staterpc"
|
||||
"github.com/samcharles93/archie-core/internal/webui"
|
||||
)
|
||||
|
||||
// buildAccessChain loads the stored policies over the wire and builds the
|
||||
// engine. The wire client satisfies the two access contracts the dashboard
|
||||
// needs alongside the engine.
|
||||
// buildAccessChain loads the stored policies over the wire and builds the
|
||||
// engine. A State Store serving no policies has no chain to evaluate: the
|
||||
// dashboard degrades to the credential check rather than refusing to serve,
|
||||
// so an unavailable policy store is a warning, not a boot failure.
|
||||
func buildAccessChain(ctx context.Context, store *staterpc.Client, log *slog.Logger) (access.Authorizer, []infraaccess.Problem, error) {
|
||||
stored, err := store.ListPolicies(ctx)
|
||||
if err != nil {
|
||||
if status.Code(err) == codes.Unavailable {
|
||||
log.Warn("access chain unavailable; the credential check is the gate", "err", err)
|
||||
return nil, nil, nil
|
||||
}
|
||||
return nil, nil, err
|
||||
}
|
||||
engine, err := infraaccess.New(stored)
|
||||
if err != nil {
|
||||
return nil, nil, err
|
||||
}
|
||||
for _, problem := range engine.Problems() {
|
||||
log.Error("stored access policy is invalid and denies its level",
|
||||
"policy", problem.Policy.ID, "level", problem.Policy.Level, "err", problem.Err)
|
||||
}
|
||||
return engine, engine.Problems(), nil
|
||||
}
|
||||
|
||||
// Run serves the dashboard until ctx is cancelled. It resolves its own
|
||||
// options, dials the Gateway and State Store contracts itself, composes the
|
||||
// HTTP surface over them, and unwinds listener then clients in reverse order
|
||||
@@ -44,6 +76,15 @@ func Run(ctx context.Context, options Options) error {
|
||||
}
|
||||
cleanups = append(cleanups, closeGateway)
|
||||
|
||||
chain, problems, err := buildAccessChain(ctx, tasks, log)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
for _, problem := range problems {
|
||||
log.Error("stored access policy is invalid and denies its level",
|
||||
"policy", problem.Policy.ID, "level", problem.Policy.Level, "err", problem.Err)
|
||||
}
|
||||
|
||||
authenticate, err := dashboardAuthenticator(ctx, opts, tasks, log)
|
||||
if err != nil {
|
||||
return err
|
||||
@@ -58,11 +99,14 @@ func Run(ctx context.Context, options Options) error {
|
||||
Log: log,
|
||||
Store: tasks,
|
||||
Chat: chat,
|
||||
Health: newReadinessRegistry(opts, tasks, chat),
|
||||
Health: newReadinessRegistry(opts, tasks, chat, problems),
|
||||
ControlPlane: tasks.ControlPlane(),
|
||||
Identities: tasks,
|
||||
Authenticate: authenticate,
|
||||
Login: login,
|
||||
Access: chain,
|
||||
Principals: tasks,
|
||||
Denials: tasks,
|
||||
})
|
||||
|
||||
// Live activity has no in-process bus in this process: the pump reads
|
||||
|
||||
@@ -20,6 +20,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
"github.com/samcharles93/archie-core/internal/domain/storecontract"
|
||||
"github.com/samcharles93/archie-core/internal/domain/taskactions"
|
||||
"github.com/samcharles93/archie-core/internal/domain/workflow/task"
|
||||
"github.com/samcharles93/archie-core/internal/events"
|
||||
"github.com/samcharles93/archie-core/internal/gateway"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/gatewayrpc"
|
||||
@@ -102,10 +103,15 @@ func serveGRPC(t *testing.T, register func(grpc.ServiceRegistrar)) (target strin
|
||||
func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) {
|
||||
st := pgstore.Open(t)
|
||||
defer st.Close()
|
||||
seeded, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "remote summary", "body", "implement", "")
|
||||
if err != nil {
|
||||
if _, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "remote summary", "body", "implement", "", nil); err != nil {
|
||||
t.Fatalf("seed task: %v", err)
|
||||
}
|
||||
// Claimed (not just enqueued): StartStep guards on the execution's own
|
||||
// current attempt, which a merely-queued task does not have yet.
|
||||
seeded, err := st.ClaimNext(t.Context())
|
||||
if err != nil || seeded == nil {
|
||||
t.Fatalf("claim seeded task: %+v %v", seeded, err)
|
||||
}
|
||||
// The daemon publishes the configuration page's projection; this process
|
||||
// only renders it (archie-core-ymut). The forge host is published too: it
|
||||
// is what the run-detail reads resolve their repository and pull-request
|
||||
@@ -129,9 +135,23 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) {
|
||||
// worker's change capture -- attributed to one attempt, so the assertions
|
||||
// further down read them back through the real client rather than a fake.
|
||||
seedAt := time.Now().UTC()
|
||||
prepareStepID, _, err := st.StartStep(t.Context(), task.StepStart{ExecutionID: seeded.ID, Attempt: 1, Kind: task.StepKindStage, Name: "prepare"})
|
||||
if err != nil {
|
||||
t.Fatalf("seed prepare step: %v", err)
|
||||
}
|
||||
if _, err := st.FinishStep(t.Context(), task.StepFinish{
|
||||
StepID: prepareStepID, ExecutionID: seeded.ID, From: taskstate.StepRunning, To: taskstate.StepSucceeded,
|
||||
}); err != nil {
|
||||
t.Fatalf("finish prepare step: %v", err)
|
||||
}
|
||||
// Terminal, not left running: the attempt rail reads the task's own
|
||||
// record for "is this still happening" (inFlight), and a run still
|
||||
// marked running would report the attempt "running" regardless of its
|
||||
// finished step, rather than the "ok" a completed run's own stages earn.
|
||||
if err := st.Transition(t.Context(), seeded.ID, taskstate.Running, taskstate.Completed, "done"); err != nil {
|
||||
t.Fatalf("complete seeded task: %v", err)
|
||||
}
|
||||
for _, e := range []events.Event{
|
||||
{Kind: events.KindStageStart, TaskID: seeded.ID, Attempt: 1, Stage: "prepare", At: seedAt},
|
||||
{Kind: events.KindStageFinish, TaskID: seeded.ID, Attempt: 1, Stage: "prepare", At: seedAt.Add(time.Second), Data: map[string]any{"duration_ms": 1000}},
|
||||
{Kind: events.KindConfigCaptured, TaskID: seeded.ID, Attempt: 1, At: seedAt, Data: map[string]any{
|
||||
"schema": events.ConfigCapturedSchema, "document": map[string]any{"bot_user": "archie"},
|
||||
}},
|
||||
@@ -150,7 +170,7 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) {
|
||||
|
||||
stateTarget, stopState := serveGRPC(t, func(r grpc.ServiceRegistrar) {
|
||||
eda := pgstore.EDA(t, nil)
|
||||
staterpc.RegisterServer(r, staterpc.Deps{Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, Log: slog.New(slog.DiscardHandler)})
|
||||
staterpc.RegisterServer(r, staterpc.Deps{Tasks: st, Captures: eda, BindingDispatcher: eda, ConfigSnapshots: st, StepReader: st, Log: slog.New(slog.DiscardHandler)})
|
||||
})
|
||||
defer stopState()
|
||||
chat := &fakeChat{sessions: []gateway.SessionContext{
|
||||
@@ -178,7 +198,7 @@ func TestUIServesDashboardAgainstRemoteContracts(t *testing.T) {
|
||||
Log: slog.New(slog.DiscardHandler),
|
||||
Store: stateClient,
|
||||
Chat: chatClient,
|
||||
Health: newReadinessRegistry(options, stateClient, chatClient),
|
||||
Health: newReadinessRegistry(options, stateClient, chatClient, nil),
|
||||
})
|
||||
ts := httptest.NewServer(srv.Handler())
|
||||
defer ts.Close()
|
||||
|
||||
@@ -156,7 +156,7 @@ func composeUIProcessWithLog(t *testing.T) (*webui.Server, int64, int) {
|
||||
st := pgstore.Open(t)
|
||||
t.Cleanup(func() { _ = st.Close() })
|
||||
|
||||
task, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "a task", "body", "implement", "")
|
||||
task, err := st.EnqueueChatTask(t.Context(), "acme", "widget", "a task", "body", "implement", "", nil)
|
||||
if err != nil {
|
||||
t.Fatalf("seed task: %v", err)
|
||||
}
|
||||
@@ -193,7 +193,7 @@ func composeUIProcessWithLog(t *testing.T) (*webui.Server, int64, int) {
|
||||
Options: options,
|
||||
Log: slog.New(slog.DiscardHandler),
|
||||
Store: client,
|
||||
Health: newReadinessRegistry(options, client, nil),
|
||||
Health: newReadinessRegistry(options, client, nil, nil),
|
||||
})
|
||||
return srv, task.ID, task.Attempt
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
package controlplane
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
// AgentProfileKind is the control-plane resource for Kit and image agent
|
||||
// profiles. It exists so a Kit profile applies without a restart
|
||||
// (docs/prds/external-agent-harness.md, "Selection"): [containers].profiles
|
||||
// in config.toml is only its seed, ContainerRuntimePoliciesKind carries every
|
||||
// other container setting and none of this one (config.ContainerConfig.
|
||||
// Profiles is json:"-"), and this resource's own ApplyMode is "live".
|
||||
//
|
||||
// Its document is agentProfile (container_settings.go's snake_case wire
|
||||
// type), not config.AgentProfile directly: that internal type carries no
|
||||
// json tags, so encoding/json would fall back to its Go field names --
|
||||
// "Tools", "Image" -- exactly the defect archie-core-1171 fixed for the rest
|
||||
// of this document family.
|
||||
const AgentProfileKind = "agent-profiles"
|
||||
|
||||
func agentProfileDefinition() Definition {
|
||||
return Definition{
|
||||
Kind: AgentProfileKind,
|
||||
Title: "Agent profiles",
|
||||
ApplyMode: "live",
|
||||
Document: map[string]agentProfile{},
|
||||
Seed: seedAgentProfiles,
|
||||
Validate: validateAgentProfiles,
|
||||
}
|
||||
}
|
||||
|
||||
func seedAgentProfiles(cfg config.Config) any {
|
||||
return agentProfilesDocument(cfg.Containers.Profiles)
|
||||
}
|
||||
|
||||
// agentProfilesDocument maps the internal type to the document's wire type.
|
||||
func agentProfilesDocument(profiles map[string]config.AgentProfile) map[string]agentProfile {
|
||||
if profiles == nil {
|
||||
return nil
|
||||
}
|
||||
out := make(map[string]agentProfile, len(profiles))
|
||||
for name, p := range profiles {
|
||||
out[name] = agentProfile{Image: p.Image, Kit: p.Kit, Adapter: p.Adapter, Tools: p.Tools}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// agentProfilesSettings reverses agentProfilesDocument, for the layering in
|
||||
// runtime_config.go and for validation against config.ValidateAgentProfiles.
|
||||
func agentProfilesSettings(profiles map[string]agentProfile) map[string]config.AgentProfile {
|
||||
if profiles == nil {
|
||||
return nil
|
||||
}
|
||||
out := make(map[string]config.AgentProfile, len(profiles))
|
||||
for name, p := range profiles {
|
||||
out[name] = config.AgentProfile{Image: p.Image, Kit: p.Kit, Adapter: p.Adapter, Tools: p.Tools}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func validateAgentProfiles(input []byte) error {
|
||||
// The rules live in the config package and are shared with the file
|
||||
// document's own validation (config.ContainerConfig.ValidateProfiles):
|
||||
// which profiles are valid cannot differ between the file that seeds
|
||||
// this resource and the resource that replaces it.
|
||||
return validateAs(input, func(profiles map[string]agentProfile) error {
|
||||
return config.ValidateAgentProfiles(agentProfilesSettings(profiles))
|
||||
})
|
||||
}
|
||||
@@ -134,6 +134,33 @@ func (c *Client) WatchWorkflowExecutionSettings(ctx context.Context, afterVersio
|
||||
func(err error) AppliedSettings { return AppliedSettings{Err: err} }), nil
|
||||
}
|
||||
|
||||
// AppliedResource carries a watched resource's version only, without its
|
||||
// document. The kinds applied with it are applied by re-running the whole
|
||||
// layering, which reads every kind back from the store, so the document the
|
||||
// stream carries would be decoded and then thrown away; a stored value this
|
||||
// build cannot read is reported by the layering that refuses it (with
|
||||
// last-known-good kept), not by the watch.
|
||||
type AppliedResource struct {
|
||||
Version int64
|
||||
Err error
|
||||
}
|
||||
|
||||
// WatchResource streams version updates for any resource kind without
|
||||
// decoding the document. It is the shape the runtime-resource watches read
|
||||
// (archie-core-zfb0.1): keepWatch reconnects on it exactly as it does on a
|
||||
// typed stream, and the resume point still moves past a document the client
|
||||
// refused to decode -- the store answered with that version, and resuming
|
||||
// before it would re-offer it on every reconnect.
|
||||
func (c *Client) WatchResource(ctx context.Context, kind string, afterVersion int64) (<-chan AppliedResource, error) {
|
||||
stream, err := c.rpc.Watch(ctx, &pb.WatchRequest{Kind: kind, AfterVersion: afterVersion})
|
||||
if err != nil {
|
||||
return nil, controlplanerpc.ClientError(err)
|
||||
}
|
||||
return watchUpdates(ctx, stream,
|
||||
func(resource *pb.Resource) AppliedResource { return AppliedResource{Version: resource.Version} },
|
||||
func(err error) AppliedResource { return AppliedResource{Err: err} }), nil
|
||||
}
|
||||
|
||||
type AppliedSettings struct {
|
||||
Settings workflow.ExecutionSettings
|
||||
Version int64
|
||||
|
||||
@@ -0,0 +1,148 @@
|
||||
package controlplane
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
"github.com/samcharles93/archie-core/internal/infrastructure/controlplanerpc"
|
||||
)
|
||||
|
||||
// containerRuntimePolicies is the container-runtime-policies resource document.
|
||||
// Its shape IS the contract the Web UI edits, so it is defined here with
|
||||
// explicit snake_case json tags and never handed the internal config.ContainerConfig
|
||||
// directly: that struct's tags belong to the TOML file format, and when it was
|
||||
// the document, encoding/json fell back to its Go field names -- "Image",
|
||||
// "MaxConcurrency", "LegacyEnabled" -- the only Go-cased resource left in the
|
||||
// registry (archie-core-1171). The two durations are config.Duration, which
|
||||
// already writes the string the file accepts; the leak was the keys only.
|
||||
//
|
||||
// Profiles is deliberately not a field here: config.ContainerConfig.Profiles
|
||||
// is json:"-" (its own resource, AgentProfileKind, applies live where the
|
||||
// rest of this one is restart-required -- docs/prds/external-agent-harness.md
|
||||
// "Selection"), so this document never carries it either.
|
||||
type containerRuntimePolicies struct {
|
||||
Image string `json:"image"`
|
||||
MaxConcurrency int `json:"max_concurrency"`
|
||||
MaxUptime config.Duration `json:"max_uptime"`
|
||||
VolumeTTL config.Duration `json:"volume_ttl"`
|
||||
PullPolicy string `json:"pull_policy"`
|
||||
Network string `json:"network"`
|
||||
}
|
||||
|
||||
// agentProfile is one named execution environment as the document writes it.
|
||||
type agentProfile struct {
|
||||
Image string `json:"image,omitempty"`
|
||||
Kit string `json:"kit,omitempty"`
|
||||
Adapter string `json:"adapter,omitempty"`
|
||||
Tools []string `json:"tools,omitempty"`
|
||||
}
|
||||
|
||||
// legacyContainerKeys are the Go field names encoding/json fell back to while
|
||||
// the document was the internal config struct. The decoder's case-insensitive
|
||||
// fallback compares whole keys, so "MaxConcurrency" never matches
|
||||
// "max_concurrency"; every store written before the reshape holds these keys,
|
||||
// so reading them is deliberate and everything else stays strict.
|
||||
var legacyContainerKeys = map[string]string{
|
||||
"Image": "image", "MaxConcurrency": "max_concurrency", "MaxUptime": "max_uptime",
|
||||
"VolumeTTL": "volume_ttl", "PullPolicy": "pull_policy", "Network": "network",
|
||||
}
|
||||
|
||||
// legacyProfileKeys are the same fallback at the profile nesting level.
|
||||
var legacyProfileKeys = map[string]string{
|
||||
"Image": "image", "Kit": "kit", "Adapter": "adapter", "Tools": "tools",
|
||||
}
|
||||
|
||||
func (p *agentProfile) UnmarshalJSON(data []byte) error {
|
||||
type document agentProfile
|
||||
var decoded document
|
||||
err := controlplanerpc.DecodeRenamingLegacyKeys(data, legacyProfileKeys, &decoded)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
*p = agentProfile(decoded)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *containerRuntimePolicies) UnmarshalJSON(data []byte) error {
|
||||
type document containerRuntimePolicies
|
||||
var raw map[string]json.RawMessage
|
||||
if err := json.Unmarshal(data, &raw); err != nil {
|
||||
return err
|
||||
}
|
||||
// "LegacyEnabled" decoded the removed containers.enabled switch during the
|
||||
// window in which this resource existed, and stores written then hold it.
|
||||
// It has no counterpart in the current shape -- it never had a runtime
|
||||
// consumer -- so it is dropped rather than renamed: the strict decode would
|
||||
// otherwise refuse a document every deployment of that window stores.
|
||||
delete(raw, "LegacyEnabled")
|
||||
// "profiles"/"Profiles" carried config.ContainerConfig.Profiles before it
|
||||
// moved to its own resource, AgentProfileKind; a document stored under
|
||||
// either name before that still decodes, with the key simply dropped.
|
||||
delete(raw, "profiles")
|
||||
delete(raw, "Profiles")
|
||||
encoded, err := json.Marshal(raw)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var decoded document
|
||||
if err := controlplanerpc.DecodeRenamingLegacyKeys(encoded, legacyContainerKeys, &decoded); err != nil {
|
||||
return err
|
||||
}
|
||||
*p = containerRuntimePolicies(decoded)
|
||||
return nil
|
||||
}
|
||||
|
||||
// settings maps the document onto the internal config struct the daemon runs.
|
||||
// Profiles is never set here: config.ContainerConfig.Profiles is json:"-",
|
||||
// and AgentProfileKind's own layering step in runtime_config.go is what sets
|
||||
// it, after this one runs.
|
||||
func (p containerRuntimePolicies) settings() config.ContainerConfig {
|
||||
return config.ContainerConfig{
|
||||
Image: p.Image, MaxConcurrency: p.MaxConcurrency, MaxUptime: p.MaxUptime,
|
||||
VolumeTTL: p.VolumeTTL, PullPolicy: p.PullPolicy, Network: p.Network,
|
||||
}
|
||||
}
|
||||
|
||||
func seedContainerPolicies(cfg config.Config) any {
|
||||
containers := cfg.Containers
|
||||
return containerRuntimePolicies{
|
||||
Image: containers.Image, MaxConcurrency: containers.MaxConcurrency, MaxUptime: containers.MaxUptime,
|
||||
VolumeTTL: containers.VolumeTTL, PullPolicy: containers.PullPolicy, Network: containers.Network,
|
||||
}
|
||||
}
|
||||
|
||||
func validateContainers(input []byte) error {
|
||||
return validateAs(input, func(policies containerRuntimePolicies) error {
|
||||
settings := policies.settings()
|
||||
if settings.MaxConcurrency < 0 || settings.MaxUptime < 0 || settings.VolumeTTL < 0 {
|
||||
return fmt.Errorf("container limits must not be negative")
|
||||
}
|
||||
if settings.PullPolicy != "" && settings.PullPolicy != "missing" && settings.PullPolicy != "always" {
|
||||
return fmt.Errorf("pull_policy must be missing or always")
|
||||
}
|
||||
// The image is required for autonomous workflow workers; the same rule
|
||||
// holds for the stored policies that replace the file's [containers].
|
||||
if strings.TrimSpace(settings.Image) == "" {
|
||||
return fmt.Errorf("container image is required for autonomous workflow workers")
|
||||
}
|
||||
// Profiles is json:"-" on config.ContainerConfig: it is
|
||||
// AgentProfileKind's document now, validated there.
|
||||
return nil
|
||||
})
|
||||
}
|
||||
|
||||
// normalizeContainerPolicies canonicalizes the stored document: decoding into
|
||||
// the shape above and re-encoding writes the snake_case keys, dropping the
|
||||
// Go-cased keys an earlier revision stored. A document that still carries them
|
||||
// converges the next time it is written; reads tolerate them meanwhile
|
||||
// (containerRuntimePolicies), so nothing has to be re-saved before it can be
|
||||
// read again.
|
||||
func normalizeContainerPolicies(input []byte) ([]byte, error) {
|
||||
var policies containerRuntimePolicies
|
||||
if err := json.Unmarshal(input, &policies); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return json.Marshal(policies)
|
||||
}
|
||||
@@ -0,0 +1,172 @@
|
||||
package controlplane
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"github.com/samcharles93/archie-core/internal/config"
|
||||
)
|
||||
|
||||
// containerPoliciesDefinition returns the registered definition, so a test that
|
||||
// pins the document's shape also pins its wiring: Seed, Validate and Normalize
|
||||
// are the three functions the registry actually runs.
|
||||
func containerPoliciesDefinition(t *testing.T) Definition {
|
||||
t.Helper()
|
||||
for _, definition := range operationalDefinitions() {
|
||||
if definition.Kind == ContainerRuntimePoliciesKind {
|
||||
return definition
|
||||
}
|
||||
}
|
||||
t.Fatal("container-runtime-policies is not registered")
|
||||
return Definition{}
|
||||
}
|
||||
|
||||
// TestContainerRuntimePoliciesSeedIsTheDocumentShape pins what an operator sees
|
||||
// in the Web UI: snake_case keys and durations they can read, matching every
|
||||
// sibling resource in the registry. The Go-cased keys this replaced are asserted
|
||||
// absent, because the defect was invisible to a test that only compared decoded
|
||||
// values -- encoding/json round-trips the wrong spelling perfectly happily.
|
||||
func TestContainerRuntimePoliciesSeedIsTheDocumentShape(t *testing.T) {
|
||||
cfg := config.Config{Containers: config.ContainerConfig{
|
||||
Image: "archie-agent:test", MaxConcurrency: 4,
|
||||
MaxUptime: config.Duration(2 * time.Hour), VolumeTTL: config.Duration(24 * time.Hour),
|
||||
PullPolicy: "missing", Network: "bridge",
|
||||
}}
|
||||
encoded, err := json.Marshal(containerPoliciesDefinition(t).Seed(cfg))
|
||||
if err != nil {
|
||||
t.Fatalf("marshal seed: %v", err)
|
||||
}
|
||||
var document map[string]any
|
||||
if err := json.Unmarshal(encoded, &document); err != nil {
|
||||
t.Fatalf("unmarshal seed: %v", err)
|
||||
}
|
||||
want := map[string]any{
|
||||
"image": "archie-agent:test", "max_concurrency": float64(4),
|
||||
"max_uptime": "2h0m0s", "volume_ttl": "24h0m0s",
|
||||
"pull_policy": "missing", "network": "bridge",
|
||||
}
|
||||
for key, value := range want {
|
||||
if document[key] != value {
|
||||
t.Errorf("seed %s = %#v, want %#v", key, document[key], value)
|
||||
}
|
||||
}
|
||||
// The Go field names encoding/json fell back to when the document was the
|
||||
// internal config struct.
|
||||
for _, legacy := range []string{"Image", "MaxConcurrency", "MaxUptime", "VolumeTTL", "PullPolicy", "Network"} {
|
||||
if _, present := document[legacy]; present {
|
||||
t.Errorf("seed carries the Go-cased key %q", legacy)
|
||||
}
|
||||
}
|
||||
// Profiles is its own resource (AgentProfileKind, applying live where the
|
||||
// rest of this document is restart-required), so it never appears here at
|
||||
// all, under either casing.
|
||||
if _, present := document["profiles"]; present {
|
||||
t.Error("seed carries profiles: it belongs to AgentProfileKind now")
|
||||
}
|
||||
if _, present := document["Profiles"]; present {
|
||||
t.Error("seed carries Profiles: it belongs to AgentProfileKind now")
|
||||
}
|
||||
}
|
||||
|
||||
// legacyContainerDocument is a document as an earlier revision stored it: the
|
||||
// Go field names encoding/json fell back to while the document was the internal
|
||||
// config struct, LegacyEnabled from the short window in which the removed
|
||||
// containers.enabled switch still decoded, and Profiles from before it moved to
|
||||
// its own resource, AgentProfileKind. Every store written before either reshape
|
||||
// holds a document like this one, so it has to keep working -- Profiles simply
|
||||
// drops, the way LegacyEnabled already does.
|
||||
const legacyContainerDocument = `{"Image":"archie-agent:test","MaxConcurrency":4,"MaxUptime":"2h0m0s","VolumeTTL":"24h0m0s","PullPolicy":"missing","Network":"bridge","LegacyEnabled":false,"Profiles":{"net":{"Image":"proxy:1","Tools":["whois"]}}}`
|
||||
|
||||
// TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape covers the
|
||||
// two halves the change needs: a legacy document still validates and still
|
||||
// reads, and writing it back (Definition.Decode is what every write path runs)
|
||||
// rewrites it into the current shape. The control plane fails closed, so a
|
||||
// shape change without this tolerance stops archied starting on a store that
|
||||
// already holds the old document.
|
||||
func TestContainerRuntimePoliciesReadsADocumentWrittenBeforeTheReshape(t *testing.T) {
|
||||
definition := containerPoliciesDefinition(t)
|
||||
|
||||
if err := definition.Validate([]byte(legacyContainerDocument)); err != nil {
|
||||
t.Fatalf("Validate(legacy) = %v, want it accepted: it is what existing stores hold", err)
|
||||
}
|
||||
|
||||
decoded, err := definition.Decode([]byte(legacyContainerDocument))
|
||||
if err != nil {
|
||||
t.Fatalf("Decode(legacy) = %v", err)
|
||||
}
|
||||
for _, legacy := range []string{`"Image"`, `"MaxConcurrency"`, `"LegacyEnabled"`, `"Profiles"`, `"profiles"`} {
|
||||
if strings.Contains(string(decoded), legacy) {
|
||||
t.Fatalf("decoded document = %s, want the canonical keys without %q", decoded, legacy)
|
||||
}
|
||||
}
|
||||
var document struct {
|
||||
Image string `json:"image"`
|
||||
MaxConcurrency int `json:"max_concurrency"`
|
||||
MaxUptime string `json:"max_uptime"`
|
||||
VolumeTTL string `json:"volume_ttl"`
|
||||
PullPolicy string `json:"pull_policy"`
|
||||
Network string `json:"network"`
|
||||
}
|
||||
if err := json.Unmarshal(decoded, &document); err != nil {
|
||||
t.Fatalf("unmarshal decoded document: %v", err)
|
||||
}
|
||||
if document.Image != "archie-agent:test" || document.MaxConcurrency != 4 ||
|
||||
document.MaxUptime != "2h0m0s" || document.VolumeTTL != "24h0m0s" ||
|
||||
document.PullPolicy != "missing" || document.Network != "bridge" {
|
||||
t.Errorf("document = %+v, want the legacy values preserved in the current shape", document)
|
||||
}
|
||||
}
|
||||
|
||||
// TestContainerRuntimePoliciesKeepsDisallowUnknownFields: the legacy tolerance
|
||||
// renames the keys an existing store holds and nothing else (plus dropping
|
||||
// profiles/Profiles, which no longer belongs to this document at all), because
|
||||
// swallowing any other unknown key decodes as "unset" and an unset image is a
|
||||
// broken worker.
|
||||
func TestContainerRuntimePoliciesKeepsDisallowUnknownFields(t *testing.T) {
|
||||
if err := containerPoliciesDefinition(t).Validate([]byte(`{"image":"archie-agent:test","maxconcurrency":4}`)); err == nil {
|
||||
t.Error("Validate accepted a misspelled key")
|
||||
}
|
||||
}
|
||||
|
||||
// TestContainerRuntimePoliciesLayersLegacyDocuments walks the stored forms to
|
||||
// config.Containers: the snake_case document and the Go-cased one an existing
|
||||
// store holds. Both have to reach the running config, or a deployment's
|
||||
// container policies silently stop applying the next time it boots.
|
||||
func TestContainerRuntimePoliciesLayersLegacyDocuments(t *testing.T) {
|
||||
for _, tt := range []struct {
|
||||
name string
|
||||
stored string
|
||||
}{
|
||||
{
|
||||
name: "the current shape",
|
||||
stored: `{"image":"archie-agent:test","max_concurrency":4,"max_uptime":"2h0m0s","volume_ttl":"24h0m0s","pull_policy":"missing","network":"bridge"}`,
|
||||
},
|
||||
{
|
||||
name: "the Go-cased shape an existing store holds",
|
||||
stored: legacyContainerDocument,
|
||||
},
|
||||
} {
|
||||
t.Run(tt.name, func(t *testing.T) {
|
||||
client := NewRPCClient(&runtimeConfigClient{values: map[string]any{
|
||||
SchedulingPolicyKind: map[string]any{"poll_interval": "2m", "dispatch": map[string]any{"trigger": "assignee"}},
|
||||
ContainerRuntimePoliciesKind: json.RawMessage(tt.stored),
|
||||
}})
|
||||
got, _, err := client.RuntimeConfig(t.Context(), config.Config{})
|
||||
if err != nil {
|
||||
t.Fatalf("RuntimeConfig: %v", err)
|
||||
}
|
||||
if got.Containers.Image != "archie-agent:test" || got.Containers.MaxConcurrency != 4 ||
|
||||
got.Containers.MaxUptime != config.Duration(2*time.Hour) || got.Containers.Network != "bridge" {
|
||||
t.Fatalf("Containers = %+v, want the stored document applied", got.Containers)
|
||||
}
|
||||
// Profiles is AgentProfileKind's document now, not this one's; this
|
||||
// resource carries none, under either casing, so it never reaches
|
||||
// out.Containers.Profiles.
|
||||
if len(got.Containers.Profiles) != 0 {
|
||||
t.Fatalf("Profiles = %+v, want none: container-runtime-policies carries no profiles", got.Containers.Profiles)
|
||||
}
|
||||
})
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,78 @@
|
||||
package controlplane
|
||||
|
||||
import "github.com/samcharles93/archie-core/internal/config"
|
||||
|
||||
// CredentialBindingsKind is the control-plane resource mapping a Kit
|
||||
// credential@1 service name to an org secret
|
||||
// (docs/prds/external-agent-harness.md, Credentials; docs/prds/orgs-and-access.md).
|
||||
// It exists so a binding applies without a restart, the same reason
|
||||
// AgentProfileKind is its own resource: [containers].credentials in
|
||||
// config.toml is only its seed, and kitrun.Launcher reads the live
|
||||
// control-plane document on every launch, never a value captured at boot.
|
||||
const CredentialBindingsKind = "credential-bindings"
|
||||
|
||||
// credentialBinding is one config.CredentialBinding as the document writes
|
||||
// it: explicit snake_case json tags, following channel_settings.go /
|
||||
// container_settings.go's precedent, never the internal config struct
|
||||
// (which has no json tags and would fall back to Go field names).
|
||||
type credentialBinding struct {
|
||||
Service string `json:"service"`
|
||||
Org string `json:"org,omitempty"`
|
||||
Secret credentialValue `json:"secret"`
|
||||
}
|
||||
|
||||
// credentialValue is config.SecretRef as this document writes it.
|
||||
type credentialValue struct {
|
||||
Engine string `json:"engine,omitempty"`
|
||||
Key string `json:"key,omitempty"`
|
||||
}
|
||||
|
||||
func credentialBindingsDefinition() Definition {
|
||||
return Definition{
|
||||
Kind: CredentialBindingsKind,
|
||||
Title: "Credential bindings",
|
||||
ApplyMode: "live",
|
||||
Document: []credentialBinding{},
|
||||
Seed: seedCredentialBindings,
|
||||
Validate: validateCredentialBindings,
|
||||
}
|
||||
}
|
||||
|
||||
func seedCredentialBindings(cfg config.Config) any {
|
||||
return credentialBindingsDocument(cfg.Containers.Credentials)
|
||||
}
|
||||
|
||||
func credentialBindingsDocument(bindings []config.CredentialBinding) []credentialBinding {
|
||||
if bindings == nil {
|
||||
return nil
|
||||
}
|
||||
out := make([]credentialBinding, len(bindings))
|
||||
for i, b := range bindings {
|
||||
out[i] = credentialBinding{Service: b.Service, Org: b.Org, Secret: credentialValue{Engine: b.Secret.Engine, Key: b.Secret.Key}}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// credentialBindingsSettings reverses credentialBindingsDocument, for the
|
||||
// layering in runtime_config.go and for validation against
|
||||
// config.ContainerConfig.ValidateCredentialBindings.
|
||||
func credentialBindingsSettings(bindings []credentialBinding) []config.CredentialBinding {
|
||||
if bindings == nil {
|
||||
return nil
|
||||
}
|
||||
out := make([]config.CredentialBinding, len(bindings))
|
||||
for i, b := range bindings {
|
||||
out[i] = config.CredentialBinding{Service: b.Service, Org: b.Org, Secret: config.SecretRef{Engine: b.Secret.Engine, Key: b.Secret.Key}}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func validateCredentialBindings(input []byte) error {
|
||||
// The rules live in the config package and are shared with the file
|
||||
// document's own validation (config.ContainerConfig.ValidateCredentialBindings):
|
||||
// which bindings are valid cannot differ between the file that seeds this
|
||||
// resource and the resource that replaces it.
|
||||
return validateAs(input, func(bindings []credentialBinding) error {
|
||||
return config.ContainerConfig{Credentials: credentialBindingsSettings(bindings)}.ValidateCredentialBindings()
|
||||
})
|
||||
}
|
||||
@@ -8,7 +8,7 @@ import (
|
||||
// Schemas are not declared here: each Definition names its document type, and
|
||||
// Definition.Descriptor derives the JSON Schema from it (internal/app/controlplane/schema.go).
|
||||
func builtinDefinitions(steps workflow.StepRegistry) []Definition {
|
||||
definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition()}
|
||||
definitions := []Definition{workflowDefinition(), workflowDefinitionsDefinition(steps), personaDefinition(), scheduleDefinition(), agentProfileDefinition(), credentialBindingsDefinition()}
|
||||
definitions = append(definitions, modelDefinitions()...)
|
||||
definitions = append(definitions, operationalDefinitions()...)
|
||||
return definitions
|
||||
|
||||
Loaded 100 of 332 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user