jason.woltje
073bbfdb6a
Investigation (pi 0.84.4 docs + host auth.json metadata, values never read): provider stacking is native (one auth.json keyed by provider; resolution --api-key > auth.json > env > models.json; OAuth auto-refresh). Multi-account per provider is NOT native -> named-file design: auth.<account>.json + per-launch injection. - scripts/auth.sh: status (provider names, credential types, perms, env-side names informational — never credential material) and accounts (named files, active marker). Exit codes per convention: 3 missing for a read, 2 unparseable, 4 file/environment (symlinks refuse). - scripts/agent.sh --auth <account>: resolves auth.<account>.json and exports PI_AUTH_FILE (the existing compose read-only mount source — no new plumbing); missing/invalid account refuses pre-container. - scripts/test-auth.sh: 13 no-Docker cases; core assertion is the safety property itself — fixture key/token/env VALUES never reach output. - Docs: TOOLS.md Auth section, AGENTS.md command surface + suites. Headless task runs keep the default credential (worker auth selection is a separate policy decision). Real-host smoke: anthropic/openai-codex oauth + zai api_key reported, perms 600, no named accounts yet. Suites 24/90/14/17/13 + verify green. Agreed sequence M16-M19 complete; M20 owner-gated.
116 lines
5.8 KiB
Markdown
116 lines
5.8 KiB
Markdown
# AGENTS.md — Mosaic Stack rebuild (`mosaicstack/stack-v2`)
|
|
|
|
Operational context for any agent session working in this repository.
|
|
Read top to bottom; it is deliberately short — depth lives in the files it
|
|
points to, not here.
|
|
|
|
## What this repository is
|
|
|
|
A standalone rebuild of Mosaic Stack: a file-based, fail-closed
|
|
orchestration foundation that dispatches sandboxed headless pi workers to do
|
|
real work, with immutable run records as evidence. Thirteen-plus tagged
|
|
milestones (`git tag -l`) from `poc-container-hello-v0` to today; suites
|
|
green at every step. Not production software — a proven foundation.
|
|
|
|
## Non-negotiable invariants (the canon)
|
|
|
|
1. **Root is bootstrap-only.** First-class system configuration lives at the
|
|
repository root; everything else gets a dedicated directory (`roles/`,
|
|
`contracts/`, `missions/`, `tasks/`, `docs/`). Do not add new files to root.
|
|
2. **Configuration**: `~/.config/mosaic-dev/config.json` is the sole system
|
|
config — created only by `scripts/bootstrap.sh`, never overwritten,
|
|
fail-closed on any problem. Repo-scoped role authority lives in
|
|
`roles/*.json` (versioned, reviewed commits only).
|
|
3. **Secrets** never enter the repository or container images; auth is
|
|
runtime-only (read-only mount or environment variable).
|
|
4. **Contracts** (`contracts/`) are immutable and image-baked. Missions and
|
|
tasks are declarative JSON with strict schemas.
|
|
5. **Run records** under `<dataRoot>/runs/` are write-once evidence — never
|
|
rewritten, only pruned via `prune` with a receipt.
|
|
6. **Fail closed**: missing or invalid config/policy refuses the operation.
|
|
Never improvise around a refusal; diagnose it.
|
|
7. **Policy**: missions govern tasks (least-privilege intersection — a task
|
|
narrows, never widens). Role authority is declared in `roles/` and changes
|
|
only via reviewed commits.
|
|
8. **Git**: commit only after suites are green; push only `main`; never
|
|
force-push. `scripts/conductor-apply.sh` commits locally — push stays an
|
|
explicit act.
|
|
9. **Append-only logs**: BUILD-LOG.md (phases), `activation-log.jsonl`,
|
|
`.pruned.log`, docs/SESSIONS.md. Corrections are new entries, never edits.
|
|
|
|
## Session protocol (mandatory)
|
|
|
|
- **Register** your session in `docs/SESSIONS.md` — one append-only line
|
|
(date, actor, scope, outcome). Never rewrite or remove entries.
|
|
- **Cadence**: read `docs/plans/CURRENT.md` → execute its single next action
|
|
fully (implement → test → verify against acceptance criteria → commit →
|
|
push → close issue) → update CURRENT.md → register in SESSIONS.md.
|
|
- "next" means one action. A batch mandate ("run the queue") repeats the
|
|
loop until green or blocked. Blocked means stop and report, never improvise.
|
|
- Substantial work gets a Gitea issue and a BUILD-LOG phase entry
|
|
(before/after, with corrections recorded honestly).
|
|
|
|
## Role model
|
|
|
|
- **Conductor**: a system-scoped role — not an agent, not a daemon. Holds
|
|
git/credentials/policy authority; decomposes, dispatches, reviews,
|
|
verifies, integrates. Protocol: `docs/plans/CONDUCTOR.md`. Exists only
|
|
when invoked; push is never automatic.
|
|
- **Workers**: headless pi via `scripts/run-task.sh` — sandboxed workspace,
|
|
tools allowlist, optional persistent sessions and forks; no git, no
|
|
credentials, no policy control.
|
|
- Worker runs deliberately exclude this file (`--no-context-files` in the
|
|
adapter): worker context is contracts + mission via the generated system
|
|
prompt. This file is for conductor-level sessions.
|
|
|
|
## Command surface
|
|
|
|
`scripts/bootstrap.sh` (idempotent) · `build.sh` · `hello.sh` ·
|
|
`verify.sh` · `run-task.sh run <task.json>` · `release.sh
|
|
package|activate|rollback|status` · `auth.sh status|accounts` · `reset.sh` (**danger**: wipes the data
|
|
root; triple-safety-checked) · `mosaic-task.mjs validate|run|show|list|retry|prune|resolve-role` ·
|
|
`agent.sh <name>` (interactive TUI agent) ·
|
|
suites: `test-config.sh`, `test-task.sh`, `test-release.sh`,
|
|
`test-conductor.sh`, `test-auth.sh`.
|
|
|
|
Full reference — usage, fields, exit codes, safety notes:
|
|
`docs/TOOLS.md` (read on demand; do not rely on this summary for detail).
|
|
|
|
## Data map (canon)
|
|
|
|
- `~/.config/mosaic-dev/config.json` — system config (user-authored; never
|
|
auto-written).
|
|
- `<dataRoot>` (from config; default `~/.mosaic-dev`):
|
|
- `runs/` — write-once run evidence (`result.json`, snapshots, `stderr.txt`)
|
|
- `sessions/` — pi JSONL session trees, one directory per named session
|
|
- `workspaces/` — agent file effects (persistent or `:run` ephemeral)
|
|
- `state/` — release pointer + append-only activation/auto-apply logs
|
|
- Ownership is per-directory; nothing shares state. Directory map and
|
|
lifecycle rules: README.md "Data map" section.
|
|
|
|
## Pointers (depth lives here)
|
|
|
|
- `docs/plans/CURRENT.md` — THE next action (single source of "what now")
|
|
- `docs/plans/ROADMAP.md` — agreed milestone path (M16+)
|
|
- `docs/plans/CONDUCTOR.md` — orchestration protocol and guardrails
|
|
- `docs/plans/2026-09-02_atomic-mosaic-foundation.md` — architecture, invariants
|
|
- `docs/plans/2026-09-03_autonomous-run.md` — batch-run tracker
|
|
- `BUILD-LOG.md` — append-only build/verification history with corrections
|
|
- `LAYERS.md` — implemented vs deferred layers
|
|
- `docs/SESSIONS.md` — session registry
|
|
- `adapters/README.md` — the harness adapter contract
|
|
- `roles/` — role contracts (conductor, future agent/coder/reviewer)
|
|
|
|
## Recovery rule
|
|
|
|
Compacted, restarted, or new? Nothing that matters is lost: this file +
|
|
`docs/plans/CURRENT.md` + `git log --oneline -10` + the suites reconstruct
|
|
the full state. **Never guess** — verify with the suites; the run records
|
|
and logs hold the receipts.
|
|
|
|
## Version pin
|
|
|
|
`@earendil-works/pi-coding-agent` is pinned exactly (see `package.json` /
|
|
`RELEASE`); never install unversioned. Release identity: `RELEASE` file
|
|
(0.0.X until declared stable); image tags derive from it.
|