docs: sync with goclaw 392f0fda..d85bf171 (56 commits) — EN+VI+ZH (#65)

Author: thieung

README.md

@@ -64,6 +64,7 @@
 
 - [Channel Overview](channels/overview.md)
 - [Telegram](channels/telegram.md)
+- [Bitrix24](channels/bitrix24.md)
 - [Discord](channels/discord.md)
 - [Feishu / Lark](channels/feishu.md)
 - [Larksuite](channels/larksuite.md)

advanced/browser-automation.md

@@ -199,6 +199,91 @@ The snapshot returns an accessibility tree. Use `interactive: true` to see only
 
 ---
 
+## Selected Cookie Sync
+
+Server-side browser sessions start with no login state. **Selected cookie sync** lets a user pick specific cookies from a site they are logged into and copy them into GoClaw, so an agent's browser can act as that signed-in session — without sharing a password.
+
+A small Chrome extension (`chrome-selected-cookie-sync`) does the picking. There is **no automatic background sync**: the user opens the extension on the active tab, checks the exact cookies to share, and clicks **Sync**. GoClaw stores the values encrypted and replays them into the agent's browser only for matching domains and paths.
+
+```mermaid
+flowchart LR
+    USER["User on logged-in site"] --> EXT["chrome-selected-cookie-sync\nextension"]
+    EXT -->|"POST /v1/browser/cookies/sync"| GW["GoClaw gateway"]
+    GW -->|"AES-256-GCM encrypt"| DB[("browser_cookies\ntable")]
+    DB -->|"decrypt + domain/path match"| AGENT["Agent browser session"]
+```
+
+### Endpoints
+
+All three endpoints require **operator** auth (gateway token, API key, or paired-browser auth).
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/v1/browser/cookies/sync` | Upsert selected cookies for an agent |
+| `GET` | `/v1/browser/cookies?agent_id=&domain=&name=&path=` | List synced cookie **metadata** (never values) |
+| `DELETE` | `/v1/browser/cookies?agent_id=&domain=&name=&path=` | Revoke synced cookies |
+
+The client only ever chooses `agent_id`. **Tenant and user are derived from the auth context**, not from the request body — a client cannot spoof another user's cookies. Sync is rejected when the auth context has no user, or when no `agent_id` is supplied.
+
+**Sync request body:**
+
+```json
+{
+  "agent_id": "default",
+  "source": "chrome-selected-cookie-sync",
+  "cookies": [
+    {
+      "domain": "example.com",
+      "name": "session",
+      "path": "/",
+      "value": "REDACTED",
+      "secure": true,
+      "httpOnly": true,
+      "sameSite": "lax",
+      "expirationDate": 1789999999
+    }
+  ]
+}
+```
+
+**Response:** `{ "synced": 1 }`. Limits: max 200 cookies per request, 16 KB per cookie value, 1 MB total body.
+
+The `GET` response returns metadata only — `domain`, `name`, `path`, `secure`, `httpOnly`, `sameSite`, `expiresAt`, `source`, `updatedAt`. Cookie **values are never returned**.
+
+### Scope and uniqueness
+
+Each stored cookie is keyed by `(tenant_id, user_id, agent_id, domain, path, name)`. Re-syncing the same cookie updates the existing row (upsert). This scope is what keeps one user's cookies from leaking into another user's or another agent's browser session.
+
+### Security
+
+- **Encrypted at rest**: cookie values are encrypted with AES-256-GCM before being written to the `browser_cookies` table. Requires the `GOCLAW_ENCRYPTION_KEY` environment variable — **sync and list fail closed (HTTP 503) when it is unset**, so cookies are never persisted in plaintext.
+- **Write-only values**: the list endpoint and audit logs return metadata only. Cookie values never appear in API responses or logs.
+- **Scoped replay**: the agent browser receives a cookie only when the requested URL's host and path match the stored cookie's domain/path, the cookie has not expired, and the tenant/user/agent scope matches.
+- **Explicit selection**: the extension reads cookies only after the user grants host permission for the active site, and sends only the cookies the user checked.
+- **Revocation**: delete from the extension or call `DELETE /v1/browser/cookies?agent_id=<agent>&domain=<domain>` to remove synced cookies. Omitting `domain` removes all cookies for that agent.
+
+### How the agent consumes synced cookies
+
+When the agent's browser navigates to an `http(s)` URL, GoClaw's cookie provider looks up cookies for the current browser scope (`tenant_id` / `user_id` / `agent_id`), decrypts them, and injects only those whose domain and path match the target URL (and that have not expired). Non-HTTP schemes get no cookies. The agent never sees raw values — they are applied directly to the Chrome session via CDP.
+
+### Install the extension
+
+The extension lives in the GoClaw repo at `extensions/chrome-selected-cookie-sync/`.
+
+1. Open `chrome://extensions`, enable **Developer mode**, click **Load unpacked**, and select the `extensions/chrome-selected-cookie-sync/` folder.
+2. Open a tab on the site you are logged into, then click the extension icon.
+3. Fill in the popup:
+   - **Gateway URL** — e.g. `http://localhost:18790`
+   - **Token** — an operator token (sent as `Authorization: Bearer <token>`)
+   - **User ID** — sent as the `X-GoClaw-User-Id` header
+   - **Agent ID** — e.g. `default`
+4. Click **Grant access** to give the extension host permission for the current site, then **Refresh** to list the site's cookies.
+5. Check the cookies you want to share (or **Select all**), then click **Sync**. The popup confirms `Synced N cookies.`
+
+Settings are saved in `chrome.storage.local`. The extension requests gateway-origin permission before sending, and asks for active-tab host permission before reading cookies.
+
+---
+
 ## Security Considerations
 
 - **SSRF protection**: GoClaw applies SSRF filtering to tool inputs — agents cannot be trivially directed to internal network addresses.
@@ -256,4 +341,4 @@ Returns:
 - [Exec Approval](/exec-approval) — require human sign-off before running commands
 - [Hooks & Quality Gates](/hooks-quality-gates) — add pre/post checks to agent actions
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: d85bf171 | updated: 2026-06-07 -->

advanced/cli-credentials.md

@@ -167,6 +167,7 @@ A `400` response on create/update includes the rejected key names in `rejected_k
   "error": "env keys denied: LD_PRELOAD, PATH",
   "rejected_keys": "LD_PRELOAD,PATH"
 }
+```
 
 ## REST API
 
@@ -246,6 +247,126 @@ POST /v1/cli-credentials/{id}/agent-grants/{grantId}/env:reveal
 
 Returns the decrypted plaintext env vars. Rate-limited to 10 calls/minute per user. See [Revealing Decrypted Env Vars](#revealing-decrypted-env-vars) for full details.
 
+## Typed Credential Adapters
+
+The sections above describe the **legacy env-paste model** — you paste arbitrary environment variables and GoClaw injects them verbatim into the child process. That works for tools that read auth from a single stable env var (`GH_TOKEN`, `AWS_ACCESS_KEY_ID`, …), but it fails for tools like `git` that read credentials from config files, credential helpers, or per-remote URLs — pasting a PAT into `GIT_TOKEN` does nothing.
+
+**Typed credential adapters** solve this. Instead of pasting raw env vars, you choose a credential *type*, and GoClaw routes the credential through a server-side adapter that knows how to inject it correctly and securely for that specific tool.
+
+### Credential types
+
+A user credential row carries a `credential_type` (migration `000073`):
+
+| `credential_type` | Meaning |
+|-------------------|---------|
+| `NULL` / `env` | Legacy env passthrough — env vars injected verbatim, exactly as before. No host scoping. |
+| `pat` | Personal Access Token, for HTTPS git remotes (GitHub/GitLab/Gitea). Requires a `host_scope`. |
+| `ssh_key` | SSH private key (PEM), for git over SSH. Requires a `host_scope`. |
+
+`NULL`/`env` rows are never migrated — existing legacy credentials keep working unchanged. Typed adapters are opt-in per credential.
+
+### User credentials vs binary/system credentials
+
+Typed adapters operate on **user credentials**, not the binary-level env defaults:
+
+- **Binary/system credentials** — the binary definition + its default env vars (and agent-grant overrides) described above. Shared across the binary's grants.
+- **User credentials** — per-user typed secrets stored in `secure_cli_user_credentials`, scoped to a single hostname.
+
+Manage user credentials in the dashboard under **Settings → CLI Credentials → User Credentials**. Click **Add**, select the user, choose the credential type (`Personal Access Token` or `SSH Private Key`), enter the **Host Scope**, and paste the secret. The stored secret is AES-256-GCM encrypted and can never be read back — editing the row shows a `••••••••` placeholder; leaving the secret field blank preserves the stored value, typing a new value replaces it.
+
+### The git adapter
+
+The `git` adapter is the first shipped typed adapter. It injects credentials **only** for network subcommands:
+
+```
+clone   fetch   pull   push   submodule
+```
+
+Any other subcommand (`status`, `log`, `diff`, `commit`, `branch`, …) is a local operation and runs **uncredentialed** — no injection, no audit-log line.
+
+**PAT flow.** The token is injected through environment variables, never on `argv`:
+
+```
+GIT_CONFIG_COUNT=1
+GIT_CONFIG_KEY_0=http.https://<host>/.extraheader
+GIT_CONFIG_VALUE_0=Authorization: Bearer <token>
+```
+
+Because the token lives in an env value (not a command-line flag), it never appears in `ps`, `/proc/<pid>/cmdline`, or shell history. The injected vars are scoped to the spawned `git` process only — GoClaw's own environment and sibling exec calls never see them.
+
+**SSH flow.** The PEM key is written to a `0600`-mode tmpfile in the system temp dir (prefix `goclaw-gitkey-*`), and `GIT_SSH_COMMAND` is set to:
+
+```
+ssh -i <tmpfile> -o IdentitiesOnly=yes -o BatchMode=yes -o StrictHostKeyChecking=accept-new
+```
+
+`StrictHostKeyChecking=accept-new` accepts unknown host keys on **first contact (TOFU)**. Pre-seed `~/.ssh/known_hosts` to close the window (see [Security Hardening](/deploy-security)). The tmpfile is removed after exec via a deferred cleanup. **Passphrase-protected SSH keys are rejected at save time** — re-export your key without a passphrase, or use a dedicated deploy key.
+
+### Host scope
+
+Both `pat` and `ssh_key` require a **`host_scope`** — the exact ASCII `host` or `host:port` the credential is valid for. It is normalized to lowercase ASCII (via `idna.ToASCII`) and matched **exactly**. v1 has **no wildcards**, and the port is part of the key:
+
+| Stored `host_scope` | `github.com` | `api.github.com` | `github.com:8443` |
+|---------------------|:---:|:---:|:---:|
+| `github.com` | ✓ | ✗ | ✗ |
+
+If you run a self-hosted server on the scheme's default port (443 HTTPS, 22 SSH), omit the port; if on a non-default port, include it (e.g. `gitea.internal:8443`). When no stored credential matches the resolved remote host, the adapter falls through to the uncredentialed path and the remote rejects the operation if it requires auth.
+
+### Env visibility: sensitive vs non-sensitive
+
+Stored env entries now carry a `kind`. When the dashboard or admin API reads a credential back, the response masks values according to kind:
+
+| `kind` | In API response |
+|--------|-----------------|
+| `sensitive` (default; legacy string maps decode here) | `value: null`, `masked: true` |
+| `value` (explicitly non-sensitive, e.g. a region or profile name) | plain value returned, `masked: false` |
+
+This lets operators see non-secret context (e.g. `AWS_DEFAULT_REGION=us-west-2`) in the UI while secrets stay masked. Secrets are still never returned except via the dedicated `env:reveal` endpoint.
+
+### Migrating from legacy env credentials
+
+There is no forced migration. A row with `credential_type IS NULL` or `= 'env'` keeps emitting its env vars exactly as before. To upgrade a git credential, open the user-credentials dialog, pick **Personal Access Token** or **SSH Private Key**, enter the host scope, paste the secret, and save — the legacy row is replaced atomically.
+
+### v1 limitations
+
+- **No wildcard hosts** — one credential per exact `host[:port]`; `*.github.com` is not supported.
+- **No passphrase-protected SSH keys** — rejected at validation time.
+- **No sandbox propagation** — the adapter mutates the forked child's environment, which is incompatible with the bind-mount Docker sandbox path. Credentialed exec runs on the host only in v1.
+- **No host-key pinning** — SSH uses TOFU (`accept-new`); pre-seed `known_hosts`.
+
+### Google Workspace CLI (gws)
+
+GoClaw ships a `gws` preset for the Google Workspace CLI (`@googleworkspace/cli`).
+
+**Availability.** The `gws` binary is preinstalled **only in the published `full` Docker image**. On `latest`/`base` images, install `@googleworkspace/cli` from the Packages page (requires a Node-enabled build, `ENABLE_NODE=true`; Node.js 18+).
+
+**Credentials.** Create a SecureCLI credential from the `gws` preset and provide at least one auth source:
+
+| Env var | Purpose |
+|---------|---------|
+| `GOOGLE_WORKSPACE_CLI_CREDENTIALS_FILE` | Path to exported `gws` credentials or an OAuth credentials JSON file |
+| `GOOGLE_WORKSPACE_CLI_TOKEN` | Pre-obtained Google OAuth access token (optional) |
+| `GOOGLE_WORKSPACE_CLI_CLIENT_ID` | OAuth client ID for manual auth flows (optional) |
+| `GOOGLE_WORKSPACE_CLI_CLIENT_SECRET` | OAuth client secret for manual auth flows (optional) |
+
+**Blocked commands.** The preset blocks interactive and credential-exporting auth flows:
+
+```
+gws auth setup    gws auth login    gws auth export    gws auth logout
+```
+
+Run those flows outside agent execution, then store the resulting token or credentials-file path in SecureCLI.
+
+**Usage.** Default usage is read-oriented. Use `--params` for query parameters, `--json` for request bodies, and `--page-all` for paginated reads:
+
+```sh
+gws drive files list --params '{"pageSize": 10}'
+gws gmail users messages list --params '{"userId": "me", "maxResults": 10}'
+gws calendar events list --params '{"calendarId": "primary", "maxResults": 10}'
+```
+
+> **Write caution.** Write commands can modify Workspace data. Keep the default preset read-oriented and create a separate, reviewed SecureCLI config for any approved write workflow.
+
 ## Common Patterns
 
 ### Allow only one agent to use a sensitive CLI tool
@@ -277,4 +398,4 @@ Update the grant: `{"enabled": false}`. The binary remains accessible to other a
 - [API Keys & RBAC](/api-keys-rbac)
 - [Security Hardening](/deploy-security)
 
-<!-- goclaw-source: 392f0fda | updated: 2026-05-21 -->
+<!-- goclaw-source: d85bf171 | updated: 2026-06-07 -->

advanced/cost-tracking.md

@@ -232,6 +232,69 @@ monthly budget exceeded ($5.02 / $5.00)
 
 The check runs once per request, before any LLM calls. Sub-agent delegations run under their own agent records with their own budgets.
 
+> The agent's `budget_monthly_cents` is also mirrored into the [AI Budget Usage Caps](/usage-quota) system as a managed `month`-window cost-cap policy, so the same limit is enforced there too.
+
+---
+
+## Model Pricing (Catalog & Overrides)
+
+The static `telemetry.model_pricing` map above is the simplest way to price models. For dynamic, database-backed pricing — used by the [AI Budget Usage Caps](/usage-quota) cost caps — GoClaw also keeps a **pricing catalog** and per-tenant **overrides** in PostgreSQL (migration `000070`).
+
+### OpenRouter catalog sync
+
+GoClaw can pull a full model price list from [OpenRouter](https://openrouter.ai) and store it in the `usage_pricing_catalog` table. Each entry captures per-unit prices for input, output, cache read/write, reasoning, request, image, and web-search units, stored as high-precision decimals.
+
+```bash
+curl -X POST -H "Authorization: Bearer your-token" \
+  "http://localhost:8080/v1/model-pricing/sync-openrouter"
+```
+
+This endpoint requires **master scope** (it updates the shared global catalog). The catalog is upserted by `model_id`, so re-running the sync refreshes prices in place.
+
+### Per-model price overrides
+
+When you want different prices for a specific tenant + provider + model (e.g. a negotiated rate, or a model OpenRouter doesn't list), set an **override** in the `usage_pricing_overrides` table. Overrides are scoped to one tenant and take priority over the global catalog.
+
+```bash
+# List the synced catalog (optionally filter by model)
+curl -H "Authorization: Bearer your-token" \
+  "http://localhost:8080/v1/model-pricing?model=claude-sonnet-4-5"
+
+# Set a tenant override
+curl -X PUT -H "Authorization: Bearer your-token" \
+  -H "Content-Type: application/json" \
+  "http://localhost:8080/v1/model-pricing/overrides" \
+  -d '{
+    "provider_id": "22222222-2222-2222-2222-222222222222",
+    "provider_type": "anthropic",
+    "model_id": "claude-sonnet-4-5",
+    "pricing": { "input": "0.000003", "output": "0.000015" }
+  }'
+
+# List / delete overrides
+curl -H "Authorization: Bearer your-token" \
+  "http://localhost:8080/v1/model-pricing/overrides"
+curl -X DELETE -H "Authorization: Bearer your-token" \
+  "http://localhost:8080/v1/model-pricing/overrides/{id}"
+```
+
+| Method & path | Scope | Description |
+|---------------|-------|-------------|
+| `POST /v1/model-pricing/sync-openrouter` | master | Refresh the global price catalog from OpenRouter |
+| `GET /v1/model-pricing` | admin | List the synced catalog (`?model=`, `?limit=`) |
+| `PUT /v1/model-pricing/overrides` | tenant-admin | Create or update a per-tenant model price override |
+| `GET /v1/model-pricing/overrides` | admin | List overrides (`?provider_id=`) |
+| `DELETE /v1/model-pricing/overrides/{id}` | tenant-admin | Remove an override |
+
+### How pricing resolves
+
+When a cost cap needs a price for a model, GoClaw resolves in this order:
+
+1. **Tenant override** for the matching provider + model (highest priority)
+2. **Global OpenRouter catalog** entry by `model_id` / canonical id
+
+If neither is found, a cost-capped call is blocked with reason `pricing_unknown`. Prices are stored as decimal USD **per token/unit** and converted to micro-dollars when caps compute cost.
+
 ---
 
 ## Common Issues
@@ -252,4 +315,4 @@ The check runs once per request, before any LLM calls. Sub-agent delegations run
 - [Observability](/deploy-observability) — OpenTelemetry export for spans including cost fields
 - [Configuration Reference](/config-reference) — full `telemetry` config options
 
-<!-- goclaw-source: 050aafc9 | updated: 2026-04-09 -->
+<!-- goclaw-source: d85bf171 | updated: 2026-06-07 -->

advanced/custom-tools.md

@@ -67,6 +67,8 @@ curl -X POST http://localhost:8080/v1/tools/custom \
 | `agent_id` | UUID | null | Scope to one agent; omit for global |
 | `enabled` | bool | true | Disable without deleting |
 
+> **Three distinct timeouts — don't confuse them.** This per-custom-tool `timeout_seconds` (default 60) applies only to this one custom tool's command. It is separate from the host `exec` builtin tool's own `timeout_seconds` setting (also default 60, max 3600 — see [Tools Overview → Execution Timeout](/tools-overview)) and from the sandbox `sandbox_config.timeout_sec` (agent-level, default 300 — see [Sandbox](/sandbox)). A custom tool routed through the sandbox is still bounded by the sandbox timeout.
+
 ### Command templates
 
 Use `{{.paramName}}` placeholders. GoClaw replaces them with shell-escaped values using simple string replacement — not Go's `text/template` engine, so template functions and pipelines are not supported. Every substituted value is single-quoted with embedded single-quotes escaped, so even a malicious LLM cannot break out of the argument.
@@ -250,4 +252,4 @@ Returns all documents that link to the specified path. Respects team boundaries
 - [Exec Approval](/exec-approval) — require human approval before commands run
 - [Sandbox](/sandbox) — run commands inside Docker for extra isolation
 
-<!-- goclaw-source: 29457bb3 | updated: 2026-04-25 -->
+<!-- goclaw-source: d85bf171 | updated: 2026-06-07 -->