vericify 1.2.0 → 1.3.1

package/src/adapters/handshake/cursor.js

@@ -0,0 +1,100 @@
+import { existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+
+function cursorInstructionBlock() {
+  return `---
+description: Vericify process post instructions
+alwaysApply: true
+---
+
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id cursor --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id cursor --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id cursor --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id cursor --kind stale_ack --summary "<reason>"\``;
+}
+
+export function cursorHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  const cursorDir = resolve(workspaceRoot, ".cursor");
+  const cursorMcpPath = resolve(cursorDir, "mcp.json");
+  const rulesDir = resolve(cursorDir, "rules");
+  const fallbackRulesPath = resolve(workspaceRoot, ".cursorrules");
+  const mcpPlaceholder = {
+    _vericify: true,
+    mcpServers: {
+      vericify: {
+        command: "vericify-mcp",
+        args: ["--workspace-root", "."],
+        _note: "vericify-mcp not yet installed. Run: npm install -g vericify-mcp",
+      },
+    },
+  };
+
+  if (existsSync(cursorDir)) {
+    try {
+      const mcpResult = mergeJsonFile(cursorMcpPath, (existing) => {
+        const current = existing && typeof existing === "object" ? existing : {};
+        return {
+          ...current,
+          _vericify: true,
+          mcpServers: {
+            ...(current.mcpServers && typeof current.mcpServers === "object" ? current.mcpServers : {}),
+            vericify: current.mcpServers?.vericify ?? mcpPlaceholder.mcpServers.vericify,
+          },
+        };
+      });
+      result.mcp_written = Boolean(mcpResult.written);
+      result.mcp_path = cursorMcpPath;
+      if (mcpResult.skipped) skippedReasons.push(mcpResult.reason);
+    } catch (error) {
+      skippedReasons.push(`.cursor/mcp.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push(".cursor directory is missing; MCP placeholder skipped");
+  }
+
+  let instructionTarget = null;
+  if (existsSync(rulesDir)) {
+    instructionTarget = resolve(rulesDir, "vericify.mdc");
+  } else if (existsSync(fallbackRulesPath)) {
+    instructionTarget = fallbackRulesPath;
+  }
+
+  if (instructionTarget) {
+    try {
+      const instructionResult = writeInstructionBlock(instructionTarget, VERICIFY_MARKER, cursorInstructionBlock(), {
+        createIfAbsent: true,
+        createDirs: true,
+      });
+      result.instruction_written = Boolean(instructionResult.written);
+      result.instruction_path = instructionTarget;
+      if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+    } catch (error) {
+      skippedReasons.push(`Cursor instruction write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push("No .cursor/rules/ or .cursorrules file exists; instruction block skipped");
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "cursor",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    mcpWritten: result.mcp_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/handshake/index.js

@@ -0,0 +1,35 @@
+import { createHandshakeResult } from "./common.js";
+import { antigravityHandshake } from "./antigravity.js";
+import { claudeCodeHandshake } from "./claude-code.js";
+import { codexHandshake } from "./codex.js";
+import { cursorHandshake } from "./cursor.js";
+import { vscodeCopilotHandshake } from "./vscode-copilot.js";
+
+const HANDSHAKE_FNS = {
+  "claude-code": claudeCodeHandshake,
+  codex: codexHandshake,
+  cursor: cursorHandshake,
+  "vscode-copilot-chat": vscodeCopilotHandshake,
+  antigravity: antigravityHandshake,
+};
+
+export function runHandshake(workspaceRoot, options = {}) {
+  const adapterId = String(options.adapterId ?? "").trim();
+  const fn = HANDSHAKE_FNS[adapterId];
+  if (!fn) {
+    return {
+      skipped: true,
+      reason: "No handshake defined for this adapter.",
+      ...createHandshakeResult(),
+    };
+  }
+
+  try {
+    return fn(workspaceRoot, options);
+  } catch (error) {
+    return {
+      ...createHandshakeResult(),
+      skipped_reasons: [`Handshake failed: ${error instanceof Error ? error.message : String(error)}`],
+    };
+  }
+}

package/src/adapters/handshake/vscode-copilot.js

@@ -0,0 +1,82 @@
+import { existsSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createHandshakeResult, emitHandshakeStartedEvent, mergeJsonFile, writeInstructionBlock } from "./common.js";
+
+const VERICIFY_MARKER = "<!-- vericify-instruction -->";
+
+function copilotInstructionBlock() {
+  return `${VERICIFY_MARKER}
+## Vericify Process Posts
+
+When working in this workspace, emit native Vericify process posts at these moments:
+
+- **Blocker:** \`vericify post --run-id workspace:current --agent-id vscode-copilot-chat --kind blocker --summary "<what is blocking>"\`
+- **Handoff:** \`vericify post --run-id workspace:current --agent-id vscode-copilot-chat --kind handoff_note --summary "<handoff context>"\`
+- **Completion:** \`vericify post --run-id workspace:current --agent-id vscode-copilot-chat --kind completion --summary "<what changed>"\`
+- **Intentional silence:** \`vericify post --run-id workspace:current --agent-id vscode-copilot-chat --kind stale_ack --summary "<reason>"\`
+<!-- /vericify-instruction -->`;
+}
+
+export function vscodeCopilotHandshake(workspaceRoot, options = {}) {
+  const result = createHandshakeResult();
+  const skippedReasons = [];
+  const vscodeDir = resolve(workspaceRoot, ".vscode");
+  const githubDir = resolve(workspaceRoot, ".github");
+  const mcpPath = resolve(vscodeDir, "mcp.json");
+  const instructionPath = resolve(githubDir, "copilot-instructions.md");
+
+  if (existsSync(vscodeDir)) {
+    try {
+      const mcpResult = mergeJsonFile(mcpPath, (existing) => {
+        const current = existing && typeof existing === "object" ? existing : {};
+        return {
+          ...current,
+          servers: {
+            ...(current.servers && typeof current.servers === "object" ? current.servers : {}),
+            vericify: current.servers?.vericify ?? {
+              _vericify: true,
+              type: "stdio",
+              command: "vericify-mcp",
+              args: ["--workspace-root", "${workspaceFolder}"],
+              _note: "vericify-mcp not yet installed. Run: npm install -g vericify-mcp",
+            },
+          },
+        };
+      });
+      result.mcp_written = Boolean(mcpResult.written);
+      result.mcp_path = mcpPath;
+      if (mcpResult.skipped) skippedReasons.push(mcpResult.reason);
+    } catch (error) {
+      skippedReasons.push(`.vscode/mcp.json write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  } else {
+    skippedReasons.push(".vscode directory is missing; MCP placeholder skipped");
+  }
+
+  try {
+    mkdirSync(dirname(instructionPath), { recursive: true });
+    const instructionResult = writeInstructionBlock(instructionPath, VERICIFY_MARKER, copilotInstructionBlock(), {
+      createIfAbsent: true,
+      createDirs: true,
+    });
+    result.instruction_written = Boolean(instructionResult.written);
+    result.instruction_path = instructionPath;
+    if (instructionResult.skipped) skippedReasons.push(instructionResult.reason);
+  } catch (error) {
+    skippedReasons.push(`copilot instructions write failed: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  const eventResult = emitHandshakeStartedEvent(workspaceRoot, {
+    adapterId: "vscode-copilot-chat",
+    sessionId: options.sessionId ?? null,
+    hooksWritten: false,
+    instructionWritten: result.instruction_written,
+    mcpWritten: result.mcp_written,
+  });
+
+  return {
+    ...result,
+    event_emitted: eventResult.event_emitted,
+    skipped_reasons: [...skippedReasons, ...eventResult.skipped_reasons].filter(Boolean),
+  };
+}

package/src/adapters/registry.js

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
+import { runHandshake } from "./handshake/index.js";
 import { readAdapterAttachments, upsertAdapterAttachment } from "../store/adapter-attachments.js";
 
 const ADAPTER_DEFINITIONS = [
@@ -90,7 +91,27 @@ export function readWorkspaceAdapterAttachments(workspaceRoot) {
 }
 
 export function attachWorkspaceAdapter(workspaceRoot, input) {
-  return upsertAdapterAttachment(workspaceRoot, input);
+  const attachment = upsertAdapterAttachment(workspaceRoot, input);
+  let handshake;
+  try {
+    handshake = runHandshake(workspaceRoot, {
+      adapterId: input.adapter_id,
+      sessionId: input.session_id,
+      captureMode: input.capture_mode,
+    });
+  } catch (error) {
+    handshake = { error: error instanceof Error ? error.message : String(error) };
+  }
+  const skippedReasons = [
+    ...(Array.isArray(handshake?.skipped_reasons) ? handshake.skipped_reasons : []),
+    ...(handshake?.reason ? [handshake.reason] : []),
+    ...(handshake?.error ? [`Handshake error: ${handshake.error}`] : []),
+  ];
+  return {
+    ...attachment,
+    skipped_reasons: skippedReasons,
+    handshake,
+  };
 }
 
 export function detectWorkspaceAdapters(workspaceRoot, attachments = undefined) {

package/src/api.js

@@ -7,6 +7,8 @@ export {
   loadWorkspaceState,
 } from "./adapters/index.js";
 export { buildRunComparison, findRunById } from "./compare/engine.js";
+export { buildCompactDelta } from "./context/delta.js";
+export { buildCompactPacket, buildCompactPacketDetails } from "./context/packet.js";
 export { projectWorkspaceState } from "./projection/runs.js";
 export { publishRunArtifact } from "./publish/artifact.js";
 export { enqueueSyncOutboxItem } from "./sync/outbox.js";

package/src/context/delta.js

@@ -0,0 +1,97 @@
+import { buildCompactPacketDetails } from "./packet.js";
+import { decodeCompactCursor, isCompactCursor } from "./id.js";
+
+function oneLine(value) {
+  return String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function summarizeChangeSummary(current, previous) {
+  const rows = [];
+  if (!previous) return rows;
+
+  if (previous.run !== current.run) {
+    rows.push(`run switched from ${previous.run ?? "unknown"} to ${current.run}.`);
+  }
+  if (previous.latest_checkpoint_id !== current.latest_checkpoint_id) {
+    rows.push(
+      `latest checkpoint moved from ${previous.latest_checkpoint_id ?? "none"} to ${current.latest_checkpoint_id ?? "none"}.`
+    );
+  }
+  if (previous.last_activity_id !== current.last_activity_id) {
+    rows.push(`latest activity is now ${current.last_activity_id ?? "unknown"}.`);
+  }
+  if (previous.last_meaningful_update_at !== current.last_meaningful_update_at) {
+    rows.push(`last meaningful update changed to ${current.last_meaningful_update_at ?? "unknown"}.`);
+  }
+  if (previous.packet_digest !== current.packet_digest) {
+    rows.push("packet content changed.");
+  }
+
+  return [...new Set(rows)].slice(0, 3);
+}
+
+function buildFallbackChangeSummary(current, since) {
+  return [
+    `No compact cursor matched ${since}.`,
+    `Current checkpoint is ${current.latest_checkpoint_id ?? "unknown"}.`,
+  ];
+}
+
+function determineChanged(currentCursor, since, selectedRun) {
+  if (isCompactCursor(since)) {
+    const previous = decodeCompactCursor(since);
+    if (!previous) {
+      return { changed: true, previous: null };
+    }
+
+    return {
+      changed:
+        previous.run !== currentCursor.run ||
+        previous.status !== currentCursor.status ||
+        previous.latest_checkpoint_id !== currentCursor.latest_checkpoint_id ||
+        previous.last_meaningful_update_at !== currentCursor.last_meaningful_update_at ||
+        previous.last_activity_id !== currentCursor.last_activity_id ||
+        previous.packet_digest !== currentCursor.packet_digest,
+      previous,
+    };
+  }
+
+  if (selectedRun?.run?.run_id === "workspace:current") {
+    throw new Error(
+      "workspace:current resume requires a vcx_... cursor; run vericify context and reuse the emitted id."
+    );
+  }
+
+  const latestCheckpointId = currentCursor.latest_checkpoint_id;
+  const changed = since !== latestCheckpointId;
+  return { changed, previous: null };
+}
+
+export function buildCompactDelta(projected, options = {}) {
+  const since = String(options.since ?? "").trim();
+  if (!since) {
+    throw new Error("Compact delta requires --since.");
+  }
+
+  const details = buildCompactPacketDetails(projected, options);
+  const currentCursor = details.cursor.payload;
+  const { changed, previous } = determineChanged(currentCursor, since, details.selectedRun);
+  const delta = {
+    since,
+    changed,
+    ...details.packet,
+  };
+
+  if (changed) {
+    const change_summary = isCompactCursor(since) && previous
+      ? summarizeChangeSummary(currentCursor, previous)
+      : buildFallbackChangeSummary(currentCursor, since);
+    if (change_summary.length) {
+      delta.change_summary = change_summary;
+    }
+  }
+
+  return delta;
+}

package/src/context/id.js

@@ -0,0 +1,61 @@
+import { hashText } from "../core/util.js";
+
+const VCX_PREFIX = "vcx_";
+
+function encodeBase64Url(value) {
+  return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function decodeBase64Url(value) {
+  return Buffer.from(value, "base64url").toString("utf8");
+}
+
+export function isCompactCursor(value) {
+  return String(value ?? "").startsWith(VCX_PREFIX);
+}
+
+export function decodeCompactCursor(value) {
+  if (!isCompactCursor(value)) return null;
+  try {
+    const raw = decodeBase64Url(String(value).slice(VCX_PREFIX.length));
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+export function buildCompactCursorPayload({
+  run,
+  status,
+  latest_checkpoint_id,
+  last_meaningful_update_at,
+  last_activity_id,
+  packet_digest,
+}) {
+  return {
+    version: 1,
+    run: String(run ?? ""),
+    status: String(status ?? ""),
+    latest_checkpoint_id: latest_checkpoint_id ?? null,
+    last_meaningful_update_at: last_meaningful_update_at ?? null,
+    last_activity_id: last_activity_id ?? null,
+    packet_digest: String(packet_digest ?? ""),
+  };
+}
+
+export function encodeCompactCursor(payload) {
+  return `${VCX_PREFIX}${encodeBase64Url(JSON.stringify(payload))}`;
+}
+
+export function buildCompactCursor(input) {
+  const payload = buildCompactCursorPayload(input);
+  return {
+    cursor: encodeCompactCursor(payload),
+    payload,
+  };
+}
+
+export function compactPacketDigest(packet) {
+  return hashText(JSON.stringify(packet));
+}

package/src/context/packet.js

@@ -0,0 +1,210 @@
+import { buildRunComparison } from "../compare/engine.js";
+import { firstDefined, unique } from "../core/util.js";
+import { isMeaningfulActivity } from "../projection/live-signal.js";
+import { buildCompactCursor, compactPacketDigest } from "./id.js";
+import { selectCompactRun } from "./select.js";
+
+function oneLine(value) {
+  return String(value ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function truncate(value, max = 160) {
+  const text = oneLine(value);
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1)).trimEnd()}…`;
+}
+
+function splitFocusText(value) {
+  return oneLine(value)
+    .split(/(?:\n|,|;)+/)
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+function formatEvent(item) {
+  const parts = [];
+  if (item?.actor_id) parts.push(oneLine(item.actor_id));
+  if (item?.label) parts.push(oneLine(item.label));
+  if (item?.summary) parts.push(truncate(item.summary, 120));
+  return parts.length ? parts.join(": ") : truncate(item?.activity_id ?? "activity");
+}
+
+function latestMeaningfulActivity(runDetail) {
+  const meaningful = (runDetail?.activity_items ?? [])
+    .filter((item) => isMeaningfulActivity(item))
+    .sort((left, right) => String(left.timestamp ?? "").localeCompare(String(right.timestamp ?? "")));
+  return meaningful.at(-1) ?? null;
+}
+
+function nullIfUndefined(value) {
+  return value === undefined ? null : value;
+}
+
+const RECOMMENDED_ACTION_SENTENCES = {
+  accept_handoff: "Accept the handoff and continue with the incoming work.",
+  write_note: "Write the next note or blocker update.",
+  resolve_blocker: "Resolve the blocker before continuing.",
+  update_state: "Post the current state update.",
+  clarify_owner: "Clarify ownership before proceeding.",
+  ack_stale: "Acknowledge the stale state and re-check progress.",
+  observe_only: "Observe only. No urgent operator action.",
+};
+
+function sentenceForRecommendedAction(action) {
+  return RECOMMENDED_ACTION_SENTENCES[String(action ?? "").trim()] ?? null;
+}
+
+function deriveFocus(runDetail, latestActivity = null) {
+  const focus = [];
+  const summaryLabels = runDetail?.run_summary?.current_node_labels ?? [];
+  focus.push(...summaryLabels.slice(0, 3).map((label) => oneLine(label)));
+
+  const latestCheckpoint = runDetail?.recent_checkpoints?.at(-1);
+  focus.push(...splitFocusText(latestCheckpoint?.task_delta_summary ?? ""));
+  if (!focus.length) {
+    focus.push(...splitFocusText(latestCheckpoint?.process_summary?.split("\n")?.[0] ?? ""));
+  }
+
+  const meaningfulActivity = latestActivity ?? latestMeaningfulActivity(runDetail);
+  if (meaningfulActivity?.summary) {
+    focus.push(truncate(meaningfulActivity.summary, 120));
+  }
+
+  if (!focus.length && runDetail?.run?.title) {
+    focus.push(oneLine(runDetail.run.title));
+  }
+
+  return unique(focus).slice(0, 3);
+}
+
+function deriveBlockers(runDetail) {
+  const blockers = [];
+  const blockedNodes = (runDetail?.nodes ?? []).filter((node) => node.status === "blocked").map((node) => node.title);
+  blockers.push(...blockedNodes.map((title) => oneLine(title)));
+
+  const signal = runDetail?.live_signal ?? {};
+  if (["blocked", "overdue_handoff"].includes(signal.attention_class)) {
+    blockers.push(`Attention class: ${signal.attention_class}`);
+  }
+  if (signal.attention_reason) {
+    blockers.push(truncate(signal.attention_reason, 160));
+  }
+
+  return unique(blockers).slice(0, 3);
+}
+
+function deriveLastEvents(runDetail) {
+  const meaningful = (runDetail?.activity_items ?? []).filter((item) => isMeaningfulActivity(item));
+  const source = meaningful.length
+    ? meaningful
+    : (runDetail?.recent_checkpoints ?? []).map((checkpoint, index) => ({
+        activity_id: checkpoint.checkpoint_id ?? `${runDetail?.run?.run_id ?? "run"}:checkpoint:${index + 1}`,
+        actor_id: runDetail?.run?.run_id ?? "run",
+        label: "checkpoint",
+        summary: checkpoint.task_delta_summary ?? checkpoint.process_summary?.split("\n")?.[0] ?? "",
+        timestamp: checkpoint.timestamp,
+      }));
+
+  return [...source]
+    .sort((left, right) => String(left.timestamp ?? "").localeCompare(String(right.timestamp ?? "")))
+    .slice(-5)
+    .map((item) => formatEvent(item));
+}
+
+function deriveLiveSignalSubset(runDetail) {
+  const signal = runDetail?.live_signal ?? {};
+  return {
+    attention_class: nullIfUndefined(signal.attention_class),
+    expected_next_event: nullIfUndefined(signal.expected_next_event),
+    recommended_post_kind: nullIfUndefined(signal.recommended_post_kind),
+    needs_narrative: nullIfUndefined(signal.needs_narrative),
+    should_interrupt_agent: nullIfUndefined(signal.should_interrupt_agent),
+  };
+}
+
+function deriveRecommendedAction(selectedRun, comparisonRun) {
+  const liveSignalAction = oneLine(selectedRun?.live_signal?.recommended_owner_action ?? "");
+  const mappedAction = sentenceForRecommendedAction(liveSignalAction);
+  if (mappedAction) return mappedAction;
+
+  if (comparisonRun) {
+    const comparison = buildRunComparison(selectedRun, comparisonRun);
+    const recommended = comparison.recommended_actions?.[0];
+    if (recommended) return oneLine(recommended);
+  }
+
+  return "Observe only. No urgent operator action.";
+}
+
+function buildPacketFingerprint(packet) {
+  return {
+    run: packet.run,
+    status: packet.status,
+    focus: packet.focus,
+    blockers: packet.blockers,
+    live_signal: packet.live_signal,
+    last_5_events: packet.last_5_events,
+    recommended_action: packet.recommended_action,
+  };
+}
+
+export function buildCompactPacketDetails(projected, options = {}) {
+  const selection = selectCompactRun(projected, options);
+  const selectedRun = selection.selectedRun;
+  const comparisonRun = selection.comparisonRun;
+
+  if (!selectedRun) {
+    throw new Error("Compact packet requires a selected run.");
+  }
+
+  const latestActivity = latestMeaningfulActivity(selectedRun);
+  const focus = deriveFocus(selectedRun, latestActivity);
+  const blockers = deriveBlockers(selectedRun);
+  const last_5_events = deriveLastEvents(selectedRun);
+  const live_signal = deriveLiveSignalSubset(selectedRun);
+  const recommended_action = deriveRecommendedAction(selectedRun, comparisonRun);
+
+  const packet = {
+    run: selectedRun.run.run_id,
+    status: selectedRun.run.status,
+    focus,
+    blockers,
+    live_signal,
+    last_5_events,
+    recommended_action,
+  };
+  const fingerprint = buildPacketFingerprint(packet);
+  const packet_digest = compactPacketDigest(fingerprint);
+  const latestCheckpoint = selectedRun.recent_checkpoints?.at(-1);
+  const cursor = buildCompactCursor({
+    run: packet.run,
+    status: packet.status,
+    latest_checkpoint_id: latestCheckpoint?.checkpoint_id ?? null,
+    last_meaningful_update_at: firstDefined(
+      selectedRun.live_signal?.last_meaningful_update_at,
+      latestActivity?.timestamp,
+      selectedRun.run.updated_at
+    ),
+    last_activity_id: firstDefined(latestActivity?.activity_id, latestCheckpoint?.checkpoint_id),
+    packet_digest,
+  });
+
+  return {
+    packet: {
+      id: cursor.cursor,
+      ...packet,
+    },
+    selection,
+    selectedRun,
+    comparisonRun,
+    fingerprint,
+    cursor,
+    packet_digest,
+  };
+}
+
+export function buildCompactPacket(projected, options = {}) {
+  return buildCompactPacketDetails(projected, options).packet;
+}