@bolloon/bolloon-agent 0.1.0

package/dist/bollharness-integration/bollharness-integration/context-router.js

@@ -0,0 +1,542 @@
+/**
+ * Context Router - Port of Bollharness context-fragments to Bolloon
+ *
+ * Implements path-based automatic context injection.
+ * When editing certain files, relevant context fragments are automatically injected.
+ *
+ * Loads fragments from src/bollharness/scripts/context-fragments/
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+export const BOLLHARNESS_CONTEXT_DIR = path.join('src', 'bollharness', 'scripts', 'context-fragments');
+export const FRAGMENTS_DIR = BOLLHARNESS_CONTEXT_DIR;
+/**
+ * Context Map - Maps file paths to relevant context fragments
+ * Uses actual fragment filenames from src/bollharness/scripts/context-fragments/
+ */
+export const CONTEXT_MAP = {
+    'src/agents/': ['truth-source-hierarchy', 'protocol-consumers'],
+    'src/documents/': ['truth-source-hierarchy', 'db-shared-structures'],
+    'src/network/': ['truth-source-hierarchy', 'protocol-consumers'],
+    'src/constraints/': ['truth-source-hierarchy', 'fixed-three-layers'],
+    'src/social/': ['truth-source-hierarchy', 'bridge-constitution'],
+    'src/test/': ['truth-source-hierarchy', 'general-dev-principles'],
+    'src/workflows/': ['truth-source-hierarchy', 'catalyst-distributed'],
+    'src/bollharness-integration/': ['truth-source-hierarchy', 'artifact-linkage'],
+    'docs/': ['truth-source-hierarchy', 'two-language'],
+    'docs/decisions/': ['truth-source-hierarchy', 'artifact-linkage'],
+    'CLAUDE.md': ['truth-source-hierarchy', 'bridge-constitution'],
+    'README.md': ['truth-source-hierarchy', 'general-dev-principles'],
+};
+/**
+ * Default fragments to inject when no specific match
+ */
+export const FALLBACK_FRAGMENTS = ['general-dev-principles', 'code-quality'];
+/**
+ * Load a context fragment by name
+ */
+export function loadFragment(name) {
+    if (!name)
+        return '';
+    const candidate = path.join(FRAGMENTS_DIR, `${name}.md`);
+    try {
+        const resolved = path.resolve(candidate);
+        const fragmentsDirResolved = path.resolve(FRAGMENTS_DIR);
+        if (!resolved.startsWith(fragmentsDirResolved))
+            return '';
+        if (fs.existsSync(resolved) && fs.statSync(resolved).isFile()) {
+            return fs.readFileSync(resolved, 'utf-8').trim();
+        }
+    }
+    catch { }
+    return '';
+}
+/**
+ * Match file path to context fragments
+ * Adapted from bollharness's match() function
+ */
+export function match(filePath) {
+    if (!filePath)
+        return [];
+    if (path.isAbsolute(filePath))
+        return [];
+    const normalized = path.normalize(filePath).replace(/\\/g, '/');
+    if (normalized.startsWith('../') || normalized === '..' || normalized.includes('/../')) {
+        return [];
+    }
+    const matched = [];
+    const sortedPatterns = Object.keys(CONTEXT_MAP).sort((a, b) => b.length - a.length);
+    for (const pattern of sortedPatterns) {
+        if (normalized.startsWith(pattern) || normalized.endsWith(pattern)) {
+            matched.push(...CONTEXT_MAP[pattern]);
+        }
+    }
+    return [...new Set(matched)];
+}
+/**
+ * Get all fragments for a file
+ */
+export function getFragments(filePath) {
+    let fragments = match(filePath);
+    if (!fragments.length) {
+        fragments = Array.isArray(FALLBACK_FRAGMENTS) ? FALLBACK_FRAGMENTS : [FALLBACK_FRAGMENTS];
+    }
+    return fragments;
+}
+/**
+ * Load all fragments for a file
+ */
+export function loadFragments(filePath) {
+    const fragmentNames = getFragments(filePath);
+    const contentParts = [];
+    for (const name of fragmentNames) {
+        const text = loadFragment(name);
+        if (text)
+            contentParts.push(text);
+    }
+    return contentParts;
+}
+/**
+ * Context Router class for integration with Bolloon
+ */
+export class ContextRouter {
+    fragmentsDir;
+    injectedFile;
+    injectedTTL = 3600; // 1 hour
+    constructor(fragmentsDir) {
+        this.fragmentsDir = fragmentsDir || FRAGMENTS_DIR;
+        this.injectedFile = path.join('.boll', 'guard', 'injected.json');
+    }
+    /**
+     * Get fragments for a file path
+     */
+    match(filePath) {
+        return match(filePath);
+    }
+    /**
+     * Load fragment content
+     */
+    loadFragment(name) {
+        return loadFragment.call({ FRAGMENTS_DIR: this.fragmentsDir }, name);
+    }
+    /**
+     * Get all context for a file
+     */
+    getContext(filePath) {
+        const fragments = this.match(filePath);
+        const contentParts = [];
+        for (const name of fragments) {
+            const text = this.loadFragment(name);
+            if (text)
+                contentParts.push(text);
+        }
+        return contentParts.join('\n\n---\n\n');
+    }
+    /**
+     * Get judgments for a file path (judgment-aware extension)
+     */
+    async getJudgmentsForPath(filePath, minConfidence = 0.7) {
+        try {
+            const { getJudgmentsForPath } = await import('./context-router-judgment.js');
+            const result = await getJudgmentsForPath(filePath, { minConfidence });
+            return result.contextYaml;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Get core judgments for session start
+     */
+    async getCoreJudgments(minConfidence = 0.9) {
+        try {
+            const { getCoreJudgmentsForSession } = await import('./context-router-judgment.js');
+            return await getCoreJudgmentsForSession(minConfidence);
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Get judgments for a specific context
+     */
+    async getJudgmentsForContext(context, minConfidence = 0.7) {
+        try {
+            const { getJudgmentsForContextRequest } = await import('./context-router-judgment.js');
+            const result = await getJudgmentsForContextRequest(context, { minConfidence });
+            return result.contextYaml;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Generate judgment injection for a gate
+     */
+    async generateJudgmentInjection(filePath, gate) {
+        try {
+            const { generateJudgmentInjection } = await import('./context-router-judgment.js');
+            return await generateJudgmentInjection(filePath, gate);
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Check if fragment was recently injected
+     */
+    wasRecentlyInjected(fragmentName) {
+        if (!fs.existsSync(this.injectedFile))
+            return false;
+        try {
+            const data = JSON.parse(fs.readFileSync(this.injectedFile, 'utf-8'));
+            if (Date.now() / 1000 - data.timestamp > this.injectedTTL)
+                return false;
+            return (data.fragments || []).includes(fragmentName);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Mark fragments as injected
+     */
+    markInjected(fragmentNames) {
+        const guardDir = path.dirname(this.injectedFile);
+        if (!fs.existsSync(guardDir)) {
+            fs.mkdirSync(guardDir, { recursive: true });
+        }
+        let existing = [];
+        if (fs.existsSync(this.injectedFile)) {
+            try {
+                const data = JSON.parse(fs.readFileSync(this.injectedFile, 'utf-8'));
+                existing = data.fragments || [];
+            }
+            catch { }
+        }
+        const allFragments = [...new Set([...existing, ...fragmentNames])];
+        const data = { timestamp: Date.now() / 1000, fragments: allFragments };
+        fs.writeFileSync(this.injectedFile, JSON.stringify(data, null, 2), 'utf-8');
+    }
+}
+/**
+ * Context fragments content
+ * These can be stored in context-fragments/ directory
+ */
+export const CONTEXT_FRAGMENTS = {
+    'general-dev-principles': `# General Development Principles
+
+## Core Values
+- **Code over Convention**: Write code that works correctly, not just conventionally
+- **Explicit over Implicit**: Make dependencies and side effects visible
+- **Composition over Inheritance**: Prefer composing behavior to inheriting it
+- **Fail Fast**: Detect errors early and fail loudly
+
+## Code Quality
+- Write self-documenting code with clear intent
+- Keep functions small and focused (single responsibility)
+- Avoid premature optimization
+- Test at boundaries
+
+## Collaboration
+- Commit early and often
+- Write meaningful commit messages
+- Review code for clarity, not just correctness
+- Leave code better than you found it`,
+    'code-quality': `# Code Quality Guidelines
+
+## Readability
+- Use meaningful variable and function names
+- Add comments that explain *why*, not *what*
+- Keep lines under 100 characters
+- Use consistent formatting
+
+## Maintainability
+- DRY (Don't Repeat Yourself)
+- SOLID principles
+- Keep modules loosely coupled
+- Make side effects explicit
+
+## Testing
+- Test behavior, not implementation
+- Cover edge cases
+- Write tests before debugging
+- Aim for meaningful assertions`,
+    'agent-architecture': `# Agent Architecture Patterns
+
+## Multi-Agent Design
+- Define clear agent responsibilities
+- Use message passing for inter-agent communication
+- Maintain agent isolation
+- Implement graceful degradation
+
+## Skill System
+- Skills should be composable
+- Each skill has single responsibility
+- Skills communicate via structured interfaces
+- Version skills for compatibility`,
+    'multi-agent-patterns': `# Multi-Agent Collaboration Patterns
+
+## Task Delegation
+- Match tasks to agent capabilities
+- Track task state across agents
+- Handle partial failures gracefully
+- Aggregate results appropriately
+
+## Communication
+- Use structured message formats
+- Implement acknowledgment protocols
+- Handle timeouts and retries
+- Log for debugging`,
+    'documentation-standards': `# Documentation Standards
+
+## When to Document
+- Document *why*, not *what*
+- Keep docs close to code
+- Update docs with code changes
+- Delete outdated documentation
+
+## Types of Documentation
+- README: Project overview and setup
+- API docs: Usage examples
+- Architecture docs: Design decisions
+- Inline comments: Complex logic explanation`,
+    'decision-tracking': `# Decision Tracking with ADRs
+
+## ADR Format
+- Title and status
+- Context and problem statement
+- Decision and rationale
+- Consequences (positive and negative)
+
+## When to Create ADR
+- Architectural changes
+- Technology choices
+- Process changes
+- Cross-cutting concerns`,
+    'adr-patterns': `# Architecture Decision Records
+
+## Structure
+1. **Title**: Brief descriptive title
+2. **Status**: Proposed, Accepted, Deprecated
+3. **Context**: Background and constraints
+4. **Decision**: What we decided
+5. **Consequences**: What changed
+
+## Review Process
+- Propose with clear rationale
+- Solicit feedback from stakeholders
+- Document dissenting opinions
+- Update status as decisions evolve`,
+    'project-governance': `# Project Governance
+
+## Truth Sources
+- CLAUDE.md: Project overview and norms
+- docs/: Architecture and decisions
+- code/: Implementation
+- issues/: Tracking and discussions
+
+## Decision Making
+- Small changes: Direct implementation
+- Medium changes: Discuss first
+- Large changes: ADR required`,
+    'truth-source-hierarchy': `# Truth Source Hierarchy
+
+## Priority Order
+1. **Code**: Ground truth for behavior
+2. **Tests**: Verification of behavior
+3. **Docs**: Explanation of behavior
+4. **Comments**: Intent and caveats
+5. **Commits**: History and rationale
+
+## Conflict Resolution
+- Code vs docs: Code wins
+- Comments vs code: Code wins
+- Multiple docs: Newest wins
+- Stale info: Delete or update`,
+    'testing-patterns': `# Testing Patterns
+
+## Test Structure
+- Arrange: Set up test data
+- Act: Execute the behavior
+- Assert: Verify the outcomes
+
+## Test Types
+- Unit tests: Single function/class
+- Integration tests: Component interaction
+- E2E tests: Full system flow
+
+## Best Practices
+- Test one thing per test
+- Use descriptive test names
+- Keep tests independent
+- Mock external dependencies`,
+    'quality-standards': `# Quality Standards
+
+## Code Review Checklist
+- [ ] Does it work correctly?
+- [ ] Is it readable?
+- [ ] Are there tests?
+- [ ] Is it documented?
+- [ ] Are there security concerns?
+- [ ] Performance implications?
+
+## Definition of Done
+- Code complete
+- Tests passing
+- Documentation updated
+- No known issues`,
+    'workflow-patterns': `# Workflow Patterns
+
+## Pipeline Design
+- Input validation
+- Transformation steps
+- Output generation
+- Error handling
+
+## State Management
+- Track workflow progress
+- Handle partial completion
+- Support retry logic
+- Log state changes`,
+    'orchestration-patterns': `# Orchestration Patterns
+
+## Task Coordination
+- Define task dependencies
+- Execute in correct order
+- Handle parallel execution
+- Aggregate results
+
+## Error Recovery
+- Identify failure points
+- Implement retry strategies
+- Rollback when needed
+- Notify stakeholders`,
+    'document-processing': `# Document Processing
+
+## Supported Formats
+- Markdown: Primary format
+- PDF: Via external parser
+- DOCX: Via external parser
+- Plain text: Direct reading
+
+## Processing Pipeline
+- Load document
+- Extract text
+- Chunk content
+- Process chunks
+- Aggregate results`,
+    'parser-patterns': `# Parser Patterns
+
+## Design Principles
+- Single responsibility per parser
+- Consistent error handling
+- Graceful degradation
+- Clear error messages
+
+## Content Extraction
+- Strip formatting
+- Preserve structure
+- Handle encoding
+- Validate content`,
+    'p2p-protocols': `# P2P Protocols
+
+## Connection Management
+- Bootstrap connections
+- Maintain peer list
+- Handle disconnections
+- Reconnect gracefully
+
+## Message Routing
+- Direct messages
+- Broadcast messages
+- Topic subscriptions
+- Message queuing`,
+    'connection-patterns': `# Connection Patterns
+
+## Lifecycle
+- Connect
+- Authenticate
+- Exchange
+- Disconnect
+
+## Reliability
+- Heartbeat monitoring
+- Timeout handling
+- Retry mechanisms
+- Graceful degradation`,
+    'constraint-design': `# Constraint Design
+
+## Principles
+- Constraints should be explicit
+- Fail with clear messages
+- Allow override when needed
+- Document rationale
+
+## Implementation
+- Pre-conditions
+- Post-conditions
+- Invariants
+- Error handling`,
+    'validation-patterns': `# Validation Patterns
+
+## Input Validation
+- Type checking
+- Range validation
+- Format validation
+- Business rule validation
+
+## Error Reporting
+- Clear error messages
+- Field-level errors
+- Actionable suggestions
+- Error codes`,
+    'social-protocols': `# Social Protocols
+
+## Agent Discovery
+- Broadcast presence
+- Maintain registry
+- Handle joins/leaves
+- Cache agent info
+
+## Collaboration
+- Task distribution
+- Result aggregation
+- Conflict resolution
+- Consensus building`,
+    'agent-discovery': `# Agent Discovery
+
+## Registration
+- Announce capabilities
+- Update status
+- Heartbeat mechanism
+- Graceful cleanup
+
+## Lookup
+- Search by capability
+- Filter by status
+- Sort by relevance
+- Cache results`,
+    'project-intro': `# Project Introduction
+
+## Overview
+Bolloon is a P2P AI document processing system with multi-agent collaboration.
+
+## Key Features
+- Document processing pipeline
+- P2P network communication
+- Multi-agent task coordination
+- Constraint-based guardrails`,
+    'getting-started': `# Getting Started
+
+## Setup
+1. Install dependencies
+2. Configure environment
+3. Initialize P2P identity
+4. Start processing
+
+## Basic Usage
+- Process documents
+- Coordinate with peers
+- Monitor performance`,
+};

package/dist/bollharness-integration/bollharness-integration/gate-state-machine.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Gate State Machine - Implements Bollharness's 8-Gate workflow governance
+ *
+ * Port of bollharness's lead skill Gate system to Bolloon's multi-agent architecture.
+ *
+ * Gates:
+ * G0 → G1 → G2* → G3 → G4* → G5 → G6* → G7 → G8*
+ *              审查门            审查门            审查门            审查门
+ * (* = 独立审查者，使用独立的agent上下文)
+ */
+export type Gate = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+export interface GateConfig {
+    entryCondition: string;
+    requiredArtifact: string;
+    requiredNextSkill: string;
+    requiredReviewSubstrate?: string;
+    isReviewGate: boolean;
+}
+export interface GateTransition {
+    from: Gate;
+    to: Gate;
+    blockers: string[];
+    artifact?: Record<string, unknown>;
+}
+export interface GateState {
+    currentGate: Gate;
+    entrySatisfied: boolean;
+    blockers: string[];
+    requiredArtifact: string;
+    requiredNextSkill: string;
+    requiredReviewSubstrate?: string;
+    artifacts: Map<string, unknown>;
+}
+export declare class GateStateMachine {
+    private state;
+    private coordinator;
+    private reviewAgentContext;
+    constructor();
+    private initState;
+    getState(): GateState;
+    getCurrentGate(): Gate;
+    getGateConfig(gate: Gate): GateConfig;
+    /**
+     * 检查是否可以进入下一个Gate
+     */
+    canTransition(): boolean;
+    /**
+     * 提交产物到当前Gate
+     */
+    submitArtifact(name: string, artifact: unknown): void;
+    /**
+     * 获取Gate包 - 用于skill输出
+     */
+    getGatePack(): {
+        current_gate: number;
+        entry_satisfied: boolean;
+        blockers: string[];
+        required_artifact: string;
+        required_next_skill: string;
+        required_review_substrate?: string;
+    };
+    /**
+     * 尝试转移到下一个Gate
+     */
+    transition(reviewResult?: {
+        verdict: 'PASS' | 'BLOCK';
+        details?: string;
+    }): Promise<GateTransition>;
+    /**
+     * 回退到指定Gate
+     */
+    rollback(gate: Gate): void;
+    /**
+     * 检查快速通道条件
+     */
+    checkFastTrack(changeClassification: 'policy' | 'contract' | 'implementation'): boolean;
+    private checkEntryCondition;
+    private updateStateForGate;
+    /**
+     * 执行独立审查（用于审查门）
+     * 使用独立的agent上下文
+     */
+    executeIndependentReview(task: string, substrate: string): Promise<{
+        verdict: 'PASS' | 'BLOCK';
+        details: string;
+    }>;
+}