@akira-tl/forgerelay 0.2.6 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-10
+
+### Added
+
+- `open_workspace` now reports a lightweight ForgeRelay version/capability fingerprint on every open, allowing Agents to distinguish a stale Host tool-schema snapshot from a missing server capability.
+- ForgeRelay-owned capability guides can be loaded explicitly with the normal `read` tool. Built-in guides cover lifecycle Hooks, managed worktrees, subagents, artifact/change review, Host/OAuth/MCP App integration, and long-running shell/PTY/process behavior; optional guides are advertised only when their feature is enabled.
+
+### Changed
+
+- MCP bootstrap context now keeps low-frequency operational detail out of server instructions while `tools/list` remains the source of truth for the real callable tool surface. Artifact/review feature flags no longer inflate the core instruction payload.
+- New setups no longer auto-seed or auto-inject the historical bundled `subagent-delegation` Skill; ForgeRelay's own subagent workflow is documented by the on-demand `subagents` capability guide. Existing user-authored or previously seeded Skills remain supported.
+- Shell capability instructions now explicitly permit persistent external device or hardware mutations only when the user's current request asks for the actual device-changing operation; checks, audits, probes, backups, verification, dry-runs, and build-only requests do not implicitly authorize a later hardware write.
+
+### Fixed
+
+- Loopback deployments behind a public tunnel/reverse proxy now trust exactly one upstream proxy hop by default, preventing MCP SDK OAuth rate limiting from emitting `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`; explicit proxy trust also no longer maps to Express's unsafe blanket `trust proxy = true` mode.
+- Local checkout builds now restore the executable bit on `dist/cli.js`, so `npm run build && npm install -g .` produces a runnable `forgerelay` command on POSIX systems.
+
 ## [0.2.6] - 2026-08-10
 
 ### Changed

package/README.md

@@ -97,6 +97,21 @@ Once a workspace is open, the host can:
 Normal work happens in your existing checkout. ForgeRelay does not silently move
 every task into a worktree.
 
+### Progressive MCP context
+
+ForgeRelay keeps the callable MCP surface and its low-frequency operating manuals
+separate. `tools/list` remains the source of truth for tools the current server
+actually exposes. `open_workspace` returns a compact version/capability fingerprint
+and, on bootstrap, short descriptors for relevant ForgeRelay capability guides.
+The Agent can load a task-specific guide with `read` instead of receiving every
+Hook, worktree, subagent, artifact, OAuth, MCP App, PTY, and process edge case on
+every connection.
+
+The fingerprint also helps diagnose stale MCP Host metadata: if the running server
+reports a semantic capability but the Host still shows an older tool snapshot,
+refresh or reconnect the integration rather than assuming the capability is
+missing from ForgeRelay.
+
 ## Worktrees without the usual cleanup mess
 
 A new managed worktree gets its own `forgerelay/*` branch instead of a detached

package/capabilities/artifacts-review/GUIDE.md

