Cloud coding-agent sessions

View as Markdown

Hand a pull request finding to a connected Cursor or Devin account from a terminal: read the protected prompt, start one session with it, and follow its status.

Before you start#

An organization administrator connects Cursor or Devin in the console first and allows the repositories each connection may work on. The help center describes how to connect a vendor and start a session from the console.

A session starts from a finding that a pull request review recorded at an exact commit, whether the environment assessment or the code review found it. The console offers the start on environment findings only; these commands also accept a code review finding, so an organization with environment checks off can start sessions here. A session works only in that finding's repository, and you need GitHub write access to that repository.

Token#

These commands need a personal token with the agent_sessions:start scope. Create one from Personal tokens, set PROOFLINE_TOKEN to it, and set PROOFLINE_ORGANIZATION_ID or pass --org. Authentication describes personal tokens.

proofline login cannot grant this scope, so a browser sign-in cannot start a session. Organization tokens, CI job tokens and MCP credentials cannot start one either, and neither can a coding agent's MCP tools.

Read the prompt#

proofline session prompt FINDING_ID

The result holds the prompt Proofline will send, with protected values withheld, its prompt_digest, and the ID and vendor of each active connection that allows the finding's repository. Read the prompt before you start a session.

Start a session#

Name one of the listed connections and the digest of the prompt you reviewed:

proofline session start FINDING_ID --connection-id CONNECTION_ID --prompt-digest PROMPT_DIGEST

The command starts one session and never retries. Running it again requests another session. If the command ends with a dropped connection or a server or proxy error instead of a session, follow Recover an unconfirmed start before you run it again. If the finding's prompt changed after you read it, the start is refused; read the prompt again. If the pull request's head moved, the finding needs another review first.

Each finding series allows three sessions at one commit, and each organization allows 50 session requests in 24 hours. The vendor bills its connected account for the session, and Proofline spends no credits on it.

Follow a session#

proofline session get SESSION_ID

The result has the recorded status, the vendor's link, the vendor's summary and any pull request GitHub verified in the finding's repository. Proofline follows a session for up to six hours. A finished session does not mark the finding fixed; review the vendor's pull request as you would any other change.

Recover an unconfirmed start#

A start is unconfirmed in two cases. The command can lose its answer to a dropped connection or a server or proxy error, which leaves you without a session ID. Or session get shows status FAILED with cause START_UNCONFIRMED: Proofline sent the request and the vendor did not confirm it. Either way the vendor may already be running the session and billing its account, so check before you start another.

Your session start command names the finding and the connection. proofline session prompt FINDING_ID reads the rest again without starting anything: target holds the repository, pull request and reviewed commit, and connections gives the vendor of each connection ID.

Without a session ID#

The command line cannot list a finding's sessions, so look in the console or at the vendor:

  • For an environment finding, open the finding from its pull request's review in the console. Its Cloud sessions list shows each recorded session with its status and vendor link. A new session there on the connection you named is your request; follow it in that list. If the list shows none, Proofline did not record the request, and nothing reached the vendor. Recover an unconfirmed cloud coding-agent session describes the console steps.
  • The console lists sessions for environment findings only. For a code review finding, open the vendor account behind the connection and look for a session on the finding's repository and pull request that started when you ran the command.

A recorded start the vendor did not confirm#

Proofline stops following a session whose cause is START_UNCONFIRMED, and it has no vendor link for it. In the vendor account that vendor and connection_id name, look for a session on target.repository_full_name and pull request target.pull_request_number that started near created_at. If you find one, follow its status at the vendor, and check its pull request as you would any other change.

A session whose status is HEAD_MOVED never reached the vendor. The pull request had moved past the reviewed commit, and observed_head_sha names the head Proofline saw.

Start again or review again#

Start another session only when the vendor shows none for your request. The vendor bills that start as a new session, and every recorded request, an unconfirmed one included, counts toward the three sessions per finding series at one commit and the organization's 50 a day.

If the pull request's head has moved past target.head_sha, a session from this finding ends as HEAD_MOVED without reaching the vendor. Review the pull request again with proofline review --pr and start from the finding that review records at the new head. A session already at the vendor keeps working from the earlier commit, so check it first.

The API requests#

The commands send these requests, each with the same personal token:

CommandRequest
session promptPreview a coding-agent session, GET /api/v1/organizations/{org_id}/findings/{finding_id}/agent-session-prompt
session startStart a coding-agent session, POST /api/v1/organizations/{org_id}/findings/{finding_id}/agent-sessions
session getGet a coding-agent session, GET /api/v1/organizations/{org_id}/agent-sessions/{session_id}

The start's body names connection_id and prompt_digest:

curl -sS -X POST "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/findings/$FINDING_ID/agent-sessions" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"connection_id\": \"$CONNECTION_ID\", \"prompt_digest\": \"$PROMPT_DIGEST\"}"