@feltdb/core 0.2.0

package/dist/agent-registry.js

@@ -0,0 +1,134 @@
+/**
+ * Agent Registry
+ *
+ * Similar to PeerRegistry and CapabilityLocationRegistry.
+ * Maps AgentRef to Agent definition, available providers, and compatible state.
+ */
+/**
+ * Registry for agent definitions and discovery
+ */
+export class AgentRegistry {
+    constructor() {
+        this.agents = new Map();
+    }
+    /**
+     * Register an agent definition
+     */
+    register(agentRef, definition) {
+        const key = agentRef.toString();
+        const entry = {
+            agentRef,
+            definition,
+            providers: [],
+            compatibleStateVersions: [],
+            registeredAt: Date.now(),
+            updatedAt: Date.now(),
+            active: true,
+        };
+        this.agents.set(key, entry);
+    }
+    /**
+     * Unregister an agent
+     */
+    unregister(agentRef) {
+        const key = agentRef.toString();
+        this.agents.delete(key);
+    }
+    /**
+     * Get an agent registration entry
+     */
+    get(agentRef) {
+        const key = agentRef.toString();
+        return this.agents.get(key);
+    }
+    /**
+     * Get agent by name (returns latest version)
+     */
+    getByName(name) {
+        let latest;
+        for (const entry of this.agents.values()) {
+            if (entry.definition.name === name) {
+                if (!latest || entry.agentRef.version > latest.agentRef.version) {
+                    latest = entry;
+                }
+            }
+        }
+        return latest;
+    }
+    /**
+     * Get all registered agents
+     */
+    getAll() {
+        return Array.from(this.agents.values());
+    }
+    /**
+     * Add a provider for an agent
+     */
+    addProvider(agentRef, provider) {
+        const key = agentRef.toString();
+        const entry = this.agents.get(key);
+        if (!entry) {
+            throw new Error(`Agent not registered: ${key}`);
+        }
+        // Remove existing provider from same peer if any
+        entry.providers = entry.providers.filter(p => p.peerId !== provider.peerId);
+        // Add new provider
+        entry.providers.push(provider);
+        entry.updatedAt = Date.now();
+    }
+    /**
+     * Remove a provider
+     */
+    removeProvider(agentRef, peerId) {
+        const key = agentRef.toString();
+        const entry = this.agents.get(key);
+        if (!entry) {
+            throw new Error(`Agent not registered: ${key}`);
+        }
+        entry.providers = entry.providers.filter(p => p.peerId !== peerId);
+        entry.updatedAt = Date.now();
+    }
+    /**
+     * Get available providers for an agent
+     */
+    getAvailableProviders(agentRef) {
+        const entry = this.get(agentRef);
+        if (!entry) {
+            return [];
+        }
+        return entry.providers.filter(p => p.available);
+    }
+    /**
+     * Find agents by capability
+     */
+    findByCapability(capability) {
+        const result = [];
+        for (const entry of this.agents.values()) {
+            if (entry.definition.capabilities.includes(capability)) {
+                result.push(entry);
+            }
+        }
+        return result;
+    }
+    /**
+     * Update agent availability
+     */
+    updateAvailability(agentRef, peerId, available) {
+        const entry = this.get(agentRef);
+        if (!entry) {
+            throw new Error(`Agent not registered: ${agentRef.toString()}`);
+        }
+        const provider = entry.providers.find(p => p.peerId === peerId);
+        if (provider) {
+            provider.available = available;
+            provider.lastHeartbeat = Date.now();
+            entry.updatedAt = Date.now();
+        }
+    }
+    /**
+     * Clear all registrations
+     */
+    clear() {
+        this.agents.clear();
+    }
+}

package/dist/agent-runtime.d.ts