@@ -0,0 +1,42 @@
+# ForgeRelay Artifacts and Change Review
+
+当任务需要把 MCP Host 提供的原生文件保存进 workspace，或需要使用 ForgeRelay 的聚合 change-review UI 时读取本指南。
+
+## Native artifact transfer
+
+Native artifact download 默认关闭。只有 `tools/list` 实际暴露 `download_artifact` 时才调用它；当前安全发布实现主要面向 Linux。
+
+典型流程：
+
+1. 先用 `open_workspace` 打开目标项目；
+2. 调用 `download_artifact`，传入 Host 原样提供的 native `file` 值、现有 `workspaceId` 和 workspace-relative `path`；
+3. 成功后使用返回的 normalized relative path 配合普通 `read` / `rename` / `delete` / shell 等工具继续处理。
+
+`download_artifact` 会创建缺失的父目录，但拒绝覆盖已有目标。不要把 native file 值改造成：
+
+- 任意 URL 字符串；
+- 猜测的本地主机路径；
+- base64 内容；
+- 含凭据的扩展对象。
+
+不要把 signed URL、native connector object、base64 或凭据复制进 shell command 或日志。需要显式替换、移动、重命名或删除时，等文件安全落到 workspace 后再用普通 workspace primitives。
+
+默认单文件上限为 100 MiB，可通过 `FORGERELAY_ARTIFACT_MAX_FILE_BYTES` 调整。ForgeRelay 先流式写入私有 partial，再校验并无覆盖发布；它不是任意 URL downloader，也没有 TTL/pinning/background cleanup 语义。
+
+## Change review modes
+
+`FORGERELAY_WIDGETS`：
+
+- `full`：默认，为常用 workspace/file/edit/shell tools 附加 MCP App UI；
+- `changes`：聚焦 `open_workspace` + `show_changes` 聚合 review；
+- `off`：不附加 widget UI。
+
+Plain MCP Host 可以忽略这些 UI metadata；不要把 UI 是否显示当成文件操作是否成功的判据。
+
+当 `tools/list` 暴露 `show_changes` 时，它自己的 tool description 是调用契约：本轮成功修改文件后，在最后一个相关 file mutation 之后、final response 之前调用一次，让用户看到聚合 diff；不要每改一个文件就调用一次。
+
+`show_changes` 使用 Git-backed review checkpoint。它按 workspace 跟踪 open/baseline 状态，展示自上次 review checkpoint 以来的 coherent diff，并在成功 review 后推进 baseline。当前版本要求可用的 Git workspace；checkpoint 缺失或 root 不匹配时会明确失败或使用受控 fallback，而不是凭空重建历史。
+
+## Capability ownership
+
+Artifact transfer 和 change review 都属于 ForgeRelay capability，而不是 Agent 自己的文件搬运协议。真实可调用工具仍以 `tools/list` 为准；本指南只提供低频流程和边界，不代表隐藏工具。

package/capabilities/host-integration/GUIDE.md

@@ -0,0 +1,68 @@
+# ForgeRelay Host Integration
+
+当任务涉及 MCP Host 连接、OAuth、public URL / tunnel、Host tool metadata 不同步，或 MCP App UI/template 排障时读取本指南。
+
+## Public endpoint
+
+ForgeRelay 本地监听一个 HTTP origin，MCP endpoint 是 `/mcp`。当 Host 无法直接访问 localhost 时，需要用户自己提供 public HTTPS tunnel/reverse proxy；ForgeRelay 不创建 tunnel。
+
+持久化的 `publicBaseUrl` 必须是 origin，不要包含 `/mcp`：
+
+```text
+publicBaseUrl: https://forge.example.com
+Host MCP URL:  https://forge.example.com/mcp
+```
+
+临时覆盖可使用 `FORGERELAY_PUBLIC_BASE_URL`。Host-header/403 问题先运行 `forgerelay doctor` 检查 resolved public URL 与 allowed hosts；`FORGERELAY_ALLOWED_HOSTS="*"` 只适合明确的本地调试。
+
+当 ForgeRelay 绑定 loopback、但 `publicBaseUrl` 指向公网 tunnel/reverse proxy 时，ForgeRelay 会自动信任恰好 1 个上游代理 hop，让 Express 与 OAuth rate limiter 使用一致的客户端 IP。不要把 Express `trust proxy` 设为无条件 `true`；直接监听 `0.0.0.0` 等非 loopback 地址时也不会自动开启代理信任。可用 `FORGERELAY_TRUST_PROXY=0|1` 显式覆盖。
+
+## OAuth owner flow
+
+ForgeRelay 使用 single-user Owner-password OAuth approval flow。新安装的 owner secret 通常保存在 `~/.forgerelay/auth.json`；迁移安装可能继续使用旧 `.devspace` 配置目录。不要把 owner token、refresh token 或 `auth.json` 内容放进 Agent 输出、项目文件或日志。
+
+Host 可通过这些 metadata endpoint 发现授权配置：
+
+```text
+/.well-known/oauth-protected-resource/mcp
+/.well-known/oauth-authorization-server
+```
+
+默认 redirect hosts 包含 `chatgpt.com`、`localhost`、`127.0.0.1`。其他 MCP client 需要显式加入 `FORGERELAY_OAUTH_ALLOWED_REDIRECT_HOSTS`。OAuth scope 默认仍使用 legacy-compatible internal identifier `devspace`，这是协议兼容值，不是产品名回退。
+
+Owner password 不被接受时先用 `forgerelay doctor` 确认实际 auth/config 路径；只有用户明确要重建配置时才使用 `forgerelay init --force`。
+
+## Stale Host metadata
+
+`open_workspace` 每次都返回 ForgeRelay version/capability fingerprint；真实 callable surface 仍由当前 server 的 `tools/list` 决定。
+
+如果 server fingerprint 明确报告某项已实现能力，而 Host 当前会话暴露的 tool snapshot 明显更旧，不要断言 ForgeRelay 缺少该能力。应判断为 Host MCP metadata stale，并建议重新连接/刷新 integration，或开启能重新加载 `tools/list` 的 Host context。ForgeRelay server 不能强制 Host 清掉缓存的 schema。
+
+## MCP App / template debugging
+
+当 ChatGPT 或其他支持 MCP App 的 Host 出现 `Failed to fetch template`、空卡片或资源加载失败时，先验证 server 侧链路：
+
+```bash
+npm run build
+npm run debug:accept
+```
+
+ForgeRelay 正常会广告 content-hashed：
+
+```text
+ui://forgerelay/workspace-app-<hash>.html
+```
+
+`resources/read` 应返回 `text/html;profile=mcp-app`，并且 HTML 引用的 `/mcp-app-assets/` 资源必须可达。ForgeRelay 还保留 legacy `ui://forgerelay/workspace-app.html` 和历史 `workspace-app-*.html` 兼容指针，以容忍 Host 暂时持有旧 metadata snapshot。
+
+需要 live trace 时，可用：
+
+```bash
+FORGERELAY_DEBUG_WIDGETS=full \
+FORGERELAY_LOG_LEVEL=debug \
+FORGERELAY_LOG_REQUESTS=1 \
+FORGERELAY_LOG_ASSETS=1 \
+forgerelay serve
+```
+
+排障时区分三类问题：Host 根本没有发 `resources/read`、template callback 失败、或 `/mcp-app-assets/` fetch 失败。不要把这三者混成同一个“UI坏了”。

