Skip to main content
Not yet released. This guide describes implemented changes awaiting rollout. Availability requires the corresponding backend and dashboard release.

​
Goal

Connect proposed agent actions to canonical operations without exposing private task content or confusing approval with execution.

​
Prerequisites

  • An authenticated session or API token permitted to read the selected resource.
  • A backend release that includes the version 1 agent-activity contract.

​
Workflow

1
Read agent-activity for the resource, separately from its operation-activity collection.
2
Render pending decisions, other current actions and paginated history, deduplicated by action ID.
3
Use operations references to associate actions with the existing canonical operation records.
4
Offer new decisions or recorded-decision recovery only through the explicit server capabilities, then refresh both reads.

​
Routes and parameters

All paths below are relative to /api/v1. Append /{actionID} for an exact retained action read. Use the database route matching its ownership context. Existing operation-activity, event, release and log endpoints remain compatible.
  • Lists accept limit from 1 to 100, default 25, and an opaque cursor. Pending/current are refreshed independently of that history limit.
  • Unknown or duplicated parameters, empty cursors and invalid limits are rejected. Exact reads accept no query parameters.
  • An action ID is agent_tool_execution:<UUID>. Percent-encode the complete ID once as a path segment. Never construct identity from a label or timestamp.
  • No objective-scoped agent-activity feed or new SDK/CLI command is added by this release.

​
Collection and item contract

The normal response envelope contains data.contract_version=1, scope, observed_at, pending, pending_complete, current, current_complete, history and availability. Arrays remain arrays; unknown nullable values remain null.
  • history contains items, limit, complete, has_more and next_cursor. An action appears once among pending/current/history.
  • Items contain stable id, source kind/record_id/status, known action_key and agent identity, principal and affected resource references, environment, controlled title/summary, available impact/revision/review fields, lifecycle state, terminal evidence and timestamps.
  • Action states are proposed, pending_approval, queued, running, succeeded, failed, cancelled, expired, superseded or unknown. Unknown state remains current with terminal=null.
  • authorization records the proven outcome and basis. approval supplies safe scope, lifecycle, expiry and explicit decision/recovery capabilities. owner_context and private links require separate authorization.
  • operations contains canonical activity_id, resource, relation and exact safe detail href. Relations are originated, controlled or observed. A succeeded tool action does not change the linked workload’s outcome.
  • Safe review fields are an allowlist, not arbitrary tool arguments. Unsupported detail, revision or impact remains unavailable. Never infer no downtime or no data changes from an empty review.

​
Pagination and incomplete sources

History is ordered by durable creation time descending, then full action ID descending. The signed opaque cursor binds the viewer, resource, linked-project context and feed. Operation-activity cursors cannot be used for agent-activity. A creation boundary does not freeze action state or future permissions. Required target, scope and authorization evidence must resolve before an item can be returned or history advanced. On a required source failure, affected unverified items are suppressed, completeness is false and next_cursor/has_more are null. Retry the identical incoming cursor after recovery; do not treat this as the end of history. Optional display, operation-link, private-context or continuation enrichment can fail while verified history remains complete. Inspect availability.sources even after HTTP 200. Missing private controls must not be interpreted as permission.
  • Complete empty data returns 200 with empty arrays, complete=true and has_more=false.
  • Total required projection failure returns 503 activity_sources_unavailable with incomplete shaped data. Authority infrastructure failures return 503 activity_access_unavailable with no partial authorization.
  • Missing, unrelated or inaccessible selected resources/actions return 404 activity_not_found. Invalid queries/IDs/cursors return 400. Existing authentication and token-scope errors remain 401/403.
  • Pending and current each have a 1,000-action safety ceiling; read_limit_exceeded reports incompleteness rather than silent truncation.
  • Retain last safe data during transient failure with a stale indication. On access denial, remove inaccessible records. Refresh page one and deduplicate by stable ID as actions settle.

​
Authorization and private data

  • human_approved with basis=human_decision identifies a matching recorded human approval, including its real actor and decision time.
  • automatic with basis=read_only_rule or standing_policy identifies stored evidence at execution admission. Policy ID/version are owner-private.
  • not_recorded means a successful evidence read cannot establish historical authorization. Current policy is never used to backfill it.
  • Resource readers receive safe facts, not private prompts, conversation text, raw arguments, approval notes, controller payloads, secrets or another user’s billing data.
  • Each child resource also requires its canonical resource permission and token scope. Parent Application/project access cannot bypass restricted child access.
  • Private context requires independent task ownership and agent-read permission. Decision and recovery controls additionally require the existing owner-governance credential rules.
  • These GET requests never reconcile, repair a queue, invoke a model or consume AI credits. Authorized reads remain available with no subscription, no credits or disabled execution.

​
Submit one new decision

Only when approval.can_decide=true, submit the offered action_hash and approved or denied choice to approval.decision_path. The wire choice is denied; the reader displays declined. A valid decision is still subject to transactional owner, target/version, hash, expiry and cancellation checks. The resource projection suppresses decision and recovery capabilities for application.manifest.apply, application.manifest.prune and application.release.create/retry/rollback/cancel because a complete persisted UUID target set is not established. Exact action identity alone does not establish complete approval scope; use only capabilities actually returned by the server. The existing endpoint owns continuation. Do not issue a second resume request after approval. Refresh agent-activity and operation-activity; approval acceptance and queue admission do not establish deployment success.
  • The response data remains the legacy flat approval object, with optional continuation. Do not render its raw scope, risk explanation or other payload as the resource panel’s safe Review changes content.
  • continuation states are waiting_approvals, queued, running, settled, blocked, unavailable or not_required. They remain separate from action/controller state.
  • A committed decision with unconfirmed continuation returns 503 approval_continuation_unavailable and the recorded approval plus retryable continuation. Do not show it as an unrecorded decision.
  • Expired pending approvals return 410. Conflicting decisions, changed actions and revoked authority are rejected; no new execution is admitted.

​
Recover after a lost response or reload

A fresh owner-authorized read can return approval.can_recover=true and recovery={method,href,request}. This is distinct from can_decide. Send exactly the projected recovery request to the same decision endpoint; do not offer a different approve/deny choice, infer recovery from missing operations, or run recovery automatically during polling. Recovery uses the recorded decision and action hash with note omitted. Omission preserves the original durable note; an explicitly different note, decision or hash conflicts. It reuses the existing durable continuation identity or repairs its missing reference, without admitting another invocation. No saved browser request is required. Queued/running work with a confirmed reference needs no recovery. Revoked credentials, expired authority, changed targets, cancelled or terminal runs, independent credit/input waits and ambiguous unavailable evidence suppress recovery. Resource-only readers receive no recovery request or private continuation details. If no decision committed, a fresh read still shows pending according to current permissions. Retry the original choice/hash while the outcome is uncertain; do not substitute an opposite choice.

​
Expected result

Consumers can show a pending approval before an operation exists and retain the same action identity after execution.

Live workload workspace

Follow a deployment, release or database operation alongside its activity and approval decisions.

Operation activity API

Read canonical current operations and paginated history without invoking an agent.

Resource activity

Follow builds, deployments, releases and database operations from the resource you are working on.

Raw customer API command

Call an existing customer API path with bounded inputs, safe retries, downloads, and path restrictions.