Skip to content

AGENTS.md

Latest commit

 

History

History
50 lines (38 loc) · 10.4 KB

AGENTS.md

File metadata and controls

50 lines (38 loc) · 10.4 KB
Raw

Repository Guide

Toolchain and checks

  • Install with pnpm install --frozen-lockfile; pnpm-lock.yaml is canonical. Bun is still required because build, setup, and dashboard scripts run through it—do not substitute bun install.
  • Full verification: pnpm build && pnpm typecheck && pnpm lint && pnpm test. Build must precede tests because test/dashboard/app-bundle.test.ts rejects a stale source hash.
  • Focus a Node test with pnpm test --project node test/path.test.ts; add -t "test name" for one case. Run dashboard DOM tests with pnpm test --project dom test/dashboard/app-dom.test.ts. The dom project is the only happy-dom suite; all other tests use the node project and a bun:sqlite shim.
  • pnpm typecheck covers src/, not tests or scripts. ESLint also ignores tests and generated dashboard files.

Package surfaces

  • Server plugin src/index.ts — published as root (.) and ./server alias. TUI plugin src/tui.tsx. Installer CLI src/install/cli.ts (bin). Standalone dashboard via pnpm dashboard (scripts/dashboard.ts); not a package export.
  • src/index.ts is the server entry; the host-neutral composition root is createForgeCore in src/host/forge-core.ts, wrapped by the OpenCode 2.x adapter in src/host/v2.ts. Forge supports OpenCode 2.x only. Core boundaries: src/loop/ (runtime/state machine), src/storage/ (database and repositories), src/tools/ (OpenCode tools), src/agents/ (agent definitions).

