@sschepis/robodev 1.0.0 → 1.0.1

package/.cursorrules

@@ -0,0 +1,21 @@
+# Roo Code - Structured Development Rules
+
+You are an AI assistant operating within a **Structured Development Framework**.
+Your behavior must be governed by the "Living Manifest" (SYSTEM_MAP.md) located in the project root.
+
+## Core Directives
+
+1. **Check the Manifest First**: Before answering any coding request, read `SYSTEM_MAP.md` to understand the current system state, locked features, and global invariants.
+2. **Respect Locks**:
+   - If a feature is in **Interface** or **Implementation** phase, its API signatures are **LOCKED**. You cannot change them without explicit user override.
+   - If a feature is **Locked**, you cannot modify it.
+3. **Follow the Flow**:
+   - **Discovery Phase**: Analyze requirements -> Call `submit_technical_design`.
+   - **Design Review**: Wait for user approval -> Call `approve_design`.
+   - **Interface Phase**: Define types -> Call `lock_interfaces`.
+   - **Implementation Phase**: Write code -> Call `submit_critique` -> Finalize.
+
+## Tool Usage
+
+- Use `read_manifest` to access the system map.
+- Use `submit_technical_design`, `approve_design`, `lock_interfaces`, and `submit_critique` to move through the development phases.

package/.snapshots/SYSTEM_MAP.2026-02-16T04-30-50-661Z.md

@@ -0,0 +1,19 @@
+# System Manifest (SYSTEM_MAP.md)
+Last Updated: 2026-02-16T04:30:50.659Z
+
+## 1. Global Invariants
+| ID | Invariant | Description |
+|---|---|---|
+| INV-001 | No External Math Libs | Use standard Math library only. |
+| INV-002 | Strict Typing | All interfaces must be defined in .d.ts files. |
+
+## 2. Feature Registry
+| Feature ID | Name | Status | Phase | Lock Level | Priority | Dependencies |
+|---|---|---|---|---|---|---|
+| FEAT-000 | System Init | Active | Discovery | None | High | - |
+
+## 3. Dependency Graph
+- FEAT-000: System Init
+
+## 4. State Snapshots
+- [2026-02-16T04:30:50.659Z] Initial State Created

package/SYSTEM_MAP.md

@@ -0,0 +1,20 @@
+# System Manifest (SYSTEM_MAP.md)
+Last Updated: 2026-02-16T04:30:50.659Z
+
+## 1. Global Invariants
+| ID | Invariant | Description |
+|---|---|---|
+| INV-001 | No External Math Libs | Use standard Math library only. |
+| INV-002 | Strict Typing | All interfaces must be defined in .d.ts files. |
+
+## 2. Feature Registry
+| Feature ID | Name | Status | Phase | Lock Level | Priority | Dependencies |
+|---|---|---|---|---|---|---|
+| FEAT-000 | System Init | Active | Discovery | None | High | - |
+
+## 3. Dependency Graph
+- FEAT-000: System Init
+
+## 4. State Snapshots
+- [2026-02-16T04:30:50.659Z] Initial State Created
+- [2026-02-16T04:30:50.661Z] Snapshot: Initial Init (SYSTEM_MAP.2026-02-16T04-30-50-661Z.md)

package/current_SYSTEM_MAP.md

