dsh-checklists 0.3.3 → 0.5.0

package/README.md

@@ -28,6 +28,7 @@ If the agent forgets to mark something, you say so in chat and it fixes it.
 | `checklist_edit` | Changes an item's text (not its state) |
 | `checklist_list` | Full tree with ids and states, for when the digest is truncated |
 | `checklist_delete` | Deletes a list (by id or exact title) |
+| `checklist_remove_item` | Removes one item and everything nested under it |
 | `checklist_rename` | Renames a list; titles stay unique within the session |
 | `checklist_template_save` | Saves a list as a reusable template for future sessions |
 
@@ -49,7 +50,7 @@ From a local build or tarball:
 npm install
 npm run build
 npm pack
-dsh plugin --profile dev add ./dsh-checklists-0.3.2.tgz
+dsh plugin --profile dev add ./dsh-checklists-0.4.0.tgz
 dsh --profile dev --dump-config        # the tool-checklist row should appear
 ```
 

package/lib/gate.js

@@ -0,0 +1,55 @@
+/**
+ * Turn-end gate: decides whether a turn is closing with the checklist stale.
+ *
+ * Kept pure on purpose — the host event wiring lives in `index.ts`, so the rule
+ * itself is testable without a running harness and can be reasoned about by
+ * reading one function.
+ *
+ * The gate never guesses *what* was completed. It only notices the shape of the
+ * problem: real work happened, the checklist was not touched, and something is
+ * still marked as in progress.
+ */
+/** Observation endpoint for the gate's last decisions. */
+export const NUDGE_ROUTE = '/dsh-checklist/nudge';
+/**
+ * Tools whose result can change the workspace. `run_code` is included because
+ * the PTC transport can reach any tool behind it.
+ */
+export const MUTATING_TOOLS = new Set([
+    'bash',
+    'pwsh',
+    'write',
+    'edit',
+    'str_replace_editor',
+    'apply_patch',
+    'run_code',
+]);
+/** Tools that already keep a checklist current. */
+const CHECKLIST_WRITES = new Set([
+    'checklist_create',
+    'checklist_add',
+    'checklist_check',
+    'checklist_edit',
+    'checklist_remove_item',
+    'checklist_delete',
+    'checklist_rename',
+]);
+export function isChecklistWrite(name) {
+    return CHECKLIST_WRITES.has(name);
+}
+/**
+ * Decide whether the closing turn should be challenged.
+ *
+ * @param activity - what the turn did.
+ * @param doingCount - items currently in `doing` across the session.
+ * @returns the decision and a short human-readable reason, logged either way.
+ */
+export function decideNudge(activity, doingCount) {
+    if (!activity.mutated)
+        return { nudge: false, reason: 'no mutating tool calls' };
+    if (activity.checklistWrite)
+        return { nudge: false, reason: 'checklist already updated' };
+    if (doingCount === 0)
+        return { nudge: false, reason: 'nothing in progress' };
+    return { nudge: true, reason: `${doingCount} item(s) still doing after workspace changes` };
+}

package/lib/index.js

@@ -11,6 +11,8 @@
  * document is the single source of truth.
  */
 import { renderDigest } from './digest.js';
+import { decideNudge, isChecklistWrite, MUTATING_TOOLS, NUDGE_ROUTE } from './gate.js';
+import { countState } from './model.js';
 import { serveProbe, PROBE_ROUTE } from './probe.js';
 import { serveItemUpdate, serveState, ITEM_ROUTE, STATE_ROUTE } from './route.js';
 import { ChecklistStore } from './store.js';
@@ -44,6 +46,52 @@ export function apply(ctx, config = {}) {
     if (config.pruneDays !== 0) {
         void store.prune(config.pruneDays ?? 14).catch(() => undefined);
     }
+    // --- Turn-end gate (observation mode) ------------------------------------
+    // Watches one turn's tool activity and decides, as the turn closes, whether
+    // the checklist was left stale. This release only records the decision — the
+    // event is not exercised yet — so enabling `steer` is a one-line follow-up
+    // once the log shows it fires when it should.
+    const activity = new Map();
+    const gateLog = [];
+    const events = ctx;
+    ctx.effect(() => events.on('tools/result', (payload) => {
+        const event = payload;
+        const toolName = event.exec?.name;
+        const agentId = event.exec?.agent?.id;
+        if (typeof toolName !== 'string' || typeof agentId !== 'string')
+            return;
+        const current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
+        if (MUTATING_TOOLS.has(toolName))
+            current.mutated = true;
+        if (isChecklistWrite(toolName))
+            current.checklistWrite = true;
+        activity.set(agentId, current);
+    }));
+    ctx.effect(() => events.on('agent/turn-stopping', (payload) => {
+        const event = payload;
+        const agentId = event.agent?.id;
+        if (typeof agentId !== 'string')
+            return;
+        const current = activity.get(agentId) ?? { mutated: false, checklistWrite: false };
+        activity.set(agentId, { mutated: false, checklistWrite: false });
+        const doc = store.peek(agentId);
+        let doing = 0;
+        if (doc)
+            for (const list of doc.lists)
+                doing += countState(list.items, 'doing');
+        const decision = decideNudge(current, doing);
+        if (!decision.nudge && process.env.DSH_CHECKLIST_DEBUG !== '1')
+            return;
+        gateLog.push({
+            at: new Date().toISOString(),
+            sessionId: agentId,
+            nudge: decision.nudge,
+            reason: decision.reason,
+            doing,
+        });
+        if (gateLog.length > 20)
+            gateLog.shift();
+    }));
     let loggedScope = false;
     ctx.inject(['systemPrompt'], (promptCtx) => {
         promptCtx.systemPrompt.context({
@@ -93,5 +141,19 @@ export function apply(ctx, config = {}) {
                 serveProbe(req, res);
             },
         }), 'dsh-checklist: client probe route');
+        // What the turn-end gate decided, for verification before it steers.
+        webCtx.effect(() => webCtx.webServer.register({
+            kind: 'exact',
+            path: NUDGE_ROUTE,
+            handler: (req, res) => {
+                const body = Buffer.from(`${JSON.stringify({ mode: 'observe', entries: gateLog }, null, 2)}\n`, 'utf8');
+                res.writeHead(200, {
+                    'content-type': 'application/json; charset=utf-8',
+                    'content-length': String(body.byteLength),
+                    'cache-control': 'no-store',
+                });
+                res.end(body);
+            },
+        }), 'dsh-checklist: nudge log route');
     });
 }

package/lib/model.js

@@ -9,12 +9,25 @@ export const ITEM_STATES = ['todo', 'doing', 'done', 'blocked'];
 export function emptyDoc(sessionId) {
     return { version: 1, sessionId, lists: [] };
 }
-/** Mint the next `<prefix>N` identifier that is not already in `used`. */
+/**
+ * Mint the next `<prefix>N` identifier.
+ *
+ * Numbers start after the highest one already in `used`, so a removed item's id
+ * is not handed to the next arrival: a freed `i3` stays dead instead of
+ * silently aliasing a different item. The high-water mark is not persisted, so
+ * removing the newest item and adding another can still reuse that id — fully
+ * closing the hole needs a stored counter, which means a schema change.
+ */
 export function mintId(prefix, used) {
-    let n = 1;
-    while (used.has(`${prefix}${n}`))
-        n += 1;
-    return `${prefix}${n}`;
+    let highest = 0;
+    for (const id of used) {
+        if (!id.startsWith(prefix))
+            continue;
+        const suffix = Number(id.slice(prefix.length));
+        if (Number.isInteger(suffix) && suffix > highest)
+            highest = suffix;
+    }
+    return `${prefix}${highest + 1}`;
 }
 /**
  * Build an item tree from plain lines.
@@ -80,6 +93,16 @@ export function countItems(items) {
     }
     return { total, done };
 }
+/** Count items in one state across a tree. */
+export function countState(items, state) {
+    let total = 0;
+    for (const item of items) {
+        if (item.state === state)
+            total += 1;
+        total += countState(item.children, state);
+    }
+    return total;
+}
 /**
  * Resolve one model-supplied reference against the session's checklists.
  *
@@ -89,14 +112,17 @@ export function countItems(items) {
  *
  * @param lists - the session's checklists.
  * @param ref - a model-supplied item id, text, or prefix.
- * @param listId - optional checklist id to search within.
+ * @param listId - optional checklist id **or exact title** to search within.
  * @returns the hit, the ambiguity, or a miss.
  */
 export function resolveRef(lists, ref, listId) {
     const needles = ref.trim().toLowerCase();
     if (needles.length === 0)
         return { kind: 'miss' };
-    const scoped = listId ? lists.filter((list) => list.id === listId) : lists;
+    // Accept a title here as well as an id: every other tool does, and a model
+    // that just created "Release 2.3" will pass that back, not "l1".
+    const scope = listId ? findList(lists, listId) : undefined;
+    const scoped = listId ? (scope ? [scope] : []) : lists;
     const entries = [];
     for (const list of scoped) {
         for (const { item } of flatten(list.items))
@@ -147,6 +173,27 @@ export function findItemById(lists, id) {
     }
     return undefined;
 }
+/**
+ * Remove one item (and its whole subtree) by exact id.
+ *
+ * Mutates the array in place, so callers must pass a document they own — the
+ * store's `update` already hands out a clone.
+ *
+ * @param items - sibling list to search, at any depth.
+ * @param id - exact item id.
+ * @returns the removed node, or `undefined` when no item has that id.
+ */
+export function removeItemById(items, id) {
+    const index = items.findIndex((entry) => entry.id === id);
+    if (index >= 0)
+        return items.splice(index, 1)[0];
+    for (const item of items) {
+        const removed = removeItemById(item.children, id);
+        if (removed)
+            return removed;
+    }
+    return undefined;
+}
 /**
  * Validate a checklist rename before applying it.
  *

package/lib/tools.js

@@ -5,7 +5,7 @@
  * the single source of truth and the sidebar (phase 2) is a read-only mirror.
  */
 import { defineTool } from '@deepseek-ai/dsh-tools';
-import { buildItems, checkRename, countItems, findList, flatten, ITEM_STATES, isItemState, mintId, nextItem, resolveRef, toLines, } from './model.js';
+import { buildItems, checkRename, countItems, findList, flatten, ITEM_STATES, isItemState, mintId, nextItem, removeItemById, resolveRef, toLines, } from './model.js';
 /** Ships with the plugin so a first run has something to instantiate. */
 const DEFAULT_TEMPLATES = {
     release: [
@@ -542,6 +542,78 @@ export function registerChecklistTools(ctx, store, config = {}) {
             });
         },
     })));
+    ctx.effect(() => ctx.tools.register(defineTool({
+        name: 'checklist_remove_item',
+        description: 'Remove one item — and everything nested under it — from a checklist in the CURRENT session. '
+            + 'Match it by id or exact text. Use it to drop work that no longer applies; '
+            + 'to change the item instead, use checklist_edit.',
+        parameters: {
+            listId: {
+                type: 'string',
+                required: true,
+                description: 'Checklist id, or its exact title.',
+            },
+            item: {
+                type: 'string',
+                required: true,
+                description: 'Item id or exact item text.',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    listId: { type: 'string', required: true },
+                    itemId: { type: 'string', required: true },
+                    text: { type: 'string', required: true },
+                    removed: { type: 'integer', required: true },
+                },
+            },
+            render: (_args, value) => {
+                const result = value;
+                const extra = result.removed > 1 ? ` (+${result.removed - 1} nested)` : '';
+                return [{ type: 'text', text: `Removed "${result.text}"${extra}.` }];
+            },
+        },
+        timeoutMs: 10_000,
+        async execute(args, exec) {
+            const input = args;
+            const sessionId = sessionOf(exec);
+            const listRef = text(input.listId).trim();
+            const itemRef = text(input.item).trim();
+            if (listRef.length === 0)
+                throw new Error('checklist_remove_item: listId must not be empty');
+            if (itemRef.length === 0)
+                throw new Error('checklist_remove_item: item must not be empty');
+            return store.update(sessionId, (doc) => {
+                const list = findList(doc.lists, listRef);
+                if (!list) {
+                    const available = doc.lists.map((entry) => `${entry.id} (${entry.title})`).join(', ');
+                    throw new Error(`checklist_remove_item: no checklist "${listRef}" in this session. `
+                        + `Available: ${available.length > 0 ? available : 'none'}`);
+                }
+                const found = resolveRef([list], itemRef);
+                if (found.kind === 'ambiguous') {
+                    const options = found.candidates.map((entry) => `${entry.item.id} (${entry.item.text})`).join(', ');
+                    throw new Error(`checklist_remove_item: "${itemRef}" is ambiguous; use an id: ${options}`);
+                }
+                if (found.kind === 'miss') {
+                    throw new Error(`checklist_remove_item: no item "${itemRef}" in "${list.title}". Call checklist_list for ids.`);
+                }
+                const removed = removeItemById(list.items, found.hit.item.id);
+                if (!removed) {
+                    throw new Error(`checklist_remove_item: item "${itemRef}" disappeared from "${list.title}"`);
+                }
+                return {
+                    listId: list.id,
+                    itemId: removed.id,
+                    text: removed.text,
+                    removed: countItems([removed]).total,
+                };
+            });
+        },
+    })));
     ctx.effect(() => ctx.tools.register(defineTool({
         name: 'checklist_delete',
         description: 'Delete one checklist from the CURRENT session. The list and its items are gone; there is no archive. '

package/lib/types/gate.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Turn-end gate: decides whether a turn is closing with the checklist stale.
+ *
+ * Kept pure on purpose — the host event wiring lives in `index.ts`, so the rule
+ * itself is testable without a running harness and can be reasoned about by
+ * reading one function.
+ *
+ * The gate never guesses *what* was completed. It only notices the shape of the
+ * problem: real work happened, the checklist was not touched, and something is
+ * still marked as in progress.
+ */
+export interface TurnActivity {
+    /** The turn ran a tool that can change the workspace. */
+    mutated: boolean;
+    /** The turn already wrote to a checklist. */
+    checklistWrite: boolean;
+}
+/** Observation endpoint for the gate's last decisions. */
+export declare const NUDGE_ROUTE = "/dsh-checklist/nudge";
+export interface NudgeDecision {
+    nudge: boolean;
+    reason: string;
+}
+/**
+ * Tools whose result can change the workspace. `run_code` is included because
+ * the PTC transport can reach any tool behind it.
+ */
+export declare const MUTATING_TOOLS: ReadonlySet<string>;
+export declare function isChecklistWrite(name: string): boolean;
+/**
+ * Decide whether the closing turn should be challenged.
+ *
+ * @param activity - what the turn did.
+ * @param doingCount - items currently in `doing` across the session.
+ * @returns the decision and a short human-readable reason, logged either way.
+ */
+export declare function decideNudge(activity: TurnActivity, doingCount: number): NudgeDecision;

package/lib/types/model.d.ts

@@ -25,7 +25,15 @@ export interface SessionDoc {
     lists: Checklist[];
 }
 export declare function emptyDoc(sessionId: string): SessionDoc;
-/** Mint the next `<prefix>N` identifier that is not already in `used`. */
+/**
+ * Mint the next `<prefix>N` identifier.
+ *
+ * Numbers start after the highest one already in `used`, so a removed item's id
+ * is not handed to the next arrival: a freed `i3` stays dead instead of
+ * silently aliasing a different item. The high-water mark is not persisted, so
+ * removing the newest item and adding another can still reuse that id — fully
+ * closing the hole needs a stored counter, which means a schema change.
+ */
 export declare function mintId(prefix: string, used: ReadonlySet<string>): string;
 /**
  * Build an item tree from plain lines.
@@ -53,6 +61,8 @@ export interface ItemCounts {
     done: number;
 }
 export declare function countItems(items: readonly ChecklistItem[]): ItemCounts;
+/** Count items in one state across a tree. */
+export declare function countState(items: readonly ChecklistItem[], state: ItemState): number;
 export interface RefHit {
     list: Checklist;
     item: ChecklistItem;
@@ -75,7 +85,7 @@ export type RefResult = {
  *
  * @param lists - the session's checklists.
  * @param ref - a model-supplied item id, text, or prefix.
- * @param listId - optional checklist id to search within.
+ * @param listId - optional checklist id **or exact title** to search within.
  * @returns the hit, the ambiguity, or a miss.
  */
 export declare function resolveRef(lists: readonly Checklist[], ref: string, listId?: string): RefResult;
@@ -97,6 +107,17 @@ export declare function findItemById(lists: readonly Checklist[], id: string): {
     list: Checklist;
     item: ChecklistItem;
 } | undefined;
+/**
+ * Remove one item (and its whole subtree) by exact id.
+ *
+ * Mutates the array in place, so callers must pass a document they own — the
+ * store's `update` already hands out a clone.
+ *
+ * @param items - sibling list to search, at any depth.
+ * @param id - exact item id.
+ * @returns the removed node, or `undefined` when no item has that id.
+ */
+export declare function removeItemById(items: ChecklistItem[], id: string): ChecklistItem | undefined;
 export type RenameCheck = {
     kind: 'ok';
     list: Checklist;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-checklists",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Session-scoped checklists for DeepSeek Harness: the agent tracks work as a tree, the model always sees a compact digest, and a read-only sidebar tab mirrors it.",
   "type": "module",
   "main": "lib/index.js",