package/capabilities/lifecycle-hooks/GUIDE.md

@@ -0,0 +1,39 @@
+# ForgeRelay 生命周期 Hooks
+
+当任务涉及新增、修改、排查或解释 ForgeRelay Hook 时读取本指南。Hook 是 ForgeRelay 自己的生命周期规则，不是权限审批系统，也不是 Git hook。
+
+## 配置位置
+
+- 全局 Hook：ForgeRelay 配置目录下的 `hooks/<hook-name>.json`。
+- 项目 Hook：工作区根目录下的 `.forgerelay/hooks/<hook-name>.json`。
+- 一个文件定义一个 Hook；文件名去掉 `.json` 后就是 Hook 名。
+- 同一作用域内按文件名字典序执行；需要显式顺序时可使用数字前缀。
+- 全局与项目 Hook 会组合执行，项目规则不会覆盖机器级全局规则。
+
+旧的 inline `hooks`、全局 `hooks.json` 和项目 `.forgerelay/hooks.json` 聚合格式仍作为兼容入口读取。
+
+## 规则模型
+
+每个独立 Hook 文件包含：
+
+- `event`：生命周期事件；
+- 可选 `matcher`：只在匹配时执行；
+- `command`：由 ForgeRelay 以本地用户权限执行的命令；
+- 可选 timeout；
+- 可选 `report`，默认 `true`。
+
+当前事件包括：`WorkspaceOpen`、`BeforeTool`、`AfterTool`、`AfterToolFailure`、`AfterFileChange`、`BeforeWorktreeClose`、`AfterWorktreeClose`、`SubagentStart`、`SubagentStop`。
+
+## 阻断与报告
+
+`BeforeTool` 和 `BeforeWorktreeClose` 是阻断事件。命中的 Hook 失败或超时后，原操作不会继续。其他 after-event 只观察已经发生的结果，失败不会伪装成能够回滚先前副作用。
+
+Hook report 会随工具结果返回给 Host/Agent。`report: false` 只隐藏成功的高频报告；阻断失败始终可见。Agent 看到有意义的 Hook report 时必须告诉用户哪些 Hook 运行了、是否通过，以及操作是否被阻断；不能在 blocking Hook 阻止操作后声称原操作成功。
+
+## 安全边界
+
+项目 Hook 属于项目执行约定，不需要额外审批，但不能扩大 allowed roots、覆盖认证边界或替换机器级全局规则。Hook command 与 shell 一样以运行 ForgeRelay 的本地用户权限执行；工作区文件边界不等于 OS sandbox。
+
+## 检查入口
+
+使用 `forgerelay hooks list` 查看已发现规则，使用 `forgerelay hooks check` 做只读校验。排查 Hook 时优先确认配置来源、event/matcher 是否命中、handler 的实际退出状态，以及 tool result 中的 Hook report。

