Tasks

Task assets are strict, local automation sources. They live at <bundle>/tasks/<id>.yml and can be run directly or reconciled to cron, launchd, or Windows Task Scheduler with akm task sync. The task file is authored source; scheduler entries are derived OS state.

Task source v4 (version: 4) is the only task source grammar akm reads. A document with version: 3 or version: 2 fails to load with UsageError code TASK_SCHEMA_VERSION_UNSUPPORTED, naming akm migrate apply, which converts it. A declared version: 4 document whose schedule[] still carries a per-entry enabled key — 0.9.15's v4 grammar accepted it, this release's does not — fails the same way with TASK_SOURCE_INVALID (activation is host-local, below). Each such file fails on its own: akm task sync reports it and keeps reconciling every other task. Task source v4 adds typed inputs: and a single bounded output: schema (command targets only), and makes scheduling OPTIONAL rather than mandatory. akm task add authors task source v4 directly.

If you have version: 3 or version: 2 files on disk (from an earlier akm release), see Migrating to task source v4 below — akm migrate apply converts both generations in one pass and rewrites the file on disk (akm upgrade runs it after an install). The retired v3 grammar itself is documented at the bottom of this page (Task v3 (retired): grammar reference for migration) purely so you can read an old file while migrating it; it is no longer accepted as a standing grammar by any command in this release.

Files and schema

The only recognized task extension is .yml. A .yaml near miss is never indexed, scheduled, or run. Every task should declare version: 4; a document with no version: key, or a version: that is not a number, fails with TASK_SOURCE_INVALID (must be exactly 4. / is required and must be exactly 4.) — a genuinely malformed v4 document, not a legacy one. version: 3 and version: 2 fail with TASK_SCHEMA_VERSION_UNSUPPORTED naming akm migrate apply (see Migrating to task source v4). The published task schema describes the hand-authored contract; src/tasks/source/task-source-v4.ts is the authoritative bounded parser.

version: 4
name: Nightly review
uses: workflows/nightly-review
inputs:
  strict:
    type: boolean
    default: true
schedule: "0 4 * * *"
timeout: 30000

Task YAML is bounded before expansion: source size, YAML depth, aggregate node count, mapping width, string size, and collection sizes all have finite limits. Aliases, merge keys, custom tags, duplicate keys, accessors, and non-plain data are rejected rather than normalized.

Executable targets: uses or run

A task selects exactly one of uses or run; the two fields are mutually exclusive.

uses accepts these target shapes:

• akm/command, the built-in inline/referenced command action. Its with object requires exactly one of with.ref or with.content; they are mutually exclusive. with.arguments is one optional portable string, used for the single, one-pass $ARGUMENTS substitution. with: is legal only alongside uses: akm/command — every other target uses typed inputs: instead (see Input flags).
• Asset refs rooted at commands/, workflows/, or scripts/, optionally qualified with a bundle such as team//commands/review.

A GitHub Action locator (owner/repo[/path]@ref, e.g. actions/checkout@v4) is not a recognized uses: shape — it fails at parse with TASK_SOURCE_INVALID alongside every other unrecognized target. AKM never acquired or executed a remote action in any release; this is the removal of a recognized-but-rejected spelling, not a capability that used to work.

