@hua-labs/tap 0.2.1 → 0.2.2

package/dist/index.d.mts

@@ -10,6 +10,8 @@ interface AdapterContext {
     platform: Platform;
     /** Instance ID for TAP_AGENT_ID env injection. Set by 'tap add'. */
     instanceId?: string;
+    /** Agent name from state. Injected as TAP_AGENT_NAME in MCP config. */
+    agentName?: string;
 }
 interface ProbeResult {
     installed: boolean;
@@ -129,6 +131,10 @@ interface InstanceState {
     bridge: BridgeState | null;
     /** Headless mode configuration. null = interactive (default). */
     headless: HeadlessConfig | null;
+    /** Whether bridge manages its own app-server process. Saved for restart mode preservation. */
+    manageAppServer?: boolean;
+    /** Whether bridge runs without auth gateway. Saved for restart mode preservation. */
+    noAuth?: boolean;
     warnings: string[];
 }
 /** @deprecated Use InstanceState. Kept for v1 state migration. */
@@ -199,6 +205,8 @@ interface TapSharedConfig {
     appServerUrl?: string;
     /** GitHub URL for the comms repository (used by `tap comms pull/push`). */
     commsRepoUrl?: string;
+    /** Control tower agent name. Used for auto-notify on new agent join (M111). */
+    towerName?: string;
 }
 /**
  * Local config (tap-config.local.json) — gitignored, machine-specific overrides.
@@ -214,6 +222,7 @@ interface TapResolvedConfig {
     stateDir: string;
     runtimeCommand: string;
     appServerUrl: string;
+    towerName: string | null;
 }
 /** Config resolution source for diagnostics. */
 type ConfigSource = "cli-flag" | "env" | "local-config" | "shared-config" | "legacy-shell-config" | "auto";
@@ -239,6 +248,46 @@ declare function resolveConfig(overrides?: ConfigOverrides, startDir?: string):
 declare function saveSharedConfig(repoRoot: string, config: TapSharedConfig): void;
 declare function saveLocalConfig(repoRoot: string, config: TapLocalConfig): void;
 
+interface BridgeStartOptions {
+    instanceId: InstanceId;
+    runtime: RuntimeName;
+    stateDir: string;
+    commsDir: string;
+    bridgeScript: string;
+    platform: Platform;
+    agentName?: string;
+    runtimeCommand?: string;
+    appServerUrl?: string;
+    repoRoot?: string;
+    port?: number;
+    /** Headless configuration. Passed as env vars to the bridge process. */
+    headless?: HeadlessConfig | null;
+    /** Bridge script operational flags (forwarded to codex-app-server-bridge.ts) */
+    busyMode?: "steer" | "wait";
+    pollSeconds?: number;
+    reconnectSeconds?: number;
+    messageLookbackMinutes?: number;
+    threadId?: string;
+    ephemeral?: boolean;
+    processExistingMessages?: boolean;
+    manageAppServer?: boolean;
+    /** Skip auth gateway — app-server listens directly on the public port (localhost only). */
+    noAuth?: boolean;
+}
+interface RestartBridgeOptions extends BridgeStartOptions {
+    /** Max seconds to wait for active turn to complete before killing. Default: 30 */
+    drainTimeoutSeconds?: number;
+}
+/**
+ * Graceful bridge restart: wait for active turn → cleanup → stop → start.
+ * Prevents message loss during restart by draining active work first
+ * and replaying unprocessed messages on the new instance.
+ *
+ * For headless instances: drain phase cleans up headless dispatch files
+ * to prevent the new bridge from re-injecting completed review requests.
+ * (별 finding: eager marking + replay collision)
+ */
+declare function restartBridge(options: RestartBridgeOptions): Promise<BridgeState>;
 declare function rotateLog(logPath: string): void;
 /**
  * Update the heartbeat timestamp for a running bridge.
@@ -355,6 +404,19 @@ declare function startAgents(options?: AgentControlOptions): Promise<AgentContro
  * Always operates on the cwd-based repo (same as CLI commands).
  */
 declare function stopAgents(): Promise<AgentControlResult>;
+interface HealthReport {
+    ok: boolean;
+    timestamp: string;
+    bridges: DashboardSnapshot["bridges"];
+    agents: DashboardSnapshot["agents"];
+    warnings: DashboardSnapshot["warnings"];
+    headless: Record<string, unknown>[];
+}
+/**
+ * Health check that combines dashboard snapshot with headless state.
+ * Consumed by monitoring tools (Uptime Kuma, cron, autopilot).
+ */
+declare function getHealthReport(options?: StateApiOptions): HealthReport;
 /**
  * Resolve tap configuration for API consumers.
  * Returns paths and settings without requiring CLI args.
@@ -431,4 +493,4 @@ declare function resolveNodeRuntime(configCommand: string, repoRoot: string): Re
  */
 declare function buildRuntimeEnv(repoRoot: string, baseEnv?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 
-export { type AdapterContext, type AgentControlOptions, type AgentControlResult, type AgentInfo, type AppServerAuthState, type AppServerState, type ApplyResult, type ArtifactKind, type BridgeInfo, type BridgeMode, type BridgeState, type CommandCode, type CommandName, type CommandResult, type ConfigOverrides, type ConfigResolution, type ConfigSource, type DashboardSnapshot, type DashboardWarning, type EventStreamOptions, type HttpServerOptions, type InstanceId, type InstanceState, LOCAL_CONFIG_FILE, type OwnedArtifact, type PRInfo, type PatchOp, type PatchOpType, type PatchPlan, type Platform, type ProbeResult, type ResolvedRuntime, type RuntimeAdapter, type RuntimeName, type RuntimeSource, type RuntimeState, SHARED_CONFIG_FILE, type StateApiOptions, type TapLocalConfig, type TapResolvedConfig, type TapSharedConfig, type TapState, type TapStateV1, type VerifyCheck, type VerifyResult, buildRuntimeEnv, collectDashboardSnapshot, createInitialState, getConfig, getDashboardSnapshot, getFnmBinDir, getHeartbeatAge, loadLocalConfig, loadSharedConfig, loadState, probeFnmNode, readNodeVersion, resolveConfig, resolveNodeRuntime, rotateLog, saveLocalConfig, saveSharedConfig, saveState, startAgents, startHttpServer, stateExists, stopAgents, streamEvents, updateBridgeHeartbeat, version };
+export { type AdapterContext, type AgentControlOptions, type AgentControlResult, type AgentInfo, type AppServerAuthState, type AppServerState, type ApplyResult, type ArtifactKind, type BridgeInfo, type BridgeMode, type BridgeState, type CommandCode, type CommandName, type CommandResult, type ConfigOverrides, type ConfigResolution, type ConfigSource, type DashboardSnapshot, type DashboardWarning, type EventStreamOptions, type HealthReport, type HttpServerOptions, type InstanceId, type InstanceState, LOCAL_CONFIG_FILE, type OwnedArtifact, type PRInfo, type PatchOp, type PatchOpType, type PatchPlan, type Platform, type ProbeResult, type ResolvedRuntime, type RuntimeAdapter, type RuntimeName, type RuntimeSource, type RuntimeState, SHARED_CONFIG_FILE, type StateApiOptions, type TapLocalConfig, type TapResolvedConfig, type TapSharedConfig, type TapState, type TapStateV1, type VerifyCheck, type VerifyResult, buildRuntimeEnv, collectDashboardSnapshot, createInitialState, getConfig, getDashboardSnapshot, getFnmBinDir, getHealthReport, getHeartbeatAge, loadLocalConfig, loadSharedConfig, loadState, probeFnmNode, readNodeVersion, resolveConfig, resolveNodeRuntime, restartBridge, rotateLog, saveLocalConfig, saveSharedConfig, saveState, startAgents, startHttpServer, stateExists, stopAgents, streamEvents, updateBridgeHeartbeat, version };

package/dist/index.mjs

@@ -199,7 +199,8 @@ function resolveConfig(overrides = {}, startDir) {
     commsDir: "auto",
     stateDir: "auto",
     runtimeCommand: "auto",
-    appServerUrl: "auto"
+    appServerUrl: "auto",
+    towerName: "auto"
   };
   let commsDir;
   if (overrides.commsDir) {
@@ -268,8 +269,16 @@ function resolveConfig(overrides = {}, startDir) {
   } else {
     appServerUrl = DEFAULT_APP_SERVER_URL;
   }
+  const towerName = local.towerName ?? shared.towerName ?? null;
   return {
-    config: { repoRoot, commsDir, stateDir, runtimeCommand, appServerUrl },
+    config: {
+      repoRoot,
+      commsDir,
+      stateDir,
+      runtimeCommand,
+      appServerUrl,
+      towerName
+    },
     sources
   };
 }
@@ -469,6 +478,10 @@ function canWriteOrCreate(filePath) {
     return false;
   }
 }
+function isEphemeralPath(p) {
+  const normalized = p.replace(/\\/g, "/").toLowerCase();
+  return normalized.includes("/_npx/") || normalized.includes("\\_npx\\") || normalized.includes("/fnm_multishells/") || normalized.includes("\\fnm_multishells\\") || normalized.includes("/tmp/") || normalized.includes("\\temp\\");
+}
 function findLocalTapCommsSource(ctx) {
   const candidates = [
     path5.join(
@@ -528,8 +541,10 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   const warnings = [];
   const issues = [];
   const env = {
-    TAP_AGENT_NAME: "<set-per-session>",
-    TAP_COMMS_DIR: toForwardSlashPath(ctx.commsDir)
+    TAP_AGENT_NAME: ctx.agentName ?? "<set-per-session>",
+    TAP_COMMS_DIR: toForwardSlashPath(ctx.commsDir),
+    TAP_STATE_DIR: toForwardSlashPath(ctx.stateDir),
+    TAP_REPO_ROOT: toForwardSlashPath(ctx.repoRoot)
   };
   if (instanceId) {
     env.TAP_AGENT_ID = instanceId;
@@ -542,11 +557,29 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
   }
   const isBundled = sourcePath.endsWith(".mjs");
   let command = bunCommand;
+  let args = [toForwardSlashPath(sourcePath)];
   if (!command && isBundled) {
-    command = process.execPath;
-    warnings.push(
-      "bun not found; using node to run the compiled MCP server. Install bun for better performance."
-    );
+    const isEphemeralSource = isEphemeralPath(sourcePath);
+    const isEphemeralNode = isEphemeralPath(process.execPath);
+    if (isEphemeralSource) {
+      command = "npx";
+      args = ["@hua-labs/tap", "serve"];
+      warnings.push(
+        "Detected npx cache path. Using `npx @hua-labs/tap serve` as stable MCP launcher."
+      );
+    } else if (isEphemeralNode) {
+      command = "node";
+      warnings.push(
+        "Detected ephemeral node path. Using `node` from PATH for MCP config stability."
+      );
+    } else {
+      command = toForwardSlashPath(process.execPath);
+    }
+    if (!isEphemeralSource) {
+      warnings.push(
+        "bun not found; using node to run the compiled MCP server. Install bun for better performance."
+      );
+    }
   }
   if (!command) {
     issues.push(
@@ -555,8 +588,8 @@ function buildManagedMcpServerSpec(ctx, instanceId) {
     return { command: null, args: [], env, sourcePath, warnings, issues };
   }
   return {
-    command: isBundled && command === process.execPath ? toForwardSlashPath(command) : command,
-    args: [toForwardSlashPath(sourcePath)],
+    command,
+    args,
     env,
     sourcePath,
     warnings,
@@ -1558,6 +1591,40 @@ function isBridgeRunning(stateDir, instanceId) {
   if (!state) return false;
   return isProcessAlive(state.pid);
 }
+function resolveAgentName(instanceId, explicit, context) {
+  if (explicit) return explicit;
+  try {
+    const repoRoot = context?.repoRoot ?? context?.stateDir?.replace(/[\\/].tap-comms$/, "") ?? process.cwd();
+    const state = loadState(repoRoot);
+    const stateAgent = state?.instances[instanceId]?.agentName;
+    if (stateAgent) return stateAgent;
+  } catch {
+  }
+  return process.env.TAP_AGENT_NAME || process.env.CODEX_TAP_AGENT_NAME || null;
+}
+function inferRestartMode(bridgeState, flags, savedMode) {
+  const wasManaged = bridgeState?.appServer != null;
+  const hadAuth = bridgeState?.appServer?.auth != null;
+  const manageAppServer = flags?.noServer === true ? false : flags?.noServer === void 0 ? savedMode?.manageAppServer ?? wasManaged : true;
+  const noAuth = flags?.noAuth === true ? true : flags?.noAuth === void 0 ? savedMode?.noAuth ?? !hadAuth : false;
+  return { manageAppServer, noAuth };
+}
+function cleanupHeadlessDispatch(inboxDir, agentName) {
+  const removed = [];
+  if (!fs7.existsSync(inboxDir)) return removed;
+  const normalizedAgent = agentName.replace(/-/g, "_");
+  const marker = `-headless-${normalizedAgent}-review-`;
+  try {
+    for (const file of fs7.readdirSync(inboxDir)) {
+      if (file.includes(marker)) {
+        fs7.unlinkSync(path7.join(inboxDir, file));
+        removed.push(file);
+      }
+    }
+  } catch {
+  }
+  return removed;
+}
 async function startBridge(options) {
   const {
     instanceId,
@@ -1568,7 +1635,10 @@ async function startBridge(options) {
     agentName,
     port
   } = options;
-  const resolvedAgent = agentName || process.env.TAP_AGENT_NAME || process.env.CODEX_TAP_AGENT_NAME;
+  const resolvedAgent = resolveAgentName(instanceId, agentName, {
+    repoRoot: options.repoRoot,
+    stateDir
+  });
   if (!resolvedAgent) {
     throw new Error(
       `No agent name for ${instanceId} bridge. Set TAP_AGENT_NAME env var or pass --agent-name flag.`
@@ -1720,6 +1790,35 @@ async function stopBridge(options) {
   clearBridgeState(stateDir, instanceId);
   return true;
 }
+async function restartBridge(options) {
+  const { instanceId, stateDir, platform } = options;
+  const drainTimeout = (options.drainTimeoutSeconds ?? 30) * 1e3;
+  const repoRoot = options.repoRoot ?? stateDir.replace(/[\\/].tap-comms$/, "");
+  const runtimeStateDir = getBridgeRuntimeStateDir(repoRoot, instanceId);
+  const heartbeatPath = path7.join(runtimeStateDir, "heartbeat.json");
+  if (fs7.existsSync(heartbeatPath)) {
+    const startWait = Date.now();
+    while (Date.now() - startWait < drainTimeout) {
+      try {
+        const hb = JSON.parse(fs7.readFileSync(heartbeatPath, "utf-8"));
+        if (!hb.activeTurnId) break;
+      } catch {
+        break;
+      }
+      await new Promise((r) => setTimeout(r, 1e3));
+    }
+  }
+  if (options.headless?.enabled && options.commsDir) {
+    const agentName = options.agentName ?? instanceId;
+    cleanupHeadlessDispatch(path7.join(options.commsDir, "inbox"), agentName);
+  }
+  await stopBridge({ instanceId, stateDir, platform });
+  const restartOptions = {
+    ...options,
+    processExistingMessages: true
+  };
+  return startBridge(restartOptions);
+}
 function rotateLog(logPath) {
   if (!fs7.existsSync(logPath)) return;
   try {
@@ -1763,6 +1862,7 @@ var init_bridge = __esm({
     "use strict";
     init_common();
     init_runtime();
+    init_state();
     DEFAULT_APP_SERVER_URL2 = "ws://127.0.0.1:4501";
     APP_SERVER_HEALTH_TIMEOUT_MS = 1500;
     APP_SERVER_START_TIMEOUT_MS = 2e4;
@@ -3230,7 +3330,7 @@ async function bridgeStart(identifier, agentName, flags = {}) {
         log(`TUI connect:  ${bridge.appServer.url}`);
       }
     }
-    const updated = { ...instance, bridge };
+    const updated = { ...instance, bridge, manageAppServer, noAuth };
     const newState = updateInstanceState(state, instanceId, updated);
     saveState(repoRoot, newState);
     return {
@@ -3721,6 +3821,121 @@ function bridgeStatusOne(identifier) {
     }
   };
 }
+async function bridgeRestart(identifier, flags) {
+  const repoRoot = findRepoRoot();
+  const state = loadState(repoRoot);
+  if (!state) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: "TAP_NOT_INITIALIZED",
+      message: "Not initialized. Run: npx @hua-labs/tap init",
+      warnings: [],
+      data: {}
+    };
+  }
+  const resolved = resolveInstanceId(identifier, state);
+  if (!resolved.ok) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: resolved.code,
+      message: resolved.message,
+      warnings: [],
+      data: {}
+    };
+  }
+  const instanceId = resolved.instanceId;
+  const inst = state.instances[instanceId];
+  if (!inst) {
+    return {
+      ok: false,
+      command: "bridge",
+      code: "TAP_INSTANCE_NOT_FOUND",
+      message: `Instance not found: ${instanceId}`,
+      warnings: [],
+      data: {}
+    };
+  }
+  const adapter = getAdapter(inst.runtime);
+  const ctx = {
+    ...createAdapterContext(state.commsDir, repoRoot),
+    instanceId
+  };
+  const bridgeScript = adapter.resolveBridgeScript?.(ctx);
+  if (!bridgeScript) {
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_SCRIPT_MISSING",
+      message: `Bridge script not found for ${instanceId}`,
+      warnings: [],
+      data: {}
+    };
+  }
+  const { config: resolvedConfig } = resolveConfig({}, repoRoot);
+  const drainStr = typeof flags["drain-timeout"] === "string" ? flags["drain-timeout"] : "30";
+  const drainTimeout = parseInt(drainStr, 10) || 30;
+  logHeader(`@hua-labs/tap bridge restart ${instanceId}`);
+  log(`Drain timeout: ${drainTimeout}s`);
+  try {
+    const currentBridgeState = loadBridgeState(ctx.stateDir, instanceId);
+    const { manageAppServer, noAuth } = inferRestartMode(
+      currentBridgeState,
+      {
+        noServer: flags["no-server"] === true ? true : void 0,
+        noAuth: flags["no-auth"] === true ? true : void 0
+      },
+      {
+        manageAppServer: inst.manageAppServer,
+        noAuth: inst.noAuth
+      }
+    );
+    const bridge = await restartBridge({
+      instanceId,
+      runtime: inst.runtime,
+      stateDir: ctx.stateDir,
+      commsDir: ctx.commsDir,
+      bridgeScript,
+      platform: ctx.platform,
+      agentName: inst.agentName ?? void 0,
+      runtimeCommand: resolvedConfig.runtimeCommand,
+      appServerUrl: resolvedConfig.appServerUrl,
+      repoRoot,
+      port: inst.port ?? void 0,
+      headless: inst.headless,
+      drainTimeoutSeconds: drainTimeout,
+      manageAppServer,
+      noAuth
+    });
+    logSuccess(`Bridge restarted (PID: ${bridge.pid})`);
+    const updated = { ...inst, bridge, manageAppServer, noAuth };
+    const newState = updateInstanceState(state, instanceId, updated);
+    saveState(repoRoot, newState);
+    return {
+      ok: true,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_START_OK",
+      message: `Bridge for ${instanceId} restarted (PID: ${bridge.pid})`,
+      warnings: [],
+      data: { pid: bridge.pid }
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    logError(msg);
+    return {
+      ok: false,
+      command: "bridge",
+      instanceId,
+      code: "TAP_BRIDGE_START_FAILED",
+      message: msg,
+      warnings: [],
+      data: {}
+    };
+  }
+}
 async function bridgeCommand(args) {
   const { positional, flags } = parseArgs(args);
   const subcommand = positional[0];
@@ -3780,12 +3995,25 @@ async function bridgeCommand(args) {
       }
       return bridgeStatusAll();
     }
+    case "restart": {
+      if (!identifierArg) {
+        return {
+          ok: false,
+          command: "bridge",
+          code: "TAP_INVALID_ARGUMENT",
+          message: "Missing instance. Usage: npx @hua-labs/tap bridge restart <instance>",
+          warnings: [],
+          data: {}
+        };
+      }
+      return bridgeRestart(identifierArg, flags);
+    }
     default:
       return {
         ok: false,
         command: "bridge",
         code: "TAP_INVALID_ARGUMENT",
-        message: `Unknown bridge subcommand: ${subcommand}. Use: start, stop, status`,
+        message: `Unknown bridge subcommand: ${subcommand}. Use: start, stop, restart, status`,
         warnings: [],
         data: {}
       };
@@ -4003,6 +4231,9 @@ init_dashboard();
 init_dashboard();
 init_utils();
 init_config();
+init_state();
+import * as fs13 from "fs";
+import * as path14 from "path";
 function getDashboardSnapshot(options) {
   const repoRoot = options?.repoRoot ?? findRepoRoot();
   return collectDashboardSnapshot(repoRoot, options?.commsDir);
@@ -4049,6 +4280,60 @@ async function stopAgents() {
     commandResult: result
   };
 }
+function getHealthReport(options) {
+  const repoRoot = options?.repoRoot ?? findRepoRoot();
+  const snapshot = collectDashboardSnapshot(repoRoot, options?.commsDir);
+  const headlessStates = [];
+  try {
+    const state = loadState(repoRoot);
+    const activeMatchers = /* @__PURE__ */ new Set();
+    if (state) {
+      for (const [id, inst] of Object.entries(state.instances)) {
+        if (inst?.installed && inst.bridgeMode === "app-server") {
+          activeMatchers.add(id);
+          if (inst.agentName) activeMatchers.add(inst.agentName);
+        }
+      }
+    }
+    const tmpDir = path14.join(repoRoot, ".tmp");
+    if (fs13.existsSync(tmpDir)) {
+      for (const dir of fs13.readdirSync(tmpDir)) {
+        if (!dir.startsWith("codex-app-server-bridge")) continue;
+        const suffix = dir.replace("codex-app-server-bridge-", "");
+        if (activeMatchers.size > 0) {
+          let matched = false;
+          for (const matcher of activeMatchers) {
+            if (suffix === matcher || suffix.startsWith(matcher)) {
+              matched = true;
+              break;
+            }
+          }
+          if (!matched) continue;
+        }
+        const hsPath = path14.join(tmpDir, dir, "headless-state.json");
+        if (!fs13.existsSync(hsPath)) continue;
+        try {
+          const hs = JSON.parse(fs13.readFileSync(hsPath, "utf-8"));
+          headlessStates.push({ instanceDir: dir, ...hs });
+        } catch {
+        }
+      }
+    }
+  } catch {
+  }
+  const hasFailures = snapshot.warnings.some((w) => w.level === "error");
+  const hasBridgeDown = snapshot.bridges.some(
+    (b) => b.status === "stale" || b.status === "stopped"
+  );
+  return {
+    ok: !hasFailures && !hasBridgeDown,
+    timestamp: snapshot.generatedAt,
+    bridges: snapshot.bridges,
+    agents: snapshot.agents,
+    warnings: snapshot.warnings,
+    headless: headlessStates
+  };
+}
 function getConfig(options) {
   const repoRoot = options?.repoRoot ?? findRepoRoot();
   const { config } = resolveConfig({}, repoRoot);
@@ -4104,8 +4389,9 @@ async function handleEvents(req, res, apiOptions) {
   }
   res.end();
 }
-function handleHealth(res) {
-  jsonResponse(res, { ok: true, timestamp: (/* @__PURE__ */ new Date()).toISOString() });
+function handleHealth(res, apiOptions) {
+  const report = getHealthReport(apiOptions);
+  jsonResponse(res, report);
 }
 async function startHttpServer(options) {
   const port = options?.port ?? 4580;
@@ -4136,7 +4422,7 @@ async function startHttpServer(options) {
               handleConfig(res, apiOptions);
               return;
             case "/health":
-              handleHealth(res);
+              handleHealth(res, apiOptions);
               return;
           }
         }
@@ -4192,6 +4478,7 @@ export {
   getConfig,
   getDashboardSnapshot,
   getFnmBinDir,
+  getHealthReport,
   getHeartbeatAge,
   loadLocalConfig,
   loadSharedConfig,
@@ -4200,6 +4487,7 @@ export {
   readNodeVersion,
   resolveConfig,
   resolveNodeRuntime,
+  restartBridge,
   rotateLog,
   saveLocalConfig,
   saveSharedConfig,