Plugin Helpers

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

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

1
export interface ConfigReport {
2
  diagnostics: ConfigDiagnostic[];
3
}

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

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

1
export interface PluginContext {
2
  /** Register an infallible event subscriber for this component. */
3
  registerSubscriber(name: string, callback: (event: Json) => void): void;
4
  /** Register a tool sanitize-request guardrail for this component. */
5
  registerToolSanitizeRequestGuardrail(
6
    name: string,
7
    priority: number,
8
    callback: (name: string, args: Json) => Json,
9
  ): void;
10
  /** Register a tool sanitize-response guardrail for this component. */
11
  registerToolSanitizeResponseGuardrail(
12
    name: string,
13
    priority: number,
14
    callback: (name: string, result: Json) => Json,
15
  ): void;
16
  /** Register a tool conditional-execution guardrail for this component. */
17
  registerToolConditionalExecutionGuardrail(
18
    name: string,
19
    priority: number,
20
    callback: (name: string, args: Json) => string | null,
21
  ): void;
22
  /** Register an LLM sanitize-request guardrail for this component. */
23
  registerLlmSanitizeRequestGuardrail(name: string, priority: number, callback: (request: Json) => Json): void;
24
  /** Register an LLM sanitize-response guardrail for this component. */
25
  registerLlmSanitizeResponseGuardrail(name: string, priority: number, callback: (response: Json) => Json): void;
26
  /** Register an LLM conditional-execution guardrail for this component. */
27
  registerLlmConditionalExecutionGuardrail(
28
    name: string,
29
    priority: number,
30
    callback: (request: Json) => string | null,
31
  ): void;
32
  /** Register an LLM request intercept for this component. */
33
  registerLlmRequestIntercept(
34
    name: string,
35
    priority: number,
36
    breakChain: boolean,
37
    callback: (args: { name: string; request: Json; annotated: Json | null }) => {
38
      request: Json;
39
      annotated: Json | null;
40
    },
41
  ): void;
42
  /** Register an LLM execution intercept for this component. */
43
  registerLlmExecutionIntercept(
44
    name: string,
45
    priority: number,
46
    callback: (request: Json, next: (request: Json) => Json | Promise<Json>) => Json | Promise<Json>,
47
  ): void;
48
  /** Register an LLM streaming execution intercept for this component. */
49
  registerLlmStreamExecutionIntercept(
50
    name: string,
51
    priority: number,
52
    callback: (
53
      request: Json,
54
      next: (request: Json) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
55
    ) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
56
  ): void;
57
  /** Register a tool request intercept for this component. */
58
  registerToolRequestIntercept(
59
    name: string,
60
    priority: number,
61
    breakChain: boolean,
62
    callback: (name: string, args: Json) => Json,
63
  ): void;
64
  /** Register a tool execution intercept for this component. */
65
  registerToolExecutionIntercept(
66
    name: string,
67
    priority: number,
68
    callback: (args: Json, next: (args: Json) => Json | Promise<Json>) => Json | Promise<Json>,
69
  ): void;
70
}

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

1
export declare function defaultConfig(): PluginConfig;

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

1
export declare function validate(config: PluginConfig): ConfigReport;

1
export declare function initialize(config: PluginConfig): Promise<ConfigReport>;

1
export declare function clear(): void;

1
export declare function report(): ConfigReport | null;

1
export declare function listKinds(): string[];

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

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

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