Introducing a new way to review your PRs.

Read the announcement

stablyai / orca

Orca lets you run a fleet of bots with your own subscription (e.g. Claude Code, Grok, Agy, Codex). Available on desktop, mobile and remote runtime.

View on GitHub

34 documents · Updated Nov 20, 2026

docs / bot-conversations-and-automation

Bot conversations and connector automation

Bot conversations give each bot a durable place to receive work, keep context, and report progress. The system connects home chats, external connector threads, group rooms, work items, approvals, tools, and scheduled runs so an owner can follow bot activity from the desktop or a paired phone. This page is part of Bot orchestration.

Conversation model

The conversation model gives each bot a stable home while allowing work to start from many sources. A home chat remains the bot's main conversation. Threads, side chats, group rooms, and automation runs use their own conversations but still belong to the bot's activity view.

Home chats

The home chat is created when a bot is first used and runs in the bot's home workspace. An owner can reset it without losing the old history. Background conversations can wait without a visible tab until the owner opens them from activity.

Each message records its source. The source can be a person, another bot, an automation event, or an owner action. This preserves the bot's conversation identity while making the reason for each turn clear.

References: src/…/bot-chat-session.ts• L40-85 src/…/bot-chat-session.ts• L100-152 src/…/bot-chat-session.ts• L256-333

Connector conversations

Connector conversations let a bot respond to supported external services. The system maps an external conversation to a bot session in the bot's home and can attach verified work links such as pull requests.

The request keeps the asker, source, destination, and response route together. External event text is content for the bot to assess. It does not gain authority to change the request.

This diagram shows the path from an external message to a response or work update.

flowchart LR
  E[Connector event] --> C[External conversation]
  C --> S[Bot session in home]
  S --> T[Bot turn]
  T --> R[Answer, handoff, or status]
  R --> C

References: src/…/bot-conversations.ts• L14-55 src/…/bot-request-policy.ts• L7-14 src/…/bot-request-view.ts• L42-68

Group lifecycle

A bot group is a shared room for several bots. The room has its own history, member sessions, reply rule, and optional threads. It remains a separate space from each member's home chat.

Room membership

Creating a group starts a room session for each selected bot. Adding a bot starts sessions for the room and its threads. Removing a bot closes its sessions and keeps its completed output in the transcript.

The group revision changes after a membership or reply-rule update. Clients must use the current revision when they edit the room or send a message. A room with no members stays readable but cannot accept new messages until a bot joins.

Groups currently support bots on the same local execution host. Deleting a bot removes it from every group.

References: src/…/bot-group-membership.ts• L17-64 src/…/bot-group-membership.ts• L67-145 src/…/bot-group-membership.ts• L147-188 src/…/bot-group.ts• L1-120

Room turns

An owner message becomes turns for the chosen audience. The room can address one bot, all bots, or only mentioned bots. The room saves the message and its turns before delivery, so a restart can resume the same work instead of creating a duplicate turn.

Each bot receives the room history as quoted context. The bot's home transcript remains separate. A thread starts fresh sessions for the current members and takes its title from the first post.

sequenceDiagram
  participant O as Owner
  participant G as Group room
  participant B as Bot sessions
  participant A as Activity
  O->>G: Send message
  G->>G: Apply audience and save turns
  G->>B: Deliver admitted turns
  B-->>G: Reply or request
  G->>A: Update transcript and unread state
  A-->>O: Show activity or prompt

References: src/…/bot-group-delivery.ts• L21-98 src/…/bot-group-delivery.ts• L233-287 src/…/bot-group-store.ts• L222-245

Peer requests and approvals

Bots in a group can ask another current member a question, request a handoff, or request a status update. The system checks that the request belongs to an active owner message and that both members are still active.

Approvals and structured questions pause a bot turn until the owner responds. The desktop and phone collect these prompts in the group room so the owner can select the waiting bot and answer or cancel the request.

References: src/…/bot-group-peer-requests.ts• L35-87 src/…/bot-group-peer-requests.ts• L172-230 src/…/BotGroupApprovalDock.tsx• L19-99 mobile/…/MobileBotGroupRoom.tsx• L115-124

Work items and owner attention

Work items turn bot work into durable units that an owner can track outside a chat. They connect a bot, its source conversation, its current state, owner questions, activity history, and related workers or external work.

Work items

An item moves through planned, working, needs you, done, and canceled states. A linked worker can move an item into working. Links provide evidence or output through workers, pull requests, URLs, and files.

The item view combines saved item events with current worker and pull-request facts. This keeps the item useful when a worker changes host or when its source chat is no longer available. Changes from outside the owning chat are sent back to that chat so the bot can continue from the new state.

