@ctrl-spc/cs 0.7.7 → 0.7.8

package/dist/panel3/tools.js

@@ -112,6 +112,10 @@
 // The runtime import comes FIRST, deliberately: `tsc` elides a type-only import
 // and takes the leading comment with it, so a file whose first statement is
 // `import type` loses its v3 header in the published `dist/`.
+import { presentDesign } from '../design-review.js';
+import { canonicalArgsHash, getDocumentHandler, proposeProjectContextHandler, placeWorkItemHandler, resolveFeedbackHandler, PROJECT_DOCUMENT_TYPES, errorMessage } from '../product-tools.js';
+import { workflowToolForName, workflowToolAlwaysAllowed } from '../workflow-tool-mentions.js';
+import { captureUrlScreenshot } from '../browser.js';
 import { createServer as createHttpServer } from 'node:http';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -126,7 +130,7 @@ import { workBrief } from './prompt.js';
    here is the same fact without a second round trip. */
 import { harness } from './spawn.js';
 import { listCodebases } from '../codebases.js';
-import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage } from '../workflows.js';
+import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING } from '../workflows.js';
 /* ═══ 38-panel3-steps: THE FIFTH NEUTRAL MODULE, AND A DECISION LIKE THE OTHERS.
    ═══ Stages and steps are the work item's own record, shared by both
    generations and read by the web's Steps section. `steps.ts` owns the rows so
@@ -738,7 +742,173 @@ async function stageForWriting(caller, stageId, consequence) {
     await carriedWorkItem(caller, stage.workItemId, consequence);
     return stage;
 }
+function productResult(result) {
+    const text = result.content.filter((item) => Boolean(item && typeof item === 'object' && 'text' in item)).map(item => item.text).join('\n');
+    if (result.isError)
+        throw new Error(text);
+    return text;
+}
 const TOOLS = [
+    {
+        name: 'get_document', levels: ALL,
+        description: 'Read a project context document or instruction in full by id. Read-only.',
+        input: { id: z.string().uuid() },
+        handler: async (caller, args) => productResult(await getDocumentHandler(caller.client, args)),
+    },
+    {
+        name: 'add_comment', levels: ALL,
+        description: 'Leave a durable note or handover on a work item. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), body: z.string().min(1) },
+        handler: async (caller, args) => {
+            const { work_item_id, body } = args;
+            await carriedWorkItem(caller, work_item_id, 'a comment cannot be added to it');
+            const comment = await only(caller.client.from('comments')
+                .insert({ task_id: work_item_id, body, author_id: caller.userId }).select('id'), 'add', 'the comment');
+            return `Added comment ${comment.id}.`;
+        },
+    },
+    {
+        name: 'create_product_idea', levels: [1],
+        description: 'Capture a potential improvement without committing to implementation. First read existing work items, including Product Ideas, and the product to avoid duplicates. Only a human can promote an idea. ' + FIREWALL_WRITING_RULE,
+        input: { project_id: z.string().uuid(), title: z.string().min(1), description: z.string().optional() },
+        handler: async (caller, args) => {
+            const a = args;
+            const id = await returned(caller.client.rpc('create_product_idea', {
+                p_project: a.project_id, p_name: a.title, p_description: a.description ?? '', p_owner: caller.userId,
+            }), 'create', 'the product idea');
+            if (!id)
+                throw new Error('The product idea was not created.');
+            await receipt(caller, 'work_item', id, a.title);
+            return `Created Product Idea ${a.title}, id ${id}. No work has started. Only a human can promote it.`;
+        },
+    },
+    {
+        name: 'place_work_item', levels: [1],
+        description: 'Move a work item into an epic or sprint in its project. Null removes placement. Its status stays the same.',
+        input: { work_item_id: z.string().uuid(), epic_id: z.string().uuid().nullable().optional(),
+            sprint_id: z.string().uuid().nullable().optional(), before_work_item_id: z.string().uuid().optional() },
+        handler: async (caller, args) => productResult(await placeWorkItemHandler(caller.client, args)),
+    },
+    {
+        name: 'reorder_backlog', levels: [1],
+        description: 'Move one backlog work item before another, or to the bottom. Read the current order first and explain the reason.',
+        input: { project_id: z.string().uuid(), task_id: z.string().uuid(), before_task_id: z.string().uuid().optional(), reason: z.string().min(1) },
+        handler: async (caller, args) => {
+            const a = args;
+            const items = await rows(caller.client.from('tasks').select('id, revision')
+                .eq('project_id', a.project_id).eq('status', 'backlog').is('archived_at', null).eq('is_idea', false).order('position').order('created_at').order('id'), 'read', 'the backlog');
+            const moving = items.find(item => item.id === a.task_id);
+            if (!moving || (a.before_task_id && !items.some(item => item.id === a.before_task_id)))
+                throw new Error('Both items must be live backlog work in this project. Nothing was moved.');
+            if (a.task_id === a.before_task_id)
+                throw new Error('An item cannot be placed before itself. Nothing was moved.');
+            await returned(caller.client.rpc('save_task_if_current', { p_task_id: a.task_id,
+                p_expected_revision: moving.revision, p_changes: {}, p_tag_ids: null, p_reorder: true,
+                p_before_task_id: a.before_task_id ?? null }), 'reorder', 'the backlog');
+            return `Reordered the backlog: ${a.reason}`;
+        },
+    },
+    {
+        name: 'propose_project_context', levels: [2, 3],
+        description: 'Submit repository guidance for human review in Project settings. Pending proposals for this scan are replaced; accepted context is never changed. Name the scanned codebase and use repository-relative source paths. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), codebase: z.string().min(1), proposals: z.array(z.object({
+                title: z.string().min(1), type: z.enum(PROJECT_DOCUMENT_TYPES), content: z.string().min(1),
+                source_path: z.string().min(1), reason: z.string().min(1), scope: z.enum(['project', 'codebase']),
+            })) },
+        handler: async (caller, args) => {
+            const { work_item_id, ...a } = args;
+            await carriedWorkItem(caller, work_item_id, 'project context cannot be proposed for it');
+            return productResult(await proposeProjectContextHandler(caller.client, null, { ...a, task_id: work_item_id }));
+        },
+    },
+    {
+        name: 'record_context_exploration', levels: ALL,
+        description: 'Save explored context and research in the work item’s Findings artifact. Repeated calls update the same artifact. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), content: z.string().min(1) },
+        handler: async (caller, args) => {
+            const { work_item_id, content } = args;
+            await carriedWorkItem(caller, work_item_id, 'findings cannot be recorded on it');
+            const existing = await rows(caller.client.from('artifacts').select('id')
+                .eq('task_id', work_item_id).eq('purpose_key', 'workflow_findings').is('deleted_at', null), 'read', 'existing findings');
+            if (existing.length > 1)
+                throw new Error('More than one Findings artifact exists. Choose the artifact to edit explicitly.');
+            const artifact = existing[0]
+                ? await only(caller.client.from('artifacts').update({ content, updated_by: caller.userId })
+                    .eq('id', existing[0].id).select('id'), 'update', 'the findings')
+                : await only(caller.client.from('artifacts').insert({ task_id: work_item_id, title: 'Findings',
+                    type: 'analysis', format: 'md', content, purpose_key: 'workflow_findings', created_by: caller.userId }).select('id'), 'record', 'the findings');
+            await receiptOnce(caller, 'artifact', artifact.id, 'Findings');
+            return `Recorded Findings artifact ${artifact.id}.`;
+        },
+    },
+    {
+        name: 'resolve_feedback', levels: ALL,
+        description: 'Mark specified feedback rounds addressed after revising their artifact. Supply the new revision. This does not approve the artifact.',
+        input: { work_item_id: z.string().uuid(), feedback_ids: z.array(z.string().uuid()).min(1), revision: z.number().int().positive() },
+        handler: async (caller, args) => {
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'its feedback cannot be resolved');
+            await validateWorkflowToolTarget(caller.client, a.work_item_id, 'resolve_feedback', a);
+            return productResult(await resolveFeedbackHandler(caller.client, { taskId: a.work_item_id }, a));
+        },
+    },
+    ...['present_mocks', 'present_wireframes'].map((name) => ({
+        name, levels: [2],
+        description: 'Create a self-contained HTML design and open its artifact review. Use html, with scripts inline for interactive mocks. Only the active conversation owner may present for review. Revise the same artifact for changes; do not present it again. Stop after opening review. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), title: z.string().min(1), html: z.string().min(1),
+            ...(name === 'present_wireframes' ? { kind: z.enum(['ui', 'architecture']) } : {}) },
+        handler: async (caller, args) => {
+            if (!caller.isOwner || !caller.processToken)
+                throw new Error('Escalate this design presentation to the current conversation owner. Nothing was written.');
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a design cannot be presented for it');
+            const mock = name === 'present_mocks';
+            const result = await presentDesign(caller.client, caller.userId, a.work_item_id, a, {
+                tool: name, unit: mock ? 'mock' : 'diagram', htmlSpec: 'self-contained HTML',
+                artifactType: mock ? 'mock' : a.kind === 'architecture' ? 'diagram' : 'wireframe',
+                artifactNoun: mock ? 'mock' : 'wireframe',
+            }, async (kind, id) => {
+                if (kind === 'artifact')
+                    await receiptOnce(caller, 'artifact', id, a.title);
+            }, async (review) => {
+                await asked(caller, { work_item_id: a.work_item_id, related_artifact_id: review.artifactId,
+                    category: 'wireframe_review', context: review.title, question: review.question,
+                    answer_mode: 'single_select', options: review.options }, true);
+                const decision = await only(caller.client.from('decisions').select('id')
+                    .eq('related_artifact_id', review.artifactId).eq('category', 'wireframe_review'), 'read', 'the design review');
+                return decision.id;
+            });
+            const text = productResult(result);
+            return text + '\nStop now. The conversation resumes when the user answers. Do not poll.';
+        },
+    })),
+    {
+        name: 'propose_scope_change', levels: [2],
+        description: 'Present a proposed change to approved scope, with the user request, classification, and quoted evidence, as an artifact for review. Only the conversation owner may open its approval. Stop; permission to propose does not approve expanded work. ' + FIREWALL_WRITING_RULE,
+        input: { work_item_id: z.string().uuid(), request: z.string().min(1),
+            classification: z.enum(['completion_gap', 'clarification', 'expansion', 'replacement']),
+            evidence: z.string().min(1), measured_against_version: z.number().int().positive() },
+        handler: async (caller, args) => {
+            if (!caller.isOwner || !caller.processToken)
+                throw new Error('Escalate the scope proposal to the current conversation owner. Nothing was written.');
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a scope change cannot be proposed for it');
+            const artifact = await only(caller.client.from('artifacts').insert({ task_id: a.work_item_id,
+                title: 'Scope change proposal', type: 'spec', format: 'md', created_by: caller.userId,
+                content: `# Proposed scope change\n\n${a.request}\n\nClassification: ${a.classification}\n\nCompared with approved scope version ${a.measured_against_version}:\n\n${a.evidence}\n\nProposed only. Do not implement until the user approves.`,
+            }).select('id'), 'create', 'the scope change proposal');
+            await receipt(caller, 'artifact', artifact.id, 'Scope change proposal');
+            try {
+                return await asked(caller, { work_item_id: a.work_item_id, related_artifact_id: artifact.id,
+                    category: 'scope_change', context: 'Review the proposed change before any expanded work begins.',
+                    question: 'Approve this scope change, or request changes?', answer_mode: 'single_select',
+                    options: ['approve', 'request changes'] }, true);
+            }
+            catch (error) {
+                throw new Error(`Proposal artifact ${artifact.id} was created, but review did not open: ${errorMessage(error)}. Do not create it again. Use ask_question to request approval of this artifact; do not implement it.`);
+            }
+        },
+    },
     // ── Read the record ──────────────────────────────────────────────────────
     {
         name: 'list_projects',
@@ -789,6 +959,9 @@ const TOOLS = [
                 .eq('id', work_item_id), 'read', `work item ${work_item_id}`);
             const artifacts = await rows(client.from('artifacts').select('id, type, title, created_at').eq('task_id', work_item_id)
                 .is('deleted_at', null).order('created_at'), 'read', `the artifacts on work item ${work_item_id}`);
+            const feedback = await rows(client.from('artifact_feedback').select('*').eq('task_id', work_item_id).order('created_at'), 'read', 'the artifact feedback');
+            const decisions = await rows(client.from('decisions').select('id, category, question, state, selected_options, answer_note, related_artifact_id').eq('task_id', work_item_id).order('asked_at'), 'read', 'the work item decisions');
+            const comments = await rows(client.from('comments').select('id, body, created_at').eq('task_id', work_item_id).order('created_at'), 'read', 'the work item comments');
             return [
                 `${item.name}`,
                 `id        ${item.id}`,
@@ -801,6 +974,7 @@ const TOOLS = [
                 'DESCRIPTION',
                 item.description.trim() === '' ? '(empty)' : item.description,
                 '',
+                'DECISIONS', JSON.stringify(decisions), 'FEEDBACK', JSON.stringify(feedback), 'COMMENTS', JSON.stringify(comments),
                 `ARTIFACTS  ${artifacts.length}`,
                 listed(artifacts.map((a) => line(a.id, a.type, a.title ?? '(untitled)')), 'none'),
             ].join('\n');
@@ -1879,12 +2053,12 @@ const TOOLS = [
     {
         name: 'create_sprint',
         levels: [1],
-        description: 'Create a sprint in a project. Both dates are required and the start must not be after the end.',
+        description: 'Create an ordered batch of work in a project. Dates are optional; use them only for a stated calendar constraint.',
         input: {
             project_id: z.string(),
             name: z.string().min(1),
-            start_date: z.string().describe('YYYY-MM-DD'),
-            end_date: z.string().describe('YYYY-MM-DD'),
+            start_date: z.string().optional().describe('YYYY-MM-DD'),
+            end_date: z.string().optional().describe('YYYY-MM-DD'),
         },
         handler: async (caller, args) => {
             const { project_id, name, start_date, end_date } = args;
@@ -2332,6 +2506,26 @@ const TOOLS = [
     // because a conversation is one person's. An artifact belongs to a work item
     // the whole org can see, so it goes where every other artifact goes. Two
     // visibility models, two buckets, both deliberate.
+    {
+        name: 'attach_screenshot',
+        levels: [2, 3],
+        description: 'Capture a web page and keep the screenshot as an artifact on this work item. Pass url; the tool takes the picture. ' + WORKFLOW_TOOL_TEACHING,
+        input: {
+            url: z.string().url(), work_item_id: z.string().uuid(), title: z.string().min(1).max(200),
+            platform: z.literal('web'), target: z.string().min(1).max(200),
+        },
+        handler: async (caller, args) => {
+            const a = args;
+            await carriedWorkItem(caller, a.work_item_id, 'a screenshot cannot be attached to it');
+            const capture = await captureUrlScreenshot(a.url);
+            try {
+                return await toolNamed('attach_image_artifact').handler(caller, { ...a, path: capture.path });
+            }
+            finally {
+                await capture.cleanup();
+            }
+        },
+    },
     {
         name: 'attach_image_artifact',
         levels: [2, 3],
@@ -2600,7 +2794,11 @@ const TOOLS = [
                 + 'or sends back for changes. Only the current Level 2 conversation owner may name it, and '
                 + 'its current process token is required. Leave it out for every ordinary question.'),
         },
-        handler: async (caller, args) => asked(caller, args, true),
+        handler: async (caller, args) => {
+            if (String(args.category).startsWith('workflow_tool_'))
+                throw new Error('That category is reserved for tool permissions. The tool opens its own approval question; do not create one yourself.');
+            return asked(caller, args, true);
+        },
     },
     {
         name: 'escalate',
@@ -2905,9 +3103,60 @@ async function receiptOnce(caller, kind, refId, label) {
  *  the same reason `cs show` exists: a rule nobody can print is a rule nobody
  *  can check. */
 export function toolNamesForLevel(level, isOwner = false) {
-    return TOOLS.filter((t) => t.levels.includes(level) && !(isOwner && t.name === 'escalate'))
+    return TOOLS.filter((t) => toolAvailable(t, level, isOwner))
         .map((t) => t.name);
 }
