dsh-checklists 0.0.0-stage → 0.3.3

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh bundle patch: inserts this plugin into a profile's layer stack.
+# Install with:
+#   dsh plugin --profile dev add "C:/path/to/dsh-checklists"
+- insert:
+    - id: tool-checklist
+      name: dsh-checklists
+      # Optional overrides (uncomment and edit):
+      # config:
+      #   maxDigestLines: 12
+      #   pruneDays: 14

package/lib/digest.js

@@ -0,0 +1,76 @@
+/**
+ * The compact checklist view injected into the model context every turn.
+ *
+ * This is the piece that removes the "ask me for the checklist again" loop:
+ * the digest is re-evaluated per assembly, so the model always sees current
+ * progress without anyone restating it.
+ *
+ * The rendering is deliberately small and stable — pending items first, a
+ * per-list line budget, and a hard total cap. A checklist that eats the context
+ * window would be self-defeating.
+ */
+import { countItems, flatten } from './model.js';
+const GLYPH = {
+    done: '[x]',
+    doing: '[~]',
+    todo: '[ ]',
+    blocked: '[!]',
+};
+/** Absolute cap per checklist, whatever the shared budget allows. */
+const PER_LIST_CAP = 8;
+/** Deepest nesting the digest renders. */
+const MAX_DEPTH = 2;
+const DEFAULT_RULE = 'Mark each item with checklist_check as soon as you finish it.';
+/**
+ * Render the session's checklists as a compact prompt block.
+ *
+ * Each checklist gets an equal share of the line budget. Giving the first list
+ * the whole budget starved the rest: with two lists the second showed a single
+ * line, and a third never appeared at all.
+ *
+ * @param doc - the session document, or undefined when nothing is cached.
+ * @param options - line budget and rule text.
+ * @returns the digest, or `''` when the session has no checklists.
+ */
+export function renderDigest(doc, options = {}) {
+    if (!doc || doc.lists.length === 0)
+        return '';
+    const maxLines = Math.max(4, options.maxLines ?? 12);
+    const rule = options.rule ?? DEFAULT_RULE;
+    const body = [];
+    const listCount = Math.max(1, doc.lists.length);
+    // One title line per list, the rest split evenly. Never below 3 lines, or a
+    // list would render its title and nothing else.
+    const lineBudget = Math.max(3, Math.floor(maxLines / listCount));
+    for (const list of doc.lists) {
+        const { total, done } = countItems(list.items);
+        body.push(`${list.title} · ${done}/${total}`);
+        const all = flatten(list.items).filter((entry) => entry.depth <= MAX_DEPTH);
+        // Pending first: truncation must never hide unfinished work.
+        const ordered = [
+            ...all.filter((entry) => entry.item.state !== 'done'),
+            ...all.filter((entry) => entry.item.state === 'done'),
+        ];
+        const room = Math.max(1, Math.min(PER_LIST_CAP, lineBudget - 1));
+        if (ordered.length > room) {
+            // Reserve one of the slots for the elision notice, so every list costs
+            // exactly the same number of lines and the total cap still holds.
+            const keep = Math.max(0, room - 1);
+            for (const entry of ordered.slice(0, keep)) {
+                body.push(`  ${'  '.repeat(entry.depth)}${GLYPH[entry.item.state]} ${entry.item.text}`);
+            }
+            body.push(`  … ${ordered.length - keep} more (use checklist_list)`);
+        }
+        else {
+            for (const entry of ordered) {
+                body.push(`  ${'  '.repeat(entry.depth)}${GLYPH[entry.item.state]} ${entry.item.text}`);
+            }
+        }
+    }
+    if (body.length > maxLines) {
+        const hidden = body.length - maxLines;
+        body.length = maxLines;
+        body.push(`(+${hidden} more lines — checklist_list for the full tree)`);
+    }
+    return ['## Session checklist', ...body, rule].join('\n');
+}

package/lib/index.js

