@aragon-agent/cli 0.6.44 → 0.6.45

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

@@ -0,0 +1,424 @@
+/**
+ * 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 { textResult } from '@aragon-agent/core';
+import { GOV_LIMITS } from '../limits.js';
+import { INSPECTOR_ID, parseIdentityId } from '../roles.js';
+import { eventDef, inspectorBookableCodes, isEventCode, isInspectorBookable, } from '../rules/events-table.js';
+import { Issues, SUBMIT_LIMITS as L, formatNotAccepted, isRecord, readBool, readInteger, withNotes, } from './normalize-util.js';
+const ID_PATTERN = /^[A-Za-z0-9._:-]+$/;
+const SETTLE_KINDS = ['settle', 'integrate'];
+const MIN_DISTINCT_EVIDENCE_CHARS = 6;
+const RCA_ATTRIBUTIONS_MAX = 20;
+const CONTRACT_CHECK_STATUSES = ['ok', 'mismatch', 'unverifiable'];
+const INTEGRATION_RESULTS = ['pass', 'fail', 'not_run'];
+const ATTRIBUTION_LEVELS = ['primary', 'contributing', 'oversight'];
+const CONTRACT_KINDS = ['producer', 'consumer_unverified', 'none'];
+const MISS_KINDS = ['review_integration', 'test_defect', 'test_boundary'];
+const ESCALATION_KINDS = [
+    'wp_rework_cap',
+    'integration_exhausted',
+    'dispute',
+];
+function argsOf(raw, issues, expected) {
+    if (isRecord(raw))
+        return raw;
+    issues.fail(`the arguments must be an object with ${expected}.`);
+    return {};
+}
+/** A short identifier (claim id, incident id, contract id); never clipped. */
+function readId(raw, label, issues, required) {
+    const id = issues.str(raw, label, 200, required);
+    if (id !== '' && (id.length > L.idChars || !ID_PATTERN.test(id))) {
+        issues.fail(`${label} "${id.slice(0, 40)}" is not a valid id (letters, digits, . _ : -).`);
+    }
+    return id;
+}
+// ---------------------------------------------------------------------------
+// ledger_apply
+// ---------------------------------------------------------------------------
+function judgmentCodesHint() {
+    return `Judgment codes you may book: ${inspectorBookableCodes().join(', ')}.`;
+}
+/** The event code, or `undefined` after recording why it cannot be booked here. */
+function readApplyCode(raw, issues) {
+    const text = issues.str(raw, 'code', 8, true).toUpperCase();
+    if (text === '')
+        return undefined;
+    if (!isEventCode(text)) {
+        issues.fail(`unknown event code "${text}". ${judgmentCodesHint()}`);
+        return undefined;
+    }
+    if (!isInspectorBookable(text)) {
+        issues.fail(`this event is handled by the engine (${text}: ${eventDef(text).title}). ` +
+            judgmentCodesHint());
+        return undefined;
+    }
+    return text;
+}
+/** The booked agent. The inspector is refused; the role must match the event's role. */
+function readApplyTarget(raw, code, issues) {
+    const id = issues.str(raw, 'agentId', 40, true).toLowerCase();
+    if (id === '')
+        return id;
+    if (id === INSPECTOR_ID) {
+        issues.fail('the inspector is not scored: ledger events cannot target insp.');
+        return id;
+    }
+    const parsed = parseIdentityId(id);
+    if (!parsed) {
+        issues.fail(`agentId "${id}" is not a roster id (for example dev1, rev2, tst1, dev2-r1).`);
+        return id;
+    }
+    const role = code ? eventDef(code).role : 'ALL';
+    if (role !== 'ALL' && role !== parsed.role) {
+        issues.fail(`${code} applies to ${role} agents; ${id} is a ${parsed.role} agent.`);
+    }
+    return id;
+}
+/** Evidence must be concrete: long enough, and not one character repeated. */
+function readEvidence(raw, issues) {
+    const evidence = issues.str(raw, 'evidence', GOV_LIMITS.evidenceMaxChars);
+    const distinct = new Set(evidence.toLowerCase().replace(/\s/g, '')).size;
+    if (evidence.length < GOV_LIMITS.evidenceMinChars || distinct < MIN_DISTINCT_EVIDENCE_CHARS) {
+        issues.fail('evidence must be concrete (files, lines, quotes) and at least ' +
+            `${GOV_LIMITS.evidenceMinChars} characters; no evidence, no event.`);
+    }
+    return evidence;
+}
+/** Validate a `ledger_apply` argument object. Pure; the engine may reuse it. */
+export function normalizeLedgerApply(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'code, agentId, reason and evidence');
+    const code = readApplyCode(args.code, issues);
+    const agentId = readApplyTarget(args.agentId, code, issues);
+    const reason = issues.str(args.reason, 'reason', GOV_LIMITS.reasonChars, true);
+    const evidence = readEvidence(args.evidence, issues);
+    const wpId = issues.wpId(args.wpId, 'wpId', false);
+    const incidentId = readId(args.incidentId, 'incidentId', issues, false);
+    if (code === undefined) {
+        return { ok: false, errors: issues.errors.length > 0 ? issues.errors : ['code is required.'] };
+    }
+    return issues.result({
+        code,
+        agentId,
+        reason,
+        evidence,
+        ...(wpId !== '' ? { wpId } : {}),
+        ...(incidentId !== '' ? { incidentId } : {}),
+    });
+}
+// ---------------------------------------------------------------------------
+// ledger_rule
+// ---------------------------------------------------------------------------
+/** Validate a `ledger_rule` argument object. Pure. */
+export function normalizeLedgerRule(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'claimId, decision and ruling');
+    const claimId = readId(args.claimId, 'claimId', issues, true);
+    const decision = issues.oneOf(args.decision, 'decision', ['upheld', 'rejected'], {
+        aliases: { uphold: 'upheld', reject: 'rejected', denied: 'rejected' },
+        required: true,
+    });
+    const ruling = issues.str(args.ruling, 'ruling', GOV_LIMITS.rulingChars, true);
+    return issues.result({ claimId, decision: decision ?? 'rejected', ruling });
+}
+// ---------------------------------------------------------------------------
+// ledger_settle
+// ---------------------------------------------------------------------------
+function readContractChecks(raw, issues) {
+    const out = [];
+    issues.items(raw, 'contractChecks', L.contractsMax).forEach((item, i) => {
+        const at = `contractChecks[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {contractId, status: ok | mismatch | unverifiable, note}.`);
+            return;
+        }
+        const status = issues.oneOf(item.status, `${at}.status`, CONTRACT_CHECK_STATUSES, {
+            aliases: { pass: 'ok', fail: 'mismatch', mismatched: 'mismatch', unknown: 'unverifiable' },
+            required: true,
+        });
+        out.push({
+            contractId: readId(item.contractId, `${at}.contractId`, issues, true),
+            status: status ?? 'unverifiable',
+            note: issues.str(item.note, `${at}.note`, L.rationaleChars),
+        });
+    });
+    return out;
+}
+function readIntegration(raw, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.fail('integration must be {result: pass | fail | not_run, commands: [..]}.');
+        return undefined;
+    }
+    const result = issues.oneOf(raw.result, 'integration.result', INTEGRATION_RESULTS, {
+        aliases: { passed: 'pass', failed: 'fail', skipped: 'not_run', notrun: 'not_run' },
+        required: true,
+    });
+    const commands = [];
+    issues.items(raw.commands, 'integration.commands', L.commandsMax).forEach((item, i) => {
+        const at = `integration.commands[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {cmd, exit, summary}.`);
+            return;
+        }
+        const exit = readInteger(item.exit);
+        if (exit === undefined)
+            issues.fail(`${at}.exit must be the integer exit code.`);
+        commands.push({
+            cmd: issues.str(item.cmd, `${at}.cmd`, L.commandChars, true),
+            exit: exit ?? -1,
+            summary: issues.str(item.summary, `${at}.summary`, L.resultChars),
+        });
+    });
+    return { result: result ?? 'not_run', commands };
+}
+function readAttributions(raw, issues) {
+    const out = [];
+    issues.items(raw, 'rca.attributions', RCA_ATTRIBUTIONS_MAX).forEach((item, i) => {
+        const at = `rca.attributions[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {agentId, level, contract, miss?, note}.`);
+            return;
+        }
+        const agentId = readApplyTarget(item.agentId, undefined, issues);
+        const level = issues.oneOf(item.level, `${at}.level`, ATTRIBUTION_LEVELS, { required: true });
+        const contract = issues.oneOf(item.contract, `${at}.contract`, CONTRACT_KINDS);
+        const miss = issues.oneOf(item.miss, `${at}.miss`, MISS_KINDS);
+        if (miss !== undefined && level !== 'oversight') {
+            issues.note(`${at}.miss was dropped: it applies to oversight attributions only.`);
+        }
+        out.push({
+            agentId,
+            level: level ?? 'contributing',
+            contract: contract ?? 'none',
+            ...(miss !== undefined && level === 'oversight' ? { miss } : {}),
+            note: issues.str(item.note, `${at}.note`, L.rationaleChars),
+        });
+    });
+    return out;
+}
+function readRca(raw, issues) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (!isRecord(raw)) {
+        issues.fail('rca must be {failingChecks, boundary, attributions, systemic}.');
+        return undefined;
+    }
+    const failingChecks = [];
+    issues.items(raw.failingChecks, 'rca.failingChecks', L.commandsMax).forEach((item, i) => {
+        const at = `rca.failingChecks[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {name, files: [..]}.`);
+            return;
+        }
+        failingChecks.push({
+            name: issues.str(item.name, `${at}.name`, L.shortChars, true),
+            files: issues.list(item.files, `${at}.files`, L.filesMax, L.pathChars),
+        });
+    });
+    const boundary = readBool(raw.boundary);
+    if (boundary === undefined)
+        issues.fail('rca.boundary is required: true or false.');
+    const attributions = readAttributions(raw.attributions, issues);
+    const systemic = readBool(raw.systemic) ?? false;
+    if (boundary === true && !systemic && attributions.length === 0) {
+        issues.fail('a boundary failure needs at least one attribution, or systemic:true.');
+    }
+    return { failingChecks, boundary: boundary ?? false, attributions, systemic };
+}
+function readEscalations(raw, issues) {
+    const out = [];
+    issues.items(raw, 'escalations', L.claimsMax).forEach((item, i) => {
+        const at = `escalations[${i}]`;
+        if (!isRecord(item)) {
+            issues.fail(`${at} must be {kind, wpId?, topic, positions: [{by, text}]}.`);
+            return;
+        }
+        const kind = issues.oneOf(item.kind, `${at}.kind`, ESCALATION_KINDS, {
+            aliases: { disagreement: 'dispute' },
+        });
+        const positions = [];
+        issues.items(item.positions, `${at}.positions`, 4).forEach((p, j) => {
+            if (!isRecord(p)) {
+                issues.fail(`${at}.positions[${j}] must be {by, text}.`);
+                return;
+            }
+            positions.push({
+                by: issues.str(p.by, `${at}.positions[${j}].by`, L.idChars, true),
+                text: issues.str(p.text, `${at}.positions[${j}].text`, L.argumentChars, true),
+            });
+        });
+        if (positions.length === 0)
+            issues.fail(`${at}.positions needs at least one position.`);
+        const wpId = issues.wpId(item.wpId, `${at}.wpId`, false);
+        out.push({
+            kind: kind ?? 'dispute',
+            topic: issues.str(item.topic, `${at}.topic`, L.shortChars * 2, true),
+            positions,
+            ...(wpId !== '' ? { wpId } : {}),
+        });
+    });
+    return out;
+}
+/** Cross-field rules: integrate needs a result; a failed one needs a root-cause analysis. */
+function crossCheckSettle(value, issues) {
+    if (value.kind !== 'integrate')
+        return;
+    if (!value.integration) {
+        issues.fail('integrate needs integration: {result: pass | fail | not_run, commands}.');
+    }
+    else if (value.integration.result === 'fail' && !value.rca) {
+        issues.fail('integration failed: include rca {failingChecks, boundary, attributions, systemic}. ' +
+            'Attribute only what you can show in code.');
+    }
+}
+/** Validate a `ledger_settle` argument object. Pure. */
+export function normalizeLedgerSettle(raw) {
+    const issues = new Issues();
+    const args = argsOf(raw, issues, 'kind, phase and summary');
+    const kind = issues.oneOf(args.kind, 'kind', SETTLE_KINDS, { required: true });
+    const phase = readInteger(args.phase);
+    if (phase === undefined || phase < 1)
+        issues.fail('phase must be the 1-based phase number.');
+    const integration = readIntegration(args.integration, issues);
+    const rca = readRca(args.rca, issues);
+    const value = {
+        kind: kind ?? 'settle',
+        phase: phase ?? 0,
+        summary: issues.str(args.summary, 'summary', L.summaryChars, true),
+        contractChecks: readContractChecks(args.contractChecks, issues),
+        escalations: readEscalations(args.escalations, issues),
+        ...(integration ? { integration } : {}),
+        ...(rca && integration?.result !== 'pass' ? { rca } : {}),
+    };
+    if (rca && integration?.result === 'pass') {
+        issues.note('rca was ignored: the integration passed.');
+    }
+    if (kind !== undefined)
+        crossCheckSettle(value, issues);
+    return issues.result(value);
+}
+const TEXT = { type: 'string' };
+const APPLY_DESCRIPTION = 'Book ONE judgment event against a developer, reviewer or tester. code must be a ' +
+    'judgment code (the mechanical ones are booked by the engine; booking them is refused). ' +
+    `agentId is the roster id; evidence must be concrete (files, lines, quotes), at least ` +
+    `${GOV_LIMITS.evidenceMinChars} characters. The amount comes from the event catalogue, ` +
+    'never from you. The inspector cannot be a target. No evidence, no event.';
+const RULE_DESCRIPTION = 'Rule on ONE open claim: decision upheld or rejected, with a ruling. Ruling priority: ' +
+    'spec text, then charter and contracts, then general engineering practice. The engine ' +
+    'books the resulting events. A ruling is final unless escalated to the user.';
+const SETTLE_DESCRIPTION = 'Close your stage with exactly ONE call. kind: settle or integrate; phase: the 1-based ' +
+    'phase number; summary; contractChecks as {contractId, status: ok | mismatch | ' +
+    'unverifiable, note}. For integrate give integration {result: pass | fail | not_run, ' +
+    'commands: [{cmd, exit, summary}]}; on failure also give rca {failingChecks: [{name, ' +
+    'files}], boundary, attributions: [{agentId, level: primary | contributing | oversight, ' +
+    'contract: producer | consumer_unverified | none, miss?, note}], systemic}. escalations ' +
+    'lists disputes for the user as {kind, wpId?, topic, positions: [{by, text}]}.';
+function inspect(tool, normalized, forward) {
+    if (!normalized.ok)
+        return textResult(formatNotAccepted(tool, normalized.errors));
+    return textResult(withNotes(forward(normalized.value), normalized.notes));
+}
+/** `NOT ACCEPTED: <first problem>` on one line, the rest below: the form 7.3 specifies. */
+function inlineNotAccepted(errors) {
+    const [first = 'invalid arguments.', ...rest] = errors;
+    return [
+        `NOT ACCEPTED: ${first}`,
+        ...rest.slice(0, 7).map((e) => `- ${e}`),
+        'No event was booked and nothing was deducted.',
+    ].join('\n');
+}
+/** `ledger_apply`: INSP only. */
+export function makeLedgerApplyTool(engine) {
+    return {
+        name: 'ledger_apply',
+        label: 'Book judgment event',
+        description: APPLY_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                code: { type: 'string', description: 'Event code, for example D6.' },
+                agentId: { type: 'string', description: 'Roster id of the agent, for example dev1.' },
+                wpId: { type: 'string', description: 'The work package concerned, if any.' },
+                reason: { type: 'string', description: 'One sentence.' },
+                evidence: { type: 'string', description: 'Files, lines, quotes.' },
+                incidentId: { type: 'string', description: 'Groups events of one incident (cap).' },
+            },
+            required: ['code', 'agentId', 'reason', 'evidence'],
+        },
+        async execute(_id, params) {
+            const normalized = normalizeLedgerApply(params);
+            if (!normalized.ok)
+                return textResult(inlineNotAccepted(normalized.errors));
+            return textResult(withNotes(engine.inspectorApply(normalized.value), normalized.notes));
+        },
+    };
+}
+/** `ledger_rule`: INSP only. */
+export function makeLedgerRuleTool(engine) {
+    return {
+        name: 'ledger_rule',
+        label: 'Rule on claim',
+        description: RULE_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                claimId: { type: 'string' },
+                decision: { type: 'string', description: 'upheld | rejected' },
+                ruling: TEXT,
+            },
+            required: ['claimId', 'decision', 'ruling'],
+        },
+        async execute(_id, params) {
+            return inspect('ledger_rule', normalizeLedgerRule(params), (v) => engine.inspectorRule(v));
+        },
+    };
+}
+/** `ledger_settle`: INSP only. The stage ends with this call. */
+export function makeLedgerSettleTool(engine) {
+    return {
+        name: 'ledger_settle',
+        label: 'Settle stage',
+        description: SETTLE_DESCRIPTION,
+        parameters: {
+            type: 'object',
+            properties: {
+                kind: { type: 'string', description: 'settle | integrate' },
+                phase: { type: 'number' },
+                summary: TEXT,
+                contractChecks: { type: 'array', items: { type: 'object' } },
+                integration: { type: 'object' },
+                rca: { type: 'object' },
+                escalations: { type: 'array', items: { type: 'object' } },
+            },
+            required: ['kind', 'phase', 'summary'],
+        },
+        async execute(_id, params) {
+            return inspect('ledger_settle', normalizeLedgerSettle(params), (v) => engine.inspectorSettle(v));
+        },
+    };
+}

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

