dextunnel 0.1.0

package/src/lib/debug-harness-service.mjs

@@ -0,0 +1,173 @@
+export function createDebugHarnessService({
+  ADVISORY_PARTICIPANT_IDS = [],
+  appServerState,
+  broadcast = () => {},
+  buildLivePayload = () => ({}),
+  getDefaultCwd = () => process.cwd(),
+  liveState,
+  nowIso = () => new Date().toISOString(),
+  nowMs = () => Date.now(),
+  queueCompanionWakeup = () => {}
+} = {}) {
+  function createDebugPendingInteraction(kind) {
+    const thread = liveState.selectedThreadSnapshot?.thread || null;
+    const threadId = thread?.id || liveState.selectedThreadId || "debug-thread";
+    const cwd = thread?.cwd || liveState.selectedProjectCwd || getDefaultCwd();
+    const requestId = `debug-${kind}-${nowMs()}`;
+
+    switch (kind) {
+      case "command":
+        return {
+          actionKind: "approval",
+          approveLabel: "Approve once",
+          availableDecisions: ["accept", "acceptForSession", "decline", "cancel"],
+          canApproveForSession: true,
+          command: "npm test",
+          cwd,
+          debug: true,
+          declineLabel: "Decline",
+          detail: "Local-only harness request for command approval.",
+          kind: "command",
+          method: "item/commandExecution/requestApproval",
+          requestId,
+          sessionActionLabel: "Approve for session",
+          threadId,
+          title: "Debug command approval"
+        };
+      case "file_change":
+        return {
+          actionKind: "approval",
+          approveLabel: "Approve",
+          availableDecisions: ["accept", "decline", "cancel"],
+          canApproveForSession: false,
+          debug: true,
+          declineLabel: "Decline",
+          detail: "Local-only harness request for file-change approval.",
+          kind: "file_change",
+          method: "item/fileChange/requestApproval",
+          requestId,
+          sessionActionLabel: "",
+          threadId,
+          title: "Debug file change"
+        };
+      case "permissions":
+        return {
+          actionKind: "approval",
+          approveLabel: "Allow turn",
+          canApproveForSession: true,
+          debug: true,
+          declineLabel: "Decline",
+          detail: "Local-only harness request for permissions approval.",
+          kind: "permissions",
+          method: "item/permissions/requestApproval",
+          permissions: {
+            filesystem: "workspace-write",
+            network: true
+          },
+          requestId,
+          sessionActionLabel: "Allow session",
+          threadId,
+          title: "Debug permissions request"
+        };
+      case "user_input":
+        return {
+          actionKind: "user_input",
+          debug: true,
+          detail: "Local-only harness request for tool user input.",
+          kind: "tool_input",
+          method: "item/tool/requestUserInput",
+          questions: [
+            {
+              header: "Deploy note",
+              id: "deploy_note",
+              isOther: true,
+              options: [{ label: "Ship it" }, { label: "Hold for review" }],
+              question: "What note should be attached to this run?"
+            },
+            {
+              header: "Token",
+              id: "token",
+              isSecret: true,
+              question: "Optional secret token"
+            }
+          ],
+          requestId,
+          submitLabel: "Submit",
+          threadId,
+          title: "Debug user input"
+        };
+      default:
+        throw new Error(`Unsupported debug interaction kind: ${kind}`);
+    }
+  }
+
+  function setDebugPendingInteraction(kind) {
+    if (liveState.pendingInteraction) {
+      throw new Error("Resolve the pending interaction before creating another one.");
+    }
+
+    liveState.pendingInteraction = createDebugPendingInteraction(kind);
+    liveState.lastError = null;
+    appServerState.lastInteraction = {
+      at: nowIso(),
+      kind,
+      source: "debug-harness",
+      status: "pending",
+      threadId: liveState.pendingInteraction.threadId
+    };
+    broadcast("live", buildLivePayload());
+    return buildLivePayload();
+  }
+
+  function clearDebugPendingInteraction() {
+    if (liveState.pendingInteraction?.debug) {
+      liveState.pendingInteraction = null;
+      liveState.lastError = null;
+      appServerState.lastInteraction = {
+        at: nowIso(),
+        kind: "debug-clear",
+        source: "debug-harness",
+        status: "cleared",
+        threadId: liveState.selectedThreadId || null
+      };
+      broadcast("live", buildLivePayload());
+    }
+
+    return buildLivePayload();
+  }
+
+  function setDebugCompanionWakeup({ advisorId = "", threadId = null, wakeKind = "summary" } = {}) {
+    const nextThreadId = threadId || liveState.selectedThreadId || liveState.selectedThreadSnapshot?.thread?.id || null;
+    if (!nextThreadId) {
+      throw new Error("Select a live session before creating a companion wakeup.");
+    }
+
+    const normalizedWakeKind = String(wakeKind || "").trim().toLowerCase() === "review" ? "review" : "summary";
+    const normalizedAdvisorId = String(advisorId || "").trim().toLowerCase();
+    const nextAdvisorId =
+      normalizedAdvisorId || (normalizedWakeKind === "review" ? "oracle" : "gemini");
+    if (!ADVISORY_PARTICIPANT_IDS.includes(nextAdvisorId)) {
+      throw new Error(`Unsupported advisory participant: ${advisorId}`);
+    }
+
+    queueCompanionWakeup({
+      advisorId: nextAdvisorId,
+      text:
+        normalizedWakeKind === "review"
+          ? "Review ready: local-only wakeup harness seeded a review notice for this channel."
+          : "Summary ready: local-only wakeup harness seeded a summary notice for this channel.",
+      threadId: nextThreadId,
+      turnId: null,
+      wakeKey: `debug-${nextAdvisorId}-${normalizedWakeKind}:${nowMs()}`,
+      wakeKind: normalizedWakeKind
+    });
+    return buildLivePayload();
+  }
+
+  return {
+    clearDebugPendingInteraction,
+    createDebugPendingInteraction,
+    setDebugCompanionWakeup,
+    setDebugPendingInteraction
+  };
+}

