The owner web app

This page is for developers changing the owner-facing web app. It records the rules each feature follows, the endpoints behind it and what only a real browser can check. How to use the app is user documentation, which belongs to a distribution; FreeInference’s is the Cloud Agents guide.

Sidebar and conversation list

Grouping (by project or in one list), ordering (last updated or manual), expanded projects, manual positions and added workspaces are stored per signed-in user in the current browser. Conversation ids are stored for ordering only once manual order is chosen, and switching back to last updated keeps the saved positions. Pinned conversations have one manual order shared by both groupings, appear once outside the project folders, and return to their usual place when unpinned. Conversations without a repository are grouped in a Start from scratch folder.

Search matches conversation titles and full repository names across history. Its shortcut is Command+K on a Mac and Ctrl+K elsewhere; on a Mac, Control+K stays the text field’s own key. Each result shows the conversation’s original title and opens its latest turn. Restoring an archived conversation refreshes its sidebar row at once without changing its activity time.

A completed turn shows an unread dot until it is opened, and a completion already on screen is marked read. Read receipts are saved to the account: open tabs synchronize on focus, on reconnection and every 30 seconds while visible, fetching only changes after the first sync. Receipts a browser held before cloud synchronization are imported the next time it opens the app; offline reads are cached and uploaded when the connection returns. Pinning, archiving and renaming do not reset read state.

Creating a repository

Create repository, in the workspace and new-task repository pickers, creates a repository in the signed-in user’s personal GitHub account with a README, so it has a default branch; organization repositories are not offered. It needs the GitHub App’s Repository creation: write permission, or Administration: Read and write (see Credentials). Creating a repository does not give the App access to it, and repository-access checks still apply. After a connection failure the request may have succeeded on GitHub, so the dialog keeps what was entered and does not retry by itself.

Getting started

An account with no conversations, archived ones included, sees a Getting started row: Connect GitHub, Grant a repository, then Run your first task. Connection and repository state come from /config, and the row is hidden when the deployment has no GitHub App configured. The sidebar, the new-task page and the conversation explanations share one first-run check, GET /v1/agent/conversations?include_archived=true&limit=2, which refreshes on page changes until two conversations exist. Skip hides the row per account in the current browser, with an Undo notice; the settings page brings it back.

Conversations API

GET /v1/agent/conversations returns conversations and next_cursor. Each row carries the latest job, the canonical title, archived and last_activity_at.

Parameter	Meaning
q	Case-insensitive literal substring of the title or full repository name; at most 200 characters. % and _ match themselves
repo	Exact repository
temporary	true lists only conversations without a repository; not combined with repo
include_archived	Include archived conversations; defaults to false
pinned	true or false restricts to one pin partition; omitted, both
limit	Page size, 1–200; defaults to 50
cursor	Opaque cursor from the previous response, scoped to the owner and the filters

Rows are ordered by pin time, then meaningful activity, then thread id. Conversation and message updates and job transitions count as activity; lease heartbeats do not. A conversation can move ahead of an older cursor, so a client refreshes from the first page when activity changes. The grouped view requests unpinned rows for each expanded repository and one global pinned list, and refreshes loaded rows in batches of up to 200. The backend finds each matching conversation’s most recently updated job through the thread/update index, applies the page boundary, and only then reads the latest turn for that page; keyset pagination does not make the query constant-time across all of an owner’s conversations. /jobs keeps its separate semantics.

Sources: AgentsSidebar.tsx, sidebarPreferences.ts, catalog.py and conversation_queries.py.

Conversation view

The turn rail

The rail sits in the Chat column’s right gutter. It appears when the conversation has at least two visible turns, the column is at least 720px wide, the reading area is at least 200px high and the device reports a fine pointer; Trajectory has none. The current turn has the longest, darkest mark, and a hovered or focused mark widens slightly. Mark lengths show interaction state only, never message length, duration, tokens or progress. Marks keep their spacing in long conversations; the rail scrolls on its own, with faded ends, and scrolling it does not scroll the transcript.

