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 DynamicPluginActivationSpec {
2
  pluginId: string;
3
  kind: DynamicPluginKind;
4
  manifestRef: string;
5
  environmentRef?: string | null;
6
  config?: Record<string, Json>;
7
}

1
export interface DynamicPluginActivation extends AsyncDisposable {
2
  /** Validation report produced by the successful activation. */
3
  readonly report: ConfigReport;
4
  /**
5
   * Whether this activation handle has not begun teardown. `false` does not
6
   * guarantee another process-wide activation can start after failed teardown.
7
   */
8
  readonly active: boolean;
9
  /** Clear callbacks before unloading libraries and workers. Idempotent. */
10
  close(): Promise<void>;
11
  /** Delegate structured `await using` cleanup to `close()`. */
12
  [Symbol.asyncDispose](): Promise<void>;
13
}

1
export interface PendingMarkSpec {
2
  name: string;
3
  category?: string | null;
4
  categoryProfile?: Json;
5
  data?: Json;
6
  metadata?: Json;
7
}

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

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

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

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

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

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

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

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

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 mark event sanitizer for this component. */
5
  registerMarkSanitizeGuardrail(
6
    name: string,
7
    priority: number,
8
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields,
9
  ): void;
10
  /** Register a scope-start event sanitizer for this component. */
11
  registerScopeSanitizeStartGuardrail(
12
    name: string,
13
    priority: number,
14
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields,
15
  ): void;
16
  /** Register a scope-end event sanitizer for this component. */
17
  registerScopeSanitizeEndGuardrail(
18
    name: string,
19
    priority: number,
20
    callback: (event: Json, fields: EventSanitizeFields) => EventSanitizeFields,
21
  ): void;
22
  /** Register a tool sanitize-request guardrail for this component. */
23
  registerToolSanitizeRequestGuardrail(
24
    name: string,
25
    priority: number,
26
    callback: (name: string, args: Json) => Json,
27
  ): void;
28
  /** Register a tool sanitize-response guardrail for this component. */
29
  registerToolSanitizeResponseGuardrail(
30
    name: string,
31
    priority: number,
32
    callback: (name: string, result: Json) => Json,
33
  ): void;
34
  /** Register a tool conditional-execution guardrail for this component. */
35
  registerToolConditionalExecutionGuardrail(
36
    name: string,
37
    priority: number,
38
    callback: (name: string, args: Json) => string | null,
39
  ): void;
40
  /** Register an LLM sanitize-request guardrail for this component. */
41
  registerLlmSanitizeRequestGuardrail(name: string, priority: number, callback: (request: Json) => Json): void;
42
  /** Register an LLM sanitize-response guardrail for this component. */
43
  registerLlmSanitizeResponseGuardrail(name: string, priority: number, callback: (response: Json) => Json): void;
44
  /** Register an LLM conditional-execution guardrail for this component. */
45
  registerLlmConditionalExecutionGuardrail(
46
    name: string,
47
    priority: number,
48
    callback: (request: Json) => string | null,
49
  ): void;
50
  /** Register an LLM request intercept for this component. */
51
  registerLlmRequestIntercept(
52
    name: string,
53
    priority: number,
54
    breakChain: boolean,
55
    callback: (args: { name: string; request: Json; annotated: Json | null }) => LlmRequestInterceptOutcome,
56
  ): void;
57
  /** Register an LLM execution intercept for this component. */
58
  registerLlmExecutionIntercept(
59
    name: string,
60
    priority: number,
61
    callback: (request: Json, next: (request: Json) => Json | Promise<Json>) => Json | Promise<Json>,
62
  ): void;
63
  /** Register an LLM streaming execution intercept for this component. */
64
  registerLlmStreamExecutionIntercept(
65
    name: string,
66
    priority: number,
67
    callback: (
68
      request: Json,
69
      next: (request: Json) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
70
    ) => AsyncIterable<Json> | Promise<AsyncIterable<Json>>,
71
  ): void;
72
  /** Register a tool request intercept for this component. */
73
  registerToolRequestIntercept(
74
    name: string,
75
    priority: number,
76
    breakChain: boolean,
77
    callback: (name: string, args: Json) => Json,
78
  ): void;
79
  /**
80
   * Register tool execution middleware that returns a canonical outcome.
81
   * The `next` callback resolves to the raw downstream result.
82
   */
83
  registerToolExecutionIntercept(
84
    name: string,
85
    priority: number,
86
    callback: (
87
      args: Json,
88
      next: (args: Json) => Json | Promise<Json>,
89
    ) => ToolExecutionInterceptOutcome | Promise<ToolExecutionInterceptOutcome>,
90
  ): void;
91
}

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 initializeWithDynamicPlugins(
2
  config: PluginConfig,
3
  specs: DynamicPluginActivationSpec[],
4
): Promise<DynamicPluginActivation>;

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';

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