@@ -0,0 +1,30 @@
+# System Manifest (SYSTEM_MAP.md)
+Last Updated: 2026-02-16T04:28:16.724Z
+
+## 1. Global Invariants
+| ID | Invariant | Description |
+|---|---|---|
+| INV-001 | Client-Side Computation | All physics calculations run in the browser (no server). |
+| INV-002 | Numerical Parity | TypeScript engine must match Python engine results to floating-point precision. |
+| INV-003 | Pure Functions | Computation functions must be pure for memoization. |
+| INV-004 | Color Scheme | Consistent channel-to-color mapping (s=blue, p=green, d=orange, f=red). |
+
+## 2. Feature Registry
+| Feature ID | Name | Status | Phase | Lock Level | Priority | Dependencies |
+|---|---|---|---|---|---|---|
+| FEAT-ENGINE | Computation Engine | Completed | Implementation | None | High | - |
+| FEAT-UI-MVP | Basic Periodic Table (MVP) | Active | Design | None | High | FEAT-ENGINE |
+| FEAT-DATASHEET | Element Datasheet | Pending | Discovery | None | Medium | FEAT-UI-MVP |
+| FEAT-DASHBOARD | Global Dashboard | Pending | Discovery | None | Low | FEAT-DATASHEET |
+| FEAT-TUNER | Parameter Tuner | Pending | Discovery | None | Low | FEAT-ENGINE |
+
+## 3. Dependency Graph
+- FEAT-UI-MVP depends on FEAT-ENGINE
+- FEAT-DATASHEET depends on FEAT-UI-MVP
+- FEAT-DASHBOARD depends on FEAT-DATASHEET
+- FEAT-TUNER depends on FEAT-ENGINE
+
+## 4. State Snapshots
+- [2026-02-16T04:28:16.725Z] Initial State Created (bootstrapped from design document)
+
+- [2026-02-16T04:32:14.290Z] FEAT-ENGINE implemented

package/current_TECHNICAL_DESIGN_UI_MVP.md

@@ -0,0 +1,78 @@
+# Technical Design Document: MVP UI & Periodic Table (FEAT-UI-MVP)
+
+## 1. Overview
+The MVP UI provides the core interactive experience: a standard 18-column periodic table grid and a basic element datasheet. It connects the `Computation Engine` to a user-friendly React interface.
+
+## 2. Goals & Constraints
+- **Goal**: Create a responsive periodic table that displays computed properties.
+- **Constraint**: Use React 18+ and Tailwind CSS.
+- **Constraint**: Must render correctly on desktop (≥1280px).
+- **Performance**: Instant updates when switching elements.
+
+## 3. Architecture
+
+### 3.1 Component Structure
+```
+src/components/
+├── PeriodicTable/
+│   ├── PeriodicTable.tsx          # Main grid container
+│   ├── ElementCell.tsx            # Individual cell (Z, Symbol, IE)
+│   └── CategoryLegend.tsx         # Color legend
+├── ElementDatasheet/
+│   ├── ElementDatasheet.tsx       # Details panel
+│   ├── IdentityCard.tsx           # Basic info (Z, Name, Config)
+│   └── IonizationEnergyPanel.tsx  # IE vs NIST comparison
+├── common/
+│   ├── Tooltip.tsx                # Hover info
+│   └── DataTable.tsx              # Generic table component
+```
+
+### 3.2 State Management (Context)
+- **ElementContext**:
+  - `selectedZ: number | null`
+  - `setSelectedZ: (z: number) => void`
+  - `elementData: ElementData | null` (computed via `useElement`)
+
+### 3.3 Layout (Grid)
+- **CSS Grid**: 18 columns x 7 rows (plus Lanthanides/Actinides below).
+- **Responsive**:
+  - Desktop: Grid + Datasheet side-by-side.
+  - Tablet/Mobile: Stacked layout (future phase, but planned for).
+
+## 4. Implementation Details
+
+### 4.1 PeriodicTable.tsx
+- **Props**: None (uses context).
+- **Logic**:
+  - Iterates Z=1 to 118.
+  - Positions elements based on Group/Period.
+  - Handles gaps for Lanthanides/Actinides.
+  - Renders `ElementCell` for each Z.
+
+### 4.2 ElementCell.tsx
+- **Props**: `z: number`, `symbol: string`, `name: string`, `category: string`.
+- **Style**:
+  - Background color based on category (using `element-colors.css`).
+  - Border color based on prediction error (Green/Yellow/Red).
+- **Interaction**: `onClick` -> `setSelectedZ(z)`.
+
+### 4.3 ElementDatasheet.tsx
+- **Props**: None (uses context).
+- **Logic**:
+  - If `selectedZ` is null, show placeholder or instructions.
+  - If selected, render child panels passing `elementData`.
+
+### 4.4 Hooks (useElement.ts)
+- **Input**: `z: number`.
+- **Output**: `ElementData` object (memoized).
+- **Logic**: Calls `electronConfiguration(z)`, `ionizationEnergy(z)`, etc. from Engine.
+
+## 5. Styling
+- **Tailwind CSS**: Utility classes for layout and spacing.
+- **Custom CSS**: Specific grid definitions for the periodic table structure.
+- **Color Palette**: Defined in `element-colors.css` matching the design doc.
+
+## 6. Testing Strategy
+- **Component Tests**: Verify rendering of correct symbol/Z.
+- **Interaction Tests**: Click on cell updates context.
+- **Visual Regression**: Ensure grid layout is correct.

