@aragon-agent/cli 0.6.44 → 0.6.46

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

@@ -0,0 +1,66 @@
+/**
+ * Fixed-size text the orchestrator and the user read (governance-mode D-16, 8.6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Two outputs with two different readers and two different budgets:
+ *  - `buildDigest` is the TOOL RESULT of every `gov_run` / `gov_dispatch`. It lands in the
+ *    orchestrator's context for the rest of a run that may last hours, so it is bounded in
+ *    BYTES (`ToolExecutor` truncates combined tool text at 100 000 bytes, and a long CJK
+ *    request turns into three bytes per character) and it always ends with `NEXT:` - the
+ *    legal next actions - so a compacted or `/clear`ed orchestrator can resume by reading
+ *    its own last tool result.
+ *  - `buildBoardMarkdown` / `buildFinalReport` are human documents written to disk.
+ *
+ * When a digest must be clipped, the MIDDLE is dropped: the head (what happened) and the
+ * tail (`NEXT:`) are the two parts the reader cannot do without.
+ */
+import type { Claim, Escalation, LedgerEntry, RunState, StandingRow, WorkPackage } from '../types.js';
+export declare function wpStatusWord(status: WorkPackage['status']): string;
+/** Clip a string to `maxBytes` UTF-8 bytes without splitting a code point. */
+export declare function clipBytes(text: string, maxBytes: number): string;
+export declare function formatScore(row: StandingRow): string;
+export declare function renderStandings(rows: StandingRow[], health: number | null): string;
+export declare function renderWpTable(run: RunState): string;
+export declare function renderPhases(run: RunState): string;
+export declare function renderLedgerLine(entry: LedgerEntry, agentId: string): string;
+export interface DigestInput {
+    /** First line, begins with `OK:` / `NOT ACCEPTED:` / `ESCALATION:`. */
+    headline: string;
+    /** Result lines (per WP / per agent). */
+    results: string[];
+    /** Ledger lines booked by this call. */
+    ledger: string[];
+    standings?: string;
+    warnings: string[];
+    nextActions: string[];
+    /** Always printed, e.g. limits and usage. */
+    footer?: string[];
+}
+/**
+ * Compose a digest under `GOV_LIMITS.digestMaxBytes`. `NEXT:` is the only part that is
+ * never clipped; over budget, results are dropped from the end first, then ledger lines.
+ */
+export declare function buildDigest(input: DigestInput, maxBytes?: number): string;
+export interface BoardInput {
+    run: RunState;
+    standings: StandingRow[];
+    health: number | null;
+    recent: Array<{
+        entry: LedgerEntry;
+        agentId: string;
+    }>;
+}
+/** The human-readable projection rewritten at stage end and at close (`board.md`). */
+export declare function buildBoardMarkdown(input: BoardInput): string;
+export declare function renderClaim(c: Claim): string;
+export declare function renderEscalation(e: Escalation): string;
+export interface FinalReportInput extends BoardInput {
+    summary?: string;
+    wallMs: number;
+}
+/**
+ * The closing report: what was delivered, what was accepted with known issues, what was
+ * dropped, final standings. Bounded by `finalReportMaxBytes`.
+ */
+export declare function buildFinalReport(input: FinalReportInput): string;

package/dist/governance/engine/report.js

