@bolloon/bolloon-agent 0.1.0 → 0.1.1

package/docs/plans/2026-05-16-chat-ui-design.md

@@ -1,86 +0,0 @@
-# Bolloon Agent 对话界面设计
-
-## 概述
-
-为 Bolloon Agent 设计一个混合模式（终端+浏览器）的对话界面，用户可在浏览器中与 AI Agent 对话。
-
-## 交互流程
-
-1. 终端运行 `npm run dev` 启动
-2. 终端显示启动进度，浏览器自动打开 Web 界面
-3. 用户在浏览器中发送消息
-4. 后端处理并通过 P2P 网络通信
-5. AI 回复显示在浏览器中
-
-## 终端显示
-
-```
-🤖 Bolloon Agent
-
-  身份生成...  ✓
-  P2P连接...  ✓
-  HTTP服务...  ✓
-
-  🌐 浏览器已打开 → http://localhost:54188
-```
-
-## Web 界面设计
-
-### 布局
-- 固定高度视口，全屏显示
-- 顶部标题栏
-- 中部消息区域（可滚动）
-- 底部输入框
-
-### 消息样式
-- 用户消息：右对齐，蓝色/深色背景
-- AI消息：左对齐，浅色背景
-- 时间戳在消息下方（小字灰色）
-
-### 视觉风格
-- 简洁对话流，无多余装饰
-- 适合纯对话场景
-- 深色/浅色主题可扩展
-
-## 技术方案
-
-### 目录结构
-```
-src/
-  web/
-    index.html      # 极简HTML
-    style.css       # 对话样式
-    client.js       # 前端JS
-  server.ts         # Express + SSE后端
-```
-
-### 端口
-- 默认 3000
-- 可通过 PORT 环境变量配置
-
-### API
-- `GET /` - 返回 Web 界面
-- `GET /events` - SSE 流式事件
-- `POST /message` - 发送消息
-
-## 消息格式
-
-### 请求
-```json
-POST /message
-{ "text": "读取 想法.md" }
-```
-
-### 响应 (SSE)
-```
-data: {"type":"user","content":"读取 想法.md"}
-data: {"type":"ai","content":"📝 摘要..."}
-data: {"type":"done"}
-```
-
-## 状态
-
-- [ ] 创建 Web 静态文件
-- [ ] 实现 Express + SSE 后端
-- [ ] 集成到 main.ts
-- [ ] 测试完整流程

package/docs/plans/2026-05-16-constraint-runtime-design.md

@@ -1,106 +0,0 @@
-# ConstraintRuntime Design
-
-## Overview
-
-A TypeScript implementation that replicates and extends the py-bolloon architecture for AI constraint management, deep thinking, and multi-agent coordination.
-
-## Architecture
-
-```
-constraint-runtime/
-├── src/
-│   ├── index.ts                    # Main entry
-│   ├── constraint/                 # Permission & resource constraints
-│   │   ├── index.ts
-│   │   ├── permission.ts           # Tool allowlist/denylist
-│   │   └── budget.ts               # Token/turn budget tracking
-│   ├── thinking/                   # Deep thinking engine
-│   │   ├── index.ts
-│   │   ├── engine.ts               # Multi-step reasoning
-│   │   └── reflection.ts           # Self-reflection loops
-│   ├── agent/                      # Multi-agent coordination
-│   │   ├── index.ts
-│   │   ├── coordinator.ts          # Task distribution
-│   │   ├── agent-pool.ts           # Agent lifecycle
-│   │   └── result-aggregator.ts    # Result merging
-│   ├── skills/                     # Skill registry
-│   │   ├── index.ts
-│   │   └── skill-registry.ts
-│   ├── runtime/                    # Core runtime
-│   │   ├── index.ts
-│   │   ├── session.ts              # Session management
-│   │   └── turn-engine.ts         # Turn loop execution
-│   └── reference_data/            # Mirrored snapshots
-│       └── subsystems/
-└── package.json
-```
-
-## Core Components
-
-### 1. ConstraintLayer
-
-- **ToolPermissionContext**: allowlist/denylist for tools
-- **BudgetTracker**: token budget, max turns, compact_after_turns
-- **PermissionDenial**: reason when tool access denied
-
-### 2. DeepThinkingEngine
-
-- Configurable `maxDepth` (1-10 steps)
-- Chain-of-thought reasoning with reflection
-- `think(prompt) → ThinkResult` with intermediate steps
-
-### 3. AgentCoordinator
-
-- **TaskSplitter**: breaks prompt into parallel subtasks
-- **AgentPool**: manages agent lifecycle
-- **ResultAggregator**: merges parallel results
-- Parallel dispatch pattern
-
-### 4. SkillRegistry
-
-- Loads skills from `skills/` directory
-- Skill = { name, description, execute(params) }
-- Compatible with py-bolloon skill snapshot format
-
-### 5. Runtime
-
-- **Session**: maintains context, history, state
-- **TurnEngine**: executes turns with constraint checking
-- Mirrors py-bolloon `PortRuntime` pattern
-
-## Data Flow
-
-```
-User Prompt
-    ↓
-[ConstraintLayer] ← permission check
-    ↓
-[DeepThinkingEngine] ← multi-step reasoning (optional)
-    ↓
-[AgentCoordinator] ← task split
-    ↓
-[AgentPool] ← parallel execution
-    ↓
-[ResultAggregator]
-    ↓
-[SkillRegistry] ← skill enrichment
-    ↓
-Response + Updated Session
-```
-
-## CLI Commands (mirrors py-bolloon)
-
-- `summary` - render markdown summary
-- `manifest` - print module manifest
-- `tool-pool` - show tool constraints
-- `bootstrap` - build session
-- `turn-loop` - run turn loop
-- `think` - run deep thinking mode
-- `dispatch` - parallel agent dispatch
-
-## Implementation Notes
-
-- Follow py-bolloon module mirroring pattern
-- Use `PortingModule` model for tools/commands
-- Preserve `QueryEnginePort` patterns
-- TypeScript-first with strict mode

