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

LlmSanitizeRequestContext

Codec context available while an LLM request is sanitized.

1export interface LlmSanitizeRequestContext {
2  codec: LlmCodecIdentity;
3  /** Resolve the active codec for this callback. Do not retain the result after the callback returns. */
4  resolveCodec(): LlmCodec | null;
5}

LlmSanitizeResponseContext

Codec context available while an LLM response is sanitized.

1export interface LlmSanitizeResponseContext {
2  codec: LlmCodecIdentity;
3  /** Resolve the active codec for this callback. Do not retain the result after the callback returns. */
4  resolveCodec(): LlmResponseCodec | null;
5}

ConfigPolicy

Plugin-level policy for unknown or unsupported plugin configuration.

1export interface ConfigPolicy {
2  unknown_component?: UnsupportedBehavior;
3  unknown_field?: UnsupportedBehavior;
4  unsupported_value?: UnsupportedBehavior;
5}

ConfigDiagnostic

One validation or compatibility diagnostic produced by the plugin system.

1export interface ConfigDiagnostic {
2  level: 'warning' | 'error';
3  code: string;
4  component?: string;
5  field?: string;
6  message: string;
7}

ConfigReport

Validation or activation report for a plugin configuration.

1export interface ConfigReport {
2  diagnostics: ConfigDiagnostic[];
3  runtime_diagnostics?: RuntimeDiagnostic[];
4}

RuntimeDiagnostic

One bounded aggregate of a runtime plugin failure.

1export interface RuntimeDiagnostic {
2  code: string;
3  component: string;
4  field?: string;
5  message: string;
6  session_id?: string;
7  count: number;
8}

ComponentSpec interface

One top-level plugin component.

1export interface ComponentSpec {
2  kind: string;
3  enabled?: boolean;
4  config?: Record<string, Json>;
5}

PluginConfig

Canonical plugin configuration document.

1export interface PluginConfig {
2  version?: number;
3  components?: Array<{
4    kind: string;
5    enabled?: boolean;
6    config?: Record<string, Json>;
7  }>;
8  policy?: ConfigPolicy;
9}

PluginHostActivation

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

PluginHostReport

1export interface PluginHostReport {
2  config: ConfigReport;
3  dynamic_plugins: DynamicPluginValidationReport[];
4}

DynamicPluginValidationStatus

1export interface DynamicPluginValidationStatus {
2  manifest: DynamicPluginCheckState;
3  compatibility: DynamicPluginCheckState;
4  integrity: DynamicPluginCheckState;
5  environment: DynamicPluginCheckState;
6  authenticity: DynamicPluginCheckState;
7  policy_satisfied: DynamicPluginCheckState;
8  checked_at?: string | null;
9  message?: string | null;
10}

DynamicPluginFailure

1export interface DynamicPluginFailure {
2  phase: string;
3  code: string;
4  message: string;
5}

DynamicPluginValidationReport

1export interface DynamicPluginValidationReport {
2  plugin_id: string;
3  manifest_ref: string;
4  kind: DynamicPluginKind;
5  status: DynamicPluginValidationStatus;
6  failure?: DynamicPluginFailure | null;
7  selected: boolean;
8}

PendingMarkSpec

A mark Relay materializes under a managed lifecycle.

1export interface PendingMarkSpec {
2  name: string;
3  category?: string | null;
4  categoryProfile?: Json;
5  data?: Json;
6  dataSchema?: { name: string; version: string } | null;
7  metadata?: Json;
8  severity?: 'trace' | 'debug' | 'info' | 'warn' | 'warning' | 'error' | null;
9}

LlmOptimizationDataSchema

Schema tag attached to an opaque optimization contribution payload.

1export interface LlmOptimizationDataSchema {
2  name: string;
3  version: string;
4}

LlmOptimizationModel

Model identity retained for counterfactual pricing and downstream repricing.

1export interface LlmOptimizationModel {
2  model: string;
3  provider?: string;
4}

LlmOptimizationModelTransition

Baseline and effective model identities for a routing optimization.

1export interface LlmOptimizationModelTransition {
2  baseline?: LlmOptimizationModel;
3  effective?: LlmOptimizationModel;
4}

LlmOptimizationTokens

Explicit token evidence, independent from a pricing catalog.

