fengming 0.3.10 → 0.3.12

package/docs/logging.md

@@ -1,320 +0,0 @@
----
-summary: "File logs, console output, CLI tailing, and the Control UI Logs tab"
-read_when:
-  - You need a beginner-friendly overview of FengMing logging
-  - You want to configure log levels, formats, or redaction
-  - You are troubleshooting and need to find logs quickly
-title: "Logging"
----
-
-FengMing has two main log surfaces:
-
-- **File logs** (JSON lines) written by the Gateway.
-- **Console output** shown in terminals and the Gateway Debug UI.
-
-The Control UI **Logs** tab tails the gateway file log. This page explains where
-logs live, how to read them, and how to configure log levels and formats.
-
-## Where logs live
-
-By default, the Gateway writes a rolling log file under:
-
-`/tmp/fengming/fengming-YYYY-MM-DD.log`
-
-The date uses the gateway host's local timezone.
-
-Each file rotates when it reaches `logging.maxFileBytes` (default: 100 MB).
-FengMing keeps up to five numbered archives beside the active file, such as
-`fengming-YYYY-MM-DD.1.log`, and keeps writing to a fresh active log instead of
-suppressing diagnostics.
-
-You can override this in `~/.fengming/fengming.json`:
-
-```json
-{
-  "logging": {
-    "file": "/path/to/fengming.log"
-  }
-}
-```
-
-## How to read logs
-
-### CLI: live tail (recommended)
-
-Use the CLI to tail the gateway log file via RPC:
-
-```bash
-fengming logs --follow
-```
-
-Useful current options:
-
-- `--local-time`: render timestamps in your local timezone
-- `--url <url>` / `--token <token>` / `--timeout <ms>`: standard Gateway RPC flags
-- `--expect-final`: agent-backed RPC final-response wait flag (accepted here via the shared client layer)
-
-Output modes:
-
-- **TTY sessions**: pretty, colorized, structured log lines.
-- **Non-TTY sessions**: plain text.
-- `--json`: line-delimited JSON (one log event per line).
-- `--plain`: force plain text in TTY sessions.
-- `--no-color`: disable ANSI colors.
-
-When you pass an explicit `--url`, the CLI does not auto-apply config or
-environment credentials; include `--token` yourself if the target Gateway
-requires auth.
-
-In JSON mode, the CLI emits `type`-tagged objects:
-
-- `meta`: stream metadata (file, cursor, size)
-- `log`: parsed log entry
-- `notice`: truncation / rotation hints
-- `raw`: unparsed log line
-
-If the implicit local loopback Gateway asks for pairing, closes during connect,
-or times out before `logs.tail` answers, `fengming logs` falls back to the
-configured Gateway file log automatically. Explicit `--url` targets do not use
-this fallback. `fengming logs --follow` is stricter: on Linux it uses the active
-user-systemd Gateway journal by PID when available, and otherwise keeps retrying
-the live Gateway instead of following a potentially stale side-by-side file.
-
-If the Gateway is unreachable, the CLI prints a short hint to run:
-
-```bash
-fengming doctor
-```
-
-### Control UI (web)
-
-The Control UI's **Logs** tab tails the same file using `logs.tail`.
-See [Control UI](/web/control-ui) for how to open it.
-
-### Channel-only logs
-
-To filter channel activity (WhatsApp/Telegram/etc), use:
-
-```bash
-fengming channels logs --channel whatsapp
-```
-
-## Log formats
-
-### File logs (JSONL)
-
-Each line in the log file is a JSON object. The CLI and Control UI parse these
-entries to render structured output (time, level, subsystem, message).
-
-File-log JSONL records also include machine-filterable top-level fields when
-available:
-
-- `hostname`: gateway host name.
-- `message`: flattened log message text for full-text search.
-- `agent_id`: active agent id when the log call carries agent context.
-- `session_id`: active session id/key when the log call carries session context.
-- `channel`: active channel when the log call carries channel context.
-
-FengMing preserves the original structured log arguments alongside these fields
-so existing parsers that read numbered tslog argument keys keep working.
-
-Talk, realtime voice, and managed-room activity emits bounded lifecycle log
-records through this same file-log pipeline. These records include event type,
-mode, transport, provider, and size/timing measurements when available, but omit
-transcript text, audio payloads, turn ids, call ids, and provider item ids.
-
-### Console output
-
-Console logs are **TTY-aware** and formatted for readability:
-
-- Subsystem prefixes (e.g. `gateway/channels/whatsapp`)
-- Level coloring (info/warn/error)
-- Optional compact or JSON mode
-
-Console formatting is controlled by `logging.consoleStyle`.
-
-### Gateway WebSocket logs
-
-`fengming gateway` also has WebSocket protocol logging for RPC traffic:
-
-- normal mode: only interesting results (errors, parse errors, slow calls)
-- `--verbose`: all request/response traffic
-- `--ws-log auto|compact|full`: pick the verbose rendering style
-- `--compact`: alias for `--ws-log compact`
-
-Examples:
-
-```bash
-fengming gateway
-fengming gateway --verbose --ws-log compact
-fengming gateway --verbose --ws-log full
-```
-
-## Configuring logging
-
-All logging configuration lives under `logging` in `~/.fengming/fengming.json`.
-
-```json
-{
-  "logging": {
-    "level": "info",
-    "file": "/tmp/fengming/fengming-YYYY-MM-DD.log",
-    "consoleLevel": "info",
-    "consoleStyle": "pretty",
-    "redactSensitive": "tools",
-    "redactPatterns": ["sk-.*"]
-  }
-}
-```
-
-### Log levels
-
-- `logging.level`: **file logs** (JSONL) level.
-- `logging.consoleLevel`: **console** verbosity level.
-
-You can override both via the **`FENGMING_LOG_LEVEL`** environment variable (e.g. `FENGMING_LOG_LEVEL=debug`). The env var takes precedence over the config file, so you can raise verbosity for a single run without editing `fengming.json`. You can also pass the global CLI option **`--log-level <level>`** (for example, `fengming --log-level debug gateway run`), which overrides the environment variable for that command.
-
-`--verbose` only affects console output and WS log verbosity; it does not change
-file log levels.
-
-### Targeted model transport diagnostics
-
-When debugging provider calls, use targeted environment flags instead of raising
-all logs to `debug`:
-
-```bash
-FENGMING_DEBUG_MODEL_TRANSPORT=1 fengming gateway
-FENGMING_DEBUG_MODEL_PAYLOAD=tools FENGMING_DEBUG_SSE=events fengming gateway
-```
-
-Available flags:
-
-- `FENGMING_DEBUG_MODEL_TRANSPORT=1`: emit request start, fetch response, SDK
-  headers, first streaming event, stream completion, and transport errors at
-  `info` level.
-- `FENGMING_DEBUG_MODEL_PAYLOAD=summary`: include a bounded request payload
-  summary in model request logs.
-- `FENGMING_DEBUG_MODEL_PAYLOAD=tools`: include all model-facing tool names in
-  the payload summary.
-- `FENGMING_DEBUG_MODEL_PAYLOAD=full-redacted`: include a redacted, capped JSON
-  payload snapshot. Use only while debugging; secrets are redacted but prompts
-  and message text may still be present.
-- `FENGMING_DEBUG_SSE=events`: emit first-event and stream-completion timing.
-- `FENGMING_DEBUG_SSE=peek`: also emit the first five redacted SSE event
-  payloads, capped per event.
-- `FENGMING_DEBUG_CODE_MODE=1`: emit code-mode model-surface diagnostics,
-  including when native provider tools are hidden because code mode owns the
-  tool surface.
-
-These flags log through normal FengMing logging, so `fengming logs --follow`
-and the Control UI Logs tab show them. Without the flags, the same diagnostics
-remain available at `debug` level.
-
-### Trace correlation
-
-File logs are JSONL. When a log call carries a valid diagnostic trace context,
-FengMing writes the trace fields as top-level JSON keys (`traceId`, `spanId`,
-`parentSpanId`, `traceFlags`) so external log processors can correlate the line
-with OTEL spans and provider `traceparent` propagation.
-
-Gateway HTTP requests and Gateway WebSocket frames establish an internal request
-trace scope. Logs and diagnostic events emitted inside that async scope inherit
-the request trace when they do not pass an explicit trace context. Agent run and
-model-call traces become children of the active request trace, so local logs,
-diagnostic snapshots, OTEL spans, and trusted provider `traceparent` headers can
-be joined by `traceId` without logging raw request or model content.
-
-Talk lifecycle log records also flow to OTLP logs when OpenTelemetry log export
-is enabled, using the same bounded attributes as file logs.
-
-### Model call size and timing
-
-Model-call diagnostics record bounded request/response measurements without
-capturing raw prompt or response content:
-
-- `requestPayloadBytes`: UTF-8 byte size of the final model request payload
-- `responseStreamBytes`: UTF-8 byte size of streamed model response events
-- `timeToFirstByteMs`: elapsed time before the first streamed response event
-- `durationMs`: total model-call duration
-
-These fields are available to diagnostic snapshots, model-call plugin hooks, and
-OTEL model-call spans/metrics when diagnostics export is enabled.
-
-### Console styles
-
-`logging.consoleStyle`:
-
-- `pretty`: human-friendly, colored, with timestamps.
-- `compact`: tighter output (best for long sessions).
-- `json`: JSON per line (for log processors).
-
-### Redaction
-
-FengMing can redact sensitive tokens before they hit console output, file logs,
-OTLP log records, persisted session transcript text, or Control UI tool
-event payloads (tool start args, partial/final result payloads, derived
-exec output, and patch summaries):
-
-- `logging.redactSensitive`: `off` | `tools` (default: `tools`)
-- `logging.redactPatterns`: list of regex strings to override the default set. Custom patterns apply on top of the built-in defaults for Control UI tool payloads, so adding a pattern never weakens redaction of values already caught by the defaults.
-
-File logs and session transcripts stay JSONL, but matching secret values are
-masked before the line or message is written to disk. Redaction is best-effort:
-it applies to text-bearing message content and log strings, not every
-identifier or binary payload field.
-
-The built-in defaults cover common API credentials and payment-credential field
-names such as card number, CVC/CVV, shared payment token, and payment credential
-when they appear as JSON fields, URL parameters, CLI flags, or assignments.
-
-`logging.redactSensitive: "off"` only disables this general log/transcript
-policy. FengMing still redacts safety-boundary payloads that can be shown to UI
-clients, support bundles, diagnostics observers, approval prompts, or agent
-tools. Examples include Control UI tool-call events, `sessions_history` output,
-diagnostics support exports, provider error observations, exec approval command
-display, and Gateway WebSocket protocol logs. Custom `logging.redactPatterns`
-can still add project-specific patterns on those surfaces.
-
-## Diagnostics and OpenTelemetry
-
-Diagnostics are structured, machine-readable events for model runs and
-message-flow telemetry (webhooks, queueing, session state). They do **not**
-replace logs — they feed metrics, traces, and exporters. Events are emitted
-in-process whether or not you export them.
-
-Two adjacent surfaces:
-
-- **OpenTelemetry export** — send metrics, traces, and logs over OTLP/HTTP to
-  any OpenTelemetry-compatible collector or backend (Grafana, Datadog,
-  Honeycomb, New Relic, Tempo, etc.). Full configuration, signal catalog,
-  metric/span names, env vars, and privacy model live on a dedicated page:
-  [OpenTelemetry export](/gateway/opentelemetry).
-- **Diagnostics flags** — targeted debug-log flags that route extra logs to
-  `logging.file` without raising `logging.level`. Flags are case-insensitive
-  and support wildcards (`telegram.*`, `*`). Configure under `diagnostics.flags`
-  or via the `FENGMING_DIAGNOSTICS=...` env override. Full guide:
-  [Diagnostics flags](/diagnostics/flags).
-
-To enable diagnostics events for plugins or custom sinks without OTLP export:
-
-```json5
-{
-  diagnostics: { enabled: true },
-}
-```
-
-For OTLP export to a collector, see [OpenTelemetry export](/gateway/opentelemetry).
-
-## Troubleshooting tips
-
-- **Gateway not reachable?** Run `fengming doctor` first.
-- **Logs empty?** Check that the Gateway is running and writing to the file path
-  in `logging.file`.
-- **Need more detail?** Set `logging.level` to `debug` or `trace` and retry.
-
-## Related
-
-- [OpenTelemetry export](/gateway/opentelemetry) — OTLP/HTTP export, metric/span catalog, privacy model
-- [Diagnostics flags](/diagnostics/flags) — targeted debug-log flags
-- [Gateway logging internals](/gateway/logging) — WS log styles, subsystem prefixes, and console capture
-- [Configuration reference](/gateway/configuration-reference#diagnostics) — full `diagnostics.*` field reference

package/docs/nav-tabs-underline.js

@@ -1,100 +0,0 @@
-(() => {
-  const NAV_TABS_SELECTOR = ".nav-tabs";
-  const ACTIVE_UNDERLINE_SELECTOR = ".nav-tabs-item > div.bg-primary";
-  const UNDERLINE_CLASS = "nav-tabs-underline";
-  const READY_CLASS = "nav-tabs-underline-ready";
-
-  let navTabs = null;
-  let navTabsObserver = null;
-  let lastX = null;
-  let lastWidth = null;
-
-  const ensureUnderline = (tabs) => {
-    let underline = tabs.querySelector(`.${UNDERLINE_CLASS}`);
-    if (!underline) {
-      underline = document.createElement("div");
-      underline.className = UNDERLINE_CLASS;
-      tabs.appendChild(underline);
-    }
-    return underline;
-  };
-
-  const getActiveTab = (tabs) => {
-    const activeUnderline = tabs.querySelector(ACTIVE_UNDERLINE_SELECTOR);
-    return activeUnderline?.closest(".nav-tabs-item") ?? null;
-  };
-
-  const updateUnderline = () => {
-    if (!navTabs) {
-      return;
-    }
-
-    ensureUnderline(navTabs);
-
-    const activeTab = getActiveTab(navTabs);
-    if (!activeTab) {
-      navTabs.classList.remove(READY_CLASS);
-      return;
-    }
-
-    const navRect = navTabs.getBoundingClientRect();
-    const tabRect = activeTab.getBoundingClientRect();
-    const left = tabRect.left - navRect.left;
-
-    navTabs.style.setProperty("--nav-tab-underline-x", `${left}px`);
-    navTabs.style.setProperty("--nav-tab-underline-width", `${tabRect.width}px`);
-    navTabs.classList.add(READY_CLASS);
-
-    lastX = left;
-    lastWidth = tabRect.width;
-  };
-
-  const scheduleUpdate = () => {
-    requestAnimationFrame(updateUnderline);
-  };
-
-  const setupNavTabsObserver = (tabs) => {
-    if (!tabs || tabs === navTabs) {
-      return;
-    }
-
-    navTabs = tabs;
-    ensureUnderline(navTabs);
-    if (lastX !== null && lastWidth !== null) {
-      navTabs.style.setProperty("--nav-tab-underline-x", `${lastX}px`);
-      navTabs.style.setProperty("--nav-tab-underline-width", `${lastWidth}px`);
-      navTabs.classList.add(READY_CLASS);
-    }
-    navTabsObserver?.disconnect();
-    navTabsObserver = new MutationObserver(scheduleUpdate);
-    navTabsObserver.observe(navTabs, {
-      subtree: true,
-      attributes: true,
-      attributeFilter: ["class"],
-    });
-
-    scheduleUpdate();
-  };
-
-  const setupObservers = () => {
-    const tabs = document.querySelector(NAV_TABS_SELECTOR);
-    if (tabs) {
-      setupNavTabsObserver(tabs);
-    }
-  };
-
-  const rootObserver = new MutationObserver(setupObservers);
-
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", () => {
-      setupObservers();
-      rootObserver.observe(document.body, { childList: true, subtree: true });
-    });
-  } else {
-    setupObservers();
-    rootObserver.observe(document.body, { childList: true, subtree: true });
-  }
-
-  window.addEventListener("resize", scheduleUpdate);
-  void document.fonts?.ready?.then(scheduleUpdate, () => {});
-})();

