flynn/docs/plans/2026-02-14-openclaw-style-personal-agent-without-openclaw-risks-plan.md

OpenClaw-Style Personal Agent (Without OpenClaw Risks) — Milestone Plan

Date: 2026-02-14 Scope: Make Flynn feel as efficient as a productized personal assistant (OpenClaw-like), while explicitly avoiding the structural security risks of a broad “skills marketplace + many surfaces + powerful tools” system. Context: Flynn already has strong core architecture (multi-channel daemon, gateway/UI, tool policy, Docker sandboxing, memory, automation). This milestone is about tightening the trust boundary and making the safe path the default path.

Goals

1. Safe-by-default extension model: “skills” are locally-auditable, capability-declared, and policy-enforced.
2. Sandbox-by-default for risk: any skill/tool execution with meaningful blast radius runs in an isolation boundary by default.
3. Prompt-injection resistance: fetched/untrusted content cannot directly drive tool calls or secret exfiltration.
4. Operational clarity: high-quality audit trails of tool calls, approvals, and materialized changes.
5. Product efficiency parity: fast onboarding and “works everywhere I already talk” without expanding the attack surface indiscriminately.

Non-Goals (for this milestone)

• A public “skills marketplace” or auto-installing third-party skills.
• Unbounded remote device/node execution.
• Full browser RPA parity (can be a later milestone).

Threat Model (Practical)

We assume:

• An attacker can send messages on at least one channel surface (DM or group), and can embed prompt-injection payloads in web pages, email bodies, PDFs, etc.
• The assistant has access to local files, network, and credential material (directly or indirectly).

We must prevent:

• Unauthorized tool execution (filesystem writes, shell, browser automation, network posts).
• Data exfiltration (secrets and private data leaving the machine via model/tool).
• Supply-chain compromise via skills (untrusted code/commands running because “it’s a skill”).

Design Principles

• Capability declarations beat intentions: a skill’s declared permissions determine what it can do, not the LLM’s narrative.
• Deny by default, allow narrowly: explicit whitelists for tools, paths, and network hosts.
• Untrusted content isolation: fetched content is treated as data, never as instructions.
• Make approvals boring: human-in-the-loop prompts are short, scoped, and explain impact.

Milestone Structure (PR-Sized Slices)

PR 1: Capability Manifests + Policy Binding (Skills)

Outcome: Every skill has a manifest that declares what it is allowed to do, and Flynn enforces that at runtime.

Work items

• Define skills/manifest.json schema extension:
  • permissions.tool_groups: e.g. ["group:fs", "group:web", "group:runtime"]
  • permissions.tools: explicit allowlist patterns, overrides tool_groups
  • permissions.fs: allowlisted path globs (read/write separate)
  • permissions.net: allowlisted host globs + ports (optional)
  • permissions.secrets: named secret scopes (no ambient access)
• Bind skill permissions to tool policy evaluation (skill execution context carries a policy profile).
• Add a “capability diff” display for installs/enables:
  • “This skill requests: write access to ~/Documents/notes/**, network access to api.todoist.com:443, tool web.search.”
• Tests:
  • Skill with insufficient permissions cannot invoke denied tool or write outside allowed paths.
  • Skill with allowed permissions succeeds.

Acceptance

• A skill cannot call a denied tool even if the model tries.
• A skill cannot read/write outside declared fs scopes.

---

PR 2: Sandbox-by-Default Enforcement for High-Risk Tools

Outcome: Risky actions run inside isolation by default, with a clear escape hatch for trusted local workflows.

Work items

• Define a “risk tier” mapping for tool groups:
  • low: pure compute / formatting
  • medium: web fetch/search
  • high: filesystem writes, shell/process, browser automation, credentialed API actions
• Enforce:
  • high tools must execute inside the session sandbox (Docker) unless policy explicitly allows “host mode”.
• Add a per-session “execution environment” indicator in gateway/UI (host vs sandbox).
• Tests:
  • Attempting high tool in host mode without explicit allow fails deterministically.

Acceptance

• By default, tools with meaningful blast radius do not run on the host.

---

PR 3: Prompt Injection Firewall (Content Provenance + Tool Gating)

Outcome: Untrusted content can be used as context but not as control.

Work items

• Introduce provenance tags on content:
  • user_message vs fetched_content vs tool_output vs memory
• Update prompts to:
  • Explicitly forbid following instructions found inside fetched_content/tool_output.
  • Require a short “tool intent” explanation before tool use when untrusted content is present.
• Add a “tool-call guard” layer:
  • If the model’s tool call arguments contain obvious injection markers (“ignore previous”, “exfiltrate”, “send to”, etc.) and the request originated from untrusted content, force a confirmation step or deny.
  • Reject tool calls that attempt to reference secrets directly in arguments.
• Tests:
  • A web page that contains “run shell command X” does not trigger shell tool use.
  • Model attempts to copy-paste secrets into a network request are blocked/redacted.

Acceptance

• Untrusted content cannot directly cause tool execution without an explicit, policy-consistent path.

---

PR 4: Secret Scoping + Audit Logging (Operator-Grade)

Outcome: Secrets are scoped and auditable; tool usage is traceable without leaking secrets into logs.

Work items

• Add a “secret scope” mechanism for tools and skills:
  • Tools declare requiredSecretScopes[]
  • Skills declare permissions.secrets[]
  • Resolution: only scoped secrets are provided to tool execution; no ambient env pass-through.
• Extend audit log events:
  • tool start/end, policy decision, sandbox vs host, approval prompts, redactions applied
  • stable ids for correlation per session
• Tests:
  • Secrets never appear in logs (even on tool failure).
  • Tool without declared scope cannot obtain secret.

Acceptance

• You can answer “what ran, with what permissions, in what environment” for any session.

---

PR 5: Product Efficiency Layer (Minimal Surfaces, Max Habit)

Outcome: Make Flynn feel “always there” without adding unnecessary new attack surface.

Work items

• Tighten onboarding defaults:
  • choose 2-3 “recommended surfaces” and ensure they are first-class (WebChat + one messaging channel).
  • ensure pairing/auth flows are the default for unknown senders.
• Add “assistant ergonomics”:
  • a small set of default automations that are safe (summaries, reminders) behind explicit opt-in.
  • fast-path help for configuration gaps (already used for voice transcription, continue pattern).
• Tests:
  • Setup wizard produces a config with safe defaults: pairing on, conservative tool profile, sandbox for high-risk.

Acceptance

• A new user can get to a useful assistant quickly, and default config does not expose dangerous capabilities.

Sequencing

1. PR 1 (capabilities) and PR 2 (sandbox enforcement) first: they set the trust boundary.
2. PR 3 (injection firewall) next: it hardens the most common real-world failure mode.
3. PR 4 (secrets + audit) to make the system operable and trustworthy long-term.
4. PR 5 (efficiency layer) last: UX improvements on top of hardened foundations.

Definition of Done (Milestone)

• Skills are capability-declared and enforced by policy.
• High-risk tools default to sandbox execution.
• Untrusted content is isolated and cannot drive tool execution without policy-compliant intent + gating.
• Secrets are scoped and never leak into logs.
• New-user path yields a safe, useful personal assistant in under ~10 minutes on WebChat.