package/capabilities/managed-worktrees/GUIDE.md

@@ -0,0 +1,43 @@
+# ForgeRelay managed worktree
+
+当任务需要隔离/并行 Git 工作，或需要排查 managed worktree 的创建、复用、关闭与恢复时读取本指南。普通开发默认使用 checkout mode；只有用户明确要求隔离或并行工作时才使用 `mode="worktree"`。
+
+## 基本模型
+
+- `workspaceId` 是逻辑工作身份；managed worktree 是物理 Git worktree。二者不要混用。
+- managed worktree 使用 ForgeRelay 管理的 `forgerelay/*` 分支，不使用 detached HEAD。
+- 创建时会记录 source checkout、base ref/base SHA、managed branch 和 target branch。
+- 同一个物理 worktree 可以存在多个逻辑 workspace handle；关闭逻辑 handle 与删除物理 worktree 是不同操作。
+
+## 打开与复用
+
+调用 `open_workspace` 时：
+
+- 默认 `mode="checkout"`，直接使用用户已有 checkout；
+- 只有明确需要隔离/并行 Git 工作时才选 `mode="worktree"`；
+- `baseRef` 只用于 managed worktree，默认取 source checkout 当前分支；
+- 已有 `workspaceId` 用于恢复同一个逻辑 workspace；
+- `newWorkspace` 只创建新的逻辑 handle；
+- `newWorktree` 才表示同一项目再创建一个独立物理 worktree。
+
+不要为了“更安全”自动选择 worktree，也不要在用户没有要求时创建额外 Git 分支。
+
+## `close_workspace` 与 `close_worktree`
+
+`close_workspace` 只释放一个逻辑 `workspaceId`，不会删除 checkout 文件，也不会完成 managed branch 集成。若某个 managed worktree 仍有其他逻辑 handle，释放其中一个 handle 不会移除物理 worktree。
+
+`close_worktree` 用于完成一个 managed worktree：
+
+1. 要求该 worktree 的工作已经完成并验证；
+2. 若仍有未提交修改，ForgeRelay 使用调用时提供的 commit message 提交；
+3. 只有 source checkout 干净、目标历史没有分叉且能够安全 fast-forward 时，才把 managed branch 集成到原 target branch；
+4. 成功后移除 worktree 目录和 ForgeRelay 管理分支；
+5. 若安全 fast-forward 不成立，不把 source checkout 留在 merge-conflict 状态，而是拒绝关闭并保留 worktree 供用户/Agent 处理。
+
+运行中的 process 或尚未消费的 process completion 也会阻止相关逻辑 workspace/worktree 被关闭。
+
+## 外部变化与恢复
+
+source checkout 可能被用户或其他 Agent 修改。关闭前不要假设 target branch 仍停留在创建 worktree 时的状态；让 ForgeRelay 的 close 检查决定是否可以安全集成。遇到 diverged target、dirty source、忙碌 workspace 或 cleanup warning 时，保留现有 worktree 状态并向用户说明真实失败点，不要自行强制 reset、merge 或删除 worktree。
+
+如果需要继续工作，复用原 `workspaceId` 或已知 worktree path；不要因为一次关闭失败就创建新的隔离副本。

