@aragon-agent/cli 0.6.34 → 0.6.36

package/dist/todo/todo-tool.js

@@ -1,19 +1,22 @@
 /**
- * `todo_write` — the ONLY writer of `TodoStore` (todo-plan-execution §3.3 /
- * §4.1).
+ * `todo_write` — the ONLY writer of `TodoStore` (todo-plan-execution §3.3 / §4.1;
+ * todo-acceptance-criteria §6.4).
  *
  * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
  *
  * FULL-LIST REPLACEMENT, NO INCREMENTAL OPERATIONS (D-1). A delta protocol
  * (`todo_add` / `todo_complete`) lets the model's belief and the rendered panel
- * drift apart with nothing anywhere able to notice, and needs an id the model
- * must keep stable across calls - a field it will eventually get wrong. A full
- * replacement is idempotent, order-free and self-healing.
+ * drift apart with nothing anywhere able to notice, and needs an id the model must
+ * keep stable across calls - a field it will eventually get wrong. A full
+ * replacement is idempotent, order-free and self-healing. The acceptance table
+ * rides in the SAME call for exactly that reason: a second tool would be a second
+ * writer, with two refusal texts and a model free to update only half its plan.
  *
  * THE SCHEMA DECLARES SHAPE, NOT POLICY (C-8): no `enum`, no `maxItems`, no
- * `minItems`, and `activeForm` is not `required`. `ajv` is an OPTIONAL
- * dependency of core, so any of those would reject a payload where it happens to
- * be installed and repair the identical payload where it is not.
+ * `minItems`, and `acceptance` is not `required`. `ajv` is an OPTIONAL dependency
+ * of core, so any of those would reject a payload where it happens to be installed
+ * and repair the identical payload where it is not. Every bound lives in the
+ * `description` (what the model reads) and in `write()` (what is tested).
  *
  * PURE STATE: no filesystem, no network, no child process, no human wait. It
  * therefore must NOT be routed through `withPausedWatchdog` (C-9) -
@@ -22,7 +25,8 @@
  * human wait.
  */
 import { errorResult, textResult } from '@aragon-agent/core';
