@aragon-agent/cli 0.6.44 → 0.6.46

package/dist/agent/governance-wiring.js

@@ -0,0 +1,470 @@
+/**
+ * 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 { join } from 'node:path';
+import { clampGovernanceConfig, isGovernanceEnvDisabled, } from '../config/governance-config.js';
+import { getGovernanceDir } from '../config/app-paths.js';
+import { RESTART_REQUIRED_TEXT, unavailableReasonText, } from '../governance/copy.js';
+import { createGovernanceEngine } from '../governance/engine/engine.js';
+import { estimateForRun } from '../governance/engine/estimate.js';
+import { formatDispatchEstimate } from '../governance/copy.js';
+import { GOV_CHILD_TOOL_NAMES, GOV_LEAD_TOOL_NAMES, GOV_LIMITS } from '../governance/limits.js';
+import { composePosture, isGovernancePosture, POSTURES_CLASSIC, POSTURES_FULL, } from '../governance/posture.js';
+import { buildPlanGovernAddendum } from '../governance/prompts/plan-addendum.js';
+import { buildOrchestratorBlock } from '../governance/prompts/orchestrator-block.js';
+import { PLAN_INTERVIEW_TOPICS, govAskRoundsRefusal } from '../governance/prompts/refusals.js';
+import { buildRoleBlock } from '../governance/prompts/role-blocks.js';
+import { readRunReport } from '../governance/report-reader.js';
+import { ArtifactStore } from '../governance/store/artifacts.js';
+import { RunStore } from '../governance/store/run-store.js';
+import { buildChildTools } from '../governance/tools/child-tools.js';
+import { applyInspectorToolPolicy, withGovernanceReadGuard } from '../governance/tools/guard.js';
+import { makeGovDispatchTool, makeGovRunTool } from '../governance/tools/lead-tools.js';
+import { TEAM_LIMITS } from '../team/limits.js';
+/** Keyword probes that map an answered question onto the fixed interview topics. */
+const TOPIC_PROBES = [
+    /goal|success|outcome|objective|criteria/i,
+    /scope|in scope|out of scope|include|exclude/i,
+    /constraint|stack|compat|performance|style|forbid/i,
+    /quality|test|security|review|strict/i,
+    /team|parallel|budget|cost|work package|\bwp/i,
+    /risk|depend|decision/i,
+];
+function governanceOf(config) {
+    return clampGovernanceConfig(config.governance);
+}
+/** Render the approved plan as the run specification (<= `specChars`). */
+export function renderPlanAsSpec(plan) {
+    const lines = [`# ${plan.title}`, '', plan.summary, ''];
+    plan.steps.forEach((step, i) => {
+        lines.push(`${i + 1}. ${step.title}`);
+        if (step.detail)
+            lines.push(`   ${step.detail.replace(/\n/g, '\n   ')}`);
+    });
+    if (plan.filesTouched.length > 0)
+        lines.push('', `Files: ${plan.filesTouched.join(', ')}`);
+    if (plan.risks.length > 0)
+        lines.push('', 'Risks:', ...plan.risks.map((r) => `- ${r}`));
+    if (plan.openQuestions.length > 0) {
+        lines.push('', 'Open questions:', ...plan.openQuestions.map((q) => `- ${q}`));
+    }
+    const text = lines.join('\n');
+    return text.length > GOV_LIMITS.specChars ? text.slice(0, GOV_LIMITS.specChars) : text;
+}
+const RUNS_LISTED = 10;
+export class GovernanceWiring {
+    deps;
+    registered;
+    enabledAtStart;
+    env;
+    governOn = false;
+    pendingPosture = null;
+    engine = null;
+    store = null;
+    listeners = new Set();
+    engineUnsubscribe = null;
+    approvedPlan = null;
+    answeredRounds = 0;
+    coveredTopics = new Set();
+    /** A lazy facade: tools are built before the engine exists and the engine needs the runtime. */
+    api;
+    constructor(deps) {
+        this.deps = deps;
+        this.env = deps.env ?? process.env;
+        const gov = governanceOf(deps.config());
+        this.enabledAtStart = gov.enabled;
+        // STATIC, evaluated once (D-22). `neverPrompts` is read off the gate object, which is
+        // exactly what `createPlanTools` registers on.
+        this.registered =
+            deps.teamRegistered &&
+                gov.enabled &&
+                !isGovernanceEnvDisabled(this.env) &&
+                deps.gate.neverPrompts !== true;
+        this.api = this.buildLazyApi();
+    }
+    // -------------------------------------------------------------------------
+    // Registration and availability
+    // -------------------------------------------------------------------------
+    /** Whether governance tools were registered at construction. Never changes. */
+    isRegistered() {
+        return this.registered;
+    }
+    /** The live answer, with the precise reason when it is no. */
+    isAvailable() {
+        const config = this.deps.config();
+        const gov = governanceOf(config);
+        if (!this.registered)
+            return { ok: false, reason: this.unregisteredReason(gov) };
+        if (isGovernanceEnvDisabled(this.env))
+            return { ok: false, reason: 'disabled_env' };
+        if (!gov.enabled)
+            return { ok: false, reason: 'disabled_config' };
+        if (!config.team.enabled)
+            return { ok: false, reason: 'team_off' };
+        if (!this.deps.hasApiKey())
+            return { ok: false, reason: 'no_api_key' };
+        return { ok: true };
+    }
+    unregisteredReason(gov) {
+        if (isGovernanceEnvDisabled(this.env))
+            return 'disabled_env';
+        if (this.deps.gate.neverPrompts === true)
+            return 'headless';
+        if (!this.deps.teamRegistered)
+            return 'no_team';
+        // Disabled at start. Now on => the tool array cannot grow: restart. Still off => config.
+        return !this.enabledAtStart && gov.enabled ? 'restart_required' : 'disabled_config';
+    }
+    /** The exact sentence for the current unavailability, or null when available. */
+    unavailableText() {
+        const a = this.isAvailable();
+        if (a.ok)
+            return null;
+        return a.reason === 'restart_required' ? RESTART_REQUIRED_TEXT : unavailableReasonText(a.reason);
+    }
+    /** Shift+Tab cycle: four states when usable and `governance.shiftTab`, else the classic two. */
+    postureCycle() {
+        const gov = governanceOf(this.deps.config());
+        return this.isAvailable().ok && gov.shiftTab ? POSTURES_FULL : POSTURES_CLASSIC;
+    }
+    // -------------------------------------------------------------------------
+    // Posture state (the gate mode lives in the controller)
+    // -------------------------------------------------------------------------
+    isGovernOn() {
+        return this.governOn;
+    }
+    setGovernOn(on) {
+        this.governOn = on;
+    }
+    getPendingPosture() {
+        return this.pendingPosture;
+    }
+    setPendingPosture(pending) {
+        this.pendingPosture = pending;
+    }
+    /** Entering PLAN+GOVERN starts a fresh interview and drops any older plan (9.3). */
+    onPostureAdopted(posture, previous) {
+        if (posture === 'plan_govern' && previous !== 'plan_govern') {
+            this.answeredRounds = 0;
+            this.coveredTopics.clear();
+            this.approvedPlan = null;
+        }
+    }
+    isStageRunning() {
+        return this.engine?.isStageRunning() ?? false;
+    }
+    // -------------------------------------------------------------------------
+    // Prompt blocks
+    // -------------------------------------------------------------------------
+    /**
+     * `''` 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, config) {
+        if (!this.registered || !isGovernancePosture(posture) || !this.isAvailable().ok)
+            return '';
+        const gov = governanceOf(config ?? this.deps.config());
+        return buildOrchestratorBlock({
+            posture,
+            limits: {
+                maxWorkPackages: gov.maxWorkPackages,
+                maxPhases: gov.maxPhases,
+                maxRework: gov.maxRework,
+                maxFixCycles: gov.maxFixCycles,
+                budgetTokens: gov.budgetTokens,
+            },
+        });
+    }
+    /** `''` unless PLAN+GOVERN. */
+    planAddendum(posture, config) {
+        if (!this.registered || posture !== 'plan_govern' || !this.isAvailable().ok)
+            return '';
+        return buildPlanGovernAddendum(governanceOf(config ?? this.deps.config()).minAskRounds);
+    }
+    roleBlockFor(spec) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return '';
+        return buildRoleBlock(ext, { integrationCommands: ext.integrationCommands ?? [] });
+    }
+    // -------------------------------------------------------------------------
+    // PLAN+GOVERN interview and approval
+    // -------------------------------------------------------------------------
+    /** Called from the controller's `noteAnswered`: one real, answered, non-duplicate round. */
+    noteAnsweredRound(questions = []) {
+        if (!this.governOn || this.deps.getGateMode() !== 'plan')
+            return;
+        this.answeredRounds += 1;
+        const text = questions.map((q) => `${q.header} ${q.question}`).join(' ');
+        TOPIC_PROBES.forEach((probe, index) => {
+            if (probe.test(text))
+                this.coveredTopics.add(index);
+        });
+    }
+    answeredRoundCount() {
+        return this.answeredRounds;
+    }
+    /** `submit_plan` pre-check: a refusal text, or null to proceed. */
+    beforeSubmitPlan() {
+        if (!this.governOn || this.deps.getGateMode() !== 'plan')
+            return null;
+        const need = governanceOf(this.deps.config()).minAskRounds;
+        if (need <= 0 || !this.deps.gate.canPrompt())
+            return null;
+        if (this.answeredRounds >= need)
+            return null;
+        const uncovered = PLAN_INTERVIEW_TOPICS.filter((_, i) => !this.coveredTopics.has(i));
+        return govAskRoundsRefusal(this.answeredRounds, need, uncovered);
+    }
+    /** Stash the approved plan when governance is on. Returns which way the session goes. */
+    handlePlanApproved(plan) {
+        if (!this.governOn)
+            return 'build';
+        this.approvedPlan = renderPlanAsSpec(plan);
+        return 'govern';
+    }
+    /** `gov_run start` consumes the stash exactly once. */
+    takeApprovedPlan() {
+        const plan = this.approvedPlan;
+        this.approvedPlan = null;
+        return plan;
+    }
+    // -------------------------------------------------------------------------
+    // Tools
+    // -------------------------------------------------------------------------
+    /** `[]` when not registered, which is the byte-identical closed path. */
+    leadTools() {
+        if (!this.registered)
+            return [];
+        return [makeGovRunTool(this.api), makeGovDispatchTool(this.api)];
+    }
+    leadPolicyExempt() {
+        return GOV_LEAD_TOOL_NAMES;
+    }
+    childPolicyExempt() {
+        return GOV_CHILD_TOOL_NAMES;
+    }
+    /** Role tools for a governed child; `[]` for anything else. */
+    childToolsFor(spec) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return [];
+        const identity = { id: ext.identity, role: ext.role, generation: ext.generation };
+        return buildChildTools(ext.role, this.api, identity, { getCwd: () => this.deps.getCwd() });
+    }
+    /**
+     * 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, tools) {
+        const ext = spec.governance;
+        if (ext === undefined)
+            return tools;
+        const root = getGovernanceDir();
+        const base = ext.role === 'INSP'
+            ? applyInspectorToolPolicy(tools, { integrationCommands: ext.integrationCommands ?? [] })
+            : tools;
+        return base.map((tool) => withGovernanceReadGuard(tool, root));
+    }
+    // -------------------------------------------------------------------------
+    // Engine lifecycle and events
+    // -------------------------------------------------------------------------
+    /** The engine is created on first use: a session that never governs never opens a store. */
+    ensureEngine() {
+        if (this.engine !== null)
+            return this.engine;
+        const runtime = this.deps.getRuntime();
+        if (runtime === null)
+            throw new Error('governance: no team runtime in this session');
+        const store = new RunStore({ root: getGovernanceDir() });
+        this.store = store;
+        const engineDeps = {
+            runtime,
+            store,
+            artifacts: new ArtifactStore(store),
+            getConfig: () => governanceOf(this.deps.config()),
+            getTeamCeiling: () => Math.max(1, Math.min(this.deps.config().team.maxSubagents, TEAM_LIMITS.hardMaxSubagents)),
+            getCwd: () => this.deps.getCwd(),
+            getSessionId: () => this.deps.getSessionId?.(),
+            withPausedWatchdog: (fn) => this.deps.withPausedWatchdog(fn),
+            hasApiKey: () => this.deps.hasApiKey(),
+            modelCost: () => this.deps.modelCost(),
+            takeApprovedPlan: () => this.takeApprovedPlan(),
+            confirmCharter: (charter, signal) => this.confirmCharter(charter, signal),
+            now: this.deps.now ?? Date.now,
+        };
+        this.engine = createGovernanceEngine(engineDeps);
+        this.engineUnsubscribe = this.engine.subscribe((event) => {
+            for (const listener of [...this.listeners])
+                listener(event);
+        });
+        return this.engine;
+    }
+    /** `confirmCharter` through the EXISTING plan-review overlay; no new overlay kind (RV-10). */
+    async confirmCharter(charter, signal) {
+        if (!this.deps.gate.canPrompt())
+            return { decision: 'approved' };
+        const plan = {
+            title: charter.title,
+            summary: charter.summary,
+            steps: charter.steps,
+            filesTouched: charter.filesTouched,
+            risks: charter.risks,
+            openQuestions: [],
+        };
+        const response = await this.deps.withHumanWait(() => this.deps.gate.request({ kind: 'plan', plan }, signal));
+        if (response === null || response.kind !== 'planDecision')
+            return null;
+        return { decision: response.decision, feedback: response.feedback };
+    }
+    /** Subscribe to the governance event stream (works before the engine exists). */
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    snapshot() {
+        return this.engine?.snapshot() ?? null;
+    }
+    /** Run + ledger for the `/gov board` overlay (read-only views of live memory). */
+    boardInput() {
+        const core = this.engine?.internals;
+        if (core === undefined || core.run === null)
+            return null;
+        return {
+            run: core.run,
+            ledger: core.ledger,
+            boardPath: join(getGovernanceDir(), core.run.runId, 'board.md'),
+        };
+    }
+    abortStage() {
+        this.engine?.abortStage();
+    }
+    /**
+     * 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.
+     */
+    async listRuns() {
+        if (!this.registered)
+            return [];
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        const rows = await store.listRuns();
+        return rows.slice(0, RUNS_LISTED).map((r) => ({
+            runId: r.runId,
+            goal: r.goal,
+            status: r.status,
+            updatedAt: r.updatedAt,
+            ...(r.digest !== undefined ? { digest: r.digest } : {}),
+        }));
+    }
+    /** `/gov report [runId]`: a stored report, read-only (governance-mode-v1-1 7.2). */
+    async readReport(runId) {
+        if (!this.registered)
+            return { kind: 'no_run' };
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        const wanted = (runId ?? '').trim();
+        if (wanted !== '')
+            return readRunReport(store, wanted);
+        const latest = await store.latestForCwd(this.deps.getCwd());
+        return latest === null ? { kind: 'no_run' } : readRunReport(store, latest.runId);
+    }
+    /** `/gov pause`: the engine's verdict, or `no_run` when no engine was ever created. */
+    requestPause() {
+        return this.engine?.requestPause() ?? Promise.resolve('no_run');
+    }
+    cancelPause() {
+        return this.engine?.cancelPause() ?? false;
+    }
+    /** The dispatch-plan line for the live run (`/gov status`), or null without one. */
+    dispatchPlanText() {
+        const run = this.engine?.internals.run ?? null;
+        if (run === null)
+            return null;
+        const ceiling = Math.max(1, Math.min(this.deps.config().team.maxSubagents, TEAM_LIMITS.hardMaxSubagents));
+        return formatDispatchEstimate(estimateForRun(run, ceiling)) || 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.
+     */
+    async findResumableRun(runId) {
+        if (!this.registered)
+            return null;
+        const store = this.store ?? new RunStore({ root: getGovernanceDir() });
+        if (runId !== undefined && runId !== '') {
+            const known = (await store.listRuns()).find((r) => r.runId === runId);
+            return known ? known.runId : null;
+        }
+        const latest = await store.latestResumable(this.deps.getCwd());
+        return latest ? latest.runId : null;
+    }
+    dispose() {
+        this.engineUnsubscribe?.();
+        this.engineUnsubscribe = null;
+        this.engine?.dispose();
+        this.engine = null;
+        this.listeners.clear();
+    }
+    // -------------------------------------------------------------------------
+    // Lazy facade
+    // -------------------------------------------------------------------------
+    buildLazyApi() {
+        const e = () => this.ensureEngine();
+        return {
+            start: (input, signal) => e().start(input, signal),
+            status: () => e().status(),
+            resume: (runId) => e().resume(runId),
+            dispatchStage: (input, signal) => e().dispatchStage(input, signal),
+            close: (summary) => e().close(summary),
+            abandon: (reason) => e().abandon(reason),
+            resolve: (input) => e().resolve(input),
+            snapshot: () => this.snapshot(),
+            isStageRunning: () => this.isStageRunning(),
+            abortStage: () => this.abortStage(),
+            subscribe: (listener) => this.subscribe(listener),
+            dispose: () => this.dispose(),
+            submitWork: (id, input) => e().submitWork(id, input),
+            submitReview: (id, input) => e().submitReview(id, input),
+            submitTest: (id, input) => e().submitTest(id, input),
+            inspectorApply: (input) => e().inspectorApply(input),
+            inspectorRule: (input) => e().inspectorRule(input),
+            inspectorSettle: (input) => e().inspectorSettle(input),
+            standings: () => e().standings(),
+            readArtifact: (id, input) => e().readArtifact(id, input),
+            requestView: (id, input) => e().requestView(id, input),
+            scan: (id, input) => e().scan(id, input),
+        };
+    }
+    /** Posture helper for callers that only hold the gate mode. */
+    currentPosture(mode) {
+        return composePosture(mode, this.governOn);
+    }
+}

