@symerian/symi 3.0.20 → 3.0.22

package/docs/tools/chrome-extension.md

@@ -1,183 +0,0 @@
----
-summary: "Chrome extension: let Symi drive your existing Chrome tab"
-read_when:
-  - You want the agent to drive an existing Chrome tab (toolbar button)
-  - You need remote Gateway + local browser automation via Tailscale
-  - You want to understand the security implications of browser takeover
-title: "Chrome Extension"
----
-
-# Chrome extension (browser relay)
-
-The Symi Chrome extension lets the agent control your **existing Chrome tabs** (your normal Chrome window) instead of launching a separate symi-managed Chrome profile.
-
-Attach/detach happens via a **single Chrome toolbar button**.
-
-## What it is (concept)
-
-There are three parts:
-
-- **Browser control service** (Gateway or node): the API the agent/tool calls (via the Gateway)
-- **Local relay server** (loopback CDP): bridges between the control server and the extension (`http://127.0.0.1:18792` by default)
-- **Chrome MV3 extension**: attaches to the active tab using `chrome.debugger` and pipes CDP messages to the relay
-
-Symi then controls the attached tab through the normal `browser` tool surface (selecting the right profile).
-
-## Install / load (unpacked)
-
-1. Install the extension to a stable local path:
-
-```bash
-symi browser extension install
-```
-
-2. Print the installed extension directory path:
-
-```bash
-symi browser extension path
-```
-
-3. Chrome → `chrome://extensions`
-
-- Enable “Developer mode”
-- “Load unpacked” → select the directory printed above
-
-4. Pin the extension.
-
-## Updates (no build step)
-
-The extension ships inside the Symi release (npm package) as static files. There is no separate “build” step.
-
-After upgrading Symi:
-
-- Re-run `symi browser extension install` to refresh the installed files under your Symi state directory.
-- Chrome → `chrome://extensions` → click “Reload” on the extension.
-
-## Use it (set gateway token once)
-
-Symi ships with a built-in browser profile named `chrome` that targets the extension relay on the default port.
-
-Before first attach, open extension Options and set:
-
-- `Port` (default `18792`)
-- `Gateway token` (must match `gateway.auth.token` / `SYMI_GATEWAY_TOKEN`)
-
-Use it:
-
-- CLI: `symi browser --browser-profile chrome tabs`
-- Agent tool: `browser` with `profile="chrome"`
-
-If you want a different name or a different relay port, create your own profile:
-
-```bash
-symi browser create-profile \
-  --name my-chrome \
-  --driver extension \
-  --cdp-url http://127.0.0.1:18792 \
-  --color "#00AA00"
-```
-
-## Attach / detach (toolbar button)
-
-- Open the tab you want Symi to control.
-- Click the extension icon.
-  - Badge shows `ON` when attached.
-- Click again to detach.
-
-## Which tab does it control?
-
-- It does **not** automatically control “whatever tab you’re looking at”.
-- It controls **only the tab(s) you explicitly attached** by clicking the toolbar button.
-- To switch: open the other tab and click the extension icon there.
-
-## Badge + common errors
-
-- `ON`: attached; Symi can drive that tab.
-- `…`: connecting to the local relay.
-- `!`: relay not reachable/authenticated (most common: relay server not running, or gateway token missing/wrong).
-
-If you see `!`:
-
-- Make sure the Gateway is running locally (default setup), or run a node host on this machine if the Gateway runs elsewhere.
-- Open the extension Options page; it validates relay reachability + gateway-token auth.
-
-## Remote Gateway (use a node host)
-
-### Local Gateway (same machine as Chrome) — usually **no extra steps**
-
-If the Gateway runs on the same machine as Chrome, it starts the browser control service on loopback
-and auto-starts the relay server. The extension talks to the local relay; the CLI/tool calls go to the Gateway.
-
-### Remote Gateway (Gateway runs elsewhere) — **run a node host**
-
-If your Gateway runs on another machine, start a node host on the machine that runs Chrome.
-The Gateway will proxy browser actions to that node; the extension + relay stay local to the browser machine.
-
-If multiple nodes are connected, pin one with `gateway.nodes.browser.node` or set `gateway.nodes.browser.mode`.
-
-## Sandboxing (tool containers)
-
-If your agent session is sandboxed (`agents.defaults.sandbox.mode != "off"`), the `browser` tool can be restricted:
-
-- By default, sandboxed sessions often target the **sandbox browser** (`target="sandbox"`), not your host Chrome.
-- Chrome extension relay takeover requires controlling the **host** browser control server.
-
-Options:
-
-- Easiest: use the extension from a **non-sandboxed** session/agent.
-- Or allow host browser control for sandboxed sessions:
-
-```json5
-{
-  agents: {
-    defaults: {
-      sandbox: {
-        browser: {
-          allowHostControl: true,
-        },
-      },
-    },
-  },
-}
-```
-
-Then ensure the tool isn’t denied by tool policy, and (if needed) call `browser` with `target="host"`.
-
-Debugging: `symi sandbox explain`
-
-## Remote access tips
-
-- Keep the Gateway and node host on the same tailnet; avoid exposing relay ports to LAN or public Internet.
-- Pair nodes intentionally; disable browser proxy routing if you don’t want remote control (`gateway.nodes.browser.mode="off"`).
-
-## How “extension path” works
-
-`symi browser extension path` prints the **installed** on-disk directory containing the extension files.
-
-The CLI intentionally does **not** print a `node_modules` path. Always run `symi browser extension install` first to copy the extension to a stable location under your Symi state directory.
-
-If you move or delete that install directory, Chrome will mark the extension as broken until you reload it from a valid path.
-
-## Security implications (read this)
-
-This is powerful and risky. Treat it like giving the model “hands on your browser”.
-
-- The extension uses Chrome’s debugger API (`chrome.debugger`). When attached, the model can:
-  - click/type/navigate in that tab
-  - read page content
-  - access whatever the tab’s logged-in session can access
-- **This is not isolated** like the dedicated symi-managed profile.
-  - If you attach to your daily-driver profile/tab, you’re granting access to that account state.
-
-Recommendations:
-
-- Prefer a dedicated Chrome profile (separate from your personal browsing) for extension relay usage.
-- Keep the Gateway and any node hosts tailnet-only; rely on Gateway auth + node pairing.
-- Avoid exposing relay ports over LAN (`0.0.0.0`) and avoid Funnel (public).
-- The relay blocks non-extension origins and requires gateway-token auth for both `/cdp` and `/extension`.
-
-Related:
-
-- Browser tool overview: [Browser](/tools/browser)
-- Security audit: [Security](/gateway/security)
-- Tailscale setup: [Tailscale](/gateway/tailscale)

