integration.communication-os-runtime

@lssm-tech/integration.communication-os-runtime

The single composition point that closes the CommunicationOS hexagon. One createCommunicationOsRuntime({...}) call wires all five CommunicationOS ports — persistence, channels, model/agent, auth, observability — plus the ChannelAdapterRegistry into one cohesive runtime handle (plan P2-S1, AC2.1).

This package also owns the governed approve → send → event + audit orchestrator (executeApprovedSend, P1-S4): only a human-approved approval (never the agent) can resolve a ChannelAdapter and dispatch an outbound send. The injected ApprovedSendReconciliationStore atomically claims the approval before dispatch, retains the provider acceptance receipt as sent_pending_ack, and resumes audit/event completion without sending again. A claim with no durable receipt becomes ambiguous and stays fail-closed until an operator supplies the correctly bound receipt through reconcileApprovedSendReceipt. This prevents another provider send after a post-send completion failure without assuming undocumented provider idempotency. The default store is process-local for compatibility and is shared by direct calls that use the same approval store; production hosts must inject a durable implementation to preserve the boundary across restarts.

createCommunicationAgentPlatformRuntimeV1 is the canonical conversation composition seam. It binds conversations, admits already-authenticated inbound receipts, publishes background lifecycle state, and accepts help, approval, steer, queue, pause, cancel, and branch controls. CommunicationOS never executes the agent control itself: an injected Agent Host/Connect authority does so once, and the durable result is replayed on every authorized surface.

claimSequenceAttempt adds a pure scheduling state machine for approval-bound sequence intents. Every claim and retry rechecks exact target/content/channel/ side-effect/fingerprint bindings plus consent, policy, kill switch, due time, expiry, and attempt limits. The compatibility-only prepareSequenceApprovedSend previews claimability but never returns an effect-capable orchestration input; it performs no provider, outbox, persistence, or event call. prepareVerifiedSequenceApprovedSend is the effect-authorizing preparation path: immediately before preparation it reloads the approved request, verifies the versioned approval-target fingerprint and tenant, checks the ActionPacket evidence reference, and hashes the outbound body. An approval for sequence A therefore cannot prepare sequence B. At dispatch, executeApprovedSend fails closed on partial sequence markers, enforces the approved notBefore/expiry window, and requires an injected server-owned SequenceDispatchGovernancePort to re-resolve consent, policy, and kill-switch state before adapter lookup.

Agent Host and Runtime Node

The ./agent-host export is the CommunicationOS-owned bridge into LSSM OS. It implements ProviderLifecyclePortV1, but it does not grant send authority: before every effect it loads the exact digest-bound approved delivery command, re-resolves the complete ApprovedSendContext, and invokes this package's existing approveAndSend runtime. Provider receipt replay prevents duplicate delivery. A timeout or uncertain completion first enters confirmed durable indeterminate custody; observe() then uses CommunicationOS reconciliation for the exact approval/command and never blindly redispatches the channel effect.

./agent-host-admission builds the matching Durable Queue V2 envelope for the existing SQL co-atomic operation/outbox admission. It derives the outbox ref from exact scope, operation, order, command, and approved-context digests rather than accepting a caller-chosen authority ref. Agent Host only claims that envelope and calls Runtime Node; it never calls a channel adapter directly. createCommunicationOsAuthorizedAdmissionPortV1 is the production producer seam: an injected authority issues the accepted operation and signed order, the runtime verifies their exact command/context/idempotency/profile bindings, and an injected queue committer admits the operation plus Queue V2 envelope. The port owns no signing key and rejects denial, substitution, or non-durable queue outcomes before a product may report a queued delivery.

