Tools

Agent Os

Name: Agent Os
Rating: 3.5 (1 reviews)
Author: ying-wen

By ying-wen 👁 2 views ▲ 0 votes

Agent OS: semantic execution runtime plugin for OpenClaw — Effect Log, Capability Gateway, Checkpoint/Fork, Concern Streams, Liveness Monitor, A2A Communication

GitHub

Install

npm install    #

Configuration Example

{
  // Directory for SQLite database and state files
  "dataDir": "~/.openclaw/agent-os",

  // Capability Gateway settings
  "gateway": {
    "enabled": true,           // Enable tool access control
    "defaultTtlMs": 3600000,   // Token TTL: 1 hour
    "defaultMaxCalls": 200     // Max tool calls per token
  },

  // Liveness detection thresholds
  "liveness": {
    "stallThresholdMs": 300000,   // 5 minutes without activity = stall
    "loopDetectionWindow": 10,    // Check last 10 actions for loops
    "loopThreshold": 3            // 3 identical calls = loop detected
  },

  // Watchdog health check interval
  "watchdogIntervalMs": 10000,    // Check every 10 seconds

  // Agent name for A2A communication
  "agentName": "my-agent",

  // A2A authentication (optional)
  "a2a": {
    "enforceAuth": false,
    "knownTokens": {},
    "sharedSecrets": {}
  }
}

README

# Agent OS — OpenClaw Plugin

> Semantic execution runtime that makes AI agents observable, recoverable, and reliable.

