@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/engine/digest.js

@@ -0,0 +1,63 @@
+/**
+ * Digest assembly shared by the lifecycle and the stage runner (governance-mode D-16).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * Every `gov_run` / `gov_dispatch` answer is built here from the same four parts: a
+ * headline that starts with `OK:` / `NOT ACCEPTED:` / `ESCALATION:` / `PAUSED:`, the result
+ * lines, a footer with the limits and the TEAM-token line, and `NEXT:`. One builder means
+ * one place that guarantees the prefix, the byte budget and the footer wording.
+ */
+import { GOV_LIMITS } from '../limits.js';
+import { nextActions } from './state-machine.js';
+import { budgetLine, budgetNotice } from './budget.js';
+import { buildDigest, renderStandings } from './report.js';
+/** The footer every digest carries: limits, then team tokens (never the session total). */
+export function footerLines(core) {
+    const run = core.run;
+    if (run === null)
+        return [];
+    const budget = core.config().budgetTokens;
+    const lines = [
+        `Limits: rework <= ${run.limits.maxRework} per WP, fix cycles <= ${run.limits.maxFixCycles} ` +
+            `per phase, stage width <= ${core.deps.getTeamCeiling()}, ` +
+            `dispatch ${run.dispatches}/${GOV_LIMITS.hardMaxDispatches}.`,
+        budgetLine(run.usage, budget),
+    ];
+    const notice = budgetNotice(run.usage, budget);
+    if (notice !== null && notice.startsWith('BUDGET WARNING'))
+        lines.push(notice);
+    return lines;
+}
+/**
+ * What a digest says to do next while the USER has paused the run (`/gov pause`). The usual
+ * `paused` answer is `gov_run resume`, which would invite the Orchestrator to resume a run
+ * its human just stopped; only the human resumes it (their `/gov resume` is what sends the
+ * Orchestrator to call `gov_run resume`).
+ */
+export const USER_PAUSED_NEXT = 'wait for the user: only they resume this run (/gov resume). Do not dispatch.';
+/** Compose a complete tool answer for the current run state. */
+export function composeDigest(core, parts) {
+    const run = core.run;
+    const waitingOnUser = core.userPaused && run?.status === 'paused';
+    const next = run === null
+        ? []
+        : waitingOnUser
+            ? [USER_PAUSED_NEXT]
+            : nextActions(run, { teamCeiling: core.deps.getTeamCeiling() });
+    return buildDigest({
+        headline: parts.headline,
+        results: parts.results ?? [],
+        ledger: parts.ledger ?? [],
+        ...(parts.standings === true && run !== null
+            ? { standings: renderStandings(core.standingRows(), core.health()) }
+            : {}),
+        warnings: parts.warnings ?? [],
+        nextActions: next,
+        footer: footerLines(core),
+    });
+}
+/** A refusal with the legal next moves attached (no run needed). */
+export function refusal(core, reason) {
+    return composeDigest(core, { headline: `NOT ACCEPTED: ${reason}` });
+}

package/dist/governance/engine/engine-core.d.ts