References: src/…/bot-items-schema.ts• L11-77 src/…/bot-items-runtime.ts• L135-167 src/…/bot-items-runtime.ts• L220-270 src/…/bot-items-writes.ts• L92-120 src/…/bot-items.ts• L5-73

Owner attention

Needs you is the shared attention state for item questions, bot prompts, connector access requests, and blocked work. It separates an empty result from a failed read, so an unreadable source does not appear as an empty queue.

Opening a bot surface marks the relevant activity as seen while preserving new activity that arrives during the open view. The desktop and phone can therefore show the same owner work without requiring an open bot chat.

References: src/…/bot-items-runtime.ts• L220-225 src/…/BotActivityPanel.tsx• L97-152 mobile/…/MobileBotPanel.tsx• L145-178

Connector and OAuth access

Connectors give bots controlled access to external conversations and tools. Access is scoped to a bot and connector. The host remains responsible for deciding whether a person may ask that bot to act.

Connector access requests

An external person can request access to a bot through a connector. The cloud records the account decision first. The bot's host then adds the person to the connector member list or reports that the request is expired, belongs to another host, or cannot fit.

The host reads requests for its own bots and recovers grants whose member update did not finish. This keeps a cloud grant and the host's member list aligned without asking the owner to repeat a completed decision.

References: src/…/bot-access-host.ts• L41-71 src/…/bot-access-host.ts• L74-140 src/…/bot-access-host.ts• L154-188 src/…/bot-access-grant.ts• L1-100

Tool credentials and OAuth

The host keeps each bot tool credential as a protected record bound to the bot's home and credential id. Saved headers and host-managed OAuth sign-ins are separate access types. The bot's agent receives a local relay address and a bot-scoped token instead of the provider secret or OAuth token.

OAuth uses a short-lived sign-in attempt and refreshes tokens on the host. Replacing or revoking a sign-in ends its related tool sessions and open calls. This lets the bot use a connected service while keeping provider access under host control.

References: src/…/bot-tool-credentials.ts• L29-45 src/…/bot-tool-credentials.ts• L86-108 src/…/bot-tool-credentials.ts• L266-314 src/…/bot-tool-oauth.ts• L14-40 src/…/bot-tool-relay.ts• L46-88 src/…/bot-tool-relay.ts• L135-186

Scheduled and event-driven automation

Automation turns a bot prompt into a repeatable or event-driven run. A run records its trigger and its destination, then presents its conversation and result with the bot's other activity.

Automation destinations

An automation can start a background conversation in the bot's home, send to the home chat, continue an existing conversation, or target a named chat. If a named chat is gone, the run can fall back to the home chat when its policy allows it. Otherwise it reports that the destination no longer exists.

The run's conversation appears in the bot chat tree with its workers. This gives the owner one activity view for manual chats, connector threads, side chats, and automation runs without making them one session.

References: src/…/bot-automation-sessions.ts• L22-38 src/…/bot-automation-sessions.ts• L70-112 src/…/bot-items-runtime.ts• L135-152 src/…/bot-chat-tree.ts• L4-25

Scheduled background activity

Look around is bot-owned scheduled work that starts after the bot has had a conversation. Look now starts the same kind of conversation on demand. Memory tidy-up uses the same host automation tick.

Scheduled work waits for a fully awake host. Each run has an awake-time limit and stops when it exceeds that limit. A run interrupted by sleep is recorded as missed rather than as a normal bot failure. Repeated failures can turn Look around off.

References: src/…/bot-look-around-schedule.ts• L16-49 src/…/bot-look-around-runtime.ts• L23-59 src/…/bot-look-around-runtime.ts• L79-92 src/…/bot-look-around-runner.ts• L99-151 src/…/bot-background-run.ts• L22-40

Automation controls

Owners can enable or pause an automation and can request an immediate run. The desktop shows automation rows, upcoming work, and run activity. The phone shows the same bot-scoped rows with pause, resume, and Run now actions.

Deleting a bot also deletes automations that run as that bot. This prevents future scheduled or event-driven prompts from targeting a removed bot.

References: mobile/…/MobileBotAutomationsTab.tsx• L20-65 mobile/…/MobileBotAutomationsTab.tsx• L69-120 src/…/bot-automations-removal.ts• L1-14 src/…/bot-background-run.ts• L194-263

Desktop and mobile surfaces

Desktop and mobile surfaces present the same host-backed bot activity. They show chats, workers, work items, automations, prompts, connector access, and settings. They keep actions disabled when the host is offline or lacks the needed capability.

Desktop activity

The desktop Activity panel brings owner questions and work items to the front, then shows upcoming and current activity. Its Chats view groups workers under their parent chats and supports chat and worker search.

