@ctrl-spc/cs 0.7.8 → 0.7.9

package/dist/mcp.js

@@ -14,8 +14,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, assertAgentToolMentions } from './workflows.js';
-import { workflowToolForName } from './workflow-tool-mentions.js';
+import { workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING, authorToolMentions } from './workflows.js';
+import { workflowToolForName, validateApprovalAction } from './workflow-tool-mentions.js';
 import { TOOLS_SERVER_PORT, SESSION_TTL_MS } from './env.js';
 import { agentPath } from './agents.js';
 import { mcpToken, readMcpToken, readSession } from './config.js';
@@ -7802,24 +7802,19 @@ export async function readWorkflowLibraryHandler(client, args, userId) {
         // workflow ids actually present rather than as PostgREST embeds, the same
         // two-step `listClientsHandler` uses.
         const workflowIds = workflows.map((workflow) => workflow.id);
-        const links = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_stages_in_workflow')
-                .select('workflow_id, stage_id, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
-        const exits = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_stage_exits')
-                .select('workflow_id, stage_id, to_stage_id, condition, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
-        const branches = workflowIds.length
-            ? ((await must(client
-                .from('cliv2_workflow_branches')
-                .select('workflow_id, when_condition, runs_workflow_id, position')
-                .in('workflow_id', workflowIds))) ?? [])
-            : [];
+        const links = [];
+        const exits = [];
+        const branches = [];
+        // Like artifact counts above, bound GET filters so a large library remains readable.
+        for (let offset = 0; offset < workflowIds.length; offset += COUNT_BATCH) {
+            const ids = workflowIds.slice(offset, offset + COUNT_BATCH);
+            links.push(...(await must(client.from('cliv2_workflow_stages_in_workflow')
+                .select('workflow_id, stage_id, position').in('workflow_id', ids))) ?? []);
+            exits.push(...(await must(client.from('cliv2_workflow_stage_exits')
+                .select('workflow_id, stage_id, to_stage_id, condition, position').in('workflow_id', ids))) ?? []);
+            branches.push(...(await must(client.from('cliv2_workflow_branches')
+                .select('workflow_id, when_condition, runs_workflow_id, position').in('workflow_id', ids))) ?? []);
+        }
         const orgIds = [
             ...new Set([...stages.map((s) => s.org_id), ...workflows.map((w) => w.org_id)]),
         ];
@@ -7952,7 +7947,7 @@ export async function buildWorkflowHandler(client, args, fromAgent) {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
             if (typeof stage.body === 'string') {
-                assertAgentToolMentions(stage.body);
+                stage.body = authorToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
             }
         });
@@ -8050,7 +8045,7 @@ export async function editWorkflowHandler(client, args, fromAgent) {
                 prose.push([`stages[${index}].description`, stage.description]);
             }
             if (typeof stage.body === 'string') {
-                assertAgentToolMentions(stage.body);
+                stage.body = authorToolMentions(stage.body);
                 prose.push([`stages[${index}].body`, stage.body]);
             }
         });
