@obora/runtime 0.1.0

package/dist/patterns/builtin/PeerReviewPattern.d.ts

@@ -0,0 +1,40 @@
+import { CollaborationPatternBase, type BuiltinPatternKind, type PatternPayloadResult, type PatternRuntimeContext, type PeerReviewPatternConfig } from "../types.js";
+/**
+ * Peer review pattern contract.
+ *
+ * Quorum
+ * - required reviewers = participants - best_effort
+ * - quorum = all required reviewers responded in the same round
+ * - best_effort reviewers do not block quorum when missing
+ * - if quorum is not met, continue to next round until max_rounds
+ * - when max_rounds is exhausted without quorum, return success:false with reason "quorum_not_met"
+ *
+ * Termination channel
+ * - Return `success:false` (business failure) for:
+ *   - average score < min_score => reason "score_below_threshold"
+ *   - P0 count > p0_allowed => reason "p0_exceeded"
+ *   - quorum not met after max_rounds => reason "quorum_not_met"
+ *   - all business failures include `OboraErrorCode.CONSENSUS_FAIL` in output.error_codes
+ * - Throw for external constraint violations:
+ *   - timeout exceeded (`startedAt` + `config.timeout`) => throws with `OboraErrorCode.CONSENSUS_TIMEOUT`
+ *
+ * best_effort semantics
+ * - `best_effort` is a list of participant IDs
+ * - missing best_effort reviewers are ignored for quorum
+ * - responded best_effort reviews are included in average score, issue aggregation, and P0 checks
+ */
+export declare class PeerReviewPattern extends CollaborationPatternBase {
+    readonly name = "peer-review";
+    readonly kind: BuiltinPatternKind;
+    validateConfig(config: PeerReviewPatternConfig & {
+        timeout?: string;
+    }): void;
+    protected onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+    private buildBusinessFailureResult;
+    private getInput;
+    private resolveRounds;
+    private collectReviews;
+    private buildReport;
+    private hasTimedOut;
+    private resolveNow;
+}

package/dist/patterns/builtin/PipelinePattern.d.ts

@@ -0,0 +1,6 @@
+import { CollaborationPatternBase, type BuiltinPatternKind, type PatternPayloadResult, type PatternRuntimeContext } from "../types.js";
+export declare class PipelinePattern extends CollaborationPatternBase {
+    readonly name = "pipeline";
+    readonly kind: BuiltinPatternKind;
+    protected onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+}

package/dist/patterns/builtin/RedBluePattern.d.ts

@@ -0,0 +1,13 @@
+import { CollaborationPatternBase, type BuiltinPatternKind, type PatternPayloadResult, type PatternRuntimeContext, type RedBluePatternConfig } from "../types.js";
+export declare class RedBluePattern extends CollaborationPatternBase {
+    readonly name = "red-blue";
+    readonly kind: BuiltinPatternKind;
+    validateConfig(config: RedBluePatternConfig): void;
+    protected onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+    private getInput;
+    private resolveRounds;
+    private resolveTeams;
+    private normalizeTeam;
+    private normalizeRecord;
+    private checkConvergence;
+}

package/dist/patterns/builtin/SupervisorPattern.d.ts

@@ -0,0 +1,13 @@
+import { CollaborationPatternBase, type BuiltinPatternKind, type PatternPayloadResult, type PatternRuntimeContext, type SupervisorPatternConfig } from "../types.js";
+export declare class SupervisorPattern extends CollaborationPatternBase {
+    readonly name = "supervisor";
+    readonly kind: BuiltinPatternKind;
+    validateConfig(config: SupervisorPatternConfig): void;
+    protected onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+    private getInput;
+    private normalizeResult;
+    private buildAttemptQueues;
+    private extractAttempts;
+    private shiftAttempt;
+    private computeBackoff;
+}

package/dist/patterns/builtin/discussion/MeetingStateMachine.d.ts

@@ -0,0 +1 @@
+export * from "../../../_legacy/blackboard/workflow/meeting-state-machine/MeetingStateMachine.js";