The group view provides a shared transcript, member and reply controls, stop actions, and an approval dock. The connector view uses the bot settings surface so external access stays with the other bot controls.

References: src/…/BotActivityPanel.tsx• L53-65 src/…/BotActivityPanel.tsx• L97-152 src/…/BotChatsPanel.tsx• L77-149 src/…/BotGroupChat.tsx• L241-295 src/…/BotConnectorsPanel.tsx• L8-23

Mobile activity

The phone uses a full-height bot panel with Items, Chats, and Files tabs. The Chats view shows upcoming work, chat trees, and workers. A separate Automations section provides the same run controls as the desktop.

The phone can open a group transcript with member controls, reply modes, stop actions, and pending approvals. It resolves bot session links across paired computers and reports offline, ambiguous, missing, or outdated hosts instead of opening an uncertain session.

References: mobile/…/MobileBotPanel.tsx• L58-81 mobile/…/MobileBotPanel.tsx• L221-317 mobile/…/MobileBotActivityTab.tsx• L16-105 mobile/…/MobileBotGroupRoom.tsx• L115-149 mobile/…/MobileBotGroupRoom.tsx• L219-319 mobile/…/BotSessionLinkResolver.tsx• L103-155 mobile/…/BotSessionLinkResolver.tsx• L201-242

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to chat identity or destination must keep connector links, automation run chats, item sources, and phone session links aligned.
  • Changes to group membership or reply rules must preserve room revisions, session cleanup, queued-turn checks, and frozen output.
  • Changes to item states, questions, snoozes, or events must preserve Needs you counts and mail to the owning chat.
  • Changes to connector access decisions must preserve the cloud decision, host membership update, and retry of a granted-but-not-added request.
  • Changes to OAuth or tool credentials must preserve relay grants, token refresh, session invalidation, and bot deletion cleanup.
  • Changes to automation targets or run records must keep chat-tree rows, run history, item source labels, and phone controls consistent.
  • Changes to host capability or RPC contracts must preserve desktop offline behavior and phone host resolution failures.

Important failure modes

TriggerConsequenceGuard
A group send uses an old revisionThe message is rejected instead of using a stale member list.Re-read the room and send with its current revision.
A group has no active membersThe room stays readable but cannot accept a new message.Require a current member before starting a thread or sending.
A group member leaves or its bot is deletedFuture work for that member is revoked or frozen.Check active membership before admission and preserve former-session history.
A queued turn cannot be tied to its original group requestThe turn is refused rather than delivered to an unknown room.Verify the operation, member, room, and active root request.
The cloud grants connector access but the host cannot save the memberThe person has a grant but the bot still cannot receive that person's messages.Re-read granted requests and retry the host-side member update.
A tool credential or OAuth grant endsOpen calls and related tool sessions stop.End relay admission and require a new credential or sign-in.
A scheduled run starts during sleep or passes its awake-time limitThe run is deferred, missed, or stopped without being reported as a normal failure.Require full wake and enforce the run's awake-time limit.
A paired host is offline, ambiguous, or out of dateThe phone cannot safely open the requested bot session.Resolve the host before opening and show the host-specific failure.

Key files

FileWhy to read it
src/…/bot-chat-session.tsDefines the bot home chat and background session boundary.
src/…/bot-conversations.tsMaps connector conversations to bot sessions and work links.
src/…/bot-group-membership.tsShows group creation, membership changes, threads, and cleanup.
src/…/bot-group-delivery.tsShows how room messages become durable bot turns and recoverable deliveries.
src/…/bot-group-peer-requests.tsDefines group-scoped questions, handoffs, and worker reports.
src/…/bot-items-schema.tsDefines durable work-item states, events, and links.
src/…/bot-items-runtime.tsConnects item views, source chats, worker facts, and owner notifications.
src/…/bot-access-host.tsDefines cloud-backed connector access decisions and host membership updates.
src/…/bot-tool-credentials.tsDefines host-owned tool credentials and OAuth entry lifecycle.
src/…/bot-tool-relay.tsShows how agents use tools without receiving provider secrets.
src/…/bot-automation-sessions.tsDefines automation destinations and run-to-chat links.
src/…/bot-look-around-runner.tsShows scheduled bot activity, wake checks, limits, and failure recording.
src/…/BotActivityPanel.tsxShows the desktop owner view for items and activity.
src/…/BotChatsPanel.tsxShows desktop chat and worker grouping plus search.
mobile/…/MobileBotPanel.tsxShows the phone bot panel and its Items, Chats, and Files surfaces.
mobile/…/MobileBotGroupRoom.tsxShows the phone group transcript, composer, and approval entry points.
mobile/…/MobileBotAutomationsTab.tsxShows phone automation controls.