[{"data":1,"prerenderedAt":56},["ShallowReactive",2],{"$f3sg6zheic1jsd":3},{"href":4,"title":5,"description":6,"kind":7,"mark":7,"planned":8,"contributors":9,"provenance":7,"express":8,"bridge":8,"html":10,"headings":11},"\u002Fdocs\u002Fwork\u002Ftasks","Tasks","The definition of a repeatable job: its goal, its limits, the tools it may use, and what happens next. A task never runs; a run does.",null,false,[],"\u003Ch2 id=\"a-task-is-a-definition\">A task is a definition\u003C\u002Fh2>\n\u003Cp>A task is a repeatable job description: what the job is for, how to do it, what it may touch, and what happens\nafter it. Creating one does no work. Work happens in a \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fruns\">run\u003C\u002Fa>, and a run starts from a person, a\n\u003Ca href=\"\u002Fdocs\u002Fwork\u002Fschedules\">schedule, a webhook\u003C\u002Fa>, or the task before it in a \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs\">handoff\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>Create one on \u003Cstrong>Tasks → Create task\u003C\u002Fstrong>, or \u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">over the API\u003C\u002Fa>. Create a task when a capability is\nmissing, not for one piece of work: &quot;triage an issue&quot; is a task, and &quot;fix issue 42&quot; is a run of one.\u003C\u002Fp>\n\u003Ch2 id=\"anatomy\">Anatomy\u003C\u002Fh2>\n\u003Cp>Most of a task lives in its \u003Cstrong>version\u003C\u002Fstrong>, which is fixed once saved:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Part\u003C\u002Fth>\n\u003Cth>What it is\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Goal\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>One sentence of what the task is for. The model reads it on every run, and \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fself-improvement\">self-improvement\u003C\u002Fa> aims at it.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Success metric\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>How you would know it is working, one line per metric. Free text today.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Guardrails\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Rules the model must not break, one per line: &quot;never email a customer&quot;, &quot;escalate if unsure&quot;. They are instructions to the model. What actually stops a call is a tool scope or a \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates\">gate\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Skill\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The \u003Ccode>SKILL.md\u003C\u002Fcode>: how to do the job, step by step, in plain language.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Tools\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Every tool a run may call, and nothing else. A tool can be narrowed to some values of its fields. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates#tool-scopes\">Gates and tool scopes\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Inputs\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The fields a run starts with: each has a key, a label, a type (Text, Number, Link, Yes\u002Fno or File), and optionally a default and whether it is required.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Gates\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The tool calls that wait for your approval before they happen.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Spend\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>A budget per run, and which model runs it: Auto, where a model is chosen for each run up to a highest tier you may set, or an exact model. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fspend\">Spend and models\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Workspace\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>For a task that works in a repository: the branch it works on and which files it may write. See \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fworkspaces\">Workspaces\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Successors\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The tasks that run after it, and on which outcome. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs\">Handoffs\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Finishes the work on\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The outcomes that end the work for good, one per line. A run that ends on one, with no step after it, finishes the work, so it never shows on \u003Cstrong>Waiting\u003C\u002Fstrong>. Left empty, the work stays open until someone marks it finished. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fhandoffs#finished-work\">Finished work\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>Some things belong to the task itself rather than to a version, so the version history does not record them:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Part\u003C\u002Fth>\n\u003Cth>What it is\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Name and slug\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>The slug is unique in your enterprise. Successors, webhooks and the API find the task by it, so choose it deliberately.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Who runs it\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>A role. Each run goes to a member who holds that role and is free, on any team or on no team, the one who has waited longest first. A task cannot be given to one member or to a team. See \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Froles\">Roles\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Teams\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Shown, not set: the teams that have the task, because a member who holds its role sits on or leads them. A task's page reads &quot;No team yet: nobody holds this role on a team&quot; when there are none. A run is done for the teams of the member it goes to.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Runs at once\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Its lanes, if it declares any. See \u003Ca href=\"#runs-at-once\">Runs at once\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Status\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>active\u003C\u002Fcode>, or \u003Ccode>deprecated\u003C\u002Fcode>: a deprecated task starts no new runs. \u003Cstrong>Start\u003C\u002Fstrong>, the API and its webhook refuse it, its schedule stops firing, and runs waiting to start are closed. Runs already under way finish.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Cstrong>Schedule\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>Its cadence, if it has one. Changing it publishes no new version. See \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fschedules\">Schedules and webhooks\u003C\u002Fa>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A task's page in the portal also shows its runs, its \u003Ca href=\"\u002Fdocs\u002Fwork\u002Fschedules\">triggers\u003C\u002Fa>, and any self-improvement\nrecommendations waiting on it.\u003C\u002Fp>\n\u003Ch2 id=\"what-a-task-can-call\">What a task can call\u003C\u002Fh2>\n\u003Cp>Use \u003Cstrong>Add Tool\u003C\u002Fstrong> when creating a task or editing its version. The picker shows the connections available to\nits role and the teams that have it, plus the built-in actions. Choose \u003Cstrong>Add toolset\u003C\u002Fstrong> to let the model choose among a connected\nserver's actions, or \u003Cstrong>Choose actions\u003C\u002Fstrong> to select individual ones. You do not need to type tool names.\nSelected tools appear as cards; \u003Cstrong>Remove\u003C\u002Fstrong> removes an assignment from the draft. Saving publishes a new version.\u003C\u002Fp>\n\u003Cp>A whole toolset is a permission to use its discovered actions, not an action itself. The model still calls an\nindividual action with its input fields. If a connection cannot list its actions, the picker shows a retry and\nthe run reports those actions as unavailable rather than offering the catalog name as a callable tool.\u003C\u002Fp>\n\u003Cp>When an action requires an approval gate, selecting it adds that gate to the draft. Review the \u003Cstrong>Gates\u003C\u002Fstrong> before\nsaving. Existing tool scopes and approval checks still apply to whole toolsets.\u003C\u002Fp>\n\u003Cp>A task that should work with whichever tool a company connected, such as any code host, names its tools by a\n\u003Ca href=\"\u002Fdocs\u002Fwork\u002Ftool-slots\">tool slot\u003C\u002Fa> instead of a vendor: it declares the slot under \u003Cstrong>Tool slots\u003C\u002Fstrong>, and each company\nfills it with one of its own connections on \u003Cstrong>Tools\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003Cp>For an OAuth connection, choose its \u003Cstrong>Permissions\u003C\u002Fstrong> from the server’s advertised list before connecting. Nothing is selected automatically. To change access later, open \u003Cstrong>Tools → Edit\u003C\u002Fstrong> on that connection, change the checked permissions and click \u003Cstrong>Reconnect \u002F change permissions\u003C\u002Fstrong>. Authorize at the vendor, then return to OS. Existing team\u002Fmember assignment and tool restrictions stay in place. OS checks the catalog after authorization and explains when no actions are available.\u003C\u002Fp>\n\u003Cp>If the task picker cannot load actions, use \u003Cstrong>Manage connection\u003C\u002Fstrong> to open that connection’s settings. Authentication failures require reconnecting; network failures can be retried. Servers that do not advertise permissions can use their defaults or administrator-supplied scopes.\u003C\u002Fp>\n\u003Cp>On \u003Cstrong>Tools\u003C\u002Fstrong>, add or edit a connection to upload an \u003Cstrong>Image or logo\u003C\u002Fstrong>. PNG, JPEG, WebP and GIF files up to 5 MB\nare resized for the cards. You can preview or remove the image before saving. For an OAuth connection, connect\nfirst, then edit its image.\u003C\u002Fp>\n\u003Cp>A run can call only its task's selected tools, including the actions of a selected toolset. They come in two kinds:\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>Built-in tools\u003C\u002Fstrong>, which the OS answers itself: \u003Ccode>os.*\u003C\u002Fcode>, \u003Ccode>workspace.*\u003C\u002Fcode>, \u003Ccode>memory.*\u003C\u002Fcode>, \u003Ccode>web.*\u003C\u002Fcode>, and the actions of a\nbrowser.\nThe \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbuilt-in\">built-in tools reference\u003C\u002Fa> is the exact list, with what each takes, whether it writes,\nand which can wait at a gate.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Vendor tools\u003C\u002Fstrong>, from the systems your enterprise connects: GitHub, Slack and the rest. The\n\u003Ca href=\"\u002Fdocs\u002Ftools\">Tools\u003C\u002Fa> directory lists each system, and how to connect it.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Cp>How to narrow a tool to some values, and which calls wait for you, is in\n\u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates\">Gates and tool scopes\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch3 id=\"optional-tools\">Optional tools\u003C\u002Fh3>\n\u003Cp>A task can use a tool when your company has connected it and go ahead without it when you have not. Tick\n\u003Cstrong>Optional\u003C\u002Fstrong> on the tool's card when editing the task, or send the entry as \u003Ccode>{ &quot;name&quot;: &quot;sentry&quot;, &quot;optional&quot;: true }\u003C\u002Fcode>\nin \u003Ccode>tools\u003C\u002Fcode> (\u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">Tasks API\u003C\u002Fa>). A task that triages issues might read your error tracker and your\nanalytics when they are connected, and still triage from the issue alone when they are not:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;tools&quot;: [\n        &quot;codehost.issue.read&quot;,\n        &quot;codehost.issue.comment&quot;,\n        { &quot;name&quot;: &quot;sentry&quot;, &quot;optional&quot;: true },\n        { &quot;name&quot;: &quot;metabase&quot;, &quot;optional&quot;: true }\n    ]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>When no connection that reaches a run serves an optional tool, the run starts anyway. The model is not offered the\ntool, is told it is not connected, and is asked to skip any step that needs it and say what it skipped. A call to it\nanyway is handed back as \u003Ccode>tool_not_connected\u003C\u002Fcode> without ending the run. Once you connect the tool, later runs use it.\nA required tool that is not connected still holds the run as \u003Ccode>tool_not_bound:&lt;tool&gt;\u003C\u002Fcode> until you connect it, and an\noptional tool never appears among the connections a role holder is missing. Gates and scopes apply to an optional\ntool exactly as to a required one. A tool slot can be optional too: name its tools in optional entries, and a company\nthat fills no binding for the slot runs without them.\u003C\u002Fp>\n\u003Ch3 id=\"call-limits\">Call limits\u003C\u002Fh3>\n\u003Cp>A version can cap how many times one run makes a call, with \u003Ccode>callLimits\u003C\u002Fcode> (\u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">Tasks API\u003C\u002Fa>). Each\nlimit names one of the task's tools, an optional \u003Ccode>match\u003C\u002Fcode> on the call's fields, read the way a\n\u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates\">gate's match\u003C\u002Fa> is, and \u003Ccode>perRun\u003C\u002Fcode>, how many such calls a run may make. A task that files issues\nand may open at most two a run, while editing as many as it needs:\u003C\u002Fp>\n\u003Cpre>\u003Ccode class=\"language-json\">{\n    &quot;tools&quot;: [&quot;gitea.issue_write&quot;],\n    &quot;callLimits&quot;: [{ &quot;tool&quot;: &quot;gitea.issue_write&quot;, &quot;match&quot;: { &quot;method&quot;: &quot;create&quot; }, &quot;perRun&quot;: 2 }]\n}\n\u003C\u002Fcode>\u003C\u002Fpre>\n\u003Cp>The OS counts the run's own calls that matched. The call past the limit is never sent and asks nobody: the run reads\n\u003Ccode>call_limit_reached\u003C\u002Fcode> as the tool's answer and carries on with the rest of its work. A call the tool refused, or the OS\nrefused before sending it, does not count. Each run has its own count, so a retry or the next task in a handoff starts\nagain from none. It works the same for a connected tool and a built-in one.\u003C\u002Fp>\n\u003Cp>A task created without \u003Ccode>gates\u003C\u002Fcode> asks the CEO before every call of a tool it holds that reaches outside the enterprise:\neach vendor tool its connected server does not mark read-only, \u003Ccode>os.mail_send\u003C\u002Fcode> and \u003Ccode>os.mail_reply\u003C\u002Fcode>, and each tool your\nconnections mark must-gate, by name. Send\n\u003Ccode>gates: []\u003C\u002Fcode> to create it with none, or your own list, which is saved exactly as given. A later version never adds them\nback. See \u003Ca href=\"\u002Fdocs\u002Fcontrol\u002Fgates#a-task-created-without-gates\">A task created without gates\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"runs-at-once\">Runs at once\u003C\u002Fh2>\n\u003Cp>A task runs \u003Cstrong>one run at a time\u003C\u002Fstrong> unless it says how its work splits. Declare the input keys that split it, its\n\u003Cstrong>lanes\u003C\u002Fstrong>, with \u003Ccode>serializeOn\u003C\u002Fcode> (\u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">Tasks API\u003C\u002Fa>): a task that works one issue of one repository at a\ntime might declare \u003Ccode>[&quot;repo&quot;, &quot;issue&quot;]\u003C\u002Fcode>. Then runs on different issues run at once, and two runs on the same issue\nnever do: the second waits, or is skipped, as it would for a task with one lane.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>A lane is the values of those inputs, trimmed and in lower case, so \u003Ccode>Acme\u002FWeb\u003C\u002Fcode> and \u003Ccode>acme\u002Fweb\u003C\u002Fcode> are the same lane.\u003C\u002Fli>\n\u003Cli>A member still does one run at a time, or up to their \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Fmembers#tasks-at-once\">tasks at once\u003C\u002Fa> on the\nEnterprise plan. Lanes run side by side only when the task's role holders have the room between them.\u003C\u002Fli>\n\u003Cli>Keys are yours to choose: a repository, a campaign, a region. The OS never reads meaning into them.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch2 id=\"versions\">Versions\u003C\u002Fh2>\n\u003Cp>Every save publishes a new \u003Cstrong>version\u003C\u002Fstrong>, numbered from 1. A version is never changed after it is saved.\u003C\u002Fp>\n\u003Cul>\n\u003Cli>\u003Cstrong>A run keeps the version it started on.\u003C\u002Fstrong> Saving a new version while a run is under way changes nothing for that\nrun; the next run uses the new one. A run that has not started yet, waiting as \u003Ccode>pending\u003C\u002Fcode> or \u003Ccode>queued\u003C\u002Fcode>, takes\nwhichever version is current when it starts. A run that picks up another run's work after a release keeps that\nrun's version.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Version history\u003C\u002Fstrong> on the task shows every version as it was, read-only, and the runs that used it.\u003C\u002Fli>\n\u003Cli>\u003Cstrong>Going back\u003C\u002Fstrong> to an earlier definition means opening that version and saving its content as a new version. There\nis no one-click restore.\u003C\u002Fli>\n\u003C\u002Ful>\n\u003Ch3 id=\"editing-safely\">Editing safely\u003C\u002Fh3>\n\u003Cp>\u003Cstrong>Edit\u003C\u002Fstrong> on a task opens its current version; \u003Cstrong>Save as new version\u003C\u002Fstrong> publishes your changes as the next one.\u003C\u002Fp>\n\u003Cp>If someone (a person, or a self-improvement change you approved) published a newer version while you were editing,\nyour save is refused rather than putting the older definition back over theirs. Copy what you want to keep, then\n\u003Cstrong>Cancel edit\u003C\u002Fstrong> to load the newer version and make your change on top of it. Over the API, the same protection is\n\u003Ccode>baseVersionId\u003C\u002Fcode>: send the version you read, and a save made after someone else's is refused with a \u003Ccode>409\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Ch3 id=\"checks-when-you-save\">Checks when you save\u003C\u002Fh3>\n\u003Cp>A version that could never run is refused, and one with a likely mistake is saved with a warning:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Code\u003C\u002Fth>\n\u003Cth>Refused or warned\u003C\u002Fth>\n\u003Cth>Why\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gate_required_for_tool\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>The task can merge a pull request or send a new mail but declares no gate on it, or it can write a plan (a team, role, member, task or spend change) but declares no CEO gate on asking the CEO.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>gate_summary_tool_required\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>A gate of the task asks for a summary (\u003Ccode>requiresSummary\u003C\u002Fcode>), or it can reply to mail, but it cannot write one.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>deterministic_with_tools\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>A task that runs no model (\u003Ccode>deterministic\u003C\u002Fcode>) lists tools it could never call.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_when_unknown\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>A successor's \u003Ccode>when\u003C\u002Fcode> is not one the OS knows.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_cap_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>A successor's loop cap is not a whole number of at least 1.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_delay_invalid\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>A successor's delay is not more than 0 and at most 1440 minutes.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>unconditional_loop\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Refused\u003C\u002Ftd>\n\u003Ctd>Successors on \u003Ccode>terminal\u003C\u002Fcode> loop back to the task, so it would never stop.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>successor_unknown_slug\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Warned\u003C\u002Ftd>\n\u003Ctd>A successor names a task your enterprise does not have.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>outcome_not_routed:&lt;word&gt;\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Warned\u003C\u002Ftd>\n\u003Ctd>The skill tells a run to end on \u003Ccode>{&quot;outcome&quot;:&quot;&lt;word&gt;&quot;}\u003C\u002Fcode>, but no successor routes that word, the task does not list it as finishing the work, and it is not plain success (\u003Ccode>succeeded\u003C\u002Fcode> or \u003Ccode>ok\u003C\u002Fcode>), so a run that ends on it stops as a dead end. One per word.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>self_loop_unconditional\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Warned\u003C\u002Ftd>\n\u003Ctd>A successor starts the task itself again on \u003Ccode>succeeded\u003C\u002Fcode> (or with no outcome named) or on a named outcome, with no delay, so every run that ends that way starts another, for ever. A successor back to itself on \u003Ccode>ceo_approved\u003C\u002Fcode> or \u003Ccode>ceo_changes_requested\u003C\u002Fcode>, or with a delay, is fine.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>asks_ceo_without_resume\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Warned\u003C\u002Ftd>\n\u003Ctd>The task asks the CEO (\u003Ccode>os.ask_ceo\u003C\u002Fcode>), its skill does more work with the answer, but no successor on \u003Ccode>ceo_approved\u003C\u002Fcode> goes back to the task itself, so nothing picks the work up once the CEO answers.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>An outcome the task lists as finishing the work (\u003Ccode>finishesOn\u003C\u002Fcode>) always finishes it, whatever its successors branch on, so\nit never needs a successor of its own.\u003C\u002Fp>\n\u003Cp>Warnings show on the task, and on \u003Cstrong>Blockers\u003C\u002Fstrong> under \u003Cstrong>Task definitions\u003C\u002Fstrong>, until they are fixed. The two read from\nthe skill's text, \u003Ccode>outcome_not_routed\u003C\u002Fcode> and \u003Ccode>asks_ceo_without_resume\u003C\u002Fcode>, show on the task's page only: \u003Cstrong>Blockers\u003C\u002Fstrong> does\nnot read every task's skill each time it loads. A run that does end on an outcome nothing routes still shows on\n\u003Cstrong>Blockers\u003C\u002Fstrong> when it stops its pipeline, and a task whose runs keep ending that way is listed under \u003Cstrong>Task definitions\u003C\u002Fstrong>.\u003C\u002Fp>\n\u003Cp>\u003Ccode>outcome_not_routed\u003C\u002Fcode>, \u003Ccode>self_loop_unconditional\u003C\u002Fcode> and \u003Ccode>asks_ceo_without_resume\u003C\u002Fcode> are warnings when you save in the portal\nor over the API. A task created over the OS's own MCP server (\u003Ccode>os.create_task\u003C\u002Fcode>) is held to them instead: the create is\nrefused with \u003Ccode>definition_issues\u003C\u002Fcode>, naming each one, and nothing is saved until the definition is fixed. Publishing a new\nversion over MCP (\u003Ccode>os.publish_task_version\u003C\u002Fcode>) still saves and returns them as warnings.\u003C\u002Fp>\n\u003Ch2 id=\"inputs\">Inputs\u003C\u002Fh2>\n\u003Cp>A task's inputs are what a run starts with. \u003Cstrong>Start a run\u003C\u002Fstrong> on the task's page shows them as a form, filled with\nyour enterprise's own values for them, else their defaults, and will not start while a required one is empty. The\nsame keys are what a schedule, a webhook body, or the task before it provide.\u003C\u002Fp>\n\u003Cp>However a run starts, an input it leaves out or blank takes your enterprise's own value for it, else its default, and a\nrequired input with none of those refuses the start with \u003Ccode>input_required\u003C\u002Fcode> naming it: a schedule's firing, a release, a\nwebhook, the API, MCP and chat alike. The one exception is a run the task before it starts: its input is whatever that\nrun handed on, with your values and the defaults filling what it left out, and a required input still missing is left\nunset for that run to explain rather than refused. Keys the task does not declare pass through to the run as sent.\u003C\u002Fp>\n\u003Ch3 id=\"your-own-input-values\">Your own input values\u003C\u002Fh3>\n\u003Cp>A version's defaults are part of the task's definition, so only the enterprise that owns the definition can change\nthem, and a task published to the Catalog carries none. \u003Cstrong>Input values\u003C\u002Fstrong> on the task's page are where your enterprise\nkeeps its own value for each input instead: a repository, a project key, a map of IDs. They sit on the task, beside its\nschedule, not on a version, so saving them cuts no version and works on a clone you cannot edit.\u003C\u002Fp>\n\u003Cp>Every run of the task takes them, however it starts, in this order:\u003C\u002Fp>\n\u003Col>\n\u003Cli>A value the start gives: the Start form, an API or MCP call, a schedule's or release trigger's run input, a webhook\nbody, or what the task before it handed on.\u003C\u002Fli>\n\u003Cli>Your enterprise's own value.\u003C\u002Fli>\n\u003Cli>The version's default.\u003C\u002Fli>\n\u003C\u002Fol>\n\u003Cp>A retry or a restart repeats the input its run had, so a value the run already carried stays; one it lacked is filled\nfrom your values as they are now.\u003C\u002Fp>\n\u003Cp>Each value has to be of the type its input declares, and only inputs the current version declares can have one, so a\nsave naming another key is refused with \u003Ccode>input_undeclared\u003C\u002Fcode> and a value of the wrong kind with \u003Ccode>input_invalid\u003C\u002Fcode>, each\nnaming the input. A File input takes none: the file is given at each start. When a newer version stops declaring an\ninput, or changes its type, the value you saved for it is kept but no run takes it, and the task's page lists it so you\ncan clear it. A built-in task runs one shared definition for every enterprise and takes no values of any one\nenterprise's own.\u003C\u002Fp>\n\u003Cp>Over the API, \u003Ccode>GET \u002Fv1\u002Ftasks\u002F:id\u003C\u002Fcode> returns them as \u003Ccode>inputValues\u003C\u002Fcode>, with \u003Ccode>ignoredInputValues\u003C\u002Fcode> naming any the current\nversion does not take; \u003Ccode>PUT \u002Fv1\u002Ftasks\u002F:id\u002Finput-values\u003C\u002Fcode> with \u003Ccode>{ &quot;values&quot;: { ... } }\u003C\u002Fcode> replaces them and\n\u003Ccode>DELETE \u002Fv1\u002Ftasks\u002F:id\u002Finput-values\u003C\u002Fcode> clears them. Through MCP the tool is \u003Ccode>os.set_task_input_values\u003C\u002Fcode>.\u003C\u002Fp>\n\u003Cp>The task form names each type in plain words. Over the API, a task's inputs carry the stored word:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Type\u003C\u002Fth>\n\u003Cth>Stored as\u003C\u002Fth>\n\u003Cth>What a start gives\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>Text\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>string\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Any text.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Number\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>number\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A number.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Link\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>link\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A full \u003Ccode>http\u003C\u002Fcode> or \u003Ccode>https\u003C\u002Fcode> address. Anything else refuses the start with \u003Ccode>input_invalid\u003C\u002Fcode>, naming the input.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Yes\u002Fno\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>boolean\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>true\u003C\u002Fcode> or \u003Ccode>false\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>File\u003C\u002Ftd>\n\u003Ctd>\u003Ccode>file\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>A file, chosen with a file picker on \u003Cstrong>Start a run\u003C\u002Fstrong>, or sent as a \u003Ccode>data:\u003C\u002Fcode> URL over the API. It takes no default. A \u003Ca href=\"\u002Fdocs\u002Ftools\u002Fbrowser#files-in-and-out\">browser\u003C\u002Fa> can attach it to a page.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Ch2 id=\"clone-and-copy\">Clone and copy\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Community → Catalog\u003C\u002Fstrong> lists the tasks you can take into your enterprise, in two ways:\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>\u003C\u002Fth>\n\u003Cth>Clone\u003C\u002Fth>\n\u003Cth>Copy\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>What you get\u003C\u002Ftd>\n\u003Ctd>Your own installation of the original, linked to it\u003C\u002Ftd>\n\u003Ctd>A new, independent task\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Who owns the definition\u003C\u002Ftd>\n\u003Ctd>The original's owner\u003C\u002Ftd>\n\u003Ctd>You\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Can you edit it\u003C\u002Ftd>\n\u003Ctd>No: \u003Cstrong>Edit\u003C\u002Fstrong> is disabled, and self-improvement does not run on it\u003C\u002Ftd>\n\u003Ctd>Yes\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Starts on\u003C\u002Ftd>\n\u003Ctd>The original's current version\u003C\u002Ftd>\n\u003Ctd>Version 1, with the original's definition\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>Later versions\u003C\u002Ftd>\n\u003Ctd>A newer version of the original is offered on the clone's page, with the tools it adds or drops and any input it now needs a value for, and \u003Cstrong>Update\u003C\u002Fstrong> takes it. While your enterprise's \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Fenterprise#settings-on-the-enterprise-page\">Auto-update cloned tasks\u003C\u002Fa> setting is on, a quiet update follows automatically, usually within a minute of the original publishing it; updates that change tools, gates, inputs or the workspace's credentials or push rules still wait for a person to press \u003Cstrong>Update\u003C\u002Fstrong>\u003C\u002Ftd>\n\u003Ctd>None: it is yours from here\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>You choose\u003C\u002Ftd>\n\u003Ctd>Nothing: it lands with the original's name, slug and role\u003C\u002Ftd>\n\u003Ctd>Its name, slug and role\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>A quiet update is one that adds or removes no tool or gate, needs no new input value, and leaves the task's workspace\nas it is: the credentials its repository commands get from your connected tools, and what it may write and push. The\nautomatic update takes it exactly as \u003Cstrong>Update\u003C\u002Fstrong> would: the clone's name, role, schedule, input values and status stay as they are, a run\nalready going finishes on the version it started on, and the clone's version history shows the new version as\n\u003Cstrong>Applied automatically from source v\u003Cem>N\u003C\u002Fem>\u003C\u002Fstrong>, \u003Cem>N\u003C\u002Fem> being the original's version. An update your plan does not allow is\nheld, as \u003Cstrong>Update\u003C\u002Fstrong> is, and so is every update while the setting is off.\u003C\u002Fp>\n\u003Cp>A clone keeps the original's role, and a copy keeps it unless you choose another. Neither is put on a team: either\nruns once someone holds that role, and every team a holder sits on or leads has it.\u003C\u002Fp>\n\u003Cp>Either way, you can run it, schedule it, set its \u003Ca href=\"#your-own-input-values\">input values\u003C\u002Fa> and delete it. Neither brings\na schedule, input values, run history, credentials or memory: you connect your own \u003Ca href=\"\u002Fdocs\u002Ftools\">tools\u003C\u002Fa>, set your own\ninput values, and a clone may not write memory above its own task. Successors\nthat pointed at the original point at your copy; other successors look for tasks with the same slugs in your\nenterprise.\u003C\u002Fp>\n\u003Cp>\u003Cstrong>Copy\u003C\u002Fstrong> also works on your own tasks, from the task's page, to start a variant without touching the original.\u003C\u002Fp>\n\u003Cp>What a task needs to work in an enterprise that is not its author's, before you publish it to the Catalog, is in\n\u003Ca href=\"\u002Fdocs\u002Fwork\u002Fwriting-a-task\">Writing a clonable task\u003C\u002Fa>.\u003C\u002Fp>\n\u003Cp>The OS's own tasks are part of the product, not of the catalog: the same in every enterprise, and changed only\nwith a release of the OS. They cannot be cloned or copied, and nobody can edit, reschedule or delete one. You can\nstill start them. See \u003Ca href=\"\u002Fdocs\u002Fcompany\u002Fenterprise\">Enterprise\u003C\u002Fa>.\u003C\u002Fp>\n\u003Ch2 id=\"deleting-a-task\">Deleting a task\u003C\u002Fh2>\n\u003Cp>\u003Cstrong>Delete\u003C\u002Fstrong> on a task removes its definition and every version of it. Runs that already happened are kept.\u003C\u002Fp>\n\u003Ch2 id=\"over-the-api\">Over the API\u003C\u002Fh2>\n\u003Cp>With an \u003Ca href=\"\u002Fdocs\u002Fapi\u002Fauthentication\">API token\u003C\u002Fa> scoped \u003Ccode>tasks:read\u003C\u002Fcode> (and \u003Ccode>tasks:write\u003C\u002Fcode> to change them):\u003C\u002Fp>\n\u003Cdiv class=\"prose__table\">\n\u003Ctable>\n\u003Cthead>\n\u003Ctr>\n\u003Cth>Call\u003C\u002Fth>\n\u003Cth>What it does\u003C\u002Fth>\n\u003C\u002Ftr>\n\u003C\u002Fthead>\n\u003Ctbody>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Ftasks\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Create a task, with its first version.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>GET \u002Fv1\u002Ftasks\u002F{id}\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>The task, its current version and skill, its version list, and its definition warnings.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fversions\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Save a new version. Send \u003Ccode>baseVersionId\u003C\u002Fcode>.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fcopy\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Copy it, with a new name and slug, and optionally a new role.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>PUT \u002Fv1\u002Ftasks\u002F{id}\u002Fschedule\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Set its schedule.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003Ctr>\n\u003Ctd>\u003Ccode>POST \u002Fv1\u002Ftasks\u002F{id}\u002Fruns\u003C\u002Fcode>\u003C\u002Ftd>\n\u003Ctd>Start a run.\u003C\u002Ftd>\n\u003C\u002Ftr>\n\u003C\u002Ftbody>\n\u003C\u002Ftable>\n\u003C\u002Fdiv>\n\u003Cp>See \u003Ca href=\"\u002Fdocs\u002Fapi\u002Ftasks\">Tasks over the API\u003C\u002Fa> for the full shape of a task.\u003C\u002Fp>\n",[12,16,19,22,26,29,32,35,38,41,44,47,50,53],{"id":13,"text":14,"level":15,"planned":8},"a-task-is-a-definition","A task is a definition",2,{"id":17,"text":18,"level":15,"planned":8},"anatomy","Anatomy",{"id":20,"text":21,"level":15,"planned":8},"what-a-task-can-call","What a task can call",{"id":23,"text":24,"level":25,"planned":8},"optional-tools","Optional tools",3,{"id":27,"text":28,"level":25,"planned":8},"call-limits","Call limits",{"id":30,"text":31,"level":15,"planned":8},"runs-at-once","Runs at once",{"id":33,"text":34,"level":15,"planned":8},"versions","Versions",{"id":36,"text":37,"level":25,"planned":8},"editing-safely","Editing safely",{"id":39,"text":40,"level":25,"planned":8},"checks-when-you-save","Checks when you save",{"id":42,"text":43,"level":15,"planned":8},"inputs","Inputs",{"id":45,"text":46,"level":25,"planned":8},"your-own-input-values","Your own input values",{"id":48,"text":49,"level":15,"planned":8},"clone-and-copy","Clone and copy",{"id":51,"text":52,"level":15,"planned":8},"deleting-a-task","Deleting a task",{"id":54,"text":55,"level":15,"planned":8},"over-the-api","Over the API",1794928144020]