@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/engine/engine.js

@@ -0,0 +1,314 @@
+/**
+ * GovernanceEngine - the facade the tools, the wiring and the UI call
+ * (governance-mode 14.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Thin on purpose: the work lives in `lifecycle.ts` (run state), `stage-runner.ts`
+ * (dispatch), `submissions.ts` / `inspector.ts` (what children submit) and `engine-core.ts`
+ * (state, persistence, events). This class composes them and adds the read-side child
+ * entry points (`gov_read`, `gov_view`, `ledger_standings`, scan) that need nothing but the
+ * visibility matrix and the submission cache.
+ *
+ * NOTHING HERE THROWS TO THE MODEL. Every entry point converts an unexpected failure into a
+ * `NOT ACCEPTED: internal error` result: a thrown exception inside a tool call becomes an
+ * error result that invites an identical retry, and a governed run has no way to explain
+ * "the engine crashed" to a child in any other voice.
+ */
+import { getLogger } from '../../logging/logger.js';
+import { scanPaths, formatScanReport } from '../tools/scan-incomplete.js';
+import { GOV_LIMITS } from '../limits.js';
+import { findingsForFile } from './visibility.js';
+import { accessFor, decideView, formatPage, formatReadableList, listReadable, pageText, } from './visibility.js';
+import { parseArtifactId } from '../store/artifacts.js';
+import { EngineCore } from './engine-core.js';
+import { currentDisplayPhase } from './engine-core.js';
+import { handleInspectorApply, handleInspectorRule, handleInspectorSettle } from './inspector.js';
+import { abandonRun, closeRun, resolveEscalation, resumeRun, startRun, statusText, } from './lifecycle.js';
+import { cancelPause, requestPause } from './pause.js';
+import { renderStandings } from './report.js';
+import { runStage } from './stage-runner.js';
+import { handleSubmitReview, handleSubmitTest, handleSubmitWork } from './submissions.js';
+import { isRecord } from '../tools/normalize-util.js';
+const FILE_LIKE = /[\w./\\-]+\.[A-Za-z0-9]{1,8}/g;
+function internalError(where, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    getLogger().warn('agent', 'governance.engine.internal_error', {
+        where,
+        error: message.slice(0, 300),
+    });
+    return (`NOT ACCEPTED: internal error in ${where} (${message.slice(0, 160)}). ` +
+        'Nothing was recorded and no GT was deducted; retry once, then tell the orchestrator.');
+}
+function viewerOf(identity) {
+    return identity.role;
+}
+/** Text a viewer gets for one artifact at access level `access`. */
+function renderForAccess(item, access, markdown) {
+    switch (access) {
+        case 'full':
+            return markdown;
+        case 'summary': {
+            const summary = 'summary' in item && typeof item.summary === 'string' ? item.summary : '';
+            return summary !== '' ? `Summary only: ${summary}` : 'Summary only: (none recorded)';
+        }
+        case 'verdict': {
+            const verdict = 'verdict' in item ? String(item.verdict) : 'n/a';
+            return `Conclusion only: ${verdict}`;
+        }
+        case 'changes': {
+            const files = 'filesChanged' in item ? item.filesChanged : [];
+            return `Files changed: ${files.join(', ') || '(none)'}`;
+        }
+        case 'none':
+            return '';
+    }
+}
+export class GovernanceEngine {
+    core;
+    constructor(deps) {
+        this.core = new EngineCore(deps);
+    }
+    /** Exposed for tests and the wiring's persistence helpers; not part of the tool surface. */
+    get internals() {
+        return this.core;
+    }
+    // ---------------------------------------------------------------------------
+    // Orchestrator surface (async, flushed)
+    // ---------------------------------------------------------------------------
+    async start(input, signal) {
+        return this.guard('start', () => startRun(this.core, input, signal));
+    }
+    status() {
+        try {
+            return statusText(this.core);
+        }
+        catch (error) {
+            return internalError('status', error);
+        }
+    }
+    async resume(runId) {
+        return this.guard('resume', () => resumeRun(this.core, runId));
+    }
+    async dispatchStage(input, signal) {
+        return this.guard('dispatch', () => runStage(this.core, input, signal));
+    }
+    async close(summary) {
+        return this.guard('close', () => closeRun(this.core, summary));
+    }
+    async abandon(reason) {
+        return this.guard('abandon', () => abandonRun(this.core, reason));
+    }
+    async resolve(input) {
+        return this.guard('resolve', () => resolveEscalation(this.core, input));
+    }
+    async guard(where, fn) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            return internalError(where, error);
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // UI / wiring surface
+    // ---------------------------------------------------------------------------
+    snapshot() {
+        return this.core.snapshot();
+    }
+    isStageRunning() {
+        return this.core.isStageRunning();
+    }
+    abortStage() {
+        this.core.abortStage();
+    }
+    /**
+     * `/gov pause`: stop at the next clean boundary (governance-mode-v1-1 6). A human
+     * decision, so it is NOT on `GovernanceEngineApi` and no tool can reach it.
+     */
+    requestPause() {
+        return requestPause(this.core);
+    }
+    /** `/gov pause cancel`: true when a pending request was withdrawn. */
+    cancelPause() {
+        return cancelPause(this.core);
+    }
+    subscribe(listener) {
+        return this.core.subscribe(listener);
+    }
+    /**
+     * Stop timers and release the run lock WITHOUT closing the run: quitting the CLI leaves
+     * the run resumable (D-12), exactly as an Esc does.
+     */
+    dispose() {
+        const runId = this.core.run?.runId;
+        if (this.core.isStageRunning())
+            this.core.abortStage();
+        if (runId !== undefined) {
+            this.core.deps.store.stopHeartbeat(runId);
+            void this.core.deps.store.releaseLock(runId).catch(() => undefined);
+        }
+        this.core.dispose();
+    }
+    // ---------------------------------------------------------------------------
+    // Child entry points (synchronous: a tool call cannot wait on the disk)
+    // ---------------------------------------------------------------------------
+    submitWork(identity, input) {
+        return this.child('gov_submit_work', () => handleSubmitWork(this.core, identity, input));
+    }
+    submitReview(identity, input) {
+        return this.child('gov_submit_review', () => handleSubmitReview(this.core, identity, input));
+    }
+    submitTest(identity, input) {
+        return this.child('gov_submit_test', () => handleSubmitTest(this.core, identity, input));
+    }
+    inspectorApply(input) {
+        return this.child('ledger_apply', () => handleInspectorApply(this.core, input));
+    }
+    inspectorRule(input) {
+        return this.child('ledger_rule', () => handleInspectorRule(this.core, input));
+    }
+    inspectorSettle(input) {
+        return this.child('ledger_settle', () => handleInspectorSettle(this.core, input));
+    }
+    child(where, fn) {
+        try {
+            return fn();
+        }
+        catch (error) {
+            return internalError(where, error);
+        }
+    }
+    standings() {
+        if (this.core.run === null)
+            return 'OK: no governance run is active.';
+        return `OK: standings\n${renderStandings(this.core.standingRows(), this.core.health())}`;
+    }
+    // ---------------------------------------------------------------------------
+    // gov_read / gov_view / gov_scan
+    // ---------------------------------------------------------------------------
+    refs() {
+        const out = [];
+        for (const id of this.core.submissionCache.keys()) {
+            const ref = parseArtifactId(id);
+            if (ref)
+                out.push(ref);
+        }
+        return out.sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }));
+    }
+    deny(identity, id, why) {
+        this.core.log('view_denied', identity.id, { id, why });
+        const phase = currentDisplayPhase(this.core.run);
+        const log = this.core.viewLog.get(phase) ?? [];
+        this.core.viewLog.set(phase, [...log, `denied ${identity.id}: ${id} (${why})`].slice(-20));
+        return `NOT ACCEPTED: ${id} is not visible to your role (${identity.role}). The information ` +
+            'boundary is deliberate; use gov_read {"list":true} to see what you may read.';
+    }
+    readArtifact(identity, input) {
+        return this.child('gov_read', () => this.doRead(identity, input));
+    }
+    doRead(identity, input) {
+        if (this.core.run === null)
+            return 'NOT ACCEPTED: no governance run is active.';
+        const request = isRecord(input) ? input : {};
+        const viewer = viewerOf(identity);
+        if (request.list === true || typeof request.id !== 'string') {
+            return formatReadableList(listReadable({ viewer, identity: identity.id, refs: this.refs() }));
+        }
+        const id = request.id;
+        const ref = parseArtifactId(id);
+        const item = ref ? this.core.submissionCache.get(ref.id) : undefined;
+        if (ref === null || item === undefined) {
+            return `NOT ACCEPTED: no artifact with id "${id.slice(0, 80)}". Use gov_read {"list":true}.`;
+        }
+        const access = accessFor(viewer, ref.kind, ref.identity === identity.id ? 'own' : 'other');
+        if (access === 'none')
+            return this.deny(identity, id, 'role');
+        const markdown = JSON.stringify(item, null, 2);
+        const offset = typeof request.offset === 'number' ? request.offset : 0;
+        return formatPage(id, pageText(renderForAccess(item, access, markdown), offset));
+    }
+    requestView(identity, input) {
+        return this.child('gov_view', () => this.doView(identity, input));
+    }
+    doView(identity, input) {
+        const run = this.core.run;
+        if (run === null)
+            return 'NOT ACCEPTED: no governance run is active.';
+        const request = isRecord(input) ? input : {};
+        const target = typeof request.target === 'string' ? request.target : '';
+        const reason = typeof request.reason === 'string' ? request.reason : '';
+        const lower = target.toLowerCase();
+        const kind = lower.includes('test')
+            ? 'test'
+            : lower.includes('work') || lower.includes('dev')
+                ? 'work'
+                : lower.includes('inspector')
+                    ? 'inspector'
+                    : 'review';
+        const file = target.match(FILE_LIKE)?.[0];
+        const used = this.core.viewRequests.get(identity.id) ?? 0;
+        const decision = decideView({
+            viewer: identity.role,
+            target: { kind, relation: 'other', ...(file ? { file } : {}) },
+            reason,
+            requestsUsed: used,
+            failingFiles: this.failingFiles(identity),
+        });
+        if (decision.consumesRequest)
+            this.core.viewRequests.set(identity.id, used + 1);
+        const type = decision.granted ? 'view_granted' : 'view_denied';
+        this.core.log(type, identity.id, { target: target.slice(0, 200), code: decision.code });
+        const phase = currentDisplayPhase(run);
+        this.core.viewLog.set(phase, [
+            ...(this.core.viewLog.get(phase) ?? []),
+            `${type} ${identity.id}: ${decision.code}`,
+        ].slice(-20));
+        if (!decision.granted)
+            return decision.message;
+        return `${decision.message}\n${this.scopedFindings(decision.scopeFile ?? '')}`;
+    }
+    failingFiles(identity) {
+        const files = new Set();
+        for (const item of this.core.submissionCache.values()) {
+            if (item.kind !== 'test' || item.identity !== identity.id)
+                continue;
+            const test = item;
+            const texts = [
+                ...test.issues.map((i) => i.description),
+                ...test.commands.map((c) => c.summary),
+            ];
+            for (const text of texts)
+                for (const f of text.match(FILE_LIKE) ?? [])
+                    files.add(f);
+        }
+        return [...files];
+    }
+    scopedFindings(file) {
+        const lines = [];
+        for (const item of this.core.submissionCache.values()) {
+            if (item.kind !== 'review')
+                continue;
+            const review = item;
+            for (const f of findingsForFile(review.findings, file)) {
+                const where = f.line ? `${f.file}:${f.line}` : f.file;
+                lines.push(`[${f.severity}] ${where} ${f.issue} -> ${f.requiredChange}`);
+            }
+        }
+        return lines.length > 0 ? lines.slice(0, 20).join('\n') : '(no findings in that file)';
+    }
+    scan(_identity, input) {
+        const paths = isRecord(input) && Array.isArray(input.paths)
+            ? input.paths.filter((p) => typeof p === 'string')
+            : [];
+        if (paths.length === 0)
+            return 'NOT ACCEPTED: scan needs at least one path.';
+        const capped = paths.slice(0, GOV_LIMITS.scanPathsMax);
+        return scanPaths({ cwd: this.core.deps.getCwd(), paths: capped })
+            .then(formatScanReport)
+            .catch((error) => internalError('gov_scan', error));
+    }
+}
+export function createGovernanceEngine(deps) {
+    return new GovernanceEngine(deps);
+}

