@shirlytaylor73/superharness 1.5.0

package/plugins/superharness/workflow-state-server/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "superharness-workflow-state-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "private": true,
+  "main": "server.js",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "better-sqlite3": "^12.0.0",
+    "yaml": "^2.8.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.0"
+  }
+}

package/plugins/superharness/workflow-state-server/render-context.js

@@ -0,0 +1,124 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const SKILL_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+function requireStateNode(workflowGraph, stateName) {
+  const node = workflowGraph?.states?.get(stateName);
+  if (!node) {
+    throw new Error(`workflow state not found: ${stateName}`);
+  }
+  return node;
+}
+
+export function stripFrontmatter(markdown) {
+  return markdown.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '');
+}
+
+export function resolveSkillPath({ skillsDir, skillName }) {
+  if (!SKILL_NAME_PATTERN.test(skillName)) {
+    throw new Error(`invalid skill name: ${skillName}`);
+  }
+  const skillPath = path.join(skillsDir, skillName, 'SKILL.md');
+  if (!fs.existsSync(skillPath)) {
+    throw new Error(`skill not found: ${skillName}`);
+  }
+  return skillPath;
+}
+
+function renderFacts({ stateInfo, node }) {
+  return [
+    'Runtime facts:',
+    `- current_state: ${stateInfo.state}`,
+    `- previous_state: ${stateInfo.previous_state ?? 'null'}`,
+    `- active_skill: ${stateInfo.active_skill ?? node.skill ?? 'null'}`,
+    `- allowed_transitions: ${JSON.stringify(node.next)}`,
+    '- state_directory: .superharness/',
+  ].join('\n');
+}
+
+function renderRules() {
+  return [
+    'Rules:',
+    '- Follow the active skill below for this turn.',
+    '- If the state exit condition is met, call transition_state with a non-empty reason.',
+    '- Do not edit .superharness/ directly.',
+    '- If workflow config or state cannot be loaded, stop business work and report the error.',
+  ].join('\n');
+}
+
+function renderRouterGuard() {
+  return [
+    'Router guard:',
+    '- Select serial_execution or parallel_execution based on the written plan and platform capability.',
+    '- If execution cannot safely proceed, transition to systematic_debugging with a concrete reason.',
+  ].join('\n');
+}
+
+export function renderWorkflowContext({ stateInfo, workflowGraph, skillsDir }) {
+  if (!stateInfo?.state) {
+    throw new Error('stateInfo.state is required');
+  }
+
+  const node = requireStateNode(workflowGraph, stateInfo.state);
+  const parts = [
+    '<SUPERHARNESS_WORKFLOW_STATE>',
+    renderFacts({ stateInfo, node }),
+    '',
+    renderRules(),
+  ];
+
+  if (node.type === 'router') {
+    parts.push('', renderRouterGuard(), '</SUPERHARNESS_WORKFLOW_STATE>');
+    return parts.join('\n') + renderStrictAppendix({ silent_stop_allowed: node.silent_stop_allowed });
+  }
+
+  const skillName = stateInfo.active_skill ?? node.skill;
+  if (skillName) {
+    const skillPath = resolveSkillPath({ skillsDir, skillName });
+    const skillContent = stripFrontmatter(fs.readFileSync(skillPath, 'utf8')).trim();
+    parts.push('', `--- Active skill: ${skillName} ---`, skillContent);
+  }
+
+  parts.push('</SUPERHARNESS_WORKFLOW_STATE>');
+  return parts.join('\n') + renderStrictAppendix({ silent_stop_allowed: node.silent_stop_allowed });
+}
+
+export function renderActiveSkill({ stateName, skillsDir, skillName }) {
+  // State 名可能是 underscore (serial_execution)，skill 目录是 hyphen (serial-execution)。
+  // 若 caller 显式提供 skillName（来自 graph.states.get(state).skill），用它做目录查找；
+  // 否则回退到 stateName（兼容 1:1 命名的 state，如 intake/trivial/planning）。
+  const lookupName = skillName ?? stateName;
+  const skillPath = resolveSkillPath({ skillsDir, skillName: lookupName });
+  const skillContent = stripFrontmatter(fs.readFileSync(skillPath, 'utf8')).trim();
+  return [
+    `[Superharness] 已切到新状态，本轮继续遵循以下 SKILL：`,
+    ``,
+    `--- Active skill: ${stateName} ---`,
+    skillContent,
+  ].join('\n');
+}
+
+export function renderStrictAppendix({ silent_stop_allowed }) {
+  if (silent_stop_allowed) return '';
+  return [
+    '',
+    '⚠ 当前 state 不允许本轮沉默结束——必须在本轮调用 transition_state 切到下一态，',
+    '若本轮工作未完成请继续完成再切；若无法继续请用 AskUserQuestion 让用户决定。',
+  ].join('\n');
+}
+
+export function renderStopWorkContext({ reason }) {
+  return [
+    '<SUPERHARNESS_WORKFLOW_STATE>',
+    'Runtime status: unavailable',
+    `Reason: ${reason || 'workflow state context could not be loaded'}`,
+    '',
+    'Rules:',
+    '- Stop business work.',
+    '- Report the workflow error to the user.',
+    '- Do not invent workflow state.',
+    '- Do not edit .superharness/ directly.',
+    '</SUPERHARNESS_WORKFLOW_STATE>',
+  ].join('\n');
+}

