ReferenceAPIsNode.js Library Reference

Plugin Helpers

View as Markdown

Generated from crates/node/plugin.d.ts.

Import from nemo-relay-node/plugin.

Plugin configuration, validation, activation, and registration helpers.

Interfaces

ConfigPolicy

Plugin-level policy for unknown or unsupported plugin configuration.

export interface ConfigPolicy {
  unknown_component?: UnsupportedBehavior;
  unknown_field?: UnsupportedBehavior;
  unsupported_value?: UnsupportedBehavior;
}

ConfigDiagnostic

One validation or compatibility diagnostic produced by the plugin system.

export interface ConfigDiagnostic {
  level: 'warning' | 'error';
  code: string;
  component?: string;
  field?: string;
  message: string;
}

ConfigReport

Validation or activation report for a plugin configuration.

export interface ConfigReport {
  diagnostics: ConfigDiagnostic[];
  runtime_diagnostics?: RuntimeDiagnostic[];
}

RuntimeDiagnostic

One bounded aggregate of a runtime plugin failure.

export interface RuntimeDiagnostic {
  code: string;
  component: string;
  field?: string;
  message: string;
  session_id?: string;
  count: number;
}

ComponentSpec interface

One top-level plugin component.

export interface ComponentSpec {
  kind: string;
  enabled?: boolean;
  config?: Record<string, Json>;
}

PluginConfig

Canonical plugin configuration document.

export interface PluginConfig {
  version?: number;
  components?: Array<{
    kind: string;
    enabled?: boolean;
    config?: Record<string, Json>;
  }>;
  policy?: ConfigPolicy;
}

PluginHostActivation

export interface PluginHostActivation extends AsyncDisposable {
  /** Validation report produced by the successful activation. */
  readonly report: PluginHostReport;
  /** Whether this activation remains open. Failed teardown can be retried. */
  readonly isActive: boolean;
  /** Clear callbacks before unloading libraries and workers. Idempotent. */
  close(): Promise<void>;
  /** Delegate structured `await using` cleanup to `close()`. */
  [Symbol.asyncDispose](): Promise<void>;
}

PluginHostReport

export interface PluginHostReport {
  config: ConfigReport;
  dynamic_plugins: DynamicPluginValidationReport[];
  /** Existing plugins.toml files that contributed to the resolved configuration. */
  config_paths: string[];
  /** Fully merged plugin configuration with sensitive values redacted. */
  resolved_config: Json;
}

DynamicPluginValidationStatus

export interface DynamicPluginValidationStatus {
  manifest: DynamicPluginCheckState;
  compatibility: DynamicPluginCheckState;
  integrity: DynamicPluginCheckState;
  environment: DynamicPluginCheckState;
  authenticity: DynamicPluginCheckState;
  policy_satisfied: DynamicPluginCheckState;
  checked_at?: string | null;
  message?: string | null;
}

DynamicPluginFailure

export interface DynamicPluginFailure {
  phase: string;
  code: string;
  message: string;
}

DynamicPluginValidationReport

export interface DynamicPluginValidationReport {
  plugin_id: string;
  manifest_ref: string;
  kind: DynamicPluginKind;
  status: DynamicPluginValidationStatus;
  failure?: DynamicPluginFailure | null;
  selected: boolean;
}

ToolExecutionInterceptOutcome

Canonical result returned by a tool execution intercept.

result is passed to the remaining middleware and application. pendingMarks are Relay-owned lifecycle metadata emitted after the tool-end event and are not included in the application-visible result.

export interface ToolExecutionInterceptOutcome {
  result: Json;
  annotation?: Json;
  pendingMarks?: PendingMarkSpec[];
}

PluginContext

Component-scoped registration context passed to plugin handlers.

