GitHub - markjspivey-xwisee/agent-context-graph: Abstract Agent Type System with Context Graphs, DIDs/VCs, Causality, and Provenance

# Install dependencies
npm install

# Build
npm run build

# Run the Dashboard with integrated Orchestrator (port 3001)
ANTHROPIC_API_KEY=your-key npm run dashboard

# Or use Claude Code CLI instead of API
USE_CLAUDE_CLI=true npm run dashboard

# Or run the interactive demo
ANTHROPIC_API_KEY=your-key npm run demo "Create a REST API for user management"

# Validate a single context graph against SHACL shapes
npm run cli validate examples/golden-path/planner-context.json

# Validate all golden-path examples
npm run cli validate-all

# Check federation status
npm run cli federate status

# List established trust relationships
npm run cli federate trust

# List all checkpoints
npm run cli checkpoint list

# Create a checkpoint
npm run cli checkpoint create --label "Before migration"

# List active enclaves
npm run cli enclave list

# Create an enclave
npm run cli enclave create --name "feature-work" --repo "https://github.com/org/repo"

npm start
# Dashboard available at http://localhost:3000

# Standard orchestrator
ANTHROPIC_API_KEY=your-key npm run orchestrator

# Or with parallel execution enabled
ANTHROPIC_API_KEY=your-key ENABLE_PARALLEL=true npm run orchestrator

curl -X POST http://localhost:3001/goals \
  -H "Content-Type: application/json" \
  -d '{"goal": "Create a REST API for user management with CRUD operations"}'

# Get workflow status
curl http://localhost:3001/workflows/{workflow-id}

# Get orchestrator stats (includes parallelization status)
curl http://localhost:3001/stats

+------------------------------------------------------------------+
|                    CONCURRENT ORCHESTRATOR                        |
|  +----------------+  +----------------+  +-------------------+    |
|  | Task Manager   |  | Agent Pool     |  | Concurrency Policy|    |
|  +----------------+  +----------------+  +-------------------+    |
|  +----------------+  +----------------+                           |
|  | Enclave Svc    |  | Checkpoint Svc |  (Gas Town inspired)      |
|  +----------------+  +----------------+                           |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                       CONTEXT BROKER                              |
|  +----------------+  +----------------+  +-------------------+    |
|  | AAT Registry   |  | SHACL Validator|  | Policy Engine     |    |
|  +----------------+  +----------------+  +-------------------+    |
|  +----------------+  +----------------+  +-------------------+    |
|  | Trace Store    |  | Causal Eval    |  | Enclave/Checkpoint|    |
|  +----------------+  +----------------+  +-------------------+    |
+------------------------------------------------------------------+
                              |
                              v
+------------------------------------------------------------------+
|                         AGENT POOL                                |
|  +-----------+  +-----------+  +-----------+  +-----------+      |
|  | Planner   |  | Executor  |  | Observer  |  | Arbiter   |      |
|  | (LLM)     |  | (Enclave) |  | (LLM)     |  | (Singleton)|     |
|  +-----------+  +-----------+  +-----------+  +-----------+      |
+------------------------------------------------------------------+

// CreateEnclave - Create isolated git worktree
await broker.traverse({
  affordanceId: 'aff-createenclave-xxx',
  parameters: {
    repository: 'https://github.com/org/repo',
    baseBranch: 'main',
    enclaveName: 'feature-work',
    ttlSeconds: 3600
  }
});

// SealEnclave - Make read-only, preserve work
await broker.traverse({
  affordanceId: 'aff-sealenclave-xxx',
  parameters: { enclaveId: 'urn:enclave:xxx', reason: 'Task complete' }
});

// DestroyEnclave - Clean up worktree
await broker.traverse({
  affordanceId: 'aff-destroyenclave-xxx',
  parameters: { enclaveId: 'urn:enclave:xxx', archiveFirst: true }
});

// Checkpoint - Create immutable snapshot
await broker.traverse({
  affordanceId: 'aff-checkpoint-xxx',
  parameters: {
    label: 'Before refactoring',
    agentState: { taskQueue: [...], completedTasks: [...] }
  }
});

