kimiflare 0.69.0 → 0.71.0

package/README.md

@@ -237,6 +237,149 @@ kimiflare
 | `Shift+Tab` | Cycle mode (edit → plan → auto) |
 | `↑` / `↓` | Walk prompt history |
 
+## Logs
+
+KimiFlare writes structured JSON logs of agent-side activity (tool calls,
+permission decisions, MCP/LSP lifecycle, session events, errors) to
+`~/.config/kimiflare/logs/<date>.jsonl`, one file per day, with 7-day
+retention pruned automatically at startup.
+
+The logs deliberately exclude prompts and completions — those live in
+[Cloudflare AI Gateway](https://developers.cloudflare.com/ai-gateway/)
+already, and each log entry includes the Gateway `request_id` so you
+can join them when you need the network side.
+
+```sh
+kimiflare logs path             # today's file
+kimiflare logs dir              # log directory
+kimiflare logs prune            # delete files older than 7 days
+
+# Tail this session's activity, formatted:
+tail -f $(kimiflare logs path) | jq
+
+# Find the slowest tool calls in the last day:
+jq -r 'select(.event == "tool:end") | "\(.data.duration_ms)\t\(.data.tool)"' \
+  $(kimiflare logs path) | sort -rn | head
+```
+
+Disable the file sink entirely with `KIMIFLARE_LOG_SINK=off`. The
+separate `KIMIFLARE_LOG_LEVEL` env var (default `off`) controls stderr
+output — independent of the file sink.
+
+### Shipping to an OpenTelemetry collector
+
+If you set `KIMIFLARE_OTEL_ENDPOINT`, KimiFlare also ships each log
+entry to that endpoint over [OTLP/HTTP](https://opentelemetry.io/docs/specs/otlp/)
+so it lands in Datadog, Honeycomb, Grafana Loki, an internal collector,
+or any other backend that speaks OTel. Batched every 5 s (or every
+100 entries, whichever first) and best-effort — never blocks the agent
+loop.
+
+```sh
+# Full path:
+export KIMIFLARE_OTEL_ENDPOINT="https://otel.example.com/v1/logs"
+# Or just the base URL (we auto-append /v1/logs):
+export KIMIFLARE_OTEL_ENDPOINT="https://otel.example.com"
+
+# Optional headers (comma-separated key=value pairs) — e.g. for auth:
+export KIMIFLARE_OTEL_HEADERS="Authorization=Bearer xyz,X-Tenant=acme"
+```
+
+Each log entry maps to one OTel `LogRecord`. Correlation IDs
+(`session_id`, `turn_id`, `request_id`) become record attributes,
+`data.*` fields are flattened to attributes with type-preserving
+encoding, and a `service.name=kimiflare` + `service.version` pair sits
+on the resource. The same `request_id` joins to Cloudflare AI Gateway's
+per-request log without any extra work.
+
+## Hooks
+
+KimiFlare can fire shell commands at five points in an agent turn,
+configured per-project (`.kimiflare/settings.json`) or globally
+(`~/.config/kimiflare/settings.json`):
+
+| Event              | Fires when                                      | Veto? |
+|--------------------|-------------------------------------------------|-------|
+| `PreToolUse`       | A tool call is about to run                     | Yes   |
+| `PostToolUse`      | A tool call just finished                       | No    |
+| `UserPromptSubmit` | You hit Enter on a prompt                       | Yes   |
+| `Stop`             | A turn ended cleanly                            | No    |
+| `PreCompact`       | Auto-compaction is about to run                 | No    |
+
+Hooks receive the event payload as JSON on stdin **and** as
+`KIMIFLARE_HOOK_*` env vars (for shell-one-liner ergonomics).
+Non-zero exit on a veto event cancels the underlying action and
+surfaces the hook's stdout as the rejection reason.
+
+### Browse + enable from the TUI
+
+```text
+/hooks                            # list configured hooks
+/hooks recommended                # list starter hooks shipped with kimiflare
+/hooks enable stop-bell           # enable one (writes to .kimiflare/settings.json)
+/hooks enable stop-bell global    # ...or the global file
+/hooks disable stop-bell
+/hooks path                       # print settings.json paths
+/hooks reload                     # re-read settings.json after a manual edit
+```
+
+The recommended catalog includes terminal bells / macOS notifications
+on `Stop`, secret-file guards on `PreToolUse` (e.g. block edits to
+`*.env`), auto-format-with-prettier on `PostToolUse`, and a tool-call
+audit log. All ship disabled — `/hooks recommended` lists them.
+
+### Schema example
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "id": "no-secrets",
+        "matcher": "^(edit|write)$",
+        "command": "case \"$KIMIFLARE_HOOK_PATH\" in *.env|*.pem) echo 'blocked'; exit 1;; esac"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "id": "format-ts",
+        "matcher": "^(edit|write)$",
+        "command": "npx --no-install prettier --write \"$KIMIFLARE_HOOK_PATH\" >/dev/null 2>&1 || true"
+      }
+    ],
+    "Stop": [
+      { "id": "bell", "command": "printf '\\a'" }
+    ]
+  }
+}
+```
+
+Per-hook fields:
+- `command` (required) — the shell command.
+- `matcher` (optional) — anchored regex matched against the tool name
+  for `PreToolUse` / `PostToolUse`. Ignored for other events.
+- `id` (optional) — stable handle for `/hooks enable|disable`.
+  Auto-derived from `event + command` when omitted.
+- `enabled` (default `true`) — set `false` to keep a hook in config
+  but skip it.
+- `timeoutMs` (default `30000`) — hard kill if the hook hangs.
+- `description` (optional) — shown by `/hooks list`.
+
+Hooks are always-on infrastructure: they fire whether the TUI is open
+or kimiflare is running in `--print` mode. They also fire for tool
+calls generated from inside the Code Mode sandbox (heavy-tier turns),
+because hook firing lives on the `ToolExecutor` itself — every call
+path uses the same plumbing.
+
+When intent classification has assigned a tier, hook payloads include
+it as `tier: "light" | "medium" | "heavy"` (on `UserPromptSubmit`,
+`PreToolUse`, `PostToolUse`) and as `$KIMIFLARE_HOOK_TIER`. Useful for
+"skip auto-format on light turns" or "audit every heavy-turn write."
+
+SDK consumers opt in to hooks with `enableHooks: true` on
+`createAgentSession`. Default is off because the SDK is a primitive,
+not the TUI.
+
 ## Development
 
 ```sh