export interface PluginContext {
  /** Register an activation-owned eligibility gate for a global runtime registration. */
  registerConditionalMiddlewareGuardrail(
    name: string,
    kinds: RuntimeRegistrationKind[],
    registrationName: string,
    guardrail: (kinds: RuntimeRegistrationKind[], registrationName: string) => string | null,
  ): void;
  /**
   * Register an event subscriber for this component. Callback failures are isolated and reported
   * through the Node binding's callback-error channel; flushSubscribers waits for returned promises.
   */
  registerSubscriber(name: string, callback: (event: Json) => void | Promise<void>): void;
  /** Register an event metadata injector for this component. */
  registerEventMetadataInjector(
    name: string,
    priority: number,
    callback: (event: Json) => EventMetadata | Promise<EventMetadata>,
  ): void;
  /** Register a mark event sanitizer for this component. */
  registerMarkSanitizeGuardrail(
    name: string,
    priority: number,
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
  ): void;
  /** Register a scope-start event sanitizer for this component. */
  registerScopeSanitizeStartGuardrail(
    name: string,
    priority: number,
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
  ): void;
  /** Register a scope-end event sanitizer for this component. */
  registerScopeSanitizeEndGuardrail(
    name: string,
    priority: number,
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
  ): void;
  /** Register a tool sanitize-request guardrail for this component. */
  registerToolSanitizeRequestGuardrail(
    name: string,
    priority: number,
    callback: (name: string, args: Json) => Json | Promise<Json>,
  ): void;
  /** Register a tool sanitize-response guardrail for this component. */
  registerToolSanitizeResponseGuardrail(
    name: string,
    priority: number,
    callback: (name: string, result: Json) => Json | Promise<Json>,
  ): void;
  /** Register a tool conditional-execution guardrail for this component. */
  registerToolConditionalExecutionGuardrail(
    name: string,
    priority: number,
    callback: (name: string, args: Json) => string | null | Promise<string | null>,
  ): void;
  /** Register an LLM sanitize-request guardrail. The callback receives `(request, context)`. */
  registerLlmSanitizeRequestGuardrail(
    name: string,
    priority: number,
    callback: (request: Json, context: LlmSanitizeRequestContext) => Json | null | Promise<Json | null>,
  ): void;
  /** Register an LLM sanitize-response guardrail. The callback receives `(response, context)`. */
  registerLlmSanitizeResponseGuardrail(
    name: string,
    priority: number,
    callback: (response: Json, context: LlmSanitizeResponseContext) => Json | null | Promise<Json | null>,
  ): void;
  /** Register an LLM conditional-execution guardrail for this component. */
  registerLlmConditionalExecutionGuardrail(
    name: string,
    priority: number,
    callback: (request: Json) => string | null | Promise<string | null>,
  ): void;
  /** Register an LLM request intercept for this component. */
  registerLlmRequestIntercept(
    name: string,
    priority: number,
    breakChain: boolean,
    callback: (args: {
      name: string;
      request: Json;
      annotated: Json | null;
    }) => LlmRequestInterceptOutcome | Promise<LlmRequestInterceptOutcome>,
  ): void;
  /** Register an LLM execution intercept for this component. */
  registerLlmExecutionIntercept(
    name: string,
    priority: number,
    callback: (
      request: Json,
      context: LlmExecutionContext,
      next: (request: Json) => Json | Promise<Json>,
    ) => Json | Promise<Json>,
  ): void;
  /**
   * Register an LLM streaming execution intercept for this component.
   *
   * The `next` callback resolves to a lazy stream. Return that stream to
   * preserve incremental downstream delivery.
   */
  registerLlmStreamExecutionIntercept(
    name: string,
    priority: number,
    callback: (
      request: Json,
      context: LlmExecutionContext,
      next: (request: Json) => Promise<AsyncIterable<Json>>,
    ) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
  ): void;
  /** Register a tool request intercept for this component. */
  registerToolRequestIntercept(
    name: string,
    priority: number,
    breakChain: boolean,
    callback: (name: string, args: Json) => Json | Promise<Json>,
  ): void;
  /**
   * Register tool execution middleware that returns a canonical outcome.
   * The `next` callback resolves to the canonical downstream result.
   */
  registerToolExecutionIntercept(
    name: string,
    priority: number,
    callback: (
      context: ToolExecutionContext,
      next: (args: Json) => ToolExecutionResult | Promise<ToolExecutionResult>,
    ) => ToolExecutionInterceptOutcome | Promise<ToolExecutionInterceptOutcome>,
  ): void;
}

Plugin

Plugin callback contract.

export interface Plugin {
  /** Validate one component-local config object. */
  validate?(pluginConfig: Record<string, Json>): ConfigDiagnostic[] | null | undefined;
  /**
   * Install middleware and subscribers for one component instance.
   *
   * Throwing aborts the current initialization and triggers rollback.
   */
  register(pluginConfig: Record<string, Json>, context: PluginContext): void;
}

