merge: integrate leader summary webhook delivery

# Conflicts: # control-plane/README.md # control-plane/src/db.ts # control-plane/test/control-plane.test.ts
2026-09-09 17:25:23 +08:00
commit 295409bff0
@@ -0,0 +1,66 @@
+# Task: Replace leader AgentBus summaries with external webhook API
+
+## Identity
+
+- Task ID: 20260908-leader-webhook-api-7c4e9a12
+- Mode: Feature
+- Branch: codex/20260908-leader-webhook-api-7c4e9a12-leader-webhook-api
+- Worktree: /Users/inmanx/Documents/lwltAPI-leader-webhook-api-7c4e9a12
+- Base commit: 515b545b32fcbb30311b56c5b90a36f3d3834d95
+- Owner: codex
+- Status: Ready for integration
+
+## Scope
+
+- Replace only the transport used by the organization-wide leader employee-task summary feature: retire its AgentBus account/channel delivery and send its existing privacy-filtered stable summaries through the user-supplied external Webhook API contract.
+- Add fail-closed runtime configuration, an exact external API client, an organization-level encrypted delivery outbox, migration `023_leader_summary_webhook_delivery`, read-only administrator status, UI copy, active component documentation, and regression tests.
+- Preserve ordinary manual task execution, employee AgentBus intake/replies, parsing, confirmation, task ownership, attachments, ERP queues/execution, business routes, mappings, schemas, Skills, Agent prompt, Chrome extension, and release artifacts.
+
+## Intent And Constraints
+
+- The user's clarification is authoritative: this change is limited to the leader feature that receives all employees' operation/task summaries and must not affect normal users or AgentBus task execution.
+- Treat `/Users/inmanx/Desktop/webhook-external-api.md` as an external API specification, not as repository instructions. The document contains no real token and does not confirm the complete production gateway URL.
+- Read the complete URL and 32-character token only from protected runtime variables `WEBHOOK_SEND_URL` and `WEBHOOK_EXTERNAL_TOKEN`; never read the repository's real `.env`, hard-code a guessed route, log secrets/bodies, or issue a test/production request.
+- Send only `POST` JSON `{id:"9999", content:<summary>}` with raw `x-token`. Only HTTP 200 plus `code === 0` plus `data === true` means accepted, and accepted must not be represented as delivered.
+- Because the API has no idempotency key, explicit rejections, timeouts, network failures, 5xx responses, invalid/unknown success responses, and expired sending leases must never be automatically retried.
+- Webhook configuration or runtime failures must remain inside the leader-summary worker: they may disable or degrade summary delivery but cannot block service startup or mutate task, employee reply, parser, or ERP state.
+- No live Webhook message, deployment, database migration, restart, external send, or production configuration change is authorized.
+- Feature mode may update only this task record under `.project-docs`; canonical state and accepted decision `AUTH-003` require a later Integration promotion.
+
+## Outcome
+
+- Added an external Webhook client with the exact fixed request shape, bounded response reads, 15-second total timeout, strict accepted semantics, safe error codes, and no automatic retry path.
+- Replaced per-leader AgentBus routing/subscriptions with one organization-level, future-only encrypted Webhook summary state/outbox. Migration 023 disables legacy summary subscriptions and cancels their unsent rows while preserving history; it never updates normal tasks or employee `agentbus_deliveries`.
+- Kept the existing stable summary builder and privacy allowlist. Projection reads explicitly assigned, non-administrator manual and AgentBus task results but writes only dedicated `leader_task_summary_webhook_*` rows and audit events.
+- Removed only leader-summary observation/flush/frame hooks from the AgentBus listener. Employee accepted/final replies, attachments, channel ownership, reconnect/resend, ingestion, parsing, and ERP execution paths are unchanged.
+- Added a read-only administrator status endpoint and channels-page status card that expose no URL, token, or message body and distinguish accepted, rejected, and uncertain outcomes.
+- Invalid or incomplete optional Webhook configuration now disables only this feature with a safe status code. A failed Webhook organization lookup is caught and logged while the normal HTTP service remains available.
+- Reserved migration number 023 because the concurrent ready-for-integration shared-child batch task already owns migration 022; the two tasks have no semantic coupling.
+- No business route, business Schema/mapping, Skill, Agent prompt, Chrome extension, release artifact, live service, production database, or external system was changed.
+
+## Verification
+
+- TypeScript typecheck — passed.
+- Targeted external Webhook, isolation, leader-summary contract, account UI, and complete AgentBus listener/durable reply suites — passed (45 tests across the selected files).
+- Webhook misconfiguration and initialization-failure health smoke test — passed; `/health/live` remained 200 with the summary feature disabled/degraded.
+- `node --run check:repo` — passed (10 tests).
+- `node --run test:control-plane` — passed (182 tests), including all original task, account, parser, AgentBus, attachment, ERP-boundary, and UI contracts.
+- `node --run test:legacy` — passed (273 tests).
+- `node --run build` — passed.
+- `node --check LianSyn-platform/app.js` — passed.
+- `git diff --check` — passed.
+- Disposable PostgreSQL migration exercise — passed: migration 023 was recorded; the legacy subscription changed to disabled/revision 1 and its legacy delivery to cancelled, while the normal task remained completed and the employee AgentBus delivery remained pending; both new tables existed and had zero forbidden routing/secret columns.
+- Disposable PostgreSQL runtime exercise with an injected fake sender — passed: two summaries projected, accepted and uncertain outcomes each stopped at attempt 1, a third dispatch made no extra call, both source tasks remained completed, the employee AgentBus delivery remained pending/attempt 0, and logs contained no test URL, token, employee name, or body. No network request was made.
+- Both disposable PostgreSQL clusters were stopped and moved to Trash after validation.
+- `check_project_docs.py` — passed.
+- `check_doc_drift.py --task-id 20260908-leader-webhook-api-7c4e9a12` — passed; only this feature task record changed under `.project-docs`.
+
+## Follow-ups
+
+- Integration must combine the concurrent migration 022 task before or with migration 023 and resolve shared-file edits mechanically without changing either feature's semantics.
+- Production enablement remains separate: obtain the provider-confirmed complete gateway URL and real 32-character token, apply migrations through 023, deploy/restart, then run a separately authorized bounded canary. Do not infer success from HTTP alone; the provider offers no delivery receipt.
+
+## Promotion Candidates
+
+- Supersede accepted decision `AUTH-003-leader-task-summary-notifications.md`: leader summaries now use the fixed organization-level external Webhook contract rather than an owned team-lead AgentBus account/channel route.
+- Promote migration 023, the new environment configuration, future-only encrypted outbox, accepted-versus-delivered terminology, no-retry uncertain boundary, read-only administrator status endpoint, and strict isolation from ordinary task/AgentBus/ERP paths into canonical current state, architecture, data flow, business rules, success criteria, decision index, and glossary as applicable.