mirror of
https://github.com/alphaXiv/OpenResearch.git
synced 2026-11-11 09:59:34 +08:00
Daniel Kim
5e25afaf98
* Surface silently-dropped chat turns (v0.1.86) A sent message could vanish with no response and no error. Evidence from the live DB: user messages persisted with no assistant reply at all — the claude turn loop waits on child events with no watchdog, so a wedged resident child (seen: expired-OAuth refresh hang) spins forever; the user's only recourse, Stop/Escape, aborted the turn task without leaving any trace; and a failed send POST was swallowed by the UI catch. - claude adapter: watchdog the event wait (120s to first event, 30min between events, matching the codex TURN_WATCHDOG), exempting turns held on a pending mcp-gate approval; on trip, kill the child and surface a visible error (next message resumes via --resume). - ChatHost::interrupt_by_user: the Stop/Escape path now persists an 'Interrupted' marker row, so a stopped turn no longer reads as 'orx did nothing'. Internal interrupts (plan resume, deletes) stay silent. - UI: a failed send now renders a local error row instead of silently clearing busy; chat SSE reconnects re-seed sessions/busy and the active transcript (chat frames are edge-only, gap frames are lost). * Address review: verified send-failure surfacing, watchdog guard arm, shared consts - send() catch: restore draft/attachments even when session creation failed; an explicit 'session is busy' rejection always surfaces (that busy is someone else's turn); a network failure probes server-side busy first and undoes the restore when the turn is real. - claude watchdog: permission re-arm is a guard arm that no longer promotes the first-event deadline; error reports minutes on the mid-turn path and the login hint only on the first-event path. - TURN_WATCHDOG hoisted to harness/mod.rs, shared with codex. - interrupt_by_user: timestamp captured before the abort; WirePart::tool constructor (also used by push_error). - Reconnect repair: shared syncSessionList (deletedIds tombstones, contextUsage merge, seenTitles baseline), seedBusy scoped by known ids, transcript reseed retries once via msgGen when a flush raced it. * Guard claude turns against --resume replay output (echo boundary) Folds in (and supersedes) the unmerged daniel/fix-swallowed-messages branch: a --resume respawn can replay prior-session/startup output before touching the new message — fatally a stale result event, which ended the turn instantly with zero parts while the real reply streamed into a dropped channel. --replay-user-messages makes the child echo the submitted message; the turn loop now skips everything before the echo. Review round (2x empirical against claude 2.1.212): echo is byte-exact and stdin-scoped (no history replay, so no same-text false positive); pre-echo lines count as watchdog proof-of-life (API backoff after boot must not be killed at 120s; only total silence keeps the fast wedge budget + login hint); pre-echo system/init harvests the session id for first-turn interrupts; module docs pin the echo contract. * Reconcile deleted sessions on SSE reconnect; repair after a failed first connect Addresses review findings 2 and 3 on PR #139: - A session deleted while SSE was down lost its chat.session.deleted frame for good: syncSessionList removed the sidebar row but left the cached transcript, loadedSessions, activeId, and — via the known- scoped seedBusy merge — a stale busy flag. Now the pre-fetch snapshot of shown sessions is diffed against the authoritative list and every missing id gets the full forgetSession cleanup, before seedBusy so the ghost's flag can't be carried forward. The snapshot is taken before the fetch (a session created mid-flight can't be tombstoned), and the project-change reset clears the snapshot ref synchronously (the old project's rows must not read as deleted under the new one). - 'reconnected' now also fires when the first successful EventSource open follows a FAILED first connect (page loaded while the backend was briefly down) — the initial fetches likely failed too, so the panel repaired itself only on later drops, never on that first recovery. A clean first open still emits nothing. Verified live on the slot-8 dev stack: session row deleted from the DB while the backend was down; on reconnect (same page, no reload) the row, ghost transcript, active selection, and busy flag all clear.
OpenResearch CLI (orx)
Important
If you are an OpenResearch user or someone who is interested in autoresearch, we'd love to chat with you. Please email contact@alphaxiv.org if interested.
Run autoresearch on your machine
- Run research agents in parallel. Spins up agents in different worktrees so you can investigate several different directions at once.
- Works with Claude Code, Codex, and OpenCode
- Bring your own compute. Works with SSH, Slurm, Kubernetes, Modal, HuggingFace and more.
- Give it a goal. Can run the entire autoresearch loop from literature review to experiment analysis.
- Local and private. Your code and your data stays on your machine.
https://github.com/user-attachments/assets/33b62182-0795-490d-9366-0fb0b4bd49fd
Quick start
curl -LsSf https://openresearch.sh/install.sh | sh
orx up
The dashboard opens at http://127.0.0.1:4791. Give the agent a goal — for
example, ask it to reproduce a paper:
/reproduce-paper <paper URL or title> on <compute>
or turn one into an interactive marimo notebook:
/paper-to-marimo <paper URL or title> on <compute>
The dashboard
orx up runs a single local process on 127.0.0.1 — an embedded web UI plus a
JSON/SSE API over a local SQLite store. From there you get:
- Agent chat — a research assistant with full project context, backed by your locally installed harness: Claude Code, Codex, or OpenCode (pick the harness and model in the UI). Ask it to analyze runs, dig into results, edit code, and spin up new experiments.
- The experiment tree — every experiment is a git branch: a runnable snapshot of your code. The root is your baseline; children are variants measured against it, so lineage stays explicit.
- Runs — launch on your compute (Modal, Hugging Face Jobs, Kubernetes, Slurm, any SSH box, your own machine) or OpenResearch managed GPUs, and watch live logs, statuses, git diffs, files, and linked W&B runs stream in.
- Autoresearch — describe a goal and let the agent run autonomously toward it: proposing, launching, and analyzing experiments.
Everything binds to loopback only; nothing on the dashboard's paths leaves your machine except the compute and paper-search calls you initiate.
On a remote machine
Develop from your laptop while the dashboard runs next to your GPUs:
orx up --remote user@host # or an ~/.ssh/config alias; append :PORT for a custom SSH port
This starts orx up on the remote box over SSH, tunnels the port back, and
opens your browser locally. Note the remote server is unauthenticated on that
host's loopback, so other users on the same box can reach it.
Commands
Run orx --help (or orx <command> --help) for full usage. The highlights:
| Area | Commands |
|---|---|
| Dashboard | up |
| Auth | login, logout |
| Projects | projects, explore, project, create-project, env |
| Experiments | experiments, create-experiment, exp status/cmd/run/cancel |
| Runs & evidence | runs, logs, search-logs, artifacts, artifact, wandb, query, chart, report |
| Compute | compute, instance create |
| Literature | lit, paper (alphaXiv full-text search — no login required) |
| Agent integration | install-skills, skill |
| Maintenance | version, update, telemetry |
orx install-skills drops the OpenResearch skill into your local coding agents
(Claude Code, Codex, OpenCode, Cursor) so they can drive orx themselves —
orx login offers this too.
Installing
The install script above fetches the latest prebuilt release (macOS and Linux, x86_64 and arm64) and is the same as:
curl -LsSf https://github.com/alphaXiv/openresearch-cli/releases/latest/download/openresearch-cli-installer.sh | sh
orx update keeps script-installed binaries current; interactive terminals
also get a once-a-day background check with a one-line stderr notice (silence
it with ORX_NO_UPDATE_CHECK=1).
From source
Requires Rust (stable) via rustup. The prebuilt dashboard
UI is committed at ui/dist, so a plain build works:
cargo build --release # binary at target/release/orx
cargo install --path . # or install onto your PATH (~/.cargo/bin)
To hack on the dashboard UI itself (Vite + React, embedded into the binary at build time):
cd ui && pnpm install && pnpm build
Run the tests with cargo test.
Configuration
- API URL — defaults to production (
https://api.openresearch.sh); override with--api-urlorOPENRESEARCH_API_URL. - Credentials —
orx loginopens your browser, mints a personal access token, and stores it at${XDG_CONFIG_HOME:-~/.config}/openresearch/credentials.json(mode0600). Sent asAuthorization: Bearer …on every request.
Usage analytics
orx sends anonymous usage analytics to help prioritize features. It's
opt-out, and the orx up onboarding surfaces the choice on first run.
- Collected: command name, a random per-install UUID, CLI version, OS/arch,
a CI flag, and coarse event labels (e.g. "a run launched on
modal"). - Never collected: code, prompts, file contents or paths, project or experiment ids/names, repo names, tokens, emails — nothing identifying. The install UUID is not tied to your account.
orx telemetry off # persistent, per-machine
orx telemetry status # current state + the anonymous install id
orx <cmd> --no-telemetry # per-run
Events are fire-and-forget on a background task and never block a command.