package/dist/governance/engine/estimate.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `estimateDispatches` - how many `gov_dispatch` calls a plan needs, and nothing more
+ * (governance-mode-v1-1 7.3, V-5).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * ONLY THE QUANTITIES THAT CAN BE PROVEN TRUE. A total "upper bound" is NOT one of them:
+ * the rework cap is per work package and different work packages can be sent back in
+ * different rounds, authorised grants raise the caps, and chunking multiplies the calls a
+ * stage needs. So this module reports the clean-run count (chunking included), what ONE
+ * more rework round or fix cycle can add, and the hard per-run cap - and the formatter that
+ * prints it must never call any of them a ceiling on the total.
+ *
+ * The chunk sizes come from `stageChunkSize` (the same function `checkStage` enforces), so
+ * the estimate cannot drift from what the legality gate will actually demand.
+ */
+import type { RunState } from '../types.js';
+export interface DispatchEstimateInput {
+    /** Work packages per planned phase, in phase order. */
+    phaseWpCounts: readonly number[];
+    /** The ceiling `checkStage` enforces: `min(team.maxSubagents, hard cap)`. */
+    teamCeiling: number;
+}
+export interface DispatchEstimate {
+    /** Calls for a run with no rework, no fix cycle and a first-try integration. */
+    cleanRun: number;
+    /** The most one rework round can add in a single phase (dev + review + test). */
+    perReworkRound: number;
+    /** The most one fix cycle can add in a single phase (fix + the integrate after it). */
+    perFixCycle: number;
+    /** `GOV_LIMITS.hardMaxDispatches`: per run. */
+    hardCap: number;
+    /** Some phase is wider than the ceiling, so its stages are split into several calls. */
+    chunked: boolean;
+}
+export declare function estimateDispatches(input: DispatchEstimateInput): DispatchEstimate;
+/** The estimate for a run (or a plan) that already has its phases. */
+export declare function estimateForRun(run: Pick<RunState, 'phases'>, teamCeiling: number): DispatchEstimate;

