diff --git a/docs/TOOLS.md b/docs/TOOLS.md index 33dd7d6b9..8800a03ee 100644 --- a/docs/TOOLS.md +++ b/docs/TOOLS.md @@ -220,6 +220,9 @@ abandon it) · `4` usage. Details: `packages/queue/README.md`. ```bash scripts/mosaic business validate scripts/mosaic business resolve [--project ] +scripts/mosaic business instances [--json] +scripts/mosaic business instance add --definition [--vars ] [--launch] --revision +scripts/mosaic business instance set [--definition ] [--vars ] [--launch | --no-launch] --revision ``` Reads `businesses/.json` next to the system config @@ -234,6 +237,20 @@ Exit codes: `0` ok · `2` invalid file or credential reference · `3` system config problem · `4` usage or a required file missing. Details: `packages/business/README.md`. +`instances` and `instance add|set` (row 165) go to `packages/cli` and the +bus's human-only `instances` and `instances.set` verbs, so they need a live +bus host and refuse inside an agent session. `instances` prints the revision, +each instance and the definitions `add` and `set` accept. `add` and `set` +write the business file under that revision and log the change with you as +the actor. They bind no credentials: a definition that declares credentials, +or a definition change on an instance that holds them, is refused with +`organization-credentials-out-of-scope` and stays a hand edit. After an add +or a definition change the output says a bus restart is needed; the restart +needs Mos's go or Jason's hand, and the command doesn't run it. Exit codes: +`0` ok · `2` refused, nothing written · `3` human proof refused · `4` usage. +The Console's Settings page has the same two forms. Details: +`packages/cli/README.md`. + ## Inbox, decisions and the bus host (`scripts/mosaic`) ```bash diff --git a/docs/acceptance/314.md b/docs/acceptance/314.md index c652fc01c..3611cce31 100644 --- a/docs/acceptance/314.md +++ b/docs/acceptance/314.md @@ -25,9 +25,22 @@ bus schema. - `mosaic inbox` shows no open decision. If one is open, resolve or supersede it first, so step 6 starts from an empty inbox. - The business has security-reviewer and merge-gate instances, and both - are in `launch.instances`. No verb adds an instance today, so Jason adds - them by editing the business file, then runs - `scripts/mosaic business validate `. + are in `launch.instances`. Jason adds them with the row 165 command (or + the Console's Settings page), reading the revision first, then runs + `scripts/mosaic business validate `: + + ``` + scripts/mosaic business instances + scripts/mosaic business instance add security-reviewer --definition security-reviewer --launch --revision + scripts/mosaic business instances + scripts/mosaic business instance add merge-gate --definition merge-gate --launch --revision + scripts/mosaic business validate + ``` + + Each add prints the new revision, so the second add can take it instead + of a second read. Both adds say a bus restart is needed. The running bus + only learns the new instances at restart, which needs Mos's go or Jason's + hand. - `arbiters.technical` is `cto`, which step 5 assumes. ## Steps diff --git a/packages/bus/README.md b/packages/bus/README.md index 8518187dd..7867cdbe6 100644 --- a/packages/bus/README.md +++ b/packages/bus/README.md @@ -571,6 +571,20 @@ refuses `message-not-found`; malformed arguments refuse `invalid-request`. Roles get `human-required`. A successful read records nothing, so Console history reads never prevent a later `message.receive` from delivering it. +`instances` and `instances.set` (row 165, #1662, Q171, REQ-ROLE-3) are human-only. +A role session, a reader and a tester each get `human-required`, and the chief of staff +does too: neither verb is in `ORGANIZATION_KEYS`, so `organization.set` refuses the instance +keys with `invalid-request` before the writer runs (sage-0918). `instances` takes no args and +answers the business's instances, their definitions, vars and launch membership, plus the +definitions `instances.set` accepts. `instances.set` takes `{revision,instance,op,definition?, +vars?,launch?}`. `op` is `add` or `change`, and every other key is `invalid-request`. The +business package's `instance-settings.mjs` writes through the organization writer, which +logs the human as the actor. Its refusals pass through as `organization-*` codes, among them +`organization-credentials-out-of-scope` for a definition that declares credentials. The answer +carries `restart: true` after an add or a definition change: the broker keeps the roles it +loaded at start, so the change counts only after a restart that needs Mos's go or Jason's +hand. Tests: `packages/bus/tests/instances-verb.test.mjs`. + A tester (row 110, #1604) is a PM test's sender, never the human. `src/tester-cli.mjs ` is human-cli.mjs with its own nonce variable, `MOSAIC_BUS_TESTER_NONCE`, so neither shim's nonce proves the other. `verifyTester` (`src/tester.mjs`) checks the same process proof but walks the ancestry for a managed run only: a launch record, `MOSAIC_RUN_ID`, `MOSAIC_BUS_CAP` or `MOSAIC_AGENT_RUN` refuses `tester-required`. Claude and Codex markers pass, since a tester runs from inside Mos or a T3 seat. A role session can't bind: its shim reports a pid from the sandbox's PID namespace, and the seat sandbox test runs that case under bwrap. `bindTester` then binds only when the business var `bus.tester` is exactly `true`, read at bus start, else `tester-off`. A request carries exactly one of `cap`, `human` or `tester`. The session may use `message.send`, `message.receive` and `message.read`, plus the reader's views of `inbox`, `agents`, `tasks`, `trail`, `decisions`, `messages` and `replies`; every other verb refuses `tester-refused`. It sends only to a role, with a body that starts `[mos test]` (`tester-prefix`) and no `corrects` or `decision`. Its message is stored `from_role 'tester'`, `from_run 'tester-cli'`, with no request and no event, so no `human.input` backs it and `task_create` can't cite it. A role answers at the `tester` address, and only with `in_reply_to` naming a tester's message (`tester-reply-required`); the human can't send there. Those replies never reach the human's `message.receive` or `messages`. ## Shared reads and adapter boundary diff --git a/packages/bus/src/broker.mjs b/packages/bus/src/broker.mjs index 48394fa67..76f7dfaea 100644 --- a/packages/bus/src/broker.mjs +++ b/packages/bus/src/broker.mjs @@ -134,6 +134,8 @@ const oid = (x) => typeof x === 'string' && /^[0-9a-f]{40}([0-9a-f]{24})?$/.test // Row 123 (#1617): the one list of organization-file keys limits.set and organization.set accept. // Row 155 (#1649) adds assistants: an assistant instance's vars, tracker and definition. export const ORGANIZATION_KEYS = ['revision', 'limits', 'models', 'instances', 'reset', 'assistants']; +// Row 165 (#1662): the keys of the human-only instances.set (business instance-settings.mjs). +const INSTANCE_KEYS = ['revision', 'instance', 'op', 'definition', 'vars', 'launch']; // Row 123 (#1617): role.end never reaches the caller's own run. END_PROTECTED (vocabulary.mjs, row // 155): only the chief of staff, or a decision the human resolved through the CLI, ends or revokes // an instance of one (#protectedEnd, Q169). A raise to revoke one is a hard wait. @@ -1154,15 +1156,18 @@ export class Broker { return this.#requestProject(s, { verb: request.verb, args: structuredClone(args) }); if (PROJECT_FILE_VERBS.includes(request.verb)) return this.#requestProjectFile(s, { verb: request.verb, args: structuredClone(args) }); - if (["limits", "limits.set", "organization.set", "plugins", "plugins.set"].includes(request.verb)) { + if (["limits", "limits.set", "organization.set", "plugins", "plugins.set", "instances", "instances.set"].includes(request.verb)) { // Row 123 (#1617, REQ-COS-1, REQ-LIMIT-1): organization.set is limits.set for a role whose // file lists organization.change. It takes the same keys, runs the same write path and // logs the same receipt; only the actor differs: the role definition and instance. const role = request.verb === "organization.set"; if (!role && !s.human) fail("human-required"); if (!this.#organization) fail("not-configured"); - if (["limits", "plugins"].includes(request.verb)) keys(args, []); + if (["limits", "plugins", "instances"].includes(request.verb)) keys(args, []); else if (request.verb === "plugins.set") keys(args, ["revision", "plugins"], ["revision", "plugins"]); + // Row 165 (#1662): instances.set is human-only and outside ORGANIZATION_KEYS, so + // organization.set and the chief of staff's tool never reach it (sage-0918). + else if (request.verb === "instances.set") keys(args, INSTANCE_KEYS, ["revision", "instance", "op"]); else keys(args, ORGANIZATION_KEYS, ["revision"]); let actor = s.human; // This branch runs outside the store transaction below, so the grant is checked before the writer diff --git a/packages/bus/src/runtime.mjs b/packages/bus/src/runtime.mjs index ae4a3070e..f226304f0 100644 --- a/packages/bus/src/runtime.mjs +++ b/packages/bus/src/runtime.mjs @@ -9,6 +9,7 @@ import { launchSettings } from '../../business/src/launch-settings.mjs'; import { readSessions } from '../../seat/src/session.mjs'; import { createLoader, hasModule } from '../../plugins/src/loader.mjs'; import { pluginSettings } from '../../business/src/plugin-settings.mjs'; +import { instanceSettings } from '../../business/src/instance-settings.mjs'; import { webService } from './web.mjs'; import { verifyHuman } from './human.mjs'; import { createUsage } from './usage.mjs'; @@ -66,6 +67,8 @@ export async function startBroker({ // plugins and plugins.set, logged in changes.jsonl with the actor, a missing module refused. const plugins=organization?pluginSettings({dir:organization.dir,rolesDir:organization.rolesDir,exists:hasModule}):null; const settings=organization?launchSettings({...organization,sessions:()=>readSessions(dataRoot)}):null; + // Row 165 (#1662): the human adds and changes role instances through instances and instances.set. + const instances=organization?instanceSettings({dir:organization.dir,rolesDir:organization.rolesDir,system:organization.system}):null; const usage = await createUsage({ store, dataRoot, businesses, log: entry => process.stderr.write(`usage: ${JSON.stringify(entry)}\n`) }); // Row 125 (#1619, REQ-LIMIT-3, REQ-LIMIT-4): the limit checks read the organization file at @@ -93,6 +96,8 @@ export async function startBroker({ if(verb==='limits')return withTokens(id,settings.read(id)); if(verb==='limits.set')return withTokens(id,settings.set(id,args,actor)); if(verb==='plugins')return plugins.read(id); + if(verb==='instances')return instances.read(id); + if(verb==='instances.set')return instances.set(id,args,actor); const result=plugins.set(id,args,actor); limits.refresh(id).catch(e=>limitLog({event:'limit-refresh-failed',business:id,message:e.message})); return result; diff --git a/packages/bus/tests/channel-proof.test.mjs b/packages/bus/tests/channel-proof.test.mjs index 4ea8746ec..797a120dd 100644 --- a/packages/bus/tests/channel-proof.test.mjs +++ b/packages/bus/tests/channel-proof.test.mjs @@ -11,7 +11,11 @@ const baselines = { "packages/bus/src/human.mjs": "b995fc5cff3af8ade4c990d0e3bebf9d83829e00f034ebc9c3dcfd05f252b573", "packages/bus/src/human-cli.mjs": "269c3a66008c0d57a54b14b73cf988d5f61f5e815455486296716e98ce5e8073", "packages/cli/src/transport.mjs": "5129c44b4d9f642e825344df65c9bfb4bac4fc8d6b25343b42d39853dbd40774", - "packages/webui/src/bus.mjs": "d1f3a274f7aa15eb7ecc2267c65bf4fe7e45c898f77c34235b4e9c29cd1be241", // Row 155 (#1649): eight STATUS entries for the assistant routes, no proof or transport change + // Row 165 (#1662): seven STATUS entries for the role instance routes (organization-instance-exists, + // organization-unknown-instance, organization-credentials-out-of-scope, organization-launch-not-configured, + // organization-no-change, organization-project-mismatch, organization-unresolvable-instance), no proof or + // transport change. Row 155 (#1649) added eight for the assistant routes. + "packages/webui/src/bus.mjs": "dfbc2289337376b94a399a61599fd4af402b802deb2267dcffc5cf23502c9a4c", }; const repoFile = path => new URL("../../../" + path, import.meta.url); diff --git a/packages/business/README.md b/packages/business/README.md index ead6538d1..030f2fa46 100644 --- a/packages/business/README.md +++ b/packages/business/README.md @@ -357,3 +357,52 @@ For inherited selections, print-only migration reads the existing system config through its normal validator and requires an exact provider/model match. Missing or invalid config refuses; it never changes the system config. Explicit role models retain their external model and use the human-supplied provider table. + +### Role instances (row 165, #1662) + +Q171 and REQ-ROLE-3 let the human add a role instance and change an existing +one's definition, vars and launch membership without a hand edit. +`src/instance-settings.mjs` is that writer. The bus reaches it through the +human-only verbs `instances` and `instances.set`. Neither is in the broker's +`ORGANIZATION_KEYS`, so `organization.set` and the chief of staff's +`change_organization` can't reach it (sage-0918). + +`read` returns the file's revision, each instance (`definition`, `vars`, +`launched`, `launcher`, `protected`), whether the file has a launch block, and +each definition in the roles directory with the services its credentials name +and whether `add` and `set` accept it. `set` takes: + +```json +{ "revision": "<64 hex>", "instance": "sec-1", "op": "add", "definition": "security-reviewer", "vars": {}, "launch": true } +``` + +- `add` needs `definition`; `change` needs at least one of `definition`, + `vars` and `launch`. `vars` replaces the instance's vars whole. `launch` + adds the instance to `launch.instances` or removes it. Any other key is + `invalid-request`, so `holder`, `credentials` and `tracker` stay hand edits. + There is no delete. +- A definition that declares credentials refuses with + `organization-credentials-out-of-scope` (the brief's named refusal, sage-0922). + So does a definition change on an instance whose definition declares them, + because its credentials would bind to the new definition's authority. The + writer never writes an instance without its binding. A vars or launch change + on such an instance succeeds and leaves `credentials` and `tracker` as they + are. +- An `END_PROTECTED` definition, given or held, refuses with + `organization-definition-refused`; the assistant changes through + `assistants` above. +- `organization-instance-exists`, `organization-unknown-instance`, + `organization-launch-not-configured` and `organization-no-change` refuse + what their names say. +- The whole next document goes through `validateBusinessDocument`, the model + check, and each project file's id and instance resolution + (`organization-project-mismatch`, `organization-unresolvable-instance`), + the checks `mosaic business validate` runs. +- The organization writer then refuses a stale revision + (`revision-conflict`) and logs the change with the actor. + +A refusal writes nothing and logs nothing. The answer is the read with the +`transaction` and `restart`. `restart` is true after an add or a definition +change: the running broker keeps the roles it loaded at start. The writer +doesn't restart anything. The CLI (`mosaic business instance add|set`) and the +Console Settings page send the patch. diff --git a/packages/cli/README.md b/packages/cli/README.md index 38a2ac7a4..b32a8d3e2 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -854,6 +854,57 @@ mappings refuse. Every held role must map too. A migrated file prints unchanged. Jason installs the output himself in Mos's window with the PM run idle, and the re-pin follows in the same window (decision 145). +## Role instances + +Row 165 (#1662, Q171, REQ-ROLE-3). + +``` +mosaic business instances BUSINESS [--json] +mosaic business instance add BUSINESS INSTANCE --definition DEF [--vars FILE] [--launch] --revision REV +mosaic business instance set BUSINESS INSTANCE [--definition DEF] [--vars FILE] [--launch | --no-launch] --revision REV +``` + +`scripts/mosaic` sends `business instances` and `business instance` here and +every other `business` command to `packages/business`. `instances` prints the +file's revision, each instance with its definition and its marks (`launcher`, +`launched`, `protected`), the definitions `add` and `set` accept, and the +definitions that declare credentials. `add` and `set` send the bus's +human-only `instances.set` verb. `set` needs at least one of `--definition`, +`--vars` and a launch flag. `--vars FILE` is a JSON object that replaces the +instance's vars whole. `--launch` and `--no-launch` add the instance to +`launch.instances` or remove it. + +The business package's instance writer runs the checks `mosaic business +validate` runs before it writes, and logs the change in `changes.jsonl` with +the human as actor. It refuses, and the file keeps its bytes: + +| Code | When | +|---|---| +| `organization-credentials-out-of-scope` | the definition declares credentials, or a definition change on an instance that holds them | +| `organization-instance-exists` | `add` names an instance the file has | +| `organization-unknown-instance` | `set` names an instance the file lacks | +| `organization-definition-refused` | an assistant definition or instance; those change through `mosaic limits set` | +| `organization-launch-not-configured` | a launch flag when the file has no launch block | +| `organization-no-change` | the file already says that | +| `organization-project-mismatch`, `organization-unresolvable-instance` | the change would fail `mosaic business validate` against a project file | +| `revision-conflict` | the file changed since `--revision` | + +The bus sends a refusal's code alone, so the command adds the reason. A +refusal exits 2; an agent session or a non-human transport exits 3; a usage +error exits 4 before any bus call. + +The commands bind no credentials. A definition that declares them needs +`credentials` and a `tracker` bot in the instance, and those, with `holder`, +stay hand edits of the business file. A vars or launch change on an instance +that holds credentials succeeds and leaves them as they are. There is no +delete. + +An add or a definition change prints `restart needed`: the running bus keeps +the roles it loaded at start; this command does not restart it. The output +names no one; the restart itself needs Mos's go or Jason's hand. A vars or launch change +prints `no restart`, because the launcher reads it at its next launch check. +The Console Settings page has the same read and write (`packages/webui`). + ## Token usage `mosaic usage [--business ID] [--json]` reads the bus's accounting, without diff --git a/packages/cli/src/cli.mjs b/packages/cli/src/cli.mjs index a56a1b118..6a4f68be6 100644 --- a/packages/cli/src/cli.mjs +++ b/packages/cli/src/cli.mjs @@ -17,6 +17,7 @@ import { projectBusCommand, projectCommand, PROJECT_BUS_USAGE, PROJECT_USAGE } f import { resolveThread, threadCommand, threadMembers, threadsCommand, THREAD_TALK_USAGE, THREAD_USAGE, THREADS_USAGE } from "./thread.mjs"; import { limitsCommand, LIMITS_USAGE } from "./limits.mjs"; import { pluginsCommand, PLUGINS_USAGE } from "./plugins.mjs"; +import { instancesCommand, INSTANCES_USAGE } from "./instances.mjs"; import { createChannelCaller } from "../../plugins/src/channel.mjs"; import { PluginError } from "../../plugins/src/kinds.mjs"; import { CliError } from "./errors.mjs"; @@ -37,6 +38,7 @@ export const USAGE = `usage: ${USAGE_USAGE} ${LIMITS_USAGE} ${PLUGINS_USAGE} + ${INSTANCES_USAGE} ${PROJECT_USAGE} ${PROJECT_BUS_USAGE} ${THREADS_USAGE} @@ -568,6 +570,8 @@ export async function main(argv, io = { env: process.env, stdin: process.stdin, if (verb === "limits") return limitsCommand(rest,io,p=>callFor(p,io,deps)); if (verb === "usage") return usageCommand(rest, io, p => callFor(p, io, deps)); if (verb === "plugins") return pluginsCommand(rest, io, (p) => callFor(p, io, deps)); + // Row 165 (#1662): scripts/mosaic sends only `business instances` and `business instance` here. + if (verb === "business") return instancesCommand(rest, io, (p) => callFor(p, io, deps)); if (verb === "talk") return talk(rest, io, deps); if (verb === "follow") return talk(rest, io, deps, true); if (verb === "name" || verb === "names") return names(verb, rest, io, deps); diff --git a/packages/harness/tests/tools.test.mjs b/packages/harness/tests/tools.test.mjs index 9a2b8ee6c..fd5d5ef03 100644 --- a/packages/harness/tests/tools.test.mjs +++ b/packages/harness/tests/tools.test.mjs @@ -143,6 +143,20 @@ test("a role without role.end or organization.change gets neither tool, and each assert.deepEqual(names(typedTools({ resolved: only("organization.change") })).filter((n) => n === "end_run" || n === "change_organization"), ["change_organization"]); }); +// Row 165 (#1662, sage-0918): instances and instances.set are the human's. No role's tools send +// either verb, and change_organization takes none of the instance write's keys, so the chief of +// staff can't add or change an instance through it. +test("no role's tools send instances or instances.set, and change_organization takes no instance write keys", (t) => { + const assistant = resolvedFor(t, "assistant", (d) => (d.roles.assistant = { definition: "assistant", holder: "mos" })); + for (const [who, resolved] of [...["chief", "pm", "coder", "reviewer"].map((i) => [i, resolvedFor(t, i)]), ["assistant", assistant]]) { + const tools = typedTools({ resolved, arbiter: true, tracker: true }); + assert.deepEqual(tools.filter((x) => x.verb === "instances" || x.verb === "instances.set").map((x) => x.name), [], who); + assert.equal(untypedActions(resolved, tools).some((a) => a.startsWith("instances")), false, who); + } + const change = typedTools({ resolved: resolvedFor(t, "chief"), tracker: true }).find((x) => x.name === "change_organization"); + for (const key of ["instance", "op", "definition", "vars", "launch"]) assert.equal(Object.hasOwn(change.parameters.properties, key), false, key); +}); + // Row 119 gave the assistant message.send; row 138 adds record.write. test("the assistant gets send_message, the reads and the web tools (it holds the web grant), no launch", (t) => { const assistant = resolvedFor(t, "assistant", (d) => (d.roles.assistant = { definition: "assistant", holder: "mos" })); diff --git a/packages/webui/README.md b/packages/webui/README.md index 203325059..ce8500605 100644 --- a/packages/webui/README.md +++ b/packages/webui/README.md @@ -538,6 +538,41 @@ Any other method is 405. An answer is the bus's result with `at`. A bus refusal names the route, the user and the instance, and the outcome: `done` or the code. A Console started inside an agent run gets `human-required` from the broker. +## Role instances (row 165, #1662) + +Q171 (REQ-ROLE-3) lets the human add a role instance and change one's definition, vars and +launch membership from the Console. Settings shows a Role instances section, read through +`/api/bus/instances`: a table of each instance with its definition, whether it is launched +(or is the launcher) and its vars, then two forms. + +- Add an instance: a name, a definition from the ones the writer accepts, vars as JSON and, + when the file has a launch block, a Launch it box. +- Change an instance: any instance except an assistant, which changes in the Assistant + section. The definition, the vars (replacing them whole) and launch can change; a field + left as Keep or empty is not sent. + +Definitions that declare credentials are not offered. The section names them, with their +services, as hand edits of the business file, because the Console binds no credentials. +Each form sends one POST `/api/instances` under the revision the page read. When the answer +says a bus restart is needed, the receipt says so and that the Console does not restart it; +the page has no restart control. Without `--send` every control is off. A +refusal shows the code and the reason and keeps the draft; a lost answer says to read the +instances again. Nothing is sent again on its own. + +Route: POST `/api/instances` exists only under `--send` and calls the human-only +`instances.set` through the human transport. It has the Settings boundary: the signed-in +user's header (401 without it), the exact `https://` Origin and +`Sec-Fetch-Site: same-origin` (403), and a JSON object of at most 16 KiB (400). It takes +exactly `revision` (64 hex), `instance`, `op` (`add` or `change`) and any of `definition`, +`vars` (an object) and `launch` (a boolean); any other key, `holder`, `credentials` and +`tracker` included, is 400 before the bus. Any other method is 405. An answer is the bus's +result with `at`. The bus sends a refusal's code alone, so the route adds the reason: +`{error, message, sent:false}`, where the message is the code, the reason and "Nothing +changed." `revision-conflict` and `organization-instance-exists` are 409, +`human-required` 403 and the other refusals 400. A lost or unusable answer is 503 with +`sent:"unknown"`. The log line names the user, the instance and the outcome (`done +restart=true|false` or the code), never the vars. + ## Data and boundaries GET `/api/board`, `/api/conversations` and `/api/conversation`, and POST @@ -551,6 +586,7 @@ session reader or transport is implemented here. The session reader is GET `/api/bus/inbox`, `/api/bus/tasks`, `/api/bus/agents`, `/api/bus/trail?subject=`, `/api/bus/decisions?list=roles|recent`, `/api/bus/credentials`, `/api/bus/names` (row 155, each instance's seat name), +`/api/bus/instances` (row 165, the role instances and the definitions `add` accepts), `/api/bus/replies?id=` and `/api/bus/messages?limit=50&after=` are the bus reads (`src/bus.mjs`). Any other method is 405. The subject and the id must diff --git a/packages/webui/src/bus.mjs b/packages/webui/src/bus.mjs index 6c61dc52d..fee95a829 100644 --- a/packages/webui/src/bus.mjs +++ b/packages/webui/src/bus.mjs @@ -96,5 +96,9 @@ const STATUS = { // is the user's to resolve by reading again. 'organization-not-assistant': 400, 'organization-definition-refused': 400, 'unknown-model': 400, 'name-taken': 409, 'name-is-instance': 400, 'name-is-role': 400, 'not-assistant': 400, 'not-held': 409, + // Row 165 (#1662): role instances. An id already taken is the user's to resolve by reading again. + 'organization-instance-exists': 409, 'organization-unknown-instance': 400, + 'organization-credentials-out-of-scope': 400, 'organization-launch-not-configured': 400, + 'organization-no-change': 400, 'organization-project-mismatch': 400, 'organization-unresolvable-instance': 400, }; export const busStatus = code => STATUS[code] ?? 502; diff --git a/packages/webui/src/cli.mjs b/packages/webui/src/cli.mjs index 57bfb6b9a..7d7cf3d5c 100644 --- a/packages/webui/src/cli.mjs +++ b/packages/webui/src/cli.mjs @@ -52,18 +52,19 @@ try { // the system config, Business can't resolve authority and Settings has // no notifier. A refusal printed here names no path (redactor). // --send without a bus refuses to start rather than serve a composer that can't send. - let bus = null, send = null, settingsWrite = null, projectFiles = null, projectFile = null, projectSave = null, chat = null, nameWrite = null, assistantStop = null, busLine, system = null; + let bus = null, send = null, settingsWrite = null, projectFiles = null, projectFile = null, projectSave = null, chat = null, nameWrite = null, assistantStop = null, instancesWrite = null, busLine, system = null; try { system = loadSystem(); const { dataRoot } = system; const call = busCaller({ dataRoot, socket: socketPath(dataRoot), business: options.business ?? null }); chat = createChat({ call }); - // Row 155 (#1649): `names` is a webui read only, so it sits beside the shared views. - bus = { ...views({ call }), names: () => call('names') }; + // Row 155 (#1649): `names` is a webui read only, so it sits beside the shared views. Row 165 + // (#1662): so is `instances`, and its write `instances.set` is only under --send. + bus = { ...views({ call }), names: () => call('names'), instances: () => call('instances') }; // Row 148: the spec and docs editor reads like the other reads and saves only under --send. projectFiles = args => call('project.files', args); projectFile = args => call('project.file', args); - if (sendOn) {send = args => call('message.send', args);settingsWrite=args=>call('limits.set',args);projectSave=args=>call('project.file.save',args);nameWrite=args=>call('name.set',args);assistantStop=args=>call('assistant.stop',args);} + if (sendOn) {send = args => call('message.send', args);settingsWrite=args=>call('limits.set',args);projectSave=args=>call('project.file.save',args);nameWrite=args=>call('name.set',args);assistantStop=args=>call('assistant.stop',args);instancesWrite=args=>call('instances.set',args);} busLine = `Bus: ${options.business ?? 'the running bus host\'s business'}`; } catch (err) { const why = redactor({ configDir: configDir() })(err.message); @@ -71,7 +72,7 @@ try { busLine = `Bus: not configured (${why})`; } const reads = consoleReads({ root: REPO, queueRoot: options.checkout ?? REPO, system, configDir: configDir(), rolesDir: rolesDir(), business: options.business ?? null }); - const server = await startServer({ board: options.board, port: options.port, bus, reads, preview: options.preview, send, settingsWrite, projectFiles, projectFile, projectSave, chat, nameWrite, assistantStop }); + const server = await startServer({ board: options.board, port: options.port, bus, reads, preview: options.preview, send, settingsWrite, projectFiles, projectFile, projectSave, chat, nameWrite, assistantStop, instancesWrite }); const previewLine = options.preview ? `\nPreview: https://${options.preview.host}/ through the proxy, signed-in user from ${options.preview.header}, ${send ? 'reads and human messages to roles (--send); one line per send below' : 'read-only'}` : ''; const queueLine = options.checkout ? '\nQueue: read from the --checkout directory' : ''; console.log(`Mosaic Console: http://127.0.0.1:${server.address().port}/\nBoard: ${options.board}\n${busLine}${queueLine}${previewLine}\nCtrl-C stops this server.`); diff --git a/packages/webui/src/public/bus.js b/packages/webui/src/public/bus.js index 1e0be849d..67abd41f6 100644 --- a/packages/webui/src/public/bus.js +++ b/packages/webui/src/public/bus.js @@ -671,17 +671,70 @@ await assistantPost('/api/name',{instance,name},instance,result=>{if(typeof result?.name!=='string')return unknownAssistant;delete nameDrafts[instance];const prior=last.get('names');if(prior)last.set('names',{...prior,rows:[...prior.rows.filter(r=>r.instance!==result.instance),{instance:result.instance,name:result.name,at:result.at}]});return `Seat name set to ${result.name}.`;});} else if(e.target.dataset.assistantStop!==undefined)await assistantPost('/api/assistant-stop',{instance},instance,result=>Array.isArray(result?.stopped)?`Stopped ${plural(result.stopped.length,'run')}.`:unknownAssistant); }); + // Row 165 (#1662, Q171): role instances. Add one, or change one's definition, vars and launch + // membership, with the read's revision. A definition that declares credentials is named but not + // offered: binding credentials stays a hand edit. When a change needs a bus restart the receipt + // says so; the Console never restarts the bus. Drafts survive polling and refusals; nothing retries. + let instanceView=null, instanceDrafts={add:null,change:null}, instanceBusy=false, instanceReceipt=''; + const RESTART_TEXT='Restart needed: the running bus keeps the roles it loaded at start. The Console does not restart it.'; + const NO_RESTART_TEXT='No restart: the launcher reads the change at its next launch check.'; + function instancesSection(view){ + const title='

