oh-my-opencode 5.0.0-beta.8 → 5.0.0-beta.81

package/packages/omo-codex/plugin/skills/debugging/references/scripts/dap.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Zero-dependency DAP REPL, modeled on oh-my-pi's debug tool. DAP framing is UTF-8 byte based.
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import { createInterface } from "node:readline";
+import { stdin, stdout, stderr, env } from "node:process";
+
+export const MAX_ROWS = 100;
+export const MAX_OUTPUT_BYTES = 32 * 1024;
+
+export function isTcpAdapterSpec(spec) {
+  const separator = spec.lastIndexOf(":");
+  return separator > 0 &&
+    !spec.includes("/") &&
+    !spec.includes("\\") &&
+    /^\d+$/.test(spec.slice(separator + 1));
+}
+
+export class DapFrameParser {
+  constructor() { this.buffer = Buffer.alloc(0); }
+  push(chunk) {
+    this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+    const messages = [];
+    while (true) {
+      const marker = this.buffer.indexOf(Buffer.from("\r\n\r\n"));
+      if (marker < 0) break;
+      const header = this.buffer.subarray(0, marker).toString("ascii");
+      const match = header.match(/(?:^|\r\n)Content-Length:\s*(\d+)/i);
+      if (!match) { this.buffer = this.buffer.subarray(marker + 4); continue; }
+      const length = Number(match[1]);
+      const start = marker + 4;
+      if (this.buffer.length < start + length) break;
+      const body = this.buffer.subarray(start, start + length);
+      this.buffer = this.buffer.subarray(start + length);
+      try { messages.push(JSON.parse(body.toString("utf8"))); } catch { /* malformed frames are ignored */ }
+    }
+    return messages;
+  }
+}
+
+const timeoutMs = Number(env.DAP_TIMEOUT_MS || 15000);
+let transport = null;
+let parser = null;
+let nextSeq = 1;
+let initialized = false;
+let terminated = false;
+let currentStop = null;
+let topFrame = null;
+const pending = new Map();
+const breakpoints = new Map();
+// Event-driven waits. A tight `await setImmediate` busy-loop starves Bun's socket
+// data callbacks (the `initialized` event then never processes and launch deadlocks),
+// so every wait subscribes to the actual DAP event instead of polling state.
+const eventWaiters = new Map();
+function onEvent(name) {
+  return new Promise(resolve => {
+    const list = eventWaiters.get(name) || [];
+    list.push(resolve);
+    eventWaiters.set(name, list);
+  });
+}
+function emitEvent(name, value) {
+  const list = eventWaiters.get(name) || [];
+  eventWaiters.delete(name);
+  for (const resolve of list) resolve(value);
+}
+function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
+
+const debugTraffic = Boolean(env.DAP_DEBUG);
+function trace(direction, message) { if (debugTraffic) stderr.write(`DAP ${direction} ${JSON.stringify(message).slice(0, 300)}\n`); }
+function line(text) { stdout.write(`${text}\n`); }
+function error(kind, detail = "") { line(`ERR: ${kind}${detail ? ` ${detail}` : ""}`); }
+function send(message) {
+  trace(">", message);
+  const body = Buffer.from(JSON.stringify(message));
+  transport.write(Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`), body]));
+}
+function request(command, args = {}) {
+  if (!transport || terminated) return Promise.reject(new Error("no-session"));
+  const seq = nextSeq++;
+  send({ type: "request", seq, command, arguments: args });
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { pending.delete(seq); reject(new Error("timeout")); }, timeoutMs);
+    pending.set(seq, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: value => { clearTimeout(timer); reject(value); } });
+  });
+}
+function onMessage(message) {
+  trace("<", message);
+  if (message.type === "response") {
+    const wait = pending.get(message.request_seq);
+    if (!wait) return;
+    pending.delete(message.request_seq);
+    if (message.success === false) wait.reject(new Error("adapter-error")); else wait.resolve(message);
+  } else if (message.type === "event") {
+    if (message.event === "initialized") { initialized = true; emitEvent("initialized"); }
+    if (message.event === "stopped") { currentStop = message.body || {}; emitEvent("stopped", currentStop); }
+    if (message.event === "terminated" || message.event === "exited") { terminated = true; emitEvent("terminated"); }
+  }
+}
+function connectTransport(write, read, close = read) {
+  transport = { write: chunk => write.write(chunk), destroy: () => close.destroy?.() };
+  parser = new DapFrameParser();
+  read.on("data", chunk => { for (const message of parser.push(chunk)) onMessage(message); });
+  read.on("error", () => { if (!terminated) error("adapter-failed"); });
+  read.on("close", () => { if (!terminated) error("adapter-failed"); });
+}
+function connectSocket(socket) { connectTransport(socket, socket, socket); }
+async function startAdapter(spec) {
+  if (isTcpAdapterSpec(spec)) {
+    const separator = spec.lastIndexOf(":");
+    const socket = createConnection(Number(spec.slice(separator + 1)), spec.slice(0, separator));
+    connectSocket(socket);
+    await new Promise((resolve, reject) => { socket.once("connect", resolve); socket.once("error", reject); });
+  } else {
+    // A .mjs/.cjs/.ts adapter spec runs under the current Bun/Node runtime (e.g. the
+    // fixture adapter); any other spec is an adapter executable (lldb-dap, debugpy, dlv)
+    // spawned directly with its own argv.
+    const isScript = /\.(mjs|cjs|ts)$/.test(spec);
+    const [cmd, argv] = isScript ? [process.execPath, [spec]] : [spec, []];
+    const child = spawn(cmd, argv, { stdio: ["pipe", "pipe", "inherit"] });
+    connectTransport(child.stdin, child.stdout, child);
+    child.on("error", () => error("adapter-failed"));
+  }
+}
+// Waits for a stopped event. When `required` is false this is a best-effort grace
+// window (e.g. an optional stop-on-entry); it returns on the first stop OR on timeout
+// without failing, so adapters that run straight to a breakpoint are not broken.
+async function waitForStop(required = true, graceMs) {
+  if (currentStop || terminated) return Boolean(currentStop);
+  const budget = graceMs ?? timeoutMs;
+  await Promise.race([onEvent("stopped"), onEvent("terminated"), sleep(budget)]);
+  return Boolean(currentStop);
+}
+// Waits for the adapter's `initialized` event, event-driven (never a busy-loop).
+async function waitInitialized() {
+  if (initialized) return;
+  await Promise.race([onEvent("initialized"), sleep(timeoutMs)]);
+  if (!initialized) throw new Error("timeout");
+}
+// Adapters gate the `initialized` event on a recognized adapterID (debugpy withholds
+// it for unknown IDs, hanging the handshake). Infer a known ID from the adapter spec.
+function adapterIdFor(spec) {
+  const base = String(spec).split("/").pop().toLowerCase();
+  if (base.includes("debugpy") || base.includes("python")) return "debugpy";
+  if (base.includes("lldb")) return "lldb-dap";
+  if (base.includes("dlv") || base.includes("delve")) return "dlv";
+  if (base.includes("js-debug")) return "js-debug";
+  if (base.includes("gdb")) return "gdb";
+  return "omo";
+}
+async function launch(adapter, program, args) {
+  if (transport) return error("adapter-error", "session already exists");
+  try {
+    await startAdapter(adapter);
+    await request("initialize", { clientID: "omo-dap", adapterID: adapterIdFor(adapter), linesStartAt1: true, columnsStartAt1: true, pathFormat: "path" });
+    // Send launch BEFORE awaiting `initialized`: debugpy's adapter defers/flushes the
+    // initialized event until further client activity, so waiting for it first
+    // deadlocks the handshake. DAP allows launch any time after the initialize
+    // response; `initialized` is only required before configurationDone.
+    // stopOnEntry yields an initial stopped event with a real threadId, so the client
+    // can set breakpoints and inspect from a valid stopped state before continuing.
+    // `console: "internalConsole"` is REQUIRED by debugpy (without it the launch never
+    // spawns the debug server -> "Server is not available"); lldb-dap ignores it.
+    // lldb-dap reports the launch response success unreliably (false even when the
+    // process started and stopped); the process/stopped EVENTS are the real signal,
+    // so a non-success launch response is tolerated, not fatal.
+    await request("launch", { program, args, console: "internalConsole", justMyCode: false, stopOnEntry: true }).catch(() => null);
+    await waitInitialized();
+    await request("configurationDone").catch(() => null);
+    // Best-effort: lldb-dap stops at entry, other adapters run to the first breakpoint.
+    await waitForStop(false, 2000);
+    line("READY: launch");
+  } catch (e) { error(e.message === "timeout" ? "timeout" : e.message === "adapter-error" ? "adapter-error" : "adapter-failed"); }
+}
+async function snapshot() {
+  if (terminated) { line("EXIT: terminated"); return; }
+  try {
+    const response = await request("stackTrace", { threadId: currentStop?.threadId || 1, levels: 1 });
+    topFrame = response.body?.stackFrames?.[0];
+    const f = topFrame;
+    if (f) line(`STOP: stopped reason=${currentStop?.reason || "unknown"} threadId=${currentStop?.threadId || ""} ${f.name} at ${f.source?.path || "?"}:${f.line || 0}:${f.column || 0}`);
+    else line(`STOP: stopped reason=${currentStop?.reason || "unknown"} threadId=${currentStop?.threadId || ""} ? at ?:0:0`);
+  } catch (e) { error(e.message === "timeout" ? "timeout" : "adapter-error"); }
+}
+function boundedTable(header, rows) {
+  const all = rows.map(row => row.join("\t"));
+  const chosen = all.slice(0, MAX_ROWS);
+  const prefix = `${header.join("\t")}\n`;
+  let output = prefix;
+  let count = 0;
+  for (const row of chosen) {
+    const candidate = `${row}\n`;
+    if (Buffer.byteLength(output + candidate) > MAX_OUTPUT_BYTES) break;
+    output += candidate; count++;
+  }
+  stdout.write(output);
+  const rowDropped = all.length - count;
+  const byteDropped = Buffer.byteLength(all.slice(count).join("\n") + (all.length > count ? "\n" : ""));
+  if (rowDropped > 0 || byteDropped > 0) line(`TRUNCATED: rows dropped=${rowDropped} bytes dropped=${byteDropped}`);
+}
+async function command(input) {
+  const parts = input.trim().split(/\s+/);
+  const cmd = parts.shift();
+  if (!cmd) return;
+  if (cmd === "quit") { transport?.destroy?.(); process.exit(0); }
+  if (cmd === "launch") return launch(parts.shift(), parts.shift(), parts);
+  if (cmd === "attach") {
+    const [host, port] = (parts.shift() || "").split(":");
+    try {
+      await startAdapter(`${host}:${port}`);
+      await request("initialize", { clientID: "omo-dap", adapterID: "debugpy", linesStartAt1: true, columnsStartAt1: true, pathFormat: "path" });
+      await waitInitialized();
+      await request("attach", { justMyCode: false });
+      await request("configurationDone");
+      line("READY: attach");
+    } catch (e) { error(e.message === "timeout" ? "timeout" : "adapter-failed"); }
+    return;
+  }
+  if (!transport) return error("no-session");
+  try {
+    if (cmd === "break" || cmd === "rmbreak") {
+      const [file, lineNo] = (parts[0] || "").split(":");
+      if (!file || !lineNo) return error("invalid-args");
+      const set = breakpoints.get(file) || [];
+      const next = cmd === "break" ? [...set.filter(x => x.line !== Number(lineNo)), { line: Number(lineNo) }] : set.filter(x => x.line !== Number(lineNo));
+      const response = await request("setBreakpoints", { source: { path: file }, breakpoints: next });
+      breakpoints.set(file, next);
+      if (response.body?.breakpoints?.some(bp => bp.verified === false)) error("unverified-breakpoint"); else line(`BREAK: ${file}:${lineNo}`);
+    } else if (["continue", "step", "next", "stepin", "stepout", "pause"].includes(cmd)) {
+      const dapCmd = { step: "next", stepin: "stepIn", stepout: "stepOut" }[cmd] || cmd;
+      const threadId = currentStop?.threadId || 1;
+      currentStop = null;
+      await request(dapCmd, { threadId });
+      // Wait for the resulting stopped event (breakpoint hit / step completed) before
+      // snapshotting; without this the stack is read while the debuggee is still running.
+      await waitForStop();
+      await snapshot();
+    } else if (cmd === "stack") {
+      const r = await request("stackTrace", { threadId: currentStop?.threadId || 1, levels: Number(parts[0]) || 100 });
+      boundedTable(["FRAME", "NAME", "FILE", "LINE", "COLUMN"], (r.body?.stackFrames || []).map(f => [String(f.id), f.name, f.source?.path || "", String(f.line || ""), String(f.column || "")]));
+    } else if (cmd === "scopes") {
+      const r = await request("scopes", { frameId: topFrame?.id || 42 });
+      boundedTable(["NAME", "VARIABLES_REFERENCE"], (r.body?.scopes || []).map(s => [s.name, String(s.variablesReference)]));
+    } else if (cmd === "vars") {
+      if (!parts[0]) return error("invalid-args");
+      const r = await request("variables", { variablesReference: Number(parts[0]) });
+      boundedTable(["NAME", "VALUE"], (r.body?.variables || []).map(v => [v.name, v.value ?? ""]));
+    } else if (cmd === "eval") {
+      if (!parts.length) return error("invalid-args");
+      const r = await request("evaluate", { expression: parts.join(" "), frameId: topFrame?.id || 42 });
+      line(`EVAL\t${r.body?.result || ""}`);
+    } else if (cmd === "threads") {
+      const r = await request("threads"); boundedTable(["ID", "NAME"], (r.body?.threads || []).map(t => [String(t.id), t.name]));
+    } else if (cmd === "sessions") line("SESSION\tSTATE\n1\tactive");
+    else if (cmd === "terminate") { await request("terminate", { restart: false }); line("EXIT: terminated"); terminated = true; }
+    else error("invalid-args");
+  } catch (e) { error(e.message === "timeout" ? "timeout" : e.message === "adapter-error" ? "adapter-error" : "adapter-failed"); }
+}
+
+if (import.meta.main) {
+  // Serialize stdin commands: fire-and-forget (`void command(...)`) lets a `continue`
+  // race ahead of the launch handshake's configurationDone, and the adapter then
+  // drops or rejects the out-of-order request. Each line awaits the previous command.
+  let chain = Promise.resolve();
+  const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+  rl.on("line", value => { chain = chain.then(() => command(value)).catch(() => {}); });
+}

package/packages/omo-codex/plugin/skills/debugging/references/scripts/fixture-adapter.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Deterministic DAP fixture used by dap.test.ts.
+import { stdin, stdout, argv } from "node:process";
+
+let seq = 1;
+let buffer = Buffer.alloc(0);
+const noAnswer = argv.includes("--no-answer") || process.env.DAP_FIXTURE_NO_ANSWER === "1";
+
+function send(message) {
+  const body = Buffer.from(JSON.stringify(message));
+  stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  stdout.write(body);
+}
+function response(request, body = {}, success = true, message) {
+  send({ type: "response", seq: seq++, request_seq: request.seq, success, command: request.command, body, ...(message ? { message } : {}) });
+}
+function event(event, body = {}) { send({ type: "event", seq: seq++, event, body }); }
+function handle(request) {
+  if (noAnswer && request.command === "initialize") return;
+  switch (request.command) {
+    case "initialize":
+      response(request, { supportsConfigurationDoneRequest: true, supportsEvaluateForHovers: true });
+      event("initialized");
+      break;
+    case "setBreakpoints": {
+      const bps = request.arguments?.breakpoints ?? [];
+      response(request, { breakpoints: bps.map((bp, i) => ({ id: i + 1, verified: !request.arguments?.source?.path?.includes("unverified"), line: bp.line, column: bp.column ?? 1, message: "fixture" })) });
+      break;
+    }
+    case "configurationDone": response(request); break;
+    case "launch": response(request); break;
+    case "continue": response(request, { allThreadsContinued: true }); event("stopped", { reason: "breakpoint", threadId: 1, allThreadsStopped: true }); break;
+    case "next": case "stepIn": case "stepOut": response(request); event("stopped", { reason: "step", threadId: 1 }); break;
+    case "pause": response(request); event("stopped", { reason: "pause", threadId: 1 }); break;
+    case "threads": response(request, { threads: [{ id: 1, name: "main" }] }); break;
+    case "stackTrace": response(request, { stackFrames: [{ id: 42, name: "main", source: { path: "/tmp/program.py" }, line: 12, column: 3 }] }); break;
+    case "scopes": response(request, { scopes: [{ name: "Locals", variablesReference: 7, expensive: false }] }); break;
+    case "variables": response(request, { variables: Array.from({ length: 250 }, (_, i) => ({ name: `v${i + 1}`, value: request.arguments?.variablesReference === 8 ? `${String(i + 1)} ${"x".repeat(500)}` : String(i + 1), variablesReference: 0 })) }); break;
+    case "evaluate": response(request, { result: "42", type: "int", variablesReference: 0 }); break;
+    case "terminate": response(request); event("terminated", {}); break;
+    default: response(request, {}, false, `unsupported ${request.command}`);
+  }
+}
+stdin.on("data", chunk => {
+  buffer = Buffer.concat([buffer, chunk]);
+  while (true) {
+    const marker = buffer.indexOf(Buffer.from("\r\n\r\n"));
+    if (marker < 0) return;
+    const header = buffer.subarray(0, marker).toString();
+    const match = header.match(/Content-Length:\s*(\d+)/i);
+    if (!match) { buffer = buffer.subarray(marker + 4); continue; }
+    const length = Number(match[1]);
+    const start = marker + 4;
+    if (buffer.length < start + length) return;
+    const body = buffer.subarray(start, start + length);
+    buffer = buffer.subarray(start + length);
+    try { handle(JSON.parse(body.toString("utf8"))); } catch { /* fixture input is controlled */ }
+  }
+});

package/packages/omo-codex/plugin/skills/debugging/references/tools/dap.md

@@ -0,0 +1,103 @@
+# DAP Client (`dap.mjs`) — Drive the Debugger's Protocol, Not Its Text
+
+**Design modeled on the `debug` tool of oh-my-pi (https://github.com/can1357/oh-my-pi, branch omp2).** Their harness proved the shape: one structured debug surface with bounded output, stop snapshots, and classified errors. This script brings the same discipline to any agent with a shell — no harness tool registration required.
+
+Debuggers already speak the Debug Adapter Protocol (DAP), a machine-readable JSON protocol. Driving DAP beats screen-scraping a PTY for the same reason an API beats OCR: structured stops, structured variables, structured errors. **If the debugger speaks DAP, use this script instead of parsing `gdb`/`pdb` output.**
+
+The script is at `references/scripts/dap.mjs` — zero dependencies, runs under Bun or Node.
+
+---
+
+## When to use which interface
+
+| Situation | Use |
+|---|---|
+| Source-level debugging of Python / Go / Node / native code, and you need breakpoints, stepping, variables | `dap.mjs` (this file) |
+| Browser-served JS, or anything already in Chrome | Scripted CDP — see `references/runtimes/node.md` |
+| Stripped binary, no source, no symbols | Ghidra (static) + Frida (live) — see `references/tools/` |
+| The debugger has no DAP mode (plain gdb on an exotic target) | pwndbg, with the output-budget rule from `references/methodology/00-setup.md` |
+
+---
+
+## How to drive it
+
+`dap.mjs` is a **REPL**, not a one-shot command: a debug session is long-lived, so the script runs as a persistent process reading one command per line on stdin and writing bounded text on stdout. Run it as a background shell session, send commands to its stdin, and subscribe to its output.
+
+```
+bun references/scripts/dap.mjs
+```
+
+Every execution-control answer prints a single snapshot line beginning with `STOP:` — subscribe your watcher to that exact prefix so a breakpoint hit wakes you instead of you polling.
+
+### Commands
+
+| Command | Effect |
+|---|---|
+| `launch <adapter> <program> [args...]` | Spawn a stdio adapter (path to executable or `.mjs` adapter) and launch the program under it |
+| `attach <host:port>` | Connect to a listening adapter over TCP and attach |
+| `break <file>:<line>` / `rmbreak <file>:<line>` | Set / remove a source breakpoint |
+| `continue` / `step` / `next` / `stepin` / `stepout` / `pause` | Execution control; each prints a `STOP:` snapshot when the debuggee next stops |
+| `stack [limit]` | TSV backtrace, bounded |
+| `scopes` | Scopes of the top frame with their variablesReferences |
+| `vars <ref>` | Variables under a variablesReference from `scopes` — refs are session-scoped; always chain `scopes` first |
+| `eval <expr>` | Evaluate in the top frame |
+| `threads` / `sessions` | Thread list / session state |
+| `terminate` / `quit` | End the debuggee / exit the REPL |
+
+### Output contract (what keeps your context alive)
+
+- Tabular results are TSV with a header row.
+- Hard caps: `MAX_ROWS = 100`, `MAX_OUTPUT_BYTES = 32 KB`. Overflow prints an explicit `TRUNCATED: rows dropped=N bytes dropped=M` line — never a silent cut.
+- After every continue/step: `STOP: stopped reason=<why> threadId=<id> <frame> at <file>:<line>:<col>`. On debuggee exit: `EXIT: terminated`.
+- Errors are one line, classified: `ERR: invalid-args | no-session | adapter-failed | unverified-breakpoint | timeout | terminated | adapter-error`. The token tells you the recovery — see the failure taxonomy in `references/methodology/02-investigate.md`.
+- Every request times out after 15 s (override with `DAP_TIMEOUT_MS`) and the session stays alive.
+- `DAP_DEBUG=1` logs raw protocol traffic to stderr for diagnosing a misbehaving adapter.
+
+### Adapter quirks this client already handles
+
+- **debugpy** requires `console: "internalConsole"` in the launch request, and withholds the `initialized` event for unrecognized `adapterID`s — the client sends both correctly. It also flushes `initialized` lazily, so the client launches first and awaits the event after.
+- **lldb-dap** reports the launch response's `success` unreliably (`false` even when the process started and stopped) and reports `threadId: 0` on the entry stop. The events are the real signal; the client tolerates the response flag.
+
+---
+
+## Adapter matrix
+
+Translated from oh-my-pi's `builtin_adapters()` (omp2 `crates/docserver/src/dap_adapter.rs`). Install the one matching your runtime; the client speaks to all of them the same way.
+
+| Runtime | Adapter | Install | Launch mode |
+|---|---|---|---|
+| Python | debugpy | `pip install debugpy` | `python -m debugpy.adapter` (stdio) |
+| Go | dlv | `go install github.com/go-delve/delve/cmd/dlv@latest` | `dlv dap` (stdio) |
+| C/C++/Swift/Rust/Zig | lldb-dap | ships with Xcode CLT / LLVM | `lldb-dap` (stdio) |
+| C/C++/Rust/Zig | codelldb | VS Code extension binary | stdio |
+| C/C++/Rust | gdb | `brew install gdb` / apt | via gdb's DAP mode where available |
+| JS/TS | js-debug | `npm i -g @vscode/js-debug` | stdio |
+| .NET | netcoredbg | GitHub releases | stdio |
+| Ruby | rdbg | `gem install debug` | stdio |
+| Kotlin | kotlin-debug-adapter | GitHub releases | stdio |
+| PHP | php-debug-adapter | composer | stdio |
+| Bash | bash-debug-adapter | GitHub releases | stdio |
+| Dart/Flutter | dart debug adapter | ships with Dart SDK | `dart` (stdio) |
+| Elixir | elixir-ls debugger | GitHub releases | stdio |
+
+If an adapter is missing, the install line is the fix — do not fall back to scraping a REPL.
+
+---
+
+## Worked example (Python)
+
+```
+launch /path/to/python -m debugpy.adapter myscript.py   # or a wrapper script path
+break myscript.py:12
+continue
+STOP: stopped reason=breakpoint threadId=1 compute at myscript.py:12:1
+stack
+scopes
+vars 6          # the variablesReference scopes just printed for Locals
+eval total
+continue
+terminate
+quit
+```
+
+Cleanup is part of the session: `terminate` the debuggee, `quit` the REPL, and journal any wrapper scripts you created per the skill's cleanup phase.

package/packages/omo-codex/plugin/skills/debugging/references/tools/frida.md

@@ -0,0 +1,193 @@
+# Frida — Hook a Live Process and See Real Values at Runtime
+
+**https://frida.re**
+
+Frida injects a JavaScript engine into a running process and lets you intercept function calls, read arguments, patch return values, and trace execution without touching the binary on disk. **When static analysis in Ghidra shows you *what* a function does, Frida shows you what it does *right now*, with real inputs.** The two compose naturally: use Ghidra to find the target function and its offset, then use Frida to hook it and watch live traffic.
+
+Choose Frida over Ghidra when you need runtime values (actual arguments, return codes, heap contents) or when the binary's control flow is too obfuscated for static analysis to resolve.
+
+---
+
+## Install
+
+```bash
+pip install frida-tools            # Python 3 required
+frida --version                    # verify
+```
+
+On macOS, attaching to another user's process needs root (`sudo frida ...`). SIP-protected system binaries (`/usr/bin/*`, `/usr/sbin/*`) are off-limits entirely. On Linux, you may need `ptrace` permissions: run as root or set `kernel.yama.ptrace_scope=0`.
+
+---
+
+## Target discovery with `frida-ps`
+
+```bash
+frida-ps                         # list local processes
+frida-ps -U                      # USB-connected device (iOS/Android)
+frida-ps | grep -i target        # find your target by name
+```
+
+---
+
+## `frida-trace` — zero-code entry point
+
+`frida-trace` auto-generates JavaScript handler stubs for every matched function. You don't write any code to start.
+
+```bash
+frida-trace -p <pid> -i "recv*"                               # trace exported functions by glob
+frida-trace -p <pid> -m "-[NSURLSession dataTaskWithRequest:*]"  # Objective-C method
+frida-trace -U -p <pid> -j "com.example.App!login*"             # Java method (Android)
+frida-trace -f ./target -i "open"                               # spawn + trace from start
+```
+
+Generated handler files land in `__handlers__/`. Each looks like:
+
+```js
+// __handlers__/libSystem.B.dylib/open.js
+{
+  onEnter(log, args, state) {
+    // args[0] is the first argument (a pointer)
+    log(`open("${args[0].readUtf8String()}")`);
+  },
+  onLeave(log, retval, state) {
+    log(`  => ${retval}`);
+  }
+}
+```
+
+Edit that file, save, and `frida-trace` hot-reloads it. This is the fastest path from "I wonder what this function receives" to a concrete answer.
+
+---
+
+## The JS agent API
+
+When `frida-trace` isn't enough, you write a JS agent and load it with `frida` or from a Python host script. These are the building blocks.
+
+### Find a function
+
+```js
+// By exported symbol name
+const openPtr = Module.getExportByName(null, "open");  // null = any module
+const sslWritePtr = Module.getExportByName("libssl.so", "SSL_write");
+
+// By offset in a stripped binary (get the offset from Ghidra)
+const base = Module.getBaseAddress("target");
+const funcPtr = base.add(0x1a3c);
+```
+
+### Intercept calls
+
+```js
+Interceptor.attach(openPtr, {
+  onEnter(args) {
+    // args[0], args[1], ... are NativePointer objects
+    const path = args[0].readUtf8String();
+    const flags = args[1].toInt32();
+    send({ event: "open", path: path, flags: flags });
+  },
+  onLeave(retval) {
+    // retval is the return value as a NativePointer
+    send({ event: "open_ret", fd: retval.toInt32() });
+  }
+});
+```
+
+### Read memory
+
+```js
+args[0].readUtf8String()          // read a UTF-8 C string from a pointer
+args[0].readCString()             // read a raw C string (stops at null)
+args[1].readByteArray(len)        // read len raw bytes (returns ArrayBuffer)
+```
+
+### Replace / stub a function
+
+```js
+// Force a function to always return 0 (e.g. bypass a license check)
+Interceptor.replace(checkLicensePtr, new NativeCallback(function () {
+  return 0;
+}, 'int', []));
+```
+
+Use `Interceptor.replace` sparingly. It changes program behavior, so always note in your journal that you patched something and why.
+
+---
+
+## Python host script
+
+A host script lets you load a JS agent, receive `send()` messages, and post-process results from the Python side.
+
+```python
+import frida, sys
+
+with open("agent.js") as f:
+    agent_source = f.read()
+
+def on_message(message, data):
+    if message["type"] == "send":
+        print(f"[*] {message['payload']}")
+    else:
+        print(f"[!] {message}")
+
+session = frida.attach(int(sys.argv[1]))
+script = session.create_script(agent_source)
+script.on("message", on_message)
+script.load()
+
+try:
+    sys.stdin.read()                 # block until Ctrl+C
+except KeyboardInterrupt:
+    session.detach()
+```
+
+The agent runs inside the target; the host script stays in your terminal and prints structured output.
+
+---
+
+## Output-budget discipline
+
+**Hooking a hot function (e.g. `malloc`, `read`) will flood your context with thousands of lines.** Don't print every call. Aggregate in the agent and report a summary.
+
+```js
+// Count calls, report every 1000
+let callCount = 0;
+Interceptor.attach(mallocPtr, {
+  onEnter(args) {
+    callCount++;
+    if (callCount % 1000 === 0) {
+      send({ event: "malloc_summary", total_calls: callCount });
+    }
+  }
+});
+```
+
+Alternatives: filter by argument value, only log calls from a specific caller module, or batch into an array and `send()` on a timer.
+
+---
+
+## ⚠️ Gotchas
+
+**Attach vs. spawn.** `frida -p <pid>` attaches to an already-running process. If you need to catch early initialization (constructors, `main` entry), spawn the process with `frida -f ./target`. Frida pauses it at startup. Resume with `%resume` in the REPL or by calling `device.resume(pid)` from Python.
+
+**Stripped binaries have no symbol names.** `Module.getExportByName` returns null for internal functions. You must find the function offset in Ghidra, then compute the address at runtime:
+
+```js
+const addr = Module.getBaseAddress("target").add(0x4a20);
+Interceptor.attach(addr, { /* ... */ });
+```
+
+**A crashing target kills your session.** If the target segfaults or aborts, Frida's agent dies with it. Script a respawn loop on the Python side if you expect crashes.
+
+**Thread safety.** `onEnter`/`onLeave` fire on multiple threads. Keep shared state to simple counters.
+
+---
+
+## Cleanup
+
+```bash
+kill <pid>                         # kill any process you spawned with -f
+rm -rf __handlers__/               # remove generated handler stubs
+rm -f agent.js host.py             # remove session-specific scripts
+```
+
+Always note in your journal which processes you attached to and whether you replaced any functions. A forgotten `Interceptor.replace` in a long-running target will cause confusing behavior later.