Run

Interactions

An interaction is a structured request for a human or agent to respond. Inside a loop, an interaction step creates the request, suspends the run, and resumes the run when the interaction resolves.

Interactions can also stand alone as inbox items. The loop-backed path is the one to use when a run needs a decision before it continues.

step request-review kind=interaction
  creates interaction iact_01...
  run moves to suspended
  target responds in the inbox
  interaction reaches completed
  Mobius emits interaction.resolved
  run resumes with the response as step output

Protocols

protocol names what kind of answer the interaction is asking for.

Protocol	Use when	Common response shape
`request_information`	The run needs a value, choice, or freeform answer.	Text, one option, or multiple options.
`request_approval`	The run needs permission to continue.	Confirm, approve, deny, or defer.
`request_review`	The run needs judgment on an artifact, plan, diff, or recommendation.	Select a verdict or write review notes.

Keep the protocol honest. If the next step branches on a yes/no decision, use request_approval. If the next step needs a comment or field value, use request_information.

Spec modes

spec.mode controls the input UI. The protocol controls meaning; the mode controls how the answer is collected.

Mode	Fields	Allowed with
`confirm`	`default_confirmed`	`request_approval`
`select`	`options`, optional `default_value`	`request_information`, `request_approval`, `request_review`
`multi_select`	`options`, optional `default_values`	`request_information`
`input`	`default_text`, `placeholder`, `multiline`	`request_information`, `request_review`

For select and multi_select, every option needs a stable value and a human-readable label. Values are what later steps read; labels are what responders see.

Resolution policies

resolution_policy decides when enough people have answered.

Policy	What resolves the interaction	Use when
`any_of`	The first eligible response resolves it.	One approval, one answer, or one reviewer is enough.
`all_of`	Every target must respond.	Each named person owns part of the decision.
`quorum`	`threshold` distinct targets must respond.	A group decision should resolve before everyone answers.

Default to any_of for first versions. It makes the run unblock quickly, and you can tighten the policy once you know the real review pattern.

An approval step

This step asks one target to approve a deploy recommendation:

steps:
  - key: approve-deploy
    name: Approve deploy
    kind: interaction
    config:
      protocol: request_approval
      targets:
        - usr_platform_lead
      prompt: |
        Scout recommends deploying the platform service.
        Review the run output and approve only if the risk section is clean.
      resolution_policy: any_of
      spec:
        mode: confirm
        default_confirmed: false
    timeout:
      duration: 2h
      on_timeout: fail
    save_as: deploy_approval

When the target approves, later steps can read {{ .context.deploy_approval }}.

A review step

Review interactions usually point at a subject: a pull request, artifact, ticket, or run output. The step config carries the prompt and response mode; the interaction record stores the subject and response history.

steps:
  - key: review-plan
    kind: interaction
    config:
      protocol: request_review
      targets:
        - usr_reviewer
      prompt: |
        Review Scout's plan for the next platform release. Choose the
        closest verdict and leave notes if the plan needs changes.
      resolution_policy: any_of
      spec:
        mode: select
        options:
          - value: approved
            label: Approved
          - value: changes_requested
            label: Changes requested
          - value: blocked
            label: Blocked

Use request_review when the responder is judging an artifact or proposal, not simply granting permission.

Delivery

Without a delivery override, Mobius delivers interactions to the app inbox. That default is inbox_only, which keeps the response tied to project identity and audit history.

The delivery model also supports email:

{
  "channels": [
    {
      "kind": "email",
      "email": { "to": ["lead@acme.example"] }
    }
  ]
}

Use email when the target will not live in the app all day. Use the inbox when you want the least moving parts.

Where responders work

In the app, interactions live under Runtime > Interactions. The page has two useful views:

My inbox shows pending interactions assigned to the current user.
Project board shows pending, completed, expired, and cancelled interactions across the project.

When a responder submits a response, Mobius stores an interaction response record. If the resolution policy is satisfied, the interaction moves to completed, the outcome is frozen, and the waiting run receives the outcome.

Statuses

Status	Meaning
`pending`	Waiting for enough eligible responses.
`completed`	Resolved by the policy. The outcome is available to the consumer.
`expired`	The interaction reached its expiry time without resolving.
`cancelled`	A user or system cancelled the request.

pending is the only live status. The other three are terminal.

Consumers

consumer names what is waiting on an interaction:

Consumer kind	What waits
`run`	A loop run step. Resolution enqueues `interaction.resolved` and resumes the waiting run or step.
`agent_tool`	A hosted-agent tool call waiting for the response value.
`http_subscriber`	An external HTTP callback that receives the resolved interaction.
`none`	No waiting consumer. The interaction is a durable record only.

Loop authors usually get run for free by using an interaction step. Use standalone interactions when you want an inbox item without run side effects.

Failure and cancellation

An interaction step fails the run if its timeout expires and timeout.on_timeout is fail. Cancelling the interaction also closes the wait, so operators do not have to leave obsolete runs suspended.

This is the point of making the decision a step: the run has a visible wait, a deadline, an audit record, and one place to see who answered.

Add interaction steps to steps.
Watch suspended runs from runs.
Use source events from the event catalog.
Give agents the right access with roles.