package/error.txt

@@ -0,0 +1 @@
+ENOENT: no such file or directory, open '/Users/sschepis/GDrive/prime-resonance-spectral-theory/model-explorer/package.json'

package/file_list.txt

@@ -0,0 +1,12 @@
+.ai-man
+.cursorrules
+.snapshots
+SYSTEM_MAP.md
+TECHNICAL_DESIGN_DASHBOARD.md
+TECHNICAL_DESIGN_DATASHEET.md
+TECHNICAL_DESIGN_ENGINE.md
+TECHNICAL_DESIGN_TUNER.md
+TECHNICAL_DESIGN_UI_MVP.md
+design.md
+docs
+src

package/npm_version.txt

@@ -0,0 +1 @@
+10.9.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sschepis/robodev",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "type": "module",
   "description": "Robodev: AI-powered development assistant",
   "author": "sschepis",

package/src/config.mjs

@@ -19,6 +19,7 @@ export const config = {
     temperature: parseFloat(process.env.AI_TEMPERATURE || '0.7'),
     maxTokens: parseInt(process.env.AI_MAX_TOKENS || '4096', 10),
     contextWindowSize: parseInt(process.env.AI_CONTEXT_WINDOW || '128000', 10),
+    maxTurns: parseInt(process.env.AI_MAX_TURNS || '30', 10),
   },
   
   // System Configuration

package/src/core/ai-assistant.mjs

@@ -31,6 +31,9 @@ export class MiniAIAssistant {
             generateContentStream: (req) => callProviderStream(req)
         };
 
+        // Configurable max conversation turns (defaults to config, which defaults to 30)
+        this.maxTurns = options.maxTurns || config.ai.maxTurns;
+
         // Initialize all subsystems
         this.reasoningSystem = new ReasoningSystem();
         this.customToolsManager = new CustomToolsManager();
@@ -131,7 +134,20 @@ export class MiniAIAssistant {
     }
 
     // Main function to process user input and orchestrate tool use
