@ctrl-spc/cs 0.7.7 → 0.7.9

package/dist/design-review.js

@@ -0,0 +1,242 @@
+/** One design presentation format and review record for both harnesses. */
+import { randomUUID } from 'node:crypto';
+import { must, textResult, errorResult } from './product-tools.js';
+const ARTIFACT_COLUMNS = 'id,task_id,type,format,title,purpose_key,system_kind,content,storage_path,created_by,from_agent,created_at,revision';
+const DECISION_COLUMNS = 'id,task_id,state,category,context,question,answer_mode,options,answer,selected_options,answer_note,question_comment_id,related_artifact_id,asked_by,asked_by_agent_run_id,asked_at,decided_by,decided_at';
+const RESERVED_OPTION_LABELS = ['approve', 'request changes'];
+export async function presentDesign(client, userId, workItemId, args, spec, attribute, askReview) {
+    try {
+        if (!args.title || !args.title.trim())
+            return errorResult(`${spec.tool} requires a non-empty title.`);
+        const extra = spec.extraValidation?.();
+        if (extra)
+            return errorResult(extra);
+        // Exactly ONE of the two shapes: html (a single render, exactly Phase 1)
+        // or options (2..11 competing renders).
+        const hasHtml = args.html !== undefined;
+        const hasOptions = args.options !== undefined;
+        if (hasHtml && hasOptions) {
+            return errorResult(`${spec.tool} takes either html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s), not both.`);
+        }
+        if (!hasHtml && !hasOptions) {
+            return errorResult(`${spec.tool} requires html (one ${spec.unit}) or options (2..11 competing ${spec.unit}s).`);
+        }
+        const multi = hasOptions;
+        let opts = [];
+        if (multi) {
+            if (!Array.isArray(args.options) || args.options.length < 2 || args.options.length > 11) {
+                return errorResult(`${spec.tool} requires 2..11 options (use html for a single ${spec.unit}; a review decision is capped at 12 options including the reserved one).`);
+            }
+            opts = args.options.map((option) => ({ label: (option.label ?? '').trim(), html: option.html ?? '' }));
+            if (opts.some((o) => !o.label)) {
+                return errorResult(`${spec.tool} requires a non-empty label for every option.`);
+            }
+            if (opts.some((o) => !o.html.trim())) {
+                return errorResult(`${spec.tool} requires non-empty html for every option (${spec.htmlSpec}).`);
+            }
+            const lowered = opts.map((o) => o.label.toLowerCase());
+            if (new Set(lowered).size !== lowered.length) {
+                return errorResult(`${spec.tool} requires distinct option labels (case-insensitive).`);
+            }
+            if (lowered.some((label) => RESERVED_OPTION_LABELS.includes(label))) {
+                return errorResult(`${spec.tool} option labels 'approve' and 'request changes' are reserved review outcomes — rename the option.`);
+            }
+        }
+        else if (!args.html || !args.html.trim()) {
+            return errorResult(`${spec.tool} requires non-empty html (${spec.htmlSpec}).`);
+        }
+        const title = args.title.trim();
+        // Sentence-initial form of the artifact noun, for the attribution warning.
+        const capitalNoun = spec.artifactNoun.charAt(0).toUpperCase() + spec.artifactNoun.slice(1);
+        // The review decision's question — the recovery message below quotes it
+        // LITERALLY, so both must come from this one string.
+        const question = `Review the ${spec.artifactNoun} and leave feedback.`;
+        // One entry per artifact to create, in presentation order (idx 0 = the
+        // primary). Multi tags EVERY entry with the option ↔ artifact mapping key;
+        // single stays untagged, exactly Phase 1.
+        const presentationId = multi ? randomUUID() : null;
+        const renders = multi
+            ? opts.map((option, idx) => ({
+                title: idx === 0 ? title : `${title} — ${option.label}`,
+                html: option.html,
+                purpose_key: `wireframe_option:${presentationId}:${idx}`,
+            }))
+            : [{ title, html: args.html, purpose_key: null }];
+        // The review decision's options: the approval outcome(s) first, 'request
+        // changes' always last (the DB caps decision options at 12, hence ≤11 labels).
+        const reviewOptions = multi ? [...opts.map((o) => o.label), 'request changes'] : ['approve', 'request changes'];
+        // The renders land on the session's task. Confirm it is live under the
+        // user's RLS first (mirrors create_artifact) so a task archived after
+        // begin_work gets a clean error instead of an opaque insert failure.
+        const task = await must(client.from('tasks').select('id').eq('id', workItemId).is('archived_at', null).maybeSingle());
+        if (!task)
+            return errorResult(`No task found for id "${workItemId}".`);
+        // 1. Each render as a normal artifact — the SAME insert create_artifact
+        // does, one row per render, in presentation order.
+        const created = [];
+        const attributionWarnings = [];
+        for (const render of renders) {
+            let row = null;
+            try {
+                row = await must(client
+                    .from('artifacts')
+                    .insert({
+                    task_id: workItemId,
+                    type: spec.artifactType,
+                    format: 'html',
+                    // 18d Slice 3, gate A: a mock or wireframe IS "a presented
+                    // document" in story 2's list, and its body is agent-authored
+                    // HTML the user opens fullscreen.
+                    title: render.title,
+                    ...(render.purpose_key ? { purpose_key: render.purpose_key } : {}),
+                    content: render.html,
+                    created_by: userId,
+                    from_agent: null,
+                    agent_run_id: null,
+                })
+                    .select(ARTIFACT_COLUMNS)
+                    .single());
+                if (!row)
+                    throw new Error('Artifact insert returned no row.');
+            }
+            catch (err) {
+                // Nothing created yet → fatal and generic, exactly the Phase 1 path.
+                if (created.length === 0)
+                    throw err;
+                // A later option insert failing orphans the already-created options:
+                // return them (ids included) with guidance the agent can actually act
+                // on. No tool can delete an artifact (update_artifact has no deleted_at
+                // and there is no delete tool), so "clean up" is not an instruction the
+                // agent can execute — removal is a manual web action, and the agent's
+                // job is to surface it and hold off re-presenting (a blind retry would
+                // duplicate the created options).
+                const createdIds = created.map((row) => row.id).join(', ');
+                const failure = {
+                    artifacts: created,
+                    error: `${spec.tool}: created ${created.length} of ${renders.length} option artifacts, then the insert for ` +
+                        `'${render.title}' failed: ${err.message}. No review request was opened. There is no delete ` +
+                        `tool: the created artifacts (${createdIds}) are inert until removed manually in the web. Report this ` +
+                        `failure to the user with those ids, and do NOT call ${spec.tool} again (it would duplicate the ` +
+                        'created options) until the user confirms.',
+                };
+                if (attributionWarnings.length)
+                    failure.attribution_warning = attributionWarnings.join(' ');
+                return { ...textResult(failure), isError: true };
+            }
+            created.push(row);
+            // Best-effort session attribution per artifact (mirrors create_artifact:
+            // the session's task matches by construction). The artifact already exists
+            // and is part of the real return value, so a failed attribution write must
+            // NOT fail the tool — it is surfaced in the returned text, never dropped.
+            //
+            /* 18c SLICE 6: `todo_id` records WHICH RUN produced this render, off the
+               connection rather than the session. See createArtifactHandler's
+               attribution block (ux.md § "Slice 6"). This tool refuses outright
+               without a session AND without a work item (requiresWorkItem above), so
+               its session is always work-item-anchored and its `todoId` is always
+               null: this is the exact case gap 13 names, and the connection is the
+               only place the request can be read from. */
+            try {
+                await attribute('artifact', row.id);
+            }
+            catch (err) {
+                attributionWarnings.push(`${capitalNoun} artifact created, but recording session attribution failed: ${err.message}`);
+            }
+        }
+        const primary = created[0];
+        // 2. The review request as a single_select decision — the SAME RPC
+        // ask_question uses; 'wireframe_review' is the sentinel category the web
+        // keys on (feature 09). The artifacts above already exist, so from here a
+        // failure must NOT be the generic fatal error: swallowing them would orphan
+        // them in the DB (plain cards with no "feedback requested"), leave the
+        // agent with no ids to recover with, and invite a blind retry that
+        // duplicates artifacts. So this step gets its OWN try/catch (the FIRST
+        // artifact-insert failure path above stays fatal and generic), and on
+        // failure the error result STILL carries the created artifact(s) plus a
+        // message telling the agent to retry the review step — via ask_question
+        // with related_artifact_id — or clean up, not re-present.
+        let decision;
+        try {
+            const decisionId = await askReview({ title, question, options: reviewOptions, artifactId: primary.id });
+            if (!decisionId)
+                throw new Error('Review request insert returned no decision id.');
+            // Best-effort attribution for the decision (mirrors ask_question exactly),
+            // 18c Slice 6 `todo_id` included.
+            try {
+                await attribute('decision', decisionId);
+            }
+            catch (err) {
+                attributionWarnings.push(`Review request created, but recording session attribution failed: ${err.message}`);
+            }
+            // Re-fetch the created decision with the SAME columns get_task returns, so
+            // the agent sees what it made and can later read the feedback back with
+            // get_task.
+            const fetched = await must(client.from('decisions').select(DECISION_COLUMNS).eq('id', decisionId).maybeSingle());
+            if (!fetched)
+                throw new Error('Created review decision could not be re-fetched.');
+            decision = fetched;
+        }
+        catch (err) {
+            // The recovery instruction must be LITERAL and complete: the web's review
+            // surface matches ONLY category === 'wireframe_review' (a sentinel that is
+            // deliberately not in any tool description, and that mocks reuse verbatim
+            // — there is no 'mock_review'), and the decision-consistency
+            // guard makes category immutable — so a plausible-but-wrong retry category
+            // would leave the review permanently stuck as a generic question. Spell out
+            // the exact ask_question call, with the real title, the full literal
+            // options array, and the primary artifact id. The multi failure payload
+            // carries ALL created artifacts (ids included).
+            const optionsLiteral = `[${reviewOptions.map((label) => `'${label}'`).join(', ')}]`;
+            const failure = {
+                ...(multi ? { artifacts: created } : { artifact: primary }),
+                error: `${spec.tool}: the ${spec.artifactNoun} artifact${multi ? 's were' : ' was'} created, but opening the review request failed: ` +
+                    `${err.message}. Do NOT call ${spec.tool} again (it would duplicate the artifact${multi ? 's' : ''}) — ` +
+                    `retry the review step with ask_question({ category: 'wireframe_review', context: '${title}', ` +
+                    `question: '${question}', answer_mode: 'single_select', ` +
+                    `options: ${optionsLiteral}, related_artifact_id: '${primary.id}' }) — the category string must be exactly ` +
+                    "'wireframe_review' or the web will not show the review UI — or clean up.",
+            };
+            if (attributionWarnings.length)
+                failure.attribution_warning = attributionWarnings.join(' ');
+            return { ...textResult(failure), isError: true };
+        }
+        const payload = {
+            ...(multi ? { artifacts: created } : { artifact: primary }),
+            decision,
+            instruction: multi
+                ? `The user has been asked to review ${created.length} competing options. They send CUMULATIVE feedback ` +
+                    "rounds — any number, any time, without waiting for you: poll get_task and read them from its `feedback` " +
+                    'list (oldest first). Every round is tagged with the presentation PRIMARY artifact (the first option) and ' +
+                    'its artifact_revision at send time — the version stamp of the presentation, NOT a per-option pointer. ' +
+                    "Which OPTION a note concerns is named inline in the note's \"(…)\" option label within the round's body. " +
+                    'This decision is the approval gate only: it stays open across rounds and decides ONLY when the user ' +
+                    'approves — once its state is decided, selected_options[0] is the approved option label and answer_note ' +
+                    'may carry a final comment. To act on feedback, revise the option artifact each note names IN PLACE with ' +
+                    'update_artifact (its revision bumps automatically), then call resolve_feedback with the ids of the ' +
+                    "rounds that revision actually addressed and the revised OPTION artifact's NEW revision number — only " +
+                    'rounds you genuinely acted on. Option revisions are their own number-space (not the primary v-tags): ' +
+                    'the review surface shows a multi round as resolved WITHOUT a version number, so name WHICH option you ' +
+                    'revised in any accompanying update, and never expect the primary revision to move when only options ' +
+                    "changed. A round the user flips back to 'reopened' is open feedback again: address it on the next pass " +
+                    `and re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.'
+                : `The user has been asked to review the ${spec.artifactNoun}. They send CUMULATIVE feedback rounds — any number, any ` +
+                    "time, without waiting for you: poll get_task and read them from its `feedback` list (oldest first), each " +
+                    'tagged with the artifact_revision it critiques so you know which version the notes are about. This ' +
+                    'decision is the approval gate only: it stays open across rounds and decides ONLY when the user approves ' +
+                    "— once its state is decided, selected_options[0] is 'approve' and answer_note may carry a final comment. " +
+                    `To act on feedback, revise this ${spec.artifactNoun} IN PLACE with update_artifact (its revision bumps ` +
+                    'automatically, so later rounds name the new version), then call resolve_feedback with the ids of the ' +
+                    'rounds that revision actually addressed and the NEW revision number — only rounds you genuinely acted ' +
+                    "on. A round the user flips back to 'reopened' is open feedback again: address it on the next pass and " +
+                    `re-resolve. Keep polling. Do NOT call ${spec.tool} ` +
+                    'again for iterations of this same design.',
+        };
+        if (attributionWarnings.length)
+            payload.attribution_warning = attributionWarnings.join(' ');
+        return textResult(payload);
+    }
+    catch (err) {
+        return errorResult(`${spec.tool} failed: ${err.message}`);
+    }
+}