dextunnel 0.1.0

package/src/lib/interaction-resolution-service.mjs

@@ -0,0 +1,185 @@
+export function createInteractionResolutionService({
+  appServerState,
+  broadcast = () => {},
+  buildLivePayload = () => ({}),
+  controlLeaseTtlMs,
+  ensureRemoteControlLease = () => {},
+  getWatcherController = () => null,
+  hasWatcherController = () => false,
+  liveState,
+  maybeWakeCompanionForInteractionResolution = () => {},
+  nowIso = () => new Date().toISOString(),
+  setControlLease = () => {}
+} = {}) {
+  function isWriterSurface(source) {
+    return source === "remote" || source === "agent";
+  }
+
+  function normalizeUserInputAnswers(questions, answers = {}) {
+    const payload = {};
+
+    for (const question of questions || []) {
+      const raw = answers[question.id];
+      const list = Array.isArray(raw)
+        ? raw.map((value) => String(value).trim()).filter(Boolean)
+        : raw == null
+          ? []
+          : [String(raw).trim()].filter(Boolean);
+
+      if (list.length > 0) {
+        payload[question.id] = { answers: list };
+      }
+    }
+
+    return payload;
+  }
+
+  function getCommandDecision(action, pending) {
+    const decisions = pending.availableDecisions || [];
+
+    if (action === "decline") {
+      return decisions.includes("decline") ? "decline" : "cancel";
+    }
+
+    if (action === "session" && decisions.includes("acceptForSession")) {
+      return "acceptForSession";
+    }
+
+    return "accept";
+  }
+
+  async function resolvePendingInteraction(body) {
+    const pending = liveState.pendingInteraction;
+    if (!pending) {
+      throw new Error("No pending interaction.");
+    }
+
+    const authorityClientId = body.authorityClientId || null;
+    if (isWriterSurface(body.source) && pending.threadId) {
+      ensureRemoteControlLease(pending.threadId, body.source, authorityClientId);
+    }
+
+    const activeWatcherController = getWatcherController();
+
+    if (!pending.debug && !hasWatcherController()) {
+      throw new Error("Live watcher is not connected.");
+    }
+
+    if (pending.debug) {
+      appServerState.lastInteraction = {
+        action: body.action || (pending.actionKind === "user_input" ? "submit" : "approve"),
+        answers:
+          pending.actionKind === "user_input"
+            ? normalizeUserInputAnswers(pending.questions, body.answers || {})
+            : null,
+        at: nowIso(),
+        flowContinuation: pending.flowContinuation || "",
+        flowLabel: pending.flowLabel || "",
+        flowStep: pending.flowStep || null,
+        kind: pending.kind,
+        kindLabel: pending.kindLabel || null,
+        retryAttempt: pending.retryAttempt || 1,
+        summary: pending.summary || null,
+        source: "debug-harness",
+        status: "resolved",
+        threadId: pending.threadId || null
+      };
+      liveState.pendingInteraction = null;
+      liveState.lastError = null;
+      maybeWakeCompanionForInteractionResolution({
+        interaction: appServerState.lastInteraction,
+        threadId: pending.threadId || null
+      });
+      broadcast("live", buildLivePayload());
+      return;
+    }
+
+    switch (pending.method) {
+      case "item/commandExecution/requestApproval":
+        activeWatcherController.respond(pending.requestId, {
+          decision: getCommandDecision(body.action || "approve", pending)
+        });
+        break;
+      case "item/fileChange/requestApproval":
+        activeWatcherController.respond(pending.requestId, {
+          decision: body.action === "decline" ? "decline" : "accept"
+        });
+        break;
+      case "item/permissions/requestApproval":
+        if ((body.action || "approve") !== "approve") {
+          if (body.action === "session") {
+            activeWatcherController.respond(pending.requestId, {
+              permissions: pending.permissions || {},
+              scope: "session"
+            });
+            break;
+          }
+
+          activeWatcherController.respondError(pending.requestId, "Permission request declined by the companion.");
+          break;
+        }
+
+        activeWatcherController.respond(pending.requestId, {
+          permissions: pending.permissions || {},
+          scope: body.scope === "session" ? "session" : "turn"
+        });
+        break;
+      case "item/tool/requestUserInput": {
+        if ((body.action || "submit") !== "submit") {
+          activeWatcherController.respondError(pending.requestId, "User input cancelled by the companion.");
+          break;
+        }
+
+        const answers = normalizeUserInputAnswers(pending.questions, body.answers || {});
+        activeWatcherController.respond(pending.requestId, {
+          answers
+        });
+        break;
+      }
+      default:
+        activeWatcherController.respondError(pending.requestId, "Unsupported interaction from Dextunnel.");
+        break;
+    }
+
+    appServerState.lastInteraction = {
+      action: body.action || (pending.actionKind === "user_input" ? "submit" : "approve"),
+      answers:
+        pending.actionKind === "user_input"
+          ? normalizeUserInputAnswers(pending.questions, body.answers || {})
+          : null,
+      at: nowIso(),
+      flowContinuation: pending.flowContinuation || "",
+      flowLabel: pending.flowLabel || "",
+      flowStep: pending.flowStep || null,
+      itemId: pending.itemId || null,
+      kind: pending.kind,
+      kindLabel: pending.kindLabel || null,
+      requestId: pending.requestId,
+      retryAttempt: pending.retryAttempt || 1,
+      summary: pending.summary || null,
+      source: "app-server",
+      status: "responded",
+      threadId: pending.threadId || null,
+      turnId: pending.turnId || null
+    };
+    if (isWriterSurface(body.source) && pending.threadId) {
+      setControlLease({
+        clientId: authorityClientId,
+        owner: body.source,
+        reason: "interaction",
+        source: body.source,
+        threadId: pending.threadId,
+        ttlMs: controlLeaseTtlMs
+      });
+    }
+    liveState.pendingInteraction = null;
+    liveState.lastError = null;
+    broadcast("live", buildLivePayload());
+  }
+
+  return {
+    getCommandDecision,
+    normalizeUserInputAnswers,
+    resolvePendingInteraction
+  };
+}

