diff --git a/README.md b/README.md index f5cf622..1209488 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ # Moss -**Moss is an open, robotics-aware terminal agent and embeddable agent runtime developed by 地瓜机器人 (D-Robotics).** Install `moss` and start with the built-in D-Robotics model gateway; community login is optional. When you want your own model, billing, data boundary, or private gateway, switch to any OpenAI-compatible endpoint or Anthropic without changing the agent. +**Moss is an open, robotics-aware terminal agent and embeddable agent runtime developed by 地瓜机器人 (D-Robotics).** Run `moss` and start working immediately on the built-in D-Robotics model gateway — no model API key and no forced login. When you want your own model, billing, data boundary, or private gateway, point Moss at any OpenAI-compatible endpoint or Anthropic without changing the agent. -`moss` is the primary CLI command. `dmoss` remains a compatible alias for existing users and scripts. +`moss` is the primary command. `dmoss` remains a compatible alias for existing users and scripts.

Moss terminal startup demo @@ -12,18 +12,35 @@ Moss board connection and image attachment demo

-## Why Moss? +## Quick Start -Moss gives you the familiar terminal-agent loop from Claude Code and Codex, but with a different ownership model: +```bash +npm i -g @rdk-moss/agent@latest +moss +``` -- **Bring your own model** - DeepSeek, Qwen, OpenAI-compatible gateways, Anthropic, or self-hosted endpoints. -- **Use it immediately** - the built-in D-Robotics gateway works without a model API key or forced community login. -- **Work with robots and edge devices** - `/connect ` adds RDK board SSH, diagnostics, and ROS2 tools inside the same session. -- **Embed it in your own product** - Moss is a runtime with public contracts, not only a closed standalone app. -- **Stay honest about evidence** - Moss is prompted to separate verified facts, reasonable inferences, and unverified assumptions, and to say when CodeGraph, device access, or other evidence is unavailable. -- **Grow reusable skills** - Moss can install workspace skills into `.moss/skills//SKILL.md` through the approved `install_skill` tool, then rediscover them in later runs. -- **Keep going when you set a goal** - `/goal ` turns the CLI into a goal runner that continues across turns until the goal is completed, blocked, cleared, or stopped by the user. -- **Keep the first screen usable** - focused slash commands, image/file attachment, goals, compaction, sessions, MCP, skills, and sub-agents stay available without turning `/help` into a wall. +The npm package is `@rdk-moss/agent`; the command is `moss`. Node 22.16 or newer is required. The first launch works out of the box on the built-in gateway — ask it something and it answers. `moss auth login` is optional and only links a D-Robotics developer community account. + +You can also run Moss without entering the interactive UI: + +```bash +moss "check disk usage on this project" # one-shot: answer and exit +echo "list the failing tests" | moss # piped stdin +moss -m qwen-plus "summarize @README.md" # override the model for one run; @path attaches a file +``` + +Update anytime with `npm i -g @rdk-moss/agent@latest`, or `/upgrade` from inside Moss. + +## Why Moss + +Moss gives you the familiar terminal-agent loop from Claude Code and Codex with a different ownership model: + +- **Use it immediately** — the built-in D-Robotics gateway works with no model key and no forced community login. +- **Bring your own model** — DeepSeek, Qwen, any OpenAI-compatible gateway, Anthropic, or a self-hosted endpoint. Switching providers never changes the agent. +- **Work with robots and edge devices** — `/connect ` puts the whole session on an RDK board over SSH, with diagnostics and ROS2 tools, then `/disconnect` restores local tools. +- **Survive long, interruptible work** — sessions are saved as you go, a working-context checkpoint tracks the active task, and `moss resume`/`--continue` pick the task back up instead of restarting it. +- **Stay honest about evidence** — Moss is prompted to separate verified facts, inferences, and assumptions, to report when CodeGraph or device access is unavailable, and to never claim a result it did not verify. +- **Embed it in your own product** — Moss is a runtime with public contracts and npm packages, not only a closed standalone app. If that direction is useful, star the repo to follow the open runtime, fork it to build your own host, and open issues for model providers, board workflows, or host-adapter gaps you want Moss to support. @@ -33,139 +50,89 @@ If that direction is useful, star the repo to follow the open runtime, fork it t | --- | --- | --- | --- | | Interactive terminal agent | `moss` (`dmoss` alias) | yes | yes | | Default first run | Built-in D-Robotics gateway, no model key or forced login | Anthropic account | OpenAI account | -| Bring your own model | OpenAI-compatible, Anthropic, private gateways, self-hosted models | limited to Anthropic path | limited to OpenAI path | -| Robotics / board workflows | First-class RDK board connect, SSH, diagnostics, ROS2 tool path | general developer agent | general developer agent | +| Bring your own model | OpenAI-compatible, Anthropic, private gateways, self-hosted models | Anthropic path | OpenAI path | +| Robotics / board workflows | First-class RDK board connect, SSH, diagnostics, ROS2 tools | general developer agent | general developer agent | | Embedding model | Public Host Adapter contract and npm packages | standalone product | standalone product | | Product control | Host owns UI, tools, storage, approvals, credentials, telemetry | vendor-owned app | vendor-owned app | Claude Code and Codex are excellent polished standalone assistants. Moss is for people who want that style of agent while also owning the runtime, model route, device tools, and product integration surface. -## Install - -```bash -npm i -g @rdk-moss/agent@latest -moss -``` - -The npm package is `@rdk-moss/agent`. The command is `moss`. Existing `dmoss` commands still work. - -Optional: run `moss auth login` when you want to link a D-Robotics developer community account. It is not required for normal first use. - -Every plain `moss` launch starts a **new saved conversation**. Resume only when you ask for it: - -```bash -moss resume --last -moss resume --session -moss --session -``` +## A Five-Minute Tour -Update anytime: - -```bash -npm i -g @rdk-moss/agent@latest -# or from inside Moss: -/upgrade -``` - -## Five-Minute Tutorial - -1. Open a project: +1. Open a project and start Moss: ```bash cd my-project moss ``` -2. Ask for a read-only orientation: +2. Ask for a read-only orientation, then check the runtime state: ```text Inspect this repo and tell me the build, test, and release path. - ``` - -3. Check the current runtime state: - - ```text /status /model ``` -4. Attach context: +3. Attach context (drag a path in, or use `/attach`); on the macOS TUI you can copy a screenshot and press `Ctrl+V`: ```text /attach ./screenshot.png - /attach ./notes.txt What is wrong in this UI? ``` - On the full macOS TUI, copy a screenshot and press `Ctrl+V`; Moss attaches it as `[Image #1]` for the next prompt. - -5. Give Moss a concrete task: +4. Give Moss a concrete task. It asks before file writes, commands, and external actions unless you choose a more autonomous policy: ```text Fix the failing test, explain the root cause, and run the narrowest verification. ``` -Moss asks before file writes, commands, and external actions unless you explicitly choose a more autonomous approval profile. - -For longer work, set an explicit goal: - -```text -/goal migrate this repo to the new package name and verify the build -``` - -The CLI keeps working until the goal is completed, blocked, cleared, or stopped. Normal tool-loop count limits are opt-in host/user budgets, not hidden defaults. - -## Honest Runtime Capabilities - -Moss now tells the model what is actually available in the current run before it starts working: - -- The system prompt includes the registered tool names for this run, so Moss should not invent tool names or claim unavailable capabilities. -- CodeGraph guidance is conditional: if `codegraph_*` MCP tools are registered, Moss can prefer structural navigation; otherwise it must say CodeGraph is unavailable and fall back to listed tools such as `search_code`, `search_files`, `list_directory`, and `read_file`. -- The behavior contract explicitly asks Moss to be 实事求是: separate verified facts from inference and assumptions, report missing evidence, and avoid filling unknown gaps just to sound confident. - -## Skills +## Interactive Commands -Moss discovers `SKILL.md` files under `.moss/skills/`, `.moss/agent/skills/`, legacy `skills/` and `agent/skills/`, and configured extra skill directories. Built-in workflow skills cover methodical building, debugging, test-driven changes, migration safety, and CodeGraph navigation when available. +Inside a session, type `/help` for the full list. The commands you will use most: -Moss can also install a new workspace skill itself through the `install_skill` tool. The tool writes a frontmatter-backed `SKILL.md` under `.moss/skills//SKILL.md`, is treated as a workspace write, and therefore goes through the normal approval policy. +| Command | Purpose | +| --- | --- | +| `/status` | Model, login, workspace, board target, and tool state | +| `/model` · `/models` | Switch the active model, or list models for the provider | +| `/sessions` · `/resume [key\|--last]` | List saved conversations, and switch into one | +| `/connect ` · `/disconnect` | Enter / leave board mode for an RDK device | +| `/goal ` | Run until a goal condition is met (goal runner) | +| `/compact` | Compress older history into a summary to free context | +| `/attach ` | Attach an image or text file to the next prompt | +| `/diff` · `/review` | Show working-tree changes, or review them for bugs/safety | +| `/mcp` · `/doctor` | Inspect MCP servers, or health-check the session | +| `/memory` · `/skills` | Show stored long-term memory, or available/learned skills | +| `/yolo` | Grant full power for this session — no per-call approval (`/yolo off` reverts) | +| `/clear` | Start a new conversation (clears the context window) | -Example prompt: +You can also press **Shift+Tab** to cycle the interaction mode (see [Automation And Safety](#automation-and-safety)). -```text -Turn the workflow we just used into a reusable Moss skill. Install it as a low-risk skill and include the trigger phrases we used. -``` +## Long-Running Tasks And Resume -## Use Your Own Model +Moss is built to survive long, interruptible work rather than restart from zero. -The built-in D-Robotics gateway is for instant first use. Configure your own provider when you need your own account, billing, private gateway, data-local deployment, or a self-hosted model. Your model config overrides the built-in gateway. - -Guided setup: +Every plain `moss` launch is a new saved conversation. Pick history back up only when you ask: ```bash -moss setup -moss auth status +moss resume --last # continue the most recent saved session +moss resume --session # continue a specific session +moss --session work # continue or create a named session +moss --continue "keep going" # one-shot that auto-resumes the latest session +moss fork --last # branch a copy of a session without touching the original ``` -Model settings (provider, model, baseUrl, API key) live in moss config only. Environment variables such as `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, or `DMOSS_PROVIDER` are deliberately ignored — a key exported for another tool will never silently change which provider Moss talks to. `moss doctor` lists any such leftover variables under `env ignored`. - -Private OpenAI-compatible gateway: - -```bash -moss config set provider openai-compatible -moss config set model -moss config set baseUrl https://llm.example.com -moss setup # stores the API key (hidden prompt) -moss auth status -moss -``` +Use `/sessions` to list saved conversations and `/resume [key|--last]` to switch into one without leaving Moss. The session pickers show a title derived from the first message, so a saved session is recognizable instead of a bare `cli-` key. -For scripts and CI, provide a config file instead of env vars: `moss --config-file /path/to/config.json` (JSON with `provider` / `model` / `baseUrl` / `apiKey`). +Within a run, Moss keeps a working-context checkpoint of the active task — goal, completed and pending steps, important paths, and recent tool findings. If a run is interrupted — a tool-loop guard fires, a tool errors, or the turn budget is reached — the task is marked **resumable** instead of lost, the CLI tells you it stopped before finishing and how to continue, and the saved context is re-injected on the next turn. Saying `continue` / `继续` (or running `/goal`) resumes from that checkpoint and avoids repeating finished steps rather than starting over. Compaction preserves the goal and pending steps, so long tasks keep their thread even after older history is summarized. -`baseUrl` is the API root, not the full chat endpoint. Do not include `/chat/completions`. Both `https://llm.example.com` and `https://llm.example.com/v1` are accepted; Moss calls `/v1/chat/completions` for OpenAI-compatible providers. +For multi-step work you can also hand Moss an explicit goal and let it drive: -Configuration priority is: CLI flags and `-c key=value` > project `.moss/config.json` > `moss config` / `moss setup` > built-in gateway. +```text +/goal migrate this repo to the new package name and verify the build +``` -Inside Moss, use `/model` to list models from the active provider when available, choose by number, or type `/model ` for a custom model. +The goal runner keeps working until the goal is completed, blocked, cleared, or stopped. Per-request tool-loop budgets are opt-in host/user limits. ## Connect An RDK Board @@ -173,11 +140,16 @@ Use `/connect` inside a live session; no restart is required: ```text /connect 192.168.1.10 --user root +/connect ubuntu@192.168.1.10 --port 2222 --key ~/.ssh/id_rsa /status Check camera, ROS2 nodes, disk space, and device health. ``` -After connection, Moss can route board diagnostics through the active device tool group while keeping the conversation context. The host still controls SSH credentials, approval policy, protected paths, and available device tools. +`/connect` verifies SSH reachability and credentials before enabling device tools; if the probe fails it reports why and the tools stay disabled. Pass `--no-verify` to register tools without probing (e.g. a board that is about to boot). + +After a verified connect the session enters **board mode**: the default tools (`exec`, `read_file`, `write_file`, `edit_file`, `list_directory`, `search_files`, `search_code`, `move_file`) run on the board over SSH, so working in Moss feels like running it on the board itself. ROS2 tools (`ros2_topic_list`, `ros2_topic_echo`, `ros2_node_list`, `ros2_service_call`, `ros2_launch`, …) and `device_*` diagnostics become available, and honor the board's `ROS_DOMAIN_ID` when one is configured. Leave board mode with `/disconnect` or Ctrl+D on an empty prompt — local tools are restored exactly as they were. Pass `--hybrid` to keep the local tools and only add the `device_*` / `ros2_*` tools alongside. + +The host still controls SSH credentials, approval policy, protected paths, and available device tools. Device and ROS tools require host-side `ssh`/`sshpass` and execute Linux commands on the remote device rather than on your workstation. ## Attach Images And Files @@ -188,19 +160,34 @@ After connection, Moss can route board diagnostics through the active device too Explain what you see and propose the next debug step. ``` -Images (`png`, `jpg`, `jpeg`, `gif`, `webp`) are sent as model image blocks when the active provider/model supports vision. Text files are inserted as prompt context. Use `/attach list` to review pending attachments and `/attach clear` to discard them before sending. +Images (`png`, `jpg`, `jpeg`, `gif`, `webp`) are sent as model image blocks when the active provider/model supports vision. Text files are inserted as prompt context. Use `/attach list` to review pending attachments and `/attach clear` to discard them. In a prompt, an `@path` reference (`summarize @README.md`) attaches that file inline. -## Build With Moss +## Use Your Own Model -Only using the CLI? You can stop here. +The built-in D-Robotics gateway is for instant first use. Configure your own provider when you need your own account, billing, private gateway, data-local deployment, or a self-hosted model. Your model config always overrides the built-in gateway. -Building a product or service that embeds Moss? Scaffold a host project: +```bash +moss setup # interactive: choose provider + model, paste the API key (hidden) +moss auth status # show the resolved provider/model/key source +``` + +Supported providers are `deepseek`, `qwen`, `openai`, `anthropic`, and `openai-compatible`. A private OpenAI-compatible gateway: ```bash -npx create-dmoss-app my-host +moss config set provider openai-compatible +moss config set model +moss config set baseUrl https://llm.example.com +moss setup # stores the API key (hidden prompt) +moss ``` -Embed into an existing product host by installing the packages, registering providers / tools / storage / approval gates / event sinks, publishing a `MossHostRuntimeManifest`, and running `evaluateMossHostCompatibility()` in CI. This is useful when you want Moss inside your own IDE, robot console, browser app, desktop app, or device platform instead of only as the `moss` terminal command - see [Integrating Moss Into A Host](#integrating-moss-into-a-host). +Model settings (provider, model, baseUrl, API key) live in moss config only. Environment variables such as `DEEPSEEK_API_KEY`, `OPENAI_API_KEY`, or `DMOSS_PROVIDER` are deliberately ignored — a key exported for another tool will never silently change which provider Moss talks to. `moss doctor` lists any such leftover variables under `env ignored`. + +`baseUrl` is the API root, not the full chat endpoint — do not include `/chat/completions`. Both `https://llm.example.com` and `https://llm.example.com/v1` are accepted; Moss calls `/v1/chat/completions` for OpenAI-compatible providers, and rejects a malformed base URL at set time instead of failing on the first call. + +Configuration priority is: CLI flags and `-c key=value` > project `.moss/config.json` > `moss config` / `moss setup` > built-in gateway. For scripts and CI, prefer an explicit config file over env vars: `moss --config-file /path/to/config.json` (JSON with `provider` / `model` / `baseUrl` / `apiKey`). + +Inside Moss, use `/model` to list models from the active provider, choose by number, or type `/model ` for a custom model. ## Automation And Safety @@ -212,18 +199,61 @@ DMOSS_CLI_AUTO_APPROVE=1 moss --workspace-write "write and verify the tool" moss config set profile autonomous ``` -`DMOSS_CLI_AUTO_APPROVE=1` only approves tools that pass the active safety policy. It does not bypass `--read-only`, `deniedTools`, protected paths, or workspace sandbox checks. For browser-driven real websites, use `--full-access` because `web_browser_control` is classified as an external interaction. +`DMOSS_CLI_AUTO_APPROVE=1` only approves tools that pass the active safety policy. It does not bypass `--read-only`, `deniedTools`, protected paths, the dangerous-command floor, or workspace sandbox checks. For browser-driven real websites, use `--full-access` because `web_browser_control` is classified as an external interaction. In a headless (`-p` / piped / non-TTY) run, auto-approved mutating tools leave a one-line `[approval]` audit note on stderr so the run stays observable. -Moss exposes two browser tools when a local Chrome/Chromium executable is available: `web_browser_fetch` for read-only JavaScript-rendered pages and `web_browser_control` for approved browser workflows. `@rdk-moss/agent` uses `puppeteer-core`, so it does not download a browser during install. If auto-discovery cannot find one, set: +Interactively you have three modes, toggled with **Shift+Tab**: `plan` (read-only — Moss proposes a plan but makes no changes), `default` (normal per-call approval), and `accept-edits` (auto-approve workspace writes). `/yolo` grants a full-power session with no per-call prompts for this run (`/yolo off` reverts). For unattended starts you can set the policy up front with `--ask-for-approval ` where `` is `never`, `prompt`, `on-request`, `read-only`, `workspace-write`, or `full-access`; an unknown value is rejected rather than silently ignored. None of these bypass `--read-only`, `deniedTools`, protected paths, or the dangerous-command floor. + +Trust can be scoped per tool with `moss config set trustedTools ` and `deniedTools ` (name or glob). A broad wildcard such as `*` is flagged when you set it, because it auto-approves every tool. Device mutations (reboot, restart, on-device `rm`, `ros2_service_call`, …) are never blanket-trusted: answering "always" approves only the current call, and the next device command still prompts. + +Moss exposes two browser tools when a local Chrome/Chromium executable is available: `web_browser_fetch` for read-only JavaScript-rendered pages and `web_browser_control` for approved browser workflows. `@rdk-moss/agent` uses `puppeteer-core`, so it does not download a browser during install. If auto-discovery cannot find one, set `export DMOSS_BROWSER_EXECUTABLE="/path/to/chrome-or-chromium"`. + +## MCP Servers + +Moss can load tools from [Model Context Protocol](https://modelcontextprotocol.io) servers. Register them without editing JSON: ```bash -export DMOSS_BROWSER_EXECUTABLE="/path/to/chrome-or-chromium" +moss mcp add fs npx -y @modelcontextprotocol/server-filesystem /data +moss mcp add ros-docs node ./mcp/ros-docs.js --env ROS_DISTRO=humble +moss mcp list +moss mcp remove fs +moss config set mcp.enabled true # enable MCP servers from config ``` +Inside a session, `/mcp` shows configured servers, their connection status, and tool counts. A server whose connection fails is reported rather than silently dropped. The server config lives next to your Moss config (default `~/.config/dmoss/mcp.json`); override the path with `moss config set mcp.configPath ` or `DMOSS_MCP_CONFIG`. + +## Skills And Memory + +Moss discovers `SKILL.md` files under `.moss/skills/`, `.moss/agent/skills/`, legacy `skills/` and `agent/skills/`, and configured extra skill directories. Built-in workflow skills cover methodical building, debugging, test-driven changes, migration safety, and CodeGraph navigation when available. Moss can install a new workspace skill itself through the `install_skill` tool, which writes a frontmatter-backed `SKILL.md` under `.moss/skills//SKILL.md` as a workspace write that goes through the normal approval policy. Successful runs can also crystallize into skill candidates you review with `/skills` and promote or discard. + +Long-term memory is available through `memory_read` / `memory_write` / `memory_delete`, and Moss auto-loads workspace context from `USER.md`, `MEMORY.md`, and `AGENTS.md` at the workspace root. Use `/memory` to see stored memories. + +## Honest Runtime Behavior + +Moss tells the model what is actually available in the current run before it starts working: + +- The system prompt includes the registered tool names for this run, so Moss should not invent tool names or claim unavailable capabilities. +- CodeGraph guidance is conditional: if `codegraph_*` tools are registered, Moss can prefer structural navigation; otherwise it says CodeGraph is unavailable and falls back to `search_code`, `search_files`, `list_directory`, and `read_file`. +- The behavior contract asks Moss to be 实事求是: separate verified facts from inference and assumptions, report missing evidence, and never claim a result — "connected", "launched", "opened", "done" — without an actual check behind it. Moss does not spawn a desktop GUI app to "open a terminal"; it already runs inside one. + +## Troubleshooting + +Run `moss doctor` to health-check Node, version, auth, provider/model, workspace, runtime dir, safety policy, and MCP in one report. It exits non-zero on a real failure, so it works as a CI health gate. Inside a session, `/doctor` runs the same check for the live run and `/mcp` shows MCP status. `moss config validate` checks config files and surfaces audit warnings. + +## Build With Moss + +Only using the CLI? You can stop here. + +Building a product or service that embeds Moss? Scaffold a host project: + +```bash +npx create-dmoss-app my-host +``` + +Embed into an existing product host by installing the packages, registering providers / tools / storage / approval gates / event sinks, publishing a `MossHostRuntimeManifest`, and running `evaluateMossHostCompatibility()` in CI. This is useful when you want Moss inside your own IDE, robot console, browser app, desktop app, or device platform instead of only as the `moss` terminal command — see [Integrating Moss Into A Host](#integrating-moss-into-a-host). + ## Repository Scope -This repository contains the parts of Moss that can be maintained independently -from a product shell. +This repository contains the parts of Moss that can be maintained independently from a product shell. | Package | Role | | --- | --- | @@ -238,8 +268,7 @@ Product hosts are outside this repository. ## Architecture -If you only use `moss`, you can skip this section. It exists for teams that -embed Moss into a larger product. +If you only use `moss`, you can skip this section. It exists for teams that embed Moss into a larger product. Moss is split around a narrow host boundary: @@ -260,9 +289,7 @@ Moss packages - public extension contracts ``` -The agent runtime should not import product code. Product hosts inject concrete -providers, tools, storage, approval handling, knowledge modules, and event -transports. +The agent runtime should not import product code. Product hosts inject concrete providers, tools, storage, approval handling, knowledge modules, and event transports. ## Host Adapter Contract @@ -276,18 +303,7 @@ import { } from '@rdk-moss/core/contracts/host-adapter'; ``` -A host declares: - -- Host id, name, and version. -- Moss package versions it is consuming. -- Capabilities such as `llm_provider`, `tool_registry`, `approval_gate`, - `event_sink`, `memory`, `knowledge`, `device_runtime`, and `channel_runtime`. -- Provider families supplied by the host. -- Tool names and permission boundaries. -- Event schemas and knowledge modules. - -Moss releases use `evaluateMossHostCompatibility()` to decide whether the host -can consume the release unchanged. +A host declares its id/name/version, the Moss package versions it consumes, capabilities such as `llm_provider`, `tool_registry`, `approval_gate`, `event_sink`, `memory`, `knowledge`, `device_runtime`, and `channel_runtime`, the provider families it supplies, tool names and permission boundaries, and event schemas and knowledge modules. Moss releases use `evaluateMossHostCompatibility()` to decide whether a host can consume the release unchanged. Read the detailed contract guide: @@ -295,128 +311,77 @@ Read the detailed contract guide: ## Project Goal And Roadmap -Moss is being developed as a robotics-grade, host-neutral agent runtime. The -roadmap defines the north star, non-goals, six-month target, and phase plan: +Moss is being developed as a robotics-grade, host-neutral agent runtime. The roadmap defines the north star, non-goals, six-month target, and phase plan: - [`docs/roadmap.md`](docs/roadmap.md) ## Maintainer Guides -These documents are intended to be durable project manuals, not session notes: - -- [`AGENTS.md`](AGENTS.md): agent working rules, architecture-review discipline, - CodeGraph usage, and bug-fix checklists for this repository. -- [`ARCHITECTURE_ASSESSMENT.md`](ARCHITECTURE_ASSESSMENT.md): current - architecture findings, rejected hypotheses, and "do not change" decisions. -- [`CLEAN_CODE_ASSESSMENT.md`](CLEAN_CODE_ASSESSMENT.md): code quality review - and cleanup guidance. -- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md): Host - Adapter contract guide. -- [`docs/tool-runtime.md`](docs/tool-runtime.md): tool execution pipeline, - ownership boundaries, hooks, approval, timeout, and guard limits. -- [`docs/tool-side-effect-idempotency-rfc.md`](docs/tool-side-effect-idempotency-rfc.md): - RFC for in-flight deduplication of non-idempotent tools. -- [`docs/release-checklist.md`](docs/release-checklist.md): release validation - and host update checklist. - -Historical phase notes such as [`docs/goals-phase-5.md`](docs/goals-phase-5.md) -and [`docs/goals-phase-6.md`](docs/goals-phase-6.md) can help explain why the -current contracts and tests exist, but the roadmap and release checklist are the -source of truth for new work. +These documents are durable project manuals, not session notes: + +- [`AGENTS.md`](AGENTS.md): agent working rules, architecture-review discipline, CodeGraph usage, and bug-fix checklists for this repository. +- [`ARCHITECTURE_ASSESSMENT.md`](ARCHITECTURE_ASSESSMENT.md): current architecture findings, rejected hypotheses, and "do not change" decisions. +- [`CLEAN_CODE_ASSESSMENT.md`](CLEAN_CODE_ASSESSMENT.md): code quality review and cleanup guidance. +- [`docs/host-adapter-contract.md`](docs/host-adapter-contract.md): Host Adapter contract guide. +- [`docs/tool-runtime.md`](docs/tool-runtime.md): tool execution pipeline, ownership boundaries, hooks, approval, timeout, and guard limits. +- [`docs/tool-side-effect-idempotency-rfc.md`](docs/tool-side-effect-idempotency-rfc.md): RFC for in-flight deduplication of non-idempotent tools. +- [`docs/release-checklist.md`](docs/release-checklist.md): release validation and host update checklist. + +Historical phase notes such as [`docs/goals-phase-5.md`](docs/goals-phase-5.md) and [`docs/goals-phase-6.md`](docs/goals-phase-6.md) explain why the current contracts and tests exist, but the roadmap and release checklist are the source of truth for new work. ## Architecture Review Discipline -Do not turn open-ended reviews into endless issue lists. A candidate issue is -worth fixing only when it blocks a committed goal, a real host path, safety, -data correctness, resource lifecycle, or a contract that downstream users rely -on. Style concerns, framework feature comparisons, and speculative future -abstractions should be recorded as observations or rejected explicitly. +Do not turn open-ended reviews into endless issue lists. A candidate issue is worth fixing only when it blocks a committed goal, a real host path, safety, data correctness, resource lifecycle, or a contract that downstream users rely on. Style concerns, framework feature comparisons, and speculative future abstractions should be recorded as observations or rejected explicitly. Before changing architecture, preserve this loop: 1. Generate hypotheses from the actual code and active host workflows. -2. Try to falsify each hypothesis by reading source, checking callers, tracing - runtime flow, or running a focused test. -3. Fix bugs with declare + enforce + test. Existing tests are regression - checks; the fix still needs a test that would have failed before the change. -4. Document "do not touch" conclusions when a suspicion is falsified, so future - reviews do not spend time re-litigating the same point. +2. Try to falsify each hypothesis by reading source, checking callers, tracing runtime flow, or running a focused test. +3. Fix bugs with declare + enforce + test. Existing tests are regression checks; the fix still needs a test that would have failed before the change. +4. Document "do not touch" conclusions when a suspicion is falsified, so future reviews do not re-litigate the same point. ## What Does Not Belong In Moss -Keep product-specific code in the host repository. - -Do not add: +Keep product-specific code in the host repository. Do not add: - Product-host `server/**`, `src/**`, or native-shell code. -- Product configuration defaults, local sessions, logs, or generated desktop - artifacts. -- Supabase keys, model keys, image provider keys, device passwords, SSH - credentials, or user account details. -- Host-owned integrations such as board deployment, external chat channels, - desktop IPC, native packaging, or product settings UI. +- Product configuration defaults, local sessions, logs, or generated desktop artifacts. +- Supabase keys, model keys, image provider keys, device passwords, SSH credentials, or user account details. +- Host-owned integrations such as board deployment, external chat channels, desktop IPC, native packaging, or product settings UI. - Built `dist/` directories as tracked source. -RDK-specific domain knowledge may live in a separate optional package. The Moss -core packages should stay useful to other robotics or device-product hosts. +RDK-specific domain knowledge may live in a separate optional package. The Moss core packages should stay useful to other robotics or device-product hosts. ## Development -Use Node 22.16 or newer for this workspace. - -Moss is verified on Ubuntu, macOS, and Windows in CI. Device and ROS tools are -optional runtime capabilities: they require host-side `ssh`/`sshpass` when -configured, and execute Linux commands on the remote device rather than on the -developer workstation. +Use Node 22.16 or newer for this workspace. Moss is verified on Ubuntu, macOS, and Windows in CI. ```sh npm install npm run verify ``` -`npm run verify` runs: - -1. Open-source boundary checks. -2. Workspace hygiene checks for Node engine consistency, package test scripts, - and local Markdown links. -3. Workspace builds. -4. Typechecks. -5. Package tests. - -The boundary check can be run directly: - -```bash -npm run check:boundaries -``` +`npm run verify` runs open-source boundary checks, workspace hygiene checks (Node engine consistency, package test scripts, and local Markdown links), workspace builds, typechecks, and package tests. The boundary check can be run directly with `npm run check:boundaries`. ## Integrating Moss Into A Host 1. Install or vendor the relevant Moss packages. 2. Keep credentials and product-specific defaults in the host. -3. Register host providers, tools, storage, approval gates, and event sinks with - the agent runtime. +3. Register host providers, tools, storage, approval gates, and event sinks with the agent runtime. 4. Publish a `MossHostRuntimeManifest` from the host adapter. -5. Run `evaluateMossHostCompatibility()` in CI before adopting a new Moss - release. +5. Run `evaluateMossHostCompatibility()` in CI before adopting a new Moss release. -For a downstream product host, the host adapter lives in that host repository -and should be validated by its own Moss upgrade flow. +For a downstream product host, the host adapter lives in that host repository and should be validated by its own Moss upgrade flow. ## Version Policy Moss follows semver for the public package surface. -- Patch releases fix bugs or improve internals without requiring host adapter - changes. -- Minor releases may add optional fields, optional capabilities, or new helper - APIs. Existing hosts should continue to work. -- Major releases may change required Host Adapter fields or required - capabilities. Hosts must update their adapter before adopting the release. +- Patch releases fix bugs or improve internals without requiring host adapter changes. +- Minor releases may add optional fields, optional capabilities, or new helper APIs. Existing hosts should continue to work. +- Major releases may change required Host Adapter fields or required capabilities. Hosts must update their adapter before adopting the release. -For downstream product hosts, a Moss patch or minor update should normally be a -submodule/package update plus validation. Adapter changes are required only when -`MOSS_HOST_ADAPTER_CONTRACT_VERSION` changes incompatibly or a release declares -new required host capabilities, event schemas, or provider families. +For downstream product hosts, a Moss patch or minor update should normally be a submodule/package update plus validation. Adapter changes are required only when `MOSS_HOST_ADAPTER_CONTRACT_VERSION` changes incompatibly or a release declares new required host capabilities, event schemas, or provider families. ## Release Checklist @@ -431,5 +396,4 @@ npm run verify npm run smoke:moss-cli ``` -If the release is intended for a downstream host, update its Moss dependency or -vendored subtree and run the host upgrade verification there. +If the release is intended for a downstream host, update its Moss dependency or vendored subtree and run the host upgrade verification there. diff --git a/packages/dmoss-agent/README.md b/packages/dmoss-agent/README.md index 0f0b800..235c4e3 100644 --- a/packages/dmoss-agent/README.md +++ b/packages/dmoss-agent/README.md @@ -236,6 +236,9 @@ moss "prompt" run a one-shot prompt moss auth login optional: link a D-Robotics developer community account moss auth status show community login and provider/model/key source moss setup configure your own provider/model/API key +moss doctor health-check config, auth, workspace, board, and MCP (non-zero exit on failure) +moss resume --last continue the most recent saved session (fork --last branches a copy) +moss mcp add [args...] register an MCP server without editing JSON (mcp list / mcp remove) moss config --help show configuration commands moss --help show the focused CLI help moss --help --all show the complete CLI reference @@ -249,8 +252,12 @@ Inside Moss: /goal show or manage the active goal runner /compact compress older conversation history into a summary /attach attach an image or text file to the next prompt -/connect connect an RDK board for this session -/sessions list saved conversations you can resume +/connect connect an RDK board and enter board mode (/disconnect to leave) +/sessions list saved conversations (use /resume to switch into one) +/resume switch this session to a saved conversation ([key|--last]) +/mcp show configured MCP servers, status, and tool counts +/doctor health-check model, egress, board, MCP, and config in this session +/yolo grant full power for this session — no per-call approval (/yolo off reverts) /diff show git working-tree changes /auth login optional: link a D-Robotics developer community account /help show focused command help diff --git a/packages/dmoss-agent/src/cli-main.ts b/packages/dmoss-agent/src/cli-main.ts index 9c011ee..9f8c42e 100644 --- a/packages/dmoss-agent/src/cli-main.ts +++ b/packages/dmoss-agent/src/cli-main.ts @@ -4,9 +4,9 @@ import { execSync } from 'node:child_process'; import os from 'node:os'; import { resolveCliAgentRuntimeOptions } from './cli/agent-runtime.js'; import { createCliToolApprovalHook, resolveCliSafetyMode } from './cli/approval.js'; -import { loadCliConfigFile, loadEnvFromAncestors, resolveCliConfig, resolveConfigDir, safeProcessCwd } from './cli/config.js'; +import { CliConfigWriteError, loadCliConfigFile, loadEnvFromAncestors, resolveCliConfig, resolveConfigDir, safeProcessCwd } from './cli/config.js'; import { parseCliArgs } from './cli/args.js'; -import { renderCliDoctor } from './cli/doctor.js'; +import { renderCliDoctor, cliDoctorHasFailure } from './cli/doctor.js'; import { displayHelp, displayVersion } from './cli/help.js'; import { createConfiguredGuardrailHooks } from './cli/guardrails.js'; import { createConfiguredHookCallbacks } from './cli/hooks.js'; @@ -195,6 +195,17 @@ if (parsedArgs.help && parsedArgs.command === 'config') { if (parsedArgs.help) displayHelp(c, { all: parsedArgs.helpAll }); if (parsedArgs.version) displayVersion(c); +// A mistyped subcommand (`moss confgi`) must NOT silently become a billable chat +// one-shot. Fail fast with a suggestion; the user can still force a prompt via +// `moss chat ""`. Only bare single-token typos reach here (see parseCliArgs). +if (parsedArgs.unknownCommand) { + const { token, suggestion } = parsedArgs.unknownCommand; + console.error(`moss: unknown command '${token}'`); + console.error(`Did you mean '${suggestion}'? Run \`moss --help\` for usage.`); + console.error(`To send it to the agent as a prompt instead: moss chat "${token}"`); + process.exit(1); +} + async function setupMesh(agent: DmossAgent, deviceConfig: DeviceSshConfig | null) { const meshPort = parseInt(process.env.DMOSS_MESH_PORT || '9090', 10); const meshId = process.env.DMOSS_MESH_ID || `dmoss-${Date.now()}`; @@ -324,7 +335,11 @@ async function main() { // Model settings are config-only (decision 2026-06). Say so once when a // leftover provider env var is present, instead of silently ignoring it — // doctor shows the same list as a structured `env ignored` line. - if (resolvedConfig.ignoredModelEnvVars.length > 0 && parsedArgs.command !== 'doctor') { + // Gate on the resolved CLI log level so `--quiet` / `DMOSS_LOG_LEVEL=warn` + // silence this notice; doctor's `env ignored` line stays the source of truth. + const cliLogLevel = resolveCliLogLevel(); + const noticesVisible = cliLogLevel === 'debug' || cliLogLevel === 'info'; + if (resolvedConfig.ignoredModelEnvVars.length > 0 && parsedArgs.command !== 'doctor' && noticesVisible) { console.error( `[config] ignoring model env var(s): ${resolvedConfig.ignoredModelEnvVars.join(', ')} — ` + 'model settings come only from moss config (moss setup / moss config set)', @@ -338,15 +353,17 @@ async function main() { const runtimeDir = workspacePathMigration.paths.runtimeDir; if (parsedArgs.command === 'doctor') { - console.error(await renderCliDoctor({ + const report = await renderCliDoctor({ config: resolvedConfig, configDir: resolveConfigDir(), runtimeDir, currentVersion: getPackageVersion(), safetyMode, detailMode: resolveCliDetailMode(argv), - })); - return; + }); + console.error(report); + // Exit non-zero on any `fail` line so doctor works as an automation health gate. + process.exit(cliDoctorHasFailure(report) ? 1 : 0); } if (parsedArgs.command === 'update') { const code = await runCliUpdate({ @@ -403,6 +420,11 @@ async function main() { useLast: parsedArgs.sessionLast || continueLatest, forkSource: parsedArgs.forkSource, }); + if (session.error) { + console.error(`[session] ${session.error}`); + console.error('[session] List saved sessions with `moss sessions`, or start a new one with `moss`.'); + process.exit(1); + } if (session.notice) console.error(`[session] ${session.notice}`); const memoryManager = new MemoryManager(workspacePathMigration.paths.memoryDir); const skillLearner = new SkillLearner({ skillsDir: workspacePathMigration.paths.skillsDir }); @@ -559,4 +581,13 @@ async function main() { } } -main().catch((err) => { console.error('Fatal:', err); process.exit(1); }); +main().catch((err) => { + // Config-write failures already carry a clean, actionable one-liner — show it + // alone instead of a raw Node stack from writeFileSync. + if (err instanceof CliConfigWriteError) { + console.error(`moss: ${err.message}`); + process.exit(1); + } + console.error('Fatal:', err); + process.exit(1); +}); diff --git a/packages/dmoss-agent/src/cli/approval.ts b/packages/dmoss-agent/src/cli/approval.ts index efa3e2b..7333944 100644 --- a/packages/dmoss-agent/src/cli/approval.ts +++ b/packages/dmoss-agent/src/cli/approval.ts @@ -291,6 +291,17 @@ function isWorkspaceTrustEligible(sideEffect: ToolSideEffectClass): boolean { return sideEffect === 'local_write'; } +/** + * Whether answering "a" (Always) may blanket-trust this tool for the rest of + * the session. device_mutation is excluded: those are idempotent:false physical + * board operations (reboot, restart, rm on the device), so trusting the whole + * tool by name after one approval would silently auto-approve every later + * device command. They re-prompt every time; "a" only approves the current call. + */ +function isSessionTrustEligible(sideEffect: ToolSideEffectClass): boolean { + return sideEffect !== 'device_mutation'; +} + function previewInput(input: Record): string { const raw = sanitizeSecrets(JSON.stringify(input, null, 2)); return raw.length > 1200 ? `${raw.slice(0, 1200)}\n... [truncated ${raw.length} chars]` : raw; @@ -401,8 +412,11 @@ function approvalScopeSummary(preview: CliToolApprovalPreview, input: Record line !== ''); return lines.join('\n'); } @@ -592,6 +609,12 @@ export function createCliToolApprovalHook( // was unusable for any mutating tool). read-only still blocks all mutation at // isAllowedInMode above; the dangerous-command floor and deniedTools still apply. if (!process.stdin.isTTY) { + // Headless auto-approval is a real decision with no human in the loop: + // leave a one-line audit trail on stderr so `-p` runs are observable. + // (deniedTools / read-only / isCommandDangerous already gated above.) + console.error( + `[approval] headless auto-approve: ${tool.name} (${preview.sideEffect}) under ${liveMode} — no TTY to prompt`, + ); return { approved: true }; } @@ -603,9 +626,11 @@ export function createCliToolApprovalHook( if (answer === 'a' || answer === 'always') { if (isWorkspaceTrustEligible(preview.sideEffect)) { sessionTrustedWorkspaces.add(workspaceRoot); - } else { + } else if (isSessionTrustEligible(preview.sideEffect)) { sessionTrustedTools.add(tool.name); } + // device_mutation: "a" approves this call only — never blanket-trust the + // tool, so the next device command still prompts. return { approved: true }; } if (answer === 'y' || answer === 'yes') { diff --git a/packages/dmoss-agent/src/cli/args.ts b/packages/dmoss-agent/src/cli/args.ts index 2d76fdd..22931a7 100644 --- a/packages/dmoss-agent/src/cli/args.ts +++ b/packages/dmoss-agent/src/cli/args.ts @@ -25,6 +25,12 @@ export interface ParsedCliArgs { print: boolean; outputFormat: 'text' | 'json' | 'stream-json'; maxTurns?: number; + /** + * Set when a bare single-token invocation looks like a mistyped subcommand + * (e.g. `moss confgi`). The caller must surface "unknown command, did you + * mean …?" and exit non-zero instead of starting a billable chat one-shot. + */ + unknownCommand?: { token: string; suggestion: string }; rawArgv: string[]; } @@ -137,20 +143,60 @@ function normalizeDetail(value: string): ParsedCliArgs['detailMode'] { throw new Error(`Unsupported detail mode "${value}"`); } +const KNOWN_COMMANDS: readonly CliCommand[] = [ + 'setup', + 'auth', + 'config', + 'doctor', + 'update', + 'resume', + 'fork', + 'mcp', +]; + function asCommand(value: string | undefined): CliCommand | null { - if ( - value === 'setup' || - value === 'auth' || - value === 'config' || - value === 'doctor' || - value === 'update' || - value === 'resume' || - value === 'fork' || - value === 'mcp' - ) { - return value; + return value && (KNOWN_COMMANDS as readonly string[]).includes(value) ? (value as CliCommand) : null; +} + +function levenshtein(a: string, b: string): number { + const m = a.length; + const n = b.length; + if (m === 0) return n; + if (n === 0) return m; + let prev = Array.from({ length: n + 1 }, (_, i) => i); + let curr = new Array(n + 1); + for (let i = 1; i <= m; i++) { + curr[0] = i; + for (let j = 1; j <= n; j++) { + const cost = a[i - 1] === b[j - 1] ? 0 : 1; + curr[j] = Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost); + } + [prev, curr] = [curr, prev]; } - return null; + return prev[n]; +} + +/** + * Closest known subcommand within edit distance 2, or null. Used to turn a + * mistyped `moss confgi` into a "did you mean 'config'?" error instead of a + * silent billable chat one-shot. Deliberately conservative: an exact command + * match is handled earlier, and legitimate one-word prompts (`moss hi`) sit far + * outside distance 2 from every command so they keep flowing to chat. + * @public + */ +export function closestKnownCommand(token: string): string | null { + const candidate = token.toLowerCase().trim(); + if (!candidate || (KNOWN_COMMANDS as readonly string[]).includes(candidate)) return null; + let best: string | null = null; + let bestDistance = Infinity; + for (const command of KNOWN_COMMANDS) { + const distance = levenshtein(candidate, command); + if (distance < bestDistance) { + bestDistance = distance; + best = command; + } + } + return bestDistance <= 2 ? best : null; } function flagConsumesNext(arg: string): boolean { @@ -322,11 +368,19 @@ export function parseCliArgs(argv: string[]): ParsedCliArgs { if (arg === '--ask-for-approval' || arg.startsWith('--ask-for-approval=')) { const parsed = readValue(argv, i, arg); const raw = parsed.value.toLowerCase().trim(); - if (raw === 'never') { + const approval = normalizeApprovalPolicyConfig(raw); + const safety = normalizeSafetyMode(raw); + if (!approval && !safety) { + // Silently dropping unknown values let `--ask-for-approval yolo` look + // accepted while changing nothing; reject so the user sees the typo. + throw new Error( + `--ask-for-approval must be never|prompt|on-request|read-only|workspace-write|full-access, got "${parsed.value}"`, + ); + } + if (approval === 'never') { approvalPolicy = 'never'; configOverrides.approvalPolicy = 'never'; } - const safety = normalizeSafetyMode(raw); if (safety) safetyModeOverride = safety; i = parsed.nextIndex; continue; @@ -371,6 +425,21 @@ export function parseCliArgs(argv: string[]): ParsedCliArgs { } } + // Catch a mistyped subcommand BEFORE it becomes a billable chat one-shot. + // Only a bare single-token invocation (`moss confgi`) with no flags qualifies; + // multi-word prose prompts and flag-bearing invocations are never intercepted. + let unknownCommand: ParsedCliArgs['unknownCommand']; + if ( + command === 'chat' && + commandArgs.length === 0 && + promptParts.length === 1 && + !argv.includes('--') && + !argv.some((token) => token.startsWith('-')) + ) { + const suggestion = closestKnownCommand(promptParts[0]); + if (suggestion) unknownCommand = { token: promptParts[0], suggestion }; + } + return { command, commandArgs, @@ -390,6 +459,7 @@ export function parseCliArgs(argv: string[]): ParsedCliArgs { print, outputFormat, maxTurns, + unknownCommand, rawArgv: argv, }; } diff --git a/packages/dmoss-agent/src/cli/config.ts b/packages/dmoss-agent/src/cli/config.ts index c84f750..dfcf3ba 100644 --- a/packages/dmoss-agent/src/cli/config.ts +++ b/packages/dmoss-agent/src/cli/config.ts @@ -135,6 +135,23 @@ export class CliConfigFileError extends Error { } } +/** + * Raised when persisting a config file fails (EACCES on a read-only dir, ENOSPC, + * a root-owned config.json after `sudo npm i -g`, …). Carries a one-line, + * stack-free message so the CLI surfaces `cannot write config to : ` + * instead of dumping a raw `writeFileSync` Node stack at the user. + * @public + */ +export class CliConfigWriteError extends Error { + readonly configPath: string; + + constructor(configPath: string, reason: string) { + super(`cannot write config to ${configPath}: ${reason}`); + this.name = 'CliConfigWriteError'; + this.configPath = configPath; + } +} + export type CliConfigProfile = 'cautious' | 'balanced' | 'autonomous'; export type CliSafetyModeConfig = 'read-only' | 'workspace-write' | 'full-access'; export type ConfigApprovalPolicy = 'prompt' | 'never'; @@ -430,11 +447,19 @@ export function loadCliConfigFile( } export function saveConfigFileAtPath(config: ConfigFile, configPath: string): void { - fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 }); - fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { - encoding: 'utf-8', - mode: 0o600, - }); + try { + fs.mkdirSync(path.dirname(configPath), { recursive: true, mode: 0o700 }); + fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`, { + encoding: 'utf-8', + mode: 0o600, + }); + } catch (err) { + // A write failure (EACCES/EPERM/ENOSPC/EROFS) must read as a clean, + // actionable line — never a raw Node stack trace through the top-level + // `Fatal:` handler. + const reason = err instanceof Error ? err.message : String(err); + throw new CliConfigWriteError(configPath, reason); + } try { fs.chmodSync(configPath, 0o600); } catch { diff --git a/packages/dmoss-agent/src/cli/doctor.ts b/packages/dmoss-agent/src/cli/doctor.ts index f9f9f87..e72b820 100644 --- a/packages/dmoss-agent/src/cli/doctor.ts +++ b/packages/dmoss-agent/src/cli/doctor.ts @@ -29,6 +29,17 @@ function fail(label: string, detail: string): string { return ` fail ${label}: ${detail}`; } +/** + * True when a rendered doctor report contains at least one `fail` line. The + * caller exits non-zero on failure so `moss doctor` is usable as a CI/automation + * health gate (it previously always exited 0, masking unwritable workspaces, + * missing API keys, and broken MCP config). + * @public + */ +export function cliDoctorHasFailure(report: string): boolean { + return report.split('\n').some((line) => line.startsWith(' fail ')); +} + export function renderNodeDoctorLine(version: string = process.version): string { return nodeVersionProblem(version) ? fail('node', `${version}; requires >=${MIN_NODE_MAJOR}.${MIN_NODE_MINOR}.0`) diff --git a/packages/dmoss-agent/src/cli/model-catalog.ts b/packages/dmoss-agent/src/cli/model-catalog.ts index 52b53d8..ce3c4d6 100644 --- a/packages/dmoss-agent/src/cli/model-catalog.ts +++ b/packages/dmoss-agent/src/cli/model-catalog.ts @@ -1,5 +1,5 @@ import fs from 'node:fs'; -import { buildApiV1Url } from '../provider/api-v1-url.js'; +import { buildApiV1Url, isHttpUrl } from '../provider/api-v1-url.js'; import { normalizeProvider, parseConfigBoolean, @@ -140,6 +140,9 @@ export function parseCustomModelConfigInput(input: string): CustomModelConfigPar if (!baseUrl || !apiKey || !model) { return { ok: false, message: 'Missing base_url, api key, or model_name.' }; } + if (!isHttpUrl(baseUrl)) { + return { ok: false, message: `Invalid base_url: ${baseUrl}. Use a full http(s) URL, e.g. https://your-gateway.example/v1.` }; + } const imageInput = values.imageInput === undefined ? undefined : parseConfigBoolean(values.imageInput); if (values.imageInput !== undefined && imageInput === null) { diff --git a/packages/dmoss-agent/src/cli/output.ts b/packages/dmoss-agent/src/cli/output.ts index 18b61ce..44b07ee 100644 --- a/packages/dmoss-agent/src/cli/output.ts +++ b/packages/dmoss-agent/src/cli/output.ts @@ -219,7 +219,7 @@ export function createCliRunRenderer(options: CliRunRendererOptions = {}) { breakAnswerForStatus(); stderrLine(`${mark('fail')} error ${event.retriable ? 'retryable ' : ''}${summarizeForCli(event.error, 400)}`); break; - case 'done': + case 'done': { if (state.thinkingOpen) { stderr.write('\n'); state.thinkingOpen = false; @@ -228,7 +228,19 @@ export function createCliRunRenderer(options: CliRunRendererOptions = {}) { stdout.write('\n'); state.answerOpen = false; } + // Long-horizon continuity: a run stopped by the turn cap is TRUNCATED, + // not finished. Without this the partial answer is indistinguishable + // from normal completion and the user never learns to continue. Printed + // even in quiet mode because it is a hard stop, not progress noise; + // gated on the truncation stop reason so normal completions stay silent. + const stopReason = event.result?.stopReason; + if (stopReason === 'max_turns_reached' || stopReason === 'tool_followup_cap_reached') { + stderrLine( + `${mark('fail')} stopped at the turn limit before finishing — the task is paused, not complete. Continue with ${ui.bold('moss resume --last')} (or ${ui.bold('moss --continue')}).`, + ); + } break; + } } } diff --git a/packages/dmoss-agent/src/cli/session.ts b/packages/dmoss-agent/src/cli/session.ts index 70b0d03..06e00c7 100644 --- a/packages/dmoss-agent/src/cli/session.ts +++ b/packages/dmoss-agent/src/cli/session.ts @@ -7,6 +7,12 @@ export interface CliSessionResolution { sourceSessionKey?: string; forked: boolean; notice?: string; + /** + * Set when an explicit session key was requested but does not exist. The CLI + * must surface this and exit non-zero instead of printing a false + * "Resuming session" notice over an empty conversation. + */ + error?: string; } function sortRecent(sessions: SessionMeta[]): SessionMeta[] { @@ -59,8 +65,14 @@ async function resolveExistingSession( store: SessionStore, explicit: string | undefined, useLast: boolean, -): Promise<{ key: string; notice?: string } | null> { - if (explicit) return { key: explicit }; +): Promise<{ key: string; notice?: string; error?: string } | null> { + if (explicit) { + // Verify the key actually exists before claiming a resume. Returning it + // unchecked printed "Resuming session: " then ran an empty session + // when the key was a typo (no success without a verified outcome). + if (await store.exists(explicit)) return { key: explicit }; + return { key: explicit, error: `No saved session named "${explicit}" in this workspace.` }; + } const sessions = sortRecent(await store.listSessions()); if (sessions.length === 0) return null; if (useLast) return { key: sessions[0].sessionKey }; @@ -82,6 +94,9 @@ export async function resolveCliSession(options: { if (options.command === 'resume') { const resolved = await resolveExistingSession(options.store, options.sessionKey, Boolean(options.useLast)); + if (resolved?.error) { + return { sessionKey: resolved.key, forked: false, error: resolved.error }; + } if (!resolved) { const sessionKey = options.sessionKey || createCliSessionKey(); return { @@ -98,8 +113,11 @@ export async function resolveCliSession(options: { } const source = await resolveExistingSession(options.store, options.forkSource || options.sessionKey, Boolean(options.useLast)); + if (source?.error) { + return { sessionKey: source.key, forked: true, error: source.error }; + } if (!source) { - const fallback = `cli-fork-${timestampForKey()}`; + const fallback = `cli-fork-${timestampForKey()}-${randomUUID().slice(0, 8)}`; return { sessionKey: fallback, forked: true, @@ -107,7 +125,10 @@ export async function resolveCliSession(options: { }; } const messages = await options.store.loadMessages(source.key); - const forkKey = `cli-fork-${timestampForKey()}`; + // Second-precision timestamps collide when two forks land in the same second; + // the random suffix (mirroring createCliSessionKey) keeps rapid forks distinct + // so one long-task branch never silently overwrites another. + const forkKey = `cli-fork-${timestampForKey()}-${randomUUID().slice(0, 8)}`; await options.store.replaceMessages(forkKey, messages); return { sessionKey: forkKey, diff --git a/packages/dmoss-agent/src/cli/setup.ts b/packages/dmoss-agent/src/cli/setup.ts index e836e59..e4c88f4 100644 --- a/packages/dmoss-agent/src/cli/setup.ts +++ b/packages/dmoss-agent/src/cli/setup.ts @@ -2,9 +2,10 @@ import fs from 'node:fs'; import path from 'node:path'; import * as readline from 'node:readline'; import { stdin as input, stderr as output, stdout as standardOutput } from 'node:process'; -import { stripEndpointSuffix } from '../provider/api-v1-url.js'; +import { isHttpUrl, stripEndpointSuffix } from '../provider/api-v1-url.js'; import { auditResolvedCliConfig, + isBroadTrustedToolPattern, loadCliConfigFile, loadConfigFile, normalizeApprovalPolicyConfig, @@ -420,7 +421,14 @@ export async function runSetupWizard(): Promise { const modelAnswer = rl ? await questionWith(rl, `Model [${defaultModel}]: `) : nextPipedAnswer(); const model = modelAnswer || defaultModel; const baseUrlAnswer = rl ? await questionWith(rl, `Base URL [${defaultBaseUrl}]: `) : nextPipedAnswer(); - const baseUrl = sanitizeBaseUrl(baseUrlAnswer || defaultBaseUrl); + const baseUrlInput = baseUrlAnswer || defaultBaseUrl; + if (!isHttpUrl(baseUrlInput)) { + rl?.close(); + print(`Setup cancelled: base URL must be a full http(s) URL, got: ${baseUrlInput}`); + process.exitCode = 1; + return; + } + const baseUrl = sanitizeBaseUrl(baseUrlInput); const imageInput = current.imageInput ?? preset.defaultImageInput; let apiKey: string; if (input.isTTY) { @@ -657,6 +665,12 @@ export function runConfigSet(args: string[], startDir = process.cwd()): void { } else if (key === 'model') next.model = value; else if (key === 'baseUrl') { + if (!isHttpUrl(value)) { + print(`Invalid baseUrl: ${value.trim()}`); + print('baseUrl must be a full http(s) URL, e.g. https://your-gateway.example/v1'); + process.exitCode = 1; + return; + } const sanitized = sanitizeBaseUrl(value); if (sanitized !== value.trim().replace(/\/+$/, '')) { print(`[config] baseUrl normalized to API root: ${sanitized}`); @@ -692,7 +706,14 @@ export function runConfigSet(args: string[], startDir = process.cwd()): void { next.approvalPolicy = policy; } else if (key === 'trustedTools') { try { - next.trustedTools = parseTrustedTools(value) ?? []; + const parsedTrusted = parseTrustedTools(value) ?? []; + next.trustedTools = parsedTrusted; + const broad = parsedTrusted.filter(isBroadTrustedToolPattern); + if (broad.length > 0) { + print( + `[config] WARNING: broad trusted pattern(s) ${broad.join(', ')} auto-approve every mutating tool the safety mode allows; prefer exact tool names or narrow server__tool globs.`, + ); + } } catch (err) { print(err instanceof Error ? err.message : String(err)); process.exitCode = 1; diff --git a/packages/dmoss-agent/src/cli/tui.ts b/packages/dmoss-agent/src/cli/tui.ts index 7b18007..74857db 100644 --- a/packages/dmoss-agent/src/cli/tui.ts +++ b/packages/dmoss-agent/src/cli/tui.ts @@ -501,6 +501,7 @@ export function formatTuiSessions( const marker = session.sessionKey === currentSessionKey ? '*' : ' '; const count = `${session.messageCount} message${session.messageCount === 1 ? '' : 's'}`; lines.push(` ${marker} ${session.sessionKey} · ${count} · updated ${formatSessionTimestamp(session.updatedAt)}`); + if (session.title) lines.push(` ${session.title}`); } } lines.push(''); @@ -2862,11 +2863,12 @@ function SessionPicker({ state }: { state: SessionPickerState }): React.ReactEle const index = start + offset; const isSelected = index === selected; const count = `${session.messageCount} msg${session.messageCount === 1 ? '' : 's'}`; + const titleSuffix = session.title ? ` — ${truncateTerminalText(session.title, 48)}` : ''; return React.createElement(Text, { key: `${session.sessionKey}-${index}`, color: isSelected ? theme.permission : theme.text, bold: isSelected, - }, `${isSelected ? '› ' : ' '}${String(index + 1).padStart(2, ' ')}. ${session.sessionKey} · ${count} · ${formatSessionTimestamp(session.updatedAt)}`); + }, `${isSelected ? '› ' : ' '}${String(index + 1).padStart(2, ' ')}. ${session.sessionKey} · ${count} · ${formatSessionTimestamp(session.updatedAt)}${titleSuffix}`); }), React.createElement(Text, { color: theme.textDim }, 'Enter resume · Up/Down move · Esc cancel · /resume '), @@ -4912,7 +4914,8 @@ export function DmossTui({ agent, skillLearner, runtime, sessionKey: initialSess ); } -function commandList(customCommands: readonly CommandSpec[] = []): string { +/** In-TUI `/help` command reference. Exported for discoverability tests. @internal */ +export function commandList(customCommands: readonly CommandSpec[] = []): string { const customSection = customCommands.length ? [ '', @@ -4931,6 +4934,7 @@ function commandList(customCommands: readonly CommandSpec[] = []): string { ' /auth login optional: link a D-Robotics developer community account', ' /connect connect an RDK board for this session', ' /sessions list saved conversations you can resume', + ' /resume [key|--last] switch into a saved conversation (no arg opens a picker)', ' /diff show git working-tree changes', '', 'Shortcuts', diff --git a/packages/dmoss-agent/src/context/default-workflow.ts b/packages/dmoss-agent/src/context/default-workflow.ts index d8e95de..514a078 100644 --- a/packages/dmoss-agent/src/context/default-workflow.ts +++ b/packages/dmoss-agent/src/context/default-workflow.ts @@ -18,5 +18,6 @@ export function buildMossDefaultWorkflowPrompt(): string { '- Prefer CodeGraph for structural questions when codegraph_* tools are available: definitions, callers, callees, traces, impact radius, and focused context. Use rg/direct reads for exact text, docs, generated files, or known files.', '- If CodeGraph tools are unavailable, say so briefly when relevant and fall back to rg/source reads; do not pretend structural graph evidence was checked.', '- Before claiming completion, report the verification actually run and any residual uncertainty. Do not call work done because the source looks plausible.', + '- You are ALREADY running inside a terminal/shell session. Never spawn a desktop GUI app to "open a terminal" (no `open -a Terminal`, `gnome-terminal`, `xdg-open`, `start`, or similar) — on board/headless targets these commands fail and any "opened"/"launched" claim would be false. For an ambiguous request like "open a terminal", run the needed shell command directly here, or ask the user to clarify what they want run; do not invent a host-specific GUI launcher.', ].join('\n'); } diff --git a/packages/dmoss-agent/src/context/deterministic-summary.ts b/packages/dmoss-agent/src/context/deterministic-summary.ts index 027b9f2..2e76c55 100644 --- a/packages/dmoss-agent/src/context/deterministic-summary.ts +++ b/packages/dmoss-agent/src/context/deterministic-summary.ts @@ -1,4 +1,7 @@ -import type { Message } from "../core/session/session-jsonl.js"; +import { + COMPACTION_SUMMARY_PREFIX, + type Message, +} from "../core/session/session-jsonl.js"; import { sanitizeSecrets } from "../safety/secret-sanitizer.js"; const DEFAULT_SUMMARY_FALLBACK = "No prior history."; @@ -60,11 +63,35 @@ function fallbackMessageNote(message: Message, index: number): string { return `${label}: ${parts.join("; ")}`; } +function textFromUserMessage(message: Message): string { + if (message.role !== "user") return ""; + if (typeof message.content === "string") { + return message.content; + } + return message.content + .filter((block) => block.type === "text" && Boolean(block.text)) + .map((block) => block.type === "text" ? block.text : "") + .join("\n"); +} + +function extractPrimaryUserGoal(messages: Message[]): string { + for (const message of messages) { + const text = textFromUserMessage(message).trim(); + if (!text) continue; + if (text.trimStart().startsWith(COMPACTION_SUMMARY_PREFIX)) continue; + if (text.includes("> { + const goalSplit = splitGoalCheckpointMessages(run.params.currentMessages as LLMMessage[]); + const cleanMessages = stripTaskFrameCheckpointsFromLlmMessages(goalSplit.messages); + const checkpoint = createTaskFrameCheckpointMessage(run.state.taskFrame); + const goalCheckpoint = goalSplit.goal + ? createGoalCheckpointMessage(goalSplit.goal) + : undefined; + const nextMessages = lastMessageNeedsToolFollowUp(cleanMessages) + ? [ + ...cleanMessages.slice(0, -1), + ...(goalCheckpoint ? [goalCheckpoint] : []), + checkpoint, + cleanMessages[cleanMessages.length - 1], + ] + : [ + ...cleanMessages, + ...(goalCheckpoint ? [goalCheckpoint] : []), + checkpoint, + ]; + // Type bridge: LLMMessage and session Message are the same runtime shape here. + const nextSessionMessages = nextMessages as unknown as typeof run.params.currentMessages; + run.params.currentMessages.splice( + 0, + run.params.currentMessages.length, + ...nextSessionMessages, + ); + await run.params.replaceMessages?.(run.sessionKey, run.params.currentMessages); + return { + type: 'working_context_checkpoint', + status: run.state.taskFrame.status, + reason, + goal: run.state.taskFrame.goal, + nextAction: run.state.taskFrame.nextAction, + }; + } + /** * Event adaptation: maps mini agent events to task-frame updates * and yields adapted DmossAgentEvents. @@ -976,6 +1021,7 @@ export class DmossAgent { summaryChars: miniEvent.summaryChars, droppedMessages: miniEvent.droppedMessages, }); + yield await this.refreshActiveTaskFrameCheckpoint(run, 'compaction'); } else if (miniEvent.type === 'turn_transition') { if (miniEvent.reason === 'aborted_by_user') { state.taskFrame = recordTaskFrameStop(state.taskFrame, { reason: 'abort' }); diff --git a/packages/dmoss-agent/src/core/goal/task-frame.ts b/packages/dmoss-agent/src/core/goal/task-frame.ts index 6163e65..dfc3f8f 100644 --- a/packages/dmoss-agent/src/core/goal/task-frame.ts +++ b/packages/dmoss-agent/src/core/goal/task-frame.ts @@ -373,6 +373,16 @@ export function recordTaskFrameToolEnd( } uniquePush(next.completedSteps, `Ran ${params.toolName}`); + // A successful tool call means the agent is making forward progress, so any + // earlier tool-error recovery markers are no longer blocking work. Without + // this, a worked-around error (e.g. write_file fails → the agent retries via + // exec and finishes) leaves its "Resolve …error" marker in pendingSteps + // forever — `unresolvedPendingSteps` never string-matches it — which latches + // an otherwise-completed run into `paused_resumable` at end_turn (and wrongly + // suppresses skill learning, which gates on status === 'completed'). + next.pendingSteps = next.pendingSteps.filter( + (step) => !/^resolve or work around the latest .* error/i.test(step), + ); next.currentStep = `Processed ${params.toolName} result`; next.nextAction = `Use the latest ${params.toolName} result to continue.`; next.status = 'active'; @@ -392,27 +402,13 @@ export function recordTaskFrameCompaction( return next; } -/** - * Plan closure discipline: - * Before marking a task as completed, reconcile all pending steps. - * Each unfinished step is either promoted to completed (if the assistant - * response covers it) or explicitly marked as deferred. - */ -function reconcilePendingSteps(frame: TaskFrame): TaskFrame { - if (frame.pendingSteps.length === 0) return frame; - const next = { - ...frame, - completedSteps: [...frame.completedSteps], - pendingSteps: [] as string[], - }; - for (const step of frame.pendingSteps) { - const alreadyDone = next.completedSteps.some( - (cs) => cs.toLowerCase().includes(step.toLowerCase().slice(0, 40)), +function unresolvedPendingSteps(frame: TaskFrame): string[] { + return frame.pendingSteps.filter((step) => { + const needle = step.toLowerCase().slice(0, 40); + return !frame.completedSteps.some((completed) => + completed.toLowerCase().includes(needle), ); - if (alreadyDone) continue; - uniquePush(next.completedSteps, `Deferred: ${step}`); - } - return next; + }); } export function recordTaskFrameAssistant( @@ -429,11 +425,18 @@ export function recordTaskFrameAssistant( next.nextAction = next.nextAction || 'Continue from the latest resumable checkpoint.'; } else { - const reconciled = reconcilePendingSteps(next); - reconciled.status = 'completed'; - reconciled.currentStep = 'Task response completed'; - reconciled.nextAction = 'No automatic continuation is required unless the user asks for a follow-up.'; - return reconciled; + const unresolved = unresolvedPendingSteps(next); + if (unresolved.length > 0) { + next.status = 'paused_resumable'; + next.pendingSteps = unresolved; + next.currentStep = 'Assistant response recorded; pending work remains'; + next.nextAction = unresolved[0] ?? 'Continue with the pending task steps.'; + return next; + } + next.status = 'completed'; + next.currentStep = 'Task response completed'; + next.nextAction = 'No automatic continuation is required unless the user asks for a follow-up.'; + return next; } } return next; diff --git a/packages/dmoss-agent/src/core/loop/agent-loop-compaction.ts b/packages/dmoss-agent/src/core/loop/agent-loop-compaction.ts index b0b2691..bb85b2e 100644 --- a/packages/dmoss-agent/src/core/loop/agent-loop-compaction.ts +++ b/packages/dmoss-agent/src/core/loop/agent-loop-compaction.ts @@ -113,13 +113,6 @@ async function runCompactionCore( return { attempted: true, succeeded: false, retrySameTurn: false }; } - push({ - type: 'compaction', - summaryChars: prep.summary.length, - droppedMessages: droppedFromPrep, - ...(checkpointOutline ? { checkpointOutline } : {}), - }); - let compactionSummary: Message | undefined = prep.summaryMessage; // If aborted after prepareCompaction returned, do NOT mutate currentMessages. @@ -133,6 +126,13 @@ async function runCompactionCore( compactionSummary = undefined; } + push({ + type: 'compaction', + summaryChars: prep.summary.length, + droppedMessages: droppedFromPrep, + ...(checkpointOutline ? { checkpointOutline } : {}), + }); + const stats = computeStats({ summary: prep.summary, summaryMessage: prep.summaryMessage, diff --git a/packages/dmoss-agent/src/core/loop/agent-loop-response.ts b/packages/dmoss-agent/src/core/loop/agent-loop-response.ts index d03c70b..6cc9340 100644 --- a/packages/dmoss-agent/src/core/loop/agent-loop-response.ts +++ b/packages/dmoss-agent/src/core/loop/agent-loop-response.ts @@ -14,6 +14,7 @@ import type { ToolHookRegistry } from '../tools/tool-hooks.js'; import type { AgentLoopMutableState } from './agent-loop-state.js'; import type { ToolLoopGuardState } from '../tools/tool-loop-guard.js'; import type { LoopControlSignal } from './agent-loop-context-prep.js'; +import type { AgentLoopExtensions } from './agent-loop-types.js'; import { injectToolCallFromPlanText, normalizeAssistantToolCalls, @@ -31,6 +32,7 @@ import { } from './agent-loop-tool-execution.js'; const GUARDED_DELTA_CHUNK = 96; +const MAX_COMPLETION_GATE_ATTEMPTS = 2; function pushGuardedMessageDeltas(push: (event: MiniAgentEvent) => void, text: string): void { if (!text) return; @@ -100,6 +102,8 @@ export interface ProcessLlmResponseParams { | { approved: true; response?: string } | { approved: false; reason: string; response?: string } >; + completionGate?: AgentLoopExtensions['completionGate']; + delayedVisibleDeltas?: boolean; toolAbortSignalFor?: (toolCallId: string) => AbortSignal | undefined; enrichToolContext?: (baseCtx: ToolContext, sessionKey: string) => ToolContext; evaluateSteering: () => Message[]; @@ -160,6 +164,8 @@ export async function processLlmResponse( maxToolCalls, checkToolApproval, guardAssistantOutput, + completionGate, + delayedVisibleDeltas, toolAbortSignalFor, enrichToolContext, evaluateSteering, @@ -285,10 +291,6 @@ export async function processLlmResponse( } replaceAssistantVisibleText(assistantContent, visibleAssistantText); } - if (guardAssistantOutput && !hasThinkingOnly) { - pushGuardedMessageDeltas(push, visibleAssistantText); - } - push({ type: 'message_end', message: assistantMsg, text: visibleAssistantText }); // ===== Update state ===== state.hasMoreToolCalls = toolCalls.length > 0; @@ -296,6 +298,47 @@ export async function processLlmResponse( state.finalText = visibleAssistantText; } + if (completionGate && !state.hasMoreToolCalls && state.finalText.trim().length > 0 && !abortSignal.aborted) { + const decision = await completionGate({ + sessionKey, + runId, + turn: state.turns, + response: state.finalText, + ...(streamStopReason ? { stopReason: streamStopReason } : {}), + messages: currentMessages, + totalToolCalls: state.toolExecutionMetrics.totalToolCalls, + toolCallsByName: state.toolExecutionMetrics.toolCallsByName, + }); + if (!decision.ok && state.completionGateAttempts < MAX_COMPLETION_GATE_ATTEMPTS) { + state.completionGateAttempts += 1; + state.finalText = ''; + const bufferedIndex = assistantBuffer.lastIndexOf(assistantMsg); + if (bufferedIndex >= 0) assistantBuffer.splice(bufferedIndex, 1); + state.pendingMessages = [buildCorrectionMessage( + decision.correction ?? + `[System] Completion rejected: ${decision.reason}. Continue the task and only finish when the required evidence is available.`, + )]; + pushTurnEnd(); + state.lastTurnEndMs = Date.now(); + return { control: 'continue' }; + } + if (decision.ok) { + state.completionGateAttempts = 0; + } else { + visibleAssistantText = + decision.fallbackResponse ?? + `I could not verify completion after retrying: ${decision.reason}. I cannot mark this task complete without the required evidence.`; + replaceAssistantVisibleText(assistantContent, visibleAssistantText); + state.finalText = visibleAssistantText; + state.completionGateAttempts = 0; + } + } + + if (delayedVisibleDeltas && !hasThinkingOnly) { + pushGuardedMessageDeltas(push, visibleAssistantText); + } + push({ type: 'message_end', message: assistantMsg, text: visibleAssistantText }); + // ===== Nudge predicate ===== const toolsForNudge = resolveToolsForRun(); const namedWebToolRe = buildNamedWebToolMatcher(toolsForNudge.map((x) => x.name)); diff --git a/packages/dmoss-agent/src/core/loop/agent-loop-state.ts b/packages/dmoss-agent/src/core/loop/agent-loop-state.ts index 3eff5d1..9cd25fe 100644 --- a/packages/dmoss-agent/src/core/loop/agent-loop-state.ts +++ b/packages/dmoss-agent/src/core/loop/agent-loop-state.ts @@ -15,6 +15,7 @@ export interface AgentLoopMutableState { outputContinuationCount: number; planToolNudgeAttempts: number; postToolThinkingOnlyRetryAttempts: number; + completionGateAttempts: number; postLimitToolFollowUpsUsed: number; proactiveCompactionAttempted: boolean; promptPruneCompactionAttempted: boolean; @@ -38,6 +39,7 @@ export function createInitialLoopState(): AgentLoopMutableState { outputContinuationCount: 0, planToolNudgeAttempts: 0, postToolThinkingOnlyRetryAttempts: 0, + completionGateAttempts: 0, postLimitToolFollowUpsUsed: 0, proactiveCompactionAttempted: false, promptPruneCompactionAttempted: false, diff --git a/packages/dmoss-agent/src/core/loop/agent-loop-types.ts b/packages/dmoss-agent/src/core/loop/agent-loop-types.ts index 614923b..f582fd5 100644 --- a/packages/dmoss-agent/src/core/loop/agent-loop-types.ts +++ b/packages/dmoss-agent/src/core/loop/agent-loop-types.ts @@ -97,6 +97,19 @@ export interface AgentLoopExtensions { >; compactHooks?: CompactHookRegistry; steeringEngine?: SteeringEngine; + completionGate?: (request: { + sessionKey: string; + runId: string; + turn: number; + response: string; + stopReason?: string; + messages: Message[]; + totalToolCalls: number; + toolCallsByName: Record; + }) => Promise< + | { ok: true } + | { ok: false; reason: string; correction?: string; fallbackResponse?: string } + >; } export interface AgentLoopDeps { diff --git a/packages/dmoss-agent/src/core/loop/agent-loop.ts b/packages/dmoss-agent/src/core/loop/agent-loop.ts index dbc5bb2..5e995af 100644 --- a/packages/dmoss-agent/src/core/loop/agent-loop.ts +++ b/packages/dmoss-agent/src/core/loop/agent-loop.ts @@ -419,7 +419,7 @@ export function runAgentLoop( compactHooks, recordLlmUsage, lastMessageNeedsToolFollowUpLlm, - suppressVisibleDeltas: Boolean(params.guardAssistantOutput), + suppressVisibleDeltas: Boolean(params.guardAssistantOutput || params.completionGate), }); if (llmResult.control === 'retry') { @@ -458,6 +458,8 @@ export function runAgentLoop( maxToolCalls, checkToolApproval: params.checkToolApproval, guardAssistantOutput: params.guardAssistantOutput, + completionGate: params.completionGate, + delayedVisibleDeltas: Boolean(params.guardAssistantOutput || params.completionGate), toolAbortSignalFor: params.toolAbortSignalFor, enrichToolContext: params.enrichToolContext, evaluateSteering, diff --git a/packages/dmoss-agent/src/core/loop/context-budget-planner.ts b/packages/dmoss-agent/src/core/loop/context-budget-planner.ts index 96e3db4..a7be32b 100644 --- a/packages/dmoss-agent/src/core/loop/context-budget-planner.ts +++ b/packages/dmoss-agent/src/core/loop/context-budget-planner.ts @@ -102,16 +102,16 @@ export function planContextBudgetActions( }); } - actions.push({ - kind: 'microcompact', - reason: pressureReason, - microcompactConfig: - pressureReason === 'proactive_threshold' - ? { keepRecentResults: 2, minContentLength: 50 } - : pressureReason === 'warning_threshold' - ? { keepRecentResults: 4, minContentLength: 100 } - : {}, - }); + if (pressureReason === 'warning_threshold' || pressureReason === 'proactive_threshold') { + actions.push({ + kind: 'microcompact', + reason: pressureReason, + microcompactConfig: + pressureReason === 'proactive_threshold' + ? { keepRecentResults: 2, minContentLength: 50 } + : { keepRecentResults: 4, minContentLength: 100 }, + }); + } return { actions, diff --git a/packages/dmoss-agent/src/core/session/jsonl-session-store.ts b/packages/dmoss-agent/src/core/session/jsonl-session-store.ts index 958e67d..7b43e23 100644 --- a/packages/dmoss-agent/src/core/session/jsonl-session-store.ts +++ b/packages/dmoss-agent/src/core/session/jsonl-session-store.ts @@ -20,6 +20,16 @@ import type { SessionStore, SessionMeta } from './session.js'; export interface JsonlSessionStoreConfig { dir: string; + /** + * Optional cap on the number of session files kept on disk. When set to a + * positive integer, creating a brand-new session prunes the oldest sessions + * (by `updatedAt`) until at most `maxSessions` remain; the session being + * written is never a prune candidate. Omitted / `<= 0` means unbounded + * (the default — session retention is a host policy, so moss never deletes + * user history unless the host opts in). + * @beta + */ + maxSessions?: number; } type JsonlSessionEntry = @@ -30,9 +40,14 @@ export class JsonlSessionStore implements SessionStore { private static readonly writeChains = new Map>(); private readonly dir: string; + private readonly maxSessions: number; constructor(config: JsonlSessionStoreConfig) { this.dir = path.resolve(config.dir); + this.maxSessions = + typeof config.maxSessions === 'number' && Number.isFinite(config.maxSessions) && config.maxSessions > 0 + ? Math.floor(config.maxSessions) + : 0; } private encodedSessionStem(sessionKey: string): string { @@ -80,6 +95,27 @@ export class JsonlSessionStore implements SessionStore { } } + /** + * Human-readable session title derived from the first user message, so the + * session pickers can show "Deploy the YOLO model…" instead of a bare + * `cli-20260613-…` key. Returns undefined when no user message exists yet + * (never fabricates a title). Whitespace-collapsed and length-capped. + */ + private deriveTitle(messages: LLMMessage[]): string | undefined { + for (const message of messages) { + if (message.role !== 'user') continue; + const text = + typeof message.content === 'string' + ? message.content + : message.content + .map((block) => (block.type === 'text' ? block.text : '')) + .join(' '); + const cleaned = text.replace(/\s+/g, ' ').trim(); + if (cleaned) return cleaned.length > 80 ? `${cleaned.slice(0, 79)}…` : cleaned; + } + return undefined; + } + private replayMessagesFromContent(raw: string): { messages: LLMMessage[]; malformedCount: number } { const lines = raw.split('\n').filter((l) => l.trim()); const messages: LLMMessage[] = []; @@ -117,10 +153,13 @@ export class JsonlSessionStore implements SessionStore { async appendMessage(sessionKey: string, message: LLMMessage): Promise { const filePath = this.sessionPath(sessionKey); const entry = JSON.stringify({ type: 'message', message, ts: Date.now() }); + let isNewSession = false; await this.enqueueWrite(filePath, async () => { await this.ensureDir(); + isNewSession = this.maxSessions > 0 && !(await this.fileExists(filePath)); await this.appendLineDurably(filePath, entry + '\n'); }); + if (isNewSession) await this.pruneOldestSessions(sessionKey); } async replaceMessages(sessionKey: string, messages: LLMMessage[]): Promise { @@ -130,10 +169,45 @@ export class JsonlSessionStore implements SessionStore { messages, ts: Date.now(), }); + let isNewSession = false; await this.enqueueWrite(filePath, async () => { await this.ensureDir(); + isNewSession = this.maxSessions > 0 && !(await this.fileExists(filePath)); await this.appendLineDurably(filePath, entry + '\n'); }); + if (isNewSession) await this.pruneOldestSessions(sessionKey); + } + + private async fileExists(filePath: string): Promise { + try { + await fsp.access(filePath); + return true; + } catch { + return false; + } + } + + /** + * Opt-in retention: when `maxSessions` is set, delete the oldest sessions + * (by `updatedAt`) so at most `maxSessions` remain. The session just written + * (`keepSessionKey`) is always retained. Best-effort: a prune failure never + * fails the originating append. + */ + private async pruneOldestSessions(keepSessionKey: string): Promise { + if (this.maxSessions <= 0) return; + try { + const sessions = await this.listSessions(); + if (sessions.length <= this.maxSessions) return; + const removable = sessions + .filter((s) => s.sessionKey !== keepSessionKey) + .sort((a, b) => a.updatedAt - b.updatedAt); + const removeCount = sessions.length - this.maxSessions; + for (const session of removable.slice(0, removeCount)) { + await this.deleteSession(session.sessionKey); + } + } catch { + // Retention is best-effort; never let pruning surface as a write error. + } } async listSessions(): Promise { @@ -147,12 +221,14 @@ export class JsonlSessionStore implements SessionStore { try { const stat = await fsp.stat(filePath); const content = await fsp.readFile(filePath, 'utf-8'); - const activeMessageCount = this.replayMessagesFromContent(content).messages.length; + const activeMessages = this.replayMessagesFromContent(content).messages; + const title = this.deriveTitle(activeMessages); sessions.push({ sessionKey, createdAt: stat.birthtimeMs, updatedAt: stat.mtimeMs, - messageCount: activeMessageCount, + messageCount: activeMessages.length, + ...(title ? { title } : {}), }); } catch { // skip inaccessible files diff --git a/packages/dmoss-agent/src/core/tools/tool-loop-guard.ts b/packages/dmoss-agent/src/core/tools/tool-loop-guard.ts index f2df712..cd93748 100644 --- a/packages/dmoss-agent/src/core/tools/tool-loop-guard.ts +++ b/packages/dmoss-agent/src/core/tools/tool-loop-guard.ts @@ -20,6 +20,9 @@ const SINGLE_TOOL_LIMIT_EXEMPT_TOOLS = new Set([ 'device_file_list', ]); +const DEFAULT_IDENTICAL_TOOL_INPUT_LIMIT = 3; +const DEFAULT_TOOL_FAILURE_LIMIT = 3; + export type ToolLoopGuardState = { bySignature: Map; byTool: Map; @@ -27,11 +30,15 @@ export type ToolLoopGuardState = { total: number; }; -function resolveOptionalPositiveIntEnv(name: string): number | undefined { +function resolveOptionalPositiveIntEnv(name: string, fallback?: number): number | undefined { const raw = readEnv(name); - if (!raw) return undefined; + if (!raw) return fallback; + const normalized = raw.trim().toLowerCase(); + if (normalized === '0' || normalized === 'off' || normalized === 'false' || normalized === 'disabled') { + return undefined; + } const value = Number.parseInt(raw, 10); - return Number.isFinite(value) && value > 0 ? value : undefined; + return Number.isFinite(value) && value > 0 ? value : fallback; } export function createToolLoopGuardState(): ToolLoopGuardState { @@ -97,10 +104,16 @@ export function shouldShortCircuitToolCall( toolName: string, input: Record, ): string | null { - const identicalLimit = resolveOptionalPositiveIntEnv('DMOSS_TOOL_LOOP_IDENTICAL_LIMIT'); + const identicalLimit = resolveOptionalPositiveIntEnv( + 'DMOSS_TOOL_LOOP_IDENTICAL_LIMIT', + DEFAULT_IDENTICAL_TOOL_INPUT_LIMIT, + ); const singleToolLimit = resolveOptionalPositiveIntEnv('DMOSS_TOOL_LOOP_SINGLE_TOOL_LIMIT'); const totalLimit = resolveOptionalPositiveIntEnv('DMOSS_TOOL_LOOP_TOTAL_LIMIT'); - const failureLimit = resolveOptionalPositiveIntEnv('DMOSS_TOOL_LOOP_FAILURE_LIMIT'); + const failureLimit = resolveOptionalPositiveIntEnv( + 'DMOSS_TOOL_LOOP_FAILURE_LIMIT', + DEFAULT_TOOL_FAILURE_LIMIT, + ); const signature = `${toolName}:${stableSerializeToolInput(input)}`; const sameSignatureCount = state.bySignature.get(signature) ?? 0; const sameToolCount = state.byTool.get(toolName) ?? 0; diff --git a/packages/dmoss-agent/src/provider/api-v1-url.ts b/packages/dmoss-agent/src/provider/api-v1-url.ts index c570add..771ddf4 100644 --- a/packages/dmoss-agent/src/provider/api-v1-url.ts +++ b/packages/dmoss-agent/src/provider/api-v1-url.ts @@ -16,6 +16,23 @@ export function stripEndpointSuffix(value: string): string { .replace(/\/v1$/i, ''); } +/** + * True only for a syntactically valid absolute http(s) URL. Used at config + * SET time so a malformed or non-http(s) baseUrl (typo'd scheme, bare host, + * ftp://...) is rejected up front instead of failing opaquely at the first + * model call. + * + * @public + */ +export function isHttpUrl(value: string): boolean { + try { + const url = new URL(value.trim()); + return url.protocol === 'http:' || url.protocol === 'https:'; + } catch { + return false; + } +} + export function buildApiV1Url(baseUrl: string, path: string): string { const normalizedBaseUrl = stripEndpointSuffix(baseUrl.trim()); const normalizedPath = path.trim().replace(/^\/+/, ''); diff --git a/packages/dmoss-agent/src/provider/pi-ai-adapter.ts b/packages/dmoss-agent/src/provider/pi-ai-adapter.ts index 6265516..395a736 100644 --- a/packages/dmoss-agent/src/provider/pi-ai-adapter.ts +++ b/packages/dmoss-agent/src/provider/pi-ai-adapter.ts @@ -193,7 +193,7 @@ export class PiAiLLMProvider implements LLMProvider { */ const thinkingChunks: string[] = []; let stopReason: LLMResponse['stopReason'] = 'end_turn'; - let usage = { inputTokens: 0, outputTokens: 0 }; + let usage: NonNullable = { inputTokens: 0, outputTokens: 0 }; const requestThinkingMode = hasThinkingModeConfigured( this.model, @@ -258,7 +258,7 @@ export class PiAiLLMProvider implements LLMProvider { const content: LLMContentBlock[] = []; const thinkingChunks: string[] = []; let stopReason: LLMResponse['stopReason'] = 'end_turn'; - let usage = { inputTokens: 0, outputTokens: 0 }; + let usage: NonNullable = { inputTokens: 0, outputTokens: 0 }; let incomplete: LLMResponse['incomplete'] | undefined; const requestThinkingMode = hasThinkingModeConfigured( diff --git a/packages/dmoss-agent/src/provider/pi-ai-stream-parser.ts b/packages/dmoss-agent/src/provider/pi-ai-stream-parser.ts index facd168..dc0f435 100644 --- a/packages/dmoss-agent/src/provider/pi-ai-stream-parser.ts +++ b/packages/dmoss-agent/src/provider/pi-ai-stream-parser.ts @@ -28,6 +28,37 @@ import { const log = getRootLogger().child('provider:pi-ai'); +/** + * Map a pi-ai usage payload to the D-Moss usage shape, preserving prompt-cache + * token counts when the gateway reports them. pi-ai's own cost model uses + * `cacheRead`/`cacheWrite` (see PiAiModelCost); some OpenAI-compatible gateways + * surface `cacheReadTokens`/`cacheCreationTokens` instead. Read both so cache + * metrics are observable on the pi-ai path (the native Anthropic provider already + * reports them). Without this, `cache_metrics` is always 0 on the pi-ai path and + * prompt-cache effectiveness cannot be verified. + */ +function mapPiUsage( + evtUsage: { input?: number; output?: number } | undefined, +): { inputTokens: number; outputTokens: number; cacheReadTokens?: number; cacheCreationTokens?: number } | undefined { + if (!evtUsage) return undefined; + const raw = evtUsage as Record; + const num = (...keys: string[]): number | undefined => { + for (const k of keys) { + const v = raw[k]; + if (typeof v === 'number' && Number.isFinite(v)) return v; + } + return undefined; + }; + const cacheReadTokens = num('cacheRead', 'cacheReadTokens', 'cache_read_input_tokens'); + const cacheCreationTokens = num('cacheWrite', 'cacheCreationTokens', 'cache_creation_input_tokens'); + return { + inputTokens: evtUsage.input ?? 0, + outputTokens: evtUsage.output ?? 0, + ...(cacheReadTokens !== undefined ? { cacheReadTokens } : {}), + ...(cacheCreationTokens !== undefined ? { cacheCreationTokens } : {}), + }; +} + class PiAiProviderRuntimeError extends Error { readonly surface: import('./error-classify.js').ProviderErrorSurface; @@ -50,7 +81,7 @@ export function processEvent( thinkingChunks?: string[], ): { stopReason?: LLMResponse['stopReason']; - usage?: { inputTokens: number; outputTokens: number }; + usage?: NonNullable; } { const t = event.type; @@ -151,9 +182,7 @@ export function processEvent( return { stopReason: stopReasonOut, - usage: evtUsage - ? { inputTokens: evtUsage.input ?? 0, outputTokens: evtUsage.output ?? 0 } - : undefined, + usage: mapPiUsage(evtUsage), }; } else if ( t === 'start' || @@ -254,9 +283,7 @@ export function processEvent( if (hasToolUseAfterErr) { return { stopReason: 'tool_use', - usage: errUsage - ? { inputTokens: errUsage.input ?? 0, outputTokens: errUsage.output ?? 0 } - : undefined, + usage: mapPiUsage(errUsage), }; } if (errUsage) { @@ -265,7 +292,7 @@ export function processEvent( errPayload?.stopReason === 'toolCall' || errPayload?.stopReason === 'toolUse' ? 'tool_use' : 'end_turn', - usage: { inputTokens: errUsage.input ?? 0, outputTokens: errUsage.output ?? 0 }, + usage: mapPiUsage(errUsage), }; } } diff --git a/packages/dmoss-agent/src/tools/device-ros2.ts b/packages/dmoss-agent/src/tools/device-ros2.ts index 95c1265..590e4d5 100644 --- a/packages/dmoss-agent/src/tools/device-ros2.ts +++ b/packages/dmoss-agent/src/tools/device-ros2.ts @@ -13,6 +13,17 @@ import { buildSshCommand, runSsh, sshBinFor, shellEscape, sshFailureToError } fr const ROS_SETUP = 'source /opt/tros/humble/setup.bash 2>/dev/null || source /opt/ros/humble/setup.bash 2>/dev/null || true'; +/** + * Clamp a user-supplied sampling window (seconds) for topic echo/hz. Defaults + * to 5s (the historical window) and is bounded so a typo can't pin an SSH + * session open. Exported for tests. @internal + */ +export function clampSampleSeconds(value: unknown): number { + const n = Math.floor(Number(value)); + if (!Number.isFinite(n) || n < 1) return 5; + return Math.min(n, 60); +} + /** @internal */ export const ROS2_LAUNCH_OK_MARKER = '__MOSS_ROS2_LAUNCH_OK__'; /** @internal */ @@ -45,13 +56,24 @@ export function interpretRos2LaunchOutput(output: string, pkg: string, launchFil ); } +/** + * Prefix that pins the ROS2 DDS domain when the device config specifies one. + * Without it, a robot on a non-default ROS_DOMAIN_ID silently returns empty + * topic/node/service lists. Exported for tests. @internal + */ +export function ros2DomainPrefix(config: DeviceSshConfig): string { + return typeof config.rosDomainId === 'number' && Number.isInteger(config.rosDomainId) + ? `export ROS_DOMAIN_ID=${config.rosDomainId}; ` + : ''; +} + async function sshExec( config: DeviceSshConfig, cmd: string, timeout = 15_000, ctx?: ToolContext, ): Promise { - const remoteCmd = `${ROS_SETUP} && ${cmd}`; + const remoteCmd = `${ros2DomainPrefix(config)}${ROS_SETUP} && ${cmd}`; const sshArgs = buildSshCommand(config, remoteCmd, 5); try { @@ -93,11 +115,13 @@ export function createRos2Tools(config: DeviceSshConfig): Tool[] { type: 'object', properties: { topic: { type: 'string', description: 'Topic name (e.g. /camera/image_raw)' }, + timeout_sec: { type: 'number', description: 'Seconds to wait for a message (default 5, max 60). Raise it for low-rate topics.' }, }, required: ['topic'], }, async execute(input, ctx) { - return sshExec(config, `timeout 5 ros2 topic echo ${shellEscape(input.topic)} --once 2>&1 || echo "(no message within 5s)"`, 10_000, ctx); + const window = clampSampleSeconds(input.timeout_sec); + return sshExec(config, `timeout ${window} ros2 topic echo ${shellEscape(input.topic)} --once 2>&1 || echo "(no message within ${window}s)"`, (window + 5) * 1000, ctx); }, }; @@ -109,11 +133,13 @@ export function createRos2Tools(config: DeviceSshConfig): Tool[] { type: 'object', properties: { topic: { type: 'string', description: 'Topic name' }, + timeout_sec: { type: 'number', description: 'Seconds to sample the rate (default 5, max 60). Raise it for low-rate topics.' }, }, required: ['topic'], }, async execute(input, ctx) { - return sshExec(config, `timeout 5 ros2 topic hz ${shellEscape(input.topic)} 2>&1 | tail -5`, 10_000, ctx); + const window = clampSampleSeconds(input.timeout_sec); + return sshExec(config, `timeout ${window} ros2 topic hz ${shellEscape(input.topic)} 2>&1 | tail -5`, (window + 5) * 1000, ctx); }, }; diff --git a/packages/dmoss-agent/src/tools/device-ssh.ts b/packages/dmoss-agent/src/tools/device-ssh.ts index 286748b..cf27164 100644 --- a/packages/dmoss-agent/src/tools/device-ssh.ts +++ b/packages/dmoss-agent/src/tools/device-ssh.ts @@ -24,6 +24,13 @@ export interface DeviceSshConfig { password?: string; port?: number; keyPath?: string; + /** + * DDS domain the robot's ROS2 graph lives on. When set, the ros2_* tools + * export ROS_DOMAIN_ID before each command — without it, a robot on a + * non-default domain silently returns empty topic/node/service lists. + * @beta + */ + rosDomainId?: number; } async function sshRun( @@ -166,6 +173,12 @@ export function createDeviceSshTools(config: DeviceSshConfig): Tool[] { try { return await sshRun(config, input.command, timeout, ctx); } catch (err) { + if (err instanceof ProcessError && err.timedOut) { + throw new Error( + `Device command timed out after ${Math.round(timeout / 1000)}s. ` + + `Raise the limit with timeout_ms (e.g. timeout_ms: ${timeout * 4}) for long commands like colcon build or apt install.`, + ); + } if (err instanceof ProcessError) { const output = [err.stdout, err.stderr].filter(Boolean).join('\n').trim(); throw new Error(`Device command failed (exit ${err.exitCode}):\n${output || err.message}`); @@ -280,11 +293,14 @@ export function getDeviceConfigFromEnv(): DeviceSshConfig | null { const host = process.env.DMOSS_DEVICE_HOST; if (!host) return null; + const rawDomain = process.env.DMOSS_ROS_DOMAIN_ID; + const parsedDomain = rawDomain !== undefined ? Number.parseInt(rawDomain, 10) : NaN; return { host, user: process.env.DMOSS_DEVICE_USER || 'root', password: process.env.DMOSS_DEVICE_PASSWORD, port: parseInt(process.env.DMOSS_DEVICE_PORT || '22', 10), keyPath: process.env.DMOSS_DEVICE_KEY, + ...(Number.isInteger(parsedDomain) && parsedDomain >= 0 ? { rosDomainId: parsedDomain } : {}), }; } diff --git a/packages/dmoss-agent/src/tools/device-workspace.ts b/packages/dmoss-agent/src/tools/device-workspace.ts index db1ee24..41b0bc9 100644 --- a/packages/dmoss-agent/src/tools/device-workspace.ts +++ b/packages/dmoss-agent/src/tools/device-workspace.ts @@ -84,6 +84,12 @@ async function boardRun( }); return { stdout: result.stdout, stderr: result.stderr, exitCode: 0 }; } catch (err) { + if (err instanceof ProcessError && err.timedOut) { + throw new Error( + `Board command timed out after ${Math.round(opts.timeout / 1000)}s. ` + + `Raise the limit with timeout_ms (e.g. timeout_ms: ${opts.timeout * 4}) for long commands like colcon build or apt install.`, + ); + } if (err instanceof ProcessError && opts.allowNonZeroExit && !isTransportFailure(config, err)) { return { stdout: err.stdout, stderr: err.stderr, exitCode: err.exitCode }; } diff --git a/packages/dmoss-agent/src/utils/run-process.ts b/packages/dmoss-agent/src/utils/run-process.ts index 590d229..d74821f 100644 --- a/packages/dmoss-agent/src/utils/run-process.ts +++ b/packages/dmoss-agent/src/utils/run-process.ts @@ -28,13 +28,16 @@ export class ProcessError extends Error { readonly exitCode: number; readonly stdout: string; readonly stderr: string; + /** True when the child was killed because its timeout elapsed (not an abort). */ + readonly timedOut: boolean; - constructor(exitCode: number, stdout: string, stderr: string) { + constructor(exitCode: number, stdout: string, stderr: string, timedOut = false) { super(`Process exited with code ${exitCode}`); this.name = 'ProcessError'; this.exitCode = exitCode; this.stdout = stdout; this.stderr = stderr; + this.timedOut = timedOut; } } @@ -58,6 +61,7 @@ export function runProcess(cmd: string, opts: RunProcessOptions): Promise | undefined; const kill = (signal: NodeJS.Signals = 'SIGKILL') => { @@ -81,7 +85,10 @@ export function runProcess(cmd: string, opts: RunProcessOptions): Promise 0) { - timeoutId = setTimeout(() => kill(), opts.timeout); + timeoutId = setTimeout(() => { + timedOut = true; + kill(); + }, opts.timeout); } const onAbort = () => kill(); @@ -115,7 +122,7 @@ export function runProcess(cmd: string, opts: RunProcessOptions): Promise { + promptCount++; + return 'a'; + }); + try { + const approve = createCliToolApprovalHook('workspace-write', {}); + await approve({ + tool: tool('some_local_tool', 'memory_write'), + input: { text: 'x' }, + sessionKey: 's', + }); + const second = await approve({ + tool: tool('some_local_tool', 'memory_write'), + input: { text: 'y' }, + sessionKey: 's', + }); + assert.deepEqual(second, { approved: true }); + assert.equal(promptCount, 1, 'session-trust-eligible tools keep their session-wide "always" trust'); + } finally { + setCliApprovalAsker(null); + Object.defineProperty(process.stdin, 'isTTY', { value: oldIsTty, configurable: true }); + } +} + +// --- prompt for a device mutation does not advertise an "always" option ------- +{ + const preview = describeCliToolApproval( + { tool: tool('device_exec', 'device_mutation'), input: { command: 'reboot' }, sessionKey: 's' }, + 'full-access', + ); + const prompt = renderCliApprovalPrompt(preview, { command: 'reboot' }); + assert.match(prompt, /device mutations always re-prompt/); + assert.doesNotMatch(prompt, /allow this scope for the session/); +} + +console.log('[PASS] device mutations are not blanket-trusted by "Always"'); +// --- headless (-p / no TTY) auto-approval of a mutating tool is audited ------ +{ + const oldIsTty = process.stdin.isTTY; + Object.defineProperty(process.stdin, 'isTTY', { value: false, configurable: true }); + const origWrite = process.stderr.write.bind(process.stderr); + let captured = ''; + process.stderr.write = (chunk, ...rest) => { + captured += typeof chunk === 'string' ? chunk : chunk.toString(); + return origWrite(chunk, ...rest); + }; + try { + const approve = createCliToolApprovalHook('workspace-write', {}); + const result = await approve({ + tool: tool('write_file', 'local_write'), + input: { path: 'a.txt', content: 'x' }, + sessionKey: 's', + }); + assert.deepEqual(result, { approved: true }, 'headless -p stays usable: mutating tool still auto-approved'); + assert.match( + captured, + /\[approval\] headless auto-approve: write_file \(local_write\) under workspace-write/, + 'headless auto-approval of a mutating tool must leave an audit line', + ); + } finally { + process.stderr.write = origWrite; + Object.defineProperty(process.stdin, 'isTTY', { value: oldIsTty, configurable: true }); + } +} + +console.log('[PASS] headless mutating auto-approvals are audited'); + diff --git a/packages/dmoss-agent/test/cli-args.spec.mjs b/packages/dmoss-agent/test/cli-args.spec.mjs index a7f6a13..c9a40c3 100644 --- a/packages/dmoss-agent/test/cli-args.spec.mjs +++ b/packages/dmoss-agent/test/cli-args.spec.mjs @@ -143,4 +143,66 @@ assert.throws(() => parseCliArgs(['-c', 'maxTurns=0']), /Unsupported maxAgentTur assert.throws(() => parseCliArgs(['-c', 'contextTokens=1.5']), /Unsupported contextTokens/); assert.throws(() => parseCliArgs(['--max-turns', '0', 'hello']), /--max-turns/); +// --ask-for-approval must reject unknown values instead of silently ignoring +// them (a typo like `--ask-for-approval yolo` used to look accepted while +// changing nothing). +assert.throws(() => parseCliArgs(['--ask-for-approval', 'yolo', 'hi']), /--ask-for-approval must be/); +assert.throws(() => parseCliArgs(['--ask-for-approval=bogus', 'hi']), /--ask-for-approval must be/); +{ + // Every documented value is still accepted with its existing effect. + assert.equal(parseCliArgs(['--ask-for-approval', 'never', 'hi']).approvalPolicy, 'never'); + assert.equal(parseCliArgs(['--ask-for-approval', 'never', 'hi']).configOverrides.approvalPolicy, 'never'); + const prompt = parseCliArgs(['--ask-for-approval', 'prompt', 'hi']); + assert.equal(prompt.approvalPolicy, 'prompt'); + assert.equal(prompt.safetyModeOverride, undefined); + const onRequest = parseCliArgs(['--ask-for-approval', 'on-request', 'hi']); + assert.equal(onRequest.approvalPolicy, 'prompt'); + assert.equal(onRequest.safetyModeOverride, 'workspace-write'); + assert.equal(parseCliArgs(['--ask-for-approval', 'full-access', 'hi']).safetyModeOverride, 'full-access'); + assert.equal(parseCliArgs(['--ask-for-approval', 'read-only', 'hi']).safetyModeOverride, 'read-only'); +} + +// Mistyped subcommands must be caught before they become billable chat one-shots. +import { closestKnownCommand } from '../dist/cli/args.js'; +{ + // Typos close to a real command are flagged with a suggestion, NOT run as chat. + for (const [typo, expected] of [ + ['confgi', 'config'], + ['resme', 'resume'], + ['setpu', 'setup'], + ['doctr', 'doctor'], + ['mcpp', 'mcp'], + ]) { + const parsed = parseCliArgs([typo]); + assert.equal(parsed.command, 'chat', `${typo} still parses as chat command`); + assert.ok(parsed.unknownCommand, `${typo} should be flagged as an unknown command`); + assert.equal(parsed.unknownCommand.token, typo); + assert.equal(parsed.unknownCommand.suggestion, expected, `${typo} -> ${expected}`); + } +} +{ + // Legitimate one-word prompts are far from every command and must reach chat. + for (const word of ['hi', 'help me', 'ls', 'why', 'go']) { + const parsed = parseCliArgs(word.split(' ')); + assert.equal(parsed.unknownCommand, undefined, `'${word}' must NOT be treated as a typo'd command`); + assert.equal(parsed.prompt, word); + } +} +{ + // Multi-word prose and flag-bearing invocations are never intercepted. + assert.equal(parseCliArgs(['tell', 'me', 'about', 'confgi']).unknownCommand, undefined); + assert.equal(parseCliArgs(['-m', 'x', 'confgi']).unknownCommand, undefined); + assert.equal(parseCliArgs(['--', 'confgi']).unknownCommand, undefined); + // Real commands never trip the typo guard. + assert.equal(parseCliArgs(['config']).unknownCommand, undefined); + assert.equal(parseCliArgs(['doctor']).unknownCommand, undefined); +} +{ + // closestKnownCommand: conservative edit-distance-2 matcher. + assert.equal(closestKnownCommand('confgi'), 'config'); + assert.equal(closestKnownCommand('config'), null, 'exact command is not a typo'); + assert.equal(closestKnownCommand('hi'), null, 'far from every command'); + assert.equal(closestKnownCommand(''), null); +} + console.log('[PASS] CLI argument parser preserves prompts and override flags'); diff --git a/packages/dmoss-agent/test/cli-config-setup.spec.mjs b/packages/dmoss-agent/test/cli-config-setup.spec.mjs index f5f6317..6b87f95 100644 --- a/packages/dmoss-agent/test/cli-config-setup.spec.mjs +++ b/packages/dmoss-agent/test/cli-config-setup.spec.mjs @@ -1002,6 +1002,39 @@ try { assert.equal(loadConfigFile().approvalPolicy, 'never'); runConfigSet(['trustedTools', 'exec,filesystem__*']); assert.deepEqual(loadConfigFile().trustedTools, ['exec', 'filesystem__*']); + // config set must LOUDLY warn when a broad trusted pattern is set, since '*' + // means 'auto-approve every mutating tool the safety mode allows'. A narrow + // 'server__*' glob must NOT trigger the warning. + { + const origWrite = process.stderr.write.bind(process.stderr); + let captured = ''; + process.stderr.write = (chunk, ...rest) => { + captured += typeof chunk === 'string' ? chunk : chunk.toString(); + return origWrite(chunk, ...rest); + }; + try { + captured = ''; + runConfigSet(['trustedTools', 'exec,filesystem__*']); + assert.doesNotMatch( + captured, + /WARNING: broad trusted pattern/, + 'narrow trusted globs must not warn', + ); + captured = ''; + runConfigSet(['trustedTools', '*']); + assert.match( + captured, + /WARNING: broad trusted pattern\(s\) \*/, + 'config set trustedTools * must loudly warn at set time', + ); + assert.deepEqual(loadConfigFile().trustedTools, ['*'], '* is still saved (escape hatch stays usable)'); + // restore a narrow value so later assertions in this block keep their expectations + runConfigSet(['trustedTools', 'exec,filesystem__*']); + } finally { + process.stderr.write = origWrite; + } + } + runConfigSet(['deniedTools', 'device_*,write_file']); assert.deepEqual(loadConfigFile().deniedTools, ['device_*', 'write_file']); runConfigSet(['promptCache', 'false']); diff --git a/packages/dmoss-agent/test/cli-config-write-error.spec.mjs b/packages/dmoss-agent/test/cli-config-write-error.spec.mjs new file mode 100644 index 0000000..cbcc58e --- /dev/null +++ b/packages/dmoss-agent/test/cli-config-write-error.spec.mjs @@ -0,0 +1,84 @@ +#!/usr/bin/env node +/** + * Config-write failures must surface a clean, one-line message — never a raw + * Node `writeFileSync` stack trace through the top-level `Fatal:` handler. + * + * Regression: `moss config set model x` against a read-only / unwritable config + * dir printed `Fatal: Error: EACCES … at Object.writeFileSync (...)` with all + * internal frames. saveConfigFileAtPath now wraps the failure in a typed + * CliConfigWriteError ("cannot write config to : ") and cli-main + * prints that line alone. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/cli-config-write-error.spec.mjs + */ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; +import { CliConfigWriteError, saveConfigFileAtPath } from '../dist/cli/config.js'; + +const repoPackageDir = path.resolve(fileURLToPath(new URL('..', import.meta.url))); +const distCli = path.join(repoPackageDir, 'dist', 'cli.js'); + +// 1) Unit: saveConfigFileAtPath wraps a write failure in CliConfigWriteError +// with a stack-free, actionable message. Parenting the target dir under a +// regular file forces mkdir to fail deterministically on every platform +// (ENOTDIR on POSIX, EEXIST on Windows) — no chmod/root assumptions. +{ + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dmoss-cfg-write-')); + try { + const fileAsParent = path.join(tmp, 'not-a-dir'); + fs.writeFileSync(fileAsParent, 'x'); + const badPath = path.join(fileAsParent, 'config.json'); + let caught; + try { + saveConfigFileAtPath({ model: 'x' }, badPath); + } catch (err) { + caught = err; + } + assert.ok(caught, 'saveConfigFileAtPath must throw when the path is unwritable'); + assert.ok(caught instanceof CliConfigWriteError, `expected CliConfigWriteError, got ${caught?.name}`); + assert.equal(caught.configPath, badPath); + assert.match(caught.message, /^cannot write config to .+: /); + assert.doesNotMatch(caught.message, /writeFileSync|mkdirSync|\bat /, 'message must not embed a stack'); + console.log(' [PASS] saveConfigFileAtPath wraps write failures in CliConfigWriteError'); + } finally { + fs.rmSync(tmp, { recursive: true, force: true }); + } +} + +// 2) End-to-end: `moss config set` against an unwritable config dir prints the +// clean one-liner and exits 1 — no raw stack, no `Fatal:` dump. +{ + const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dmoss-cfg-write-cli-')); + try { + const fileAsParent = path.join(tmp, 'not-a-dir'); + fs.writeFileSync(fileAsParent, 'x'); + const result = spawnSync(process.execPath, [distCli, 'config', 'set', 'model', 'test-model'], { + cwd: repoPackageDir, + env: { + PATH: process.env.PATH, + HOME: path.join(tmp, 'home'), + DMOSS_CONFIG_DIR: path.join(fileAsParent, 'sub'), + DMOSS_NO_BUNDLED_DEFAULT: '1', + DMOSS_NO_UPDATE_CHECK: '1', + DMOSS_NO_COLOR: '1', + LANG: 'C.UTF-8', + }, + encoding: 'utf8', + }); + const out = `${result.stdout}\n${result.stderr}`; + assert.equal(result.status, 1, `expected exit 1, got ${result.status}\n${out}`); + assert.match(out, /moss: cannot write config to .+: /, `expected clean error line, got:\n${out}`); + assert.doesNotMatch(out, /at Object\.writeFileSync|at saveConfigFileAtPath|^Fatal:/m, `stack leaked:\n${out}`); + console.log(' [PASS] `moss config set` surfaces a clean config-write error, not a stack'); + } finally { + fs.rmSync(tmp, { recursive: true, force: true }); + } +} + +console.log('cli-config-write-error: all checks passed'); diff --git a/packages/dmoss-agent/test/cli-doctor.spec.mjs b/packages/dmoss-agent/test/cli-doctor.spec.mjs index 9e5ab48..a18f0bd 100644 --- a/packages/dmoss-agent/test/cli-doctor.spec.mjs +++ b/packages/dmoss-agent/test/cli-doctor.spec.mjs @@ -8,7 +8,13 @@ import assert from 'node:assert/strict'; import fs from 'node:fs'; import os from 'node:os'; import path from 'node:path'; -import { renderCliDoctor, renderNodeDoctorLine } from '../dist/cli/doctor.js'; +import { renderCliDoctor, renderNodeDoctorLine, cliDoctorHasFailure } from '../dist/cli/doctor.js'; + +// Exit-code gate: any `fail` line must make the report report a failure so the +// CLI can exit non-zero (doctor previously always exited 0, masking problems). +assert.equal(cliDoctorHasFailure('[doctor] Moss\n ok node: v22\n ok auth: ok'), false); +assert.equal(cliDoctorHasFailure('[doctor] Moss\n ok node: v22\n fail workspace: /x is not writable'), true); +assert.equal(cliDoctorHasFailure(' warn env ignored: DEEPSEEK_API_KEY'), false); function resolvedConfig(overrides = {}) { const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dmoss-doctor-config-')); diff --git a/packages/dmoss-agent/test/cli-env-ignored-notice.spec.mjs b/packages/dmoss-agent/test/cli-env-ignored-notice.spec.mjs new file mode 100644 index 0000000..00b130b --- /dev/null +++ b/packages/dmoss-agent/test/cli-env-ignored-notice.spec.mjs @@ -0,0 +1,70 @@ +#!/usr/bin/env node +/** + * The startup "[config] ignoring model env var(s): …" notice is informational, + * not a warning. It must respect the resolved CLI log level: `--quiet` and + * `DMOSS_LOG_LEVEL=warn` silence it. The doctor report keeps showing the + * ignored vars as the structured source of truth regardless of log level. + * + * Regression: the notice printed on EVERY chat/one-shot/resume invocation, so + * `moss --quiet -p "…"` could not produce clean stdout-only output. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/cli-env-ignored-notice.spec.mjs + */ +import assert from 'node:assert/strict'; +import { spawnSync } from 'node:child_process'; +import fs from 'node:fs'; +import os from 'node:os'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const repoPackageDir = path.resolve(fileURLToPath(new URL('..', import.meta.url))); +const distCli = path.join(repoPackageDir, 'dist', 'cli.js'); +const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dmoss-env-notice-')); + +const NOTICE = /ignoring model env var\(s\)/; + +function run(args, extraEnv = {}) { + // No api key + no bundled default → a one-shot stops at the missing-config + // gate (after the env-ignored notice, before any model call). OPENAI_API_KEY + // is a deliberately-ignored model env var, so the notice triggers. + const result = spawnSync(process.execPath, [distCli, ...args], { + cwd: repoPackageDir, + env: { + PATH: process.env.PATH, + HOME: path.join(tmp, 'home'), + DMOSS_CONFIG_DIR: path.join(tmp, 'config'), + DMOSS_NO_BUNDLED_DEFAULT: '1', + DMOSS_NO_UPDATE_CHECK: '1', + DMOSS_NO_COLOR: '1', + LANG: 'C.UTF-8', + OPENAI_API_KEY: 'leftover-from-another-tool', + ...extraEnv, + }, + encoding: 'utf8', + }); + return `${result.stdout}\n${result.stderr}`; +} + +try { + // Default log level: the notice is shown. + assert.match(run(['-p', 'hi']), NOTICE, 'notice must show at the default log level'); + + // --quiet (resolves to log level "warn") silences the notice. + assert.doesNotMatch(run(['--quiet', '-p', 'hi']), NOTICE, '--quiet must silence the notice'); + + // DMOSS_LOG_LEVEL=warn silences the notice. + assert.doesNotMatch( + run(['-p', 'hi'], { DMOSS_LOG_LEVEL: 'warn' }), + NOTICE, + 'DMOSS_LOG_LEVEL=warn must silence the notice', + ); + + // doctor keeps the ignored env var as the source of truth even under --quiet. + assert.match(run(['--quiet', 'doctor']), /OPENAI_API_KEY/, 'doctor must still report ignored env vars'); + + console.log('[PASS] env-ignored notice respects log level; doctor stays the source of truth'); +} finally { + fs.rmSync(tmp, { recursive: true, force: true }); +} diff --git a/packages/dmoss-agent/test/cli-help-resume-discoverability.spec.mjs b/packages/dmoss-agent/test/cli-help-resume-discoverability.spec.mjs new file mode 100644 index 0000000..cdfb8de --- /dev/null +++ b/packages/dmoss-agent/test/cli-help-resume-discoverability.spec.mjs @@ -0,0 +1,25 @@ +#!/usr/bin/env node +/** + * In-TUI /help (commandList) must name /resume — the command that actually + * switches into a saved conversation. Before this fix /help listed /sessions + * ("conversations you can resume") but never told the user the verb is /resume. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/cli-help-resume-discoverability.spec.mjs + */ + +import assert from 'node:assert/strict'; +import { commandList } from '../dist/cli/tui.js'; + +const text = commandList(); + +assert.match( + text, + /\/resume/, + '/help must name /resume so users can discover how to switch into a saved session', +); +// The pairing with /sessions should remain so list-then-switch reads as one flow. +assert.match(text, /\/sessions/, '/help should still list /sessions'); + +console.log(' [PASS] in-TUI /help surfaces /resume next to /sessions'); diff --git a/packages/dmoss-agent/test/cli-model-catalog.spec.mjs b/packages/dmoss-agent/test/cli-model-catalog.spec.mjs index 3c1c901..84dc030 100644 --- a/packages/dmoss-agent/test/cli-model-catalog.spec.mjs +++ b/packages/dmoss-agent/test/cli-model-catalog.spec.mjs @@ -67,3 +67,16 @@ assert.equal(invalidCustomConfig.ok, false); assert.match(invalidCustomConfig.message, /api key/i); console.log('[PASS] CLI model catalog supports selectable model lists'); +// Malformed / non-http(s) base_url must be rejected, not silently accepted and +// then fail opaquely at the first model call. +for (const badBaseUrl of ['notaurl', 'htps://gateway.example', 'ftp://gateway.example/api', 'localhost:8080']) { + const bad = parseCustomModelConfigInput(`base_url=${badBaseUrl} key=sk-test model_name=custom-coder`); + assert.equal(bad.ok, false, `expected ${badBaseUrl} to be rejected`); + assert.match(bad.message, /Invalid base_url/); +} + +// A valid http(s) base_url still parses. +const goodBaseUrl = parseCustomModelConfigInput('base_url=https://gateway.example/v1 key=sk-test model_name=custom-coder'); +assert.equal(goodBaseUrl.ok, true); + +console.log('[PASS] CLI model catalog rejects malformed base_url'); diff --git a/packages/dmoss-agent/test/cli-output-max-turns.spec.mjs b/packages/dmoss-agent/test/cli-output-max-turns.spec.mjs new file mode 100644 index 0000000..f697773 --- /dev/null +++ b/packages/dmoss-agent/test/cli-output-max-turns.spec.mjs @@ -0,0 +1,55 @@ +#!/usr/bin/env node +/** + * Long-horizon truncation surfacing. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/cli-output-max-turns.spec.mjs + */ +import assert from 'node:assert/strict'; +import { createCliRunRenderer } from '../dist/cli/output.js'; + +function createCapture() { + let text = ''; + return { + stream: { write(chunk) { text += String(chunk); return true; } }, + read() { return text; }, + }; +} + +// RED before fix: a max_turns run printed only a newline, looking like normal +// completion. The user must be told it is truncated and how to continue. +{ + const stdout = createCapture(); + const stderr = createCapture(); + const renderer = createCliRunRenderer({ detailMode: 'progress', stdout: stdout.stream, stderr: stderr.stream }); + renderer.handle({ type: 'text_delta', delta: 'Partial work so far' }); + renderer.handle({ type: 'done', result: { response: 'Partial work so far', toolCalls: [], toolResults: [], stopReason: 'max_turns_reached' } }); + assert.match(stderr.read(), /turn limit/i, 'truncation must be announced'); + assert.match(stderr.read(), /moss resume --last/, 'must tell the user how to continue'); + assert.equal(stdout.read(), 'Partial work so far\n', 'the partial answer still goes to stdout'); +} + +// Even in quiet mode the hard stop must surface (it is not progress noise). +{ + const stdout = createCapture(); + const stderr = createCapture(); + const renderer = createCliRunRenderer({ detailMode: 'quiet', stdout: stdout.stream, stderr: stderr.stream }); + renderer.handle({ type: 'text_delta', delta: 'half' }); + renderer.handle({ type: 'done', result: { response: 'half', toolCalls: [], toolResults: [], stopReason: 'tool_followup_cap_reached' } }); + assert.match(stderr.read(), /moss resume --last/, 'quiet mode still warns on truncation'); +} + +// A NORMAL completion must stay silent (no false truncation banner) — this also +// guards the existing quiet-mode empty-stderr contract. +{ + const stdout = createCapture(); + const stderr = createCapture(); + const renderer = createCliRunRenderer({ detailMode: 'quiet', stdout: stdout.stream, stderr: stderr.stream }); + renderer.handle({ type: 'text_delta', delta: 'Only answer' }); + renderer.handle({ type: 'done', result: { response: 'Only answer', toolCalls: [], toolResults: [], stopReason: 'end_turn' } }); + assert.equal(stderr.read(), '', 'normal completion prints no truncation notice'); + assert.equal(stdout.read(), 'Only answer\n'); +} + +console.log('[PASS] CLI renderer surfaces max_turns truncation with a resume hint'); diff --git a/packages/dmoss-agent/test/cli-session-fork-collision.spec.mjs b/packages/dmoss-agent/test/cli-session-fork-collision.spec.mjs new file mode 100644 index 0000000..673c9a5 --- /dev/null +++ b/packages/dmoss-agent/test/cli-session-fork-collision.spec.mjs @@ -0,0 +1,34 @@ +#!/usr/bin/env node +/** + * Fork-key collision regression: two forks created within the same second must + * NOT share a key and must NOT overwrite each other's messages. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/cli-session-fork-collision.spec.mjs + */ +import assert from 'node:assert/strict'; +import { InMemorySessionStore } from '../dist/core/session/session.js'; +import { resolveCliSession } from '../dist/cli/session.js'; + +const store = new InMemorySessionStore(); +await store.appendMessage('src-a', { role: 'user', content: 'branch A content' }); +await store.appendMessage('src-b', { role: 'user', content: 'branch B content' }); + +// Two forks back-to-back (same wall-clock second). RED before fix: identical +// cli-fork-<14digits> keys, second replaceMessages clobbers the first branch. +const forkA = await resolveCliSession({ command: 'fork', store, sessionKey: 'src-a' }); +const forkB = await resolveCliSession({ command: 'fork', store, sessionKey: 'src-b' }); + +assert.equal(forkA.forked, true); +assert.equal(forkB.forked, true); +assert.notEqual(forkA.sessionKey, forkB.sessionKey, 'rapid forks must get distinct keys'); + +const a = await store.loadMessages(forkA.sessionKey); +const b = await store.loadMessages(forkB.sessionKey); +assert.equal(a.length, 1); +assert.equal(b.length, 1); +assert.match(String(a[0].content), /branch A content/, 'fork A keeps its own messages'); +assert.match(String(b[0].content), /branch B content/, 'fork B is not overwritten by A'); + +console.log('[PASS] Rapid forks get unique keys and do not overwrite each other'); diff --git a/packages/dmoss-agent/test/cli-session.spec.mjs b/packages/dmoss-agent/test/cli-session.spec.mjs index a5e4ca2..50cfcc4 100644 --- a/packages/dmoss-agent/test/cli-session.spec.mjs +++ b/packages/dmoss-agent/test/cli-session.spec.mjs @@ -44,3 +44,22 @@ await store.appendMessage('newer', { role: 'user', content: 'new' }); } console.log('[PASS] CLI session resume and fork resolve existing JSONL sessions'); +{ + // resume/fork of a non-existent (typo'd) explicit key must NOT print a false + // "Resuming session" notice and run empty — it must surface a clear error. + const resumeMissing = await resolveCliSession({ command: 'resume', store, sessionKey: 'does-not-exist' }); + assert.match(resumeMissing.error, /No saved session named "does-not-exist"/); + assert.equal(resumeMissing.notice, undefined); + + const forkMissing = await resolveCliSession({ command: 'fork', store, sessionKey: 'also-missing' }); + assert.match(forkMissing.error, /No saved session named "also-missing"/); + assert.equal(forkMissing.notice, undefined); + + // An explicit key that DOES exist still resolves cleanly with no error. + const resumeReal = await resolveCliSession({ command: 'resume', store, sessionKey: 'newer' }); + assert.equal(resumeReal.error, undefined); + assert.equal(resumeReal.sessionKey, 'newer'); + assert.match(resumeReal.notice, /Resuming session/); +} + +console.log('[PASS] CLI session resume rejects missing explicit keys'); diff --git a/packages/dmoss-agent/test/compaction-fallback.spec.mjs b/packages/dmoss-agent/test/compaction-fallback.spec.mjs index cbf5a3b..e9ae77b 100644 --- a/packages/dmoss-agent/test/compaction-fallback.spec.mjs +++ b/packages/dmoss-agent/test/compaction-fallback.spec.mjs @@ -33,11 +33,30 @@ function makeMessages(count) { // ── Test 1: Deterministic fallback summary is non-empty ── { const msgs = makeMessages(10); - const summary = buildDeterministicCompactionSummary(msgs); + const summary = buildDeterministicCompactionSummary(msgs, 'test'); assert.ok(summary.length > 10, `deterministic summary must be non-empty, got ${summary.length} chars`); console.log(' [PASS] deterministic summary generates non-empty text for 10 messages'); } +// ── Test 1b: Deterministic fallback carries the original user goal up front ── +{ + const msgs = [ + { + role: 'user', + content: [{ type: 'text', text: '请修复摄像头部署脚本并跑验证' }], + }, + ...makeMessages(40), + ]; + const summary = buildDeterministicCompactionSummary(msgs, 'overflow'); + const goalSection = summary.match(/## 1\. 主要目标\n([\s\S]*?)\n\n## 2\./)?.[1] ?? ''; + assert.match( + goalSection, + /请修复摄像头部署脚本并跑验证/, + 'fallback summary must preserve the original user goal in section 1, not only in later excerpts', + ); + console.log(' [PASS] deterministic summary preserves the original user goal in section 1'); +} + // ── Test 2: Deterministic summary for empty messages ── { const summary = buildDeterministicCompactionSummary([]); @@ -219,4 +238,4 @@ function makeMessages(count) { console.log(' [PASS] summarizeInStages: smaller-chunks second failure returns final fallback'); } -console.log('\n[pass] compaction-fallback: 13/13'); +console.log('\n[pass] compaction-fallback: 14/14'); diff --git a/packages/dmoss-agent/test/context-budget-planner.spec.mjs b/packages/dmoss-agent/test/context-budget-planner.spec.mjs index d89d27a..70b8ba5 100644 --- a/packages/dmoss-agent/test/context-budget-planner.spec.mjs +++ b/packages/dmoss-agent/test/context-budget-planner.spec.mjs @@ -48,9 +48,8 @@ import { assert.equal(plan.reason, 'baseline_hygiene'); assert.deepEqual( plan.actions.map((a) => a.kind), - ['invalidate_stale_reads', 'microcompact'], + ['invalidate_stale_reads'], ); - assert.deepEqual(plan.actions.at(-1).microcompactConfig, {}); } { @@ -108,14 +107,8 @@ import { push: (event) => events.push(event), }); - assert(result.savedChars > 0); - assert.equal(events.length, 1); - assert.equal(events[0].type, 'context_action'); - assert.deepEqual( - events[0].actions.map((a) => a.kind), - ['microcompact'], - ); - assert.equal(events[0].savedChars, result.savedChars); + assert.equal(result.savedChars, 0); + assert.equal(events.length, 0, 'low-pressure context hygiene must not compact active history'); } { diff --git a/packages/dmoss-agent/test/default-workflow.spec.mjs b/packages/dmoss-agent/test/default-workflow.spec.mjs index 8239d2d..d8c0189 100644 --- a/packages/dmoss-agent/test/default-workflow.spec.mjs +++ b/packages/dmoss-agent/test/default-workflow.spec.mjs @@ -22,6 +22,17 @@ import { SkillRegistry } from '../dist/skills/index.js'; assert.match(prompt, /existing user data/); } +{ + // The agent must be told it is already in a terminal and must not invent + // desktop GUI launchers (which fail on headless/board targets). + const prompt = buildMossDefaultWorkflowPrompt(); + assert.match(prompt, /ALREADY running inside a terminal/); + assert.match(prompt, /open -a Terminal/); + assert.match(prompt, /xdg-open/); + assert.match(prompt, /headless/); + assert.match(prompt, /clarify/); +} + { const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'moss-default-skills-')); try { diff --git a/packages/dmoss-agent/test/dmoss-agent-run-loop-bridge-context-taskframe.spec.mjs b/packages/dmoss-agent/test/dmoss-agent-run-loop-bridge-context-taskframe.spec.mjs index feb417e..0252ed4 100644 --- a/packages/dmoss-agent/test/dmoss-agent-run-loop-bridge-context-taskframe.spec.mjs +++ b/packages/dmoss-agent/test/dmoss-agent-run-loop-bridge-context-taskframe.spec.mjs @@ -197,6 +197,113 @@ function makeAgent(config) { ); } +{ + const store = new InMemorySessionStore(); + const gateCalls = []; + const { provider, streamRequests } = createModelEventProvider((options, onEvent, callNumber) => { + if (callNumber === 1) { + onEvent({ type: 'content_block_delta', text: 'premature completion', deltaRole: 'visible' }); + return { + stopReason: 'end_turn', + content: [{ type: 'text', text: 'premature completion' }], + usage: { inputTokens: 1, outputTokens: 1 }, + }; + } + onEvent({ type: 'content_block_delta', text: 'continued with evidence', deltaRole: 'visible' }); + return { + stopReason: 'end_turn', + content: [{ type: 'text', text: 'continued with evidence' }], + usage: { inputTokens: 1, outputTokens: 1 }, + }; + }); + const agent = makeAgent({ + llmProvider: provider, + sessionStore: store, + enableCompaction: false, + enableContextPruning: false, + maxAgentTurns: 4, + completionGate: async ({ response, turn }) => { + gateCalls.push({ response, turn }); + if (gateCalls.length === 1) { + return { + ok: false, + reason: 'no verification evidence', + correction: '[System] Completion rejected: run validation before claiming the task is complete.', + }; + } + return { ok: true }; + }, + }); + + const events = await collect( + agent.streamChat('bridge-completion-gate', 'finish only after verification', { + runId: 'run-completion-gate', + }), + ); + + const done = events.find((event) => event.type === 'done'); + assert(done, 'expected done event'); + assert.equal(done.result.response, 'continued with evidence'); + assert.equal(gateCalls.length, 2, 'completion gate should inspect the retry response too'); + assert.equal(streamRequests.length, 2, 'rejected completion should trigger another LLM turn'); + assert( + !events.some((event) => event.type === 'text_delta' && event.delta.includes('premature completion')), + 'completion-gate rejected text must not stream to the UI before retry', + ); + assert( + events.some((event) => event.type === 'text_delta' && event.delta.includes('continued with evidence')), + 'approved completion text should stream after the gate passes', + ); + assert( + streamRequests[1].messages.some((message) => + JSON.stringify(message).includes('Completion rejected: run validation'), + ), + 'second LLM request should include the completion-gate correction message', + ); +} + +{ + const store = new InMemorySessionStore(); + const { provider } = createModelEventProvider((_options, onEvent) => { + onEvent({ type: 'content_block_delta', text: 'still claiming completion', deltaRole: 'visible' }); + return { + stopReason: 'end_turn', + content: [{ type: 'text', text: 'still claiming completion' }], + usage: { inputTokens: 1, outputTokens: 1 }, + }; + }); + const agent = makeAgent({ + llmProvider: provider, + sessionStore: store, + enableCompaction: false, + enableContextPruning: false, + maxAgentTurns: 5, + completionGate: async () => ({ + ok: false, + reason: 'missing validation evidence', + correction: '[System] Completion rejected: gather validation evidence.', + fallbackResponse: 'I could not verify completion after retrying; this remains unverified.', + }), + }); + + const events = await collect( + agent.streamChat('bridge-completion-gate-exhausted', 'finish only after verification', { + runId: 'run-completion-gate-exhausted', + }), + ); + + const done = events.find((event) => event.type === 'done'); + assert(done, 'expected done event after completion-gate retry exhaustion'); + assert.equal( + done.result.response, + 'I could not verify completion after retrying; this remains unverified.', + ); + assert( + !events.some((event) => event.type === 'text_delta' && event.delta.includes('still claiming completion')), + 'completion-gate exhausted path must not stream the rejected completion claim', + ); +} + { const store = new InMemorySessionStore(); const compactHooks = new CompactHookRegistry(); @@ -293,6 +400,19 @@ function makeAgent(config) { 1, 'recovered provider request should not receive duplicate compaction summaries', ); + const recoveredCheckpoints = checkpointMessages(streamRequests[1].messages); + assert.equal( + recoveredCheckpoints.length, + 1, + 'recovered provider request must receive the live TaskFrame checkpoint after compaction', + ); + const recoveredFrame = parseCheckpoint(recoveredCheckpoints[0]); + assert.equal(recoveredFrame.source, 'compaction'); + assert.match(recoveredFrame.goal, /overflow compaction please/); + assert( + recoveredFrame.completedSteps.some((step) => step.includes('Saved context checkpoint')), + 'compaction checkpoint should preserve the saved-context step for the next LLM request', + ); assert.equal( countCompactionSummaries(await store.loadMessages('bridge-context-overflow')), 1, diff --git a/packages/dmoss-agent/test/exec-timeout-message.spec.mjs b/packages/dmoss-agent/test/exec-timeout-message.spec.mjs new file mode 100644 index 0000000..daa48f2 --- /dev/null +++ b/packages/dmoss-agent/test/exec-timeout-message.spec.mjs @@ -0,0 +1,49 @@ +#!/usr/bin/env node +/** + * A device/board command that hits its timeout must report a legible TIMEOUT + * (with the knob to raise it), not an indistinguishable 'command failed' / + * transport error. Long ops (colcon build, apt install) used to look broken. + * + * Red before fix: ProcessError has no timedOut flag and the exec handlers + * surface the SIGKILL'd ssh exit as a generic failure. + * + * Run after `npm run build -w @rdk-moss/agent`. + */ +import assert from 'node:assert/strict'; +import { ProcessError } from '../dist/utils/run-process.js'; +import { createDeviceSshTools } from '../dist/tools/device-ssh.js'; +import { createBoardWorkspaceTools } from '../dist/tools/device-workspace.js'; + +const CONFIG = { host: '10.0.0.9', user: 'root', port: 22 }; + +// ProcessError carries the timeout marker (and stays backward-compatible). +assert.equal(new ProcessError(255, '', '').timedOut, false); +assert.equal(new ProcessError(124, '', '', true).timedOut, true); + +// device_exec: a timed-out child -> legible timeout message with the knob. +{ + const tools = Object.fromEntries(createDeviceSshTools(CONFIG).map((t) => [t.name, t])); + // device_exec routes through runSsh; force a timeout via an unreachable host + // would be slow, so instead assert the message shape using a tiny timeout and + // a command that sleeps. We avoid real SSH by checking the board path below, + // and here only assert the tool exists + default timeout text. + assert.ok(tools.device_exec, 'device_exec exists'); + assert.match(tools.device_exec.inputSchema.properties.timeout_ms.description, /default: 30000/); +} + +// board exec: inject a runner that throws a timed-out ProcessError and assert +// the message says 'timed out' with a raise hint (no real SSH). +{ + const runner = async () => { + throw new ProcessError(255, '', '', true); + }; + const tools = createBoardWorkspaceTools(CONFIG, { runProcessImpl: runner }); + const exec = tools.find((t) => t.name === 'exec'); + await assert.rejects( + () => exec.execute({ command: 'colcon build', timeout_ms: 1000 }, {}), + (e) => /timed out after 1s/i.test(e.message) && /timeout_ms/.test(e.message), + 'board exec timeout must be legible and name the knob', + ); +} + +console.log('[PASS] exec timeouts are legible and point at timeout_ms'); diff --git a/packages/dmoss-agent/test/jsonl-session-store-max-sessions.spec.mjs b/packages/dmoss-agent/test/jsonl-session-store-max-sessions.spec.mjs new file mode 100644 index 0000000..09d3a22 --- /dev/null +++ b/packages/dmoss-agent/test/jsonl-session-store-max-sessions.spec.mjs @@ -0,0 +1,81 @@ +#!/usr/bin/env node +/** + * Opt-in session-count retention for JsonlSessionStore. + * + * Before: only a per-file 50MB cap existed; session files accumulated unbounded + * in `.moss/sessions`. JsonlSessionStore now accepts `maxSessions` — a positive + * cap prunes the oldest sessions (by updatedAt) when a NEW session is created, + * never touching the session just written. The default (omitted / <= 0) keeps + * the historical unbounded behavior, because retention is a host policy and + * moss must not delete user history unless the host opts in. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/jsonl-session-store-max-sessions.spec.mjs + */ +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; + +import { JsonlSessionStore } from '../dist/core/session/jsonl-session-store.js'; + +const countJsonl = async (dir) => + (await fs.readdir(dir)).filter((f) => f.endsWith('.jsonl')).length; + +// 1) Default (no maxSessions): unbounded — every session is kept. +{ + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-maxsess-default-')); + const store = new JsonlSessionStore({ dir }); + for (let i = 0; i < 5; i++) { + await store.appendMessage(`session-${i}`, { role: 'user', content: `m${i}` }); + } + assert.equal(await countJsonl(dir), 5, 'default store must keep all sessions (unbounded)'); + console.log(' [PASS] default JsonlSessionStore keeps sessions unbounded'); +} + +// 2) maxSessions cap: creating new sessions prunes the oldest down to the cap. +{ + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-maxsess-cap-')); + const store = new JsonlSessionStore({ dir, maxSessions: 3 }); + + // Create 5 sessions with strictly increasing mtimes so "oldest" is unambiguous. + for (let i = 0; i < 5; i++) { + await store.appendMessage(`session-${i}`, { role: 'user', content: `m${i}` }); + const fp = path.join(dir, `session-${i}.jsonl`); + const t = new Date(Date.now() + i * 1000); + await fs.utimes(fp, t, t); + } + // The cap is enforced lazily on the NEXT new-session create, so add one more + // after the mtimes are deterministic, then assert the cap holds. + await store.appendMessage('session-5', { role: 'user', content: 'm5' }); + const fp5 = path.join(dir, 'session-5.jsonl'); + const t5 = new Date(Date.now() + 10_000); + await fs.utimes(fp5, t5, t5); + await store.appendMessage('session-6', { role: 'user', content: 'm6' }); + + const remaining = new Set((await store.listSessions()).map((s) => s.sessionKey)); + assert.equal(remaining.size, 3, `cap must hold at 3, got ${remaining.size}: ${[...remaining]}`); + assert.ok(remaining.has('session-6'), 'the just-written session must never be pruned'); + assert.ok(!remaining.has('session-0'), 'the oldest session must be pruned first'); + assert.ok(!remaining.has('session-1'), 'the next-oldest session must be pruned'); + console.log(' [PASS] maxSessions prunes oldest sessions and never the active one'); +} + +// 3) Appending to an EXISTING session never prunes (count does not grow). +{ + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-maxsess-reuse-')); + const store = new JsonlSessionStore({ dir, maxSessions: 2 }); + await store.appendMessage('a', { role: 'user', content: '1' }); + await store.appendMessage('b', { role: 'user', content: '1' }); + // Re-append to existing sessions many times: must not delete the other one. + for (let i = 0; i < 5; i++) { + await store.appendMessage('a', { role: 'user', content: `more-${i}` }); + await store.appendMessage('b', { role: 'user', content: `more-${i}` }); + } + const keys = new Set((await store.listSessions()).map((s) => s.sessionKey)); + assert.deepEqual(keys, new Set(['a', 'b']), 'appending to existing sessions must not prune'); + console.log(' [PASS] appending to existing sessions does not trigger pruning'); +} + +console.log('jsonl-session-store-max-sessions: all checks passed'); diff --git a/packages/dmoss-agent/test/jsonl-session-title.spec.mjs b/packages/dmoss-agent/test/jsonl-session-title.spec.mjs new file mode 100644 index 0000000..ac6cd87 --- /dev/null +++ b/packages/dmoss-agent/test/jsonl-session-title.spec.mjs @@ -0,0 +1,93 @@ +#!/usr/bin/env node +/** + * JsonlSessionStore derives a human-readable title from the first user message, + * and the TUI session pickers surface it instead of leaving the bare key alone. + * + * Run: + * npm run build -w @rdk-moss/agent + * node packages/dmoss-agent/test/jsonl-session-title.spec.mjs + */ + +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; + +import { JsonlSessionStore } from '../dist/core/session/jsonl-session-store.js'; +import { formatTuiSessions } from '../dist/cli/tui.js'; + +const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-jsonl-session-title-')); +const store = new JsonlSessionStore({ dir }); + +// First user message becomes the title; assistant/system content is ignored. +await store.appendMessage('cli-20260613-deploy', { + role: 'assistant', + content: 'system preamble that must not become the title', +}); +await store.appendMessage('cli-20260613-deploy', { + role: 'user', + content: 'Deploy the YOLO model to the RDK X5 board', +}); + +// Over-long first messages are length-capped so they cannot blow out the picker. +const longMessage = 'x'.repeat(200); +await store.appendMessage('cli-20260613-long', { role: 'user', content: longMessage }); + +// Content-block (image+text) user messages still yield the text part. +await store.appendMessage('cli-20260613-blocks', { + role: 'user', + content: [ + { type: 'image', data: 'xxx', mimeType: 'image/png' }, + { type: 'text', text: 'Why does the camera node crash on startup?' }, + ], +}); + +// A session with no user message must not fabricate a title. +await store.appendMessage('cli-20260613-empty', { + role: 'assistant', + content: 'only assistant content here', +}); + +const sessions = await store.listSessions(); +const byKey = Object.fromEntries(sessions.map((s) => [s.sessionKey, s])); + +assert.equal( + byKey['cli-20260613-deploy'].title, + 'Deploy the YOLO model to the RDK X5 board', + 'title should come from the first user message, not assistant content', +); +assert.ok( + byKey['cli-20260613-long'].title.length <= 80, + 'over-long titles must be length-capped', +); +assert.ok( + byKey['cli-20260613-long'].title.endsWith('…'), + 'truncated titles should end with an ellipsis', +); +assert.equal( + byKey['cli-20260613-blocks'].title, + 'Why does the camera node crash on startup?', + 'title should extract the text part of a content-block user message', +); +assert.equal( + byKey['cli-20260613-empty'].title, + undefined, + 'sessions with no user message must not fabricate a title', +); + +console.log(' [PASS] JsonlSessionStore derives title from the first user message'); + +// The TUI session list surfaces the title so bare cli- keys are legible. +const rendered = formatTuiSessions(sessions, 'cli-20260613-deploy'); +assert.match( + rendered, + /Deploy the YOLO model to the RDK X5 board/, + 'formatTuiSessions should surface the saved title alongside the key', +); +assert.match( + rendered, + /Why does the camera node crash/, + 'formatTuiSessions should surface each session title', +); + +console.log(' [PASS] formatTuiSessions surfaces the saved session title'); diff --git a/packages/dmoss-agent/test/pi-ai-adapter.spec.mjs b/packages/dmoss-agent/test/pi-ai-adapter.spec.mjs index fd3d587..2e98c64 100644 --- a/packages/dmoss-agent/test/pi-ai-adapter.spec.mjs +++ b/packages/dmoss-agent/test/pi-ai-adapter.spec.mjs @@ -207,3 +207,87 @@ import { PiAiFirstEventTimeoutError } from '../dist/provider/pi-ai-adapter.js'; } console.log('All pi-ai-adapter checks passed.'); +// ── pi-ai cache usage tokens are surfaced (prompt-cache observability) ── +// Before the fix the parser dropped cache tokens, so cacheReadTokens / +// cacheCreationTokens were always undefined on the pi-ai path and the +// downstream cache_metrics event always reported 0 — making it impossible to +// verify prompt caching works on the dominant production path. +{ + const { PiAiLLMProvider } = await import('../dist/provider/index.js'); + + // Gateway that reports cache tokens in pi-ai cost-style naming. + const provider = new PiAiLLMProvider({ + streamFn: async function* () { + yield { + type: 'done', + stopReason: 'stop', + message: { + content: [{ type: 'text', text: 'ok' }], + usage: { input: 1200, output: 30, cacheRead: 1000, cacheWrite: 200 }, + }, + }; + }, + model: { api: 'anthropic-messages', provider: 'anthropic', id: 'claude-sonnet-4-20250514' }, + apiKey: 'sk-ant-api03-abcdef1234567890ghijklmnopqrstuv', + }); + + const res = await provider.complete({ + model: 'claude-sonnet-4-20250514', + systemPrompt: 'stable prompt\n\ndynamic turn context', + systemPromptParts: { stable: 'stable prompt', dynamic: 'dynamic turn context' }, + messages: [{ role: 'user', content: 'hi' }], + }); + + assert.equal(res.usage.inputTokens, 1200); + assert.equal(res.usage.outputTokens, 30); + assert.equal(res.usage.cacheReadTokens, 1000, 'cache read tokens must be surfaced on the pi-ai path'); + assert.equal(res.usage.cacheCreationTokens, 200, 'cache creation tokens must be surfaced on the pi-ai path'); +} + +// Alternate gateway naming (cacheReadTokens / cacheCreationTokens) also works. +{ + const { PiAiLLMProvider } = await import('../dist/provider/index.js'); + const provider = new PiAiLLMProvider({ + streamFn: async function* () { + yield { + type: 'done', + stopReason: 'stop', + message: { + content: [{ type: 'text', text: 'ok' }], + usage: { input: 50, output: 5, cacheReadTokens: 40, cacheCreationTokens: 10 }, + }, + }; + }, + model: { api: 'openai', provider: 'openai', id: 'gpt-5' }, + apiKey: 'sk-test', + }); + const res = await provider.complete({ + model: 'gpt-5', + systemPrompt: 's', + messages: [{ role: 'user', content: 'hi' }], + }); + assert.equal(res.usage.cacheReadTokens, 40); + assert.equal(res.usage.cacheCreationTokens, 10); +} + +// No cache fields reported → usage still valid, cache fields simply absent. +{ + const { PiAiLLMProvider } = await import('../dist/provider/index.js'); + const provider = new PiAiLLMProvider({ + streamFn: async function* () { + yield { + type: 'done', + stopReason: 'stop', + message: { content: [{ type: 'text', text: 'ok' }], usage: { input: 7, output: 2 } }, + }; + }, + model: { api: 'openai', provider: 'openai', id: 'gpt-5' }, + apiKey: 'sk-test', + }); + const res = await provider.complete({ model: 'gpt-5', systemPrompt: 's', messages: [{ role: 'user', content: 'hi' }] }); + assert.equal(res.usage.inputTokens, 7); + assert.equal(res.usage.cacheReadTokens, undefined); +} + +console.log('[PASS] pi-ai cache usage tokens are surfaced for prompt-cache observability'); + diff --git a/packages/dmoss-agent/test/readme-accuracy.spec.mjs b/packages/dmoss-agent/test/readme-accuracy.spec.mjs new file mode 100644 index 0000000..cac9251 --- /dev/null +++ b/packages/dmoss-agent/test/readme-accuracy.spec.mjs @@ -0,0 +1,50 @@ +#!/usr/bin/env node +/** + * Run: + * node packages/dmoss-agent/test/readme-accuracy.spec.mjs + * + * Pins user-facing README claims to live CLI behavior so they cannot silently + * rot. Fails (red) against the pre-fix README; passes after the doc edits land. + */ +import assert from 'node:assert/strict'; +import fs from 'node:fs'; +import path from 'node:path'; +import { fileURLToPath } from 'node:url'; + +const here = path.dirname(fileURLToPath(import.meta.url)); +const rootReadme = fs.readFileSync(path.resolve(here, '../../../README.md'), 'utf-8'); +const agentReadme = fs.readFileSync(path.resolve(here, '../README.md'), 'utf-8'); + +// DOC-1: root /connect must document board mode + how to leave it. +assert.match(rootReadme, /board mode/i, 'root README /connect section must mention board mode'); +assert.match(rootReadme, /\/disconnect/, 'root README must document /disconnect'); +assert.match(rootReadme, /--hybrid/, 'root README must document the --hybrid connect flag'); + +// DOC-2: root README must have a resume / long-running-task section. +assert.match(rootReadme, /Long-Running Tasks And Resume/, 'root README needs a long-task/resume section'); +assert.match(rootReadme, /moss resume --last/, 'root README must show moss resume --last'); +assert.match(rootReadme, /--continue/, 'root README must document --continue'); +assert.match(rootReadme, /resumable/i, 'root README must explain interrupted runs are resumable'); + +// DOC-3: Automation & Safety must cover interactive modes, /yolo, and the full +// accepted value set of --ask-for-approval (these were undocumented). +assert.match(rootReadme, /Shift\+Tab/, 'root README must document Shift+Tab interaction modes'); +assert.match(rootReadme, /\/yolo/, 'root README must document /yolo'); +for (const policy of ['never', 'on-request', 'read-only', 'workspace-write', 'full-access']) { + assert.ok( + new RegExp(`--ask-for-approval[\\s\\S]*${policy}`).test(rootReadme), + `root README --ask-for-approval must list the "${policy}" value`, + ); +} +assert.match(rootReadme, /moss doctor/, 'root README must point at moss doctor for troubleshooting'); + +// DOC-4/DOC-5: agent README must not tell users to resume from /sessions, and +// must document /resume as the switch command. +assert.doesNotMatch( + agentReadme, + /\/sessions\s+list saved conversations you can resume/, + 'agent README must not claim /sessions resumes — /sessions lists, /resume switches', +); +assert.match(agentReadme, /\/resume/, 'agent README must document /resume'); + +console.log('readme-accuracy.spec.mjs: all README claims match live CLI behavior'); diff --git a/packages/dmoss-agent/test/ros2-domain-id.spec.mjs b/packages/dmoss-agent/test/ros2-domain-id.spec.mjs new file mode 100644 index 0000000..e0159bf --- /dev/null +++ b/packages/dmoss-agent/test/ros2-domain-id.spec.mjs @@ -0,0 +1,42 @@ +#!/usr/bin/env node +/** + * ros2_* tools must pin ROS_DOMAIN_ID when the device config specifies a + * domain — otherwise a robot on a non-default DDS domain silently returns + * empty topic/node/service lists (looks like 'the tool doesn't work'). + * + * Red before fix: ros2DomainPrefix does not exist and the remote command + * never contains ROS_DOMAIN_ID. Green after: the export is prepended. + * + * Run after `npm run build -w @rdk-moss/agent`. + */ +import assert from 'node:assert/strict'; +import { ros2DomainPrefix } from '../dist/tools/device-ros2.js'; +import { getDeviceConfigFromEnv } from '../dist/tools/device-ssh.js'; + +// 1. No domain configured -> no export (byte-for-byte current behavior). +assert.equal(ros2DomainPrefix({ host: 'h' }), ''); + +// 2. Domain configured -> export prefix that the remote shell will run +// before sourcing the ROS setup. +assert.equal(ros2DomainPrefix({ host: 'h', rosDomainId: 42 }), 'export ROS_DOMAIN_ID=42; '); +assert.equal(ros2DomainPrefix({ host: 'h', rosDomainId: 0 }), 'export ROS_DOMAIN_ID=0; '); + +// 3. DMOSS_ROS_DOMAIN_ID flows from env into the device config. +const savedHost = process.env.DMOSS_DEVICE_HOST; +const savedDomain = process.env.DMOSS_ROS_DOMAIN_ID; +try { + process.env.DMOSS_DEVICE_HOST = '10.0.0.9'; + process.env.DMOSS_ROS_DOMAIN_ID = '7'; + assert.equal(getDeviceConfigFromEnv().rosDomainId, 7); + + process.env.DMOSS_ROS_DOMAIN_ID = ''; + assert.equal(getDeviceConfigFromEnv().rosDomainId, undefined, 'blank domain is ignored'); + + process.env.DMOSS_ROS_DOMAIN_ID = 'not-a-number'; + assert.equal(getDeviceConfigFromEnv().rosDomainId, undefined, 'invalid domain is ignored'); +} finally { + if (savedHost === undefined) delete process.env.DMOSS_DEVICE_HOST; else process.env.DMOSS_DEVICE_HOST = savedHost; + if (savedDomain === undefined) delete process.env.DMOSS_ROS_DOMAIN_ID; else process.env.DMOSS_ROS_DOMAIN_ID = savedDomain; +} + +console.log('[PASS] ros2 tools pin ROS_DOMAIN_ID from config/env'); diff --git a/packages/dmoss-agent/test/ros2-sample-window.spec.mjs b/packages/dmoss-agent/test/ros2-sample-window.spec.mjs new file mode 100644 index 0000000..ba3c723 --- /dev/null +++ b/packages/dmoss-agent/test/ros2-sample-window.spec.mjs @@ -0,0 +1,32 @@ +#!/usr/bin/env node +/** + * ros2_topic_echo / ros2_topic_hz must let the caller widen the sampling + * window — a hardcoded 5s window misses low-rate topics ('no message within + * 5s' on a healthy 0.5 Hz topic). Default stays 5s (current behavior). + * + * Red before fix: clampSampleSeconds is absent; the tools have no timeout_sec + * input and the remote command always says `timeout 5`. + * + * Run after `npm run build -w @rdk-moss/agent`. + */ +import assert from 'node:assert/strict'; +import { clampSampleSeconds, createRos2Tools } from '../dist/tools/device-ros2.js'; + +// Clamp: default 5, min 1, max 60, invalid -> 5. +assert.equal(clampSampleSeconds(undefined), 5); +assert.equal(clampSampleSeconds(0), 5); +assert.equal(clampSampleSeconds('nope'), 5); +assert.equal(clampSampleSeconds(20), 20); +assert.equal(clampSampleSeconds(999), 60); + +// The tools expose timeout_sec and thread the window into the remote command. +const tools = Object.fromEntries(createRos2Tools({ host: 'h' }).map((t) => [t.name, t])); +for (const name of ['ros2_topic_echo', 'ros2_topic_hz']) { + assert.ok(tools[name].inputSchema.properties.timeout_sec, `${name} exposes timeout_sec`); +} + +// Capture the remote command by injecting an SSH error and reading the message, +// or by stubbing — simplest: spy through a runner is not exposed here, so assert +// the default window via the schema + clamp contract above. Behavioral window +// threading is covered by clampSampleSeconds being the single source. +console.log('[PASS] ros2 echo/hz expose a clamped, widenable sampling window'); diff --git a/packages/dmoss-agent/test/task-frame-continuation.spec.mjs b/packages/dmoss-agent/test/task-frame-continuation.spec.mjs index 6dad28a..885a7c0 100644 --- a/packages/dmoss-agent/test/task-frame-continuation.spec.mjs +++ b/packages/dmoss-agent/test/task-frame-continuation.spec.mjs @@ -13,8 +13,34 @@ import { InMemorySessionStore, createOrUpdateTaskFrame, detectContinuationIntent, + recordTaskFrameAssistant, + recordTaskFrameToolEnd, } from '../dist/core/index.js'; +// Regression: a tool error the agent works around (write_file fails → exec +// succeeds → end_turn) must complete, NOT latch into paused_resumable with a +// stale "resolve write_file error" marker (this also wrongly blocked skill +// learning, which gates on status === 'completed'). +{ + let frame = createOrUpdateTaskFrame({ sessionKey: 's', runId: 'r', userMessage: 'create files a b c' }); + frame = recordTaskFrameToolEnd(frame, { toolName: 'write_file', result: 'EACCES permission denied', isError: true }); + assert.equal(frame.status, 'paused_resumable', 'an unrecovered error pauses the task'); + frame = recordTaskFrameToolEnd(frame, { toolName: 'exec', result: 'wrote file', isError: false }); + assert.equal(frame.status, 'active', 'a successful tool call resumes forward progress'); + assert.deepEqual(frame.pendingSteps, [], 'the worked-around error marker is cleared on success'); + frame = recordTaskFrameAssistant(frame, 'Done, all three files created.', 'end_turn'); + assert.equal(frame.status, 'completed', 'a worked-around error must not block completion'); +} + +// Guard the other direction: an error that is NOT worked around (error is the +// last tool, then end_turn) still pauses for resume. +{ + let frame = createOrUpdateTaskFrame({ sessionKey: 's', runId: 'r', userMessage: 'deploy the service' }); + frame = recordTaskFrameToolEnd(frame, { toolName: 'exec', result: 'connection refused', isError: true }); + frame = recordTaskFrameAssistant(frame, 'I hit an error and stopped.', 'end_turn'); + assert.equal(frame.status, 'paused_resumable', 'an unrecovered error at end_turn stays resumable'); +} + const GUARD_MARKER = '[dmoss-agent] Tool loop guard stopped'; function lastToolResultText(messages) { @@ -171,6 +197,36 @@ assert.equal(preserved.nextAction, 'Resolve or work around the latest read err') assert.equal(preserved.goal, '孵化桌宠'); assert.equal(preserved.status, 'paused_resumable'); +const unresolvedAfterAnswer = recordTaskFrameAssistant( + { + schemaVersion: 1, + sessionKey: 's', + runId: 'r3', + goal: '修复部署流程并验证', + constraints: [], + currentStep: 'Inspect failure', + completedSteps: ['Read deployment logs'], + pendingSteps: ['Run validation command'], + artifacts: [], + importantPaths: [], + toolFindings: [], + nextAction: 'Run validation command', + status: 'active', + source: 'user', + updatedAt: Date.now(), + }, + '我已经整理了排查结论', + 'end_turn', + Date.now(), +); +assert.equal( + unresolvedAfterAnswer.status, + 'paused_resumable', + 'assistant end_turn must not mark a task complete while explicit pending steps remain', +); +assert.deepEqual(unresolvedAfterAnswer.pendingSteps, ['Run validation command']); +assert.match(unresolvedAfterAnswer.nextAction, /Run validation command/); + const provider = new GuardThenResumeProvider(); const store = new InMemorySessionStore(); const calls = []; diff --git a/packages/dmoss-agent/test/tool-loop-guard.spec.mjs b/packages/dmoss-agent/test/tool-loop-guard.spec.mjs index 433c7e4..fb25489 100644 --- a/packages/dmoss-agent/test/tool-loop-guard.spec.mjs +++ b/packages/dmoss-agent/test/tool-loop-guard.spec.mjs @@ -58,21 +58,32 @@ function runHighVolumeLocalToolGuardTests() { 'unset tool-loop env should not create an implicit by-tool or total-count guard', ); } - for (let i = 0; i < 8; i += 1) { + for (let i = 0; i < 3; i += 1) { assert.equal( shouldShortCircuitToolCall(state, 'preset_probe', { value: 'same' }), null, - 'unset tool-loop env should not create an implicit identical-input guard', + 'default identical-input guard should allow a small retry budget', ); } - for (let i = 0; i < 8; i += 1) { + assert.match( + shouldShortCircuitToolCall(state, 'preset_probe', { value: 'same' }) ?? '', + /identical input was already requested 3 time/, + 'unset tool-loop env should conservatively stop the fourth identical call', + ); + for (let i = 0; i < 2; i += 1) { recordToolLoopOutcome(state, 'web_fetch', true); assert.equal( shouldShortCircuitToolCall(state, 'web_fetch', { value: `failed-${i}` }), null, - 'unset tool-loop env should not create an implicit repeated-failure guard', + 'default failure guard should allow a small retry budget', ); } + recordToolLoopOutcome(state, 'web_fetch', true); + assert.match( + shouldShortCircuitToolCall(state, 'web_fetch', { value: 'failed-2' }) ?? '', + /web_fetch has failed 3 time/, + 'unset tool-loop env should conservatively stop a repeatedly failing tool', + ); }); withEnv({ @@ -91,6 +102,30 @@ function runHighVolumeLocalToolGuardTests() { } }); + withEnv({ + DMOSS_TOOL_LOOP_IDENTICAL_LIMIT: '0', + DMOSS_TOOL_LOOP_SINGLE_TOOL_LIMIT: undefined, + DMOSS_TOOL_LOOP_TOTAL_LIMIT: undefined, + DMOSS_TOOL_LOOP_FAILURE_LIMIT: 'off', + }, () => { + const state = createToolLoopGuardState(); + for (let i = 0; i < 8; i += 1) { + assert.equal( + shouldShortCircuitToolCall(state, 'preset_probe', { value: 'same' }), + null, + 'explicit 0 should disable the default identical-input guard', + ); + } + for (let i = 0; i < 8; i += 1) { + recordToolLoopOutcome(state, 'web_fetch', true); + assert.equal( + shouldShortCircuitToolCall(state, 'web_fetch', { value: `failed-${i}` }), + null, + 'explicit off should disable the default repeated-failure guard', + ); + } + }); + withEnv({ DMOSS_TOOL_LOOP_IDENTICAL_LIMIT: 99, DMOSS_TOOL_LOOP_SINGLE_TOOL_LIMIT: 3, @@ -374,11 +409,12 @@ await runChatScenario( ); await runChatScenario( - 'invalid env values do not create hidden default limits', + 'invalid env values fall back to conservative defaults', [ { name: 'preset_probe', input: { value: 'same' } }, { name: 'preset_probe', input: { value: 'same' } }, { name: 'preset_probe', input: { value: 'same' } }, + { name: 'preset_probe', input: { value: 'same' } }, ], { DMOSS_TOOL_LOOP_IDENTICAL_LIMIT: 'not-a-number', @@ -387,9 +423,9 @@ await runChatScenario( DMOSS_TOOL_LOOP_FAILURE_LIMIT: undefined, }, ({ calls, result, messages }) => { - assert.equal(calls.length, 1, 'idempotent replay may reuse the result, but the hidden guard must stay off'); - assert.equal(result.response, 'done'); - assert.ok(!lastToolResultText(messages).includes(GUARD_MARKER)); + assert.equal(calls.length, 1, 'idempotent replay may reuse the result before the default guard trips'); + assert.equal(result.response, 'saw guard and pivoted'); + assert.ok(lastToolResultText(messages).includes(GUARD_MARKER)); }, ); diff --git a/packages/dmoss-skills/src/index.ts b/packages/dmoss-skills/src/index.ts index 4b401a0..9ca02ca 100644 --- a/packages/dmoss-skills/src/index.ts +++ b/packages/dmoss-skills/src/index.ts @@ -58,6 +58,7 @@ export { export { SkillPipeline, + DEFAULT_READONLY_TOOL_NAMES, type SkillPipelineConfig, type SkillPipelineResult, } from "./skill-pipeline.js"; diff --git a/packages/dmoss-skills/src/skill-pipeline.ts b/packages/dmoss-skills/src/skill-pipeline.ts index 57cdaab..1a6b34a 100644 --- a/packages/dmoss-skills/src/skill-pipeline.ts +++ b/packages/dmoss-skills/src/skill-pipeline.ts @@ -5,10 +5,41 @@ import { distillCandidate, type DistillResult } from "./skill-distiller.js"; import { promoteSkillCandidate, type PromoteResult } from "./skill-promoter.js"; import { isHighConfidence } from "./skill-scorer.js"; +/** + * Read-only / info-gathering tool names used by the low-value run gate. + * A run whose every distinct tool is in this set did no mutating or + * meaningful work and is not worth persisting as a skill candidate. Hosts + * that know each tool's authoritative `sideEffectClass` can override this via + * {@link SkillPipelineConfig.readonlyToolNames}; the defaults cover the + * well-known vendor-neutral read-only built-ins. Mutating/verifying tools + * (`exec`, `device_exec`, writes) are deliberately absent. + * @public + */ +export const DEFAULT_READONLY_TOOL_NAMES: readonly string[] = [ + "read", + "read_file", + "device_file_read", + "list_directory", + "search_files", + "search_code", + "glob", + "grep", + "memory_read", + "web_fetch", + "web_search", +]; + export interface SkillPipelineConfig { workspaceDir: string; model?: string; autoPromoteHighConfidence?: boolean; + /** + * Tool names treated as read-only info-gathering by the low-value run gate. + * Defaults to {@link DEFAULT_READONLY_TOOL_NAMES}. Pass the host's set of + * `sideEffectClass: 'readonly'` tool names to keep the gate authoritative + * without hard-coding a vendor workflow into core. + */ + readonlyToolNames?: readonly string[]; } export interface SkillPipelineResult { @@ -25,15 +56,32 @@ interface ExtractedToolCall { failed: boolean; } +/** + * True when the assistant's final text reads as a clarifying question rather + * than a completed result. Conservative and language-neutral: the trimmed + * text ends with a question mark (ASCII `?` or fullwidth `？`). Declarative + * results ("Done. …") are never matched. + */ +function isClarifyingQuestion(text: string): boolean { + const trimmed = text.trim(); + if (!trimmed) return false; + const last = trimmed[trimmed.length - 1]; + return last === "?" || last === "？"; +} + export class SkillPipeline { private readonly workspaceDir: string; private readonly model: string; private readonly autoPromote: boolean; + private readonly readonlyToolNames: ReadonlySet; constructor(config: SkillPipelineConfig) { this.workspaceDir = config.workspaceDir; this.model = config.model ?? "unknown"; this.autoPromote = config.autoPromoteHighConfidence ?? false; + this.readonlyToolNames = new Set( + (config.readonlyToolNames ?? DEFAULT_READONLY_TOOL_NAMES).map((n) => n.trim()), + ); } /** @@ -60,6 +108,15 @@ export class SkillPipeline { const assistantText = this.getLastAssistantText(messages); if (!userMessage || !assistantText) return null; + // Quality gate (host-neutral): skip persistence for low-value runs so the + // candidate store is not polluted by trivial info-gathering or + // clarification turns. Two signals, both derivable from evidence we have: + // (a) the assistant's final turn is a clarifying question — the task was + // not completed, it asked the user for more input; and + // (b) every distinct tool used is read-only info-gathering — no mutating + // or meaningful work happened. + if (this.isLowValueRun(toolCalls, assistantText)) return null; + const currentToolNames = [...new Set(toolCalls.map((tc) => tc.name))]; const sortedToolNamesKey = [...currentToolNames].sort().join("|"); @@ -119,6 +176,24 @@ export class SkillPipeline { }; } + /** + * True when a finished run is not worth persisting as a skill candidate: + * the assistant ended by asking a clarifying question, or every distinct + * tool used was read-only info-gathering with no mutating/meaningful work. + */ + private isLowValueRun( + toolCalls: ExtractedToolCall[], + assistantText: string, + ): boolean { + if (isClarifyingQuestion(assistantText)) return true; + const distinct = new Set(toolCalls.map((tc) => tc.name).filter(Boolean)); + if (distinct.size === 0) return true; + for (const name of distinct) { + if (!this.readonlyToolNames.has(name)) return false; + } + return true; + } + private extractToolCalls(messages: LLMMessage[]): ExtractedToolCall[] { const calls: ExtractedToolCall[] = []; const byId = new Map(); diff --git a/packages/dmoss-skills/test/skill-pipeline-quality-gate.spec.mjs b/packages/dmoss-skills/test/skill-pipeline-quality-gate.spec.mjs new file mode 100644 index 0000000..2d9febc --- /dev/null +++ b/packages/dmoss-skills/test/skill-pipeline-quality-gate.spec.mjs @@ -0,0 +1,129 @@ +#!/usr/bin/env node +/** + * Low-value run gate: SkillPipeline must NOT persist trivial info-gathering or + * clarification turns, but MUST still persist runs with mutating/meaningful work. + * Run: npm run build -w @rdk-moss/skills && node packages/dmoss-skills/test/skill-pipeline-quality-gate.spec.mjs + */ +import assert from 'node:assert/strict'; +import fs from 'node:fs/promises'; +import os from 'node:os'; +import path from 'node:path'; + +import { SkillPipeline } from '../dist/skill-pipeline.js'; + +function makeMessages(toolCalls, userText, assistantText) { + const msgs = [{ role: 'user', content: userText }]; + const assistantContent = []; + for (const tc of toolCalls) { + assistantContent.push({ + type: 'tool_use', + id: `call_${tc.name}_${Math.random().toString(36).slice(2, 8)}`, + name: tc.name, + input: tc.input || {}, + }); + } + assistantContent.push({ type: 'text', text: assistantText }); + msgs.push({ role: 'assistant', content: assistantContent }); + for (const tc of toolCalls) { + msgs.push({ + role: 'user', + content: [ + { + type: 'tool_result', + tool_use_id: assistantContent.find((b) => b.name === tc.name)?.id || '', + content: tc.failed ? 'error' : 'ok', + is_error: tc.failed || false, + }, + ], + }); + } + return msgs; +} + +async function countCandidates(dir) { + try { + const entries = await fs.readdir(path.join(dir, '.moss', 'skills', 'candidates'), { withFileTypes: true }); + return entries.filter((e) => e.isDirectory()).length; + } catch { + return 0; + } +} + +// (a) All read-only info-gathering ending in a clarifying question → skip. +{ + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-gate-a-')); + const pipeline = new SkillPipeline({ workspaceDir: tmp, model: 'test' }); + const messages = makeMessages( + [ + { name: 'memory_read', input: { query: 'board ip' } }, + { name: 'read_file', input: { path: '/etc/config' } }, + ], + 'How do I connect to the board?', + 'Which board are you targeting — the RDK X5 or the X3?', + ); + const result = await pipeline.processSession('gate-a', messages); + assert.equal(result, null, 'clarifying-question turn must not persist a candidate'); + assert.equal(await countCandidates(tmp), 0, 'no candidate dir should be written'); + await fs.rm(tmp, { recursive: true, force: true }); + console.log(' [PASS] skips all-readonly run that ends in a clarifying question'); +} + +// (b) All read-only info-gathering, declarative final text → still skip. +{ + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-gate-b-')); + const pipeline = new SkillPipeline({ workspaceDir: tmp, model: 'test' }); + const messages = makeMessages( + [ + { name: 'read_file', input: { path: '/a' } }, + { name: 'search_code', input: { query: 'foo' } }, + ], + 'Where is foo defined?', + 'foo is defined in src/foo.ts.', + ); + const result = await pipeline.processSession('gate-b', messages); + assert.equal(result, null, 'all-readonly info-gathering run must not persist a candidate'); + assert.equal(await countCandidates(tmp), 0, 'no candidate dir should be written'); + await fs.rm(tmp, { recursive: true, force: true }); + console.log(' [PASS] skips all-readonly info-gathering run (declarative text)'); +} + +// (c) Clarifying question even with a mutating tool → skip (task not finished). +{ + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-gate-c-')); + const pipeline = new SkillPipeline({ workspaceDir: tmp, model: 'test' }); + const messages = makeMessages( + [ + { name: 'read_file', input: { path: '/a' } }, + { name: 'write_file', input: { path: '/a', content: 'x' } }, + ], + 'Set up the deploy script', + 'Before I continue, should this target staging or production?', + ); + const result = await pipeline.processSession('gate-c', messages); + assert.equal(result, null, 'clarifying-question final turn must not persist even with a write'); + await fs.rm(tmp, { recursive: true, force: true }); + console.log(' [PASS] skips clarifying-question turn even with a mutating tool'); +} + +// (d) Control: read + mutating write, declarative result → STILL persists. +{ + const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'dmoss-gate-d-')); + const pipeline = new SkillPipeline({ workspaceDir: tmp, model: 'test' }); + const messages = makeMessages( + [ + { name: 'read_file', input: { path: '/tmp/config.yaml' } }, + { name: 'exec', input: { command: 'cat /tmp/config.yaml' } }, + { name: 'write_file', input: { path: '/tmp/config.yaml', content: 'updated' } }, + ], + 'Update the config file on the device', + 'Done. The config file has been updated successfully.', + ); + const result = await pipeline.processSession('gate-d', messages); + assert.ok(result, 'a run with mutating work and a declarative result must still persist'); + assert.ok(result.candidateId, 'should have a candidateId'); + assert.ok(await countCandidates(tmp) >= 1, 'a candidate dir should be written'); + await fs.rm(tmp, { recursive: true, force: true }); + console.log(' [PASS] still persists runs with mutating/meaningful work'); +} + +console.log('\nAll skill-pipeline quality-gate tests passed.');