@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/engine/spec-builder.js

@@ -0,0 +1,321 @@
+/**
+ * Sub-agent spec construction (governance-mode 8.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE ENGINE BUILDS EVERY BRIEF; THE ORCHESTRATOR NEVER DOES (6.2 rule 5). That is what
+ * makes the information boundary real: a role sees exactly the sections this module is
+ * handed, and the CALLER (the engine) is the one who decides what each role may be
+ * handed, from `visibility.ts`. This module is deliberately a pure assembler with no
+ * access to the store, so it cannot leak a section it was not given.
+ *
+ * It also re-applies the three length clamps `normalizeSubagentSpecs` applies to the
+ * orchestrator's own specs (D-24 / RV-4): the engine bypasses that function, so the
+ * `label` / `description` / `prompt` bounds have to hold here or nowhere.
+ */
+import { TEAM_AGGREGATE_LABEL, TEAM_LIMITS } from '../../team/limits.js';
+import { GOV_LIMITS } from '../limits.js';
+/** Marker appended to any clipped section. Stable: tests and models rely on it. */
+export const TRUNCATION_MARK = '[truncated]';
+const ROLE_WORD = {
+    DEV: 'DEV',
+    REV: 'REV',
+    TEST: 'TEST',
+    INSP: 'INSP',
+};
+function clampText(text, max) {
+    const trimmed = text.trim();
+    return trimmed.length > max ? `${trimmed.slice(0, Math.max(0, max - 1))}~` : trimmed;
+}
+function bullet(items) {
+    return items.map((i) => `- ${i}`).join('\n');
+}
+function describeWp(wp) {
+    const lines = [
+        `WP ${wp.id}: ${wp.title}`,
+        `  goal: ${wp.goal}`,
+        `  owned files: ${wp.files.length > 0 ? wp.files.join(', ') : '(none declared)'}`,
+        `  acceptance:`,
+        ...wp.acceptance.map((a) => `    - ${a}`),
+    ];
+    if (wp.dependsOn.length > 0)
+        lines.push(`  depends on: ${wp.dependsOn.join(', ')}`);
+    return lines.join('\n');
+}
+function describeContracts(contracts, wpIds) {
+    const relevant = contracts.filter((c) => !c.voided &&
+        (wpIds === null || wpIds.has(c.producer) || c.consumers.some((id) => wpIds.has(id))));
+    if (relevant.length === 0)
+        return '';
+    return relevant
+        .map((c) => `${c.id} ${c.name}: producer ${c.producer}; consumers ${c.consumers.join(', ')}\n` +
+        `  ${c.definition}`)
+        .join('\n');
+}
+/** The one-line "what to do and which tool to call" instruction. Priority 1. */
+function taskInstruction(brief) {
+    const wpList = brief.wps.map((w) => w.id).join(', ');
+    const n = brief.wps.length;
+    const once = (tool) => n > 1
+        ? `Call ${tool} exactly once for EACH of these ${n} work packages (${wpList}), ` +
+            `in this order, passing the wpId each time.`
+        : `Call ${tool} exactly once when you are finished.`;
+    switch (brief.stage) {
+        case 'dev':
+            return (`Implement work package ${wpList} completely. Touch only the files it owns. ` +
+                `Verify every contract you produce or consume. ${once('gov_submit_work')}`);
+        case 'fix':
+            return (`Integration failed. Fix work package ${wpList} so the interfaces align with the ` +
+                `contracts. The goal is interface alignment, not turning the test green. State ` +
+                `which contracts you re-verified. ${once('gov_submit_work')}`);
+        case 'review':
+            return (`Review work package ${wpList} independently of the developer. ${once('gov_submit_review')} Do not merge or skip any package.`);
+        case 'test':
+            return (`Test work package ${wpList}: run the existing suites, write missing tests ` +
+                `(including cross-module boundary tests) and trace every acceptance criterion to ` +
+                `evidence. ${once('gov_submit_test')}`);
+        case 'settle':
+            return (`Run the settle stage of phase ${brief.phase}: rule on every open claim with ` +
+                `ledger_rule, audit the flags below, award or withhold discretionary events with ` +
+                `ledger_apply (evidence required), and check each contract statically on both ` +
+                `sides. Finish with exactly one ledger_settle call (kind "settle").`);
+        case 'integrate':
+            return (`Run the integrate stage of phase ${brief.phase}: use only the registered ` +
+                `integration commands, record the result, and on failure include a structured ` +
+                `RCA. Finish with exactly one ledger_settle call (kind "integrate").`);
+    }
+}
+function reworkSection(brief) {
+    if (brief.requiredChanges === undefined)
+        return null;
+    const parts = [];
+    for (const wp of brief.wps) {
+        const items = brief.requiredChanges[wp.id];
+        if (items === undefined || items.length === 0)
+            continue;
+        parts.push(`WP ${wp.id} (rework ${wp.reworkCount}):\n` +
+            items.map((c, i) => `  ${i + 1}. ${c.file}: ${c.issue} -> ${c.change}`).join('\n'));
+    }
+    if (parts.length === 0)
+        return null;
+    return {
+        priority: 4,
+        title: 'REQUIRED CHANGES (address each one, or use your single appeal)',
+        body: parts.join('\n'),
+    };
+}
+function submissionSection(brief) {
+    if (brief.workSubmissions !== undefined) {
+        const parts = [];
+        for (const wp of brief.wps) {
+            const sub = brief.workSubmissions[wp.id];
+            if (sub === undefined)
+                continue;
+            const contracts = sub.interfaceContracts
+                .map((c) => `${c.interface}/${c.role}/${c.verified}`)
+                .join('; ');
+            parts.push(`WP ${wp.id} by ${sub.identity}: ${clampText(sub.summary, 600)}\n` +
+                `  files changed: ${sub.filesChanged.join(', ') || '(none)'}\n` +
+                `  contract claims: ${contracts || '(none)'}`);
+        }
+        return parts.length === 0
+            ? null
+            : { priority: 5, title: 'SUBMITTED WORK UNDER REVIEW', body: parts.join('\n') };
+    }
+    if (brief.changeLists !== undefined) {
+        const parts = brief.wps.map((wp) => `WP ${wp.id}: ${(brief.changeLists?.[wp.id] ?? []).join(', ') || '(none)'}`);
+        return { priority: 5, title: 'FILES CHANGED BY THE DEVELOPER', body: parts.join('\n') };
+    }
+    return null;
+}
+function verdictSection(brief) {
+    if (brief.reviewVerdicts === undefined)
+        return null;
+    const parts = brief.wps
+        .filter((wp) => brief.reviewVerdicts?.[wp.id] !== undefined)
+        .map((wp) => `WP ${wp.id}: review verdict ${brief.reviewVerdicts?.[wp.id]}`);
+    if (parts.length === 0)
+        return null;
+    return {
+        priority: 6,
+        title: 'REVIEW CONCLUSIONS (conclusion only; comments are withheld on purpose)',
+        body: parts.join('\n'),
+    };
+}
+function appealSection(brief) {
+    if (brief.appeals === undefined)
+        return null;
+    const parts = brief.wps
+        .filter((wp) => brief.appeals?.[wp.id] !== undefined)
+        .map((wp) => {
+        const a = brief.appeals[wp.id];
+        return (`WP ${wp.id}: the developer appeals findings [${a.findingIds.join(', ')}]: ` +
+            `${clampText(a.argument, 500)}\n  You MUST answer each with appealResponses ` +
+            `(uphold or withdraw).`);
+    });
+    if (parts.length === 0)
+        return null;
+    return { priority: 7, title: 'APPEAL', body: parts.join('\n') };
+}
+function inspectorSection(brief) {
+    const m = brief.inspector;
+    if (m === undefined)
+        return null;
+    const lines = [];
+    lines.push(`Registered integration commands: ${brief.run.integrationCommands.length > 0 ? brief.run.integrationCommands.join(' | ') : '(none - static verification only)'}`);
+    if (m.integrationAttempt !== undefined)
+        lines.push(`Integration attempt: ${m.integrationAttempt}`);
+    if (m.healthWarning === true) {
+        lines.push('Team health is low: check interface conflicts specifically.');
+    }
+    lines.push('Events already booked by the engine (do not re-book):');
+    lines.push(m.autoEvents.length > 0 ? bullet(m.autoEvents) : '- (none)');
+    lines.push('Open claims:');
+    lines.push(m.openClaims.length > 0
+        ? bullet(m.openClaims.map((c) => `${c.id} [${c.kind}] ${c.raisedBy} vs ${c.against} on ${c.wpId}: ${c.text}`))
+        : '- (none)');
+    lines.push('Mechanical flags:');
+    lines.push(m.flags.length > 0 ? bullet(m.flags) : '- (none)');
+    for (const [wpId, text] of Object.entries(m.reviewDigest))
+        lines.push(`Review ${wpId}: ${text}`);
+    for (const [wpId, text] of Object.entries(m.testDigest))
+        lines.push(`Test ${wpId}: ${text}`);
+    if (m.viewEvents !== undefined && m.viewEvents.length > 0) {
+        lines.push('View requests this phase:');
+        lines.push(bullet(m.viewEvents));
+    }
+    return { priority: 10, title: 'INSPECTOR BRIEF', body: lines.join('\n') };
+}
+function notesSection(brief) {
+    if (brief.notes === undefined)
+        return null;
+    if (brief.stage !== 'dev' && brief.stage !== 'fix')
+        return null;
+    const parts = brief.wps
+        .filter((wp) => (brief.notes?.[wp.id] ?? '').trim().length > 0)
+        .map((wp) => `WP ${wp.id}: ${clampText(brief.notes[wp.id], GOV_LIMITS.noteChars)}`);
+    if (parts.length === 0)
+        return null;
+    return { priority: 9, title: 'ORCHESTRATOR NOTE', body: parts.join('\n') };
+}
+function buildSections(brief) {
+    const wpIds = new Set(brief.wps.map((w) => w.id));
+    const isInspector = brief.role === 'INSP';
+    const sections = [
+        { priority: 1, title: 'TASK', body: taskInstruction(brief) },
+        brief.missingOnly !== undefined && brief.missingOnly.length > 0
+            ? {
+                priority: 1,
+                title: 'REMINDER',
+                body: `Your earlier attempt ended without a submission for: ` +
+                    `${brief.missingOnly.join(', ')}. Submit those now; they are the only ones listed.`,
+            }
+            : null,
+        brief.wps.length > 0
+            ? { priority: 2, title: 'WORK PACKAGES', body: brief.wps.map(describeWp).join('\n\n') }
+            : null,
+        describeContracts(brief.run.contracts, isInspector ? null : wpIds) === ''
+            ? null
+            : {
+                priority: 3,
+                title: 'CONTRACTS (exact interfaces shared between work packages)',
+                body: describeContracts(brief.run.contracts, isInspector ? null : wpIds),
+            },
+        reworkSection(brief),
+        brief.rcaText !== undefined && brief.rcaText.length > 0
+            ? { priority: 4, title: 'ROOT CAUSE ANALYSIS', body: brief.rcaText }
+            : null,
+        submissionSection(brief),
+        verdictSection(brief),
+        appealSection(brief),
+        {
+            priority: 8,
+            title: 'SPECIFICATION EXCERPT (priority: spec > charter and contracts > best practice)',
+            body: clampText(brief.run.spec, GOV_LIMITS.specExcerptChars),
+        },
+        notesSection(brief),
+        inspectorSection(brief),
+    ];
+    return sections.filter((s) => s !== null);
+}
+/**
+ * Join sections by priority under `budget` characters, clipping from the LOW-priority end
+ * and marking every clipped section. The task instruction is never clipped: a brief
+ * without its instruction is a brief that cannot be followed.
+ */
+export function assemblePrompt(sections, budget) {
+    const ordered = [...sections].sort((a, b) => a.priority - b.priority);
+    const render = (s, body) => `## ${s.title}\n${body}`;
+    const rendered = ordered.map((s) => render(s, s.body));
+    const total = rendered.reduce((n, r) => n + r.length + 2, 0);
+    if (total <= budget)
+        return rendered.join('\n\n');
+    const out = [];
+    let remaining = budget;
+    for (const s of ordered) {
+        const full = render(s, s.body);
+        const cost = full.length + 2;
+        if (cost <= remaining || s.priority === 1) {
+            out.push(full);
+            remaining -= cost;
+            continue;
+        }
+        const header = `## ${s.title}\n`;
+        const room = remaining - header.length - TRUNCATION_MARK.length - 3;
+        if (room < 60)
+            continue;
+        out.push(`${header}${s.body.slice(0, room)} ${TRUNCATION_MARK}`);
+        remaining = 0;
+    }
+    return out.join('\n\n');
+}
+function describe(brief) {
+    const ids = brief.wps.map((w) => w.id).join(',');
+    const head = brief.role === 'INSP' ? `INSP ${brief.stage}` : `${ROLE_WORD[brief.role]} ${ids}`;
+    const tail = brief.stage === 'dev'
+        ? 'implement'
+        : brief.stage === 'fix'
+            ? 'align interfaces'
+            : brief.stage === 'review'
+                ? 'review'
+                : brief.stage === 'test'
+                    ? 'verify'
+                    : brief.stage;
+    return clampText(`${head}: ${tail}`, TEAM_LIMITS.descriptionChars);
+}
+/**
+ * Build one `SubagentSpec`. The label IS the roster identity, which already satisfies
+ * `[a-z0-9-]{1,12}`; the guard below catches a future identity scheme that does not,
+ * rather than letting `TeamRuntime` discover it as a dropped child.
+ */
+export function buildSubagentSpec(brief) {
+    const label = brief.identity.toLowerCase().slice(0, TEAM_LIMITS.labelChars);
+    if (!/^[a-z0-9-]{1,12}$/.test(label) || label === TEAM_AGGREGATE_LABEL) {
+        throw new Error(`governance: identity "${brief.identity}" is not a legal subagent label`);
+    }
+    const ext = {
+        role: brief.role,
+        identity: brief.identity,
+        runId: brief.run.runId,
+        phase: brief.phase,
+        stage: brief.stage,
+        wpIds: brief.wps.map((w) => w.id),
+        tokens: brief.tokens,
+        generation: brief.generation,
+        profile: brief.run.profile,
+        ...(brief.predecessor ? { predecessorAnalysis: brief.predecessor } : {}),
+        ...(brief.role === 'INSP' ? { integrationCommands: [...brief.run.integrationCommands] } : {}),
+    };
+    const prompt = assemblePrompt(buildSections(brief), TEAM_LIMITS.promptChars);
+    return {
+        label,
+        description: describe(brief),
+        prompt,
+        readOnly: false,
+        governance: ext,
+    };
+}
+/** Convenience for tests and the engine: render derived required changes from a review. */
+export function requiredChangesOf(review) {
+    return review.requiredChanges;
+}

