@animalabs/agent-framework 0.1.0

package/src/gate/types.ts

@@ -0,0 +1,112 @@
+/**
+ * EventGate type definitions.
+ *
+ * The EventGate is a core framework component that evaluates incoming events
+ * against declarative policies to decide whether they should trigger inference.
+ * Policies are read from a `gate.json` file with hot-reload support.
+ */
+
+// ---------------------------------------------------------------------------
+// Gate behaviors
+// ---------------------------------------------------------------------------
+
+/** How a matching policy affects inference triggering. */
+export type GateBehavior =
+  | 'always'    // Trigger inference immediately
+  | 'skip'      // Don't trigger inference (event still enters context)
+  | { debounce: number };  // Batch events per-policy, deliver after delay (ms)
+
+// ---------------------------------------------------------------------------
+// Policy match criteria
+// ---------------------------------------------------------------------------
+
+/** Criteria for matching an event. All specified fields must match (AND logic). */
+export interface GatePolicyMatch {
+  /** Event types to match (exact). Empty/omitted = all. */
+  scope?: string[];
+  /** ServerId to match (exact or glob with *). */
+  source?: string;
+  /** ChannelId to match (exact or glob with *). */
+  channel?: string;
+  /** Content text filter. */
+  filter?: { type: 'text' | 'regex'; pattern: string };
+}
+
+// ---------------------------------------------------------------------------
+// Policy
+// ---------------------------------------------------------------------------
+
+/** A single gate policy — one rule in the ordered policy list. */
+export interface GatePolicy {
+  name: string;
+  match: GatePolicyMatch;
+  behavior: GateBehavior;
+}
+
+// ---------------------------------------------------------------------------
+// Config (persisted as gate.json)
+// ---------------------------------------------------------------------------
+
+/** Top-level gate configuration, stored in gate.json. */
+export interface GateConfig {
+  policies: GatePolicy[];
+  /** Behavior when no policy matches. Default: 'always'. */
+  default?: 'always' | 'skip';
+}
+
+// ---------------------------------------------------------------------------
+// FrameworkConfig-facing options
+// ---------------------------------------------------------------------------
+
+/** Options for configuring the EventGate via FrameworkConfig. */
+export interface GateOptions {
+  /** Path to gate.json. Default: derived from storePath. */
+  configPath?: string;
+  /** Initial config, seeded to gate.json if the file doesn't exist. */
+  config?: GateConfig;
+}
+
+// ---------------------------------------------------------------------------
+// Runtime types (internal to EventGate, exported for tests/tools)
+// ---------------------------------------------------------------------------
+
+/** The result of evaluating an event against the gate. */
+export interface GateDecision {
+  /** Whether to trigger inference. */
+  trigger: boolean;
+  /** Name of the matching policy (null if default applied). */
+  policyName: string | null;
+  /** The behavior that was applied. */
+  behavior: GateBehavior;
+}
+
+/** Information about an event being evaluated. */
+export interface GateEventInfo {
+  content: string;
+  eventType: string;
+  serverId: string;
+  channelId: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Per-policy runtime statistics (for gate:status). */
+export interface GatePolicyStats {
+  name: string;
+  behavior: GateBehavior;
+  matchCount: number;
+  lastMatchTimestamp: number | null;
+  debounceState?: {
+    pendingCount: number;
+    nextDeliveryMs: number | null;
+  };
+}
+
+/** Full gate status returned by gate:status tool. */
+export interface GateStatus {
+  configPath: string;
+  configSource: 'file' | 'initial' | 'default';
+  lastReloadTimestamp: number | null;
+  default: 'always' | 'skip';
+  policies: GatePolicyStats[];
+  errors: string[];
+}

package/src/index.ts

@@ -0,0 +1,63 @@
+// Types
+export * from './types/index.js';
+
+// Core classes
+export { AgentFramework } from './framework.js';
+export { Agent } from './agent.js';
+export type { StartStreamResult } from './agent.js';
+export { ProcessQueueImpl } from './queue.js';
+export { ModuleRegistry } from './module-registry.js';
+
+// Built-in modules
+export * from './modules/index.js';
+
+// API
+export { ApiServer } from './api/server.js';
+export { McpServer } from './api/mcp-server.js';
+export type {
+  ApiServerConfig,
+  ApiMessage,
+  ApiRequest,
+  ApiResponse,
+  ApiEvent,
+  ApiCommand,
+  MessageSendParams,
+  MessageListParams,
+  InferenceRequestParams,
+  InferenceAbortParams,
+  BranchCreateParams,
+  BranchSwitchParams,
+  BranchDeleteParams,
+  AgentContextParams,
+  ModuleStateParams,
+  StoreInspectParams,
+  MessageInfo,
+  BranchInfo,
+  ModuleInfo,
+  StateInfo,
+  ApiEventType,
+  InferenceStartEvent,
+  InferenceCompleteEvent,
+  InferenceAbortedEvent,
+  InferenceErrorEvent,
+  ToolStartEvent,
+  ToolCompleteEvent,
+  ToolErrorEvent,
+  SpeechEvent,
+  MessageAddedEvent,
+  BranchSwitchedEvent,
+  BranchCreatedEvent,
+  BranchDeletedEvent,
+} from './api/types.js';
+// Note: AgentInfo, MessageEditedEvent, MessageRemovedEvent intentionally not re-exported
+// from api/types.js to avoid conflicts with ./types/index.js
+
+// EventGate
+export { EventGate } from './gate/index.js';
+export type { GateConfig, GateOptions, GatePolicy, GatePolicyMatch, GateBehavior } from './gate/index.js';
+
+// Re-export commonly used types from dependencies
+export type { ContextManager, ContextStrategy, TokenBudget } from '@animalabs/context-manager';
+export { PassthroughStrategy, AutobiographicalStrategy, KnowledgeStrategy } from '@animalabs/context-manager';
+export type { KnowledgeConfig, PhaseType } from '@animalabs/context-manager';
+export type { Membrane, NormalizedMessage, NormalizedRequest, ContentBlock } from '@animalabs/membrane';