Tasks

A task is a persisted unit of work assigned to one agent. Tasks can run independently or be generated when a mission executes.

Create a task

const task = await client.createTask({
  title: "Build the authentication endpoint",
  description: "Implement POST /v1/login and add integration tests.",
  assignTo: "backend-dev",
  expectations: [
    { type: "test", command: "pnpm test auth" },
    { type: "file_exists", paths: ["src/routes/login.ts"] }
  ],
  expectedOutcomes: [
    { type: "file", label: "Login route", path: "src/routes/login.ts" }
  ]
});

The REST endpoint is POST /v1/tasks. It requires title, description, and assignTo; optional fields include draft, loop, expectations, expectedOutcomes, dependsOn, group, maxDuration, retryPolicy, notifications, sideEffects, executionMode, sandbox, and user. user is opaque attribution metadata. Polpo persists and propagates it but does not authenticate it. Use sandbox.isolation to choose whether a run can reuse a warm sandbox or must start fresh:

await client.createTask({
  title: "Run migration tests",
  description: "Apply migrations in isolation and report failures.",
  assignTo: "qa-agent",
  sandbox: { isolation: "fresh" }
});

Task and request sandbox policy overrides the agent default. See Runtime Sandboxes.

Persisted task

The runtime adds fields such as id, status, retries, maxRetries, timestamps, phase, result, outcomes, deadline, and priority. result contains process output and the current assessment; older assessments are retained in assessmentHistory. expectedOutcomes declare artifacts the agent should produce. Each entry requires type and label, with optional description, path, mimeType, required, and tags. Actual outcomes are registered at runtime as file, text, url, json, or media artifacts.

Dependencies

For a standalone persisted task, dependsOn contains task IDs. Inside a mission document, dependsOn contains unique task titles because IDs do not exist until mission execution.

Status and phase

Task statuses are:

draft -> pending -> assigned -> in_progress -> review -> done
                    |             |           |
                    +-------------+-----------+-> awaiting_approval
                                                -> failed -> pending

The exact valid transitions are:

From	Allowed next states
`draft`	`pending`
`pending`	`assigned`, `awaiting_approval`
`awaiting_approval`	`assigned`, `failed`, `done`, `pending`
`assigned`	`in_progress`, `awaiting_approval`
`in_progress`	`review`, `failed`, `awaiting_approval`
`review`	`done`, `failed`, `awaiting_approval`
`failed`	`pending`
`done`	none

phase is separate from status and can be execution, review, fix, or clarification. Tasks without expectations or metrics do not enter an LLM quality review merely because they completed; successful execution can transition directly to done. See Assessment.

Retries and side effects

{
  "retryPolicy": {
    "escalateAfter": 2,
    "fallbackAgent": "senior-dev",
    "escalateModel": "anthropic/claude-sonnet-4-5"
  },
  "sideEffects": true
}

fallbackAgent and escalateModel apply to escalation retries. They belong to the task or mission task, not the agent config. When sideEffects is true, automatic fix and retry paths are blocked before repeating irreversible work. The task moves to awaiting_approval so a human can decide how to continue. It does not imply approval before the first execution.

Local deployment

Standalone task files live under .polpo/tasks/*.json. They are opt-in during deployment:

polpo deploy --include-tasks

polpo deploy --all also includes them. Mission tasks should normally be authored inside the mission’s data document instead. See the Tasks API for update, retry, kill, reassess, queue, force-fail, and activity endpoints.

Getting Started

Platform

Agents

Orchestration

Create a task

Persisted task

Dependencies

Status and phase

Retries and side effects

Local deployment

​Create a task

​Persisted task

​Dependencies

​Status and phase

​Retries and side effects

​Local deployment

Create a task

Persisted task

Dependencies

Status and phase

Retries and side effects

Local deployment