@@ -8693,6 +8688,7 @@ export const TOOL_NAMES = [
     // 18c Slice 1: the run's own activity, unasked, on the request's card.
     'report_activity',
     'ask_question',
+    'require_approval',
     'present_wireframes',
     'present_mocks',
     'resolve_feedback',
@@ -8801,6 +8797,7 @@ const SERVER_INSTRUCTIONS = `You are connected to CTRL+SPC, where this user's wo
    - The PLAN for a work item: create_stage and create_step to lay it out, then update_step to record progress — in_progress when you start, a rewritten next_action as it changes, done when finished. Never create a second step to report on the first. These need a WORK ITEM and an approved scope: they are its committed plan, not a log of what you did. A panel request with no work item has no plan to write, so use report_activity and, if the work deserves an item of its own, ask for one. Never attach it to an unrelated work item to get past a refusal.
    - Anything learned, decided or discovered: record_user_input, add_comment, record_context_exploration, propose_project_context. The transcript is never the record.
    - Following a process: read_workflow_library, then start_workflow on the work item so its stages appear where the user can watch them.
+   - Creating a reusable workflow: build_workflow. Describe the requested process in its stages; do not execute those stages or create a plan artifact about creating the workflow. Ask only the clarification needed to author it, through ask_question. A work item used to hold this conversation does not turn workflow authoring into code implementation. ${WORKFLOW_AUTHORING_TEACHING}
    - A method the team has already written down: list_skills, then get_skill. A skill is a document TO FOLLOW for the rest of the work, not reference material to summarise. Look before improvising your own method.
    - A secret the work needs: list_credentials, then get_credential. Fetch it rather than asking the user for something they have already stored, and never write a value into a file, a commit, a log or your answer.
    Call list_tasks or get_task first when you need to know what the work is, and LOOK BEFORE YOU CREATE: if a work item already covers this, use it instead of adding a near-duplicate. If you are unsure whether a tool exists, look before falling back to the terminal.
@@ -10726,8 +10723,28 @@ runTodoIdSource = null) {
         touchSession(connectionId);
         return readWorkflowLibraryHandler(client, args, userId);
     });
+    server.registerTool('require_approval', {
+        description: 'Pause for the user to approve a specific action before you perform it, including editing code, running a migration, or pushing commits. Name its exact scope in action and details; use relative paths, never absolute local paths. Stop on pending or denial; retry the identical call after the answer. Only an approved result permits that action. This tool does not execute it. ' + WORKFLOW_TOOL_TEACHING,
+        inputSchema: {
+            action: z.string().trim().min(1).max(240),
+            details: z.string().trim().min(1).max(8000),
+            workflow_tool_instance: z.string().uuid().optional(),
+        },
+    }, async (args) => {
+        touchSession(connectionId);
+        try {
+            validateApprovalAction(args.action, args.details);
+            const session = openSessions.get(connectionId) ?? null;
+            await permissionForWorkflowCall(client, session, 'require_approval', args);
+            return runGated(client, userId, session, 'require_approval', args, `${args.action} — ${args.details}`, async () => textResult({ approved: true, action: args.action, details: args.details,
+                instruction: 'The user approved only this action and scope. You may now perform it.' }), await runTodoIdOf());
+        }
+        catch (error) {
+            return errorResult(errorMessage(error));
+        }
+    });
     server.registerTool('build_workflow', {
-        description: 'Build a WHOLE workflow in one call in CTRL+SPC — its stages, the order they run in, the ' +
+        description: WORKFLOW_AUTHORING_TEACHING + 'Build a WHOLE workflow in one call in CTRL+SPC — its stages, the order they run in, the ' +
             'loops back between them, and the branch conditions that apply everywhere. This is the ' +
             'only way to create a workflow: there is no create-stage tool, because assembling one ' +
             'piece at a time is the work this removes. ' +

package/dist/panel3/prompt.js

@@ -598,6 +598,12 @@ export function workBrief(level, responsibility, boundary, workItemId, attachmen
                 'time, and before any reading that takes a while. It does not end your turn and it is not',
                 'your reply; you carry on straight afterwards.',
                 '',
+                'WORKFLOW AUTHORING',
+                'When asked to create a workflow, use create_workflow to save it; do not execute the workflow.',
+                'Ask clarifying questions with ask_question only when the missing answer changes its behavior.',
+                'Write the requested tool mentions and per-use permissions in the stage bodies using the tool schema instructions.',
+                'The saved workflow appears as a reviewable card in this conversation. Do not substitute a plan artifact or a prose-only reply.',
+                '',
                 'TRACEABILITY BEFORE A CODEBASE FILE CHANGES',
                 'A codebase-file change means ANY file change: source, config, docs, tests, migrations,',
                 'generated inputs, and assets all count. "Non-code" means no codebase file changes at all.',

package/dist/panel3/tools.js

@@ -114,7 +114,7 @@
 // `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 { workflowToolForName, workflowToolAlwaysAllowed, validateApprovalAction } 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';
@@ -130,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, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING } from '../workflows.js';
+import { buildWorkflow, duplicateWorkflow, editWorkflow, readWorkflow, rewordStage, workflowToolPermission, validateWorkflowToolTarget, WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_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
@@ -749,6 +749,13 @@ function productResult(result) {
     return text;
 }
 const TOOLS = [
+    {
+        name: 'require_approval', levels: [1, 2],
+        description: 'Pause for the user to approve a specific action before you perform it, including editing code, running a migration, or pushing commits. Name the action and exact scope using relative paths, never absolute local paths. Stop on pending or denial and retry the identical call after the answer. Only an approved result permits that action. This tool does not execute it.',
+        input: { action: z.string().trim().min(1).max(240), details: z.string().trim().min(1).max(8000) },
+        handler: async (_caller, args) => JSON.stringify({ approved: true, action: args.action, details: args.details,
+            instruction: 'The user approved only this action and scope. You may now perform it.' }),
+    },
     {
         name: 'get_document', levels: ALL,
         description: 'Read a project context document or instruction in full by id. Read-only.',
@@ -1164,7 +1171,7 @@ const TOOLS = [
            described and can write it down as it was described. A launcher writes one
            line and exits; a worker owns one piece of somebody else's process. */
         levels: [2],
-        description: "Write a new workflow into this organisation's library: a name, what it is about, and its "
+        description: WORKFLOW_AUTHORING_TEACHING + "Write a new workflow into this organisation's library: a name, what it is about, and its "
             + 'stages in order, each with a one-line description and the markdown document an agent '
             + 'following it reads. Stages are numbered from 1, the way get_workflow prints them. exits '
             + 'are the conditional ways back: from_stage N, if condition, go back to to_stage M, where M '
@@ -3115,6 +3122,8 @@ async function invokeWorkflowTool(caller, tool, args) {
     const invoke = () => tool.handler(caller, inputs);
     if (!canonical || workflowToolAlwaysAllowed(canonical))
         return invoke();
+    if (canonical === 'require_approval')
+        validateApprovalAction(String(a.action), String(a.details));
     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;
@@ -3135,9 +3144,9 @@ async function invokeWorkflowTool(caller, tool, args) {
         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')
+    if (canonical !== 'require_approval' && (!permission || permission.approval === 'not-required'))
         return invoke();
-    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission.id, args: inputs });
+    const fingerprint = canonicalArgsHash({ tool: tool.name, workItemId, instance: permission?.id ?? null, 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);
@@ -3151,8 +3160,8 @@ async function invokeWorkflowTool(caller, tool, args) {
     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.',
+        question: canonical === 'require_approval' ? `May I ${String(a.action)}?` : `May I ${tool.name.replaceAll('_', ' ')}${a.title ? `: ${String(a.title).slice(0, 180)}` : ''}?`,
+        category, context: canonical === 'require_approval' ? String(a.details) : '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.');

package/dist/workflow-tool-mentions.js

@@ -1,6 +1,8 @@
+import { absolutePathToken } from './local-paths.js';
 /** Shared by the stage editor and both tool servers. The stage body remains
  * the record: each Markdown link names one invocation, never a tool-wide grant. */
 export const WORKFLOW_TOOLS = [
+    { id: 'require_approval', name: 'Require Approval', detail: 'Pause before any action, such as editing code, running migrations, or pushing commits.', alwaysAllowed: false, advanced: false },
     { id: 'create_artifact', name: 'Create Artifact', detail: 'Write a user story, plan, spec, diagram, or interactive mock.', alwaysAllowed: false, advanced: false },
     { id: 'update_artifact', name: 'Edit Artifact', detail: 'Revise an existing artifact.', alwaysAllowed: false, advanced: false },
     { id: 'ask_question', name: 'Ask Question', detail: 'Ask for feedback, a decision, or approval. Always available.', alwaysAllowed: true, advanced: false },
@@ -35,7 +37,7 @@ export function workflowToolForName(name) {
 }
 export function toolMentionText(tool, id, approval = 'required') {
     const entry = WORKFLOW_TOOLS.find(entry => entry.id === tool);
-    return `[@${entry.name}](ctrl-spc://tool/${tool}/${id}?approval=${workflowToolAlwaysAllowed(tool) ? 'not-required' : approval})`;
+    return `[@${entry.name}](ctrl-spc://tool/${tool}/${id}?approval=${tool === 'require_approval' ? 'required' : workflowToolAlwaysAllowed(tool) ? 'not-required' : approval})`;
 }
 export function toolMentions(body) {
     const mentions = [];
@@ -45,7 +47,7 @@ export function toolMentions(body) {
             continue;
         mentions.push({
             id: match[2], tool: match[1],
-            approval: workflowToolAlwaysAllowed(match[1]) ? 'not-required' : match[3],
+            approval: match[1] === 'require_approval' ? 'required' : workflowToolAlwaysAllowed(match[1]) ? 'not-required' : match[3],
             from: match.index, to: match.index + match[0].length,
         });
     }
@@ -78,6 +80,7 @@ export const WORKFLOW_TOOL_TEACHING = 'Tool mentions in workflow stage documents
     'the tool itself opens the permission question before writing anything. Do not open a separate ask_question for permission to use that tool. ' +
     'When the user approves that tool question, retry the same call with exactly the same arguments. Read tools and Ask Question never need permission. Permission does not grant access to another project or change your agent level. If an action is only available to your coordinator, escalate that action with its mention id. ' +
     'Approval to use a tool is separate from approval of its output: still ask every review question written in the stage. Present Mock and Present Wireframe open their own output review; do not ask a duplicate review question. Proposing a scope or context change never accepts it. ' +
+    'Require Approval is a separate checkpoint for ANY action, including native shell and code tools: call require_approval with the specific action and its scope BEFORE doing it, then stop until that tool returns approval. It does not execute the action or approve other actions. Do not use ask_question instead of this checkpoint. ' +
     'If your level cannot ask the user, escalate the review to the conversation owner and stop.';
 /** Agents may preserve existing settings, but cannot author their own grants. */
 export function assertAgentToolMentions(body, previous = '') {
@@ -91,3 +94,35 @@ export function assertAgentToolMentions(body, previous = '') {
         }
     }
 }
+/** Library authoring accepts compact links; the server owns occurrence IDs so
+ * agent-created mentions render exactly like ones inserted in the editor. */
+export function authorToolMentions(body) {
+    const expanded = body.replace(/\[@[^\]\n]+\]\(ctrl-spc:\/\/tool\/([a-z_]+)\?approval=(required|not-required)\)/g, (_match, name, approval) => {
+        const tool = workflowToolForName(name);
+        if (!tool)
+            throw new Error(`Unknown workflow tool: ${name}. Nothing was written.`);
+        return toolMentionText(tool, crypto.randomUUID(), approval);
+    });
+    validateToolMentions(expanded);
+    let result = expanded;
+    for (const mention of toolMentions(expanded).reverse()) {
+        result = result.slice(0, mention.from) + toolMentionText(mention.tool, crypto.randomUUID(), mention.approval) + result.slice(mention.to);
+    }
+    return result;
+}
+export const WORKFLOW_AUTHORING_TEACHING = 'When the user asks you to create a workflow, build it in the library; do not merely describe it or execute it. ' +
+    'Use ask_question for missing requirements that materially change the workflow, then continue after the answer. ' +
+    'Encode every requested tool use and permission as a Markdown mention in the stage body. ' +
+    'Use compact links: [@Create Artifact](ctrl-spc://tool/create_artifact?approval=not-required) to write a plan without asking; ' +
+    '[@Ask Question](ctrl-spc://tool/ask_question?approval=not-required) to review its output; ' +
+    'before editing code, [@Require Approval](ctrl-spc://tool/require_approval?approval=required). ' +
+    'The server assigns unique IDs and the user sees editable controls in the stage editor. ' +
+    'Set not-required only when the user permits that use. Otherwise default to required. Never convert permission to write a plan into permission to execute it. ' +
+    'Each occurrence has its own setting. Put the action and scope beside each Require Approval mention, including migrations or pushing commits. ' +
+    'Available tool IDs: ' + WORKFLOW_TOOLS.map(tool => `${tool.id} (${tool.name})`).join(', ') + '. ';
+/** Approval prose is displayed in the hosted app; keep machine-local paths local. */
+export function validateApprovalAction(action, details) {
+    if (absolutePathToken(action) || absolutePathToken(details)) {
+        throw new Error('Use repo-relative or scratch-relative paths in the approval action and scope, never absolute local paths. No approval was requested.');
+    }
+}

package/dist/workflows.js

@@ -1,7 +1,7 @@
 import { absolutePathToken } from './local-paths.js';
 import { listSteps } from './steps.js';
-import { assertAgentToolMentions, toolMentions, validateToolMentions } from './workflow-tool-mentions.js';
-export { WORKFLOW_TOOL_TEACHING, assertAgentToolMentions } from './workflow-tool-mentions.js';
+import { assertAgentToolMentions, authorToolMentions, toolMentions, validateToolMentions } from './workflow-tool-mentions.js';
+export { WORKFLOW_TOOL_TEACHING, WORKFLOW_AUTHORING_TEACHING, authorToolMentions, assertAgentToolMentions } from './workflow-tool-mentions.js';
 /** Resolve permission from the current stage's saved document, never agent
  * prose or a supplied boolean. Both harnesses use the same stage resolver. */
 export async function workflowToolPermission(client, workItemId, tool, instance) {
@@ -140,7 +140,7 @@ export async function readWorkflow(client, workflowId) {
 export async function buildWorkflow(client, input) {
     const prose = [['name', input.name], ['description', input.description]];
     input.stages.forEach((stage, i) => {
-        assertAgentToolMentions(stage.body);
+        stage.body = authorToolMentions(stage.body);
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));
@@ -253,7 +253,7 @@ export async function editWorkflow(client, input) {
     input.stages.forEach((stage, i) => {
         if ('stage_id' in stage)
             return;
-        assertAgentToolMentions(stage.body);
+        stage.body = authorToolMentions(stage.body);
         prose.push([`stage ${i + 1} name`, stage.name], [`stage ${i + 1} description`, stage.description], [`stage ${i + 1} body`, stage.body]);
     });
     input.exits.forEach((exit, i) => prose.push([`exit ${i + 1} condition`, exit.condition]));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ctrl-spc/cs",
-  "version": "0.7.8",
+  "version": "0.7.9",
   "description": "CTRL+SPC — minimal, reliable per-machine agent presence. Sign-in, auto-start, agent detection, heartbeat presence, and ping acknowledgement.",
   "engines": {
     "node": ">=22"