# @agimon-ai/doompi-task

Track persistent, dependency-aware tasks in Pi and optionally delegate them through DoomPi Team.

Part of the [DoomPi distribution](https://www.npmjs.com/package/@agimon-ai/doompi).

Task owns task records and `tasks.json`. Team owns agents and runs. When both are loaded, Task delegates pending work through Team without merging their stored state.

> **Alpha:** task and delegation contracts may change between releases.

## Requirements

- Node.js 22.19.0 or newer
- Pi 0.85.0 and Pi TUI 0.85.0

## Install

Define a layer and select it in `.doom/modes.yaml`:

```yaml
layers:
  task:
    packages: ['@agimon-ai/doompi-task']

majorMode:
  minimal:
    description: Lean mode with persistent tasks.
    layers: [task]
```

For standalone Pi:

```bash
pi install npm:@agimon-ai/doompi-task
```

Task works without Team for local graph management. Add `@agimon-ai/doompi-team` to the same
selected mode when `assign` and `cancel` should launch or control subagents.

## Use the `task` tool

Supported actions are:

| Action        | Purpose                                                            |
| ------------- | ------------------------------------------------------------------ |
| `upsert`      | Create tasks or update status, metadata, dependencies, and details |
| `list`, `get` | Read the graph or one task                                         |
| `delete`      | Tombstone a task                                                   |
| `clear`       | Close and reset the graph after active delegations stop            |
| `assign`      | Delegate a pending, unblocked task through Team                    |
| `cancel`      | Stop a delegated run and return its task to pending                |

```json
{
  "action": "upsert",
  "tasks": [
    { "ref": "design", "subject": "Design the API" },
    {
      "subject": "Implement the API",
      "blockedBy": ["design"]
    }
  ]
}
```

The reducer enforces lifecycle transitions and rejects dependency cycles. A graph allows 15
non-deleted tasks by default; updates still apply when full, but new tasks are rejected until space
is freed.

## TUI

Use `/tasks` or `SPC t l` to open the interactive task view. These surfaces require a TUI. The
`task` tool remains available in headless sessions.

## Storage and cleanup

The default session-tree store is:

```text
~/.pi/agent/doom-task/<session>/tasks.json
```

Task is authoritative across transcript compaction because the graph is file-backed. This does not
mean Task persists Team membership, intercom, or child-process state.

Defaults and overrides:

| Setting                           | Default        | Purpose                                    |
| --------------------------------- | -------------- | ------------------------------------------ |
| `DOOM_TASK_MAX_TASKS`             | `15`           | Maximum non-deleted tasks                  |
| `DOOM_TASK_STORE_TTL_MS`          | 30 days        | Retention for inactive session-tree stores |
| `DOOM_TASK_DELEGATION_TIMEOUT_MS` | 20 minutes     | Delegated-run result timeout               |
| `DOOM_TASK_STORE`                 | Unset          | Override the complete store file path      |
| `DOOM_TASK_COLLAPSE_KEY`          | `ctrl+shift+t` | Override the task-view collapse key        |

Startup reconciliation removes expired stores and repairs delegation records whose owning process
is no longer live.

## Task and Team together

Task uses Team's delegation service and records its lifecycle events on the task. It also contributes
pending assignments through `doom/background-work`. Team discovers the selected agent, applies
model and tool policy, owns the run, and returns completion or failure. If Team unloads or is
replaced, both connections are removed and rebound without leaving a process-global registration.
Intercom and Team membership remain Team state; `tasks.json` remains Task state.

## Public API

```ts
import { detectCycle, isBlocked, TaskStore } from '@agimon-ai/doompi-task';
import type { Task, TaskStatus } from '@agimon-ai/doompi-task';
```

Focused subpaths include `/tool-schema`, `/store-reducer`, `/store-task-store`,
`/delegation-manager`, and `/tui-selectors`. Pi loads `/extensions/pi` through package metadata.

## Source layout

The host entries are generated from `src/extensions`. Pi and headless session roots hold each
session's store, delegation manager, startup work, service injection, and cleanup. Their tools,
commands, hooks, and resources register from files beside the roots. The global backend channel
publishes task graph updates. The session frontend owns the cockpit channel and Activity dock
section, plus Task Space, the terminal widget, and the task tool renderer. Shared task rules and
persistence stay in `src/services`; the published compatibility APIs remain in `src/exports`.

## Development

Run from this package directory in the workspace:

```bash
pnpm build
pnpm typecheck
pnpm test
pnpm lint
```

Maintained by [Agimon](https://agimon.ai/about).

## License

MIT

Named Pi and server factories live in `src/extensions`. Controllers declare commands, tools consume services, and `models` contains the durable task document types and graph. Services own persistence, delegation, and configuration. Public entries are flat files in `src/exports`, with flat package subpaths. Pi shutdown aborts the factory signal to fence pending session initialization immediately; idempotent `onStop` and `onDispose` cleanup awaits pending work before disposing the store and telemetry.