package/dist/patterns/builtin/discussion/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./MeetingStateMachine.js";
+export * from "./types.js";

package/dist/patterns/builtin/discussion/types.d.ts

@@ -0,0 +1 @@
+export * from "../../../_legacy/blackboard/workflow/meeting-state-machine/types.js";

package/dist/patterns/examples/OxfordDebatePattern.d.ts

@@ -0,0 +1,11 @@
+import { CollaborationPatternBase, type PatternPayloadResult, type PatternRuntimeContext } from "../types.js";
+export declare class OxfordDebatePattern extends CollaborationPatternBase {
+    readonly name = "oxford-debate";
+    readonly kind = "oxford-debate";
+    readonly version = "1.0.0";
+    validateConfig(config: Record<string, unknown>): void;
+    protected onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+    private parseInput;
+    private resolveParticipant;
+    private vote;
+}

package/dist/patterns/examples/index.d.ts

@@ -0,0 +1 @@
+export * from "./OxfordDebatePattern.js";

package/dist/patterns/index.d.ts

@@ -0,0 +1,14 @@
+export * from "./types.js";
+export * from "./PatternRegistry.js";
+export * from "./CustomPatternAPI.js";
+export * from "./resolveCustomPattern.js";
+export * from "./builtin/PipelinePattern.js";
+export * from "./builtin/DiscussionPattern.js";
+export * from "./builtin/ConsensusPattern.js";
+export * from "./builtin/BrainstormPattern.js";
+export * from "./builtin/PeerReviewPattern.js";
+export * from "./builtin/SupervisorPattern.js";
+export * from "./builtin/FanOutFanInPattern.js";
+export * from "./builtin/RedBluePattern.js";
+export * from "./builtin/CompositePattern.js";
+export * from "./builtin/discussion/index.js";

package/dist/patterns/resolveCustomPattern.d.ts

@@ -0,0 +1,22 @@
+import type { PatternRegistry } from "./PatternRegistry.js";
+import type { CollaborationPattern } from "./types.js";
+export interface ResolveCustomPatternOptions {
+    cwd?: string;
+    loadFromFile?: (filePath: string, options?: {
+        cwd?: string;
+    }) => CollaborationPattern | Promise<CollaborationPattern>;
+}
+export declare function resolveCustomPattern(registry: PatternRegistry, patternRef: string, options?: ResolveCustomPatternOptions): CollaborationPattern;
+export declare function resolveCustomPatternAsync(registry: PatternRegistry, patternRef: string, options?: ResolveCustomPatternOptions): Promise<CollaborationPattern>;
+/**
+ * Load a CollaborationPattern from a YAML file.
+ * Reads the file synchronously, parses YAML, and returns the parsed object.
+ */
+export declare function loadPatternFromYamlFile(resolvedPath: string): CollaborationPattern;
+/**
+ * Default file-path based pattern loading for JS/TS modules.
+ * Path is already resolved by the caller.
+ */
+export declare function loadCustomPatternFromFile(filePath: string, options?: {
+    cwd?: string;
+}): CollaborationPattern;

package/dist/patterns/types.d.ts