@@ -0,0 +1,97 @@
+/**
+ * dsh-checklist — session-scoped checklists for DeepSeek Harness.
+ *
+ * Two contributions:
+ *   1. Five tools (`checklist_*`) that let the agent create and update a tree
+ *      of items for the current session.
+ *   2. A dynamic prompt context that renders a compact digest of that tree on
+ *      every assembly, so the model never has to be reminded what is pending.
+ *
+ * The agent is the only writer. There is no client write path: the session
+ * document is the single source of truth.
+ */
+import { renderDigest } from './digest.js';
+import { serveProbe, PROBE_ROUTE } from './probe.js';
+import { serveItemUpdate, serveState, ITEM_ROUTE, STATE_ROUTE } from './route.js';
+import { ChecklistStore } from './store.js';
+import { registerChecklistTools } from './tools.js';
+export const name = 'dsh-checklist';
+export const inject = ['tools'];
+/**
+ * Resolve which session this prompt assembly belongs to.
+ *
+ * An agent's scope key is the Agent object itself (`scopeTarget(agent, agent)`
+ * in the agent registry), and `Agent.id` is the shared agent/session id. The
+ * initiator lookup is a fallback for assemblies that carry no scope. When
+ * neither yields an id, the digest stays empty rather than guessing.
+ */
+function sessionOfAssembly(ctx, assembly) {
+    const scope = assembly?.scope;
+    if (scope && typeof scope.id === 'string' && scope.id.length > 0)
+        return scope.id;
+    const agents = ctx.agents;
+    const initiator = agents?.currentInitiator?.();
+    return typeof initiator?.id === 'string' && initiator.id.length > 0 ? initiator.id : undefined;
+}
+export function apply(ctx, config = {}) {
+    const store = new ChecklistStore(config.storageRoot);
+    const maxLines = config.maxDigestLines ?? 12;
+    registerChecklistTools(ctx, store, {
+        maxItemsPerList: config.maxItemsPerList,
+        templates: config.templates,
+    });
+    // Opportunistic housekeeping: never blocks startup, never fails the plugin.
+    if (config.pruneDays !== 0) {
+        void store.prune(config.pruneDays ?? 14).catch(() => undefined);
+    }
+    let loggedScope = false;
+    ctx.inject(['systemPrompt'], (promptCtx) => {
+        promptCtx.systemPrompt.context({
+            name: 'dsh-checklist',
+            order: 65,
+            text: (assembly) => {
+                if (!loggedScope && process.env.DSH_CHECKLIST_DEBUG === '1') {
+                    loggedScope = true;
+                    const scope = assembly?.scope;
+                    console.error('[dsh-checklist] assembly scope:', scope ? `keys=[${Object.keys(scope).join(',')}] id=${String(scope.id)}` : 'none');
+                }
+                const sessionId = sessionOfAssembly(ctx, assembly);
+                if (!sessionId)
+                    return '';
+                const cached = store.peek(sessionId);
+                if (!cached) {
+                    // First turn after a restart: warm the cache for the next assembly.
+                    void store.prime(sessionId).catch(() => undefined);
+                    return '';
+                }
+                return renderDigest(cached, { maxLines });
+            },
+        });
+    });
+    // Read-only state endpoint consumed by the sidebar tab (phase 2).
+    ctx.inject(['webServer'], (webCtx) => {
+        webCtx.effect(() => webCtx.webServer.register({
+            kind: 'exact',
+            path: STATE_ROUTE,
+            handler: (req, res) => {
+                void serveState(req, res, store);
+            },
+        }), 'dsh-checklist: state route');
+        // The single write path outside the agent: an item-text edit from the sidebar.
+        webCtx.effect(() => webCtx.webServer.register({
+            kind: 'exact',
+            path: ITEM_ROUTE,
+            handler: (req, res) => {
+                void serveItemUpdate(req, res, store);
+            },
+        }), 'dsh-checklist: item route');
+        // Diagnostics channel for the browser half; see src/probe.ts.
+        webCtx.effect(() => webCtx.webServer.register({
+            kind: 'exact',
+            path: PROBE_ROUTE,
+            handler: (req, res) => {
+                serveProbe(req, res);
+            },
+        }), 'dsh-checklist: client probe route');
+    });
+}