Generated and bundled files

  • pnpm build rewrites src/version.ts, src/dashboard/marked-source.ts, and src/dashboard/app-bundle.ts. Edit package.json, src/dashboard/marked.min.js, or src/dashboard/app/ respectively, never the generated files.
  • pnpm build removes the output directory before compiling (scripts/build.ts), so deleting or renaming source modules cannot leave stale output in dist/.
  • scripts/build.ts runs tsc first, then Bun.build overwrites dist/index.js (server) and dist/tui.js (TUI) with self-contained bundles. Both must stay bundled so the plugin loads without resolving node_modules; the vendored installer mode (bunx opencode-forge --vendor) depends on it. @opentui/*, @opencode/plugin/tui, solid-js, and bun:sqlite stay external because opencode's runtime provides them. Import other @opencode/* packages type-only (the FORGE_RPC contract is a plain object checked with satisfies) so their runtime stays out of the bundles.
  • resolveShippedRoot in src/utils/shipped-paths.ts is the only way to locate shipped files on disk. Never derive paths from import.meta.url directly: bundling collapses it, which would silently break the migration SQL loader, prompt loading, and bundled-asset sync.
  • Bundled prompts (src/prompts/) and skills (skills/) sync on every plugin load, preserving user edits. The standalone installer handles conflicts and orphan pruning.
  • docs/api/ is generated by pnpm docs:api (typedoc, cleanOutputDir: true), including the docs/api/_media/ copies of docs/*.md. Edit docs/*.md and regenerate; never hand-edit or hand-copy anything under docs/api/.
  • The section-summary block template is the single SECTION_SUMMARY_TEMPLATE in src/loop/prompts.ts, built from the marker constants in src/utils/section-summary.ts; do not hand-write the marker strings into prompt markdown files or other prompt builders.

Loop runtime

  • MAX_TOTAL_SECTIONS in src/constants/loop.ts is the single section cap. Update both architect.md and architect-auto.md prose when it changes.
  • PLAN_AUTHORING_TOOL_NAMES and FORGE_MANAGED_PERMISSIONS/FORGE_REQUIRED_PERMISSIONS in src/constants/loop.ts are the single sources for tool-exclude lists, permission rulesets, and the audit ruleset. Do not re-list tool names by hand.
  • Persisted review findings are the only channel from the auditor to the coding agent. Coder prompts inline each finding in full; auditor response prose is never injected into a coder prompt, and the only part of it the runtime parses is the section-summary block. formatFindingDetails in src/utils/review-format.ts is the single finding renderer for both review-read and every coder prompt. lastAuditResult is persisted for the dashboard and loop-status display only.
  • Watchdog has exactly two progress signals (recordActivity, recordSessionContent); busy is not one of them. Content signal is fed from loop.tick first branch, must stay O(1). Busy ceiling (busyStallTimeoutMs) is measured from the newest of both across loop and subagent sessions.
  • Multiple plugin instances share one process, but OpenCode loads a separate copy of the module graph per location, so module-level state is per location. State that must be one per process (host sandbox controllers, idle-gate markers, prompt in-flight guard, loop registry, loop state locks, internal-abort markers, V2 session status cache, pending shell-sandbox markers, TUI event emitters) goes through processShared in src/utils/process-shared.ts; a plain module-level Map/Set silently splits between the host and worktree instances. Loop-scoped shared entries are keyed by projectLoopKey(projectId, loopName) because one process can host several projects. Plugin init supervises only loops in the loop registry (started or restarted in this process), never loops persisted before it. Ownership gate: ownsLoopWorktree in src/loop/runtime.ts compares directory to worktreeDir via canonicalizePath. startWatchdog and session.error handler gate on it — fail-safe, never a hang. Do not extend the gate to the idle handler. The one idle suppression is a queued session inbox item (isPromptQueued); it stays fail-safe because a cancelled inbox event that empties the queue replays the suppressed idle in the owning instance, session.deleted clears the entries, and entries older than QUEUED_PROMPT_MAX_AGE_MS expire. The ungated idle handler is safe only because each instance receives just its own location's session events. OpenCode 2.x (verified on 2.0.15) delivers every location's events to every plugin subscription, so createV2SessionOwnership in src/host/v2-events.ts drops session events whose session lives in another location before core.onEvent. Without it, a host instance and a worktree instance of the same project share the Forge DB, both match the loop, and every phase transition creates two sessions. A failed session lookup delivers the event (fail-safe, never a hang).
  • Busy/idle/retry come only from session.execution.* and session.retry.scheduled, mapped in normalizeV2Event (src/host/v2-events.ts). OpenCode 2.x never publishes session.status/session.idle; never map them as well, or a release that emits both would double-rotate phases.
  • LoopService.resolveActiveLoopForSession is the only correct "is this session inside a running loop" check. resolveLoopName matches terminated loops too.

Sandbox

  • src/sandbox/msb.ts is the sole TypeScript runtime/lifecycle facade and msb CLI argument owner; route runtime operations through its SandboxRuntime facade. The one required exception is the generated shell shim (src/sandbox/shell-shim.ts), which invokes msb exec directly when an agent shell command must run inside a sandbox. src/sandbox/process.ts is the only child-process spawner; all TypeScript shell execution goes through runCommand.
  • OpenCode's shell.hook('create.before') carries no session identity. Loop sandboxes route there by working directory; host session sandboxes route through the shell tool wrapper in src/host/v2-hooks.ts, which prefixes the command with a one-off forge-sandbox-required-<uuid> && marker that the shell hook strips. An unstripped marker must fail the command ("command not found"), never run it on the host. Commands the user runs directly (!, terminals) do not pass through the wrapper and stay on the host.
  • buildSandboxWorkspaces canonicalizes the host side of every mount and leaves containerDir as the original path. msb refuses a host path that traverses a symlink and fails the whole sandbox with ENOTDIR, which on macOS breaks every os.tmpdir() mount because /var is a symlink to private/var. Never canonicalize the container side: absolute paths handed to the agent must resolve identically inside the sandbox.
  • Every named disk buildMsbCreateArgs mounts must also be removed by removeSandbox (named volumes survive msb rm); a test pins the two sets equal, so a new disk needs both sides. /opt/forge/cache is the cache disk: the create-time prepareCacheDisk chown+chmod is memoized per container and re-applied on adoption, and must never become a per-tool-call exec. The cache path must stay free of .: msb derives a named disk's id from its guest mount path and rejects ids that are not [A-Za-z0-9_-] (msb >= 0.7.0), failing sandbox start with managed additional disk has an invalid or reserved device id.
  • getSandboxState is the only liveness primitive; five states: running, stopped (reusable, never create/evict), transient (real but not directly executable: Created/Starting/Draining/Paused map here), unknown (query failed), missing (may create or evict). Stopped/Crashed map to the reusable stopped state because msb exec starts them in place. registerActiveSandbox is the only place a usable sandbox is recorded.
  • container/Dockerfile must derive from a plain OCI base and keep the final USER agent; ENTRYPOINT/CMD are ignored because msb runs agentd as PID 1.

Dashboard, storage, and paths

  • Dashboard uses solid-js/html, not JSX. No <${Show}> or <${For}>; use reactive thunks/memos and .map(). Root component returns one wrapper element. test/dashboard/app-dom.test.ts enforces these constraints.
  • src/dashboard/render.ts owns the stylesheet; test/dashboard/render.test.ts enforces CSS token usage, sticky stack --z-subnav < --z-app-bar < --z-popover, app-bar height variables at relevant breakpoints, and matching loop-table data-col attributes.
  • Storage migrations are registered explicitly, in execution order, in the lowercase migrations array in src/storage/migrations/index.ts; they are not discovered from filenames.
  • resolveDashboardConfig in src/dashboard/config.ts is the only dashboard bind host/port resolver. Every launch surface must pass overrides into startDashboardServer and render warnings. Dashboard has no auth; DASHBOARD_EXPOSED_WARNING is the single warning.
  • resolveForgeDbPath in src/utils/opencode-paths.ts is the only place <dataDir>/forge.db is built.