@@ -0,0 +1,252 @@
+import { OboraErrorCode } from "../errors/OboraErrorCode.js";
+export { OboraErrorCode };
+/**
+ * Core domain patterns. "composite" is a meta-pattern registered separately
+ * because it orchestrates other patterns rather than implementing domain logic.
+ */
+export declare const BUILTIN_PATTERN_KINDS: readonly ["pipeline", "discussion", "consensus", "brainstorming", "peer-review", "red-blue", "fan-out-fan-in", "supervisor"];
+export type BuiltinPatternKind = (typeof BUILTIN_PATTERN_KINDS)[number];
+export type PatternFailureCategory = "failure" | "timeout" | "escalation";
+export interface PatternRuntimeHooks {
+    onStart?(context: PatternRuntimeContext): Promise<void> | void;
+    onEvent?(event: PatternRuntimeEvent, context: PatternRuntimeContext): Promise<void> | void;
+    onComplete?(result: PatternRuntimeResult, context: PatternRuntimeContext): Promise<void> | void;
+    onError?(error: unknown, context: PatternRuntimeContext): Promise<void> | void;
+}
+export type PatternExecutionFn = (context: PatternRuntimeContext) => Promise<PatternRuntimeResult>;
+/**
+ * External runtime contract used by orchestrator/executors.
+ * `run` is the stable entrypoint for runtime integration.
+ */
+export interface PatternRuntimeContract {
+    readonly name: string;
+    readonly kind: BuiltinPatternKind | (string & {});
+    readonly version?: string;
+    validateConfig?(config: PatternConfig): void;
+    run: PatternExecutionFn;
+}
+export interface PatternRuntimeEvent {
+    type: string;
+    payload?: unknown;
+    timestamp?: string;
+}
+export interface PatternPayloadContext {
+    steps?: Array<(input: unknown) => unknown | Promise<unknown>>;
+    input?: unknown;
+    [key: string]: unknown;
+}
+export interface PatternRuntimeContext extends PatternPayloadContext {
+    executionId?: string;
+    stepName?: string;
+    pattern: string;
+    participants?: Record<string, string>;
+    config?: PatternConfig;
+    emit?: (event: PatternRuntimeEvent) => Promise<void> | void;
+    hooks?: PatternRuntimeHooks;
+}
+export interface PatternPayloadResult {
+    success: boolean;
+    output: unknown;
+    metadata?: Record<string, unknown>;
+}
+export interface PatternRuntimeResult extends PatternPayloadResult {
+    pattern: string;
+}
+/**
+ * SCHEMAS SSOT naming uses PatternContext/PatternResult.
+ * Keep these aliases bound to runtime I/O types.
+ */
+export type PatternContext = PatternRuntimeContext;
+export type PatternResult = PatternRuntimeResult;
+export type CustomConvergenceFn = (context: {
+    round: number;
+    opinions: Record<string, string>;
+    participants: string[];
+}) => boolean;
+export type VoterRole = "ai" | "human" | "service";
+export interface VoterRoleConfig {
+    /** Role of this voter. Default: "ai". */
+    role: VoterRole;
+    /** Voter ids assigned this role. */
+    voters: string[];
+}
+export type EscalationTrigger = "timeout" | "quorum_not_met";
+export interface EscalationConfig {
+    /** Which failure conditions trigger escalation instead of plain failure/throw. */
+    triggers: EscalationTrigger[];
+    /** Opaque target identifier for the escalation handler. */
+    target?: string;
+}
+export type CustomEvaluator = (context: {
+    votes: Array<{
+        voterId: string;
+        approved: boolean;
+        score?: number;
+        reason?: string;
+        role?: VoterRole;
+    }>;
+    participants: string[];
+    requiredParticipants: string[];
+    config: ConsensusPatternConfig;
+}) => boolean | {
+    approved: boolean;
+    reason?: string;
+    score?: number;
+};
+export interface DiscussionPatternConfig {
+    max_rounds?: number;
+    convergence?: "no_disagreements" | "majority" | "unanimous" | "custom";
+    on_deadlock?: "escalate" | "retry" | "fail";
+    /** Number of extra retry rounds when on_deadlock='retry'. Default 1. Must be >= 1. */
+    retry_budget?: number;
+    custom_convergence?: CustomConvergenceFn;
+}
+export interface ConsensusPatternConfig {
+    rule?: "majority" | "unanimous" | "weighted" | "score-threshold" | "custom";
+    weights?: Record<string, number>;
+    threshold?: number;
+    timeout?: string;
+    best_effort?: string[];
+    custom_evaluate?: CustomEvaluator;
+    /** Voter role assignments. Voters not listed default to "ai". */
+    voter_roles?: VoterRoleConfig[];
+    /** Escalation integration point for timeout/quorum failures. */
+    escalation?: EscalationConfig;
+}
+export interface BrainstormingPatternConfig {
+    phase_1?: "generate";
+    phase_2?: "evaluate";
+    top_n?: number;
+    dedup?: "semantic" | "exact";
+}
+export interface PeerReviewPatternConfig {
+    min_score?: number;
+    p0_allowed?: number;
+    max_rounds?: number;
+    best_effort?: string[];
+}
+export type RedBlueEscalationTrigger = "max_rounds_exhausted";
+export interface RedBlueEscalationConfig {
+    /** Which failure conditions trigger escalation instead of plain failure. */
+    triggers: RedBlueEscalationTrigger[];
+    /** Opaque target identifier for the escalation handler. */
+    target?: string;
+}
+export interface RedBluePatternConfig {
+    red_team?: string[];
+    blue_team?: string[];
+    max_rounds?: number;
+    convergence?: "red_finds_nothing" | "max_rounds" | "custom";
+    /** Required when convergence='custom'. */
+    custom_convergence?: (payload: {
+        round: number;
+        rounds: Array<{
+            round: number;
+            red_findings: Record<string, unknown>;
+            blue_responses: Record<string, unknown>;
+        }>;
+        current_round: {
+            round: number;
+            red_findings: Record<string, unknown>;
+            blue_responses: Record<string, unknown>;
+        };
+        subject: unknown;
+        red_team: string[];
+        blue_team: string[];
+    }) => boolean;
+    /** Escalation integration point for failure paths. */
+    escalation?: RedBlueEscalationConfig;
+}
+export interface PipelinePatternConfig {
+    stages?: string[];
+}
+/**
+ * failure_policy controls how partial participant failures are handled:
+ * - "best_effort" (default): succeed if at least 1 participant succeeds.
+ * - "required": succeed only if >= min_success participants succeed.
+ *   When min_success is omitted under "required", ALL participants must succeed.
+ *
+ * min_success: minimum number of successful participants for "required" mode.
+ *   Must be >= 1 and <= participant count. Ignored under "best_effort".
+ */
+export interface FanOutFanInPatternConfig {
+    merge?: "concatenate" | "rank" | "vote" | "custom";
+    failure_policy?: "best_effort" | "required";
+    /** Minimum successful participants for "required" mode. Defaults to total participant count. */
+    min_success?: number;
+}
+export interface SupervisorPatternConfig {
+    strategy?: "one_for_one" | "one_for_all";
+    max_restarts?: number;
+    backoff?: "linear" | "exponential";
+}
+export interface CompositeStage {
+    name: string;
+    pattern: string;
+    config?: Record<string, unknown>;
+    participants?: Record<string, string>;
+    input_from?: "previous" | "root" | string;
+}
+export interface CompositePatternConfig {
+    stages: CompositeStage[];
+    on_stage_failure?: "fail" | "skip" | "escalate";
+}
+export interface CustomPatternDefinition {
+    name: string;
+    version?: string;
+    kind?: string;
+    description?: string;
+    execute: (context: PatternRuntimeContext) => Promise<PatternPayloadResult>;
+    validateConfig?: (config: PatternConfig) => void;
+}
+export interface CustomPatternConfig {
+    [key: string]: unknown;
+}
+export type PatternConfig = DiscussionPatternConfig | ConsensusPatternConfig | BrainstormingPatternConfig | PeerReviewPatternConfig | RedBluePatternConfig | PipelinePatternConfig | FanOutFanInPatternConfig | SupervisorPatternConfig | CompositePatternConfig | CustomPatternConfig;
+export type PatternConfigByKind = {
+    discussion: DiscussionPatternConfig;
+    consensus: ConsensusPatternConfig;
+    brainstorming: BrainstormingPatternConfig;
+    "peer-review": PeerReviewPatternConfig;
+    "red-blue": RedBluePatternConfig;
+    pipeline: PipelinePatternConfig;
+    "fan-out-fan-in": FanOutFanInPatternConfig;
+    supervisor: SupervisorPatternConfig;
+    composite: CompositePatternConfig;
+};
+export type PatternYamlStep<K extends keyof PatternConfigByKind = keyof PatternConfigByKind> = {
+    pattern: K;
+    config?: PatternConfigByKind[K];
+};
+export type BlackboardDomain = "agenda" | "meeting-state-machine" | "message-bus" | "consensus-rule-engine" | "voting-session-store" | "knowledge" | "decision" | "state" | "actor-pool" | "supervisor" | "supervisor-tree";
+export type PatternBlackboardDomainMapping = Record<keyof PatternConfigByKind, readonly BlackboardDomain[]>;
+export declare const PATTERN_BLACKBOARD_DOMAIN_MAP: PatternBlackboardDomainMapping;
+export declare const PATTERN_ERROR_CODE_MAP: Record<keyof PatternConfigByKind, Record<PatternFailureCategory, OboraErrorCode>>;
+export declare function isBuiltinPatternKind(value: string): value is BuiltinPatternKind;
+/**
+ * Internal pattern implementation contract.
+ * - `run`: external runtime entrypoint (called by orchestrator/executors)
+ * - `execute`: internal compatibility entrypoint (delegates to `run`)
+ * External callers should always use `run`.
+ */
+export interface CollaborationPattern extends PatternRuntimeContract {
+    execute: PatternExecutionFn;
+}
+export declare abstract class CollaborationPatternBase implements CollaborationPattern {
+    abstract readonly name: string;
+    abstract readonly kind: BuiltinPatternKind | (string & {});
+    readonly version = "1.0.0";
+    validateConfig(_config: PatternConfig): void;
+    /**
+     * Internal compatibility entrypoint; delegates to `run`.
+     */
+    execute(context: PatternRuntimeContext): Promise<PatternRuntimeResult>;
+    /**
+     * External runtime entrypoint used by orchestrator.
+     * Error channel contract:
+     * - throw: unrecoverable external constraint violations (timeout/policy/etc), handled by upper recovery.
+     * - return { success: false }: expected business-level failure (e.g., quorum not met / rejected).
+     */
+    run(context: PatternRuntimeContext): Promise<PatternRuntimeResult>;
+    protected abstract onExecute(context: PatternRuntimeContext): Promise<PatternPayloadResult>;
+}

