@aragon-agent/cli 0.6.43 → 0.6.45

package/dist/governance/store/scoreboard-export.js

@@ -0,0 +1,65 @@
+/**
+ * One-way export of the ledger in the `token_ledger.py` v2.0 field layout
+ * (governance-mode section 12.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * The point is that a user can point the reference skill's scripts at
+ * `scoreboard.json` for ad-hoc analysis. It is NEVER read back: the ledger of record is
+ * `events.jsonl` (+ `ledger.json`), and a second readable copy would be a second source
+ * of truth that could drift. Python's vocabulary only knows `provisional` and
+ * `confirmed` as history statuses, so `immediate` positives (which land in `confirmed`,
+ * RV-9) are exported as `confirmed`.
+ */
+export const SCOREBOARD_VERSION = '2.0';
+function iso(ms) {
+    return new Date(ms).toISOString();
+}
+function historyRow(entry) {
+    return {
+        event: entry.code,
+        delta: entry.delta,
+        status: entry.settlement === 'provisional' ? 'provisional' : 'confirmed',
+        balance_after: entry.confirmedAfter + entry.provisionalAfter,
+        confirmed_after: entry.confirmedAfter,
+        provisional_after: entry.provisionalAfter,
+        reason: entry.reason,
+        timestamp: iso(entry.at),
+    };
+}
+function escrowRow(entry) {
+    const actionMap = { held: 'hold', released: 'confirm', clawed_back: 'clawback' };
+    return {
+        action: actionMap[entry.action],
+        phase: entry.phase,
+        delta: entry.action === 'clawed_back' ? -entry.amount : entry.amount,
+        reason: entry.reason,
+        timestamp: iso(entry.at),
+    };
+}
+function agentRow(record) {
+    return {
+        role: record.role,
+        generation: record.generation,
+        tokens: record.confirmed + record.provisional,
+        tokens_confirmed: record.confirmed,
+        tokens_provisional: record.provisional,
+        status: record.status,
+        replaced_by: record.replacedBy,
+        history: record.history.map(historyRow),
+        escrow_history: record.escrowHistory.map(escrowRow),
+    };
+}
+/** Build the export document. Pure: `now` is injected so the output is reproducible. */
+export function buildScoreboard(ledger, now) {
+    const agents = {};
+    for (const [id, record] of Object.entries(ledger.agents))
+        agents[id] = agentRow(record);
+    return {
+        version: SCOREBOARD_VERSION,
+        generated_by: 'aragon-governance',
+        generated_at: iso(now),
+        agents,
+        phase_reports: [],
+    };
+}

