vericify 1.2.0 → 1.3.0

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;
+}

package/src/context/select.js

@@ -0,0 +1,65 @@
+import { compareRunsByAttention } from "../projection/live-signal.js";
+
+const TRACE_PREFIX = "trace:";
+
+export function isTraceRun(runDetail) {
+  return String(runDetail?.run?.run_id ?? "").startsWith(TRACE_PREFIX);
+}
+
+export function sortCompactRuns(runs) {
+  return [...(runs ?? [])].sort(compareRunsByAttention);
+}
+
+export function findBestComparisonRun(selectedRun, rankedRuns) {
+  const selectedRunId = selectedRun?.run?.run_id;
+  const neighborIds = Array.isArray(selectedRun?.similarity?.neighbors)
+    ? selectedRun.similarity.neighbors.map((neighbor) => neighbor.run_id).filter(Boolean)
+    : [];
+
+  for (const neighborId of neighborIds) {
+    const candidate = rankedRuns.find((run) => run.run?.run_id === neighborId);
+    if (candidate && candidate.run?.run_id !== selectedRunId && !isTraceRun(candidate)) {
+      return candidate;
+    }
+  }
+
+  return rankedRuns.find((run) => run.run?.run_id !== selectedRunId && !isTraceRun(run)) ?? null;
+}
+
+export function selectCompactRun(projected, options = {}) {
+  const runs = Array.isArray(projected?.runs) ? projected.runs : [];
+  if (!runs.length) {
+    throw new Error("Compact packet requires projected runs.");
+  }
+
+  const rankedRuns = sortCompactRuns(runs);
+  const explicitRunId = String(options.runId ?? "").trim();
+  const explicitRun = explicitRunId ? rankedRuns.find((run) => run.run?.run_id === explicitRunId) : undefined;
+  if (explicitRunId && !explicitRun) {
+    throw new Error(`Unknown run id: ${explicitRunId}`);
+  }
+
+  const workspaceRun = rankedRuns.find((run) => run.run?.run_id === "workspace:current");
+  let selectedRun = explicitRun ?? workspaceRun ?? rankedRuns.find((run) => !isTraceRun(run)) ?? rankedRuns[0];
+  if (!explicitRun && selectedRun && isTraceRun(selectedRun)) {
+    selectedRun = rankedRuns.find((run) => !isTraceRun(run)) ?? selectedRun;
+  }
+
+  const hasNonTraceRun = rankedRuns.some((run) => !isTraceRun(run));
+  const surfacedRuns = hasNonTraceRun
+    ? rankedRuns.filter((run) => !isTraceRun(run) || run.run?.run_id === selectedRun?.run?.run_id)
+    : rankedRuns;
+  const hiddenRuns = rankedRuns.filter((run) => !surfacedRuns.includes(run));
+
+  return {
+    selectedRun,
+    rankedRuns,
+    surfacedRuns,
+    hiddenRuns,
+    hiddenRunCount: hiddenRuns.length,
+    surfaceRunCount: surfacedRuns.length,
+    comparisonRun: findBestComparisonRun(selectedRun, rankedRuns),
+    explicitRunId: explicitRunId || undefined,
+    workspaceRun,
+  };
+}