Skip to content

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

app.<appSlug>.<name>
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 refused BAD_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.

hadron team events --app acme.com:eng --code-prefix app.eng.

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.