package/lib/model.js

@@ -0,0 +1,222 @@
+/**
+ * Pure data model for session-scoped checklists.
+ *
+ * Nothing in this module imports a DSH package: the tree shape, the id
+ * allocation, and the reference resolver are unit-testable without a running
+ * harness.
+ */
+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`. */
+export function mintId(prefix, used) {
+    let n = 1;
+    while (used.has(`${prefix}${n}`))
+        n += 1;
+    return `${prefix}${n}`;
+}
+/**
+ * Build an item tree from plain lines.
+ *
+ * A line indented with two leading spaces per level nests under the previous
+ * shallower line. This is the format the model writes, and the format
+ * {@link toLines} round-trips.
+ *
+ * @param lines - item texts, optionally indented.
+ * @param used - id set to extend; pass the ids already present when appending
+ *   to an existing checklist, or ids will collide.
+ * @returns the root items, with ids assigned depth-first.
+ */
+export function buildItems(lines, used = new Set()) {
+    const roots = [];
+    const stack = [];
+    for (const raw of lines) {
+        const text = raw.trim();
+        if (text.length === 0)
+            continue;
+        const indent = raw.length - raw.trimStart().length;
+        const node = { id: mintId('i', used), text, state: 'todo', children: [] };
+        used.add(node.id);
+        while (stack.length > 0 && stack[stack.length - 1].indent >= indent)
+            stack.pop();
+        const parent = stack[stack.length - 1];
+        if (parent)
+            parent.node.children.push(node);
+        else
+            roots.push(node);
+        stack.push({ indent, node });
+    }
+    return roots;
+}
+/** Render an item tree back to indented lines (inverse of {@link buildItems}). */
+export function toLines(items, depth = 0) {
+    const out = [];
+    for (const item of items) {
+        out.push(`${'  '.repeat(depth)}${item.text}`);
+        out.push(...toLines(item.children, depth + 1));
+    }
+    return out;
+}
+/** Depth-first flattening, carrying each item's nesting depth. */
+export function flatten(items, depth = 0) {
+    const out = [];
+    for (const item of items) {
+        out.push({ item, depth });
+        out.push(...flatten(item.children, depth + 1));
+    }
+    return out;
+}
+export function countItems(items) {
+    let total = 0;
+    let done = 0;
+    for (const item of items) {
+        total += 1;
+        if (item.state === 'done')
+            done += 1;
+        const nested = countItems(item.children);
+        total += nested.total;
+        done += nested.done;
+    }
+    return { total, done };
+}
+/**
+ * Resolve one model-supplied reference against the session's checklists.
+ *
+ * Resolution order: exact id, exact case-insensitive text, unique
+ * case-insensitive prefix. Ambiguity is surfaced rather than guessed: the
+ * model can then pass a list id or the full text.
+ *
+ * @param lists - the session's checklists.
+ * @param ref - a model-supplied item id, text, or prefix.
+ * @param listId - optional checklist id 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;
+    const entries = [];
+    for (const list of scoped) {
+        for (const { item } of flatten(list.items))
+            entries.push({ list, item });
+    }
+    const byId = entries.find((entry) => entry.item.id.toLowerCase() === needles);
+    if (byId)
+        return { kind: 'hit', hit: byId };
+    const exact = entries.filter((entry) => entry.item.text.toLowerCase() === needles);
+    if (exact.length === 1)
+        return { kind: 'hit', hit: exact[0] };
+    if (exact.length > 1)
+        return { kind: 'ambiguous', candidates: exact };
+    const prefixed = entries.filter((entry) => entry.item.text.toLowerCase().startsWith(needles));
+    if (prefixed.length === 1)
+        return { kind: 'hit', hit: prefixed[0] };
+    if (prefixed.length > 1)
+        return { kind: 'ambiguous', candidates: prefixed };
+    return { kind: 'miss' };
+}
+/** Whether a value is a valid item state. */
+export function isItemState(value) {
+    return typeof value === 'string' && ITEM_STATES.includes(value);
+}
+/**
+ * Find a checklist by id or by exact case-insensitive title.
+ *
+ * Ids are what the tools hand out, but a model that just created "Release 2.3"
+ * will often pass the title back; accepting both avoids a pointless round trip.
+ *
+ * @param lists - the session's checklists.
+ * @param ref - a checklist id or its exact title.
+ * @returns the matching checklist, or `undefined`.
+ */
+export function findList(lists, ref) {
+    const needle = ref.trim().toLowerCase();
+    if (needle.length === 0)
+        return undefined;
+    return lists.find((list) => list.id.toLowerCase() === needle || list.title.toLowerCase() === needle);
+}
+/** Find one item by exact id across every list. */
+export function findItemById(lists, id) {
+    for (const list of lists) {
+        for (const { item } of flatten(list.items)) {
+            if (item.id === id)
+                return { list, item };
+        }
+    }
+    return undefined;
+}
+/**
+ * Validate a checklist rename before applying it.
+ *
+ * Titles are how the user reads the sidebar and how `findList` resolves a
+ * reference, so a rename must never create a second list with the same title.
+ * Renaming a list to its own title (any case) is a no-op, not a conflict.
+ *
+ * @param lists - the session's checklists.
+ * @param ref - checklist id or exact title.
+ * @param nextTitle - the requested new title.
+ * @returns the resolved list, or the reason the rename cannot proceed.
+ */
+export function checkRename(lists, ref, nextTitle) {
+    const to = nextTitle.trim();
+    if (to.length === 0)
+        return { kind: 'empty' };
+    const list = findList(lists, ref);
+    if (!list) {
+        return { kind: 'missing', available: lists.map((entry) => `${entry.id} (${entry.title})`) };
+    }
+    const lower = to.toLowerCase();
+    if (list.title.trim().toLowerCase() === lower) {
+        return { kind: 'ok', list, from: list.title, to };
+    }
+    const clash = lists.find((entry) => entry !== list && entry.title.trim().toLowerCase() === lower);
+    if (clash)
+        return { kind: 'duplicate', existing: clash.title };
+    return { kind: 'ok', list, from: list.title, to };
+}
+/**
+ * The next item to work on, in depth-first order.
+ *
+ * Rules, in the order they are applied:
+ * - A `done` subtree is skipped entirely.
+ * - A `blocked` subtree is skipped (and counted).
+ * - An item with open children is a container: descend and return its first
+ *   actionable leaf. A section header is never "the next thing to do".
+ * - A leaf is returned as-is.
+ *
+ * @param lists - the checklists to search.
+ * @param listId - optional checklist id to scope the search.
+ * @returns the next item (if any) plus the remaining and blocked counts.
+ */
+export function nextItem(lists, listId) {
+    const scope = listId ? lists.filter((list) => list.id === listId) : lists;
+    let remaining = 0;
+    let blocked = 0;
+    for (const list of scope) {
+        for (const { item } of flatten(list.items)) {
+            if (item.state === 'blocked')
+                blocked += 1;
+            else if (item.state !== 'done')
+                remaining += 1;
+        }
+    }
+    for (const list of scope) {
+        const found = firstOpen(list.items, []);
+        if (found)
+            return { next: { list, item: found.item, path: found.path }, remaining, blocked };
+    }
+    return { remaining, blocked };
+}
+function firstOpen(items, ancestors) {
+    for (const item of items) {
+        if (item.state === 'done' || item.state === 'blocked')
+            continue;
+        const child = firstOpen(item.children, [...ancestors, item.text]);
+        if (child)
+            return child;
+        return { item, path: ancestors };
+    }
+    return undefined;
+}

package/lib/probe.js

@@ -0,0 +1,46 @@
+/**
+ * Client diagnostics channel.
+ *
+ * The client half runs in a browser we cannot attach a debugger to from here.
+ * This endpoint lets it report its own load/registration stages to the host, so
+ * "the tab is not there" can be told apart from "the module never loaded".
+ *
+ * In-memory and bounded: it answers one question and dies with the process.
+ */
+export const PROBE_ROUTE = '/dsh-checklist/client-probe';
+const MAX_REPORTS = 12;
+const MAX_DETAIL = 500;
+const reports = [];
+export function serveProbe(req, res) {
+    if (req.method !== 'GET') {
+        res.writeHead(405, { allow: 'GET' });
+        res.end();
+        return;
+    }
+    let url;
+    try {
+        url = new URL(req.url ?? '/', 'http://127.0.0.1');
+    }
+    catch {
+        res.writeHead(400);
+        res.end();
+        return;
+    }
+    const stage = url.searchParams.get('stage');
+    if (stage) {
+        reports.push({
+            at: new Date().toISOString(),
+            stage: stage.slice(0, 80),
+            detail: (url.searchParams.get('detail') ?? '').slice(0, MAX_DETAIL),
+        });
+        if (reports.length > MAX_REPORTS)
+            reports.shift();
+    }
+    const payload = Buffer.from(`${JSON.stringify({ reports }, null, 2)}\n`, 'utf8');
+    res.writeHead(200, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': String(payload.byteLength),
+        'cache-control': 'no-store',
+    });
+    res.end(payload);
+}

package/lib/route.js

@@ -0,0 +1,155 @@
+/**
+ * Read-only HTTP endpoint for the sidebar.
+ *
+ * Same-origin, GET only, one query parameter. The store validates the session
+ * id (it becomes a file name), so a crafted `session` cannot escape the storage
+ * directory; anything invalid answers 400 rather than throwing.
+ */
+import { findItemById } from './model.js';
+import { toPublicState } from './state.js';
+export const STATE_ROUTE = '/dsh-checklist/state';
+export const ITEM_ROUTE = '/dsh-checklist/item';
+/** Longest session id we will even look at; real ones are UUIDs. */
+const MAX_SESSION_ID = 200;
+/** Request body cap for the one write endpoint. */
+const MAX_BODY_BYTES = 16 * 1024;
+/** Item text cap, matching `checklist_edit`. */
+const MAX_TEXT = 500;
+function sendJson(res, status, body) {
+    const payload = Buffer.from(`${JSON.stringify(body)}\n`, 'utf8');
+    res.writeHead(status, {
+        'content-type': 'application/json; charset=utf-8',
+        'content-length': String(payload.byteLength),
+        'cache-control': 'no-store',
+    });
+    res.end(payload);
+}
+/**
+ * Serve one session's checklist state.
+ *
+ * @param req - the incoming request.
+ * @param res - the response to write.
+ * @param store - the session store.
+ */
+export async function serveState(req, res, store) {
+    if (req.method !== 'GET') {
+        res.writeHead(405, { allow: 'GET' });
+        res.end();
+        return;
+    }
+    let session;
+    try {
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        session = url.searchParams.get('session');
+    }
+    catch {
+        sendJson(res, 400, { error: 'malformed request url' });
+        return;
+    }
+    if (!session) {
+        sendJson(res, 400, { error: 'the session query parameter is required' });
+        return;
+    }
+    if (session.length > MAX_SESSION_ID) {
+        sendJson(res, 400, { error: 'session id is too long' });
+        return;
+    }
+    try {
+        const doc = await store.prime(session);
+        sendJson(res, 200, toPublicState(doc));
+    }
+    catch {
+        // The store rejects unsafe ids by throwing; never echo the id back.
+        sendJson(res, 400, { error: 'invalid session id' });
+    }
+}
+async function readJsonBody(req, limit = MAX_BODY_BYTES) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of req) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+        size += buffer.byteLength;
+        if (size > limit)
+            throw new Error('body too large');
+        chunks.push(buffer);
+    }
+    if (size === 0)
+        throw new Error('empty body');
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'));
+}
+/**
+ * Apply one text edit from the sidebar.
+ *
+ * This is the only write path outside the agent, so it is deliberately narrow:
+ * one item, by exact id, with an optional `expectedText` guard. When the guard
+ * does not match, the answer is 409 rather than a silent overwrite — the client
+ * re-reads and the user retries.
+ *
+ * @param req - the incoming request; must be POST.
+ * @param res - the response to write.
+ * @param store - the session store.
+ */
+export async function serveItemUpdate(req, res, store) {
+    if (req.method !== 'POST') {
+        res.writeHead(405, { allow: 'POST' });
+        res.end();
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch {
+        sendJson(res, 400, { error: 'invalid JSON body' });
+        return;
+    }
+    if (body === null || typeof body !== 'object') {
+        sendJson(res, 400, { error: 'body must be an object' });
+        return;
+    }
+    const { session, itemId, text: nextText, expectedText } = body;
+    if (typeof session !== 'string' || session.length === 0 || session.length > MAX_SESSION_ID) {
+        sendJson(res, 400, { error: 'session is required' });
+        return;
+    }
+    if (typeof itemId !== 'string' || itemId.length === 0) {
+        sendJson(res, 400, { error: 'itemId is required' });
+        return;
+    }
+    if (typeof nextText !== 'string') {
+        sendJson(res, 400, { error: 'text is required' });
+        return;
+    }
+    const trimmed = nextText.trim();
+    if (trimmed.length === 0) {
+        sendJson(res, 400, { error: 'text must not be empty' });
+        return;
+    }
+    if (trimmed.length > MAX_TEXT) {
+        sendJson(res, 400, { error: `text is longer than ${MAX_TEXT} characters` });
+        return;
+    }
+    try {
+        const outcome = await store.update(session, (doc) => {
+            const found = findItemById(doc.lists, itemId);
+            if (!found)
+                return { status: 404 };
+            if (typeof expectedText === 'string' && found.item.text !== expectedText) {
+                return { status: 409 };
+            }
+            found.item.text = trimmed;
+            return { status: 200, item: { id: found.item.id, text: trimmed } };
+        });
+        if (outcome.status === 200)
+            sendJson(res, 200, { ok: true, item: outcome.item });
+        else if (outcome.status === 409) {
+            sendJson(res, 409, { error: 'conflict', detail: 'the item changed since the sidebar read it' });
+        }
+        else {
+            sendJson(res, 404, { error: 'item not found' });
+        }
+    }
+    catch {
+        sendJson(res, 400, { error: 'invalid session id' });
+    }
+}

package/lib/state.js

@@ -0,0 +1,36 @@
+/**
+ * The public JSON shape the sidebar reads.
+ *
+ * Deliberately separate from the stored document: the client gets no `version`
+ * field, no future internals, and nothing it could mistake for a write channel.
+ */
+import { countItems } from './model.js';
+function toPublicItem(item) {
+    return {
+        id: item.id,
+        text: item.text,
+        state: item.state,
+        children: item.children.map(toPublicItem),
+    };
+}
+function toPublicList(list) {
+    return {
+        id: list.id,
+        title: list.title,
+        createdAt: list.createdAt,
+        items: list.items.map(toPublicItem),
+    };
+}
+export function toPublicState(doc) {
+    const counts = { lists: doc.lists.length, total: 0, done: 0 };
+    for (const list of doc.lists) {
+        const listCounts = countItems(list.items);
+        counts.total += listCounts.total;
+        counts.done += listCounts.done;
+    }
+    return {
+        sessionId: doc.sessionId,
+        lists: doc.lists.map(toPublicList),
+        counts,
+    };
+}