package/src/lib/desktop-integration.mjs

@@ -0,0 +1,146 @@
+import { execFile } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export const CODEX_NAVIGATION_SEQUENCES = {
+  viewBackForward: [
+    { itemTitle: "Back", menuTitle: "View" },
+    { itemTitle: "Forward", menuTitle: "View" }
+  ],
+  viewPreviousNextThread: [
+    { itemTitle: "Previous Thread", menuTitle: "View" },
+    { itemTitle: "Next Thread", menuTitle: "View" }
+  ]
+};
+
+function escapeAppleScriptString(value) {
+  return String(value || "").replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
+}
+
+export function buildCodexMenuItemAppleScript({
+  activate = true,
+  activationDelaySeconds = 0.2,
+  itemTitle,
+  menuTitle
+} = {}) {
+  const escapedMenuTitle = escapeAppleScriptString(menuTitle);
+  const escapedItemTitle = escapeAppleScriptString(itemTitle);
+  const lines = [];
+
+  if (activate) {
+    lines.push('tell application "Codex" to activate');
+    if (activationDelaySeconds > 0) {
+      lines.push(`delay ${Number(activationDelaySeconds)}`);
+    }
+  }
+
+  lines.push('tell application "System Events"');
+  lines.push('  tell process "Codex"');
+  lines.push(
+    `    click menu item "${escapedItemTitle}" of menu "${escapedMenuTitle}" of menu bar item "${escapedMenuTitle}" of menu bar 1`
+  );
+  lines.push("  end tell");
+  lines.push("end tell");
+
+  return lines;
+}
+
+export async function activateCodex({
+  activationDelayMs = 200,
+  openCommand = execFileAsync,
+  wait = delay
+} = {}) {
+  await openCommand("osascript", ["-e", 'tell application "Codex" to activate']);
+  if (activationDelayMs > 0) {
+    await wait(activationDelayMs);
+  }
+  return {
+    activated: true
+  };
+}
+
+export async function runCodexMenuItem(
+  {
+    activate = true,
+    activationDelaySeconds = 0.2,
+    itemTitle,
+    menuTitle
+  } = {},
+  { scriptCommand = execFileAsync } = {}
+) {
+  if (!menuTitle || !itemTitle) {
+    throw new Error("menuTitle and itemTitle are required");
+  }
+
+  const scriptLines = buildCodexMenuItemAppleScript({
+    activate,
+    activationDelaySeconds,
+    itemTitle,
+    menuTitle
+  });
+  const args = scriptLines.flatMap((line) => ["-e", line]);
+  await scriptCommand("osascript", args);
+  return {
+    activated: activate,
+    itemTitle,
+    menuTitle
+  };
+}
+
+export async function runCodexNavigationSequence(
+  sequenceId,
+  {
+    activateEachStep = false,
+    activationDelaySeconds = 0.2,
+    runMenuItem = runCodexMenuItem,
+    stepDelayMs = 120,
+    wait = delay
+  } = {}
+) {
+  const steps = CODEX_NAVIGATION_SEQUENCES[sequenceId];
+  if (!Array.isArray(steps)) {
+    throw new Error(`Unknown Codex navigation sequence: ${sequenceId}`);
+  }
+
+  const completed = [];
+
+  for (let index = 0; index < steps.length; index += 1) {
+    const step = steps[index];
+    const result = await runMenuItem(
+      {
+        activate: activateEachStep || index === 0,
+        activationDelaySeconds,
+        ...step
+      }
+    );
+    completed.push(result);
+    if (index < steps.length - 1 && stepDelayMs > 0) {
+      await wait(stepDelayMs);
+    }
+  }
+
+  return {
+    sequenceId,
+    steps: completed
+  };
+}
+
+export function buildCodexThreadDeeplink(threadId) {
+  const normalized = String(threadId || "").trim();
+  if (!normalized) {
+    throw new Error("threadId is required");
+  }
+
+  return `codex://threads/${encodeURIComponent(normalized)}`;
+}
+
+export async function openThreadInCodex(threadId, { openCommand = execFileAsync } = {}) {
+  const deeplink = buildCodexThreadDeeplink(threadId);
+  await openCommand("open", [deeplink]);
+  return {
+    deeplink,
+    threadId: String(threadId || "").trim()
+  };
+}

