codex-agent-view 0.2.0

package/scripts/capture-hook.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+
+import {
+  appendFileSync,
+  chmodSync,
+  closeSync,
+  constants,
+  mkdirSync,
+  openSync,
+  realpathSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAX_STDIN_BYTES = 2 * 1024 * 1024;
+const SAFE_METADATA_FIELDS = new Set([
+  "agent_id",
+  "agent_type",
+  "hook_event_name",
+  "model",
+  "permission_mode",
+  "reason",
+  "session_id",
+  "source",
+  "stop_hook_active",
+  "tool_name",
+  "tool_use_id",
+  "trigger",
+  "turn_id",
+]);
+
+function summarizePrivateValue(value) {
+  if (value === null) {
+    return { redacted: true, type: "null" };
+  }
+
+  if (Array.isArray(value)) {
+    return { redacted: true, type: "array", length: value.length };
+  }
+
+  if (typeof value === "object") {
+    return {
+      redacted: true,
+      type: "object",
+      keys: Object.keys(value).sort(),
+    };
+  }
+
+  return {
+    redacted: true,
+    type: typeof value,
+    length: typeof value === "string" ? value.length : undefined,
+  };
+}
+
+export function minimizePayload(payload, captureFull = false) {
+  if (captureFull) {
+    return payload;
+  }
+
+  return Object.fromEntries(
+    Object.entries(payload).map(([key, value]) => [
+      key,
+      SAFE_METADATA_FIELDS.has(key) ? value : summarizePrivateValue(value),
+    ]),
+  );
+}
+
+export function capturePath(env = process.env, cwd = process.cwd()) {
+  const base = env.CODEX_AGENT_VIEW_CAPTURE_DIR
+    ? resolve(env.CODEX_AGENT_VIEW_CAPTURE_DIR)
+    : env.PLUGIN_DATA
+      ? resolve(env.PLUGIN_DATA, "captures")
+      : resolve(cwd, ".codex-agent-view", "captures");
+
+  return { directory: base, file: resolve(base, "events.jsonl") };
+}
+
+async function readStdin() {
+  const chunks = [];
+  let bytes = 0;
+
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > MAX_STDIN_BYTES) {
+      throw new Error(`hook payload exceeds ${MAX_STDIN_BYTES} bytes`);
+    }
+    chunks.push(chunk);
+  }
+
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+async function main() {
+  const raw = await readStdin();
+  const payload = JSON.parse(raw);
+  if (payload === null || Array.isArray(payload) || typeof payload !== "object") {
+    throw new TypeError("hook payload must be a JSON object");
+  }
+
+  const { directory, file } = capturePath();
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const flags =
+    constants.O_APPEND |
+    constants.O_CREAT |
+    constants.O_WRONLY |
+    (constants.O_NOFOLLOW ?? 0);
+  const descriptor = openSync(file, flags, 0o600);
+
+  const record = {
+    schema_version: 1,
+    captured_at_ms: Date.now(),
+    payload: minimizePayload(
+      payload,
+      process.env.CODEX_AGENT_VIEW_CAPTURE_FULL === "1",
+    ),
+  };
+
+  try {
+    chmodSync(file, 0o600);
+    appendFileSync(descriptor, `${JSON.stringify(record)}\n`, {
+      encoding: "utf8",
+    });
+  } finally {
+    closeSync(descriptor);
+  }
+
+  // A neutral JSON object is valid for every captured event and is required by
+  // events such as SubagentStop when a successful hook writes to stdout.
+  process.stdout.write("{}\n");
+}
+
+const isDirectRun =
+  process.argv[1] &&
+  realpathSync(fileURLToPath(import.meta.url)) ===
+    realpathSync(resolve(process.argv[1]));
+
+if (isDirectRun) {
+  main().catch((error) => {
+    process.stderr.write(`codex-agent-view hook capture failed: ${error.message}\n`);
+    process.exitCode = 1;
+  });
+}

