Inputs, outputs, and work item contracts

Every work item your App processes carries a contract: what the Runbook receives as input, and what it must produce as output. The contract is compiled from your Runbook and the schemas attached to it, and your reviewers see the same contract you authored.

Audience: builders

Where the contract comes from

You do not declare the contract in a separate config file. The Runbook is the source.

The Inputs section in your Runbook names the fields, files, and integrations the App can rely on. The compiler turns that into an input contract: the structured fields a trigger or human submitter must supply when they create a work item.
The procedure and outcomes you describe drive the output contract: the named outputs (slots) the Runbook is responsible for filling by the time the run finishes.

When you save the Runbook, the compiler regenerates both contracts. Open Review and publish to see what changed before it goes live.

How a work item receives input

Each work item carries the input the trigger or submitter provided.

Trigger-created work items carry whatever the trigger pulled: the inbound email's subject and body, the Slack message, the file the watcher picked up, or the JSON the webhook received. The Runbook reads these the same way it would read any other field.
Manually-created work items use the input contract directly. The composer on the Work items tab renders one input control per field in the input contract. Required fields gate Submit.
Attachments ride alongside the structured fields. The work item hero shows them as file chips so reviewers can open the same files the agent saw.

The raw input is always available on the work item via the Show raw payload disclosure inside the Review surface.

Output slots

The Runbook is responsible for filling a set of named outputs (slots). The Review surface on a work item renders one tab per slot.

Each slot has:

A key. The stable identifier the Runbook writes to.
A label. What reviewers see on the tab.
A kind. The shape of the value (markdown, JSON, a verdict, and so on). The label shows the kind alongside the slot name.
Required or optional. Required slots must be filled by the time the run finishes.

While the run is still in flight, empty slots read as pending and the surface stays quiet about gaps. Once the run lands, missing required slots surface as a "Missing required outputs" alert with the slot names listed.

Schemas bound to a slot

For structured outputs, you can bind a schema to a slot. The platform validates the value against the schema and reports the result on the work item.

The validation status appears as a small badge in the Review header:

Pending. The validator has not run yet (the work item is still queued or running).
Ready. Outputs satisfy the contract.
Repairing. A repair pass is in flight to bring outputs in line.
Failed. The contract is not satisfied and the repair pass did not resolve it.
No outputs. The Runbook does not declare a structured contract for this slot.

Backward-compatible vs breaking changes

When you edit the Runbook and publish, the contract can shift. Some shifts are safe; some break upstream callers.

Backward compatible:

Adding an optional input field.
Adding a new output slot.
Rewording a label or description.
Marking an output slot optional that used to be required.

Breaking:

Adding a required input field. Triggers that don't supply it will fail until they are updated.
Removing or renaming an output slot. Existing work items still hold the old output; new runs no longer produce it.
Marking an input field required that used to be optional.

The publish confirmation dialog calls out trigger input contract changes explicitly so you can update the upstream callers before the new version goes live. See Review and publish for the impact summary.

Outputs from an earlier contract

Slot keys are decided when the Runbook compiles. If you publish a new version that renames a slot, work items that completed before the change still hold their outputs under the old key. The platform does not throw those away.

On the Review surface of an older work item, those values surface as additional read-only tabs marked earlier, with an info banner that explains: "This work item produced outputs on a previous workflow contract. They're listed alongside the current outputs and marked earlier."

The earlier-tab pattern is a bridge, not the answer. The durable fix is to keep slot keys stable across compiles. The platform is moving toward declaring outputs explicitly in the Runbook and pinning the contract to each work item at run time. Until that lands, prefer additive changes over renames whenever the rename is cosmetic.

Rerunning against the current contract

The Rerun button on a work item puts it back on the queue against the App's currently published workflow. If the contract changed between the original run and the rerun, the rerun produces outputs under the new contract.