@aragon-agent/cli 0.6.35 → 0.6.36

package/dist/todo/store.d.ts

@@ -1,6 +1,6 @@
 /**
- * `TodoStore` — the session's todo list plus its CLI-local event stream
- * (todo-plan-execution §3.5).
+ * `TodoStore` — the session's todo list, its acceptance table, and its CLI-local
+ * event stream (todo-plan-execution §3.5; todo-acceptance-criteria §6.2.3).
  *
  * ASCII ONLY: `src/todo/**` is inside the glyph scanner's scope.
  *
@@ -9,54 +9,105 @@
  * is why `AgentController` can own this object as unconditionally as it owns
  * `TeamRuntime`.
  *
- * The list projects the current plan. Explicit clear/reset and a new TUI task
- * may remove that projection while the model still remembers the old plan.
- * Continuations preserve it; legacy callers retain completion/staleness rules.
+ * TWO TABLES, ONE WRITER, ONE COMMIT. `items` and `acceptance` are the plan's two
+ * halves: they are replaced together, cleared together, and refused together
+ * (I-4). Nothing here is a partial update, which is what makes I-9 ("the panel is
+ * never a contradiction of the model") provable rather than argued.
  *
- * Every write is a FULL REPLACEMENT and every clear is a FULL REMOVAL - there is
- * no partial update anywhere, which is what makes I-9 ("the panel is never a
- * contradiction of the model") provable rather than argued.
+ * `snapshot()` IS NOT A COMPUTATION. Every projection is rebuilt at the commit
+ * points (`write` / `restore` / `clear` / `reopenAll`, plus
+ * `refreshAcceptanceProjection` when `todo.acceptance` is flipped) and merely READ
+ * here, because `App` calls `snapshot()` on every event: re-deriving and
+ * re-stamping on read would give the reducer a new object every frame, invalidate
+ * `TodoCard`'s `React.memo` and the transcript's height cache, and undo the redraw
+ * savings `mapEntry` buys with object identity (P1-3).
  */