1export interface LlmOptimizationTokens {
2  /** Token counts must be non-negative JavaScript safe integers. */
3  prompt_tokens?: number;
4  /** Token counts must be non-negative JavaScript safe integers. */
5  completion_tokens?: number;
6  /** Token counts must be non-negative JavaScript safe integers. */
7  cache_read_tokens?: number;
8  /** Token counts must be non-negative JavaScript safe integers. */
9  cache_write_tokens?: number;
10  /** Token counts must be non-negative JavaScript safe integers. */
11  total_tokens?: number;
12}

LlmOptimizationTokenImpact

Baseline, effective, and saved token evidence for one optimization.

1export interface LlmOptimizationTokenImpact {
2  baseline?: LlmOptimizationTokens;
3  effective?: LlmOptimizationTokens;
4  saved?: LlmOptimizationTokens;
5  quality?: 'observed' | 'estimated';
6  estimation_method?: string;
7}

LlmOptimizationContribution

One plugin’s optimization evidence.

kind is deliberately an open string so new optimizer categories round-trip without a Relay release. Unknown top-level fields are retained by the wire contract and represented by this interface’s JSON extension surface.

1export interface LlmOptimizationContribution {
2  id?: string;
3  /** Relay ordering must remain within JavaScript's safe-integer range. */
4  sequence?: number;
5  producer: string;
6  kind: 'input_compression' | 'model_routing' | (string & {});
7  applied: boolean;
8  model_transition?: LlmOptimizationModelTransition;
9  token_impact?: LlmOptimizationTokenImpact;
10  payload_schema?: LlmOptimizationDataSchema;
11  payload?: Json;
12  [key: string]: Json | undefined;
13}

LlmRequestInterceptOutcome

Canonical result returned by an LLM request intercept.

1export interface LlmRequestInterceptOutcome {
2  request: Json;
3  annotated?: Json | null;
4  pendingMarks?: PendingMarkSpec[];
5  optimizationContributions?: LlmOptimizationContribution[];
6}

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.

1export interface ToolExecutionInterceptOutcome {
2  result: Json;
3  annotation?: Json;
4  pendingMarks?: PendingMarkSpec[];
5}

PluginContext

Component-scoped registration context passed to plugin handlers.