package/dist/governance/engine/stage-runner.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `gov_dispatch`: run one stage of the current phase (governance-mode 7.2, 8.2-8.4).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE DIVISION OF LABOUR. This module owns everything BEFORE and AFTER the children run:
+ * legality, budget, assignment, briefs, the stage record, the single automatic redispatch of
+ * whatever came back without a submission, the pause on abort, and the digest. It owns NONE
+ * of the judgement: when a child calls `gov_submit_*` / `ledger_*` the adjudication half
+ * (`submissions.ts`, `inspector.ts`) books the ledger and routes the work package
+ * synchronously inside that tool call. That is why a stage that is aborted half way keeps
+ * every submission already made, and why "resume re-runs only what is missing" needs no
+ * bookkeeping here: a routed WP is simply no longer eligible for the stage.
+ *
+ * A MISSING SUBMISSION IS NOT A MISDEED (8.4). Infrastructure failures, a model that
+ * wandered off and a context that ran out all look the same from here, so the first answer
+ * is one reminder-bearing redispatch of only the missing WPs, and the second is `blocked`
+ * with `blockedAt` set to this stage - never a deduction.
+ */
+import type { EngineCore } from './engine-core.js';
+/** `gov_dispatch`. Always returns text; an interrupted stage is `PAUSED:`, not an error. */
+export declare function runStage(core: EngineCore, raw: unknown, signal?: AbortSignal): Promise<string>;