@holoscript/agent-protocol

uAA2++ 7-Phase Protocol — The cognitive lifecycle contract for autonomous agents.

Defines protocol phases, BaseAgent interface, BaseService lifecycle, and PWG (Pattern/Wisdom/Gotcha) knowledge interchange format.

Quick Start

import { BaseAgent, ProtocolPhase, PhaseResult } from '@holoscript/agent-protocol';

class MyAgent extends BaseAgent {
  readonly identity = {
    id: 'agent_001',
    name: 'MyAgent',
    domain: 'spatial-reasoning',
    version: '1.0.0',
    capabilities: ['3d-pathfinding', 'object-recognition'],
  };

  async intake(input: unknown): Promise<PhaseResult> {
    // Phase 0: Gather data and context
    return {
      phase: ProtocolPhase.INTAKE,
      status: 'success',
      data: {
        /* collected context */
      },
      durationMs: 0,
      timestamp: Date.now(),
    };
  }

  // Implement remaining 6 phases: reflect, execute, compress, dreaming/reintake, grow, evolve
  // ...
}

const agent = new MyAgent();
const result = await agent.runCycle('Analyze spatial layout');
// result.status === 'complete', result.phases.length === 7

8-Phase Protocol

| Phase | ID | Purpose | | ------------- | --- | ------------------------------------------------------------------ | | 0. INTAKE | 0 | Gather data and context | | 1. REFLECT | 1 | Analyze and understand | | 2. EXECUTE | 2 | Take action | | 3. COMPRESS | 3 | Store knowledge efficiently | | 4. DREAMING | 4 | Validate and re-evaluate compressed knowledge (REINTAKE API key) | | 5. GROW | 5 | Learn patterns, wisdom, gotchas | | 6. EVOLVE | 6 | Adapt and optimize | | 7. AUTONOMIZE | 7 | Self-directed goal synthesis |

PWG Knowledge Format

import { Pattern, Wisdom, Gotcha } from '@holoscript/agent-protocol';

const pattern: Pattern = {
  id: 'P.SPATIAL.001',
  domain: 'spatial-reasoning',
  problem: 'Object occlusion in 3D scenes',
  solution: 'Use Z-buffer depth testing and spatial hashing',
  tags: ['3d', 'rendering', 'occlusion'],
  confidence: 0.95,
  createdAt: Date.now(),
  updatedAt: Date.now(),
};

const wisdom: Wisdom = {
  id: 'W.SPATIAL.042',
  domain: 'spatial-reasoning',
  insight: 'Geospatial coordinates are the only universal anchor across AR/VR/Web',
  context: 'Cross-platform spatial computing',
  source: 'uAA2++ research phase 3',
  tags: ['cross-reality', 'anchors'],
  createdAt: Date.now(),
};

const gotcha: Gotcha = {
  id: 'G.SPATIAL.009',
  domain: 'spatial-reasoning',
  mistake: 'Using Euler angles for quaternion interpolation',
  fix: 'Always use quaternion SLERP for smooth rotation',
  severity: 'high',
  tags: ['quaternions', 'rotation', 'math'],
  createdAt: Date.now(),
};

BaseService Lifecycle

import { BaseService, ServiceLifecycle, ServiceError } from '@holoscript/agent-protocol';

class MySpatialService extends BaseService {
  constructor() {
    super(
      { name: 'spatial-indexer', version: '1.0.0', description: 'Spatial hash grid service' },
      { timeout: 5000, retries: 2 }
    );
  }

  protected async onInit(): Promise<void> {
    // Initialize resources
  }

  protected async onReady(): Promise<void> {
    // Service is ready to accept requests
  }

  protected async onStop(): Promise<void> {
    // Cleanup resources
  }
}

const service = new MySpatialService();
await service.initialize();
// service.isReady() === true

Goal Synthesizer (Phase 7: AUTONOMIZE)

import { GoalSynthesizer } from '@holoscript/agent-protocol';

const synthesizer = new GoalSynthesizer();
const goal = synthesizer.synthesize('coding', 'autonomous-boredom');
// goal.description: "Refactor legacy modules in the codebase"
// goal.priority: "low"
// goal.source: "autonomous-boredom"

MicroPhase Decomposer

import { MicroPhaseDecomposer } from '@holoscript/agent-protocol';

const decomposer = new MicroPhaseDecomposer();

decomposer.registerTask({
  id: 'task_1',
  name: 'Load scene',
  estimatedDuration: 100,
  dependencies: [],
  execute: async () => ({ loaded: true }),
});

decomposer.registerTask({
  id: 'task_2',
  name: 'Process geometry',
  estimatedDuration: 200,
  dependencies: ['task_1'],
  execute: async () => ({ processed: 42 }),
});

const plan = decomposer.createExecutionPlan();
// plan.groups.length === 2 (task_1 in group 0, task_2 in group 1)
// plan.parallelizationRatio: percentage of time saved via parallel execution

const results = await decomposer.executePlan(plan);
// results[0].status === 'success', results[1].status === 'success'

Scripts

npm run test    # Run tests
npm run build   # Build to dist/
npm run dev     # Watch mode

Package boundary & release posture

@holoscript/agent-protocol targets external, public, and agent framework consumers who need the uAA2++ 7/8-phase protocol contracts (interfaces, enums, PWG knowledge format) plus a set of ready-made multi-agent protocol implementations (ReactAgent, PlanExecuteAgent, DebateOrchestrator, SwarmOrchestrator, A2AHSNAPBridge, IdempotentTransportAdapter) without pulling in the full @holoscript/framework runtime.

npm install @holoscript/agent-protocol

The package boundary is protocol-level: it does not ship a scheduler, persistence layer, or LLM client — callers bring caller-owned transport, storage, and model clients and point it at their own infrastructure; nothing here assumes founder-local config or a specific deployment.

Known limitations (v0-preview): interfaces may still change before a v1 release. A few Quick Start examples above reference BaseAgent, BaseService, GoalSynthesizer, and MicroPhaseDecomposer, which are not currently exported from this package's public entry point — treat those as illustrative pending a docs correction, and rely on the exported protocol implementations (ReactAgent, PlanExecuteAgent, DebateOrchestrator, SwarmOrchestrator) instead. Run pnpm test to validate what you actually import before depending on it in production.