npm package: @simplaix/lobster-shell
Description: Lobster Shell plugin for Simplaix Gateway tool policy & audit integration
Latest version: 0.1.5

# lobster-shell

OpenClaw plugin (`@simplaix/lobster-shell`) for [Simplaix Gateway](https://github.com/simplaix/simplaix-gateway) — **tool policy evaluation**, **audit logging**, and **mobile approval pairing**.

Every tool call made by an OpenClaw agent is intercepted:

1. **Before execution** — calls `/api/v1/tool-gate/evaluate` to check policy. The Gateway may `allow`, `deny`, or `require_confirmation` (human-in-the-loop). Denied or rejected calls are blocked before the tool runs.
2. **After execution** — calls `/api/v1/tool-gate/audit` to record the result, error status, and duration.

The plugin registers a `/pair` command that generates a deep link for the Simplaix mobile approval app. If the Gateway is unreachable, the plugin **fails open** (tool calls proceed with a warning).

## How it works

### Policy evaluation

```
Agent calls tool
       │
       ▼
  POST /api/v1/tool-gate/evaluate
       │
       ├─ allow       → tool executes
       ├─ confirmed   → tool executes (human approved)
       ├─ denied      → BLOCKED (policy violation)
       ├─ rejected    → BLOCKED (human rejected)
       ├─ timeout     → BLOCKED (approval timed out)
       └─ unreachable → tool executes (fail-open)
```

### Audit logging

```
Tool execution completes
       │
       ▼
  POST /api/v1/tool-gate/audit  (fire-and-forget)
       │
       └─ Updates pending record with result, durationMs, status
```

### Pairing (`/pair` command)

```
User sends /pair
  → Plugin calls POST /api/v1/auth/pairing-code
  → Gateway returns { token, deepLink }
  → User taps link → mobile app opens → device registered for push notifications
```

### Agent identity

The plugin sends the `art_xxx` token as `Authorization: Bearer art_xxx`. The Gateway resolves the agent identity from this token — no `agentId` is sent in request bodies.

## Setup

No Docker or PostgreSQL required — the gateway uses SQLite by default.

### 1. Install the gateway

```bash
npm install -g @simplaix/simplaix-gateway
```

### 2. Create a workspace and initialise

```bash
mkdir my-gateway && cd my-gateway
gateway init
```

`gateway init` generates a `.env` with auto-generated secrets.

### 3. Start the gateway + dashboard

```bash
# With public tunnel + dashboard UI (recommended)
gateway start --tunnel --dashboard

# Or local-only
gateway start --dashboard
```

This starts:
- **Gateway** on `http://localhost:7521`
- **Dashboard UI** on `http://localhost:3000`
- **Python agent** on `http://localhost:8000`
- **Cloudflare tunnel** (if `--tunnel`) → prints public HTTPS URL

### 4. Create an admin user

```bash
gateway admin create --email admin@example.com --password yourpassword
```

### 5. Get an admin JWT

```bash
ADMIN_JWT=$(curl -s -X POST http://localhost:3000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@example.com","password":"yourpassword"}' \
  | jq -r '.token')
```

### 6. Register an agent and capture `runtime_token`

```bash
curl -s -X POST http://localhost:7521/api/v1/admin/agents \
  -H "Authorization: Bearer $ADMIN_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-openclaw-agent",
    "upstreamUrl": "http://localhost:8000",
    "description": "OpenClaw agent with policy enforcement"
  }' | jq .
```

Save the `runtime_token` (`art_xxx`) — it is shown **once**.

### 7. Seed policies and capture `PROVIDER_ID`

```bash
ADMIN_JWT="$ADMIN_JWT" AGENT_ID="<agent.id>" bash \
  $(npm root -g)/@simplaix/simplaix-gateway/../lobster-shell/seed-openclaw-policies.sh
```

Or if you have the repo cloned:

```bash
ADMIN_JWT="$ADMIN_JWT" AGENT_ID="<agent.id>" bash seed-openclaw-policies.sh
```

### 8. Configure `~/.openclaw/openclaw.json`

```jsonc
{
  "plugins": {
    "entries": {
      "lobster-shell": {
        "enabled": true,
        "config": {
          "gatewayUrl": "http://localhost:7521",
          "providerId": "<PROVIDER_ID>",
          "timeoutMs": 310000,
          "skipTools": []
        }
      }
    }
  },
  "env": {
    "vars": {
      "SIMPLAIX_AGENT_RUNTIME_TOKEN": "<art_xxx>"
    }
  }
}
```

### 9. Install the plugin

```bash
openclaw plugins install @simplaix/lobster-shell
```

### 10. Guide users to `/pair`

Share the dashboard URL (`http://localhost:3000` or the public tunnel URL printed by `--tunnel`). Users send `/pair` in WhatsApp/Telegram, tap the returned link, and the mobile approval app connects.

### Verify

- `/api/health` returns healthy
- Plugin initialization log: `[simplaix-gateway] Policy & Audit plugin initialized`
- Tool calls hit `evaluate` and `audit` endpoints
- High-risk tools trigger mobile confirmation
- Users can pair successfully

## Configuration reference

### Plugin config (`openclaw.json` → `plugins.entries.lobster-shell.config`)

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `gatewayUrl` | `string` | *required* | Gateway base URL (e.g. `http://localhost:7521`) |
| `providerId` | `string` | `"lobster-shell"` | Provider ID for policy evaluation |
| `timeoutMs` | `number` | `310000` | HTTP timeout (ms) for evaluate endpoint |
| `skipTools` | `string[]` | `[]` | Tool names to skip (no policy check, no audit) |

### Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `SIMPLAIX_AGENT_RUNTIME_TOKEN` | Yes | Agent runtime token (`art_xxx`) from step 6 |
| `SIMPLAIX_GATEWAY_URL` | No | Alternative to `gatewayUrl` in config |

## OpenClaw hook notes

- OpenClaw may call `register()` twice; the plugin guards against duplicate registration.
- `after_tool_call` fires twice per execution — the plugin only sends the audit on the second (complete) invocation that includes `durationMs`.
- `after_tool_call` context lacks `sessionKey`, so `toolName` is used as the correlation key.

## Files

```
lobster-shell/
  package.json                  # @simplaix/lobster-shell
  openclaw.plugin.json          # Plugin manifest (config schema, UI hints)
  index.ts                      # Entry point (hooks + commands)
  seed-openclaw-policies.sh     # Seeds default tool policies
  skills/                       # Agent setup skills
  README.md
```

## License

See the Simplaix Gateway repository license.