Implement install stages S3–S5: package, policy, and skills sync.

Attach/onboard sandbox from agents/hermes, additive OpenShell policy overlays, and nemohermes skill install for scaffold skills. No doctor/connect and no push.
2026-07-27 12:13:25 -07:00
parent e5e179e541
commit 0198ab6881
38 changed files with 1422 additions and 51 deletions
@@ -1,14 +1,52 @@
-# OpenShell policy (scaffold)
+# OpenShell policy

-**Status:** Structure only — no live policy applied until **build**.
+**Status:** Base policy and overlays ready for S5.

-## Intended contents
+## Structure

 | Path | Purpose |
 |------|---------|
-| `policy.yaml` (or equivalent) | Deny-by-default base for salon egress |
-| `overlays/` | Per-integration allowlists (Square MCP host, QBO local, channels, etc.) |
+| `base.yaml` | Deny-by-default intent (reference; not applied directly) |
+| `overlays/inference.yaml` | Inference endpoint (applied at S5) |
+| `overlays/square-mcp.yaml` | Square MCP (applied at S7 when connected) |
+| `overlays/quickbooks.yaml` | QuickBooks Online (applied at S7 when connected) |
+| `overlays/vagaro.yaml` | Vagaro REST API (applied at S7 when connected) |
+| `overlays/channels.yaml` | Messaging channels (applied at S7 when connected) |

-Apply via platform CLIs only: `openshell policy set`, `nemohermes <name> policy-add` / `policy-remove`.
+## Policy lifecycle

