diff --git a/docs/LOCAL_SETUP.md b/docs/LOCAL_SETUP.md new file mode 100644 index 0000000..dc463c1 --- /dev/null +++ b/docs/LOCAL_SETUP.md @@ -0,0 +1,312 @@ +# Local Setup + +This guide runs the active Zopu stack locally, including the browser chat and the AgentOS issue-to-PR path. + +## What runs + +```text +Browser (React Router/Vite, :5173) + -> Convex Cloud (durable product state, auth, workflows) + -> Flue agent server (:3585) + -> Rivet Engine guard endpoint (:6420) + -> AgentOS registry runner + -> isolated Pi workspace mounted from the local repository + -> Gitea branch and pull request +``` + +The active stack does not use `repos/`; that directory is archived reference code. In particular, the old standalone server on port `3590` is not part of this setup. + +## Requirements + +- macOS or Linux +- Bun and Node.js matching the repository toolchain (`packages/agents` requires Node `>=22.18 <23 || >=23.6`) +- pnpm 11 +- Git with SSH access to `git.openputer.com` +- [Tea](https://gitea.com/gitea/tea) authenticated to `https://git.openputer.com` +- a Convex account with access to the development deployment +- an OpenAI-completions-compatible model endpoint and API key + +Install dependencies from the repository root: + +```bash +bun install --frozen-lockfile +``` + +Confirm Git and Tea access before testing issue or PR tools: + +```bash +git ls-remote origin HEAD +tea login list +tea issues list +``` + +The default Tea login should target `https://git.openputer.com`. Never put credentials in committed files. + +## Environment + +Create the local environment file: + +```bash +cp .env.example .env +``` + +At minimum, configure these groups. + +### Application and Convex + +```env +CONVEX_DEPLOYMENT=dev: +CONVEX_URL=https://.convex.cloud +CONVEX_SITE_URL=https://.convex.site +SITE_URL=http://localhost:5173 +VITE_AUTH_URL=http://localhost:5173 +VITE_CONVEX_URL=https://.convex.cloud +``` + +### Flue and model provider + +```env +FLUE_DB_TOKEN= +FLUE_URL=http://127.0.0.1:3585 + +AGENT_MODEL_PROVIDER= +AGENT_MODEL_NAME= +AGENT_MODEL_API=openai-completions +AGENT_MODEL_BASE_URL=https:///v1 +AGENT_MODEL_API_KEY= +AGENT_MODEL_CONTEXT_WINDOW= +AGENT_MODEL_MAX_TOKENS= +``` + +`FLUE_DB_TOKEN` must match the value stored in the Convex deployment. + +### Rivet and AgentOS + +```env +RIVET_ENDPOINT=http://127.0.0.1:6420 +RIVET_PUBLIC_ENDPOINT=http://127.0.0.1:6420 +RIVET_WORKSPACE_TOKEN= +ZOPU_SOURCE_REPOSITORY=/absolute/path/to/zopu-code +AGENT_WORKSPACE_ROOT=/absolute/path/to/zopu-agent-workspaces +``` + +Use the same repository checkout for `ZOPU_SOURCE_REPOSITORY`. The harness creates Git worktrees beneath `AGENT_WORKSPACE_ROOT`, copies the source checkout's `.env`, installs dependencies, and mounts the isolated checkout into AgentOS. + +Port `6420` is the Rivet Engine guard endpoint used by the application. Port `6421` is an internal engine API-peer port and must not be used as `RIVET_ENDPOINT`. + +### Gitea + +```env +GITEA_URL=https://git.openputer.com +GITEA_TOKEN= +``` + +`GITEA_TOKEN` is optional for read-only agent startup but required for the complete issue-to-PR flow unless Tea and Git already have sufficient local credentials. + +The legacy variables `VITE_FLUE_URL` and `VITE_ZOPU_SERVER_URL` are not used by the active web chat path. + +## One-time Convex setup + +On a new machine, authenticate and configure the Convex development deployment: + +```bash +bun run dev:setup +``` + +Then configure the deployment-scoped values from `packages/backend`: + +```bash +cd packages/backend +bunx convex env set SITE_URL 'http://localhost:5173' +bunx convex env set FLUE_DB_TOKEN '' +bunx convex env set FLUE_URL 'http://:3585' +``` + +Convex runs in the cloud, so `FLUE_URL` must be reachable from the Convex deployment. `127.0.0.1` and `localhost` point at Convex's machine, not your laptop. For the current Mac setup, expose Flue over Tailscale and use the Mac's Tailscale address, for example `http://100.x.y.z:3585`. + +`SITE_URL` is deployment-scoped and single-valued. Set it to the exact browser origin currently being tested: + +```bash +# Browser opened locally +bunx convex env set SITE_URL 'http://localhost:5173' + +# Browser opened from another device over Tailscale +bunx convex env set SITE_URL 'http://:5173' +``` + +If work execution uses a separate agent URL, set `AGENT_BACKEND_URL`; otherwise it falls back to `FLUE_URL`. + +## Start the stack + +Run each process in its own terminal. The order matters for the AgentOS path. + +### 1. Start Convex development + +```bash +bun run dev:server +``` + +This watches and publishes functions to the configured Convex cloud development deployment. + +### 2. Start Rivet Engine + +The installed RivetKit 2.3.9 package supplies the platform-specific `rivet-engine` binary. Start it with: + +```bash +./node_modules/.pnpm/@rivetkit+engine-cli-*/node_modules/@rivetkit/engine-cli-*/rivet-engine start +``` + +There must be exactly one local engine listening on `127.0.0.1:6420`. Do not start a second engine, and do not use `npx rivetkit dev`; that command is unavailable in the installed version. + +### 3. Start the AgentOS registry runner + +```bash +cd packages/agents +bun run runner +``` + +The runner registers the AgentOS workspace actor with Rivet Engine. Keep it running whenever a coding attempt or issue-to-PR request may execute. + +### 4. Start Flue agents + +For laptop-only access: + +```bash +bun run dev:agents -- --port 3585 +``` + +For Convex callbacks or access from another device, bind Flue to all interfaces: + +```bash +bun run dev:tailscale:agents -- --port 3585 +``` + +Always pass port `3585`; the Flue CLI defaults to `3583`, but the current Zopu configuration and Convex environment use `3585`. + +If the shell already exports remote Rivet values, shell values override `.env`. Start Flue with explicit local values: + +```bash +RIVET_ENDPOINT=http://127.0.0.1:6420 \ +RIVET_PUBLIC_ENDPOINT=http://127.0.0.1:6420 \ +bun run dev:tailscale:agents -- --port 3585 +``` + +### 5. Start the web application + +For laptop-only access: + +```bash +bun run dev:web +``` + +For phone or other Tailscale-device access: + +```bash +bun run dev:tailscale:web +``` + +Open `http://localhost:5173`, or `http://:5173` when using the Tailscale command. + +## Verify the setup + +Check the listeners: + +```bash +curl -I http://127.0.0.1:6420 +curl -I http://127.0.0.1:3585 +curl -I http://127.0.0.1:5173 +``` + +Any HTTP response confirms the process is reachable; these roots may redirect or return `404` because their functional routes live elsewhere. + +Then verify behavior in order: + +1. Open the web app and sign in. +2. Send a simple chat message and confirm the response streams back through Convex. +3. Ask Zopu to list open Gitea issues. +4. For the full execution path, send `Create a PR for issue #N` for an open, unassigned test issue. +5. Confirm chat immediately reports that the issue was accepted. +6. Follow the Flue server logs for `[create_pr_for_issue]` and wait for a `completed` line with the PR URL. +7. Confirm the branch and pull request in Gitea. + +The PR pipeline is asynchronous: the initial chat turn acknowledges acceptance, while AgentOS implements, commits, pushes, and opens the pull request in the background. + +## Request flow + +```text +Web sends a conversation mutation to Convex + -> Convex persists the exact message + -> Convex dispatches to FLUE_URL/agents/zopu/ + -> Flue runs the Zopu agent and its typed tools + -> responses return to Convex + -> the web observes Convex's reactive projection + +For code execution: + -> Flue calls the local AgentOS harness + -> the harness creates an isolated Git worktree + -> a Rivet actor boots an AgentOS VM and mounts the worktree + -> Pi implements the issue and produces a candidate revision + -> the host pushes a unique branch + -> Tea creates a Gitea pull request +``` + +## Common failures + +### Chat stays pending or reports that Flue is unavailable + +- Confirm Flue is listening on `3585`. +- Confirm the Convex deployment's `FLUE_URL` uses a host-reachable address, not `localhost`. +- Confirm `FLUE_DB_TOKEN` is identical in `.env` and the Convex deployment. + +### Sign-in fails or the browser reports CORS errors + +Set Convex `SITE_URL` to the exact browser origin. The shared development deployment trusts only the current single value. + +### AgentOS fails while mounting the repository + +- Confirm both Rivet endpoints use port `6420`. +- Confirm the engine and `bun run runner` are both running. +- Confirm `ZOPU_SOURCE_REPOSITORY` contains `.git`. +- Confirm `AGENT_WORKSPACE_ROOT` is writable. +- Restart the runner after changing AgentOS registry configuration; Flue hot reload is not enough. + +The harness clients require CBOR encoding for host-directory mount descriptors. Do not remove the `encoding: "cbor"` configuration in `packages/agents/src/runtime/agent-os.ts`. + +### AgentOS reports an ACP completed-message resource limit + +The workspace registry raises `limits.acp.maxCompletedMessageBytes` for long Pi coding runs. Restart the runner so the updated registry configuration is registered with Rivet Engine. + +### Flue connects to a remote Rivet deployment unexpectedly + +Environment variables exported by the shell override values loaded from `.env`. Start Flue and the runner with explicit `RIVET_ENDPOINT` and `RIVET_PUBLIC_ENDPOINT` values pointing to `127.0.0.1:6420`. + +### Gitea issue or PR commands fail + +Run: + +```bash +tea login list +git ls-remote origin HEAD +tea issues list +``` + +Confirm the default Tea login, SSH key, repository remote, and token all target `git.openputer.com`. + +## Repository checks + +After changing source or configuration: + +```bash +bunx ultracite check +bun run check-types +bun run check +``` + +For agent-only changes, run `bun run check-types` from `packages/agents` before the root check. + +See also: + +- [`TECH.md`](TECH.md) for architecture and ownership boundaries +- [`deployment.md`](deployment.md) for the shared staging deployment +- [Rivet AgentOS quickstart](https://rivet.dev/docs/agent-os/quickstart) +- [Flue local development](https://flue.dev/docs/cli/dev) diff --git a/docs/README.md b/docs/README.md index e010f24..5f90edc 100644 --- a/docs/README.md +++ b/docs/README.md @@ -16,10 +16,12 @@ Dense context set for product development and coding agents. 9. evaluation.md — quality measurement and improvement ``` +For a runnable development environment, see [`LOCAL_SETUP.md`](LOCAL_SETUP.md). + ## Use by role | Role | Minimum context | -|---|---| +| --- | --- | | Product/definition agent | agent-context, product, glossary, dev-loop | | Architecture/design agent | agent-context, tech, dev-loop, current Work Definition | | Coding agent | agent-context, current Design Packet/Slice, tech sections, repository rules |