Functions

defaultConfig

Create an empty plugin configuration.

Returns the canonical top-level config shape with version = 1 and no configured components so callers can build a document incrementally before validating or activating it.

Returns

A new PluginConfig object ready for mutation or validation.

Remarks

Mutating the returned object does not affect runtime state until it is passed to initialize.

export declare function defaultConfig(): PluginConfig;

ComponentSpec function

Create a plugin component entry for a plugin config document.

Packages a plugin kind, component-local config, and enablement flag into the object shape expected by PluginConfig.components.

Parameters

  • kind: Registered plugin kind to reference.
  • config: Component-local config passed to plugin hooks.
  • options: Optional component-level flags.

Returns

A ComponentSpec ready to insert into a plugin config.

Remarks

Setting options.enabled = false preserves the component for validation while skipping runtime registration during initialize.

export declare function ComponentSpec(
  kind: string,
  config?: Record<string, Json>,
  options?: {
    enabled?: boolean;

initialize

Initialize the core-owned static and dynamic plugin host.

Resolves an explicit or discovered user file with the system configuration, then applies programmatic config and activates one owned lifetime.

Parameters

  • config: Programmatic configuration. It overrides file values.
  • additionalPluginsToml: Optional explicit plugins.toml layer. A missing explicit file is reported as a plugin.configuration_file_missing warning in the host report.

Returns

An owned activation with the unified host report.

Remarks

Keep the returned activation alive while callbacks may run and call close() or use await using for deterministic teardown.

export declare function initialize(config: PluginConfig, additionalPluginsToml?: string): Promise<PluginHostActivation>;

validate

Validate the plugin host without loading plugin code.

Resolves the same layered configuration and trust policy used by activation while leaving the process-wide host lease untouched.

Parameters

  • config: Programmatic configuration. It overrides file values.
  • additionalPluginsToml: Optional explicit plugins.toml layer. A missing explicit file is reported as a plugin.configuration_file_missing warning in the host report.

Returns

Structured static and dynamic validation report.

Remarks

Validation performs no activation and does not acquire the host lease.

export declare function validate(config: PluginConfig, additionalPluginsToml?: string): PluginHostReport;

validateExact

Validate only the supplied static plugin configuration.

Unlike validate, this does not discover or merge plugins.toml files. Use it for component-specific validation when config is the complete document to check.

Parameters

  • config: Complete static plugin configuration.

Returns

Static validation results with no dynamic plugins.

export declare function validateExact(config: PluginConfig): PluginHostReport;

listKinds

List registered plugin kinds.

Returns the plugin kind identifiers currently known to the global registry so callers can inspect what can be referenced from plugin configs.

Returns

The registered plugin kind names.

Remarks

The list reflects registry state only; it does not indicate whether a plugin kind is currently active in the runtime configuration.

export declare function listKinds(): string[];

register

Register a plugin kind with JavaScript validation and registration hooks.

Adapts the higher-level Plugin object contract to the native callback shape expected by the Node binding.

Parameters

  • pluginKind: Unique plugin kind identifier to register.
  • plugin: Plugin implementation with validate and register hooks.

Returns

Nothing.

Remarks

Omitting plugin.validate makes the plugin permissive during validation; plugin.register still runs later during initialize.

export declare function register(pluginKind: string, plugin: Plugin): void;

deregister

Remove a previously registered plugin kind.

Deletes the plugin kind from the registry so future config validation and initialization calls can no longer reference it.

Parameters

  • pluginKind: Registered plugin kind identifier to remove.

Returns

true when a plugin kind was removed, otherwise false.

Remarks

Active runtime registrations remain until the owning plugin-host activation closes.

export declare function deregister(pluginKind: string): boolean;

Type Aliases

UnsupportedBehavior

Policy behavior for unsupported configuration.

export type UnsupportedBehavior = 'ignore' | 'warn' | 'error';

DynamicPluginKind

Execution lane for a dynamically loaded Relay plugin.

export type DynamicPluginKind = 'rust_dynamic' | 'worker';

DynamicPluginCheckState

export type DynamicPluginCheckState = 'unknown' | 'valid' | 'invalid';