package/docs/network.md

@@ -1,72 +0,0 @@
----
-summary: "Network hub: gateway surfaces, pairing, discovery, and security"
-read_when:
-  - You need the network architecture + security overview
-  - You are debugging local vs tailnet access or pairing
-  - You want the canonical list of networking docs
-title: "Network"
----
-
-This hub links the core docs for how FengMing connects, pairs, and secures
-devices across localhost, LAN, and tailnet.
-
-## Core model
-
-Most operations flow through the Gateway (`fengming gateway`), a single long-running process that owns channel connections and the WebSocket control plane.
-
-- **Loopback first**: the Gateway WS defaults to `ws://127.0.0.1:18789`.
-  Non-loopback binds require a valid gateway auth path: shared-secret
-  token/password auth, or a correctly configured non-loopback
-  `trusted-proxy` deployment.
-- **One Gateway per host** is recommended. For isolation, run multiple gateways with isolated profiles and ports ([Multiple Gateways](/gateway/multiple-gateways)).
-- **Canvas host** is served on the same port as the Gateway (`/__fengming__/canvas/`, `/__fengming__/a2ui/`), protected by Gateway auth when bound beyond loopback.
-- **Remote access** is typically SSH tunnel or Tailscale VPN ([Remote Access](/gateway/remote)).
-
-Key references:
-
-- [Gateway architecture](/concepts/architecture)
-- [Gateway protocol](/gateway/protocol)
-- [Gateway runbook](/gateway)
-- [Web surfaces + bind modes](/web)
-
-## Pairing + identity
-
-- [Pairing overview (DM + nodes)](/channels/pairing)
-- [Gateway-owned node pairing](/gateway/pairing)
-- [Devices CLI (pairing + token rotation)](/cli/devices)
-- [Pairing CLI (DM approvals)](/cli/pairing)
-
-Local trust:
-
-- Direct local loopback connects can be auto-approved for pairing to keep
-  same-host UX smooth.
-- FengMing also has a narrow backend/container-local self-connect path for
-  trusted shared-secret helper flows.
-- Tailnet and LAN clients, including same-host tailnet binds, still require
-  explicit pairing approval.
-
-## Discovery + transports
-
-- [Discovery and transports](/gateway/discovery)
-- [Bonjour / mDNS](/gateway/bonjour)
-- [Remote access (SSH)](/gateway/remote)
-- [Tailscale](/gateway/tailscale)
-
-## Nodes + transports
-
-- [Nodes overview](/nodes)
-- [Bridge protocol (legacy nodes, historical)](/gateway/bridge-protocol)
-- [Node runbook: iOS](/platforms/ios)
-- [Node runbook: Android](/platforms/android)
-
-## Security
-
-- [Security overview](/gateway/security)
-- [Gateway config reference](/gateway/configuration)
-- [Troubleshooting](/gateway/troubleshooting)
-- [Doctor](/gateway/doctor)
-
-## Related
-
-- [Gateway runbook](/gateway)
-- [Remote access](/gateway/remote)