Role instances

'; + if(!view)return `
${title}${empty('The role instances could not be read.','They are read from the bus host with your identity.')}
`; + if(!instanceDrafts.add&&!instanceDrafts.change)instanceView=view; + const v=instanceView, disabled=!canSend||out()||instanceBusy?' disabled':''; + const defs=Object.entries(v.definitions), accepted=defs.filter(([,d])=>d.accepted).map(([n])=>n); + const bound=defs.filter(([,d])=>Array.isArray(d.services)&&d.services.length).map(([n,d])=>`${txt(n)} (${d.services.map(txt).join(', ')})`); + const changeable=Object.entries(v.instances).filter(([,e])=>!e.protected).map(([n])=>n); + const rows=Object.entries(v.instances).map(([name,e])=>`${txt(name)}${txt(e.definition)}${e.launcher?'launcher':e.launched?'yes':'no'}${e.vars&&Object.keys(e.vars).length?`${txt(JSON.stringify(e.vars))}`:'none'}`).join(''); + const opts=(list,sel,keep)=>`${keep?``:''}${list.map(n=>``).join('')}`; + const a=instanceDrafts.add||{}, c=instanceDrafts.change||{}; + const addLaunch=v.launch?``:''; + const changeLaunch=v.launch?``:''; + const addForm=`
Add an instance
${addLaunch}
`; + const changeForm=changeable.length?`
Change an instance
${changeLaunch}
`:''; + return `
${title}