-See [design/mcp-integrations.md](../../design/mcp-integrations.md) and [docs/POLICY.md](../../docs/POLICY.md).
+1. **Install (S5):** Apply inference overlay. Existing balanced-tier presets (npm, pypi, huggingface, brew) are preserved.
+2. **Connect (S7):** Apply SaaS/channel overlays as integrations are enabled.
+3. **Upgrade:** Re-apply all overlays (idempotent via `--yes`).
+4. **Doctor (S6):** Verify active policy matches expected state.
+
+## Apply policy
+
+```bash
+# Apply inference overlay (S5)
+nemohermes <name> policy-add --from-file policy/openshell/overlays/inference.yaml --yes
+
+# Apply SaaS overlay (S7, when connected)
+nemohermes <name> policy-add --from-file policy/openshell/overlays/square-mcp.yaml --yes
+
+# Apply built-in channel preset (S7, when connected)
+nemohermes <name> policy-add telegram --yes
+
+# List active presets
+nemohermes <name> policy-list
+
+# Export current policy
+nemohermes <name> policy-get
+```
+
+## Key principles
+
+- **Additive only:** policy-add never removes existing presets.
+- **No wipe:** Never remove balanced-tier presets (npm, pypi, huggingface, brew).
+- **Always deny:** Social publish, payment/refund/payout/bill-pay are never allowed.
+- **Platform-first:** All policy mutations via `nemohermes` / `openshell` CLIs.
+
+## Design reference
+
+- [design/DESIGN_PLAN.md §3](../../design/DESIGN_PLAN.md) — Hermes as NemoClaw-managed infrastructure
+- [docs/POLICY.md](../../docs/POLICY.md) — Full policy documentation
@@ -0,0 +1,33 @@
+# policy/openshell/base.yaml
+# Lumina base policy — reference document.
+#
+# This file documents the deny-by-default intent for the Lumina sandbox.
+# It is NOT applied directly. The live policy is managed by nemohermes
+# policy-add/policy-remove commands.
+#
+# Apply via: nemohermes <name> policy-add --from-file <path>
+#
+# ── Deny-by-default intent ────────────────────────────────────────────────
+#
+# The sandbox starts with NO network egress except what is explicitly allowed
+# by applied policy presets. The base tier (balanced) provides:
+#
+#   npm, pypi, huggingface, brew  — package management (always allowed)
+#
+# Lumina adds overlays for:
+#   - inference endpoints (main model + vision)
+#   - SaaS integrations (Square, QBO, Vagaro) — when connected
+#   - messaging channels (WhatsApp, Telegram, Email) — when connected
+#
+# ── Always deny ────────────────────────────────────────────────────────────
+# - Social publish APIs (no silent publish)
+# - Payment/refund/payout/bill-pay endpoints
+# - Any host not explicitly listed in an overlay
+#
+# ── Policy lifecycle ───────────────────────────────────────────────────────
+# 1. Install (S5): apply base overlays (inference)
+# 2. Connect (S7): apply SaaS/channel overlays as integrations are enabled
+# 3. Upgrade: re-apply all overlays (idempotent)
+# 4. Doctor (S6): verify active policy matches expected state
+#
+# See docs/POLICY.md for full policy documentation.
@@ -0,0 +1,18 @@
+# policy/openshell/overlays/channels.yaml
+# Messaging channels policy overlay (applied at S7 when channels are connected).
+#
+# Allows the sandbox to reach messaging channel APIs. Each channel has
+# its own built-in preset in nemohermes (telegram, whatsapp, slack, etc.).
+# This overlay documents which channels Lumina uses.
+#
+# Apply via: nemohermes <name> policy-add <preset-name> --yes
+# (Built-in presets; no --from-file needed for standard channels)
+#
+# Planned channels:
+#   - whatsapp  (nemohermes built-in preset)
+#   - telegram  (nemohermes built-in preset)
+#   - email     (handled by openshell provider store)
+#
+# Rules:
+#   - Owner ↔ agent: full messaging
+#   - Client outbound: draft-first only (no silent send/publish)
@@ -0,0 +1,49 @@
+# policy/openshell/overlays/inference.yaml
+# Inference endpoint policy overlay for Lumina.
+#
+# Allows the sandbox to reach the configured inference endpoint through
+# the OpenShell gateway. The gateway resolves inference.local to the
+# actual endpoint URL from .env.
+#
+# Apply via: nemohermes <name> policy-add --from-file <this-file> --yes
+#
+# This overlay is additive — it does not remove existing presets.
+
+preset:
+  name: lumina-inference
+network_policies:
+  lumina-inference:
+    name: lumina-inference
+    endpoints:
+      - host: inference.local
+        port: 443
+        protocol: rest
+        enforcement: enforce
+        rules:
+          - allow:
+              method: POST
+              path: /v1/chat/completions
+          - allow:
+              method: POST
+              path: /v1/messages
+          - allow:
+              method: POST
+              path: /v1/responses
+          - allow:
+              method: POST
+              path: /v1/completions
+          - allow:
+              method: POST
+              path: /v1/embeddings
+          - allow:
+              method: GET
+              path: /v1/models
+          - allow:
+              method: GET
+              path: /v1/models/**
+    binaries:
+      - path: /usr/local/bin/hermes
+      # Glob supported by nemohermes policy engine (verified against built-in
+      # presets: huggingface, nous_research, npm_yarn, pypi all use python3*)
+      - path: /usr/bin/python3*
+      - path: /opt/hermes/.venv/bin/python
@@ -0,0 +1,38 @@
+# policy/openshell/overlays/quickbooks.yaml
+# QuickBooks Online policy overlay (applied at S7 when QBO is connected).
+#
+# Allows the sandbox to reach QuickBooks Online APIs for read operations
+# (reports, search, get). Write/update/delete operations are excluded
+# at the MCP tool level.
+#
+# Apply via: nemohermes <name> policy-add --from-file <this-file> --yes
+
+preset:
+  name: quickbooks-online
+network_policies:
+  quickbooks-online:
+    name: quickbooks-online
+    endpoints:
+      - host: quickbooks.api.intuit.com
+        port: 443
+        protocol: rest
+        enforcement: enforce
+        rules:
+          - allow:
+              method: GET
+              path: /**
+          - allow:
+              method: POST
+              path: /**
+      - host: oauth.platform.intuit.com
+        port: 443
+        protocol: rest
+        enforcement: enforce
+        rules:
+          - allow:
+              method: POST
+              path: /**
+    binaries:
+      - path: /usr/local/bin/hermes
+      - path: /usr/bin/python3*
+      - path: /opt/hermes/.venv/bin/python
@@ -0,0 +1,30 @@
+# policy/openshell/overlays/square-mcp.yaml
+# Square MCP policy overlay (applied at S7 when Square is connected).
+#
+# Allows the sandbox to reach Square's MCP server for bookings, customers,
+# catalog, and inventory reads. Payment/refund/payout tools are excluded
+# at the MCP tool level, not the network level.
+#
+# Apply via: nemohermes <name> policy-add --from-file <this-file> --yes
+
+preset:
+  name: square-mcp
+network_policies:
+  square-mcp:
+    name: square-mcp
+    endpoints:
+      - host: connect.squareup.com
+        port: 443
+        protocol: rest
+        enforcement: enforce
+        rules:
+          - allow:
+              method: GET
+              path: /**
+          - allow:
+              method: POST
+              path: /**
+    binaries:
+      - path: /usr/local/bin/hermes
+      - path: /usr/bin/python3*
+      - path: /opt/hermes/.venv/bin/python
@@ -0,0 +1,33 @@
+# policy/openshell/overlays/vagaro.yaml
+# Vagaro policy overlay (applied at S7 when Vagaro is connected).
+#
+# Allows the sandbox to reach Vagaro's REST API for appointments, clients,
+# services, and staff data. Webhook ingestion is handled by the local
+# vagaro-webhooks service (compose-managed), not direct sandbox egress.
+#
+# Apply via: nemohermes <name> policy-add --from-file <this-file> --yes
+
+preset:
+  name: vagaro
+network_policies:
+  vagaro:
+    name: vagaro
+    endpoints:
+      - host: api.vagaro.com
+        port: 443
+        protocol: rest
+        enforcement: enforce
+        rules:
+          - allow:
+              method: GET
+              path: /**
+          - allow:
+              method: POST
+              path: /**
+          - allow:
+              method: PUT
+              path: /**
+    binaries:
+      - path: /usr/local/bin/hermes
+      - path: /usr/bin/python3*
+      - path: /opt/hermes/.venv/bin/python