Skip to content

Team task handles

A task's handle is AT<n>(.<n>)*: for example AT3, AT3.405 or AT0.388. It is a short alias for the task's id. Anywhere the server or the MCP tools take a task id, they take the handle too.

Proposed

These rules are built in the server (hadron-server#2579) and are being confirmed; they may change. The wording follows spec cor:agt:050:01, Entity: Agent task. Examples marked illustrative need that server change deployed; none has been run against production. The CLI is not covered here: it follows with hadron-cli#1131.

For what a task is and why a team keeps projects, see Team tasks.

Grammar

Part Meaning
AT Fixed prefix.
First number The project, counted per App from 1. AT3 is the third project of its App.
Each later number A task, counted per parent. AT3.405 is the 405th child of AT3; AT3.405.16 is the 16th child of that.

One segment per level of the tree the task sits in. A segment with a leading zero is malformed, and so is a zero anywhere below the project level. AT0 and AT0.388 are valid.

AT0: no project

Project number 0 is reserved. The platform creates AT0 once for each App, and nothing else ever takes the number 0. AT0 means no project: a task created with no project and no parent becomes a child of AT0, such as AT0.388.

AT0 is a row the platform makes for you, with the fixed title "No project" and the backlog status, so it is never matched to a worker and never raises a stall alarm. Read it only by its id or handle. Listings of root tasks (rootsOnly) return the projects and the AT0.<n> tasks, never AT0 itself. finish, cancel, start, assign, make ready and every update of AT0 are refused.

AT0.388 is not GitHub issue #388. A task's source keeps the link to its issue; the handle is a different number.

Create a project

Ask for a project when you create a task: set project: true. A project has no parent and takes the next project number from 1. Asking for a project together with a parent is refused. Creating a project needs no authority beyond the one creating any task needs.

A create that asks for neither a project nor a parent becomes a child of AT0, so the stored handle always matches the tree.

Over MCP this is the project input on hadron_task_create (illustrative: needs the

2579 deploy).

Permanence

  • A task's handle never changes. A task's parent is fixed when it is created: you can't move a task under another project or parent, an attempt is refused, and a different project needs a new task.
  • Once a task exists, its handle is never given to another task, whatever becomes of that task. Gaps in the numbers are normal.
  • A create that fails gives no task, so it keeps no handle.

One App, and the qualified form

A bare handle means a task of one App. A caller acting as one App (an App key, a worker session) means that App.

A person who belongs to several Apps and gives a bare handle is refused and told to qualify it. That refusal depends only on how many Apps you belong to, never on whether any task carries the number.

The qualified form names the App by the App part of a task's URN, its root and App slug:

hrn:agenttask:<root>:<app-slug>:AT<n>(.<n>)*

An earlier form of that address keeps resolving after a rename, as URN composition sets out.

Refusals

You give You get
A handle that names no task you may read, including another App's The same answer as an unknown id. It never says whether another App has such a task.
A qualified handle Never reaches past your own access to the App it names.
A bare handle, from a person in several Apps Refused, and told to qualify it.
A malformed handle Refused.
project together with a parent Refused.
An attempt to move a task under another parent Refused.

Why the numbers are per App and per parent

A platform-wide count would show anyone who sees one number how many tasks other Apps create. A count per parent means creates under different parents don't contend, and one parent's count shows only what you could already see.