diff --git a/docs/plans/2026-11-10_system-type-toolsets-design.md b/docs/plans/2026-11-10_system-type-toolsets-design.md index 4569108e8..bdcbab5ea 100644 --- a/docs/plans/2026-11-10_system-type-toolsets-design.md +++ b/docs/plans/2026-11-10_system-type-toolsets-design.md @@ -25,20 +25,25 @@ project gets the toolsets of the system types that project uses." `{selected, active, inactive}`, where `active = selected ∩ enabled` and `inactive = selected − enabled`. - **Launch.** `resolveInstance` (`packages/organization/src/resolve.mjs`) - starts from the role definition's `tools`, filters them by each layer's - `limits.tools` (system, business, project, agent), and freezes the result - with a digest. The launcher (`packages/cli/src/launcher.mjs`) passes that + starts from the role definition's `tools` and `network`, narrows them by + each layer's `limits.tools` and `limits.network` (system, business, + project, agent), and freezes the result with a digest. The role's `tools` + is therefore a ceiling: a launch gets those tools minus whatever a layer + limit removes, never more. The launcher (`packages/cli/src/launcher.mjs`) passes that result to `buildBundle` (`packages/harness/src/bundle.mjs`), which writes `policy.json` (`tools: builtinTools(resolved.limits.tools)`), `tools.json` - (typed host tools) and `manifest.json` once each (`flag: "wx"`). + (typed host tools) and `manifest.json` once each (`flag: "wx"`). Typed + host tools (`typedTools`, `packages/harness/src/tools.mjs`) are not granted + by tool name: each is built only when the resolved `authority` holds the + action it needs. - **Run tasks.** `scripts/mosaic-task.mjs` validates a mission's `capabilities.tools` as a ceiling and a task's `capabilities.tools` as the allowlist, both drawn from `SUPPORTED_TOOLS`. A task narrows the mission. It never widens it. Nothing on the launch path reads system types today, so every launch gets -exactly its role's tools. That is the coding module's behavior, and the -design keeps it as the default. +its role's tools as narrowed by the layer limits. That is the coding +module's behavior, and the design keeps it as the default. ## Resolution at launch @@ -63,19 +68,27 @@ A launch resolves its toolsets in the host-side launcher, before 4. **Map toolset names to tools.** Each active module's `toolsets` are looked up in the reviewed mapping file (below). The result is a set of tool names, each a member of the role vocabulary `TOOLS` - (`packages/organization/src/vocabulary.mjs`) or a typed host tool that - `typedTools` already knows how to build. -5. **Bound by the ceilings.** The added tools are intersected, in this order, - with: - - the role's `systemTypeTools` ceiling (new, see the proposal); - - every layer's `limits.tools`, exactly as `resolveInstance` already - filters the base tools; - - for a run task, the mission's `capabilities.tools` and then the task's. + (`packages/organization/src/vocabulary.mjs`). Typed host tools cannot be + named: they stay gated by the role's `authority` actions exactly as today, + and a system type never changes `authority`. +5. **Bound by the ceilings.** The role's `tools` stays the hard ceiling for + every effective tool, including any a system type switches on. A role may + hold some of its tools back for typed projects by listing them in + `systemTypeTools` (new, see the proposal), which must be a subset of the + role's `tools`. Then: + - `base` = (role `tools` − `systemTypeTools`), narrowed by every layer's + `limits.tools`, as `resolveInstance` does today; + - `added` = mapped tools ∩ `systemTypeTools`, narrowed by every layer's + `limits.tools` the same way; + - `effective` = `base ∪ added`; + - for a run task, `effective` is then intersected with the mission's + `capabilities.tools` and then the task's. That intersection covers + base tools too, as it does today. - The final set is `base ∪ added`, where `base` is today's result and - `added` has passed every filter above. Base tools are never removed by a - system type, and no added tool can exceed any ceiling. Invariant 7 holds - because each later layer can only remove entries. + Every term is a subset of role `tools` ∩ every layer limit, so a system + type can only switch on a tool the role already holds and the layers + already allow. Invariant 7 holds because each later step can only remove + entries. A role without `systemTypeTools` behaves exactly as today. 6. **Record it.** `resolveInstance` takes the added list as an input and includes `systemTypes: {project, active, dropped, toolsets, added}` in the resolved object, so the digest covers it. `buildBundle` writes the same @@ -119,9 +132,9 @@ Rules a loader enforces, fail-closed: has exactly the key `tools`. - Each toolset name matches `NAME` from `packages/plugins/src/kinds.mjs`, the same pattern modules must use. -- `tools` is a non-empty list of distinct names, each in `TOOLS` or in the - typed-tool names `typedTools` can build. Anything else refuses - `toolset-mapping-invalid` at load. +- `tools` is a non-empty list of distinct names, each in `TOOLS`. A typed + host tool name, or anything else, refuses `toolset-mapping-invalid` at + load. - The file is read from the release copy, like the role files, and its sha256 goes into `manifest.sources`. @@ -139,7 +152,7 @@ them. The repository decides what a type's toolsets may contain. | An active id has no installed module | launch refuses `system-type-missing` | | A module names a toolset the mapping lacks | launch refuses `toolset-unmapped` | | The mapping file is missing, unreadable or invalid | launch refuses `toolset-mapping-invalid`, but only when at least one active type declares a toolset; a launch with nothing to map never reads it | -| A mapped tool is outside the role's `systemTypeTools` ceiling | the tool is dropped and recorded under `dropped`, launch continues | +| A mapped tool is outside the role's `systemTypeTools` (and so not switched on) | the tool is dropped and recorded under `dropped`, launch continues | | The bus cannot answer the project's selection | launch refuses `system-types-unavailable`; it does not fall back to "no types", which could hide a missing toolset the operator expects | | A selection is inactive (disabled in the organization) | dropped and recorded, launch continues | @@ -149,19 +162,21 @@ change what an agent may do refuses instead. ## The coding module Coding declares `toolsets: []`. It adds nothing, and a coding project's agent -keeps exactly its role's tools: for `roles/coder.json` that is -`read, write, edit, bash, grep, find, ls` with network `api-only`, the same as -today. Turning the design on changes nothing for any shipped module until a +keeps its role's tools as the layer limits narrow them: for +`roles/coder.json` the ceiling is `read, write, edit, bash, grep, find, ls` +with network `api-only`, the same as today. Turning the design on changes nothing for any shipped module until a module declares a toolset and a reviewed commit maps it. ## Proposed `roles/` change (not applied) 1. Add an optional V2 key `systemTypeTools` to the role schema (`packages/organization/src/role.mjs`): a distinct list from `TOOLS` (same - check as `checkTools`, but empty is allowed). It is the role's ceiling for - tools a system type may add. Absent means `[]`, so no system type can add - any tool to that role. Every existing role file stays valid and behaves as - today. + check as `checkTools`, but empty is allowed) that must be a subset of the + role's own `tools`, or the role file refuses at load. It names the tools + the role holds back unless an active system type maps them. Absent means + `[]`: nothing is held back and no system type changes that role's tools. + Every existing role file stays valid and behaves as today, and + `checkCreative` keeps inspecting `tools`, which still bounds everything. ```diff const V2_REQUIRED = ["roleVersion", "name", "title", "contract", "tools", "network", "authority", "credentials"]; @@ -174,10 +189,15 @@ module declares a toolset and a reviewed commit maps it. 3. Have `resolveInstance` accept `systemTypes` (the launcher's step 1-4 result) and apply step 5. Have `buildBundle` copy the block into the manifest. `scripts/mosaic-task.mjs` already bounds tools by mission and - task. It would apply the same filter to the added list. + task. It would apply that filter to the final effective set. No contract under `contracts/` changes: the constitution's least-privilege -rule already covers this, and the design adds no new authority. Each of the +rule already covers this. The design adds no grant path: the effective set +stays within role `tools` and every layer limit, and `authority`, network and +credentials are untouched. What it does add is a runtime input (the +project's active system types) that can switch a held-back tool on, so a +role author who lists a tool in `systemTypeTools` is deciding that an +organization owner's enable plus a project's selection may turn it on. Each of the three steps is a reviewed change to role policy and needs Jason's sign-off before it is built. diff --git a/packages/webui/src/public/system-types.js b/packages/webui/src/public/system-types.js index b926f6e12..7996e86e6 100644 --- a/packages/webui/src/public/system-types.js +++ b/packages/webui/src/public/system-types.js @@ -153,11 +153,14 @@ ? `