Add an instance or change one's definition, vars and launch membership. Holder, credentials and tracker stay hand edits, and so does an instance of a definition that declares credentials. An assistant changes in the Assistant section.

${rows}
InstanceDefinitionLaunchedVars
${addForm}${changeForm}${bound.length?`

Definitions that declare credentials, a hand edit: ${bound.join(', ')}.

`:''}

${canSend?'Changes are checked and logged with your identity.':'Changes require signed-in send mode.'}

${txt(instanceReceipt)}

`; + } + const instanceFields=form=>Object.fromEntries([...form.querySelectorAll('[data-instance-field]')].map(el=>[el.dataset.instanceField,el.type==='checkbox'?el.checked:el.value])); + function instancePayload(op,f){ + const payload={revision:instanceView.revision,instance:String(f.instance??'').trim(),op}; + if(!payload.instance)throw Error('Name the instance.'); + if(f.definition)payload.definition=f.definition; + if(op==='add'&&!payload.definition)throw Error('Choose a definition.'); + if(String(f.vars??'').trim()!==''){let parsed;try{parsed=JSON.parse(f.vars);}catch{throw Error('Vars must be JSON.');}if(!parsed||typeof parsed!=='object'||Array.isArray(parsed))throw Error('Vars must be a JSON object.');payload.vars=parsed;} + if(op==='add'&&f.launch===true)payload.launch=true; + if(op==='change'&&(f.launch==='yes'||f.launch==='no'))payload.launch=f.launch==='yes'; + if(op==='change'&&!['definition','vars','launch'].some(k=>Object.hasOwn(payload,k)))throw Error('Nothing changed.'); + return payload; + } + const unknownInstance='Outcome unknown. Read the role instances again before trying. Draft kept.'; + // The answer replaces the view the next render draws, so it must have the read's whole shape. + const instanceAnswer=r=>/^[a-f0-9]{64}$/.test(r?.revision??'')&&typeof r.restart==='boolean'&&[r.instances,r.definitions].every(o=>o&&typeof o==='object'&&!Array.isArray(o)); + for(const kind of ['input','change'])document.addEventListener(kind,e=>{const form=e.target?.closest?.('.instance-form');if(form)instanceDrafts[form.dataset.op]=instanceFields(form);}); + document.addEventListener('click',e=>{if(e.target.id!=='instances-reload')return;instanceDrafts={add:null,change:null};instanceView=null;instanceReceipt='';last.delete('instances');render(true);}); + document.addEventListener('submit',async e=>{ + const form=e.target?.closest?.('.instance-form');if(!form||e.target!==form)return;e.preventDefault();if(!canSend||out()||instanceBusy||!instanceView)return; + const op=form.dataset.op;instanceDrafts[op]=instanceFields(form);let payload; + try{payload=instancePayload(op,instanceDrafts[op]);}catch(err){instanceReceipt=err.message;render(false);return;} + instanceBusy=true;instanceReceipt='';render(false); + try{const response=await fetch('/api/instances',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify(payload),cache:'no-store',redirect:'manual'});if(response.type==='opaqueredirect'){instanceReceipt='Sign in again. Draft kept.';signOut();}else{const result=await response.json(); + if(response.ok&&instanceAnswer(result)){instanceDrafts[op]=null;instanceView=result;const prior=last.get('instances');if(prior)last.set('instances',{...prior,rows:[result]});instanceReceipt=`${op==='add'?'Added':'Changed'} ${payload.instance}. ${result.restart?RESTART_TEXT:NO_RESTART_TEXT}`;} + else instanceReceipt=response.ok||result?.sent==='unknown'?unknownInstance:`${result?.message||'Refused.'} Draft kept.`;}} + catch{instanceReceipt=unknownInstance;}finally{instanceBusy=false;if(!out())render(false);} + }); async function settingsView(get) { const s = await get.api('settings'), n = s.notifier || {}; let usage, names = null; try { [usage] = await get('usage'); } catch (err) { if (err.status === 403 || err.code === 'signed-out') throw err; } try { names = await get('names'); } catch { /* the section says the name could not be read */ } + let instances = null; + try { [instances] = await get('instances'); } catch (err) { if (err.status === 403 || err.code === 'signed-out') throw err; } let limitRows = [], limitsRefused = false; try { limitRows = await get('limits'); } catch (err) { if (err.status === 403 || err.code === 'signed-out') throw err; limitsRefused = true; } const notify = typeof n.binding === 'string' ? `
Binding
${txt(n.binding)}