package/src/lib/interaction-state.mjs

@@ -0,0 +1,360 @@
+export function createInteractionStateService({
+  appServerState,
+  liveState,
+  nowIso = () => new Date().toISOString(),
+  trimInteractionText = (value, maxLength = 72) => String(value || "").trim().slice(0, maxLength)
+} = {}) {
+  function interactionKindLabel(request) {
+    switch (request.method) {
+      case "item/commandExecution/requestApproval":
+        return "Command";
+      case "item/fileChange/requestApproval":
+        return "File change";
+      case "item/permissions/requestApproval":
+        return "Permissions";
+      case "item/tool/requestUserInput":
+        return "Tool input";
+      default:
+        return "Action";
+    }
+  }
+
+  function interactionRequestSummary(request) {
+    switch (request.method) {
+      case "item/commandExecution/requestApproval":
+        return trimInteractionText(request.params?.command || "command approval", 52);
+      case "item/fileChange/requestApproval":
+        return trimInteractionText(request.params?.changes?.[0]?.path || "file change", 52);
+      case "item/permissions/requestApproval":
+        return "permissions";
+      case "item/tool/requestUserInput": {
+        const firstQuestion = request.params?.questions?.[0] || null;
+        const questionText = `${firstQuestion?.question || ""}`;
+        const matchedTool = questionText.match(/tool "([^"]+)"/i);
+        if (matchedTool?.[1]) {
+          return `${matchedTool[1]} approval`;
+        }
+        return trimInteractionText(firstQuestion?.header || firstQuestion?.question || "user input", 52);
+      }
+      default:
+        return trimInteractionText(request.method || "interaction", 52);
+    }
+  }
+
+  function interactionRetryContinuation(summary, action = null) {
+    switch (action) {
+      case "cancel":
+        return `Codex asked for ${summary} again after the last step was canceled.`;
+      case "decline":
+        return `Codex asked for ${summary} again after the last step was declined.`;
+      case "session":
+        return `Codex asked for ${summary} again after session access was allowed.`;
+      case "submit":
+        return `Codex asked for ${summary} again after the last input was submitted.`;
+      default:
+        return `Codex asked for ${summary} again in the same turn.`;
+    }
+  }
+
+  function describeInteractionFlow({
+    actionKind = "",
+    flowStep = 1,
+    previousAction = null,
+    previousSummary = "",
+    retryAttempt = 1,
+    summary = ""
+  } = {}) {
+    const flowLabel = flowStep > 1 ? `Step ${flowStep} of the live flow` : "Waiting on this turn";
+
+    if (retryAttempt > 1) {
+      return {
+        flowContinuation: interactionRetryContinuation(summary, previousAction),
+        flowLabel
+      };
+    }
+
+    if (flowStep > 1) {
+      if (previousSummary && previousSummary !== summary) {
+        return {
+          flowContinuation: `Last step settled: ${previousSummary}. Now waiting on ${summary}.`,
+          flowLabel
+        };
+      }
+
+      return {
+        flowContinuation: summary
+          ? `Continuing ${summary} in the same turn.`
+          : "Continuing the same live flow.",
+        flowLabel
+      };
+    }
+
+    return {
+      flowContinuation:
+        actionKind === "user_input"
+          ? "Codex needs this input before the turn can continue."
+          : "Codex needs this decision before the turn can continue.",
+      flowLabel
+    };
+  }
+
+  function beginInteractionFlow(request) {
+    const threadId = request.params?.threadId || null;
+    const turnId = request.params?.turnId || null;
+    const summary = interactionRequestSummary(request);
+    const previous = liveState.interactionFlow;
+    const sameTurn = Boolean(
+      previous &&
+        previous.threadId &&
+        previous.threadId === threadId &&
+        previous.turnId &&
+        previous.turnId === turnId
+    );
+    const sameRequest = Boolean(sameTurn && previous.method === request.method && previous.summary === summary);
+    const lastInteraction =
+      appServerState.lastInteraction?.threadId === threadId && appServerState.lastInteraction?.turnId === turnId
+        ? appServerState.lastInteraction
+        : null;
+    const step = sameTurn ? (previous.step || 0) + 1 : 1;
+    const retryAttempt = sameRequest ? (previous.retryAttempt || 1) + 1 : 1;
+
+    liveState.interactionFlow = {
+      method: request.method,
+      previousAction: sameRequest ? lastInteraction?.action || null : null,
+      previousSummary: sameTurn && !sameRequest ? previous.summary || "" : sameTurn ? previous.previousSummary || "" : "",
+      requestId: request.requestId,
+      retryAttempt,
+      startedAt: sameTurn ? previous.startedAt : nowIso(),
+      step,
+      summary,
+      threadId,
+      turnId
+    };
+
+    return liveState.interactionFlow;
+  }
+
+  function clearInteractionFlow({ threadId = null } = {}) {
+    if (!threadId || liveState.interactionFlow?.threadId === threadId) {
+      liveState.interactionFlow = null;
+    }
+  }
+
+  function summarizeNotificationInteraction(pending, request) {
+    return {
+      at: nowIso(),
+      detail: pending?.detail || "",
+      flowContinuation: pending?.flowContinuation || "",
+      flowLabel: pending?.flowLabel || "",
+      flowStep: pending?.flowStep || null,
+      itemId: request.params?.itemId || null,
+      kind: pending?.kind || "interaction",
+      kindLabel: pending?.kindLabel || null,
+      requestId: request.requestId,
+      retryAttempt: pending?.retryAttempt || 1,
+      summary: pending?.summary || interactionRequestSummary(request),
+      source: "app-server",
+      status: "pending",
+      threadId: pending?.threadId || request.params?.threadId || null,
+      turnId: pending?.turnId || request.params?.turnId || null
+    };
+  }
+
+  function mapPendingInteraction(request, flow = null) {
+    const flowStep = flow?.step || 1;
+    const kindLabel = interactionKindLabel(request);
+    const summary = interactionRequestSummary(request);
+    const retryAttempt = flow?.retryAttempt || 1;
+    const { flowLabel, flowContinuation } = describeInteractionFlow({
+      actionKind:
+        request.method === "item/tool/requestUserInput"
+          ? "user_input"
+          : "approval",
+      flowStep,
+      previousAction: flow?.previousAction || null,
+      previousSummary: flow?.previousSummary || "",
+      retryAttempt,
+      summary
+    });
+
+    switch (request.method) {
+      case "item/commandExecution/requestApproval":
+        return {
+          actionKind: "approval",
+          approveLabel: "Approve once",
+          availableDecisions: request.params.availableDecisions || ["accept", "decline", "cancel"],
+          canApproveForSession: (request.params.availableDecisions || []).includes("acceptForSession"),
+          command: request.params.command || null,
+          cwd: request.params.cwd || null,
+          declineLabel: "Decline",
+          detail:
+            request.params.reason ||
+            request.params.command ||
+            "Codex requested permission to execute a command.",
+          flowContinuation,
+          flowLabel,
+          flowStep,
+          itemId: request.params.itemId || null,
+          kind: "command",
+          kindLabel,
+          method: request.method,
+          requestId: request.requestId,
+          retryAttempt,
+          sessionActionLabel: "Approve for session",
+          summary,
+          threadId: request.params.threadId,
+          title: request.params.command || "Approve command",
+          turnId: request.params.turnId
+        };
+      case "item/fileChange/requestApproval":
+        return {
+          actionKind: "approval",
+          approveLabel: "Approve",
+          availableDecisions: ["accept", "decline", "cancel"],
+          canApproveForSession: false,
+          declineLabel: "Decline",
+          detail: request.params.reason || "Codex requested approval for a file change.",
+          flowContinuation,
+          flowLabel,
+          flowStep,
+          itemId: request.params.itemId || null,
+          kind: "file_change",
+          kindLabel,
+          method: request.method,
+          requestId: request.requestId,
+          retryAttempt,
+          sessionActionLabel: "",
+          summary,
+          threadId: request.params.threadId,
+          title: "Approve file change",
+          turnId: request.params.turnId
+        };
+      case "item/permissions/requestApproval":
+        return {
+          actionKind: "approval",
+          approveLabel: "Allow turn",
+          canApproveForSession: true,
+          declineLabel: "Decline",
+          detail: request.params.reason || "Codex requested additional permissions.",
+          flowContinuation,
+          flowLabel,
+          flowStep,
+          itemId: request.params.itemId || null,
+          kind: "permissions",
+          kindLabel,
+          method: request.method,
+          permissions: request.params.permissions,
+          requestId: request.requestId,
+          retryAttempt,
+          sessionActionLabel: "Allow session",
+          summary,
+          threadId: request.params.threadId,
+          title: "Grant permissions",
+          turnId: request.params.turnId
+        };
+      case "item/tool/requestUserInput":
+        return {
+          actionKind: "user_input",
+          detail: trimInteractionText(
+            request.params.questions?.[0]?.question ||
+              request.params.questions?.[0]?.header ||
+              "Codex needs user input to continue.",
+            180
+          ),
+          flowContinuation,
+          flowLabel,
+          flowStep,
+          itemId: request.params.itemId || null,
+          kind: "tool_input",
+          kindLabel,
+          method: request.method,
+          questions: request.params.questions || [],
+          requestId: request.requestId,
+          retryAttempt,
+          submitLabel: "Submit",
+          summary,
+          threadId: request.params.threadId,
+          title: "Provide input",
+          turnId: request.params.turnId
+        };
+      default:
+        return {
+          actionKind: "unsupported",
+          detail: `Unsupported server request: ${request.method}`,
+          flowContinuation,
+          flowLabel,
+          flowStep,
+          kind: "unsupported",
+          kindLabel,
+          method: request.method,
+          requestId: request.requestId,
+          retryAttempt,
+          summary,
+          title: "Unsupported request"
+        };
+    }
+  }
+
+  function getScopedEvent(event) {
+    if (!event) {
+      return null;
+    }
+
+    const selectedThreadId = liveState.selectedThreadId || null;
+    if (!selectedThreadId || !event.threadId) {
+      return selectedThreadId ? null : event;
+    }
+
+    return event.threadId === selectedThreadId ? event : null;
+  }
+
+  function getLastInteractionForSelectedThread() {
+    return getScopedEvent(appServerState.lastInteraction || null);
+  }
+
+  function getPendingInteractionForSelectedThread() {
+    const pending = liveState.pendingInteraction || null;
+    if (!pending) {
+      return null;
+    }
+
+    const selectedThreadId = liveState.selectedThreadId || null;
+    if (!selectedThreadId || !pending.threadId) {
+      return pending;
+    }
+
+    return pending.threadId === selectedThreadId ? pending : null;
+  }
+
+  function getLastWriteForSelectedThread() {
+    return getScopedEvent(appServerState.lastWrite || null);
+  }
+
+  function getLastControlEventForSelectedThread() {
+    return getScopedEvent(appServerState.lastControlEvent || null);
+  }
+
+  function getLastSelectionEventForSelectedThread() {
+    return getScopedEvent(appServerState.lastSelectionEvent || null);
+  }
+
+  function getLastSurfaceEventForSelectedThread() {
+    return getScopedEvent(appServerState.lastSurfaceEvent || null);
+  }
+
+  return {
+    beginInteractionFlow,
+    clearInteractionFlow,
+    describeInteractionFlow,
+    getLastControlEventForSelectedThread,
+    getLastInteractionForSelectedThread,
+    getLastSelectionEventForSelectedThread,
+    getLastSurfaceEventForSelectedThread,
+    getLastWriteForSelectedThread,
+    getPendingInteractionForSelectedThread,
+    interactionKindLabel,
+    interactionRequestSummary,
+    mapPendingInteraction,
+    summarizeNotificationInteraction
+  };
+}