package/scripts/send-hook.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+import { minimizePayload } from "./capture-hook.mjs";
+import { readRuntimeInfo } from "../src/runtime/config.mjs";
+
+const MAX_STDIN_BYTES = 2 * 1024 * 1024;
+const SEND_TIMEOUT_MS = 750;
+
+async function readStdin() {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > MAX_STDIN_BYTES) {
+      throw new Error(`hook payload exceeds ${MAX_STDIN_BYTES} bytes`);
+    }
+    chunks.push(chunk);
+  }
+  const payload = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+  if (payload === null || Array.isArray(payload) || typeof payload !== "object") {
+    throw new TypeError("hook payload must be a JSON object");
+  }
+  return payload;
+}
+
+function debug(code) {
+  if (process.env.CODEX_AGENT_VIEW_DEBUG === "1") {
+    process.stderr.write(`codex-agent-view hook sender: ${code}\n`);
+  }
+}
+
+async function send(payload) {
+  const runtime = await readRuntimeInfo();
+  const response = await fetch(
+    `http://${runtime.host}:${runtime.port}/api/events`,
+    {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${runtime.token}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify(minimizePayload(payload)),
+      signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+    },
+  );
+  if (!response.ok) {
+    throw new Error(`monitor returned HTTP ${response.status}`);
+  }
+}
+
+async function main() {
+  try {
+    await send(await readStdin());
+  } catch {
+    // Monitoring is fail-open: an unavailable companion must not block Codex.
+    debug("delivery_failed");
+  }
+  process.stdout.write("{}\n");
+}
+
+main().catch(() => {
+  debug("unexpected_failure");
+  process.stdout.write("{}\n");
+});

package/skills/codex-agent-view/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: codex-agent-view
+description: Inspect and diagnose the local Codex Agent View companion monitor for the current parent task and its subagents. Use when the user asks to see task or subagent status, check whether the read-only monitor is healthy or stale, diagnose why local lifecycle events are unavailable, or explicitly start, install, or remove Codex Agent View.
+---
+
+# Codex Agent View
+
+Use the packaged CLI as the authority for monitor health and observed hook state.
+
+1. Run `codex-agent-view status --json` first.
+2. If it succeeds, summarize the monitor update time, observed parent task/session, subagent states, permission wait state, and relevant diagnostics. Preserve `unknown`, missing, duplicate, and out-of-order states instead of guessing that work started or completed.
+3. If status fails because the monitor or runtime file is unavailable, run `codex-agent-view doctor --json`. Report the Codex CLI, plugin, monitor, and runtime-directory findings before suggesting a change.
+4. Start the monitor only when the user explicitly asks to start it. Run `codex-agent-view start --no-open`, keep the returned local URL private, and then retry `codex-agent-view status --json` when the monitor is reachable.
+
+Treat an empty session list as “no hook events observed by this monitor,” not proof that no Codex task or subagent exists. Explain that restarting the in-memory monitor clears previously observed state.
+
+Run `codex-agent-view install` or `codex-agent-view uninstall` only when the user explicitly requests that lifecycle action. Explain that install changes local Codex plugin registration and requires hook review/trust. Before uninstalling, distinguish the default command, which preserves runtime data, from `codex-agent-view uninstall --purge`, which removes the configured runtime directory.
+
+Keep the workflow read-only with respect to Codex tasks. Never stop or restart a task or subagent, send a message to an agent, approve or deny a permission request, or change Codex approval, sandbox, hook-trust, or telemetry settings. Never enable full debug capture or upload a capture without a separate explicit request and a sensitive-data warning.
+
+Do not expose the monitor bearer token, runtime file contents, prompts, transcripts, tool inputs, or tool outputs. Report only the minimum state needed to answer the user's question.

package/src/core/index.mjs

@@ -0,0 +1,3 @@
+export { normalizeHookPayload } from "./normalize-hook-payload.mjs";
+export { createMonitorStore } from "./monitor-store.mjs";
+

package/src/core/monitor-store.mjs

