Skip to content
rachel/ccccocc
File

Blob: AGENTS.md

Markdown82 lines

AGENTS.md

Rules To Remember

  • Use Sandbox SDK as the primary abstraction. Do not add an SSH bridge, custom container control plane, or extra proxy layers when @cloudflare/sandbox already covers the job.
  • Preserve the ownership model user/workspace -> sandbox and logical terminal tab -> session. Do not collapse those boundaries for convenience.

Naming

  • The product name is ccccocc, always lowercase.
  • Product framing may say "Cloudflare Containers", but implementation choices should target Sandbox SDK and Cloudflare's native terminal WebSocket path.

Repository Status

  • This repo is no longer a blank scaffold. Multi-tab workspace state, reconnect handling, shared-session detection, backup and restore, and Cloudflare Access auth already exist in the live tree.
  • Frontend files are under active iteration. Expect unrelated local edits and avoid reverting them.
  • Terminal behavior is platform-sensitive. Automated tests help, but reconnect, alternate-screen TUIs, and container lifecycle changes still need manual verification.

Source Of Truth

  • The live source tree wins when docs drift.
  • docs/SPEC.md is the product and architecture intent.
  • README.md is the human-facing guide. Keep repo-operating instructions here in AGENTS.md.
  • src/shared/protocol.ts is the shared terminal control contract.
  • src/client/workspace/store.ts and src/client/workspace/types.ts own the logical tab and session persistence model.
  • src/worker/auth.ts owns auth mode selection and sandbox ownership derivation.
  • wrangler.jsonc is the runtime binding contract.
  • worker-configuration.d.ts and dist/ are generated outputs. Regenerate them; do not hand-edit them.

Working Rules

  • Keep edits scoped and minimal.
  • Multiple agents may be working in parallel. Do not revert unrelated changes.
  • Assume the dev server may already be running. Do not start npm run dev unless the user asks or the task clearly requires it.
  • Keep the repo single-package unless there is a concrete technical need to change that.
  • Prefer explicit code over clever code. Small duplication is acceptable when it keeps session or auth behavior obvious.
  • Preserve the split between src/client, src/worker, and src/shared. If both client and worker do not need a type or helper, it probably does not belong in src/shared.
  • Prefer direct use of existing @cloudflare/sandbox APIs. Do not add another abstraction layer unless the repo has a concrete gap.
  • Avoid extra control-plane infrastructure. The Sandbox class is already the Durable Object; add more coordination only when there is a clear need.
  • Keep the PTY byte path simple. Do not insert avoidable middleware or transform layers between terminal I/O and proxyTerminal.
  • For Cloudflare runtime or Sandbox behavior that may have changed, prefer current official Cloudflare docs over memory.

Important Invariants

  • The client should identify sandboxes by workspace, not raw sandbox IDs. The worker derives sandboxId = ${userId}-${workspace} after authentication.
  • One sandbox exists per user and workspace. One backend session exists per logical in-app terminal tab.
  • Refresh persistence is per browser tab or window via sessionStorage. The persisted model is the tab collection plus active tab, not a single global session ID.
  • Closing a UI tab detaches from the backend session by default. Do not silently delete sessions unless the UI explicitly says it will.
  • Creating a new tab or choosing "New Session" must use explicit session creation semantics. Do not rely on implicit session auto-creation for intended cwd, environment, or labels.
  • Sandbox sessions may be silently created with defaults when referenced. Reattaching to a session ID is not proof that the expected shell state still exists.
  • Terminal WebSocket behavior is fixed: incoming binary frames are PTY output, incoming text frames are JSON control and status, outgoing binary frames are UTF-8 keystrokes, outgoing text frames are resize messages, and buffered PTY replay may arrive before ready.
  • ghostty-web should be initialized once at app startup. Reconnect flows should clear terminal state before replay to avoid duplicate output.
  • Control-key handling is custom in the terminal adapter path to work around ghostty-web encoder issues. Preserve that behavior when changing input handling.
  • cwd for created sessions must stay under /workspace.
  • Session env vars are sanitized server-side. Labels returned by the session API are client metadata only; the Sandbox SDK does not persist them.
  • Dev auth is intentionally localhost-only when Access is not configured. Non-local hosts must reject requests until Access is configured.
  • Containers are ephemeral. Without backup and restore or mounted object storage, files, processes, sessions, and shell state disappear on restart or idle eviction.

Validation

  • npm run typecheck for most changes. This regenerates worker-configuration.d.ts.
  • npm test for unit and worker route coverage.
  • npm run build when changing bundling, routes, runtime bindings, or container wiring.
  • npm run types:generate after changing wrangler.jsonc or .dev.vars.example.
  • Use test/MANUAL_TEST_CHECKLIST.md for reconnect, multi-tab, shared-session, resize, paste, and interactive TUI regression checks.
  • Manual verification is still expected for alternate-screen apps, network interruption recovery, container restart detection, and Cloudflare Access flows.

Quick References

  • Product overview and setup: README.md
  • Product and architecture intent: docs/SPEC.md
  • App shell and workspace UI: src/client/app.tsx, src/client/components/terminal-workspace.tsx, src/client/components/tab-strip.tsx, src/client/components/session-controls.tsx
  • Terminal integration: src/client/terminal/adapter.ts, src/client/terminal/socket.ts, src/client/terminal/use-shared-session-detection.ts
  • Global styles and theme: src/client/styles/app.css
  • UI primitives: src/client/components/ui/
  • Tab and session persistence: src/client/workspace/store.ts, src/client/workspace/types.ts
  • Worker routes and lifecycle APIs: src/worker/index.ts
  • Auth and sandbox ownership: src/worker/auth.ts
  • Shared protocol types: src/shared/protocol.ts
  • Container bootstrap: container/Dockerfile, container/container-shell.sh, container/root.zshrc
  • Tests and manual checklist: test/