diff --git a/.env.example b/.env.example index 2d1643f..0ee282f 100644 --- a/.env.example +++ b/.env.example @@ -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 diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 425bb9c..5b4edde 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -21,4 +21,5 @@ jobs: cache: pnpm - run: pnpm install --frozen-lockfile - run: pnpm typecheck + - run: pnpm build:web - run: pnpm test diff --git a/README.md b/README.md index 822dabf..f597947 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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. diff --git a/docs/0_QUICKSTART.md b/docs/0_QUICKSTART.md index 2d0dcf3..4c08e80 100644 --- a/docs/0_QUICKSTART.md +++ b/docs/0_QUICKSTART.md @@ -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. @@ -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 | @@ -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 @@ -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 diff --git a/docs/1_EXTENSION.md b/docs/1_EXTENSION.md index 7b692c7..6378b0a 100644 --- a/docs/1_EXTENSION.md +++ b/docs/1_EXTENSION.md @@ -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 diff --git a/docs/2_ARCHITECTURE.md b/docs/2_ARCHITECTURE.md index 33eb8e6..8c85e8b 100644 --- a/docs/2_ARCHITECTURE.md +++ b/docs/2_ARCHITECTURE.md @@ -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. @@ -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] @@ -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 @@ -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 diff --git a/package.json b/package.json index c2a8117..eddb4f9 100644 --- a/package.json +++ b/package.json @@ -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", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index be352ef..356b261 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -52,6 +52,31 @@ importers: specifier: ^2.9.1 version: 2.9.1 + web: + dependencies: + react: + specifier: ^19.3.0 + version: 19.3.1 + react-dom: + specifier: ^19.3.0 + version: 19.3.1(react@19.3.1) + devDependencies: + '@types/react': + specifier: ^19.3.0 + version: 19.3.0 + '@types/react-dom': + specifier: ^19.3.0 + version: 19.3.0(@types/react@19.3.0) + '@vitejs/plugin-react': + specifier: ^6.1.1 + version: 6.3.0(vite@8.3.3(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1)) + typescript: + specifier: ^5.9.3 + version: 5.9.3 + vite: + specifier: ^8.3.1 + version: 8.3.3(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1) + packages: '@anthropic-ai/sdk@0.91.1': @@ -546,6 +571,9 @@ packages: '@smithy/core@3.35.1': resolution: {integrity: sha512-i4YPS4B6ts7bjn7UwLnGjiZdprOvHvgGobFZsYK3GIY3E5hIqtj0rReU69BcTpGp+fvtraSNXeG1l+jtJvF55w==} engines: {node: '>=18.0.0'} + deprecated: |- + Deprecated due to a bug in custom logger data redaction. Upgrade to the latest version. If you used a custom logger with this + version, review your logs and rotate any credentials or other secrets. See https://github.com/aws/aws-sdk-js-v3/issues/8393. '@smithy/credential-provider-imds@4.5.2': resolution: {integrity: sha512-A9uSdn72ozbRUSit0eib0TW7nXuNPlaeM0zcGkJ+nE6tFcSDbnmtwoxbTCFBukVQcszDAyvsd7+rTduPTXpygg==} @@ -595,9 +623,33 @@ packages: '@types/node@24.19.1': resolution: {integrity: sha512-aS3/DG0oM05K0RIXXP+hKjinGG5IgSSVGzswZxW3O0sS3pH4/fycXundUC9XsszgKCk4gHXylTEK6hyFxVxnoQ==} + '@types/react-dom@19.3.0': + resolution: {integrity: sha512-ZI7bU42mZXXKHn/qNLEw2IrbiINU7X5+vfgdixBHkCNpYWXjKgfQ/P+uyGb5CjOLB9UcnTeg3rylQtV2hym44Q==} + peerDependencies: + '@types/react': ^19.3.0 + + '@types/react@19.3.0': + resolution: {integrity: sha512-N0rFCuH9YoxG9/m61l9MfpJKfmLOVU0em7ipIz6TRgSSkvReLB9vL85GB+yr8Bs5leqpvg96JSwF4ZS1s4viQg==} + '@types/retry@0.12.0': resolution: {integrity: sha512-wWKOClTTiizcZhXnPY4wikVAwmdYHp8q6DmC+EJUzAMsycb7HB32Kh9RN4+0gExjmPmZSAQjgURXIGATPegAvA==} + '@vitejs/plugin-react@6.3.0': + resolution: {integrity: sha512-H9E955aVvD2F4zNHCw4eIZbIfF6xKldlh7MNu+hSU7xwQzh65lI/N+CJWqmfhi0PEjDXIt/H7T7J/4wU63KJiw==} + engines: {node: ^20.19.0 || >=22.12.0} + peerDependencies: + '@rolldown/plugin-babel': ^0.1.7 || ^0.2.0 || ^0.3.0 + babel-plugin-react-compiler: ^1.0.0 + oxc-transform-react: '>=0.152.0 <0.157.0' + vite: ^8.0.0 + peerDependenciesMeta: + '@rolldown/plugin-babel': + optional: true + babel-plugin-react-compiler: + optional: true + oxc-transform-react: + optional: true + '@vitest/mocker@5.0.3': resolution: {integrity: sha512-T8sWAIbkSyAjkwTcaEc3Iu0o9A27X1/kdXrizhZkGuSKScRQtRzclfAMpOTcGdXCsqxeWlpGy3XjqaW8CpLORg==} peerDependencies: @@ -644,6 +696,9 @@ packages: resolution: {integrity: sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==} engines: {node: '>=0.10.0'} + csstype@3.2.3: + resolution: {integrity: sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==} + data-uri-to-buffer@4.0.1: resolution: {integrity: sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==} engines: {node: '>= 12'} @@ -914,6 +969,15 @@ packages: resolution: {integrity: sha512-dYDWdjSl5RNb7SgPxGQcRU+GtvP7s2fpkrY0r432PcOIaZ0/rBcxEZnQN67iJhFuQiVw754JDoPruPCNdGsbjg==} engines: {node: '>=12.0.0'} + react-dom@19.3.1: + resolution: {integrity: sha512-Y0bARz53lhEC1NMCASs0/j+faB/zqt3R8hpvg1e8+61ZVJ4UL0UdC4cBbXfZMcIuhrfgeILTLe+ZeBCavQPtKQ==} + peerDependencies: + react: ^19.3.1 + + react@19.3.1: + resolution: {integrity: sha512-QNhWdt7nrgVWWQG58QuGsAR3jv3Hbe4mb4vz7w2csnHavciZJgda1CPNaldF6eVxv90ud3jUXpKlHL69gO38yw==} + engines: {node: '>=0.10.0'} + redis@5.12.1: resolution: {integrity: sha512-LDsoVvb/CpoV9EN3FXvgvSHNJWuCIzl9MiO3ppOevuGLpSGJhwfQjpEwfFJcQvNSddHADDdZaWx0HnmMxRXG7g==} engines: {node: '>= 18.19.0'} @@ -930,6 +994,9 @@ packages: safe-buffer@5.2.1: resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==} + scheduler@0.28.0: + resolution: {integrity: sha512-juorfCmIkIw8tT+p5BXSm6PJjQF/ycEYmKyzURCIt/RaZIhL+PulbQ9Yu2z1HdOJDdqDTlxA1+xKBmHXJsczAw==} + source-map-js@1.2.2: resolution: {integrity: sha512-KGj/8Y43x35aZVDtt+J4mK1hoLGHULMYfSkODJNQjNDC3oW1PqPoxMwo0pLUsWM/UEGzON/NxeHywEfNXNP3Vw==} engines: {node: '>=0.10.0'} @@ -1650,8 +1717,21 @@ snapshots: dependencies: undici-types: 7.24.6 + '@types/react-dom@19.3.0(@types/react@19.3.0)': + dependencies: + '@types/react': 19.3.0 + + '@types/react@19.3.0': + dependencies: + csstype: 3.2.3 + '@types/retry@0.12.0': {} + '@vitejs/plugin-react@6.3.0(vite@8.3.3(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))': + dependencies: + '@rolldown/pluginutils': 1.0.1 + vite: 8.3.3(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1) + '@vitest/mocker@5.0.3(vite@8.3.3(@types/node@24.19.1)(esbuild@0.28.2)(jiti@2.7.0)(tsx@4.23.15)(yaml@2.9.1))': dependencies: '@jridgewell/trace-mapping': 0.3.31 @@ -1681,6 +1761,8 @@ snapshots: cluster-key-slot@1.1.2: {} + csstype@3.2.3: {} + data-uri-to-buffer@4.0.1: {} debug@4.4.3: @@ -1943,6 +2025,13 @@ snapshots: '@types/node': 24.19.1 long: 5.3.2 + react-dom@19.3.1(react@19.3.1): + dependencies: + react: 19.3.1 + scheduler: 0.28.0 + + react@19.3.1: {} + redis@5.12.1(@opentelemetry/api@1.9.0): dependencies: '@redis/bloom': 5.12.1(@redis/client@5.12.1(@opentelemetry/api@1.9.0)) @@ -1979,6 +2068,8 @@ snapshots: safe-buffer@5.2.1: {} + scheduler@0.28.0: {} + source-map-js@1.2.2: {} std-env@4.3.0: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 5cd447a..9cf3b31 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -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 diff --git a/render.yaml b/render.yaml index a85d1bb..ba4c902 100644 --- a/render.yaml +++ b/render.yaml @@ -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 @@ -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 diff --git a/src/api.ts b/src/api.ts index dd361f9..6d10063 100644 --- a/src/api.ts +++ b/src/api.ts @@ -4,15 +4,16 @@ import { present } from "./util.ts"; import { safeEqual } from "./callback.ts"; import { createLog, type Log } from "./log.ts"; import { serve } from "@hono/node-server"; -import { Hono } from "hono"; +import { serveStatic } from "@hono/node-server/serve-static"; +import { Hono, type Context } from "hono"; import { bearerAuth } from "hono/bearer-auth"; import { HTTPException } from "hono/http-exception"; -import { validator } from "hono/validator"; import { ClientError, Render } from "@renderinc/sdk"; import { z } from "zod"; import { createHmac } from "node:crypto"; import { realpathSync } from "node:fs"; import { pathToFileURL } from "node:url"; +import { createWebSession, type WebConfig } from "./web.ts"; export type TaskRun = { status: string; input?: unknown; results: unknown[]; error?: string }; export type GetTaskRun = (id: string) => Promise; @@ -24,6 +25,7 @@ export type AppDeps = { getTaskRun: GetTaskRun; isLocalDev: boolean; log: Log; + web?: WebConfig; }; /** @@ -104,32 +106,29 @@ export function createApp(deps: AppDeps) { app.get("/healthz", (c) => c.text("ok")); - app.use("/v1/*", bearerAuth({ token: deps.apiToken })); - - app.post( - "/v1/questions", - validator("json", (value, c) => { - const parsed = PostBody.safeParse(value); - return parsed.success ? parsed.data : c.json({ error: z.prettifyError(parsed.error) }, 400); - }), - async (c) => { - const { question, follow_up_to, callback, metadata } = c.req.valid("json"); - const earlier = follow_up_to ? await conversationSoFar(follow_up_to) : []; - const transcript: Transcript = [...earlier, { role: "user", text: question }]; - if (transcript.length > TRANSCRIPT_MAX_MESSAGES) { - throw httpError(400, `a conversation holds at most ${TRANSCRIPT_MAX_MESSAGES} messages; ask a new question instead`); - } - const run = await deps.startQuestion({ transcript, callback, metadata }, { - idempotencyKey: c.req.header("idempotency-key"), - signal: AbortSignal.timeout(5000), - }); - deps.log.info("task started", { event: "task_started", run_id: run.id, follow_up: !!follow_up_to }); - return c.json({ id: toQuestionId(deps.questionIdSecret, run.id) }, 202); - }, - ); + const startRequest = async (c: Context) => { + if (!c.req.header("content-type")?.toLowerCase().startsWith("application/json")) { + return c.json({ error: "send JSON with Content-Type: application/json" }, 415); + } + const parsed = PostBody.safeParse(await c.req.json().catch(() => null)); + if (!parsed.success) return c.json({ error: z.prettifyError(parsed.error) }, 400); + const { question, follow_up_to, callback, metadata } = parsed.data; + const earlier = follow_up_to ? await conversationSoFar(follow_up_to) : []; + const transcript: Transcript = [...earlier, { role: "user", text: question }]; + if (transcript.length > TRANSCRIPT_MAX_MESSAGES) { + throw httpError(400, `a conversation holds at most ${TRANSCRIPT_MAX_MESSAGES} messages; ask a new question instead`); + } + const run = await deps.startQuestion({ transcript, callback, metadata }, { + idempotencyKey: c.req.header("idempotency-key"), + signal: AbortSignal.timeout(5000), + }); + deps.log.info("task started", { event: "task_started", run_id: run.id, follow_up: !!follow_up_to }); + return c.json({ id: toQuestionId(deps.questionIdSecret, run.id) }, 202); + }; - app.get("/v1/questions/:id", async (c) => { + const pollRequest = async (c: Context) => { const id = c.req.param("id"); + if (!id) throw httpError(404, "not found"); const run = await readRun(id); const status = run.status; if (status === "pending" || status === "running" || status === "paused") { @@ -142,7 +141,26 @@ export function createApp(deps: AppDeps) { // readRun verified the signed ID before its public run-ID prefix is used for correlation. const traceId = id.slice(0, id.lastIndexOf(".")); return c.json({ id, status: "failed", error: "The investigation could not be completed.", trace_id: traceId }); - }); + }; + + app.use("/v1/*", bearerAuth({ token: deps.apiToken })); + app.post("/v1/questions", startRequest); + app.get("/v1/questions/:id", pollRequest); + + if (deps.web) { + const session = createWebSession(deps.web); + app.get("/api/session", session.status); + app.post("/api/session", session.login); + app.delete("/api/session", session.logout); + app.use("/api/*", session.require); + app.post("/api/questions", startRequest); + app.get("/api/questions/:id", pollRequest); + app.all("/api/*", (c) => c.json({ error: "not found" }, 404)); + app.all("/v1/*", (c) => c.json({ error: "not found" }, 404)); + + app.use("*", serveStatic({ root: deps.web.distDir })); + app.get("*", serveStatic({ root: deps.web.distDir, path: "index.html" })); + } return app; } @@ -155,6 +173,9 @@ const Env = z RENDER_API_KEY: z.string().min(1).optional(), RENDER_LOCAL_DEV_URL: z.string().min(1).optional(), WORKFLOW_SLUG: z.string().min(1).default("codebase-researcher-workflow"), + WEB_PASSWORD: z.string().min(12, "WEB_PASSWORD must be at least 12 characters").max(256).optional(), + WEB_SESSION_SECRET: z.string().min(32, "WEB_SESSION_SECRET must be at least 32 characters").optional(), + WEB_DIST_DIR: z.string().min(1).default("web/dist"), }) .refine((e) => e.QUESTION_ID_SECRET !== e.API_TOKEN, { message: "QUESTION_ID_SECRET must differ from API_TOKEN", @@ -163,6 +184,10 @@ const Env = z .refine((e) => e.RENDER_LOCAL_DEV_URL || e.RENDER_API_KEY, { message: "RENDER_API_KEY is required unless RENDER_LOCAL_DEV_URL is set", }) + .refine((e) => !e.WEB_PASSWORD || e.WEB_SESSION_SECRET, { + message: "WEB_SESSION_SECRET is required when WEB_PASSWORD enables the web UI", + path: ["WEB_SESSION_SECRET"], + }) .transform((e) => ({ port: e.PORT, apiToken: e.API_TOKEN, @@ -170,6 +195,9 @@ const Env = z renderApiKey: e.RENDER_API_KEY, localDevUrl: e.RENDER_LOCAL_DEV_URL, taskSlug: `${e.WORKFLOW_SLUG}/answer_question`, + web: e.WEB_PASSWORD && e.WEB_SESSION_SECRET + ? { password: e.WEB_PASSWORD, sessionSecret: e.WEB_SESSION_SECRET, distDir: e.WEB_DIST_DIR } + : undefined, })); export type ApiConfig = z.output; @@ -206,6 +234,7 @@ if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.ar getTaskRun, isLocalDev: !!env.localDevUrl, log, + web: env.web, }); const server = serve({ fetch: app.fetch, port: env.port, hostname: "0.0.0.0" }, (info) => { diff --git a/src/web.ts b/src/web.ts new file mode 100644 index 0000000..77d4d9f --- /dev/null +++ b/src/web.ts @@ -0,0 +1,143 @@ +import { createHash, createHmac } from "node:crypto"; +import type { Context, MiddlewareHandler } from "hono"; +import { deleteCookie, getCookie, setCookie } from "hono/cookie"; +import { z } from "zod"; +import { safeEqual } from "./callback.ts"; + +export type WebConfig = { + password: string; + sessionSecret: string; + distDir: string; +}; + +const SESSION_COOKIE = "researcher_session"; +const SESSION_TTL_MS = 7 * 24 * 60 * 60_000; +const CLOCK_SKEW_MS = 60_000; +const TOKEN = /^v1\.(\d{1,15})\.(\d{1,15})\.([\w-]{43})$/; +const Login = z.object({ password: z.string().min(1).max(256) }); + +const sha256 = (value: string) => createHash("sha256").update(value).digest("hex"); + +/** Hash first so different password lengths still take the constant-time comparison path. */ +export const passwordMatches = (presented: string, expected: string) => + safeEqual(sha256(presented), sha256(expected)); + +/** Changing either web secret invalidates every browser session. */ +export const sessionKey = (config: Pick): Buffer => + createHmac("sha256", config.sessionSecret).update(`researcher-session:${config.password}`).digest(); + +const sign = (key: Buffer, body: string) => createHmac("sha256", key).update(body).digest("base64url"); + +export function issueSession(key: Buffer, nowMs = Date.now()): string { + const body = `v1.${nowMs}.${nowMs + SESSION_TTL_MS}`; + return `${body}.${sign(key, body)}`; +} + +export function verifySession(key: Buffer, token: string | undefined, nowMs = Date.now()): boolean { + const match = token ? TOKEN.exec(token) : null; + if (!match) return false; + const [, issuedAt = "", expiresAt = "", signature = ""] = match; + if (!safeEqual(sign(key, `v1.${issuedAt}.${expiresAt}`), signature)) return false; + return ( + Number(issuedAt) <= nowMs + CLOCK_SKEW_MS && + nowMs < Number(expiresAt) && + Number(expiresAt) - Number(issuedAt) <= SESSION_TTL_MS + ); +} + +const isHttps = (c: Context) => + (c.req.header("x-forwarded-proto")?.split(",")[0]?.trim() ?? + new URL(c.req.url).protocol.slice(0, -1)) === "https"; + +const cookieOptions = (c: Context) => ({ + httpOnly: true, + sameSite: "Lax" as const, + path: "/", + secure: isHttps(c), +}); + +class LoginThrottle { + readonly #failures = new Map(); + + retryAfterMs(key: string, nowMs = Date.now()): number { + const recent = this.#recent(key, nowMs); + return recent.length >= 10 ? recent[0]! + 60_000 - nowMs : 0; + } + + fail(key: string, nowMs = Date.now()): void { + if (this.#failures.size >= 10_000 && !this.#failures.has(key)) { + for (const existing of this.#failures.keys()) { + if (!this.#recent(existing, nowMs).length) this.#failures.delete(existing); + } + if (this.#failures.size >= 10_000) { + const oldest = this.#failures.keys().next().value; + if (oldest) this.#failures.delete(oldest); + } + } + this.#failures.set(key, [...this.#recent(key, nowMs), nowMs]); + } + + reset(key: string): void { + this.#failures.delete(key); + } + + #recent(key: string, nowMs: number): number[] { + return (this.#failures.get(key) ?? []).filter((time) => nowMs - time < 60_000); + } +} + +const clientKey = (c: Context) => + c.req.header("x-forwarded-for")?.split(",").map((part) => part.trim()).filter(Boolean).at(-1) ?? + "unknown"; + +const apiError = (c: Context, status: 400 | 401 | 415 | 429, error: string, message: string) => + c.json({ error, message }, status); + +/** + * Stateless browser authentication for the optional UI. The bearer-token API remains separate and + * unchanged; browser code never receives API_TOKEN. + */ +export function createWebSession(config: WebConfig) { + const key = sessionKey(config); + const throttle = new LoginThrottle(); + + return { + status: (c: Context) => + c.json({ authenticated: verifySession(key, getCookie(c, SESSION_COOKIE)) }), + + login: async (c: Context) => { + if (!c.req.header("content-type")?.toLowerCase().startsWith("application/json")) { + return apiError(c, 415, "unsupported_media_type", "Send JSON with Content-Type: application/json"); + } + const client = clientKey(c); + const retryAfterMs = throttle.retryAfterMs(client); + if (retryAfterMs > 0) { + c.header("retry-after", String(Math.ceil(retryAfterMs / 1000))); + return apiError(c, 429, "too_many_attempts", "Too many attempts; try again in a minute"); + } + const body = Login.safeParse(await c.req.json().catch(() => null)); + if (!body.success || !passwordMatches(body.data.password, config.password)) { + throttle.fail(client); + return apiError(c, 401, "wrong_password", "Wrong password"); + } + throttle.reset(client); + setCookie(c, SESSION_COOKIE, issueSession(key), { + ...cookieOptions(c), + maxAge: SESSION_TTL_MS / 1000, + }); + return c.body(null, 204); + }, + + logout: (c: Context) => { + deleteCookie(c, SESSION_COOKIE, cookieOptions(c)); + return c.body(null, 204); + }, + + require: (async (c, next) => { + if (!verifySession(key, getCookie(c, SESSION_COOKIE))) { + return apiError(c, 401, "unauthorized", "Sign in first"); + } + await next(); + }) satisfies MiddlewareHandler, + }; +} diff --git a/test/api.test.ts b/test/api.test.ts index 9fa00a0..202ff84 100644 --- a/test/api.test.ts +++ b/test/api.test.ts @@ -1,5 +1,8 @@ import { describe, expect, it } from "vitest"; import { createHmac } from "node:crypto"; +import { mkdtemp, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; import { ClientError } from "@renderinc/sdk"; import { createApp, loadEnv, toQuestionId, type AppDeps, type GetTaskRun } from "../src/api.ts"; import { signCallback, verifyCallback } from "../src/callback.ts"; @@ -267,6 +270,81 @@ describe("HTTP API", () => { }); }); +describe("optional web UI", () => { + const web = { + password: "test-web-password", + sessionSecret: "test-web-session-secret-1234567890", + distDir: "unused", + }; + + it("is absent unless configured", async () => { + const { app } = harness(); + expect((await app.request("/api/session")).status).toBe(404); + expect((await app.request("/")).status).toBe(404); + }); + + it("authenticates with an HTTP-only session without exposing the bearer token", async () => { + const { app, started } = harness({ web }); + expect(await (await app.request("/api/session")).json()).toEqual({ authenticated: false }); + expect((await app.request("/api/questions", { + method: "POST", + headers: { "content-type": "application/json" }, + body: JSON.stringify({ question }), + })).status).toBe(401); + + const wrong = await app.request("/api/session", { + method: "POST", + headers: { "content-type": "application/json", "x-forwarded-for": "192.0.2.1" }, + body: JSON.stringify({ password: "not-the-password" }), + }); + expect(wrong.status).toBe(401); + + const login = await app.request("/api/session", { + method: "POST", + headers: { "content-type": "application/json", "x-forwarded-proto": "https" }, + body: JSON.stringify({ password: web.password }), + }); + expect(login.status).toBe(204); + const setCookie = login.headers.get("set-cookie") ?? ""; + expect(setCookie).toContain("researcher_session="); + expect(setCookie).toContain("HttpOnly"); + expect(setCookie).toContain("Secure"); + expect(setCookie).not.toContain(TOKEN); + const cookie = setCookie.split(";", 1)[0]!; + + expect(await (await app.request("/api/session", { headers: { cookie } })).json()).toEqual({ authenticated: true }); + const start = await app.request("/api/questions", { + method: "POST", + headers: { cookie, "content-type": "application/json" }, + body: JSON.stringify({ question }), + }); + expect(start.status).toBe(202); + expect(started).toHaveLength(1); + const unknownWeb = await app.request("/api/not-a-route", { headers: { cookie } }); + expect(unknownWeb.status).toBe(404); + expect(unknownWeb.headers.get("content-type")).toContain("application/json"); + const unknownApi = await app.request("/v1/not-a-route", { headers: AUTH }); + expect(unknownApi.status).toBe(404); + expect(unknownApi.headers.get("content-type")).toContain("application/json"); + }); + + it("serves the single-page app only when the UI is enabled", async () => { + const distDir = await mkdtemp(join(tmpdir(), "researcher-web-")); + try { + await writeFile(join(distDir, "index.html"), "
Researcher UI
"); + const { app } = harness({ web: { ...web, distDir } }); + const root = await app.request("/"); + expect(root.status).toBe(200); + expect(await root.text()).toContain("Researcher UI"); + const route = await app.request("/questions/local-id"); + expect(route.status).toBe(200); + expect(await route.text()).toContain("Researcher UI"); + } finally { + await rm(distDir, { recursive: true, force: true }); + } + }); +}); + describe("signCallback / verifyCallback", () => { it("accepts its own signature and rejects tampered, foreign, stale, or missing ones", () => { const secret = "test-callback-secret-1234567890"; @@ -309,4 +387,21 @@ describe("loadEnv", () => { expect(loadEnv({ QUESTION_ID_SECRET, API_TOKEN: "tok", RENDER_API_KEY: "rk" }).taskSlug).toBe("codebase-researcher-workflow/answer_question"); expect(loadEnv({ QUESTION_ID_SECRET, API_TOKEN: "tok", RENDER_API_KEY: "rk", WORKFLOW_SLUG: "my-wf" }).taskSlug).toBe("my-wf/answer_question"); }); + + it("enables the web UI only with a password and server-side session secret", () => { + const base = { QUESTION_ID_SECRET, API_TOKEN: "tok", RENDER_API_KEY: "rk" }; + expect(loadEnv(base).web).toBeUndefined(); + expect(() => loadEnv({ ...base, WEB_PASSWORD: "a-secure-password" })).toThrow(/WEB_SESSION_SECRET/); + expect(loadEnv({ ...base, WEB_SESSION_SECRET: "s".repeat(32) }).web).toBeUndefined(); + expect(loadEnv({ + ...base, + WEB_PASSWORD: "a-secure-password", + WEB_SESSION_SECRET: "s".repeat(32), + WEB_DIST_DIR: "/tmp/researcher-ui", + }).web).toEqual({ + password: "a-secure-password", + sessionSecret: "s".repeat(32), + distDir: "/tmp/researcher-ui", + }); + }); }); diff --git a/web/index.html b/web/index.html new file mode 100644 index 0000000..a716cb9 --- /dev/null +++ b/web/index.html @@ -0,0 +1,13 @@ + + + + + + + Codebase Researcher + + +
+ + + diff --git a/web/package.json b/web/package.json new file mode 100644 index 0000000..b0470bc --- /dev/null +++ b/web/package.json @@ -0,0 +1,21 @@ +{ + "name": "@codebase-researcher/web", + "private": true, + "version": "0.0.0", + "type": "module", + "scripts": { + "dev": "vite", + "build": "tsc --noEmit && vite build" + }, + "dependencies": { + "react": "^19.3.0", + "react-dom": "^19.3.0" + }, + "devDependencies": { + "@types/react": "^19.3.0", + "@types/react-dom": "^19.3.0", + "@vitejs/plugin-react": "^6.1.1", + "typescript": "^5.9.3", + "vite": "^8.3.1" + } +} diff --git a/web/src/App.tsx b/web/src/App.tsx new file mode 100644 index 0000000..b5a3474 --- /dev/null +++ b/web/src/App.tsx @@ -0,0 +1,491 @@ +import { useCallback, useEffect, useMemo, useState, type FormEvent, type ReactNode } from "react"; +import * as api from "./api.ts"; +import { addQuestion, clearQuestions, loadQuestions, questionChain } from "./storage.ts"; +import type { Confidence, FinalAnswer, Poll, Reply, StoredQuestion } from "./types.ts"; + +const POLL_MS = 3_000; + +const shortId = (id: string) => id.split(".", 1)[0]?.slice(-12) ?? id.slice(0, 12); +const titleFor = (text: string) => text.split(/\r?\n/, 1)[0]?.trim() || "Untitled question"; + +function Login({ onAuthenticated }: { onAuthenticated: () => void }) { + const [password, setPassword] = useState(""); + const [submitting, setSubmitting] = useState(false); + const [error, setError] = useState(""); + + const submit = async (event: FormEvent) => { + event.preventDefault(); + if (!password || submitting) return; + setSubmitting(true); + setError(""); + try { + await api.login(password); + onAuthenticated(); + } catch (err) { + setError(err instanceof Error ? err.message : "Sign in failed"); + setSubmitting(false); + } + }; + + return ( +
+
+
Render
+

Codebase Researcher

+

Evidence-backed answers from the exact code your agent read.

+ + setPassword(event.target.value)} + autoFocus + /> + {error &&

{error}

} + +
+
+ ); +} + +function ConfidenceBadge({ confidence }: { confidence: Confidence }) { + const bars = confidence === "high" ? 3 : confidence === "medium" ? 2 : 1; + return ( + + + ); +} + +function ListSection({ + title, + items, + marker, +}: { + title: string; + items: string[]; + marker: "observed" | "inferred" | "unknown"; +}) { + return ( +
+ + {title} + {items.length} + + {items.length ? ( +
    + {items.map((item, index) =>
  • {item}
  • )} +
+ ) :

None

} +
+ ); +} + +function AnswerCard({ answer, traceId }: { answer: FinalAnswer; traceId: string }) { + const copyEscalation = () => { + void navigator.clipboard?.writeText( + `${answer.escalation_question}\n\nContext: ${answer.answer}\nTrace: ${traceId}`, + ); + }; + + return ( +
+
+
+

Short answer

+

{answer.answer}

+
+ +
+ + + +
+ + Evidence + {answer.evidence.length} + + {answer.evidence.length ? ( +
    + {answer.evidence.map((evidence, index) => { + const label = ( + <> + {evidence.repository}{" "} + {evidence.path}:{evidence.start_line}–{evidence.end_line}{" "} + @ {evidence.commit.slice(0, 12)} + + ); + return ( +
  • + {evidence.url + ? {label} + : label} +
  • + ); + })} +
+ ) :

None

} +
+
+

Suggested engineering owner

+

{answer.suggested_owner}

+
+
+
+

Escalation-ready question

+ +
+

{answer.escalation_question}

+
+
Trace {traceId}
+
+ ); +} + +function ReplyCard({ reply }: { reply: Reply }) { + switch (reply.kind) { + case "answer": + return ; + case "clarification": + return ( +
+
Needs your reply
+

{reply.result.question}

+

Why this is needed

+

{reply.result.why_needed}

+
Trace {reply.traceId}
+
+ ); + case "failure": + return ( +
+
Investigation failed
+

{reply.reason}

+
Trace {reply.traceId}
+
+ ); + } +} + +function PollCard({ poll }: { poll?: Poll }) { + if (!poll || poll.status === "running") { + return ( +
+ +
+

Investigating

+

The researcher is reading code and validating its citations. This usually takes one to two minutes.

+
+
+ ); + } + if (poll.status === "failed") { + return ( +
+
Investigation failed
+

{poll.error}

+ {poll.trace_id &&
Trace {poll.trace_id}
} +
+ ); + } + if (poll.reply) return ; + return ( +
+
No reply recorded
+

The workflow completed without a result.

+
+ ); +} + +function Composer({ + followUp, + disabled, + onSubmit, +}: { + followUp: boolean; + disabled: boolean; + onSubmit: (text: string) => Promise; +}) { + const [text, setText] = useState(""); + const [submitting, setSubmitting] = useState(false); + const [error, setError] = useState(""); + + const submit = async (event: FormEvent) => { + event.preventDefault(); + const question = text.trim(); + if (!question || disabled || submitting) return; + setSubmitting(true); + setError(""); + try { + await onSubmit(question); + setText(""); + } catch (err) { + setError(err instanceof Error ? err.message : "Couldn’t start the investigation"); + } finally { + setSubmitting(false); + } + }; + + return ( +
+ +