Agent refs such as agents/reviewer are personas and are not executable. Task refs such as tasks/nightly are also not executable. Local actions (./action) are rejected and Docker actions (docker://image) are unsupported. GitHub expressions are unsupported and rejected before dispatch.

The runtime applies this target-by-target field matrix. Validation is strict; fields are not silently discarded.

Script refs use this closed table; any other extension fails before dispatch:

run is one non-empty shell string. It may specify shell from the closed host shell table bash, sh, zsh, pwsh, powershell, or cmd. Shell expansion is runtime behavior for an explicitly authored task run; AKM does not infer a shell from uses. working-directory must be a relative, contained path under the task's workspace root. Absolute paths, traversal, dangling links, and symlink escapes fail before execution.

Every field that used to live under v3's akm: options bag is a top-level key in task source v4: agent, engine, model, inference, tools, timeout, redact, maxSteps, and maxRetries, plus description, when_to_use, and tags. Environment entries (env) are literal string, number, or boolean values. Keep credentials out of task source; redact contains environment variable names, never secret values.

timeout: (milliseconds) means a different mechanism depending on the target. For run: (native shell/script) and workflows/<name> targets it is an outer supervisory deadline: the runner kills the child process, or aborts the workflow run at its next step boundary, when it fires. For uses: akm/command, commands/<name>, and any other agent/LLM dispatch target there is no outer process kill — timeout: instead resolves through the execution cascade (config/persona/command/task layers) into the dispatch's own deadline, and the SDK/CLI runner races each phase against it internally. Either way, a dispatch that times out is recorded as status: failed with detail.reason: "timeout" in task_history — not a silent completed — and akm task run exits non-zero for it; see health-advisories.md's task-fail-rate row for how akm health surfaces a timeout-dominant failure pattern.

Scheduling

Scheduling is optional. Omit schedule: entirely for a manual-only task: the source still parses, still runs with akm task run, and akm task sync silently contributes zero scheduler bindings for it (no OS entry, no failure) rather than rejecting the source for missing a trigger.

version: 4
name: Nightly review
run: akm improve --strategy default
schedule:
  - cron: "@daily"

A bare string (schedule: "0 8 * * 1") is shorthand for one trigger with no inputs. A list entry may set literal inputs; those literals are validated against the task's inputs: declarations both at parse time and again at akm task sync (once with declared defaults applied), and are delivered to the scheduled run: akm task sync compiles each entry's inputs into the scheduler binding's own invocation tail (akm task run <id> --scheduled --<name> <value>…, names sorted), so the fired run receives them exactly as akm task run <id> --<name> <value> would. Multiple schedule entries create deterministic scheduler bindings for the one source task.

Task source v4 has no enablement flag. A source describes what may run; it cannot authorize its own host scheduling. Activation is this host's list of fully-qualified refs in config.json under scheduler.enabled. A ref that is not listed is disabled. A config with no list at all (written before 0.9.17) means "keep what is installed": the first sync fills the list from the akm-written native bindings. Use akm task enable <bundle>//tasks/<id> and akm task disable <bundle>//tasks/<id> to change the list and immediately sync the affected bundle. akm task add enables its new task by default; --disabled writes the same task source but does not list it.

akm task run <id> executes a task immediately, including a disabled task. akm task sync scans every enabled configured bundle, reads only locally activated task/workflow refs, and reconciles the native scheduler one row at a time (see Operations). --bundle <name> narrows that pass to one active bundle. If every configured bundle is disabled, sync removes the attributable native entries without reading task content. Workflow targets create a fresh durable workflow freeze at fire time.

Typed inputs and output

version: 4
name: Review code
description: Summarize a pull request's changed surface
inputs:
  scope:
    type: string
    enum: [changed, all]
    default: changed
  strict:
    type: boolean
    default: true
  ticket:
    type: string
    required: true
output:
  type: object
  properties:
    summary: { type: string }
uses: commands/review
schedule:
  - cron: "0 8 * * 1"
    inputs: { scope: all, ticket: OPS-1234 }
timeout: 45000
engine: reviewer
redact: [TOKEN]

• inputs: declares named, typed parameters. Each declaration is a bounded JSON Schema (type, enum, properties, items, minimum/maximum, allOf/anyOf/oneOf/not, and similar keywords — an unlisted keyword is rejected) plus two keys unique to task source v4: default (which must itself satisfy the rest of the declaration) and required: true (mutually exclusive with default). Declaration names follow the same identifier grammar as workflow parameters, and additionally may not name a flag akm task run already declares for itself — bundle, format, detail, shape, output, scheduled, quiet, verbose, help, no-quiet, or no-verbose. Parsing rejects a colliding name with TASK_SOURCE_INVALID at declaration time, since akm task run --<name>, akm task explain --<name>, and a schedule[].inputs entry would otherwise route the value into akm task run's own flag instead of the declared input.
• A required: true input with no default must be satisfied by every schedule binding. A scheduled run supplies no input flags — the entry's own inputs: literals plus the declared defaults are the whole value set it gets — and a required: true input may not carry a default, so an entry that names no value for one could never run. Parsing rejects that contradiction with TASK_SOURCE_INVALID at the offending entry's own field path (schedule, or schedule[<i>]), naming the unsatisfied input. The rule covers every entry: the schedule: "<cron>" string shorthand, a list entry with no inputs: key, and an entry whose inputs: mapping is present but incomplete. akm task sync keeps its own equivalent check over the defaulted values and still rejects the whole desired set before touching any scheduler state. Give every schedule entry an explicit value for the input, or declare a default instead; manual runs are unaffected — a task with no schedule: stays valid whatever it requires, and akm task run takes the value from the input's own flag.
• output: is a single bounded JSON Schema, replacing v3's akm.outputSchema. It is legal only on a command target (uses: commands/<ref> or uses: akm/command), where it is forwarded to the prepared invocation as a response-shaping schema. run:, uses: scripts/, and uses: workflows/ executions have no output-schema consumer — a native run's status comes from its exit code alone — so declaring output: on them fails parsing with TASK_SOURCE_INVALID instead of silently recording a contract nothing enforces.
• A task source v4 document can be the target of a workflow step's uses: tasks/<ref> — see the GitHub-shaped YAML subset for how a workflow step's with: binds a v4 task's declared inputs:.

Input flags

akm task run <id> accepts one exact-name flag per declared inputs: entry, mirroring akm workflow run's parameter flags:

akm task run review --scope all --strict  # doclint:ignore

Flag names are task-specific — they come from that task's own inputs: declarations — so they are not listed on akm task run --help and the example above uses one task's actual declared names, not a fixed syntax. An undeclared flag fails with UNKNOWN_FLAG; a value that does not satisfy its declaration, or a missing required: true input supplied by neither a flag nor a default, fails with INPUT_BINDING_INVALID — both exit 2 with the usual {ok:false,error,code} envelope on stderr.

Where the materialized values go next depends on the task's own target, and is narrower than it may look: when the target is uses: workflows/<ref>, the values become the child run's params (the same with: → params path a workflow step's own composition uses); for every other target — run: shell, scripts/<ref>, commands/<ref> — the values are validated and then discarded. akm task run's own flags never populate an AKM_TASK_INPUTS environment variable or a ## Task inputs prompt block. Those two surfaces are a different delivery path: they exist only when a workflow step composes this task through uses: tasks/<ref> and a with: binding, resolved fresh for that step's own dispatch — see with: on a task-composed step. A scheduled run (schedule[].inputs, above) reaches the target through this same akm task run path, so it inherits the identical rule: delivered as params for a workflows/<ref> target, otherwise validated and discarded. akm task explain (below) shows the materialized values regardless of where they end up, which is the fastest way to check what a given akm task run invocation would actually deliver. akm task add --params renders --params values as typed inputs: declarations with default: values (typed from each JSON value's runtime type), not a with: bag.

akm task explain

akm task explain <ref> [input flags] prints a task's source path and version, its declared inputs: (name, type, enum, required, default), the values that would actually be supplied — with provenance (default | flag | schedule-binding) — the resolved target kind/ref, effective execution settings with field-level provenance, and schedule bindings. It is read-only: it never spawns anything, writes history, or touches the scheduler. A secret-shaped value (a declared default, a supplied value, or a schedule binding's literal) prints as "<redacted>" with its row marked redacted: true instead of the real value; an env: binding is shown as a name/ref only, never its resolved value.

akm task explain review --scope all  # doclint:ignore

akm task explain's default output (no --format flag) is the same raw JSON as --format json, byte for byte — there is nothing to lose by piping the default form into jq or a script. --format text is a separate renderer: it flattens the same envelope into dotted.path=value lines (the same convention akm config list --format text uses), not a copy of the JSON.

A secret-shaped input default (as opposed to a supplied value) is redacted the same way, but its accompanying explanation currently reuses workflow-parameter wording that does not quite fit a task input — treat the redaction itself as reliable even where the prose reads oddly. akm task run --<name> <secret-looking-value> never echoes the offered value in its error envelope, whether the value fails typed-flag coercion or fails the declared schema (an enum/minimum/maximum mismatch included) — both paths report only the violated constraint.

Migrating to task source v4

akm migrate status and akm migrate apply [--dry-run] run both migration generations against your task tree in one pass: task-v2 → task-v3 first, then task-v3 → task source v4 against the resulting files. Each generation keeps its own lock, backup, prevalidation, and rollback — a file blocked in the first generation does not stop the second generation from converting files that are already version: 3.

akm migrate apply --dry-run
akm migrate apply

The planner reports every input file as changed, skipped, or blocked, for both generations combined. Resolve every blocked file manually, then preview again. Apply validates a complete replacement before writing and backs up each original immediately before replacement.

Common v2 → v3 blocked reasons and what to do about each — these need a hand-authored replacement, not a re-run; see the 0.9.1 to 0.9.2 migration guide for the full v2 to v4 field mapping (command: array → run: + shell:, timeoutMs: → timeout:). Source-owned enabled fields are removed; native bindings that are provably enabled seed the host-local activation list:

Common v3 → v4 blocked reasons and what to do about each:

The migrator translates structure, never intent: it never invents an inputs: declaration on a file's behalf, regardless of how inferable a with: value's shape looks — declaring inputs: (and rewriting a step to bind it) is left to the person editing the migrated file by hand.

A changed file can still carry an informational notice alongside its converted bytes, for a translation that is faithful but not one-to-one. Each notice is reported on that file's own plan entry, and it is the only record of a field the migrator resolved by dropping rather than rewriting — read them. Two cases produce one today:

• akm.outputSchema on a run:, uses: scripts/, or uses: workflows/ target is dropped, not hoisted to output:. v4 accepts output: only on a command target (uses: commands/<ref> or uses: akm/command) — the only kinds whose runtime enforces it — and on the other three v3 never enforced it either, so nothing enforceable is lost. The file migrates as changed with a notice naming the dropped field; it is not blocked, and there is nothing to edit by hand first. If you wanted that schema enforced, move the work behind a command target and author output: there.
• on.workflow_dispatch with no on.schedule drops silently, since every v4 task is runnable manually with akm task run whether or not it has a schedule:. The migrated document simply has no schedule: key.

The migrator is also installed as its own executable, akm-migrate, with the same status / apply [--dry-run] surface; akm migrate wraps it, and akm upgrade runs apply after installing a release. A tree that is already all version: 3 simply reports the first generation as current.

See the 0.9.1 to 0.9.2 migration guide for full before/after examples and recovery guidance.

Operations

• akm search --type task (or its alias akm task list) and akm show tasks/<id> inspect task assets.

• akm task explain <ref> prints a task's declared inputs, resolved target, effective execution settings, and schedule bindings without running anything — see akm task explain above.

• akm task validate <path> parses one task file by filesystem path (the file need not live in a configured bundle) and reports the same valid/blocked/invalid/not-a-task diagnostic akm task sync would produce for it — including sync's own cron-dialect check and its per-schedule-entry input-contract check — without touching the scheduler and without requiring a configured engine, even for a command-kind task. The envelope's own sourceVersion field names the file's declared schema version. A version 2/3 file, and a version: 4 file still carrying a retired schedule[].enabled, report blocked (exit 1) naming akm migrate apply, which converts them.

• akm task add validates a task source v4 document, writes it, adds its ref to local scheduler activation, and syncs its bundle. --params renders typed inputs: declarations instead of a with: bag; --schedule is required on every invocation. --disabled writes the same source but leaves the ref out of activation. --force overwrites an existing task of the same id; without it add refuses. Add also refuses, before writing anything, when the id is already scheduled from another bundle or installation. If the row itself cannot be installed, add fails and says so; the task stays written and enabled, and the next akm task sync retries it.

• akm task history reads durable run history from state.db.

• akm task enable <ref> / akm task disable <ref> change only local scheduler config, then reconcile that bundle.

• Delete the .yml source and sync to remove its derived binding(s).

• akm task sync reads the installed rows once, compares each against what its source renders, and installs, rewrites, or removes rows one at a time. A row that fails to install or remove is reported in failures and every other row still applies. A source that fails to parse is reported the same way, and its installed row is left exactly as it is. Rows akm cannot attribute to a bundle this sync covers — another bundle's, another installation's (the row's AKM_BUNDLE_DIR names a different working stash), or anything outside akm's # akm:task markers, com.akm.task. labels, or \akm\ task folder — are never touched. A Task Scheduler row is compared by the fingerprint akm writes into its <Source> plus its enabled state, so an edit made in Task Scheduler that keeps that fingerprint is left alone.

• akm task sync, add, enable, disable, and prune --yes hold one lock file, $STATE/locks/scheduler.lock, while they read and write the native scheduler. A second one started meanwhile exits 75 (retry shortly); a lock left by a process that is no longer running is reclaimed.

• akm task sync --dry-run previews the reconcile (adds/updates/removes, removals annotated with their owning bundle) without writing to the scheduler; exits non-zero when removals are pending.

• akm task prune removes installed scheduler entries sync cannot reach because they no longer resolve to a live bundle: a row whose AKM_BUNDLE_DIR names a directory that is gone, or a row written before 0.9.17-alpha.7 whose --scheduler-context descriptor cannot be read. It never touches an entry that still resolves to a live bundle. Defaults to a dry-run preview (zero writes); --yes executes it; --id <id1,id2,...> scopes to specific ids and refuses any id that isn't a current orphan candidate.

• A plain sync keeps each installed row's launcher. Use akm task sync --rebind only when deliberately changing the captured AKM runtime, then verify with akm task doctor. When the launcher sync writes runs akm from a source checkout (src/cli.ts, a local build, or a package inside a git work tree), sync says so once: scheduled runs then run whatever the checkout holds.

• akm task sync writes one PATH= line inside a # akm:env BEGIN/END section directly above the first akm task block in the crontab (on macOS, an EnvironmentVariables entry in each plist). It is the PATH of the shell that ran the sync, rewritten on every crontab write and removed with the last akm block; cron applies it to every row below it.

• A task's row is its command plus its schedule: <launcher> task run <id> --bundle <bundle> --scheduled, and it sets its own environment. Every row sets AKM_BUNDLE_DIR to the working stash of the shell that ran the sync (its AKM_BUNDLE_DIR, or the default bundle), so the scheduled run uses the same working stash, --bundle finds a stash no config names, and sync tells rows of other installations sharing the scheduler apart (#846). Rows synced from a shell that set AKM_CONFIG_DIR, AKM_DATA_DIR, AKM_CACHE_DIR or AKM_STATE_DIR explicitly set those too. Each backend does it its own way: a VAR=value prefix in the crontab, an EnvironmentVariables entry in the plist, a $env:VAR='value'; assignment ahead of the command in Task Scheduler. Other defaults resolve at fire time, so a scheduled run uses the same state, data and cache directories an interactive command does. Run the sync from a shell whose environment you would want scheduled.

  15 2 * * * AKM_BUNDLE_DIR=/home/u/akm /home/u/.bun/bin/bun /home/u/.bun/lib/node_modules/akm-cli/dist/akm task run nightly --bundle work --scheduled > /home/u/.cache/akm/tasks/logs/nightly.log 2>&1
  

  A row whose command is over 1,000 bytes runs a wrapper script under the log directory instead (sh <log dir>/.akm-cron-wrapper-<id>-<hash>.sh); sync reads the script to tell which task the row runs.

  Releases 0.9.0 through 0.9.17-alpha.6 wrote a --scheduler-context <file> argument into each row instead, naming a descriptor file under $DATA/tasks/context/ that held the same values. akm still applies that file when such a row fires, and the first akm task sync after upgrading rewrites each row in place: it shows as an update, keeps the row's launcher and schedule, and sets the values inline. A row the sync leaves as it is (its task file failed to load, or a --bundle sync did not cover it) still names its file; once akm task doctor lists no binding with a contextPath, the old descriptor files are not read and can be deleted.

Scheduler execution is at least once. Backends provide a stable invocation identity and AKM fences stale attempts, but an ambiguous process crash can be observed only after the external work has started. Make scheduled side effects idempotent where possible.

Task v3 (retired): grammar reference for migration

Nothing in this section is accepted by src/ in this release — it exists only so you can read an already-authored version: 3 file while deciding how to migrate it. The v3 grammar used an akm: options bag, an on: trigger block, and exactly one required scheduling source:

version: 3
name: Nightly review
uses: workflows/nightly-review
with:
  strict: true
akm:
  schedule: "0 4 * * *"
  enabled: true
  timeout: 30m

or, with the GitHub-shaped local trigger subset:

version: 3
uses: commands/review
on:
  schedule:
    - cron: "0 6 * * *"
  workflow_dispatch: {}

with: on any uses: target carried v3's untyped params bag (workflow refs consumed it as run params; command/script refs rejected it outright). A GitHub Action locator (owner/repo[/path]@ref) was a recognized uses: shape that was always rejected before dispatch — remote action acquisition was never implemented in any akm release. akm.enabled was source-owned scheduling state. akm migrate apply removes it; migration preserves actual host activation only when the native scheduler proves that the corresponding binding is enabled.

See Migrating to task source v4 above to convert a file out of this grammar.

See also

• CLI Reference: task
• Scheduling guide
• Workflow source formats
• Data and telemetry