A preview shows the question as sent, not the conversation title, and the attempt’s last visible reply once the turn is terminal, so a running answer does not change beneath the pointer. It excludes reasoning, tool arguments, tool output and runtime records, and caps the question at 50 characters and the reply at 120. Copied Fork history uses durable messages for both transcript and preview, even where those turns have no stored event log.

A jump places the turn’s first question about 24px below the top of the reading area, or a turn without a question at its first visible content. It changes neither the URL, the selected attempt nor the workspace state. A later jump, manual scrolling or leaving the conversation cancels an unfinished one; a target that cannot be found leaves the transcript in place and announces that the turn is unavailable. Hovering and jumping send no request and persist nothing. A historical turn link limits the rail to the turns that view rendered.

The rail is a named navigation region of real buttons with one mark in the tab order; arrow keys, Home and End reach the others. The current mark has aria-current, the preview is the mark’s description, and a requested jump is announced once, while streaming output announces nothing.

Reading position

The transcript either follows new output at its end or holds the reader’s text in place as output arrives. It opens following, and follows again after Back to bottom, scrolling to the live end, or acceptance of a follow-up the reader sent. Scrolling up, jumping through the rail or selecting an older attempt holds the position. While held, new content adds a dot to Back to bottom and updates its name, without pulling the reader back. Switching to Trajectory and back keeps the position; reloading opens at the end.

Tasks and subagents

The Tasks and subagents window shows the selected turn and attempt’s latest recorded task list and delegated agents. It appears only when one of them has meaningful recorded data. A task creation result links the assigned id to the task’s name, so later status updates change the same row; Status not recorded means the selected events hold no status for it.

A subagent card’s reply, under Returned to the main agent, comes from where each runtime records it:

• Claude Code’s Agent or Task, and OpenCode’s and Kilo’s task, return the agent’s answer as the call’s own result; Claude records the agent’s status beside it.

• Codex returns a finished agent’s answer, or its error, as the message of the agent state its wait call reports.

• pi has no subagents.

A tool from an MCP server is never shown as a task list or a subagent, whatever its name; Codex, pi, OpenCode and Kilo sessions recorded before each call stored its MCP server can still show one as a subagent. A card says when a reply is still pending, was not recorded or was stored in part, and a background launch says it returned only a launch notice. Trajectory links a child step to its delegating step through runtime ownership records: Claude Code records the delegating call, and Codex the subagent’s own thread. Sessions recorded before those records keep a flat step list.

Workspace pane keyboard

Workspace, Git, file-list and terminal tabs select a view with Left/Right, Home and End while focus stays in the tab strip. Narrow Git panes use a changed-file selector so the diff keeps the width, and the diff and file preview are keyboard-scrollable regions. Opening a file in a narrow pane focuses its preview; Back or Escape returns to the list and focuses that file.

Checking it in a browser

Unit and DOM tests cover the navigation data, focus and an injected box model (useConversationScroll.dom.test.tsx). Markdown reflow, the sticky composer, resize timing and real pixel positions need a browser and a conversation with several turns:

1. Click a middle mark. Its question lands about 24px below the reading area’s top and the mark becomes current.

2. Scroll well into a long turn until its question is off-screen. That turn’s mark stays current.

3. Scroll up while output streams. The text keeps its screen position within a few pixels and Back to bottom appears.

4. Use Back to bottom, or scroll to the end. Following resumes; scroll up again and it stays paused.

5. Try columns on both sides of 720px, reading areas on both sides of 200px, and touch input. Without the rail, the transcript still scrolls normally.

6. Expand a tool row, resize the composer, and open and close the workspace while reading history. The text under the reader stays in place.

7. With about 100 turns, check mark spacing, rail scrolling and keyboard access to every mark.

8. Fork a conversation; the copied turns have marks and previews.

9. Switch to Trajectory and back: no rail there, and Chat keeps its position.

10. Repeat the keyboard checks in both languages, both themes and with reduced motion.

The design and its sizing measurements are in the turn navigation design. Sources: JobDetail.tsx, TurnNavigator.tsx, conversationTurnNavigation.ts and useConversationScroll.ts.

