codex-agent-view 0.2.0 → 0.3.0

package/bin/codex-agent-view.mjs

@@ -52,7 +52,7 @@ function printHelp() {
   process.stdout.write(`Codex Agent View
 
 Usage:
-  codex-agent-view start [--port <port>] [--no-open]
+  codex-agent-view start [--port <port>] [--open]
   codex-agent-view status [--json]
   codex-agent-view doctor [--json]
   codex-agent-view install
@@ -60,12 +60,53 @@ Usage:
   codex-agent-view --version
 
 The monitor is read-only and binds only to 127.0.0.1.
+Start prints the local URL without opening an external browser unless --open is set.
 `);
 }
 
-function optionValue(args, name) {
-  const index = args.indexOf(name);
-  return index === -1 ? undefined : args[index + 1];
+function parseStartArgs(args) {
+  let open = false;
+  let legacyNoOpen = false;
+  let port = DEFAULT_PORT;
+  let portSeen = false;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === "--open") {
+      open = true;
+      continue;
+    }
+    if (argument === "--no-open") {
+      legacyNoOpen = true;
+      continue;
+    }
+    if (argument === "--port") {
+      if (portSeen) {
+        throw new Error("--port may only be specified once");
+      }
+      const value = args[index + 1];
+      if (value === undefined || value.startsWith("--")) {
+        throw new Error("--port requires a value");
+      }
+      port = Number(value);
+      portSeen = true;
+      index += 1;
+      continue;
+    }
+    if (argument.startsWith("-")) {
+      throw new Error(`unknown start option: ${argument}`);
+    }
+    throw new Error(`unexpected start argument: ${argument}`);
+  }
+
+  if (open && legacyNoOpen) {
+    throw new Error("--open and --no-open cannot be used together");
+  }
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new Error("--port must be an integer from 0 to 65535");
+  }
+
+  return { open, port };
 }
 
 function run(command, args, { allowFailure = false } = {}) {
@@ -114,11 +155,7 @@ function openBrowser(url) {
 }
 
 async function start(args) {
-  const requestedPort = optionValue(args, "--port");
-  const port = requestedPort === undefined ? DEFAULT_PORT : Number(requestedPort);
-  if (!Number.isInteger(port) || port < 0 || port > 65535) {
-    throw new Error("--port must be an integer from 0 to 65535");
-  }
+  const options = parseStartArgs(args);
 
   const runtime = await inspectRuntime();
   if (runtime.kind === "unknown") {
@@ -130,10 +167,10 @@ async function start(args) {
     throw new Error("a Codex Agent View monitor is already running; stop it before starting another");
   }
 
-  const monitor = await startMonitorServer({ port });
+  const monitor = await startMonitorServer({ port: options.port });
   process.stdout.write(`Codex Agent View is running at ${monitor.url}\n`);
   process.stdout.write("Press Ctrl+C to stop the in-memory monitor.\n");
-  if (!args.includes("--no-open")) {
+  if (options.open) {
     openBrowser(monitor.url);
   }
 
@@ -172,32 +209,172 @@ async function status(args) {
     0,
   );
   process.stdout.write(`${sessions.length} task(s), ${agents} subagent(s) observed.\n`);
+  if (!Number.isFinite(snapshot.updated_at_ms) || snapshot.updated_at_ms <= 0) {
+    process.stdout.write(
+      "No hook event has reached this monitor yet. The monitor can be healthy while Codex skips an untrusted or not-yet-loaded hook. Run `codex-agent-view doctor`, review `/hooks` in Codex CLI, then use a new task.\n",
+    );
+  }
   for (const session of sessions) {
     process.stdout.write(`- ${session.session_id}: ${session.status} (${session.agents.length} agents)\n`);
   }
 }
 
+function parsePluginList(result) {
+  if (result.code !== 0) return null;
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return Array.isArray(parsed.installed) ? parsed.installed : [];
+  } catch {
+    return null;
+  }
+}
+
+async function inspectInstalledHookBundle(pluginEntry) {
+  const sourcePath = pluginEntry?.source?.path;
+  if (typeof sourcePath !== "string" || sourcePath.length === 0) {
+    return {
+      hooks_file: false,
+      sender_file: false,
+      source_path: null,
+      wiring_ok: false,
+    };
+  }
+  const hooksPath = join(sourcePath, "hooks", "hooks.json");
+  const senderPath = join(sourcePath, "scripts", "send-hook.mjs");
+  const hooks = await readJsonRegularFile(hooksPath);
+  const sender = await pathExists(senderPath);
+  const hookGroups = hooks?.hooks;
+  const expectedEvents = [
+    "SessionStart",
+    "SessionEnd",
+    "UserPromptSubmit",
+    "Stop",
+    "SubagentStart",
+    "SubagentStop",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+  ];
+  const hooksFile = hookGroups && typeof hookGroups === "object";
+  const declaredEvents = hooksFile
+    ? expectedEvents.filter((event) => Array.isArray(hookGroups[event]))
+    : [];
+  return {
+    declared_events: declaredEvents,
+    hooks_file: Boolean(hooksFile),
+    sender_file: Boolean(sender?.isFile() && !sender.isSymbolicLink()),
+    source_path: sourcePath,
+    wiring_ok:
+      Boolean(hooksFile) &&
+      declaredEvents.length === expectedEvents.length &&
+      Boolean(sender?.isFile() && !sender.isSymbolicLink()),
+  };
+}
+
 async function doctor(args) {
   const codex = await run("codex", ["--version"], { allowFailure: true });
   let monitor = { ok: false, message: "not running" };
   try {
     const snapshot = await fetchState();
-    monitor = { ok: true, sessions: snapshot.sessions?.length || 0 };
+    monitor = {
+      events_received:
+        Number.isFinite(snapshot.updated_at_ms) && snapshot.updated_at_ms > 0,
+      ok: true,
+      sessions: snapshot.sessions?.length || 0,
+      updated_at_ms:
+        Number.isFinite(snapshot.updated_at_ms) && snapshot.updated_at_ms > 0
+          ? snapshot.updated_at_ms
+          : null,
+    };
   } catch (error) {
     monitor = { ok: false, message: error.message };
   }
   const plugins = await run("codex", ["plugin", "list", "--json"], {
     allowFailure: true,
   });
-  let installed = false;
-  try {
-    const parsed = JSON.parse(plugins.stdout);
-    installed = parsed.installed?.some((entry) => entry.pluginId === PLUGIN_ID) || false;
-  } catch {}
+  const pluginList = parsePluginList(plugins);
+  const pluginEntry = pluginList?.find((entry) => entry.pluginId === PLUGIN_ID) || null;
+  const hookBundle = await inspectInstalledHookBundle(pluginEntry);
+  const diagnostics = [];
+  if (codex.code !== 0) {
+    diagnostics.push({
+      action: "Install or repair Codex CLI so `codex --version` succeeds.",
+      code: "codex_cli_unavailable",
+      severity: "error",
+    });
+  }
+  if (pluginList === null) {
+    diagnostics.push({
+      action: "Check `codex plugin list --json` and the installed Codex CLI version.",
+      code: "plugin_list_unavailable",
+      severity: "error",
+    });
+  } else if (!pluginEntry) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install`.",
+      code: "plugin_not_installed",
+      severity: "error",
+    });
+  } else if (pluginEntry.enabled !== true) {
+    diagnostics.push({
+      action: "Enable Codex Agent View in the Codex plugin browser, then start a new task.",
+      code: "plugin_disabled",
+      severity: "error",
+    });
+  }
+  if (pluginEntry && !hookBundle.wiring_ok) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install` again to restore the owned plugin bundle.",
+      code: "hook_bundle_invalid",
+      severity: "error",
+    });
+  }
+  if (pluginEntry && pluginEntry.version !== (await packageVersion())) {
+    diagnostics.push({
+      action: "Run `codex-agent-view install` to align the installed plugin with this CLI package.",
+      code: "plugin_version_mismatch",
+      severity: "warning",
+    });
+  }
+  if (!monitor.ok) {
+    diagnostics.push({
+      action: "Run `codex-agent-view start` before expecting live task events.",
+      code: "monitor_not_running",
+      severity: "warning",
+    });
+  }
+  if (pluginEntry) {
+    diagnostics.push({
+      action: "Review the current plugin hook definition in interactive Codex CLI `/hooks`.",
+      code: "hook_trust_unverified",
+      severity: "info",
+    });
+  }
+  if (monitor.ok && monitor.events_received === false) {
+    diagnostics.push({
+      action:
+        "Open Codex CLI, review and trust the current definition in `/hooks`, then start a new task. Restart a Codex app process that was already open during installation.",
+      code: "no_hook_events_observed",
+      severity: "warning",
+    });
+  }
   const report = {
     codex: { ok: codex.code === 0, version: codex.stdout.trim() || null },
+    diagnostics,
+    hook: {
+      ...hookBundle,
+      trust: pluginEntry ? "unknown" : "not_applicable",
+      trust_note: pluginEntry
+        ? "Codex CLI does not expose persisted hook trust through `plugin list --json`; review `/hooks` interactively."
+        : null,
+    },
     monitor,
-    plugin: { installed },
+    plugin: {
+      enabled: pluginEntry?.enabled === true,
+      installed: Boolean(pluginEntry),
+      source_path: pluginEntry?.source?.path || null,
+      version: pluginEntry?.version || null,
+    },
     runtime_directory: runtimeDirectory(),
   };
   if (args.includes("--json")) {
@@ -205,8 +382,20 @@ async function doctor(args) {
     return;
   }
   process.stdout.write(`Codex CLI: ${report.codex.ok ? report.codex.version : "not available"}\n`);
-  process.stdout.write(`Plugin: ${installed ? "installed" : "not installed"}\n`);
+  process.stdout.write(
+    `Plugin: ${report.plugin.installed ? `installed (${report.plugin.enabled ? "enabled" : "disabled"})` : "not installed"}\n`,
+  );
+  if (report.plugin.installed) {
+    process.stdout.write(`Hook bundle: ${report.hook.wiring_ok ? "valid" : "invalid"}\n`);
+    process.stdout.write("Hook trust: unknown (Codex exposes review through interactive `/hooks`)\n");
+  }
   process.stdout.write(`Monitor: ${monitor.ok ? "running" : monitor.message}\n`);
+  if (monitor.ok) {
+    process.stdout.write(`Hook events: ${monitor.events_received ? "observed" : "none observed"}\n`);
+  }
+  for (const diagnostic of diagnostics) {
+    process.stdout.write(`[${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.action}\n`);
+  }
 }
 
 async function pathExists(path) {
@@ -362,8 +551,30 @@ async function install() {
     await run("codex", ["plugin", "marketplace", "add", destination, "--json"]);
   }
   await run("codex", ["plugin", "add", PLUGIN_ID, "--json"]);
+  const verification = await run("codex", ["plugin", "list", "--json"], {
+    allowFailure: true,
+  });
+  const installed = parsePluginList(verification)?.find(
+    (entry) => entry.pluginId === PLUGIN_ID,
+  );
+  if (!installed) {
+    throw new Error(
+      "Codex did not report the plugin as installed after registration; run `codex-agent-view doctor` for details",
+    );
+  }
+  if (installed.enabled !== true) {
+    throw new Error(
+      "the plugin was registered but is disabled; enable it in the Codex plugin browser, then run `codex-agent-view doctor`",
+    );
+  }
   process.stdout.write(`Installed ${PLUGIN_ID} from ${destination}.\n`);
-  process.stdout.write("Review and trust the hook in the CLI /hooks screen, restart Codex, then start a new task.\n");
+  process.stdout.write("Registration verified: installed and enabled.\n");
+  process.stdout.write(
+    "Hook trust cannot be granted or inspected non-interactively. Review and trust this plugin's current hook definition in Codex CLI `/hooks`.\n",
+  );
+  process.stdout.write(
+    "If Codex was already open during installation, restart it completely, then create a new task.\n",
+  );
 }
 
 function isBroadRuntimeRoot(root) {

package/hooks/hooks.json

@@ -1,6 +1,50 @@
 {
   "description": "Capture privacy-minimized Codex lifecycle payloads for the local companion monitor.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 3
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/scripts/send-hook.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "SubagentStart": [
       {
         "hooks": [

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-agent-view",
-  "version": "0.2.0",
-  "description": "Local read-only companion monitor for Codex parent tasks and subagents.",
+  "version": "0.3.0",
+  "description": "Read-only Codex app task view with an optional local live monitor.",
   "type": "module",
   "main": "./src/core/index.mjs",
   "exports": "./src/core/index.mjs",

package/public/app.js

@@ -65,6 +65,7 @@ const elements = Object.freeze({
 const viewState = {
   updatedAtMs: null,
   sessions: [],
+  diagnostics: [],
   hasLoaded: false,
   errorMessage: "",
   canRetry: true,
@@ -130,10 +131,22 @@ function normalizeActivity(value) {
   };
 }
 
+function normalizeDiagnostic(value) {
+  const diagnostic = isRecord(value) ? value : {};
+  return {
+    code: safeString(diagnostic.code, "unknown_diagnostic"),
+    diagnosedAtMs: safeTimestamp(diagnostic.diagnosed_at_ms),
+  };
+}
+
 function deriveSessionStatus(session, agents, recentActivities) {
   if (session.permission?.status === "waiting_for_user") {
     return "waiting";
   }
+  const reportedStatus = normalizeCoreStatus(session.status);
+  if (reportedStatus === "running" || reportedStatus === "completed") {
+    return reportedStatus;
+  }
   if (
     agents.some((agent) => agent.status === "running") ||
     recentActivities[0]?.status === "running"
@@ -154,6 +167,7 @@ function normalizeSession(value, index) {
 
   return {
     sessionId: safeString(session.session_id, `unknown-session-${index + 1}`),
+    workspaceLabel: safeString(session.workspace_label, ""),
     status: deriveSessionStatus(session, agents, recentActivities),
     lastActivityAtMs: safeTimestamp(session.last_seen_at_ms),
     agents,
@@ -166,7 +180,8 @@ function normalizeState(value) {
     !isRecord(value) ||
     value.schema_version !== 1 ||
     value.source_of_truth !== "hook" ||
-    !Array.isArray(value.sessions)
+    !Array.isArray(value.sessions) ||
+    !Array.isArray(value.diagnostics)
   ) {
     throw new TypeError("상태 응답 형식이 올바르지 않습니다.");
   }
@@ -174,6 +189,7 @@ function normalizeState(value) {
   return {
     updatedAtMs: safeTimestamp(value.updated_at_ms),
     sessions: value.sessions.map(normalizeSession),
+    diagnostics: value.diagnostics.map(normalizeDiagnostic),
   };
 }
 
@@ -354,11 +370,12 @@ function createSessionCard(session) {
   identity.className = "session-identity";
   const eyebrow = document.createElement("span");
   eyebrow.className = "session-kind";
-  eyebrow.textContent = "PARENT TASK";
-  const title = document.createElement("h3");
+  eyebrow.append("PARENT TASK · ");
   const id = document.createElement("code");
   id.textContent = session.sessionId;
-  title.append(id);
+  eyebrow.append(id);
+  const title = document.createElement("h3");
+  title.textContent = session.workspaceLabel || "프로젝트 정보 없음";
   identity.append(eyebrow, title);
 
   const sessionState = document.createElement("div");
@@ -420,6 +437,7 @@ function sessionMatchesQuery(session, query) {
 
   const searchableValues = [
     session.sessionId,
+    session.workspaceLabel,
     session.status,
     ...session.agents.flatMap((agent) => [agent.agentId, agent.agentType, agent.status]),
     ...session.recentActivities.flatMap((activity) => [
@@ -462,7 +480,7 @@ function renderMetrics() {
   elements.metricWaiting.textContent = String(waitingCount);
   elements.metricCompleted.textContent = String(countStatus("completed"));
   elements.lastUpdated.textContent = !viewState.updatedAtMs
-    ? "시간 정보 없음"
+    ? "수신된 hook 없음"
     : formatDateTime(viewState.updatedAtMs);
 }
 
@@ -486,10 +504,77 @@ function setStateMessage(kind, title, description, includeRetry = false) {
   }
 }
 
+function setEmptyObservationMessage() {
+  elements.stateMessage.className = "state-message state-empty state-empty-observation";
+  elements.stateMessage.replaceChildren();
+
+  const heading = document.createElement("strong");
+  const copy = document.createElement("span");
+
+  if (viewState.diagnostics.length) {
+    heading.textContent = "표시 가능한 task가 없습니다.";
+    copy.textContent = `Monitor가 hook 입력 ${viewState.diagnostics.length}건을 받았지만 유효한 session으로 적용하지 않았습니다.`;
+  } else {
+    heading.textContent = "이 관찰 창에서 수신된 hook event가 0건입니다.";
+    copy.textContent = "로컬 monitor 연결은 정상입니다. 이 결과만으로 Codex에 실행 중인 task나 agent가 없다고 판단할 수 없습니다.";
+  }
+
+  const guidance = document.createElement("div");
+  guidance.className = "empty-guidance";
+
+  const guidanceTitle = document.createElement("h3");
+  guidanceTitle.textContent = "표시되지 않을 때 확인 순서";
+
+  const automaticTracking = document.createElement("p");
+  automaticTracking.className = "automatic-tracking";
+  automaticTracking.textContent = "task ID를 입력하거나 task별로 등록할 필요가 없습니다. Trusted hook event가 자동으로 이 목록에 추가됩니다.";
+
+  const steps = document.createElement("ol");
+  for (const step of [
+    "Codex Agent View를 실행한 뒤 새 Codex task를 시작합니다.",
+    "설치된 plugin의 현재 hook command를 검토하고 직접 trust했는지 확인합니다.",
+    "plugin 설치 또는 hook trust 변경 후 공식 Codex 앱을 완전히 재시작하고 새 task에서 subagent를 실행합니다.",
+  ]) {
+    const item = document.createElement("li");
+    item.textContent = step;
+    steps.append(item);
+  }
+
+  const boundary = document.createElement("p");
+  boundary.className = "observation-boundary";
+  boundary.textContent = "Plugin 설치·trust 전에 이미 지나간 event와 monitor가 꺼져 있던 동안의 event는 재생되지 않습니다.";
+
+  guidance.append(guidanceTitle, automaticTracking, steps, boundary);
+
+  if (viewState.diagnostics.length) {
+    const diagnostics = document.createElement("details");
+    diagnostics.className = "diagnostic-details";
+    const summary = document.createElement("summary");
+    summary.textContent = `검증 diagnostic ${viewState.diagnostics.length}건`;
+    const codes = document.createElement("ul");
+    const diagnosticCounts = new Map();
+    for (const { code } of viewState.diagnostics) {
+      diagnosticCounts.set(code, (diagnosticCounts.get(code) ?? 0) + 1);
+    }
+    for (const [diagnosticCode, count] of diagnosticCounts) {
+      const item = document.createElement("li");
+      const code = document.createElement("code");
+      code.textContent = diagnosticCode;
+      item.append(code, ` · ${count}건`);
+      codes.append(item);
+    }
+    diagnostics.append(summary, codes);
+    guidance.append(diagnostics);
+  }
+
+  elements.stateMessage.append(heading, copy, guidance);
+}
+
 function renderSessions() {
   const visibleSessions = filteredSessions();
   const hasFilters = elements.search.value.trim() || elements.statusFilter.value !== "all";
 
+  elements.toolbar.hidden = viewState.sessions.length === 0;
   elements.stateMessage.hidden = false;
 
   elements.sessionList.replaceChildren();
@@ -523,11 +608,7 @@ function renderSessions() {
 
   if (!viewState.sessions.length) {
     elements.sessionList.hidden = true;
-    setStateMessage(
-      "empty",
-      "아직 관찰된 task가 없습니다.",
-      "Codex에서 task나 subagent가 시작되면 이곳에 나타납니다.",
-    );
+    setEmptyObservationMessage();
     return;
   }
 
@@ -597,6 +678,7 @@ async function refreshState() {
     const nextState = normalizeState(await response.json());
     viewState.updatedAtMs = nextState.updatedAtMs;
     viewState.sessions = nextState.sessions;
+    viewState.diagnostics = nextState.diagnostics;
     viewState.hasLoaded = true;
     viewState.errorMessage = "";
     viewState.canRetry = true;

package/public/index.html

@@ -95,20 +95,25 @@
             </p>
           </div>
 
-          <form class="toolbar" role="search" aria-label="task와 subagent 검색 및 필터">
+          <form
+            class="toolbar"
+            role="search"
+            aria-label="자동 수신된 task와 subagent 목록 필터"
+            hidden
+          >
             <div class="field field-search">
-              <label for="session-search">검색</label>
+              <label for="session-search">목록 필터 (선택)</label>
               <input
                 id="session-search"
                 name="query"
                 type="search"
-                placeholder="Session ID, agent ID, 유형 또는 event"
+                placeholder="자동 수신된 task·agent 목록에서 찾기"
                 autocomplete="off"
                 spellcheck="false"
               >
             </div>
             <div class="field">
-              <label for="status-filter">상태</label>
+              <label for="status-filter">상태 필터 (선택)</label>
               <select id="status-filter" name="status">
                 <option value="all">모든 상태</option>
                 <option value="running">실행 중</option>

package/public/styles.css

@@ -362,6 +362,10 @@ h1 {
   gap: var(--space-3);
 }
 
+.toolbar[hidden] {
+  display: none;
+}
+
 .field {
   display: grid;
   gap: var(--space-2);
@@ -425,6 +429,74 @@ h1 {
   color: var(--text-secondary);
 }
 
+.state-empty-observation {
+  justify-items: stretch;
+  text-align: left;
+}
+
+.state-empty-observation > strong,
+.state-empty-observation > span {
+  justify-self: center;
+  text-align: center;
+}
+
+.empty-guidance {
+  width: min(42rem, 100%);
+  margin-top: var(--space-5);
+  padding: var(--space-4);
+  background: var(--surface-raised);
+  border: 1px solid var(--border-default);
+  border-radius: var(--radius-sm);
+}
+
+.empty-guidance h3 {
+  margin-bottom: var(--space-3);
+  font-size: var(--text-sm);
+}
+
+.automatic-tracking {
+  margin-bottom: var(--space-3);
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.empty-guidance ol {
+  margin: 0;
+  padding-left: 1.25rem;
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.empty-guidance li + li {
+  margin-top: var(--space-2);
+}
+
+.observation-boundary {
+  margin: var(--space-4) 0 0;
+  padding-top: var(--space-3);
+  color: var(--text-muted);
+  border-top: 1px solid var(--border-default);
+  font-size: var(--text-xs);
+}
+
+.diagnostic-details {
+  margin-top: var(--space-3);
+  color: var(--text-secondary);
+  font-size: var(--text-sm);
+}
+
+.diagnostic-details summary {
+  min-height: 2.75rem;
+  padding: var(--space-2) 0;
+  cursor: pointer;
+  font-weight: 700;
+}
+
+.diagnostic-details ul {
+  margin: 0;
+  padding-left: 1.25rem;
+}
+
 .state-message.state-error {
   background: var(--danger-soft);
   border-color: color-mix(in srgb, var(--danger) 40%, transparent);