package/dist/plugins/PluginLoader.d.ts

@@ -0,0 +1,16 @@
+import type { AnyPlugin } from "./types.js";
+import { PluginRegistry } from "./PluginRegistry.js";
+export declare class PluginLoader {
+    private readonly registry;
+    private readonly loaded;
+    constructor(registry: PluginRegistry);
+    load(plugin: AnyPlugin, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    loadFromModule(modulePath: string, exportName?: string, options?: {
+        replace?: boolean;
+    }): Promise<void>;
+    unload(name: string): Promise<void>;
+    unloadAll(): Promise<void>;
+    listLoaded(): string[];
+}

package/dist/plugins/PluginRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { AnyPlugin, OboraPlugin, PluginType } from "./types.js";
+export interface RegisterOptions {
+    replace?: boolean;
+}
+export declare class PluginRegistry {
+    private readonly byName;
+    private readonly byType;
+    register(plugin: AnyPlugin, options?: RegisterOptions): Promise<void>;
+    registerAll(plugins: readonly AnyPlugin[], options?: RegisterOptions): Promise<void>;
+    unregister(name: string): Promise<void>;
+    get<T extends OboraPlugin>(type: PluginType, name: string): T;
+    has(type: PluginType, name: string): boolean;
+    list(type?: PluginType): OboraPlugin[];
+    clear(): Promise<void>;
+}

package/dist/plugins/builtins.d.ts

@@ -0,0 +1,137 @@
+import type { AuditEvent, AuditFilter } from "../audit/types.js";
+import { PipelinePattern } from "../patterns/builtin/PipelinePattern.js";
+import { DiscussionPattern } from "../patterns/builtin/DiscussionPattern.js";
+import { ConsensusPattern } from "../patterns/builtin/ConsensusPattern.js";
+import { BrainstormPattern } from "../patterns/builtin/BrainstormPattern.js";
+import { PeerReviewPattern } from "../patterns/builtin/PeerReviewPattern.js";
+import { SupervisorPattern } from "../patterns/builtin/SupervisorPattern.js";
+import { FanOutFanInPattern } from "../patterns/builtin/FanOutFanInPattern.js";
+import { RedBluePattern } from "../patterns/builtin/RedBluePattern.js";
+import { CompositePattern } from "../patterns/builtin/CompositePattern.js";
+import type { PatternRegistry } from "../patterns/PatternRegistry.js";
+import type { AgentPlugin, AnyPlugin, AuditStorePlugin, ConsensusRulePlugin, PatternPlugin, PolicyRulePlugin, RecoveryStrategyPlugin, StateTransformPlugin, ToolPlugin } from "./types.js";
+import type { PluginRegistry } from "./PluginRegistry.js";
+export declare class BuiltinAgentPlugin implements AgentPlugin {
+    readonly type: "agent";
+    readonly name = "builtin-agent";
+    readonly version = "1.0.0";
+    createAgent(config: unknown): unknown;
+}
+export declare class FileWriteToolPlugin implements ToolPlugin {
+    private readonly sandboxRoot;
+    readonly type: "tool";
+    readonly name = "file-write";
+    readonly version = "1.0.0";
+    readonly schema: {
+        type: string;
+        required: string[];
+        properties: {
+            path: {
+                type: string;
+            };
+            content: {
+                type: string;
+            };
+        };
+    };
+    constructor(sandboxRoot?: string);
+    execute(params: unknown): Promise<{
+        path: string;
+        bytes: number;
+    }>;
+}
+export declare class PipelinePatternPlugin extends PipelinePattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "pipeline";
+    readonly version = "1.0.0";
+}
+export declare class DiscussionPatternPlugin extends DiscussionPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "discussion";
+    readonly version = "1.0.0";
+}
+export declare class ConsensusPatternPlugin extends ConsensusPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "consensus";
+    readonly version = "1.0.0";
+}
+export declare class BrainstormPatternPlugin extends BrainstormPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "brainstorming";
+    readonly version = "1.0.0";
+}
+export declare class PeerReviewPatternPlugin extends PeerReviewPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "peer-review";
+    readonly version = "1.0.0";
+}
+export declare class SupervisorPatternPlugin extends SupervisorPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "supervisor";
+    readonly version = "1.0.0";
+}
+export declare class FanOutFanInPatternPlugin extends FanOutFanInPattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "fan-out-fan-in";
+    readonly version = "1.0.0";
+}
+export declare class RedBluePatternPlugin extends RedBluePattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "red-blue";
+    readonly version = "1.0.0";
+}
+export declare class CompositePatternPlugin extends CompositePattern implements PatternPlugin {
+    readonly type: "pattern";
+    readonly name = "composite";
+    readonly version = "1.0.0";
+    constructor(registry: PatternRegistry);
+}
+export declare class AllowAllPolicyRulePlugin implements PolicyRulePlugin {
+    readonly type: "policy-rule";
+    readonly name = "allow-all-policy";
+    readonly version = "1.0.0";
+    evaluate(): {
+        type: "allow";
+    };
+}
+export declare class RetryRecoveryStrategyPlugin implements RecoveryStrategyPlugin {
+    readonly type: "recovery-strategy";
+    readonly name = "retry-recovery";
+    readonly version = "1.0.0";
+    handle(): Promise<{
+        status: "recovered";
+    }>;
+}
+export declare class MajorityConsensusRulePlugin implements ConsensusRulePlugin {
+    readonly type: "consensus-rule";
+    readonly name = "majority-consensus";
+    readonly version = "1.0.0";
+    evaluate(votes: unknown[]): {
+        status: "pass" | "fail";
+        approved: number;
+        total: number;
+    };
+}
+export declare class InMemoryAuditStorePlugin implements AuditStorePlugin {
+    readonly type: "audit-store";
+    readonly name = "in-memory-audit-store";
+    readonly version = "1.0.0";
+    private readonly store;
+    record(event: AuditEvent): Promise<void>;
+    query(filter: AuditFilter): Promise<AuditEvent[]>;
+}
+export declare class IdentityStateTransformPlugin implements StateTransformPlugin {
+    readonly type: "state-transform";
+    readonly name = "identity-transform";
+    readonly version = "1.0.0";
+    transform(value: unknown): unknown;
+}
+export declare function createBuiltinPlugins(options?: {
+    sandboxRoot?: string;
+    patternRegistry?: PatternRegistry;
+}): AnyPlugin[];
+export declare function registerBuiltinPlugins(registry: PluginRegistry, options?: {
+    sandboxRoot?: string;
+    replace?: boolean;
+    patternRegistry?: PatternRegistry;
+}): Promise<void>;

