Add agent mode service: policy-bound local autopilot (Phase 1)

New Python service on :8476 implementing supervised agent layer with
deny-by-default policy engine, capability tokens, hard budgets, and
storage gateway. Includes systemd sandboxing, UI proxy endpoints,
OpenAPI schema, and 82 tests (all passing).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SecAI-Hub

.github/workflows/ci.yml

@@ -67,6 +67,13 @@ jobs:
           python -m py_compile services/common/audit_chain.py
           python -m py_compile services/common/auth.py
           python -m py_compile services/common/mlock_helper.py
+          python -m py_compile services/agent/agent/app.py
+          python -m py_compile services/agent/agent/models.py
+          python -m py_compile services/agent/agent/policy.py
+          python -m py_compile services/agent/agent/planner.py
+          python -m py_compile services/agent/agent/executor.py
+          python -m py_compile services/agent/agent/storage.py
+          python -m py_compile services/agent/agent/capabilities.py
 
       - name: Test
         run: python -m pytest tests/ -v

docs/api.md

@@ -111,6 +111,79 @@ Proxy an outbound request through the Airlock.
 
 ---
 
+## Agent API (port 8476)
+
+### POST /v1/task
+
+Submit a new task for the agent to plan and execute.
+
+- **Request body:**
+  ```json
+  {
+    "intent": "summarize the documents in my workspace",
+    "mode": "standard",
+    "workspace": ["/vault/user_docs/project"],
+    "preferences": { "read_file": "always" }
+  }
+  ```
+- **Response:** `201 Created` -- task with planned steps
+- **Error:** `400 Bad Request` -- missing intent or invalid mode
+
+### GET /v1/task/{id}
+
+Get task status and step details.
+
+- **Response:** `200 OK` -- task object with steps
+- **Error:** `404 Not Found` -- task not found
+
+### POST /v1/task/{id}/approve
+
+Approve pending steps that require user confirmation.
+
+- **Request body:**
+  ```json
+  {
+    "step_ids": ["abc123"],
+    "approve_all": false
+  }
+  ```
+- **Response:** `200 OK` -- updated task
+
+### POST /v1/task/{id}/deny
+
+Deny pending steps.
+
+- **Request body:**
+  ```json
+  {
+    "step_ids": ["abc123"],
+    "deny_all": false
+  }
+  ```
+- **Response:** `200 OK` -- updated task
+
+### POST /v1/task/{id}/cancel
+
+Cancel a running or pending task.
+
+- **Response:** `200 OK` -- task cancelled
+- **Error:** `409 Conflict` -- task already completed/failed/cancelled
+
+### GET /v1/tasks
+
+List all tasks (most recent first).
+
+- **Query params:** `limit` (default 50, max 200)
+- **Response:** `200 OK` -- array of task objects
+
+### GET /v1/modes
+
+List available operating modes with descriptions.
+
+- **Response:** `200 OK` -- array of mode objects (offline_only, standard, online_assisted, sensitive)
+
+---
+
 ## UI API (port 8480)
 
 ### Model Management

docs/architecture.md

@@ -22,7 +22,11 @@ A 7-stage verification pipeline that every model must pass before promotion. Che
 
 The active inference environment. llama-server runs promoted models from the trusted registry. The Tool Firewall gates all tool invocations through a default-deny policy. The Search Mediator (disabled by default) provides sanitized, Tor-routed web search.
 
-### 5. Airlock
+### 5. Agent Layer
+
+A policy-bound local autopilot that orchestrates bounded local workflows. The Agent (:8476) decomposes user intent into steps, evaluates each step against a deny-by-default policy engine with capability tokens and sensitivity labels, then executes approved steps through the storage gateway and tool firewall. Low-risk local actions (search, summarize, draft) run automatically; high-risk actions (outbound requests, exports, trust changes) require explicit approval. See [Agent Mode](components/agent.md) for full details.
+
+### 6. Airlock
 
 The controlled boundary between the appliance and the external network. Disabled by default because it represents the largest privacy risk surface. When enabled, it enforces destination allowlists, PII scanning, credential scanning, rate limiting, and HTTPS-only connections.
 
@@ -62,6 +66,13 @@ The controlled boundary between the appliance and the external network. Disabled
                               +--------+---------+
                                        |
                               +--------v---------+
