Repository Guidelines

Project Structure

This is an experimental TJWater Agent service. Runtime TypeScript lives in src/; opencode agent assets live in .opencode/; tests live in tests/. The project intentionally has no cli/ directory and no user-auth middleware.

Key boundaries:

src/context/ owns local request context.
src/uiEnvelope/ owns the agent-ui@1 protocol, registry, and tool mapping.
src/routes/ owns HTTP/SSE wiring.
src/results/, src/sessions/, src/memory/, and src/learning/ keep their existing persistence responsibilities.

Generated data/, logs/, and dependency folders must not be committed.

Commands

Use Bun:

bun install
bun run dev
bun run check
bun test tests/**/*.test.ts

bun run dev starts src/server.ts in watch mode. bun run check runs TypeScript checks for the main project and .opencode.

Coding Notes

Use TypeScript ESM and keep types explicit at module boundaries. Preserve the local service patterns before adding new abstractions. Do not reintroduce free-form CLI command execution; future backend access should use typed tools or adapters.

Tests

Add focused Bun tests for route behavior, runtime/session state, result refs, and UIEnvelope mapping. Tests must not depend on mutable files under data/.

Security

This experimental service has no user authentication. Do not add secrets, tokens, passwords, API keys, session dumps, or generated result references to the repository. Keep .env, data/, and logs/ statically denied in opencode.json; do not replace those denials with prompt-only guidance. Keep arbitrary Bash and edit operations approval-gated and subagents disabled.

Runtime Readiness

Complete the OpenCode health check, warmup session, and model tool discovery before the HTTP server starts listening. A warmup failure must fail startup. Once listening, /health must expose the ready and warmed_up readiness fields used by deployment checks.

1.9 KiB Raw Blame History