Add Nisse build specification
Seeds nisse-core as the home for system-level design documentation. The spec covers the shared library (Part A), both agents (Parts B and C), and the supporting services, build order, and open decisions. nisse-core holds this because the document describes the shared design rather than either agent's implementation; the repo gains code later, at the extraction step in the build order. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
dongarandClaude Opus 5 committed
commit
be04c28542
1 file changed
+802
@@ -0,0 +1,802 @@
|
|||||||
|
# Nisse — Build Specification
|
||||||
|
|
||||||
|
A build-oriented spec for two self-hosted AI agents sharing a common library. This
|
||||||
|
document states **requirements per component** so major pieces can be broken out and
|
||||||
|
built independently. It is deliberately lighter on the supporting services (Matrix,
|
||||||
|
Gitea, Vikunja, Outline, LiteLLM) and heaviest on the **agent library** and the
|
||||||
|
**two agents**, which is where the real design work lives.
|
||||||
|
|
||||||
|
For deeper rationale behind any decision here, see the companion `Architecture.md`.
|
||||||
|
|
||||||
|
**Document history.** The Tiered Inference amendment has been folded into this
|
||||||
|
document and no longer exists separately: its A-series components appear as A10–A16,
|
||||||
|
its network and credential revisions in A5 and B3, and its revised build order as
|
||||||
|
Part G. The inference-hardware question it raised has since been resolved in
|
||||||
|
principle (Part H: a 4090-class host).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. Naming
|
||||||
|
|
||||||
|
The project is **Nisse**, after the Nordic farm spirit that keeps the place running
|
||||||
|
overnight and expects to be treated well in return. Three artifacts:
|
||||||
|
|
||||||
|
| Artifact | Name | Role |
|
||||||
|
|---|---|---|
|
||||||
|
| Shared library | `nisse-core` | The spine both agents sit on (Part A) |
|
||||||
|
| Dev Agent | `nisse-dev` | Plans and implements software projects (Part B) |
|
||||||
|
| Sysadmin Agent | `nisse-ops` | Operates infrastructure (Part C) |
|
||||||
|
|
||||||
|
Throughout this document, **Dev Agent** and **Sysadmin Agent** name the *roles* in
|
||||||
|
conceptual discussion; `nisse-dev` and `nisse-ops` name the *artifacts* — repos,
|
||||||
|
container images, VM hostnames, Matrix identities, and service accounts. Use the
|
||||||
|
same string across all of those: the VM, the container, the Caddy host, the Matrix
|
||||||
|
account, and the Bitwarden machine account for a given agent all share one name, so
|
||||||
|
that grepping the infrastructure for `nisse-ops` finds everything.
|
||||||
|
|
||||||
|
Published under a personal GitHub account rather than an org; `github.com/nisse` is
|
||||||
|
squatted and GitHub does not reclaim inactive usernames. The repo names carry the
|
||||||
|
identity. `nisse-core` is free on PyPI if packages are ever published.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0.1 What We're Building
|
||||||
|
|
||||||
|
Two agents:
|
||||||
|
|
||||||
|
1. **Dev Agent** — `nisse-dev` (build first) — plans and implements software
|
||||||
|
projects, produces Gitea PRs for human review, reacts to review comments and
|
||||||
|
commits.
|
||||||
|
2. **Sysadmin Agent** — `nisse-ops` (follow-on) — operates and maintains
|
||||||
|
infrastructure, driven by tickets, gated on high-consequence actions.
|
||||||
|
|
||||||
|
Both are thin applications over a shared **`nisse-core`** library. The library is
|
||||||
|
*extracted from the Dev Agent after it works* — not designed up front for two
|
||||||
|
consumers that don't exist yet. Build the Dev Agent as if the library were internal,
|
||||||
|
then lift the seams that proved real.
|
||||||
|
|
||||||
|
Whether the three artifacts live in one repository or three is **an open decision**
|
||||||
|
(Part H). It changes what the extraction step in the build order concretely means.
|
||||||
|
|
||||||
|
### Guiding principles (apply to everything below)
|
||||||
|
|
||||||
|
- **Human-gated autonomy.** Agents work independently once told to start, but never
|
||||||
|
cross key boundaries (start implementation, apply infrastructure change) without
|
||||||
|
explicit sign-off.
|
||||||
|
- **No per-command approval.** Within an approved unit of work, execution is
|
||||||
|
unattended. Control lives at the *boundaries*, not per action.
|
||||||
|
- **Isolation matched to blast radius.** Dev Agent is disposable and sealed; Sysadmin
|
||||||
|
Agent is trusted with live-infrastructure reach. They never share a running
|
||||||
|
instance.
|
||||||
|
- **Stateless image, stateful volumes.** Containers are replaceable; durable state
|
||||||
|
lives on named volumes and must survive both redeploys and unexpected reboots.
|
||||||
|
- **Structured channels for machines, prose channels for humans.** Never route
|
||||||
|
machine event intake through human-facing formatters (chat bridges).
|
||||||
|
- **Own the stack.** Everything self-hostable stays inside the network where practical.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART A — THE AGENT LIBRARY (`nisse-core`)
|
||||||
|
|
||||||
|
The shared spine. Every component here is consumed by both agents. This is the part
|
||||||
|
to get right.
|
||||||
|
|
||||||
|
### A1. Transport
|
||||||
|
|
||||||
|
**Purpose:** all human⇄agent conversation — commands in, questions/approvals/updates
|
||||||
|
out.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- A `Transport` interface the orchestrator depends on; **no platform SDK imported
|
||||||
|
directly** anywhere else. Methods (at least): `send_message`,
|
||||||
|
`send_approval_request`, `ask_question`, `on_message` (inbound callback/stream).
|
||||||
|
- **`MatrixTransport`** is the first and primary implementation. Self-hosted
|
||||||
|
homeserver (Synapse or Conduit) keeps the control plane in-network. Must support
|
||||||
|
threaded conversations (for plan discussion) and per-agent identities.
|
||||||
|
- Interface must make adding `TelegramTransport` / `SlackTransport` later a matter of
|
||||||
|
one new class + config, no orchestrator changes.
|
||||||
|
- Both agents run as **distinct identities** (`@nisse-dev`, `@nisse-ops`) in separate
|
||||||
|
rooms on the same homeserver.
|
||||||
|
|
||||||
|
Explicitly *not* required: rich message formatting, custom clients. Existing Matrix
|
||||||
|
clients (Element) are the UI.
|
||||||
|
|
||||||
|
**Matrix is strictly a UI channel.** Although the homeserver is self-hosted and
|
||||||
|
therefore not "remote," room history must not become load-bearing context. The
|
||||||
|
canonical log (A10) is the sole source of truth.
|
||||||
|
|
||||||
|
### A2. State Store and Durability *(critical path — build first)*
|
||||||
|
|
||||||
|
**Purpose:** durable, crash-safe persistence of everything that must outlive a
|
||||||
|
process restart. This is what makes the whole system safe to redeploy and reboot; it
|
||||||
|
blocks everything else.
|
||||||
|
|
||||||
|
Must persist: active project/task, per-project state-machine position, approvals
|
||||||
|
granted, pending questions, session continuity, (dev) git clone locations.
|
||||||
|
|
||||||
|
Disposable (never on the state volume): agent code, build artifacts/test containers,
|
||||||
|
shipped-out logs.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- **Crash-atomic writes.** SQLite in **WAL mode** (default choice) or atomic
|
||||||
|
file writes (`write-temp → fsync → rename`). A power cut mid-write must never
|
||||||
|
produce torn state.
|
||||||
|
- **Checkpoint after every state transition**, with `fsync`. No "flush later" —
|
||||||
|
in-memory state that hasn't hit disk is assumed lost.
|
||||||
|
- **Durable intent log.** Before a unit of work starts, record intent, so a restart
|
||||||
|
knows what was in flight.
|
||||||
|
- **Idempotent transitions reconciled against external truth.** On any operation with
|
||||||
|
an external side effect (open PR, push branch), restart must detect the effect
|
||||||
|
already happened (query Gitea/git) rather than repeat it.
|
||||||
|
- **`schema_version`** field from the first commit, with a migration hook, so a newer
|
||||||
|
image can read older state.
|
||||||
|
|
||||||
|
### A3. Boot-Time Reconciliation
|
||||||
|
|
||||||
|
**Purpose:** turn an ambiguous crash into a safe, known state.
|
||||||
|
|
||||||
|
Every startup (clean or post-crash), before accepting operator commands:
|
||||||
|
1. Open state store (WAL recovery is automatic).
|
||||||
|
2. Run any pending schema migration.
|
||||||
|
3. Read intent log; look for a transition that began but never committed.
|
||||||
|
4. Reconcile against external truth (Gitea/git for the dev agent; relevant services
|
||||||
|
for the sysadmin agent).
|
||||||
|
5. **Interrupted mid-delegation (A13) — apply the deterministic resume rule.**
|
||||||
|
**Auto-resume** the delegation — re-render its transcript from the canonical log
|
||||||
|
and continue the loop, posting a notice (not a question) to transport — when the
|
||||||
|
cut is clean: the last durable event is a completed `tool_result` or assistant
|
||||||
|
turn, the delegation branch sits at the expected commit, no cap is breached, and
|
||||||
|
external truth matches the log. **Gate to `AWAIT_INPUT`** when the last event is a
|
||||||
|
`tool_call` with no recorded result whose effect cannot be verified by inspection
|
||||||
|
(tree diff for edits, Gitea query for pushes), or on any branch/log mismatch. The
|
||||||
|
judgment is an observable check, never model self-assessment — the same reasoning
|
||||||
|
as A12.
|
||||||
|
6. Any other interruption → move to **`AWAIT_INPUT`** and post to transport
|
||||||
|
(e.g. "restarted mid-milestone-2, branch at commit abc123, continue or re-plan?").
|
||||||
|
Never blind-resume.
|
||||||
|
7. Otherwise resume the last committed state.
|
||||||
|
|
||||||
|
### A4. Control Loop, State Machine, and Gating Primitives
|
||||||
|
|
||||||
|
**Purpose:** the generic engine that drives an agent through gated work. Each agent
|
||||||
|
supplies its own concrete states; the primitives are shared.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- A **state machine** framework: named states, transitions, and human gates. Each
|
||||||
|
gate blocks until an explicit operator action arrives via transport.
|
||||||
|
- **Gating is structural, not advisory.** The mechanism (used by both agents):
|
||||||
|
- Expose a **`submit_plan(type, content)`** tool to the model. Calling it posts the
|
||||||
|
plan for approval and **ends the agent's turn.** The agent cannot self-advance.
|
||||||
|
- Expose an **`ask_human(question)`** tool — non-terminal: pause, post question,
|
||||||
|
block until answered, resume.
|
||||||
|
- **Do not** expose any "proceed" / "start" tool. Advancement past a gate happens
|
||||||
|
only when the orchestrator receives operator approval and hands over the next
|
||||||
|
task. The agent has no path to approve itself.
|
||||||
|
- **Approval sources.** A gate waits on an approval event from any registered
|
||||||
|
**`ApprovalSource`** — the Matrix transport (A1), the Gitea comment poller (B2), or
|
||||||
|
the Vikunja comment stream (C4). First valid approval wins and is consumed; the
|
||||||
|
gate records which channel satisfied it, and the orchestrator echoes the outcome to
|
||||||
|
the other channels so the records converge. Each source authenticates the approver
|
||||||
|
against a per-channel operator allowlist (Matrix MXID, Gitea username, Vikunja
|
||||||
|
username).
|
||||||
|
- **Approvals bind to a plan revision, never to "the current gate."** Every submitted
|
||||||
|
plan revision carries a monotonically-increasing tag (`rev-N`). An approval naming
|
||||||
|
a stale revision is rejected with a notice, never applied to a newer one — this is
|
||||||
|
what makes multi-channel approval race-free.
|
||||||
|
- **One consistent approval UI across all channels.** Approval is always the typed
|
||||||
|
word `approve`, attached to a specific revision: in Matrix, a reply to the plan
|
||||||
|
message (the reply relation carries the binding; a bare `approve` in the room binds
|
||||||
|
to the latest revision only when unambiguous, otherwise the agent asks); in Gitea
|
||||||
|
and Vikunja, a comment `approve rev-N`, with the tag printed in the plan comment
|
||||||
|
for copy-paste. Any other reply/comment is `reject <feedback>`. Reactions/emoji are
|
||||||
|
never an approval path. Approvals are consumed at first sight; later edits to an
|
||||||
|
approval comment are ignored and logged.
|
||||||
|
- **Autonomy inside an approved unit of work:** all tool/command use auto-approved
|
||||||
|
(Claude Agent SDK `bypassPermissions` or an allow-all `canUseTool`). Escalation to
|
||||||
|
the human happens *only* via `ask_human`.
|
||||||
|
- The loop must survive restart mid-work (relies on A2/A3).
|
||||||
|
|
||||||
|
### A5. LLM Access *(tiered)*
|
||||||
|
|
||||||
|
**Purpose:** reach both a locally-hosted model and frontier models through one
|
||||||
|
interface, with the frontier vendor swappable by config.
|
||||||
|
|
||||||
|
A locally-hosted model drives the control loop and performs mechanical work; frontier
|
||||||
|
models are engaged for work that exceeds local capability. Two requirements drive the
|
||||||
|
tiering:
|
||||||
|
|
||||||
|
1. **No remotely-held state.** Conversation and task state lives on the agent VM. No
|
||||||
|
provider holds anything the system depends on to resume.
|
||||||
|
2. **Vendor fluidity.** The frontier tier should be swappable — Anthropic, OpenAI,
|
||||||
|
Google, or a vendor that does not exist yet — as a configuration change, not a
|
||||||
|
refactor.
|
||||||
|
|
||||||
|
These two are only in tension if portability is required *within* a session. Making
|
||||||
|
frontier engagements **ephemeral and self-contained** (A13) allows vendor-specific
|
||||||
|
session data to be used freely inside a delegation while keeping the durable record
|
||||||
|
vendor-neutral.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- **One client interface**, `complete(canonical_log, tools, model) -> canonical_events`,
|
||||||
|
present at the **first real LLM call** — not introduced as a later cutover. The same
|
||||||
|
reasoning that produced the `Transport` abstraction.
|
||||||
|
- **LiteLLM in front of everything, from the start.** The agent VM gets exactly one
|
||||||
|
LLM destination; LiteLLM fans out to the local inference host and to frontier
|
||||||
|
vendors behind it. This also resolves the RFC1918 conflict in B3 — a LAN-resident
|
||||||
|
inference host would otherwise need a second hole punched in the egress allowlist.
|
||||||
|
- **Passthrough for the vendor driving a given session** (`/v1/messages` for
|
||||||
|
Anthropic), so vendor-specific features are not lost on the path where they matter —
|
||||||
|
delegations (A13) always take this path. **Normalized routing for everything else**;
|
||||||
|
the canonical log (A10) reconciles the difference.
|
||||||
|
- **Fallback chains configured at LiteLLM.** Rate limits and outages differ per
|
||||||
|
vendor; a frontier failure should not kill a task.
|
||||||
|
- **No vendor credentials on the agent VM.** LiteLLM holds every key, sourced from
|
||||||
|
Bitwarden machine accounts (A7); the agent holds one LiteLLM token. Adding a vendor
|
||||||
|
does not touch the agent VM, and a compromised agent leaks no provider keys.
|
||||||
|
- Config from env/`.env`, **nothing hardcoded**: base URL, auth token, and the role
|
||||||
|
mapping (A11). Changing any of it is an env change + restart, nothing more.
|
||||||
|
- **Budget caps and spend alerts live on the LiteLLM virtual key**, not in agent code.
|
||||||
|
|
||||||
|
### A6. Browser Tool
|
||||||
|
|
||||||
|
**Purpose:** drive web UIs. Shared implementation; each agent points it at a
|
||||||
|
different network with different trust.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- **Playwright** (headless Chromium), exposed to the model as tool actions:
|
||||||
|
navigate, click, type, read DOM, screenshot. Screenshot + accessibility-tree loop
|
||||||
|
so the model can operate UIs it wasn't trained on.
|
||||||
|
- Runs **inside the agent's VM**. Network reachability is set by the agent's
|
||||||
|
deployment, not the tool.
|
||||||
|
- Must support authenticated sessions (for the sysadmin agent's admin UIs) while
|
||||||
|
being usable without auth (dev agent's test apps).
|
||||||
|
|
||||||
|
### A7. Secrets Client
|
||||||
|
|
||||||
|
**Purpose:** fetch credentials at runtime instead of baking them into images.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- Client for **Bitwarden/Vaultwarden** via **machine account / Secrets Manager** (or
|
||||||
|
`bw` CLI + API key). Not the personal vault.
|
||||||
|
- Reads only from a **dedicated, minimally-scoped machine account** per agent.
|
||||||
|
- A single **bootstrap token** (the machine-account credential) is the one secret
|
||||||
|
that lives on the box: tight file perms, never in image or repo.
|
||||||
|
- (Deferred, not first cut: dynamic/short-lived secrets via Vault/OpenBao. Leave the
|
||||||
|
interface able to grow toward this; don't build it yet.)
|
||||||
|
|
||||||
|
### A8. SSO Identity
|
||||||
|
|
||||||
|
**Purpose:** each agent authenticates as itself.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- Each agent is a dedicated **LLDAP** principal (`svc-nisse-dev`, `svc-nisse-ops`) in
|
||||||
|
a tightly-scoped **Authelia** group. Never the operator's account.
|
||||||
|
- Support an **unattended-auth path**: because interactive MFA is impossible for a
|
||||||
|
headless agent, allow a narrow **IP-scoped, group-scoped, target-scoped**
|
||||||
|
single-factor exception. Keep it specific on all three axes.
|
||||||
|
|
||||||
|
### A9. Logging
|
||||||
|
|
||||||
|
**Purpose:** observability without bloating state.
|
||||||
|
|
||||||
|
Requirements: structured logs to journald / external log stack, **not** kept
|
||||||
|
in-container. Every gate crossing, tool call, and escalation is logged.
|
||||||
|
|
||||||
|
### A10. Canonical Transcript Schema
|
||||||
|
|
||||||
|
The durable record is a **canonical event log** in SQLite, not a provider-shaped
|
||||||
|
`messages` array. Provider request bodies are rendered at call time from this log.
|
||||||
|
|
||||||
|
| Event | Payload |
|
||||||
|
|---|---|
|
||||||
|
| `user_message` | text, source (Matrix event ID) |
|
||||||
|
| `assistant_text` | text, model that produced it |
|
||||||
|
| `tool_call` | canonical call ID, tool name, arguments |
|
||||||
|
| `tool_result` | canonical call ID, result, success/failure |
|
||||||
|
| `plan_submitted` | plan body, authoring model |
|
||||||
|
| `gate_opened` | gate type, reason |
|
||||||
|
| `delegation_started` | brief, target role, resolved model, caps |
|
||||||
|
| `delegation_completed` | handback note, artifacts, tokens, duration, exit status |
|
||||||
|
| `compaction` | summary, producing model, range of events replaced |
|
||||||
|
|
||||||
|
Rules:
|
||||||
|
- **Canonical tool-call IDs are minted locally.** Provider IDs are mapped at the
|
||||||
|
boundary and never used as a join key. Providers differ in both ID format and in
|
||||||
|
where tool calls sit structurally (content blocks vs. a separate array on the
|
||||||
|
assistant message).
|
||||||
|
- **No provider-side handles for content.** If a Files API is used, store the bytes or
|
||||||
|
a content-addressed local path; upload or inline at render time. A provider file ID
|
||||||
|
must never be the only reference to something.
|
||||||
|
- **Vendor-opaque reasoning artifacts are stored, tagged with the producing model, and
|
||||||
|
never replayed outside the session that produced them.** This covers Anthropic
|
||||||
|
signed thinking blocks, OpenAI encrypted reasoning items, and Gemini thought
|
||||||
|
signatures. Inside a delegation, replay per that vendor's rules. On delegation exit,
|
||||||
|
the artifacts become archival only. A "session" here is the **delegation**, not the
|
||||||
|
process lifetime: a delegation resumed after a crash (A3) is the same session and
|
||||||
|
may replay its own artifacts.
|
||||||
|
- **Token budgeting is a render-time concern.** Context window and tokenizer are
|
||||||
|
properties of the model being called. Compute budget when building the request, not
|
||||||
|
when writing the log.
|
||||||
|
- **Compaction summaries are first-class log events** with the producing model
|
||||||
|
recorded, so a tier change does not silently inherit opaquely-compacted history.
|
||||||
|
- **Prompt cache breakpoints are placed by the renderer and never stored.** A tier
|
||||||
|
change means a cold cache — a cost event, not a correctness event.
|
||||||
|
|
||||||
|
### A11. Role Configuration
|
||||||
|
|
||||||
|
Model identity is expressed as **roles**, resolved to concrete model strings in config:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
roles:
|
||||||
|
executor: local/<model> # drives the loop, mechanical work
|
||||||
|
planner: <frontier> # authors plans
|
||||||
|
delegate: <frontier> # scoped sub-task execution
|
||||||
|
consultant: <frontier> # advisory, no repo access
|
||||||
|
```
|
||||||
|
|
||||||
|
"Best model this week" is a config edit. **The resolved mapping is pinned at task
|
||||||
|
start** and recorded in the log, so a mid-task config change cannot split a task
|
||||||
|
across two planners.
|
||||||
|
|
||||||
|
### A12. Escalation Triggers
|
||||||
|
|
||||||
|
The local model does **not** decide when it needs help. Small models are poorly
|
||||||
|
calibrated about their own competence and will escalate either constantly or never.
|
||||||
|
Triggers are observable from outside the model:
|
||||||
|
|
||||||
|
1. **Phase policy.** Planning and architecture escalate unconditionally. Mechanical
|
||||||
|
edits stay local.
|
||||||
|
2. **Failure count.** Local attempts; tests fail twice; escalate with the failures
|
||||||
|
attached to the brief.
|
||||||
|
|
||||||
|
A model-invoked `ask_expert` (A14) exists in addition to these, never as a
|
||||||
|
replacement, and carries a per-task budget so a confused executor cannot spend twenty
|
||||||
|
consults circling.
|
||||||
|
|
||||||
|
### A13. Delegation
|
||||||
|
|
||||||
|
Escalation is **delegation**: a frontier model receives a scoped sub-task, works
|
||||||
|
autonomously with full tool access, and hands back. It is not a consult, and the local
|
||||||
|
model does not interpret or re-derive the frontier model's reasoning.
|
||||||
|
|
||||||
|
**Harness — one, not one per vendor.** Do not adopt each vendor's agent SDK to obtain
|
||||||
|
their best agentic behavior; that recreates the lock-in this design avoids, relocated.
|
||||||
|
One loop, one cap regime, one handback contract.
|
||||||
|
|
||||||
|
**Normalization lives in the A10 renderer, not on the wire.** Vendors disagree
|
||||||
|
structurally about tool calling (content blocks vs. `tool_calls` arrays, tool-result
|
||||||
|
placement, streaming deltas) and about reasoning artifacts (signed thinking blocks,
|
||||||
|
encrypted reasoning items, thought signatures) — and a normalizing middlebox is lossy
|
||||||
|
exactly where a long-running delegation lives. So:
|
||||||
|
|
||||||
|
- **Delegations run over LiteLLM's passthrough route** (`/v1/messages` for Anthropic,
|
||||||
|
per A5), with the A10 renderer producing the vendor-native request body. The
|
||||||
|
renderer is a per-vendor adapter by definition — it already has to know each wire
|
||||||
|
shape to render the canonical log.
|
||||||
|
- **LiteLLM's normalized route is reserved for calls where fidelity is cheap:**
|
||||||
|
`ask_expert` (A14), fallback chains, and trialing a new vendor before its renderer
|
||||||
|
adapter exists.
|
||||||
|
- **Adding a vendor** therefore means writing one renderer adapter — or provisionally
|
||||||
|
accepting LiteLLM's normalization for that vendor and validating it against the A16
|
||||||
|
eval set before trusting it with delegations. A day-one build needs exactly one
|
||||||
|
adapter: the vendor actually in use.
|
||||||
|
|
||||||
|
**Scoping and authority.** Delegation sits **inside** the plan gate, not around it. A
|
||||||
|
frontier sub-agent that acts freely would bypass `submit_plan` (A4), which is the
|
||||||
|
structural control the design rests on.
|
||||||
|
|
||||||
|
- **Planning is itself a delegation** that produces a plan and stops. Human approves.
|
||||||
|
- **Execution delegations are scoped to a sub-task the approved plan already
|
||||||
|
contains.**
|
||||||
|
|
||||||
|
The frontier model is smart twice; neither time is it authorized to expand the work.
|
||||||
|
|
||||||
|
Because plans may be executed by a materially weaker model, the planner system prompt
|
||||||
|
must require **explicit, low-inference plans** — the executor cannot reconstruct
|
||||||
|
intent.
|
||||||
|
|
||||||
|
**Isolation and caps.**
|
||||||
|
- **Branch at delegation start.** Abort discards the branch. This gives delegations the
|
||||||
|
same atomicity property that boot-time reconciliation (A3) gives interrupted state
|
||||||
|
transitions.
|
||||||
|
- **Hard caps on turns, tokens, and wall clock.**
|
||||||
|
- **Checkpoint delegation events as they arrive.** Every `tool_call` / `tool_result` /
|
||||||
|
assistant turn inside a delegation is durably written to the canonical log when it
|
||||||
|
happens (per A2), never batched at handback. This is what makes a delegation
|
||||||
|
resumable after a crash — the deterministic resume rule lives in A3.
|
||||||
|
- **Defined failure return.** On cap breach or explicit failure, the local loop gates
|
||||||
|
to `AWAIT_INPUT` rather than resuming on top of a half-edited tree.
|
||||||
|
|
||||||
|
**Handback.** The final delegation action is a **structured handback note written for a
|
||||||
|
weaker reader**, not a human-facing summary:
|
||||||
|
|
||||||
|
- what changed
|
||||||
|
- what is now true that was not before
|
||||||
|
- what to do next
|
||||||
|
|
||||||
|
That note plus the resulting file state is the entire interface back to the local loop.
|
||||||
|
The delegation's internal transcript is stored alongside the composite event,
|
||||||
|
vendor-tagged, and never replayed into anything.
|
||||||
|
|
||||||
|
#### Rejected alternative: ask-and-apply
|
||||||
|
|
||||||
|
An alternative was considered in which the local model asks a frontier model for advice
|
||||||
|
and applies the answer itself. **Rejected.**
|
||||||
|
|
||||||
|
Its principal advantage was blast radius — the frontier model never touches the repo,
|
||||||
|
and everything flows through a gated local loop. That was explicitly not a concern
|
||||||
|
here.
|
||||||
|
|
||||||
|
Without it, the comparison is lopsided:
|
||||||
|
|
||||||
|
- Delegation lets the frontier model read the code, run the tests, and see the
|
||||||
|
failures. Ask-and-apply forces it to reason blind from whatever the local model
|
||||||
|
thought to include in the brief, and small models write poor briefs.
|
||||||
|
- The cost advantage is illusory: one delegation that succeeds beats three consult
|
||||||
|
round-trips that do not.
|
||||||
|
- Any variant where the local model *interprets* rather than applies verbatim
|
||||||
|
reintroduces the capability gap downstream of the expensive call.
|
||||||
|
|
||||||
|
The diff-application machinery, verbatim-fidelity rules, and local-model-as-verifier
|
||||||
|
design are all dropped.
|
||||||
|
|
||||||
|
### A14. `ask_expert` (retained, minimal)
|
||||||
|
|
||||||
|
One narrow case survives delegation: **questions requiring no repo access.** "Which of
|
||||||
|
these two approaches is better," "why does this library behave this way," "is this API
|
||||||
|
deprecated."
|
||||||
|
|
||||||
|
- Single stateless call, text answer.
|
||||||
|
- No diff application, no fidelity concerns, no session state.
|
||||||
|
- Reuses the delegation brief format.
|
||||||
|
- Structured output contracted **at the prompt level, not the API level** — vendors
|
||||||
|
differ on JSON mode and schema enforcement. Parse, validate against a local schema,
|
||||||
|
retry once.
|
||||||
|
|
||||||
|
Expected implementation size: small. Do not let it grow into a second escalation
|
||||||
|
subsystem.
|
||||||
|
|
||||||
|
### A15. Local Model Accommodations
|
||||||
|
|
||||||
|
- **Constrained decoding for tool-call JSON.**
|
||||||
|
- **Reduced tool schema for the executor role:** fewer tools, flatter arguments, no
|
||||||
|
deeply nested optionals. Maintain **two tool manifests keyed on role**, rendered at
|
||||||
|
request time like everything else.
|
||||||
|
|
||||||
|
### A16. Delegation Evaluation Capture
|
||||||
|
|
||||||
|
Capture a **consult/delegation eval set** from day one. Each `delegation_started` /
|
||||||
|
`delegation_completed` pair (A10) is already a clean input-output record; the
|
||||||
|
additional cost is marking outcomes as good or bad.
|
||||||
|
|
||||||
|
Without this, "best model this week" is decided by benchmark chatter, and swapping the
|
||||||
|
frontier tier becomes something to avoid because the effect is unmeasurable. With it, a
|
||||||
|
new model is a config change and a re-run.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART B — THE DEV AGENT / `nisse-dev` (build first)
|
||||||
|
|
||||||
|
A thin app over `nisse-core`. Plans and implements software projects; produces PRs.
|
||||||
|
|
||||||
|
### B1. Workflow (state machine)
|
||||||
|
|
||||||
|
```
|
||||||
|
IDLE
|
||||||
|
→ [use <project>] clone repo, begin architecture planning
|
||||||
|
PLANNING_ARCH
|
||||||
|
→ agent drafts architecture + implementation plan → submit_plan
|
||||||
|
AWAIT_ARCH_SIGNOFF ← human gate (approve / reject+feedback)
|
||||||
|
→
|
||||||
|
MILESTONE_PLANNING
|
||||||
|
→ agent drafts plan for a specific milestone → submit_plan
|
||||||
|
AWAIT_MILESTONE_SIGNOFF ← human gate
|
||||||
|
→ [start milestone <n>]
|
||||||
|
EXECUTING autonomous; no per-command approval
|
||||||
|
→ may enter AWAIT_INPUT (ask_human) any time it's unsure
|
||||||
|
PR_OPEN
|
||||||
|
→ open PR; react to review comments and commits (review loop)
|
||||||
|
→ on acceptance → next milestone, or project complete
|
||||||
|
```
|
||||||
|
|
||||||
|
### B2. Requirements
|
||||||
|
|
||||||
|
- **One active project at a time.** Operator selects it.
|
||||||
|
- **Operator commands** (over transport): `use <project>`, `approve`,
|
||||||
|
`reject <feedback>`, `start milestone <n>`, `status`, plus free text during
|
||||||
|
planning (forwarded to the agent as answers).
|
||||||
|
- **Plan gating** per A4: architecture plan and each milestone plan require sign-off
|
||||||
|
before the next phase. Enforced structurally. Plans and approvals are externalized
|
||||||
|
to Gitea issue comments (Part H, decided); Matrix and Gitea are both approval
|
||||||
|
channels, with revision binding and the uniform `approve` UI per A4.
|
||||||
|
- **Autonomous execution** within a started milestone: builds, runs, tests without
|
||||||
|
per-command approval; asks questions any time via `ask_human`.
|
||||||
|
- **Gitea integration:**
|
||||||
|
- *Outbound:* `git` + Gitea API to push branches and open PRs, via a dedicated
|
||||||
|
Gitea **service account** with a scoped token. Record any runnable test service's
|
||||||
|
URL/port in the PR description.
|
||||||
|
- *Inbound:* react to PR comments, commits, pushes. **Poll** the Gitea API
|
||||||
|
(15–30s) rather than take webhooks, to keep the VM outbound-only. Intake is
|
||||||
|
structured JSON — never via a chat bridge.
|
||||||
|
- *On Gitea unavailability:* the poller backs off (exponential, capped at a few
|
||||||
|
minutes) and retries indefinitely, logging the outage. Polling is pure intake —
|
||||||
|
an outage delays reactions but never fails a task or forces a state transition.
|
||||||
|
Outbound Gitea operations that fail mid-flight are already covered by the
|
||||||
|
intent log and boot-time reconciliation (A2/A3).
|
||||||
|
- **Browser (A6)** scoped to the **internal test network only** — used to exercise
|
||||||
|
web apps it built and reproduce bugs. **No SSO needed** for this.
|
||||||
|
|
||||||
|
### B3. Deployment & Isolation
|
||||||
|
|
||||||
|
- **Dedicated VM** (Proxmox), not a bare container — the agent builds and runs Docker
|
||||||
|
containers, so it needs its own real Docker daemon. (Docker-in-a-container via
|
||||||
|
socket-mount ≈ host root; via dind = nested-storage pain. The VM boundary is the
|
||||||
|
correct trust boundary for unattended arbitrary command execution.)
|
||||||
|
- **Sealed to start:** egress allow-list (LiteLLM, Gitea, package registries), **no
|
||||||
|
ingress**. Egress denial must include **RFC1918 except the specific LiteLLM/Gitea
|
||||||
|
IPs** — sealed from the internet must also mean no reach to NAS/Proxmox/UDM.
|
||||||
|
- **The LAN-resident inference host is not a second exception.** It sits behind
|
||||||
|
LiteLLM (A5), so the allowlist keeps exactly one LLM destination regardless of how
|
||||||
|
many models or vendors are in play.
|
||||||
|
- **No Tailscale** on this VM (it routes around firewall policy). Manage via Proxmox
|
||||||
|
console / jump host.
|
||||||
|
- **Own VLAN from day one** (even a VLAN of one) and test services on **predictable
|
||||||
|
ports** (e.g. 18000–18099), so opening access later is a firewall edit, not a
|
||||||
|
rebuild. (Sealed for now; may relax later.)
|
||||||
|
- Test containers on a dedicated **internal Docker network with no route out**.
|
||||||
|
- Build-daemon storage on a **separate mount** from the state volume, so
|
||||||
|
`docker system prune` between milestones can't touch agent state.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART C — THE SYSADMIN AGENT / `nisse-ops` (follow-on)
|
||||||
|
|
||||||
|
A thin app over the extracted `nisse-core`. Operates infrastructure; driven by
|
||||||
|
tickets; gated on consequences. Built after the Dev Agent works.
|
||||||
|
|
||||||
|
### C1. How it differs (not reducible to config)
|
||||||
|
|
||||||
|
| Axis | Dev Agent | Sysadmin Agent |
|
||||||
|
|---|---|---|
|
||||||
|
| Rollback | revert snapshot / discard branch | none for `zfs destroy` or a firewall lockout |
|
||||||
|
| Trust model | allow-all in sandbox | tiered **allow / deny / confirm** policy |
|
||||||
|
| Work shape | long milestones → a PR | short reactive tasks + scheduled checks → live changes |
|
||||||
|
| Driver | Gitea projects | **Vikunja tickets** |
|
||||||
|
| Placement | sealed, own VLAN, no Tailscale | Tailscale, credentials, broad reach |
|
||||||
|
|
||||||
|
Running both roles in one instance would collapse isolation — build them as separate
|
||||||
|
deployments over the same library.
|
||||||
|
|
||||||
|
### C2. Permission Policy Engine *(the defining addition)*
|
||||||
|
|
||||||
|
Tiered policy, evaluated on every action:
|
||||||
|
- **Read-only telemetry** (metrics, logs, status) — free.
|
||||||
|
- **Reversible service actions** (restart a container) — allowed.
|
||||||
|
- **High-consequence actions** (storage, networking, auth) — **confirm-first** over
|
||||||
|
transport before executing.
|
||||||
|
|
||||||
|
This is the sysadmin analog of the dev agent's plan gate: the human boundary sits at
|
||||||
|
irreversible / high-blast-radius actions.
|
||||||
|
|
||||||
|
Special cases fold into the tiers:
|
||||||
|
- **Browser actions against admin UIs default to confirm-first.** Changes to
|
||||||
|
**network gear (UniFi) are the most conservatively gated action in the system** — a
|
||||||
|
bad remote UI click can sever the path used to fix it.
|
||||||
|
- **Action-triggering tickets are operator-scoped** (C4). Auto-generated tickets
|
||||||
|
(e.g. from a monitoring alert) route through confirm-first, never drive unattended.
|
||||||
|
|
||||||
|
### C3. Interfaces
|
||||||
|
|
||||||
|
- **Browser (A6):** into admin UIs. **Prefer real APIs where they exist** (Proxmox,
|
||||||
|
TrueNAS good; UniFi partial); use the browser only for genuinely UI-only gaps —
|
||||||
|
it's the least stable interface.
|
||||||
|
- **SSO (A8):** logs into admin UIs as `svc-nisse-ops`. This account is a high-value
|
||||||
|
credential; its blast radius equals its Authelia scope, so scope it minimally.
|
||||||
|
- **Secrets (A7):** UI/SSO logins and service API tokens from Bitwarden.
|
||||||
|
- **Event intake:** monitoring feeds the orchestrator as **structured JSON**
|
||||||
|
(directly or via Alertmanager), never through a Matrix bridge. The agent posts
|
||||||
|
curated, state-aware updates to `#ops` ("Gitea 502ing, restarted, back up").
|
||||||
|
|
||||||
|
### C4. Ticket-Driven Control (Vikunja)
|
||||||
|
|
||||||
|
The sysadmin analog of "dev agent driven by Gitea."
|
||||||
|
- **Vikunja ticket = task of record** (durable, has status/queue/history). **Matrix =
|
||||||
|
live conversation about it** (questions, confirm-first prompts, progress).
|
||||||
|
- **Flow:** ticket filed → agent picks up → discuss/confirm over Matrix → update
|
||||||
|
status as it progresses → close with result.
|
||||||
|
- **Mechanics:** Vikunja REST API + webhooks (same two-direction, JSON-only pattern
|
||||||
|
as Gitea); dedicated service account, scoped token from Bitwarden. Verify the
|
||||||
|
installed version's webhooks fire on comment creation; if not, poll comments as
|
||||||
|
B2 polls Gitea.
|
||||||
|
- **Approvals:** Vikunja is an `ApprovalSource` (A4) for plan gates on its own
|
||||||
|
tickets, via `approve rev-N` comments. Live **confirm-first** prompts (C2) stay
|
||||||
|
Matrix-primary — polling latency makes a ticket comment a poor interactive
|
||||||
|
channel — with the outcome written back to the ticket as the record.
|
||||||
|
- **Trust:** a driving ticket is an instruction channel into an infrastructure-
|
||||||
|
changing agent → action-triggering ticket creation is operator-scoped (C2).
|
||||||
|
|
||||||
|
### C5. Deployment & Isolation
|
||||||
|
|
||||||
|
- Longer-lived, **stateful VM** (not disposable).
|
||||||
|
- Has **Tailscale** + scoped credentials to reach infrastructure across both sites.
|
||||||
|
- Updated **in place** via the container pipeline, **restart gated on an idle flag**.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART D — NOTES / KNOWLEDGE (Outline)
|
||||||
|
|
||||||
|
Shared knowledge store for both agents (sysadmin-primary). Not a message bus — see
|
||||||
|
note below.
|
||||||
|
|
||||||
|
Requirements:
|
||||||
|
- **Read — runbooks as context.** Procedures written in Outline are fetched before
|
||||||
|
acting, constraining the agent toward *your* procedures over improvised ones.
|
||||||
|
- **Write — durable record.** Agent writes change logs / incident notes / findings
|
||||||
|
back to Outline: searchable, off-box, and an extra externalized record that
|
||||||
|
survives volume loss.
|
||||||
|
- Access via Outline **REST API**, dedicated service account, token from Bitwarden.
|
||||||
|
|
||||||
|
**Deliberately rejected:** using a shared notes store (Outline *or* an Obsidian vault)
|
||||||
|
as an **agent-to-agent message bus**. It's unstructured, race-prone (last-write-wins,
|
||||||
|
no delivery semantics), and a shared read-write store both agents touch would
|
||||||
|
undermine the dev/sysadmin isolation boundary. Agent coordination, if ever needed,
|
||||||
|
goes through the **human**, **Matrix**, or a **Vikunja ticket** handed from one agent
|
||||||
|
to another — or a real message queue if genuine multi-agent async ever arrives.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART E — SUPPORTING SERVICES (installed)
|
||||||
|
|
||||||
|
**Status: all supporting services are installed and running.** What remains for each
|
||||||
|
is per-agent *configuration* (service accounts, scoped tokens, rooms), created as
|
||||||
|
each agent is built — not standing up the service itself.
|
||||||
|
|
||||||
|
- **Matrix homeserver** (Synapse/Conduit): ✅ installed. *Remaining per-agent:* create
|
||||||
|
the two bot identities (`@nisse-dev`, `@nisse-ops`), one room per agent + `#ops`.
|
||||||
|
- **Gitea:** ✅ installed. *Remaining per-agent:* `nisse-dev` service account + scoped
|
||||||
|
token; enable native-JSON webhooks or confirm API polling access.
|
||||||
|
- **LiteLLM proxy:** ✅ installed, and **on the path from the first LLM call** (A5) —
|
||||||
|
it is the agent VM's single LLM destination, providing per-agent virtual keys with
|
||||||
|
budget caps, central logging, vendor swap, fallback routing, and the Anthropic
|
||||||
|
passthrough. *Remaining per-agent:* mint a virtual key; configure routes for the
|
||||||
|
local inference host and each frontier vendor, with keys sourced from Bitwarden.
|
||||||
|
- **Local inference host:** 🔜 **decided in principle, hardware pending** — a
|
||||||
|
4090-class server (Part H). Interim: a Jetson Nano running Ollama validates the
|
||||||
|
plumbing, and the `executor` role maps to a Haiku-class frontier model via LiteLLM
|
||||||
|
until the server arrives. Everything in A5, A12, and A15 assumes the eventual host
|
||||||
|
sits on the LAN behind LiteLLM.
|
||||||
|
- **Vikunja:** ✅ installed. *Remaining (sysadmin):* service account + scoped token;
|
||||||
|
webhook/poll config (Part C4).
|
||||||
|
- **Outline:** ✅ installed. *Remaining per-agent:* service account + API token
|
||||||
|
(Part D).
|
||||||
|
- **Bitwarden/Vaultwarden:** ✅ installed. *Remaining per-agent:* dedicated
|
||||||
|
minimally-scoped machine account + bootstrap token (A7).
|
||||||
|
- **LLDAP + Authelia:** ✅ installed. *Remaining per-agent:* create `svc-nisse-dev` /
|
||||||
|
`svc-nisse-ops` principals, scoped groups, and the narrow unattended-auth exception
|
||||||
|
(A8).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART F — DEPLOYMENT MODEL (both agents)
|
||||||
|
|
||||||
|
- **Containers + persistent volumes.** Stateless image; named volumes carry state
|
||||||
|
across redeploys (and allow optional persistence between deployments).
|
||||||
|
- **Image delivery:** Gitea Actions → Gitea OCI registry → Watchtower for the *pull*.
|
||||||
|
- **Gate the restart, not the pull:** an idle/"safe-to-restart" flag; Watchtower must
|
||||||
|
never restart mid-work. *Unplanned* interruptions (reboot/crash) are handled by the
|
||||||
|
durability layers (A2/A3), not by restart timing.
|
||||||
|
- **Survive reboots:** VM + Docker service set to start on boot; `restart:
|
||||||
|
unless-stopped`; ZFS snapshots of the state dataset (scheduled + on each approval).
|
||||||
|
- **Terraform + cloud-init:** deferred. When adopted, `bpg/proxmox` + cloud-init,
|
||||||
|
VM definitions as code, clean `destroy`/`apply`; the dev agent becomes a candidate
|
||||||
|
for immutable rebuilds.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART G — BUILD ORDER
|
||||||
|
|
||||||
|
1. **State store + durability (A2/A3)** — critical path; everything sits on it.
|
||||||
|
2. **Transport (A1, Matrix) + control loop/gating (A4)** with a **stub agent** that
|
||||||
|
just echoes plans — get the approval loop feeling right before any real LLM.
|
||||||
|
3. **LiteLLM + LLM client interface (A5).** The interface must exist at the **first
|
||||||
|
real LLM call**, not as a later cutover. Mint a virtual key with a budget cap;
|
||||||
|
verify prompt caching survives the passthrough.
|
||||||
|
4. **Canonical log schema and renderer (A10).** Before any transcript accumulates in a
|
||||||
|
provider-shaped form that would have to be migrated later.
|
||||||
|
5. **Local executor loop (A11/A12/A15)** — role resolution pinned at task start, phase
|
||||||
|
policy, failure-count escalation, reduced tool manifest, constrained decoding.
|
||||||
|
6. **Gitea layer** — polling intake, PR creation, comment/commit handling.
|
||||||
|
7. **Delegation harness + plan-gate integration (A13/A14).** Begin capturing the eval
|
||||||
|
set here (A16); the records are free once the composite events exist.
|
||||||
|
8. **Browser tool (A6)** for `nisse-dev` — test apps on the sealed network.
|
||||||
|
9. First **genuinely unattended milestone** (budget caps + ZFS rollback earn their keep
|
||||||
|
here). Crash-atomic writes and reconcile-on-boot must be in place first.
|
||||||
|
10. **Extract `nisse-core`**; build the **Sysadmin Agent** (`nisse-ops`): policy
|
||||||
|
engine (C2), SSO + scoped browser (A8/A6), secrets (A7), Vikunja control (C4),
|
||||||
|
Outline runbooks (D), scheduled checks, alert intake.
|
||||||
|
- Under a monorepo, extraction is a **package split** within one tree: move code
|
||||||
|
behind a package boundary, no release machinery required.
|
||||||
|
- Under three repos, it is a **repo split plus a version-pinning contract**:
|
||||||
|
`nisse-core` gets tagged releases, and `nisse-dev` pins a version rather than
|
||||||
|
tracking `main`, or every core change becomes a coordinated two-repo bump.
|
||||||
|
This is the step the open repo-layout decision (Part H) actually bites on.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## PART H — OPEN DECISIONS
|
||||||
|
|
||||||
|
- **Inference hardware — resolved in principle, no longer blocking.** Target: a
|
||||||
|
**4090-class host (24GB VRAM)** running a **24–32B open model** at 4–5-bit
|
||||||
|
quantization (candidates: Devstral Small 24B, Qwen3-32B / Qwen3-30B-A3B,
|
||||||
|
GPT-OSS-20B). Models of this class are competent at tool calling and mechanical
|
||||||
|
edits, which puts the system in "tiering genuinely load-bearing" territory rather
|
||||||
|
than "local model as dispatcher." Consequences:
|
||||||
|
- **Context, not weights, is the VRAM pressure.** A 32B at 4-bit leaves roughly
|
||||||
|
5GB for KV cache, and agent loops render long contexts. Model size vs. context
|
||||||
|
length vs. KV-cache quantization is an empirical trade — tune it, and the
|
||||||
|
thresholds that depend on local capability (A12 failure count, A14 consult
|
||||||
|
budget, A15 manifest size), at build-order step 5 on the real hardware.
|
||||||
|
- **Interim posture:** until the server exists, the `executor` role points at a
|
||||||
|
cheap frontier model (Haiku-class) through LiteLLM — a config entry under A11,
|
||||||
|
nothing structural, so the build order does not stall. The Jetson Nano validates
|
||||||
|
plumbing (Ollama → LiteLLM → agent) only; nothing learned from models it can run
|
||||||
|
transfers to threshold tuning.
|
||||||
|
- If the 24GB class proves insufficient in practice, additional hardware is the
|
||||||
|
fallback — the role indirection (A11) makes that swap invisible to the agents.
|
||||||
|
|
||||||
|
The rest resolve when reached, not now.
|
||||||
|
|
||||||
|
- **Repository layout:** one monorepo with three packages vs. three separate repos.
|
||||||
|
Three repos match the build order and give each artifact its own CI and release
|
||||||
|
cadence, at the cost of version-pinning `nisse-core` from Gitea and coordinating
|
||||||
|
bumps every time the shared interface moves. A monorepo is less friction while
|
||||||
|
`nisse-core` is still being extracted from a working `nisse-dev` and its seams are
|
||||||
|
still moving. Splitting later is easy; merging later is not. Decide by step 10.
|
||||||
|
- **Sysadmin browser access to network gear:** standing vs. per-task hand-off. The
|
||||||
|
lock-yourself-out risk argues for per-task.
|
||||||
|
- **Policy action taxonomy (C2):** the concrete list of which operations are
|
||||||
|
allow vs. confirm. Best decided with the agent half-built in front of you.
|
||||||
|
- **Approved-plan externalization — decided: Gitea-backed from the start.** Plans are
|
||||||
|
posted as issue comments on the project repo; the approval comment (author,
|
||||||
|
timestamp, revision tag) is the durable off-box record, authenticated by Gitea's
|
||||||
|
own auth. The state store keeps only a pointer ("gate 3 satisfied by comment 8841"),
|
||||||
|
so boot-time reconciliation (A3) can re-derive gate state from Gitea even after
|
||||||
|
state-volume loss — external truth wins (A2). Approval mechanics and revision
|
||||||
|
binding are specified in A4.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Repository Layout
|
||||||
|
|
||||||
|
```
|
||||||
|
nisse-core/ # shared library (extracted after nisse-dev works)
|
||||||
|
transport/ # matrix | telegram | slack (A1)
|
||||||
|
state/ # persistence, reconcile, migration (A2/A3)
|
||||||
|
control/ # loop, state machine, gating, ask_human (A4)
|
||||||
|
llm/ # client interface, role resolution (A5)
|
||||||
|
log/ # canonical event log + renderer (A10)
|
||||||
|
delegation/ # delegation harness, ask_expert (C1/C3)
|
||||||
|
browser/ # Playwright tool (A6)
|
||||||
|
secrets/ # Bitwarden machine-account client (A7)
|
||||||
|
sso/ # LLDAP identity + auth path (A8)
|
||||||
|
logging/ # structured operational logs (A9)
|
||||||
|
|
||||||
|
nisse-dev/ # app: sealed VM (Part B)
|
||||||
|
workflow (arch/milestone gating), Gitea PR layer, allow-all sandbox
|
||||||
|
browser → internal test network only
|
||||||
|
|
||||||
|
nisse-ops/ # app: separate host, Tailscale (Part C)
|
||||||
|
policy engine, tiered confirmation, scheduled checks
|
||||||
|
Vikunja ticket intake, Outline runbooks/records
|
||||||
|
browser → admin UIs (API-first, UI fallback), confirm-first gating
|
||||||
|
|
||||||
|
infra/ # (future) Terraform + cloud-init (Part F)
|
||||||
|
nisse-dev.tf | nisse-ops.tf | templates/
|
||||||
|
```
|
||||||
|
|
||||||
|
Shown as three sibling trees. Under a monorepo they become three packages under one
|
||||||
|
root; under three repos, three checkouts. Either way the module boundaries are the
|
||||||
|
same, which is the point of deciding this late (Part H).
|
||||||
|
|
||||||
|
`log/` carries the canonical event log and its renderer (A10); `delegation/` carries
|
||||||
|
the delegation harness and `ask_expert` (A13/A14).
|
||||||
Reference in new issue
Block a user