+                              |   Agent Autopilot |
+                              |  :8476 (Py)       |
+                              | (planner, policy, |
+                              |  storage gateway) |
+                              +--------+---------+
+                                       |
+                              +--------v---------+
                               |     UI (Flask)    |
                               |  :8480 (Py)       |
                               +--------+---------+
@@ -85,6 +96,11 @@ The controlled boundary between the appliance and the external network. Disabled
 
 ```
 UI (:8480)
+  |-- Agent (:8476)                 [task orchestration, policy enforcement]
+  |     |-- Inference Worker         [planning via LLM]
+  |     |-- Tool Firewall (:8475)   [tool invocation gating]
+  |     |-- Storage Gateway          [mediated file access]
+  |     +-- Airlock (:8490)         [outbound requests, if enabled]
   |-- Inference Worker (llama-server)
   |     |-- Registry (:8470)        [model loading]
   |     |-- Tool Firewall (:8475)   [tool invocation]

docs/components/agent.md

@@ -0,0 +1,125 @@
+# Agent Mode
+
+Policy-bound local autopilot for SecAI_OS. Automates bounded local
+workflows while preserving the project's security and privacy posture.
+
+## Design
+
+The agent is a **supervised local autopilot**, not a free-roaming autonomous
+agent. It runs low-risk local tasks automatically and interrupts only at
+high-risk boundaries such as outbound requests, export actions, destructive
+operations, or trust-state changes.
+
+### Architecture (5 components)
+
+```
+User Intent
+    ↓
+┌──────────┐
+│ Planner  │  Decomposes intent into steps (via inference worker or heuristic)
+└────┬─────┘
+     ↓
+┌──────────────┐
+│ Policy Engine│  Deny-by-default. Evaluates each step against capabilities,
+│              │  workspace scope, sensitivity labels, and session mode.
+└────┬─────────┘
+     ↓ allow / ask / deny
+┌──────────────┐
+│  Executor    │  Runs approved steps with budget enforcement.
+│              │  Dispatches to storage gateway, tool firewall, or airlock.
+└────┬─────────┘
+     ↓
+┌──────────────┐       ┌────────────────┐
+│ Storage GW   │       │  Tool Firewall │
+│ (file access)│       │  (:8475)       │
+└──────────────┘       └────────────────┘
+```
+
+### Operating modes
+
+| Mode | Network | File scope | Approval style |
+|------|---------|-----------|----------------|
+| **Offline-only** | Blocked | Approved workspaces | Auto for low-risk |
+| **Standard** (default) | Disabled unless enabled | Approved workspaces | Auto + ask |
+| **Online-assisted** | Airlock-mediated | Approved workspaces | Always ask for online |
+| **Sensitive** | Blocked | Explicitly scoped | Tighter budgets, aggressive recycling |
+
+### Allow / deny matrix
+
+- **Allow by default (auto)**: local search, summarize, draft, classify, report, explain security decisions
+- **Configurable (user preference: always / ask / never)**: file reads, file writes, tool invocations
+- **Hard approval required**: outbound requests, data export, trust changes, batch deletes, scope widening, new tools
+- **Always denied**: security setting changes
+
+## Service details
+
+| Property | Value |
+|----------|-------|
+| Port | 8476 |
+| Language | Python (Flask) |
+| Bind | 127.0.0.1 (loopback only) |
+| Systemd unit | `secure-ai-agent.service` |
+| Policy file | `/etc/secure-ai/policy/agent.yaml` |
+| Audit log | `/var/lib/secure-ai/logs/agent-audit.jsonl` |
+| Depends on | registry, tool-firewall, inference |
+
+## API endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/v1/task` | Submit a new task |
+| GET | `/v1/task/<id>` | Get task status |
+| POST | `/v1/task/<id>/approve` | Approve pending steps |
+| POST | `/v1/task/<id>/deny` | Deny pending steps |
+| POST | `/v1/task/<id>/cancel` | Cancel a task |
+| GET | `/v1/tasks` | List tasks |
+| GET | `/v1/modes` | List operating modes |
+| GET | `/health` | Health check |
+
+## Capability tokens
+
+Every task run receives a scoped capability token defining:
+- **Readable paths**: which directories the agent may read
+- **Writable paths**: where the agent may write output
+- **Allowed tools**: which tools may be invoked through the tool firewall
+- **Online access**: whether outbound requests are even possible
+- **Sensitivity ceiling**: maximum data sensitivity level (low / medium / high)
+
+## Hard budgets
+
+Each task is constrained by:
+- Max plan steps (default: 30)
+- Max tool calls (default: 80)
+- Max tokens (default: 32,000)
+- Max wall-clock time (default: 600s)
+- Max files touched (default: 20)
+- Max output size (default: 1 MB)
+
+Sensitive mode uses tighter limits (10 steps, 120s, 5 files).
+
+## Storage gateway
+
+All file access goes through the storage gateway, which:
+- Validates paths against the capability token scope
+- Blocks access to sensitive system files (`/etc/shadow`, service tokens, etc.)
+- Classifies file sensitivity (heuristic: SSN, email, credit card, credential patterns)
+- Enforces sensitivity ceiling (high-sensitivity files blocked in low-ceiling sessions)
+- Redacts sensitive content before any outbound use
+- Enforces file size limits (2 MB read, 1 MB write)
+
+## Sandboxing
+
+The agent systemd service uses the same defense-in-depth as other services:
+- `DynamicUser=yes`, `ProtectSystem=strict`, `ProtectHome=yes`
+- `PrivateTmp=yes`, `PrivateDevices=yes`, `NoNewPrivileges=yes`
+- `MemoryDenyWriteExecute=yes`, `RestrictNamespaces=yes`
+- `SystemCallFilter=@system-service @network-io`
+- `MemoryMax=512M`, `CPUQuota=50%`, `TasksMax=64`
+- Read-only access to vault user docs; read-write only to outputs and logs
+
+## Implementation phases
+
+1. **Phase 1** (current): Safe local autopilot — planner, policy engine, storage gateway, tool-firewall mediation, capability tokens, automatic low-risk workflows, UI approval flow
+2. **Phase 2**: Security explainability — detailed explanations for quarantine/registry/airlock decisions, per-workspace permissions, sensitivity labels, audit views
+3. **Phase 3**: Online-assisted mode — airlock-mediated outbound, search mediation, redaction flows, approval UX for online steps
+4. **Phase 4**: Stronger isolation — adversarial testing, signed releases, additional sandboxing profiles, policy bypass regression tests