package/dist/governance/tools/child-tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The governance tool array of one governed child, by role (governance-mode 5.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE ROLE DECIDES THE TOOLS, AND THE TOOLS DECIDE THE POWERS:
+ *
+ *  - DEV / FIX: submit work, read, standings, view. No scan (the developer is the one being
+ *    scanned) and no review or ledger tool.
+ *  - REV: submit review, scan, read, standings, view.
+ *  - TEST: submit test, scan, read, standings, view.
+ *  - INSP: the three ledger tools, read, scan, standings. No submit tools and no `gov_view`
+ *    (its read access has no restriction to ask around).
+ *
+ * Nothing here can write the ledger except the inspector tools (I-G1): the submit tools hand
+ * structured data to the engine, which books it. This function returns ONLY governance
+ * tools; the caller appends them to the child's built-in tools and, for the inspector,
+ * passes the built-ins through `applyInspectorToolPolicy`.
+ */
+import type { AgentTool } from '@aragon-agent/core';
+import type { GovRole, GovernanceEngineApi, Identity } from '../types.js';
+import { type ScanToolContext } from './scan-incomplete.js';
+/** What a child's tools need from the host. Read live, never cached. */
+export type ChildToolContext = ScanToolContext;
+/**
+ * Build the governance tools for `identity` in `role`.
+ *
+ * `identity.role` is not consulted: the caller states the role explicitly so a mismatched
+ * pair fails a test instead of silently handing out the wrong powers.
+ */
+export declare function buildChildTools(role: GovRole, engine: GovernanceEngineApi, identity: Identity, ctx: ChildToolContext): AgentTool[];

package/dist/governance/tools/child-tools.js

@@ -0,0 +1,65 @@
+/**
+ * The governance tool array of one governed child, by role (governance-mode 5.1, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE ROLE DECIDES THE TOOLS, AND THE TOOLS DECIDE THE POWERS:
+ *
+ *  - DEV / FIX: submit work, read, standings, view. No scan (the developer is the one being
+ *    scanned) and no review or ledger tool.
+ *  - REV: submit review, scan, read, standings, view.
+ *  - TEST: submit test, scan, read, standings, view.
+ *  - INSP: the three ledger tools, read, scan, standings. No submit tools and no `gov_view`
+ *    (its read access has no restriction to ask around).
+ *
+ * Nothing here can write the ledger except the inspector tools (I-G1): the submit tools hand
+ * structured data to the engine, which books it. This function returns ONLY governance
+ * tools; the caller appends them to the child's built-in tools and, for the inspector,
+ * passes the built-ins through `applyInspectorToolPolicy`.
+ */
+import { makeLedgerApplyTool, makeLedgerRuleTool, makeLedgerSettleTool, } from './inspector-tools.js';
+import { makeScanTool } from './scan-incomplete.js';
+import { makeReadTool, makeStandingsTool, makeViewTool } from './shared-tools.js';
+import { makeSubmitReviewTool, makeSubmitTestTool, makeSubmitWorkTool, } from './submit-tools.js';
+/**
+ * Build the governance tools for `identity` in `role`.
+ *
+ * `identity.role` is not consulted: the caller states the role explicitly so a mismatched
+ * pair fails a test instead of silently handing out the wrong powers.
+ */
+export function buildChildTools(role, engine, identity, ctx) {
+    switch (role) {
+        case 'DEV':
+            return [
+                makeSubmitWorkTool(engine, identity),
+                makeReadTool(engine, identity),
+                makeStandingsTool(engine),
+                makeViewTool(engine, identity),
+            ];
+        case 'REV':
+            return [
+                makeSubmitReviewTool(engine, identity),
+                makeScanTool(ctx),
+                makeReadTool(engine, identity),
+                makeStandingsTool(engine),
+                makeViewTool(engine, identity),
+            ];
+        case 'TEST':
+            return [
+                makeSubmitTestTool(engine, identity),
+                makeScanTool(ctx),
+                makeReadTool(engine, identity),
+                makeStandingsTool(engine),
+                makeViewTool(engine, identity),
+            ];
+        case 'INSP':
+            return [
+                makeLedgerApplyTool(engine),
+                makeLedgerRuleTool(engine),
+                makeLedgerSettleTool(engine),
+                makeReadTool(engine, identity),
+                makeScanTool(ctx),
+                makeStandingsTool(engine),
+            ];
+    }
+}

package/dist/governance/tools/guard.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tool wrappers that enforce the governance boundaries (governance-mode 7.4, D-2, D-6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THREE WRAPPERS, THREE DIFFERENT STRENGTHS - and the difference is the point:
+ *
+ *  - `withGovernanceGate` is a HARD gate on the Orchestrator's tool calls (D-2): the lead
+ *    cannot change the workspace, whatever the prompt says. It is a property of the tool
+ *    layer, not a request.
+ *  - `applyInspectorToolPolicy` removes the inspector's write tools and narrows its shell to
+ *    the registered integration commands.
+ *  - `withGovernanceReadGuard` is a TRIPWIRE, not a security boundary (D-6). The shell cannot
+ *    be fully confined, so a child that has been told nothing about the governance store's
+ *    location and that is refused when a call mentions it is a speed bump for a model that
+ *    stumbles into it, nothing more. Do not cite it as a security control anywhere.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { AgentMode } from '../../agent/agent-mode.js';
+/** What the gate reads on EVERY call. Never captured: `/gov off` and Shift+Tab flip both. */
+export interface GovernanceGateState {
+    governOn: boolean;
+    mode: AgentMode;
+}
+/**
+ * Wrap one lead tool with the governance gate.
+ *
+ * Tools the gate has no opinion on are returned UNCHANGED (same object), so the wrapped
+ * array differs from the input only where the gate can act, and a hot read-only tool pays
+ * no extra frame.
+ *
+ * Decision table (state is read live, per call):
+ *  - `write_file / edit_file / bash / bash_kill / skill_install / skill_create`: refused
+ *    whenever governance is on, in either gate mode (plan mode refuses them too; the plan
+ *    gate is the outer wrapper and speaks first).
+ *  - `task`: refused only when governance is on AND the mode is `build`. In the PLAN+GOVERN
+ *    planning phase it stays available for read-only research (6.1).
+ *  - `gov_run / gov_dispatch`: refused with the off text when governance is off, and with
+ *    the plan-phase text when the mode is `plan`.
+ *
+ * Refusals of the refused-tool set are `errorResult` (the plan gate's convention: a refused
+ * tool did not run); the gov-tool refusals are plain text (a retry cannot help).
+ */
+export declare function withGovernanceGate(tool: AgentTool, getState: () => GovernanceGateState): AgentTool;
+export interface InspectorPolicyOptions {
+    /** The commands the orchestrator registered at `start`. Empty = the inspector has no bash. */
+    integrationCommands: readonly string[];
+}
+/** True when `command` is exactly a registered command or extends one at a word boundary. */
+export declare function isAllowedIntegrationCommand(command: string, registered: readonly string[]): boolean;
+/**
+ * The inspector's tool array: write tools removed; `bash` replaced by the restricted shell
+ * (or dropped when no integration command is registered - the inspector then verifies
+ * statically and says so in its report).
+ *
+ * It is NOT done with `spec.readOnly`: that would route the child through the plan gate,
+ * which refuses `bash` in full ("a shell string cannot be classified"), and the inspector
+ * could not run the integration suite at all (5.1).
+ */
+export declare function applyInspectorToolPolicy(tools: readonly AgentTool[], options: InspectorPolicyOptions): AgentTool[];
+/**
+ * Refuse a read-class tool call whose arguments mention the governance root.
+ *
+ * A TRIPWIRE (D-6). Defeating it needs a path the model was never given, spelled in a form
+ * the substring test misses (a symlink, an environment variable, a relative hop). It exists
+ * to stop the accidental read and to make the deliberate one a conscious act that the
+ * refusal text names.
+ *
+ * An empty `governanceRoot` returns the tool unchanged: `''.includes` would match every call.
+ */
+export declare function withGovernanceReadGuard(tool: AgentTool, governanceRoot: string): AgentTool;

package/dist/governance/tools/guard.js

@@ -0,0 +1,194 @@
+/**
+ * Tool wrappers that enforce the governance boundaries (governance-mode 7.4, D-2, D-6).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THREE WRAPPERS, THREE DIFFERENT STRENGTHS - and the difference is the point:
+ *
+ *  - `withGovernanceGate` is a HARD gate on the Orchestrator's tool calls (D-2): the lead
+ *    cannot change the workspace, whatever the prompt says. It is a property of the tool
+ *    layer, not a request.
+ *  - `applyInspectorToolPolicy` removes the inspector's write tools and narrows its shell to
+ *    the registered integration commands.
+ *  - `withGovernanceReadGuard` is a TRIPWIRE, not a security boundary (D-6). The shell cannot
+ *    be fully confined, so a child that has been told nothing about the governance store's
+ *    location and that is refused when a call mentions it is a speed bump for a model that
+ *    stumbles into it, nothing more. Do not cite it as a security control anywhere.
+ */
+import { errorResult, textResult } from '@aragon-agent/core';
+import { GOV_LEAD_TOOL_NAMES, GOVERN_ORCHESTRATOR_REFUSED_TOOLS } from '../limits.js';
+import { govOffRefusal, govPlanPhaseRefusal, governRefusal } from '../prompts/refusals.js';
+const REFUSED_TOOLS = new Set(GOVERN_ORCHESTRATOR_REFUSED_TOOLS);
+/**
+ * Wrap one lead tool with the governance gate.
+ *
+ * Tools the gate has no opinion on are returned UNCHANGED (same object), so the wrapped
+ * array differs from the input only where the gate can act, and a hot read-only tool pays
+ * no extra frame.
+ *
+ * Decision table (state is read live, per call):
+ *  - `write_file / edit_file / bash / bash_kill / skill_install / skill_create`: refused
+ *    whenever governance is on, in either gate mode (plan mode refuses them too; the plan
+ *    gate is the outer wrapper and speaks first).
+ *  - `task`: refused only when governance is on AND the mode is `build`. In the PLAN+GOVERN
+ *    planning phase it stays available for read-only research (6.1).
+ *  - `gov_run / gov_dispatch`: refused with the off text when governance is off, and with
+ *    the plan-phase text when the mode is `plan`.
+ *
+ * Refusals of the refused-tool set are `errorResult` (the plan gate's convention: a refused
+ * tool did not run); the gov-tool refusals are plain text (a retry cannot help).
+ */
+export function withGovernanceGate(tool, getState) {
+    const refusable = REFUSED_TOOLS.has(tool.name);
+    const isGovTool = GOV_LEAD_TOOL_NAMES.has(tool.name);
+    if (!refusable && !isGovTool)
+        return tool;
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const { governOn, mode } = getState();
+            if (isGovTool) {
+                if (!governOn)
+                    return textResult(govOffRefusal());
+                if (mode === 'plan')
+                    return textResult(govPlanPhaseRefusal());
+            }
+            else if (governOn && (tool.name !== 'task' || mode === 'build')) {
+                return errorResult(governRefusal(tool.name));
+            }
+            return original(id, params, ctx);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Inspector tool policy
+// ---------------------------------------------------------------------------
+/** Tools the inspector never receives: it audits, it does not change the workspace. */
+const INSPECTOR_REMOVED_TOOLS = new Set([
+    'write_file',
+    'edit_file',
+    'skill_install',
+    'skill_create',
+    'bash_kill',
+]);
+/**
+ * Shell metacharacters that would let an allowed prefix carry a second command
+ * (`npm test; curl ...`, `npm test && rm -rf`, `npm test $(...)`). The registered command
+ * may itself contain any of them (an exact match is always allowed); only the SUFFIX the
+ * inspector appends is screened. Stricter than the spec's "word-boundary prefix", on
+ * purpose: a prefix rule alone is a shell with extra steps.
+ */
+const SHELL_CONTROL_CHARS = /[;&|<>`\r\n]|\$\(/;
+/** True when `command` is exactly a registered command or extends one at a word boundary. */
+export function isAllowedIntegrationCommand(command, registered) {
+    const candidate = command.trim();
+    if (candidate === '')
+        return false;
+    return registered.some((raw) => {
+        const base = raw.trim();
+        if (base === '')
+            return false;
+        if (candidate === base)
+            return true;
+        if (!candidate.startsWith(base))
+            return false;
+        const rest = candidate.slice(base.length);
+        return /^\s/.test(rest) && !SHELL_CONTROL_CHARS.test(rest);
+    });
+}
+function restrictBash(bash, registered) {
+    const original = bash.execute;
+    const listing = registered.join('; ');
+    return {
+        ...bash,
+        description: `${bash.description} RESTRICTED: only the registered integration commands may run ` +
+            `(${listing}); anything else is refused.`,
+        async execute(id, params, ctx) {
+            const command = params.command;
+            if (typeof command !== 'string' || !isAllowedIntegrationCommand(command, registered)) {
+                return textResult('NOT ACCEPTED: the inspector may only run the registered integration commands: ' +
+                    `${listing}`);
+            }
+            return original(id, params, ctx);
+        },
+    };
+}
+/**
+ * The inspector's tool array: write tools removed; `bash` replaced by the restricted shell
+ * (or dropped when no integration command is registered - the inspector then verifies
+ * statically and says so in its report).
+ *
+ * It is NOT done with `spec.readOnly`: that would route the child through the plan gate,
+ * which refuses `bash` in full ("a shell string cannot be classified"), and the inspector
+ * could not run the integration suite at all (5.1).
+ */
+export function applyInspectorToolPolicy(tools, options) {
+    const registered = options.integrationCommands.map((c) => c.trim()).filter((c) => c !== '');
+    const out = [];
+    for (const tool of tools) {
+        if (INSPECTOR_REMOVED_TOOLS.has(tool.name))
+            continue;
+        if (tool.name === 'bash') {
+            if (registered.length > 0)
+                out.push(restrictBash(tool, registered));
+            continue;
+        }
+        out.push(tool);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Governance-store read tripwire
+// ---------------------------------------------------------------------------
+const READ_GUARDED_TOOLS = new Set([
+    'read_file',
+    'list_dir',
+    'glob',
+    'grep',
+    'bash',
+]);
+const STORE_REFUSAL = 'NOT ACCEPTED: the governance store is not readable from here; use gov_read';
+/** Forward-slash, lower-case form used ONLY for the substring comparison. */
+function comparable(text) {
+    return text.replace(/\\/g, '/').toLowerCase();
+}
+/** Every string anywhere in `value`, depth-bounded so a hostile argument cannot blow up. */
+function collectStrings(value, out, depth = 0) {
+    if (typeof value === 'string')
+        out.push(value);
+    else if (depth < 4 && Array.isArray(value)) {
+        for (const item of value)
+            collectStrings(item, out, depth + 1);
+    }
+    else if (depth < 4 && value !== null && typeof value === 'object') {
+        for (const item of Object.values(value))
+            collectStrings(item, out, depth + 1);
+    }
+}
+/**
+ * Refuse a read-class tool call whose arguments mention the governance root.
+ *
+ * A TRIPWIRE (D-6). Defeating it needs a path the model was never given, spelled in a form
+ * the substring test misses (a symlink, an environment variable, a relative hop). It exists
+ * to stop the accidental read and to make the deliberate one a conscious act that the
+ * refusal text names.
+ *
+ * An empty `governanceRoot` returns the tool unchanged: `''.includes` would match every call.
+ */
+export function withGovernanceReadGuard(tool, governanceRoot) {
+    const root = comparable(governanceRoot).replace(/\/+$/, '');
+    if (root === '' || !READ_GUARDED_TOOLS.has(tool.name))
+        return tool;
+    const original = tool.execute;
+    return {
+        ...tool,
+        async execute(id, params, ctx) {
+            const strings = [];
+            collectStrings(params, strings);
+            if (strings.some((s) => comparable(s).includes(root)))
+                return textResult(STORE_REFUSAL);
+            return original(id, params, ctx);
+        },
+    };
+}

package/dist/governance/tools/inspector-tools.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The Inspector's ledger tools: `ledger_apply`, `ledger_rule`, `ledger_settle`
+ * (governance-mode 5.4, 5.6, 5.7, 7.3).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE INSPECTOR BOOKS JUDGEMENT, NOT MECHANICS (D-4). The rule engine books every
+ * mechanical event by itself; `ledger_apply` accepts ONLY the codes whose bookers include
+ * `S` (`isInspectorBookable`), and answers any other code with "this event is handled by
+ * the engine". That is what removes a whole class of failure: an LLM inspector that forgets
+ * to book, books twice, or invents an amount. Amounts never come from the model - the
+ * catalogue row supplies the delta.
+ *
+ * EVIDENCE OR NO EVENT. A judgement event needs concrete evidence (files, lines, quotes) of
+ * at least `GOV_LIMITS.evidenceMinChars`; the check also rejects filler such as one repeated
+ * character, which would satisfy a bare length test.
+ *
+ * THE INSPECTOR IS NOT SCORED (I-G5). A target of `insp` is refused here, before the
+ * engine, and the engine refuses it again (defence in depth for a rule the whole fairness
+ * argument rests on).
+ *
+ * THE TARGET'S ROLE MUST MATCH THE EVENT'S. `D6` is a developer event; booking it against
+ * `rev1` is a typo or a hallucination, and a ledger that accepts it is wrong silently.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import { type EventCode } from '../rules/events-table.js';
+import type { GovernanceEngineApi, InspectorReport, RcaInput } from '../types.js';
+import { type Normalized } from './normalize-util.js';
+export interface LedgerApplyInput {
+    code: EventCode;
+    agentId: string;
+    wpId?: string;
+    reason: string;
+    evidence: string;
+    incidentId?: string;
+}
+export interface LedgerRuleInput {
+    claimId: string;
+    decision: 'upheld' | 'rejected';
+    ruling: string;
+}
+/** `ledger_settle` arguments. `kind` is the tool's name for the report's `stage`. */
+export interface LedgerSettleInput {
+    kind: InspectorReport['stage'];
+    phase: number;
+    summary: string;
+    contractChecks: InspectorReport['contractChecks'];
+    integration?: NonNullable<InspectorReport['integration']>;
+    rca?: RcaInput;
+    escalations: InspectorReport['escalations'];
+}
+/** Validate a `ledger_apply` argument object. Pure; the engine may reuse it. */
+export declare function normalizeLedgerApply(raw: unknown): Normalized<LedgerApplyInput>;
+/** Validate a `ledger_rule` argument object. Pure. */
+export declare function normalizeLedgerRule(raw: unknown): Normalized<LedgerRuleInput>;
+/** Validate a `ledger_settle` argument object. Pure. */
+export declare function normalizeLedgerSettle(raw: unknown): Normalized<LedgerSettleInput>;
+/** `ledger_apply`: INSP only. */
+export declare function makeLedgerApplyTool(engine: GovernanceEngineApi): AgentTool;
+/** `ledger_rule`: INSP only. */
+export declare function makeLedgerRuleTool(engine: GovernanceEngineApi): AgentTool;
+/** `ledger_settle`: INSP only. The stage ends with this call. */
+export declare function makeLedgerSettleTool(engine: GovernanceEngineApi): AgentTool;