@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/agent/governance-view.d.ts

@@ -0,0 +1,40 @@
+/**
+ * The governance slice of the view model: the small pure folds `reducer.ts` delegates to
+ * (governance-mode section 14.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`agent/` is glyph-scanned).
+ *
+ * WHY A FILE OF ITS OWN. `reducer.ts` is already past the file-size ceiling and the repo
+ * rule is "wiring-style growth only": each governance `case` in the reducer is a line or
+ * two that calls a function here, so the logic is unit-testable without a `ViewState`.
+ */
+import type { AgentMode } from './agent-mode.js';
+import type { GovernanceSnapshot } from '../governance/types.js';
+import { type Posture } from '../governance/posture.js';
+/** The posture half of a `setAgentMode` action. */
+export interface AdoptedPostureInput {
+    mode: AgentMode;
+    pending: AgentMode | null;
+    /** Written from the controller's adopted state; absent for callers that predate postures. */
+    posture?: Posture;
+    pendingPosture?: Posture | null;
+}
+/**
+ * The pair of posture fields one `setAgentMode` dispatch writes.
+ *
+ * "NEVER DISPATCH THE REQUESTED VALUE, ONLY THE ADOPTED ONE" (spec 4.3): the controller
+ * reports all four values together and the reducer mirrors them, so the badge and the gate
+ * cannot disagree. A dispatch that carries only the gate mode (every pre-governance call
+ * site) keeps the governance dimension the view already has and swaps the mode half, which
+ * is exactly what such a caller meant.
+ */
+export declare function adoptPosture(current: Posture, action: AdoptedPostureInput): {
+    posture: Posture;
+    pendingPosture: Posture | null;
+};
+/**
+ * Fold a pushed snapshot into the view: a snapshot OLDER than the one held, for the same
+ * run, is dropped (the wiring throttles, and a late flush must not roll the panel back).
+ * Returns the held object unchanged when nothing should change.
+ */
+export declare function foldGovernanceSnapshot(held: GovernanceSnapshot | null, incoming: GovernanceSnapshot): GovernanceSnapshot;

package/dist/agent/governance-view.js

@@ -0,0 +1,40 @@
+/**
+ * The governance slice of the view model: the small pure folds `reducer.ts` delegates to
+ * (governance-mode section 14.4).
+ *
+ * Pure: no React, no I/O. ASCII ONLY (`agent/` is glyph-scanned).
+ *
+ * WHY A FILE OF ITS OWN. `reducer.ts` is already past the file-size ceiling and the repo
+ * rule is "wiring-style growth only": each governance `case` in the reducer is a line or
+ * two that calls a function here, so the logic is unit-testable without a `ViewState`.
+ */
+import { composePosture, isGovernancePosture } from '../governance/posture.js';
+/**
+ * The pair of posture fields one `setAgentMode` dispatch writes.
+ *
+ * "NEVER DISPATCH THE REQUESTED VALUE, ONLY THE ADOPTED ONE" (spec 4.3): the controller
+ * reports all four values together and the reducer mirrors them, so the badge and the gate
+ * cannot disagree. A dispatch that carries only the gate mode (every pre-governance call
+ * site) keeps the governance dimension the view already has and swaps the mode half, which
+ * is exactly what such a caller meant.
+ */
+export function adoptPosture(current, action) {
+    const governed = isGovernancePosture(current);
+    const posture = action.posture ?? composePosture(action.mode, governed);
+    const pendingPosture = action.pendingPosture !== undefined
+        ? action.pendingPosture
+        : action.pending === null
+            ? null
+            : composePosture(action.pending, governed);
+    return { posture, pendingPosture };
+}
+/**
+ * Fold a pushed snapshot into the view: a snapshot OLDER than the one held, for the same
+ * run, is dropped (the wiring throttles, and a late flush must not roll the panel back).
+ * Returns the held object unchanged when nothing should change.
+ */
+export function foldGovernanceSnapshot(held, incoming) {
+    if (held !== null && held.runId === incoming.runId && incoming.rev < held.rev)
+        return held;
+    return incoming;
+}

package/dist/agent/governance-wiring.d.ts

