Tasks

Conceptual

Objectives, capabilities, budgets and completion criteria.

A task is the contract between caller and runtime. It states what outcome is wanted, what the agent is allowed to do, how much it may spend, and how completion will be judged.

Task object#

Fields

objectivestringrequired: The goal in natural language. State outcomes, not procedures.
capabilitiesstring[]: Requested capability scopes, intersected with key and workspace policy.
budgetobject: Limits: steps, wallClockSeconds, toolCalls, usd. Exceeding a budget suspends rather than truncates silently.
completion.criteriastring[]: Human-readable conditions evaluated by the verifier before the task may close.
approvals.requiredstring[]: Effect names that must be approved by a human before dispatch.
attachmentsAttachment[]: Files, documents or datasets available to the run.
contextobject: Structured facts injected into project memory for this task only.
scheduleobject: Optional recurrence or delayed start. See Background Execution.
webhookUrlstring: Destination for lifecycle callbacks. See Webhooks.

Writing good objectives#

Weak objective	Stronger objective
"Look at our churn data"	"Identify the three largest drivers of Q2 churn and quantify each with a confidence interval"
"Improve the API"	"Reduce p95 latency on /search below 200ms without changing the response contract; prove it with a benchmark"
"Research competitors"	"Produce a positioning memo comparing pricing, deployment model and enterprise controls across the four named competitors, citing primary sources"

Status values#

Status	Meaning	Terminal
`queued`	Accepted, awaiting capacity	No
`planning`	Decomposition in progress	No
`running`	Steps executing	No
`awaiting_approval`	Blocked on a human decision	No
`suspended`	Budget exhausted or dependency unavailable	No
`verifying`	Completion criteria being checked	No
`completed`	Criteria satisfied and verified	Yes
`completed_with_caveats`	Delivered with unverified elements reported	Yes
`failed`	Non-recoverable failure with reason	Yes
`cancelled`	Cancelled by caller or policy	Yes

Creating a task with full controls

const task = await pimsy.tasks.create({
  objective: class="tok-str">"Audit our public API docs against the live OpenAPI spec and file issues for every mismatch.",
  capabilities: [class="tok-str">"research.web", class="tok-str">"files.read", class="tok-str">"connector.github"],
  budget: { steps: class="tok-num">80, wallClockSeconds: class="tok-num">2700, toolCalls: class="tok-num">200 },
  approvals: { required: [class="tok-str">"github.issue.create"] },
  completion: {
    criteria: [
      class="tok-str">"Every endpoint in the spec is checked",
      class="tok-str">"Each reported mismatch cites the spec path and doc URL",
      class="tok-str">"No duplicate issues filed"
    ]
  },
  webhookUrl: class="tok-str">"https://ops.example.com/hooks/pimsy"
});

Last updated 2026-09-12