package/dist/governance/engine/estimate.js

@@ -0,0 +1,46 @@
+/**
+ * `estimateDispatches` - how many `gov_dispatch` calls a plan needs, and nothing more
+ * (governance-mode-v1-1 7.3, V-5).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * ONLY THE QUANTITIES THAT CAN BE PROVEN TRUE. A total "upper bound" is NOT one of them:
+ * the rework cap is per work package and different work packages can be sent back in
+ * different rounds, authorised grants raise the caps, and chunking multiplies the calls a
+ * stage needs. So this module reports the clean-run count (chunking included), what ONE
+ * more rework round or fix cycle can add, and the hard per-run cap - and the formatter that
+ * prints it must never call any of them a ceiling on the total.
+ *
+ * The chunk sizes come from `stageChunkSize` (the same function `checkStage` enforces), so
+ * the estimate cannot drift from what the legality gate will actually demand.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { stageChunkSize } from './state-machine.js';
+/** Calls one stage needs over `wpCount` work packages at `ceiling`. */
+function callsFor(stage, wpCount, ceiling) {
+    if (wpCount <= 0)
+        return 0;
+    const size = stageChunkSize(stage, ceiling);
+    return Number.isFinite(size) ? Math.ceil(wpCount / size) : 1;
+}
+/** Calls that always happen once per phase: the settle and the first integrate. */
+const FIXED_CALLS_PER_PHASE = 2;
+export function estimateDispatches(input) {
+    const counts = input.phaseWpCounts.filter((w) => w > 0);
+    const at = (stage, w) => callsFor(stage, w, input.teamCeiling);
+    const roundOf = (w) => at('dev', w) + at('review', w) + at('test', w);
+    return {
+        cleanRun: counts.reduce((sum, w) => sum + roundOf(w) + FIXED_CALLS_PER_PHASE, 0),
+        perReworkRound: Math.max(0, ...counts.map(roundOf)),
+        perFixCycle: counts.length === 0 ? 0 : Math.max(...counts.map((w) => at('fix', w))) + 1,
+        hardCap: GOV_LIMITS.hardMaxDispatches,
+        chunked: counts.some((w) => w > Math.max(1, Math.floor(input.teamCeiling))),
+    };
+}
+/** The estimate for a run (or a plan) that already has its phases. */
+export function estimateForRun(run, teamCeiling) {
+    return estimateDispatches({
+        phaseWpCounts: run.phases.map((phase) => phase.wpIds.length),
+        teamCeiling,
+    });
+}

package/dist/governance/engine/inspector.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `ledger_apply` / `ledger_rule` / `ledger_settle` - the engine side (governance-mode 5.4,
+ * 5.6, 5.7, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE INSPECTOR HAS NO SECOND ACCOUNTING PATH (I-G7). Everything it books goes through the
+ * same `core.ledgerOp` as the engine's own events, with the same catalogue deltas and the
+ * same caps; the only difference is `by: "inspector:insp"` and the evidence it must attach.
+ * It cannot name its own amount, cannot target itself (I-G5) and cannot book a mechanical
+ * code - those are refused here even if the tool layer let them through.
+ */
+import type { EngineCore } from './engine-core.js';
+export declare function handleInspectorApply(core: EngineCore, input: unknown): string;
+export declare function handleInspectorRule(core: EngineCore, input: unknown): string;
+export declare function handleInspectorSettle(core: EngineCore, input: unknown): string;