@@ -0,0 +1,42 @@
+/**
+ * The Orchestrator's two tools, `gov_run` and `gov_dispatch` (governance-mode 7.2).
+ *
+ * ASCII ONLY (`governance/` is glyph-scanned).
+ *
+ * THE SCHEMAS DECLARE SHAPE, NOT POLICY (the `plan-tools.ts` P0-4 lesson). `type`,
+ * `required` and `default` stay; every bound lives in the `description`, which is what the
+ * model reads, and is enforced by the engine's own validation. Putting `maxItems` or an
+ * `enum` in the schema would make behaviour depend on whether `ajv`, an OPTIONAL dependency
+ * of core, happened to install: with it a bad call is rejected by the executor as a tool
+ * ERROR (inviting an identical retry), without it the same call reaches the engine. One
+ * design, two behaviours.
+ *
+ * RESULTS ARE ALWAYS `textResult` (7.1 rule 2), aborts and partial failures included - an
+ * error result invites the most expensive possible reaction, a retry of the whole stage.
+ * The engine owns validation and the `NOT ACCEPTED:` / `NEXT:` vocabulary; these tools only
+ * route.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { GovernanceEngineApi } from '../types.js';
+/** The `gov_run` actions, in the order the description lists them. */
+export declare const GOV_RUN_ACTIONS: readonly ["start", "status", "resume", "close", "abandon", "resolve"];
+export type GovRunAction = (typeof GOV_RUN_ACTIONS)[number];
+/** Text returned when the tool call's signal was already aborted at entry. */
+export declare const DISPATCH_ABORTED_AT_ENTRY: string;
+/**
+ * `gov_run`: start, inspect, resume, close, abandon and resolve a governed run.
+ *
+ * An unknown `action` is a non-error `NOT ACCEPTED` that lists the valid ones: the model
+ * guessed a verb, and a list repairs that in one turn.
+ */
+export declare function makeGovRunTool(engine: GovernanceEngineApi): AgentTool;
+/**
+ * `gov_dispatch`: run one stage.
+ *
+ * ABORT HANDLING (D-21). The executor timer is disabled for this tool (`gov_dispatch: 0`),
+ * which is safe ONLY because the tool honours `ctx.signal`: (1) a signal that is already
+ * aborted returns the paused text at once, without touching the engine; (2) the signal is
+ * handed to the engine so the stage can stop; (3) if the engine rejects after an abort, that
+ * is a pause, not a tool failure. Any other rejection is a real defect and propagates.
+ */
+export declare function makeGovDispatchTool(engine: GovernanceEngineApi): AgentTool;