package/src/lib/desktop-rehydration-smoke.mjs

@@ -0,0 +1,269 @@
+import process from "node:process";
+import { setTimeout as delay } from "node:timers/promises";
+
+import { createCodexAppServerBridge } from "./codex-app-server-client.mjs";
+import {
+  openThreadInCodex,
+  runCodexNavigationSequence
+} from "./desktop-integration.mjs";
+
+export const DESKTOP_REHYDRATION_ATTEMPTS = [
+  {
+    category: "desktop",
+    destructive: false,
+    expectedDesktopOutcome: "navigation-only",
+    id: "revealInCodex",
+    label: "Reveal in Codex"
+  },
+  {
+    category: "appServer",
+    destructive: false,
+    expectedDesktopOutcome: "none",
+    id: "threadRead",
+    label: "app-server thread/read"
+  },
+  {
+    category: "appServer",
+    destructive: false,
+    expectedDesktopOutcome: "negative",
+    id: "threadResume",
+    label: "app-server thread/resume"
+  },
+  {
+    category: "desktop",
+    destructive: false,
+    expectedDesktopOutcome: "negative",
+    id: "viewBackForward",
+    label: "Codex View -> Back / Forward"
+  },
+  {
+    category: "desktop",
+    destructive: false,
+    expectedDesktopOutcome: "negative",
+    id: "viewPreviousNextThread",
+    label: "Codex View -> Previous Thread / Next Thread"
+  }
+];
+
+function defaultStamp(now = new Date()) {
+  const iso = now.toISOString().replace(/[-:.]/g, "");
+  return iso.replace(".000Z", "Z");
+}
+
+function buildProbe(promptStamp) {
+  const normalized = String(promptStamp || defaultStamp()).trim();
+  const prompt = `REHYDRATION_SMOKE_${normalized}. Reply with exactly: REHYDRATION_SMOKE_ACK_${normalized}.`;
+  const ack = `REHYDRATION_SMOKE_ACK_${normalized}`;
+  return {
+    ack,
+    prompt,
+    stamp: normalized
+  };
+}
+
+function objectContainsMarker(value, marker) {
+  return JSON.stringify(value || {}).includes(marker);
+}
+
+function stringifyError(error) {
+  if (!error) {
+    return "Unknown error.";
+  }
+  if (error instanceof Error) {
+    return error.message || error.name || "Error";
+  }
+  return String(error);
+}
+
+function createManualChecks({ probe } = {}) {
+  return [
+    `After each attempt, check whether "${probe.prompt}" and "${probe.ack}" are visible in Codex without restarting.`,
+    "Expect Reveal in Codex to navigate only, not force desktop rehydration.",
+    "Expect thread/read and thread/resume to prove app-server state, not the desktop view.",
+    "Expect View navigation attempts to stay best-effort and currently negative unless Codex changed.",
+    `If you need a positive desktop visibility check, quit and reopen the Codex app manually and confirm "${probe.prompt}" and "${probe.ack}" appear afterward.`
+  ];
+}
+
+async function waitForProbeReadback(
+  bridge,
+  threadId,
+  {
+    ack,
+    prompt,
+    probePollMs = 1200,
+    probeTimeoutMs = 45000,
+    seed = {},
+    wait = delay
+  } = {}
+) {
+  let promptVisible = Boolean(seed.promptVisible);
+  let ackVisible = Boolean(seed.ackVisible);
+  let thread = seed.thread || null;
+  const startedAt = Date.now();
+
+  while (!(promptVisible && ackVisible)) {
+    thread = await bridge.readThread(threadId, true);
+    promptVisible = objectContainsMarker(thread, prompt);
+    ackVisible = objectContainsMarker(thread, ack);
+
+    if (promptVisible && ackVisible) {
+      break;
+    }
+
+    if (Date.now() - startedAt >= probeTimeoutMs) {
+      break;
+    }
+
+    if (probePollMs > 0) {
+      await wait(probePollMs);
+    }
+  }
+
+  return {
+    ackVisible,
+    promptVisible,
+    status: promptVisible && ackVisible ? "persisted" : "readback-mismatch",
+    thread
+  };
+}
+
+export async function runDesktopRehydrationSmoke({
+  bridgeFactory = createCodexAppServerBridge,
+  cwd = process.cwd(),
+  includeProbe = true,
+  openThread = openThreadInCodex,
+  probePollMs = 1200,
+  promptStamp = defaultStamp(),
+  probeTimeoutMs = 45000,
+  runNavigationSequence = runCodexNavigationSequence,
+  threadId,
+  wait = delay
+} = {}) {
+  const normalizedThreadId = String(threadId || "").trim();
+  if (!normalizedThreadId) {
+    throw new Error("threadId is required");
+  }
+
+  const bridge = await bridgeFactory();
+  const probe = buildProbe(promptStamp);
+  const report = {
+    attempts: [],
+    cwd,
+    manualChecks: [],
+    probe: {
+      ...probe,
+      included: includeProbe,
+      status: includeProbe ? "pending" : "skipped"
+    },
+    threadId: normalizedThreadId
+  };
+
+  const pushAttempt = (entry) => {
+    report.attempts.push(entry);
+    return entry;
+  };
+
+  try {
+    if (includeProbe) {
+      const sendResult = await bridge.sendText({
+        createThreadIfMissing: false,
+        cwd,
+        text: probe.prompt,
+        threadId: normalizedThreadId,
+        timeoutMs: probeTimeoutMs
+      });
+      const readback = await waitForProbeReadback(bridge, normalizedThreadId, {
+        ack: probe.ack,
+        prompt: probe.prompt,
+        probePollMs,
+        probeTimeoutMs,
+        seed: {
+          ackVisible: objectContainsMarker(sendResult?.snapshot, probe.ack),
+          promptVisible: objectContainsMarker(sendResult?.snapshot, probe.prompt),
+          thread: sendResult?.thread || null
+        },
+        wait
+      });
+      report.probe = {
+        ...probe,
+        ackVisible: readback.ackVisible,
+        included: true,
+        promptVisible: readback.promptVisible,
+        status: readback.status,
+        turnId: sendResult?.turn?.id || null,
+        turnStatus: sendResult?.turn?.status || null
+      };
+    }
+
+    const skipDesktopAttempts = includeProbe && report.probe.status !== "persisted";
+
+    for (const attempt of DESKTOP_REHYDRATION_ATTEMPTS) {
+      if (skipDesktopAttempts && attempt.category === "desktop") {
+        pushAttempt({
+          ...attempt,
+          detail: "Skipped because write/readback proof did not settle cleanly.",
+          status: "skipped"
+        });
+        continue;
+      }
+
+      try {
+        let result = null;
+
+        switch (attempt.id) {
+          case "revealInCodex":
+            result = await openThread(normalizedThreadId);
+            break;
+          case "threadRead": {
+            const thread = await bridge.readThread(normalizedThreadId, true);
+            result = {
+              ackVisible: includeProbe ? objectContainsMarker(thread, probe.ack) : null,
+              promptVisible: includeProbe ? objectContainsMarker(thread, probe.prompt) : null,
+              threadId: thread?.id || normalizedThreadId
+            };
+            break;
+          }
+          case "threadResume": {
+            const thread = await bridge.resumeThread({
+              cwd,
+              threadId: normalizedThreadId
+            });
+            result = {
+              ackVisible: includeProbe ? objectContainsMarker(thread, probe.ack) : null,
+              promptVisible: includeProbe ? objectContainsMarker(thread, probe.prompt) : null,
+              threadId: thread?.id || normalizedThreadId
+            };
+            break;
+          }
+          case "viewBackForward":
+            result = await runNavigationSequence("viewBackForward");
+            break;
+          case "viewPreviousNextThread":
+            result = await runNavigationSequence("viewPreviousNextThread");
+            break;
+          default:
+            throw new Error(`Unknown rehydration attempt: ${attempt.id}`);
+        }
+
+        pushAttempt({
+          ...attempt,
+          result,
+          status: "ok"
+        });
+      } catch (error) {
+        pushAttempt({
+          ...attempt,
+          detail: stringifyError(error),
+          status: "failed"
+        });
+      }
+    }
+
+    report.manualChecks = createManualChecks({ probe });
+
+    return report;
+  } finally {
+    await bridge.dispose?.();
+  }
+}