package/dist/agent/invocation-card.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Invocation cards (tui-invocation-cards): what a transcript shows INSTEAD of the
+ * system prompt a command submitted on the user's behalf.
+ *
+ * Pure and total: no IO, no React, no Ink, nothing but `import type`. ASCII ONLY -
+ * `src/agent/**` new files sit inside the `glyphs.test.ts` scan scope.
+ *
+ * ONE CONSTRUCTOR (I-3). `buildInvocationCard` is the only function that turns raw
+ * command-layer material into a card, `App.submitMessage` is its only caller, and
+ * `sanitizeInvocationCard` (the session-load path) shares its normaliser so a card
+ * written today and a card read back tomorrow cannot drift apart.
+ *
+ * ORDER IS REDACT -> NORMALISE -> LIMIT, and it is the load-bearing part (I-6). Cut
+ * first and a secret that straddles the cut leaves a prefix shorter than the
+ * redaction patterns' minimum length: the half-key sails through into the
+ * transcript, the session file and the exit replay.
+ */
+export type InvocationVariant = 'skill' | 'team' | 'todo' | 'govern';
+/** Everything one card needs; persisted, queued and rendered in this one shape. */
+export interface InvocationCard {
+    readonly variant: InvocationVariant;
+    /** Skill name / 'continue' / 'resume'; '' for team. */
+    readonly name: string;
+    /** What the user typed (or its equivalent), redacted and capped; also `Entry.text`. */
+    readonly commandLine: string;
+    /** The user's own words (args / brief), redacted and trimmed; may be ''. */
+    readonly input: string;
+    /** Characters cut from `input`; 0 when nothing was cut. */
+    readonly inputHidden: number;
+    /** Fact fragments, each at most `factMaxChars`, at most `factsMax` of them. */
+    readonly facts: readonly string[];
+    /** One disclosure sentence. */
+    readonly note?: string;
+}
+/**
+ * The renderer, the height estimate and the loader all read THESE numbers (I-4).
+ * A card's height is a function of its data and these limits, so it is bounded:
+ * header + `inputMaxLines` + hidden tail + note.
+ */
+export declare const INVOCATION_LIMITS: {
+    readonly commandLineMaxChars: 2000;
+    readonly inputMaxChars: 480;
+    readonly inputMaxLines: 8;
+    readonly nameMaxChars: 64;
+    readonly factsMax: 5;
+    readonly factMaxChars: 28;
+    readonly noteMaxChars: 140;
+};
+/**
+ * Raw material from the command layer: NOT redacted, NOT trimmed. Commands must not
+ * cut or scrub it themselves - both happen exactly once, in `buildInvocationCard`.
+ */
+export interface InvocationCardInput {
+    variant: InvocationVariant;
+    name?: string;
+    commandLine: string;
+    input?: string;
+    facts?: readonly string[];
+    note?: string;
+}
+/**
+ * Total, never throws. `redact` is injected (the same closure `Command:` echo uses) so
+ * this module depends on nothing; the default is the identity for tests and the loader.
+ */
+export declare function buildInvocationCard(input: InvocationCardInput, redact?: (text: string) => string): InvocationCard;
+/**
+ * Session-load path: `null` for anything that is not a plausible card, so the caller
+ * drops the field and the entry degrades to a plain user message (I-7). Re-derives
+ * `inputHidden` from nothing - it trusts the stored count only when it is a sane integer.
+ */
+export declare function sanitizeInvocationCard(value: unknown): InvocationCard | null;
+/**
+ * Emergency kill switch (`ARAGON_NO_INVOCATION_CARDS=1`): every command and the App fall
+ * back to the pre-card behaviour. Read at call time, not import time, so a test (or a
+ * wrapper script) that sets the variable after load is honoured.
+ */
+export declare function invocationCardsEnabled(env?: NodeJS.ProcessEnv): boolean;