Inbox Agent

Inbox Agent is CoWork OS's local-first, agent-assisted email workspace. It is designed to be more than a mailbox viewer: it keeps recent mail cached locally, syncs in the background, classifies work into action lanes, lets you reply or forward like a normal email client, and turns important threads into tasks, automations, Mission Control issues, and relationship memory.

The current product shape is:

• Classic inbox remains available as the familiar three-pane mailbox.
• Today mode is the agent-first working mode for deciding what needs attention now.
• Agent Rail and Ask Inbox share the right sidebar so thread actions, mailbox questions, live agent steps, answers, and evidence stay close to the message.
• @Inbox from the main composer routes mailbox questions into Inbox Agent without starting a normal task run.
• Provider state is authoritative for read/unread and supported server actions; the local database is the cache plus agent metadata.

What It Does

Inbox Agent helps you move from "read everything" to "act on what matters":

• sync Gmail and IMAP/SMTP mail into a local encrypted cache, then keep it fresh with background autosync
• classify threads into Unread, Needs reply, Suggested actions, and Open commitments
• group the current inbox into Today lanes: Needs action, Happening today, Good to know, and More to browse
• classify practical domains such as travel, packages, receipts, bills, shopping, newsletters, work, personal, and finance
• keep Inbox, Sent, and All views separate so outbound mail does not clutter received mail
• make unread mail visually distinct and update read/unread state through the provider when capability is available
• ask mailbox questions through Ask Inbox, with hybrid local/provider retrieval, live run steps, attachment-aware evidence, and matched email provenance
• generate AI summaries and AI reply drafts, while keeping drafts editable before send
• send a manual reply, reply-all, or forward without requiring an AI-generated draft
• extract commitments, edit commitment details, and mark already-handled threads done
• roll up noisy senders into a sender cleanup center
• show attachment chips and fetch/extract attachment text only on demand
• resolve contact identities across email, Slack, Teams, WhatsApp, Signal, iMessage, and CRM-linked handles
• reply via a linked non-email channel when that channel is a better target
• hand off a thread into Mission Control as a company issue and wake the recommended operator
• create inbox automations, reminders, scheduled review patrols, and Gmail forwarding automations
• emit mailbox events into Knowledge Graph, Heartbeat, triggers, playbooks, Mission Control, and daily briefings

Core Surfaces

Normal Email Client Actions

Inbox Agent supports direct email handling in the selected thread:

• Reply opens a manual composer with the latest inbound sender prefilled.
• Reply all includes the latest inbound sender plus other non-self recipients.
• Forward opens a manual composer with a forwarded-message block and no prefilled recipient.
• Cc/Bcc are supported in the manual composer.
• Send routes through the connected provider path: Gmail API for Gmail, AgentMail reply-all for AgentMail replies, and SMTP for IMAP/SMTP accounts.
• AI draft send sends the edited subject/body visible in the draft card, not the original generated text.
• After send, reply-needed state and the draft card are cleared for replies. Forwarding does not mark the original thread as handled.

Current compose boundary:

• The replacement-grade compose/outbox schema and IPC APIs exist for provider-backed drafts, scheduled send, undo send, and queued sends.
• The visible thread-level manual composer currently sends directly through the existing provider path.
• A full background outbox worker that drains queued compose drafts into Gmail API, Microsoft Graph, or SMTP is still a future provider execution pass.

Read, Unread, Done, And Commitments

Unread is a provider-backed message state. When supported, Mark read and Mark unread update the server mailbox, then reconcile local cache state. Gmail requires the Gmail modify scope for read-state changes.

Needs reply is an agent classification. It can be cleared when:

• you send a reply from Inbox Agent
• you use Mark done after handling the thread elsewhere
• the thread is reclassified and no longer needs a reply

Open commitments are extracted follow-up items, not the same thing as unread mail. If a commitment was already handled, use Mark done on the thread or update the commitment state in the commitments section.

Autosync And Local Cache

Inbox Agent loads cached mail immediately on startup and refreshes in the background. Autosync runs periodically while the app is open and syncs a bounded recent batch so the inbox behaves more like a normal mail client without blocking the UI.

