Tasks

task = client.tasks.create(  name: "Morning digest",  instruction: "Summarise what arrived since yesterday and email the summary to me.",  trigger: {    kind: "schedule",    schedule: {cadence: "daily", hour: 8, weekdays: [1, 2, 3, 4, 5], timezone: "Europe/Berlin"}  },  autonomy: "organize") queued = client.tasks.run(task[:id]) client.tasks.iterate_approvals(run_id: queued[:id]) do |request|  puts "#{request[:tool]} #{request[:summary]}"   if request[:tool] == "replyToEmail"    client.tasks.approve(request[:id], subject: "Your morning digest")  else    client.tasks.deny(request[:id])  endend run = client.tasks.get_run(queued[:id]) run[:transcript].to_a.each do |step|  step[:calls].to_a.each { |call| puts "#{step[:at]} #{call[:tool]} #{call[:done]}" }end job = client.tasks.start_run(  instruction: "Find every invoice that arrived this month and label it Invoices.",  maxSteps: 30) failed = client.tasks.list_all_runs(task_id: task[:id], status: "failed") client.tasks.cancel_run(job[:id])client.tasks.pause(task[:id])client.tasks.resume(task[:id]) puts run[:status], run[:result], failed.size

A task is an instruction in plain words with what starts it: a schedule, mail that arrives, or manual for only when asked. A run is one execution, and start_run starts one with no task saved. Read a run again with get_run until its status is done, failed or cancelled. Its transcript holds every step it took and the tools each step called.

autonomy says how much a run may do without asking: ask, organize or reply. Anything past that waits as an approval request for 7 days. approve lets the run go ahead, with subject and body to replace what it wrote in a send or a reply, and deny refuses it. The run carries on once every request of its step is answered.

Reading needs tasks:read, threads:read and emails:read. A task acts with what its caller holds, so create, update, resume, run, start_run and approve need tasks:write, threads:read, threads:write, emails:read, emails:send and labels:write, and the scopes of every toolkit the task names. delete, pause, cancel_run and deny need tasks:write alone.

A task works across every address of the workspace, so a key or an app limited to particular addresses or domains is refused with 422 capability_unsupported.

A task whose toolkits hold connectors may use the apps connected for the workspace, never a connector that belongs to one person, and it then also needs connectors:read and connectors:use. Such a run reads through a connector alone, every change in an app waits as an approval request whatever the autonomy, and with reply every answer to an email waits for approval as well.