@nexus-cortex/core 4.26.0

package/dist/system-messages/types.d.ts

@@ -0,0 +1,184 @@
+/**
+ * System Message Types
+ *
+ * Types for the hot-reload system message architecture
+ */
+/**
+ * System message source
+ */
+export type MessageSource = 'builtin' | 'workspace' | 'runtime';
+/**
+ * System message type
+ */
+export type MessageType = 'instruction' | 'constraint' | 'context' | 'template';
+/**
+ * System message data
+ */
+export interface SystemMessage {
+    /** Unique message identifier (e.g., 'tool_usage_guide') */
+    id: string;
+    /** Message type */
+    type: MessageType;
+    /** File path relative to source directory */
+    path: string;
+    /** Whether message is enabled */
+    enabled: boolean;
+    /** Source of the message */
+    source: MessageSource;
+    /** Priority for injection order (higher = injected first) */
+    priority: number;
+    /** Message content (markdown) */
+    content: string;
+    /** Optional conditions for when to inject */
+    conditions?: MessageConditions;
+    /** Metadata */
+    metadata: MessageMetadata;
+}
+/**
+ * Conditions for message injection
+ */
+export interface MessageConditions {
+    /** Require tools to be enabled */
+    requireTools?: boolean;
+    /** Minimum number of tools */
+    minToolCount?: number;
+    /** Only for specific model families */
+    modelFamily?: string[];
+    /** Only in debug mode */
+    debugOnly?: boolean;
+    /** Inject only on a specific turn (0 = first turn → R28 pins it static). */
+    turnNumber?: number;
+    /**
+     * Inject when turn matches modulo. Presence ALSO marks the message
+     * turn-varying (see turnVaryingClassifier) → routed to the live user
+     * turn instead of the cached `system` field. `{divisor:1,remainder:0}`
+     * = every turn.
+     */
+    turnNumberModulo?: {
+        divisor: number;
+        remainder: number;
+    };
+}
+/**
+ * Message metadata
+ */
+export interface MessageMetadata {
+    /** Author/creator */
+    author?: string;
+    /** Creation timestamp */
+    created: string;
+    /** Last modification timestamp */
+    modified?: string;
+    /** Human-readable description */
+    description?: string;
+    /** Display name */
+    displayName?: string;
+}
+/**
+ * System message info (for listing)
+ */
+export interface SystemMessageInfo {
+    id: string;
+    type: MessageType;
+    source: MessageSource;
+    path: string;
+    enabled: boolean;
+    priority: number;
+    metadata: MessageMetadata;
+    fileSize?: number;
+    lastModified?: Date;
+}
+/**
+ * Message registry (stored in registry.json)
+ */
+export interface MessageRegistry {
+    /** Registry format version */
+    version: string;
+    /** Last modification time */
+    lastModified: string;
+    /** Registered messages */
+    messages: MessageRegistryEntry[];
+}
+/**
+ * Registry entry for a message
+ */
+export interface MessageRegistryEntry {
+    id: string;
+    type: MessageType;
+    path: string;
+    enabled: boolean;
+    priority: number;
+    conditions?: MessageConditions;
+    metadata: MessageMetadata;
+}
+/**
+ * Store event types
+ */
+export type StoreEventType = 'message_created' | 'message_updated' | 'message_deleted' | 'message_toggled' | 'store_reloaded' | 'registry_updated';
+/**
+ * Store event
+ */
+export interface StoreEvent {
+    type: StoreEventType;
+    messageId?: string;
+    message?: SystemMessage;
+    enabled?: boolean;
+    timestamp: Date;
+}
+/**
+ * Store change listener callback
+ */
+export type StoreChangeListener = (event: StoreEvent) => void;
+/**
+ * Message template for creating new messages
+ */
+export interface MessageTemplate {
+    id: string;
+    type: MessageType;
+    displayName?: string;
+    description?: string;
+    priority?: number;
+}
+/**
+ * Validation result
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationWarning[];
+    stats: ValidationStats;
+}
+/**
+ * Validation error
+ */
+export interface ValidationError {
+    type: 'size' | 'encoding' | 'frontmatter' | 'security' | 'syntax';
+    message: string;
+    line?: number;
+    column?: number;
+}
+/**
+ * Validation warning
+ */
+export interface ValidationWarning {
+    type: 'length' | 'formatting' | 'deprecated';
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validation statistics
+ */
+export interface ValidationStats {
+    lines: number;
+    chars: number;
+    words: number;
+}
+/**
+ * Editor launch result
+ */
+export interface EditResult {
+    wasModified: boolean;
+    filePath: string;
+    editor: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/system-messages/types.d.ts.map

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

package/dist/system-messages/types.js

@@ -0,0 +1,7 @@
+/**
+ * System Message Types
+ *
+ * Types for the hot-reload system message architecture
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/system-messages/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/system-messages/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/tools/ClientSideToolFilter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ClientSideToolFilter — Progressive tool loading for non-PTC providers.
+ *
+ * Tracks recently used tools and returns essential + recently-used tools,
+ * reducing token usage by not sending all tool schemas on every request.
+ *
+ * For PTC providers (Anthropic), use native `defer_loading` instead.
+ */
+import type { CanonicalTool } from '../adapters/FormatAdapter.interface.js';
+export declare class ClientSideToolFilter {
+    private recentlyUsed;
+    private discoveredTools;
+    /** Record that a tool was used (adds to recent list). */
+    recordToolUse(name: string): void;
+    /** Get filtered tools: essential + discovered + recently-used. */
+    getFilteredTools(allTools: CanonicalTool[]): CanonicalTool[];
+    /** Get deferred tool names (standard tier, not yet discovered/used). */
+    getDeferredToolNames(allTools: CanonicalTool[]): string[];
+    /** Get deferred tools with metadata for richer announcements. */
+    getDeferredTools(allTools: CanonicalTool[]): {
+        name: string;
+        description: string;
+    }[];
+    /** Get list of recently used tool names. */
+    getRecentlyUsed(): readonly string[];
+    /**
+     * Record tools discovered via SearchTools result.
+     * Discovered tools are sticky — they stay available for the rest of the session
+     * rather than competing with recent-use slots.
+     */
+    recordDiscoveredTools(searchResultJson: string): void;
+    /** Reset tracking. */
+    reset(): void;
+}
+//# sourceMappingURL=ClientSideToolFilter.d.ts.map

package/dist/tools/ClientSideToolFilter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClientSideToolFilter.d.ts","sourceRoot":"","sources":["../../src/tools/ClientSideToolFilter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wCAAwC,CAAC;AAM5E,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,YAAY,CAAgB;IACpC,OAAO,CAAC,eAAe,CAAqB;IAE5C,yDAAyD;IACzD,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQjC,kEAAkE;IAClE,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,aAAa,EAAE;IAU5D,wEAAwE;IACxE,oBAAoB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE;IAOzD,iEAAiE;IACjE,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,EAAE;IAOpF,4CAA4C;IAC5C,eAAe,IAAI,SAAS,MAAM,EAAE;IAIpC;;;;OAIG;IACH,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI;IAerD,sBAAsB;IACtB,KAAK,IAAI,IAAI;CAId"}

package/dist/tools/ClientSideToolFilter.js

@@ -0,0 +1,74 @@
+/**
+ * ClientSideToolFilter — Progressive tool loading for non-PTC providers.
+ *
+ * Tracks recently used tools and returns essential + recently-used tools,
+ * reducing token usage by not sending all tool schemas on every request.
+ *
+ * For PTC providers (Anthropic), use native `defer_loading` instead.
+ */
+import { ToolNamingHandler } from '../adapters/ToolNamingHandler.js';
+const MAX_RECENT = 15;
+const namingHandler = new ToolNamingHandler();
+export class ClientSideToolFilter {
+    recentlyUsed = [];
+    discoveredTools = new Set();
+    /** Record that a tool was used (adds to recent list). */
+    recordToolUse(name) {
+        this.recentlyUsed = this.recentlyUsed.filter((n) => n !== name);
+        this.recentlyUsed.unshift(name);
+        if (this.recentlyUsed.length > MAX_RECENT) {
+            this.recentlyUsed.pop();
+        }
+    }
+    /** Get filtered tools: essential + discovered + recently-used. */
+    getFilteredTools(allTools) {
+        const recentSet = new Set(this.recentlyUsed);
+        return allTools.filter((t) => t.discoveryTier === 'essential' ||
+            recentSet.has(t.name) ||
+            this.discoveredTools.has(t.name));
+    }
+    /** Get deferred tool names (standard tier, not yet discovered/used). */
+    getDeferredToolNames(allTools) {
+        const activeSet = new Set([...this.recentlyUsed, ...this.discoveredTools]);
+        return allTools
+            .filter((t) => t.discoveryTier !== 'essential' && !activeSet.has(t.name))
+            .map((t) => t.name);
+    }
+    /** Get deferred tools with metadata for richer announcements. */
+    getDeferredTools(allTools) {
+        const activeSet = new Set([...this.recentlyUsed, ...this.discoveredTools]);
+        return allTools
+            .filter((t) => t.discoveryTier !== 'essential' && !activeSet.has(t.name))
+            .map((t) => ({ name: t.name, description: t.description }));
+    }
+    /** Get list of recently used tool names. */
+    getRecentlyUsed() {
+        return this.recentlyUsed;
+    }
+    /**
+     * Record tools discovered via SearchTools result.
+     * Discovered tools are sticky — they stay available for the rest of the session
+     * rather than competing with recent-use slots.
+     */
+    recordDiscoveredTools(searchResultJson) {
+        try {
+            const parsed = JSON.parse(searchResultJson);
+            if (parsed.tools && Array.isArray(parsed.tools)) {
+                for (const tool of parsed.tools) {
+                    if (tool.name && typeof tool.name === 'string') {
+                        // SearchTools may return snake_case names (model-facing convention).
+                        // Convert to PascalCase for internal matching against allTools.
+                        this.discoveredTools.add(namingHandler.convertName(tool.name, 'PascalCase'));
+                    }
+                }
+            }
+        }
+        catch { /* skip malformed JSON */ }
+    }
+    /** Reset tracking. */
+    reset() {
+        this.recentlyUsed = [];
+        this.discoveredTools.clear();
+    }
+}
+//# sourceMappingURL=ClientSideToolFilter.js.map

package/dist/tools/ClientSideToolFilter.js.map

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

package/dist/tools/ServerSideTools.d.ts

@@ -0,0 +1,181 @@
+/**
+ * Server-Side Tool Support
+ *
+ * Handles provider-managed agentic tool execution where the provider's
+ * server autonomously loops through tool calls rather than requiring
+ * client-side execution.
+ *
+ * Examples:
+ * - XAI: web_search(), x_search(), code_interpreter()
+ * - Future: Other providers adding similar capabilities
+ *
+ * Architecture:
+ * - Tool definitions flagged as 'server' vs 'client'
+ * - Orchestrator passes tools to provider
+ * - Provider executes autonomously
+ * - Response includes citations, tool usage metadata
+ */
+/**
+ * Tool Execution Mode
+ */
+export type ToolExecutionMode = 'client' | 'server' | 'both';
+/**
+ * Server-Side Tool Metadata
+ *
+ * Returned by providers that support autonomous tool execution
+ */
+export interface ServerSideToolMetadata {
+    /** Map of tool categories to invocation counts (for billing) */
+    toolUsage: Record<string, number>;
+    /** List of all URLs/sources consulted during autonomous search */
+    citations?: string[];
+    /** Detailed list of tool calls made (including failed attempts) */
+    toolCalls: Array<{
+        id: string;
+        name: string;
+        arguments: string;
+        status?: 'success' | 'failed';
+    }>;
+    /** Whether this was an autonomous multi-step loop */
+    autonomousExecution: boolean;
+    /** Provider-specific metadata */
+    providerMetadata?: Record<string, any>;
+}
+/**
+ * Extended Tool Definition
+ *
+ * Adds server-side capability flags to standard tool definitions
+ */
+export interface ServerSideToolDefinition {
+    /** Tool execution mode */
+    executionMode: ToolExecutionMode;
+    /** Tool name (matches server-side tool type) */
+    name: string;
+    /** Tool description */
+    description?: string;
+    /** Server-side tool configuration (provider-specific) */
+    serverConfig?: {
+        /** For XAI web_search */
+        allowed_domains?: string[];
+        excluded_domains?: string[];
+        enable_image_understanding?: boolean;
+        /** For XAI x_search */
+        allowed_x_handles?: string[];
+        excluded_x_handles?: string[];
+        from_date?: string;
+        to_date?: string;
+        enable_video_understanding?: boolean;
+    };
+}
+/**
+ * Server-Side Tool Registry
+ *
+ * Maps provider tool names to their execution modes
+ */
+export declare const SERVER_SIDE_TOOL_REGISTRY: Record<string, Record<string, ToolExecutionMode>>;
+/**
+ * Check if a tool is server-side for a given provider
+ */
+export declare function isServerSideTool(provider: string, toolName: string): boolean;
+/**
+ * Check if a tool is client-side for a given provider
+ */
+export declare function isClientSideTool(provider: string, toolName: string): boolean;
+/**
+ * Get all server-side tools for a provider
+ */
+export declare function getServerSideTools(provider: string): string[];
+/**
+ * XAI Server-Side Tool Builders
+ *
+ * Helper functions to create XAI-specific server-side tools
+ */
+export declare const XAIServerSideTools: {
+    /**
+     * Web Search Tool
+     *
+     * Allows autonomous web search and page browsing
+     */
+    webSearch(config?: {
+        allowed_domains?: string[];
+        excluded_domains?: string[];
+        enable_image_understanding?: boolean;
+    }): ServerSideToolDefinition;
+    /**
+     * X Search Tool
+     *
+     * Allows autonomous X (Twitter) search
+     */
+    xSearch(config?: {
+        allowed_x_handles?: string[];
+        excluded_x_handles?: string[];
+        from_date?: string;
+        to_date?: string;
+        enable_image_understanding?: boolean;
+        enable_video_understanding?: boolean;
+    }): ServerSideToolDefinition;
+    /**
+     * Code Execution Tool
+     *
+     * Allows autonomous Python code execution
+     */
+    codeExecution(): ServerSideToolDefinition;
+    codeInterpreter(): ServerSideToolDefinition;
+};
+/**
+ * OpenAI Server-Side Tool Builders
+ *
+ * R20: OpenAI hosted tools on the Responses API. Direct parity with XAI's
+ * server-side tools — same wire-format pattern `{ type: 'tool_name' }` in the
+ * tools array; OpenAI's infrastructure autonomously loops through tool calls
+ * and returns citations/sources in the response metadata.
+ */
+export declare const OpenAIServerSideTools: {
+    /**
+     * Web Search Tool (Responses API native)
+     *
+     * Autonomous web search with citations.
+     */
+    webSearch(): ServerSideToolDefinition;
+    /**
+     * Code Interpreter Tool (Responses API native)
+     *
+     * Sandboxed Python execution. Container automatically managed by OpenAI.
+     */
+    codeInterpreter(): ServerSideToolDefinition;
+    /**
+     * File Search Tool (Responses API native)
+     *
+     * Vector-store-backed retrieval. Requires pre-uploaded vector store ids
+     * (configured at request time via additional API parameters).
+     */
+    fileSearch(): ServerSideToolDefinition;
+    /**
+     * Image Generation Tool (Responses API native)
+     *
+     * Generates images via gpt-image-1 / DALL-E.
+     */
+    imageGeneration(): ServerSideToolDefinition;
+};
+/**
+ * Convert ServerSideToolDefinition to CanonicalTool format
+ *
+ * This allows server-side tools to flow through the standard tool pipeline
+ */
+export declare function toCanonicalTool(toolDef: ServerSideToolDefinition): any;
+/**
+ * Separate client and server tools for a request
+ *
+ * Some providers don't allow mixing client and server tools
+ */
+export declare function separateTools(provider: string, tools: any[]): {
+    clientTools: any[];
+    serverTools: any[];
+};
+/**
+ * Extract server-side tool metadata from provider response
+ *
+ * Handles different provider response formats
+ */
+export declare function extractServerSideMetadata(provider: string, response: any): ServerSideToolMetadata | null;
+//# sourceMappingURL=ServerSideTools.d.ts.map

package/dist/tools/ServerSideTools.d.ts.map

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