@forbocai/core 0.5.6 → 0.5.8

package/dist/index.d.ts

@@ -20,7 +20,7 @@ interface CortexStatus {
     engine: 'mock' | 'remote' | 'node-llama-cpp' | 'web-llm';
 }
 interface ICortex {
-    init(): Promise<CortexStatus>;
+    init(onProgress?: (progress: number) => void): Promise<CortexStatus>;
     complete(prompt: string, options?: CompletionOptions): Promise<string>;
     completeStream(prompt: string, options?: CompletionOptions): AsyncGenerator<string>;
 }
@@ -49,12 +49,22 @@ interface AgentConfig {
     persona: string;
     initialState?: Partial<AgentState>;
     apiUrl?: string;
+    apiKey?: string;
 }
 interface AgentResponse {
     dialogue: string;
     action?: AgentAction;
     thought?: string;
 }
+/** Dialogue Request (Full API-side logic) */
+interface DialogueRequest {
+    diagMessage: string;
+    diagContext?: Array<[string, string]>;
+}
+/** Dialogue Response (Full API-side logic) */
+interface DialogueResponse {
+    diagReply: string;
+}
 interface MemoryItem {
     id: string;
     text: string;
@@ -100,6 +110,20 @@ interface RecalledMemory {
     importance: number;
     similarity?: number;
 }
+/** Speak Request (Simple Dialogue) */
+interface SpeakRequest {
+    speakMessage: string;
+    speakContext?: Record<string, unknown>;
+    speakAgentState: Record<string, unknown>;
+}
+/** Speak Response (Simple Dialogue) */
+interface SpeakResponse {
+    speakReply: string;
+    speakHistory: Array<{
+        role: string;
+        content: string;
+    }>;
+}
 /** Step 5: API → SDK. API returns full SLM prompt + constraints. */
 interface ContextResponse {
     prompt: string;
@@ -142,12 +166,21 @@ interface ValidationResult {
     reason?: string;
     correctedAction?: AgentAction;
 }
-interface ValidationRule {
+interface BridgeRule {
+    ruleName: string;
+    ruleDescription: string;
+    ruleActionTypes: string[];
+}
+interface DirectiveRuleSet {
+    rulesetId: string;
+    rulesetRules: BridgeRule[];
+}
+/**
+ * @deprecated Use BridgeRule for data-only rules.
+ * Local validation execution is no longer supported in the SDK ("API is The Law").
+ */
+interface ValidationRule extends BridgeRule {
     id: string;
-    name: string;
-    description: string;
-    actionTypes: string[];
-    validate: (action: AgentAction, context: ValidationContext) => ValidationResult;
 }
 interface Soul {
     id: string;
@@ -158,72 +191,53 @@ interface Soul {
     state: AgentState;
     signature?: string;
 }
+/**
+ * Soul configuration (Thin Client)
+ */
+interface SoulConfig {
+    apiUrl?: string;
+    gatewayUrl?: string;
+}
+/**
+ * Soul export result
+ */
+interface SoulExportResult {
+    txId: string;
+    url: string;
+    soul: Soul;
+}
 
 /**
  * Interface for Agent operations
  */
 interface IAgent {
-    /**
-     * Processes an input string with optional context to generate a response.
-     * Follows the multi-round protocol: directive → context → verdict.
-     * @param input - The input string from the user or system.
-     * @param context - Optional context data to influence the agent's response.
-     * @returns A promise that resolves to the agent's response.
-     */
     process(input: string, context?: Record<string, unknown>): Promise<AgentResponse>;
-    /**
-     * Retrieves the current state of the agent.
-     * @returns The current AgentState.
-     */
+    speak(message: string, context?: Record<string, unknown>): Promise<string>;
+    reply(message: string, context?: Record<string, unknown>): Promise<string>;
     getState(): AgentState;
-    /**
-     * Updates the agent's state.
-     * @param newState - The new state to set.
-     */
     setState(newState: AgentState): void;
-    /**
-     * Exports the agent's data to a Soul object.
-     * @returns A promise resolving to the Soul representation of the agent.
-     */
+    dialogue(message: string, context?: Array<[string, string]>): Promise<string>;
     export(): Promise<Soul>;
+    exportSoul(config?: SoulConfig): Promise<SoulExportResult>;
 }
 /**
  * Pure function to create initial agent state
- * @param partial - Optional partial state to initialize with.
- * @returns The initialized AgentState.
  */
 declare const createInitialState: (partial?: Partial<AgentState>) => AgentState;
 /**
  * Pure function to update agent state
- * Returns new state without mutating original
- * @param currentState - The current state of the agent.
- * @param updates - The updates to apply to the state.
- * @returns A new AgentState object with the updates applied.
  */
 declare const updateAgentState: (currentState: AgentState, updates: Partial<AgentState>) => AgentState;
 /**
  * Pure function to export agent to Soul
- * @param agentId - The ID of the agent.
- * @param name - The name of the agent.
- * @param persona - The persona description of the agent.
- * @param state - The current state of the agent.
- * @param memories - The list of memories associated with the agent.
- * @returns A Soul object representing the agent.
  */
 declare const exportToSoul: (agentId: string, name: string, persona: string, state: AgentState, memories: MemoryItem[]) => Soul;
 /**
  * Factory function to create Agent (Functional/Closure based)
- * Implements the multi-round protocol where the SDK is a dumb executor.
- * @param config - The configuration object for creating the agent.
- * @returns An instance of IAgent.
  */
 declare const createAgent: (config: AgentConfig) => IAgent;
 /**
  * Pure function to import Agent from Soul
- * @param soul - The Soul object to import from.
- * @param cortex - The Cortex instance for the agent.
- * @param memory - Optional memory instance.
- * @returns An instantiated IAgent.
  */
 declare const fromSoul: (soul: Soul, cortex: ICortex, memory?: IMemory | null) => Promise<IAgent>;
 
@@ -231,103 +245,43 @@ declare const fromSoul: (soul: Soul, cortex: ICortex, memory?: IMemory | null) =
  * Bridge configuration
  */
 interface BridgeConfig {
-    /** Base URL for the API. */
     apiUrl?: string;
-    /** If true, reject any unknown action types. */
-    strictMode?: boolean;
-    /** Custom validation rules to apply. */
-    customRules?: ValidationRule[];
+    agentId?: string;
 }
 /**
  * Interface for Bridge operations
  */
 interface IBridge {
     /**
-     * Validates an agent action against registered rules.
-     * @param action - The action to validate.
-     * @param context - Optional validation context.
-     * @returns A promise that resolves to the validation result.
+     * Validate an action against the API.
+     * If agentId is provided in config, uses agent-scoped validation.
      */
     validate(action: AgentAction, context?: ValidationContext): Promise<ValidationResult>;
     /**
-     * Registers a new validation rule.
-     * @param rule - The rule to register.
-     */
-    registerRule(rule: ValidationRule): void;
-    /**
-     * Lists all registered validation rules.
-     * @returns An array of ValidationRule objects.
+     * List all rulesets currently registered on the API.
      */
-    listRules(): ValidationRule[];
-    /**
-     * Removes a validation rule by its ID.
-     * @param ruleId - The ID of the rule to remove.
-     * @returns True if the rule was removed, false otherwise.
-     */
-    removeRule(ruleId: string): boolean;
+    listRulesets(): Promise<DirectiveRuleSet[]>;
 }
 /**
- * Factory function to create Bridge instance (Functional/Closure based)
- * @param config - Optional configuration for the Bridge.
- * @returns An instance of IBridge.
+ * Factory function to create Bridge instance
+ * All validation logic now resides on the server ("API is The Law").
  */
 declare const createBridge: (config?: BridgeConfig) => IBridge;
 /**
- * Pure function to validate action (standalone, no class needed)
- * @param action - The action to validate.
- * @param rules - The list of rules to validate against.
- * @param context - Optional validation context.
- * @returns The result of the validation.
+ * Standalone validation helper (deprecated locally, calls API)
+ * @deprecated Use createBridge(config).validate(action, context)
  */
-declare const validateAction: (action: AgentAction, rules: readonly ValidationRule[], context?: ValidationContext) => ValidationResult;
-
-/**
- * Soul export configuration
- */
-interface SoulExportConfig {
-    /** Include memories in export */
-    includeMemories?: boolean;
-    /** Arweave wallet JWK (object or JSON string) for direct uploads */
-    walletJwk?: Record<string, unknown> | string;
-    /** Deprecated: use walletJwk */
-    privateKey?: Record<string, unknown> | string;
-    /** Bundler URL for ANS-104 data item uploads */
-    bundlerUrl?: string;
-    /** Gateway URL for read access (default: https://arweave.net) */
-    gatewayUrl?: string;
-}
+declare const validateAction: (action: AgentAction, context?: ValidationContext, config?: BridgeConfig) => Promise<ValidationResult>;
 /**
- * Soul export result
- */
-interface SoulExportResult {
-    /** Arweave data item ID (TXID) */
-    txId: string;
-    /** Gateway URL to access the soul. */
-    url: string;
-    /** The exported Soul object. */
-    soul: Soul;
-}
-/**
- * Soul import configuration
+ * Register a server-side rule preset for an agent session.
  */
-interface SoulImportConfig {
-    /** Gateway URL for Arweave (defaults to https://arweave.net) */
-    gatewayUrl?: string;
-}
+declare const loadPreset: (presetName: string, apiUrl?: string) => Promise<DirectiveRuleSet>;
+
 /**
  * Interface for Soul operations
  */
 interface ISoul {
-    /**
-     * Exports the Soul to Arweave.
-     * @param config - Export configuration.
-     * @returns A promise resolving to the export result.
-     */
-    export(config?: SoulExportConfig): Promise<SoulExportResult>;
-    /**
-     * Returns the raw Soul data object.
-     * @returns The Soul object.
-     */
+    export(config?: SoulConfig): Promise<SoulExportResult>;
     toJSON(): Soul;
 }
 /**
@@ -343,31 +297,18 @@ declare const serializeSoul: (soul: Soul) => string;
  */
 declare const deserializeSoul: (json: string) => Soul;
 /**
- * Pure function to upload Soul to Arweave using ANS-104 data items
+ * Export agent Soul to Arweave via API
  */
-declare const uploadToArweave: (soul: Soul, config: SoulExportConfig) => Promise<SoulExportResult>;
+declare const exportSoul: (agentId: string, _soul: Soul, // Soul data is derived from agent state on the API
+config?: SoulConfig) => Promise<SoulExportResult>;
 /**
- * Export agent Soul to Arweave (direct ANS-104 or API)
+ * Import Soul from Arweave by TXID via API
  */
-declare const exportSoul: (_agentId: string, soul: Soul, config?: SoulExportConfig) => Promise<SoulExportResult>;
+declare const importSoulFromArweave: (txId: string, config?: SoulConfig) => Promise<Soul>;
 /**
- * Import Soul from Arweave by TXID
+ * Get list of all exported Souls from the API
  */
-declare const importSoulFromArweave: (txId: string, config?: SoulImportConfig) => Promise<Soul>;
-/**
- * Soul entry in the listing
- */
-interface SoulListEntry {
-    txId: string;
-    name: string;
-    agentId?: string;
-    exportedAt: string;
-    url: string;
-}
-/**
- * Get list of all exported Souls
- */
-declare const getSoulList: (limit?: number, apiUrl?: string) => Promise<SoulListEntry[]>;
+declare const getSoulList: (limit?: number, apiUrl?: string) => Promise<any[]>;
 /**
  * Factory function to create Soul instance
  */
@@ -384,108 +325,59 @@ declare const validateSoul: (soul: Soul) => {
  * Ghost test configuration
  */
 interface GhostConfig {
-    /** API URL for ghost orchestration */
     apiUrl?: string;
-    /** Test suite to run */
     testSuite: 'exploration' | 'combat' | 'dialogue' | 'pathfinding' | 'full';
-    /** Maximum duration in seconds */
     duration: number;
-    /** Capture screenshots on failure */
     captureScreenshots?: boolean;
-    /** Custom test parameters */
     params?: Record<string, unknown>;
 }
 /**
  * Ghost session status
  */
 interface GhostStatus {
-    /** The unique ID of the session. */
     sessionId: string;
-    /** The current status of the session. */
     status: 'pending' | 'running' | 'completed' | 'failed';
-    /** Progress percentage (0-100). */
     progress: number;
-    /** ISO timestamp when the session started. */
     startedAt: string;
-    /** Duration in seconds elapsed. */
     duration: number;
-    /** Number of errors encountered. */
     errors: number;
 }
 /**
  * Individual test result
  */
 interface GhostTestResult {
-    /** Name of the test case. */
     name: string;
-    /** Whether the test passed. */
     passed: boolean;
-    /** Duration of the test in milliseconds. */
     duration: number;
-    /** Error message if the test failed. */
     error?: string;
-    /** URL or path to a screenshot if captured. */
     screenshot?: string;
 }
 /**
  * Complete session results
  */
 interface GhostResults {
-    /** The session ID. */
     sessionId: string;
-    /** Total number of tests run. */
     totalTests: number;
-    /** Number of passed tests. */
     passed: number;
-    /** Number of failed tests. */
     failed: number;
-    /** Number of skipped tests. */
     skipped: number;
-    /** Total duration in milliseconds. */
     duration: number;
-    /** List of individual test results. */
     tests: GhostTestResult[];
-    /** Code/Feature coverage (0.0-1.0). */
     coverage: number;
-    /** Additional metrics collected during the session. */
     metrics: Record<string, number>;
 }
 /**
  * Interface for Ghost operations
  */
 interface IGhost {
-    /**
-     * Starts a Ghost session.
-     * @returns A promise resolving to the session ID.
-     */
     run(): Promise<string>;
-    /**
-     * Gets the current status of the session.
-     * @returns A promise resolving to the GhostStatus.
-     */
     status(): Promise<GhostStatus>;
-    /**
-     * Gets the results of the session.
-     * @returns A promise resolving to the GhostResults.
-     */
     results(): Promise<GhostResults>;
-    /**
-     * Stops the current session.
-     */
     stop(): Promise<void>;
-    /**
-     * Waits for the session to complete.
-     * @param pollIntervalMs - Polling interval in milliseconds.
-     * @param timeoutMs - Timeout in milliseconds.
-     * @param onProgress - Optional callback for progress updates.
-     * @returns A promise resolving to the GhostResults.
-     */
     waitForCompletion(pollIntervalMs?: number, timeoutMs?: number, onProgress?: (status: GhostStatus) => void): Promise<GhostResults>;
 }
 /**
  * Start a Ghost testing session
- * @param config - The configuration for the Ghost session.
- * @returns A promise resolving to an object containing the session ID and initial status.
  */
 declare const startGhostSession: (config: GhostConfig) => Promise<{
     sessionId: string;
@@ -493,40 +385,24 @@ declare const startGhostSession: (config: GhostConfig) => Promise<{
 }>;
 /**
  * Get Ghost session status
- * @param sessionId - The ID of the session to check.
- * @param apiUrl - Optional API URL override.
- * @returns A promise resolving to the GhostStatus.
  */
 declare const getGhostStatus: (sessionId: string, apiUrl?: string) => Promise<GhostStatus>;
 /**
  * Get Ghost session results
- * @param sessionId - The ID of the session to retrieve results for.
- * @param apiUrl - Optional API URL override.
- * @returns A promise resolving to the GhostResults.
  */
 declare const getGhostResults: (sessionId: string, apiUrl?: string) => Promise<GhostResults>;
 /**
  * Poll Ghost session until completion
- * @param sessionId - The ID of the session to wait for.
- * @param pollIntervalMs - Polling interval in milliseconds.
- * @param timeoutMs - Timeout in milliseconds.
- * @param apiUrl - Optional API URL override.
- * @param onProgress - Optional callback for progress updates.
- * @returns A promise resolving to the GhostResults upon completion.
  */
 declare const waitForGhostCompletion: (sessionId: string, pollIntervalMs?: number, timeoutMs?: number, apiUrl?: string, onProgress?: (status: GhostStatus) => void) => Promise<GhostResults>;
 /**
  * Stop a running Ghost session
- * @param sessionId - The ID of the session to stop.
- * @param apiUrl - Optional API URL override.
- * @returns A promise resolving to the stop status.
  */
 declare const stopGhostSession: (sessionId: string, apiUrl?: string) => Promise<{
     stopped: boolean;
-    status: string;
 }>;
 /**
- * Get Ghost session history
+ * Ghost session history entry
  */
 interface GhostHistoryEntry {
     sessionId: string;
@@ -538,15 +414,10 @@ interface GhostHistoryEntry {
 }
 /**
  * Get Ghost session history
- * @param limit - Max number of entries to retrieve.
- * @param apiUrl - Optional API URL override.
- * @returns A promise resolving to an array of GhostHistoryEntry.
  */
 declare const getGhostHistory: (limit?: number, apiUrl?: string) => Promise<GhostHistoryEntry[]>;
 /**
  * Factory function to create Ghost session (Functional/Closure based)
- * @param config - The configuration for the Ghost session.
- * @returns An instance of IGhost.
  */
 declare const createGhost: (config: GhostConfig) => IGhost;
 
@@ -554,57 +425,58 @@ declare const createGhost: (config: GhostConfig) => IGhost;
  * Creates a remote Cortex instance that proxies inference to the ForbocAI API.
  * This is environment-agnostic as it only uses the standard fetch API.
  */
-declare const createRemoteCortex: (apiUrl: string, cortexId?: string) => ICortex;
+declare const createRemoteCortex: (apiUrl: string, cortexId?: string, apiKey?: string) => ICortex;
 
-interface RPGAgentState extends AgentState {
-    inventory: string[];
-    hp: number;
-    mana: number;
-    skills: Record<string, number>;
-    relationships: Record<string, number>;
-    mood: string;
-}
-declare const RPG_MOODS: {
-    readonly hostile: "hostile";
-    readonly suspicious: "suspicious";
-    readonly neutral: "neutral";
-    readonly friendly: "friendly";
-    readonly loyal: "loyal";
-};
-declare const RPG_MEMORY_TYPES: {
-    readonly observation: "observation";
-    readonly experience: "experience";
-    readonly knowledge: "knowledge";
-    readonly emotion: "emotion";
-};
-declare const createRPGState: (partial?: Partial<RPGAgentState>) => RPGAgentState;
-declare const movementRule: ValidationRule;
-declare const attackRule: ValidationRule;
-declare const interactRule: ValidationRule;
-declare const speakRule: ValidationRule;
-declare const resourceRule: ValidationRule;
-declare const rpgRules: ValidationRule[];
-declare const spatialRules: ValidationRule[];
-declare const socialRules: ValidationRule[];
-declare const puzzleRules: ValidationRule[];
+/**
+ * Consume an async token stream, calling `onChunk` for each token.
+ * Useful for rendering typewriter effects in UI.
+ */
+declare const streamToCallback: (stream: AsyncGenerator<string, void, unknown>, onChunk: (chunk: string) => void) => Promise<void>;
+/**
+ * Consume an async token stream and return the full accumulated string.
+ */
+declare const streamToString: (stream: AsyncGenerator<string, void, unknown>) => Promise<string>;
+/**
+ * Stream tokens from a cortex directly to a callback.
+ * Convenience wrapper combining cortex.completeStream + streamToCallback.
+ */
+declare const streamFromCortex: (cortex: ICortex, prompt: string, onChunk: (chunk: string) => void, options?: {
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+}) => Promise<string>;
+/**
+ * Stream tokens from a cortex with a delay between tokens (for typewriter pacing).
+ *
+ * @param delayMs - Milliseconds to wait between tokens (default: 30ms)
+ */
+declare const streamFromCortexWithDelay: (cortex: ICortex, prompt: string, onChunk: (chunk: string) => void, options?: {
+    temperature?: number;
+    maxTokens?: number;
+    stop?: string[];
+    delayMs?: number;
+}) => Promise<string>;
 
-type index_RPGAgentState = RPGAgentState;
-declare const index_RPG_MEMORY_TYPES: typeof RPG_MEMORY_TYPES;
-declare const index_RPG_MOODS: typeof RPG_MOODS;
-declare const index_attackRule: typeof attackRule;
-declare const index_createRPGState: typeof createRPGState;
-declare const index_interactRule: typeof interactRule;
-declare const index_movementRule: typeof movementRule;
-declare const index_puzzleRules: typeof puzzleRules;
-declare const index_resourceRule: typeof resourceRule;
-declare const index_rpgRules: typeof rpgRules;
-declare const index_socialRules: typeof socialRules;
-declare const index_spatialRules: typeof spatialRules;
-declare const index_speakRule: typeof speakRule;
-declare namespace index {
-  export { type index_RPGAgentState as RPGAgentState, index_RPG_MEMORY_TYPES as RPG_MEMORY_TYPES, index_RPG_MOODS as RPG_MOODS, index_attackRule as attackRule, index_createRPGState as createRPGState, index_interactRule as interactRule, index_movementRule as movementRule, index_puzzleRules as puzzleRules, index_resourceRule as resourceRule, index_rpgRules as rpgRules, index_socialRules as socialRules, index_spatialRules as spatialRules, index_speakRule as speakRule };
-}
+/**
+ * Pure Functional Utilities for ForbocAI SDK
+ */
+/**
+ * Delay execution for a specified number of milliseconds.
+ */
+declare const delay: (ms: number) => Promise<void>;
+/**
+ * Functional pipe for chaining functions.
+ */
+declare const pipe: <T>(...fns: Array<(arg: T) => T>) => (initialValue: T) => T;
+/**
+ * Closure-based memoization for async functions (single value cache).
+ */
+declare const memoiseAsync: <T>(fn: () => Promise<T>) => () => Promise<T>;
+/**
+ * Closure-based memoization for sync functions (single value cache).
+ */
+declare const memoise: <T>(fn: () => T) => () => T;
 
-declare const SDK_VERSION = "0.5.6";
+declare const SDK_VERSION = "0.5.7";
 
-export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type BridgeConfig, type CompletionOptions, type ContextRequest, type ContextResponse, type CortexConfig, type CortexStatus, type DirectiveRequest, type DirectiveResponse, type GhostConfig, type GhostHistoryEntry, type GhostResults, type GhostStatus, type GhostTestResult, type IAgent, type IBridge, type ICortex, type IGhost, type IMemory, type ISoul, type MemoryItem, type MemoryRecallInstruction, type MemoryStoreInstruction, type PromptConstraints, type RecalledMemory, SDK_VERSION, type Soul, type SoulExportConfig, type SoulExportResult, type SoulImportConfig, type SoulListEntry, type ValidationContext, type ValidationResult, type ValidationRule, type VerdictRequest, type VerdictResponse, createAgent, createBridge, createGhost, createInitialState, createRemoteCortex, createSoul, createSoulInstance, deserializeSoul, exportSoul, exportToSoul, fromSoul, getGhostHistory, getGhostResults, getGhostStatus, getSoulList, importSoulFromArweave, index as presets, serializeSoul, startGhostSession, stopGhostSession, updateAgentState, uploadToArweave, validateAction, validateSoul, waitForGhostCompletion };
+export { type AgentAction, type AgentConfig, type AgentResponse, type AgentState, type BridgeConfig, type BridgeRule, type CompletionOptions, type ContextRequest, type ContextResponse, type CortexConfig, type CortexStatus, type DialogueRequest, type DialogueResponse, type DirectiveRequest, type DirectiveResponse, type DirectiveRuleSet, type GhostConfig, type GhostHistoryEntry, type GhostResults, type GhostStatus, type GhostTestResult, type IAgent, type IBridge, type ICortex, type IGhost, type IMemory, type ISoul, type MemoryItem, type MemoryRecallInstruction, type MemoryStoreInstruction, type PromptConstraints, type RecalledMemory, SDK_VERSION, type Soul, type SoulConfig, type SoulExportResult, type SpeakRequest, type SpeakResponse, type ValidationContext, type ValidationResult, type ValidationRule, type VerdictRequest, type VerdictResponse, createAgent, createBridge, createGhost, createInitialState, createRemoteCortex, createSoul, createSoulInstance, delay, deserializeSoul, exportSoul, exportToSoul, fromSoul, getGhostHistory, getGhostResults, getGhostStatus, getSoulList, importSoulFromArweave, loadPreset, memoise, memoiseAsync, pipe, serializeSoul, startGhostSession, stopGhostSession, streamFromCortex, streamFromCortexWithDelay, streamToCallback, streamToString, updateAgentState, validateAction, validateSoul, waitForGhostCompletion };