// Resume - Restore from checkpoint
await broker.traverse({
  affordanceId: 'aff-resume-xxx',
  parameters: {
    checkpointId: 'urn:checkpoint:xxx',
    verifyIntegrity: true
  }
});

// Establish trust with another broker
await federationService.establishTrust({
  targetBrokerDID: 'did:web:partner-broker.example.com',
  trustLevel: 'LimitedTrust',
  protocol: 'DIDComm',
  credentialBridges: [{
    localCredential: 'PlannerCapability',
    remoteCredential: 'ExternalPlannerCapability',
    trustLevel: 'LimitedTrust'
  }]
});

// Federate context to partner broker
await federationService.federateContext({
  targetBrokerDID: 'did:web:partner-broker.example.com',
  contextGraphId: 'urn:uuid:ctx-123',
  includeCredentials: false,  // Don't share sensitive creds
  maxHops: 3
});

import { ConcurrentOrchestrator } from './agents/concurrent-orchestrator.js';

const orchestrator = new ConcurrentOrchestrator({
  brokerUrl: 'http://localhost:3000',
  aatRegistry: myAATRegistry,
  repositoryUrl: 'https://github.com/org/repo', // For enclaves
  enableCheckpointing: true,
  checkpointIntervalMs: 60000,
  concurrencyPolicy: {
    maxTotalAgents: 10,
    maxPerType: {
      'aat:ExecutorAgentType': 5,
      'aat:ArbiterAgentType': 1  // Singleton
    },
    conflictMatrix: {
      'aat:ArbiterAgentType': ['aat:ArbiterAgentType']
    },
    resourceLimits: {
      maxTokensPerMinute: 100000,
      maxCostPerHour: 10,  // $10/hr cap
      maxConcurrentAPICalls: 10
    }
  }
});

await orchestrator.start();

// Submit goal with parallel execution
const workflowId = await orchestrator.submitGoal(
  'Implement user authentication',
  { enableParallelExecution: true }
);

// Check parallelization status
const status = orchestrator.getParallelizationStatus();
// { activeAgentsByType: {...}, maxByType: {...}, conflicts: [...] }

