integration.communication-os-agent

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

Governed agent binding for CommunicationOS (plan P1-S2 + P1-S3, AC1.2, AC1.4).

It wires the @lssm-tech/lib.ai-agent runtime so it drafts replies and extracts decisions/risks/actions/summaries/intent for CommunicationOS — using the fail-closed governed command-inbox as the approval seam and a SovereigntyProfile-driven sovereign LLM (Mistral EU by default, Claude as a config-only alternative) — without ever giving the agent outbound send authority.

Why this is an integration package

This package binds three reusable libs (ai-agent, ai-providers, communication-runtime) plus the communication-spec contracts to a concrete runtime target (the governed agent). It introduces no new domain contracts and depends only downward (libs + spec), matching package-architecture.md for the integrations/ layer. It is the glue between the generic agent runtime and the CommunicationOS governance surface; it does not belong in a lib (it composes several libs) nor in a bundle/app (it is reusable across verticals).

Safety invariants (non-negotiable)

1. Allowlist, not denylist (pre-mortem #3, R3). createCommunicationAgentOperationRegistry() builds the agent's operationRegistry from an explicit allowlist: reply.draft, summary.generate, intent.classify, action.extract, decision.extract, risk.extract. The outbound communication.reply.send operation is structurally absent — it is never registered, so the agent can never resolve it into a tool. A future send-like operation cannot leak in by omission.
2. Inbox-backed approval seam (architect MUST-FIX 1). CommunicationInboxApprovalStore implements ApprovalStore. Every approval request is projected through createCommunicationCommandInboxItem, producing a fail-closed inbox item (canExecute: false). The agent can only create pending records; it cannot transition them to approved and holds no send tool. The store is wrapped as new ApprovalWorkflow(store) and passed as approvalWorkflow — the inbox object is never passed directly.
3. Send is a separate port the agent cannot call. Outbound delivery is reachable only by an inbox approval transition driven by a human or an explicitly authorized policy — never by the agent.

Sovereign model binding (P1-S3, AC1.4)

resolveSovereignDefaultModel / createSovereignModelSelector resolve the LanguageModel from the tenant SovereigntyProfile.llmProviderId: Mistral (sovereign EU) by default, Claude (anthropic) as the alternative, switchable by config only. On-prem/self-host hosting routes through a provider-local-model OpenAI-compatible baseUrl.

Thread assist over the Vercel AI Gateway

./thread-assist-gateway exports createGatewayThreadAssistModels(). It returns a read/draft-only thread assist port for any entry of COMMUNICATION_OS_AI_MODEL_CATALOG (@lssm-tech/lib.communication-spec/contracts/ai-model-catalog), built on the shared createVercelGatewayModel adapter.

Every call carries the enforced Gateway policy: EU inference zone, zero data retention, no training, and only the catalog's inference providers. There is no direct-provider key and no automatic fallback model. Ports are cached per model id, so switching models per request does not rebuild clients.

Omit apiKey to let the Gateway SDK use AI_GATEWAY_API_KEY or Vercel OIDC. CommunicationOS API uses this binding for summaries, drafts and inbox triage. The port's triage() (./thread-triage) requests strict structured output (Output.object with the communicationThreadTriageJsonSchema() schema) and validates the label again, so invalid output always rejects. The sovereign binding below remains for the governed agent.

Usage

import { createCommunicationOsAgent } from '@lssm-tech/integration.communication-os-agent';

const { factory, approvalStore, approvalWorkflow } = createCommunicationOsAgent({
  models: {
    sovereignty: { llmProviderId: 'mistral', hostingMode: 'saas' },
    providers: {
      mistral: { apiKey: process.env.MISTRAL_API_KEY },
      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY },
    },
  },
  inbox: { log: { events: [], version: 0 } },
});