@@ -0,0 +1,332 @@
+import { normalizeHookPayload } from "./normalize-hook-payload.mjs";
+
+const DEFAULT_LIMITS = Object.freeze({
+  maxActivitiesPerSession: 100,
+  maxAgentsPerSession: 100,
+  maxDiagnostics: 100,
+  maxSessions: 50,
+});
+
+function positiveInteger(value, name) {
+  if (!Number.isSafeInteger(value) || value <= 0) {
+    throw new TypeError(`${name} must be a positive safe integer`);
+  }
+  return value;
+}
+
+function createSession(event) {
+  return {
+    session_id: event.session_id,
+    first_seen_at_ms: event.received_at_ms,
+    last_seen_at_ms: event.received_at_ms,
+    agents: new Map(),
+    tools: new Map(),
+    permission: { status: "idle" },
+    recent_activities: [],
+  };
+}
+
+function deriveSessionStatus(session) {
+  if (session.permission.status === "waiting_for_user") {
+    return "waiting_for_user";
+  }
+  if (
+    [...session.agents.values()].some(({ status }) => status === "running") ||
+    [...session.tools.values()].some(({ status }) => status === "running")
+  ) {
+    return "running";
+  }
+  return "observed";
+}
+
+function touchMapEntry(map, key, value) {
+  map.delete(key);
+  map.set(key, value);
+}
+
+function trimMap(map, limit) {
+  while (map.size > limit) {
+    map.delete(map.keys().next().value);
+  }
+}
+
+function addActivity(session, event, status, limit) {
+  const activity = {
+    type: event.type,
+    status,
+    turn_id: event.turn_id,
+    received_at_ms: event.received_at_ms,
+  };
+
+  for (const field of ["agent_id", "agent_type", "tool_name", "tool_use_id"]) {
+    if (field in event) {
+      activity[field] = event[field];
+    }
+  }
+
+  session.recent_activities.unshift(activity);
+  if (session.recent_activities.length > limit) {
+    session.recent_activities.length = limit;
+  }
+}
+
+function applySubagentEvent(session, event, limits) {
+  let agent = session.agents.get(event.agent_id);
+  if (!agent) {
+    agent = {
+      agent_id: event.agent_id,
+      agent_type: event.agent_type,
+      status: "unknown",
+      started_at_ms: null,
+      stopped_at_ms: null,
+      last_seen_at_ms: event.received_at_ms,
+      has_out_of_order_events: false,
+      start_observed: false,
+      stop_observed: false,
+    };
+  }
+
+  if (event.type === "subagent_started") {
+    if (agent.start_observed) {
+      return "duplicate";
+    }
+    agent.start_observed = true;
+    agent.started_at_ms = event.received_at_ms;
+    if (agent.stop_observed) {
+      agent.status = "stopped";
+      agent.has_out_of_order_events = true;
+    } else {
+      agent.status = "running";
+    }
+  } else {
+    if (agent.stop_observed) {
+      return "duplicate";
+    }
+    agent.stop_observed = true;
+    agent.stopped_at_ms = event.received_at_ms;
+    agent.status = agent.start_observed ? "stopped" : "stopped_without_start";
+    agent.has_out_of_order_events = !agent.start_observed;
+  }
+
+  agent.agent_type = event.agent_type;
+  agent.last_seen_at_ms = Math.max(agent.last_seen_at_ms, event.received_at_ms);
+  touchMapEntry(session.agents, event.agent_id, agent);
+  trimMap(session.agents, limits.maxAgentsPerSession);
+  addActivity(session, event, agent.status, limits.maxActivitiesPerSession);
+  return "applied";
+}
+
+function createTool(event) {
+  return {
+    tool_use_id: event.tool_use_id,
+    tool_name: event.tool_name,
+    turn_id: event.turn_id,
+    status: "unknown",
+    started_at_ms: null,
+    completed_at_ms: null,
+    last_seen_at_ms: event.received_at_ms,
+    start_observed: false,
+    completion_observed: false,
+    has_out_of_order_events: false,
+  };
+}
+
+function applyToolEvent(session, event, limits) {
+  const tool = session.tools.get(event.tool_use_id) ?? createTool(event);
+  let activityStatus;
+
+  if (event.type === "tool_started") {
+    if (tool.start_observed) {
+      return "duplicate";
+    }
+    tool.start_observed = true;
+    tool.started_at_ms = event.received_at_ms;
+    if (tool.completion_observed) {
+      tool.status = "completed";
+      tool.has_out_of_order_events = true;
+      activityStatus = "late_start_observed";
+    } else {
+      tool.status = "running";
+      activityStatus = "running";
+    }
+  } else {
+    if (tool.completion_observed) {
+      return "duplicate";
+    }
+    tool.completion_observed = true;
+    tool.completed_at_ms = event.received_at_ms;
+    tool.status = tool.start_observed ? "completed" : "completed_without_start";
+    tool.has_out_of_order_events = !tool.start_observed;
+    activityStatus = tool.status;
+
+    const permission = session.permission;
+    if (
+      permission.status === "waiting_for_user" &&
+      permission.tool_name === event.tool_name &&
+      permission.turn_id === event.turn_id &&
+      event.received_at_ms >= permission.requested_at_ms
+    ) {
+      session.permission = { status: "idle" };
+    }
+  }
+
+  tool.tool_name = event.tool_name;
+  tool.turn_id = event.turn_id;
+  tool.last_seen_at_ms = Math.max(tool.last_seen_at_ms, event.received_at_ms);
+  touchMapEntry(session.tools, event.tool_use_id, tool);
+  trimMap(session.tools, limits.maxActivitiesPerSession);
+  addActivity(session, event, activityStatus, limits.maxActivitiesPerSession);
+  return "applied";
+}
+
+function applyPermissionEvent(session, event, limits) {
+  const permission = session.permission;
+  if (
+    permission.status === "waiting_for_user" &&
+    permission.tool_name === event.tool_name &&
+    permission.turn_id === event.turn_id
+  ) {
+    return "duplicate";
+  }
+
+  if (
+    permission.status === "waiting_for_user" &&
+    event.received_at_ms < permission.requested_at_ms
+  ) {
+    return "stale";
+  }
+
+  session.permission = {
+    status: "waiting_for_user",
+    tool_name: event.tool_name,
+    turn_id: event.turn_id,
+    requested_at_ms: event.received_at_ms,
+  };
+  addActivity(
+    session,
+    event,
+    "waiting_for_user",
+    limits.maxActivitiesPerSession,
+  );
+  return "applied";
+}
+
+function applyEvent(session, event, limits) {
+  if (event.type === "subagent_started" || event.type === "subagent_stopped") {
+    return applySubagentEvent(session, event, limits);
+  }
+  if (event.type === "tool_started" || event.type === "tool_completed") {
+    return applyToolEvent(session, event, limits);
+  }
+  return applyPermissionEvent(session, event, limits);
+}
+
+function snapshotSession(session) {
+  return {
+    session_id: session.session_id,
+    status: deriveSessionStatus(session),
+    first_seen_at_ms: session.first_seen_at_ms,
+    last_seen_at_ms: session.last_seen_at_ms,
+    agents: [...session.agents.values()]
+      .map(({ start_observed, stop_observed, ...agent }) => ({ ...agent }))
+      .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
+    recent_activities: session.recent_activities.map((activity) => ({
+      ...activity,
+    })),
+    permission: { ...session.permission },
+  };
+}
+
+/** Create a bounded, process-local monitor store whose only input is hook data. */
+export function createMonitorStore(options = {}) {
+  const limits = {
+    maxActivitiesPerSession: positiveInteger(
+      options.maxActivitiesPerSession ?? DEFAULT_LIMITS.maxActivitiesPerSession,
+      "maxActivitiesPerSession",
+    ),
+    maxAgentsPerSession: positiveInteger(
+      options.maxAgentsPerSession ?? DEFAULT_LIMITS.maxAgentsPerSession,
+      "maxAgentsPerSession",
+    ),
+    maxDiagnostics: positiveInteger(
+      options.maxDiagnostics ?? DEFAULT_LIMITS.maxDiagnostics,
+      "maxDiagnostics",
+    ),
+    maxSessions: positiveInteger(
+      options.maxSessions ?? DEFAULT_LIMITS.maxSessions,
+      "maxSessions",
+    ),
+  };
+  const now = options.now ?? Date.now;
+  if (typeof now !== "function") {
+    throw new TypeError("now must be a function");
+  }
+
+  const sessions = new Map();
+  const diagnostics = [];
+  let updatedAtMs = 0;
+
+  function addDiagnostic(diagnostic) {
+    diagnostics.unshift({ ...diagnostic });
+    if (diagnostics.length > limits.maxDiagnostics) {
+      diagnostics.length = limits.maxDiagnostics;
+    }
+    updatedAtMs = Math.max(updatedAtMs, diagnostic.diagnosed_at_ms);
+  }
+
+  function ingest(payload, ingestOptions = {}) {
+    const receivedAtMs = ingestOptions.receivedAtMs ?? now();
+    const normalized = normalizeHookPayload(payload, { receivedAtMs });
+    if (normalized.status === "ignored") {
+      addDiagnostic(normalized.diagnostic);
+      return normalized;
+    }
+
+    const { event } = normalized;
+    let session = sessions.get(event.session_id);
+    if (!session) {
+      session = createSession(event);
+    }
+
+    const status = applyEvent(session, event, limits);
+    if (status === "duplicate") {
+      return { status, event };
+    }
+    if (status === "stale") {
+      const diagnostic = {
+        code: "stale_event_ignored",
+        diagnosed_at_ms: event.received_at_ms,
+        field: "received_at_ms",
+      };
+      addDiagnostic(diagnostic);
+      return { status, event, diagnostic };
+    }
+
+    session.first_seen_at_ms = Math.min(
+      session.first_seen_at_ms,
+      event.received_at_ms,
+    );
+    session.last_seen_at_ms = Math.max(
+      session.last_seen_at_ms,
+      event.received_at_ms,
+    );
+    touchMapEntry(sessions, session.session_id, session);
+    trimMap(sessions, limits.maxSessions);
+    updatedAtMs = Math.max(updatedAtMs, event.received_at_ms);
+    return { status: "applied", event };
+  }
+
+  function getSnapshot() {
+    return {
+      schema_version: 1,
+      source_of_truth: "hook",
+      updated_at_ms: updatedAtMs,
+      sessions: [...sessions.values()]
+        .map(snapshotSession)
+        .sort((left, right) => right.last_seen_at_ms - left.last_seen_at_ms),
+      diagnostics: diagnostics.map((diagnostic) => ({ ...diagnostic })),
+    };
+  }
+
+  return Object.freeze({ ingest, getSnapshot });
+}

