Plugin System

Plugin System

AgentCTX’s plugin system lets you extend the platform with custom middleware, emitters, plane handlers, and tool adapters. Plugins are audited before activation to ensure they don’t compromise security.

Plugin Structure

my-plugin/
├── actx-plugin.yaml        # Plugin manifest
├── src/
│   ├── middleware.ts        # Custom gateway middleware
│   ├── emitter.ts           # Custom sidecar emitter
│   └── handler.ts           # Custom plane handler
└── tests/
    └── plugin.test.ts       # Plugin tests

Plugin Manifest

name: my-plugin
version: 1.0.0
description: Custom integration for internal API
author: your-team

# What the plugin provides
provides:
  middleware: src/middleware.ts
  emitter:
    target: internal-api
    module: src/emitter.ts

# Required permissions
permissions:
  planes: [tools, knowledge]
  network: [api.internal.com]
  filesystem: [read]

# Scope constraints
scopes:
  backends: [internal-*]
  roles: [admin, dev]

Auditing Plugins

Before activating a plugin, audit it with static analysis:

actx audit ./my-plugin/

This checks:

• Scope boundaries — does it access only declared planes/backends?
• Permission alignment — do declared permissions match actual imports?
• Security patterns — no eval, no dynamic require, no unsafe operations
• Dependency audit — checks for known vulnerabilities

Marketplace

The marketplace provides discovery and distribution for plugins:

?i marketplace #plugins ^10      Search for available plugins
+i marketplace register="..."    Register a plugin

Plugins go through:

1. Static audit — automated code analysis
2. Scope verification — declared vs actual permissions
3. Signature — Ed25519 signed by the publisher
4. Review — community or enterprise review process

Custom Middleware

Extend the gateway pipeline with custom middleware:

import type { RequestContext, NextFunction } from '@agentctx/core';

export async function rateLimitMiddleware(
  ctx: RequestContext,
  next: NextFunction
) {
  const key = `${ctx.identity.agentId}:${ctx.statement.plane}`;
  if (await isRateLimited(key)) {
    return { ok: false, code: 'RATE_LIMITED', error: 'Too many requests' };
  }
  return next(ctx);
}

See Also

• Gateway & Routing — middleware pipeline
• Custom Emitters — sidecar extension