Digital Worker Team Chat Observer Design

Summary

• Product Digital Worker — Phase 1 chat observer
• Providers (MVP) WhatsApp, Telegram, Discord — direct integration
• Behaviors Mention-response + proactive task drafts
• AI posture Local triage → gated remote; AccessGate-governed
• Approval Safe actions auto; consequential actions gated
• Promotion target Fieldforce task (only task model today)

The first Digital Worker is a Team Chat Observer that lives inside approved team chats. It answers @-mentions directly in-channel and quietly drafts follow-up tasks from real commitments into a review inbox — all behind verified identity, per-channel capability policy, and an AccessGate-governed two-tier LLM. Gremlin integrates directly with the WhatsApp, Telegram, and Discord bot APIs (no middleware), and humans approve only the actions that actually change the system.

Scope & Goals

The MVP proves exactly two behaviors and nothing more:

Success criteria

• An org admin can bind a worker to approved channels and allowed users.
• A mapped member can mention the worker and receive useful, policy-compliant help.
• In proactive channels, the worker drafts follow-up tasks into a review inbox.
• Managers/supervisors can review, edit, approve, dismiss, or promote drafts into Fieldforce tasks.
• Every event, policy decision, AI generation, approval, dismissal, and promotion is auditable.

Key decisions

Four load-bearing decisions each became an ADR. They are the things a future reader would otherwise read as a bug.

Approach considered

Architecture

flowchart TB
    wa["WhatsApp · webhook + Graph send"]
    tg["Telegram · webhook + Bot API"]
    dc["Discord · Gateway WS (single-owner lease)"]
    core["Go Digital Worker Core · normalize, bind, identity, policy"]
    triage["Local triage (Ollama, unbilled)"]
    gate{"AccessGate"}
    llm["Remote: extraction / mention reply"]
    inbox["Worker Inbox (drafts)"]
    ff["Fieldforce task"]
    send["ChatSender → channel"]
    wa --> core
    tg --> core
    dc --> core
    core -->|"reply-on-mention (safe)"| send
    core -->|"proactive"| triage
    triage -->|"positive hit"| gate
    gate -->|"allowed"| llm
    gate -->|"denied / 402"| hold["No draft · watermark held · retry"]
    llm --> inbox
    inbox -->|"approve / promote"| ff
    

Heterogeneous ingest — the key consequence of going direct

The three providers do not share one ingest model, and that decides multi-replica safety.

The Go core owns organization/user identity, external chat identity mapping, worker bindings, channel allowlists, capability policies, the inbox and approval states, audit logs, AccessGate calls and DB-managed prompts, inbound ingest and outbound send (ChatSender), and task promotion into Fieldforce.

Security & permissions

Chat platforms are untrusted. Display names never grant authority — only a verified mapping between an external chat identity and a Gremlin user does.

Identity uniqueness

UNIQUE (organization_id, provider, external_user_id) — one chat account resolves to one Gremlin user per org; the same account may map independently in another org.

Resolution

Keys on (organization_id, provider, external_user_id) and requires status = 'verified'; any miss → default-deny unknown_user.

Verification (MVP)

Admin assertion in the panel — platform user IDs are stable; a self-service DM-code challenge is deferred.

Capability policy

Per worker/channel: observe, reply-on-mention, proactive-draft, create-inbox-item, promote-task, assign-task, schedule-meeting.

Role-based approval

Authority comes from Gremlin org/team roles, not chat roles.

Two-tier action model

Default-deny: if identity mapping, channel binding, or policy is missing, the worker does nothing except record a denied event for observability.

Proactive extraction & the watermark

flowchart LR
    msg["New message"] --> ingest["Cheap ingest → dw_chat_events"]
    ingest --> triage{"Local triage: real commitment?"}
    triage -->|"no"| skip["Skip · no spend"]
    triage -->|"yes"| gate{"AccessGate"}
    gate -->|"denied / 402 / 502"| hold["No draft · watermark held · retry + backfill"]
    gate -->|"allowed"| extract["Remote extraction (conversation window)"]
    extract --> draft["Inbox draft · advance watermark"]
    

Processing flow

1. Normalize the event; resolve channel binding; resolve external identity; load capability policy.
2. Mention-response path (safe, ungated, per-event)

   If mentioned and reply-on-mention is allowed, call the remote model via AccessGate (digital_worker:mention_response), validate, and post the answer directly back to chat. Record to dw_chat_events + dw_ai_runs + an internal_only inbox row. A consequential ask also creates a gated draft.