Agent OS runs as an [OpenClaw](https://github.com/openclaw/openclaw) plugin, injecting structured state management, self-monitoring, and recovery capabilities via the plugin hook system. **Zero core file modifications.**

## What It Does

| Primitive | Purpose |
|-----------|---------|
| **Effect Log** | Append-only record of every tool call (intent + outcome). Enables replay, auditing, loop detection. |
| **Scratch Space** | Key-value working memory with semantic annotations. Survives context compaction. |
| **Concern Streams** | Tracks beliefs (with confidence), decisions (with rationale), and constraints. |
| **Capability Gateway** | Token-based access control for tool calls (TTL, max-calls, tool patterns). |
| **Checkpoint/Fork** | State snapshots for rollback + speculative execution branches. |
| **Liveness Monitor** | Detects stalls and infinite loops. Auto-recovery via watchdog. |
| **A2A Communication** | Agent-to-agent discovery, messaging, delegation, reputation, and economics. |
| **Memory Tiers** | Hot/warm/cold/archive memory with automatic consolidation and decay. |

## Quick Start

```bash
# 1. Clone
git clone https://github.com/ying-wen/openclaw-agent-os.git
cd openclaw-agent-os

# 2. Install dependencies
pnpm install    # or npm install

# 3. Run tests (requires Node 22+)
pnpm test       # 187 tests across 13 test files
```

## Requirements

- **Node.js 22+** (required for `node:sqlite`)
- **OpenClaw** (host application, `>=2026.3.24`)

## Installation

### Option A: Install from local path

```bash
# Link the plugin to OpenClaw
openclaw plugins install /path/to/openclaw-agent-os
```

### Option B: Install from npm (after publishing)

```bash
openclaw plugins install openclaw-agent-os
```

### Option C: Development mode (symlink)

```bash
# From OpenClaw config, add local extension path
# In ~/.openclaw/openclaw.json:
{
  "plugins": {
    "entries": {
      "agent-os": {
        "enabled": true,
        "source": "/path/to/openclaw-agent-os",
        "config": {}
      }
    },
    "slots": {
      "contextEngine": "agent-os"
    }
  }
}
```

## Configuration

Add plugin config in `~/.openclaw/openclaw.json` under `plugins.entries.agent-os.config`:

```jsonc
{
  // Directory for SQLite database and state files
  "dataDir": "~/.openclaw/agent-os",

  // Capability Gateway settings
  "gateway": {
    "enabled": true,           // Enable tool access control
    "defaultTtlMs": 3600000,   // Token TTL: 1 hour
    "defaultMaxCalls": 200     // Max tool calls per token
  },

  // Liveness detection thresholds
  "liveness": {
    "stallThresholdMs": 300000,   // 5 minutes without activity = stall
    "loopDetectionWindow": 10,    // Check last 10 actions for loops
    "loopThreshold": 3            // 3 identical calls = loop detected
  },

  // Watchdog health check interval
  "watchdogIntervalMs": 10000,    // Check every 10 seconds

  // Agent name for A2A communication
  "agentName": "my-agent",

  // A2A authentication (optional)
  "a2a": {
    "enforceAuth": false,
    "knownTokens": {},
    "sharedSecrets": {}
  }
}
```

### Slot Assignment

Agent OS registers as a **context engine**. To activate it, assign the `contextEngine` slot:

```json
{
  "plugins": {
    "slots": {
      "contextEngine": "agent-os"
    }
  }
}
```

This replaces the default `"legacy"` context engine with Agent OS, enabling:
- Context injection (beliefs, state, warnings) into every LLM call
- Automatic memory consolidation after each turn
- Auto-checkpointing before compaction

## Architecture

```
openclaw-agent-os/
├── src/
│   ├── index.ts              ← Plugin entry: register hooks/tools/services/contextEngine
│   ├── api.ts                ← Re-export openclaw/plugin-sdk/plugin-entry
│   ├── config.ts             ← Config schema + Zod-like parsing
│   ├── core/                 ← 13 core modules
│   │   ├── effect-log.ts         SQLite-backed tool call log
│   │   ├── scratch-space.ts      Key-value working memory
│   │   ├── concern-stream.ts     Beliefs, decisions, constraints
│   │   ├── capability-gateway.ts Token-based access control
│   │   ├── checkpoint-store.ts   State snapshots
│   │   ├── fork-manager.ts       Speculative execution branches
│   │   ├── liveness-monitor.ts   Stall/loop detection
│   │   ├── fallback-recovery.ts  Automated recovery strategies
│   │   ├── context-engine.ts     ContextEngine implementation
│   │   ├── economics.ts          Credit ledger for A2A
│   │   ├── memory-tiers.ts       Hot/warm/cold/archive memory
│   │   ├── memory-bridge.ts      Cross-session memory bridge
│   │   └── conflict-resolution.ts Belief conflict detection
│   ├── hooks/                ← 9 hook handlers
│   │   ├── before-tool-call.ts
│   │   ├── after-tool-call.ts
│   │   ├── before-prompt-build.ts
│   │   ├── session-lifecycle.ts
│   │   ├── agent-lifecycle.ts
│   │   ├── before-compaction.ts
│   │   ├── after-compaction.ts
│   │   ├── subagent-hooks.ts
│   │   └── shared-context.ts     Type definitions
│   ├── tools/
│   │   └── agent-os-state.ts     LLM-facing tool (16 actions)
│   ├── services/
│   │   └── watchdog.ts           Background health monitor
│   └── a2a/                  ← Agent-to-Agent communication
│       ├── client.ts             HTTP client for remote agents
│       ├── endpoints.ts          Incoming request handlers
│       ├── auth.ts               HMAC authentication
│       ├── reputation.ts         Agent reliability tracking
│       ├── social.ts             Social graph management
│       └── types.ts              A2A protocol types
├── tests/                    ← 13 test files, 187+ tests
├── docs/
│   └── architecture.md
├── openclaw.plugin.json      ← Plugin manifest
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── LICENSE
```

## Development Workflow

### Running Tests

```bash
# All tests (sequential, required for SQLite thread safety)
pnpm test

# Watch mode
pnpm test:watch

# Type checking
pnpm typecheck
```

Tests use `pool: "forks"` with `maxForks: 1` because SQLite `DatabaseSync` is not thread-safe across Vitest worker threads.

### Test Files

| File | Coverage |
|------|----------|
| `core-modules.test.ts` | Effect Log, Scratch Space, Checkpoints, Streams, Liveness, Fork, Gateway |
| `gateway-interception.test.ts` | Capability Gateway token validation |
| `liveness-detection.test.ts` | Stall/loop detection scenarios |
| `recovery-replay.test.ts` | Checkpoint restore + replay |
| `fallback-recovery.test.ts` | Automated recovery strategies |
| `context-injection.test.ts` | Context engine prompt injection |
| `subagent-integration.test.ts` | Multi-agent context propagation |
| `new-features.test.ts` | Conflict detection, enhanced gateway |
| `a2a-endpoints.test.ts` | A2A HTTP endpoints |
| `a2a-auth.test.ts` | HMAC authentication |
| `scheduler-economics-memory.test.ts` | Credits, memory tiers |
| `e2e-full-pipeline.test.ts` | End-to-end pipeline |
| `e2e-stress.test.ts` | Stress testing |

### Adding a New Feature

1. Write tests in `tests/`
2. Implement in `src/core/` (or appropriate subdirectory)
3. Wire into hooks/tools in `src/index.ts`
4. Run `pnpm test` to verify
5. Update `openclaw.plugin.json` if new config options are needed

### E2E Testing with OpenClaw Gateway

```bash
# 1. Start OpenClaw gateway (in another terminal)
openclaw gateway run --port 18789

# 2. Connect an agent
openclaw agent

# 3. Use the agent_os_state tool to verify
#    Actions: status, set_state, get_state, add_belief, remember, recall, etc.
```

## Tool: agent_os_state

The plugin registers an `agent_os_state` tool with 16 actions:

| Action | Description |
|--------|-------------|
| `set_state` | Set a key-value pair in scratch space |
| `get_state` | Get a value by key |
| `list_state` | List all state entries |
| `remember` | Store a fact with semantic annotation |
| `recall` | Search memories by query |
| `add_belief` | Record a belief with confidence score |
| `add_decision` | Record a decision with rationale and alternatives |
| `status` | Full health report (liveness, streams, state, effects) |
| `a2a_discover` | Discover a remote agent's capabilities |
| `a2a_send` | Send a message to a remote agent |
| `a2a_delegate` | Delegate a task to a remote agent |
| `interrupt_child` | Interrupt a child agent session |
| `balance` | Check credit balance (A2A economics) |
| `settle` | Settle a task payment |
| `recall_memory` | Search across all memory tiers |
| `consolidate_memory` | Trigger memory consolidation |

## Hook Integration

Agent OS hooks into the following OpenClaw lifecycle events:

| Hook | What It Does |
|------|-------------|
| `before_tool_call` | Log intent to Effect Log, check Capability Gateway token |
| `after_tool_call` | Record completion, update liveness monitor |
| `before_prompt_build` | Inject context (beliefs, warnings, state) into system prompt |
| `session_start` | Initialize concern stream for the session |
| `agent_end` | Auto-checkpoint scratch space + effect log |
| `before_compaction` | Snapshot state before compaction |
| `after_compaction` | Create post-compaction checkpoint |
| `subagent_spawning` | Propagate parent context to child agent |
| `subagent_ended` | Merge child results, detect belief conflicts |

## Publishing

```bash
# Bump version
npm version patch  # or minor/major

# Publish to npm
npm publish

# Users can then install via:
openclaw plugins install openclaw-agent-os
```

## License

MIT

tools