-import { TODO_LIMITS } from './limits.js';
+import { acceptanceSummary, countUncheckedCriteria, countUnfinishedSteps, derivePlanPhase, planOutstanding, } from './acceptance.js';
+import { ACCEPT_LIMITS, TODO_LIMITS, TODO_RESULT_LIMITS } from './limits.js';
 /**
  * Turned off mid-session. A NON-ERROR result on purpose: the user turned a
  * display off, the model did nothing wrong, and an error result invites a retry.
@@ -42,11 +46,58 @@ const TODO_WRITE_DESCRIPTION = 'Record and update the plan for a multi-step task
     '`in_progress`; mark an item `completed` and the next one `in_progress` in the same call, ' +
     `the moment the step is done. At most ${TODO_LIMITS.maxItems} items; extras are dropped, so ` +
     'keep within it. This list is how the user follows a long task, so keep it current.';
+/**
+ * Appended only while the capability is on, so `todo.acceptance: false` leaves the
+ * whole parameters object byte-identical to the version without this feature
+ * (AC-29 / I-5).
+ */
+const ACCEPTANCE_DESCRIPTION = ' A plan also carries acceptance criteria: how you will know each part is really done. ' +
+    'Send them in the same call. When every step is completed, check the criteria ONE at a ' +
+    'time, actually run the check you named, and record each verdict with its evidence. A ' +
+    'verdict without evidence is not a verdict. Report failures honestly: fix the work, ' +
+    'reopen the criterion, check it again.';
+/** The `acceptance` JSON Schema property (§6.4.1). Shape only - no enum, no bounds. */
+const ACCEPTANCE_PARAMETER = {
+    type: 'array',
+    description: 'How you will KNOW the work is done: one checkable criterion per line. Send the ' +
+        'complete list every time, same as todos.',
+    items: {
+        type: 'object',
+        properties: {
+            content: {
+                type: 'string',
+                description: `One checkable statement, <= ${ACCEPT_LIMITS.contentChars} chars. Not a wish: ` +
+                    'something you can point at and say yes or no.',
+            },
+            check: {
+                type: 'string',
+                description: `How you will check it, <= ${ACCEPT_LIMITS.checkChars} chars. ` +
+                    "e.g. 'npm test -- runs green'.",
+            },
+            status: {
+                type: 'string',
+                description: 'pending | passed | failed. Only after you actually checked it.',
+            },
+            evidence: {
+                type: 'string',
+                description: `What you saw, <= ${ACCEPT_LIMITS.evidenceChars} chars. Required for passed or ` +
+                    'failed; a verdict without evidence does not count.',
+            },
+            reopen: {
+                type: 'boolean',
+                description: 'true only to undo an earlier verdict and check the same criterion again.',
+            },
+        },
+        required: ['content'],
+    },
+};
 export function createTodoTool(deps) {
     return {
         name: 'todo_write',
         label: 'Update todos',
-        description: TODO_WRITE_DESCRIPTION,
+        description: deps.hasAcceptance()
+            ? TODO_WRITE_DESCRIPTION + ACCEPTANCE_DESCRIPTION
+            : TODO_WRITE_DESCRIPTION,
         parameters: {
             type: 'object',
             properties: {
@@ -75,49 +126,71 @@ export function createTodoTool(deps) {
                         required: ['content', 'status'],
                     },
                 },
+                // ABSENT ENTIRELY WHILE THE CAPABILITY IS OFF, so the model is not told
+                // about a field that would be ignored (I-5 / AC-29).
+                ...(deps.hasAcceptance() ? { acceptance: ACCEPTANCE_PARAMETER } : {}),
             },
+            // `acceptance` IS NOT REQUIRED, and cannot be: `ajv` is optional in core, so
+            // a schema-level requirement would be enforced in some installs and not in
+            // others (C-8). The gate lives in `write()` (AC-11).
             required: ['todos'],
         },
         async execute(_id, params) {
-            // 1. Turned off mid-session. The tool array is immutable for the life of
-            //    the session (C-1), so `/todo off` cannot unregister - it flips this
-            //    closure instead.
+            // 1. Turned off mid-session. The tool array is immutable for the life of the
+            //    session (C-1), so `/todo off` cannot unregister - it flips this closure.
             if (!deps.isEnabled()) {
                 deps.store.reject(TODO_OFF_REFUSAL);
                 return textResult(TODO_OFF_REFUSAL);
             }
-            const todos = params.todos;
-            // 2. GATED ON AN EMPTY STORE, and that gate is the whole subtlety.
-            //    Shrinking an EXISTING list to one item is legitimate - the model
-            //    merged two steps - so the guard must fire only on a fresh plan.
+            const payload = params;
+            const todos = payload.todos;
+            // 2. GATED ON AN EMPTY STORE, and that gate is the whole subtlety. Shrinking
+            //    an EXISTING list to one item is legitimate - the model merged two steps
+            //    - so the guard must fire only on a fresh plan.
             if (deps.store.isEmpty() &&
                 Array.isArray(todos) &&
                 todos.length < TODO_LIMITS.minFreshItems) {
                 deps.store.reject(TOO_SMALL_REFUSAL);
                 return textResult(TOO_SMALL_REFUSAL);
             }
-            // 3. Repair, never reject. Zero survivors is the single hard failure, and
-            //    it leaves the previous list untouched (AC-9).
-            const result = deps.store.write(todos);
-            if (result.items.length === 0) {
-                return errorResult('No usable todo items: each needs a non-empty content string.');
+            // 3. Repair, never reject. A refusal leaves BOTH tables untouched (I-4), and
+            //    the kind decides the result shape: a broken payload is an error (today's
+            //    behaviour, unchanged), an incomplete plan is not - an error would invite
+            //    the model to retry the identical payload.
+            const result = deps.store.write(params);
+            if (!result.accepted) {
+                const refusal = result.refusal
+                    ?? 'No usable todo items: each needs a non-empty content string.';
+                return result.refusalKind === 'policy' ? textResult(refusal) : errorResult(refusal);
             }
-            return textResult(buildResultText(result.items, result.repairs));
+            return textResult(buildResultText(result.items, result.acceptance, result.repairs, deps.hasAcceptance()));
         },
     };
 }
 /**
  * The tool result — THE SINGLE STRONGEST LEVER ON R-b ("one at a time"), because
  * unlike the system prompt it is re-read on every single call. There is
- * deliberately NO RATE LIMIT to compete with it: a cap would fire exactly when
- * the model is being most diligent and produce a refusal it cannot act on, and
- * the costs a cap would have contained are already gone (§3.8 collapses N calls
- * into ONE transcript entry, and the store is memory-only).
+ * deliberately NO RATE LIMIT to compete with it: a cap would fire exactly when the
+ * model is being most diligent and produce a refusal it cannot act on, and the
+ * costs a cap would have contained are already gone (§3.8 collapses N calls into
+ * ONE transcript entry, and the store is memory-only).
+ *
+ * FOUR PHASES, and the acceptance paragraph is inserted after the "In progress /
+ * Every item" paragraph and before any `Note:`. In `verify` and in the two `done`
+ * cases it also REPLACES that paragraph's closing sentence, because a plan that
+ * carries criteria has something more specific to say about being finished. With the
+ * capability off, or with no criteria, every branch below is byte-identical to the
+ * version without this feature (AC-28).
  */