1export interface PluginContext {
2  /** Register an activation-owned eligibility gate for a global runtime registration. */
3  registerConditionalMiddlewareGuardrail(
4    name: string,
5    kinds: RuntimeRegistrationKind[],
6    registrationName: string,
7    guardrail: (kinds: RuntimeRegistrationKind[], registrationName: string) => string | null,
8  ): void;
9  /**
10   * Register an event subscriber for this component. Callback failures are isolated and reported
11   * through the Node binding's callback-error channel; flushSubscribers waits for returned promises.
12   */
13  registerSubscriber(name: string, callback: (event: Json) => void | Promise<void>): void;
14  /** Register an event metadata injector for this component. */
15  registerEventMetadataInjector(
16    name: string,
17    priority: number,
18    callback: (event: Json) => EventMetadata | Promise<EventMetadata>,
19  ): void;
20  /** Register a mark event sanitizer for this component. */
21  registerMarkSanitizeGuardrail(
22    name: string,
23    priority: number,
24    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
25  ): void;
26  /** Register a scope-start event sanitizer for this component. */
27  registerScopeSanitizeStartGuardrail(
28    name: string,
29    priority: number,
30    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
31  ): void;
32  /** Register a scope-end event sanitizer for this component. */
33  registerScopeSanitizeEndGuardrail(
34    name: string,
35    priority: number,
36    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields | Promise<EventSanitizeFields>,
37  ): void;
38  /** Register a tool sanitize-request guardrail for this component. */
39  registerToolSanitizeRequestGuardrail(
40    name: string,
41    priority: number,
42    callback: (name: string, args: Json) => Json | Promise<Json>,
43  ): void;
44  /** Register a tool sanitize-response guardrail for this component. */
45  registerToolSanitizeResponseGuardrail(
46    name: string,
47    priority: number,
48    callback: (name: string, result: Json) => Json | Promise<Json>,
49  ): void;
50  /** Register a tool conditional-execution guardrail for this component. */
51  registerToolConditionalExecutionGuardrail(
52    name: string,
53    priority: number,
54    callback: (name: string, args: Json) => string | null | Promise<string | null>,
55  ): void;
56  /** Register an LLM sanitize-request guardrail. The callback receives `(request, context)`. */
57  registerLlmSanitizeRequestGuardrail(
58    name: string,
59    priority: number,
60    callback: (request: Json, context: LlmSanitizeRequestContext) => Json | null | Promise<Json | null>,
61  ): void;
62  /** Register an LLM sanitize-response guardrail. The callback receives `(response, context)`. */
63  registerLlmSanitizeResponseGuardrail(
64    name: string,
65    priority: number,
66    callback: (response: Json, context: LlmSanitizeResponseContext) => Json | null | Promise<Json | null>,
67  ): void;
68  /** Register an LLM conditional-execution guardrail for this component. */
69  registerLlmConditionalExecutionGuardrail(
70    name: string,
71    priority: number,
72    callback: (request: Json) => string | null | Promise<string | null>,
73  ): void;
74  /** Register an LLM request intercept for this component. */
75  registerLlmRequestIntercept(
76    name: string,
77    priority: number,
78    breakChain: boolean,
79    callback: (args: {
80      name: string;
81      request: Json;
82      annotated: Json | null;
83    }) => LlmRequestInterceptOutcome | Promise<LlmRequestInterceptOutcome>,
84  ): void;
85  /** Register an LLM execution intercept for this component. */
86  registerLlmExecutionIntercept(
87    name: string,
88    priority: number,
89    callback: (request: Json, next: (request: Json) => Json | Promise<Json>) => Json | Promise<Json>,
90  ): void;
91  /**
92   * Register an LLM streaming execution intercept for this component.
93   *
94   * The `next` callback resolves to a lazy stream. Return that stream to
95   * preserve incremental downstream delivery.
96   */
97  registerLlmStreamExecutionIntercept(
98    name: string,
99    priority: number,
100    callback: (
101      request: Json,
102      next: (request: Json) => Promise<AsyncIterable<Json>>,
103    ) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
104  ): void;
105  /** Register a tool request intercept for this component. */
106  registerToolRequestIntercept(
107    name: string,
108    priority: number,
109    breakChain: boolean,
110    callback: (name: string, args: Json) => Json | Promise<Json>,
111  ): void;
112  /**
113   * Register tool execution middleware that returns a canonical outcome.
114   * The `next` callback resolves to the canonical downstream result.
115   */
116  registerToolExecutionIntercept(
117    name: string,
118    priority: number,
119    callback: (
120      args: Json,
121      next: (args: Json) => ToolExecutionResult | Promise<ToolExecutionResult>,
122    ) => ToolExecutionInterceptOutcome | Promise<ToolExecutionInterceptOutcome>,
123  ): void;
124}

Plugin

Plugin callback contract.

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

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.

1export 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.

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

initialize

Initialize the core-owned static and dynamic plugin host.

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

Parameters

  • config: Lowest-precedence programmatic configuration.
  • additionalPluginsToml: Optional explicit plugins.toml layer.

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.

1export 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: Lowest-precedence programmatic configuration.
  • additionalPluginsToml: Optional explicit plugins.toml layer.

Returns

Structured static and dynamic validation report.

Remarks

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

1export 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.

1export 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.

1export 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.

1export 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.

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

Type Aliases

LlmCodecIdentity

Codec identity available while a managed LLM event is sanitized.

1export type LlmCodecIdentity =
2  | { kind: 'none' }
3  | {
4      kind: 'builtin';

UnsupportedBehavior

Policy behavior for unsupported configuration.

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

DynamicPluginKind

Execution lane for a dynamically loaded Relay plugin.

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

DynamicPluginCheckState

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

EventMetadataScalar

Scalar value accepted in event metadata additions.

1export type EventMetadataScalar = string | number | boolean;

EventMetadataValue

Flat value accepted in event metadata additions. After JSON conversion, numeric arrays must contain only integer values or only floating-point values.

1export type EventMetadataValue = EventMetadataScalar | string[] | number[] | boolean[];

EventMetadata

Metadata additions returned by an event metadata injector.

1export type EventMetadata = Record<string, EventMetadataValue>;