createCommunicationOsAuthorityIssuerV1 is the server-side issue() implementation of that seam. It takes nothing from the request on trust: an operator CommunicationOsAuthorityDeploymentV1 (strictly parsed by parseCommunicationOsAuthorityDeploymentV1) names the Runtime Node, provider binding, capability, queue topology and capability profile; an injected CommunicationOsApprovalBindingPortV1 proves, server-side, a current human approval of exactly the requested scope, thread, draft, channel, content digest and idempotency key; and a trusted clock bounds the order to the deployment TTL (30 to 900 s). The issued standard Runtime V3 order derives its ids from scope and idempotency key, commits its authorization digest to the approval evidence, names that evidence in signatureRef, and is checked against the queue admission it must produce. Malformed requests, foreign environments, missing or unavailable approval, malformed evidence and an untrusted clock are typed denials; nothing is persisted. It is not a Connect signature: a host that needs Connect-signed orders injects a Connect-backed issuer behind the same interface. parseCommunicationOsAuthorityDeploymentV1 also rejects a profile that could not admit an approved send (placement, encryption, ordering), so a bad configuration fails before the first delivery. createCommunicationOsDeferredAdmissionPortV1 is the admission port for hosts whose durable record of an approved send is their own CommunicationOS transaction rather than a queue write. It admits only an envelope with no communicationOsQueueAdmissionIssuesV1 (scoped profile digest, scope, ordering, encryption, placement, operation binding), records nothing, and types its result queueRecord: 'deferred_to_caller': the caller persists the operation, order, runtime outbox and envelope refs atomically with the effect, in the outbox row of an outbound message (appendCommunicationEventWithOutbox) or in the message event of an in-app post. The order and envelope expire ttlSeconds (30 to 900 s) after issue. A dispatcher that reaches the outbox record later must not send on the expired order: it re-admits the send (a fresh issue for the same idempotency key keeps the same operation and order ids) or reports a retryable failure, because the producing host already counts the send as queued. Size ttlSeconds above the worker's pickup latency. A CommunicationOS room is addressed as communicationOsRoomThreadRefV1(roomId) (communication-room:<base64url(roomId)>, reversed by parseCommunicationOsRoomThreadRefV1), because room ids may contain more than the one colon a runtime ref allows. An Agent Host approved-send resolver that compares context.threadId with command.threadRef must accept this form; the calendar briefing path still sends the raw room id. The current in-app walking skeleton is credential-free T1 evidence, not a live channel claim.

The same ./agent-host surface now provides the additive outbox delivery capability. CommunicationOsOutboxAgentHostProviderV1 accepts only a leased outbox record whose tenant, workspace, resource reference, idempotency key, immutable payload, and exact lease identity match the Runtime Node execution. The lease must still be live under the injected trusted clock. Only then can the injected channel dispatcher run. Its provider receipt is hashed into the Runtime Node receipt, while the raw provider receipt reference is not persisted there. Agent Host composes this provider through ExactProviderRouterV1; a nearby adapter or capability can never be selected as fallback. Unknown provider outcomes remain Runtime Node indeterminate custody and are not retried through this bridge.

An adapter ambiguity that carries sanitized provider diagnostic refs becomes an attested indeterminate provider receipt with no external delivery ref. Agent Host custody retains those diagnostics alongside its recovery ref. Diagnostic correlations remain evidence for reconciliation or operator help; they never prove acceptance, delivery, or definitive failure.

For held outcomes, Runtime Node may invoke observe with a separate exact work order. The injected reconciliation port must return provider evidence bound to the original send work order; Agent Host verifies its digest, source time, and result before the persistence port transitions custody to delivered or definitive failure. The observation also requires an unexpired, digest-bound authority artifact from an authenticated provider callback or authorized operator, tied to the exact scope, work order, and observation. Conversation text and diagnostic correlations alone cannot resolve custody. Observation never calls the channel dispatcher.

Why a factory + registry

• Adopt in <1 file. A vertical wires CommunicationOS through a single createCommunicationOsRuntime call (≤40 LOC) with no edits to any channel / persistence / agent package — it composes their published public APIs only.
• The registry lives HERE. Per the architecture (Option C), per-channel packages stay provider-specific; the ChannelAdapterRegistry composition point is owned by this factory, not by any single channel package.

The five composed ports

Runtime handle

createCommunicationOsRuntime(config) returns a CommunicationOsRuntime:

• ingest({ channelType, rawPayload }) — normalize a raw inbound payload.

Fixture-safe inbound normalization

normalizeFixtureInboundEnvelope bridges an already-normalized channel fixture into a tenant-bound CommunicationSpec ingestion record. The bridge reuses the F002 CompanyOS tenant-governance envelope for scope, consent, evidence/replay, and idempotency metadata. It performs no provider calls, webhook handling, credential lookup, or outbound sending.

• draftViaAgent({ sessionId, agentId, toolCallId, threadId, reason }) — produce a fail-closed pending approval; returns the approval id (the agent holds no send authority and cannot self-approve).
• searchInbox(input) / getThread(input) / listMessages(input) — actor-scoped reads.
• approveAndSend({ approvalRequestId, context }) — fail-closed; reconciliation does not repeat a provider-accepted send while audit/event completion remains retryable.
• eraseSubject({ channelType, ... }) — best-effort GDPR erasure (three-state outcome).
• channelRegistry / agent / approvalWorkflow — composed surfaces.