package/dist/plugins/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./types.js";
+export * from "./validator.js";
+export * from "./PluginRegistry.js";
+export * from "./PluginLoader.js";
+export * from "./builtins.js";

package/dist/plugins/types.d.ts

@@ -0,0 +1,52 @@
+import type { AuditEvent, AuditFilter } from "../audit/types.js";
+import type { PatternRuntimeContract, PatternRuntimeContext, PatternRuntimeResult } from "../patterns/types.js";
+export type PluginType = "agent" | "tool" | "pattern" | "policy-rule" | "recovery-strategy" | "consensus-rule" | "audit-store" | "state-transform";
+export interface OboraPlugin {
+    name: string;
+    version: string;
+    type: PluginType;
+    onLoad?(): Promise<void>;
+    onUnload?(): Promise<void>;
+}
+export interface AgentPlugin extends OboraPlugin {
+    type: "agent";
+    createAgent(config: unknown): unknown;
+}
+export interface ToolPlugin extends OboraPlugin {
+    type: "tool";
+    schema: Record<string, unknown>;
+    execute(params: unknown, context: unknown): Promise<unknown>;
+}
+export interface PatternPlugin extends OboraPlugin, PatternRuntimeContract {
+    type: "pattern";
+    /** Explicitly restated for pattern plugin contract readability. */
+    name: string;
+    version: string;
+    execute(context: PatternRuntimeContext): Promise<PatternRuntimeResult>;
+}
+export interface PolicyRulePlugin extends OboraPlugin {
+    type: "policy-rule";
+    evaluate(action: unknown, context: unknown): unknown;
+}
+export interface RecoveryStrategyPlugin extends OboraPlugin {
+    type: "recovery-strategy";
+    handle(failure: unknown): Promise<unknown>;
+}
+export interface ConsensusRulePlugin extends OboraPlugin {
+    type: "consensus-rule";
+    evaluate(votes: unknown[]): unknown;
+}
+export interface AuditStorePlugin extends OboraPlugin {
+    type: "audit-store";
+    record(event: AuditEvent): Promise<void>;
+    query(filter: AuditFilter): Promise<AuditEvent[]>;
+}
+export interface StateTransformPlugin extends OboraPlugin {
+    type: "state-transform";
+    transform(value: unknown): unknown;
+}
+export type AnyPlugin = AgentPlugin | ToolPlugin | PatternPlugin | PolicyRulePlugin | RecoveryStrategyPlugin | ConsensusRulePlugin | AuditStorePlugin | StateTransformPlugin;
+export interface PluginValidationResult {
+    valid: boolean;
+    errors: string[];
+}

package/dist/plugins/validator.d.ts

@@ -0,0 +1,3 @@
+import type { AnyPlugin, PluginValidationResult } from "./types.js";
+export declare function validatePlugin(plugin: unknown): PluginValidationResult;
+export declare function assertValidPlugin(plugin: unknown): asserts plugin is AnyPlugin;