files/scripts/build-services.sh

@@ -120,6 +120,18 @@ for scanner in modelscan fickling garak modelaudit; do
         echo "  WARNING: ${scanner} install failed — scanner will be skipped at runtime"
 done
 
+# --- Agent service (policy-bound local autopilot) ---
+echo "Building: agent"
+pip3 install --prefix=/usr --no-cache-dir /tmp/services/agent 2>/dev/null || \
+    pip3 install --prefix=/usr --break-system-packages --no-cache-dir /tmp/services/agent
+cat > "${INSTALL_DIR}/agent" <<'WRAPPER'
+#!/usr/bin/env python3
+from agent.app import main
+main()
+WRAPPER
+chmod +x "${INSTALL_DIR}/agent"
+echo "  -> ${INSTALL_DIR}/agent"
+
 # Web UI
 echo "Building: ui"
 pip3 install --prefix=/usr --no-cache-dir /tmp/services/ui 2>/dev/null || \

files/system/etc/secure-ai/config/appliance.yaml

@@ -42,6 +42,8 @@ services:
     bind: "127.0.0.1:8470"
   tool_firewall:
     bind: "127.0.0.1:8475"
+  agent:
+    bind: "127.0.0.1:8476"
   ui:
     bind: "127.0.0.1:8480"
   airlock:
@@ -55,6 +57,18 @@ services:
   tor:
     socks: "127.0.0.1:9050"
 
+# Agent mode configuration (spec: SecAI_OS Agent Mode Specification)
+# The agent is a supervised local autopilot — not an autonomous agent.
+# It automates bounded local workflows and treats every online action
+# as a policy-gated exception routed through the airlock.
+agent:
+  # Whether agent mode is available (default: true, per spec §1)
+  enabled: true
+  # Default operating mode: offline_only | standard | online_assisted | sensitive
+  default_mode: "standard"
+  # Policy file for agent-specific rules
+  policy_path: "/etc/secure-ai/policy/agent.yaml"
+
 traffic_analysis_protection:
   # Network traffic analysis countermeasures (M19).
   # Query timing randomization: random 0.5–3s delay before each search.