-    async run(userInput, isRetry = false) {
+    // @param {string} userInput - The user's input
+    // @param {boolean|Object} optionsOrIsRetry - Options object { isRetry, signal } or boolean for backwards compat
+    async run(userInput, optionsOrIsRetry = {}) {
+        // Backwards compatibility: if boolean, treat as legacy isRetry parameter
+        const options = typeof optionsOrIsRetry === 'boolean'
+            ? { isRetry: optionsOrIsRetry }
+            : optionsOrIsRetry;
+        const { isRetry = false, signal } = options;
+
+        // Check for cancellation before starting
+        if (signal?.aborted) {
+            throw new DOMException('Agent execution was cancelled', 'AbortError');
+        }
+
         // Ensure custom tools are loaded
         await this.initializeCustomTools();
         
@@ -149,9 +165,14 @@ export class MiniAIAssistant {
         }
         
         let finalResponse = null;
-        const maxTurns = 30; // Maximum conversation turns (increased for complex tasks)
+        const maxTurns = this.maxTurns;
 
         for (let i = 0; i < maxTurns; i++) {
+            // Check for cancellation at the start of each turn
+            if (signal?.aborted) {
+                throw new DOMException('Agent execution was cancelled', 'AbortError');
+            }
+
             // Show conversation turn progress
             consoleStyler.log('progress', `Processing turn ${i + 1}/${maxTurns}`, { timestamp: true });
             
@@ -248,8 +269,8 @@ export class MiniAIAssistant {
                             const stats = this.historyManager.getStats();
                             consoleStyler.log('recovery', `Session memory preserved: ${stats.messageCount} messages`, { indent: true });
                             
-                            // Recursive retry with improved prompt
-                            return await this.run(improvedPrompt, true);
+                            // Recursive retry with improved prompt (pass signal through)
+                            return await this.run(improvedPrompt, { isRetry: true, signal });
                         } else {
                             consoleStyler.log('quality', `✓ Response quality approved (${rating}/10)`);
                         }
@@ -379,7 +400,17 @@ export class MiniAIAssistant {
     }
 
     // Function to call the AI provider with streaming response.
-    async runStream(userInput, onChunk) {
+    // @param {string} userInput - The user's input
+    // @param {Function} onChunk - Callback for each chunk of streamed content
+    // @param {Object} [options] - Options object { signal }
+    async runStream(userInput, onChunk, options = {}) {
+        const { signal } = options;
+
+        // Check for cancellation before starting
+        if (signal?.aborted) {
+            throw new DOMException('Agent execution was cancelled', 'AbortError');
+        }
+
         // Ensure custom tools are loaded
         await this.initializeCustomTools();
 
@@ -391,10 +422,15 @@ export class MiniAIAssistant {
         this.reasoningSystem.predictReasoningFromInput(userInput);
 
         let reasoning = this.reasoningSystem.getSimplifiedReasoning('', {});
-        const maxTurns = 30; // Maximum conversation turns (increased for complex tasks)
+        const maxTurns = this.maxTurns;
 
         try {
             for (let i = 0; i < maxTurns; i++) {
+                // Check for cancellation at the start of each turn
+                if (signal?.aborted) {
+                    throw new DOMException('Agent execution was cancelled', 'AbortError');
+                }
+
                 consoleStyler.log('progress', `Processing turn ${i + 1}/${maxTurns}`, { timestamp: true });
 
                 const enhancedHistory = enhanceMessagesWithWorkReporting([...this.historyManager.getHistory()]);

package/src/lib/index.mjs

@@ -2,6 +2,17 @@ import { MiniAIAssistant } from '../core/ai-assistant.mjs';
 import { ConsoleStatusAdapter } from './adapters/console-status-adapter.mjs';
 import { NetworkLLMAdapter } from './adapters/network-llm-adapter.mjs';
 import { consoleStyler } from '../ui/console-styler.mjs';
+import { config } from '../config.mjs';
+
+/**
+ * Error thrown when an agent execution is cancelled via AbortSignal.
+ */
+export class CancellationError extends Error {
+    constructor(message = 'Agent execution was cancelled') {
+        super(message);
+        this.name = 'CancellationError';
+    }
+}
 
 /**
  * Main entry point for the AI Man Library.
@@ -14,24 +25,26 @@ export class AiMan {
      * @param {string} [config.workingDir] - Working directory (defaults to process.cwd())
      * @param {Object} [config.llmAdapter] - Adapter for LLM calls (defaults to NetworkLLMAdapter)
      * @param {Object} [config.statusAdapter] - Adapter for status/logging (defaults to ConsoleStatusAdapter)
+     * @param {number} [config.maxTurns] - Maximum conversation turns per execution (defaults to AI_MAX_TURNS env or 30)
      * @param {Object} [config.overrides] - Overrides for internal components (model, temperature, etc.)
      */
-    constructor(config = {}) {
-        this.workingDir = config.workingDir || process.cwd();
+    constructor(cfg = {}) {
+        this.workingDir = cfg.workingDir || process.cwd();
         
         // Initialize adapters
-        this.llmAdapter = config.llmAdapter || new NetworkLLMAdapter(config.overrides || {});
-        this.statusAdapter = config.statusAdapter || new ConsoleStatusAdapter();
+        this.llmAdapter = cfg.llmAdapter || new NetworkLLMAdapter(cfg.overrides || {});
+        this.statusAdapter = cfg.statusAdapter || new ConsoleStatusAdapter();
         
         // Configure global logger redirect if a custom status adapter is provided
         // This ensures that internal components using consoleStyler route logs through the adapter
-        if (config.statusAdapter) {
+        if (cfg.statusAdapter) {
              consoleStyler.setListener(this.statusAdapter);
         }
 
         // Initialize the core assistant with injected dependencies
         this.assistant = new MiniAIAssistant(this.workingDir, {
-            llmAdapter: this.llmAdapter
+            llmAdapter: this.llmAdapter,
+            maxTurns: cfg.maxTurns
         });
     }
 
@@ -45,9 +58,23 @@ export class AiMan {
     /**
      * Execute a high-level task
      * @param {string} task - The task description
+     * @param {Object} [options] - Execution options
+     * @param {AbortSignal} [options.signal] - AbortSignal to cancel execution
      * @returns {Promise<string>} The result of the task execution
+     * @throws {CancellationError} If execution is cancelled via signal
+     *
+     * @example
+     * const controller = new AbortController();
+     * const promise = aiMan.execute('build feature X', { signal: controller.signal });
+     * // Cancel after 60 seconds
+     * setTimeout(() => controller.abort(), 60000);
+     * try {
+     *   const result = await promise;
+     * } catch (err) {
+     *   if (err instanceof CancellationError) console.log('Cancelled');
+     * }
      */
-    async execute(task) {
+    async execute(task, options = {}) {
         // Ensure initialized
         if (!this.assistant.customToolsLoaded) {
             await this.initialize();
@@ -56,10 +83,49 @@ export class AiMan {
         this.statusAdapter.onToolStart('ai_man_execute', { task });
         
         try {
-            const result = await this.assistant.run(task);
+            const result = await this.assistant.run(task, { signal: options.signal });
             this.statusAdapter.onToolEnd('ai_man_execute', result);
             return result;
         } catch (error) {
+            // Wrap AbortError into our CancellationError for a cleaner public API
+            if (error.name === 'AbortError') {
+                const cancellation = new CancellationError(error.message);
+                this.statusAdapter.log('system', 'Agent execution was cancelled');
+                throw cancellation;
+            }
+            const errorMessage = `Execution failed: ${error.message}`;
+            this.statusAdapter.log('error', errorMessage);
+            throw error;
+        }
+    }
+
+    /**
+     * Execute a high-level task with streaming output
+     * @param {string} task - The task description
+     * @param {Function} onChunk - Callback for each chunk of streamed content
+     * @param {Object} [options] - Execution options
+     * @param {AbortSignal} [options.signal] - AbortSignal to cancel execution
+     * @returns {Promise<string>} The final result
+     * @throws {CancellationError} If execution is cancelled via signal
+     */
+    async executeStream(task, onChunk, options = {}) {
+        // Ensure initialized
+        if (!this.assistant.customToolsLoaded) {
+            await this.initialize();
+        }
+
+        this.statusAdapter.onToolStart('ai_man_execute_stream', { task });
+
+        try {
+            const result = await this.assistant.runStream(task, onChunk, { signal: options.signal });
+            this.statusAdapter.onToolEnd('ai_man_execute_stream', result);
+            return result;
+        } catch (error) {
+            if (error.name === 'AbortError') {
+                const cancellation = new CancellationError(error.message);
+                this.statusAdapter.log('system', 'Agent execution was cancelled');
+                throw cancellation;
+            }
             const errorMessage = `Execution failed: ${error.message}`;
             this.statusAdapter.log('error', errorMessage);
             throw error;
@@ -96,6 +162,9 @@ export class AiMan {
     }
 }
 
-// Re-export adapters for convenience
+// Re-export adapters and core types for convenience
 export { ConsoleStatusAdapter } from './adapters/console-status-adapter.mjs';
 export { NetworkLLMAdapter } from './adapters/network-llm-adapter.mjs';
+export { MiniAIAssistant } from '../core/ai-assistant.mjs';
+export { config } from '../config.mjs';
+export { consoleStyler } from '../ui/console-styler.mjs';

package/src/lib/interfaces.d.ts

@@ -3,11 +3,13 @@
  */
 export interface AiManConfig {
   /** The working directory for the project */
-  workingDir: string;
+  workingDir?: string;
   /** Adapter for the host LLM service */
   llmAdapter?: LLMAdapter;
   /** Adapter for status reporting */
   statusAdapter?: StatusAdapter;
+  /** Maximum conversation turns per execution (defaults to AI_MAX_TURNS env or 30) */
+  maxTurns?: number;
   /** Optional overrides for internal components */
   overrides?: {
     model?: string;
@@ -15,6 +17,14 @@ export interface AiManConfig {
   };
 }
 
+/**
+ * Options for execute() and executeStream() calls
+ */
+export interface ExecuteOptions {
+  /** AbortSignal to cancel the execution */
+  signal?: AbortSignal;
+}
+
 /**
  * Adapter interface for providing LLM capabilities
  * Conforms to OpenAI-compatible request/response structure
@@ -69,10 +79,20 @@ export interface StatusAdapter {
   onToolEnd(toolName: string, result: any): void;
 }
 
+/**
+ * Error thrown when agent execution is cancelled via AbortSignal
+ */
+export declare class CancellationError extends Error {
+  constructor(message?: string);
+  name: 'CancellationError';
+}
+
 /**
  * The main interface for the library
  */
-export interface AiManInterface {
+export declare class AiMan {
+  constructor(config?: AiManConfig);
+
   /**
    * Initialize the library
    */
@@ -80,15 +100,27 @@ export interface AiManInterface {
 
   /**
    * Execute a high-level task
-   * @param taskDescription The user's request
+   * @param task The user's request
+   * @param options Execution options including optional AbortSignal
    * @returns The final result or confirmation
+   * @throws {CancellationError} If cancelled via signal
+   */
+  execute(task: string, options?: ExecuteOptions): Promise<string>;
+
+  /**
+   * Execute a high-level task with streaming output
+   * @param task The user's request
+   * @param onChunk Callback for each chunk of streamed content
+   * @param options Execution options including optional AbortSignal
+   * @returns The final result
+   * @throws {CancellationError} If cancelled via signal
    */
-  executeTask(taskDescription: string): Promise<string>;
+  executeStream(task: string, onChunk: (chunk: string) => void, options?: ExecuteOptions): Promise<string>;
 
   /**
    * Get the current status of the project/workspace
    */
-  getProjectStatus(): Promise<any>;
+  getContext(): any;
 
   /**
    * Get the tool definition for integrating this library into an agent
@@ -96,3 +128,9 @@ export interface AiManInterface {
    */
   getToolDefinition(): object;
 }
+
+export { ConsoleStatusAdapter } from './adapters/console-status-adapter.mjs';
+export { NetworkLLMAdapter } from './adapters/network-llm-adapter.mjs';
+export { MiniAIAssistant } from '../core/ai-assistant.mjs';
+export { config } from '../config.mjs';
+export { consoleStyler } from '../ui/console-styler.mjs';

package/src_files_list.txt

@@ -0,0 +1,7 @@
+engine
+engine/constants.ts
+engine/index.ts
+engine/math.ts
+engine/resonance.ts
+engine/spectrum.ts
+engine/types.ts

package/temp_SYSTEM_MAP.md

@@ -0,0 +1,28 @@
+# System Manifest (SYSTEM_MAP.md)
+Last Updated: 2026-02-16T04:28:16.724Z
+
+## 1. Global Invariants
+| ID | Invariant | Description |
+|---|---|---|
+| INV-001 | Client-Side Computation | All physics calculations run in the browser (no server). |
+| INV-002 | Numerical Parity | TypeScript engine must match Python engine results to floating-point precision. |
+| INV-003 | Pure Functions | Computation functions must be pure for memoization. |
+| INV-004 | Color Scheme | Consistent channel-to-color mapping (s=blue, p=green, d=orange, f=red). |
+
+## 2. Feature Registry
+| Feature ID | Name | Status | Phase | Lock Level | Priority | Dependencies |
+|---|---|---|---|---|---|---|
+| FEAT-ENGINE | Computation Engine | Active | Design | None | High | - |
+| FEAT-UI-MVP | Basic Periodic Table (MVP) | Active | Design | None | High | FEAT-ENGINE |
+| FEAT-DATASHEET | Element Datasheet | Pending | Discovery | None | Medium | FEAT-UI-MVP |
+| FEAT-DASHBOARD | Global Dashboard | Pending | Discovery | None | Low | FEAT-DATASHEET |
+| FEAT-TUNER | Parameter Tuner | Pending | Discovery | None | Low | FEAT-ENGINE |
+
+## 3. Dependency Graph
+- FEAT-UI-MVP depends on FEAT-ENGINE
+- FEAT-DATASHEET depends on FEAT-UI-MVP
+- FEAT-DASHBOARD depends on FEAT-DATASHEET
+- FEAT-TUNER depends on FEAT-ENGINE
+
+## 4. State Snapshots
+- [2026-02-16T04:28:16.725Z] Initial State Created (bootstrapped from design document)