package/src/lib/launch-release-bar.mjs

@@ -0,0 +1,158 @@
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { APP_SERVER_DRIFT_RUNBOOK_PATH } from "./app-server-contract.mjs";
+
+export function defaultLaunchStatusPath({ cwd = process.cwd() } = {}) {
+  return path.join(cwd, ".agent", "artifacts", "launch", "local-launch-status.json");
+}
+
+export function computeLaunchFingerprint({
+  cwd = process.cwd(),
+  execFileSyncImpl = execFileSync
+} = {}) {
+  try {
+    execFileSyncImpl("git", ["-C", cwd, "rev-parse", "--git-dir"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+
+    let head = null;
+    try {
+      head = execFileSyncImpl("git", ["-C", cwd, "rev-parse", "HEAD"], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }).trim();
+    } catch {
+      head = null;
+    }
+
+    const status = execFileSyncImpl(
+      "git",
+      ["-C", cwd, "status", "--porcelain=v1", "--untracked-files=normal"],
+      {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"]
+      }
+    ).trimEnd();
+    const digest = createHash("sha1").update(status).digest("hex");
+    return {
+      head,
+      hasGit: true,
+      statusDigest: digest,
+      fingerprint: `${head || "nohead"}:${digest}`
+    };
+  } catch {
+    const digest = createHash("sha1").update(cwd).digest("hex");
+    return {
+      head: null,
+      hasGit: false,
+      statusDigest: digest,
+      fingerprint: `nogit:${digest}`
+    };
+  }
+}
+
+export async function readLaunchAttestation({ statusPath = defaultLaunchStatusPath() } = {}) {
+  try {
+    const raw = await readFile(statusPath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export function deriveLaunchBar({
+  fingerprint,
+  state,
+  requiredManualChecks = DEFAULT_MANUAL_CHECKS
+}) {
+  const automatedPass = Boolean(state?.automated?.fingerprint === fingerprint);
+  const manualPass = Boolean(state?.manual?.fingerprint === fingerprint);
+
+  const staleAutomated = Boolean(state?.automated && !automatedPass);
+  const staleManual = Boolean(state?.manual && !manualPass);
+
+  let status = "RED";
+  let message = "Automated launch checks have not been confirmed for this build.";
+  if (automatedPass && manualPass) {
+    status = "GREEN";
+    message = "Local launch bar is green.";
+  } else if (automatedPass) {
+    status = "YELLOW";
+    message = "Automated launch bar is green. Manual launch checks still required.";
+  } else if (staleAutomated || staleManual) {
+    message = "Launch attestations are stale for the current repo state. Re-run the launch checks.";
+  }
+
+  return {
+    acceptedLimitations: ACCEPTED_LAUNCH_LIMITATIONS,
+    automatedPass,
+    docs: LAUNCH_SUPPORT_DOCS,
+    manualPass,
+    message,
+    requiredManualChecks,
+    staleAutomated,
+    staleManual,
+    status
+  };
+}
+
+export async function writeLaunchAttestation({
+  kind,
+  cwd = process.cwd(),
+  statusPath = defaultLaunchStatusPath({ cwd }),
+  now = new Date().toISOString(),
+  fingerprint = computeLaunchFingerprint({ cwd })
+} = {}) {
+  if (!kind || !["automated", "manual"].includes(kind)) {
+    throw new Error("writeLaunchAttestation requires kind=automated|manual");
+  }
+
+  const current = (await readLaunchAttestation({ statusPath })) ?? { version: 1 };
+  const next = {
+    ...current,
+    version: 1,
+    [kind]: {
+      fingerprint: fingerprint.fingerprint,
+      hasGit: fingerprint.hasGit,
+      head: fingerprint.head,
+      recordedAt: now
+    }
+  };
+
+  await mkdir(path.dirname(statusPath), { recursive: true });
+  await writeFile(statusPath, `${JSON.stringify(next, null, 2)}\n`, "utf8");
+  return next;
+}
+
+export async function clearLaunchAttestations({
+  statusPath = defaultLaunchStatusPath()
+} = {}) {
+  await rm(statusPath, { force: true });
+}
+
+export const DEFAULT_MANUAL_CHECKS = [
+  "Open the remote after a fresh restart and confirm the selected room loads cleanly.",
+  "Switch feed filters and confirm the visible lane actually changes, not just the button state.",
+  "Send or queue one remote reply and confirm the control and queue UX stays clear on the selected thread.",
+  "Trigger Gemini or Oracle from the room and confirm the action only stages advisory text; it must not auto-send or silently take control.",
+  "Use Reveal in Codex and confirm the correct desktop thread opens while the restart caveat stays visible.",
+  "Confirm the remote clearly signals shared-room behavior and keeps drafts and queue local to that surface.",
+  "If testing desktop visibility, restart the Codex app and confirm remote-written turns appear after restart."
+];
+
+export const ACCEPTED_LAUNCH_LIMITATIONS = [
+  "Desktop Codex still requires a full app restart to reliably rehydrate externally written turns.",
+  "Reveal in Codex is a navigation aid, not a desktop visibility promise.",
+  "Desktop recovery is manual: quit and reopen the Codex app when you need to see newer turns there."
+];
+
+export const LAUNCH_SUPPORT_DOCS = [
+  "docs/ops/apple-host-options.md",
+  "docs/ops/apple-menubar-release.md",
+  "docs/ops/bridge-api-contract.md",
+  "docs/ops/desktop-sync.md"
+];