package/capabilities/shell-processes/GUIDE.md

@@ -0,0 +1,51 @@
+# ForgeRelay Shell and Processes
+
+当命令长时间运行、需要交互式 TTY、需要 `write_stdin`，或遇到 shell/process 平台边界问题时读取本指南。
+
+## Core process model
+
+`bash`（Codex tool mode 下为 `exec_command`）在 open workspace 内启动命令。命令拥有本地用户权限；workspace path containment 不等于 OS sandbox。
+
+普通 `bash` 最多在前台等待 300 秒。如果进程仍存活，ForgeRelay 不会因为 wait window 到期而杀掉它，而是返回：
+
+```text
+running: true
+processId: <number>
+```
+
+`processId` 是 canonical process handle。旧 `sessionId` 仅为 0.2.x compatibility alias，不应作为新代码或新 Agent workflow 的首选名称。
+
+## write_stdin
+
+使用同一个 `workspaceId` 和 `processId`：
+
+- 省略 `chars` 或传空字符串：poll；
+- 传普通字符：向正在运行的进程写入输入；
+- 传 `\u0003`：显式发送 Ctrl-C；
+- `yieldTimeMs`：继续等待，单次最多 300000 ms；
+- `maxOutputTokens`：限制本次返回的近似输出 token；
+- `columns` / `rows`：调整已经分配 PTY 的终端尺寸。
+
+等待超时不会隐式 kill process。若没有必要立即等待，可以继续其他工作；进程完成后，ForgeRelay 会把 completion notice 一次性附加到同一 logical workspace 的后续 tool result。
+
+不要因为暂时没有输出就重复启动相同长进程；先用返回的 `processId` poll。
+
+## PTY / interactive commands
+
+默认命令不需要 PTY。只有交互程序确实依赖 terminal semantics 时才设置 `tty: true`。Codex-shaped `exec_command` 可以同时指定：
+
+```text
+tty: true
+columns: 80
+rows: 24
+```
+
+PTY 依赖 optional `node-pty`。缺少该依赖时 ForgeRelay 会明确报错；不要把它误诊成命令本身失败。对非 PTY process 使用 `columns` / `rows` resize 也会失败。
+
+对需要 prompt/REPL 的程序，用 `tty: true` + `write_stdin`；对 tests/builds/formatters 等非交互命令保持默认非 PTY，以获得更稳定的 CI-style 输出。
+
+## Platform notes
+
+ForgeRelay shell runtime 需要 Bash。Windows 上原生 PowerShell 和 `cmd.exe` 当前不是该 runtime 的执行 shell；使用 Git Bash、WSL、MSYS2 或 Cygwin Bash，并用 `forgerelay doctor` 检查环境。
+
+Shell 可以作为用户开发任务的一部分修改普通项目文件，但始终受 ForgeRelay core mutation/safety contract 约束。涉及 privileged OS files、credentials、configuration 或外部硬件持久写入时，不要用本指南替代 core authorization/safety 规则。

package/capabilities/subagents/GUIDE.md