package/docs/plans/2026-05-16-constraint-runtime-implementation.md

@@ -1,441 +0,0 @@
-# ConstraintRuntime Implementation Plan
-
-> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
-
-**Goal:** Create a TypeScript implementation that replicates py-bolloon architecture with AI constraint management, deep thinking, and multi-agent coordination.
-
-**Architecture:** Module mirroring pattern (py-bolloon style) with TypeScript-first implementation. Core components: ConstraintLayer, DeepThinkingEngine, AgentCoordinator, SkillRegistry.
-
-**Tech Stack:** TypeScript, Node.js, strict mode
-
----
-
-## Task 1: Project Scaffold
-
-**Files:**
-- Create: `src/constraint-runtime/index.ts`
-- Create: `src/constraint-runtime/package.json`
-- Create: `src/constraint-runtime/tsconfig.json`
-
-**Step 1: Create project structure**
-
-```bash
-mkdir -p src/constraint-runtime/{src/{constraint,thinking,agent,skills,runtime,reference_data/subsystems},tests}
-```
-
-**Step 2: Create package.json**
-
-```json
-{
-  "name": "@bolloon/constraint-runtime",
-  "version": "0.1.0",
-  "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc",
-    "test": "vitest run"
-  }
-}
-```
-
-**Step 3: Create tsconfig.json**
-
-```json
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "NodeNext",
-    "moduleResolution": "NodeNext",
-    "strict": true,
-    "outDir": "dist",
-    "rootDir": "src"
-  },
-  "include": ["src/**/*"]
-}
-```
-
----
-
-## Task 2: Core Models
-
-**Files:**
-- Create: `src/constraint-runtime/src/models.ts`
-
-**Step 1: Create models**
-
-```typescript
-export interface PortingModule {
-  name: string;
-  responsibility: string;
-  source_hint: string;
-  status: 'mirrored' | 'ported' | 'pending';
-}
-
-export interface PermissionDenial {
-  tool_name: string;
-  reason: string;
-}
-
-export interface UsageSummary {
-  input_tokens: number;
-  output_tokens: number;
-}
-
-export interface TurnResult {
-  prompt: string;
-  output: string;
-  matched_commands: string[];
-  matched_tools: string[];
-  permission_denials: PermissionDenial[];
-  usage: UsageSummary;
-  stop_reason: string;
-}
-```
-
----
-
-## Task 3: ConstraintLayer
-
-**Files:**
-- Create: `src/constraint-runtime/src/constraint/index.ts`
-- Create: `src/constraint-runtime/src/constraint/permission.ts`
-- Create: `src/constraint-runtime/src/constraint/budget.ts`
-
-**Step 1: Create permission context**
-
-```typescript
-export class ToolPermissionContext {
-  private denyTools: Set<string>;
-  private denyPrefixes: string[];
-
-  static fromIterables(denyTools: string[] = [], denyPrefixes: string[] = []): ToolPermissionContext {
-    return new ToolPermissionContext(new Set(denyTools.map(t => t.toLowerCase())), denyPrefixes);
-  }
-
-  blocks(name: string): boolean {
-    const lower = name.toLowerCase();
-    if (this.denyTools.has(lower)) return true;
-    return this.denyPrefixes.some(p => lower.startsWith(p.toLowerCase()));
-  }
-}
-```
-
-**Step 2: Create budget tracker**
-
-```typescript
-export class BudgetTracker {
-  constructor(
-    public maxBudgetTokens: number = 2000,
-    public maxTurns: number = 8,
-    public compactAfterTurns: number = 12
-  ) {}
-
-  addTurn(inputTokens: number, outputTokens: number): UsageSummary {
-    return { input_tokens: inputTokens, output_tokens: outputTokens };
-  }
-
-  isBudgetExceeded(usage: UsageSummary): boolean {
-    return usage.input_tokens + usage.output_tokens > this.maxBudgetTokens;
-  }
-}
-```
-
----
-
-## Task 4: DeepThinkingEngine
-
-**Files:**
-- Create: `src/constraint-runtime/src/thinking/index.ts`
-- Create: `src/constraint-runtime/src/thinking/engine.ts`
-- Create: `src/constraint-runtime/src/thinking/reflection.ts`
-
-**Step 1: Create thinking engine**
-
-```typescript
-export interface ThinkStep {
-  step: number;
-  thought: string;
-  reflection?: string;
-  improvement?: string;
-}
-
-export interface ThinkResult {
-  originalPrompt: string;
-  steps: ThinkStep[];
-  finalOutput: string;
-  depth: number;
-}
-
-export class DeepThinkingEngine {
-  constructor(private maxDepth: number = 3) {}
-
-  async think(prompt: string): Promise<ThinkResult> {
-    const steps: ThinkStep[] = [];
-    let current = prompt;
-
-    for (let i = 0; i < this.maxDepth; i++) {
-      const thought = await this.generateThought(current, i);
-      const reflection = await this.reflect(thought, current);
-
-      steps.push({
-        step: i + 1,
-        thought,
-        reflection: reflection.question,
-        improvement: reflection.improvement
-      });
-
-      if (reflection.improvement) {
-        current = reflection.improvement;
-      }
-    }
-
-    return {
-      originalPrompt: prompt,
-      steps,
-      finalOutput: steps[steps.length - 1]?.improvement ?? current,
-      depth: this.maxDepth
-    };
-  }
-
-  private async generateThought(prompt: string, step: number): Promise<string> {
-    return `[Step ${step + 1}] Thinking about: ${prompt}`;
-  }
-
-  private async reflect(thought: string, original: string): Promise<{ question: string; improvement?: string }> {
-    return {
-      question: `Is "${thought}" the best approach?`,
-      improvement: step < this.maxDepth - 1 ? `${thought} (refined)` : undefined
-    };
-  }
-}
-```
-
----
-
-## Task 5: AgentCoordinator
-
-**Files:**
-- Create: `src/constraint-runtime/src/agent/index.ts`
-- Create: `src/constraint-runtime/src/agent/coordinator.ts`
-- Create: `src/constraint-runtime/src/agent/agent-pool.ts`
-- Create: `src/constraint-runtime/src/agent/result-aggregator.ts`
-
-**Step 1: Create coordinator**
-
-```typescript
-import { DeepThinkingEngine } from '../thinking/engine.js';
-
-export interface SubTask {
-  id: string;
-  description: string;
-  priority: number;
-}
-
-export interface AgentResult {
-  taskId: string;
-  output: string;
-  success: boolean;
-  metadata?: Record<string, unknown>;
-}
-
-export class AgentCoordinator {
-  private engine: DeepThinkingEngine;
-
-  constructor(maxDepth: number = 3) {
-    this.engine = new DeepThinkingEngine(maxDepth);
-  }
-
-  async dispatch(prompt: string, parallelCount: number = 3): Promise<AgentResult[]> {
-    const tasks = this.splitTask(prompt, parallelCount);
-    const agents = Array.from({ length: Math.min(tasks.length, parallelCount) }, (_, i) => ({
-      id: `agent-${i}`,
-      execute: (task: SubTask) => this.executeTask(task)
-    }));
-
-    const results = await Promise.all(
-      tasks.map(task =>
-        agents[task.id.charCodeAt(task.id.length - 1) % agents.length].execute(task)
-      )
-    );
-
-    return this.aggregate(results);
-  }
-
-  private splitTask(prompt: string, count: number): SubTask[] {
-    const words = prompt.split(' ');
-    const chunkSize = Math.ceil(words.length / count);
-    const chunks: SubTask[] = [];
-
-    for (let i = 0; i < count; i++) {
-      const chunk = words.slice(i * chunkSize, (i + 1) * chunkSize).join(' ');
-      if (chunk) {
-        chunks.push({
-          id: `task-${i}`,
-          description: chunk,
-          priority: i
-        });
-      }
-    }
-    return chunks;
-  }
-
-  private async executeTask(task: SubTask): Promise<AgentResult> {
-    const thinkResult = await this.engine.think(task.description);
-    return {
-      taskId: task.id,
-      output: thinkResult.finalOutput,
-      success: true
-    };
-  }
-
-  private aggregate(results: AgentResult[]): AgentResult[] {
-    return results.sort((a, b) => a.taskId.localeCompare(b.taskId));
-  }
-}
-```
-
----
-
-## Task 6: SkillRegistry
-
-**Files:**
-- Create: `src/constraint-runtime/src/skills/index.ts`
-- Create: `src/constraint-runtime/src/skills/skill-registry.ts`
-
-**Step 1: Create skill registry**
-
-```typescript
-export interface Skill {
-  name: string;
-  description: string;
-  execute(params: Record<string, unknown>): Promise<string>;
-}
-
-export class SkillRegistry {
-  private skills: Map<string, Skill> = new Map();
-
-  register(skill: Skill): void {
-    this.skills.set(skill.name, skill);
-  }
-
-  get(name: string): Skill | undefined {
-    return this.skills.get(name);
-  }
-
-  list(): Skill[] {
-    return Array.from(this.skills.values());
-  }
-
-  async execute(name: string, params: Record<string, unknown>): Promise<string> {
-    const skill = this.skills.get(name);
-    if (!skill) throw new Error(`Skill not found: ${name}`);
-    return skill.execute(params);
-  }
-}
-```
-
----
-
-## Task 7: Runtime Session
-
-**Files:**
-- Create: `src/constraint-runtime/src/runtime/index.ts`
-- Create: `src/constraint-runtime/src/runtime/session.ts`
-- Create: `src/constraint-runtime/src/runtime/turn-engine.ts`
-
-**Step 1: Create session**
-
-```typescript
-import { ToolPermissionContext } from '../constraint/permission.js';
-import { BudgetTracker } from '../constraint/budget.js';
-import { DeepThinkingEngine } from '../thinking/engine.js';
-import { AgentCoordinator } from '../agent/coordinator.js';
-
-export interface RuntimeSession {
-  sessionId: string;
-  messages: string[];
-  context: Record<string, unknown>;
-  permissionContext: ToolPermissionContext;
-  budget: BudgetTracker;
-}
-
-export class Session {
-  constructor(
-    public sessionId: string,
-    public messages: string[] = [],
-    public context: Record<string, unknown> = {},
-    public permissionContext: ToolPermissionContext = new ToolPermissionContext(),
-    public budget: BudgetTracker = new BudgetTracker()
-  ) {}
-
-  addMessage(msg: string): void {
-    this.messages.push(msg);
-  }
-}
-```
-
----
-
-## Task 8: Main Entry Point
-
-**Files:**
-- Create: `src/constraint-runtime/src/index.ts`
-
-**Step 1: Create main export**
-
-```typescript
-export { ToolPermissionContext } from './constraint/permission.js';
-export { BudgetTracker } from './constraint/budget.js';
-export { DeepThinkingEngine, type ThinkResult, type ThinkStep } from './thinking/engine.js';
-export { AgentCoordinator, type SubTask, type AgentResult } from './agent/coordinator.js';
-export { SkillRegistry, type Skill } from './skills/skill-registry.js';
-export { Session, type RuntimeSession } from './runtime/session.js';
-```
-
----
-
-## Task 9: Tests
-
-**Files:**
-- Create: `src/constraint-runtime/tests/constraint.test.ts`
-- Create: `src/constraint-runtime/tests/thinking.test.ts`
-- Create: `src/constraint-runtime/tests/agent.test.ts`
-
-**Step 1: Write constraint tests**
-
-```typescript
-import { describe, it, expect } from 'vitest';
-import { ToolPermissionContext } from '../src/constraint/permission.js';
-
-describe('ToolPermissionContext', () => {
-  it('blocks denied tools', () => {
-    const ctx = ToolPermissionContext.fromIterables(['BashTool'], []);
-    expect(ctx.blocks('BashTool')).toBe(true);
-    expect(ctx.blocks('FileReadTool')).toBe(false);
-  });
-});
-```
-
----
-
-## Task 10: Build & Verify
-
-**Step 1: Install dependencies**
-
-```bash
-cd src/constraint-runtime
-npm install typescript vitest @types/node --save-dev
-```
-
-**Step 2: Build**
-
-```bash
-npm run build
-```
-
-**Step 3: Test**
-
-```bash
-npm run test
-```