-function buildResultText(items, repairs) {
+export function buildResultText(items, acceptance, repairs, acceptanceEnabled) {
     const done = items.filter((item) => item.status === 'completed').length;
     const activeIndex = items.findIndex((item) => item.status === 'in_progress');
+    const phase = derivePlanPhase(items, acceptance);
     const lines = [`Todos updated. ${done}/${items.length} done.`];
+    // Only while the capability is on AND there is a table: those are exactly the cases
+    // in which `acceptanceParagraph` speaks for the finished plan, and exactly the cases
+    // in which `I-5` does not demand the pre-feature bytes.
+    const showsCriteria = acceptanceEnabled && acceptance.length > 0;
     if (activeIndex >= 0) {
         lines.push(`In progress: ${items[activeIndex].activeForm}`);
         const next = items.slice(activeIndex + 1).find((item) => item.status === 'pending');
@@ -125,10 +198,93 @@ function buildResultText(items, repairs) {
             lines.push(`Next: ${next.content}`);
         lines.push('Call todo_write again the moment that item is finished - exactly one item in', 'progress at a time, and do not batch several completions into one call.');
     }
-    else {
+    else if (showsCriteria && phase === 'verify') {
+        // REPLACES the paragraph rather than joining it (P1-1). Saying "Every item is
+        // complete. Tell the user what you did." and then "Check ONE criterion now" in
+        // the same result would end the turn on the first sentence.
+        lines.push('Every step is complete. Now verify the acceptance criteria.');
+    }
+    else if (!(showsCriteria && phase === 'done')) {
         lines.push('Every item is complete. Tell the user what you did.');
     }
+    if (showsCriteria) {
+        // THE SAME REPLACEMENT RULE AS THE `verify` BRANCH ABOVE, for both `done` cases
+        // (§6.4.4). Leaving the generic line in front of the paragraph would print "Tell
+        // the user what you did" immediately before "Do not describe the work as done"
+        // when a criterion failed - the one sentence this feature exists to say, cancelled
+        // by the line above it.
+        lines.push(...acceptanceParagraph(items, acceptance, phase));
+    }
     for (const repair of repairs)
         lines.push(`Note: ${repair}`);
-    return lines.join('\n');
+    return boundText(lines);
+}
+/** The phase-specific acceptance paragraph (§6.4.4), verbatim. */
+function acceptanceParagraph(items, acceptance, phase) {
+    // `acceptanceSummary` with a DEAD clock, not a second copy of the counting: the
+    // paragraph and the rail must agree about `checked`/`failed`, and two loops over
+    // the same table is exactly how they stop agreeing.
+    const snapshotLike = acceptanceSummary(acceptance, () => 0);
+    const outstanding = {
+        steps: countUnfinishedSteps(items),
+        checks: countUncheckedCriteria(acceptance),
+    };
+    if (phase === 'work') {
+        return [
+            `Acceptance: ${snapshotLike.checkedCount}/${snapshotLike.total} checked. ` +
+                'Check them one at a time once every step is completed.',
+        ];
+    }
+    if (phase === 'done' && snapshotLike.failedCount === 0) {
+        return [
+            `Every step is complete and all ${snapshotLike.total} acceptance criteria passed. ` +
+                'Tell the user what you did',
+            'and how you checked it.',
+        ];
+    }
+    if (phase === 'done') {
+        return [
+            `Every step is complete but ${snapshotLike.failedCount} of ${snapshotLike.total} ` +
+                'acceptance criteria FAILED. Do not describe the work as',
+            'done: fix it, reopen the failed criterion (reopen: true), check it again - or tell the user',
+            'plainly what is still broken.',
+        ];
+    }
+    const lines = [
+        `Acceptance: ${snapshotLike.checkedCount}/${snapshotLike.total} checked`
+            + (snapshotLike.failedCount > 0 ? `, ${snapshotLike.failedCount} failed.` : '.'),
+    ];
+    const open = planOutstanding(items, acceptance, false);
+    if (open.length > 0)
+        lines.push('Unchecked:', ...open.map((row) => `  ${row}`));
+    if (outstanding.checks > open.length) {
+        const hidden = outstanding.checks - open.length;
+        lines.push(`  ... and ${hidden} more (send the complete list to see them all)`);
+    }
+    lines.push('Check ONE criterion now: actually run its check, then send the complete list with', 'that criterion passed or failed and the evidence you saw.');
+    return lines;
+}
+/**
+ * I-11's ceiling on the one text the model re-reads on every call.
+ *
+ * Truncation is by LINES, because a paragraph cut mid-sentence reads as a model
+ * error while a missing last line reads as brevity - and the note says which one
+ * happened.
+ */
+function boundText(lines) {
+    const text = lines.join('\n');
+    if (text.length <= TODO_RESULT_LIMITS.maxChars)
+        return text;
+    const kept = [];
+    let used = 0;
+    const budget = TODO_RESULT_LIMITS.maxChars - TODO_RESULT_LIMITS.truncationNote.length - 1;
+    for (const line of lines) {
+        const cost = line.length + (kept.length > 0 ? 1 : 0);
+        if (used + cost > budget)
+            break;
+        kept.push(line);
+        used += cost;
+    }
+    kept.push(TODO_RESULT_LIMITS.truncationNote);
+    return kept.join('\n');
 }

package/dist/todo/types.d.ts

@@ -24,6 +24,53 @@ export interface TodoItem {
     activeForm: string;
     status: TodoStatus;
 }
+/**
+ * The two settled states of a criterion, plus "not checked" and "being checked"
+ * (todo-acceptance-criteria §6.1). Mutually exclusive and exhaustive.
+ *
+ * `in_progress` IS A STORE-OWNED DERIVED STATE (v2, P0-1): the model cannot write
+ * it, the tool schema does not expose it, normalization always downgrades it to
+ * `pending`, and `TodoStore.write()` re-derives at most one after every commit.
+ * That is the same discipline `TodoItem`'s "exactly one in_progress" follows: one
+ * state has exactly one writer, otherwise the derived phase, the rail's anchor
+ * and the transcript card each read a different "criterion being checked".
+ */
+export type AcceptanceStatus = 'pending' | 'in_progress' | 'passed' | 'failed';
+export interface AcceptanceItem {
+    /** One checkable statement, sanitized, <= ACCEPT_LIMITS.contentChars. */
+    content: string;
+    /** How it will be checked (command / file / observation), <= checkChars. */
+    check: string;
+    status: AcceptanceStatus;
+    /** Required for `passed` / `failed`; otherwise the verdict drops to `pending`. */
+    evidence: string;
+    /**
+     * Explicit re-open. Only honoured when the same criterion's normalized
+     * `content` is unchanged (§6.2.1 step 9). INPUT ONLY: never stored, consumed
+     * and discarded by `write()`.
+     */
+    reopen?: boolean;
+}
+/** The immutable projection, isomorphic to `TodoSnapshot`. Rebuilt per commit. */
+export interface AcceptanceSnapshot {
+    items: AcceptanceItem[];
+    total: number;
+    /** `passed` + `failed`. */
+    checkedCount: number;
+    passedCount: number;
+    failedCount: number;
+    /** Injected clock, for the same reason `TodoSnapshot.updatedAt` has one (P2-4). */
+    updatedAt: number;
+}
+/**
+ * `work`   - at least one step is not completed.
+ * `verify` - every step is completed and at least one criterion is unresolved.
+ * `done`   - every step is completed and every criterion is settled (or there is
+ *            no acceptance table at all).
+ *
+ * DERIVED, NEVER STORED (I-3): `derivePlanPhase` is the only judge.
+ */
+export type PlanPhase = 'work' | 'verify' | 'done';
 /** The immutable projection the UI renders. Rebuilt on every write. */
 export interface TodoSnapshot {
     items: TodoItem[];
@@ -38,6 +85,17 @@ export interface TodoSnapshot {
      * that fails on a slow machine and nowhere else (P2-4).
      */
     updatedAt: number;
+    /**
+     * The acceptance projection; `null` when there are no criteria (or the
+     * capability is off).
+     *
+     * REQUIRED, NOT OPTIONAL (fail-closed, §6.1): `TodoStore` is the only writer and
+     * it always knows what belongs here. Optional would let one call site silently
+     * under-report an entire table. The cost is the 15 existing test fixtures that
+     * spell out a `TodoSnapshot` literal (§7.3) - a mechanical edit, done in the
+     * same step as this field.
+     */
+    acceptance: AcceptanceSnapshot | null;
 }
 /**
  * Why a list went away.