Threads

Use threads to group related tasks together. When you create a task, RobotRock assigns it a threadId. Pass that same threadId on later tasks to group them, and they appear as a single collapsed entry in the inbox with a count badge. Opening the entry shows every task in the thread stacked, newest on top.

Threads are useful when one piece of work produces several approvals over time—for example a deployment that needs a plan review, then a post-deploy sign-off, or an agent that comes back to the same human repeatedly during a session.

How it works

1. You create a task. If you do not supply a threadId, the server generates one (thread_<uuid>) and returns it on the response.
2. You reuse that threadId on subsequent sendToHuman() calls.
3. The inbox groups tasks that share a threadId. A thread with two or more tasks shows one row with a badge for the task count; a single-task thread looks like a normal task.
4. Opening a thread shows all of its tasks stacked in the detail pane, newest first.

Threads are scoped to your tenant—any task created with your API keys can share a threadId regardless of which app bucket it lands in.

Thread priority is also thread-scoped: set priority on any task in the thread to update ordering for the whole group.

Create the first task in a thread

Omit threadId to start a new thread. Read task.threadId from the response and keep it for the next task.

import { robotrock } from "@/lib/robotrock";

const first = await robotrock.sendToHuman({
  type: "deploy-approval",
  name: "Approve staging deploy",
  actions: [
    { id: "approve", title: "Approve" },
    { id: "reject", title: "Reject" },
  ],
});

// The server generated a thread id; reuse it for related tasks.
const threadId = first.task.threadId;

Add a task to an existing thread

Pass the saved threadId on the next task.

await robotrock.sendToHuman({
  type: "deploy-approval",
  name: "Confirm production rollout",
  threadId, // groups this task with the first one
  actions: [
    { id: "approve", title: "Approve" },
    { id: "reject", title: "Reject" },
  ],
});

You can also supply your own stable threadId (for example, your internal workflow id) instead of reusing the generated one:

await robotrock.sendToHuman({
  type: "deploy-approval",
  name: "Approve staging deploy",
  threadId: `deploy_${deploymentId}`,
  actions: [{ id: "approve", title: "Approve" }],
});

Where threadId lives

threadId is a top-level field on the task—like assignTo, it is not part of context.

The threadId is also returned by getTask so you can confirm which thread a task belongs to.

Inbox behavior

• Tasks that share a threadId collapse into one inbox row.
• The row shows the newest task in the thread plus a badge with the total task count.
• Selecting the row opens the detail pane with every task in the thread stacked, newest on top, each with its own actions and handled state.
• A thread with only one task is indistinguishable from an ungrouped task.

Related

• Send to human — send tasks and receive taskId and threadId
• Priority — thread priority and inbox ordering
• Updates — send short status updates to a thread
• Task lifecycle — look up, monitor, and cancel tasks
• Context — rich inbox display data for each task