Trace how Roomote agents run through the Roomote runtime and integrations. Use when debugging or changing controller/worker/queue behavior, preview proxy flows, snapshots, MCP setup, or Slack/Linear/GitHub entry points that create or resume Roomote agent work.
التثبيت
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
Trace how Roomote agents run through the Roomote runtime and integrations. Use when debugging or changing controller/worker/queue behavior, preview proxy flows, snapshots, MCP setup, or Slack/Linear/GitHub entry points that create or resume Roomote agent work.
Roomote Runtime Integrations
Trace the full Roomote agent path before changing runtime code.
Start Here
Read packages/cloud-agents/src/server/cloud-job-queue.ts for queue claim/release behavior.
Read apps/controller/src/BaseController.ts and apps/controller/src/orphaned-cloud-jobs.ts for dispatch and recovery.
Read apps/worker/src/run-task/* and apps/worker/src/commands/* for worker execution and harness startup.
Read packages/cloud-agents/src/system-prompt.ts and packages/cloud-agents/src/server/workflows/ for prompt assembly and workflow builders.
Runtime Map
Producers create tasks from web UI, API routes, or integration webhooks.
Queue/controller logic turns those requests into dequeued jobs and machine dispatch.
Workers prepare repos/services, configure MCPs, and run the active harness.
Preview proxy exposes preview URLs and auth flows for running agent environments.
Slack, Linear, GitHub, and MCP routes are entry surfaces into the same Roomote agent runtime.
OpenCode Runtime Debugging Playbook
Use this when you need to debug worker, sandbox-server, or OpenCode server
harness behavior with the currently checked-in repo surfaces.
Preferred Validation
Confirm the OpenCode CLI exists: command -v opencode.
Confirm auth exists when needed: OPENAI_API_KEY.
Start with the smallest targeted worker or sandbox-server test that covers
the code you are changing.
If you need lower-level payload inspection beyond the checked-in tests, use
the real caller under test or add a temporary local-only probe in your branch.
Do not leave ad hoc probe helpers committed unless you intentionally turn
them into supported scripts.
environment package code under packages/ related to environment config
Slack / Linear / GitHub flows:
webhook handlers under apps/api/src/handlers/
related packages under packages/slack, packages/linear, and GitHub handlers
MCP setup:
packages/types/src/mcp-oauth.ts
apps/worker/src/commands/setup/setup-mcps.ts
apps/api/src/handlers/mcp/index.ts
apps/api/src/handlers/mcp/routing.ts
Current Invariants
Docker is the default worker compute provider for Roomote local and self-hosted deployments.
Hosted compute providers should preserve the sandbox-compatible API/contract surface used by Docker, Vercel Sandbox, and Modal-backed workers.
Local preview-proxy runs on port 8081.
Webhook mounts are under /api/webhooks/*.
GitHub MCP is router-side today. The worker-side integration catalog is no
longer just Linear; treat packages/types/src/mcp-oauth.ts as the source of
truth for the current task-facing integrations.
GitHub App installation flow and GitHub user OAuth flow are separate concepts.
Output Standard
Name the exact entry surface affected by the change.
Trace the handoff path end-to-end before proposing a fix.