package/src/core/normalize-hook-payload.mjs

@@ -0,0 +1,146 @@
+const NORMALIZED_EVENT_TYPES = Object.freeze({
+  PermissionRequest: "permission_requested",
+  PostToolUse: "tool_completed",
+  PreToolUse: "tool_started",
+  SubagentStart: "subagent_started",
+  SubagentStop: "subagent_stopped",
+});
+
+const MAX_IDENTIFIER_LENGTH = 512;
+const MAX_LABEL_LENGTH = 256;
+
+function isObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isBoundedString(value, maxLength = MAX_IDENTIFIER_LENGTH) {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= maxLength
+  );
+}
+
+function ignored(code, diagnosedAtMs, field) {
+  return {
+    status: "ignored",
+    diagnostic: {
+      code,
+      diagnosed_at_ms: diagnosedAtMs,
+      ...(field ? { field } : {}),
+    },
+  };
+}
+
+function requiredString(payload, field, diagnosedAtMs, maxLength) {
+  if (!(field in payload)) {
+    return ignored("missing_required_field", diagnosedAtMs, field);
+  }
+
+  if (!isBoundedString(payload[field], maxLength)) {
+    return ignored("invalid_field", diagnosedAtMs, field);
+  }
+
+  return null;
+}
+
+function resolveReceivedAtMs(options) {
+  const receivedAtMs = options?.receivedAtMs ?? Date.now();
+  if (!Number.isSafeInteger(receivedAtMs) || receivedAtMs < 0) {
+    throw new TypeError("receivedAtMs must be a non-negative safe integer");
+  }
+  return receivedAtMs;
+}
+
+function commonEvent(payload, type, receivedAtMs) {
+  return {
+    schema_version: 1,
+    source: "hook",
+    type,
+    session_id: payload.session_id,
+    turn_id: payload.turn_id,
+    received_at_ms: receivedAtMs,
+  };
+}
+
+/**
+ * Validate an untrusted Codex hook payload and retain only monitor-safe fields.
+ * Raw prompts, tool input/output, paths, and assistant messages are never copied.
+ */
+export function normalizeHookPayload(payload, options = {}) {
+  const receivedAtMs = resolveReceivedAtMs(options);
+  if (!isObject(payload)) {
+    return ignored("malformed_payload", receivedAtMs);
+  }
+
+  const eventNameError = requiredString(
+    payload,
+    "hook_event_name",
+    receivedAtMs,
+    MAX_LABEL_LENGTH,
+  );
+  if (eventNameError) {
+    return eventNameError;
+  }
+
+  const type = NORMALIZED_EVENT_TYPES[payload.hook_event_name];
+  if (!type) {
+    return ignored("unsupported_hook_event", receivedAtMs, "hook_event_name");
+  }
+
+  for (const field of ["session_id", "turn_id"]) {
+    const error = requiredString(payload, field, receivedAtMs);
+    if (error) {
+      return error;
+    }
+  }
+
+  const event = commonEvent(payload, type, receivedAtMs);
+
+  if (type === "subagent_started" || type === "subagent_stopped") {
+    for (const [field, maxLength] of [
+      ["agent_id", MAX_IDENTIFIER_LENGTH],
+      ["agent_type", MAX_LABEL_LENGTH],
+    ]) {
+      const error = requiredString(payload, field, receivedAtMs, maxLength);
+      if (error) {
+        return error;
+      }
+    }
+
+    event.agent_id = payload.agent_id;
+    event.agent_type = payload.agent_type;
+  }
+
+  if (type === "tool_started" || type === "tool_completed") {
+    for (const [field, maxLength] of [
+      ["tool_name", MAX_LABEL_LENGTH],
+      ["tool_use_id", MAX_IDENTIFIER_LENGTH],
+    ]) {
+      const error = requiredString(payload, field, receivedAtMs, maxLength);
+      if (error) {
+        return error;
+      }
+    }
+
+    event.tool_name = payload.tool_name;
+    event.tool_use_id = payload.tool_use_id;
+  }
+
+  if (type === "permission_requested") {
+    const error = requiredString(
+      payload,
+      "tool_name",
+      receivedAtMs,
+      MAX_LABEL_LENGTH,
+    );
+    if (error) {
+      return error;
+    }
+
+    event.tool_name = payload.tool_name;
+  }
+
+  return { status: "accepted", event };
+}
+