residoo 0.1.0 → 0.2.0

package/src/sources/open-interpreter.js

@@ -0,0 +1,224 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * Open Interpreter (the classic Python "natural language interface for
+ * computers" CLI, `pip install open-interpreter`, entry point `interpreter`).
+ *
+ * VERIFICATION STATUS: NOT installed on the machine this adapter was built on
+ * (checked: no `interpreter`/`open-interpreter` on PATH, no `open-interpreter`
+ * in `pip3 list`, no conversations directory under any of the paths below).
+ * Ships anyway per CONTRIBUTING.md rule 3, on unusually strong grounds for an
+ * "unverified" source: not a description of the tool, but the tool's own
+ * source code, read directly, plus a real, on-this-machine execution of the
+ * exact path-resolution call the tool itself makes at import time (only the
+ * `interpreter.chat()` LLM round-trip itself was not exercised, since that
+ * needs a model API key this research had no reason to acquire):
+ *
+ *  - `interpreter/core/core.py` (fetched from the real GitHub history, tag
+ *    v0.4.2 — see the naming note below) confirms conversation logging is ON
+ *    by default (`conversation_history=True` in `OpenInterpreter.__init__`)
+ *    and shows the exact write path: after every `chat()` turn, the full
+ *    `self.messages` list is re-serialized whole with `json.dump(self.messages, f)`
+ *    to `<conversation_history_path>/<conversation_filename>`, where the
+ *    filename is `<first-25-chars-of-first-message-slug>__<Month_DD_YYYY_HH-MM-SS>.json`
+ *    and `conversation_history_path` defaults to `get_storage_path("conversations")`.
+ *  - `interpreter/terminal_interface/utils/local_storage_path.py` confirms
+ *    `get_storage_path(sub)` is `os.path.join(platformdirs.user_config_dir("open-interpreter"), sub)`
+ *    — i.e. a single call into the third-party `platformdirs` library, not a
+ *    hand-rolled per-OS branch.
+ *  - `interpreter/terminal_interface/conversation_navigator.py` and
+ *    `.../utils/get_conversations.py` both independently confirm the
+ *    directory is listed non-recursively for `*.json` files — no subfolders,
+ *    no other extension.
+ *  - `platformdirs`' OWN source (tox-dev/platformdirs, macos.py/windows.py/
+ *    unix.py + api.py, fetched and read directly) confirms, for a call with
+ *    only an appname (no appauthor) exactly like this one:
+ *      * macOS: `user_config_dir` == `user_data_dir` == `~/Library/Application
+ *        Support/<appname>` (macOS doesn't split these the way XDG does).
+ *      * Linux/XDG: `$XDG_CONFIG_HOME/<appname>` or `~/.config/<appname>`.
+ *      * Windows: `user_config_dir` == `user_data_dir`; `appauthor` defaults
+ *        to `appname` when omitted (confirmed from platformdirs' own
+ *        `api.py` docstring), giving `%LOCALAPPDATA%\<appname>\<appname>`.
+ *  - REAL execution, on this machine, of the literal call `core.py` makes:
+ *    a throwaway venv with only `platformdirs` installed (a zero-dependency,
+ *    pure-path-math package — not the multi-hundred-MB `open-interpreter`
+ *    package itself, which was not worth installing just to import one
+ *    function) ran `platformdirs.user_config_dir("open-interpreter")` and
+ *    printed `/Users/Dan/Library/Application Support/open-interpreter` —
+ *    exactly matching the macOS formula derived from source above. The venv
+ *    was deleted after use; nothing from it is installed anymore.
+ *  - PyPI's `open-interpreter` project page confirms the latest release is
+ *    0.4.3 (2024-10-26) — i.e. this scheme, introduced in v0.3.0 (see below),
+ *    is still what today's `pip install open-interpreter` ships.
+ *
+ * NAMING TRAP, resolved during this research: the GitHub org this project
+ * lived under (`openinterpreter`) was reused in 2026 for an unrelated, brand
+ * new Rust rewrite ("a coding agent for open models like Kimi K3", built on
+ * OpenAI's open-sourced Codex CLI — its repo tree is full of `codex-rs/*`
+ * paths). That is NOT this tool. This adapter targets the classic Python
+ * package the task actually asked for ("Python-based local-execution agent"),
+ * reached via the org's still-intact git tag history (tag `v0.4.2`, the last
+ * one cut before the rewrite) rather than the `main` branch, which now holds
+ * the unrelated project.
+ *
+ * VERSION DRIFT, checked and deliberately scoped around: fetching
+ * `local_storage_path.py` at old tags shows v0.1.x/v0.2.x used a DIFFERENT
+ * library and app name — `appdirs.user_config_dir("Open Interpreter")`
+ * (capitalized, space, no hyphen) — before v0.3.0 switched to the
+ * `platformdirs` + `"open-interpreter"` scheme this adapter targets as
+ * current. That legacy scheme was itself verified the same way: real
+ * execution on this machine (`appdirs.user_config_dir("Open Interpreter")`
+ * printed `/Users/Dan/Library/Application Support/Open Interpreter` — note
+ * the differing capitalization from the current path) plus reading appdirs'
+ * own source for its Windows/Linux formulas. Both schemes read `conversations/`
+ * for `*.json` files the same way in both eras (confirmed directly from
+ * source at old and new tags alike), so this source scans both directories
+ * rather than picking one — the same "format moved, so read every location
+ * it has lived" choice cursor.js and gemini-cli.js make for their own
+ * cross-version drift.
+ */
+function platformdirsConfigDir(appname) {
+  const home = os.homedir();
+  if (process.platform === "darwin") {
+    return path.join(home, "Library", "Application Support", appname);
+  }
+  if (process.platform === "win32") {
+    // appauthor is never passed by Open Interpreter's own call, so
+    // platformdirs falls back to using appname as the author too (confirmed
+    // from platformdirs' api.py docstring) — hence the doubled segment.
+    const base = process.env.LOCALAPPDATA || path.join(home, "AppData", "Local");
+    return path.join(base, appname, appname);
+  }
+  // Linux and other XDG-following unix platforms.
+  const configHome = process.env.XDG_CONFIG_HOME || path.join(home, ".config");
+  return path.join(configHome, appname);
+}
+
+const CURRENT_CONVERSATIONS_DIR = path.join(platformdirsConfigDir("open-interpreter"), "conversations");
+const LEGACY_CONVERSATIONS_DIR = path.join(platformdirsConfigDir("Open Interpreter"), "conversations");
+
+// Bounds for readLines() — same shape as claude-code.js's, but the number is
+// NOT backed by a real large Open Interpreter conversation file this tool
+// was tested against (no install available). A single conversation file here
+// is a whole-session JSON re-dump, not an append-only log, so it is expected
+// to be far smaller than a multi-session JSONL transcript in practice — this
+// is a generous, untested backstop against a pathological file, not evidence
+// of what real files look like.
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB
+const READ_TIMEOUT_MS = 60_000;
+
+function id() { return "open-interpreter"; }
+function label() { return "Open Interpreter"; }
+
+function available() {
+  return dirExists(CURRENT_CONVERSATIONS_DIR) || dirExists(LEGACY_CONVERSATIONS_DIR);
+}
+
+function dirExists(p) {
+  try { return fs.statSync(p).isDirectory(); } catch { return false; }
+}
+
+/**
+ * Same defensive symlink-following pattern as claude-code.js — see that
+ * file's docstring for the full reasoning. Duplicated rather than imported:
+ * each source here is meant to be a small, self-contained file a reviewer
+ * can audit on its own (see CONTRIBUTING.md).
+ */
+function isFileFollowingSymlink(fullPath, dirent) {
+  if (dirent.isFile()) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return fs.statSync(fullPath).isFile(); } catch { return false; }
+}
+
+/**
+ * Yield { file, mtimeMs, sizeBytes, broken } for every `*.json` file directly
+ * inside one conversations directory — flat, non-recursive, matching
+ * `get_conversations.py`'s own `os.listdir(...)` + `.endswith(".json")`
+ * exactly (no subfolder nesting exists in this format at either the current
+ * or legacy path).
+ */
+function* walkConversationsDir(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return; } // directory doesn't exist — not broken, just nothing here yet
+
+  for (const e of entries) {
+    if (!e.name.endsWith(".json")) continue;
+    const file = path.join(dir, e.name);
+    if (!isFileFollowingSymlink(file, e)) {
+      if (e.isSymbolicLink()) yield { file, broken: true };
+      continue;
+    }
+    let stat;
+    try { stat = fs.statSync(file); } catch { yield { file, broken: true }; continue; }
+    yield { file, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+/**
+ * Yields every `*.json` conversation file under both the current
+ * (platformdirs) and legacy (appdirs) conversations directories — see the
+ * module docstring for why both are read. When both directories happen to
+ * resolve to the exact same path (impossible here since the app names differ
+ * in case/hyphenation on every supported OS, but guarded anyway in case a
+ * future platformdirs/appdirs release ever changes that), the second walk is
+ * skipped rather than double-yielding every file in it.
+ */
+function* files() {
+  yield* walkConversationsDir(CURRENT_CONVERSATIONS_DIR);
+  if (LEGACY_CONVERSATIONS_DIR !== CURRENT_CONVERSATIONS_DIR) {
+    yield* walkConversationsDir(LEGACY_CONVERSATIONS_DIR);
+  }
+}
+
+/**
+ * Read one conversation file as an array of raw text lines. Identical
+ * streaming strategy to claude-code.js's readLines (a JSON file on disk is
+ * still line-delimited text as far as a byte stream is concerned) — see that
+ * file's docstring for the full reasoning behind streaming + a hard timeout.
+ *
+ * In practice, `json.dump(self.messages, f)` is called with no `indent=`, so
+ * the whole file is one single physical line (Python's json module escapes
+ * embedded newlines inside string values as `\n`, it doesn't emit them raw)
+ * — that's fine: the pattern-matcher works on raw text regardless of how
+ * many physical lines it's split across, exactly per the adapter contract
+ * cursor.js's docstring already spells out for a whole-document-per-row case.
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1; // +1 for the stripped newline
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    // Whatever WAS read before the failure is real content and may contain a
+    // real secret — discarding it because the file didn't finish cleanly
+    // would be a silent false negative, which is worse than an honest
+    // "partial" label.
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };

package/src/sources/openclaw.js

@@ -0,0 +1,218 @@
+"use strict";
+
+const fs = require("fs");
+const { createInterface } = require("readline/promises");
+const path = require("path");
+const os = require("os");
+
+/**
+ * OpenClaw (openclaw/openclaw, "your own personal AI assistant... the
+ * lobster way") session transcripts. OpenClaw is a multi-channel agent
+ * gateway (Discord/Slack/Telegram/iMessage/etc.) that can launch and drive
+ * other coding agents (Claude Code, Codex, OpenCode, Kiro CLI, Pi) as
+ * subprocesses — those tools' own transcripts are already covered by this
+ * project's other sources; this source covers OpenClaw's OWN session/chat
+ * logs (the conversation the user has with OpenClaw itself, across whatever
+ * channel it's reached from).
+ *
+ * VERIFICATION STATUS: NOT checked against a real install — no `~/.openclaw`
+ * (or any of the legacy names below) exists on the machine this adapter was
+ * built on. Ships per CONTRIBUTING.md rule 3 on two independent
+ * corroborating sources, WITH THE SAME INTEGRITY CAVEAT documented at length
+ * in hermes.js's module docstring — summarized here, read that file for the
+ * full reasoning: `gh api` showed openclaw/openclaw at 388,546 GitHub stars
+ * for a repo created 2025-11-24 (more stars in under a year than
+ * facebook/react has after 13 years, sanity-checked against real repos in
+ * the same research pass), and independent search turned up a real fake-
+ * GitHub-stars research paper, a Hacker News thread about a plagiarism
+ * dispute between Hermes Agent and OpenClaw specifically, and a GitHub topic
+ * literally describing "Two zero-human AI companies battle for GitHub stars
+ * using Hermes Agent + Paperclip." That doesn't make the format below wrong,
+ * but it does mean OpenClaw's own docs and Hermes' own docs may not be
+ * independent of each other (Hermes' docs describe importing OpenClaw's
+ * config directory directly) — treat this as
+ * multi-source-corroborated-but-unverified, not stronger, and see this
+ * adapter's PR description/report for the full writeup.
+ *
+ * The two sources:
+ *
+ *   1. OpenClaw's own docs (docs.openclaw.ai/cli, /gateway/configuration):
+ *      default state directory `~/.openclaw`, overridable via
+ *      `OPENCLAW_STATE_DIR`; `--profile <name>` isolates state under
+ *      `~/.openclaw-<name>`; `--dev` uses `~/.openclaw-dev`.
+ *   2. ccusage (github.com/ccusage/ccusage — see hermes.js for why this
+ *      project's own star count and code were trusted) ships a tested Rust
+ *      adapter for OpenClaw (rust/adapters/openclaw/src/{paths,parser}.rs),
+ *      fetched and read directly. It confirms: an `OPENCLAW_DIR` env var
+ *      (comma-separated list — ccusage's own name, not confirmed identical
+ *      to OPENCLAW_STATE_DIR above, so this source checks both rather than
+ *      betting on one), and — absent either — four candidate home-relative
+ *      directories: `~/.openclaw`, `~/.clawdbot`, `~/.moltbot`, `~/.moldbot`
+ *      (evidently earlier names across OpenClaw's own rebrand history).
+ *      Under whichever directory exists, it recursively collects files whose
+ *      name contains `.jsonl` as an exact suffix, or as
+ *      `.jsonl.deleted.<...>` / `.jsonl.reset.<...>` (OpenClaw's own naming
+ *      for archived/rotated session files) — confirmed by that adapter's own
+ *      unit test asserting exactly these three shapes. Each line is plain
+ *      JSONL: a `{"type":"model_change",...}` or
+ *      `{"type":"custom","customType":"model-snapshot",...}` tracking
+ *      record, or a `{"type":"message","message":{"role":...,...}}` record —
+ *      confirmed directly from that adapter's own parser and fixture data.
+ *
+ * One deliberate departure from ccusage's own behaviour: its directory walk
+ * explicitly `continue`s past any symlink it meets (`file_type.is_symlink()
+ * => continue`) — reasonable for a usage-stats tool, wrong for a security
+ * scanner. This source instead follows claude-code.js's own house
+ * convention: follow a symlink if it resolves, report it `broken: true` if
+ * it doesn't, never silently skip it either way (CONTRIBUTING.md rule 5).
+ */
+const OPENCLAW_STATE_DIR_ENV = "OPENCLAW_STATE_DIR"; // OpenClaw's own official docs name
+const OPENCLAW_DIR_ENV = "OPENCLAW_DIR"; // ccusage's name — kept as a second, unconfirmed alias
+const LEGACY_HOME_NAMES = [".openclaw", ".clawdbot", ".moltbot", ".moldbot"];
+
+function id() { return "openclaw"; }
+function label() { return "OpenClaw"; }
+
+function envRoots() {
+  for (const envVar of [OPENCLAW_STATE_DIR_ENV, OPENCLAW_DIR_ENV]) {
+    const val = process.env[envVar];
+    if (val && val.trim() !== "") {
+      return val.split(",").map((s) => s.trim()).filter((s) => s !== "").map((p) => path.resolve(p));
+    }
+  }
+  return null;
+}
+
+/**
+ * Resolve every OpenClaw state root that actually exists on disk: either
+ * both env-var overrides (checked in envRoots()), or every legacy/renamed
+ * default directory under $HOME that's present, PLUS any `~/.openclaw-*`
+ * sibling (covers `--profile <name>` and `--dev`, per source 1 above —
+ * ccusage's own code doesn't do this, since it wasn't documented from
+ * ccusage's side, only OpenClaw's own docs).
+ */
+function stateRoots() {
+  const env = envRoots();
+  if (env) return env.filter((p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } });
+
+  const home = os.homedir();
+  const roots = [];
+  for (const name of LEGACY_HOME_NAMES) {
+    const dir = path.join(home, name);
+    try { if (fs.statSync(dir).isDirectory()) roots.push(dir); } catch { /* not present */ }
+  }
+
+  let homeEntries;
+  try { homeEntries = fs.readdirSync(home, { withFileTypes: true }); }
+  catch { homeEntries = []; }
+  for (const e of homeEntries) {
+    if (!e.name.startsWith(".openclaw-")) continue;
+    const dir = path.join(home, e.name);
+    if (roots.includes(dir)) continue;
+    let isDir = e.isDirectory();
+    if (!isDir && e.isSymbolicLink()) {
+      try { isDir = fs.statSync(dir).isDirectory(); } catch { isDir = false; }
+    }
+    if (isDir) roots.push(dir);
+  }
+  return roots;
+}
+
+function available() {
+  return stateRoots().length > 0;
+}
+
+function isKindFollowingSymlink(fullPath, dirent, checkFn) {
+  if (checkFn(dirent)) return true;
+  if (!dirent.isSymbolicLink()) return false;
+  try { return checkFn(fs.statSync(fullPath)); } catch { return false; }
+}
+const isDirFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isDirectory());
+const isFileFollowingSymlink = (p, d) => isKindFollowingSymlink(p, d, (x) => x.isFile());
+
+/**
+ * True for `*.jsonl`, `*.jsonl.deleted.<...>`, `*.jsonl.reset.<...>` —
+ * mirrors ccusage's own `is_openclaw_session_file` (including its own unit
+ * test's exact examples) byte for byte.
+ */
+function isOpenClawSessionFile(name) {
+  const index = name.indexOf(".jsonl");
+  if (index === -1) return false;
+  const suffix = name.slice(index);
+  return suffix === ".jsonl" || suffix.startsWith(".jsonl.deleted.") || suffix.startsWith(".jsonl.reset.");
+}
+
+/**
+ * Recursively yield { file, mtimeMs, sizeBytes, broken } for every session
+ * file under one root. Depth-first, symlink-following-with-broken-reporting
+ * (see module docstring for why this deliberately differs from ccusage's
+ * own skip-on-symlink walk).
+ */
+function* walk(dir) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { yield { file: dir, broken: true }; return; }
+
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    if (e.isDirectory() || (e.isSymbolicLink() && isDirFollowingSymlink(full, e))) {
+      yield* walk(full);
+      continue;
+    }
+    if (!isOpenClawSessionFile(e.name)) continue;
+    if (!e.isFile()) {
+      const resolved = isFileFollowingSymlink(full, e);
+      if (!resolved) {
+        if (e.isSymbolicLink()) yield { file: full, broken: true };
+        continue;
+      }
+    }
+    let stat;
+    try { stat = fs.statSync(full); } catch { yield { file: full, broken: true }; continue; }
+    yield { file: full, mtimeMs: stat.mtimeMs, sizeBytes: stat.size, broken: false };
+  }
+}
+
+function* files() {
+  for (const root of stateRoots()) yield* walk(root);
+}
+
+const MAX_BYTES = 2 * 1024 * 1024 * 1024; // 2GB — same untested-against-a-real-huge-file backstop
+                                            // claude-code.js uses, for the same stated reason.
+const READ_TIMEOUT_MS = 60_000;
+
+/**
+ * Read one session file as an array of raw text lines — identical
+ * streamed/bounded/timed-out shape to claude-code.js's own readLines(), for
+ * the same reasons documented there (JSONL, so this needs no JSON-array
+ * reconstruction the way codebuff.js's chat-messages.json does).
+ */
+async function readLines(file) {
+  let stat;
+  try { stat = fs.statSync(file); }
+  catch { return { lines: [], status: "failed", bytesRead: 0 }; }
+  if (stat.size > MAX_BYTES) return { lines: [], status: "too-large", bytesRead: 0 };
+
+  const lines = [];
+  let bytesRead = 0;
+  const stream = fs.createReadStream(file, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+
+  const timer = setTimeout(() => stream.destroy(new Error("read timed out")), READ_TIMEOUT_MS);
+
+  try {
+    for await (const line of rl) {
+      lines.push(line);
+      bytesRead += Buffer.byteLength(line, "utf-8") + 1;
+    }
+    return { lines, status: "complete", bytesRead };
+  } catch {
+    return { lines, status: lines.length > 0 ? "partial" : "failed", bytesRead };
+  } finally {
+    clearTimeout(timer);
+    rl.close();
+    stream.destroy();
+  }
+}
+
+module.exports = { id, label, available, files, readLines };