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

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.

Commands

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)

Examples

# 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

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.