Table of Contents

IAgentPlugin

Last updated:

IAgentPlugin is the entry point Oscova instantiates after a plugin manifest and assembly pass validation. Its job is deliberately small: register contributions with AgentPluginBuilder.

Note

An entry point is the public class named by entryType in oscova-plugin.json.

Contract

using Oscova.Agents.Plugins;

namespace Example.Hello;

public sealed class MyAgentPlugin : IAgentPlugin
{
    public void Configure(AgentPluginBuilder builder)
    {
        builder.AddToolset(context => new MyToolset(context.UserTimeZone));
    }
}

IAgentPlugin declares one method:

void Configure(AgentPluginBuilder builder);

The entry class must be public and have a public parameterless constructor. For each successful load, the loader creates a new entry instance and a new AgentPluginBuilder, calls Configure once, and snapshots the declared contributions only if the call succeeds.

Lifecycle

  1. Oscova inspects manifests without loading plugin assemblies.
  2. At startup, the saved activation list selects which valid plugins may load.
  3. The loader resolves the assembly and entryType, verifies IAgentPlugin, and creates the entry instance.
  4. The loader calls Configure and snapshots the builder's toolset and provider factories.
  5. Provider factories run once during startup with one shared AgentPluginContext per plugin. Toolset factories run later with one separate context per plugin and user scope.
  6. Loaded plugins and their assembly load contexts remain active for the host process lifetime.

Enabling, disabling, or replacing a plugin takes effect only after the administrator saves the next-startup selection and restarts the host. There is no hot unload or reload.

Configure registrations only

Use Configure to call the public registration methods on AgentPluginBuilder:

  • AddToolset<TToolset>(Func<AgentPluginContext, TToolset>) registers a non-null factory for a class that implements ICrewToolset.
  • AddModelProvider<TProvider>(Func<AgentPluginContext, TProvider>) registers a non-null factory for a class that implements IModelProvider.
  • AddSpeechRecognitionProvider<TProvider>(Func<AgentPluginContext, TProvider>) registers a non-null factory for a class that implements ISpeechRecognitionProvider.
  • AddSpeechSynthesisProvider<TProvider>(Func<AgentPluginContext, TProvider>) registers a non-null factory for a class that implements ISpeechSynthesisProvider.

Each method returns the same builder so registrations can be chained. Every registration method throws ArgumentNullException when its factory is null.

Configure is synchronous and has no cancellation token. Contribution factories are also synchronous. Keep both paths deterministic and inexpensive:

  • do not call remote APIs.
  • do not resolve user credentials.
  • do not block on asynchronous work.
  • do not start background work.
  • do not retain the builder as mutable runtime state.

Perform setup that depends on a user when the toolset factory receives AgentPluginContext. Provider factories may use CreateHttpClient, LoggerFactory, and the Host-tracked download operation, but their resolver does not expose user credentials. Perform cancellable asynchronous work inside the later tool or provider operation when its contract supports cancellation. Provider operations receive selected API keys through their existing parameters.

Caution

Plugins are trusted in-process assemblies. IAgentPlugin is not a sandbox boundary, so install only assemblies you trust to run inside the host process.

Failure behavior

Plugin discovery and loading are failure-isolated:

  • an invalid manifest is reported without loading its assembly.
  • a missing entry type, incompatible entry type, constructor failure, or Configure exception records an error diagnostic and skips the plugin.
  • one failed plugin does not prevent other valid enabled plugins from loading.
  • a toolset-factory exception skips that contribution for the affected user while the plugin and its other contributions remain available.
  • a provider-activation failure omits that provider while other providers continue loading.

Normal user-configuration problems, such as a missing API key, should not make Configure fail. Resolve credentials for the user scope and return actionable guidance from the operation that needs them.

Loader diagnostics can include exception messages and can be shown to administrators. Do not put credentials, tokens, or other secrets in exceptions thrown by the entry constructor or Configure.

Troubleshooting

The entry type is rejected

Verify that the manifest uses the fully qualified type name, the type is public, it implements the same compatible Oscova.Agents.Plugins.IAgentPlugin contract as the host, and it has a public parameterless constructor.

Configure fails

Move remote calls, credential resolution, and user-dependent setup out of Configure. The loader reports the exception as a plugin load diagnostic and does not publish partial registrations from that plugin.

A toolset is absent for one user

Check runtime logs for the toolset factory failure. Validate only the inputs used to construct that user's contribution. Do not move the failing setup back into Configure, because that would prevent the whole plugin from loading.

A change is not visible

Restart the host after changing activation or plugin files. A successful load is fixed for that process lifetime.