agent-context-graph/
├── principles/              # Foundational principles
│   ├── aat.md
│   ├── affordances.md
│   ├── hypermedia-principles.md
│   ├── hypergraph.md
│   ├── category-theory.md
│   ├── prov.md
│   ├── policy.md
│   ├── semiotics.md
│   ├── threat-model.md
│   └── decentralized-identity.md
├── architecture/            # System architecture
│   ├── ARCHITECTURE_INDEX.md
│   ├── ARCHITECTURE.md
│   ├── interfaces.md
│   └── gas-town-inspirations.md
├── protocol/                # Protocol-level documentation
│   └── API.md               # Complete API reference
├── guides/                  # Build and usage guides
│   ├── GETTING_STARTED.md
│   └── 00-HOW-TO-BUILD.md
├── implementations/         # Reference implementations + demos (index)
│   └── README.md
├── spec/                    # Specifications
│   ├── aat/                 # AAT JSON definitions
│   ├── ontology/            # OWL ontologies (Turtle)
│   │   ├── acg-core.ttl     # Core ontology (ExecutionEnclave, Checkpoint)
│   │   ├── aat-types.ttl    # Agent type hierarchy + parallelization
│   │   ├── actions.ttl      # Action taxonomy (incl. Federation, Causal)
│   │   ├── federation.ttl   # Federation ontology
│   │   ├── personal-broker.ttl   # Personal broker ontology
│   │   ├── social-federation.ttl # Social connections ontology
│   │   ├── shared-context.ttl    # Shared context ontology
│   │   └── channel-bridge.ttl    # Channel bridge ontology
│   ├── shacl/               # SHACL validation shapes
│   │   └── params.ttl       # Parameter shapes (enclave, checkpoint, federation)
│   └── hydra/               # Hydra API documentation
│   ├── context-graph.schema.json # Context Graph JSON Schema
│   ├── prov-trace.schema.json    # PROV Trace JSON Schema
│   ├── HYPERGRAPH.md        # Hypergraph spec
│   ├── CATEGORY-THEORY.md   # Category theory spec
│   ├── cgp.md               # Context Graph Profile
│   ├── causal-affordance.md # Causal affordance spec
│   └── telemetry.md         # Telemetry spec
├── examples/                # Example files
│   ├── federation-workflow.ts  # Multi-agent collaboration demo
│   └── golden-path/
│       ├── planner-context.json      # Basic planner scenario
│       ├── executor-context.json     # Executor with tool access
│       ├── observer-context.json     # Observer with watch affordances
│       ├── arbiter-context.json      # Arbiter approval workflows
│       ├── archivist-context.json    # Archive and retrieval
│       ├── infrastructure-context.json   # Enclaves and checkpoints
│       ├── delegated-planning-context.json  # Hierarchical delegation
│       ├── multi-hop-federation-context.json  # Cross-broker federation
│       ├── causal-intervention-context.json   # Causal semantics
│       ├── error-scenario-context.json        # Error handling/recovery
│       └── prov-trace.json           # PROV activity trace
├── src/
│   ├── agents/              # Agent orchestration layer
│   │   ├── agent-runtime.ts # Agent execution loop
│   │   ├── llm-client.ts    # Claude API integration
│   │   ├── orchestrator.ts  # Standard orchestrator
│   │   ├── concurrent-orchestrator.ts  # AAT-aware parallel orchestrator
│   │   └── task-manager.ts  # Task queue & lifecycle
│   ├── broker/              # Context Broker
│   │   └── context-broker.ts # Includes enclave/checkpoint handling
│   ├── services/            # Service implementations
│   │   ├── aat-registry.ts  # AAT management + parallelization rules
│   │   ├── policy-engine.ts # Policy + concurrency evaluation
│   │   ├── enclave-service.ts   # Git worktree isolation
│   │   ├── checkpoint-store.ts  # State persistence
│   │   ├── shacl-validator.ts   # SHACL validation
│   │   ├── federation-service.ts    # Cross-broker federation
│   │   ├── personal-broker.ts       # Conversations, memory, contacts
│   │   ├── social-federation.ts     # Connections, groups, discovery
│   │   ├── shared-context.ts        # CRDT-based shared contexts
│   │   ├── channel-bridge.ts        # Slack/Discord/Matrix/Email
│   │   ├── realtime-sync.ts         # WebSocket sync service
│   │   ├── activitypub-bridge.ts    # ActivityPub protocol
│   │   ├── didcomm-messaging.ts     # DIDComm encrypted messaging
│   │   ├── did-auth.ts              # DID/VC authentication
│   │   └── federation-persistence.ts # SQLite persistence
│   ├── cli/                 # CLI tooling
│   │   ├── index.ts         # acg CLI commands
│   │   ├── chat.ts          # Interactive chat CLI
│   │   └── ws-client.ts     # WebSocket test client
│   ├── interfaces/          # TypeScript interfaces
│   ├── dashboard/           # Web dashboard
│   ├── demo/                # Demo scripts
│   └── index.ts             # Broker server
├── tests/
│   ├── agents/              # Agent tests
│   ├── services/            # Service unit tests
│   │   ├── federation-service.test.ts
│   │   └── shacl-validator.test.ts
│   ├── negative/            # Security tests
│   └── integration/         # Integration tests
│       └── federation.test.ts  # Federation flow tests
├── AGENTS.md                # Rules for coding agents
└── package.json

ANTHROPIC_API_KEY=your-key npm run orchestrator

USE_CLAUDE_CLI=true npm run orchestrator

const orchestrator = new Orchestrator({
  brokerUrl: 'http://localhost:3000',
  useClaudeCodeCLI: true,
  cliConfig: {
    cliPath: 'claude',
    workingDirectory: '/project',
    model: 'opus'  // Default: Claude Opus 4.5
  }
});