package/docs/tools/creating-skills.md

@@ -1,54 +0,0 @@
----
-title: "Creating Skills"
----
-
-# Creating Custom Skills 🛠
-
-Symi is designed to be easily extensible. "Skills" are the primary way to add new capabilities to your assistant.
-
-## What is a Skill?
-
-A skill is a directory containing a `SKILL.md` file (which provides instructions and tool definitions to the LLM) and optionally some scripts or resources.
-
-## Step-by-Step: Your First Skill
-
-### 1. Create the Directory
-
-Skills live in your workspace, usually `~/.symi/workspace/skills/`. Create a new folder for your skill:
-
-```bash
-mkdir -p ~/.symi/workspace/skills/hello-world
-```
-
-### 2. Define the `SKILL.md`
-
-Create a `SKILL.md` file in that directory. This file uses YAML frontmatter for metadata and Markdown for instructions.
-
-```markdown
----
-name: hello_world
-description: A simple skill that says hello.
----
-
-# Hello World Skill
-
-When the user asks for a greeting, use the `echo` tool to say "Hello from your custom skill!".
-```
-
-### 3. Add Tools (Optional)
-
-You can define custom tools in the frontmatter or instruct the agent to use existing system tools (like `bash` or `browser`).
-
-### 4. Refresh Symi
-
-Ask your agent to "refresh skills" or restart the gateway. Symi will discover the new directory and index the `SKILL.md`.
-
-## Best Practices
-
-- **Be Concise**: Instruct the model on _what_ to do, not how to be an AI.
-- **Safety First**: If your skill uses `bash`, ensure the prompts don't allow arbitrary command injection from untrusted user input.
-- **Test Locally**: Use `symi agent --message "use my new skill"` to test.
-
-## Shared Skills
-
-You can also browse and contribute skills to [SymiHub](https://symihub.com).

package/docs/tools/elevated.md

@@ -1,55 +0,0 @@
----
-summary: "Elevated exec mode and /elevated directives"
-read_when:
-  - Adjusting elevated mode defaults, allowlists, or slash command behavior
-title: "Elevated Mode"
----
-
-# Elevated Mode (/elevated directives)
-
-## What it does
-
-- `/elevated on` runs on the gateway host and keeps exec approvals (same as `/elevated ask`).
-- `/elevated full` runs on the gateway host **and** auto-approves exec (skips exec approvals).
-- `/elevated ask` runs on the gateway host but keeps exec approvals (same as `/elevated on`).
-- `on`/`ask` do **not** force `exec.security=full`; configured security/ask policy still applies.
-- Only changes behavior when the agent is **sandboxed** (otherwise exec already runs on the host).
-- Directive forms: `/elevated on|off|ask|full`, `/elev on|off|ask|full`.
-- Only `on|off|ask|full` are accepted; anything else returns a hint and does not change state.
-
-## What it controls (and what it doesn’t)
-
-- **Availability gates**: `tools.elevated` is the global baseline. `agents.list[].tools.elevated` can further restrict elevated per agent (both must allow).
-- **Per-session state**: `/elevated on|off|ask|full` sets the elevated level for the current session key.
-- **Inline directive**: `/elevated on|ask|full` inside a message applies to that message only.
-- **Groups**: In group chats, elevated directives are only honored when the agent is mentioned. Command-only messages that bypass mention requirements are treated as mentioned.
-- **Host execution**: elevated forces `exec` onto the gateway host; `full` also sets `security=full`.
-- **Approvals**: `full` skips exec approvals; `on`/`ask` honor them when allowlist/ask rules require.
-- **Unsandboxed agents**: no-op for location; only affects gating, logging, and status.
-- **Tool policy still applies**: if `exec` is denied by tool policy, elevated cannot be used.
-- **Separate from `/exec`**: `/exec` adjusts per-session defaults for authorized senders and does not require elevated.
-
-## Resolution order
-
-1. Inline directive on the message (applies only to that message).
-2. Session override (set by sending a directive-only message).
-3. Global default (`agents.defaults.elevatedDefault` in config).
-
-## Setting a session default
-
-- Send a message that is **only** the directive (whitespace allowed), e.g. `/elevated full`.
-- Confirmation reply is sent (`Elevated mode set to full...` / `Elevated mode disabled.`).
-- If elevated access is disabled or the sender is not on the approved allowlist, the directive replies with an actionable error and does not change session state.
-- Send `/elevated` (or `/elevated:`) with no argument to see the current elevated level.
-
-## Availability + allowlists
-
-- Feature gate: `tools.elevated.enabled` (default can be off via config even if the code supports it).
-- Per-agent gate: `agents.list[].tools.elevated.enabled` (optional; can only further restrict).
-- Per-agent allowlist: `agents.list[].tools.elevated.allowFrom` (optional; when set, the sender must match **both** global + per-agent allowlists).
-- All gates must pass; otherwise elevated is treated as unavailable.
-
-## Logging + status
-
-- Elevated exec calls are logged at info level.
-- Session status includes elevated mode (e.g. `elevated=ask`, `elevated=full`).

package/docs/tools/exec-approvals.md

@@ -1,261 +0,0 @@
----
-summary: "Exec approvals, allowlists, and sandbox escape prompts"
-read_when:
-  - Configuring exec approvals or allowlists
-  - Implementing exec approval UX in the macOS app
-  - Reviewing sandbox escape prompts and implications
-title: "Exec Approvals"
----
-
-# Exec approvals
-
-Exec approvals are the **companion app / node host guardrail** for letting a sandboxed agent run
-commands on a real host (`gateway` or `node`). Think of it like a safety interlock:
-commands are allowed only when policy + allowlist + (optional) user approval all agree.
-Exec approvals are **in addition** to tool policy and elevated gating (unless elevated is set to `full`, which skips approvals).
-Effective policy is the **stricter** of `tools.exec.*` and approvals defaults; if an approvals field is omitted, the `tools.exec` value is used.
-
-If the companion app UI is **not available**, any request that requires a prompt is
-resolved by the **ask fallback** (default: deny).
-
-## Where it applies
-
-Exec approvals are enforced locally on the execution host:
-
-- **gateway host** → `symi` process on the gateway machine
-- **node host** → node runner (macOS companion app or headless node host)
-
-macOS split:
-
-- **node host service** forwards `system.run` to the **macOS app** over local IPC.
-- **macOS app** enforces approvals + executes the command in UI context.
-
-## Settings and storage
-
-Approvals live in a local JSON file on the execution host:
-
-`~/.symi/exec-approvals.json`
-
-Example schema:
-
-```json
-{
-  "version": 1,
-  "socket": {
-    "path": "~/.symi/exec-approvals.sock",
-    "token": "base64url-token"
-  },
-  "defaults": {
-    "security": "deny",
-    "ask": "on-miss",
-    "askFallback": "deny",
-    "autoAllowSkills": false
-  },
-  "agents": {
-    "main": {
-      "security": "allowlist",
-      "ask": "on-miss",
-      "askFallback": "deny",
-      "autoAllowSkills": true,
-      "allowlist": [
-        {
-          "id": "B0C8C0B3-2C2D-4F8A-9A3C-5A4B3C2D1E0F",
-          "pattern": "~/Projects/**/bin/rg",
-          "lastUsedAt": 1737150000000,
-          "lastUsedCommand": "rg -n TODO",
-          "lastResolvedPath": "/Users/user/Projects/.../bin/rg"
-        }
-      ]
-    }
-  }
-}
-```
-
-## Policy knobs
-
-### Security (`exec.security`)
-
-- **deny**: block all host exec requests.
-- **allowlist**: allow only allowlisted commands.
-- **full**: allow everything (equivalent to elevated).
-
-### Ask (`exec.ask`)
-
-- **off**: never prompt.
-- **on-miss**: prompt only when allowlist does not match.
-- **always**: prompt on every command.
-
-### Ask fallback (`askFallback`)
-
-If a prompt is required but no UI is reachable, fallback decides:
-
-- **deny**: block.
-- **allowlist**: allow only if allowlist matches.
-- **full**: allow.
-
-## Allowlist (per agent)
-
-Allowlists are **per agent**. If multiple agents exist, switch which agent you’re
-editing in the macOS app. Patterns are **case-insensitive glob matches**.
-Patterns should resolve to **binary paths** (basename-only entries are ignored).
-Legacy `agents.default` entries are migrated to `agents.main` on load.
-
-Examples:
-
-- `~/Projects/**/bin/peekaboo`
-- `~/.local/bin/*`
-- `/opt/homebrew/bin/rg`
-
-Each allowlist entry tracks:
-
-- **id** stable UUID used for UI identity (optional)
-- **last used** timestamp
-- **last used command**
-- **last resolved path**
-
-## Auto-allow skill CLIs
-
-When **Auto-allow skill CLIs** is enabled, executables referenced by known skills
-are treated as allowlisted on nodes (macOS node or headless node host). This uses
-`skills.bins` over the Gateway RPC to fetch the skill bin list. Disable this if you want strict manual allowlists.
-
-## Safe bins (stdin-only)
-
-`tools.exec.safeBins` defines a small list of **stdin-only** binaries (for example `jq`)
-that can run in allowlist mode **without** explicit allowlist entries. Safe bins reject
-positional file args and path-like tokens, so they can only operate on the incoming stream.
-Validation is deterministic from argv shape only (no host filesystem existence checks), which
-prevents file-existence oracle behavior from allow/deny differences.
-File-oriented options are denied for default safe bins (for example `sort -o`, `sort --output`,
-`sort --files0-from`, `wc --files0-from`, `jq -f/--from-file`, `grep -f/--file`).
-Safe bins also enforce explicit per-binary flag policy for options that break stdin-only
-behavior (for example `sort -o/--output` and grep recursive flags).
-Safe bins also force argv tokens to be treated as **literal text** at execution time (no globbing
-and no `$VARS` expansion) for stdin-only segments, so patterns like `*` or `$HOME/...` cannot be
-used to smuggle file reads.
-Safe bins must also resolve from trusted binary directories (system defaults plus the gateway
-process `PATH` at startup). This blocks request-scoped PATH hijacking attempts.
-Shell chaining and redirections are not auto-allowed in allowlist mode.
-
-Shell chaining (`&&`, `||`, `;`) is allowed when every top-level segment satisfies the allowlist
-(including safe bins or skill auto-allow). Redirections remain unsupported in allowlist mode.
-Command substitution (`$()` / backticks) is rejected during allowlist parsing, including inside
-double quotes; use single quotes if you need literal `$()` text.
-
-Default safe bins: `jq`, `cut`, `uniq`, `head`, `tail`, `tr`, `wc`.
-
-`grep` and `sort` are not in the default list. If you opt in, keep explicit allowlist entries for
-their non-stdin workflows.
-For `grep` in safe-bin mode, provide the pattern with `-e`/`--regexp`; positional pattern form is
-rejected so file operands cannot be smuggled as ambiguous positionals.
-
-## Control UI editing
-
-Use the **Control UI → Nodes → Exec approvals** card to edit defaults, per‑agent
-overrides, and allowlists. Pick a scope (Defaults or an agent), tweak the policy,
-add/remove allowlist patterns, then **Save**. The UI shows **last used** metadata
-per pattern so you can keep the list tidy.
-
-The target selector chooses **Gateway** (local approvals) or a **Node**. Nodes
-must advertise `system.execApprovals.get/set` (macOS app or headless node host).
-If a node does not advertise exec approvals yet, edit its local
-`~/.symi/exec-approvals.json` directly.
-
-CLI: `symi approvals` supports gateway or node editing (see [Approvals CLI](/cli/approvals)).
-
-## Approval flow
-
-When a prompt is required, the gateway broadcasts `exec.approval.requested` to operator clients.
-The Control UI and macOS app resolve it via `exec.approval.resolve`, then the gateway forwards the
-approved request to the node host.
-
-When approvals are required, the exec tool returns immediately with an approval id. Use that id to
-correlate later system events (`Exec finished` / `Exec denied`). If no decision arrives before the
-timeout, the request is treated as an approval timeout and surfaced as a denial reason.
-
-The confirmation dialog includes:
-
-- command + args
-- cwd
-- agent id
-- resolved executable path
-- host + policy metadata
-
-Actions:
-
-- **Allow once** → run now
-- **Always allow** → add to allowlist + run
-- **Deny** → block
-
-## Approval forwarding to chat channels
-
-You can forward exec approval prompts to any chat channel (including plugin channels) and approve
-them with `/approve`. This uses the normal outbound delivery pipeline.
-
-Config:
-
-```json5
-{
-  approvals: {
-    exec: {
-      enabled: true,
-      mode: "session", // "session" | "targets" | "both"
-      agentFilter: ["main"],
-      targets: [
-        { channel: "slack", to: "U12345678" },
-        { channel: "telegram", to: "123456789" },
-      ],
-    },
-  },
-}
-```
-
-Reply in chat:
-
-```
-/approve <id> allow-once
-/approve <id> allow-always
-/approve <id> deny
-```
-
-### macOS IPC flow
-
-```
-Gateway -> Node Service (WS)
-                 |  IPC (UDS + token + HMAC + TTL)
-                 v
-             Mac App (UI + approvals + system.run)
-```
-
-Security notes:
-
-- Unix socket mode `0600`, token stored in `exec-approvals.json`.
-- Same-UID peer check.
-- Challenge/response (nonce + HMAC token + request hash) + short TTL.
-
-## System events
-
-Exec lifecycle is surfaced as system messages:
-
-- `Exec running` (only if the command exceeds the running notice threshold)
-- `Exec finished`
-- `Exec denied`
-
-These are posted to the agent’s session after the node reports the event.
-Gateway-host exec approvals emit the same lifecycle events when the command finishes (and optionally when running longer than the threshold).
-Approval-gated execs reuse the approval id as the `runId` in these messages for easy correlation.
-
-## Implications
-
-- **full** is powerful; prefer allowlists when possible.
-- **ask** keeps you in the loop while still allowing fast approvals.
-- Per-agent allowlists prevent one agent’s approvals from leaking into others.
-- Approvals only apply to host exec requests from **authorized senders**. Unauthorized senders cannot issue `/exec`.
-- `/exec security=full` is a session-level convenience for authorized operators and skips approvals by design.
-  To hard-block host exec, set approvals security to `deny` or deny the `exec` tool via tool policy.
-
-Related:
-
-- [Exec tool](/tools/exec)
-- [Elevated mode](/tools/elevated)
-- [Skills](/tools/skills)