heyspex 0.1.0

package/vendor/heyspex-mcp/fleet-queue-tools.mjs

@@ -0,0 +1,241 @@
+/**
+ * HeySpex fleet-queue MCP tools — agent-facing FACE 1 of the fleet-queue
+ * Neon port ([[HS-60Z1-EPIC]] Phase 5). Thin wrappers around the bearer-authed
+ * queue API landing in Phase 3:
+ *
+ *   POST   /api/fleet/queue                    { lane, kind, payload?, requestedBy? } -> { id, position }
+ *   GET    /api/fleet/queue?lane=&status=&limit= -> { items }
+ *   GET    /api/fleet/queue/peek?lane=          -> { item }
+ *   POST   /api/fleet/queue/:taskId/claim       { machineKey } -> { ok, reclaimed } | 409/404 { ok:false, reason }
+ *   POST   /api/fleet/queue/:taskId/complete    { machineKey, result? } -> { accepted }
+ *   POST   /api/fleet/queue/:taskId/fail        { machineKey, reason? } -> { accepted }
+ *
+ * Pure-logic module: each `executeFleetQueueXxx` takes an injected
+ * `consoleFetch` (the shared factory in console-fetch.mjs; idiom mirrored from
+ * procedure-tools.mjs / submit-for-review.mjs) so tests never touch a real
+ * server. cli.mjs wires the real consoleFetch + `resolveFleetToken()` and
+ * mounts the four tools below as heyspex_fleet_queue_{submit,claim,complete,list}.
+ *
+ * Auth: the queue API requires `Authorization: Bearer <fleet token>` — the
+ * same session token a companion presents on `/api/fleet/join` pull calls
+ * (see spex-console/src/lib/fleet/fleet-bearer-auth.ts). `resolveFleetToken`
+ * mirrors that file's resolution order (env -> ~/.heyspex/credentials.yaml ->
+ * Windows registry) so an agent already holding a joined machine's token can
+ * call these tools with no extra setup.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir, platform } from 'node:os';
+import { join } from 'node:path';
+
+/**
+ * Resolve the caller's fleet bearer token. Mirror of
+ * `resolveExpectedFleetToken` in spex-console/src/lib/fleet/fleet-bearer-auth.ts
+ * (kept in sync deliberately — this is the token that route checks).
+ * Returns null when no token can be resolved; callers still issue the
+ * request (the API 401s, which surfaces as a clean error, not a throw).
+ */
+export function resolveFleetToken() {
+  const env = process.env.HEYSPEX_FLEET_TOKEN;
+  if (env && env.trim()) return env.trim();
+  try {
+    const yaml = readFileSync(join(homedir(), '.heyspex', 'credentials.yaml'), 'utf8');
+    const clerk = yaml.match(/^clerk:\s*$([\s\S]*?)(?=^\S|\s*$(?![\s\S]))/m)?.[1] ?? yaml;
+    const m = clerk.match(/^\s*companion_token:\s*["']?([^"'\r\n#]+)/m);
+    if (m?.[1]?.trim()) return m[1].trim();
+  } catch {
+    // fall through to the registry fallback
+  }
+  if (platform() === 'win32') {
+    try {
+      const out = execFileSync('reg', ['query', 'HKCU\\Environment', '/v', 'HEYSPEX_FLEET_TOKEN'], {
+        encoding: 'utf8',
+      });
+      const m = out.match(/HEYSPEX_FLEET_TOKEN\s+REG_[A-Z_]+\s+(.+)/);
+      return m?.[1]?.trim() || null;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+function bearerHeaders(fleetToken) {
+  return fleetToken ? { Authorization: `Bearer ${fleetToken}` } : {};
+}
+
+/**
+ * HS-FS7X (interim only — full fix is the unstarted [[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]]
+ * child tasks). This route writes to the Neon-backed `/api/fleet/queue`, but
+ * `dev-factory/lib/fleet-queue-runner.mjs` — the only thing that actually
+ * claims and executes queued work — still reads exclusively from the legacy
+ * file-backed queue (`dev-factory/lib/fleet-queue.mjs`). A submit through this
+ * tool therefore succeeds and is durably recorded, but nothing will ever pick
+ * it up. Every success return carries this warning so a caller cannot mistake
+ * "accepted" for "will run" until the runner is repointed at Neon.
+ */
+export const NEON_QUEUE_NO_RUNNER_WARNING =
+  'Neon fleet queue has NO runner reading it yet — dev-factory/lib/fleet-queue-runner.mjs ' +
+  'still only reads the legacy JSONL file queue. This item is durably recorded in Neon but ' +
+  'will NOT execute until HS-XOCK-60Z1 (fleet-queue Neon port) lands. Track: ' +
+  '[[HS-XOCK-60Z1-EPIC-fleet-work-queue-in-heyspex]].';
+
+/**
+ * `heyspex_fleet_queue_submit` — POST /api/fleet/queue. `kind` defaults to
+ * "task" when omitted (the API requires a kind string).
+ *
+ * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null }} ctx
+ */
+export async function executeFleetQueueSubmit({ consoleFetch, args = {}, fleetToken = null }) {
+  const lane = typeof args.lane === 'string' ? args.lane.trim() : '';
+  if (!lane) {
+    return { error: 'INVALID_ARGS', message: 'lane is required' };
+  }
+  const kind = typeof args.kind === 'string' && args.kind.trim() ? args.kind.trim() : 'task';
+
+  const body = {
+    lane,
+    kind,
+    payload: args.payload ?? {},
+    requestedBy: args.requested_by ?? null,
+  };
+
+  const result = await consoleFetch('/api/fleet/queue', {
+    method: 'POST',
+    headers: bearerHeaders(fleetToken),
+    body,
+  });
+
+  if (!result.ok) {
+    return {
+      error: 'SUBMIT_FAILED',
+      message: `POST /api/fleet/queue returned ${result.status}`,
+      status: result.status,
+      console_response: result.body,
+    };
+  }
+
+  return {
+    id: result.body?.id ?? null,
+    position: result.body?.position ?? null,
+    lane,
+    warning: NEON_QUEUE_NO_RUNNER_WARNING,
+  };
+}
+
+/**
+ * `heyspex_fleet_queue_claim` — POST /api/fleet/queue/:taskId/claim. A 404
+ * (unknown id) or 409 (double-claim / terminal state) is a normal outcome for
+ * a busy machine-gated resource, so it is surfaced as `{ ok:false, reason }`
+ * rather than an `error` (which would read as an unexpected failure).
+ *
+ * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null }} ctx
+ */
+export async function executeFleetQueueClaim({ consoleFetch, args = {}, fleetToken = null }) {
+  const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : '';
+  const machineKey = typeof args.machine_key === 'string' ? args.machine_key.trim() : '';
+  if (!taskId) {
+    return { error: 'INVALID_ARGS', message: 'task_id is required' };
+  }
+  if (!machineKey) {
+    return { error: 'INVALID_ARGS', message: 'machine_key is required' };
+  }
+
+  const result = await consoleFetch(`/api/fleet/queue/${encodeURIComponent(taskId)}/claim`, {
+    method: 'POST',
+    headers: bearerHeaders(fleetToken),
+    body: { machineKey },
+  });
+
+  if ((result.status === 404 || result.status === 409) && result.body && typeof result.body === 'object') {
+    return {
+      ok: false,
+      reason: result.body.reason ?? (result.status === 404 ? 'unknown id' : 'claim_conflict'),
+      task_id: taskId,
+      status: result.status,
+    };
+  }
+
+  if (!result.ok) {
+    return {
+      error: 'CLAIM_FAILED',
+      message: `POST /api/fleet/queue/${taskId}/claim returned ${result.status}`,
+      status: result.status,
+      console_response: result.body,
+    };
+  }
+
+  return {
+    ok: true,
+    reclaimed: result.body?.reclaimed ?? false,
+    task_id: taskId,
+  };
+}
+
+/**
+ * `heyspex_fleet_queue_complete` — POST /api/fleet/queue/:taskId/complete.
+ *
+ * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null }} ctx
+ */
+export async function executeFleetQueueComplete({ consoleFetch, args = {}, fleetToken = null }) {
+  const taskId = typeof args.task_id === 'string' ? args.task_id.trim() : '';
+  const machineKey = typeof args.machine_key === 'string' ? args.machine_key.trim() : '';
+  if (!taskId) {
+    return { error: 'INVALID_ARGS', message: 'task_id is required' };
+  }
+  if (!machineKey) {
+    return { error: 'INVALID_ARGS', message: 'machine_key is required' };
+  }
+
+  const body = { machineKey };
+  if (args.result !== undefined) body.result = args.result;
+
+  const result = await consoleFetch(`/api/fleet/queue/${encodeURIComponent(taskId)}/complete`, {
+    method: 'POST',
+    headers: bearerHeaders(fleetToken),
+    body,
+  });
+
+  if (!result.ok) {
+    return {
+      error: 'COMPLETE_FAILED',
+      message: `POST /api/fleet/queue/${taskId}/complete returned ${result.status}`,
+      status: result.status,
+      console_response: result.body,
+    };
+  }
+
+  return { accepted: result.body?.accepted ?? true, task_id: taskId };
+}
+
+/**
+ * `heyspex_fleet_queue_list` — GET /api/fleet/queue?lane=&status=&limit=. The
+ * visibility read: queue depth, in-flight items, and history.
+ *
+ * @param {{ consoleFetch: Function, args?: Record<string, unknown>, fleetToken?: string|null }} ctx
+ */
+export async function executeFleetQueueList({ consoleFetch, args = {}, fleetToken = null }) {
+  const params = new URLSearchParams();
+  if (typeof args.lane === 'string' && args.lane.trim()) params.set('lane', args.lane.trim());
+  if (typeof args.status === 'string' && args.status.trim()) params.set('status', args.status.trim());
+  if (args.limit !== undefined && args.limit !== null && args.limit !== '') {
+    params.set('limit', String(args.limit));
+  }
+  const qs = params.toString();
+  const path = `/api/fleet/queue${qs ? `?${qs}` : ''}`;
+
+  const result = await consoleFetch(path, { headers: bearerHeaders(fleetToken) });
+
+  if (!result.ok) {
+    return {
+      error: 'LIST_FAILED',
+      message: `GET ${path} returned ${result.status}`,
+      status: result.status,
+      console_response: result.body,
+    };
+  }
+
+  const items = Array.isArray(result.body?.items) ? result.body.items : [];
+  return { items, count: items.length };
+}

package/vendor/heyspex-mcp/hooks-engine.mjs

@@ -0,0 +1,399 @@
+/**
+ * HeySpex MCP Hook Engine
+ *
+ * Loads hook config from .commandcode/hooks.json (or .heyspex/hooks.json)
+ * and runs hook scripts before/after MCP tool handlers — matching the Claude
+ * Code hook lifecycle (UserPromptSubmit, PreToolUse, PostToolUse, SessionEnd)
+ * inside the MCP server process.
+ *
+ * Fail-silent contract: any hook failure silently passes through. A hook that
+ * breaks the agent is worse than a hook that silently does nothing.
+ *
+ * Zero dependencies — Node.js stdlib only.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { getActiveConfig } from './vault-resolve.mjs';
+
+const HOOK_CONFIG_SEARCH = [
+  '.commandcode/hooks.json',
+  '.heyspex/hooks.json',
+];
+
+// ─────────────────────────────────────────────────────────────
+// Config loading
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Read hook config from disk. Returns empty config on any failure.
+ * @param {string} rootDir — vault root
+ * @returns {{ userPromptSubmit: HookGroup[], preToolUse: HookGroup[], postToolUse: HookGroup[], sessionEnd: HookGroup[] }}
+ */
+export function loadHooksConfig(rootDir) {
+  for (const relPath of HOOK_CONFIG_SEARCH) {
+    const filePath = join(rootDir, relPath);
+    if (!existsSync(filePath)) continue;
+    try {
+      const raw = readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      const hooks = parsed?.hooks ?? parsed;
+      return {
+        userPromptSubmit: hooks?.UserPromptSubmit ?? [],
+        preToolUse: hooks?.PreToolUse ?? [],
+        postToolUse: hooks?.PostToolUse ?? [],
+        sessionEnd: hooks?.SessionEnd ?? [],
+        _configPath: filePath,
+      };
+    } catch {
+      /* malformed JSON — skip silently */
+      return { userPromptSubmit: [], preToolUse: [], postToolUse: [], sessionEnd: [] };
+    }
+  }
+  return { userPromptSubmit: [], preToolUse: [], postToolUse: [], sessionEnd: [] };
+}
+
+/**
+ * Full parsed config for introspection (heyspex_hooks_list tool).
+ * @param {string} rootDir
+ * @returns {object}
+ */
+export function listHookConfig(rootDir) {
+  const cfg = loadHooksConfig(rootDir);
+  return {
+    userPromptSubmit: cfg.userPromptSubmit,
+    preToolUse: cfg.preToolUse,
+    postToolUse: cfg.postToolUse,
+    sessionEnd: cfg.sessionEnd,
+    configPath: cfg._configPath ?? null,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Matcher
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Does a matcher string match a tool name?
+ *
+ * - `*`, `""`, or omitted — matches all
+ * - `tool1|tool2` — exact match against any pipe-delimited entry
+ * - anything else — exact match
+ *
+ * @param {string|undefined} matcher
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+function matcherMatches(matcher, toolName) {
+  if (!matcher || matcher === '*') return true;
+  // Pipe-delimited list
+  if (matcher.includes('|')) {
+    const parts = matcher.split('|').map((p) => p.trim());
+    return parts.includes(toolName);
+  }
+  return matcher === toolName;
+}
+
+/**
+ * Return all hook groups matching an event + tool name.
+ * @param {'UserPromptSubmit'|'PreToolUse'|'PostToolUse'|'SessionEnd'} event
+ * @param {string} toolName
+ * @param {object} config — from loadHooksConfig
+ * @returns {HookGroup[]}
+ */
+export function matchHooks(event, toolName, config) {
+  let groups;
+  switch (event) {
+    case 'UserPromptSubmit': groups = config.userPromptSubmit ?? []; break;
+    case 'PreToolUse': groups = config.preToolUse ?? []; break;
+    case 'PostToolUse': groups = config.postToolUse ?? []; break;
+    case 'SessionEnd': groups = config.sessionEnd ?? []; break;
+    default: return [];
+  }
+  if (event === 'UserPromptSubmit' || event === 'SessionEnd') {
+    return groups;
+  }
+  return groups.filter((g) => matcherMatches(g.matcher, toolName));
+}
+
+// ─────────────────────────────────────────────────────────────
+// Placeholder substitution
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Substitute ${HEYSPEX_VAULT_ROOT} in strings.
+ * @param {string|string[]} val
+ * @param {string} vaultRoot
+ * @returns {string|string[]}
+ */
+function resolvePlaceholders(val, vaultRoot) {
+  if (Array.isArray(val)) {
+    return val.map((v) => resolvePlaceholders(v, vaultRoot));
+  }
+  if (typeof val === 'string') {
+    return val.replace(/\$\{HEYSPEX_VAULT_ROOT\}/g, vaultRoot);
+  }
+  return val;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Hook execution
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Execute a single hook command.
+ *
+ * @param {object} hookDef — { type, command, args, timeout? }
+ * @param {object} payload — JSON payload to write to stdin
+ * @param {object} options
+ * @param {string} options.vaultRoot — vault root (for placeholders + env)
+ * @returns {{ ok: boolean, blocked: boolean, reason?: string, modifiedInput?: object, output?: string }}
+ */
+export function executeHook(hookDef, payload, { vaultRoot } = {}) {
+  if (hookDef.type !== 'command') {
+    // Only command hooks supported for now
+    return { ok: true, blocked: false };
+  }
+
+  const command = resolvePlaceholders(hookDef.command, vaultRoot);
+  const rawArgs = hookDef.args ?? [];
+  const args = resolvePlaceholders(rawArgs, vaultRoot);
+  const timeout = (hookDef.timeout ?? 5) * 1000; // seconds → ms, default 5s
+
+  const input = JSON.stringify(payload);
+
+  const result = spawnSync(command, args, {
+    input,
+    encoding: 'utf8',
+    timeout,
+    maxBuffer: 1024 * 1024, // 1 MB
+    env: {
+      ...process.env,
+      CLAUDE_PROJECT_DIR: vaultRoot,
+      HEYSPEX_VAULT_ROOT: vaultRoot,
+      // MCP hook path is always agent context (Command Code lacks CLAUDE_AGENT env).
+      CLAUDE_AGENT: 'true',
+      // Prevent infinite recursion — child hooks don't re-enter the MCP server
+      HEYSPEX_MCP_INLINE_CALLS: '1',
+      HEYSPEX_MCP_HOOKS: '1',
+    },
+    windowsHide: true,
+  });
+
+  const stdout = (result.stdout ?? '').trim();
+  const stderr = (result.stderr ?? '').trim();
+  const status = result.status;
+  const error = result.error;
+
+  // Timeout or spawn error — fail silent
+  if (error) {
+    return { ok: true, blocked: false };
+  }
+
+  // Exit code 2 = hard block
+  if (status === 2) {
+    const reason = stderr || 'Blocked by hook';
+    return { ok: false, blocked: true, reason, output: stdout };
+  }
+
+  // Non-zero exit that isn't 2 = non-blocking error
+  if (status !== 0 && status !== null) {
+    return { ok: true, blocked: false };
+  }
+
+  // Exit 0 — parse stdout for JSON decision
+  if (stdout) {
+    try {
+      const json = JSON.parse(stdout);
+
+      // Top-level decision: block
+      if (json.decision === 'block') {
+        return {
+          ok: false,
+          blocked: true,
+          reason: json.reason ?? 'Blocked by hook',
+          output: stdout,
+        };
+      }
+
+      // hookSpecificOutput: PreToolUse with permissionDecision or modifiedInput
+      if (json.hookSpecificOutput) {
+        const hso = json.hookSpecificOutput;
+        if (hso.permissionDecision === 'deny') {
+          return {
+            ok: false,
+            blocked: true,
+            reason: hso.permissionDecisionReason ?? 'Denied by hook',
+            output: stdout,
+          };
+        }
+        if (hso.modifiedInput) {
+          return {
+            ok: true,
+            blocked: false,
+            modifiedInput: hso.modifiedInput,
+            output: stdout,
+          };
+        }
+        // additionalContext is passed through in output
+        if (hso.additionalContext) {
+          return {
+            ok: true,
+            blocked: false,
+            additionalContext: hso.additionalContext,
+            output: stdout,
+          };
+        }
+      }
+    } catch {
+      /* stdout not JSON — treat as pass-through */
+    }
+  }
+
+  return { ok: true, blocked: false, output: stdout };
+}
+
+// ─────────────────────────────────────────────────────────────
+// Orchestration
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Run all matching hooks for an event.
+ *
+ * @param {'UserPromptSubmit'|'PreToolUse'|'PostToolUse'|'SessionEnd'} event
+ * @param {string} toolName
+ * @param {object} toolArgs
+ * @param {object|null} toolResult — null for PreToolUse/UserPromptSubmit/SessionEnd
+ * @param {object} config — from loadHooksConfig
+ * @param {object} [options]
+ * @param {function} [options.onBlock] — called with (reason) on block
+ * @returns {{ blocked: boolean, reason?: string, modifiedInput?: object, additionalContexts?: string[] }}
+ */
+export function runHooks(event, toolName, toolArgs, toolResult, config, options = {}) {
+  const rootDir = config._configPath
+    ? join(config._configPath, '..', '..')
+    : getActiveConfig().repoRootAbs;
+
+  const groups = matchHooks(event, toolName, config);
+  if (groups.length === 0) return { blocked: false };
+
+  let modifiedInput = null;
+  const additionalContexts = [];
+
+  for (const group of groups) {
+    const handlers = group.hooks ?? [];
+    for (const hookDef of handlers) {
+      // Build stdin payload matching Claude Code hook input shape
+      const payload = {
+        hook_event_name: event,
+        tool_name: toolName,
+        tool_input: modifiedInput ?? toolArgs,
+        cwd: rootDir,
+      };
+
+      if (event === 'UserPromptSubmit') {
+        payload.prompt = toolArgs?.prompt ?? toolArgs?.text ?? '';
+      }
+
+      // For PostToolUse, attach the tool result
+      if (event === 'PostToolUse' && toolResult) {
+        payload.tool_response = toolResult;
+      }
+
+      try {
+        const result = executeHook(hookDef, payload, { vaultRoot: rootDir });
+
+        if (result.blocked) {
+          if (options.onBlock) options.onBlock(result.reason ?? '');
+          return {
+            blocked: true,
+            reason: result.reason ?? 'Blocked by hook',
+          };
+        }
+
+        if (result.modifiedInput) {
+          modifiedInput = {
+            ...(modifiedInput ?? toolArgs),
+            ...result.modifiedInput,
+          };
+        }
+
+        if (result.additionalContext) {
+          additionalContexts.push(result.additionalContext);
+        }
+      } catch {
+        /* fail-silent — hook error never breaks the tool */
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    ...(modifiedInput ? { modifiedInput } : {}),
+    ...(additionalContexts.length > 0 ? { additionalContexts } : {}),
+  };
+}
+
+/**
+ * Prepend hook additionalContext blocks onto an MCP tool result (text content).
+ * @param {object} toolResult
+ * @param {string[]} contexts
+ * @returns {object}
+ */
+export function attachHookContexts(toolResult, contexts) {
+  if (!toolResult || !contexts?.length) return toolResult;
+
+  const banner = contexts
+    .map((c) => `[HeySpex hook context]\n${c}`)
+    .join('\n\n');
+
+  const content = Array.isArray(toolResult.content) ? [...toolResult.content] : [];
+  const first = content[0];
+
+  if (first?.type === 'text' && typeof first.text === 'string') {
+    content[0] = { ...first, text: `${banner}\n\n${first.text}` };
+  } else if (first?.type === 'text') {
+    content[0] = { ...first, text: banner };
+  } else {
+    content.unshift({ type: 'text', text: banner });
+  }
+
+  return { ...toolResult, content };
+}
+
+/**
+ * Run PostToolUse hooks and merge Pre/Post additionalContext onto a tool result.
+ * @param {string} toolName
+ * @param {object} toolArgs
+ * @param {object} toolResult
+ * @param {object} hooksCfg
+ * @param {{ additionalContexts?: string[] }} [preHookResult]
+ * @returns {object}
+ */
+export function finalizeToolResultWithHooks(toolName, toolArgs, toolResult, hooksCfg, preHookResult) {
+  if (!toolResult || toolResult.isError) return toolResult;
+
+  const contexts = [...(preHookResult?.additionalContexts ?? [])];
+  const postResult = runHooks('PostToolUse', toolName, toolArgs, toolResult, hooksCfg);
+
+  if (postResult.blocked) {
+    return {
+      isError: true,
+      content: [{
+        type: 'text',
+        text: JSON.stringify({
+          error: 'HOOK_BLOCKED',
+          message: postResult.reason ?? 'Blocked by PostToolUse hook',
+        }),
+      }],
+    };
+  }
+
+  if (postResult.additionalContexts?.length) {
+    contexts.push(...postResult.additionalContexts);
+  }
+
+  return attachHookContexts(toolResult, contexts);
+}