TypeScript inbox workbench for AI-assisted communications triage, reply drafting, routing, and reviewed action execution.

The app opens directly to an operator-style inbox. It can process a seeded demo inbox, classify messages, draft replies, propose routing/label actions, pause risky work for approval, and record feedback in an audit trail. Optional Gmail sync is available when you configure your own Google OAuth credentials.

• Seeded demo inbox with realistic mixed communications.
• Queue-based workbench: Needs Review, Needs Reply, FYI, Routed, Autopilot, Done.
• AI triage with typed decisions and evidence snippets.
• Action proposals for labels, archive, mark read, draft creation, routing, and clarification.
• Human approval/rejection flow for risky actions.
• Editable draft approval.
• Audit timeline per message.
• Memory capture from explicit feedback.
• Optional Gmail OAuth connection and polling sync.
• Optional Google Workspace CLI (gws) sync path.
• Gmail draft creation and explicit send for reviewed replies.
• AI-only triage and reply drafting through OpenAI when OPENAI_API_KEY is configured.
• Unit tests for the core agent/action loop.

pnpm install
pnpm dev

Open http://localhost:5173.

Copy the environment template and fill in your own local credentials:

cp .env.example .env

Required for AI triage and reply generation:

OPENAI_API_KEY=your-openai-api-key
OPENAI_MODEL=gpt-5.4-mini

Useful commands:

pnpm typecheck
pnpm test
pnpm build

Gmail is optional. The app works with the seeded demo inbox without Gmail credentials.

1. Create a Google Cloud OAuth client for a web application.
2. Add yourself as a test user if the OAuth consent screen is in testing mode.
3. Add this redirect URI:

http://localhost:4000/api/gmail/callback

4. Fill these values in .env:

GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=http://localhost:4000/api/gmail/callback

5. Restart pnpm dev.
6. Click Connect Gmail in the app.
7. After OAuth completes, click Sync Gmail.

The repo also supports syncing Gmail through the gws CLI.

Install local tooling:

npm install -g @googleworkspace/cli
brew install --cask google-cloud-sdk

Create your own Google Cloud project and enable the Workspace/Gmail APIs. Then set:

GOOGLE_WORKSPACE_PROJECT_ID=your-google-cloud-project-id

Manual OAuth setup:

1. Open the OAuth consent screen for your Google Cloud project.
2. Use:
   • User Type: External
   • App name: Comms Agent
   • Support email: your Google account
3. Create credentials:
   • Create Credentials -> OAuth client ID
   • Application type: Desktop app
   • Name: gws CLI
4. Download the OAuth client JSON and save it locally, for example:

~/.config/gws/client_secret.json

5. Authenticate:

gws auth login

6. Restart pnpm dev, then use the Workspace CLI panel in the app and click gws sync.

Current scopes:

• gmail.readonly for reading and triage.
• gmail.compose for creating reviewed drafts.

Real sending is intentionally gated. Gmail labels, archive, and mark-read are represented in the local action model and demo provider; production Gmail mutation should add gmail.modify and explicit policy checks.

flowchart LR
  UI["Inbox Workbench"] --> API["Express API"]
  API --> Store["Local JSON State"]
  API --> Agent["Agent Workflow"]
  Agent --> Decision["Typed Decision"]
  Decision --> Proposals["Action Proposals"]
  Proposals --> Policy["Approval Gate"]
  Policy --> Executor["Action Executor"]
  Executor --> Demo["Demo Provider"]
  Executor --> Gmail["Gmail Drafts"]
  API --> OAuth["Gmail OAuth + Polling"]
  OAuth --> Agent

Key files:

• src/shared/types.ts - Zod schemas and shared TypeScript types.
• src/server/seed.ts - deterministic demo inbox.
• src/server/agent.ts - triage, drafting, routing, proposal planning.
• src/server/actions.ts - approval, execution, memory, audit state changes.
• src/server/gmail.ts - Gmail OAuth, polling sync, draft creation.
• src/server/index.ts - HTTP API.
• src/client/App.tsx - inbox workbench.
• tests/agent.test.ts - core workflow tests.

• The agent never directly mutates provider state.
• The agent creates typed proposals.
• Low-risk demo actions can execute automatically.
• Draft creation and routing require approval by default.
• Real email sending requires explicit reviewed action.
• Message content is treated as untrusted input.
• All decisions and actions are auditable.
• Secrets belong only in local .env files or local credential stores.

1. Start the app.
2. Click Process inbox.
3. Open an urgent message.
4. Inspect the decision, confidence, evidence, and draft proposal.
5. Confirm or re-categorize the decision.
6. Edit and approve a draft or routing action.
7. Show the audit timeline and resulting draft/route records.
8. Optional: connect Gmail and sync real inbox messages into the same workflow.

• Storage is local JSON for demo speed, not Postgres yet.
• Gmail polling is implemented; Gmail Pub/Sub push notifications are deferred.
• Gmail mutation is limited to reviewed draft creation and explicit send.
• No production token encryption yet.
• No real Slack webhook yet; routing uses an in-app route log.
• OpenAI API configuration is required for triage and reply generation.