@@ -0,0 +1,220 @@
+/**
+ * Fixed-size text the orchestrator and the user read (governance-mode D-16, 8.6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Two outputs with two different readers and two different budgets:
+ *  - `buildDigest` is the TOOL RESULT of every `gov_run` / `gov_dispatch`. It lands in the
+ *    orchestrator's context for the rest of a run that may last hours, so it is bounded in
+ *    BYTES (`ToolExecutor` truncates combined tool text at 100 000 bytes, and a long CJK
+ *    request turns into three bytes per character) and it always ends with `NEXT:` - the
+ *    legal next actions - so a compacted or `/clear`ed orchestrator can resume by reading
+ *    its own last tool result.
+ *  - `buildBoardMarkdown` / `buildFinalReport` are human documents written to disk.
+ *
+ * When a digest must be clipped, the MIDDLE is dropped: the head (what happened) and the
+ * tail (`NEXT:`) are the two parts the reader cannot do without.
+ */
+import { GOV_LIMITS } from '../limits.js';
+const WP_STATUS_WORD = {
+    pending: 'pending',
+    dev_running: 'developing',
+    awaiting_review: 'awaiting review',
+    review_running: 'in review',
+    awaiting_test: 'awaiting test',
+    test_running: 'in test',
+    rework: 'rework',
+    tested_ok: 'tested ok',
+    integrated: 'integrated',
+    blocked: 'BLOCKED',
+    dropped: 'dropped',
+};
+export function wpStatusWord(status) {
+    return WP_STATUS_WORD[status];
+}
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/** Clip a string to `maxBytes` UTF-8 bytes without splitting a code point. */
+export function clipBytes(text, maxBytes) {
+    if (byteLength(text) <= maxBytes)
+        return text;
+    let out = '';
+    let used = 0;
+    for (const ch of text) {
+        const size = byteLength(ch);
+        if (used + size > maxBytes)
+            break;
+        out += ch;
+        used += size;
+    }
+    return out;
+}
+export function formatScore(row) {
+    const conf = row.confirmed;
+    if (row.provisional > 0)
+        return `${conf + row.provisional} (${conf} + ${row.provisional}P)`;
+    return String(conf);
+}
+export function renderStandings(rows, health) {
+    if (rows.length === 0)
+        return 'Standings: (no scored agents yet)';
+    const lines = rows.map((r) => {
+        const gen = r.generation > 0 ? ` gen${r.generation}` : '';
+        const tail = r.status === 'eliminated'
+            ? `ELIMINATED${r.replacedBy ? ` (replaced by ${r.replacedBy})` : ''}`
+            : r.label;
+        return `  ${r.id.padEnd(8)} ${r.role.padEnd(4)}${gen} ${formatScore(r).padEnd(14)} ${tail}`;
+    });
+    const healthLine = health === null ? '' : `\n  team health: ${Math.round(health)}`;
+    return `Standings (GT = governance tokens, unrelated to LLM context tokens):\n${lines.join('\n')}${healthLine}`;
+}
+export function renderWpTable(run) {
+    const lines = run.wpOrder
+        .map((id) => run.workPackages[id])
+        .filter((w) => w !== undefined)
+        .map((w) => {
+        const extra = [];
+        if (w.reworkCount > 0)
+            extra.push(`rework ${w.reworkCount}`);
+        if (w.status === 'blocked' && w.blockedAt)
+            extra.push(`blocked at ${w.blockedAt}`);
+        if (w.acceptedWithIssues)
+            extra.push('accepted with issues');
+        return `  ${w.id.padEnd(16)} p${w.phase + 1}  ${wpStatusWord(w.status)}${extra.length > 0 ? ` (${extra.join(', ')})` : ''}`;
+    });
+    return `Work packages:\n${lines.join('\n')}`;
+}
+function describePhase(p) {
+    const flags = [];
+    if (p.settled)
+        flags.push('settled');
+    if (p.integrated) {
+        flags.push(p.integrationAccepted ? 'integrated' : 'integration FAILED, accepted by user');
+    }
+    if (p.fixCycles > 0)
+        flags.push(`fix cycles ${p.fixCycles}`);
+    return `  phase ${p.index + 1}: ${p.wpIds.join(', ')}${flags.length > 0 ? ` [${flags.join(', ')}]` : ''}`;
+}
+export function renderPhases(run) {
+    return `Phases:\n${run.phases.map(describePhase).join('\n')}`;
+}
+export function renderLedgerLine(entry, agentId) {
+    const sign = entry.delta > 0 ? '+' : '';
+    const pool = entry.settlement === 'provisional' ? 'P' : '';
+    const cap = entry.capped ? ` (capped from ${entry.capped.requested})` : '';
+    return `${agentId} ${sign}${entry.delta}${pool} ${entry.code} ${entry.reason}${cap}`;
+}
+/**
+ * Compose a digest under `GOV_LIMITS.digestMaxBytes`. `NEXT:` is the only part that is
+ * never clipped; over budget, results are dropped from the end first, then ledger lines.
+ */
+export function buildDigest(input, maxBytes = GOV_LIMITS.digestMaxBytes) {
+    const tail = [
+        ...(input.footer ?? []),
+        input.nextActions.length > 0 ? `NEXT:\n${input.nextActions.map((n) => `  ${n}`).join('\n')}` : 'NEXT: (none)',
+    ].join('\n');
+    const warn = input.warnings.map((w) => `${w}`);
+    const parts = (results, ledger, standings) => [
+        input.headline,
+        ...results,
+        ...(ledger.length > 0 ? ['Ledger:', ...ledger.map((l) => `  ${l}`)] : []),
+        ...(standings && input.standings ? [input.standings] : []),
+        ...warn,
+        tail,
+    ].join('\n');
+    let results = [...input.results];
+    let ledger = [...input.ledger];
+    let text = parts(results, ledger, true);
+    if (byteLength(text) <= maxBytes)
+        return text;
+    text = parts(results, ledger, false);
+    while (byteLength(text) > maxBytes && ledger.length > 3) {
+        ledger = ledger.slice(0, ledger.length - 1);
+        text = parts(results, [...ledger, `(+ more ledger rows; see gov_run status)`], false);
+    }
+    while (byteLength(text) > maxBytes && results.length > 4) {
+        results = results.slice(0, results.length - 1);
+        text = parts([...results, '(+ more results omitted)'], ledger, false);
+    }
+    if (byteLength(text) > maxBytes) {
+        const headBudget = Math.max(200, maxBytes - byteLength(tail) - 40);
+        const head = clipBytes(parts(results, [], false).replace(tail, '').trimEnd(), headBudget);
+        text = `${head}\n(clipped)\n${tail}`;
+    }
+    return text;
+}
+/** The human-readable projection rewritten at stage end and at close (`board.md`). */
+export function buildBoardMarkdown(input) {
+    const { run } = input;
+    const lines = [
+        `# Governance run ${run.runId}`,
+        '',
+        `Goal: ${run.goal}`,
+        `Status: ${run.status}   Profile: ${run.profile}`,
+        '',
+        '```',
+        renderPhases(run),
+        '',
+        renderWpTable(run),
+        '',
+        renderStandings(input.standings, input.health),
+        '```',
+    ];
+    if (run.escalations.length > 0) {
+        lines.push('', '## Escalations');
+        for (const e of run.escalations)
+            lines.push(renderEscalation(e));
+    }
+    if (run.claims.length > 0) {
+        lines.push('', '## Claims');
+        for (const c of run.claims)
+            lines.push(renderClaim(c));
+    }
+    if (input.recent.length > 0) {
+        lines.push('', '## Recent ledger');
+        for (const r of input.recent.slice(-40))
+            lines.push(`- ${renderLedgerLine(r.entry, r.agentId)}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderClaim(c) {
+    const ruling = c.rulingText ? ` - ${c.rulingText}` : '';
+    return `- ${c.id} [${c.kind}] ${c.raisedBy} vs ${c.against} on ${c.wpId}: ${c.status}${ruling}`;
+}
+export function renderEscalation(e) {
+    const ruling = e.ruling ? ` - ruling: ${e.ruling}` : '';
+    return `- ${e.id} [${e.kind}] ${e.topic}: ${e.status}${ruling}`;
+}
+/**
+ * The closing report: what was delivered, what was accepted with known issues, what was
+ * dropped, final standings. Bounded by `finalReportMaxBytes`.
+ */
+export function buildFinalReport(input) {
+    const { run } = input;
+    const wps = run.wpOrder.map((id) => run.workPackages[id]).filter((w) => !!w);
+    const delivered = wps.filter((w) => w.status === 'integrated' && !w.acceptedWithIssues);
+    const withIssues = wps.filter((w) => w.acceptedWithIssues);
+    const dropped = wps.filter((w) => w.status === 'dropped');
+    const open = wps.filter((w) => !['integrated', 'dropped'].includes(w.status));
+    const lines = [`# Final report - run ${run.runId}`, '', `Goal: ${run.goal}`, ''];
+    if (input.summary)
+        lines.push(`Orchestrator summary: ${input.summary}`, '');
+    lines.push(`Delivered (${delivered.length}): ${delivered.map((w) => w.id).join(', ') || '(none)'}`);
+    if (withIssues.length > 0) {
+        lines.push(`Accepted WITH ISSUES (${withIssues.length}): ${withIssues.map((w) => w.id).join(', ')}`);
+    }
+    if (dropped.length > 0)
+        lines.push(`Not delivered (dropped): ${dropped.map((w) => w.id).join(', ')}`);
+    if (open.length > 0)
+        lines.push(`UNFINISHED: ${open.map((w) => w.id).join(', ')}`);
+    const failedPhases = run.phases.filter((p) => p.integrated && !p.integrationAccepted);
+    if (failedPhases.length > 0) {
+        lines.push(`Integration FAILED but accepted by the user in phase(s): ${failedPhases
+            .map((p) => p.index + 1)
+            .join(', ')}`);
+    }
+    lines.push('', renderStandings(input.standings, input.health), '');
+    lines.push(`Team tokens: input ${run.usage.inputTokens}, output ${run.usage.outputTokens}, cost ${run.usage.costUsd === null ? 'pricing unknown' : `$${run.usage.costUsd.toFixed(4)}`}; wall ${Math.round(input.wallMs / 1000)}s`);
+    return clipBytes(`${lines.join('\n')}\n`, GOV_LIMITS.finalReportMaxBytes);
+}

package/dist/governance/engine/run-digest.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `RunDigest` - one run reduced to eight scalars for `/gov runs` (governance-mode-v1-1 7.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * WHY A DIGEST AND NOT THE RUN. `index.jsonl` is append-only and read whole by
+ * `listRuns()`, so a row must stay small (< 400 B) and must not need `run.json`: listing ten
+ * runs by opening ten run folders would race the engine that holds one of them. The digest
+ * is derived from the same in-memory copies `checkpoint()` already clones, so it costs no
+ * extra disk read and cannot disagree with the checkpoint it rides.
+ *
+ * UNKNOWN IS NOT ZERO. `costUsd` is `null` whenever the run's price is unknown (v1 8.5 /
+ * C-11): a run whose dispatches could not be priced must read as `n/a`, never `$0.00`.
+ *
+ * HEALTH IS ROUNDED TO A WHOLE NUMBER. Every ledger delta moves the mean, and a digest that
+ * changed on every fraction would append an index row per booking instead of per stage.
+ */
+import type { LedgerState, RunDigest, RunState } from '../types.js';
+export type { RunDigest };
+export declare function buildRunDigest(run: RunState, ledger: LedgerState): RunDigest;

package/dist/governance/engine/run-digest.js

@@ -0,0 +1,42 @@
+/**
+ * `RunDigest` - one run reduced to eight scalars for `/gov runs` (governance-mode-v1-1 7.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure.
+ *
+ * WHY A DIGEST AND NOT THE RUN. `index.jsonl` is append-only and read whole by
+ * `listRuns()`, so a row must stay small (< 400 B) and must not need `run.json`: listing ten
+ * runs by opening ten run folders would race the engine that holds one of them. The digest
+ * is derived from the same in-memory copies `checkpoint()` already clones, so it costs no
+ * extra disk read and cannot disagree with the checkpoint it rides.
+ *
+ * UNKNOWN IS NOT ZERO. `costUsd` is `null` whenever the run's price is unknown (v1 8.5 /
+ * C-11): a run whose dispatches could not be priced must read as `n/a`, never `$0.00`.
+ *
+ * HEALTH IS ROUNDED TO A WHOLE NUMBER. Every ledger delta moves the mean, and a digest that
+ * changed on every fraction would append an index row per booking instead of per stage.
+ */
+import { teamHealth } from '../rules/ledger-state.js';
+/** The phase to show: the first not-integrated one, else the last (mirrors the panel). */
+function displayPhase(run) {
+    if (run.phases.length === 0)
+        return 1;
+    const open = run.phases.find((p) => !p.integrated);
+    return (open ? open.index : run.phases.length - 1) + 1;
+}
+function finiteOrNull(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+export function buildRunDigest(run, ledger) {
+    const records = Object.values(ledger.agents);
+    const health = teamHealth(ledger);
+    return {
+        phase: displayPhase(run),
+        phaseCount: run.phases.length,
+        agents: records.length,
+        health: health === null ? null : Math.round(health),
+        tokens: run.usage.inputTokens + run.usage.outputTokens,
+        costUsd: finiteOrNull(run.usage.costUsd),
+        dispatches: run.dispatches,
+        eliminations: records.filter((a) => a.status === 'eliminated').length,
+    };
+}

package/dist/governance/engine/spec-builder.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 type { SubagentSpec } from '../../team/types.js';
+import type { Contract, FailureAnalysis, GovRole, ProfileId, ReviewSubmission, ReviewVerdict, StageKind, WorkPackage, WorkSubmission } from '../types.js';
+/** Marker appended to any clipped section. Stable: tests and models rely on it. */
+export declare const TRUNCATION_MARK = "[truncated]";
+export interface RequiredChange {
+    file: string;
+    issue: string;
+    change: string;
+}
+export interface BriefRun {
+    runId: string;
+    goal: string;
+    profile: ProfileId;
+    /** The verbatim spec (plus approved plan snapshot). */
+    spec: string;
+    contracts: Contract[];
+    integrationCommands: string[];
+}
+/**
+ * Everything one child may see. EVERY optional field is a section the caller chose to
+ * disclose to this role; absent means "not part of this role's view".
+ */
+export interface ChildBrief {
+    run: BriefRun;
+    /** Roster id, e.g. `dev1`. */
+    identity: string;
+    role: GovRole;
+    generation: number;
+    tokens: number;
+    /** 1-based phase number. */
+    phase: number;
+    stage: StageKind;
+    /** The WPs this child handles, in the fixed order they must be submitted. */
+    wps: WorkPackage[];
+    predecessor?: FailureAnalysis;
+    /** Same-batch peers, for the `team_send` hint (same role only, D-3). */
+    peers?: string[];
+    /** DEV / FIX: per-WP rework items written by the reviewer (the only feedback, D-7). */
+    requiredChanges?: Record<string, RequiredChange[]>;
+    /** FIX: the full RCA text. */
+    rcaText?: string;
+    /** REV / INSP: the DEV's submission per WP. TEST gets `changeLists` instead. */
+    workSubmissions?: Record<string, WorkSubmission>;
+    /** TEST: the changed-file list per WP (and nothing else of the DEV's report). */
+    changeLists?: Record<string, string[]>;
+    /** TEST / INSP: the review CONCLUSION per WP (never the comments, D-7). */
+    reviewVerdicts?: Record<string, ReviewVerdict>;
+    /** REV: the DEV's appeal per WP, plus the prior review's finding ids. */
+    appeals?: Record<string, {
+        findingIds: string[];
+        argument: string;
+    }>;
+    /** DEV: the developer's own previous submission summary on rework. */
+    previousOwn?: Record<string, string>;
+    /** Orchestrator notes, accepted for dev and fix only (6.2 rule 5). */
+    notes?: Record<string, string>;
+    /** Re-dispatch after a missing submission: only these WPs are listed. */
+    missingOnly?: string[];
+    /** INSP-only material. */
+    inspector?: InspectorMaterial;
+}
+export interface InspectorMaterial {
+    /** Compact lines of the events the engine already booked this phase. */
+    autoEvents: string[];
+    openClaims: Array<{
+        id: string;
+        kind: string;
+        raisedBy: string;
+        against: string;
+        wpId: string;
+        text: string;
+    }>;
+    /** Mechanical suspicion flags (D17 / R12 signatures, ownership violations). */
+    flags: string[];
+    /** Review findings per WP (full text), inspector has full visibility. */
+    reviewDigest: Record<string, string>;
+    testDigest: Record<string, string>;
+    /** Integration attempt context for `integrate`. */
+    integrationAttempt?: number;
+    healthWarning?: boolean;
+    viewEvents?: string[];
+}
+interface Section {
+    priority: number;
+    title: string;
+    body: string;
+}
+/**
+ * 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 declare function assemblePrompt(sections: Section[], budget: number): string;
+/**
+ * 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 declare function buildSubagentSpec(brief: ChildBrief): SubagentSpec;
+/** Convenience for tests and the engine: render derived required changes from a review. */
+export declare function requiredChangesOf(review: ReviewSubmission): RequiredChange[];
+export {};