cognitive-kit 1.0.0-alpha.1 → 1.0.0-alpha.3

package/README.md

@@ -1,16 +1,67 @@
 # cognitive-kit
 
-Pluggable cognitive layer — embeddable MCP server with 27+ tools for reasoning, research, planning, creativity, reflection, security, knowledge, analysis, agency orchestration, and adaptive pipelines.
+**Pluggable cognitive layer** — embeddable MCP server with 31+ tools for reasoning, research, planning, creativity, reflection, security, knowledge, analysis, agency orchestration, and adaptive pipelines. Zero external infrastructure required.
 
-## Quick Start
+```
+npm i cognitive-kit
+npx cognitive-kit
+```
+
+---
+
+## Architecture
+
+```
+                    CognitiveKit
+                   /    |    |    |     \
+          MCP Server  Guardian  Agency  Forge  Federation
+              |        Gate    Orch.   Registry  Manager
+          ToolRegistry   |       |        |         |
+        (31 tools)  Sovereignty Adaptive Pattern  SSE + Client
+                    +Firewall Pipeline Detector  Multi-Kit
+                    +State    +8 Agents +Forger
+                     Guardian
+```
+
+### Core Components
+
+| Component | Description |
+|-----------|-------------|
+| **MCP Server** | Model Context Protocol server (v2024-11-05). Supports stdio, SSE, and Direct transports |
+| **Guardian Gate** | Middleware that wraps every tool call: sovereignty validation → firewall → state check |
+| **Agency Orchestrator** | Adaptive pipeline that selects agents and phases dynamically based on objective analysis |
+| **Skill Forger** | Detects usage patterns and auto-generates new skills |
+| **Federation Manager** | Connects multiple Cognitive Kit instances via SSE protocol |
+
+### 31 MCP Tools
+
+| Category | Tools |
+|----------|-------|
+| **Cognitive** (5) | `cognitive_reason`, `cognitive_research`, `cognitive_plan`, `cognitive_create`, `cognitive_reflect` |
+| **Security** (9) | `security_gate`, `ethics_audit`, `integrity_ledger`, `threat_mapper`, `red_team`, `blast_radius`, `guardian_status`, `guardian_freeze`, `guardian_unfreeze` |
+| **Knowledge** (3) | `memory_vam`, `knowledge_evolve`, `context_synth` |
+| **Analysis** (4) | `code_archaeologist`, `sentiment_adapter`, `consensus_engine`, `execution_flow` |
+| **Agency** (4) | `swarm_orchestrator`, `meta_orchestrator`, `subagent_protocol`, `agency_execute` |
+| **Federation** (4) | `federation_status`, `federation_connect`, `federation_execute`, `federation_disconnect` |
+| **Host** (2+) | `fs_read`, `fs_write`, `fs_list`, `fs_stat`, `pg_query`, `pg_schema`, `vscode_read_file`, `vscode_get_selection` |
+
+---
+
+## Installation
+
+```bash
+npm install cognitive-kit
+```
+
+### Quick Start (MCP Server)
 
 ```bash
 npx cognitive-kit
 ```
 
-Connect any MCP client (VS Code, Cursor, Claude Desktop, custom) via stdio.
+Connects to any MCP client (VS Code, Cursor, Claude Desktop, custom) via stdio.
 
-## Usage as Library
+### Quick Start (Library)
 
 ```typescript
 import { CognitiveKit } from 'cognitive-kit';
@@ -19,84 +70,100 @@ const kit = new CognitiveKit({
   host: { type: 'cli', name: 'My App', capabilities: ['filesystem'] },
   storage: { type: 'memory' },
   transport: { type: 'stdio' },
-  sovereignty: { hostId: 'my-host', hostName: 'My App' },
+  sovereignty: { hostId: 'my-app', hostName: 'My App' },
 });
 
 await kit.start();
+// 31 MCP tools ready
 ```
 