+/** The stage owns the setting; the existing question path owns permission.
+ * An exact-call fingerprint prevents approval of one edit authorizing another. */
+async function invokeWorkflowTool(caller, tool, args) {
+    const canonical = workflowToolForName(tool.name);
+    const a = args;
+    const { workflow_tool_instance: instance, workflow_work_item_id: explicitSource, ...inputs } = a;
+    const invoke = () => tool.handler(caller, inputs);
+    if (!canonical || workflowToolAlwaysAllowed(canonical))
+        return invoke();
+    const attached = await loadAttachments(caller.client, caller.cardId);
+    const ids = attached.filter(item => item.kind === 'work_item').map(item => item.ref_id);
+    let workItemId = explicitSource;
+    if (!workItemId && ids.length === 1)
+        workItemId = ids[0];
+    if (!workItemId && ids.includes(String(a.work_item_id ?? a.task_id)))
+        workItemId = String(a.work_item_id ?? a.task_id);
+    if (!workItemId && tool.name === 'create_step') {
+        const stage = await stageById(caller.client, String(a.stage_id));
+        workItemId = stage?.workItemId ?? undefined;
+    }
+    if (!workItemId && ids.length > 1)
+        throw new Error('Name workflow_work_item_id from the card attachments so the correct stage controls this action.');
+    if (workItemId)
+        await carriedWorkItem(caller, workItemId, 'its workflow permissions cannot be used', attached);
+    const permission = await workflowToolPermission(caller.client, workItemId ?? null, canonical, instance);
+    if (!tool.levels.includes(caller.level) && !permission)
+        throw new Error('This planning action requires an explicit tool mention in the current workflow stage. Nothing was written.');
+    if (permission)
+        await validateWorkflowToolTarget(caller.client, workItemId, canonical, a);
+    if (!permission || permission.approval === 'not-required')
+        return invoke();
+    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission.id, args: inputs });
+    const category = `workflow_tool_${fingerprint}`;
+    const questions = await withAskContent(caller.client, await rows(caller.client.from('panel3_asks').select(`pending_run_id, answered_at, ${ASK_CONTENT_COLUMNS}`).eq('card_id', caller.cardId), 'read', 'workflow tool approvals'));
+    const previous = questions.find(question => question.category === category && question.decision_id !== null);
+    if (previous?.answered_at) {
+        if (previous.selected_options?.length === 1 && previous.selected_options[0] === 'approve')
+            return invoke();
+        throw new Error('The user did not approve this workflow tool action. Nothing was written.');
+    }
+    if (previous)
+        throw new Error('This workflow tool action is waiting for user approval. Stop until the user answers.');
+    if (caller.level === 3)
+        throw new Error('This workflow tool action requires user approval. Escalate the exact action to the conversation owner and stop; the owner must perform the approved call.');
+    await asked(caller, {
+        question: `May I ${tool.name.replaceAll('_', ' ')}${a.title ? `: ${String(a.title).slice(0, 180)}` : ''}?`,
+        category, context: 'This use of the tool requires approval in the workflow stage.',
+        answer_mode: 'single_select', options: ['approve', 'deny'], work_item_id: workItemId,
+    }, true);
+    throw new Error('This workflow tool action is waiting for user approval. Nothing was written. Stop until the user answers, then retry the same call with the same arguments.');
+}
 /**
  * One tool's handler, by name. Exported for the same reason `toolNamesForLevel`
  * is: a test that only calls `workBrief` with a hand-built array proves the
@@ -2927,6 +3176,11 @@ export function toolShape(name) {
     const { description, input } = toolNamed(name);
     return { description, input };
 }
+function toolAvailable(tool, level, isOwner) {
+    if (isOwner && tool.name === 'escalate')
+        return false;
+    return tool.levels.includes(level) || (level === 2 && isOwner && workflowToolForName(tool.name) !== undefined);
+}
 function toolNamed(name) {
     const tool = TOOLS.find((t) => t.name === name);
     if (!tool)
@@ -2948,9 +3202,14 @@ function buildServer(caller) {
             + 'hold rather than one that is missing.',
     });
     for (const tool of TOOLS) {
-        if (!tool.levels.includes(caller.level) || (caller.isOwner && tool.name === 'escalate'))
+        if (!toolAvailable(tool, caller.level, caller.isOwner))
             continue;
-        server.registerTool(tool.name, { description: tool.description, inputSchema: tool.input }, (async (args) => {
+        server.registerTool(tool.name, { description: tool.description + ' ' + WORKFLOW_TOOL_TEACHING, inputSchema: { ...tool.input,
+                ...(workflowToolForName(tool.name) ? {
+                    workflow_tool_instance: z.string().uuid().optional(),
+                    workflow_work_item_id: z.string().uuid().optional().describe('The attached work item whose workflow stage instructs this action. Needed when the card carries multiple work items.'),
+                } : {}),
+            } }, (async (args) => {
             try {
                 /* ═══ NOTHING THIS RUN READ GOES BACK OUT THROUGH A TOOL. ═══ Every
                    argument of every tool, redacted before the handler sees it: see
@@ -2959,7 +3218,7 @@ function buildServer(caller) {
                    on; `writeAnswer` in run.ts is the other. It is identity for the
                    runs that read no credential, which is nearly all of them. */
                 const safe = redactArgs(secretScope(caller), args);
-                return { content: [{ type: 'text', text: await tool.handler(caller, safe) }] };
+                return { content: [{ type: 'text', text: await invokeWorkflowTool(caller, tool, safe) }] };
             }
             catch (error) {
                 /* ═══ A FAILURE REACHES THE AGENT AS A FAILURE. ═══ Constraint 7, at