Skip to content

Latest commit

 

History

History
1593 lines (1262 loc) · 63.3 KB

extension-development.md

File metadata and controls

1593 lines (1262 loc) · 63.3 KB

BotNexus Extension Development Guide

Table of Contents

  1. What is a BotNexus Extension?
  2. The botnexus-extension.json manifest
  3. Extension Project Structure & Conventions
  4. Creating a Channel Extension
  5. Provider Extensions
  6. Creating a Tool Extension
  7. Dependency Injection Patterns
  8. Extension Metadata with BotNexusExtensionAttribute
  9. Accessing Configuration
  10. World-Level Extension Defaults
  11. OAuth Providers
  12. Webhook Handlers
  13. Testing Extensions in Isolation
  14. Build Pipeline & Output
  15. Out-of-tree extension repositories
  16. Troubleshooting

What is a BotNexus Extension?

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.json manifest.
  • Extensions are loaded into their own AssemblyLoadContext. Extensions declaring endpoint-contributor or api-contributor are loaded non-collectible (ASP.NET uses Reflection.Emit for typed hub proxies).
  • Discovery is one level deep: <extensions root>/<extension-folder>/botnexus-extension.json.
  • Extension configuration is keyed by manifest id in the concrete scope declared by configurationScopes.

The botnexus-extension.json manifest

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.

Fields

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.

extensionTypes

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 — an IHostedService contributed by a channel extension is registered behind ChannelFaultBarrierHostedService, so a misconfigured channel costs that channel and not the process.
  • endpoint-contributor / api-contributor — force a non-collectible load context.

configSchema

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.

Worked example

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."
    }
  ]
}

Extension Project Structure & Conventions

On-disk layout

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.

Source layout

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.

Project File (.csproj)

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.


Creating a Channel Extension

Channels are messaging platforms where agents receive user messages and send responses. Examples: Discord, Slack, Telegram, SignalR.

Step 1: Create a Class Inheriting BaseChannel

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);
    }
}

Step 2: Define a Configuration Class

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"]
        }
      }
    }
  }
}

Step 3: Create an Extension Registrar (Optional but Recommended)

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));
    }
}

Step 4: Add the manifest, build and deploy

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": "..." }
      }
    }
  }
}

Provider Extensions

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/ — working IApiProvider implementation.
  • src/agent/BotNexus.Agent.Providers.IntegrationMock/ — deterministic test-only provider.

Creating a Tool Extension

Tools are capabilities that agents can invoke to perform actions. Examples: GitHub API wrapper, web search, custom calculations, email sender.

Step 1: Create a Tool Class

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);

Step 2: Tool Configuration Class

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; }
}

Step 3: Extension Registrar

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);
        });
    }
}

Step 4: Manifest and configuration

{
  "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" }
      }
    }
  }
}

Dependency Injection Patterns

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.

Convention-Based Registration (Automatic)

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 IChannel

Limitations:

  • Only works for single implementations
  • No configuration binding
  • No validation
  • No logging

Custom Registration with IExtensionRegistrar (Recommended)

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

Hybrid Approach: Service Extension Methods

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);
}

Extension Metadata with BotNexusExtensionAttribute

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}");

Accessing Configuration

Extensions receive configuration scoped to their own section (from ~/.botnexus/config.json or appsettings.json).

Configuration Binding in IExtensionRegistrar

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;
}

Configuration Shape in config.json

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 } } } }
  }
}

Using IOptions<T> Pattern

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;
    }
}

Agent extension defaults

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.

OAuth Providers

Some LLM providers (like GitHub Copilot) require OAuth instead of API keys. Use IOAuthProvider to implement OAuth flows.

OAuth Interfaces

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);
}

Example: GitHub Device Code Flow (Copilot)

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;
            }
        }
    }
}

File-Based Token Store

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;
    }
}

Webhook Handlers

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.


Testing Extensions in Isolation

Test your extension without the full Gateway by mocking dependencies.

Example: Unit Test for a Tool

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);
    }
}

Example: DI Integration Test

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);
    }
}

Build Pipeline & Output

How the copy target works

Each extension project declares its own AfterTargets="Build" copy target (there is no shared Extension.targets). When you build an extension project:

  1. Compile: normal MSBuild compilation to bin/<Config>/net10.0/, including the transitive managed dependency closure because CopyLocalLockFileAssemblies is true.
  2. Copy: the project's CopyExtensionToArtifacts target copies the entry assembly and the botnexus-extension.json manifest into artifacts/extensions/<manifest-id>/.
  3. Deploy: botnexus serve stages 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 All Extensions

