Digital Worker Phase 3 — Progress & Risk Digest Design

Goals & scope

Phase 3 is deliberately the lowest-risk, highest-leverage next step. It composes primitives already shipped in Phases 1 and 2 — chat-event ingest, task extraction, the system_cron actor precedent from Fieldforce briefings, the notifications module, AccessGate billing, the watermark recovery pattern, and the feature-flagged panel nav — and introduces no new way for the worker to act on the outside world.

Success criteria

• A manager who owns a team channel receives a digest on a configurable cadence (daily default, weekly option) without having to remember to look.
• Four sections: Progress summary, Blockers & risks, Commitment health (overdue/stale + unclear ownership), and Suggested follow-ups.
• Risk facts are computed from already-extracted structured data, so they are precise and source-linked; narrative comes from a single bounded LLM pass.
• Managers can regenerate on demand from the panel; empty periods produce no notification.
• Every digest is persisted with provenance and readable as history, behind the two-tier digital_worker flag, respecting existing privacy and retention boundaries.

Out of scope

Approach selected — mirror the Fieldforce briefings engine

Architecture

flowchart TD
    cron["Cron tick · system_cron · single-owner lease"] --> due{"Binding due? (cadence / hour / weekday)"}
    due -->|yes| gen["GenerateChannelDigest(binding, trigger)"]
    ondemand["POST .../channel-bindings/:id/digest"] --> gen
    gen --> struct["Structured pass: commitment health (no AI)"]
    gen --> llm["LLM pass (gated): progress / blockers / follow-ups"]
    struct --> val["Validate: strict schema + verified-owner"]
    llm --> val
    val --> store["Persist dw_digests (+ dw_ai_runs)"]
    store --> notify["Notify digest_ready · generated only"]
    

The generation use case lives in the Go digitalworker module alongside the Phase 1/2 use cases. The AccessGate actor is the synthetic dw_worker:<role_agent_id> for both triggers, keeping the triggering human out of the org AI-spend ledger.

Data model

All tables are dw_-prefixed and expressed as raw SQL in migrator.go (CHECK constraints + JSONB), per the schema convention in CONTEXT.md.

dw_digests

One row per generated digest — the source of truth for both the rendered content and the per-binding watermark.

Index: (org_id, channel_binding_id, created_at DESC) for the panel history list.

dw_channel_bindings (ALTER)

Cadence config lives as new columns on the existing binding row, matching where proactive-mode, capabilities, and approver rules already live (no extra join).

Generation pipeline (hybrid)

One use case, GenerateChannelDigest(binding, trigger, actor), runs identically for scheduled and on-demand triggers.

1. Window

   Read [period_start, period_end): the dw_chat_events in range plus structured rows (dw_inbox_items and their states, Fieldforce task states for promoted items). The window is capped (max messages / chars, same idea as the Phase-1 triage window) so token cost is bounded.

2. Structured pass (no AI)

   Build Commitment health deterministically: overdue/stale (commitment_type set, due_date < now(), not promoted/dismissed/completed) and unclear ownership (suggested_owner_user_id IS NULL). Precise and source-linked — no hallucination risk.

3. LLM pass (one gated call)

   Send the bounded chat window plus the already-computed structured facts to the remote model via AccessGate digital_worker:progress_digest (DB-managed, versioned prompt template). It returns strict JSON for the three narrative sections.

4. Validation (Phase-1 rules reused)

   Drop items whose source_message_ids fall outside the window; any owner reference must resolve to a verified dw_external_identities row or it is nulled. Schema failure → drop bad fields, retry once, then status='failed'.

5. Empty & cost guards

   No chat and no structured signals → status='empty', skip the LLM call and the notification. Overdue commitments but no chat → structured-only digest (narrative empty). Scheduled cadence bounds volume, so no local-triage pre-filter is needed.

The narrative LLM call returns strict JSON:

{
  "progress":   [ { "text": "...", "source_message_ids": ["..."] } ],
  "blockers":   [ { "text": "...", "severity": "low|medium|high", "source_message_ids": ["..."] } ],
  "follow_ups": [ { "text": "...", "refers_to": "commitment|blocker|none", "ref_id": "...", "source_message_ids": ["..."] } ]
}

Passing the structured facts into the prompt lets follow-ups reference real overdue commitments without the LLM recomputing them.

Scheduling, on-demand trigger & delivery

Scheduled path (cron)

A periodic loop under the system_cron actor, same precedent as Fieldforce briefings. Each tick, for every binding with digest_enabled = true, it checks whether the binding is due (org-local digest_send_hour reached, weekly matches digest_weekday) and that no successful/empty digest already exists for the current period (idempotent).

• Multi-replica safety: reuse the existing lease / advisory-lock pattern (cf. the Discord gateway owner lease) so exactly one replica generates per binding per period.
• Kill-switch: the whole feature sits behind the two-tier digital_worker feature flag (ADR-0016); flag off ⇒ no digests.

On-demand path

POST .../channel-bindings/:id/digest calls the same use case with trigger='on_demand', actor = the requesting user. Authorization = that binding's approver rules ∩ role scope (or owner/admin) — the same gate as viewing it. A light minimum-interval guard prevents AI-spend abuse on top of AccessGate caps.

Delivery / recipients

A new notification event digital_worker:digest_ready flows through the existing notifications module, deep-linking to the binding's digest page. Recipients = the binding's approver rules ∩ role scope — the exact targeting Phase 1 already uses for digital_worker:inbox_pending. One notification per generated digest; empty and failed are not notified to managers (failed surfaces in worker health / audit for admins).

Panel experience

Two surfaces, splitting reading (managers) from configuring (admins), following the Phase-2 pattern. The manager reader lives at /app/digital-workers/digests (the notification deep-link target); the admin config block lives on the channel-binding editor under /app/settings/digital-workers.

Components, nav & i18n

Components

New under src/features/digital-workers/digests/, reusing existing panel primitives (cards, chips/badges, section list, markdown renderer, filter bar) per the panel-ui-style guide.

Query hooks

digests-by-binding list, digest detail, generate-on-demand mutation, binding digest-config update (TanStack Query).

Nav

A "Digests" link in the sidebar (apps/panel/src/app.tsx) behind the digital_worker flag; field-team hidden.

i18n

New Paraglide digitalWorkerDigest.* namespace (en/zh/ms) for chrome. LLM-authored section text is server-supplied and not re-translated client-side.

API

GET  /api/organizations/:org_id/digital-workers/channel-bindings/:id/digests   # history list
GET  /api/organizations/:org_id/digital-workers/digests/:digest_id             # detail
POST /api/organizations/:org_id/digital-workers/channel-bindings/:id/digest    # on-demand generate
# digest_enabled / cadence / send_hour / weekday folded into the existing binding-update endpoint

Internal use-case API: GenerateChannelDigest(binding, trigger, actor) -> Digest.

Safety & privacy

Error handling

Testing strategy

Rollout plan

1. Schema + structured-only

   Add dw_digests and binding columns; generate Commitment health with no LLM call; readable in the panel.

2. LLM narrative pass

   Add the gated digital_worker:progress_digest call for Progress, Blockers, and Follow-ups.

3. Scheduling

   The system_cron loop with the single-owner lease and org-local due-calculation.

4. Delivery

   The digital_worker:digest_ready notification fan-out reusing inbox-notification targeting.

5. On-demand + config UI

   The panel config block and "Generate now" endpoint.

This order yields a useful, fully-auditable digest before any scheduling or AI narrative is switched on, and keeps every step reversible.