- What is a BotNexus Extension?
- The
botnexus-extension.jsonmanifest - Extension Project Structure & Conventions
- Creating a Channel Extension
- Provider Extensions
- Creating a Tool Extension
- Dependency Injection Patterns
- Extension Metadata with BotNexusExtensionAttribute
- Accessing Configuration
- World-Level Extension Defaults
- OAuth Providers
- Webhook Handlers
- Testing Extensions in Isolation
- Build Pipeline & Output
- Out-of-tree extension repositories
- Troubleshooting
A BotNexus extension is a standalone .NET class library that plugs into the BotNexus core framework without requiring recompilation of the main Gateway application. Extensions enable developers to:
- Channels: Add messaging platforms (Discord, Slack, Telegram, etc.)
- Providers: Add LLM backends (OpenAI, Anthropic, Copilot, local models, etc.)
- Tools: Add agent capabilities (GitHub integration, web search, custom APIs, etc.)
The extension system is built on dynamic assembly loading driven by a manifest. Each extension is a
flat folder under the extensions root containing its assemblies and a botnexus-extension.json
manifest. AssemblyLoadContextExtensionLoader.DiscoverAsync enumerates the immediate subdirectories of
that root, and a directory without a botnexus-extension.json is skipped silently. There is no
{type}/{name} nesting: the extension type is declared inside the manifest, not encoded in the
path.
Key principles:
- The manifest is the contract. No manifest, no extension — see The
botnexus-extension.jsonmanifest. - Extensions are loaded into their own
AssemblyLoadContext. Extensions declaringendpoint-contributororapi-contributorare loaded non-collectible (ASP.NET usesReflection.Emitfor typed hub proxies). - Discovery is one level deep:
<extensions root>/<extension-folder>/botnexus-extension.json. - Extension configuration is keyed by manifest
idin the concrete scope declared byconfigurationScopes.
This is the single most important file in an extension. It is deserialized into ExtensionManifest
(src/gateway/BotNexus.Gateway.Contracts/ExtensionModels.cs) with case-insensitive property matching,
then validated by ValidateManifest before the entry assembly is loaded. A manifest that fails
validation causes the extension to be skipped with a warning — the gateway still starts.
| Field | Type | Required | Rule |
|---|---|---|---|
id |
string | yes | Non-empty. Unique across all extensions; a duplicate id is treated as already-loaded. Convention: botnexus-{kebab-name}. This is the key operators use in config. |
name |
string | yes | Non-empty human-readable display name. |
description |
string | no | One-line summary. Not validated. |
version |
string | yes | Non-empty. SemVer by convention. |
entryAssembly |
string | yes | Bare DLL filename, relative to the extension folder. Must exist. Rejected if it contains invalid filename characters, is an absolute path, or resolves outside the extension directory. |
extensionTypes |
string[] | yes | At least one value, each from the allowed set below. Matched case-insensitively. |
dependencies |
string[] | no | Extension ids that must already be loaded. An unresolved dependency fails the load. |
enabled |
bool | no | Defaults to true. |
configSchema |
object[] | no | Declared config fields. Defaults to []. See configSchema. |
The values are singular, and each corresponds to a service contract the loader discovers in the
entry assembly. The allowed set is the allowedTypes list in ValidateManifest; an unlisted value is
a hard validation failure.
| Value | Contract |
|---|---|
channel |
IChannelAdapter |
tool |
IAgentTool / IAgentToolContributor |
command |
ICommandContributor |
media-handler |
IMediaHandler |
endpoint-contributor |
IEndpointContributor |
api-contributor |
IApiContributor |
hook-handler |
hook handler types |
isolation |
IIsolationStrategy |
session-store |
ISessionStore |
auth-handler |
IGatewayAuthHandler |
router |
IMessageRouter |
agent-registry |
IAgentRegistry |
agent-supervisor |
IAgentSupervisor |
agent-communicator |
agent change/notifier contracts |
activity-broadcaster |
IActivityBroadcaster |
Two values carry behaviour beyond documentation:
channel— anIHostedServicecontributed by a channel extension is registered behindChannelFaultBarrierHostedService, so a misconfigured channel costs that channel and not the process.endpoint-contributor/api-contributor— force a non-collectible load context.
Each entry declares one top-level config field for this extension
(ExtensionConfigFieldSchema). ExtensionConfigValidator uses it for exactly two things: warn when a
required field is absent, and apply default when an optional field is absent. It does not
type-check values and does not descend into nested objects.
| Key | Type | Meaning |
|---|---|---|
id |
string | Key in the extension's config object. |
type |
string | string, integer, bool, object, array. Declarative only — not enforced. |
default |
string | Applied when the field is absent and not required. Always a string in the manifest. |
required |
bool | A missing required field produces a startup warning, not a failure. |
sensitive |
bool | Masked in logs and in the portal. |
description |
string | Shown in the portal's extension view. |
An empty configSchema: [] is legal and means the extension's config is not manifest-validated.
The smallest real manifest in the tree —
src/extensions/BotNexus.Extensions.ExecTool/botnexus-extension.json, deployed verbatim to
~/.botnexus/extensions/botnexus-exec/botnexus-extension.json:
{
"id": "botnexus-exec",
"name": "Exec Tool",
"description": "Shell command execution tool for agents",
"version": "1.0.0",
"entryAssembly": "BotNexus.Extensions.ExecTool.dll",
"extensionTypes": ["tool"],
"enabled": true,
"configSchema": []
}A channel extension declaring config fields —
src/extensions/BotNexus.Extensions.Channels.Telegram/botnexus-extension.json (schema abridged; the
file declares seven fields):
{
"id": "botnexus-telegram",
"name": "Telegram Channel",
"description": "Telegram Bot API channel adapter - long polling or secure webhook, DMs and group topics",
"version": "1.1.0",
"entryAssembly": "BotNexus.Extensions.Channels.Telegram.dll",
"extensionTypes": ["channel"],
"enabled": true,
"configSchema": [
{
"id": "botToken",
"type": "string",
"required": true,
"sensitive": true,
"description": "Telegram Bot API token from @BotFather. Required for all operations."
},
{
"id": "pollingTimeoutSeconds",
"type": "integer",
"required": false,
"default": "30",
"sensitive": false,
"description": "Long polling timeout in seconds."
}
]
}One flat folder per extension, named by the manifest id. An actual
~/.botnexus/extensions/ listing:
~/.botnexus/extensions/
├── botnexus-agent365/
├── botnexus-audio-transcription/
├── botnexus-data-store/
├── botnexus-debug-tool/
├── botnexus-exec/
│ ├── botnexus-extension.json
│ ├── BotNexus.Extensions.ExecTool.dll
│ ├── BotNexus.Extensions.ExecTool.deps.json
│ ├── BotNexus.Agent.Core.dll
│ ├── BotNexus.Domain.dll
│ └── runtimes/
├── botnexus-mcp/
├── botnexus-mcp-invoke/
├── botnexus-process/
├── botnexus-qmd/
├── botnexus-servicebus/
├── botnexus-signalr/
├── botnexus-skills/
├── botnexus-telegram/
└── botnexus-web/
The extensions root is gateway.extensionLoader.path in config.json, defaulting to
~/.botnexus/extensions. Set gateway.extensionLoader.enabled to false to disable dynamic loading
entirely.
In the repository, each extension is a project directly under src/extensions/ — no extra nesting —
with the manifest in the project root:
src/extensions/
├── BotNexus.Extensions.ExecTool/
│ ├── BotNexus.Extensions.ExecTool.csproj
│ ├── botnexus-extension.json
│ └── ...sources
└── BotNexus.Extensions.Channels.Telegram/
See src/extensions/AGENTS.md for the naming and manifest-formatting rules enforced on this tree.
There is no Extension.targets and no ExtensionType/ExtensionName MSBuild property. An extension
project sets CopyLocalLockFileAssemblies and declares its own copy target. The real
BotNexus.Extensions.ExecTool.csproj, abridged:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<!--
Extension assemblies load into an isolated AssemblyLoadContext, so their managed NuGet
dependency closure must ship in the extension output directory. Library projects do not copy
transitive managed dependencies by default, and the ALC cannot resolve one the host has not
already loaded - it fails with FileNotFoundException at load/dispose time and can crash the
host. See issues #2184 and #2001.
-->
<CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
<RootNamespace>BotNexus.Extensions.ExecTool</RootNamespace>
<Description>Enhanced shell execution tool with timeout, background mode, and Windows command resolution.</Description>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\..\agent\BotNexus.Agent.Core\BotNexus.Agent.Core.csproj" />
<ProjectReference Include="..\..\gateway\BotNexus.Gateway.Abstractions\BotNexus.Gateway.Abstractions.csproj" />
</ItemGroup>
<!-- Copy extension output + manifest to artifacts/extensions/ for dev-time discovery -->
<Target Name="CopyExtensionToArtifacts" AfterTargets="Build">
<PropertyGroup>
<ExtensionArtifactDir>$(MSBuildThisFileDirectory)..\..\..\artifacts\extensions\botnexus-exec\</ExtensionArtifactDir>
</PropertyGroup>
<MakeDir Directories="$(ExtensionArtifactDir)" />
<Copy SourceFiles="$(TargetPath)" DestinationFolder="$(ExtensionArtifactDir)" SkipUnchangedFiles="true" />
<Copy SourceFiles="$(MSBuildThisFileDirectory)botnexus-extension.json" DestinationFolder="$(ExtensionArtifactDir)" SkipUnchangedFiles="true" />
</Target>
</Project>The manifest must also be copied next to the assembly — the CopyExtensionToArtifacts target above
does it for dev-time discovery, and botnexus serve re-deploys each project's manifest into
<extensions root>/<id>/botnexus-extension.json when it stages extensions.
Channels are messaging platforms where agents receive user messages and send responses. Examples: Discord, Slack, Telegram, SignalR.
All channels inherit from BaseChannel, a template method pattern providing common functionality.
using BotNexus.Channels.Base;
using BotNexus.Core.Abstractions;
using BotNexus.Core.Models;
using Discord;
using Discord.WebSocket;
using Microsoft.Extensions.Logging;
namespace BotNexus.Channels.Discord;
/// <summary>Discord channel implementation using Discord.Net SDK.</summary>
public sealed class DiscordChannel : BaseChannel
{
private readonly DiscordSocketClient _client;
private readonly string _botToken;
public DiscordChannel(
string botToken,
IMessageBus messageBus,
ILogger<DiscordChannel> logger,
IReadOnlyList<string>? allowList = null)
: base(messageBus, logger, allowList)
{
_botToken = botToken;
_client = new DiscordSocketClient(new DiscordSocketConfig
{
LogLevel = LogSeverity.Warning
});
_client.MessageReceived += OnMessageReceivedAsync;
}
/// <summary>Unique channel identifier (e.g., "discord", "slack").</summary>
public override string Name => "discord";
/// <summary>Human-readable display name for UI/logs.</summary>
public override string DisplayName => "Discord";
/// <summary>Called when the channel should start listening for messages.</summary>
protected override async Task OnStartAsync(CancellationToken cancellationToken)
{
await _client.LoginAsync(TokenType.Bot, _botToken).ConfigureAwait(false);
await _client.StartAsync().ConfigureAwait(false);
}
/// <summary>Called when the channel should stop and clean up resources.</summary>
protected override async Task OnStopAsync(CancellationToken cancellationToken)
{
await _client.StopAsync().ConfigureAwait(false);
await _client.LogoutAsync().ConfigureAwait(false);
}
/// <summary>Send a message to a user/channel on this platform.</summary>
public override async Task SendAsync(OutboundMessage message, CancellationToken cancellationToken = default)
{
if (!ulong.TryParse(message.ChatId, out var channelId))
{
Logger.LogWarning("Invalid Discord channel ID: {ChatId}", message.ChatId);
return;
}
if (_client.GetChannel(channelId) is IMessageChannel channel)
await channel.SendMessageAsync(message.Content).ConfigureAwait(false);
else
Logger.LogWarning("Discord channel {ChannelId} not found", channelId);
}
/// <summary>Internal event handler that publishes incoming messages to the agent loop.</summary>
private async Task OnMessageReceivedAsync(SocketMessage socketMessage)
{
// Ignore bot messages to avoid feedback loops
if (socketMessage.Author.IsBot) return;
var inbound = new InboundMessage(
Channel: Name,
SenderId: socketMessage.Author.Id.ToString(),
ChatId: socketMessage.Channel.Id.ToString(),
Content: socketMessage.Content,
Timestamp: socketMessage.Timestamp,
Media: [],
Metadata: new Dictionary<string, object>
{
["username"] = socketMessage.Author.Username,
["message_id"] = socketMessage.Id
});
// Publish to the message bus for the agent loop to process
await PublishMessageAsync(inbound).ConfigureAwait(false);
}
}Create a strongly-typed config class for your channel. This will be bound from configuration (~/.botnexus/config.json or appsettings.json).
namespace BotNexus.Channels.Discord;
public class DiscordChannelConfig
{
public bool Enabled { get; set; }
public string? BotToken { get; set; }
public IReadOnlyList<string>? AllowFrom { get; set; }
}In configuration:
{
"BotNexus": {
"Channels": {
"Instances": {
"discord": {
"enabled": true,
"botToken": "your-discord-bot-token",
"allowFrom": ["admin-user-id"]
}
}
}
}
}Implement IExtensionRegistrar to control how your channel is registered in the DI container. This gives you full control over dependencies and validation.
using BotNexus.Core.Abstractions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
namespace BotNexus.Channels.Discord;
public sealed class DiscordExtensionRegistrar : IExtensionRegistrar
{
public void Register(IServiceCollection services, IConfiguration configuration)
{
var channelConfig = configuration.Get<DiscordChannelConfig>() ?? new DiscordChannelConfig();
// Skip loading if not enabled
if (!channelConfig.Enabled)
return;
// Validate required config
if (string.IsNullOrWhiteSpace(channelConfig.BotToken))
throw new InvalidOperationException("Discord channel is enabled but BotToken is missing.");
// Register as IChannel singleton
services.AddSingleton<IChannel>(sp => new DiscordChannel(
channelConfig.BotToken,
sp.GetRequiredService<IMessageBus>(),
sp.GetRequiredService<ILogger<DiscordChannel>>(),
channelConfig.AllowFrom));
}
}Add a botnexus-extension.json next to the .csproj:
{
"id": "botnexus-discord",
"name": "Discord Channel",
"description": "Discord messaging platform integration",
"version": "1.0.0",
"entryAssembly": "BotNexus.Extensions.Channels.Discord.dll",
"extensionTypes": ["channel"],
"enabled": true,
"configSchema": [
{
"id": "botToken",
"type": "string",
"required": true,
"sensitive": true,
"description": "Discord bot token."
}
]
}# Build the extension
dotnet build src/extensions/BotNexus.Extensions.Channels.Discord
# Output (assembly closure + manifest) lands in one flat folder:
# artifacts/extensions/botnexus-discord/Configure the extension by its manifest id in ~/.botnexus/config.json:
{
"gateway": {
"extensions": {
"defaults": {
"botnexus-discord": { "enabled": true, "botToken": "..." }
}
}
}
}LLM providers are not extensions and are not loaded through the extension pipeline. They live in
src/agent/BotNexus.Agent.Providers.*/ projects, implement IApiProvider from
BotNexus.Agent.Providers.Core.Registry, and are wired directly in
src/gateway/BotNexus.Gateway.Api/Program.cs. There is no provider value in the manifest's
extensionTypes allow-list, so a provider cannot be manifest-loaded at all.
Authoring a provider is documented in exactly one place: Provider Development Guide. This page does not restate it.
Reference implementations:
src/agent/BotNexus.Agent.Providers.OpenAICompat/— workingIApiProviderimplementation.src/agent/BotNexus.Agent.Providers.IntegrationMock/— deterministic test-only provider.
Tools are capabilities that agents can invoke to perform actions. Examples: GitHub API wrapper, web search, custom calculations, email sender.
Implement ITool interface with a Definition and ExecuteAsync method.
using System.Net.Http.Headers;
using System.Text.Json;
using System.Text.Json.Nodes;
using BotNexus.Core.Abstractions;
using BotNexus.Core.Models;
using Microsoft.Extensions.Logging;
namespace BotNexus.Tools.GitHub;
/// <summary>
/// GitHub tool that exposes read-only GitHub API operations to agents.
/// Actions: get_repo, list_issues, get_issue, list_prs, search_code.
/// </summary>
public sealed class GitHubTool : ITool
{
private readonly HttpClient _http;
private readonly ILogger _logger;
private readonly string? _defaultOwner;
public GitHubTool(GitHubToolConfig config, HttpClient? httpClient = null, ILogger? logger = null)
{
_logger = logger ?? NullLogger.Instance;
_defaultOwner = config.DefaultOwner;
_http = httpClient ?? new HttpClient();
_http.BaseAddress = new Uri(config.ApiBase.TrimEnd('/') + '/');
_http.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/vnd.github+json"));
_http.DefaultRequestHeaders.Add("X-GitHub-Api-Version", "2022-11-28");
_http.DefaultRequestHeaders.Add("User-Agent", "BotNexus-GitHub-Tool/1.0");
if (!string.IsNullOrWhiteSpace(config.Token))
_http.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", config.Token);
}
/// <summary>Define what this tool does and what parameters it accepts.</summary>
public ToolDefinition Definition { get; } = new(
Name: "github",
Description: "Interact with GitHub repositories (read-only). Actions: get_repo, list_issues, get_issue, list_prs, search_code.",
Parameters: new Dictionary<string, ToolParameterSchema>
{
["action"] = new("string", "Action to perform",
Required: true,
EnumValues: ["get_repo", "list_issues", "get_issue", "list_prs", "search_code"]),
["owner"] = new("string", "Repository owner (user or organization)", Required: false),
["repo"] = new("string", "Repository name", Required: false),
["number"] = new("string", "Issue or PR number", Required: false),
["query"] = new("string", "Search query", Required: false),
["state"] = new("string", "Filter: open, closed, or all (default: open)", Required: false,
EnumValues: ["open", "closed", "all"]),
["per_page"] = new("string", "Results per page (1-100, default: 10)", Required: false)
});
/// <summary>Execute the tool with the given parameters.</summary>
public async Task<string> ExecuteAsync(
IReadOnlyDictionary<string, object?> arguments,
CancellationToken cancellationToken = default)
{
_logger.LogDebug("Executing tool '{ToolName}'", Definition.Name);
try
{
var action = GetRequiredString(arguments, "action");
var owner = GetOptionalString(arguments, "owner", _defaultOwner ?? string.Empty);
var repo = GetOptionalString(arguments, "repo");
var state = GetOptionalString(arguments, "state", "open");
var perPage = GetOptionalInt(arguments, "per_page", 10);
return await (action.ToLowerInvariant() switch
{
"get_repo" => GetRepoAsync(owner, repo, cancellationToken),
"list_issues" => ListIssuesAsync(owner, repo, state, perPage, cancellationToken),
"get_issue" => GetIssueAsync(owner, repo, GetRequiredString(arguments, "number"), cancellationToken),
"list_prs" => ListPrsAsync(owner, repo, state, perPage, cancellationToken),
"search_code" => SearchCodeAsync(owner, repo, GetRequiredString(arguments, "query"), perPage, cancellationToken),
_ => throw new ToolArgumentException($"Unknown action '{action}'")
}).ConfigureAwait(false);
}
catch (OperationCanceledException)
{
_logger.LogWarning("Tool '{ToolName}' was cancelled", Definition.Name);
throw;
}
catch (ToolArgumentException ex)
{
_logger.LogWarning("Tool '{ToolName}' argument error: {Message}", Definition.Name, ex.Message);
return $"Error: {ex.Message}";
}
catch (Exception ex)
{
_logger.LogError(ex, "Tool '{ToolName}' threw an unexpected error", Definition.Name);
return $"Error executing tool '{Definition.Name}': {ex.Message}";
}
}
private async Task<string> GetRepoAsync(string owner, string repo, CancellationToken ct)
{
ValidateOwnerRepo(owner, repo);
var json = await GetJsonAsync($"repos/{owner}/{repo}", ct).ConfigureAwait(false);
if (json is not JsonObject obj) return "Repository not found";
return FormatJson(new
{
full_name = obj["full_name"]?.GetValue<string>(),
description = obj["description"]?.GetValue<string>(),
language = obj["language"]?.GetValue<string>(),
stars = obj["stargazers_count"]?.GetValue<int>(),
forks = obj["forks_count"]?.GetValue<int>(),
open_issues = obj["open_issues_count"]?.GetValue<int>(),
default_branch = obj["default_branch"]?.GetValue<string>(),
html_url = obj["html_url"]?.GetValue<string>(),
visibility = obj["visibility"]?.GetValue<string>(),
topics = obj["topics"]?.AsArray()?.Select(t => t?.GetValue<string>()).ToList()
});
}
private async Task<string> ListIssuesAsync(string owner, string repo, string state, int perPage, CancellationToken ct)
{
ValidateOwnerRepo(owner, repo);
var json = await GetJsonAsync($"repos/{owner}/{repo}/issues?state={state}&per_page={perPage}", ct).ConfigureAwait(false);
if (json is not JsonArray items) return "No issues found";
var issues = items.OfType<JsonObject>().Select(i => new
{
number = i["number"]?.GetValue<int>(),
title = i["title"]?.GetValue<string>(),
state = i["state"]?.GetValue<string>(),
author = i["user"]?["login"]?.GetValue<string>(),
created_at = i["created_at"]?.GetValue<string>(),
html_url = i["html_url"]?.GetValue<string>()
});
return FormatJson(issues);
}
private async Task<string> GetIssueAsync(string owner, string repo, string number, CancellationToken ct)
{
ValidateOwnerRepo(owner, repo);
if (!int.TryParse(number, out _))
throw new ToolArgumentException("'number' must be a valid integer");
var json = await GetJsonAsync($"repos/{owner}/{repo}/issues/{number}", ct).ConfigureAwait(false);
if (json is not JsonObject obj) return "Issue not found";
return FormatJson(new
{
number = obj["number"]?.GetValue<int>(),
title = obj["title"]?.GetValue<string>(),
state = obj["state"]?.GetValue<string>(),
author = obj["user"]?["login"]?.GetValue<string>(),
body = obj["body"]?.GetValue<string>(),
labels = obj["labels"]?.AsArray()?.OfType<JsonObject>().Select(l => l["name"]?.GetValue<string>()).ToList(),
html_url = obj["html_url"]?.GetValue<string>()
});
}
private async Task<string> ListPrsAsync(string owner, string repo, string state, int perPage, CancellationToken ct)
{
ValidateOwnerRepo(owner, repo);
var json = await GetJsonAsync($"repos/{owner}/{repo}/pulls?state={state}&per_page={perPage}", ct).ConfigureAwait(false);
if (json is not JsonArray items) return "No pull requests found";
var prs = items.OfType<JsonObject>().Select(p => new
{
number = p["number"]?.GetValue<int>(),
title = p["title"]?.GetValue<string>(),
state = p["state"]?.GetValue<string>(),
author = p["user"]?["login"]?.GetValue<string>(),
head = p["head"]?["label"]?.GetValue<string>(),
base_branch = p["base"]?["label"]?.GetValue<string>(),
html_url = p["html_url"]?.GetValue<string>()
});
return FormatJson(prs);
}
private async Task<string> SearchCodeAsync(string owner, string repo, string query, int perPage, CancellationToken ct)
{
var repoFilter = (!string.IsNullOrEmpty(owner) && !string.IsNullOrEmpty(repo))
? $"+repo:{owner}/{repo}" : string.Empty;
var json = await GetJsonAsync(
$"search/code?q={Uri.EscapeDataString(query)}{repoFilter}&per_page={perPage}", ct).ConfigureAwait(false);
if (json is not JsonObject result) return "No results";
var items = result["items"]?.AsArray()?.OfType<JsonObject>().Select(i => new
{
path = i["path"]?.GetValue<string>(),
repo = i["repository"]?["full_name"]?.GetValue<string>(),
html_url = i["html_url"]?.GetValue<string>()
});
return FormatJson(new
{
total_count = result["total_count"]?.GetValue<int>(),
items
});
}
private async Task<JsonNode?> GetJsonAsync(string path, CancellationToken ct)
{
var response = await _http.GetAsync(path, ct).ConfigureAwait(false);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync(ct).ConfigureAwait(false);
return JsonNode.Parse(body);
}
private static void ValidateOwnerRepo(string owner, string repo)
{
if (string.IsNullOrWhiteSpace(owner))
throw new ToolArgumentException("'owner' is required (set a default in GitHubToolConfig)");
if (string.IsNullOrWhiteSpace(repo))
throw new ToolArgumentException("'repo' is required");
}
private static string FormatJson(object? value) =>
JsonSerializer.Serialize(value, new JsonSerializerOptions { WriteIndented = true });
private static string GetRequiredString(IReadOnlyDictionary<string, object?> args, string key)
{
var value = args.GetValueOrDefault(key)?.ToString();
if (string.IsNullOrWhiteSpace(value))
throw new ToolArgumentException($"'{key}' is required and must be nonnempty.");
return value;
}
private static string GetOptionalString(IReadOnlyDictionary<string, object?> args, string key, string defaultValue = "")
=> args.GetValueOrDefault(key)?.ToString() ?? defaultValue;
private static int GetOptionalInt(IReadOnlyDictionary<string, object?> args, string key, int defaultValue = 0)
{
var raw = args.GetValueOrDefault(key);
if (raw is null) return defaultValue;
if (raw is int i) return i;
if (raw is long l) return (int)l;
return int.TryParse(raw.ToString(), out var parsed) ? parsed : defaultValue;
}
}
internal sealed class ToolArgumentException(string message) : Exception(message);namespace BotNexus.Tools.GitHub;
public class GitHubToolConfig
{
public string ApiBase { get; set; } = "https://api.github.com";
public string? Token { get; set; }
public string? DefaultOwner { get; set; }
}using BotNexus.Core.Abstractions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Logging;
using Microsoft.Extensions.Options;
namespace BotNexus.Tools.GitHub;
public sealed class GitHubExtensionRegistrar : IExtensionRegistrar
{
public void Register(IServiceCollection services, IConfiguration configuration)
{
services.Configure<GitHubToolConfig>(configuration);
services.AddSingleton<ITool>(sp =>
{
var config = sp.GetRequiredService<IOptions<GitHubToolConfig>>().Value;
var logger = sp.GetService<ILogger<GitHubTool>>();
return new GitHubTool(config, logger: logger);
});
}
}{
"id": "botnexus-github",
"name": "GitHub Tools",
"description": "GitHub API tools for agents",
"version": "1.0.0",
"entryAssembly": "BotNexus.Extensions.GitHub.dll",
"extensionTypes": ["tool"],
"enabled": true,
"configSchema": [
{ "id": "token", "type": "string", "required": true, "sensitive": true, "description": "GitHub PAT." },
{ "id": "defaultOwner", "type": "string", "required": false, "sensitive": false, "description": "Default repository owner." }
]
}Operator config, keyed by the manifest id:
{
"gateway": {
"extensions": {
"defaults": {
"botnexus-github": { "enabled": true, "token": "ghp_...", "defaultOwner": "your-org" }
}
}
}
}Emitting telemetry? Extensions get the same telemetry seam the platform core uses — metrics auto-prefixed to
botnexus.ext.<id>.*and durable usage isolated to your extension id in the shared store. See Extension Telemetry.
If your extension assembly contains exactly one type implementing IChannel or ITool, the loader will automatically register it without requiring an IExtensionRegistrar. (LLM providers are not extension-loaded at all — see Provider Extensions.)
// Extension loader discovers this automatically
public sealed class MyChannel : IChannel { ... }
// No need for IExtensionRegistrar — it's registered as IChannelLimitations:
- Only works for single implementations
- No configuration binding
- No validation
- No logging
Implement IExtensionRegistrar for full control:
public sealed class MyExtensionRegistrar : IExtensionRegistrar
{
public void Register(IServiceCollection services, IConfiguration configuration)
{
// Bind configuration from this extension's section
services.Configure<MyConfig>(configuration);
// Validate configuration
var config = configuration.Get<MyConfig>();
if (config?.ApiKey is null)
throw new InvalidOperationException("MyExtension requires ApiKey in config");
// Register as singleton or transient
services.AddSingleton<IMyInterface>(sp =>
new MyImplementation(
sp.GetRequiredService<IMyDependency>(),
sp.GetRequiredService<ILogger<MyImplementation>>(),
config));
return services;
}
}Benefits:
- Full DI control
- Configuration validation
- Multiple implementations
- Logging and diagnostics
- Per-request vs singleton control
For complex registrations, use static extension methods alongside IExtensionRegistrar:
public static class MyServiceExtensions
{
public static IServiceCollection AddMyServices(
this IServiceCollection services,
IConfiguration configuration)
{
services.Configure<MyConfig>(configuration);
services.AddSingleton<ITool, MyTool>();
return services;
}
}
public sealed class MyExtensionRegistrar : IExtensionRegistrar
{
public void Register(IServiceCollection services, IConfiguration configuration)
=> services.AddMyServices(configuration);
}Optionally, decorate your assembly with BotNexusExtensionAttribute for metadata (informational only — not required for loading).
using BotNexus.Core.Abstractions;
[assembly: BotNexusExtension(
name: "Discord Channel",
Version = "1.0.0",
Author = "Your Name",
Description = "Discord messaging platform integration for BotNexus agents")]
namespace BotNexus.Channels.Discord;Query at runtime:
var attr = assembly.GetCustomAttribute<BotNexusExtensionAttribute>();
Console.WriteLine($"{attr?.Name} v{attr?.Version} by {attr?.Author}");Extensions receive configuration scoped to their own section (from ~/.botnexus/config.json or appsettings.json).
public void Register(IServiceCollection services, IConfiguration configuration)
{
// configuration is already scoped to this extension's section,
// keyed by the manifest id (e.g. "botnexus-web")
var config = configuration.Get<MyExtensionConfig>() ?? new MyExtensionConfig();
// Access properties
var apiKey = config.ApiKey;
var model = config.DefaultModel;
}Runtime settings are keyed by manifest id. Loader settings are separate from extension-owned settings:
{
"world": { "extensions": { "example-policy": { "mode": "restricted" } } },
"gateway": {
"extensionLoader": { "path": "~/.botnexus/extensions", "enabled": true },
"extensions": { "example-transport": { "listen": true } }
},
"agents": {
"defaults": { "extensions": { "botnexus-web": { "search": { "provider": "brave", "apiKey": "${env:WEB_KEY}" } } } },
"my-agent": { "extensions": { "botnexus-web": { "search": { "maxResults": 10 } } } }
}
}For best practices, inject IOptions<T> in your services:
public sealed class MyTool
{
public MyTool(IOptions<MyToolConfig> options, ILogger<MyTool> logger)
{
var config = options.Value;
Logger = logger;
}
}agents.defaults.extensions.<id> stores shared agent values. A consumer binds that entry and the named agents.<agentId>.extensions.<id> entry separately, then chooses named-agent, agent-default, and code fallback for each property. This intentionally is not a deep merge: world and gateway settings never flow into agent settings.
Some LLM providers (like GitHub Copilot) require OAuth instead of API keys. Use IOAuthProvider to implement OAuth flows.
namespace BotNexus.Core.Abstractions;
public interface IOAuthProvider
{
Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default);
bool HasValidToken { get; }
}
public interface IOAuthTokenStore
{
Task<OAuthToken?> GetTokenAsync(string key);
Task SaveTokenAsync(string key, OAuthToken token);
Task DeleteTokenAsync(string key);
}
public record OAuthToken(string AccessToken, DateTime ExpiresAt, string? RefreshToken = null)
{
public bool IsExpired => DateTime.UtcNow >= ExpiresAt.AddMinutes(-5);
}using BotNexus.Core.Abstractions;
using Microsoft.Extensions.Logging;
namespace BotNexus.Agent.Providers.Copilot;
public sealed class CopilotOAuthProvider : IOAuthProvider
{
private readonly string _clientId;
private readonly IOAuthTokenStore _tokenStore;
private readonly ILogger _logger;
public CopilotOAuthProvider(string clientId, IOAuthTokenStore tokenStore, ILogger logger)
{
_clientId = clientId;
_tokenStore = tokenStore;
_logger = logger;
}
public bool HasValidToken { get; private set; }
public async Task<string> GetAccessTokenAsync(CancellationToken cancellationToken = default)
{
var token = await _tokenStore.GetTokenAsync("copilot") ?? await AcquireTokenAsync(cancellationToken);
HasValidToken = token is not null && !token.IsExpired;
return token?.AccessToken ?? throw new InvalidOperationException("No valid Copilot token");
}
private async Task<OAuthToken?> AcquireTokenAsync(CancellationToken cancellationToken)
{
// Implement GitHub device code flow
_logger.LogInformation("Starting GitHub device code flow for Copilot...");
using var http = new HttpClient();
// 1. Request device code
var deviceRequest = new { client_id = _clientId, scopes = "read:user" };
var deviceResponse = await http.PostAsJsonAsync(
"https://github.com/login/device/code",
deviceRequest,
cancellationToken);
var deviceData = await deviceResponse.Content.ReadAsAsync<dynamic>();
var deviceCode = deviceData.device_code;
var userCode = deviceData.user_code;
var verificationUri = deviceData.verification_uri;
_logger.LogInformation("Visit {Url} and enter code: {UserCode}", verificationUri, userCode);
Console.WriteLine($"Visit {verificationUri} and enter: {userCode}");
// 2. Poll for token
while (true)
{
await Task.Delay(5000, cancellationToken);
var tokenRequest = new { client_id = _clientId, device_code = deviceCode, grant_type = "urn:ietf:params:oauth:grant-type:device_code" };
var tokenResponse = await http.PostAsJsonAsync(
"https://github.com/login/oauth/access_token",
tokenRequest,
cancellationToken);
var tokenData = await tokenResponse.Content.ReadAsAsync<dynamic>();
if (tokenData.access_token is not null)
{
var token = new OAuthToken(
AccessToken: tokenData.access_token,
ExpiresAt: DateTime.UtcNow.AddHours(8),
RefreshToken: tokenData.refresh_token);
await _tokenStore.SaveTokenAsync("copilot", token);
return token;
}
}
}
}using BotNexus.Core.Abstractions;
using BotNexus.Core.Configuration;
using System.Text.Json;
namespace BotNexus.Agent.Providers.Copilot;
public sealed class FileOAuthTokenStore : IOAuthTokenStore
{
private readonly string _storePath;
public FileOAuthTokenStore(string? tokenDirectory = null)
{
_storePath = tokenDirectory
?? Path.Combine(BotNexusHome.ResolveHomePath(), "tokens");
Directory.CreateDirectory(_storePath);
}
public async Task<OAuthToken?> GetTokenAsync(string key)
{
var filePath = Path.Combine(_storePath, $"{key}.json");
if (!File.Exists(filePath)) return null;
var json = await File.ReadAllTextAsync(filePath);
return JsonSerializer.Deserialize<OAuthToken>(json);
}
public async Task SaveTokenAsync(string key, OAuthToken token)
{
var filePath = Path.Combine(_storePath, $"{key}.json");
var json = JsonSerializer.Serialize(token);
await File.WriteAllTextAsync(filePath, json);
}
public Task DeleteTokenAsync(string key)
{
var filePath = Path.Combine(_storePath, $"{key}.json");
if (File.Exists(filePath)) File.Delete(filePath);
return Task.CompletedTask;
}
}If your extension needs to receive incoming webhooks (e.g., Slack request URL callbacks), implement IWebhookHandler.
using BotNexus.Core.Abstractions;
using Microsoft.AspNetCore.Http;
namespace BotNexus.Channels.Slack;
public sealed class SlackWebhookHandler : IWebhookHandler
{
private readonly IChannel _slackChannel;
private readonly ILogger _logger;
public SlackWebhookHandler(IChannel slackChannel, ILogger<SlackWebhookHandler> logger)
{
_slackChannel = slackChannel;
_logger = logger;
}
/// <summary>Route path where this handler listens (e.g., /webhooks/slack).</summary>
public string Path => "/webhooks/slack";
/// <summary>Process incoming webhook request.</summary>
public async Task<IResult> HandleAsync(HttpContext context)
{
try
{
var body = await new StreamReader(context.Request.Body).ReadToEndAsync();
_logger.LogDebug("Received Slack webhook: {Body}", body);
var slackEvent = JsonSerializer.Deserialize<SlackEventWrapper>(body);
// Handle Slack verification challenge
if (slackEvent?.Type == "url_verification")
{
return Results.Ok(new { challenge = slackEvent.Challenge });
}
// Handle event
if (slackEvent?.Event is not null)
{
var inbound = new InboundMessage(
Channel: "slack",
SenderId: slackEvent.Event.User,
ChatId: slackEvent.Event.Channel,
Content: slackEvent.Event.Text,
Timestamp: DateTime.UtcNow,
Media: [],
Metadata: new Dictionary<string, object> { ["ts"] = slackEvent.Event.Ts });
// Publish to agent loop
// await _slackChannel.PublishMessageAsync(inbound);
}
return Results.Ok();
}
catch (Exception ex)
{
_logger.LogError(ex, "Error processing Slack webhook");
return Results.StatusCode(500);
}
}
}Register webhook handlers in your extension registrar:
services.AddSingleton<IWebhookHandler>(sp =>
new SlackWebhookHandler(
sp.GetRequiredService<IChannel>(),
sp.GetRequiredService<ILogger<SlackWebhookHandler>>()));The Gateway automatically registers all IWebhookHandler instances at startup.
Test your extension without the full Gateway by mocking dependencies.
using BotNexus.Core.Abstractions;
using BotNexus.Core.Models;
using BotNexus.Tools.GitHub;
using Xunit;
public sealed class GitHubToolTests
{
[Fact]
public async Task GetRepo_WithValidOwnerAndRepo_ReturnsRepositoryData()
{
// Arrange
var config = new GitHubToolConfig { DefaultOwner = "microsoft" };
var tool = new GitHubTool(config);
var args = new Dictionary<string, object?>
{
["action"] = "get_repo",
["owner"] = "microsoft",
["repo"] = "vscode"
};
// Act
var result = await tool.ExecuteAsync(args);
// Assert
Assert.NotNull(result);
Assert.Contains("vscode", result);
}
[Fact]
public async Task ExecuteAsync_WithMissingRequiredArg_ReturnsErrorMessage()
{
// Arrange
var config = new GitHubToolConfig();
var tool = new GitHubTool(config);
var args = new Dictionary<string, object?>
{
["action"] = "get_repo"
// Missing "owner" and "repo"
};
// Act
var result = await tool.ExecuteAsync(args);
// Assert
Assert.Contains("Error", result);
}
}using BotNexus.Core.Abstractions;
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Xunit;
public sealed class GitHubExtensionTests
{
[Fact]
public void GitHubExtensionRegistrar_Registers_ITool()
{
// Arrange
var services = new ServiceCollection();
var config = new ConfigurationBuilder()
.AddInMemoryCollection(new Dictionary<string, string?>
{
["DefaultOwner"] = "microsoft",
["Token"] = "ghp_test"
})
.Build();
// Act
var registrar = new GitHubExtensionRegistrar();
registrar.Register(services, config);
// Assert
var provider = services.BuildServiceProvider();
var tool = provider.GetService<ITool>();
Assert.NotNull(tool);
Assert.Equal("github", tool.Definition.Name);
}
}Each extension project declares its own AfterTargets="Build" copy target (there is no shared
Extension.targets). When you build an extension project:
- Compile: normal MSBuild compilation to
bin/<Config>/net10.0/, including the transitive managed dependency closure becauseCopyLocalLockFileAssembliesistrue. - Copy: the project's
CopyExtensionToArtifactstarget copies the entry assembly and thebotnexus-extension.jsonmanifest intoartifacts/extensions/<manifest-id>/. - Deploy:
botnexus servestages each extension project's output plus its manifest into<extensions root>/<manifest-id>/, pruning stale files from earlier generations.
Example:
# Build the exec tool extension
dotnet build src/extensions/BotNexus.Extensions.ExecTool
# Output appears in one flat folder named by the manifest id:
# artifacts/extensions/botnexus-exec/
# ├── botnexus-extension.json
# ├── BotNexus.Extensions.ExecTool.dll
# └── ...dependency closure# Build the entire solution (includes all extensions)
dotnet build dirs.proj# Stage extensions into the gateway's extensions root
botnexus serve
# Extensions land in:
# ~/.botnexus/extensions/<manifest-id>/Use the public BotNexus extension template when the extension belongs in its own Git repository. The template contains a manifest, one deterministic IAgentTool, tests, packaging scripts, CopyLocalLockFileAssemblies=true, and both supported checkout reference shapes.
src/BotNexus.Extensions.Reference/
BotNexus.Extensions.Reference.csproj
ReferenceEchoTool.cs
botnexus-extension.json
tests/BotNexus.Extensions.Reference.Tests/
scripts/
Keep the manifest beside the extension project. Packaged output remains one flat folder named by the manifest id; the repository may contain source, tests, automation and documentation around that folder.
Pass the local checkout as the BotNexusRepoRoot MSBuild property. The template also reads the BOTNEXUS_REPO_ROOT environment variable.
The default source shape uses ProjectReference entries below $(BotNexusRepoRoot). Use it for normal development because contract changes compile with the extension. The binary shape uses Reference and HintPath entries for BotNexus assemblies already built from the same checkout. Select it with -p:BotNexusReferenceShape=binary; build the required BotNexus projects first and use BotNexusBinaryConfiguration when they were not built in Release.
Both shapes must fail with the resolved missing path. Neither shape may search another machine path, download an unversioned DLL, or commit BotNexus contract assemblies to the extension repository. Pin the BotNexus revision in continuous integration and release automation.
Main branch: the lifecycle below is implemented on main at a753ffe23 (including #4505). Check that your installed version includes it before using these commands.
Warning
A compiled extension runs inside the gateway with full gateway trust and the gateway process's operating-system permissions. Its build can also execute repository-defined MSBuild tasks with the build process's permissions. Registration is not a sandbox or code-signing decision. Review the repository, dependencies and requested revision before enabling it. Enabled registrations participate in later lifecycle operations, not only an explicit sync.
- Install Git and the .NET SDK required by the BotNexus checkout and the extension project. The reconciler invokes
gitanddotneton the host and passes the resolved BotNexus checkout asBotNexusRepoRootto extension builds. - Make the repository reachable from that host. For a private repository, configure Git credentials or SSH authentication for the operating-system account that runs the CLI or gateway. Git operations set
GIT_TERMINAL_PROMPT=0; arrange noninteractive authentication, including any SSH host-key trust, before syncing. A portal session or an agent's GitHub tool credentials do not configure host Git authentication. Do not put credentials in the repository URL. - Use a compatible extension revision and keep a record of the requested ref and resolved commit. The registration ID identifies a source repository; each deployed extension uses its own manifest
id.
The URL below is fictional. Replace it with a repository you have reviewed and can access. Run these commands on the BotNexus host, using the same BotNexus home as the gateway:
# Save repository metadata; this does not fetch or execute repository content.
botnexus extensions add --id reference-extension --url https://git.example.com/extensions/reference-extension.git --ref main
botnexus extensions list
# Clone/update, resolve the ref, build and deploy all enabled registrations.
botnexus extensions sync
# Restart interrupts active gateway work and loads the deployed assemblies.
botnexus gateway restartextensions reconcile is an alias for extensions sync. Adding, updating, enabling, disabling or removing a registration changes metadata only; synchronization is a separate operation. To review a registration before it participates in lifecycle work, add it with --disabled and enable it later with botnexus extensions enable --id reference-extension.
--ref accepts a branch, tag or commit. A commit gives the most reproducible registration; a tag is readable but can be moved by a repository owner; a branch follows future commits. Use --no-updates on add or update to stop fetching an existing clone; it does not disable builds or deployment, and a missing clone is still cloned. Use update --updates to restore fetching. For example:
botnexus extensions update --id reference-extension --ref v1.0.0
botnexus extensions sync
botnexus gateway restartThe Configuration page exposes the same registry and requires an explicit trust acknowledgement when adding a repository. Sync Now is available for enabled registrations and runs the shared clone/ref/build/deploy pipeline for the selected repository. Deployment still reconciles all enabled repository sources and in-tree sources, using previous staged output for repositories not rebuilt by that request. Sync does not restart the running gateway or grant tools to an agent.
ExtensionLifecycleReconciler performs these steps under a lock scoped to the BotNexus home. A process-local semaphore and an exclusive file lock serialize overlapping CLI and API passes across processes.
- Materialize source. Clone a missing repository under
<BotNexus home>/extension-repositories/<registration-id>/repository. For an existing clean clone, fetch when updates are enabled, resolve the requested branch, tag or commit to an exact SHA, and check out that commit detached. - Discover and build. Recursively find every
.csprojwith abotnexus-extension.jsonin the same directory. A repository can contain multiple extension projects; test or helper projects without an adjacent manifest are not selected. Build each selected project inRelease, withBotNexusRepoRootand a separate output directory inside a candidate generation. No selected projects is a named failure. - Validate and deploy. Once all selected projects build, validate their outputs and reconcile them with in-tree outputs and other enabled registered sources into
<BotNexus home>/extensions/<manifest-id>. Deployment checks manifests, entry assemblies and extension-ID collisions before activation. Each extension directory uses atomic replacement with retry/rollback handling; this is not an all-repositories atomic switch. - Record the result. Promote the candidate to the repository's
stageddirectory and record lifecycle success only after deployment is accepted for that repository. The registry also stores the clone path, attempt time, resolved commit and bounded named failure details.
The same pipeline runs from botnexus build, botnexus update, botnexus serve, and gateway start/restart. Where those paths build BotNexus, reconciliation follows a successful platform build. Repository failures are reported but do not by themselves fail the platform build or prevent update/startup from continuing. Explicit extensions sync returns a non-zero exit code if an enabled repository fails; the API reports a failed selected sync to the caller.
Source reconciliation never resets, cleans or deletes the managed clone. A dirty clone, a current commit that is not an ancestor of the requested commit, a missing or mismatched origin, or an invalid ref produces a named failure. With --no-updates, an existing clone resolves refs from locally available Git objects without fetching. Preserve local work and resolve the reported condition explicitly rather than expecting sync to discard it.
A clone or build failure does not promote a partial candidate generation: the previous staged generation remains a deployment source for an enabled registration. Registered-source validation failures preserve source-owned last-known-good live directories when available. Activation failures attempt to restore the previous live directory; rollback can also fail, so inspect the named diagnostic before relying on that deployment. Other repositories can continue. A first-time failure has no previous deployment to fall back to, and a successful pass can remove obsolete output. Last-known-good handling is not a guarantee of extension compatibility or a backup of operator data.
Registered output is included in normal deployment reconciliation; it is not treated as an unrelated manual installation and blindly pruned on the next serve or update. Unregistered manual package installations can still be pruned as stale. Keep the source and package if using the template's local-install scripts for development.
# Retain metadata but exclude this repository from future builds/deployment sources.
botnexus extensions disable --id reference-extension
botnexus extensions sync
botnexus gateway restart
# Alternatively, remove its registration metadata.
botnexus extensions remove --id reference-extensionDisable/remove does not immediately unload code, delete the managed clone, or delete its staged files. A later deployment pass excludes disabled or removed registrations and can prune their live extension directories. When at least one registration remains (even if all are disabled), maintenance sync runs that deployment pass. If removing the final registration leaves the registry empty, extensions sync and botnexus build perform no deployment work. Host-startup reconciliation used by serve, update and gateway start/restart still refreshes in-tree deployment and prunes stale live output with an empty registry. Restart is required to stop using assemblies already loaded in a running gateway. Delete preserved clone/staging data only as a separate explicit action after checking for local work.
Registration, deployment, loading, extension configuration and an agent's tool grants are separate decisions. Configure values by each manifest id in its declared configuration scopes, and grant the intended tool IDs through the agent's tool configuration. A successful sync does not supply extension secrets, change tool grants, or hot-reload assemblies in the running gateway.
After deployment and gateway restart, verify GET /api/extensions, the intended agent's available tools, and one fresh conversation. Check the persisted reconciliation status and gateway logs when something is missing. A directory on disk proves only that files were copied; a resolved SHA alone does not prove the latest build and deployment succeeded.
Symptom: Extension folder exists but the extension doesn't register.
Checks:
-
Does
<extensions root>/<folder>/botnexus-extension.jsonexist? A directory without a manifest is skipped silently at Debug level — this is the single most common cause. -
Is
enabledtruein the manifest, and is the extension enabled in config by its manifestid?"agents": { "defaults": { "extensions": { "botnexus-discord": { "enabled": true } } } }
-
Does the file named by
entryAssemblyexist in that same folder? A missing entry assembly logs a manifest-validation warning and skips the extension. -
Are the
extensionTypesvalues valid and singular ("tool","channel", not"tools")? An unrecognised value fails validation outright. -
Check the Gateway logs for loading errors:
Skipping '~/.botnexus/extensions/foo' because botnexus-extension.json is missing. Skipping extension in '...' due to manifest or assembly validation failure. Extension 'botnexus-exec' from '...': discovered 1 implementation(s): IAgentTool->ExecTool -
Verify assembly compatibility:
- All extensions must target
net10.0 - Core dependencies must have matching versions
- All extensions must target
Cause: Extension DLLs weren't copied during build.
Fix:
- Ensure
.csprojsetsCopyLocalLockFileAssemblies=true - Ensure
.csprojhas a copy target that also copiesbotnexus-extension.json - Rebuild:
dotnet clean && dotnet build - Verify output:
ls artifacts/extensions/<manifest-id>/
Cause: Extension assembly doesn't have an IExtensionRegistrar implementation and convention-based registration failed (multiple or no implementations of IChannel/ITool).
Fix:
- Create a class implementing
IExtensionRegistrar - Ensure it's public and not abstract
- Rebuild and redeploy
Cause: Extension config is missing from ~/.botnexus/config.json, or is keyed by something other
than the manifest id.
Fix:
{
"gateway": {
"extensions": {
"defaults": {
"botnexus-discord": { "enabled": true, "botToken": "your-token" }
}
}
}
}Symptom: System.Net.Http version 4.3.4 was referenced by two extensions
Cause: Extensions have conflicting transitive dependencies.
Fix:
- Use
AssemblyLoadContextisolation (extensions are already isolated) - Align dependency versions across extensions
- Use
CopyLocalLockFileAssemblies=falseif a shared assembly is available in the runtime
Symptom: IOAuthProvider.HasValidToken is false after some hours.
Fix:
- Implement token refresh logic in
IOAuthProvider.GetAccessTokenAsync() - Check
OAuthToken.IsExpiredbefore use - Persist refresh tokens in
IOAuthTokenStore
Symptom: IWebhookHandler is registered but webhook events aren't arriving.
Checks:
- Is the Gateway listening on the correct port (default 5005)?
- Is the webhook route registered? Check Gateway logs:
Registered webhook handler: /webhooks/slack - Is the external service (Slack, etc.) configured to send to the correct URL?
- Are firewall/network rules blocking the connection?
To create a BotNexus extension:
- Create a class library targeting
net10.0undersrc/extensions/ - Add a
botnexus-extension.jsondeclaringid,name,version,entryAssemblyand singularextensionTypes - Set
CopyLocalLockFileAssemblies=trueand add a copy target that also copies the manifest - Implement the contract for your declared type (
IChannelAdapter,IAgentTool, …; LLM providers are not extensions — see Provider Extensions) - Optionally implement
IExtensionRegistrarfor advanced DI - Add configuration keyed by the manifest
idin~/.botnexus/config.json - Build and the flat extension folder appears in
artifacts/extensions/<manifest-id>/ - Enable in config and the Gateway loads it at startup
Happy extending!
A manifest with configSchema must declare configurationScopes using only world, gateway, and agent. Values are stored independently at world.extensions.<id>, gateway.extensions.<id>, agents.defaults.extensions.<id>, and agents.<agentId>.extensions.<id>. Gateway loader settings live at gateway.extensionLoader; the former gateway.extensions.defaults shape is rejected with migration guidance.
Binding reads one raw scope at a time. Agent consumers may read both agent-default and named-agent bags, but must choose precedence explicitly for each property: named agent first, agent default second, then the code default. World and gateway values never flow into agent configuration implicitly.