AkurAI-Tasks

AkurAI-Framework-based task and Kanban service for work spanning multiple projects and repositories. One Rust process exposes the same command core through CLI, authenticated REST, MCP over stdio/HTTP, and a no-build web application.

The vertical slice is deployed through AkurAI Build, but it is not yet the authoritative replacement for legacy task sources. Remaining authorization, recovery, immutable-artifact, lossless-import, and cutover gates live in AkurAI Notes note 139 (AkurAI-Tasks — PLAN).

What works

• multiple projects, each scoped to zero or more owner/repository identifiers;
• project task IDs (PROJECT-1, PROJECT-2, …) and nine-state Kanban boards;
• revision-checked adjacent transitions, blocking, dependencies, Ready frontier, claims, evidence, comments, durable handoffs, and append-only audit events;
• actor-scoped idempotency for every mutation;
• one embedded AkurAI-Framework BTree commit for projection, event, and idempotency result;
• CLI, authenticated REST, a 25-tool MCP 2025-11-25 surface, and responsive web UI;
• bearer authentication and same-origin enforcement for REST and Streamable HTTP MCP.

Build and check

Run on Titan from the repository root:

./scripts/check.sh

The gate runs the Rust workspace tests, builds the binary, creates a real temporary multi-repository project and task through the CLI, reads its board, and exercises MCP over stdio. The API tests cover authenticated reads/mutations and same-origin rejection.

Run locally

Keep the token in the process environment or AkurAI PassVault-backed deployment environment; never commit it:

export AKURAI_TASKS_TOKEN='replace-with-a-local-token'
export AKURAI_TASKS_ACTOR='local-operator'
cargo run -p akurai-tasks -- \
  --db data/tasks.db \
  serve --host 127.0.0.1 --port 8090 --frontend frontend

Open http://127.0.0.1:8090. Enter the same token in the in-app session dialog. The browser keeps it in sessionStorage, so it is removed when the tab session ends.

For a separate public origin, set AKURAI_TASKS_ALLOWED_ORIGIN to the exact origin. Same-origin browser requests work without that override.

CLI

Install or refresh the Titan-local release binary through the maintained suite:

akurai-data-cli install
akurai-data-cli status
akurai-tasks help

This installs a local operator/development CLI only. It does not deploy AkurAI-Tasks or make the service a production source of truth.

Global flags may appear before or after the command:

export AKURAI_TASKS_DB=data/tasks.db
export AKURAI_TASKS_ACTOR=olafur

cargo run -p akurai-tasks -- \
  --idempotency project-akurai \
  project create AKURAI "AkurAI services" olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework

cargo run -p akurai-tasks -- \
  --idempotency task-command-core \
  item create AKURAI "Finish command core" \
  --repo olibuijr/AkurAI-Tasks --priority high

cargo run -p akurai-tasks -- project update AKURAI olibuijr/AkurAI-Tasks,olibuijr/AkurAI-Framework
cargo run -p akurai-tasks -- item set-repo AKURAI-1 olibuijr/AkurAI-Tasks
cargo run -p akurai-tasks -- board AKURAI
cargo run -p akurai-tasks -- frontier AKURAI

Repository binding

A work item's repo must name a repository the project registers. When a project registers exactly one repository the item repo is auto-filled; when it registers several an explicit --repo is required, and an unregistered or missing repo is rejected. Use project update KEY REPOS to register repositories on an existing project and item set-repo ID REPO to move an existing item onto one. The MCP equivalents are project_update and work_set_repo.

Run akurai-tasks help for transition, claim, dependency, comment, evidence, block, and handoff commands. Supply explicit idempotency keys for automation; the CLI generates one only for interactive calls.

REST

All /api/* routes except /api/health and /api/ready require:

Authorization: Bearer <token>
X-AkurAI-Actor: <stable principal>
Idempotency-Key: <required on mutations>

Primary resources:

GET  /api/projects
POST /api/projects
POST /api/projects/{key}/repos
POST /api/projects/{key}/archive
POST /api/projects/{key}/unarchive
POST /api/projects/{key}/delete
POST /api/projects/{key}/purge
GET  /api/projects/{project}/board
GET  /api/projects/{project}/frontier
POST /api/items
GET  /api/items/{id}
POST /api/items/{id}/repo
POST /api/items/{id}/transition
POST /api/items/{id}/claim
POST /api/items/{id}/dependency
POST /api/items/{id}/comment
POST /api/items/{id}/evidence
POST /api/items/{id}/handoff
POST /api/items/{id}/accept-handoff
POST /api/items/{id}/block

MCP

Stdio mode never opens a second production database in the intended deployment topology; run it against a local database only during development:

cargo run -p akurai-tasks -- --db data/tasks.db --actor agent-id mcp

The serving process exposes the same JSON-RPC dispatcher at authenticated POST /mcp. The 31-tool catalog covers projects (create, update, archive, unarchive, delete, purge), repository binding, work create/list/get/query, transitions, claims and lease renewal/release, comments, evidence, dependencies, handoffs, blocking, boards, Ready frontier, imports, audit events, and system_doctor. It also exposes tasks://projects and the next-task prompt. project_delete removes an empty project only; project_purge deletes a project with all its work items and history; project_archive/project_unarchive toggle the reversible archived flag.

Run a local catalog check without touching production data:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' |
  akurai-tasks --db /tmp/akurai-tasks-catalog.db --actor local-catalog mcp

Architecture and boundaries

• Framework checkout: /home/olafurbui/Projects/AkurAI-Framework on Titan.
• Hindsight remains authoritative for conversational memory.
• AkurAI Notes notebook AkurAI-Tasks (ID 34) remains the architecture/operations record.
• AkurAI PassVault folder AkurAI-Tasks (ID 5) is the only approved credential store.
• ACP connects editors to agents; AkurAI-Tasks is the MCP tool server, not an ACP task store.
• Agents operate persistent Tasks, Notes, Memory, PassVault, and Build state through configured MCP tools only. CLI examples in this README are local development examples with disposable state.

See AkurAI Notes note 139 (AkurAI-Tasks — PLAN) for production hardening, lossless import, backup/restore, source fencing, deployment, and cutover acceptance gates.