package/plugins/superharness/workflow-state-server/schema.sql

@@ -0,0 +1,39 @@
+CREATE TABLE IF NOT EXISTS workflow_state (
+  workspace_id TEXT PRIMARY KEY,
+  state TEXT NOT NULL,
+  status TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','completed')),
+  previous_state TEXT,
+  active_skill TEXT,
+  task_summary TEXT,
+  failure_summary TEXT,
+  updated_at INTEGER NOT NULL,
+  free_mode INTEGER NOT NULL DEFAULT 0,
+  free_started_at INTEGER
+);
+
+CREATE TABLE IF NOT EXISTS workflow_transition_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  workspace_id TEXT NOT NULL,
+  from_state TEXT,
+  to_state TEXT NOT NULL,
+  previous_state TEXT,
+  reason TEXT NOT NULL,
+  source TEXT NOT NULL CHECK (source IN ('hook','agent-tool','user-reset')),
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_workflow_transition_workspace
+  ON workflow_transition_log(workspace_id, id);
+
+CREATE TABLE IF NOT EXISTS workflow_turn (
+  workspace_id TEXT PRIMARY KEY,
+  turn_id TEXT NOT NULL,
+  block_count INTEGER NOT NULL DEFAULT 0,
+  stop_block_released INTEGER NOT NULL DEFAULT 0,
+  release_reason TEXT,
+  created_at INTEGER NOT NULL
+);
+
+-- Note: idx_workflow_transition_turn is created in state.js::ensureTurnIdColumn
+-- because the turn_id column is added via ALTER for backwards compatibility
+-- with pre-v1.3.0 databases.

package/plugins/superharness/workflow-state-server/server.js

