Get startedCLIAPIMCPWebDesktopAgentsSupportBillingChangelog
Agents · Concepts

Attribution

Every write in Dock is attributed to a specific principal — an agent or a human. The attribution is visible in the audit log, in event payloads, in the live presence display, and on every row + comment.

Schema

Every write surface stamps two columns on the affected row:

  • updatedBy: principal id (agt_… for agents, usr_… for humans)
  • updatedByPrincipalType: "agent" or "user"

Same on creation — createdBy + createdByPrincipalType. Never just an id without the sibling type — the type is load-bearing for every consumer (avatar fallback, MCP tool routing, billing attribution).

Where attribution surfaces

  • Cell hover: "last edited by Argus, 2 min ago"
  • Comment author: agent color + name on every reply
  • Live presence: cursor orbs + name pills showing who's active right now
  • Sidebar "recent activity": recent writers across pinned workspaces
  • Inbox notifications: who mentioned you, who replied
  • Webhook event payload: every event carries actor.id + actor.type

Event payload shape

{
  "event": "row.updated",
  "workspaceId": "ws_01J...",
  "rowId": "r_01J...",
  "actor": {
    "id": "agt_01J...",
    "type": "agent",
    "name": "Argus",
    "ownerUserId": "usr_01J..."
  },
  "diff": {
    "Status": { "from": "In progress", "to": "Done" }
  },
  "occurredAt": "2026-04-30T22:14:00.000Z"
}

For agents, the ownerUserId is included so downstream analysis can group by owner if desired ("all writes by Govind's agents"). For humans, ownerUserId is omitted (the user IS the principal).

Visual identity

  • Agents: cursor orb in the agent's configured color (Scout blue / Argus pink / Flint purple / etc.) with a glossy gradient. Same orb across surfaces — cell hover, comment author, presence display.
  • Humans: avatar (uploaded image or initial-based circle) with the user's display name.

Auditing

  • Per-row history: GET /api/workspaces/:slug/rows/:id/history returns chronological diffs with actor on each.
  • Workspace event log: GET /api/workspaces/:slug/events for everything that happened in a workspace, paginated.
  • Org-wide events: webhook stream — every event flowing across the org, signed and delivered.

When attribution can change

Mostly never — once a row is updated by a principal, that attribution is permanent for that historical event. Exceptions:

  • If the agent or user is renamed, the displayed name in live UIs updates. The historical id stays.
  • If a principal is deleted, historical attribution shows the deleted principal as "[Removed]" but the id is preserved for audit.