update-config

name	Update Config
description	Safely update Nexo config files with read-before-write merges, schema-aware mapping, and reload/restart awareness.
requires	{"bins":[],"env":[]}

Update Config

Update Nexo configuration intentionally and safely. Prefer minimal, reversible patches that preserve existing structure and comments.

Use when

• User asks to change runtime behavior through config instead of code.
• You need to edit files under config/ or config/plugins/.
• You must wire skills/tools/models/bindings with explicit YAML changes.

Do not use when

• The request is a source-code behavior change (edit Rust/TS files instead).
• The target setting cannot be mapped confidently to a known config file.
• The user asks only for one-off runtime commands with no config change needed.

Input contract

• request (required): desired behavior change.
• target_scope (optional): agent | llm | runtime | plugin | mcp | memory | tool_policy | explicit_file.
• target_file (optional): required when target_scope=explicit_file.
• merge_mode (optional): append_idempotent (default) or replace.
• confirm_before_write (optional): default true for ambiguous or high-impact edits.
• trigger_reload (optional): default true for hot-reloadable files.

Mapping rules

Prefer this mapping order:

1. Agent-level behavior (skills, allowed_tools, system_prompt, inbound_bindings, model.model, web_search, link_understanding) -> config/agents.yaml or config/agents.d/<agent>.yaml
2. Provider/auth/retry defaults -> config/llm.yaml
3. Reload watcher/migration/runtime knobs -> config/runtime.yaml
4. MCP client servers -> config/mcp.yaml
5. Plugin instance config -> config/plugins/<plugin>.yaml
6. Memory backend/vector knobs -> config/memory.yaml
7. Tool policy / gate rules -> config/tool_policy.yaml

If the request cannot be mapped unambiguously, ask the user before writing.

Hot-reload vs restart

• Usually hot-reloadable: config/agents.yaml, config/agents.d/**, config/llm.yaml, config/runtime.yaml.
• Usually restart-required: config/plugins/*.yaml, config/mcp.yaml, config/memory.yaml, config/broker.yaml, config/extensions.yaml, plus structural agent changes (id, plugins, workspace, skills_dir).

After writing:

• if hot-reloadable: recommend agent reload (or rely on watcher),
• else: state explicitly that daemon restart is required.

Canonical workflow

1. Clarify intent
   • Restate the requested behavior in concrete config terms.
2. Resolve target file(s)
   • Map request -> file path(s) using rules above.
3. Read before write
   • Load current file content first; never blind-overwrite.
4. Prepare minimal merge patch
   • Preserve unrelated keys and comments.
   • For arrays, default to idempotent append unless user requested replace.
5. Apply edit
   • Write only the required keys/values.
6. Validate
   • Check YAML/shape consistency (for example agent --check-config).
7. Finalize
   • Report exact file changes + reload/restart action required.

Guardrails

• Never replace whole config files when a minimal patch is possible.
• Never inline secrets in YAML when ${file:...} or env refs are expected.
• Never drop existing array entries unless user asked for replacement.
• Never claim live effect without stating hot-reload vs restart requirement.
• If validation fails, stop and report corrective action before proceeding.

Output format

Always return:

• status: applied | proposed | needs_user_input | validation_failed
• mapped_targets: list of file paths with rationale
• changes: concrete key-level mutations
• validation: checks executed and result
• activation: hot_reload or restart_required
• next_action: required unless status=applied

Examples

• request="attach verify + stuck skills to agent ana"
• request="enable web_search tavily for ana binding"
• request="increase llm retry backoff" target_scope="llm"
• request="add whatsapp instance for sales bot" target_scope="plugin"