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
| Trigger | Consequence | Guard |
|---|---|---|
| A group send uses an old revision | The 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 members | The 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 deleted | Future 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 request | The 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 member | The 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 ends | Open 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 limit | The 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 date | The phone cannot safely open the requested bot session. | Resolve the host before opening and show the host-specific failure. |
Key files
| File | Why to read it |
|---|---|
| src/…/bot-chat-session.ts | Defines the bot home chat and background session boundary. |
| src/…/bot-conversations.ts | Maps connector conversations to bot sessions and work links. |
| src/…/bot-group-membership.ts | Shows group creation, membership changes, threads, and cleanup. |
| src/…/bot-group-delivery.ts | Shows how room messages become durable bot turns and recoverable deliveries. |
| src/…/bot-group-peer-requests.ts | Defines group-scoped questions, handoffs, and worker reports. |
| src/…/bot-items-schema.ts | Defines durable work-item states, events, and links. |
| src/…/bot-items-runtime.ts | Connects item views, source chats, worker facts, and owner notifications. |
| src/…/bot-access-host.ts | Defines cloud-backed connector access decisions and host membership updates. |
| src/…/bot-tool-credentials.ts | Defines host-owned tool credentials and OAuth entry lifecycle. |
| src/…/bot-tool-relay.ts | Shows how agents use tools without receiving provider secrets. |
| src/…/bot-automation-sessions.ts | Defines automation destinations and run-to-chat links. |
| src/…/bot-look-around-runner.ts | Shows scheduled bot activity, wake checks, limits, and failure recording. |
| src/…/BotActivityPanel.tsx | Shows the desktop owner view for items and activity. |
| src/…/BotChatsPanel.tsx | Shows desktop chat and worker grouping plus search. |
| mobile/…/MobileBotPanel.tsx | Shows the phone bot panel and its Items, Chats, and Files surfaces. |
| mobile/…/MobileBotGroupRoom.tsx | Shows the phone group transcript, composer, and approval entry points. |
| mobile/…/MobileBotAutomationsTab.tsx | Shows phone automation controls. |