-## Tools (27)
-
-### Cognitive
-- `cognitive_reason` — Deductive, inductive, abductive, counterfactual logic
-- `cognitive_research` — Multi-perspective analysis (architect, guardian, executor, strategic)
-- `cognitive_plan` — 8-phase ARM planning pipeline
-- `cognitive_create` — Divergent, convergent, analogical, random ideation
-- `cognitive_reflect` — Meta-reflection, intent drift detection, reconciliation
-
-### Security & Ethics
-- `security_gate` — Zero-trust payload evaluation (SQLi, XSS, path traversal, secrets)
-- `ethics_audit` — Utilitarian, deontological, virtue ethics scoring
-- `integrity_ledger` — Immutable audit trail with cryptographic seals
-- `threat_mapper` — STRIDE-based threat modeling
-- `red_team` — Adversarial simulation across attack vectors
-- `blast_radius` — Failure propagation and impact analysis
-
-### Knowledge & Memory
-- `memory_vam` — Associative memory with store/recall/search/associate
-- `knowledge_evolve` — Knowledge graph gap analysis and evolution paths
-- `context_synth` — Multi-source context fusion and conflict resolution
-
-### Analysis
-- `code_archaeologist` — Structural patterns, complexity, anti-patterns, dependencies
-- `sentiment_adapter` — Multi-dimensional sentiment, tone, emotion analysis
-- `consensus_engine` — 5 models: unanimous, majority, supermajority, weighted, lazy
-- `execution_flow` — Process decomposition, critical path, bottleneck detection
-
-### Agency
-- `swarm_orchestrator` — Multi-agent swarm with role assignment
-- `meta_orchestrator` — Recursive orchestration at configurable depth
-- `subagent_protocol` — Hierarchical delegation with sovereignty propagation
-- `agency_execute` — Adaptive pipeline (auto-selects phases + agents from objectives)
-
-### Guardian
-- `guardian_status` — System metrics, firewall stats, sovereignty operations
-- `guardian_freeze` — Emergency stop (requires sovereignty ≥0.9)
-- `guardian_unfreeze` — Resume operations
-
-### Forge
-- `skill_forge` — Auto-generate skills from detected usage patterns
-- `skill_list_forged` — List all forged skills
+---
 
-## Architecture
+## MCP Integration Guides
 
+### VS Code
+
+Add to your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "cognitive-kit": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "vscode-${workspaceFolderBasename}",
+        "KIT_HOST_NAME": "${workspaceFolderBasename}",
+        "KIT_SOVEREIGN_KEY": ""
+      }
+    }
+  }
+}
 ```
-                    CognitiveKit
-                   /    |    |    \
-          MCP Server  Guardian  Agency  Forge
-              |        Gate    Orch.   Registry
-          ToolRegistry   |       |        |
-        (27 tools)  Sovereignty Adaptive Pattern
-                     +Firewall Pipeline Detector
-                     +State    +8 Agents +Forger
-                      Guardian
+
+### Cursor
+
+Settings → MCP → Add Server:
+
+```
+Name: cognitive-kit
+Type: command
+Command: npx cognitive-kit
+Environment variables:
+  KIT_HOST_ID=cursor
+  KIT_HOST_NAME=my-project
 ```
 
-## Host Adapters
+### Claude Desktop
+
+Edit `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "cognitive-kit": {
+      "command": "npx",
+      "args": ["cognitive-kit"],
+      "env": {
+        "KIT_HOST_ID": "claude-desktop",
+        "KIT_HOST_NAME": "Claude Desktop"
+      }
+    }
+  }
+}
+```
 
-- **CLI** (default): stdio MCP server
-- **VS Code**: read files, get editor selection, execute commands
-- **Generic**: bring your own `HostAdapter`
+### Node.js (Direct Embedding)
 
 ```typescript