Sync principles:

• provider state is the source of truth for read/unread, archive/trash, sent mail, and supported labels/folders
• local state stores cached message content, classification, Today/domain buckets, summaries, commitments, drafts, attachment metadata, and automation state
• ordinary listing is never blocked by attachment text extraction or LLM classification
• the UI can show "syncing", queued, failed, and reconnect states separately from cached mail

Ask Inbox From The Main Composer

Inbox Agent can be invoked directly from the normal task composer with @Inbox. You can either select Inbox from the Integrations section of the @ menu or type the raw lowercase form.

Example:

@inbox when do I need to make payment for my QNB credit card?

When the prompt starts with @Inbox or @inbox, CoWork strips the mention from the query, opens Inbox Agent, switches the right sidebar to Ask Inbox, and runs the remaining text there. This path uses the mailbox retrieval stack and mailbox evidence instead of the normal task executor.

Current boundary: attachments are not accepted on the @Inbox Ask Inbox route because the request is answered from mailbox evidence and indexed attachment text already known to Inbox Agent.

See Composer Mentions for the shared @ autocomplete behavior and integration-chip metadata contract.

Ask Inbox Sidebar

The right Inbox Agent sidebar has two tabs:

• Agent Rail for actions on the selected thread
• Ask Inbox for mailbox questions, live steps, answers, and evidence

The left Ask your mailbox... field is a quick launcher. Submitting it creates a run, switches the right sidebar to Ask Inbox, appends the question, and streams run progress. Ask Inbox also has its own composer pinned at the bottom so follow-up questions can continue in the same mailbox context.

Ask Inbox runs are session-local for now. They are not persisted across app restarts.

The visible step feed reflects backend work, including:

• classifying whether the prompt is a question or an action request
• planning mailbox search
• searching local FTS
• searching the local semantic mailbox index
• searching provider-native Gmail or Outlook/Microsoft Graph routes when available
• extracting or reading attachment text when relevant
• shortlisting and reading evidence
• generating an answer or creating reviewable drafts
• completion or error

Ask progress uses transient mailbox:askEvent IPC events. These are intentionally separate from persisted mailbox automation events, so progress updates do not trigger mailbox rules, Heartbeat, Knowledge Graph enrichment, or playbooks.

See Ask Inbox Architecture for the full implementation contract.

Attachments And Ask

Attachment handling is local-first and on demand:

• sync stores attachment metadata such as filename, MIME type, size, provider message id, and provider attachment id
• attachment bytes are not downloaded during ordinary sync
• text extraction runs only when Ask/search needs attachment text or the user explicitly opens/extracts an attachment result
• extracted text is cached locally for later search
• supported extraction targets include PDF, DOCX, HTML, and plain text-like files where provider fetch support exists
• failures and unsupported types are recorded without breaking inbox listing

Ask Inbox uses local retrieval first, then adds semantic retrieval, provider-native search, and attachment-aware evidence when available. When an LLM provider is configured, it can add a concise answer over the ranked evidence. Without an LLM, Ask still returns ranked local results and source snippets.

Search results are normalized with source labels such as local_fts, local_vector, provider_search, and attachment_text. This lets Ask Inbox recover emails where the wording differs from the user prompt, for example a credit-card statement email that says Son Odeme Tarihi instead of "payment due date".

Voice Input

The inbox has two voice entry points:

• the microphone next to Search threads... fills the search box and reloads matching threads
• Speak reply in the reply area appends dictated text into the reply composer without sending

Desktop behavior:

• Electron does not rely on Chromium's Web Speech service because it can request microphone permission but still fail when the speech-recognition backend is unavailable
• desktop transcription uses the configured OpenAI or Azure speech-to-text provider in Settings > Voice
• if provider transcription is not configured, the mic button shows a configuration message instead of a generic "service unavailable" error

Provider Support

Replacement Client Foundation

Inbox Agent now includes the foundation for a replacement-grade email client:

• MailboxProviderClient capability mapping for Gmail API, Microsoft Graph, IMAP/SMTP, and AgentMail
• schema for folders, labels, identities, signatures, provider drafts, compose drafts, outgoing messages, queued actions, sync cursors, client settings, attachment metadata, and action state
• shared types and IPC/preload APIs for client state, compose draft creation/update/send/schedule/discard, undo action, Today digest, sender cleanup digest, Ask, and attachment extraction
• list filters for Today bucket, domain category, folder, label, draft, scheduled, queued, attachment presence, and attachment query
• digest metadata for sync health, queued action counts, failed action counts, compose drafts, and scheduled sends
• action audit/event emission for applied actions and downstream automation hooks

Current replacement-client gap:

• native new-mail compose, provider-backed draft save/update, attachment upload, full outgoing queue draining, Microsoft Graph execution, folder/label navigation, and notification preferences still need the next implementation passes before Inbox Agent can fully replace every email-client workflow.

Gmail Forwarding Automations

Inbox Agent can create native Gmail forwarding automations from the selected thread with Auto-forward....

What the flow does:

• creates a mailbox automation with sender/domain filters, optional subject keywords, attachment extension filters, and a target recipient
• stores the selected Gmail providerThreadId so thread-created automations stay scoped to that Gmail conversation
• supports dry-run mode first so candidate messages can be labeled and audited before enabling real sends
• reconstructs and sends a new MIME email with matched attachments instead of relying on Google Apps Script forwarding
• tracks per-message dedupe and a persistent scan watermark so recurring runs survive app restarts and laptop sleep

Operational notes:

• Gmail modify scope is required because the automation creates labels, updates thread labels, fetches attachments, and sends mail
• candidate, rejected, and forwarded Gmail labels are status cues, not permanent search exclusions
• dry-run keeps the scan watermark unchanged so the same candidate set can be inspected repeatedly

Event Pipeline

Every meaningful mailbox action emits a normalized mailbox event. Events currently drive:

• Knowledge Graph enrichment for people, organizations, projects, and observations
• Heartbeat signals for stale threads, open loops, cleanup candidates, and mailbox health
• trigger evaluation for downstream actions
• playbook capture for repeated inbox patterns
• daily briefing summaries
• unified identity and relationship timeline updates across email and linked channels
• Mission Control handoff records so inbox-originated issues stay traceable

Privacy And Safety

• Mailbox bodies, summaries, excerpts, and attachment text stay in the local database.
• Attachment bytes are fetched on demand, not during ordinary sync.
• Scripts and unsafe active content in email HTML remain blocked.
• Remote images may load according to the product setting, but active content is not executed.
• Sensitive-content detection is surfaced as a warning and metadata cue, not a hard block.
• Sending, archiving, trashing, marking read/unread, scheduling, and forwarding remain gated by provider permissions.
• Automatic destructive or send actions require explicit future rules; agent suggestions do not silently execute bulk/destructive actions.

Typical Workflow

1. Open Inbox Agent and let cached mail appear immediately.
2. Use Classic mode for a familiar thread list or Today mode for the agent-first action lanes.
3. Filter by view, category, saved view, domain, account, or search.
4. Open a thread and review summary, message content, attachments, commitments, and the Agent Rail.
5. Use Reply, Reply all, or Forward for normal manual email.
6. Use Prep thread or Draft a reply with AI when you want agent help, then edit the generated draft before sending.
7. Use Mark done when you handled the email elsewhere and want it removed from Needs reply/Open commitments.
8. Use Ask Inbox for evidence-backed search across threads and attachment text, or type @inbox <question> in the main composer to open Inbox Agent directly.
9. Use Sender cleanup or bulk selection to clear noisy senders.
10. Hand off company-level issues to Mission Control when email becomes operational work.

Related Docs

• Features for the broader product feature index
• Ask Inbox Architecture for the retrieval, IPC, and UI progress model
• Composer Mentions for @ autocomplete, integration chips, and @Inbox routing
• Use Cases for copy-paste inbox workflow prompts
• Inbox Agent Product Plan for roadmap and implementation slices