@@ -0,0 +1,162 @@
+/**
+ * GovernanceWiring - the host side of governance mode (governance-mode 3.2, 14.2).
+ *
+ * ASCII ONLY (`agent/` is inside the glyph scanner's scope).
+ *
+ * `AgentController` is 3000+ lines over the repo's file limit, so every governance decision
+ * it needs lives here and the controller only forwards: registration, availability, the
+ * Orchestrator and role prompt blocks, the PLAN+GOVERN interview gate, the approved-plan
+ * stash, the engine's lifecycle, the child tool hooks. The posture TRANSITION rule is a
+ * pure function in `governance/posture-transition.ts` for the same reason.
+ *
+ * TWO LAYERS OF "CAN I USE THIS" (D-22 / RV-1 / RV-14), and they are not the same thing:
+ *
+ *  - REGISTERED is decided ONCE, in the constructor, from inputs that cannot change
+ *    afterwards: team tools exist, `governance.enabled`, the env kill switch, and the
+ *    channel's STATIC `neverPrompts` (NOT the live `canPrompt()`: at construction the App
+ *    has not attached its human channel yet, so `canPrompt()` is false for every TUI
+ *    session and keying off it would register nothing, silently, forever). The tool array
+ *    is immutable after `new Agent(...)`, so this is irreversible for the session.
+ *  - AVAILABLE is live: registered AND `team.enabled` AND an API key. It is what `/gov`,
+ *    `doctor` and the key cycle ask.
+ */
+import type { AgentTool, ModelCost } from '@aragon-agent/core';
+import type { CliConfig } from '../config/schema.js';
+import { type GovernanceAvailability } from '../governance/copy.js';
+import type { TeamRuntimeLike } from '../governance/engine/engine-core.js';
+import type { PauseOutcome } from '../governance/engine/pause.js';
+import { type Posture } from '../governance/posture.js';
+import { type RunReportResult } from '../governance/report-reader.js';
+import { type IndexEntry } from '../governance/store/run-store.js';
+import type { GovernanceEventListener, GovernanceSnapshot, LedgerState, RunState } from '../governance/types.js';
+import type { SubagentSpec } from '../team/types.js';
+import type { HumanInputGate, NormalizedPlan, NormalizedQuestion } from '../tools/human-input.js';
+import type { AgentMode } from './agent-mode.js';
+export interface WiringDeps {
+    /** `config.team.enabled` at construction: whether `task` (and a TeamRuntime) exist. */
+    teamRegistered: boolean;
+    config: () => CliConfig;
+    gate: HumanInputGate;
+    getCwd: () => string;
+    /** The gate mode (`build` | `plan`); the controller owns it. */
+    getGateMode: () => AgentMode;
+    getSessionId?: () => string | undefined;
+    withPausedWatchdog: <T>(fn: () => Promise<T>) => Promise<T>;
+    withHumanWait: <T>(fn: () => Promise<T>) => Promise<T>;
+    hasApiKey: () => boolean;
+    modelCost: () => ModelCost | undefined;
+    getRuntime: () => TeamRuntimeLike | null;
+    env?: Readonly<Record<string, string | undefined>>;
+    now?: () => number;
+}
+/** Render the approved plan as the run specification (<= `specChars`). */
+export declare function renderPlanAsSpec(plan: NormalizedPlan): string;
+/** What `/gov runs` shows per run: the index row without the cwd / session plumbing. */
+export type GovernanceRunRow = Pick<IndexEntry, 'runId' | 'goal' | 'status' | 'updatedAt' | 'digest'>;
+export declare class GovernanceWiring {
+    private readonly deps;
+    private readonly registered;
+    private readonly enabledAtStart;
+    private readonly env;
+    private governOn;
+    private pendingPosture;
+    private engine;
+    private store;
+    private readonly listeners;
+    private engineUnsubscribe;
+    private approvedPlan;
+    private answeredRounds;
+    private readonly coveredTopics;
+    /** A lazy facade: tools are built before the engine exists and the engine needs the runtime. */
+    private readonly api;
+    constructor(deps: WiringDeps);
+    /** Whether governance tools were registered at construction. Never changes. */
+    isRegistered(): boolean;
+    /** The live answer, with the precise reason when it is no. */
+    isAvailable(): GovernanceAvailability;
+    private unregisteredReason;
+    /** The exact sentence for the current unavailability, or null when available. */
+    unavailableText(): string | null;
+    /** Shift+Tab cycle: four states when usable and `governance.shiftTab`, else the classic two. */
+    postureCycle(): readonly Posture[];
+    isGovernOn(): boolean;
+    setGovernOn(on: boolean): void;
+    getPendingPosture(): Posture | null;
+    setPendingPosture(pending: Posture | null): void;
+    /** Entering PLAN+GOVERN starts a fresh interview and drops any older plan (9.3). */
+    onPostureAdopted(posture: Posture, previous: Posture): void;
+    isStageRunning(): boolean;
+    /**
+     * `''` unless governance is on, registered and available (closed state: byte-equal).
+     *
+     * `config` is the config the prompt is being composed FOR. A settings save composes the
+     * prompt from the candidate BEFORE it becomes live, so reading the live config here would
+     * quote the limits from before the save (governance-mode-v1-1 IF-3).
+     */
+    orchestratorBlock(posture: Posture, config?: CliConfig): string;
+    /** `''` unless PLAN+GOVERN. */
+    planAddendum(posture: Posture, config?: CliConfig): string;
+    roleBlockFor(spec: SubagentSpec): string;
+    /** Called from the controller's `noteAnswered`: one real, answered, non-duplicate round. */
+    noteAnsweredRound(questions?: readonly NormalizedQuestion[]): void;
+    answeredRoundCount(): number;
+    /** `submit_plan` pre-check: a refusal text, or null to proceed. */
+    beforeSubmitPlan(): string | null;
+    /** Stash the approved plan when governance is on. Returns which way the session goes. */
+    handlePlanApproved(plan: NormalizedPlan): 'govern' | 'build';
+    /** `gov_run start` consumes the stash exactly once. */
+    takeApprovedPlan(): string | null;
+    /** `[]` when not registered, which is the byte-identical closed path. */
+    leadTools(): AgentTool[];
+    leadPolicyExempt(): ReadonlySet<string>;
+    childPolicyExempt(): ReadonlySet<string>;
+    /** Role tools for a governed child; `[]` for anything else. */
+    childToolsFor(spec: SubagentSpec): AgentTool[];
+    /**
+     * Narrow a governed child's finished tool array: the inspector loses its write tools and
+     * gets the restricted shell, and every read-class tool gets the store tripwire.
+     *
+     * This runs on the factory's RESULT (see `SubagentDeps.narrowToolsFor`) because it has to
+     * see the built-in `bash` to replace it, while the role tools had to go IN through the
+     * factory. A non-governed spec comes back untouched.
+     */
+    narrowToolsFor(spec: SubagentSpec, tools: AgentTool[]): AgentTool[];
+    /** The engine is created on first use: a session that never governs never opens a store. */
+    private ensureEngine;
+    /** `confirmCharter` through the EXISTING plan-review overlay; no new overlay kind (RV-10). */
+    private confirmCharter;
+    /** Subscribe to the governance event stream (works before the engine exists). */
+    subscribe(listener: GovernanceEventListener): () => void;
+    snapshot(): GovernanceSnapshot | null;
+    /** Run + ledger for the `/gov board` overlay (read-only views of live memory). */
+    boardInput(): {
+        run: RunState;
+        ledger: LedgerState;
+        boardPath: string;
+    } | null;
+    abortStage(): void;
+    /**
+     * Recent runs for `/gov runs`, newest first. Opens the store lazily; `[]` when governance
+     * is unusable. `RunStore.listRuns()` is ALREADY newest-first: the previous
+     * `slice(-10).reverse()` therefore returned the OLDEST ten once there were more than ten.
+     */
+    listRuns(): Promise<GovernanceRunRow[]>;
+    /** `/gov report [runId]`: a stored report, read-only (governance-mode-v1-1 7.2). */
+    readReport(runId?: string): Promise<RunReportResult | {
+        kind: 'no_run';
+    }>;
+    /** `/gov pause`: the engine's verdict, or `no_run` when no engine was ever created. */
+    requestPause(): Promise<PauseOutcome>;
+    cancelPause(): boolean;
+    /** The dispatch-plan line for the live run (`/gov status`), or null without one. */
+    dispatchPlanText(): string | null;
+    /**
+     * The run `/gov resume [runId]` should hand to the orchestrator: the named one when it
+     * exists, else the newest resumable run for this directory. `null` when there is none.
+     */
+    findResumableRun(runId?: string): Promise<string | null>;
+    dispose(): void;
+    private buildLazyApi;
+    /** Posture helper for callers that only hold the gate mode. */
+    currentPosture(mode: AgentMode): Posture;
+}