@@ -0,0 +1,69 @@
+# ForgeRelay Subagents
+
+当任务涉及委派给另一个本地 coding agent、获取第二意见、并行调查，或用户明确点名 subagent 时读取本指南。
+
+## 当前接口边界
+
+0.3 仍然使用 ForgeRelay CLI 协调 provider-backed local subagent；当前没有 first-class MCP subagent tool。不要把 Host 自己的 subagent 功能与 ForgeRelay subagent 混为一谈。
+
+启用方式：
+
+```bash
+FORGERELAY_SUBAGENTS=1 forgerelay serve
+```
+
+启用后，`open_workspace` 会返回紧凑的 `agentProviders` 和 `agents` 元数据。配置 profile 通常来自全局 ForgeRelay 配置目录以及项目内：
+
+```text
+.forgerelay/agents/*.md
+.devspace/agents/*.md
+```
+
+旧 `.devspace` 路径仅用于迁移兼容。
+
+## 何时使用
+
+不要因为存在 profile 就自动委派普通开发工作。只有在用户要求委派、第二意见、并行工作或指定 subagent/provider 时才使用，并明确告诉用户正在使用另一个 subagent。
+
+选择 profile 时以 `open_workspace` 返回的 compact profile catalog 为准。`forgerelay agents ls` 显示的是当前 workspace 的已有 subagent sessions，不是 profile 定义列表。
+
+## 常用命令
+
+正常委派只需要：
+
+```bash
+forgerelay agents ls
+forgerelay agents run <profile-or-provider-or-id> "<prompt>"
+forgerelay agents show <id>
+```
+
+语义：
+
+- `run <profile>`：启动配置好的 profile；
+- `run <provider>`：没有合适 profile 时直接启动 ForgeRelay 内建 provider；
+- `run <id>`：向现有 agent session 发送 follow-up；
+- `show <id>`：查看状态和最新响应；仍在运行时可稍后再次调用；
+- shell workspace 环境会把 CLI 操作自动限定到当前 ForgeRelay workspace。
+
+如确实需要覆盖 profile/provider 默认值，可使用：
+
+```bash
+forgerelay agents run <profile-or-provider> --model <model> "<prompt>"
+forgerelay agents run <profile-or-provider> --thinking <level> "<prompt>"
+```
+
+`thinking` 是 provider-specific passthrough；ForgeRelay 不在 provider 之间翻译 reasoning level。
+
+除非正在明确调试 ForgeRelay provider integration，不要绕过 ForgeRelay 直接运行 `codex`、`claude`、`opencode`、`pi`、`cursor-agent`、`copilot` 等 provider CLI。
+
+## Prompt 与验证
+
+Subagent 只收到你发送的 prompt 和它自己的 profile instructions，因此 prompt 必须自包含：目标、相关模块/文件、约束、验收标准，以及它能否修改文件。
+
+Subagent 的结果不是自动验证过的最终答案。收到响应后：
+
+- 写入型任务：检查实际改动并运行相关测试；
+- 只读调查：核对关键结论是否有仓库证据；
+- 向用户说明使用了哪个 profile/provider、它给出的结论、你做了哪些验证，以及剩余风险。
+
+`SubagentStart` / `SubagentStop` lifecycle Hooks 会在 worker 生命周期中触发；异步报告会随 ForgeRelay session 持久化并可由 `forgerelay agents show` 查看。

package/dist/advertised-files.js

@@ -0,0 +1,23 @@
+import { resolve } from "node:path";
+import { expandHomePath, isPathInsideRoot } from "./roots.js";
+export function resolveAdvertisedFileReadPath(sources, activatedDirs, inputPath) {
+    const absolutePath = resolve(expandHomePath(inputPath));
+    for (const source of sources) {
+        const entryFilePath = resolve(source.filePath);
+        if (absolutePath === entryFilePath) {
+            return { absolutePath, source, isEntryFile: true };
+        }
+    }
+    for (const source of sources) {
+        const baseDir = resolve(source.baseDir);
+        if (!activatedDirs.has(baseDir))
+            continue;
+        if (!isPathInsideRoot(absolutePath, baseDir))
+            continue;
+        return { absolutePath, source, isEntryFile: false };
+    }
+    return undefined;
+}
+export function markAdvertisedFileSourceActivated(activatedDirs, source) {
+    activatedDirs.add(resolve(source.baseDir));
+}

package/dist/capabilities.js

