dev3000 (d3k)

d3k uses a per-project Chrome profile to preserve login state, cookies, and local storage. This is critical for handling sensitive authentication flows like Google OAuth or Supabase.

Warning: Do not attempt to substitute the managed browser with raw Chrome, Playwright, manual CDP attachment, or agent-browser --profile. Using these alternative methods uses a different profile and may trigger security blocks (e.g., "This browser or app may not be secure").

If the managed browser becomes unavailable, stop the d3k process and restart it cleanly rather than attempting to work around it with a different browser.

Sponsored runs are highly restricted to protect Vercel Labs infrastructure. Key constraints include:

• Repository Access: Only public repositories are allowed. Cloning is performed via public Git URL and a pinned commit SHA.
• Environment: No user-provided secrets, no custom runner environment variables, and no reuse of user project environment variables.
• Execution: No arbitrary scripts and no private repo access tokens.
• Permissions: No write access to the user's repository and no PR creation (in the initial version).
• Resource Limits: Hard limits are enforced on repository size, file count, token usage, runtime, and concurrency.

Each entry in the changelog consists of a version number, a date (YYYY-MM-DD), a release type, and 3-4 key highlights. The system classifies releases into three types:

• Major (x.0.0): Breaking changes or major new features.
• Minor (x.y.0): New features or significant improvements.
• Patch (x.y.z): Bug fixes or small improvements.

When interacting with an agent using d3k, the phrasing changes the agent's behavior:

• "Let me test this project with d3k": The agent prepares the headed monitored browser and hands control to you. It waits for you to reproduce the issue, then inspects the captured evidence.
• "Test/debug this with d3k": The agent is authorized to drive the managed browser and investigate the issue autonomously.

The d3k-skill-runner architecture is split into two distinct planes to separate the user interface from the execution compute:

1. Control Plane (dev3000-www): Responsible for authentication, team selection, the /skill-runner catalog UI, skill search/import, managing team settings, initiating run requests, and rendering reports by polling the worker.
2. Data Plane (per-team d3k-skill-runner worker project): A dedicated project provisioned within the user's Vercel team. It hosts durable workflows, manages sandboxes, installs d3k and skill packages, executes observation/verification, generates report payloads, and writes artifacts/run state to team-owned storage.

This split allows teams to own their execution costs (compute, storage, and potentially AI) while using dev3000-www as a unified management interface.

To maintain compatibility between the control plane and workers, three distinct versions must be tracked:

1. Worker app version: The version of the runner shell artifact.
2. Wrapper generation version
3. Workflow schema version

When the control plane communicates with a worker, it must include the expected protocol version. The worker returns its own version; if these are incompatible, the control plane should mark the worker as needing an upgrade.

DeepSec runs in one of three execution modes depending on the user and project type:

• self-hosted: The default mode. Users install d3k-skill-runner in their own team. The user's team is responsible for billing, logs, and AI Gateway usage.
• hosted: Reserved for internal Vercel/Vercel Labs execution for trusted internal teams.
• sponsored: Available for allowlisted public repositories. Vercel Labs owns the billing, logs, AI Gateway usage, and report storage. Users see this as a "free DeepSec report" and do not need to install a team runner.

Authentication between dev3000-www and the d3k-skill-runner worker must be server-to-server. Do not use browser session cookies.

Recommended Implementation:

• Shared Secret: Store a per-team worker secret in the control plane.
• HMAC Signing: All outgoing requests from the control plane to the worker must be signed using this secret and include a timestamp to prevent replay attacks.
• Validation: The worker validates the signature and ensures the request matches the expected installation/team context.

d3k uses a project-specific Chrome profile to preserve login states, cookies, and local storage. This is critical for handling sensitive authentication flows like Google OAuth or Supabase.

Important Safety Rules:

• Do not substitute the managed browser: Never use raw Chrome, Playwright, manual CDP attachment, or agent-browser --profile for auth-sensitive tasks. Doing so uses a different profile and may trigger security warnings like "This browser or app may not be secure."
• Handle unavailability correctly: If the managed browser is unavailable, stop the current d3k process and restart d3k cleanly. Do not attempt to work around it by creating a separate browser instance.
• Headless mode: Use --headless only for CI environments or when explicitly requested. Use --servers-only if you want to monitor the server but do not want browser monitoring.

When an agent uses d3k, it follows a specific lifecycle to ensure a stable debugging environment:

1. Check Status: Run d3k status --json to see if an active project session already exists.
2. Start Runtime: If no session exists, start d3k in the background using d3k --no-agent --no-tui -t.
3. Wait for Ready: Wait for d3k to provide a Portless URL and a managed browser.
4. Browser Interaction: The agent can either hand the headed browser to the user or drive it autonomously using d3k agent-browser.
5. Inspect Evidence: After reproducing an issue, the agent reads d3k errors --context and unified logs.

Crucial Rule: Do not run npm run dev or bun run dev manually while using d3k; d3k owns the dev-server session.

To qualify for a sponsored DeepSec run, the following conditions must all be met:

1. The skill must be exactly deepsec.
2. The selected Vercel project must have a Git repository.
3. The repository must be public.
4. The repository or project must be on an explicit allowlist.
5. The run must be within the quota defined for the allowlist entry.
6. The run must not provide custom runner environment variables.
7. The run must use bounded DeepSec settings.