Workspace Service

Workspace holds the record of what people are working on: projects and who is on them, the conversations inside them, the notes and meetings that feed them, the files attached to them, customer presentations, and each person's inbox.

It replaces flow-context-service and follows the platform contract. It is the only service agent-desktop calls, and one of the two the MCP gateway fronts for a chat client such as Cursor or Claude.

No request here calls an AI model. Everything is a database read or write. That is what lets the knowledge layer be slow, expensive, or down without a project page noticing.

The context pack is the interesting endpoint

GET /v1/projects/{id}/pack is what an agent is handed before it answers a question. Half of it comes from this service's own database. The other half is knowledge worked out by intelligence. Workspace owns the URL either way, so agent-desktop calls one endpoint and never has to know a second service exists.

sequenceDiagram
  participant Agent as agent-desktop
  participant WS as workspace-api
  participant PG as Postgres
  participant INT as intelligence-api

  Agent->>WS: GET /v1/projects/{id}/pack
  WS->>PG: open items, open cases, decisions, outputs, conversations
  WS->>INT: GET /v1/projects/{id}/knowledge-sections
  Note over WS,INT: unreachable → knowledge.degraded = true
  WS-->>Agent: one pack, complete or degraded

The degraded flag matters more than it looks. "We know nothing about this project" and "we could not reach the knowledge layer" both come back as an empty list. Without the flag, a caller cannot tell them apart, and will eventually tell someone nothing is known when the truth is that nobody asked.

What it owns

• Projects, membership, items, cases, handoffs, unblock requests, decisions, saved outputs, data sources, join requests, and the activity feed. A case is a finding with one owner. What was identified, approved, posted, and collected are stored separately, and a projection is not reported as cash collected. A handoff is a package offered to one person, and acceptance is that person's receipt that they can take the next step. An unblock request is one short question; an answer does not close it until the person who asked confirms it is enough
• Conversations and their turns, agent sessions, and redactions. Turns can only be added, never edited
• Notes, meetings, Slack threads, Azure DevOps and GitHub pull-request descriptions, and uploaded Word or PDF files converted to markdown — attached to any number of projects, or to none (ADR 0028)
• A claim on a document held by documents — the claim, never the file itself. The claim names a project, or the uploader when there is no project
• The facts a platform admin has settled about the business, written as markdown or uploaded as a file. Everyone can read them; only a platform admin can write one (docs/decisions/0037-admin-curated-company-facts.md↗)
• Each person's notifications and which kinds they want
• A human-readable audit log of workspace events, readable by platform admins (docs/decisions/0043-workspace-audit-log.md↗)

What it does not own

Anything worked out from the raw material. Contradictions, duplicated effort, and who knows what all live in intelligence. They reach workspace either inside the context pack or as events that turn into inbox rows.

It also does not store files. The file domain never issues a SAS URLSAS URL: A Shared Access Signature: a blob URL carrying a signed, time-limited grant of specific permissions. The documents service signs one per request with the storage account key and never stores it, so an expired URL cannot be replayed from a command response. and never holds any bytes.

Canonical service README: services/workspace/README.md↗.