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.
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 thatroles/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-staffdefinition (each organization's chief is its own, REQ-COS-3), anassistantdefinition under any name butassistant, andcredentials,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. Notchief-of-staff, notassistant. - 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:
- Start with the root agents, minus any whose
excludeOrgsnames O. - Lay the organization's
rolesover 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. - 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
assistantinstance 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
rolesalone 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
hireablelist. 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 likeaddProject's), for a role inhireable. 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:hireablegoes from[]tocoderand 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 onHIRE_ALLOWED. The chief can then hire at the organization level with the existinghireverb. 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.mjsandrole.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 keepsmessage.sendandrecord.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.mdlands 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),ctoandmerge-gatestay 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
- 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.
- 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. - A4, chief hire and fire at org and project level, bounded by the
approved
hireablelist, trailed. - A5, root-level hire and fire as inbox decisions, with the owner's approval writing the root file through A2's writer.
- A6, the root assistant.
<dataRoot>/assistant/memory, the Console read broker overorganizations.members, and the per-organizationassistantinstances retired in favor of the one root assistant. - 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-exportpackages/business/src/agent-levels.mjsthat the rename r2 stage B test requires of every organization module.validateBusinessDocumentchecksprojects.<p>.agentsand drops it from the loaded business. - Read:
GET /api/agents/levels(packages/webui/src/agent-levels-read.mjs), wired incli.mjswithloadRootreading<configDir>/agents.json. The route is instance-wide, like/api/workspace, sodisplay.jsleaves it unscoped: its fetch wrapper would otherwise rewrite it to/api/orgs/<id>/agents/levels, which does not exist. - Console editor:
SERVER_PROJECT_KEYSholdsagents, 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.