# Build the entire solution (includes all extensions)
dotnet build dirs.proj

Deploying

# Stage extensions into the gateway's extensions root
botnexus serve

# Extensions land in:
# ~/.botnexus/extensions/<manifest-id>/

Out-of-tree extension repositories

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.

Repository layout

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.

Reference the BotNexus checkout

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.

Register the repository

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.

Before you start

  • Install Git and the .NET SDK required by the BotNexus checkout and the extension project. The reconciler invokes git and dotnet on the host and passes the resolved BotNexus checkout as BotNexusRepoRoot to 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.

CLI method

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 restart

extensions 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 restart

UI method

The 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.

Lifecycle, failure and removal

What synchronization does

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.

  1. 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.
  2. Discover and build. Recursively find every .csproj with a botnexus-extension.json in 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 in Release, with BotNexusRepoRoot and a separate output directory inside a candidate generation. No selected projects is a named failure.
  3. 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.
  4. Record the result. Promote the candidate to the repository's staged directory 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.

Failure and last-known-good output

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.

Disable or remove

# 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-extension

Disable/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.

Configure, grant and verify

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.


Troubleshooting

Extension Not Loading

Symptom: Extension folder exists but the extension doesn't register.

Checks:

  1. Does <extensions root>/<folder>/botnexus-extension.json exist? A directory without a manifest is skipped silently at Debug level — this is the single most common cause.

  2. Is enabled true in the manifest, and is the extension enabled in config by its manifest id?

    "agents": { "defaults": { "extensions": { "botnexus-discord": { "enabled": true } } } }
  3. Does the file named by entryAssembly exist in that same folder? A missing entry assembly logs a manifest-validation warning and skips the extension.

  4. Are the extensionTypes values valid and singular ("tool", "channel", not "tools")? An unrecognised value fails validation outright.

  5. 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
    
  6. Verify assembly compatibility:

    • All extensions must target net10.0
    • Core dependencies must have matching versions

"No assemblies found in extension folder"

Cause: Extension DLLs weren't copied during build.

Fix:

  1. Ensure .csproj sets CopyLocalLockFileAssemblies=true
  2. Ensure .csproj has a copy target that also copies botnexus-extension.json
  3. Rebuild: dotnet clean && dotnet build
  4. Verify output: ls artifacts/extensions/<manifest-id>/

"IExtensionRegistrar not found"

Cause: Extension assembly doesn't have an IExtensionRegistrar implementation and convention-based registration failed (multiple or no implementations of IChannel/ITool).

Fix:

  1. Create a class implementing IExtensionRegistrar
  2. Ensure it's public and not abstract
  3. Rebuild and redeploy

"Configuration section not found"

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" }
      }
    }
  }
}

Dependency Version Conflicts

Symptom: System.Net.Http version 4.3.4 was referenced by two extensions

Cause: Extensions have conflicting transitive dependencies.

Fix:

  1. Use AssemblyLoadContext isolation (extensions are already isolated)
  2. Align dependency versions across extensions
  3. Use CopyLocalLockFileAssemblies=false if a shared assembly is available in the runtime

OAuth Token Expiration

Symptom: IOAuthProvider.HasValidToken is false after some hours.

Fix:

  1. Implement token refresh logic in IOAuthProvider.GetAccessTokenAsync()
  2. Check OAuthToken.IsExpired before use
  3. Persist refresh tokens in IOAuthTokenStore

Webhook Not Receiving Events

Symptom: IWebhookHandler is registered but webhook events aren't arriving.

Checks:

  1. Is the Gateway listening on the correct port (default 5005)?
  2. Is the webhook route registered? Check Gateway logs:
    Registered webhook handler: /webhooks/slack
    
  3. Is the external service (Slack, etc.) configured to send to the correct URL?
  4. Are firewall/network rules blocking the connection?

Summary

To create a BotNexus extension:

  1. Create a class library targeting net10.0 under src/extensions/
  2. Add a botnexus-extension.json declaring id, name, version, entryAssembly and singular extensionTypes
  3. Set CopyLocalLockFileAssemblies=true and add a copy target that also copies the manifest
  4. Implement the contract for your declared type (IChannelAdapter, IAgentTool, …; LLM providers are not extensions — see Provider Extensions)
  5. Optionally implement IExtensionRegistrar for advanced DI
  6. Add configuration keyed by the manifest id in ~/.botnexus/config.json
  7. Build and the flat extension folder appears in artifacts/extensions/<manifest-id>/
  8. Enable in config and the Gateway loads it at startup

Happy extending!

Explicit extension configuration scopes

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.