@shirlytaylor73/superharness 1.5.0

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

@@ -0,0 +1,424 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const IS_BUN = typeof process !== 'undefined' && !!process.versions?.bun;
+const Database = IS_BUN
+  ? (await import('bun:sqlite')).Database
+  : (await import('better-sqlite3')).default;
+
+const VALID_SOURCES = new Set(['hook', 'agent-tool', 'user-reset']);
+
+function now() {
+  return Date.now();
+}
+
+function requireReason(reason) {
+  if (typeof reason !== 'string' || reason.trim() === '') {
+    throw new Error('reason must be a non-empty string');
+  }
+  return reason.trim();
+}
+
+function requireWorkspaceRoot(workspaceRoot) {
+  if (typeof workspaceRoot !== 'string' || workspaceRoot.trim() === '') {
+    throw new Error('workspaceRoot must be a non-empty string');
+  }
+  return path.resolve(workspaceRoot);
+}
+
+function requireWorkflowGraph(workflowGraph) {
+  if (!workflowGraph?.states || !workflowGraph?.entryState) {
+    throw new Error('workflowGraph is required');
+  }
+  return workflowGraph;
+}
+
+function activeSkillFor(workflowGraph, stateName) {
+  return workflowGraph.states.get(stateName)?.skill ?? null;
+}
+
+function statusFor(workflowGraph, stateName) {
+  return workflowGraph.states.get(stateName)?.terminal ? 'completed' : 'active';
+}
+
+function normalizeSource(source = 'agent-tool') {
+  if (!VALID_SOURCES.has(source)) {
+    throw new Error(`invalid source: ${source}`);
+  }
+  return source;
+}
+
+function readSchema() {
+  return fs.readFileSync(
+    path.join(path.dirname(fileURLToPath(import.meta.url)), 'schema.sql'),
+    'utf8',
+  );
+}
+
+export function ensureTurnIdColumn(db) {
+  const columns = db.prepare("PRAGMA table_info(workflow_transition_log)").all();
+  const hasTurnId = columns.some((c) => c.name === 'turn_id');
+  if (!hasTurnId) {
+    db.exec("ALTER TABLE workflow_transition_log ADD COLUMN turn_id TEXT");
+  }
+  db.exec("CREATE INDEX IF NOT EXISTS idx_workflow_transition_turn ON workflow_transition_log(turn_id)");
+}
+
+export function ensureFreeModeColumns(db) {
+  const columns = db.prepare("PRAGMA table_info(workflow_state)").all();
+  const names = new Set(columns.map((c) => c.name));
+  if (!names.has('free_mode')) {
+    db.exec("ALTER TABLE workflow_state ADD COLUMN free_mode INTEGER NOT NULL DEFAULT 0");
+  }
+  if (!names.has('free_started_at')) {
+    db.exec("ALTER TABLE workflow_state ADD COLUMN free_started_at INTEGER");
+  }
+}
+
+export function readFreeMode(store, workspaceRoot) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  const row = store.prepare(
+    'SELECT free_mode FROM workflow_state WHERE workspace_id = ?'
+  ).get(workspaceId);
+  return row?.free_mode === 1;
+}
+
+export function assertNotFreeMode(store, workspaceRoot) {
+  if (readFreeMode(store, workspaceRoot)) {
+    throw new Error('workspace is in free mode; /free off first');
+  }
+}
+
+export function createTurn(store, { workspaceRoot, turnId }) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  store.db.prepare(`
+    INSERT OR REPLACE INTO workflow_turn
+    (workspace_id, turn_id, block_count, stop_block_released, release_reason, created_at)
+    VALUES (?, ?, 0, 0, NULL, ?)
+  `).run(workspaceId, turnId, now());
+}
+
+export function getTurn(store, { workspaceRoot }) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  return store.db.prepare('SELECT * FROM workflow_turn WHERE workspace_id = ?').get(workspaceId) ?? null;
+}
+
+export function incrementBlockCount(store, { workspaceRoot }) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  store.db.prepare('UPDATE workflow_turn SET block_count = block_count + 1 WHERE workspace_id = ?').run(workspaceId);
+}
+
+export function releaseTurnBlock(store, { workspaceRoot, reason }) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  store.db.prepare('UPDATE workflow_turn SET stop_block_released = 1, release_reason = ? WHERE workspace_id = ?').run(reason, workspaceId);
+}
+
+function normalizeRow(row) {
+  if (!row) return null;
+  return {
+    workspace_id: row.workspace_id,
+    state: row.state,
+    status: row.status,
+    previous_state: row.previous_state ?? null,
+    active_skill: row.active_skill ?? null,
+    task_summary: row.task_summary ?? null,
+    failure_summary: row.failure_summary ?? null,
+    updated_at: row.updated_at,
+    free_mode: row.free_mode === 1,
+    free_started_at: row.free_started_at ?? null,
+  };
+}
+
+function getRow(store, workspaceId) {
+  return normalizeRow(
+    store.prepare('SELECT * FROM workflow_state WHERE workspace_id = ?').get(workspaceId),
+  );
+}
+
+function insertLog(store, {
+  workspaceId,
+  fromState,
+  toState,
+  previousState,
+  reason,
+  source,
+  createdAt = now(),
+}) {
+  const turnRow = store.prepare('SELECT turn_id FROM workflow_turn WHERE workspace_id = ?').get(workspaceId);
+  const turnId = turnRow?.turn_id ?? null;
+  store.prepare(`
+    INSERT INTO workflow_transition_log (
+      workspace_id, from_state, to_state, previous_state, reason, source, turn_id, created_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(workspaceId, fromState ?? null, toState, previousState ?? null, reason, source, turnId, createdAt);
+}
+
+function upsertState(store, {
+  workspaceId,
+  workflowGraph,
+  state,
+  previousState = null,
+  taskSummary = null,
+  failureSummary = null,
+  updatedAt = now(),
+}) {
+  store.prepare(`
+    INSERT INTO workflow_state (
+      workspace_id, state, status, previous_state, active_skill,
+      task_summary, failure_summary, updated_at
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(workspace_id) DO UPDATE SET
+      state = excluded.state,
+      status = excluded.status,
+      previous_state = excluded.previous_state,
+      active_skill = excluded.active_skill,
+      task_summary = excluded.task_summary,
+      failure_summary = excluded.failure_summary,
+      updated_at = excluded.updated_at
+  `).run(
+    workspaceId,
+    state,
+    statusFor(workflowGraph, state),
+    previousState,
+    activeSkillFor(workflowGraph, state),
+    taskSummary,
+    failureSummary,
+    updatedAt,
+  );
+  return getRow(store, workspaceId);
+}
+
+function assertTransitionAllowed(workflowGraph, fromState, toState) {
+  const fromNode = workflowGraph.states.get(fromState);
+  if (!fromNode) {
+    throw new Error(`unknown from_state: ${fromState}`);
+  }
+  if (!fromNode.next.includes(toState)) {
+    throw new Error(`transition ${fromState} -> ${toState} is not allowed`);
+  }
+}
+
+const LEGACY_STATE_MAP = {
+  done: 'intake',
+  execution_choice: 'planning',
+};
+
+function migrateLegacyState(store, workspaceId, current) {
+  if (!current) return current;
+  const target = LEGACY_STATE_MAP[current.state];
+  if (!target) return current;
+
+  const updatedAt = now();
+  store.prepare(`
+    UPDATE workflow_state
+       SET state = ?,
+           status = 'active',
+           previous_state = NULL,
+           active_skill = NULL,
+           updated_at = ?
+     WHERE workspace_id = ?
+  `).run(target, updatedAt, workspaceId);
+
+  insertLog(store, {
+    workspaceId,
+    fromState: current.state,
+    toState: target,
+    previousState: null,
+    reason: `legacy migration: ${current.state} -> ${target} (state removed in v3 state machine)`,
+    source: 'user-reset',
+    createdAt: updatedAt,
+  });
+
+  return getRow(store, workspaceId);
+}
+
+export { migrateLegacyState };
+
+export function resolveWorkflowDbPath({ workspaceRoot } = {}) {
+  if (process.env.SUPERHARNESS_WORKFLOW_STATE_DB) {
+    return process.env.SUPERHARNESS_WORKFLOW_STATE_DB;
+  }
+  return path.join(requireWorkspaceRoot(workspaceRoot ?? process.cwd()), '.superharness', 'workflow-state.db');
+}
+
+export function openWorkflowStateStore({ dbPath, mode } = {}) {
+  const resolvedDbPath = mode === 'memory' ? ':memory:' : path.resolve(dbPath ?? resolveWorkflowDbPath());
+  if (resolvedDbPath !== ':memory:') {
+    fs.mkdirSync(path.dirname(resolvedDbPath), { recursive: true });
+  }
+
+  const db = new Database(resolvedDbPath);
+  const store = {
+    db,
+    path: resolvedDbPath,
+    exec(sql) {
+      return db.exec(sql);
+    },
+    prepare(sql) {
+      return typeof db.prepare === 'function' ? db.prepare(sql) : db.query(sql);
+    },
+    close() {
+      return db.close();
+    },
+  };
+
+  if (resolvedDbPath !== ':memory:') {
+    store.exec('PRAGMA journal_mode = WAL');
+  }
+  store.exec('PRAGMA foreign_keys = ON');
+  store.exec(readSchema());
+  ensureTurnIdColumn(store);
+  ensureFreeModeColumns(store);
+
+  return store;
+}
+
+export function initializeWorkflowState(store, {
+  workspaceRoot,
+  workflowGraph,
+  reason = 'initialize workflow state',
+} = {}) {
+  const graph = requireWorkflowGraph(workflowGraph);
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  const existing = getRow(store, workspaceId);
+  if (existing) {
+    return migrateLegacyState(store, workspaceId, existing) ?? existing;
+  }
+
+  const trimmedReason = requireReason(reason);
+  const state = upsertState(store, {
+    workspaceId,
+    workflowGraph: graph,
+    state: graph.entryState,
+  });
+  insertLog(store, {
+    workspaceId,
+    fromState: null,
+    toState: graph.entryState,
+    previousState: null,
+    reason: trimmedReason,
+    source: 'hook',
+  });
+  return state;
+}
+
+export function getWorkflowState(store, { workspaceRoot, workflowGraph } = {}) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  const existing = getRow(store, workspaceId);
+  if (existing) {
+    return migrateLegacyState(store, workspaceId, existing) ?? existing;
+  }
+  if (!workflowGraph) {
+    return null;
+  }
+  return initializeWorkflowState(store, {
+    workspaceRoot,
+    workflowGraph,
+    reason: 'initialize workflow state',
+  });
+}
+
+export function classifyRequest(store, {
+  workspaceRoot,
+  workflowGraph,
+  task_summary = null,
+  failure_summary = null,
+  reason,
+} = {}) {
+  assertNotFreeMode(store, workspaceRoot);
+  const graph = requireWorkflowGraph(workflowGraph);
+  const trimmedReason = requireReason(reason);
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  const current = getWorkflowState(store, { workspaceRoot, workflowGraph: graph });
+
+  const updated = upsertState(store, {
+    workspaceId,
+    workflowGraph: graph,
+    state: current.state,
+    previousState: current.previous_state,
+    taskSummary: task_summary,
+    failureSummary: failure_summary,
+  });
+  insertLog(store, {
+    workspaceId,
+    fromState: current.state,
+    toState: current.state,
+    previousState: current.previous_state,
+    reason: trimmedReason,
+    source: 'agent-tool',
+  });
+  return updated;
+}
+
+export function transitionWorkflowState(store, {
+  workspaceRoot,
+  workflowGraph,
+  from_state,
+  to_state,
+  previous_state = null,
+  reason,
+  source = 'agent-tool',
+} = {}) {
+  assertNotFreeMode(store, workspaceRoot);
+  const graph = requireWorkflowGraph(workflowGraph);
+  const trimmedReason = requireReason(reason);
+  const normalizedSource = normalizeSource(source);
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  const current = getWorkflowState(store, { workspaceRoot, workflowGraph: graph });
+
+  if (from_state !== current.state) {
+    throw new Error(`from_state ${from_state} does not match current state ${current.state}`);
+  }
+
+  let target = to_state;
+  if (target === 'previous_state') {
+    if (current.state !== 'systematic_debugging') {
+      throw new Error('previous_state transition is only valid from systematic_debugging');
+    }
+    assertTransitionAllowed(graph, current.state, 'previous_state');
+    if (!current.previous_state) {
+      throw new Error('previous_state transition has no recorded previous_state');
+    }
+    target = current.previous_state;
+  } else {
+    assertTransitionAllowed(graph, current.state, target);
+  }
+
+  if (!graph.states.has(target)) {
+    throw new Error(`unknown to_state: ${target}`);
+  }
+
+  const nextPreviousState = target === 'systematic_debugging'
+    ? (previous_state || current.state)
+    : null;
+
+  const updated = upsertState(store, {
+    workspaceId,
+    workflowGraph: graph,
+    state: target,
+    previousState: nextPreviousState,
+    taskSummary: current.task_summary,
+    failureSummary: current.failure_summary,
+  });
+  insertLog(store, {
+    workspaceId,
+    fromState: current.state,
+    toState: target,
+    previousState: nextPreviousState,
+    reason: trimmedReason,
+    source: normalizedSource,
+  });
+  return updated;
+}
+
+export function listWorkflowHistory(store, { workspaceRoot } = {}) {
+  const workspaceId = requireWorkspaceRoot(workspaceRoot);
+  return store.prepare(`
+    SELECT id, workspace_id, from_state, to_state, previous_state, reason, source, created_at
+    FROM workflow_transition_log
+    WHERE workspace_id = ?
+    ORDER BY id ASC
+  `).all(workspaceId);
+}
+

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

@@ -0,0 +1,165 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import YAML from 'yaml';
+
+const SPECIAL_TARGETS = new Set(['previous_state']);
+
+function fail(message) {
+  throw new Error(`invalid workflow config: ${message}`);
+}
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeStringList(value, field) {
+  if (!Array.isArray(value)) {
+    fail(`${field} must be an array`);
+  }
+  for (const item of value) {
+    if (typeof item !== 'string' || item.trim() === '') {
+      fail(`${field} must contain only non-empty strings`);
+    }
+  }
+  return value;
+}
+
+function defaultPluginRoot() {
+  return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+
+export function loadWorkflowConfig({ pluginRoot, workspaceRoot } = {}) {
+  const resolvedPluginRoot = pluginRoot ? path.resolve(pluginRoot) : defaultPluginRoot();
+  const candidates = [];
+
+  if (workspaceRoot) {
+    candidates.push(path.join(path.resolve(workspaceRoot), '.superharness', 'workflow.yaml'));
+  }
+  candidates.push(path.join(resolvedPluginRoot, 'workflow', 'default-workflow.yaml'));
+
+  const configPath = candidates.find((candidate) => fs.existsSync(candidate));
+  if (!configPath) {
+    fail(`workflow file not found in ${candidates.join(', ')}`);
+  }
+
+  const content = fs.readFileSync(configPath, 'utf8');
+  const parsed = YAML.parse(content);
+  if (!isObject(parsed)) {
+    fail(`${configPath} must contain a workflow object`);
+  }
+  return parsed;
+}
+
+export function validateWorkflowConfig(config, { installedSkills } = {}) {
+  if (!isObject(config)) {
+    fail('root must be an object');
+  }
+  if (config.version !== 1) {
+    fail('version must be 1');
+  }
+  if (typeof config.entryState !== 'string' || config.entryState.trim() === '') {
+    fail('entryState must be a non-empty string');
+  }
+  if (!isObject(config.states)) {
+    fail('states must be an object');
+  }
+  if (!Object.hasOwn(config.states, config.entryState)) {
+    fail(`entryState references missing state ${config.entryState}`);
+  }
+
+  // intake hard constraint (v3 state machine requires intake as entryState)
+  if (!Object.hasOwn(config.states, 'intake')) {
+    fail('intake state must exist (entry state for v3 state machine)');
+  }
+  if (config.entryState !== 'intake') {
+    fail(`entryState must be 'intake', got '${config.entryState}'`);
+  }
+
+  const terminalStates = normalizeStringList(config.terminalStates ?? [], 'terminalStates');
+  const terminalSet = new Set(terminalStates);
+
+  for (const terminalState of terminalSet) {
+    if (!Object.hasOwn(config.states, terminalState)) {
+      fail(`terminalStates references missing state ${terminalState}`);
+    }
+  }
+
+  for (const [stateName, state] of Object.entries(config.states)) {
+    if (!isObject(state)) {
+      fail(`${stateName} must be an object`);
+    }
+
+    const isTerminal = terminalSet.has(stateName) || state.type === 'terminal';
+    if (isTerminal) {
+      if (state.skill) {
+        fail(`${stateName} terminal state must not define skill`);
+      }
+      if (Array.isArray(state.next) && state.next.length > 0) {
+        fail(`${stateName} terminal state must not define next`);
+      }
+      continue;
+    }
+
+    if (!state.type || typeof state.type !== 'string') {
+      fail(`${stateName} type must be a non-empty string`);
+    }
+
+    const next = normalizeStringList(state.next ?? [], `${stateName}.next`);
+    if (next.length === 0) {
+      fail(`${stateName} next must contain at least one exit`);
+    }
+
+    if (state.skill !== undefined) {
+      if (typeof state.skill !== 'string' || state.skill.trim() === '') {
+        fail(`${stateName} skill must be a non-empty string`);
+      }
+      if (installedSkills && !installedSkills.has(state.skill)) {
+        fail(`${stateName} skill references missing skill ${state.skill}`);
+      }
+    }
+
+    for (const target of next) {
+      if (SPECIAL_TARGETS.has(target)) continue;
+      if (!Object.hasOwn(config.states, target)) {
+        fail(`${stateName} next references missing state ${target}`);
+      }
+    }
+  }
+
+  const debugState = config.states.systematic_debugging;
+  if (debugState && !terminalSet.has('systematic_debugging')) {
+    const exits = Array.isArray(debugState.next) ? debugState.next : [];
+    if (!exits.includes('previous_state')) {
+      fail('systematic_debugging next must include previous_state');
+    }
+  }
+
+  return config;
+}
+
+export function buildWorkflowGraph(config, { installedSkills } = {}) {
+  validateWorkflowConfig(config, { installedSkills });
+
+  const terminalSet = new Set(config.terminalStates ?? []);
+  const states = new Map();
+  for (const [name, state] of Object.entries(config.states)) {
+    const terminal = terminalSet.has(name) || state.type === 'terminal';
+    const silentStopAllowed = state.silent_stop_allowed === true;
+    states.set(name, {
+      name,
+      type: state.type,
+      skill: state.skill ?? null,
+      next: terminal ? [] : [...state.next],
+      terminal,
+      silent_stop_allowed: silentStopAllowed,
+    });
+  }
+
+  return {
+    version: config.version,
+    entryState: config.entryState,
+    terminalStates: terminalSet,
+    states,
+  };
+}