-import { type NormalizeResult } from './normalize.js';
-import type { TodoClearReason, TodoEventListener, TodoSnapshot } from './types.js';
+import type { AcceptanceItem, TodoClearReason, TodoEventListener, TodoItem, TodoSnapshot } from './types.js';
+/**
+ * What a `write()` decided.
+ *
+ * `accepted === false` means the WHOLE payload was refused and both tables are the
+ * current, unmodified projections. `refusalKind` decides which `ToolResult` the
+ * tool side builds: a `'payload'` refusal is a broken payload (the existing
+ * `errorResult`, kept byte for byte), while a `'policy'` refusal is an incomplete
+ * plan (a `textResult` - the tool is not broken, so an error result would invite
+ * the model to retry the identical payload).
+ */
+export interface TodoWriteResult {
+    accepted: boolean;
+    items: TodoItem[];
+    acceptance: AcceptanceItem[];
+    repairs: string[];
+    /** Non-empty when `accepted === false`: the final, model-readable refusal text. */
+    refusal?: string;
+    refusalKind?: 'payload' | 'policy';
+}
+/** The one model-readable refusal that is about the PLAN, not about the payload. */
+export declare const FRESH_ACCEPTANCE_REFUSAL: string;
 export declare class TodoStore {
     private readonly now;
+    private readonly acceptanceEnabled;
     private items;
+    private acceptance;
     private updatedAt;
     /** Consecutive `beginUserTurn()` calls since the last `write()`. */
     private turnsSinceWrite;
+    /**
+     * The acceptance projection. REBUILT AT COMMIT TIME ONLY — see the file header.
+     * `null` when there are no criteria, which is also what keeps the rail's second
+     * section, the card's second block and the status chip unrendered.
+     */
+    private acceptanceSnapshot;
+    /**
+     * Criteria whose verdict has already been reported as restored. Without it the
+     * model would receive the SAME `Note:` on every turn, because it cannot know the
+     * server restored anything and keeps re-sending the row as `pending` (P2-4).
+     * Cleared by `clear()` / `restore()`; a criterion's key is removed when the criterion
+     * itself leaves the table (not when it stops being `pending`, which would delete the
+     * key in the same commit that added it - see `pruneRestoredNotes`).
+     */
+    private readonly restoredNotes;
     private readonly listeners;
     /**
      * @param now Injected clock. Defaults to `Date.now`; a test passes a counter
      *            so `TodoSnapshot.updatedAt` is not wall time (P2-4).
+     * @param acceptanceEnabled Live read of `todo.acceptance` (D-11). Read, never
+     *            snapshotted: `/todo acceptance off` must take effect mid-session,
+     *            because the tool array cannot change (C-1).
      */
-    constructor(now?: () => number);
+    constructor(now?: () => number, acceptanceEnabled?: () => boolean);
     /** `null` means no list, which is what leaves the rail unmounted entirely. */
     snapshot(): TodoSnapshot | null;
+    /** The acceptance table itself, for the transcript entry and the session file. */
+    acceptanceItems(): AcceptanceItem[];
     isEmpty(): boolean;
     /**
      * Commit a model payload.
      *
-     * ZERO SURVIVORS LEAVES THE PREVIOUS LIST UNTOUCHED (AC-9). A model sending
-     * nothing usable is a BUG, and destroying a working plan because of one
-     * malformed call is the worst available reaction; the caller turns the empty
-     * result into an error the model can act on. Contrast `restore()`, where an
-     * empty list is a FACT about a file and therefore means "clear".
+     * ZERO SURVIVORS LEAVES THE PREVIOUS PLAN UNTOUCHED (AC-9 / I-4), and so does an
+     * incomplete fresh plan: a model sending nothing usable is a BUG, and destroying
+     * a working plan because of one malformed call is the worst available reaction.
+     * The caller turns the refusal into something the model can act on. Contrast
+     * `restore()`, where an empty list is a FACT about a file and therefore means
+     * "clear".
      */
-    write(raw: unknown): NormalizeResult;
+    write(raw: unknown): TodoWriteResult;
     /**
-     * `/resume`. Runs through `normalizeTodos` — a session file is user-editable
+     * `/resume`. Runs through both normalizers — a session file is user-editable
      * input and gets a model payload's treatment.
      *
-     * AN EMPTY (OR ALL-DROPPED) ARRAY CLEARS; IT DOES NOT NO-OP (P0-2 / D-22).
+     * AN EMPTY (OR ALL-DROPPED) TODO ARRAY CLEARS; IT DOES NOT NO-OP (P0-2 / D-22).
      * `/resume` has just called `replaceMessages`, so the conversation the current
-     * list belonged to is gone; leaving it on screen is I-2 INVERTED — a panel
-     * that disagrees with the model, which §1.2 ranks below having no panel at
-     * all. The two entry points share normalization and differ only here, which is
-     * exactly the difference between "the model sent nothing" (a bug) and "the
-     * file has nothing" (a fact).
+     * plan belonged to is gone; leaving it on screen is I-2 INVERTED — a panel that
+     * disagrees with the model, which §1.2 ranks below having no panel at all. The
+     * acceptance table goes with it: no plan, no criteria.
+     *
+     * `enabled: true` is passed to the normalizer on purpose: the file is a fact
+     * about what this plan contained, and the current switch only governs RENDERING
+     * and PROMPTING. A user who turns the capability off and back on must not find
+     * that a resume quietly deleted the stored verdicts.
      */
-    restore(items: unknown): void;
+    restore(items: unknown, acceptance?: unknown): void;
     clear(reason: TodoClearReason): void;
     /**
      * The turn boundary (§3.2).
@@ -64,15 +115,29 @@ export declare class TodoStore {
      * Called from `AgentController.prompt()` and NOT from `steer()` — the same
      * asymmetry, for the same reason, that `askRounds = 0` already has: a steer is
      * a mid-turn interjection, not a new task. The stale counter inherits that
-     * asymmetry for free, which is the behaviour you want: a steer must not age
-     * out the plan it is steering.
+     * asymmetry for free, which is the behaviour you want: a steer must not age out
+     * the plan it is steering.
      *
-     * A new TUI task drops the old plan here, while a continuation preserves it.
-     * With no policy, legacy callers retain completed/stale-plan expiration.
-     * Clearing at `agent_end` would erase the final progress before the user can
-     * inspect it and remove the plan that automatic continuation still needs.
+     * "EVERY STEP IS COMPLETED" NO LONGER MEANS "THERE IS NOTHING LEFT" (G-4):
+     * the rule is `planIsResolved`, which also asks whether every criterion has a
+     * verdict. A plan that is done but unverified is not idle work, it is one step
+     * short - so it ages by `staleTurns` instead of vanishing the moment the model
+     * ticks its last step.
      */
     beginUserTurn(policy?: 'new-task' | 'continue'): void;
+    /**
+     * Send every verdict back to `pending` and clear the evidence (§6.2.3).
+     *
+     * THE NAMED WRITER `/todo acceptance reset` NEEDS, so the command layer never
+     * walks the table itself. It is not a second writer of the plan: `items` stays
+     * exactly as it is, no `cleared` event is emitted (`TodoClearReason` therefore
+     * does not change), and only the verdict fields move - the same rule as
+     * `reopen: true`, entered from the user's side instead of the model's (AC-6).
+     *
+     * IDEMPOTENT: with nothing to re-open it returns 0 and emits NOTHING, so an
+     * empty command cannot make the transcript card blink for no reason.
+     */
+    reopenAll(): number;
     /**
      * Report a refusal that never reached `write()` (§3.3 steps 1 and 2).
      *
@@ -82,6 +147,49 @@ export declare class TodoStore {
      */
     reject(reason: string): void;
     subscribe(listener: TodoEventListener): () => void;
+    /** A refusal that changed nothing, expressed as a result the tool can branch on. */
+    private refusal;
+    /** Both tables, both projections, one timestamp, one event. */
+    private commit;
+    /**
+     * THE ONLY PRODUCER OF `in_progress` (P0-1 / AC-43).
+     *
+     * Normalization only ever DOWNGRADES that state; rendering and phase derivation
+     * only READ it. One state, one writer - otherwise the rail's anchor and the
+     * derived phase would each pick a different "criterion being checked".
+     *
+     * Forward only: criteria are promoted once EVERY step is completed, because a
+     * criterion cannot be under inspection while its steps are still running.
+     */
+    private deriveInProgress;
+    /**
+     * Re-project the acceptance table after `todo.acceptance` was flipped mid-session.
+     *
+     * THE SWITCH GOVERNS RENDERING, and the rail, the card and the status chip all read
+     * `snapshot().acceptance` rather than the flag - so without this, `/todo acceptance
+     * off` on a plan that already had criteria would leave the second section on screen
+     * until the model's next write, which is exactly the complaint P0-2 raised one path
+     * further out. The DATA is kept either way: turning the capability back on restores
+     * the same verdicts without a round trip through the model.
+     *
+     * Emits only when the projection's VISIBILITY actually changed, so a no-op flip can
+     * never make the transcript card blink.
+     */
+    refreshAcceptanceProjection(): boolean;
+    /** Rebuild the acceptance projection. The ONLY place `acceptanceSummary` runs. */
+    private commitAcceptance;
+    /**
+     * Forget a restoration note once its criterion has LEFT the table.
+     *
+     * `filtered on pending` would be the wrong rule and was the first version of this:
+     * the criterion that `noteOnce` just announced is restored WITH ITS VERDICT
+     * (`passed` / `failed`), so a pending filter deletes the key in the same commit that
+     * added it, the model re-sends the row as `pending` on the next turn, and the note is
+     * re-printed every turn for the life of the plan - the unbounded billing P2-4 exists
+     * to prevent. Keeping the key until the criterion is gone is also free: the set can
+     * never hold more than `ACCEPT_LIMITS.maxItems` entries.
+     */
+    private pruneRestoredNotes;
     /** Per-listener isolation: one bad subscriber cannot fail a tool call. */
     private emit;
 }