Integration

For end-to-end onboarding journeys, see the quick-start guides:

• 3. Onboard your first tenant — register a subscription, delegate a customer cloud project
• 4. Provision the platform core — verify and provision CoreManifest kernels
• 5. Enroll a remote kernel — install agent-kernel on a host and connect it

This page covers conventions, prerequisites, and the integration surface for downstream consumers.

Workspace Package Reuse

Mnemose builds on several workspace and upstream packages directly:

Package	How Mnemose uses it
@freeside-collective/agent-runtime	Optional upstream reviewer runtime for future autonomous IAM review. Standalone Mnemose builds do not hard-depend on it.
@freeside-collective/agent-loop	AgentLoop, AgentPool, TaskManager, AngelObserver, InProcessA2aTransport — multi-agent orchestration
@freeside-collective/agent-protocol	HttpA2aTransport, createA2aRoutes, SseWriter — browser↔agent HTTP/SSE transport
@freeside-collective/mnemosyne-core + mnemosyne-sqlite	Persona memory, agent instinct steering, semantic recall for IAM risk scoring
@freeside-collective/ui-kit	shadcn/ui + Radix + Tailwind v4 — operator console components
@freeside-collective/telemetry	Correlation IDs, structured logs, OTel traces

When no published reviewer runtime is available, Mnemose’s IAM escalation reviewer fails closed and denies requests automatically rather than coupling the build to an unpublished external package.

Platform Deployment

A complete Mnemose environment is provisioned by scripts/install.sh — a four-stage pipeline (provision → deploy → seed → verify). It runs Pulumi for the Cloudflare baseline (D1, R2, KV, Queues, DNS, routes), deploys the gateway Worker and console via Wrangler, applies D1 migrations, seeds the system tenant, and runs synthetic verification probes.

See Quick-Start 2 — Deploy the platform for the full walkthrough.

CoreManifest as topology source of truth

@mnemose/bootstrap exports coreManifestForEnv(env) — the canonical description of what must exist for a deployment. The same manifest drives:

• Pulumi config (queue topic + subscription names)
• The local-dev bootstrap script
• The gateway’s platformCore query and provisionPlatformCore mutation
• The Fleet UI’s <PlatformCorePanel> component

Edit the manifest in one place; every consumer follows.

Tenant Onboarding

1. Call the registerSelf mutation to bootstrap the system tenant (or createTenant / the RegisterSubscription command for subscription-scoped tenants)
2. Call delegateCloudProject with provider-specific fields:
   • GCP: projectId, serviceAccountEmail (the SA Mnemose will impersonate), wifPoolId, region
   • AWS: projectId (account ID), serviceAccountEmail (IAM role ARN), wifPoolId (external ID), region
3. The handler validates the credentials by attempting mintToken before persisting
4. On success a CloudProjectDelegated event is emitted and the gateway begins accepting commands for that project

Customer Cloud Prerequisites

GCP

The customer must create a Workload Identity Federation pool in their project and grant the Workload Identity User role to Mnemose’s service account on that pool. The wifAudience is auto-derived from the pool ID in the handler.

AWS

The customer must create a cross-account IAM role with a trust policy allowing Mnemose’s operator account to sts:AssumeRole with the configured ExternalId. The role ARN is stored in the serviceAccountEmail column; the external ID is stored in wifPoolId.

Gateway Integration

The services/gateway is an always-on Hono process that:

• Serves the GraphQL HTTP endpoint at /graphql
• Serves the graphql-ws WebSocket endpoint at /graphql
• Serves MCP HTTP/SSE endpoints at /mcp/<server-name>
• Proxies A2A events between the browser client and the services/agent agent loop

The gateway receives a CloudPlatform instance at startup (constructed via createGcpPlatform or createAwsPlatform). All resolvers receive the platform via GraphQL context, so they can publish commands to the event bus without importing any cloud SDK directly.

A2A Endpoints (loop-host)

services/loop-host serves the A2A protocol surface via createA2aRoutes from @freeside-collective/agent-protocol.

Agent Card Discovery

Per the A2A v1.0 specification, the agent card must be discoverable at the server root. Both paths return the same AgentCard JSON.

Method	Path	Purpose
GET	/.well-known/agent-card.json	Agent card discovery (A2A v1.0 spec)
GET	/.well-known/agent.json	Legacy alias for the same agent card

Task Operations

Task endpoints are mounted under the /a2a prefix.

Method	Path	Purpose
GET	/a2a/tasks	List tasks
POST	/a2a/tasks/:id/cancel	Cancel a task

Command Handler Integration

Command handlers are Cloud Run Functions (type: 'module', FUNCTION_TARGET env var). They receive:

• platform: CloudPlatform — injected by the Cloud Run entrypoint
• db: DbClient — Drizzle client pointed at the Cloud SQL instance
• rawPayload: unknown — the decoded Pub/Sub message body

Handlers call platform.cloudCredentials.mintToken(credentialConfig) to get a short-lived BoundCredential, then pass it into IaaSContext for all IaaS.* calls.

Adding a New Cloud Provider

See Quick-Start 8 — Add a cloud adapter for the full walkthrough. Summary:

1. Add AzureCredentialConfig and AzureBoundCredential variants to cloud-credentials.ts
2. Implement each port interface in packages/cloud-adapters/src/azure/
3. Add a createAzurePlatform(config: AzurePlatformConfig) factory in azure/index.ts
4. Export from packages/cloud-adapters/src/index.ts
5. Add 'azure' to CloudProviderSchema in @mnemose/domain
6. Update delegate-cloud-project to handle the new provider’s credential fields

No existing handler code needs to change — they all depend on the CloudPlatform interface, not any specific implementation.