Tool approvals

The Approvals inbox lists pending MCP calls across the owner’s conversations, including ones a collapsed task list hides. Its badge counts the loaded calls, with a trailing + when more exist. Approve releases that one held request under its current authorization and attempt fence; Deny refuses it. The inbox never changes a conversation’s permission rules. The queue refreshes when the owner’s change stream reports a relevant change, with polling as a fallback. An expired call leaves the queue even before the worker records the expiry, and a decision that loses a race with expiry or another tab cannot revive it.

Always allow, in a conversation’s tools panel, records the approval and the future permission in one server-side transaction, so the owner can leave or refresh after submitting. The rule is saved once no call on that conversation’s connection is waiting for approval or dispatch, and covers only the named capability in that conversation. Before saving, the server checks the owner, connection and policy revisions and the capability fingerprint again: a reconnection, a disabled connection, a permission change or a changed capability definition discards the intent instead of restoring a revoked permission. The call history shows whether the save is pending, applied or discarded.

A held call waits up to ten minutes. Claude Code’s per-server HTTP request timeout and remote idle timeout are set to the same 26-minute window as its overall tool timeout; raising only the overall timer would leave the network timers able to abandon a request that Approvals still shows as pending. A client that accepts SSE gets an immediate response and keepalive comments during the wait, then the call’s single JSON-RPC result or error. Disconnecting cancels the wait and expires the approval; nothing keeps dispatching on behalf of an abandoned request. An expired approval was never dispatched, and a changed session authorization also stops a held call before dispatch. An error after dispatch can leave the outcome unknown.

GET /v1/agent/mcp/invocations?pending_only=true reads the authenticated owner’s pending inbox; job_id or thread_id narrows it. History reads need one of those scopes, so omitting both never exposes account-wide history. limit defaults to 50 and accepts 1 to 100. A response carries invocations, has_more and next_before_id; while has_more is true, pass next_before_id as before_id. Ids run newest first and the cursor is exclusive, so new calls do not shift older pages. Reads and decisions are scoped to the owner and omit deleted conversations, whose audit history is kept. Reading never changes an invocation or grants a permission. The relay side is in MCP servers.

Memory, avatars and home suggestions

Memory is the lasting rules agents follow for an owner. Avatars and home suggestions are derived from recent requests on each read; nothing about them is stored, given to agents or affected by memory settings. The memory redesign explains the split.

Memory

Each memory is one rule in one of two scopes: user memory applies to every project, and project memory to one repository, where it takes precedence.

• Tools. Every task can call memory_save, memory_update and memory_delete on the platform’s MCP endpoint; the agent decides when, and writes each memory as one English sentence. No extra model call is made. Updating or deleting archives the old memory, owner-written ones included.

• Injection. When a task starts, its repository’s active memories and the owner’s user memories are added before the request with the ids the tools take, up to 12,000 characters: repository memories first, and within a scope the most recently written or edited first. Only the memories added get a new last_used_at; nothing is added when there are none.

• Fence. Every write checks, in its own transaction, that the task’s attempt is still the running one, so a stopped or replaced task cannot change memory even with a request under way.

• Scope. An agent saves to its task’s repository unless told a rule applies to every project; a chat without a repository saves user memories. An agent sees and changes only its task’s repository memories and the owner’s user memories.

• Limits. Each scope has its own switch; a scope that is off is neither injected nor written, and keeps its memories. A scope keeps 30 active memories of at most 240 characters. When it is full, the least recently used agent-saved memory is archived to make room; owner-written or edited memories never are, so a scope full of them refuses a new one. Archived memories can be restored and are deleted after 90 days, by an hourly purge in every control-plane process. Adding a memory identical to an active one in the same scope, ignoring case and final punctuation, returns the existing memory.

