my-task-api

---
name: my-task-api
version: 1.0.0
description: >
  Agent-task queue — file units of work, rank them, claim under a lease, then resolve, fail, or cancel. The agent-loop hot path.
triggers: [task, task queue, agent loop, work queue, claim task, resolve task, lease, backlog, to-do, assignee]
checksum: sha256-pending
---

# MyTaskAPI

A task is a unit of work that needs an agent or human to act on it. Tasks are ranked by score; a worker claims one under a time-limited lease, does the work, then resolves or fails it. This is distinct from `my-workflow-api` (event→action automation) and `my-queue-api` (durable machine jobs).

## Capabilities
<!-- llm:start -->
`task` is the **"this needs a decision"** layer — the agent-loop hot path.

The loop is: **`list` → `get <id> --body` → `claim` → `resolve`/`fail`**.

- `list` returns the top open tasks ranked by score, projected to `{id, description, score}`, plus a backlog signal — `Showing N of M open task(s)`. It is deliberately small; do not expect the full task.
- `get <id>` returns the full task object. It does **not** fetch the Markdown body.
- `get <id> --body` additionally fetches the **body tier** — the full Markdown context. Read it once, when you commit to a task.
- `claim <id>` takes an atomic lease (default 10 min). Lease expiry auto-reverts the task to open, so a crashed worker never strands a task. Heartbeat long work with `extend`.
- `resolve <id>` is terminal and unblocks dependents. `fail <id> --reason` is terminal and does not auto-retry. `cancel <id>` is terminal, distinct from fail.

Task fields at creation: `description` (~100-token triage key), `body` (full Markdown), `importance`, `due`, `assignee` (emails them a magic link), `tags`, `depends_on` (immutable DAG — a task with unresolved deps starts blocked), `dedup_key` (idempotent), `resolve_on` (an event matcher — a matching platform event auto-resolves the task), `source`.

**task vs workflow vs queue** — see `docs/orchestration-decision-guide.md`.
<!-- llm:end -->

## Commands
<!-- generated:start -->
| Command | What it does |
|---|---|
| `myapi task create "<description>" [--body <md\|@file>] [--importance <i>] [--due <rfc3339>] [--assignee <email>] [--tag <t,t>] [--depends-on <id,id>] [--resolve-on <event[:field=value]>]` | File a task |
| `myapi task list [--status <s>] [--tag <t>] [--importance <i>] [--limit <n>]` | Top open tasks, ranked |
| `myapi task get <id> [--body]` | Show a task; `--body` also fetches the body tier |
| `myapi task claim <id> [--lease <s>] [--worker <name>]` | Take an atomic lease |
| `myapi task extend <id> [--lease <s>]` | Heartbeat a live claim |
| `myapi task resolve <id>` | Resolve a task (terminal) |
| `myapi task fail <id> --reason "<why>"` | Fail a task (terminal) |
| `myapi task cancel <id>` | Cancel a task (terminal) |
<!-- generated:end -->

## Examples
<!-- llm:start -->
```bash
# File a task with full Markdown context from a file
myapi task create "Review the Q3 vendor contract" \
  --body @contract-notes.md --importance high --due 2026-06-01

# The agent loop
myapi task list                          # ranked; pick the top id
myapi task get <id> --body               # read the body, once, on commit
myapi task claim <id> --worker agent-7   # lease it
# ... do the work, heartbeat if long ...
myapi task extend <id>
myapi task resolve <id>                  # or: myapi task fail <id> --reason "blocked on legal"

# Event-driven: auto-resolve when a matching platform event fires
myapi task create "Ship once payment clears" \
  --resolve-on payment.succeeded:order_id=o_42
```
<!-- llm:end -->

## Notes

- `list` is the hot path — it returns a small ranked projection plus `total_open`, not full tasks.
- The body tier is fetched only with `get --body`. Read it once, on commit, to keep the loop token-cheap.
- A claim is a lease: it expires (default 10 min) and auto-reverts the task to open. Heartbeat with `extend`.
- `resolve` unblocks dependents; `fail` cascades to dependents that can never proceed.
- `resolve_on` matches platform events. Today few event kinds are emitted in production — verify the kind exists before relying on it.

Run `myapi task --help` for the full flag reference.