docs: add safety docs and OpenClaw gap roadmap

2026-02-15 10:17:07 -08:00
parent 28304ac397
commit f2cdd1abd2
14 changed files with 3869 additions and 40 deletions
@@ -0,0 +1,143 @@
+# Symbol Index (Agent Quick-Jump)
+
+This is a curated index of the most important exported types and functions, organized for fast navigation.
+
+It is intentionally short: if something isn't here, it's probably not a primary control surface.
+
+See also:
+
+- `docs/architecture/TYPESCRIPT_MAP.md` (conceptual map + diagrams)
+- `docs/architecture/AGENT_DIAGRAM.md` (runtime flow)
+
+## Daemon Entry Points
+
+- `src/daemon/index.ts`
+  - Creates/wires: config, tool registry, tool executor, skill registry, model router, gateway, channels.
+
+- `src/daemon/routing.ts`
+  - `createMessageRouter(deps)`
+    - Main router factory used by channel adapters + gateway.
+
+## Routing / Intents / Agents
+
+- `src/agents/router.ts`
+  - `AgentRouter.resolve(channel, senderId)`
+    - Picks an agent config for a sender/channel.
+
+- `src/agents/registry.ts`
+  - `AgentConfigRegistry.get(name)`
+    - Loads agent configs.
+
+- `src/intents/registry.ts`
+  - `IntentRegistry.match(text)`
+    - Matches text to intent rules (targets: agent or skill).
+
+## Native Agent Loop
+
+- `src/backends/native/orchestrator.ts`
+  - `AgentOrchestrator.process(message, options)`
+    - Top-level entry for “run agent on this message”.
+
+- `src/backends/native/agent.ts`
+  - `NativeAgent` (class)
+  - Internal hot path: tool loop that:
+    - asks model
+    - executes tools
+    - returns tool results
+    - repeats
+
+## Models
+
+- `src/models/router.ts`
+  - `ModelRouter.chat(request)`
+    - Chooses tier/provider fallback chain.
+
+- `src/models/types.ts`
+  - Core request/response types shared by providers.
+
+## Tools
+
+- `src/tools/types.ts`
+  - `Tool`
+  - `ToolResult`
+
+- `src/tools/registry.ts`
+  - `ToolRegistry.register(tool)`
+  - `ToolRegistry.list()`
+  - `ToolRegistry.clone()` / `ToolRegistry.replace(tool)` (used for sandbox substitution)
+
+- `src/tools/policy.ts`
+  - `ToolPolicy` (class)
+  - `ToolPolicy.resolveAllowedNames(allToolNames, context)`
+  - `ToolPolicyContext` (type)
+  - `TOOL_GROUPS` (group expansion)
+
+- `src/tools/executor.ts`
+  - `ToolExecutor.execute(toolName, args, context)`
+    - Central enforcement point:
+      - policy allow/deny
+      - hooks/autonomy confirmations
+      - skill fs/net/secret constraints
+      - untrusted-content injection guard
+      - audit events w/ redaction
+
+## Skills
+
+- `src/skills/types.ts`
+  - `SkillManifest`
+  - `SkillPermissions`
+
+- `src/skills/loader.ts`
+  - `loadSkill(dir, tier)`
+  - `loadAllSkills(...)`
+    - Validates manifests.
+
+- `src/skills/registry.ts`
+  - `SkillRegistry.get(name)`
+  - `SkillRegistry.getSystemPromptAdditions()`
+
+## Hooks / Approval
+
+- `src/hooks/engine.ts`
+  - `HookEngine.getAction(toolName)`
+  - `HookEngine.requestConfirmation(toolName, args)`
+
+- `src/hooks/autonomy.ts`
+  - `resolveAutonomy(toolName, baseAction, autonomyLevel)`
+
+## Sandbox
+
+- `src/sandbox/manager.ts`
+  - Manages per-session sandbox lifecycle.
+
+- `src/sandbox/tools.ts`
+  - Creates sandboxed tool implementations for `shell.exec` / `process.start`.
+
+- `src/sandbox/docker.ts`
+  - Docker-specific implementation.
+
+## Audit
+
+- `src/audit/index.ts`
+  - `auditLogger` singleton.
+
+- `src/audit/types.ts`
+  - Event types (`tool.start`, `tool.success`, `tool.denied`, `tool.approval`, ...)
+
+- `src/audit/logger.ts`
+  - `AuditLogger` methods: `toolStart`, `toolDenied`, `toolApproval`, ...
+
+- `src/audit/redact.ts`
+  - `redactForAudit(value)`
+
+## Gateway
+
+- `src/gateway/server.ts`
+  - WebSocket server lifecycle.
+
+- `src/gateway/handlers/*`
+  - JSON-RPC methods grouped by area.
+
+Protocol:
+
+- `docs/api/PROTOCOL.md`