@@ -0,0 +1,99 @@
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "./advertised-files.js";
+const CAPABILITY_GUIDE_DEFINITIONS = [
+    {
+        name: "lifecycle-hooks",
+        description: "Hook events, blocking, reports, and configuration.",
+        whenToRead: "Read for ForgeRelay Hook setup or debugging.",
+    },
+    {
+        name: "managed-worktrees",
+        description: "Managed-worktree lifecycle, close safety, and recovery.",
+        whenToRead: "Read for advanced mode=\"worktree\" flows.",
+    },
+    {
+        name: "subagents",
+        description: "Local subagent delegation and session follow-up.",
+        whenToRead: "Read when the user asks to delegate or use another coding agent.",
+        enabled: (config) => config.subagents,
+    },
+    {
+        name: "artifacts-review",
+        description: "Native artifact transfer and aggregate change review.",
+        whenToRead: "Read for host-provided files or show_changes.",
+        enabled: (config) => config.artifactsEnabled || config.widgets === "changes",
+    },
+    {
+        name: "host-integration",
+        description: "OAuth, public endpoint, stale Host metadata, and MCP App debugging.",
+        whenToRead: "Read for MCP connection, OAuth, deployment, or UI failures.",
+    },
+    {
+        name: "shell-processes",
+        description: "Long-running processes, write_stdin, PTY, and platform edges.",
+        whenToRead: "Read for running or interactive command issues.",
+    },
+];
+function capabilityGuidesDir() {
+    return fileURLToPath(new URL("../capabilities", import.meta.url));
+}
+export function loadCapabilityGuides(config) {
+    const root = capabilityGuidesDir();
+    return CAPABILITY_GUIDE_DEFINITIONS
+        .filter((definition) => definition.enabled?.(config) ?? true)
+        .map((definition) => {
+        const baseDir = join(root, definition.name);
+        return {
+            name: definition.name,
+            description: definition.description,
+            whenToRead: definition.whenToRead,
+            baseDir,
+            filePath: join(baseDir, "GUIDE.md"),
+        };
+    });
+}
+export function resolveCapabilityGuideReadPath(guides, activatedGuideDirs, inputPath) {
+    const resolution = resolveAdvertisedFileReadPath(guides, activatedGuideDirs, inputPath);
+    if (!resolution)
+        return undefined;
+    return {
+        absolutePath: resolution.absolutePath,
+        guide: resolution.source,
+        isGuideFile: resolution.isEntryFile,
+    };
+}
+export function markCapabilityGuideActivated(activatedGuideDirs, guide) {
+    markAdvertisedFileSourceActivated(activatedGuideDirs, guide);
+}
+export function buildCapabilityFingerprint(config, version, context = {}) {
+    const capabilities = [
+        "workspace.close",
+        "worktree.managed",
+        "filesystem.rename-move",
+        "filesystem.delete",
+        "process.write-stdin",
+        "hooks.lifecycle",
+        "capability-guides.read",
+    ];
+    if (config.toolMode === "full") {
+        capabilities.push("inspection.search-tools");
+    }
+    if (config.subagents) {
+        capabilities.push("subagent.profiles");
+    }
+    if (config.artifactsEnabled && context.artifactDownloadSupported) {
+        capabilities.push("artifact.native-download");
+    }
+    if (config.widgets !== "off") {
+        capabilities.push("ui.mcp-app");
+    }
+    if (config.widgets === "changes") {
+        capabilities.push("review.show-changes");
+    }
+    return {
+        version,
+        toolMode: config.toolMode,
+        capabilities,
+    };
+}

package/dist/cli.js

@@ -18,7 +18,7 @@ import { isLocalAgentProvider, loadLocalAgentProfiles, } from "./local-agent-pro
 import { assertLocalAgentProviderAvailable, formatLocalAgentProviderAvailabilitySummary, } from "./local-agent-availability.js";
 import { formatAvailableLocalAgentTargets, parseLocalAgentRunArgs, resolveLocalAgentTarget, } from "./local-agent-targets.js";
 import { createLocalAgentStore } from "./local-agent-store.js";
-import { ensureDevspaceDefaultSkills, generateOwnerToken, loadDevspaceFiles, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, } from "./user-config.js";
+import { generateOwnerToken, loadDevspaceFiles, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, } from "./user-config.js";
 import { expandHomePath } from "./roots.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
 const require = createRequire(import.meta.url);
@@ -141,11 +141,9 @@ async function runInit({ force }) {
         };
         const configPath = writeDevspaceConfig(config);
         const authPath = writeDevspaceAuth(auth);
