Files
openwork/ee/apps/den-controller/AGENT_FOCUS.md
Omar McAdam 2b91b4d777 refactor: repo folder structure (#1038)
* refactor(repo): move OpenWork apps into apps and ee layout

Rebase the monorepo layout migration onto the latest dev changes so the moved app, desktop, share, and cloud surfaces keep working from their new paths. Carry the latest deeplink, token persistence, build, Vercel, and docs updates forward to avoid stale references and broken deploy tooling.

* chore(repo): drop generated desktop artifacts

Ignore the moved Tauri target and sidecar paths so local cargo checks do not pollute the branch. Remove the accidentally committed outputs from the repo while keeping the layout migration intact.

* fix(release): drop built server cli artifact

Stop tracking the locally built apps/server/cli binary so generated server outputs do not leak into commits. Also update the release workflow to check the published scoped package name for @openwork/server before deciding whether npm publish is needed.

* fix(workspace): add stable CLI bin wrappers

Point the server and router package bins at committed wrapper scripts so workspace installs can create shims before dist outputs exist. Keep the wrappers compatible with built binaries and source checkouts to avoid Vercel install warnings without changing runtime behavior.
2026-03-19 11:41:38 -07:00

2.5 KiB

Agent Focus: Den Service + Polar Gate

This guide explains how agents should operate, test, and troubleshoot the Den service.

What this service does

  • Handles auth (/api/auth/*) and session lookup (/v1/me).
  • Creates workers (/v1/workers) and provisions cloud workers on Render or Daytona.
  • Optionally enforces a Polar paywall for cloud worker creation.

Core flows to test

1) Auth flow

  1. POST /api/auth/sign-up/email
  2. GET /v1/me using cookie session
  3. GET /v1/me using Bearer token from sign-up response

Expected: all succeed with 200.

2) Cloud worker flow (no paywall)

Set POLAR_FEATURE_GATE_ENABLED=false.

  1. POST /v1/workers with destination="cloud"
  2. Confirm instance.provider matches the configured cloud provisioner (render or daytona)
  3. Poll instance.url + "/health"

Expected: worker creation 202, worker health 200 after async provisioning finishes.

3) Cloud worker flow (paywall enabled)

Set all Polar env vars and POLAR_FEATURE_GATE_ENABLED=true.

For a user without entitlement:

  1. POST /v1/workers with destination="cloud"

Expected:

  • 402 payment_required
  • response contains polar.checkoutUrl

For an entitled user (has the required Polar benefit):

  1. POST /v1/workers with destination="cloud"

Expected: worker creation 202 with a healthy cloud-backed instance once provisioning completes.

Required env vars (summary)

  • Base: DATABASE_URL, BETTER_AUTH_SECRET, BETTER_AUTH_URL
  • Optional social auth: GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET
  • Render: PROVISIONER_MODE=render, RENDER_API_KEY, RENDER_OWNER_ID, and RENDER_WORKER_*
  • Daytona: PROVISIONER_MODE=daytona, DAYTONA_API_KEY, and optional DAYTONA_* sizing/mount settings
  • Polar gate:
    • POLAR_FEATURE_GATE_ENABLED
    • POLAR_ACCESS_TOKEN
    • POLAR_PRODUCT_ID
    • POLAR_BENEFIT_ID
    • POLAR_SUCCESS_URL
    • POLAR_RETURN_URL

Deployment behavior

dev is the production branch for this service. Workflow:

  • .github/workflows/deploy-den.yml

It updates Render env vars and triggers a deploy for the configured service ID. Daytona is intended for local/dev worker testing unless you build a separate hosted Den deployment path for it.

Common failure modes

  • provisioning_failed: Render deploy failed, Daytona sandbox boot failed, or worker health check timed out.
  • payment_required: Polar gate is enabled and user does not have the required benefit.
  • startup error: paywall enabled but missing Polar env vars.