@@ -0,0 +1,219 @@
+/**
+ * EngineCore - the state, persistence and event plumbing every engine module shares
+ * (governance-mode 8.6, 12.1, 14.1).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * WHY MEMORY IS AUTHORITATIVE AND DISK IS A QUEUE. The child tools (`gov_submit_*`,
+ * `ledger_*`) are synchronous: a model's tool call returns text, and the executor does not
+ * wait for a disk round trip. The run store is asynchronous (atomic rename, fsync, a FIFO
+ * mutex). So every mutation lands in memory synchronously and is appended to ONE promise
+ * chain that preserves order; `flush()` is awaited at every point where the orchestrator
+ * is waiting anyway (end of a stage, start, close). The event log stays the truth: the
+ * engine owns the sequence counter and stamps each event BEFORE the write resolves, which
+ * is also what lets a ledger entry carry the same `seq` as the event that produced it
+ * (replay equivalence, I-G2).
+ *
+ * LEDGER MUTATIONS GO THROUGH `ledgerOp` AND NOWHERE ELSE (I-G1 / I-G7): one function that
+ * logs the op, applies it with the pure ledger, and reports the entries it booked. Nothing
+ * else in the tree touches `core.ledger`.
+ */
+import { type LedgerOp } from '../rules/ledger-replay.js';
+import type { LedgerState } from '../types.js';
+import type { DispatchOutcome, TeamEventListener } from '../../team/types.js';
+import type { SubagentSpec } from '../../team/types.js';
+import type { GovernanceConfig } from '../../config/governance-config.js';
+import type { ArtifactStore } from '../store/artifacts.js';
+import type { RunStore } from '../store/run-store.js';
+import type { GovAgentState, GovernanceEvent, GovernanceEventListener, GovernanceSnapshot, InspectorReport, LedgerEntry, PipelineStep, RunState, StandingRow, StoredEventType, Submission, WorkPackage } from '../types.js';
+import type { ModelCost } from '@aragon-agent/core';
+/** The slice of `TeamRuntime` the engine drives. A seam so tests inject a scripted runtime. */
+export interface TeamRuntimeLike {
+    dispatch(specs: SubagentSpec[], requested: number, signal?: AbortSignal): Promise<DispatchOutcome>;
+    subscribe(listener: TeamEventListener): () => void;
+    abortAll(): void;
+    isBusy(): boolean;
+}
+export interface EngineDeps {
+    runtime: TeamRuntimeLike;
+    store: RunStore;
+    artifacts: ArtifactStore;
+    /** Read LIVE every call: the user may change a limit mid-run. */
+    getConfig: () => GovernanceConfig;
+    /** `min(team.maxSubagents, TEAM_LIMITS.hardMaxSubagents)`, read live (D-24). */
+    getTeamCeiling: () => number;
+    getCwd: () => string;
+    getSessionId: () => string | undefined;
+    withPausedWatchdog: <T>(fn: () => Promise<T>) => Promise<T>;
+    hasApiKey: () => boolean;
+    modelCost?: () => ModelCost | undefined;
+    /** PLAN+GOVERN: take (and clear) the approved plan snapshot, if one is pending. */
+    takeApprovedPlan?: () => string | null;
+    /** Non-consuming read of the same snapshot, so a refused `start` does not lose the plan. */
+    peekApprovedPlan?: () => string | null;
+    /**
+     * `confirmCharter`: show the charter through the existing plan-review overlay. Resolves
+     * `null` on cancel / unavailable. Absent => no confirmation step.
+     */
+    confirmCharter?: (charter: CharterPlanInput, signal?: AbortSignal) => Promise<{
+        decision: 'approved' | 'revise' | 'dismissed';
+        feedback?: string;
+    } | null>;
+    now: () => number;
+}
+/** What the charter confirmation needs; the wiring turns it into a `NormalizedPlan`. */
+export interface CharterPlanInput {
+    title: string;
+    summary: string;
+    steps: Array<{
+        title: string;
+        detail: string;
+    }>;
+    filesTouched: string[];
+    risks: string[];
+}
+/** One ledger entry a `ledgerOp` booked, with the agent that holds it. */
+export interface BookedEntry {
+    agentId: string;
+    entry: LedgerEntry;
+}
+/** What the inspector's `ledger_settle` produced, for the digest and the next legal moves. */
+export interface InspectorOutcome {
+    kind: 'settle' | 'integrate';
+    phase: number;
+    /** For integrate: did integration pass (or get accepted)? */
+    passed: boolean;
+    headline: string;
+}
+export interface LedgerOpResult {
+    seq: number;
+    booked: BookedEntry[];
+}
+/** Give an op the stored-event seq so replay stamps exactly what the live path stamped. */
+export declare function stampOp(op: LedgerOp, seq: number): LedgerOp;
+export declare class EngineCore {
+    readonly deps: EngineDeps;
+    run: RunState | null;
+    ledger: LedgerState;
+    /** Monotone event counter; the engine owns it (see file header). */
+    seq: number;
+    /** True once the user left the run in a state a new `start` may replace. */
+    readOnly: boolean;
+    /** WP ids (or `insp`) that received a valid submission during the CURRENT stage run. */
+    stageSubmitted: Set<string>;
+    /** `${identity}|${wpId}` -> consecutive validation failures (>= maxValidationFailures => absent). */
+    validationFailures: Map<string, number>;
+    /** One line per result produced this stage (digest body). */
+    stageResults: string[];
+    /** One line per ledger booking this stage (digest ledger section). */
+    stageLedgerLines: string[];
+    /** Warnings to print under the digest (caps, escalations, tripwires). */
+    stageWarnings: string[];
+    /** Set by `ledger_settle`; consumed (and cleared) by the stage runner. */
+    inspectorOutcome: InspectorOutcome | null;
+    /**
+     * Accepted submissions and inspector reports by artifact id (adjudication half). The
+     * store is async but a child's tool call is not, so reads during a run come from here;
+     * the resume path repopulates it from the artifact store.
+     */
+    submissionCache: Map<string, Submission | InspectorReport>;
+    /** Set when an artifact write was refused for the 20 MB budget (spec 12.1). */
+    storageExhausted: boolean;
+    /** Mechanical suspicion flags per 0-based phase (ownership violations), for the inspector. */
+    phaseFlags: Map<number, string[]>;
+    /** `gov_view` requests used per identity (D-9: at most one each). */
+    viewRequests: Map<string, number>;
+    /** Files each identity has written so far, from the team stream (best effort, 6.4). */
+    touchedFiles: Map<string, string[]>;
+    /** `gov_view` grants / denials per 0-based phase, shown to the inspector at settle. */
+    viewLog: Map<number, string[]>;
+    /** Set by whoever emitted this stage's `stage_ended` (exactly one per stage). */
+    stageEndedEmitted: boolean;
+    /** Set once the lazy retention prune ran for this engine instance. */
+    pruned: boolean;
+    /**
+     * `/gov pause` is waiting for the running stage to finish (governance-mode-v1-1 V-2).
+     * MEMORY ONLY: a request is never persisted, so a restart cannot surprise anyone with a
+     * run that "paused itself". Cleared when it is redeemed, cancelled, or the stage ends.
+     */
+    pauseRequested: boolean;
+    /**
+     * The current `paused` status came from `/gov pause`. Memory only, like the request; it
+     * lets `gov_dispatch` answer a user pause with the explicit "stop and wait" text while an
+     * Esc pause keeps its original refusal. Cleared by resume, a new run and close.
+     */
+    userPaused: boolean;
+    private chain;
+    private readonly listeners;
+    private rev;
+    private lastEmitAt;
+    private emitTimer;
+    private readonly agentStates;
+    private readonly activity;
+    private readonly lastDelta;
+    private stageAbort;
+    private teamUnsubscribe;
+    private persistError;
+    constructor(deps: EngineDeps);
+    now(): number;
+    config(): GovernanceConfig;
+    requireRun(): RunState;
+    wp(id: string): WorkPackage | undefined;
+    /** Public queue entry for modules that persist their own files in order with the rest. */
+    enqueueTask(job: () => Promise<unknown>): void;
+    private enqueue;
+    /** Append one event to the truth log. Returns the seq it was stamped with. */
+    log(type: StoredEventType, actor: string, payload: Record<string, unknown>): number;
+    /** Queue checkpoint writes for the current run and ledger. */
+    checkpoint(): void;
+    /** Queue a projection file write (`board.md`, reports, scoreboard). */
+    writeFile(rel: string, text: string): void;
+    exportScoreboard(): void;
+    /** Wait for every queued write. Returns a note when a write failed (and clears it). */
+    flush(): Promise<string | null>;
+    ledgerOp(op: LedgerOp, actor?: string): LedgerOpResult;
+    /** Append ledger lines for a digest (call after `ledgerOp`). */
+    noteBooked(booked: readonly BookedEntry[]): void;
+    resetStageScratch(): void;
+    private entriesAt;
+    private noteDelta;
+    standingRows(): StandingRow[];
+    health(): number | null;
+    /** Rebuild the ledger from an op log (used by `RunStore.load` replay). */
+    static replayLedger(events: ReadonlyArray<{
+        seq: number;
+        type: string;
+        payload: Record<string, unknown>;
+    }>, tailSeq: number): LedgerState;
+    setAgentState(id: string, state: GovAgentState): void;
+    agentState(id: string): GovAgentState | undefined;
+    /** Subscribe to the team stream for the duration of the engine (activity lines). */
+    attachTeam(): void;
+    detachTeam(): void;
+    clearActivity(): void;
+    beginStage(external?: AbortSignal): AbortController;
+    endStage(): void;
+    isStageRunning(): boolean;
+    /**
+     * A `gov_dispatch` call is in flight from `beginStage` until `endStage`: wider than
+     * `isStageRunning`, which is false while the stage is being set up and again while it
+     * writes its last checkpoint. A pause requested in either gap must wait, not fire.
+     */
+    isStageActive(): boolean;
+    abortStage(): void;
+    subscribe(listener: GovernanceEventListener): () => void;
+    emit(build: (snapshot: GovernanceSnapshot) => GovernanceEvent): void;
+    /** Coalesce chatty updates (activity lines) to one snapshot per interval (8.6). */
+    scheduleEmit(): void;
+    private cancelPendingEmit;
+    dispose(): void;
+    snapshot(): GovernanceSnapshot | null;
+    private rosterRows;
+    private wpOf;
+    private recent;
+    private alerts;
+    static schemaVersion(): number;
+}
+/** The phase to display: the first not-integrated one, else the last. */
+export declare function currentDisplayPhase(run: RunState): number;
+export declare function buildPipeline(run: RunState, phaseIndex: number): PipelineStep[];