diff --git a/docs/dashboard.md b/docs/dashboard.md index c1fe4b5..5c6ebdc 100644 --- a/docs/dashboard.md +++ b/docs/dashboard.md @@ -30,6 +30,7 @@ The main view discovers all agents in the workspace directory and shows their st | Daemon processes | Agents run as background daemons via `forge serve` — they survive UI shutdown | | Live status | Real-time state updates (stopped, starting, running, errored) | | Passphrase unlock | Prompts for `FORGE_PASSPHRASE` when agents have encrypted secrets | +| Startup error display | Shows actual error messages (e.g., missing env vars) in the agent card when startup fails, extracted from `.forge/serve.log` | | Auto-rescan | Detects new agents after creation | | Unified management | All agents (UI-started or CLI-started) get identical Start/Stop controls | @@ -39,6 +40,7 @@ The UI manages agents as daemon processes using `forge serve start` / `forge ser - **Agents survive UI shutdown** — closing the dashboard does not kill running agents. - **Restart detection** — restarting the UI auto-discovers running agents via `.forge/serve.json` and TCP probing. +- **PID liveness verification** — after `forge serve start` returns, the UI verifies the child process is still alive via PID probing and TCP port check. If the child crashed (e.g., missing env vars), the error is extracted from `.forge/serve.log` and displayed in the agent card. - **Unified view** — agents started from the CLI (`forge serve start`) and agents started from the UI appear identically. There is no distinction between "UI-managed" and "CLI-managed" agents. ## Interactive Chat @@ -102,7 +104,7 @@ An AI-powered conversational tool for creating custom skills. Access it via the ### How It Works -The Skill Builder uses the agent's own LLM provider to power a chat conversation that generates valid SKILL.md files and optional helper scripts. It automatically selects a stronger code-generation model when available (e.g. `gpt-4.1` for OpenAI, `claude-opus-4-6` for Anthropic). +The Skill Builder uses the agent's own LLM provider to power a chat conversation that generates valid SKILL.md files and optional helper scripts. It automatically selects a stronger code-generation model when available (e.g. `gpt-4.1` for OpenAI, `claude-opus-4-6` for Anthropic). API key detection loads the agent's `.env` file and encrypted secrets (if unlocked) in addition to system environment variables. ### Features diff --git a/docs/runtime.md b/docs/runtime.md index dbb672b..b0f9d6d 100644 --- a/docs/runtime.md +++ b/docs/runtime.md @@ -21,6 +21,10 @@ User message → Memory → LLM → tool_calls? → Execute tools → LLM → .. The loop terminates when `FinishReason == "stop"` or `len(ToolCalls) == 0`. +### Q&A Nudge Suppression + +When the agent finishes with `stop` and no workflow phases are configured, the loop checks whether edit or git tools were used. If only explore-phase tools were invoked (e.g., `web_search`, `file_read`), the conversation is classified as informational/Q&A — the agent's text response is the final answer and no continuation nudge ("You stopped…") is sent. This prevents the agent from re-summarizing answers to simple questions. + ## LLM Providers Forge supports multiple LLM providers with automatic fallback: @@ -222,7 +226,7 @@ The runner registers five hook groups: logging, audit, progress, global guardrai ## Streaming -The current implementation (v1) runs the full tool-calling loop non-streaming. `ExecuteStream` calls `Execute` internally and emits the final response as a single message on a channel. True word-by-word streaming during tool loops is planned for v2. +The LLM tool-calling loop runs non-streaming internally. `ExecuteStream` calls `Execute` and emits the final response on a channel. However, the **UI chat proxy** (`forge-ui/chat.go`) streams A2A SSE events to the browser in real-time — `status` events carry incremental text, `progress` events carry tool execution updates, and `result` events carry the final response. The frontend renders text and tool progress as each event arrives. --- ← [Tools](tools.md) | [Back to README](../README.md) | [Memory](memory.md) → diff --git a/docs/security/guardrails.md b/docs/security/guardrails.md index 6b77ae8..763f2ce 100644 --- a/docs/security/guardrails.md +++ b/docs/security/guardrails.md @@ -108,7 +108,8 @@ Some tools legitimately return PII as part of their function (e.g., `github_get_ "file_create", "code_agent_write", "code_agent_edit", - "cli_execute" + "cli_execute", + "web_search" ] } } @@ -122,6 +123,7 @@ Some tools legitimately return PII as part of their function (e.g., `github_get_ |----------|--------| | Per-guardrail scope | `allow_tools` on `no_pii` does **not** bypass `no_secrets` — each guardrail has its own allowlist | | Write tools included | `file_create`, `code_agent_write`, `code_agent_edit`, and `cli_execute` are included because they echo back content the LLM already has or return operational output that may contain incidental PII (e.g., git log author emails) | +| Web search included | `web_search` is included because search results routinely contain names, emails, and other PII that is public web content — blocking these results would make Q&A conversations unusable | | Default config | The default policy scaffold pre-configures `allow_tools` for GitHub profile tools and write tools | | Custom overrides | Override via `policy-scaffold.json` to add or remove tools from the allowlist | diff --git a/docs/security/overview.md b/docs/security/overview.md index 0619ad7..6e6ac05 100644 --- a/docs/security/overview.md +++ b/docs/security/overview.md @@ -143,7 +143,7 @@ The `cli_execute` tool (`forge-cli/tools/cli_execute.go`) provides 13 security l | 7 | **Timeout** | Configurable per-command timeout (default: 120s) | | 8 | **No shell** | Uses `exec.CommandContext` directly — no shell expansion | | 9 | **Working directory** | `cmd.Dir` set to `workDir` for relative path resolution | -| 10 | **Environment isolation** | Only `PATH`, `HOME`, `LANG`, explicit passthrough vars, proxy vars, and `GH_CONFIG_DIR` (auto-set **only for `gh` binary** when HOME is overridden) | +| 10 | **Environment isolation** | Only `PATH`, `HOME`, `LANG`, explicit passthrough vars, proxy vars, `GH_CONFIG_DIR` (auto-set **only for `gh`**), and `KUBECONFIG`/`NO_PROXY` (**only for `kubectl`/`helm`** — restores kubeconfig access and bypasses egress proxy for the K8s API server when HOME is overridden) | | 11 | **Output limits** | Configurable max output size (default: 1MB) to prevent memory exhaustion | | 12 | **Skill guardrails** | Skill-declared `deny_commands` and `deny_output` patterns via hooks | | 13 | **Custom tool entrypoint validation** | Custom tool entrypoints are validated against path traversal, symlink escape, absolute paths, and non-regular files | diff --git a/docs/tools.md b/docs/tools.md index 503433c..627cf96 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -117,11 +117,22 @@ tools: | 7 | **Timeout** | Configurable per-command timeout (default: 120s) | | 8 | **No shell** | Uses `exec.CommandContext` directly — no shell expansion | | 9 | **Working directory** | `cmd.Dir` set to `workDir` so relative paths resolve within the agent directory | -| 10 | **Environment isolation** | Only `PATH`, `HOME`, `LANG`, explicit passthrough vars, proxy vars, `OPENAI_ORG_ID` (when set), and `GH_CONFIG_DIR` (auto-set to real `~/.config/gh` **only for the `gh` binary** when HOME is overridden). `HOME` is overridden to `workDir` to prevent `~` expansion from reaching the real home directory | +| 10 | **Environment isolation** | Only `PATH`, `HOME`, `LANG`, explicit passthrough vars, proxy vars, `OPENAI_ORG_ID` (when set), `GH_CONFIG_DIR` (auto-set to real `~/.config/gh` **only for `gh`**), and `KUBECONFIG`/`NO_PROXY` (**only for `kubectl`/`helm`** — see below). `HOME` is overridden to `workDir` to prevent `~` expansion from reaching the real home directory | | 11 | **Output limits** | Configurable max output size (default: 1MB) to prevent memory exhaustion | | 12 | **Skill guardrails** | Skill-declared `deny_commands` and `deny_output` patterns block/redact command inputs and outputs (see [Skill Guardrails](security/guardrails.md#skill-guardrails)) | | 13 | **Custom tool entrypoint validation** | Custom tool entrypoints are validated: rejects empty, absolute, or `..`-containing paths; resolves symlinks and verifies the target stays within the project directory and is a regular file | +### KUBECONFIG and NO_PROXY Scoping + +When `HOME` is overridden to `workDir`, `kubectl` and `helm` lose access to `~/.kube/config`. For these two binaries only, `cli_execute` auto-sets: + +| Env Var | Value | Purpose | +|---------|-------|---------| +| `KUBECONFIG` | `/.kube/config` | Restores access to the real kubeconfig | +| `NO_PROXY` | K8s API server hostname(s) | Bypasses the egress proxy for cluster connections | + +`NO_PROXY` is extracted from the kubeconfig's `clusters[].cluster.server` field. Other binaries do not receive these variables. + ## File Create The `file_create` tool generates downloadable files that are both written to disk and uploaded to the user's channel (Slack/Telegram).