@@ -0,0 +1,290 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { loadWorkflowConfig, buildWorkflowGraph } from './validate-workflow.js';
+import {
+  openWorkflowStateStore,
+  getWorkflowState,
+  classifyRequest,
+  transitionWorkflowState,
+  listWorkflowHistory,
+  resolveWorkflowDbPath,
+  getTurn,
+  releaseTurnBlock,
+  assertNotFreeMode,
+} from './state.js';
+import { renderWorkflowContext } from './render-context.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const DEFAULT_PLUGIN_ROOT = path.resolve(__dirname, '..');
+
+function loadInstalledSkills(pluginRoot = DEFAULT_PLUGIN_ROOT) {
+  const skillsDir = path.join(pluginRoot, 'skills');
+  if (!fs.existsSync(skillsDir)) return new Set();
+  return new Set(
+    fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .filter((entry) => fs.existsSync(path.join(skillsDir, entry.name, 'SKILL.md')))
+      .map((entry) => entry.name),
+  );
+}
+
+function createRuntime({
+  workspaceRoot = process.cwd(),
+  pluginRoot = DEFAULT_PLUGIN_ROOT,
+} = {}) {
+  const config = loadWorkflowConfig({ pluginRoot, workspaceRoot });
+  const workflowGraph = buildWorkflowGraph(config, {
+    installedSkills: loadInstalledSkills(pluginRoot),
+  });
+  const store = openWorkflowStateStore({
+    mode: process.env.SUPERHARNESS_WORKFLOW_STATE_MODE,
+    dbPath: process.env.SUPERHARNESS_WORKFLOW_STATE_DB
+      ?? resolveWorkflowDbPath({ workspaceRoot }),
+  });
+
+  return {
+    store,
+    workflowGraph,
+    skillsDir: path.join(pluginRoot, 'skills'),
+  };
+}
+
+let defaultRuntime;
+function getDefaultRuntime() {
+  if (!defaultRuntime) {
+    defaultRuntime = createRuntime();
+  }
+  return defaultRuntime;
+}
+
+function wrap(handler) {
+  return async (args = {}) => {
+    try {
+      return await handler(args);
+    } catch (error) {
+      return {
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+  };
+}
+
+const RELEASE_STOP_BLOCK_DESCRIPTION =
+  '在 silent_stop_allowed=false 的 state 内 agent 无法继续工作时，由用户通过 AskUserQuestion 明确授权"终止本轮"后调用此工具。绝不可在没有用户明确授权前调用。';
+
+const PLACEHOLDER_REASONS = new Set(['ok', 'start', '用户请求']);
+
+export async function handleReleaseStopBlock({ store, args }) {
+  const { workspaceRoot, reason } = args ?? {};
+  assertNotFreeMode(store, workspaceRoot);
+  const trimmed = typeof reason === 'string' ? reason.trim() : '';
+  if (!trimmed || PLACEHOLDER_REASONS.has(trimmed)) {
+    throw new Error('reason must be non-empty and non-placeholder');
+  }
+  const turnRow = getTurn(store, { workspaceRoot });
+  if (!turnRow) {
+    throw new Error('no active turn for workspace');
+  }
+  releaseTurnBlock(store, { workspaceRoot, reason: trimmed });
+
+  // audit: write a transition_log row tagged with [escape] prefix.
+  // schema requires to_state NOT NULL, so use current workflow_state.state
+  // (or a sentinel if no workflow_state row exists yet).
+  const resolvedWorkspaceId = path.resolve(workspaceRoot);
+  const stateRow = store.prepare(
+    'SELECT state FROM workflow_state WHERE workspace_id = ?',
+  ).get(resolvedWorkspaceId);
+  const sentinelState = stateRow?.state ?? 'turn';
+  const turnIdRow = store.prepare(
+    'SELECT turn_id FROM workflow_turn WHERE workspace_id = ?',
+  ).get(resolvedWorkspaceId);
+  store.prepare(`
+    INSERT INTO workflow_transition_log (
+      workspace_id, from_state, to_state, previous_state, reason, source, turn_id, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(
+    resolvedWorkspaceId,
+    sentinelState,
+    sentinelState,
+    null,
+    `[escape] ${trimmed}`,
+    'agent-tool',
+    turnIdRow?.turn_id ?? null,
+    Date.now(),
+  );
+
+  return { ok: true };
+}
+
+export function createTools(getRuntime = getDefaultRuntime) {
+  return [
+    {
+      name: 'get_state',
+      description: 'Return current workflow state and rendered workflow context.',
+      inputSchema: {
+        type: 'object',
+        required: ['workspaceRoot'],
+        properties: {
+          workspaceRoot: { type: 'string' },
+        },
+      },
+      handler: wrap((args) => {
+        const runtime = getRuntime();
+        const state = getWorkflowState(runtime.store, {
+          workspaceRoot: args.workspaceRoot,
+          workflowGraph: runtime.workflowGraph,
+        });
+        return {
+          ...state,
+          context: renderWorkflowContext({
+            stateInfo: state,
+            workflowGraph: runtime.workflowGraph,
+            skillsDir: runtime.skillsDir,
+          }),
+        };
+      }),
+    },
+    {
+      name: 'classify_request',
+      description: 'Record a task or failure summary for the active workflow.',
+      inputSchema: {
+        type: 'object',
+        required: ['workspaceRoot', 'reason'],
+        properties: {
+          workspaceRoot: { type: 'string' },
+          task_summary: { type: 'string' },
+          failure_summary: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      handler: wrap((args) => {
+        const runtime = getRuntime();
+        return classifyRequest(runtime.store, {
+          workspaceRoot: args.workspaceRoot,
+          workflowGraph: runtime.workflowGraph,
+          task_summary: args.task_summary,
+          failure_summary: args.failure_summary,
+          reason: args.reason,
+        });
+      }),
+    },
+    {
+      name: 'transition_state',
+      description: 'Validate and execute a workflow state transition.',
+      inputSchema: {
+        type: 'object',
+        required: ['workspaceRoot', 'from_state', 'to_state', 'reason'],
+        properties: {
+          workspaceRoot: { type: 'string' },
+          from_state: { type: 'string' },
+          to_state: { type: 'string' },
+          previous_state: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      handler: wrap((args) => {
+        const runtime = getRuntime();
+        return transitionWorkflowState(runtime.store, {
+          workspaceRoot: args.workspaceRoot,
+          workflowGraph: runtime.workflowGraph,
+          from_state: args.from_state,
+          to_state: args.to_state,
+          previous_state: args.previous_state,
+          reason: args.reason,
+          source: 'agent-tool',
+        });
+      }),
+    },
+    {
+      name: 'list_history',
+      description: 'List workflow transition history for a workspace.',
+      inputSchema: {
+        type: 'object',
+        required: ['workspaceRoot'],
+        properties: {
+          workspaceRoot: { type: 'string' },
+        },
+      },
+      handler: wrap((args) => {
+        const runtime = getRuntime();
+        return listWorkflowHistory(runtime.store, {
+          workspaceRoot: args.workspaceRoot,
+        });
+      }),
+    },
+    {
+      name: 'release_stop_block',
+      description: RELEASE_STOP_BLOCK_DESCRIPTION,
+      inputSchema: {
+        type: 'object',
+        required: ['workspaceRoot', 'reason'],
+        properties: {
+          workspaceRoot: { type: 'string' },
+          reason: { type: 'string' },
+        },
+      },
+      handler: wrap((args) => {
+        const runtime = getRuntime();
+        return handleReleaseStopBlock({ store: runtime.store, args });
+      }),
+    },
+  ];
+}
+
+export const TOOLS = createTools(getDefaultRuntime);
+
+export function createMcpServer({ tools = TOOLS } = {}) {
+  const server = new Server(
+    {
+      name: 'superharness-workflow-state',
+      version: '0.1.0',
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({
+      name,
+      description,
+      inputSchema,
+    })),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const tool = tools.find((candidate) => candidate.name === request.params.name);
+    if (!tool) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: `unknown tool: ${request.params.name}` }],
+      };
+    }
+
+    const result = await tool.handler(request.params.arguments ?? {});
+    return {
+      isError: !!result?.error,
+      content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    };
+  });
+
+  return server;
+}
+
+export async function main() {
+  const server = createMcpServer();
+  await server.connect(new StdioServerTransport());
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  await main();
+}