The binding name only. Its channels, server and user ids stay in the binding file.

` : empty('No notifier binding to show.', `${n.refused ? `${txt(n.refused)}: ` : ''}${txt(n.message || 'the notifier settings could not be read')}`); - return `${head('Settings', `${readLine()} Agent limits and appearance.`)}${appearance()}${launchForm(s.launch)}${assistantSection(s.launch, names)}${tokenLimits(limitRows, limitsRefused)}${tokenUsage(usage)} + return `${head('Settings', `${readLine()} Agent limits and appearance.`)}${appearance()}${launchForm(s.launch)}${assistantSection(s.launch, names)}${instancesSection(instances)}${tokenLimits(limitRows, limitsRefused)}${tokenUsage(usage)}

Notifications

${notify}

About

Address
${txt(s.address) || 'unknown'}
Release
${s.release ? `${txt(s.release)}` : 'unknown: no RELEASE file was read'}
Business
${txt(s.business) || none}
Board
${txt(s.board) || 'unknown'}
`; } diff --git a/packages/webui/src/serve.mjs b/packages/webui/src/serve.mjs index 5635bd72c..1e73a6228 100644 --- a/packages/webui/src/serve.mjs +++ b/packages/webui/src/serve.mjs @@ -51,8 +51,9 @@ async function body(req, max = 4096) { // (#1549) adds `credentials`: what the bus host loaded, metadata only. Row 81 // (#1575) adds `replies`: the messages answering one message, for the send receipt. Row 125 // (#1619, REQ-LIMIT-3) adds `limits`: only the token limits' report, never the document. Row 155 -// (#1649) adds `names`: each instance's current seat name, for the Assistant section. -const BUS_VERBS = ['inbox', 'tasks', 'agents', 'trail', 'decisions', 'credentials', 'replies', 'messages', 'usage', 'limits', 'names']; +// (#1649) adds `names`: each instance's current seat name, for the Assistant section. Row 165 +// (#1662) adds `instances`: the business file's role instances and the definitions add accepts. +const BUS_VERBS = ['inbox', 'tasks', 'agents', 'trail', 'decisions', 'credentials', 'replies', 'messages', 'usage', 'limits', 'names', 'instances']; const DECISION_LISTS = ['roles', 'recent']; async function busRead(res, bus, verb, search) { let arg; @@ -80,6 +81,18 @@ async function busRead(res, bus, verb, search) { return json(res, busStatus(code), { error: code, message: code }); } } + if (verb === 'instances') { + if (search) return json(res, 400, { error: 'invalid-request', message: 'instances takes no arguments' }); + if (!bus?.instances) return json(res, 503, { error: 'not-configured', message: 'the Console has no bus configured' }); + try { + const value = await bus.instances(); + if (!/^[a-f0-9]{64}$/.test(value?.revision ?? '') || !value.instances || typeof value.instances !== 'object' || !value.definitions || typeof value.definitions !== 'object') throw new BusReadError('invalid-response'); + return json(res, 200, { rows: [value], at: new Date().toISOString() }); + } catch (err) { + const code = err instanceof BusReadError ? err.code : 'invalid-response'; + return json(res, busStatus(code), { error: code, message: code }); + } + } if (verb === 'trail') { arg = new URLSearchParams(search).get('subject'); if (!subjectOk(arg)) return json(res, 400, { error: 'invalid-request', message: 'subject must be a decision id, message id or task ref' }); @@ -253,6 +266,55 @@ async function seatSend(req, res, { route, write, preview, log }) { line('done'); return json(res, 200, { ...result, at: new Date().toISOString() }); } +// Row 165 (#1662, Q171): the human adds a role instance or changes one's definition, vars and +// launch membership. The Settings boundary (header user, exact Origin, same-origin Fetch Metadata, +// JSON within 16 KiB, strict keys) and one bus call, `instances.set`, through the human transport. +// The writer refuses a definition that declares credentials. The answer's `restart` says whether +// the running bus must restart before the change counts; the Console never restarts it. +const INSTANCE_KEYS = ['revision', 'instance', 'op', 'definition', 'vars', 'launch']; +// The bus answers a refusal with its code alone, so the reason the page shows is here. +const INSTANCE_REASONS = { + 'organization-credentials-out-of-scope': 'that definition declares credentials, or the instance holds them. The Console binds no credentials, so that stays a hand edit of the business file', + 'organization-instance-exists': 'the business already has that instance; change it instead', + 'organization-unknown-instance': 'the business has no such instance; add it instead', + 'organization-definition-refused': 'an assistant instance changes only in the Assistant section', + 'organization-launch-not-configured': 'the business file has no launch block, so launch membership can\'t change', + 'organization-no-change': 'the business file already says that', + 'organization-project-mismatch': 'a project file\'s id differs from its key in the business file; mosaic business validate shows it', + 'organization-unresolvable-instance': 'an instance wouldn\'t resolve against a project file; mosaic business validate shows why', + 'revision-conflict': 'the business file changed since you read it. Read the role instances again', +}; +async function instanceSend(req, res, { instancesWrite, preview, log }) { + let instance = null; + // The instance is quoted and cut short so a crafted value can't forge a log line. Vars are never logged. + const line = outcome => log(`${new Date().toISOString()} instance user=${JSON.stringify(preview.user)} instance=${quoted(instance)} ${outcome}`); + const refuse = (status, error, message, sent = false) => { line(`error=${error}`); return json(res, status, { error, message, sent }); }; + if (one(req, preview.header) !== preview.user) return json(res, 401, { error: 'sign-in required', message: 'sign in again', sent: false }); + if (one(req, 'origin') !== `https://${preview.host}`) return refuse(403, 'cross-origin request refused', 'this needs the Console\'s own Origin'); + if (one(req, 'sec-fetch-site') !== 'same-origin') return refuse(403, 'cross-site request refused', 'this needs same-origin Fetch Metadata'); + let value; + try { value = JSON.parse((await body(req, 16384)).toString('utf8')); } catch (err) { return refuse(400, 'invalid-request', err.message); } + const has = key => Object.hasOwn(value, key); + if (Object.keys(value).some(key => !INSTANCE_KEYS.includes(key)) || typeof value.revision !== 'string' || !/^[a-f0-9]{64}$/.test(value.revision) || + typeof value.instance !== 'string' || !['add', 'change'].includes(value.op) || (has('definition') && typeof value.definition !== 'string') || + (has('vars') && (!value.vars || typeof value.vars !== 'object' || Array.isArray(value.vars))) || (has('launch') && typeof value.launch !== 'boolean')) { + return refuse(400, 'invalid-request', 'this takes a revision, an instance, op add or change, and a definition, vars or launch, nothing else'); + } + ({ instance } = value); + let result; + try { result = await instancesWrite(Object.fromEntries(INSTANCE_KEYS.filter(has).map(k => [k, value[k]]))); } catch (err) { + const { code, sent } = sendOutcome(err); + return sent === false + ? refuse(busStatus(code), code, `${code}: ${Object.hasOwn(INSTANCE_REASONS, code) ? INSTANCE_REASONS[code] : 'refused by the bus'}. Nothing changed.`) + : refuse(503, 'outcome-unknown', 'the change may have been made; nothing was retried. Read the role instances again before trying', 'unknown'); + } + const object = o => o && typeof o === 'object' && !Array.isArray(o); + if (!/^[a-f0-9]{64}$/.test(result?.revision ?? '') || typeof result.restart !== 'boolean' || !object(result.definitions) || !object(result.instances) || !result.instances[instance]) { + return refuse(503, 'outcome-unknown', 'the bus answered in an unexpected shape; the change may have been made. Read the role instances again before trying', 'unknown'); + } + line(`done restart=${result.restart}`); + return json(res, 200, { ...result, at: new Date().toISOString() }); +} // Row 148 (#1642): the spec and docs editor. Two reads and one save, all through the human transport. // The save has the Settings boundary (header user, exact Origin, same-origin Fetch Metadata, JSON, // strict keys) with a 1 MiB body on this route only; every other POST keeps its own smaller limit. @@ -311,7 +373,7 @@ async function projectFileRead(res, read, path, search) { // `send` is the bus write (row 76): `args => Promise<{id}>`, only with the preview mode. `log` // takes one line per send attempt that got past sign-in; never the body. `fieldsFile` is for // tests; the field table is otherwise the committed packages/tasks/fields.json. -export async function startServer({ host = '127.0.0.1', port = 7330, board = DEFAULT_BOARD, timeout = 20000, bus = null, reads = null, preview = null, send = null, settingsWrite = null, projectFiles = null, projectFile = null, projectSave = null, chat = null, nameWrite = null, assistantStop = null, log = line => console.log(line), fieldsFile = undefined } = {}) { +export async function startServer({ host = '127.0.0.1', port = 7330, board = DEFAULT_BOARD, timeout = 20000, bus = null, reads = null, preview = null, send = null, settingsWrite = null, projectFiles = null, projectFile = null, projectSave = null, chat = null, nameWrite = null, assistantStop = null, instancesWrite = null, log = line => console.log(line), fieldsFile = undefined } = {}) { if (!isLoopback(host)) throw new Error('refusing to bind to non-loopback host'); if (host === 'localhost') host = '127.0.0.1'; const upstream = boardURL(board); @@ -357,6 +419,11 @@ export async function startServer({ host = '127.0.0.1', port = 7330, board = DEF if (!send || !write || !named) return json(res, 403, { error: 'read-only', sent: false }); return seatSend(req, res, { route: SEAT_ROUTES[path], write, preview, log }); } + if (path === '/api/instances') { + if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' }); + if (!send || !instancesWrite || !named) return json(res, 403, { error: 'read-only', sent: false }); + return instanceSend(req, res, { instancesWrite, preview, log }); + } if (path === '/api/project-file' && req.method === 'POST') { if (!send || !projectSave || !named) return json(res, 403, { error: 'read-only', sent: false }); return projectFileSend(req, res, { projectSave, preview, log }); diff --git a/scripts/mosaic b/scripts/mosaic index 22087e2fd..827c6ec29 100755 --- a/scripts/mosaic +++ b/scripts/mosaic @@ -26,6 +26,11 @@ if [ "${1:-}" = queue ]; then exec node "$REPO/packages/queue/src/cli.mjs" "$@" fi if [ "${1:-}" = business ]; then + # Row 165 (#1662): the human's role instance commands need the human proof, + # so they run in packages/cli. validate and resolve stay in packages/business. + case "${2:-}" in + instances|instance) exec node "$REPO/packages/cli/src/cli.mjs" "$@" ;; + esac shift exec node "$REPO/packages/business/src/cli.mjs" "$@" fi