App-defined actions¶
An App can record its own named steps as events in its team stream, and
route each one to a role task through the
register. The code of such an action
is app.<appSlug>.<name>. You record one with recordAppAction (GraphQL) or
hadron app action record (CLI), and read them back with
agentTeamEvents or hadron team events --code-prefix.
Built on server main, not on a deploy
This page is written against hadron-server main at
e0116470
and hadron-cli main at
1e050c37.
The CLI command first shipped in release v0.37.0, and the
GraphQL reference here mirrors what production serves,
so it does not list recordAppAction until the server is deployed with it.
Check hadron app action --help before you rely on the command: it is
unknown on a CLI older than v0.37.0.
The code¶
| Rule | Value |
|---|---|
| Prefix | app. followed by the current slug of the App you record in. A code that names another App's slug is refused. |
| Characters | Lower-case letters, digits and -. The <name> part may itself contain more .-separated segments, and each segment after the slug must start with a letter or digit. |
| Length | At most 64 characters in all, counting app. and the slug. A slug over 58 characters leaves no room for a name. |
| Shape | The whole code must be a legal URN atom, so it starts and ends with a letter or digit. |
An invalid code, or a code for another App's slug, is refused with
APP_ACTION_CODE_INVALID. The CLI checks the grammar before it sends
anything and exits 2; the server alone checks the current slug.
The three legacy app. types¶
Three older platform event types also start with app.:
app.properties-changed, app.credential-act and app.manager-act. They are
written by the platform, not App codes, and you cannot record them with
recordAppAction. They appear when you read with a bare app. prefix
(below); the app.<slug>. prefix leaves them out.
Recording¶
mutation {
recordAppAction(
appRef: "acme.com:eng"
code: "app.eng.design.approved"
taskRef: "AT0.7"
payload: { review: "done" }
) {
eventId
action { code state taskLoc taskUrn }
}
}
hadron app action record app.eng.design.approved --app acme.com:eng
hadron app action record app.eng.design.approved --task AT0.7 \
--payload '{"review":"done"}' --json
| Argument | Meaning |
|---|---|
appRef / --app |
The App. The CLI uses --app or the active App. |
code |
The code. |
taskRef / --task |
Optional. A readable task in this same App, by id or handle. An unknown or foreign task is refused TASK_NOT_FOUND. A bare handle may need qualifying when you belong to several Apps. |
payload / --payload, --payload-file |
Optional JSON object. Omitted becomes {}. Give one of the two flags, not both. |
Who may record. The caller needs the same authority as for creating a root task: a person who takes part in the App, a worker acting through its session, or a headless run in its own App (where a root task comes from). The server judges the caller; the CLI makes no authority check of its own.
Each call appends a new event. Retries are not deduplicated. If the outcome is unknown, for example a lost response, read the events before you record again: the first call may have succeeded. The CLI sends one mutation and never retries.
The payload¶
- A JSON object of at most 4096 UTF-8 bytes. An explicit
null, an array or other non-object, NUL, or an unpaired surrogate in a key or value is refusedBAD_USER_INPUT(CLI exit 2). - Everyone in the App can read it, and so can the App's own key, with or
without a
taskRef. Put nothing secret in it. - It is stored as the event's payload, wrapped as
{payload: …}.
A task-bound action does not count as acting on the task¶
Passing taskRef ties the event to the task for reading, but it is passive.
It never acknowledges an assignment or a child-finished wake, so those wakes
stay due. To act on a task, use the task's own commands.
What the register answers¶
Every successful call returns the register's answer for the code, read as
the caller, in action:
state |
taskLoc |
taskUrn |
Meaning |
|---|---|---|---|
MAPPED |
the task's loc | the task | A readable register:<code> entry exists and the caller's own Agent chain resolves a runnable task. |
UNMAPPED |
none | none | No mapping in the readable Team Agent chain, or the App has no single Team Agent. |
UNRESOLVED |
the task's loc | none | The entry is readable but its loc has no usable task. |
WITHHELD |
none | none | Code only: resolve the task yourself. Includes a failed read. |
The register is how you route the action to a role task. The entry is a node
named register:<code> in the Team Agent's system memory, as described under
the register. The answer is guidance.
It is never an authorization decision: it does not say you may do the
task, and it does not stop the event being recorded.
Who resolves it. A worker resolves the code through its own Agent chain,
so the same code can reach each role's own task. A caller with no Agent,
such as a person, gets WITHHELD with the code only, no loc, no URN, and the
server does no register lookup for them. A person is never resolved through
the Team Agent's chain. (Ruling 0159; the spec text is
cor:agt:110:03.)
Renaming the App¶
The slug in the code is checked against the App's current slug. After
an App rename, recording an old code is refused APP_ACTION_CODE_INVALID,
and the code under the new slug has no register entry until you map one: the
entry is a node named for the full code. This is the interim reading (ruling
0152); the specs have not been amended to say it.
Reading them back¶
agentTeamEvents takes a codePrefix: a literal prefix on the event type,
which intersects types when both are given. An empty prefix matches
everything. In the CLI it is team events --code-prefix, and it combines with
the other filters.
| Prefix | What it returns |
|---|---|
app.<slug>. |
Only this App's recorded actions. |
app. |
Those, and the three legacy platform types. |
Omitting the flag leaves the query exactly as before. Events come oldest first, as for any team events read.
Refusals¶
| Refusal | When | CLI exit |
|---|---|---|
APP_ACTION_CODE_INVALID |
Not the grammar, over 64 characters, or another App's slug. | 2 |
TASK_NOT_FOUND |
taskRef is unknown, foreign or unreadable. |
4 |
BAD_USER_INPUT |
The payload is not an object of at most 4096 bytes. | 2 |
A caller without the creator authority is refused as for creating a task. The
server conceals that refusal as APP_NOT_FOUND, which the CLI reports as exit
4 (not found), not as forbidden. Exit 8 (forbidden) applies only to refusals
the server reports as FORBIDDEN.
Related¶
- Team task warnings: the register, its entries and the three answer states.
- Route your App's own steps to a role task: a worked example.
- The action register index: how a code finds its task.
hadron app action recordandteam events.