admitAgentAutomationFollowUpV1 is the background-result bridge. It accepts only exact claim, receipt, finalized automation state, follow-up, canonical conversation, and delivery-intent artifacts. It verifies every digest, scope, conversation, lifecycle, automation, and delivery-window binding before calling an injected durable intent-admission port. Reconciliation-required state, indeterminate outcomes, stale conversations, substituted intents, and mismatched admission receipts fail closed. The bridge does not select a provider, send a message, or weaken preference, consent, eligibility, fallback, or Runtime Node authority.

Wiring example (≤40 LOC, AC2.1)

The canonical wiring lives in src/runtime.fixture.ts between the WIRING-START / WIRING-END markers and is measured by src/runtime.test.ts:

return createCommunicationOsRuntime({
  persistence: deps.persistence,
  reads: deps.reads,
  channels: [
    createTelegramChannelAdapter({ botToken: deps.telegramBotToken, fetchImpl: deps.fetchImpl }),
    createEmailChannelAdapter({ outbound: deps.emailOutbound, fromAddress: { email: deps.fromEmail } }),
  ],
  model: {
    sovereignty: { llmProviderId: 'mistral' },
    providers: { mistral: { apiKey: deps.mistralApiKey } },
    createModel: deps.createModel,
  },
  inbox: { log: deps.eventLog },
  auth: { resolveActorContext: deps.resolveActor },
  observability: deps.observability,
  events: deps.events,
});

Self-host / on-prem bring-up (P2-S3, AC2.2)

@lssm-tech/integration.communication-os-runtime/install is the server-only one-command bring-up for a self-hosted CommunicationOS. bringUpCommunicationOs runs DB migrations, reads env + sovereignty config, composes the runtime via the factory, and (optionally) builds the governed MCP gateway.

One command

// server-only — pulls the node-only persistence ./database subpath
import { bringUpCommunicationOs } from '@lssm-tech/integration.communication-os-runtime/install';
import { buildCommunicationOsMcpServer } from '@lssm-tech/app.communicationos-mcp/server';

const { runtime, mcpServer, close } = await bringUpCommunicationOs({
  buildMcpServer: buildCommunicationOsMcpServer, // governed allowlist owner
});

With no DATABASE_URL this stands up an in-process PgLite engine (zero external services). Set DATABASE_URL to bind managed Postgres instead. The governed communication_os schema + actor-aware RLS are applied idempotently on every boot, so the call is safe to repeat.

Environment contract

No secrets are baked into code — every value is read from the env. All keys are optional; a bare environment resolves to a runnable EU self-host on PgLite.

SovereigntyProfile knobs

The defaults target a sovereign EU self-host: EU residency, a sovereign LLM (mistral, or a local endpoint via COMMOS_LLM_BASE_URL), RLS on, and a documented 365-day retention window — mirroring the SovereigntyProfileModel contract (communication-spec/contracts/sovereignty.ts). Switch to a local sovereign model with COMMOS_LLM_PROVIDER=local + COMMOS_LLM_BASE_URL; the slice runs unchanged (no code edit — only config).

Server-only boundary

The factory itself is pure composition — it imports NO node-only code. The node-only persistence engine (createDatabaseRuntime / Postgres) is built by the caller behind the server-only @lssm-tech/integration.communication-os-persistence/database subpath and injected as config.persistence. The package root barrel therefore stays browser-safe (pre-mortem #1). Never re-export the node-only engine through this package.

Exports

• . — createCommunicationOsRuntime, the runtime/config types, the orchestrator, and the governed audit-descriptor builder (browser-safe).
• ./runtime / ./runtime-types / ./types / ./approval-send-orchestrator / ./audit-descriptor — focused subpaths.
• ./delivery-routing — optional persisted delivery preparation. Hosts inject the artifact store and system principal; absent configuration and persistence conflicts fail closed. The surface selects no provider adapter and performs no send.
• ./install — server-only self-host bring-up (bringUpCommunicationOs, resolveSelfHostConfig, createSelfHostReadPort). Pulls the node-only persistence engine; never re-exported from the root barrel.

Tests

bun test            # full suite (orchestrator + factory + self-host bring-up)
bun run typecheck   # tsgo --noEmit

src/install/bring-up.smoke.test.ts is the AC2.2 smoke test: it brings up against PgLite (no external services), asserts the governed tables exist, the runtime is constructed, and the governed MCP tool allowlist registers (the send tool is never exposed). The real-Postgres path runs only when DATABASE_URL is set and is skipped gracefully otherwise.