Agent-driven onboarding

The agent calls whoami. It checks that scopes has bugbearer:setup and that apps is null (all apps). connect_app needs both.

The agent calls connect_app with a repo (owner/name, and subdir in a monorepo) or a public staging URL. For a URL it sets notProduction to true, and only after you confirm the URL is not production.

The result has a next field:

• ready: a URL app is saved. Nothing more to do.
• run_setup: a repo app exists. Go on to the brief.
• install_github_app: Bugbearer cannot read the repo yet. Go to the next step.

This is a human step. The agent cannot do it. The result holds an installUrl. The agent gives it to you. You open it, pick the account or organization, and add the repo. For a repo in an organization, an owner may have to approve. Then the agent calls connect_app again.

The agent calls get_brief_schema with the appId. It returns the JSON Schema of the setup brief and the rules for writing it.

The agent reads the repo as the rules say, writes the brief, and calls submit_brief. The result is { ok: true } or { ok: false, errors }. Each error has a path and a reason. The agent fixes them and sends again.

A brief holds names only. It has no field for a secret value.

The agent calls start_setup with the appId. It returns a sessionId. Setup works for repo apps only. It uses the brief you sent.

The agent calls get_setup_status and waits between calls. The result shows the setup phase and status, the target state, and:

• pendingEnv: names of environment variables that wait for a value.
• pendingAccounts: test accounts that need a password.
• modelKeyMissing: names of model keys that are missing.
• questions: open questions for you.

The agent shows you questions. You enter passwords for pendingAccounts in the web app. The agent can send pendingEnv and modelKeyMissing values with set_env. See the next steps.

The agent shows you each open question. You tell it the answer. The agent calls answer_setup_question with plain text of at most 4000 characters. The tool refuses any text with a KEY=value assignment. Values go through set_env.

If the setup stopped, the agent calls resume_setup to restart it from its saved history. To stop a setup, it calls cancel_setup.

The agent calls set_env with the appId. It returns a curl command with a one-use token that expires after 15 minutes. You put your test-mode keys in an env file on the machine where the agent runs its shell. The agent runs the command with the path of that file. It does not read, print or open the file. The reply lists names and decisions, never values.

You can ask for mode: "link" instead. The result is the address of the setup review screen, where you type the values yourself.

The agent calls list_env_status to check which names are stored, which are still missing, and which the boot plan reads (inPlan). If the upload reply lists a name in notInPlan, the agent follows its next step. See Secrets and test keys.

The agent calls get_boot_plan to read the saved plan, the last validation and the rules for a plan. If the plan needs a change, it calls propose_boot_plan. The result is { saved: true } or a list of problems. Both tools refuse while a setup runs for the app.

The agent then calls validate_boot_plan. It boots the saved plan for real and waits up to 30 seconds. If the result has status: "running", the agent reads progress with get_boot_plan and calls validate_boot_plan again only after the boot ends.

The agent calls start_run with the appId and a brief of 3 to 4000 characters that says what to test. Bugbearer plans the test cases and starts the run. No person presses Start. The agent polls get_run and lists runs with list_runs.

If a test account has no stored password, the call is refused and the message names the account. You add the password in the web app.

The agent calls list_draft_cases and shows you the cases. It asks you which ones to keep. After you answer, it calls approve_cases or reject_cases with at most 50 case ids. reject_cases needs a reason. An approved case runs on every scheduled run.