Skip to content

Agent Callbacks

Agent callbacks let a MindRoom agent hand a background process a script that wakes the originating agent and thread when the work finishes.

They are a small adapter over external triggers rather than a separate callback service.

The intended flow is simple:

  1. The MindRoom agent starts a background Codex session or another long-running task.
  2. It calls mint_callback with a short label for that task.
  3. It includes the returned instruction in the background agent's prompt.
  4. The background agent runs the script with a short result summary when it finishes.

Configuration

Enable the tool on agents that launch background work:

agents:
  orchestrator:
    role: Launch and supervise coding agents.
    tools:
      - callback_manager

No callback-specific configuration is required.

Callbacks use the existing external_trigger_policy, which is enabled by default, and count toward max_triggers_per_owner until used or deleted.

Tool Result

mint_callback(label) returns a script path and an instruction like this:

When finished, run: bash /path/to/callback_1234.sh "<short result summary>"

The script needs only Bash and curl.

It posts the summary back to the room and thread where the callback was minted, waking the same MindRoom agent.

MindRoom stores the callback as a bearer-authenticated external trigger whose delivery mode is single_use.

After successful Matrix delivery, the external trigger is consumed and the script deletes itself.

If delivery fails, the script remains so the background agent can retry it.

Changing the request's event_id cannot make the trigger deliver more than once.

Unused callbacks do not expire automatically, so delete abandoned records with external_trigger_manager if they are no longer needed.

Network Access

Generated scripts use the embedded API server's bound address, including a non-default --api-port.

When no embedded API server is running, they fall back to http://127.0.0.1:8765.

Set MINDROOM_URL when the background process needs another address to reach the MindRoom API.

Point MINDROOM_URL only at a trusted MindRoom endpoint because the script sends its bearer token there.

Security

Each script contains a random bearer token whose hash is stored in MindRoom control state.

The token can only wake the agent, room, and thread captured when it was minted.

Missing or incorrect tokens receive the same not-found response.

The request then follows the normal external-trigger readiness, authorization, room-membership, replay, Matrix-delivery, and failure-retry path.

Use External Triggers directly for reusable integrations that need stable signed identities.