diff --git a/packages/bus/README.md b/packages/bus/README.md index ce50f8d7b..83c2f8b69 100644 --- a/packages/bus/README.md +++ b/packages/bus/README.md @@ -576,10 +576,10 @@ scope probes and rotation/expiry notifications; S2 never probes real services. ## Schema and verification -`schema.sql` is v3e, SHA-256 -`21e6c091f14f818396f4d7836f381cc1389d45b2680ecaa1a00646b652c45050`. +`schema.sql` is v3f, SHA-256 +`472cbcd0d4548848873f3029e8250dc07bba4fb8db2a93241aae5b8e7e3771e2`. It has 14 tables, 64 triggers and five views. Source digest and a trusted full -sqlite_master digest are checked at open, alongside schema version `3e`, WAL, +sqlite_master digest are checked at open, alongside schema version `3f`, WAL, quick_check and foreign-key integrity. Missing metadata refuses; it never reinitializes an existing file. Full synchronous WAL transactions either commit or roll back. SQL UPDATE, DELETE and INSERT OR REPLACE refuse on evidence tables. @@ -644,3 +644,45 @@ core; an indexed/insert-scoped optimization requires equivalent checks and tests The schema itself remains byte-identical to v3b. S3 must normalize service read start times to this form before storing snapshots. External service `updated` is not a broker timestamp; its interpretation remains S3's responsibility. + +## Project records and file-backed north-star specs (row 138) + +The business's declared project resolves to its separate local records Git +repository (packages/project). `spec.read {project,commit?}` is available to a +held role instance, scoped to its business. It returns the committed +spec/north-star.md, its last file-changing commit, confirmation flag and up to +100 path-history entries with truncated=true if more exist. Optional commit is +a full reachable SHA-1; arbitrary revision expressions refuse. Uncommitted bytes +are ignored. Only author.name equal to business.human confirms a spec; a latest +agent-authored change is visible but unconfirmed, with no fallback to an older +human version. A later docs commit does not change the spec's file commit. + +`decision.raise` optionally takes project, spec_path (spec/north-star.md) and +spec_commit together. The broker reads the current committed snapshot and +refuses a different commit (stale-spec), unconfirmed file (spec-unconfirmed), +or incomplete citation (invalid-spec-citation). Missing files and unsafe +repositories retain the project reader's refusal codes. Uncited raises keep the +existing synchronous validity and routing rules. Decisions store spec_path and +spec_commit; later Git commits never reopen or rewrite settled decisions. + +`record.write {project,path,record,decision?}` uses the shared package writer. +It checks record.write authority, validates data and binds the author to the +session's definition.instance. No caller author/business identity is accepted. +Only docs Markdown and requirement/decision JSON are writable. spec/ always +refuses project-spec-human-only. The repository's exclusive writer lock refuses +concurrent writes with project-busy before they contend for Git's index lock. +All eleven v2 role definitions grant record.write within-role. Legacy researcher +(v1) and conductor-policy are unchanged. Narrowing limits still apply. + +Git awaits run outside Store transactions. File commits and SQL receipts are +two effects: a commit followed by failure to record its authority receipt refuses +outcome-unknown and must be inspected, never blindly retried. The unchanged +socket request envelope is 64 KiB; package file validation remains 1 MiB. The server +awaits only spec.read, record.write and cited decision.raise and holds any +transient proof until completion. Other request paths stay synchronous. + +The 3e→3f offline step adds nullable spec_path/spec_commit columns to decisions, +with nulls on existing rows. It changes no event or resolution and creates no +spec/confirmation tables. The 3e fixture is pinned from 56639c99b's tree; no live +store is used. Mos runs this step only in an approved stopped-bus/re-pin window, +as described in the candidate packet's MIGRATION.md. diff --git a/packages/bus/schema.sql b/packages/bus/schema.sql index 0c636369d..6603cdad8 100644 --- a/packages/bus/schema.sql +++ b/packages/bus/schema.sql @@ -58,7 +58,7 @@ CREATE TABLE decisions ( task_ref TEXT CHECK (task_ref IS NULL OR (task_ref GLOB 'vikunja:[1-9]*/[1-9]*' AND NOT substr(task_ref, 9) GLOB '*[^0-9/]*' AND NOT substr(task_ref, 9) GLOB '*/*/*')), requirement_ref TEXT, blocking INTEGER NOT NULL CHECK (blocking IN (0,1)), supersedes TEXT REFERENCES decisions(id) -) STRICT; +, spec_path TEXT, spec_commit TEXT) STRICT; CREATE TABLE decision_events ( seq INTEGER PRIMARY KEY AUTOINCREMENT, decision TEXT NOT NULL REFERENCES decisions(id), diff --git a/packages/bus/src/broker.mjs b/packages/bus/src/broker.mjs index bd0cd0ae7..53a447b97 100644 --- a/packages/bus/src/broker.mjs +++ b/packages/bus/src/broker.mjs @@ -1,4 +1,6 @@ import { randomUUID, randomBytes } from 'node:crypto'; +import { dirname } from 'node:path'; +import { readSpec, writeRecord, ProjectError } from '../../project/src/index.mjs'; import { loadRequirements } from '../../tasks/src/requirements.mjs'; // Kept closed while S1 lands; its vocabulary is the integration authority. @@ -16,6 +18,7 @@ export const ACTIONS = Object.freeze([ 'git.merge.protected', 'review.request', 'review.verdict', + 'record.write', 'message.send', 'message.external', 'role.launch', @@ -881,6 +884,9 @@ export class Broker { const args = request.args ?? {}; if (!object(args)) fail('invalid-request'); this.#secretCheck(args); + if (request.verb === 'spec.read' || request.verb === 'record.write' || + (request.verb === 'decision.raise' && ('spec_path' in args || 'spec_commit' in args))) + return this.#requestProject(s, { verb: request.verb, args: structuredClone(args) }); if (["limits", "limits.set", "organization.set", "plugins", "plugins.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 @@ -929,6 +935,50 @@ export class Broker { throw this.#refused(s, e, request); } } + // Git and the record writer are async effects: never hold a SQL transaction across an await. + async #requestProject(s, request) { + const { verb, args } = request; + try { + this.#store.transaction(() => this.#agent(s)); + const business = this.#business(s.business); + const context = { business, project: args.project, dataRoot: dirname(this.#store.directory) }; + if (verb === 'spec.read') { + keys(args, ['project', 'commit'], ['project']); + const result = await readSpec({ ...context, ...(args.commit === undefined ? {} : { commit: args.commit }) }); + this.#store.transaction(() => this.#agent(s)); + this.#secretCheck(result); + return result; + } + if (verb === 'record.write') { + keys(args, ['project', 'path', 'record', 'decision'], ['project', 'path', 'record']); + const authority = { decision: args.decision ?? null, target: args.project }; + this.#store.transaction(() => this.#checkAuthority(s, 'record.write', authority)); + const author = { definition: business.roles[s.role].definition, instance: s.role }; + // writeRecord takes the repository's exclusive lock before its first await. A concurrent + // write to this repository refuses project-busy, including from another bus request. + const result = await writeRecord({ ...context, path: args.path, record: args.record, author }); + try { + this.#store.transaction(() => this.#consumeAuthority(s, 'record.write', authority, + { project: args.project, path: result.path, commit: result.commit })); + } catch { fail('outcome-unknown'); } + this.#secretCheck(result); + return result; + } + if (typeof args.project !== 'string' || args.spec_path !== 'spec/north-star.md' || + typeof args.spec_commit !== 'string' || !/^[0-9a-f]{40}$/.test(args.spec_commit)) + fail('invalid-spec-citation'); + const spec = await readSpec(context); + if (!spec.confirmed) fail('spec-unconfirmed'); + if (args.spec_commit !== spec.commit) fail('stale-spec'); + return this.#store.transaction(() => { + const result = this.#dispatch(s, verb, args, spec); + this.#secretCheck(result); + return result; + }); + } catch (e) { + throw this.#refused(s, e instanceof ProjectError ? new BusError(e.code) : e, request); + } + } // The eight task verbs reach the trusted S3 handler here. It runs outside any transaction, gets the // cap to authorize and record through authorize() and recordTask(); refusals are recorded as in request(). async requestTask(cap, request, handler) { @@ -1007,7 +1057,7 @@ export class Broker { complete(out.summary); return { ...out.result, untrusted: true, notice: WEB_UNTRUSTED, source: verb }; } - #dispatch(s, verb, a) { + #dispatch(s, verb, a, spec = null) { const b = this.#business(s.business), by = s.human || s.run; switch (verb) { @@ -1101,10 +1151,13 @@ export class Broker { 'supersedes', 'choice', 'approvalChoice', + 'spec_path', + 'spec_commit', ], ['action', 'question', 'options', 'recommendation', 'blocking'], ); this.#agent(s); + if ((a.spec_path !== undefined || a.spec_commit !== undefined) && !spec) fail('invalid-spec-citation'); const cls = this.#classification(s, a.action); string(a.question); if (typeof a.blocking !== 'boolean') fail('invalid-request'); @@ -1147,7 +1200,7 @@ export class Broker { } const did = randomUUID(); this.#store.run( - 'INSERT INTO decisions(id,at,business,project,raised_by_role,raised_by_run,class,action,route_to,question,options,recommendation,task_ref,requirement_ref,blocking,supersedes) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', + 'INSERT INTO decisions(id,at,business,project,raised_by_role,raised_by_run,class,action,route_to,question,options,recommendation,task_ref,requirement_ref,blocking,supersedes,spec_path,spec_commit) VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)', did, this.#now(), s.business, @@ -1164,6 +1217,8 @@ export class Broker { a.requirement_ref ?? null, Number(a.blocking), a.supersedes ?? null, + spec?.path ?? null, + spec?.commit ?? null, ); this.#event( s, diff --git a/packages/bus/src/server.mjs b/packages/bus/src/server.mjs index 693583169..97decaa14 100644 --- a/packages/bus/src/server.mjs +++ b/packages/bus/src/server.mjs @@ -96,6 +96,17 @@ export async function serve({ broker, path, authenticateHuman = null, authentica }); return; } + // Row138: only project Git effects need an await; preserve every other sync path below. + if (r.verb === 'spec.read' || r.verb === 'record.write' || + (r.verb === 'decision.raise' && (Object.hasOwn(r.args ?? {}, 'spec_path') || Object.hasOwn(r.args ?? {}, 'spec_commit')))) { + const own = transient; + transient = null; + Promise.resolve().then(() => broker.request(cap, { verb: r.verb, args: r.args ?? {} })).then( + result => { if (!socket.destroyed) finish({ ok: true, result }); }, + e => { if (!socket.destroyed) finish({ ok: false, error: e instanceof BusError ? e.code : 'invalid-envelope' }); }, + ).finally(() => { if (own) broker.disconnect(own); }); + return; + } const result = broker.request(cap, { verb: r.verb, args: r.args ?? {} }); finish({ ok: true, result }); } catch (e) { diff --git a/packages/bus/src/store.mjs b/packages/bus/src/store.mjs index 81e01cca7..92bd59b50 100644 --- a/packages/bus/src/store.mjs +++ b/packages/bus/src/store.mjs @@ -13,8 +13,8 @@ import { join, isAbsolute } from 'node:path'; import { createHash } from 'node:crypto'; const ddl = readFileSync(new URL('../schema.sql', import.meta.url), 'utf8'); -export const SCHEMA_SHA256 = '21e6c091f14f818396f4d7836f381cc1389d45b2680ecaa1a00646b652c45050'; -export const SCHEMA_VERSION = '3e'; +export const SCHEMA_SHA256 = '472cbcd0d4548848873f3029e8250dc07bba4fb8db2a93241aae5b8e7e3771e2'; +export const SCHEMA_VERSION = '3f'; // Ordered, named offline steps. New schema changes append a step and keep prior DDL pinned. const legacyDDL = readFileSync(new URL('./migrations/3b.sql', import.meta.url), 'utf8'); const LEGACY_SHA256 = '179ffe356d4ff19a49b5ebad39b6c6bfd7771deb8e1b7c55b5e746f039d69e65'; @@ -38,6 +38,10 @@ const migrations = [{ report: (store) => store.all( "SELECT business, to_role, count(*) AS n FROM messages m WHERE NOT EXISTS(SELECT 1 FROM deliveries d WHERE d.message=m.id AND d.op IN ('delivered','read')) GROUP BY business, to_role ORDER BY business, to_role", ).map((r) => `kept ${r.n} undelivered message(s) for ${r.business}/${r.to_role} without a thread; if that role is a thread instance, its thread runs never receive them, so the human re-sends them with thread.send`), +}, { + from: '3e', + to: '3f', + sql: readFileSync(new URL('./migrations/3e-3f.sql', import.meta.url), 'utf8'), }]; const timedTables = [ 'events', diff --git a/packages/bus/tests/chief-of-staff.test.mjs b/packages/bus/tests/chief-of-staff.test.mjs index 67b962f89..6f9235943 100644 --- a/packages/bus/tests/chief-of-staff.test.mjs +++ b/packages/bus/tests/chief-of-staff.test.mjs @@ -367,7 +367,7 @@ async function database3c(t) { let source = readFileSync(here('../src/store.mjs'), 'utf8'); const pinned = source .replace(/export const SCHEMA_SHA256 = '[a-f0-9]+';/, `export const SCHEMA_SHA256 = '${createHash('sha256').update(ddl3c).digest('hex')}';`) - .replace("export const SCHEMA_VERSION = '3e';", "export const SCHEMA_VERSION = '3c';") + .replace("export const SCHEMA_VERSION = '3f';", "export const SCHEMA_VERSION = '3c';") .replace(/\}, \{\n {2}from: '3c',[\s\S]*?\}\];\nconst timedTables/, '}];\nconst timedTables'); assert.notEqual(pinned, source); assert.ok(!pinned.includes('3c-3d'), 'the 3c engine has no 3c→3d step'); @@ -391,7 +391,7 @@ test('REQ-ROLE-2, REQ-COS-1: the 3c→3d migration lets the chief of staff end a assert.throws(() => new Store(root), /schema-mismatch/); const store = new Store(root, { migrateSchema: true }); t.after(() => store.close()); - assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3e'); + assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3f'); assert.equal(store.get("SELECT body FROM events WHERE id='preserved'").body, '{"fixture":true}'); assert.equal(store.get("SELECT holder_run FROM role_claims WHERE role='coder'").holder_run, 'coder-run'); const b = new Broker({ store, businesses: demo(), organization: null }); diff --git a/packages/bus/tests/comment-migration.test.mjs b/packages/bus/tests/comment-migration.test.mjs index 555da864c..0aa4b0292 100644 --- a/packages/bus/tests/comment-migration.test.mjs +++ b/packages/bus/tests/comment-migration.test.mjs @@ -28,12 +28,12 @@ function legacy(t) { return { root, source, path }; } -test('explicit 3b copy migration preserves evidence and opens as 3e; normal startup never migrates', t => { +test('explicit 3b copy migration preserves evidence and opens as 3f; normal startup never migrates', t => { const { root, source } = legacy(t); const original = readFileSync(source); assert.throws(() => new Store(root), /schema-mismatch/); const store = new Store(root, { migrateSchema: true }); - assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3e'); + assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3f'); assert.equal(store.get("SELECT body FROM events WHERE id='preserved'").body, '{"fixture":true}'); assert.equal(store.get('SELECT count(*) n FROM task_comment_cursors').n, 0); const epoch = store.get("SELECT value FROM meta WHERE key='comment_cursor_epoch'").value; @@ -62,7 +62,7 @@ test('migration refuses active writers and drifted legacy schemas, with no parti assert.throws(() => new Store(other.root, { migrateSchema: true }), /writer-locked/); }); -test('named migration registry chains 3b through 3e to a fixture-only future version in order', async t => { +test('named migration registry chains 3b through 3f to a fixture-only future version in order', async t => { const { root } = legacy(t); const { writeFileSync } = await import('node:fs'); const { pathToFileURL } = await import('node:url'); @@ -75,15 +75,15 @@ test('named migration registry chains 3b through 3e to a fixture-only future ver const sha = createHash('sha256').update(futureDDL).digest('hex'); let source = readFileSync(new URL('../src/store.mjs', import.meta.url), 'utf8'); source = source.replace(/export const SCHEMA_SHA256 = '[a-f0-9]+';/, `export const SCHEMA_SHA256 = '${sha}';`) - .replace("export const SCHEMA_VERSION = '3e';", "export const SCHEMA_VERSION = '3f';") - .replace('}];\nconst timedTables', `}, { from: '3e', to: '3f', sql: ${JSON.stringify(futureSQL)} }];\nconst timedTables`); + .replace("export const SCHEMA_VERSION = '3f';", "export const SCHEMA_VERSION = '3g';") + .replace('}];\nconst timedTables', `}, { from: '3f', to: '3g', sql: ${JSON.stringify(futureSQL)} }];\nconst timedTables`); writeFileSync(join(moduleRoot, 'src/store.mjs'), source); writeFileSync(join(moduleRoot, 'schema.sql'), futureDDL); - for (const name of ['3b.sql', '3b-3c.sql', '3c-3d.sql', '3d-3e.sql']) + for (const name of ['3b.sql', '3b-3c.sql', '3c-3d.sql', '3d-3e.sql', '3e-3f.sql']) copyFileSync(new URL('../src/migrations/' + name, import.meta.url), join(moduleRoot, 'src/migrations', name)); const { Store: FutureStore } = await import(pathToFileURL(join(moduleRoot, 'src/store.mjs'))); const future = new FutureStore(root, { migrateSchema: true }); - assert.equal(future.get("SELECT value FROM meta WHERE key='schema_version'").value, '3f'); + assert.equal(future.get("SELECT value FROM meta WHERE key='schema_version'").value, '3g'); assert.equal(future.get("SELECT name FROM sqlite_master WHERE name='future_fixture'").name, 'future_fixture'); assert.equal(future.get("SELECT count(*) n FROM task_comment_cursors").n, 0); assert.equal(future.get("SELECT id FROM events").id, 'preserved'); @@ -109,7 +109,7 @@ test('offline command migrates only the supplied fixture root and reports usage const command = new URL('../src/migrate-schema.mjs', import.meta.url).pathname; const migrated = spawnSync(process.execPath, [command, root], { encoding: 'utf8' }); assert.equal(migrated.status, 0, migrated.stderr); - assert.match(migrated.stdout, /bus schema 3e ready/); + assert.match(migrated.stdout, /bus schema 3f ready/); new Store(root).close(); const usage = spawnSync(process.execPath, [command], { encoding: 'utf8' }); assert.equal(usage.status, 2); diff --git a/packages/bus/tests/thread-migration.test.mjs b/packages/bus/tests/thread-migration.test.mjs index 47ebfb262..5a3785580 100644 --- a/packages/bus/tests/thread-migration.test.mjs +++ b/packages/bus/tests/thread-migration.test.mjs @@ -49,7 +49,7 @@ async function database3d(t) { const source = readFileSync(here('../src/store.mjs'), 'utf8'); const pinned = source .replace(/export const SCHEMA_SHA256 = '[a-f0-9]+';/, `export const SCHEMA_SHA256 = '${createHash('sha256').update(ddl3d).digest('hex')}';`) - .replace("export const SCHEMA_VERSION = '3e';", "export const SCHEMA_VERSION = '3d';") + .replace("export const SCHEMA_VERSION = '3f';", "export const SCHEMA_VERSION = '3d';") .replace(/\}, \{\n {2}from: '3d',[\s\S]*?\}\];\nconst timedTables/, '}];\nconst timedTables'); assert.ok(!pinned.includes('3d-3e'), 'the 3d engine has no 3d→3e step'); writeFileSync(join(moduleRoot, 'src/store.mjs'), pinned); @@ -95,7 +95,7 @@ test('REQ-THREAD-1 REQ-ORG-2: the 3d→3e migration adds the thread tables and l assert.throws(() => new Store(root), /schema-mismatch/); const store = new Store(root, { migrateSchema: true }); t.after(() => store.close()); - assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3e'); + assert.equal(store.get("SELECT value FROM meta WHERE key='schema_version'").value, '3f'); for (const table of ['projects', 'threads', 'thread_claims', 'message_threads', 'thread_opens']) assert.equal(store.get(`SELECT count(*) n FROM ${table}`).n, 0, table); // Parked: the undelivered ones are counted per business and role, and none is changed or given a thread. @@ -155,5 +155,5 @@ test('REQ-THREAD-1: the offline command prints the kept-message counts before th const command = new URL('../src/migrate-schema.mjs', import.meta.url).pathname; const migrated = spawnSync(process.execPath, [command, root], { encoding: 'utf8' }); assert.equal(migrated.status, 0, migrated.stderr); - assert.equal(migrated.stdout, [...REPORT, 'bus schema 3e ready', ''].join('\n')); + assert.equal(migrated.stdout, [...REPORT, 'bus schema 3f ready', ''].join('\n')); }); diff --git a/packages/business/src/vocabulary.mjs b/packages/business/src/vocabulary.mjs index 6c1d6af09..a63316935 100644 --- a/packages/business/src/vocabulary.mjs +++ b/packages/business/src/vocabulary.mjs @@ -22,6 +22,7 @@ export const ACTIONS = Object.freeze([ "git.merge.protected", "review.request", "review.verdict", + "record.write", "message.send", "message.external", "role.launch", diff --git a/packages/business/tests/chief-of-staff.test.mjs b/packages/business/tests/chief-of-staff.test.mjs index fcddaeba4..6edd8a262 100644 --- a/packages/business/tests/chief-of-staff.test.mjs +++ b/packages/business/tests/chief-of-staff.test.mjs @@ -13,11 +13,11 @@ import { THREAD_IDLE_SECONDS } from "../src/business.mjs"; import { businessDoc, launchDoc, REPO_ROLES, systemFor, tmp, writeJson } from "./helpers.mjs"; // Decision 104's list plus role.launch (decision 139) plus role.end and -// organization.change (row 123, REQ-COS-1). A role file that differs from it fails. +// organization.change (row 123, REQ-COS-1) and record.write (row 138). A role file that differs from it fails. const APPROVED = Object.freeze({ tools: ["read", "grep", "find", "ls"], network: "api-only", - authority: Object.freeze({ withinRole: Object.freeze(["message.send", "role.launch", "role.end", "organization.change"]), crossRole: Object.freeze([]) }), + authority: Object.freeze({ withinRole: Object.freeze(["message.send", "role.launch", "role.end", "organization.change", "record.write"]), crossRole: Object.freeze([]) }), credentials: Object.freeze([]), }); @@ -86,7 +86,7 @@ test("the resolved record matches the approved list, so a widened file fails", ( test("the chief of staff holds role.launch, message.send, role.end and organization.change; every other action is gated", () => { const record = resolved(loadFixture()); - const held = ["message.send", "role.launch", "role.end", "organization.change"]; + const held = ["message.send", "role.launch", "role.end", "organization.change", "record.write"]; for (const action of ACTIONS) { assert.equal(classify(record, action), held.includes(action) ? "within" : "gated", action); } diff --git a/packages/harness/README.md b/packages/harness/README.md index 1627f9770..fcc33ab30 100644 --- a/packages/harness/README.md +++ b/packages/harness/README.md @@ -307,3 +307,17 @@ These are limits, not bugs, and nothing in this package claims otherwise. hides it from other sessions. It holds no secret. - **Pi adapter paths** with spaces break its unquoted `-e` and skill splitting; the launcher's paths don't contain spaces. + +## File-backed project records (row138) + +Every agent gets read_spec(project,commit?), which returns the committed +north-star text and path history. A role holding record.write also gets +write_record(project,path,record,decision?), for validated docs/requirements/ +decisions committed as its bound instance. The broker supplies author metadata; +there is no author argument and no agent spec writer. A direct attempt to write +spec/ refuses even if a caller bypasses the offered tool schema. + +raise_decision accepts optional project, spec_path and spec_commit. Cite both +spec fields together, using the current confirmed file commit returned by +read_spec, not the repository HEAD. Uncited raises remain valid. Later human +spec commits do not reopen decisions already settled. diff --git a/packages/harness/src/tools.mjs b/packages/harness/src/tools.mjs index 3f1c6a3a6..142650912 100644 --- a/packages/harness/src/tools.mjs +++ b/packages/harness/src/tools.mjs @@ -178,6 +178,20 @@ export function typedTools({ resolved, arbiter = false, tracker = false, project url: str("The https url to fetch", { maxLength: 2048 }), }, ["url"])); } + add("read_spec", "spec.read", null, "Read a project's committed north-star spec and its file history. commit is an optional full reachable commit ID. The file commit, rather than HEAD, is what a decision cites. confirmed says the file commit was authored by the business's human.", obj({ + project: str("Project ID from the business file"), + commit: str("Optional full historical commit ID", { pattern: "^[0-9a-f]{40}$" }), + }, ["project"])); + if (held.has("record.write")) { + add("write_record", "record.write", "record.write", "Validate and commit one project document, requirement or decision as your bound role instance. The broker supplies the author. Agents never write spec/; pending human edits or another writer cause a refusal.", obj({ + project: str("Project ID from the business file"), + path: str("Named docs Markdown or requirement/decision JSON path", { + pattern: "^(docs/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\\.md|(requirements|decisions)/[A-Za-z0-9][A-Za-z0-9._-]{0,127}\\.json)$", + }), + record: { type: ["string", "object"], description: "Markdown string or a JSON record matching the project's package-owned schema" }, + decision: COMMON.decision, + }, ["project", "path", "record"])); + } add("raise_decision", "decision.raise", null, "Ask for a decision before a gated or cross-role action, or when you need a choice made. The answer arrives as a message.", obj({ action: str("The action the decision is about", { enum: [...ACTIONS] }), question: str("The question, with enough context to answer it and the reason for your recommendation"), @@ -188,6 +202,9 @@ export function typedTools({ resolved, arbiter = false, tracker = false, project approvalChoice: str("The option key that approves the action. It defaults to yes, so pass it whenever no option key is yes"), task_ref: TASK_REF, requirement_ref: str("Requirement id"), + project: str("Project ID from the business file; required with a spec citation"), + spec_path: str("Cite only this north-star path; send spec_commit with it", { const: "spec/north-star.md" }), + spec_commit: str("The current confirmed file commit from read_spec; send spec_path with it", { pattern: "^[0-9a-f]{40}$" }), }, ["action", "question", "options", "recommendation", "blocking"])); if (arbiter) { add("resolve_decision", "decision.resolve", null, "Resolve a decision routed to you.", obj({ diff --git a/packages/harness/tests/tools.test.mjs b/packages/harness/tests/tools.test.mjs index 5905dca38..458d0ddbc 100644 --- a/packages/harness/tests/tools.test.mjs +++ b/packages/harness/tests/tools.test.mjs @@ -13,7 +13,7 @@ test("the PM gets its task verbs and the reads, and no launch", (t) => { "send_message", "request_staff", "task_create", "task_assign", "task_reassign", "task_schedule", "task_priority_change", "task_scope_change", "task_update_assigned", "task_close", - "raise_decision", "resolve_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", "list_requirements", + "read_spec", "write_record", "raise_decision", "resolve_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", "list_requirements", ]); // Row 119 (#1613): only the chief of staff launches (REQ-COS-1). assert.equal(pm.launch, null); @@ -21,7 +21,7 @@ test("the PM gets its task verbs and the reads, and no launch", (t) => { const create = tools.find((x) => x.name === "task_create"); assert.deepEqual({ ...create.parameters.properties.project, description: undefined }, { type: "integer", minimum: 1, description: undefined }); assert.deepEqual(create.parameters.required, ["title", "request", "requirement"]); - assert.deepEqual(tools.filter((x) => x.parameters.properties.project).map((x) => x.name), ["task_create"]); + assert.deepEqual(tools.filter((x) => x.parameters.properties.project).map((x) => x.name), ["task_create", "read_spec", "write_record", "raise_decision"]); for (const tool of tools) { assert.equal(tool.parameters.type, "object"); assert.equal(tool.parameters.additionalProperties, false); @@ -33,7 +33,7 @@ test("the PM gets its task verbs and the reads, and no launch", (t) => { test("the chief of staff gets launch, send_message, end_run and change_organization, and no task verbs", (t) => { const chief = resolvedFor(t, "chief"); const tools = typedTools({ resolved: chief, tracker: true }); - assert.deepEqual(names(tools), ["send_message", "launch", "end_run", "change_organization", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); + assert.deepEqual(names(tools), ["send_message", "launch", "end_run", "change_organization", "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); const launch = tools.find((x) => x.name === "launch"); assert.equal(launch.verb, "launch"); assert.equal(launch.action, "role.launch"); @@ -106,11 +106,11 @@ 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 119 (#1613): the assistant holds message.send alone. +// 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" })); const tools = typedTools({ resolved: assistant, tracker: true }); - assert.deepEqual(names(tools), ["send_message", "web_search", "web_fetch", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); + assert.deepEqual(names(tools), ["send_message", "web_search", "web_fetch", "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); assert.equal(assistant.launch, null); assert.deepEqual(untypedActions(assistant, tools), []); }); @@ -144,7 +144,7 @@ test("list_requirements reads the requirement ids, for a task.create holder with test("a coder gets no launch, no resolve_decision, and no task tools without a tracker", (t) => { const coder = resolvedFor(t, "coder"); const tools = typedTools({ resolved: coder }); - assert.deepEqual(names(tools), ["send_message", "request_review", "raise_decision", "list_agents", "inbox", "trail"]); + assert.deepEqual(names(tools), ["send_message", "request_review", "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail"]); // Held actions without a tool are listed, so the manifest shows them. With // no clone to push from, push_working is one of them. assert.deepEqual(untypedActions(coder, tools), ["task.update.assigned", "git.push.working", "task.scope.change"]); @@ -154,7 +154,7 @@ test("a coder with a tracker gets its own task tools and no task_reassign", (t) const coder = resolvedFor(t, "coder"); assert.deepEqual(names(typedTools({ resolved: coder, tracker: true })), [ "send_message", "task_scope_change", "task_update_assigned", "request_review", - "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", + "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", ]); }); @@ -167,7 +167,7 @@ test("launch only when the business's launch block names the instance as launche test("an action outside the instance's authority has no tool", (t) => { const coder = resolvedFor(t, "coder", (d) => (d.roles.coder.vars["limits.authority"] = ["review.request"])); - assert.deepEqual(names(typedTools({ resolved: coder, tracker: true, projects: ["stack"] })), ["request_review", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); + assert.deepEqual(names(typedTools({ resolved: coder, tracker: true, projects: ["stack"] })), ["request_review", "read_spec", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); }); // Row 93 (#1587): the review loop's tools, by authority, and the git ones only with a clone. @@ -176,7 +176,7 @@ test("the review loop: push_working and request_review for the coder, fetch_revi const tools = typedTools({ resolved: coder, tracker: true, projects: ["stack", "site"] }); assert.deepEqual(names(tools), [ "send_message", "task_scope_change", "task_update_assigned", "push_working", "request_review", - "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", + "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task", ]); assert.deepEqual(untypedActions(coder, tools), []); const push = tools.find((x) => x.name === "push_working"); @@ -193,7 +193,7 @@ test("the review loop: push_working and request_review for the coder, fetch_revi const reviewer = resolvedFor(t, "reviewer"); const rtools = typedTools({ resolved: reviewer, tracker: true, projects: ["stack"] }); - assert.deepEqual(names(rtools), ["send_message", "task_update_assigned", "fetch_review", "review_verdict", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); + assert.deepEqual(names(rtools), ["send_message", "task_update_assigned", "fetch_review", "review_verdict", "read_spec", "write_record", "raise_decision", "list_agents", "inbox", "trail", "list_tasks", "get_task"]); const fetch = rtools.find((x) => x.name === "fetch_review"); assert.deepEqual([fetch.verb, fetch.action], ["working.fetch", null]); assert.deepEqual(fetch.parameters.required, ["task_ref", "request"]); diff --git a/packages/project/README.md b/packages/project/README.md index a23a43c63..992e2ae4b 100644 --- a/packages/project/README.md +++ b/packages/project/README.md @@ -117,3 +117,29 @@ callers must coordinate simultaneous human saves. No destructive repair, push, remote creation, role grant, spec-confirmation mechanism or live action ships. Tests: `node --test packages/project/tests/*.test.mjs`. Fixtures only. + +## Committed file reads (row 138) + +`readProjectFile({business,project,dataRoot,path,commit?})` reads only +spec/north-star.md or a named docs/NAME.md; `readSpec({business,project,dataRoot,commit?})` +fixes the spec path. Both are async and read-only, share repository/path checks, +refuse remotes and unsafe Git metadata, and validate committed project.json +identity. Working-tree edits do not replace committed content. A supplied full +SHA-1 must be a commit reachable from a captured HEAD. + +The result is {repo,path,head,revision,commit,content,author,log,truncated}. +commit is the last commit changing the file at revision, not necessarily HEAD; +content preserves exact valid UTF-8 including trailing newlines, up to 1 MiB with +no NUL. Log has at most 100 entries, newest first, each +{commit,author:{name,email},at,subject}; at is canonical UTC. truncated says more +entries exist. Reads reject nonregular Git blobs, missing paths and invalid +content. History output is separately bounded to 256 KiB. + +readSpec adds confirmed=true exactly when the file commit author.name equals +business.human. An agent-authored latest change stays unconfirmed. This is local +Git provenance, not a cryptographic identity proof. Broker citation validation +compares a fresh current snapshot and never uses an older read as authority. +Read errors are ProjectError: project-read-path, project-read-commit, +project-read-missing, project-read-content, project-invalid, plus existing +project-id/path/not-declared/repository/remote/git codes. No write or spec save +API is added; row 148 owns the human editor writer and its stale-base check. diff --git a/packages/project/src/git.mjs b/packages/project/src/git.mjs index ce4e2391b..46af3681c 100644 --- a/packages/project/src/git.mjs +++ b/packages/project/src/git.mjs @@ -1,6 +1,7 @@ import { lstatSync, readdirSync } from 'node:fs'; import { dirname, join } from 'node:path'; -import { gitEnv, runGit } from '../../seat/src/checkout.mjs'; +import { spawn } from 'node:child_process'; +import { gitEnv, runGit, GIT_LIMITS } from '../../seat/src/checkout.mjs'; import { ProjectError } from './paths.mjs'; const SAFE = ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-c', 'core.ignorestat=false', @@ -53,3 +54,33 @@ export async function requireClean(repo) { } export const identity = name => ({ GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: `${name}@mosaic.invalid`, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: `${name}@mosaic.invalid` }); + +// Blob/log reads preserve bytes and bound memory before decoding untrusted Git data. +export async function gitBytes(repo, args, maxBytes) { + return new Promise((resolve, reject) => { + const child = spawn('git', [...SAFE, '-C', repo, ...args], { + env: { ...gitEnv(), GIT_CEILING_DIRECTORIES: dirname(repo) }, + detached: true, stdio: ['ignore', 'pipe', 'pipe'], + }); + let size = 0, failed = false, settled = false; + const chunks = []; + const kill = () => { try { process.kill(-child.pid, 'SIGKILL'); } catch {} }; + const timer = setTimeout(() => { failed = true; kill(); }, GIT_LIMITS.timeoutMs); + const finish = (code) => { + if (settled) return; + settled = true; + clearTimeout(timer); + if (failed || code !== 0) reject(new ProjectError('project-git', 'bounded local Git read refused')); + else resolve(Buffer.concat(chunks)); + }; + child.stdout.on('data', chunk => { + size += chunk.length; + if (size > maxBytes) { failed = true; kill(); } + else chunks.push(chunk); + }); + // Drain stderr without retaining repository-controlled text. + child.stderr.on('data', () => {}); + child.on('error', () => finish(-1)); + child.on('close', finish); + }); +} diff --git a/packages/project/src/index.mjs b/packages/project/src/index.mjs index 6523ca8a3..47c0578be 100644 --- a/packages/project/src/index.mjs +++ b/packages/project/src/index.mjs @@ -230,3 +230,5 @@ export async function writeRecord({ path, record, author, ...context }) { if (lstatSync(lock).ino === lockStat.ino) unlinkSync(lock); } } + +export { readProjectFile, readSpec } from './read.mjs'; diff --git a/roles/assistant.json b/roles/assistant.json index 6fddc5994..39100bc43 100644 --- a/roles/assistant.json +++ b/roles/assistant.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls", "web"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-executive-officer.json b/roles/chief-executive-officer.json index 95d6679e0..08a2c93d5 100644 --- a/roles/chief-executive-officer.json +++ b/roles/chief-executive-officer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-financial-officer.json b/roles/chief-financial-officer.json index 0384fac2c..6f9de0b54 100644 --- a/roles/chief-financial-officer.json +++ b/roles/chief-financial-officer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-information-officer.json b/roles/chief-information-officer.json index 4a415d7c7..581304132 100644 --- a/roles/chief-information-officer.json +++ b/roles/chief-information-officer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-information-security-officer.json b/roles/chief-information-security-officer.json index 2db30f8fd..ec546e0b7 100644 --- a/roles/chief-information-security-officer.json +++ b/roles/chief-information-security-officer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-marketing-officer.json b/roles/chief-marketing-officer.json index 76312f93d..18ce94943 100644 --- a/roles/chief-marketing-officer.json +++ b/roles/chief-marketing-officer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send"], + "withinRole": ["message.send", "record.write"], "crossRole": [] }, "credentials": [], diff --git a/roles/chief-of-staff.json b/roles/chief-of-staff.json index 8613710a4..100c018bd 100644 --- a/roles/chief-of-staff.json +++ b/roles/chief-of-staff.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["message.send", "role.launch", "role.end", "organization.change"], + "withinRole": ["message.send", "role.launch", "role.end", "organization.change", "record.write"], "crossRole": [] }, "credentials": [] diff --git a/roles/coder.json b/roles/coder.json index 04220271f..eedb4fec3 100644 --- a/roles/coder.json +++ b/roles/coder.json @@ -6,7 +6,7 @@ "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["task.update.assigned", "git.push.working", "review.request", "message.send"], + "withinRole": ["task.update.assigned", "git.push.working", "review.request", "message.send", "record.write"], "crossRole": ["task.scope.change"] }, "credentials": [ diff --git a/roles/cto.json b/roles/cto.json index bb5bd5047..afc3f22ed 100644 --- a/roles/cto.json +++ b/roles/cto.json @@ -6,7 +6,7 @@ "tools": ["read", "write", "edit", "bash", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["review.request", "task.update.assigned", "message.send", "decision.resolve.technical"], + "withinRole": ["review.request", "task.update.assigned", "message.send", "decision.resolve.technical", "record.write"], "crossRole": ["task.scope.change"] }, "credentials": [ diff --git a/roles/pm.json b/roles/pm.json index 66525798e..1323a87a0 100644 --- a/roles/pm.json +++ b/roles/pm.json @@ -6,7 +6,7 @@ "tools": ["read", "write", "edit", "grep", "find", "ls"], "network": "api-only", "authority": { - "withinRole": ["task.create", "task.assign", "task.reassign", "task.schedule", "task.update.assigned", "task.close", "message.send"], + "withinRole": ["task.create", "task.assign", "task.reassign", "task.schedule", "task.update.assigned", "task.close", "message.send", "record.write"], "crossRole": ["task.priority.change", "task.scope.change"] }, "credentials": [ diff --git a/roles/reviewer.json b/roles/reviewer.json index 45e82435a..6f0969d18 100644 --- a/roles/reviewer.json +++ b/roles/reviewer.json @@ -6,7 +6,7 @@ "tools": ["read", "grep", "find", "ls", "bash"], "network": "api-only", "authority": { - "withinRole": ["review.verdict", "message.send", "task.update.assigned"], + "withinRole": ["review.verdict", "message.send", "task.update.assigned", "record.write"], "crossRole": [] }, "credentials": [