Inactive, because the organization has disabled them:

${value.writable && !state.archived ? '

Saving keeps only enabled types, so it removes these from the project.

' : ''}
` : ''; const intro = '

This project picks from the system types its organization has enabled. None is required.

'; + const canWrite = value.writable && !state.archived; if (!enabled.length) { - section.innerHTML = `${head}${intro}

The organization has no system types enabled. The owner enables them on the organization dashboard.

${inactive}${status}`; + // With nothing enabled the only change left is clearing what the project still selects. + const clear = canWrite && sel.inactive.length + ? `
` : ''; + section.innerHTML = `${head}${intro}

The organization has no system types enabled. The owner enables them on the organization dashboard.

${inactive}${clear}${status}`; return; } - const canWrite = value.writable && !state.archived; const boxes = enabled.map(m => ``).join(''); const why = state.archived ? '

This project is archived; its selection is shown read only.

' : value.writable ? '' : `

${esc(line('read-only'))}

`; section.innerHTML = `${head}${intro}
Selected system types${boxes}
${inactive}${canWrite ? `` : ''}
${why}${status}`; diff --git a/packages/webui/src/system-types-http.mjs b/packages/webui/src/system-types-http.mjs index d08419d29..732bb0d78 100644 --- a/packages/webui/src/system-types-http.mjs +++ b/packages/webui/src/system-types-http.mjs @@ -99,13 +99,22 @@ export async function systemTypesHTTP(req, res, { path, read, write, session, li if (req.method === 'GET') { let revision = null; if (write && project === null) { - try { revision = (await write('plugins', {}))?.revision ?? null; } catch (error) { return fail(error); } - if (!REVISION.test(revision ?? '')) return refuse(503, 'outcome-unknown'); + // The enabled set and its revision come from one plugins read. The page sends back a whole + // replacement list, so a list older than its revision would undo a change made in between. + let plugins; + try { plugins = await write('plugins', {}); } catch (error) { return fail(error); } + revision = plugins?.revision ?? null; + const enabled = plugins?.plugins?.['system-type'] ?? []; + if (!REVISION.test(revision ?? '') || !names(enabled)) return refuse(503, 'outcome-unknown'); + current.enabled = enabled; } if (live() !== session) return refuse(401, 'sign-in-required'); return json(res, 200, { ...current, writable: Boolean(write), ...(project === null && write ? { revision } : {}) }); } + // The session is checked again after the read: a sign-out while it ran dispatches no write. + if (live() !== session) return refuse(401, 'sign-in-required'); + if (project === null) { if (args.enabled.some(id => !installed.has(id))) return refuse(400, 'system-type-unknown'); let result; diff --git a/packages/webui/tests/system-types-browser.test.mjs b/packages/webui/tests/system-types-browser.test.mjs index d3b707974..e7b26a82f 100644 --- a/packages/webui/tests/system-types-browser.test.mjs +++ b/packages/webui/tests/system-types-browser.test.mjs @@ -157,7 +157,24 @@ test('a project selects only enabled modules and a disabled selection shows as i assert.match(await text(b, '[data-project-system-types]'), /The organization has no system types enabled\./); assert.deepEqual(await b.evaluate(`[...document.querySelectorAll('[data-inactive-type]')].map(li => li.dataset.inactiveType)`), ['marketing']); assert.equal(await b.evaluate(`document.querySelectorAll('[data-project-system-types] input').length`), 0); + // With nothing enabled the owner can still clear the inactive selection, without enabling a type first. + assert.equal(await text(b, '[data-project-system-types] button[type=submit]'), 'Clear the inactive types'); + await click(b, '[data-project-system-types] button[type=submit]'); + await wait(`/Saved/.test(document.querySelector('[data-project-system-types-status]')?.textContent)`); + assert.equal(await text(b, '[data-project-system-types-status]'), 'Saved. No system types selected.'); + assert.deepEqual(st.state.projects[P], []); + assert.deepEqual(st.state.enabled, []); + assert.equal(await b.evaluate(`document.querySelector('[data-inactive-type]')`), null); + assert.equal(await b.evaluate(`document.querySelector('[data-project-system-types] button[type=submit]')`), null); assert.deepEqual(p.errors, []); + + // A read-only Console shows the same inactive selection and offers no clear button. + const readOnly = await systemTypesFake({ enabled: [], projects: { [P]: ['coding'] } }); + const q = await page(t, readOnly, { send: false }); + await settings(q); + assert.deepEqual(await q.b.evaluate(`[...document.querySelectorAll('[data-inactive-type]')].map(li => li.dataset.inactiveType)`), ['coding']); + assert.equal(await q.b.evaluate(`document.querySelector('[data-project-system-types] button[type=submit]')`), null); + assert.deepEqual(readOnly.state.writes, []); }); test('the dashboard section and the project page fit a phone screen in light and dark', { timeout: 90000 }, async t => { diff --git a/packages/webui/tests/system-types-http.test.mjs b/packages/webui/tests/system-types-http.test.mjs index c0b6dd1fa..90ced42b9 100644 --- a/packages/webui/tests/system-types-http.test.mjs +++ b/packages/webui/tests/system-types-http.test.mjs @@ -19,7 +19,7 @@ import { close } from './fixture.mjs'; // ephemeral organization with the real runtime writer (plugins.set, the system types owner fence, // changes.jsonl) and the broker's console socket for the read; the SSO session is a fixture // authority. `writer` picks the cap the write transport binds: the owner's human cap, or the tester. -async function fixture(t, { writer = 'owner', send = true } = {}) { +async function fixture(t, { writer = 'owner', send = true, afterRead = null, beforeWrite = null } = {}) { // Cleanups run last-made first, registered as soon as each resource exists. const undo = []; t.after(async () => { for (const step of undo.reverse()) await step(); }); const root = mkdtempSync(join(tmpdir(), 'st-')); @@ -43,8 +43,9 @@ async function fixture(t, { writer = 'owner', send = true } = {}) { const cap = writer === 'tester' ? runtime.broker.bindTester({ business: 'demo' }) : writer === 'agent' ? runtime.broker.bindLaunch({ business: 'demo', role, run: 'agent-run', harness: 'pi' }) : owner; const calls = []; - const requestRead = (verb, args, ctx) => { calls.push(['read', verb]); return new Client({ path, console: { subject: ctx.subject } }).call(verb, args); }; - const systemTypesWrite = async (verb, args) => { calls.push(['write', verb]); return runtime.broker.request(cap, { verb, args }); }; + // afterRead and beforeWrite let a test act between the route's read and its write. + const requestRead = async (verb, args, ctx) => { calls.push(['read', verb]); const r = await new Client({ path, console: { subject: ctx.subject } }).call(verb, args); await afterRead?.(); return r; }; + const systemTypesWrite = async (verb, args) => { await beforeWrite?.(verb); calls.push(['write', verb]); return runtime.broker.request(cap, { verb, args }); }; const session = { provider: 'fixture', iss: 'https://issuer.example', sub: 'owner', name: 'jason' }; let active = true; const sso = { publicOrigin: '', publicHost: '', formTargets: () => [], session: () => active ? session : null, handle: () => {}, health: () => ({}) }; @@ -59,7 +60,8 @@ async function fixture(t, { writer = 'owner', send = true } = {}) { undo.push(() => close(web)); const project = runtime.broker.request(owner, { verb: 'project.create', args: { name: 'example' } }).id; const onDisk = () => JSON.parse(readFileSync(file)).plugins['system-type']; - return { base, file, project, calls, onDisk, signOut: () => { active = false; } }; + const ownerRequest = (verb, args) => runtime.broker.request(owner, { verb, args }); + return { base, file, project, calls, onDisk, ownerRequest, signOut: () => { active = false; } }; } function call(f, path, method = 'GET', body, headers = {}) { @@ -131,6 +133,37 @@ test('the admission checks refuse before any write', async t => { assert.deepEqual(f.onDisk(), ['coding']); }); +test('a sign-out while the read runs dispatches no write on either route', async t => { + let signOutOnRead = false; + const f = await fixture(t, { afterRead: () => { if (signOutOnRead) f.signOut(); } }); + const [, { revision }] = await call(f, ORG); + signOutOnRead = true; + const writes = () => f.calls.filter(c => c[0] === 'write' && c[1] !== 'plugins').length; + for (const [path, body] of [[ORG, { revision, enabled: [] }], [`${ORG}/projects/${f.project}`, { systemTypes: ['coding'] }]]) { + const [status, result] = await call(f, path, 'POST', body); + assert.deepEqual([status, result.error], [401, 'sign-in-required'], path); + } + assert.equal(writes(), 0); + assert.deepEqual(f.onDisk(), ['coding']); +}); + +test('the enabled set and its revision come from one read, so a change in between is not undone', async t => { + let raced = false; + const f = await fixture(t, { beforeWrite: async verb => { + // Another owner action enables Marketing after the route's Console read and before its plugins read. + if (verb !== 'plugins' || raced) return; + raced = true; + const { revision } = await f.ownerRequest('plugins', {}); + await f.ownerRequest('plugins.set', { revision, plugins: { 'system-type': ['coding', 'marketing'] } }); + } }); + const [, view] = await call(f, ORG); + assert.equal(raced, true); + assert.deepEqual(view.enabled, ['coding', 'marketing']); + const [saved, receipt] = await call(f, ORG, 'POST', { revision: view.revision, enabled: view.enabled.filter(x => x !== 'coding') }); + assert.equal(saved, 200, JSON.stringify(receipt)); + assert.deepEqual(f.onDisk(), ['marketing']); +}); + test('without the owner human proof the enable switch is refused', async t => { // A Console without --send has no write transport: the read works, the write is read-only. const readOnly = await fixture(t, { send: false });