+import { CognitiveKit, FileSystemAdapter } from 'cognitive-kit';
+
 const kit = new CognitiveKit({
-  host: new MyCustomAdapter(),
-  transport: { type: 'sse', port: 3100 },
+  host: new FileSystemAdapter('./workspace', { allowWrite: true }),
+  storage: { type: 'sqlite', path: './.kit.db' },
+  transport: { type: 'direct' },
+});
+
+await kit.initialize();
+
+// Call tools directly
+const result = await kit['toolRegistry'].execute('cognitive_reason', {
+  problem: 'Analyze this code for potential issues',
+  mode: 'logical',
+}, {
+  identity: { actorId: 'user', actorType: 'user', sovereignty: 0.9, permissions: ['execute'] },
+  host: { type: 'cli', name: 'test', capabilities: [] },
+  memory: kit['memory'],
 });
 ```
 
+---
+
 ## Configuration
 
+### KitConfig
+
 ```typescript
 interface KitConfig {
   host: HostAdapter | HostProfile;
@@ -107,4 +174,170 @@ interface KitConfig {
 }
 ```
 
-Environment variables: `KIT_HOST_ID`, `KIT_HOST_NAME`, `KIT_SOVEREIGN_KEY`.
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `KIT_HOST_ID` | `cli-host` | Unique identifier for this kit instance |
+| `KIT_HOST_NAME` | `Cognitive Kit CLI` | Human-readable host name |
+| `KIT_SOVEREIGN_KEY` | - | Key for host-level sovereignty verification |
+| `KIT_STORAGE_PATH` | `./.cognitive-kit.db` | SQLite database path |
+| `KIT_TRANSPORT` | `stdio` | Transport type: `stdio` or `sse` |
+| `KIT_FEDERATION_PORT` | `4200` | Port for federation SSE server |
+| `KIT_FEDERATION_PEERS` | - | Comma-separated peer URLs |
+| `KIT_FS_ROOT` | `cwd` | Filesystem adapter root path |
+| `KIT_FS_ALLOW_WRITE` | `false` | Enable file write operations |
+| `KIT_PG_CONNECTION` | - | PostgreSQL connection string |
+
+---
+
+## Host Adapters
+
+| Adapter | Description | Tools |
+|---------|-------------|-------|
+| **FileSystemAdapter** | Read/write/list files in a root directory | `fs_read`, `fs_write`, `fs_list`, `fs_stat` |
+| **PostgresAdapter** | Query databases, inspect schemas | `pg_query`, `pg_schema`, `pg_list_tables`, `pg_describe` |
+| **VSCodeAdapter** | VS Code editor integration | `vscode_read_file`, `vscode_get_selection`, `vscode_workspace_info` |
+| **Generic** | Minimal adapter for any host type | (no host-specific tools) |
+
+```typescript
+// Filesystem
+const kit = new CognitiveKit({
+  host: new FileSystemAdapter('./data', { allowWrite: true }),
+});
+
+// PostgreSQL
+const kit = new CognitiveKit({
+  host: new PostgresAdapter({ connectionString: 'postgres://...' }),
+});
+```
+
+---
+
+## Agency System
+
+The adaptive pipeline automatically selects phases and agents based on the objective.
+
+```typescript
+const mission = await kit.executeAgency(
+  'Design and implement a secure authentication service',
+  { mode: 'adaptive' }
+);
+
+console.log(mission.status);     // 'completed'
+console.log(mission.phases);     // ['create', 'architect', 'security']
+console.log(mission.agents);     // [{ name: 'Guardian', role: '...' }, ...]
+console.log(mission.synergyScore); // 0.85
+```
+
+### Phases
+
+delimit → collect → extract → infer → critical → synergy → architect → validate → research → reason → plan → create → reflect → security → ethics → consensus → execute
+
+### Agents
+
+Architect, Guardian, Executor, Strategist, Analyst, Innovator, Validator, Coordinator
+
+### Modes
+
+`sequential` | `parallel` | `hybrid` | `adaptive`
+
+---
+
+## Guardian Gate
+
+Every tool call passes through the Guardian Gate for security validation.
+
+```
+Caller → Sovereignty Check → Firewall (8 rules) → State Check → Tool Execution → Audit
+```
+
+```typescript
+// Check system status
+const metrics = kit.guardian.stateGuardian.getMetrics();
+console.log(metrics.totalToolCalls);   // 142
+console.log(metrics.errorRate);        // 0.02
+
+// Freeze in emergency (requires sovereignty ≥ 0.9)
+await kit.guardian.stateGuardian.freeze('Security breach detected');
+
+// Unfreeze
+kit.guardian.stateGuardian.unfreeze();
+```
+
+### Firewall Rules
+
+| ID | Pattern | Severity |
+|----|---------|----------|
+| FW-001 | System command injection | `block` |
+| FW-002 | Filesystem escape | `block` |
+| FW-003 | API key/secret leak | `block` |
+| FW-004 | Mass data access | `flag` |
+| FW-005 | Privilege escalation | `block` |
+| FW-008 | Arbitrary code execution | `block` |
+
+---
+
+## Skill Forging
+
+The kit detects usage patterns and auto-generates new skills.
+
+```typescript
+// Manual forge
+const newSkills = kit.forge.forgeFromPatterns(true);
+for (const s of newSkills) {
+  console.log(`${s.name}: ${s.toolsRequired.join(', ')}`);
+}
+
+// Auto-forge runs every 120 seconds when patterns reach threshold
+```
+
+---
+
+## Federation
+
+Connect multiple kit instances together.
+
+```typescript
+// Kit A starts federation server
+const kitA = new CognitiveKit({ transport: { type: 'sse', port: 3100 } });
+
+// Kit B connects to Kit A
+const kitB = new CognitiveKit({ transport: { type: 'stdio' } });
+await kitB.federationManager.connectTo('http://localhost:3100');
+
+// Execute tools remotely
+const result = await kitB.federationManager.executeOnPeer(
+  'http://localhost:3100',
+  'cognitive_reason',
+  { problem: 'Analyze distributed system', mode: 'logical' }
+);
+```
+
+---
+
+## Examples
+
+See full examples in the repository:
+
+- [Basic MCP Server](docs/examples/mcp-server.md)
+- [Library Embedding](docs/examples/library-embed.md)
+- [PostgreSQL Knowledge Explorer](docs/examples/pg-explorer.md)
+- [Federation Multi-Kit](docs/examples/federation.md)
+- [Custom Host Adapter](docs/examples/custom-adapter.md)
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/GaboBase/TODO-Cognitive.git
+cd packages/cognitive-kit
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT © GaboBase

package/dist/cli.d.ts

@@ -1 +1,2 @@
+#!/usr/bin/env node
 export {};

package/dist/cli.js

@@ -1,3 +1,4 @@
+#!/usr/bin/env node
 import { CognitiveKit } from './Kit.js';
 const kit = new CognitiveKit({
     host: {

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC;IAC3B,IAAI,EAAE;QACJ,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,mBAAmB;QACtD,YAAY,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC;KACzC;IACD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,qBAAqB,EAAE;IACxF,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE;IAC1E,WAAW,EAAE;QACX,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,UAAU;QAC7C,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,mBAAmB;QAC1D,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;KACvC;CACF,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;IAC9B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IAC/B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;IAC7B,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAExC,MAAM,GAAG,GAAG,IAAI,YAAY,CAAC;IAC3B,IAAI,EAAE;QACJ,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,mBAAmB;QACtD,YAAY,EAAE,CAAC,YAAY,EAAE,UAAU,CAAC;KACzC;IACD,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,qBAAqB,EAAE;IACxF,SAAS,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE;IAC1E,WAAW,EAAE;QACX,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,UAAU;QAC7C,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,mBAAmB;QAC1D,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;KACvC;CACF,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;IAC9B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE;IAC/B,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;IACjC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;IAC7B,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;AACvD,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC;IACH,MAAM,GAAG,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC;AAAC,OAAO,GAAG,EAAE,CAAC;IACb,OAAO,CAAC,KAAK,CAAC,kCAAkC,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC5F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC"}

package/dist/host/adapters/FileSystemAdapter.d.ts

@@ -0,0 +1,22 @@
+import type { HostAdapter } from '../HostAdapter.js';
+import type { HostProfile, ToolDefinition, HostCapability } from '../../types.js';
+export declare class FileSystemAdapter implements HostAdapter {
+    private rootPath;
+    private allowWrite;
+    private allowDelete;
+    constructor(rootPath?: string, options?: {
+        allowWrite?: boolean;
+        allowDelete?: boolean;
+    });
+    get profile(): HostProfile;
+    initialize(): Promise<void>;
+    shutdown(): Promise<void>;
+    getHostTools(): ToolDefinition[];
+    getCapabilities(): HostCapability[];
+    private resolvePath;
+    private createReadTool;
+    private createWriteTool;
+    private createListTool;
+    private createStatTool;
+    private createDeleteTool;
+}

package/dist/host/adapters/FileSystemAdapter.js

@@ -0,0 +1,203 @@
+import { access, readFile, writeFile, readdir, mkdir, unlink, stat } from 'node:fs/promises';
+import { resolve, extname, dirname } from 'node:path';
+export class FileSystemAdapter {
+    rootPath;
+    allowWrite;
+    allowDelete;
+    constructor(rootPath, options) {
+        this.rootPath = rootPath ?? process.env.KIT_FS_ROOT ?? process.cwd();
+        this.allowWrite = options?.allowWrite ?? (process.env.KIT_FS_ALLOW_WRITE === 'true');
+        this.allowDelete = options?.allowDelete ?? (process.env.KIT_FS_ALLOW_DELETE === 'true');
+    }
+    get profile() {
+        return {
+            type: 'cli',
+            name: 'FileSystem Adapter',
+            version: '1.0.0',
+            capabilities: this.getCapabilities(),
+            metadata: {
+                rootPath: this.rootPath,
+                allowWrite: String(this.allowWrite),
+                allowDelete: String(this.allowDelete),
+            },
+        };
+    }
+    async initialize() {
+        try {
+            await access(this.rootPath);
+            console.error(`[fs-adapter] Root: ${this.rootPath} (write: ${this.allowWrite}, delete: ${this.allowDelete})`);
+        }
+        catch {
+            console.error(`[fs-adapter] Warning: root path does not exist: ${this.rootPath}`);
+        }
+    }
+    async shutdown() { }
+    getHostTools() {
+        return [
+            this.createReadTool(),
+            this.createListTool(),
+            this.createStatTool(),
+            ...(this.allowWrite ? [this.createWriteTool()] : []),
+            ...(this.allowDelete ? [this.createDeleteTool()] : []),
+        ];
+    }
+    getCapabilities() {
+        const caps = ['filesystem'];
+        if (this.allowWrite)
+            caps.push('filesystem');
+        return caps;
+    }
+    resolvePath(userPath) {
+        const sanitized = userPath.replace(/\.\.(\/|\\)/g, '');
+        return resolve(this.rootPath, sanitized);
+    }
+    createReadTool() {
+        return {
+            id: 'fs_read',
+            name: 'Read File',
+            description: 'Read the contents of a file. Returns text content and metadata.',
+            inputSchema: { path: { type: 'string', description: 'File path relative to workspace root' } },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                const userPath = String(params.path || '');
+                if (!userPath)
+                    return { success: false, data: null, error: 'path is required' };
+                try {
+                    const fullPath = this.resolvePath(userPath);
+                    const content = await readFile(fullPath, 'utf-8');
+                    const meta = await stat(fullPath);
+                    return {
+                        success: true,
+                        data: {
+                            path: userPath,
+                            fullPath,
+                            content,
+                            size: content.length,
+                            lines: content.split('\n').length,
+                            ext: extname(fullPath),
+                            modifiedAt: meta.mtime.toISOString(),
+                        },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Cannot read: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createWriteTool() {
+        return {
+            id: 'fs_write',
+            name: 'Write File',
+            description: 'Write content to a file. Creates directories if needed.',
+            inputSchema: {
+                path: { type: 'string', description: 'File path relative to workspace root' },
+                content: { type: 'string', description: 'Content to write' },
+            },
+            sovereignty: 0.6,
+            category: 'host',
+            handler: async (params, _ctx) => {
+                const userPath = String(params.path || '');
+                const content = String(params.content || '');
+                if (!userPath)
+                    return { success: false, data: null, error: 'path is required' };
+                try {
+                    const fullPath = this.resolvePath(userPath);
+                    await mkdir(dirname(fullPath), { recursive: true });
+                    await writeFile(fullPath, content, 'utf-8');
+                    return { success: true, data: { path: userPath, bytesWritten: Buffer.byteLength(content, 'utf-8') } };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Cannot write: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createListTool() {
+        return {
+            id: 'fs_list',
+            name: 'List Directory',
+            description: 'List files and directories at a path. Shows names, types, and sizes.',
+            inputSchema: { path: { type: 'string', description: 'Directory path (default: root)' } },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                const userPath = String(params.path || '');
+                const target = userPath ? this.resolvePath(userPath) : this.rootPath;
+                try {
+                    const entries = await readdir(target, { withFileTypes: true });
+                    const items = await Promise.all(entries.map(async (entry) => {
+                        const fullPath = resolve(target, entry.name);
+                        try {
+                            const s = await stat(fullPath);
+                            return { name: entry.name, type: entry.isDirectory() ? 'dir' : 'file', size: s.size, modifiedAt: s.mtime.toISOString() };
+                        }
+                        catch {
+                            return { name: entry.name, type: entry.isDirectory() ? 'dir' : 'file', size: 0, modifiedAt: null };
+                        }
+                    }));
+                    return {
+                        success: true,
+                        data: { path: userPath || '.', fullPath: target, items, total: items.length },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Cannot list: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createStatTool() {
+        return {
+            id: 'fs_stat',
+            name: 'File Stats',
+            description: 'Get detailed information about a file or directory.',
+            inputSchema: { path: { type: 'string', description: 'File or directory path' } },
+            category: 'host',
+            handler: async (params, _ctx) => {
+                const userPath = String(params.path || '');
+                if (!userPath)
+                    return { success: false, data: null, error: 'path is required' };
+                try {
+                    const fullPath = this.resolvePath(userPath);
+                    const s = await stat(fullPath);
+                    return {
+                        success: true,
+                        data: {
+                            path: userPath, fullPath, size: s.size,
+                            isDirectory: s.isDirectory(), isFile: s.isFile(),
+                            created: s.birthtime.toISOString(), modified: s.mtime.toISOString(),
+                            permissions: s.mode.toString(8).slice(-3),
+                        },
+                    };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Cannot stat: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+    createDeleteTool() {
+        return {
+            id: 'fs_delete',
+            name: 'Delete File',
+            description: 'Permanently delete a file. Use with caution.',
+            inputSchema: { path: { type: 'string', description: 'File path to delete' } },
+            sovereignty: 0.8,
+            category: 'host',
+            handler: async (params, _ctx) => {
+                const userPath = String(params.path || '');
+                if (!userPath)
+                    return { success: false, data: null, error: 'path is required' };
+                try {
+                    const fullPath = this.resolvePath(userPath);
+                    await unlink(fullPath);
+                    return { success: true, data: { path: userPath, deleted: true } };
+                }
+                catch (err) {
+                    return { success: false, data: null, error: `Cannot delete: ${err instanceof Error ? err.message : String(err)}` };
+                }
+            },
+        };
+    }
+}
+//# sourceMappingURL=FileSystemAdapter.js.map

package/dist/host/adapters/FileSystemAdapter.js.map

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