Skip to content

Send a task to an agent

This page is the short path from a task in HeyAira to a pull request opened by an agent. The full contract is in task-version execution.

What happens

  1. You (or a chat acting for you) describe the task: what to build and the named acceptance criteria that define done.
  2. The task is configured with a repository, a catalog agent (provider and model) and, usually, independent verification.
  3. The task is sent to your Mac with workflow_send.
  4. The HeyAira Bridge on the Mac picks it up and runs the agent, Codex CLI or Claude Code, in a sandboxed Git worktree of its own. You can watch the session live in the Bridge app's Work Center.
  5. A separate, read-only verifier agent checks each criterion against the candidate commit. If it requests changes, the worker gets one correction (at most two work attempts per send), resuming its earlier session when the provider allows.
  6. The Bridge pushes the task branch and opens the pull request. The server checks on GitHub that the pull request's head is the accepted commit, on the task's own branch, and refuses the report otherwise. When GitHub cannot be asked, the publication is recorded and marked unchecked.
  7. CI results on that commit are recorded in the task's history. A failure is acted on when GitHub, asked at that moment, still shows the pull request open with the accepted commit as head: the work goes back to the agent when an attempt is left; with no attempt left, or when it cannot be sent back, the task is blocked with a reason. A failure on a merged, closed or changed pull request, or one GitHub could not confirm, is recorded and notified only (details).
  8. Your phone gets a push when a task is blocked, its checks fail, or an accepted task has no pull request after ten minutes (notifications).

The agent never merges or deploys. The pull request is where its work stops and your review starts.

One-time setup

These steps are done once per project and Mac, by the operator and the owner:

  • Repository. The repository is bound to the project with the HeyAira GitHub App (heyaira-admin github-connect), so the server can read pinned documents, pull requests and CI results.
  • Agents. The account catalog holds the worker and verifier agents: each names a provider, a model, a role and skills, with instructions kept as pinned Git documents (catalog provisioning).
  • Mac. The HeyAira Bridge is installed, paired and enrolled for the project, signed in to the provider accounts it will use, and has background work turned on with a local policy that maps the repository to a local clone and allows publishing. The policy's max_parallel_tasks is how many tasks the Mac runs at once.
  • Phone. The HeyAira iOS app is signed in for push notifications.

The calls

All three are made by a project owner or admin, from any connected MCP client. Every write needs write_context from server_identity.

  1. task_create with a title, a description and a summary.
  2. task_execution_configure with the task's current expected_version and settings: repository_id (from project_repositories), agent_id, provider, model, verification (independent by default), time_limit in seconds (8 hours by default, 24 at most) and 1 to 32 acceptance_criteria, each with an id, a description and the method used to check it. This makes a new task version.
  3. workflow_send with that task_version, the Mac's bridge_id, the same agent, provider, model and repository, the verifier_agent_id when verification is independent, the base_commit and branch to work from, and an idempotency_key.

workflow_send is refused, and creates nothing, when the Mac is offline, runs a Bridge too old for this contract, or is already full (bridge_at_capacity; send again when a task finishes). The exact arguments and scopes are in the tool catalogue; error codes are in errors and recovery.

Follow the work

  • workflow_get returns the current workflow and its ordered history: picked up, working, verifying, changes requested, done, pull request opened, CI completed.
  • task_get shows the task with its receipts, including the agent's RESULT.
  • The Bridge app shows each running session live.

A task that ended blocked or cancelled can be sent again. On the same base_commit it continues from its previous candidate; a different base starts fresh from that base. An agent that continues from a candidate, and in particular from one already published as a pull request, adds commits on top of it and never amends, rebases or resets it. To stop a task, use workflow_control with action: cancel.