@lssm-tech/lib.communication-spec
Builds start from the canonical root and grouped types, commands, queries, events, capabilities, validation, contracts, and fixtures entrypoints. All 71 existing manifest subpaths remain supported compatibility roots. The builder emits the local module closure once per target without publishing private helpers discovered in source. Export conditions, contract keys, versions, and wire schemas are unchanged; public additions update both manifest export maps deliberately.
Communication lifecycle projections use the canonical pure
@lssm-tech/lib.agent-protocol-spec/help definition for durable help requests. The type-only binding preserves projection shapes, validation, contract keys and runtime authority; no agent execution or provider dependency is introduced.
Identity resolution uses communication.account.list@2.0.0,
communication.contact.list@2.0.0, and
communication.identity.decide@1.0.0. Account outputs exclude credential references; identity merges remain human-reviewed and auditable.
Governed work uses canonical communication.governed_work.list@2.0.0,
communication.governed_work.create@2.0.0, and
communication.governed_work.transition@2.0.0. These operations cover identity review, drafts, actions, handoffs, escalations, triage, summaries, agents, consent, retention, and policy while keeping scope and transition authority on the server. The v1 operations remain exported only for deliberate migration.
Canonical CommunicationOS contracts for threads, messages, spaces, rooms, scoped principals, memberships, connections, reply drafts, handoffs, realtime state, operations, queries, events, capabilities, and validation helpers.
The additive Discord community-intelligence surface models multiple guilds per workspace with explicit staff and managed-community trust zones, guild-local specialties and roles, protected typed provider events, evidence-backed insights, restricted coaching scorecards, and Kaizen digests. Existing v1 normalized message ingestion remains unchanged.
Canonical capability namespace
COMMUNICATION_OS_CAPABILITY_KEYS is the single capability vocabulary for route discovery, role projections, contextual slots, and UI action gates. All capability identifiers use the communication-os.* namespace. The legacy
comms.* strings are no longer capability identifiers; similarly named
comms.thread.summarize, comms.reply.draft, and comms.handoff.suggest
values remain operation keys and are not authorization capabilities.
comms.thread.summarize and comms.reply.draft are at 1.1.0. This is additive: both accept an optional allowlisted Gateway model and may return
AI_MODEL_NOT_ALLOWED (summaries also AI_MODEL_OVERRIDE_DENIED).
./contracts/ai-model-catalog exposes COMMUNICATION_OS_AI_MODEL_CATALOG, the allowlist of Vercel AI Gateway models with EU inference providers. The list is pure data owned here, because this spec does not depend on ProviderSpec. A parity test in @lssm-tech/lib.communication-runtime keeps it identical to the shared @lssm-tech/lib.provider-spec/gateway-model-catalog that OPA briefings use, so both products allow exactly the same models.
./contracts/ai-model-settings.operations declares
communication.ai.model-settings.get|set (the set command is admin-only) and the communication.ai.model-setting.changed audit event.
The direct public entry point
./capabilities/communication-os.capability-ids exposes the canonical keys and the exact subset used by the 23-route CommunicationOS hub.
Private Support notes use the additive
communication.support.internal-note.create@1.0.0 command and
communication.support.internal-note.verify@1.0.0 query. Their public inputs never carry tenant, workspace, or actor authority; verification is redacted and never exposes note content.
The additive v2 ecosystem surface models strictly scoped personal and organization spaces, human/agent/system principals, hybrid connection placement, explicit encryption modes, cursor sync, messaging state, and revocable agent authority. Message v2.1 accepts optional public-safe attachment metadata backed by opaque, scope-authorized storage references; raw bytes and private storage locations are never part of the public message projection. Provider OAuth start accepts an optional provider key so Google and Microsoft mail can coexist under the email network without mutable process-global selection. Authenticated callback invalidations use the additive
communication.connection.sync.invalidated event; they request sync and never become user or agent instructions. Provider subscription create and renewal use a separate durable lifecycle:
requested is appended before Runtime Node dispatch, active requires an exact work-order receipt, definitive failed state obeys retryability, and
indeterminate retains custody without automatic retry.
communication.message.send@3.0.0 is the canonical JSON transport contract. It accepts only client intent plus replay keys; tenant, author, message identifier, revision, and timestamps are derived and returned by the authorized server.
communication.message.search@3.0.0 likewise derives tenant authority from the session while retaining explicit workspace and space selection.
communication.space.list@3.0.0, communication.room.list@3.0.0,
communication.account.list@3.0.0, and communication.contact.list@3.0.0
accept no client-selected scope. communication.room.create@3.0.0 accepts only the room name, kind, and replay key; tenant, workspace, space, principal, identifiers, revisions, and timestamps remain server-owned. CommunicationSpec remains canonical; Matrix and proprietary networks are adapters. All v1 contract keys remain exported unchanged.
Domain-command helpers classify agent-callable CommunicationOS actions such as reply drafting, reply sending, handoff creation, and escalation requests. These helpers are contract-only: they describe authority, autonomy, approval requirements, and semantic violations without provider adapters, persistence drivers, outbound sends, or runtime side effects.
Command-inbox contracts extend domain-command planning with non-executing inbox items, fail-closed status, AIP control refs, and CompanyOS bridge evidence. These contracts describe review/approval state only; they do not grant send or work-execution authority.
Agent omnichannel contracts
The additive V1 omnichannel surface keeps agent communication provider-neutral:
agent-communication binds agent applications, runs, tasks, help requests, and background results through opaque refs.agent-lifecycle-projection publishes immutable, non-authoritative run, task, help, approval, and terminal status into the canonical conversation. A help projection must bind the exact durable help request and checkpoint.canonical-agent-conversation binds one scoped conversation to its exact session, participants, channel identities, origin, revision, and digest.ingress-admission separates the durable authenticated receipt from the deterministic connection, identity, pairing, membership, mention, and consent decision. Unresolved identity or membership quarantines rather than becoming model input.agent-surface-control binds help, approval, steer, queue, pause, cancel, and branch requests to one conversation, run, human identity proof, authority decision, expiry, idempotency key, and durable result.channel-routing provides an open channel key plus well-known email, calendar, SMS, Slack, Teams, Discord, Telegram, WhatsApp, Matrix, in-app, push, webhook, web-chat, and internal-chat keys.channel-preferences records typed user choices with
authority: "preference_only"; each set has exactly one event, automation, feature, application, product, space, person, or stable platform-default resolution target plus explicit inherited parent-set refs. Resolution follows event/automation, feature/application, product, space/person, then platform default. A preference never authorizes delivery.delivery-intent, delivery-progress, and delivery-fallback carry content proof, opaque event/automation/feature/application/product classification, idempotency, receipts, reconciliation, policy, eligibility, and evidence refs with effectAuthority: "none". Route, preference, resolution, intent, progress, and fallback bindings retain revisions or digests; attempted fallback binds the exact prior progress ref and digest.
Provider acceptance remains distinct from delivered/read evidence. An ambiguous prior effect must be reconciled before an alternate route can be selected. The contracts contain no provider credentials, runtime effects, or persistence implementation.
The domain-command outbox schema carries optional reconciliation custody bindings. An indeterminate provider outcome records the exact Runtime Node work order digest and evidence refs before its lease can leave effectful execution.
Public Entry Points
. resolves through ./src/index.ts./types resolves through ./src/types/index.ts./types/domain-command resolves through ./src/types/domain-command.ts and includes command-inbox contracts./commands resolves through ./src/commands/index.ts./queries resolves through ./src/queries/index.ts./events resolves through ./src/events/index.ts./capabilities resolves through ./src/capabilities/index.ts./validation resolves through ./src/validation/index.ts./contracts/agent-communication resolves agent profiles and lifecycle links./contracts/agent-lifecycle-projection resolves evidence-bound agent status and help projections for canonical conversations./contracts/canonical-agent-conversation, ./contracts/ingress-admission, and ./contracts/agent-surface-control resolve canonical continuity, deterministic admission, and origin-neutral agent controls./contracts/channel-routing and ./contracts/channel-preferences resolve open route keys and typed non-authoritative preferences./contracts/preference-resolution resolves typed preference targets and the most-specific-to-platform-default hierarchy; it performs no runtime resolution./contracts/delivery-intent, ./contracts/delivery-progress, and
./contracts/delivery-fallback resolve the fail-closed delivery artifact set./contracts/delivery-eligibility resolves evidence-only route eligibility across consent, policy, grants, quiet hours, limits, provider health, cost, and channel-specific constraints; it grants no delivery authority./fixtures/agent-omnichannel resolves the deterministic no-network fixture./contracts/ecosystem-messaging.models resolves v2 spaces, rooms, principals, connections, messages, and authority grants./contracts/ecosystem-workspace.operations and ./contracts/ecosystem-message.operations resolve additive v2 operationscommunication.space.list@3.0.0 and communication.room.list@3.0.0 expose server-selected navigation without accepting browser scope authority; their v2 predecessors remain exported for compatibility during migration./contracts/ecosystem-messaging.events resolves additive v2 journal/realtime events- The root and
./contracts exports include browser-safe v2 request, result, error, cursor, journal, realtime, and projection DTOs. Public extension payloads use CommunicationJsonObjectDto rather than unknown records.
./contracts/ecosystem-webhook.operations resolves authenticated, replay-safe provider webhook ingresscommunication.oauth.start@3.0.0 and communication.oauth.complete@3.0.0
derive an allowlisted callback return origin from the authenticated host issuer, so embedded CompanyOS and standalone CommunicationOS return to their own shell. define scope-bound provider onboarding with PKCE, one-time opaque state, safe return paths, and credential-reference-only completion./capabilities/ecosystem-messaging.capabilities resolves v2 messaging capability constants./capabilities/communication-os.capability-ids resolves the canonical route and action capability identifiers
TenantBoundCommunicationIngestionSchema is an additive R001 contract exposed through ./contracts/ingestion. It binds the existing normalized ingestion record to the canonical F002 CompanyOS tenant-governance envelope and validates subject, consent, idempotency, and evidence/replay alignment without introducing provider or webhook behavior.
Persistence wave
CommunicationOS persistence stays contract-first. communicationOsSchemaContribution, communicationOsPersistencePlans, and createCommunicationOsMutationDescriptor expose portable schema and governed database.mutation.execute@2.0.0 envelopes for managed/BYOK providers. The domain command reference remains the write authority; provider packages execute SQL/Drizzle outside this spec package. Local/PgLite support is compatibility binding metadata, not an ownership mode.
Limite
This package owns canonical communication contracts. Runtime behavior, examples, fixtures, proof/replay, and product composition live in separate packages. Deprecated module shims may re-export this surface for compatibility only.
Approval-bound sequences
CommunicationSequenceIntentSchema is the additive, provider-neutral contract for scheduled outbound intent. It binds the exact recipient, content proof, channel, side effect, schedule/expiry, policy and consent refs, kill switch, ActionPacket, approval request, and approval fingerprint. Runtime schedulers must revalidate those bindings and controls before every initial claim and retry.
CommunicationSequenceApprovalTargetSchema is the canonical versioned human approval payload. Its deterministic fingerprint binds the sequence/version, tenant, recipient set, content proof, channel/effect, schedule and policy versions, and expiry. The approval request and ActionPacket evidence must carry that same fingerprint.
Matrix channel
ChannelTypeEnum includes matrix for deployments that ingest Matrix room events or send governed replies to Matrix rooms. Matrix bridge metadata is owned by integration contracts; this package only owns the canonical channel value.
Published browser conditions select the emitted browser artifacts alongside existing Node/Bun/type targets. Export keys and source behavior are preserved; this packaging metadata does not activate providers or grant execution authority.
