Files
stack/docs/plans/2026-11-10_agent-levels-design.md
jason.woltje d247b4eb61 fix(agents): A1 review fixes for scope, opt-outs and refusal text (#1873)
Two independent reviews (Sol, daybreak-blue) asked for changes.

- An organization's own assistant instance is scoped to that
  organization. Only the root assistant, which no union holds, is
  cross-organization.
- A root opt-out or project exclude whose name a more specific level
  defines is no longer listed as unavailable.
- A malformed root agents.json refuses with "not valid JSON" only; the
  parser's text, which can quote the file's bytes, is dropped.
- A refused root or project var names its key, never its value; an id
  check's quote of a root value is dropped too. A value can be a secret
  typed in the wrong place, and these refusals reach the Console.
- The root assistant's row shows the model the root file sets.

Tests cover each case, with a sentinel value checked absent from the
route body. The design doc records the behavior.
2026-11-10 13:29:11 -06:00

20 KiB

Agent levels and the cross-organization assistant (Phase A design, #1873)

Status: design for lane org-a1, 2026-11-10. Slice A1 (read-only store, union resolution, Agents grid) is built on branch org-a1. Everything that gives an agent a new capability is in the roles proposal and the later slices listed in section 9; none of it is applied.

Direction: PRD 1.20 draft 2 (REQ-ASSIST-1, REQ-USER-1 amendment, REQ-AGENT-1 to REQ-AGENT-3, REQ-COS-3, REQ-DEC-2, REQ-ROLE-3), owner direction rulings 4 and 11, the U0 approval and the addendum in docs/plans/2026-11-09_unified-workspace-owner-direction.md, and the role model in roles/ and docs/plans/2026-09-02_atomic-mosaic-foundation.md.

Owner words: "Agents are configured at three levels: the user's root, the organization and the project. A project's agents are the union of all three. The user's main interaction agent (the assistant) is the one exception to isolation. [...] Every other agent is isolated to the organization it works in." And: "the COS should be able to hire and fire agents to fulfill the user's needs."

1. Terms

  • Definition: a named agent entry at one level. It names a role definition in roles/ (definition) and may carry vars. It never names a credential, a holder, a tracker bot, an identity or a publish grant at the root or project level.
  • Role definition: roles/<name>.json, versioned and changed only by reviewed commits (invariant 7). A level chooses among role definitions and never creates one, so no level can grant an authority that roles/ does not already hold.
  • Copy: a root definition as it runs inside one organization. Each organization runs its own copy, and each copy has that organization's memory, files and credentials.
  • Union: the agents available in one project of one organization.

2. Where each level lives

Level File Writer today Owner
root <configDir>/agents.json, next to the instance's system config the user, by hand (no writer in A1) the instance's OS user
org roles in <configDir>/businesses/<org>.json (unchanged) existing org writers the organization
project projects.<project>.agents in the same organization file the owner's updateOrg only; no agent writer can reach it the organization

Root: <configDir>/agents.json

configDir is the directory of the instance's system config (~/.config/mosaic-<instance>/). The file sits outside the data root, so it is outside every organization root (<dataRoot>/org-runtime/<org>) and every bus, and no bus or sandbox mount reaches it. It is per instance, as the system config is (invariant 2). When accounts arrive (Phase M), it moves to a per-principal path under the same directory; the format stays.

{
  "agentsVersion": 1,
  "agents": {
    "assistant":  { "definition": "assistant", "vars": { "model": "opus-5.5" } },
    "reviewer":   { "definition": "reviewer", "excludeOrgs": ["home"] },
    "researcher": { "definition": "researcher" }
  }
}
  • Keys: definition (required), vars (agent layer, checkVars(..., "agent")), excludeOrgs (distinct organization ids; "reviewer turned off for Home" in sample 08). Any other key refuses.
  • The file must be a regular file opened without following a link, owned by the process uid and not writable by group or other, the same checks as the organization file. A missing file means no root agents. Anything else that is wrong refuses the whole root level (section 6).
  • Refused at the root: a role definition that is version 1 or missing, the chief-of-staff definition (each organization's chief is its own, REQ-COS-3), an assistant definition under any name but assistant, and credentials, holder, tracker, identity, publish, hosts.

Organization: roles

Unchanged. Every organization instance stays as it is, validated by validateBusinessDocument, with its credential map, tracker bot and identity.

Project: projects.<project>.agents

The project level is in the organization file, not in the project repository. The repository's .mosaic/project.json can be written by any agent that can push to the project, so a definition there would let an agent create agents. The organization file is reachable only by the trusted writer, and the existing projects fence (organization-projects-protected in organization.mjs) already refuses every general write that changes projects. No agent writer can add, change or remove a project agent. The owner's updateOrg can, and the Console's organization editor holds the key on the server (SERVER_PROJECT_KEYS), so the browser draft cannot change it in A1.

"projects": {
  "spring-launch": {
    "root": "...",
    "agents": {
      "social-scheduler": { "definition": "pm", "vars": { "model": "haiku-5.5" } },
      "coder":    { "vars": { "limits.network": "none" } },
      "reviewer": { "exclude": true }
    }
  }
}

Each entry has exactly one form:

  • define: { "definition", "vars"? }. Agent-layer vars. Not chief-of-staff, not assistant.
  • narrow: { "vars" } only. Every key must be an intersect key (limits.tools, limits.network, limits.authority), checked at the project layer. A project narrows an inherited agent and never widens it.
  • exclude: { "exclude": true }. The inherited agent is not available in this project.

validateBusinessDocument checks each entry's shape and role definition for every reader (bus, Console, CLI). It does not copy agents into the loaded business object, so a bus built from the file sees exactly what it saw before. A project that is deleted takes its agents with it, and so does a deleted organization.

Library projects (kind: "library") keep their own mapping check and take no agents key.

This is an additive, optional key in the organization file. It is not a bus store (SQLite) schema change: no migration, no new table, no bus verb.

3. Union resolution

For organization O and project P:

  1. Start with the root agents, minus any whose excludeOrgs names O.
  2. Lay the organization's roles over them. An org instance with the same name as a root agent replaces it entirely; the root entry is recorded as an override of that agent.
  3. Lay P's entries over the result:
    • define replaces any inherited agent of that name; the inherited entry is recorded as an override.
    • narrow merges vars through mergeVars, inherited layer first and the project layer after it, so limits only intersect. The keys it narrowed are recorded.
    • exclude removes the agent and records who removed it.

Rules:

  • The most specific level that defines a name wins, and the whole entry wins: definition and vars, never a field-by-field mix.
  • A narrow or exclude entry naming an agent that no lower level provides refuses. A typo never silently does nothing.
  • A project entry of any form naming the organization's chief (an instance whose definition is chief-of-staff) or the assistant refuses. A project cannot remove, narrow or replace the chief or the assistant.
  • Two levels never merge vars, apart from a project narrowing. Root vars stay with the root definition, and an org instance of the same name brings its own.
  • The result for each agent: name, definition, level, source (which file), the overrides it shadows, the keys narrowed, and its scope. Every agent in a union is scoped to O, an organization's own assistant instance included. Only the root assistant, which no union holds, is cross-organization.
  • The union also lists what O or P does not get: root agents turned off for O and agents P excluded. A name that a more specific level then defines is available under that definition and is not listed.

Implementation: packages/organization/src/agent-levels.mjs (loadRootAgents, checkRootAgents, checkProjectAgents, resolveAgentLevels, projectUnion). It is pure apart from the one root file read.

4. Isolation of every non-assistant agent

Every agent except the root assistant resolves to scope { org: O } in the organization it runs in, whichever level defined it. The scope fixes three things:

  • Memory and records: under the organization's root, <dataRoot>/org-runtime/O/..., on that organization's bus, as every org instance has today. A root agent's copy in O and its copy in O2 share nothing: no thread, no record, no session file.
  • Files: the project workspaces of O only. The sandbox mounts come from O's project mapping, never from another organization's.
  • Credentials: only from O's credential map. A root definition carries none (refused, section 2). In A1 a root or project agent is shown as unbound: it has no credential and cannot be launched, because the bus builds instances from roles alone and the loaded business object does not carry project agents.

When root copies run (slice A3), each copy becomes a bus instance in O under O's writer, with O's credential bindings, through the same checkRoles path an org instance takes. A copy never reads the root file at run time; it gets its definition when O's bus boots.

5. The assistant across organizations

Reads

The assistant reads another organization only through the Console's membership-checked cross-organization read: organizations.members(session) (packages/webui/src/organizations.mjs), the read GET /api/workspace uses. Each organization is admitted by showOrg (owner check, registry digest, document validation) and resolveOrg (marker, modes) before any transport is built, and each bus read goes over that organization's own socket with a deadline. The assistant process gets no org root path, no bus socket path and no file mount of any organization. It calls a read broker that the Console holds for the owner's session. A direct read of another organization's bus files does not exist as a code path: the assistant sandbox mounts only its own memory directory.

Shared memory

The assistant's one memory lives at <dataRoot>/assistant/ (mode 0700, owned by the instance user). It sits inside the instance data root and outside every org-runtime/<org> root, so deleting or archiving an organization never touches it, and no organization's agents can mount it. It holds the assistant's notes and session files. It never holds a copy of an organization's records; what the assistant learns from an organization stays in that organization, plus whatever the assistant chose to write in its own memory.

Authority

REQ-ASSIST-1: the assistant talks with the user and hands each organization's work to that organization's chief. It does not direct agents, create tasks or launch sessions. Its role keeps message.send and record.write only. The roles proposal (section 8) adds no action to it.

A1 reality

Today each organization file declares its own assistant instance. A1 shows those as org agents. A root assistant entry, if the user writes one, shows in the band as the root assistant with cross-organization scope. Nothing reads across organizations for it yet.

6. Fail-closed boundaries

Boundary A1 behavior Later slices
Root file (new) O_NOFOLLOW regular file, process uid, no group or other write; any problem refuses the whole root level and the grid says so; a missing file is "no root agents". The refusal names the file and the key at fault, never a value from the file: parser text and a var check's quote of the refused value are dropped, since a value can be a secret typed in the wrong place. Project var refusals drop the value the same way. The root writer accepts only the human session (section 7).
Organization file projects.<p>.agents (new key) Checked by validateBusinessDocument for every reader; a bad entry refuses the whole organization file, as any bad key does. Not copied into the loaded business, so buses gain nothing. The projects fence keeps every agent writer out. A project-agent writer verb, with its own guard, like addProject.
Union A narrow or exclude naming nothing refuses that project; touching the chief or assistant refuses that project; the grid shows the refusal for that project. A launch resolver refuses to launch any agent in a project whose union refuses.
Console read GET /api/agents/levels (new) Owner only (granted users and the tester get owner-only, 403); organizations come only from organizations.members(session); the body carries ids, names, role definition names, model var and level. It never carries a path, a credential reference or a var other than model and the narrowed key names. Unchanged.
Org isolation Root and project agents are not instances on any bus; nothing reads across organizations except the existing Console read. Each copy is materialized by O's own writer and runs under O's credentials.
Assistant memory Not built. <dataRoot>/assistant/ with 0700; the sandbox mounts it and nothing else.
Roles No change in commits. The proposal patch, applied only after Jason approves it.

A root file that refuses hides the root level everywhere rather than showing a partial list: an exclusion that did not parse must not let an excluded agent appear.

7. Chief-of-staff hire and fire, per level

Today roles/chief-of-staff.json lists role.hire and role.fire within its role, with "hireable": []: it can hire nothing. Each level adds a write path; none exists in A1.

  • Organization level (REQ-COS-3): the chief hires or fires an organization instance through the organization's trusted writer, for a role in its hireable list. Each hire lands in the action trail. The user can override any setting at any time through REQ-ROLE-3.
  • Project level: the chief adds or removes a project entry through a new writer verb that changes only projects.<p>.agents (a guard like addProject's), for a role in hireable. The projects fence still refuses every other change.
  • Root level (U0 ruling): the chief cannot write the root file. It raises an inbox decision (REQ-DEC-2) in its own organization that names the role definition, the agent name and the reason. The user approves or denies it in the Console inbox. On approval the Console, acting with the human's session, writes the root file through a root writer that refuses any actor other than the signed-in owner (human-required). A denied or expired decision changes nothing. A fire works the same way. The chief never learns the file's path.

hireable decides what can be hired at all; widening it is a roles/ change and needs Jason's reviewed commit. The proposal (section 8) names the roles.

8. Authority changes proposed, not applied

The patch is at /mnt/storage/scratch/mosaic-lead/reports/org-a1-roles-proposal.patch. It is never applied on this branch. It applies with git apply on origin/refactor and needs a reviewed commit that Jason approves.

What it changes:

  • roles/chief-of-staff.json: hireable goes from [] to coder and the five advisory chiefs (chief-executive-officer, chief-financial-officer, chief-information-officer, chief-information-security-officer, chief-marketing-officer). These are the only shipped definitions that pass today's hire check: version 2, not creative, and every action on HIRE_ALLOWED. The chief can then hire at the organization level with the existing hire verb. The project level (A4) uses the same list.
  • roles/chief-of-staff.md: drops "your empty hireable list", names the list, says a hired coder has no credential until the human binds one, and says the chief hires only in its own organization, never at the root.
  • packages/organization/tests/chief-of-staff.test.mjs and role.test.mjs: the tests that pin the shipped chief file move to the new list, and the contract test pins the new sentence. Two bus test comments that said "shipped chief hireable:[]" are reworded. These go in the same commit, or the organization suite fails.

What it leaves alone, and why:

  • roles/assistant.json: no change. The cross-organization read is the Console's read broker acting for the owner's session (section 5), not a role action, so the assistant needs no new grant. It keeps message.send and record.write. Adding an action would widen it for no gain.
  • roles/assistant.md: no change yet. Its "one user in one business" text stays true until A6 builds the root assistant; the contract text for the cross-organization read and the shared memory lands with A6, in that slice's own reviewed commit.
  • Root-level hire text in chief-of-staff.md lands with A5, when the inbox decision exists. A contract sentence for a tool the chief doesn't have would invite it to try.
  • HIRE_ALLOWED: unchanged. reviewer, security-reviewer (review.verdict), pm (task.create), cto and merge-gate stay unhireable. Making any of them hireable is a separate vocabulary decision, not part of this proposal.

9. Phase A slices after the roles change is approved

  1. A2, root and project writers. Owner-only root file writer (human session, trail entry, revision check) and the project-agent writer verb under the projects fence, both refusing every agent actor. Settings, Agents gets the edit forms.
  2. A3, root copies run. Each organization's bus boot materializes its root copies as instances through checkRoles, with the organization's credential bindings; unbound copies stay unlaunchable and say why. Project agents launch only in their project.
  3. A4, chief hire and fire at org and project level, bounded by the approved hireable list, trailed.
  4. A5, root-level hire and fire as inbox decisions, with the owner's approval writing the root file through A2's writer.
  5. A6, the root assistant. <dataRoot>/assistant/ memory, the Console read broker over organizations.members, and the per-organization assistant instances retired in favor of the one root assistant.
  6. A7, the Agents grid's write controls (model Change, override markers, turn off for an organization), each a trailed human action.

10. Slice A1 as built

  • Store and union: packages/organization/src/agent-levels.mjs, with the old-path re-export packages/business/src/agent-levels.mjs that the rename r2 stage B test requires of every organization module. validateBusinessDocument checks projects.<p>.agents and drops it from the loaded business.
  • Read: GET /api/agents/levels (packages/webui/src/agent-levels-read.mjs), wired in cli.mjs with loadRoot reading <configDir>/agents.json. The route is instance-wide, like /api/workspace, so display.js leaves it unscoped: its fetch wrapper would otherwise rewrite it to /api/orgs/<id>/agents/levels, which does not exist.
  • Console editor: SERVER_PROJECT_KEYS holds agents, so a browser draft of the organization file keeps the server's value. The CLI's full-document path (mosaic org update --from) is the owner's and can set project agents; A1 adds no other writer.
  • Agents grid (sample 08): the level band shows the root agents and their per-organization opt-outs, each organization's instances, and each project's own definitions. Below it, a project picker chooses which union the table shows: agent, level, defined in, memory, status, model. Root and project agents read "not running", because nothing launches them yet. The root assistant's status reads "status not reported" and its model is the one the root file sets, shown as configured. A narrowed agent names the keys, an override names what it replaces, and a line under the table lists what this project does not get and why. A refused root file, organization or project shows its reason in place of its rows. The grid has no write controls; those are A7.