package/src/lib/dextunnel-cli.mjs

@@ -0,0 +1,122 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export function packageJsonPathFromImportMetaUrl(importMetaUrl) {
+  const scriptPath = fileURLToPath(importMetaUrl);
+  return path.resolve(path.dirname(scriptPath), "../../package.json");
+}
+
+export function readPackageVersion({ packageJsonPath }) {
+  const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+  return String(packageJson.version || "0.0.0");
+}
+
+export function renderHelp({ version }) {
+  return [
+    `Dextunnel ${version}`,
+    "",
+    "Usage:",
+    "  dextunnel serve [--host <host>] [--port <port>] [--network] [--expose-host-surface]",
+    "  dextunnel doctor",
+    "  dextunnel --help",
+    "  dextunnel --version",
+    "",
+    "Commands:",
+    "  serve   Start the local Dextunnel bridge (default command).",
+    "  doctor  Run the local Codex bridge preflight checks.",
+    "",
+    "Options:",
+    "  --host <host>              Bind the bridge to a specific host.",
+    "  --port <port>              Bind the bridge to a specific port.",
+    "  --network                  Bind to 0.0.0.0 for LAN or Tailscale access.",
+    "  --expose-host-surface      Allow the host surface beyond loopback.",
+    "  -h, --help                 Show this help message.",
+    "  -v, --version              Show the package version."
+  ].join("\n");
+}
+
+function parsePort(value) {
+  const port = Number(value);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid port: ${value}`);
+  }
+  return String(port);
+}
+
+export function parseServeArgs(args, { version }) {
+  const env = {};
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    switch (arg) {
+      case "--help":
+      case "-h":
+        return { kind: "help", text: renderHelp({ version }) };
+      case "--version":
+      case "-v":
+        return { kind: "version", text: version };
+      case "--network":
+        env.DEXTUNNEL_HOST = "0.0.0.0";
+        break;
+      case "--expose-host-surface":
+        env.DEXTUNNEL_EXPOSE_HOST_SURFACE = "1";
+        break;
+      case "--host": {
+        const value = args[index + 1];
+        if (!value) {
+          throw new Error("Missing value for --host");
+        }
+        env.DEXTUNNEL_HOST = value;
+        index += 1;
+        break;
+      }
+      case "--port": {
+        const value = args[index + 1];
+        if (!value) {
+          throw new Error("Missing value for --port");
+        }
+        env.PORT = parsePort(value);
+        index += 1;
+        break;
+      }
+      default:
+        throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return { kind: "serve", env };
+}
+
+export function parseDextunnelCli(argv, { version }) {
+  const args = [...argv];
+  const first = args[0];
+
+  if (!first) {
+    return { kind: "serve", env: {} };
+  }
+
+  switch (first) {
+    case "serve":
+      return parseServeArgs(args.slice(1), { version });
+    case "doctor":
+      if (args.length > 1) {
+        throw new Error("The doctor command does not accept extra arguments.");
+      }
+      return { kind: "doctor" };
+    case "help":
+    case "--help":
+    case "-h":
+      return { kind: "help", text: renderHelp({ version }) };
+    case "version":
+    case "--version":
+    case "-v":
+      return { kind: "version", text: version };
+    default:
+      if (first.startsWith("-")) {
+        return parseServeArgs(args, { version });
+      }
+      throw new Error(`Unknown command: ${first}`);
+  }
+}