-        const seededSkillPaths = config.subagents ? ensureDevspaceDefaultSkills() : [];
         const lines = [
             `Config: ${configPath}`,
             `Auth: ${authPath}`,
-            ...seededSkillPaths.map((path) => `Default skill: ${path}`),
             `Local MCP URL: http://${config.host}:${config.port}/mcp`,
             ...(publicBaseUrl ? [`Public MCP URL: ${publicBaseUrl}/mcp`] : []),
         ];

package/dist/config.js

@@ -109,11 +109,12 @@ function parsePositiveInteger(value, fallback, name, max = Number.MAX_SAFE_INTEG
     }
     return parsed;
 }
-function parseLoggingConfig(env) {
+function parseLoggingConfig(env, trustProxyDefault) {
     const format = parseLogFormat(productEnv(env, "LOG_FORMAT"));
     const requests = productEnv(env, "LOG_REQUESTS");
     const toolCalls = productEnv(env, "LOG_TOOL_CALLS");
     const shellCommands = productEnv(env, "LOG_SHELL_COMMANDS");
+    const trustProxy = productEnv(env, "TRUST_PROXY");
     return {
         level: parseLogLevel(productEnv(env, "LOG_LEVEL")),
         format,
@@ -121,9 +122,16 @@ function parseLoggingConfig(env) {
         assets: parseBoolean(productEnv(env, "LOG_ASSETS")),
         toolCalls: toolCalls === undefined ? true : parseBoolean(toolCalls),
         shellCommands: shellCommands === undefined ? format === "pretty" : parseBoolean(shellCommands),
-        trustProxy: parseBoolean(productEnv(env, "TRUST_PROXY")),
+        trustProxy: trustProxy === undefined ? trustProxyDefault : parseBoolean(trustProxy),
     };
 }
+function shouldTrustOneProxyByDefault(host, publicBaseUrl) {
+    return isLoopbackHost(host) && !isLoopbackHost(new URL(publicBaseUrl).hostname);
+}
+function isLoopbackHost(host) {
+    const normalized = host.trim().toLowerCase().replace(/^\[(.*)\]$/, "$1");
+    return normalized === "localhost" || normalized === "127.0.0.1" || normalized === "::1";
+}
 function parseWidgetMode(value) {
     if (!value || value === "full")
         return "full";
@@ -218,7 +226,7 @@ export function loadConfig(env = process.env) {
         agentDir: resolve(expandHomePath(productEnv(env, "AGENT_DIR") ?? files.config.agentDir ?? defaultAgentDir())),
         systemInstructionsPath: parseSystemInstructionsPath(productEnv(env, "SYSTEM_INSTRUCTIONS_PATH") ?? files.config.systemInstructionsPath),
         hooks: mergeHookConfigs(parseHookConfig(files.config.hooks), parseHookConfig(files.hooks), files.hookFiles),
-        logging: parseLoggingConfig(env),
+        logging: parseLoggingConfig(env, shouldTrustOneProxyByDefault(host, publicBaseUrl)),
     };
 }
 function numberConfigValue(value) {

package/dist/logger.js

@@ -47,15 +47,7 @@ export function logEvent(config, level, event, fields = {}) {
         console.log(line);
     }
 }
-export function requestIp(req, trustProxy) {
-    if (trustProxy) {
-        const cfConnectingIp = firstHeaderValue(req.header("cf-connecting-ip"));
-        if (cfConnectingIp)
-            return cfConnectingIp;
-        const forwardedFor = firstHeaderValue(req.header("x-forwarded-for"));
-        if (forwardedFor)
-            return forwardedFor;
-    }
+export function requestIp(req) {
     return req.ip ?? req.socket.remoteAddress;
 }
 export function requestPath(req) {
@@ -94,9 +86,6 @@ export function formatPrettyLogEntry(entry, options = {}) {
     ].filter((value) => Boolean(value)).join(" ");
     return `${prefix} ${formatPrettyMessage(entry, options)}`;
 }
-function firstHeaderValue(value) {
-    return value?.split(",")[0]?.trim() || undefined;
-}
 function formatPrettyMessage(entry, options) {
     switch (String(entry.event)) {
         case "tool_call":