Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .env.example
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,11 @@ QUESTION_ID_SECRET=
# PORT=3000
# Points the API at `render workflows dev` instead of Render; RENDER_API_KEY is then optional.
# RENDER_LOCAL_DEV_URL=http://localhost:8121
# Optional browser UI: setting WEB_PASSWORD enables it at `/`. The password is at least 12
# characters; the server-only session secret is at least 32. Browser history stays in localStorage.
# WEB_PASSWORD=
# WEB_SESSION_SECRET=
# WEB_DIST_DIR=web/dist

# ── `pnpm ask` ──────────────────────────────────────────────────────────
# API_URL=http://localhost:3000
Expand Down
1 change: 1 addition & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -21,4 +21,5 @@ jobs:
cache: pnpm
- run: pnpm install --frozen-lockfile
- run: pnpm typecheck
- run: pnpm build:web
- run: pnpm test
12 changes: 11 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,10 @@ Ask how your code behaves and get an answer with file-and-line citations, checke

The button forks this repository into your GitHub account and creates a Blueprint from your fork. The fork starts out investigating the example corpus: three public repositories (the Render CLI, SDK, and agent skills). To point it at your own code, edit `config.ts` and `prompt.md` in your fork and push.

The researcher is an HTTP API with no UI. You ask questions with `pnpm ask` or `curl`, so opening the service URL in a browser shows `404 Not Found`. That's expected; `/healthz` returns `ok` when the service is up.
The researcher is an HTTP API with an optional password-protected browser UI.
Without `WEB_PASSWORD`, it remains API-only and opening the service URL returns
`404 Not Found`. Ask questions with `pnpm ask`, `curl`, or
[enable the UI](docs/0_QUICKSTART.md#enable-the-browser-ui).

## Get running

Expand All @@ -27,6 +30,13 @@ The [Quickstart](docs/0_QUICKSTART.md) has every step in detail, including how t

To try it on your machine first, without a Sandbox or a model key, clone a couple of repositories into `.scratch/repos/` and run the workflow and the API locally with the runner's `--faux` mode, which follows a fixed script instead of calling a model. [Run it locally](docs/0_QUICKSTART.md#run-it-locally) has the commands.

### Optional browser UI

Set `WEB_PASSWORD` and `WEB_SESSION_SECRET` on the API service to serve the UI
at `/`. It uses the same durable question API and stores question IDs and
titles in that browser's local storage, so it adds no database or service.
The bearer `API_TOKEN` is never sent to browser code.

## What you get

Every answer has the same structure: a short answer, a confidence level, what was observed in code, what was inferred, what was not established, file-and-line evidence, a suggested owner, and an escalation-ready question for engineering. When the question is ambiguous, the agent asks one clarifying question instead, and you answer it as a follow-up.
Expand Down
32 changes: 30 additions & 2 deletions docs/0_QUICKSTART.md
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ and [prompt](1_EXTENSION.md#customize-the-agent).
Create a Blueprint from the fork in the Render Dashboard. [`render.yaml`](../render.yaml)
creates one project with three services:

- `codebase-researcher-api`: the HTTP API. It has no UI: its only routes are
`/healthz` and `/v1/*`, so opening its URL in a browser shows `404 Not Found`.
- `codebase-researcher-api`: the HTTP API and, when enabled, its optional
password-protected browser UI.
- `codebase-researcher-workflow`: the durable question workflow.
- `codebase-researcher-snapshots`: the hourly snapshot refresh cron.

Expand All @@ -56,6 +56,7 @@ blank `sync: false` value counts as unset.
| Service | Variable | Required when |
|---|---|---|
| API | `RENDER_API_KEY` | Always |
| API | `WEB_PASSWORD` | You want the optional browser UI |
| Workflow | `RENDER_API_KEY` | Always |
| Workflow | `RENDER_WORKSPACE_ID` | The key can access multiple workspaces |
| Workflow | `ANTHROPIC_API_KEY` | Using the default model |
Expand All @@ -80,6 +81,19 @@ deployments must set this new secret before upgrading. IDs issued by older
versions become invalid; start new questions after upgrading. See
[rotation and migration](1_EXTENSION.md#question-id-signing-and-rotation).

### Enable the browser UI

The UI is optional. Set `WEB_PASSWORD` to a strong value of at least 12
characters on `codebase-researcher-api`; the Blueprint has already generated
its separate `WEB_SESSION_SECRET`. After the service redeploys, open its public
URL and sign in with that password.

The UI supports new questions, polling, structured answers and evidence, and
follow-ups. It stores question text and signed question IDs in the browser's
local storage to provide per-browser history. It adds no database and never
receives `API_TOKEN`. Leave `WEB_PASSWORD` blank to keep the service API-only;
the root URL then returns `404 Not Found`.

### Build the first snapshot

Open `codebase-researcher-snapshots` and click **Trigger Run**, or wait for its
Expand Down Expand Up @@ -248,6 +262,20 @@ tools and citation validator without calling a model. A question containing
The local provider rebuilds `.scratch/runner/runner.mjs` for each
investigation, so runner and prompt edits apply to the next question.

To use the optional UI locally, build it and add the web credentials to
Terminal 2:

```bash
pnpm build:web
API_TOKEN=dev-token QUESTION_ID_SECRET=local-only-question-id-secret-1234567890 \
WEB_PASSWORD=local-web-password WEB_SESSION_SECRET=local-web-session-secret-1234567890 \
RENDER_LOCAL_DEV_URL=http://localhost:8121 pnpm start:api
```

Then open `http://localhost:3000`. For frontend development with hot reload,
run `pnpm dev:web` and open `http://localhost:5173`; Vite proxies `/api` to
the API on port 3000.

### Test

```bash
Expand Down
9 changes: 9 additions & 0 deletions docs/1_EXTENSION.md
Original file line number Diff line number Diff line change
Expand Up @@ -354,6 +354,15 @@ string is treated as unset.
| `RENDER_API_KEY` | None | Starts and reads workflow runs |
| `WORKFLOW_SLUG` | `codebase-researcher-workflow` | Builds the `answer_question` task slug; wired by the Blueprint |
| `RENDER_LOCAL_DEV_URL` | None | Uses a local Workflows server instead of Render |
| `WEB_PASSWORD` | None | Enables the optional browser UI; at least 12 characters |
| `WEB_SESSION_SECRET` | Generated by Blueprint | Signs seven-day HTTP-only browser sessions; at least 32 characters |
| `WEB_DIST_DIR` | `web/dist` | Built static UI directory |

The browser uses same-origin `/api/session` and `/api/questions` routes backed
by an HTTP-only signed session cookie. These routes call the same start,
follow-up, and polling implementation as `/v1/questions`; they do not expose
`API_TOKEN`. Browser history is local to `localStorage`, not retained by the
API. Removing `WEB_PASSWORD` disables both the UI and `/api/*` routes.

### Workflow service

Expand Down
9 changes: 6 additions & 3 deletions docs/2_ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,9 @@ The Blueprint in [`render.yaml`](../render.yaml) creates three services:

- **API** (`codebase-researcher-api`) accepts HTTP questions, rebuilds the
conversation for follow-ups, starts durable workflow runs, and serves their
results. It holds no state of its own and has no UI: its only routes are
`/healthz` and `/v1/*`, so `/` returns 404.
results. It holds no state of its own. When `WEB_PASSWORD` is set, it also
serves a static browser UI and same-origin session routes; otherwise `/`
and `/api/*` return 404.
- **Workflow** (`codebase-researcher-workflow`) orchestrates each question,
restores a fresh Sandbox, runs the agent inside it, validates the result,
and optionally delivers a callback.
Expand All @@ -21,7 +22,7 @@ The Blueprint in [`render.yaml`](../render.yaml) creates three services:

```mermaid
flowchart LR
caller[HTTP caller or pnpm ask] --> api[API service]
caller[HTTP caller, browser UI, or pnpm ask] --> api[API service]
api -->|start answer_question| workflow[Workflow service]
workflow --> investigate[investigate subtask]
investigate -->|restore by name| sandbox[Fresh investigation Sandbox]
Expand Down Expand Up @@ -53,6 +54,7 @@ docs/
3_TAKEAWAYS.md Reusable agent and Sandbox patterns
src/
api.ts Hono API: start, follow up, and poll questions
web.ts Optional stateless browser-session authentication
ask.ts `pnpm ask` client: post, poll, print the reply
workflow.ts Workflow task registration, retries, timeout budgets
tasks.ts Parent, investigation, and delivery task bodies
Expand Down Expand Up @@ -90,6 +92,7 @@ sandbox/
verify.sh Verify files, credentials, permissions, runner, egress
build/ Builder-only Git credential and scrub scripts
test/ API, workflow, runner, Sandbox, and runtime tests
web/ Optional React UI, built into the API service
```

`.scratch/` contains local checkouts, local run directories, and the local
Expand Down
4 changes: 3 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,10 @@
"node": ">=22.19"
},
"scripts": {
"typecheck": "tsc --noEmit",
"typecheck": "tsc --noEmit && pnpm --filter @codebase-researcher/web exec tsc --noEmit",
"test": "vitest run",
"build:web": "pnpm --filter @codebase-researcher/web build",
"dev:web": "pnpm --filter @codebase-researcher/web dev",
"ask": "tsx src/ask.ts",
"refresh": "tsx src/cron.ts",
"start:api": "tsx src/api.ts",
Expand Down
91 changes: 91 additions & 0 deletions pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 3 additions & 0 deletions pnpm-workspace.yaml
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
# pnpm 11 does not support allowBuilds in package.json; keep this settings-only file.
packages:
- web

allowBuilds:
esbuild: true
protobufjs: false
Expand Down
9 changes: 7 additions & 2 deletions render.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -17,11 +17,11 @@ projects:
# Free is enough: it spins down when idle, so the first request afterward waits for a cold start,
# but questions run in the workflow, not here. Use starter to keep it warm.
plan: free
buildCommand: pnpm install --frozen-lockfile
buildCommand: pnpm install --frozen-lockfile && pnpm build:web
startCommand: pnpm start:api
healthCheckPath: /healthz
buildFilter:
paths: [src/api.ts, src/question.ts, src/investigation.ts, src/callback.ts, src/log.ts, src/util.ts, package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .node-version, tsconfig.json]
paths: [src/api.ts, src/web.ts, src/question.ts, src/investigation.ts, src/callback.ts, src/log.ts, src/util.ts, web/**, package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .node-version, tsconfig.json]
envVars:
- key: RENDER_API_KEY
sync: false
Expand All @@ -34,6 +34,11 @@ projects:
type: workflow
name: codebase-researcher-workflow
property: slug
# Optional: setting a password enables the browser UI at the service root.
- key: WEB_PASSWORD
sync: false
- key: WEB_SESSION_SECRET
generateValue: true

- type: workflow
name: codebase-researcher-workflow
Expand Down
Loading
Loading