@@ -0,0 +1,147 @@
+/**
+ * Agent Runtime
+ *
+ * Manages agent lifecycle, execution, ownership, and recovery.
+ * Agents run on the distributed fabric as durable participants.
+ */
+import type { StateFirstDB } from './db.js';
+import type { AgentRef, AgentDefinition, AgentExecution } from './agent.js';
+import { AgentExecutionStatus } from './agent.js';
+import type { AgentObservation, ObservationTrigger } from './agent-observation.js';
+import type { AgentDecision } from './agent-decision.js';
+import type { AgentRegistry } from './agent-registry.js';
+/**
+ * Agent runtime context for execution
+ */
+export interface AgentRuntimeContext {
+    /** The database instance */
+    db: StateFirstDB;
+    /** The executing agent's definition */
+    agentDefinition: AgentDefinition;
+    /** The current execution */
+    execution: AgentExecution;
+    /** Observations made so far */
+    observations: AgentObservation[];
+    /** Decisions made so far */
+    decisions: AgentDecision[];
+}
+/**
+ * Agent runtime handler function
+ * Called when agent needs to make decisions
+ */
+export type AgentHandler = (context: AgentRuntimeContext) => Promise<AgentDecision | null>;
+/**
+ * Agent runtime configuration
+ */
+export interface AgentRuntimeConfig {
+    /** Whether to persist agent state */
+    persistent: boolean;
+    /** Maximum execution time in milliseconds */
+    executionTimeoutMs: number;
+    /** Whether to support reactive triggers */
+    supportsReactiveTriggers: boolean;
+    /** Default retry policy */
+    defaultRetryPolicy?: {
+        maxAttempts: number;
+        backoffMs: number;
+    };
+}
+/**
+ * Agent execution result
+ */
+export interface AgentExecutionResult {
+    /** The execution that completed */
+    execution: AgentExecution;
+    /** Final status */
+    status: AgentExecutionStatus;
+    /** Result reference if successful */
+    resultRef?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/**
+ * Agent ownership manager for distributed execution
+ */
+export declare class AgentOwnershipManager {
+    private ownership;
+    private locks;
+    /**
+     * Claim ownership of an execution
+     */
+    claim(executionId: string, peerId: string, ttlMs: number): boolean;
+    /**
+     * Release ownership
+     */
+    release(executionId: string, peerId: string): void;
+    /**
+     * Get current owner
+     */
+    getOwner(executionId: string): string | undefined;
+    /**
+     * Check if ownership is still valid
+     */
+    isValid(executionId: string): boolean;
+    /**
+     * Renew ownership lock
+     */
+    renew(executionId: string, peerId: string, ttlMs: number): boolean;
+}
+/**
+ * Agent Runtime
+ *
+ * Manages agent lifecycle and execution across the distributed fabric.
+ */
+export declare class AgentRuntime {
+    private config;
+    private registry;
+    private handlers;
+    private executions;
+    private ownership;
+    private triggers;
+    constructor(registry: AgentRegistry, config: AgentRuntimeConfig);
+    /**
+     * Register an agent handler
+     */
+    registerHandler(agentName: string, handler: AgentHandler): void;
+    /**
+     * Create a new agent execution
+     */
+    createExecution(db: StateFirstDB, agentRef: AgentRef, goal: string, inputs: string[]): Promise<AgentExecution>;
+    /**
+     * Start an agent execution
+     */
+    start(execution: AgentExecution, peerId: string): Promise<AgentExecutionResult>;
+    /**
+     * Resume an execution from durable state
+     */
+    resume(execution: AgentExecution, peerId: string): Promise<AgentExecutionResult>;
+    /**
+     * Transition execution to next state
+     */
+    transition(execution: AgentExecution, nextStatus: AgentExecutionStatus): Promise<void>;
+    /**
+     * Complete an execution
+     */
+    complete(execution: AgentExecution, resultRef: string): Promise<void>;
+    /**
+     * Fail an execution
+     */
+    fail(execution: AgentExecution, error: string): Promise<void>;
+    /**
+     * Get execution by ID
+     */
+    getExecution(executionId: string): AgentExecution | undefined;
+    /**
+     * Get current owner of an execution
+     */
+    getOwner(executionId: string): string | undefined;
+    /**
+     * Register observation triggers for reactive execution
+     */
+    registerTriggers(agentName: string, triggers: ObservationTrigger[]): void;
+    /**
+     * Get triggers for an agent
+     */
+    getTriggers(agentName: string): ObservationTrigger[];
+}
+//# sourceMappingURL=agent-runtime.d.ts.map

package/dist/agent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runtime.d.ts","sourceRoot":"","sources":["../src/agent-runtime.ts"],"names":[],"mappings":"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"}

package/dist/agent-runtime.js

@@ -0,0 +1,240 @@
+/**
+ * Agent Runtime
+ *
+ * Manages agent lifecycle, execution, ownership, and recovery.
+ * Agents run on the distributed fabric as durable participants.
+ */
+import { AgentExecutionStatus, generateExecutionId } from './agent.js';
+/**
+ * Agent ownership manager for distributed execution
+ */
+export class AgentOwnershipManager {
+    constructor() {
+        this.ownership = new Map(); // executionId -> peerId
+        this.locks = new Map();
+    }
+    /**
+     * Claim ownership of an execution
+     */
+    claim(executionId, peerId, ttlMs) {
+        const existing = this.ownership.get(executionId);
+        // Already owned by this peer
+        if (existing === peerId) {
+            return true;
+        }
+        // Already owned by another peer
+        if (existing) {
+            return false;
+        }
+        // Check if lock is still valid
+        const lock = this.locks.get(executionId);
+        if (lock && lock.expiresAt > Date.now()) {
+            return false;
+        }
+        // Claim ownership
+        this.ownership.set(executionId, peerId);
+        this.locks.set(executionId, {
+            peerId,
+            expiresAt: Date.now() + ttlMs,
+        });
+        return true;
+    }
+    /**
+     * Release ownership
+     */
+    release(executionId, peerId) {
+        const owner = this.ownership.get(executionId);
+        if (owner === peerId) {
+            this.ownership.delete(executionId);
+            this.locks.delete(executionId);
+        }
+    }
+    /**
+     * Get current owner
+     */
+    getOwner(executionId) {
+        return this.ownership.get(executionId);
+    }
+    /**
+     * Check if ownership is still valid
+     */
+    isValid(executionId) {
+        const lock = this.locks.get(executionId);
+        if (!lock) {
+            return false;
+        }
+        return lock.expiresAt > Date.now();
+    }
+    /**
+     * Renew ownership lock
+     */
+    renew(executionId, peerId, ttlMs) {
+        const owner = this.ownership.get(executionId);
+        if (owner !== peerId) {
+            return false;
+        }
+        this.locks.set(executionId, {
+            peerId,
+            expiresAt: Date.now() + ttlMs,
+        });
+        return true;
+    }
+}
+/**
+ * Agent Runtime
+ *
+ * Manages agent lifecycle and execution across the distributed fabric.
+ */
+export class AgentRuntime {
+    constructor(registry, config) {
+        this.handlers = new Map();
+        this.executions = new Map();
+        this.triggers = new Map();
+        this.registry = registry;
+        this.config = config;
+        this.ownership = new AgentOwnershipManager();
+    }
+    /**
+     * Register an agent handler
+     */
+    registerHandler(agentName, handler) {
+        this.handlers.set(agentName, handler);
+    }
+    /**
+     * Create a new agent execution
+     */
+    async createExecution(db, agentRef, goal, inputs) {
+        const executionId = generateExecutionId(agentRef.name);
+        const execution = {
+            executionId,
+            agentRef,
+            status: AgentExecutionStatus.Created,
+            goal,
+            inputs,
+            stateVersion: 0,
+            observationIds: [],
+            decisionIds: [],
+            actionIds: [],
+            attempt: 1,
+            createdMs: Date.now(),
+        };
+        this.executions.set(executionId, execution);
+        return execution;
+    }
+    /**
+     * Start an agent execution
+     */
+    async start(execution, peerId) {
+        // Claim ownership
+        const claimed = this.ownership.claim(execution.executionId, peerId, 30000);
+        if (!claimed) {
+            throw new Error(`Failed to claim ownership of execution ${execution.executionId}`);
+        }
+        try {
+            execution.status = AgentExecutionStatus.Planning;
+            execution.ownedBy = peerId;
+            execution.startedMs = Date.now();
+            return {
+                execution,
+                status: AgentExecutionStatus.Planning,
+                resultRef: undefined,
+            };
+        }
+        catch (error) {
+            execution.status = AgentExecutionStatus.Failed;
+            execution.error = String(error);
+            execution.completedMs = Date.now();
+            return {
+                execution,
+                status: AgentExecutionStatus.Failed,
+                error: String(error),
+            };
+        }
+    }
+    /**
+     * Resume an execution from durable state
+     */
+    async resume(execution, peerId) {
+        // Try to claim ownership (new peer)
+        const claimed = this.ownership.claim(execution.executionId, peerId, 30000);
+        if (!claimed && this.ownership.getOwner(execution.executionId) !== peerId) {
+            throw new Error(`Cannot resume execution ${execution.executionId}: owned by ${this.ownership.getOwner(execution.executionId)}`);
+        }
+        execution.ownedBy = peerId;
+        execution.status = AgentExecutionStatus.Observing;
+        return {
+            execution,
+            status: AgentExecutionStatus.Observing,
+        };
+    }
+    /**
+     * Transition execution to next state
+     */
+    async transition(execution, nextStatus) {
+        const validTransitions = {
+            [AgentExecutionStatus.Created]: [AgentExecutionStatus.Planning],
+            [AgentExecutionStatus.Planning]: [AgentExecutionStatus.Observing],
+            [AgentExecutionStatus.Observing]: [AgentExecutionStatus.Deciding, AgentExecutionStatus.Waiting],
+            [AgentExecutionStatus.Deciding]: [AgentExecutionStatus.Acting],
+            [AgentExecutionStatus.Acting]: [AgentExecutionStatus.Observing, AgentExecutionStatus.Waiting, AgentExecutionStatus.Completed],
+            [AgentExecutionStatus.Waiting]: [AgentExecutionStatus.Observing, AgentExecutionStatus.Blocked],
+            [AgentExecutionStatus.Completed]: [],
+            [AgentExecutionStatus.Failed]: [],
+            [AgentExecutionStatus.Cancelled]: [],
+            [AgentExecutionStatus.Blocked]: [AgentExecutionStatus.Observing],
+        };
+        const allowed = validTransitions[execution.status] || [];
+        if (!allowed.includes(nextStatus)) {
+            throw new Error(`Invalid transition from ${execution.status} to ${nextStatus}`);
+        }
+        execution.status = nextStatus;
+    }
+    /**
+     * Complete an execution
+     */
+    async complete(execution, resultRef) {
+        execution.status = AgentExecutionStatus.Completed;
+        execution.resultRef = resultRef;
+        execution.completedMs = Date.now();
+        // Release ownership
+        if (execution.ownedBy) {
+            this.ownership.release(execution.executionId, execution.ownedBy);
+        }
+    }
+    /**
+     * Fail an execution
+     */
+    async fail(execution, error) {
+        execution.status = AgentExecutionStatus.Failed;
+        execution.error = error;
+        execution.completedMs = Date.now();
+        // Release ownership
+        if (execution.ownedBy) {
+            this.ownership.release(execution.executionId, execution.ownedBy);
+        }
+    }
+    /**
+     * Get execution by ID
+     */
+    getExecution(executionId) {
+        return this.executions.get(executionId);
+    }
+    /**
+     * Get current owner of an execution
+     */
+    getOwner(executionId) {
+        return this.ownership.getOwner(executionId);
+    }
+    /**
+     * Register observation triggers for reactive execution
+     */
+    registerTriggers(agentName, triggers) {
+        this.triggers.set(agentName, triggers);
+    }
+    /**
+     * Get triggers for an agent
+     */
+    getTriggers(agentName) {
+        return this.triggers.get(agentName) || [];
+    }
+}

package/dist/agent.d.ts

@@ -0,0 +1,132 @@
+/**
+ * FeltDB Agent Runtime
+ *
+ * Agents are durable, addressable participants in the FeltDB fabric.
+ * An agent's observations, decisions, actions, and results are all part
+ * of the same causal graph.
+ */
+/**
+ * Agent reference - a location-independent address for an agent
+ * Format: flow://agent/{name}@{version}
+ * Example: flow://agent/researcher@1
+ */
+export interface AgentRef {
+    /** Agent name */
+    name: string;
+    /** Agent version */
+    version: number;
+    /** Full canonical form */
+    toString(): string;
+}
+/**
+ * Lifecycle states for agent execution
+ */
+export declare enum AgentExecutionStatus {
+    Created = "Created",
+    Planning = "Planning",
+    Observing = "Observing",
+    Deciding = "Deciding",
+    Acting = "Acting",
+    Waiting = "Waiting",
+    Completed = "Completed",
+    Failed = "Failed",
+    Cancelled = "Cancelled",
+    Blocked = "Blocked"
+}
+/**
+ * Agent definition: what the agent is capable of doing
+ */
+export interface AgentDefinition {
+    /** Unique agent name */
+    name: string;
+    /** Agent version */
+    version: number;
+    /** Human-readable description */
+    description?: string;
+    /** List of capabilities the agent can use */
+    capabilities: string[];
+    /** Agent goals/objectives */
+    goals?: string[];
+    /** Execution constraints */
+    constraints?: {
+        /** Maximum latency in milliseconds */
+        maxLatency?: number;
+        /** Whether to require fresh state */
+        requireFreshState?: boolean;
+        /** Maximum number of decision iterations */
+        maxIterations?: number;
+        /** Maximum concurrent executions */
+        maxConcurrent?: number;
+    };
+    /** Execution tools available to the agent */
+    tools?: string[];
+    /** Agent policies */
+    policies?: {
+        /** Require human approval for certain actions */
+        requireApproval?: string[];
+        /** Actions that are forbidden */
+        forbidden?: string[];
+    };
+    /** Memory scope and retention */
+    memory?: {
+        /** Maximum memory size in KB */
+        maxSize?: number;
+        /** Memory retention period in milliseconds */
+        retentionMs?: number;
+        /** Memory scope (local, distributed, shared) */
+        scope?: 'local' | 'distributed' | 'shared';
+    };
+}
+/**
+ * Agent execution: a particular invocation of an agent
+ */
+export interface AgentExecution {
+    /** Unique execution ID */
+    executionId: string;
+    /** Reference to the agent being executed */
+    agentRef: AgentRef;
+    /** Current lifecycle status */
+    status: AgentExecutionStatus;
+    /** Goal for this execution */
+    goal: string;
+    /** Input references to the execution */
+    inputs: string[];
+    /** State version when execution started */
+    stateVersion: number;
+    /** Peer ID that owns this execution (single-owner semantics) */
+    ownedBy?: string;
+    /** Observations made during this execution */
+    observationIds: string[];
+    /** Decisions made during this execution */
+    decisionIds: string[];
+    /** Actions taken during this execution */
+    actionIds: string[];
+    /** Result reference after completion */
+    resultRef?: string;
+    /** Execution attempt number */
+    attempt: number;
+    /** Timestamp when execution was created */
+    createdMs: number;
+    /** Timestamp when execution started */
+    startedMs?: number;
+    /** Timestamp when execution completed */
+    completedMs?: number;
+    /** Optional error message if execution failed */
+    error?: string;
+    /** Metadata about the execution */
+    metadata?: Record<string, any>;
+}
+/**
+ * Parse an agent reference from its canonical form
+ * @example parseAgentRef("flow://agent/researcher@1")
+ */
+export declare function parseAgentRef(ref: string): AgentRef;
+/**
+ * Create an agent reference
+ */
+export declare function createAgentRef(name: string, version: number): AgentRef;
+/**
+ * Generate a unique execution ID
+ */
+export declare function generateExecutionId(agentName: string): string;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}