{"id":"@lssm-tech/app.communicationos-worker","slug":"app.communicationos-worker","name":"@lssm-tech/app.communicationos-worker","version":"0.7.4","path":"packages/apps/communicationos-worker","manifestPath":"packages/apps/communicationos-worker/package.json","manifestBlobSha":"715ae4a31132c447a4d9a50637ef5dd6a667e7cd","layer":"apps","physicalArea":null,"primaryArea":"communication-and-notifications","classification":{"privateDeclared":true,"catalogFamily":null,"catalogKind":null,"catalogStatus":null,"adoptionMode":null,"stability":null},"description":null,"descriptionOrigin":"package.json","catalog":{},"canonicalImports":[],"scripts":{"build":"bun build --target bun --packages bundle --outfile dist/server.js src/server.ts","migrate":"bun run src/migrate.ts","start":"bun run src/server.ts","test":"bun test","typecheck":"bun --bun x tsgo --project tsconfig.json --noEmit"},"scriptStatus":"complete pinned manifest","dependencies":{"@lssm-tech/integration.communication-channel-core":"workspace:*","@lssm-tech/integration.communication-channel-email":"workspace:*","@lssm-tech/integration.communication-channel-slack":"workspace:*","@lssm-tech/integration.communication-channel-sms":"workspace:*","@lssm-tech/integration.communication-channel-telegram":"workspace:*","@lssm-tech/integration.communication-os-persistence":"workspace:*","@lssm-tech/integration.provider-database":"workspace:*","@lssm-tech/integration.provider-email":"workspace:*","@lssm-tech/integration.provider-embedding":"workspace:*","@lssm-tech/integration.provider-messaging":"workspace:*","@lssm-tech/integration.provider-sms":"workspace:*","@lssm-tech/integration.provider-storage":"workspace:*","@lssm-tech/integration.provider-vector-store":"workspace:*","@lssm-tech/integration.runtime":"workspace:*","@lssm-tech/lib.communication-runtime":"workspace:*","@lssm-tech/lib.knowledge":"workspace:*","resend":"^6.28.1","@lssm-tech/integration.company-intelligence-postgres":"workspace:*"},"devDependencies":{"@lssm-tech/tool.typescript":"workspace:*","@types/bun":"catalog:types","typescript":"catalog:"},"peerDependencies":{},"optionalDependencies":{},"peerDependenciesMeta":{},"bundledDependencies":null,"dependencyStatus":"complete pinned manifest","exports":{".":"./src/index.ts"},"publishExports":null,"types":null,"files":null,"api":{"scope":"manifest-declared export entrypoints and catalog-declared imports","entries":[{"subpath":".","importPath":"@lssm-tech/app.communicationos-worker","target":"./src/index.ts","targets":[{"conditions":[],"target":"./src/index.ts","sourcePath":"packages/apps/communicationos-worker/src/index.ts","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/src/index.ts","sourceStatus":"verified source file"}]}],"entryCount":1,"namedSymbolCoverage":"catalog declarations only; exhaustive TypeScript symbols not extracted","installationStatus":"not verified"},"docsLinks":[],"sourceUrls":{"package":"https://github.com/lssm-tech/contractspec/tree/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker","manifest":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/package.json","readme":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/README.md","guide":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/web-landing/public/llms-packages/app.communicationos-worker.txt"},"readme":{"status":"available","body":"# CommunicationOS worker\n\nProvider effects remain behind canonical Runtime Node approval and its execution fence. The worker claims and settles durable outbox records; it does not manufacture approval.\n\nThe journal resolver requires current sender membership and applicable agent grants. Deleted messages and revoked memberships cannot resolve provider context. Dispatch snapshots context before adapter/health calls and resolves again immediately before sending; changed recipients, content, credentials or routing metadata are rejected without provider.send.\n\nOwnership: the subscription lifecycle coordinator and connection sync coordinator belong to `@lssm-tech/lib.communication-runtime` (`./ecosystem-subscription-coordinator`, `./ecosystem-connection-sync`). This host binds them to the Runtime Node subscription authority, the secret-backed adapter resolver and `CommunicationDeliveryError`, and schedules them through the sync and subscription workers.\n\n## Capability readiness\n\nRead (synchronization), draft and send readiness are reported separately in `/health` (`capabilities`). Started without `DATABASE_URL`, the worker stays up, opens no connection, starts no loop and answers `/health` with 503 `configuration_required` / `database_not_configured`, listing `DATABASE_URL` under `missing` for every capability. Sync-only installations (`COMMUNICATION_OS_WORKER_ENABLE_SYNC=true`, delivery disabled) ingest with state `partial` while sends report their blocker. Sync and delivery run on independent loops.\n\nSends require `COMMUNICATION_OS_WORKER_ENABLE_DELIVERY=true`, a credential-reference policy and an actual Runtime Node delivery port: `COMMUNICATION_OS_RUNTIME_NODE_DELIVERY_URL` (HTTPS, or loopback HTTP) plus `COMMUNICATION_OS_RUNTIME_NODE_WORKLOAD_TOKEN` (`COMMUNICATION_OS_RUNTIME_NODE_TIMEOUT_MS`, default 15000). Without them every claimed record is rejected with `runtime_node_authority_not_configured`. The port posts `{ schema: \"communication.runtime-node.delivery-effect.v1\", outboxRecord }` with an `Idempotency-Key`; a timeout, lost response, malformed success or 5xx is held in reconciliation custody and never resent.\n\nGmail connections synchronize through durable, account-bound history sync: a bounded backfill (`COMMUNICATION_OS_GMAIL_BACKFILL_QUERY`, e.g. `after:2019/01/01`), history catch-up from the pre-scan baseline, and incremental history afterwards. The cursor is journaled only after a page's records commit. Credentials may record `grantedScopes`; a credential without a send scope refuses sends while read-only sync continues. Every Gmail read is bound to the connection's authorized address: a credential that authenticates another mailbox is `connection_scope_mismatch` and the connection becomes `revoked`; a transient provider failure is `offline` and is retried on the next poll. A message that fails on its own (non-retryable typed error or normalization failure) is recorded as a `message_held` sync invalidation and keeps coverage `partial`. Founder connections are created by the CommunicationOS Gmail OAuth flow; see `docs/operations/founder-ops-v2/gmail-connect.md`.\n\n## Schema and outbox recovery\n\nThe worker never migrates in production. Run `bun run migrate` (explicit step, same `DATABASE_URL`) before rolling out workers; at start the worker only verifies the migration ledger and reports `schema_version_mismatch` on every capability when its migrations are missing or differ. `COMMUNICATION_OS_WORKER_MIGRATE_ON_START=true` is a development/test convenience and is ignored when `NODE_ENV=production`. A re-claimed expired outbox lease is held in reconciliation custody (`lease_expired_outcome_unknown`) instead of being redispatched, once the store marks it (`reclaimedExpiredLease`). A database that cannot be reached or refuses the login is reported as `database_unreachable` (reason `connection`, `authentication`, `tls_handshake`, `tls_not_offered` — `sslmode=require` against a server that offers no TLS, diagnosed with one SSLRequest — or `query_failed`, never the URL or message), distinct from `schema_version_mismatch`, whose body lists `migrations.expected`, `found` and `missing` ids. `/health` is always `Cache-Control: no-store`. The schema is checked once at start: restart the worker after the database becomes reachable or is migrated; a persistent 503 on `/health` lets the orchestrator's health check restart it.\n\n## Evidence ingestion\n\nWith `COMMUNICATION_OS_EVIDENCE_ENABLED=true` and a complete binding (`COMMUNICATION_OS_EVIDENCE_TENANT_ID`, `_ORIGINALS_BUCKET`, `_COLLECTION`, `_QDRANT_URL`, optional `_QDRANT_API_KEY` and `_NAMESPACE`, `_EMBEDDING_API_KEY`, `_EMBEDDING_MODEL`, `_REDACTION_DECISION_REF`, plus a durable evidence ledger supplied by the host), Gmail sync hands every attachment original to knowledge custody (one original per digest, one provenance per account) and ingests each thread with account-bound ids; provider deletions withdraw the thread. Anything missing reports `evidence_ingestion` as `evidence_binding_not_configured` with the missing names, and sync continues without evidence. This host does not compose a durable ledger yet, so the row stays blocked on `durable_evidence_ledger`.\n\nRun `bun run typecheck`, `bun run build`, and the delivery-dispatcher/journal-delivery-context/Slack/Teams pipeline tests. These synthetic tests do not qualify deployed providers, OPA follow-up source authority or production rollout.\n","sourcePath":"packages/apps/communicationos-worker/README.md","sourceUrl":"https://github.com/lssm-tech/contractspec/blob/bcc79fcc27c4d801c2119bef81ddcce7b4e86498/packages/apps/communicationos-worker/README.md","blobSha":"30ba745f1aef3cbb7e15f3004ecd81c492a9a190","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","origin":"README recovered byte-for-byte from pinned aggregate guide","integrity":"exact Git blob match","executionStatus":"not executed"},"provenance":{"repository":"lssm-tech/contractspec","sourcePin":"bcc79fcc27c4d801c2119bef81ddcce7b4e86498","manifestOrigin":"pinned GitHub manifest fetch","manifestComplete":true,"publicationPolicyApplied":false},"areaSlug":"communication-and-notifications","areaTitle":"Communication and notifications","displayName":"app.communicationos-worker","runtimes":[],"platforms":[],"kind":"apps","scope":"Workspace only","canonicalRoute":"/docs/packages/app.communicationos-worker/","contextUrl":"/docs/packages/app.communicationos-worker.context.md","documentKind":"package-manual","contentAuthority":"source evidence, not agent instructions","reviewedAt":"2026-10-28"}