@aragon-agent/cli 0.6.44 → 0.6.45

package/dist/governance/types.d.ts

@@ -0,0 +1,661 @@
+/**
+ * Shared shapes for the governance subsystem (governance-mode sections 5, 8, 12, 14).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure types plus a handful of tiny
+ * constants: no I/O, no React, no `node:*`.
+ *
+ * THE CONTRACT BETWEEN MODULES. `rules/` (ledger, settlement, rca, elimination),
+ * `store/` (run store), `engine/` (planner, state machine, visibility, spec builder,
+ * engine), `tools/` (what the model calls), `agent/governance-wiring.ts` and the UI all
+ * import from here and nowhere else for shapes, so a field added here is seen by every
+ * layer at compile time. `GovernanceEvent` is a CLI-LOCAL stream (D-19): it must never
+ * be folded into core's `AgentEvent` (`public-api.test.ts` freezes that union).
+ */
+import type { TokenUsage } from '@aragon-agent/core';
+import type { EventCode, Settlement } from './rules/events-table.js';
+export type { EventCode, Settlement } from './rules/events-table.js';
+/** All four powers. INSP is the fourth power and is never scored (I-G5). */
+export type GovRole = 'DEV' | 'REV' | 'TEST' | 'INSP';
+/** The three scored roles. */
+export type ScoredRole = 'DEV' | 'REV' | 'TEST';
+export type StageKind = 'dev' | 'review' | 'test' | 'settle' | 'integrate' | 'fix';
+export declare const STAGE_KINDS: readonly StageKind[];
+export type ProfileId = 'general' | 'ml' | 'product' | 'api-security';
+export declare const PROFILE_IDS: readonly ProfileId[];
+export type RunStatus = 'executing' | 'escalated' | 'paused' | 'closed' | 'abandoned';
+export type WpStatus = 'pending' | 'dev_running' | 'awaiting_review' | 'review_running' | 'awaiting_test' | 'test_running' | 'rework' | 'tested_ok' | 'integrated' | 'blocked' | 'dropped';
+/** A tool-bound identity. The factories close over this; submissions never carry their own. */
+export interface Identity {
+    /** Roster id and subagent label: `dev1`, `rev2`, `tst1`, `insp`, `dev2-r1`. */
+    id: string;
+    role: GovRole;
+    generation: number;
+}
+/** Every `gov_*` / `ledger_*` entry point returns plain text; the tool layer wraps it. */
+export type ToolText = string;
+export interface WorkPackage {
+    id: string;
+    title: string;
+    goal: string;
+    /** Owned files, INCLUDING the WP's test paths (RV-12). */
+    files: string[];
+    acceptance: string[];
+    dependsOn: string[];
+    /** 0-based phase index assigned by the planner. */
+    phase: number;
+    /** The DEV identity currently holding the WP; null until first dispatch. */
+    assignee: string | null;
+    /** REV / TEST identities assigned to the WP (sticky across rework, 5.2). */
+    reviewer: string | null;
+    tester: string | null;
+    status: WpStatus;
+    reworkCount: number;
+    /** Finding fingerprints from rejected reviews (D8 detection, 5.6). */
+    rejections: string[];
+    appealUsed: boolean;
+    /** Artifact ids per stage, oldest first. */
+    submissions: Record<StageKind, string[]>;
+    /** L3 `retry` grants consumed (<= GOV_LIMITS.maxReworkGrantsPerWp). */
+    reworkGrants: number;
+    acceptedWithIssues: boolean;
+    blockedAt?: StageKind;
+}
+export interface Contract {
+    id: string;
+    name: string;
+    producer: string;
+    consumers: string[];
+    definition: string;
+    /** Set when the producer or all consumers were dropped (resolve.disposition=drop). */
+    voided?: boolean;
+}
+export interface Claim {
+    id: string;
+    kind: 'missed_by_review' | 'security' | 'false_positive' | 'same_issue' | 'incomplete_impl';
+    raisedBy: string;
+    against: string;
+    wpId: string;
+    justification: string;
+    status: 'open' | 'upheld' | 'rejected';
+    rulingText?: string;
+    /** Phase the claim belongs to (settle rules only on its own phase's claims). */
+    phase: number;
+}
+export interface EscalationPosition {
+    by: string;
+    text: string;
+}
+export interface Escalation {
+    id: string;
+    level: 'L3';
+    kind: 'wp_rework_cap' | 'integration_exhausted' | 'dispute';
+    wpId?: string;
+    phase?: number;
+    topic: string;
+    positions: EscalationPosition[];
+    status: 'open' | 'resolved';
+    ruling?: string;
+}
+export interface PhaseState {
+    index: number;
+    wpIds: string[];
+    settled: boolean;
+    integrated: boolean;
+    integrationAttempts: number;
+    fixCycles: number;
+    /** resolve.disposition=retry on integration_exhausted (<= 1). */
+    extraFixGrants: number;
+    /** False when the user accepted a failing integration (disposition accept_failing). */
+    integrationAccepted: boolean;
+    /** True after the last integrate attempt failed and before a successful one. */
+    lastIntegrationFailed: boolean;
+}
+export interface StageState {
+    kind: StageKind;
+    phase: number;
+    wpIds: string[];
+    startedAt: number;
+    status: 'running' | 'done' | 'aborted' | 'interrupted';
+}
+export interface RunUsage {
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number | null;
+}
+/**
+ * One run reduced to eight scalars for the `/gov runs` listing (governance-mode-v1-1 7.1).
+ * Rides `index.jsonl`; built by `engine/run-digest.ts::buildRunDigest`.
+ */
+export interface RunDigest {
+    /** 1-based phase being worked on (the last one once every phase is integrated). */
+    phase: number;
+    phaseCount: number;
+    /** Scored agents that ever existed in this run, respawned ones included. */
+    agents: number;
+    /** Mean confirmed GT over the active scored agents; `null` before any agent exists. */
+    health: number | null;
+    /** Team tokens, input + output (the budget's unit). */
+    tokens: number;
+    /** `null` = pricing unknown. NEVER written as 0 on behalf of an unpriced run. */
+    costUsd: number | null;
+    /** `gov_dispatch` calls the engine accepted. */
+    dispatches: number;
+    eliminations: number;
+}
+export interface RunState {
+    schemaVersion: number;
+    runId: string;
+    cwd: string;
+    sessionId?: string;
+    goal: string;
+    profile: ProfileId;
+    status: RunStatus;
+    createdAt: number;
+    updatedAt: number;
+    phases: PhaseState[];
+    workPackages: Record<string, WorkPackage>;
+    /** Stable WP order as given at `start`. */
+    wpOrder: string[];
+    contracts: Contract[];
+    integrationCommands: string[];
+    claims: Claim[];
+    escalations: Escalation[];
+    stage: StageState | null;
+    usage: RunUsage;
+    /** Dispatches issued (cap: GOV_LIMITS.hardMaxDispatches). */
+    dispatches: number;
+    /** Monotone event sequence; mirrors the last events.jsonl line. */
+    seq: number;
+    /** Plan snapshot adopted from PLAN+GOVERN, if any. */
+    planSnapshot?: string;
+    /** Limits resolved at start (policy keys frozen into the run for reproducibility). */
+    limits: {
+        maxRework: number;
+        maxFixCycles: number;
+        budgetTokens: number;
+    };
+}
+export interface LedgerEntry {
+    seq: number;
+    at: number;
+    code: EventCode | 'RESPAWN' | 'ESCROW_RELEASE' | 'CLAWBACK';
+    delta: number;
+    settlement: Settlement | 'escrow_release' | 'clawback';
+    phase: number;
+    wpId?: string;
+    incidentId?: string;
+    by: 'engine' | `inspector:${string}`;
+    reason: string;
+    evidence?: string;
+    /** Set when the single-incident cap clipped the delta. */
+    capped?: {
+        requested: number;
+        applied: number;
+    };
+    confirmedAfter: number;
+    provisionalAfter: number;
+}
+export interface EscrowEntry {
+    seq: number;
+    at: number;
+    phase: number;
+    /** `held` when booked, `released` on confirm, `clawed_back` on clawback. */
+    action: 'held' | 'released' | 'clawed_back';
+    amount: number;
+    code?: EventCode;
+    reason: string;
+}
+export interface AgentRecord {
+    id: string;
+    role: ScoredRole;
+    generation: number;
+    /** KILL uses ONLY this; clamped to >= 0 (I-G3). */
+    confirmed: number;
+    /** Escrow; counted in the total, never in survival. */
+    provisional: number;
+    status: 'active' | 'eliminated';
+    replacedBy: string | null;
+    eliminatedReason?: 'depleted' | 'tail' | 'clawback';
+    /** Consecutive phase ends spent as the lowest-ranked member under the tail threshold. */
+    tailStrikes: number;
+    history: LedgerEntry[];
+    escrowHistory: EscrowEntry[];
+}
+export interface LedgerState {
+    schemaVersion: number;
+    /** Highest event seq folded into this state. */
+    seq: number;
+    agents: Record<string, AgentRecord>;
+    /** Cumulative negative applied per `${agentId}|${incidentId}` (I-G4). */
+    incidentNegatives: Record<string, number>;
+    /** Failure analyses keyed by eliminated agent id, handed to the successor. */
+    failureAnalyses: Record<string, FailureAnalysis>;
+}
+export interface FailureAnalysis {
+    agentId: string;
+    reason: 'depleted' | 'tail' | 'clawback';
+    topPenalties: Array<{
+        code: EventCode;
+        delta: number;
+        reason: string;
+    }>;
+    /** From a fixed code -> advice table; English, ASCII. */
+    avoid: string[];
+}
+export type StandingLabel = 'NORMAL' | 'WARNING' | 'DANGER' | 'KILLED';
+export interface StandingRow {
+    id: string;
+    role: ScoredRole;
+    generation: number;
+    confirmed: number;
+    provisional: number;
+    total: number;
+    label: StandingLabel;
+    status: 'active' | 'eliminated';
+    replacedBy: string | null;
+}
+export interface InterfaceContractCheck {
+    interface: string;
+    role: 'PRODUCER' | 'CONSUMER';
+    verified: 'YES' | 'NOT_APPLICABLE';
+    method: string;
+    peer: string;
+}
+export interface WorkSubmission {
+    kind: 'work';
+    id: string;
+    identity: string;
+    wpId: string;
+    phase: number;
+    stage: 'dev' | 'fix';
+    /** 1-based count of work submissions for this WP. */
+    attempt: number;
+    at: number;
+    summary: string;
+    filesChanged: string[];
+    interfaceContracts: InterfaceContractCheck[];
+    verification: {
+        commands: Array<{
+            cmd: string;
+            result: string;
+            note?: string;
+        }>;
+    };
+    appeal?: {
+        findingIds: string[];
+        argument: string;
+    };
+    escalate?: boolean;
+}
+export type ReviewVerdict = 'PASS' | 'PASS_WITH_FIXES' | 'NEEDS_REWORK';
+export type FindingSeverity = 'blocker' | 'major' | 'minor' | 'nit';
+export interface ReviewFinding {
+    id: string;
+    severity: FindingSeverity;
+    file: string;
+    line?: number;
+    issue: string;
+    requiredChange: string;
+    mustFix?: boolean;
+}
+export interface ReviewChecklistItem {
+    status: 'pass' | 'fail' | 'na';
+    evidence: string;
+}
+export interface ReviewSubmission {
+    kind: 'review';
+    id: string;
+    identity: string;
+    wpId: string;
+    phase: number;
+    attempt: number;
+    at: number;
+    verdict: ReviewVerdict;
+    checklist: {
+        correctness: ReviewChecklistItem;
+        quality: ReviewChecklistItem;
+        security: ReviewChecklistItem;
+        integration: ReviewChecklistItem;
+        compliance: ReviewChecklistItem;
+    };
+    findings: ReviewFinding[];
+    fixesApplied: Array<{
+        file: string;
+        rationale: string;
+    }>;
+    integrationAssessment: string;
+    appealResponses: Array<{
+        findingId: string;
+        decision: 'uphold' | 'withdraw';
+        note?: string;
+    }>;
+    excellence?: {
+        claim: string;
+        evidence: string;
+    };
+    securityFinding?: {
+        description: string;
+        evidence: string;
+    };
+    /** Derived by the engine from `findings`; the ONLY feedback surface a DEV sees (D-7). */
+    requiredChanges: Array<{
+        file: string;
+        issue: string;
+        change: string;
+    }>;
+}
+export type TestVerdict = 'ALL_PASS' | 'ISSUES_FOUND' | 'SPEC_MISMATCH' | 'INCOMPLETE_IMPL';
+export type TraceStatus = 'covered' | 'gap' | 'unverified';
+export interface TestSubmission {
+    kind: 'test';
+    id: string;
+    identity: string;
+    wpId: string;
+    phase: number;
+    attempt: number;
+    at: number;
+    verdict: TestVerdict;
+    traceability: Array<{
+        requirement: string;
+        evidence: string;
+        status: TraceStatus;
+    }>;
+    commands: Array<{
+        cmd: string;
+        exit: number;
+        summary: string;
+    }>;
+    issues: Array<{
+        severity: FindingSeverity;
+        description: string;
+        missedByReview?: boolean;
+        reviewMissJustification?: string;
+    }>;
+    boundaryTestsWritten: boolean;
+    skeletonRatio?: number;
+    skeletonEvidence?: string;
+    claims: Array<{
+        kind: Claim['kind'];
+        justification: string;
+        against?: string;
+    }>;
+}
+export type Submission = WorkSubmission | ReviewSubmission | TestSubmission;
+/** Inspector settle/integrate summary, persisted as an artifact for the report. */
+export interface InspectorReport {
+    kind: 'inspector';
+    id: string;
+    phase: number;
+    stage: 'settle' | 'integrate';
+    at: number;
+    summary: string;
+    contractChecks: Array<{
+        contractId: string;
+        status: 'ok' | 'mismatch' | 'unverifiable';
+        note: string;
+    }>;
+    integration?: {
+        result: 'pass' | 'fail' | 'not_run';
+        commands: Array<{
+            cmd: string;
+            exit: number;
+            summary: string;
+        }>;
+    };
+    rca?: RcaInput;
+    escalations: Array<{
+        kind: Escalation['kind'];
+        wpId?: string;
+        topic: string;
+        positions: EscalationPosition[];
+    }>;
+}
+export interface RcaInput {
+    failingChecks: Array<{
+        name: string;
+        files: string[];
+    }>;
+    /** Cross-module? false => an individual bug, not an integration failure. */
+    boundary: boolean;
+    attributions: Array<{
+        agentId: string;
+        level: 'primary' | 'contributing' | 'oversight';
+        contract: 'producer' | 'consumer_unverified' | 'none';
+        miss?: 'review_integration' | 'test_defect' | 'test_boundary';
+        note: string;
+    }>;
+    /** Cannot isolate to one agent => C4. */
+    systemic: boolean;
+}
+export type StoredEventType = 'run_started' | 'stage_started' | 'submission' | 'ledger' | 'claim' | 'ruling' | 'escrow' | 'eliminated' | 'respawned' | 'view_granted' | 'view_denied' | 'ownership_violation' | 'escalation' | 'resolution' | 'budget' | 'stage_ended' | 'run_paused' | 'run_resumed' | 'run_closed' | 'compacted';
+export interface StoredEvent {
+    seq: number;
+    at: number;
+    type: StoredEventType;
+    actor: string;
+    payload: Record<string, unknown>;
+}
+export type GovAgentState = 'queued' | 'working' | 'submitted' | 'idle' | 'failed' | 'eliminated';
+export interface RosterRow {
+    id: string;
+    role: GovRole;
+    generation: number;
+    state: GovAgentState;
+    wpId: string | null;
+    /** Live activity text from the team stream (already sanitized); '' when none. */
+    activity: string;
+    /** null for the inspector (not scored). */
+    confirmed: number | null;
+    provisional: number;
+    label: StandingLabel | 'NOT_SCORED';
+    /** Last delta and when it landed, for the 4 s emphasis window (10.3). */
+    lastDelta: {
+        delta: number;
+        code: string;
+        at: number;
+        provisional: boolean;
+    } | null;
+    replacedBy: string | null;
+}
+export type PipelineStepKey = 'intake' | StageKind;
+export interface PipelineStep {
+    key: PipelineStepKey;
+    state: 'done' | 'active' | 'pending';
+}
+export interface LedgerTickerRow {
+    at: number;
+    agentId: string;
+    code: string;
+    delta: number;
+    provisional: boolean;
+    reason: string;
+}
+export interface GovernanceSnapshot {
+    runId: string;
+    goal: string;
+    status: RunStatus;
+    /** 1-based phase number for display. */
+    phase: number;
+    phaseCount: number;
+    stage: StageKind | null;
+    stageRunning: boolean;
+    startedAt: number;
+    pipeline: PipelineStep[];
+    roster: RosterRow[];
+    /** Mean `confirmed` over active scored agents; null before any agent exists. */
+    health: number | null;
+    recent: LedgerTickerRow[];
+    usage: RunUsage;
+    budgetTokens: number;
+    alerts: string[];
+    reworkNote: string | null;
+    /**
+     * A cooperative `/gov pause` is waiting for the running stage to finish
+     * (governance-mode-v1-1 6.4). Optional so older fixtures read it as `false`.
+     */
+    pauseRequested?: boolean;
+    /** Monotone; lets reducers drop stale snapshots. */
+    rev: number;
+}
+export type GovernanceEvent = {
+    type: 'run_started';
+    snapshot: GovernanceSnapshot;
+    card: GovernanceCardData | null;
+} | {
+    type: 'stage_started';
+    snapshot: GovernanceSnapshot;
+} | {
+    type: 'agent_state';
+    snapshot: GovernanceSnapshot;
+} | {
+    type: 'submission';
+    snapshot: GovernanceSnapshot;
+    identity: string;
+    wpId: string;
+    kind: Submission['kind'];
+} | {
+    type: 'ledger';
+    snapshot: GovernanceSnapshot;
+} | {
+    type: 'stage_ended';
+    snapshot: GovernanceSnapshot;
+    card: GovernanceCardData | null;
+} | {
+    type: 'escrow';
+    snapshot: GovernanceSnapshot;
+    phase: number;
+    released: boolean;
+} | {
+    type: 'eliminated';
+    snapshot: GovernanceSnapshot;
+    agentId: string;
+    reason: FailureAnalysis['reason'];
+} | {
+    type: 'respawned';
+    snapshot: GovernanceSnapshot;
+    agentId: string;
+    predecessor: string;
+} | {
+    type: 'escalation';
+    snapshot: GovernanceSnapshot;
+    escalation: Escalation;
+    card: GovernanceCardData;
+} | {
+    type: 'budget';
+    snapshot: GovernanceSnapshot;
+    fraction: number;
+} | {
+    type: 'run_paused';
+    snapshot: GovernanceSnapshot;
+    reason: string;
+} | {
+    type: 'run_resumed';
+    snapshot: GovernanceSnapshot;
+} | {
+    type: 'run_closed';
+    snapshot: GovernanceSnapshot;
+    card: GovernanceCardData;
+};
+export type GovernanceEventListener = (event: GovernanceEvent) => void;
+/**
+ * Transcript card payload (`Entry.kind === 'governance'`). PURE DATA: no functions, no
+ * Dates, no class instances - it is persisted with `entries` (10.4).
+ */
+export interface GovernanceCardRow {
+    id: string;
+    role: GovRole;
+    confirmed: number | null;
+    /** Compact per-row delta text, e.g. `+15P->C D1  +10 D12`. ASCII. */
+    deltaText: string;
+}
+export interface GovernanceCardData {
+    /** charter = run start; phase = settle+integrate; escalation; final = close. */
+    variant: 'charter' | 'phase' | 'escalation' | 'final';
+    runId: string;
+    title: string;
+    /** One line status under the title, e.g. `integration passed (attempt 1)`. */
+    headline: string;
+    tone: 'ok' | 'warn' | 'error' | 'info';
+    rows: GovernanceCardRow[];
+    notes: string[];
+}
+export interface GovernanceSpecExt {
+    role: GovRole;
+    identity: string;
+    runId: string;
+    /** 1-based phase number. */
+    phase: number;
+    stage: StageKind;
+    /** WP ids this child is responsible for (one for DEV/FIX, several for REV/TEST). */
+    wpIds: string[];
+    tokens: number;
+    generation: number;
+    predecessorAnalysis?: FailureAnalysis;
+    profile: ProfileId;
+    /**
+     * The integration commands registered for the run. Carried on the INSPECTOR's spec only:
+     * the host reads it to build that child's restricted `bash` (7.4).
+     */
+    integrationCommands?: string[];
+}
+export interface WorkPackageInput {
+    id: string;
+    title: string;
+    goal: string;
+    files: string[];
+    acceptance: string[];
+    dependsOn?: string[];
+}
+export interface ContractInput {
+    id: string;
+    name: string;
+    producer: string;
+    consumers: string[];
+    definition: string;
+}
+export interface StartInput {
+    goal: string;
+    spec: string;
+    profile?: ProfileId;
+    workPackages: WorkPackageInput[];
+    contracts?: ContractInput[];
+    integrationCommands?: string[];
+}
+export interface DispatchInput {
+    stage: StageKind;
+    wps?: string[];
+    notes?: Record<string, string>;
+}
+export type ResolveDisposition = 'retry' | 'accept_as_is' | 'drop' | 'accept_failing';
+export interface ResolveInput {
+    escalationId: string;
+    ruling: string;
+    favor?: string;
+    disposition?: ResolveDisposition;
+}
+export interface GovernanceEngineApi {
+    start(input: unknown, signal?: AbortSignal): Promise<ToolText>;
+    status(): ToolText;
+    resume(runId?: string): Promise<ToolText>;
+    dispatchStage(input: unknown, signal?: AbortSignal): Promise<ToolText>;
+    close(summary?: string): Promise<ToolText>;
+    abandon(reason: string): Promise<ToolText>;
+    resolve(input: unknown): Promise<ToolText>;
+    snapshot(): GovernanceSnapshot | null;
+    isStageRunning(): boolean;
+    abortStage(): void;
+    subscribe(listener: GovernanceEventListener): () => void;
+    dispose(): void;
+    submitWork(identity: Identity, input: unknown): ToolText;
+    submitReview(identity: Identity, input: unknown): ToolText;
+    submitTest(identity: Identity, input: unknown): ToolText;
+    inspectorApply(input: unknown): ToolText;
+    inspectorRule(input: unknown): ToolText;
+    inspectorSettle(input: unknown): ToolText;
+    standings(): ToolText;
+    readArtifact(identity: Identity, input: unknown): ToolText;
+    requestView(identity: Identity, input: unknown): ToolText;
+    scan(identity: Identity, input: unknown): ToolText | Promise<ToolText>;
+}
+/** Aggregated usage helper type, re-exported for the engine's budget module. */
+export type { TokenUsage };

package/dist/governance/types.js

@@ -0,0 +1,27 @@
+/**
+ * Shared shapes for the governance subsystem (governance-mode sections 5, 8, 12, 14).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned). Pure types plus a handful of tiny
+ * constants: no I/O, no React, no `node:*`.
+ *
+ * THE CONTRACT BETWEEN MODULES. `rules/` (ledger, settlement, rca, elimination),
+ * `store/` (run store), `engine/` (planner, state machine, visibility, spec builder,
+ * engine), `tools/` (what the model calls), `agent/governance-wiring.ts` and the UI all
+ * import from here and nowhere else for shapes, so a field added here is seen by every
+ * layer at compile time. `GovernanceEvent` is a CLI-LOCAL stream (D-19): it must never
+ * be folded into core's `AgentEvent` (`public-api.test.ts` freezes that union).
+ */
+export const STAGE_KINDS = [
+    'dev',
+    'review',
+    'test',
+    'settle',
+    'integrate',
+    'fix',
+];
+export const PROFILE_IDS = [
+    'general',
+    'ml',
+    'product',
+    'api-security',
+];