Skip to content

Read the action register index

PortalCLIBeginner~5 min

You can see, for your team's App, which code sends work to which role task, and which codes land on one particular task. In the portal that is two clicks and nothing to install. The CLI gives you the same list as text or JSON, and you need it only if you want to script the read or page through a long list.

The index is read-only: looking at it changes nothing. What it is and how each answer is found is in The action register index.

Is it in your portal yet?

The portal screens and the CLI command are both merged. The CLI command is in release v0.35.0. The portal screens are in the portal's code, but this page does not confirm that the portal you use has been updated to include them. If you do not see the Action register tab described below, the portal may not have received it yet.

In the portal

Every code in an App

  1. Open your team's App and choose the Action register tab.
  2. Choose the Agent to ask as. The page says Choose an Agent to see its codes until you do. Pick the Agent whose tasks you want the codes resolved against: usually the role you are working on.
  3. Read the table. Each row has the Code, what it Resolves to, and Defined by, the Agent whose register holds the entry. Defined by is empty on an UNMAPPED row, and kept on an UNRESOLVED one.

What Resolves to says:

You see State Meaning
A task link MAPPED The code resolves to that task for the Agent you chose.
No runnable task at a location UNRESOLVED The entry exists, but the Agent's chain has no runnable task there.
The nearest register entry for this code is malformed UNMAPPED The nearest entry names no task. The row does not say which Agent holds it: whoever manages the App's Team Agent checks the Team Agent's chain for the malformed entry.

What to do about each is in The three states.

The list is paged by the server. Under the table you see a count such as Showing a–b of N, with Previous and Next. If the page says No codes shown, that is not necessarily an empty register. See Why an index can be empty.

If the page says This Agent can't be used for this App, choose another Agent: one installed in the App, or the Agent of a worker cast into it.

Which codes send work to one task

  1. Open the role's Agent and go to the definition page of the task.
  2. Find the section Codes for this task loc. If you can reach more than one App with this Agent, choose the App; with one, it is used.
  3. The page says Resolved as and the Agent's name, then lists the codes. A row says Sends work here when the code resolves to exactly this task, and Resolves to another task when the code names this location but the asking Agent's chain finds a different task first (for example an override).

If the section says Not available for this App, the index could not be read for that App and Agent. The task definition above it is still valid.

From the CLI

You need the Hadron CLI at v0.35.0 or later. Install it with Install the Hadron CLI.

hadron team register

The App is the one your worktree is bound to or that your CLI is configured for. Name it with --app. Name the asking Agent with --agent; with none, the server uses the Agent of the worker or run you are acting as. A person's or an App key's call with no --agent is refused with BAD_USER_INPUT (exit 2).

hadron team register --app acme.com:eng --agent hrn:agent:acme.com:coder

The text output is a table with the columns CODE, STATE, TASK / REASON, ACTION, ENTRY and DEFINED BY, then a summary line such as 5 shown of 7; more: true. An UNRESOLVED row reads no runnable task found at <loc>, and an UNMAPPED row reads entry is malformed. A - is a value the server did not return.

Narrow or page the list. These examples assume the App and asking Agent are already set, by your worktree binding or by --app and --agent as above:

hadron team register --code task.finish.open-children
hadron team register --task-loc tasks:finish-a-task
hadron team register --limit 50 --offset 50
hadron team register --limit 0
  • --code keeps one code; --task-loc keeps the codes whose entry names that location.
  • --limit is the page size: 20 by default, at most 200 (a larger number is capped by the server). --limit 0 returns only the count. Step through with --offset.
  • --json returns {entries, total, hasMore} and keeps every server value, nulls included. Gate on total, not on how many entries one page holds.

Unknown, foreign or unusable Agents give AGENT_NOT_FOUND (exit 4), and unknown, foreign or non-participant Apps give APP_NOT_FOUND (exit 4).

If you work against the API directly, the query is actionRegisterIndex.