Run Lifecycle

A run is a single execution attempt for a given task, agent profile, target Edge, workspace, and runtime adapter. The lifecycle matters because AgentHub delivers visible, reviewable, and auditable agent work — not a terminal transcript pasted into a webpage.

Lifecycle Map

The UI should never skip from "created" to "done" without event evidence. If the runtime cannot emit enough events, AgentHub should mark the run as degraded or failed and state a specific reason.

State Machine

stateDiagram-v2
  [*] --> Created
  Created --> Planned
  Planned --> Accepted
  Accepted --> Preparing
  Preparing --> Running
  Preparing --> Failed
  Running --> NeedsApproval
  NeedsApproval --> Running: approved
  NeedsApproval --> Cancelled: rejected or cancelled
  Running --> Applying
  Applying --> Running
  Running --> Completed
  Running --> Failed
  Running --> Cancelled
  Completed --> [*]
  Failed --> [*]
  Cancelled --> [*]

Event Envelope

Every event should be safe to render in Desktop, Web, and future integrations. Raw runtime output may be attached for debugging only when it does not expose secrets.

{
  "id": "evt_01",
  "sequence": 12,
  "type": "run.message.delta",
  "runId": "run_01",
  "sessionId": "session_01",
  "agentId": "docs-agent",
  "timestamp": "2026-06-09T00:00:00.000Z",
  "payload": {
    "text": "Reading the public docs route map."
  }
}

Core Event Groups

Approval Gates

AgentHub should default to conservative approval gates:

Approvals should be explicit actions. Do not hide them behind a generic "continue" button when the risk is file write, shell, network, publish, or deploy.

Artifacts And Diff

Artifacts and diffs are review surfaces, not proof that a change has been accepted.

Public examples should use synthetic paths such as docs/quickstart.md, not private absolute paths.

Failure Codes

Use specific, recoverable errors:

Avoid generic "something went wrong" copy in product surfaces. A user should know whether to fix CLI auth, workspace policy, target availability, approval, or adapter schema — and the error should point to the right one.

Runtime Adapter Responsibilities

Runtime adapters should:

• Start and stop the underlying runtime process.
• Parse stdout, stderr, JSONL, NDJSON, or protocol events.
• Normalize messages, tool calls, file changes, approvals, and terminal state.
• Enforce timeout and cancellation hooks.
• Avoid logging provider keys, prompt secrets, local absolute paths, and raw private file content.
• Emit stable failure events when the runtime is missing, unauthenticated, or incompatible.

The adapter owns process details; the Agent Profile owns product-facing capability, label, policy, and selection behavior.

UI Requirements

Desktop and Web should render lifecycle state consistently:

• State label and last event time are visible.
• Running state does not resize the layout or jump after hydration.
• Approval state clearly separates read-only review from apply/write.
• Failed state shows code, safe message, and next action.
• Completed state links to artifacts, diff, transcript, and audit evidence.
• Theme and language changes do not reset the run timeline in a mock or preview.

Verification

For a run lifecycle claim to be real, verify:

1. A run starts from a known actor and project or workspace.
2. Edge validates workspace, runtime profile, and approval policy.
3. Events arrive in order and can be replayed after refresh.
4. Diff, artifact, and preview events render without private absolute paths.
5. Approval blocks risky actions until explicit resolution.
6. Completed, failed, and cancelled states are terminal and stable.
7. Search, docs, and release notes describe the same lifecycle vocabulary.

Related Pages

• API And Events
• Agent Profiles
• Desktop Guide
• Web Workbench
• Troubleshooting