# AgentScope, HiClaw, And QwenPaw Integration Layer

This document defines how 99Pages Agentic OS V3 should absorb the useful
patterns from AgentScope, HiClaw, and QwenPaw without turning the product into
a fork of any one project.

## Position

99Pages Agentic OS remains local-first, AI Workforce governed, and Cockpit
centered. AgentScope, HiClaw, and QwenPaw are reference systems for mature
agent orchestration, CLI interaction, and GUI projection.

We should not copy their whole runtime. The commercial path is to implement a
compatibility layer around our existing MCP registry, SubCLI workers, run event
stream, Keybox, and Cockpit panels.

## What To Adopt

### AgentScope

- Agent/message abstraction for multi-agent runs.
- Tool and MCP bridge patterns.
- Human-in-the-loop approvals.
- Memory and knowledge source separation.
- Multi-agent routing concepts that map cleanly onto SubCLI profiles.

99Pages mapping:

- `Run` is the durable room.
- `Worker` is a SubCLI profile or MCP-backed module agent.
- `Event` is the shared trace and evidence contract.
- `Approval` is a first-class event, visible in CLI, Cockpit, Telegram, and app.

### HiClaw

- Manager/worker collaboration shape.
- Shared workspace file references.
- Transparent progress reporting.
- Developer-friendly CLI loop.

99Pages mapping:

- Main agent is fixed by Workforce policy, currently MiniMax 2.5.
- Workers are module agents selected through Workforce policy.
- Shared workspace is local disk plus R2 cache where applicable.
- Progress is the run event stream, not hidden chat history.

### QwenPaw

- Web console style for agent inspection.
- Skill/channel/agent organization.
- Memory and tool guard panels.
- Simple CLI command surface.

99Pages mapping:

- Cockpit should expose Agent Rooms, Worker Cards, Tool Calls, Approvals, and
  Evidence Panels.
- MCP, Skill, Plugin, and Mini App are one capability model in the UI.
- Slash commands should stay simple enough for Core CLI and Telegram.

## V3 Compatibility Schema

### Agent Room

```json
{
  "run_id": "run_...",
  "title": "Deploy workspace to VPS",
  "main_agent": "workforce:main",
  "status": "running",
  "workers": ["worker_project", "worker_ssh"],
  "created_at": "2026-05-22T00:00:00Z"
}
```

### Worker Card

```json
{
  "worker_id": "worker_project",
  "profile": "project_triage",
  "module": "agentic-mcp-project",
  "status": "running",
  "current_step": "reading task context",
  "last_event_id": "evt_..."
}
```

### Event

```json
{
  "event_id": "evt_...",
  "run_id": "run_...",
  "type": "tool_call",
  "actor": "worker_project",
  "summary": "called ProjectListTasks",
  "evidence": [{"type": "mcp_call", "ref": "ProjectListTasks"}]
}
```

### Approval

```json
{
  "approval_id": "appr_...",
  "run_id": "run_...",
  "requested_by": "worker_ssh",
  "action": "write remote deploy env",
  "risk": "medium",
  "status": "pending"
}
```

## Cockpit Projection

Cockpit should add an Agent Room view inspired by these systems:

- Left: runs and rooms.
- Center: timeline/event stream.
- Right: worker cards, approvals, evidence, and files.
- Bottom: command composer with slash commands and voice message.

This view should be draggable/resizable like a workbench. It should not expose
raw provider names or hidden relay endpoints.

## CLI Projection

Core CLI should keep the OpenClaw-like simplicity:

```text
/help
/run <task>
/agents
/mcp
/events <run_id>
/watch <run_id>
/approve <approval_id>
/handoff <profile> <task>
/vault
/exit
```

The command grammar should call existing V3 commands first. The TUI is a
projection of the same runtime, not a second agent implementation.

## Telegram Projection

Telegram should receive the same run summaries that Cockpit sees:

- Task accepted.
- Worker started.
- Tool called.
- Approval needed.
- Evidence captured.
- Run completed or failed.

The bot must use local message context and run events. It should not invent
progress when no event was emitted.

## Obsidian/Wiki Projection

Obsidian is the human-authored memory layer. Wiki is the product doctrine layer.
Library owns indexing and retrieval. This mirrors AgentScope/QwenPaw memory
separation while keeping 99Pages local-first.

## Licensing Rule

Use these projects as architecture references. If code is copied later, the
source license and notice must be preserved. MIT or Apache-compatible snippets
still need attribution in the repository notice file.

## Implementation Order

1. Keep V3 run event stream stable.
2. Add room and worker card projection contracts.
3. Wire SubCLI task fanout into room events.
4. Make Telegram progress consume events.
5. Add Cockpit Agent Room panel.
6. Add compatibility importers only after the native contract is stable.