GET /v1/agent/memories returns every project’s memories, and ?repo=owner/repository one repository’s, as {repo, enabled, memories, archived}. POST with {content, repo} adds an owner-written memory (repo is null for every project). PATCH /v1/agent/memories/{id} with {content, repo, expected_version} rewrites or moves it, DELETE with {expected_version} deletes it, and POST /v1/agent/memories/{id}/restore with {expected_version} restores an archived one. DELETE /v1/agent/memories clears one scope, archived memories included. PUT /v1/agent/memories/settings with {repo, enabled} turns a scope on or off, and GET /v1/agent/memories/projects lists the repositories the owner worked in or keeps memories for. Refusals carry a typed reason: memory_changed (409, a stale version), memory_scope_full (409), memory_invalid (422: credentials, over 240 characters, or limited to the current task) and memory_not_found (404). No response echoes memory text. The tables and their migrations are in the upgrade notes.

Avatars and home suggestions

Without an uploaded profile photo, an account is shown as a generated Pokémon companion: one of seven, with an expression and pose fixed for the account. The account menu and Profile show its fixed form, which GET /v1/agent/profile returns as companion_data_url, derived from the account alone so showing it on every page reads no requests. On the homepage, the habitat colors and orbiting badges follow the work areas detected, with English keywords, in the owner’s latest 50 requests. Every shape is drawn locally as a standalone SVG; account identifiers and request text are never embedded, and no image service or model is used.

The homepage also lists up to three fixed suggestions, chosen by counting English keywords in the same 50 requests: change requests without success checks or verification, failure reports without reproduction steps, and reviews without a stated scope. Only the owner’s own lines count: quoted text, code blocks, assistant replies, forked copies, automatic goal turns and deleted chats are ignored. GET /v1/agent/insights returns {focus_areas, suggestions, avatar}, derived on each read.

Workspace files

The Files pane reads the retained sandbox’s current repository and is read-only. Paths use forward slashes and stay inside the repository: absolute paths, parent traversal and .git paths are refused, and symlinks are shown without being followed. A folder listing is bounded: entries past the limit, and names that are not UTF-8, are left out, and the folder says so instead of reading as complete. An entry left out for the limit can still be opened by path. Returning to the workspace root cancels an unfinished path read, so a late response cannot move the tree. A file the run deleted reports that rather than a failed read.

Copy and download offer only complete contents within the preview size limit; an oversized file shows the limit instead of a partial copy. Raster images get a preview, and HTML and SVG stay escaped text. Download workspace, on each turn’s result in a conversation without a repository, saves the workspace as one .tar.gz without .git directories and metadata files; other hidden files are included and .gitignore does not filter it. A workspace over the server’s download limit is refused rather than saved in part. See Temporary workspaces.

Smaller features

• Notifications. My Settings → Notifications enables browser notifications for agent questions and finished turns, each toggled separately and stored per account. While the app is open they cover every chat, and clicking one opens its turn; nothing is delivered while the browser is closed.

• Plugins. Chosen with + → Plugins before a chat’s first task. Claude Code and Codex accept name@marketplace with a GitHub repository or public HTTPS marketplace source; pi, OpenCode and Kilo accept npm package names, optionally pinned to an exact version such as @example/plugin@1.2.3. Up to eight per chat. The sandbox installs them before the first prompt, and a failed installation stops startup as a task error. Selections persist with the chat and are inherited by Fork.

• Prompt rewriting. See Draft prompt rewriting.

• Review. Starts an independent code-review subagent in a workspace tab, covering every change since the conversation’s original base, current workspace changes included, and instructed not to edit files. It needs an available native Fork, so it cannot start from an archived chat or one whose context was lost. Selecting it again reopens the chat’s existing review.

• Watch PR and merge. Starts a follow-up in the same chat that watches checks and reviews, fixes failures and feedback, and merges once the current head meets the required checks and reviews; repository rules decide what may merge without a person. It keeps unsent composer text and attachments, and starts only while no chat sharing the workspace has active work or waiting messages. The agent needs source-control tools that read checks and reviews, mark drafts ready and merge: the GitHub preset with a token holding Contents and Pull requests read and write. A connection to /mcp/readonly must be reconnected with the preset. Watching ends with the turn’s timeout, and a turn that made fixes ends so the platform can publish them.