/build-a-connection

The recipe for adding a new connection to MeshWeaver — a provider (Gmail, a CRM, an e-signature service…) that people connect once and agents then use. Covers the IConnectionProvider contract, the four states, the three credential kinds, where the credential lives and how it is encrypted, typed agent tools instead of a free-form API call, webhooks, a Getting-started step, and the tests that prove it.

• Instructions: You are adding a **connection**: a provider people connect once, that agents then use on their behalf. There is ONE Connections layer (`MeshWeaver.AI.Connections`); a new provider plugs into it. **Never hand-roll a fifth OAuth controller, a private credential node or a bespoke status page** — four such flows existed before this layer, each storing its credential its own way, and one kept an access token unencrypted. # 1. Implement `IConnectionProvider` in the module that owns the provider ```csharp public sealed class AcmeConnectionProvider(...) : IConnectionProvider { public ConnectionDescriptor Descriptor { get; } = new( "acme", "Acme CRM", "Read and update your Acme contacts", AcmeIcon, ConnectionKind.OAuth, // or CredentialSet, or Link [ConnectionOwnerKind.User, ConnectionOwnerKind.Space], // who may own it SkillPath: "Skill/connect", Order: 40); public bool IsAvailable => /* this deployment configured it: client id, host, number… */; public IObservable<ConnectionHealth> ObserveStatus(ConnectionOwner owner) => …; public IObservable<ConnectionHealth> Verify(ConnectionOwner owner) => …; // "Test connection" public ConnectStart Connect(ConnectionOwner owner, string returnUrl) => …; } ``` Register it in the module's service registration — the same lane as `IAgentPlugin`: ```csharp services.AddSingleton<IConnectionProvider>(sp => new AcmeConnectionProvider(sp.GetService<…>())); ``` Use `GetService`, never `GetRequiredService`: the catalog resolves EVERY provider for every render, so one that cannot activate would take the whole Connections page down. - A **compiled module** (`src/MeshWeaver.Acme`) declares a `ProjectReference` to `../MeshWeaver.AI/MeshWeaver.AI.csproj` explicitly (the container lane resolves only declared references) and its package adds `AI@^1.0.0` to `content.requires`. - **Node-native** `Source/` code can bind `MeshWeaver.AI` too — which is why the…
• Auto mount: yes
• Launches sub thread: no