Bot orchestration
Bot orchestration is the bot platform that gives each bot a lasting identity and coordinates conversations, shared work, connector access, work items, background runs, sharing, and agent execution. A desktop host owns the durable bot state and work context. Cloud services connect approved external systems, while desktop and mobile clients present the same host-scoped activity.
System model
Persistent bot identity
A bot is a named worker with a stable record, a private home, a selected agent, and a home workspace. Its home holds its instructions and memory. The record connects that home to conversations, connector access, work preferences, and client state. This lets the bot keep its identity when a chat resets, a client changes, or work continues in the background.
The host treats the bot home as an owned boundary. Orca manages the files that describe the runtime connection, but preserves the owner's soul and memory. Creation and deletion therefore keep the record, home, workspace, automations, group membership, and tool access aligned.
References: src/…/bot-types.ts• L120-204 src/…/bot-home.ts• L121-233 src/…/bot-controller.ts• L94-127 src/…/bot-controller.ts• L141-187 src/…/bot-controller.ts• L286-312
Conversation and collaboration model
The bot's home chat is its ongoing conversation with its owner. Other chats can represent connector threads, automation runs, or background work. Each chat runs as a bot-scoped agent session, so its source and intended actor stay linked to the work it produces.
Groups add a shared room above those sessions. Each member bot has its own session. The room coordinates delivery, threads, peer requests, approvals, and stop actions. A reply mode can address all bots, one named bot, or only bots that the message mentions.
The following flow shows how a message becomes work for one or more bot sessions and returns as shared activity.
flowchart LR
A[Owner or connector message] --> B{Conversation target}
B --> C[Bot home chat]
B --> D[Connector or automation chat]
B --> E[Bot group room]
E --> F[Member bot sessions]
C --> G[Agent turn]
D --> G
F --> G
G --> H[Reply, worker, item, or request]
H --> I[Host activity and client views]
References: src/…/bot-chat-session.ts• L40-86 src/…/bot-chat-session.ts• L100-236 src/…/bot-chat-session.ts• L256-333 src/…/bot-group-runtime.ts• L48-85 src/…/bot-group-runtime.ts• L116-161 src/…/bot-group-delivery.ts• L21-99 src/…/bot-group-schema.ts• L7-103
Work items and owner attention
Bot work has two linked forms. Agent workers run in local, paired, or server-owned workspaces. Bot items give that work a durable owner-facing record with status, comments, links, questions, and history. The item view reads worker and pull-request facts from their source records, so an unavailable read does not become a false success.
Items turn bot activity into work that an owner can review. Open work can be planned, working, or waiting for the owner. Closed work can be done or canceled. Snooze and stale state guide attention without changing the work status. A Needs you item can carry a clear question with quick replies, so the owner can answer in the item and wake the owning chat.
References: src/…/bot-items.ts• L1-73 src/…/bot-items.ts• L183-208 src/…/bot-item-ask.ts• L45-58 src/…/bot-items-runtime.ts• L135-167 src/…/bot-items-runtime.ts• L220-270 src/…/BotItemView.tsx• L187-265
Connector access and tool capabilities
Connectors let a bot receive work from services such as Slack, Linear, GitHub, and Google. The bot record names its connected workspaces and the people allowed to ask it. When a connector user is not allowed, the platform creates an access request that the owner can review and grant or decline.
Agent tools use a separate capability boundary. Saved credentials stay on the host and are bound to the bot and credential. The agent receives an Orca relay grant instead of the saved secret. The relay adds the approved credential, can renew an Orca-managed sign-in, and stops calls when the bot, credential, or sign-in ends.
Access follows a chain of authority:
- A connector identifies a requester or an external event.
- The host checks the bot's connector and member policy.
- The owner grants access when approval is needed.
- Orca supplies only the connector or tool capability allowed for that bot.
- The bot turn records the source so activity and work remain traceable.
References: src/…/bot-types.ts• L68-103 src/…/bot-types.ts• L120-155 src/…/bot-access-request.ts• L28-113 src/…/bot-access-reach.ts• L104-123 src/…/bot-google-access.ts• L1-45 src/…/bot-tool-relay.ts• L46-88 src/…/bot-tool-relay.ts• L147-186
Background execution
Background execution lets a bot continue useful work without an open chat. Scheduled or owner-started runs can inspect connected context, update memory, create work items, and report results into Activity. Look around and memory tidy-up are host-managed examples that produce a suggestion or recorded result.
The host controls when a run may start and how much awake time it may use. A scheduled run needs a full wake and is deferred when power is not safe. If the run exceeds its awake-time limit, the host stops the turn and records that it did not complete normally.
References: src/…/bot-background-run.ts• L22-40 src/…/bot-background-run.ts• L50-65 src/…/bot-background-run.ts• L133-191 src/…/bot-background-run.ts• L194-279 src/…/bot-activity-host.ts• L154-209
Sharing and portability
Bot sharing packages selected parts of a bot for review before publication. A bot has one canonical share link. Publishing creates or updates the version served by that link. Stopping sharing revokes it. Receiving a bot reviews a specific version before creation and checks that the link still serves that version.
Sharing moves bot behavior without moving private credentials. Secret content is blocked from publication. The review keeps the source version and package digest, so an old review cannot silently create a newer bot.
References: src/…/bot-share-service.ts• L45-129 src/…/bot-share-service.ts• L131-147 src/…/bot-share-service.ts• L221-287 src/…/bot-share-service.ts• L313-347
Execution and client boundaries
Host execution
The execution host is the machine that owns a bot's home, workspace, agent sessions, and local records. Work can also run on a paired computer or server. Work records keep the execution host and workspace lineage so Activity can show where the agent actually ran. A workspace handed to a bot remains the bot's work even when another coordinator owns the worker inside it.
The desktop runtime is the source of truth for bot records and host activity. Its Activity view joins chats, connector links, automation runs, live agent status, recorded workers, handed workspaces, and suggestions into one client-neutral read.
References: src/…/bot-types.ts• L120-129 src/…/bot-work-runtime.ts• L75-145 src/…/bot-work-runtime.ts• L220-259 src/…/bot-activity-host.ts• L30-56 src/…/bot-activity-host.ts• L139-209
Desktop and mobile presentation
Clients read host-scoped bot listings and use the same bot identifiers, workspace scope, activity facts, and access decisions. The desktop presentation groups owner attention around Items, Chats, and Activity. It also exposes automations, settings, suggestions, connector setup, and access requests.
Mobile can list bots from the paired desktop and reachable relay servers, keep the last usable listing during reconnect, and open a bot on the host that owns it. Bot links resolve a bot home, session, or access request by host identity instead of name alone. Group rooms use the authoritative host transcript and support messages, reply audience, stop actions, approvals, and membership changes.
See bot conversations and automation for detailed conversation and automation behavior.
References: src/…/BotActivityPanel.tsx• L53-65 src/…/BotActivityPanel.tsx• L97-243 src/…/BotNeedsYouSection.tsx• L315-421 src/…/BotUpNextSection.tsx• L263-337 mobile/…/use-host-bots.ts• L51-109 mobile/…/BotLinkRouter.tsx• L34-79 mobile/…/BotSessionLinkResolver.tsx• L77-164
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the bot record, home files, home workspace, chat session, automations, groups, and tool grants consistent across create, update, agent change, and delete flows.
- Keep bot and group operations serialized with session admission so a reset, stop, membership change, or retry cannot act on a retired session.
- Keep item ownership, chat roots, worker lineage, live workspace facts, pull-request facts, and owed activity mail aligned when item or orchestration contracts change.
- Keep connector member policy, access-request expiry and redemption, Google reach, link owner data, and client refresh signals aligned.
- Keep tool credential sealing, bot-folder binding, relay grants, sign-in revisions, session identity, revocation, and deletion cleanup aligned.
- Keep background-run wake checks, awake-time limits, stop behavior, sleep markers, suggestions, and Activity results aligned.
- Keep share package selection, review version checks, digest checks, secret filtering, canonical-link behavior, and recipient creation aligned.
- Keep execution-host identity and workspace lineage in desktop reads, mobile listings, bot links, group routes, and notification targets.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A bot record and its home folder disagree | The host can open the wrong identity or restore a deleted bot | Bind the home to bot.json, validate ownership, and persist record changes with the home operation |
| A bot chat is reset while a message is being admitted | The message can enter an old session or create two home chats | Hold a per-bot lock through session selection and message admission |
| A group delivery or worker admission is interrupted | Some members can miss a turn or receive a duplicate turn | Keep per-room queues, operation ids, pending delivery records, and startup resume |
| A worker or workspace read is unavailable | Activity can claim work is done or hide work that still runs | Preserve lineage and show unknown or missing state instead of inferring success |
| An access request expires or is redeemed on another host | The requester is added to the wrong bot or remains falsely pending | Use single-use tokens, host ownership checks, and explicit redemption outcomes |
| A tool credential changes during an agent call | A request can use an old sign-in or an ended secret | Bind credentials to the bot and credential id, revoke open calls, and fence sessions |
| A scheduled run starts during a dark wake or exceeds its awake limit | The run can stall, consume an invalid slot, or continue without a trustworthy result | Require full wake, track awake time, and stop late turns |
| A share review refers to an older link version | A recipient can create content that the owner did not approve | Re-resolve the link and compare its version before creation |
| A mobile link matches several hosts or a host is outdated | The phone can open an unrelated bot or fail without context | Resolve host answers, offer a picker, and report update or reachability state |
Key files
| File | Why to read it |
|---|---|
| src/…/bot-types.ts | The durable bot identity, connector links, member policy, chat link, work preferences, and provenance fields |
| src/…/bot-controller.ts | The bot lifecycle and the relationship between records, homes, workspaces, groups, and automations |
| src/…/bot-home.ts | The bot home boundary, owner files, generated files, memory seed, and ownership check |
| src/…/bot-chat-session.ts | Home-chat creation, reset, message delivery, native-session admission, and background session choice |
| src/…/bot-group-runtime.ts | Group room lifecycle, delivery ownership, peer scope, and recovery |
| src/…/bot-group-delivery.ts | Group message admission, audience selection, reply collection, and replay |
| src/…/bot-work-runtime.ts | Worker lineage, execution hosts, workspaces, connector conversation links, and work context |
| src/…/bot-activity-host.ts | The client-neutral Activity view assembled from chats, workers, automations, and handed workspaces |
| src/…/bot-items.ts | The owner-facing work-item contract and the meaning of statuses, links, stale state, and attention |
| src/…/bot-items-runtime.ts | Item persistence, worker and pull-request joins, chat ownership, and recovery mail |
| src/…/bot-access-request.ts | Connector access requests and the member changes that a grant permits |
| src/…/bot-access-reach.ts | The shared view of what a person can reach through a bot |
| src/…/bot-tool-credentials.ts | Host-side storage and authority rules for bot tool credentials and OAuth records |
| src/…/bot-tool-relay.ts | The boundary that turns a bot's local grant into an authenticated upstream tool call |
| src/…/bot-share-service.ts | Share preview, review, publication, update, receipt, and revocation semantics |
| src/…/BotActivityPanel.tsx | The desktop owner view for items, activity, automations, and suggestions |
| mobile/…/use-host-bots.ts | Host and server bot listings, refresh behavior, execution-host scope, and last-known data |
| mobile/…/BotLinkRouter.tsx | Bot-link host resolution, access-request redemption, host choice, and link failure states |
| mobile/…/BotSessionLinkResolver.tsx | Mobile opening of bot home and session links through the owning host |