Missions

A mission stores a declarative task graph and executes it as one workflow. It supports dependencies, temporary agents, quality gates, human checkpoints, timed delays, notifications, deadlines, and schedules.

Storage model

A persisted Mission has id, name, data, status, and timestamps. data is a JSON string containing the mission document. Optional top-level persisted fields are prompt, deadline, schedule, endDate, qualityThreshold, notifications, executionCount, and user. The mission document inside data has this shape:

{
  "tasks": [
    {
      "title": "Gather pull request data",
      "description": "Collect merged pull requests for the current week.",
      "assignTo": "data-collector"
    },
    {
      "title": "Write the report",
      "description": "Summarize the collected engineering activity.",
      "assignTo": "writer",
      "dependsOn": ["Gather pull request data"],
      "expectations": [
        {"type": "file_exists", "paths": ["weekly-report.md"]}
      ]
    }
  ],
  "team": [
    {"name": "data-collector", "role": "Collects engineering metrics"},
    {"name": "writer", "role": "Writes concise internal reports"}
  ],
  "qualityGates": [
    {
      "name": "report-quality",
      "afterTasks": ["Write the report"],
      "blocksTasks": ["Publish the report"],
      "minScore": 4,
      "requireAllPassed": true
    }
  ],
  "checkpoints": [],
  "delays": []
}

Task titles must be unique. dependsOn, gate, checkpoint, and delay references use those titles. Dependencies must exist and cannot contain cycles.

Create and execute

The SDK and REST API require data to be serialized:

const document = {
  tasks: [
    {
      title: "Prepare release notes",
      description: "Summarize changes since the previous release.",
      assignTo: "writer"
    }
  ]
};

const mission = await client.createMission({
  name: "release-notes",
  prompt: "Prepare release documentation.",
  data: JSON.stringify(document)
});

await client.executeMission(mission.id);

The canonical execute route is POST /v1/missions/{missionId}/execute. Cloud also exposes its run alias where supported. Local .polpo/missions/*.json files may keep data as an object; polpo deploy serializes it before sending the API request. Put tasks, team, and gates inside data, not beside it.

Lifecycle

Mission status is one of draft, scheduled, recurring, active, paused, completed, failed, or cancelled.

Direct execution starts from draft, scheduled, recurring, failed, or cancelled.
A checkpoint pauses execution until explicitly resumed.
A recurring run returns to recurring after success or failure.
A scheduled one-shot returns to scheduled after failure so the scheduler can retry it; after success it remains completed.

Temporary team

data.team is an array of agent configs. At mission start, Polpo registers each member as a volatile agent tied to that mission run. With the default volatileCleanup: "on_complete", those agents are removed after the group reaches a terminal state. Set project enableVolatileTeams to false to disable registration, or volatileCleanup: "manual" to retain them. Temporary agents receive volatile and missionGroup internally. Do not put a { name, volatile, agents } wrapper around data.team.

Gates, checkpoints, and delays

All three constructs require a unique name, non-empty afterTasks, and non-empty blocksTasks.

Construct	Behavior	Additional fields
Quality gate	Evaluates completed upstream task quality before unblocking downstream tasks	`minScore`, `requireAllPassed`, `condition`, `notifyChannels`
Checkpoint	Unconditionally pauses until explicitly resumed	`message`, `notifyChannels`
Delay	Starts after upstream tasks are terminal and resumes automatically	ISO 8601 `duration`, `message`, `notifyChannels`

Use durations such as PT30M, PT2H, or P1D.

Report

A completed MissionReport contains missionId, execution group, allPassed, totalDuration, a tasks array, aggregated filesCreated, filesEdited, and optional outcomes and avgScore. Each task report contains title, done or failed status, duration, optional score, file lists, and outcomes. See the Missions API for editing mission tasks, gates, checkpoints, delays, team members, and notifications.

Getting Started

Platform

Agents

Orchestration

Storage model

Create and execute

Lifecycle

Temporary team

Gates, checkpoints, and delays

Report

​Storage model

​Create and execute

​Lifecycle

​Temporary team

​Gates, checkpoints, and delays

​Report

Storage model

Create and execute

Lifecycle

Temporary team

Gates, checkpoints, and delays

Report