3. Proactive-draft path (consequential, gated, two-tier)

   Local triage (unbilled) over a rolling window decides if a commitment is present; only a positive hit calls the remote extractor (digital_worker:chat_task_extract) with the conversation window, coalescing rapid hits into one draft.

4. Notify approvers via the in-app notifications module (digital_worker:inbox_pending, debounced digest, approver-scoped).
5. Approver edits, approves, dismisses, or promotes a gated draft to a Fieldforce task.
6. Audit every step across dw_chat_events, dw_ai_runs, and the shared audit_log.

Watermark + coalescing

Two distinct boundaries: triage reads a context window, but only messages after the watermark can become drafts.

M1 09:00 Alice: "the staging deploy is broken again"
M2 09:01 Bob:   "can you handle the deploy tonight?"
M3 09:01 Alice: "yeah, I'll do it after the client call"
M4 09:02 Bob:   "thanks"
M5 09:05 Carol: "lol who's getting lunch"

Message edits & deletes

Edits/deletes arrive as distinct events (eventType: "edit" | "delete", editOfMessageId) referencing the original message. The blind spot: an edit below the watermark won't re-extract on its own.

• Pending draft → always mark needs_review (free); local triage judges materiality; only a material edit (commitment/owner/due-date) spends a remote re-extraction. Typos get the flag only.
• Promoted draft → never silently mutate the Fieldforce task; flag for the manager.
• If the transport doesn't deliver edits, drafts reflect extraction-time state (known per-transport limit).

AI output schemas

Both gated calls return strict JSON. On schema failure: drop invalid fields, retry once, then store a failure audit.

digital_worker:chat_task_extract — one item per coalesced commitment:

{
  "title": "<short imperative task title>",
  "summary_md": "<one-paragraph manager-facing context>",
  "commitment_type": "commitment | request | blocker | handoff | due_date",
  "suggested_owner_user_id": "<Gremlin user_id of a VERIFIED mapped identity, or null>",
  "due_date": "<ISO-8601 date, or null if no explicit due-date language>",
  "recommended_destination": "internal_only | fieldforce_task",
  "source_message_ids": ["<externalMessageId>", "..."],
  "confidence": 0.0
}

digital_worker:mention_response:

{
  "reply_text": "<message to post in-channel, org locale>",
  "action_requested": "none | create_task",
  "extracted_task": { "...": "same shape as a chat_task_extract item, or null" }
}

Data model

Error handling

Privacy boundaries

• No proactive observation unless a channel is explicitly configured.
• Full raw payloads live in short-retention object storage behind rawPayloadRef (never inline in Postgres, never rendered in normal UI — platform-admin debugging only).
• Per-org retention config via org_module_configs (digital_worker.raw_retention_days, digital_worker.event_retention_days); each org decides its window, default ~14–30 days. No redact-at-ingest — exposure is controlled by access-control + retention. A hard-delete hook fires on unbind / erasure request.
• No private chats / DMs for proactive analysis unless explicitly enabled later.
• MVP avoids employee-performance scoring; it extracts work commitments, not personal evaluation.
• The admin panel makes active worker/channel bindings visible so teams know where the worker is present.

Open questions — all resolved

Transport availability

No middleware; transport is fixed per provider (WhatsApp/Telegram webhook, Discord Gateway). Ingest is heterogeneous.

Default promotion target

Fieldforce only — no generic Gremlin task model exists.

Raw payload storage

Short-retention object storage behind a reference; per-org retention config; no ingest redaction.

Approver notification channel

In-app notifications module (debounced digest); messenger-DM delivery deferred (WhatsApp template/opt-in constraints).

Decisions & ADRs

New ADRs introduced by this design:

ADR-0028

Two-tier LLM — local triage as an unbilled pre-gate filter.

ADR-0029

Worker acts on external chat without per-action approval (safe-executable vs consequential).

ADR-0030

Extraction watermark — advance-on-success, divergent outage recovery.

ADR-0031

Direct messenger integration (no middleware); Discord Gateway single-owner lease.

Builds on existing decisions: ADR-0007 (two audit systems), ADR-0013 / ADR-0014 / ADR-0015 (Fieldforce task model), ADR-0016 (two-tier feature flags), ADR-0023 (lease pattern).