ops-agent

第一次了解项目，先看中文设计概要；安装、配置和命令说明继续看本文档。

ops-agent is an AI operations CLI for diagnosing and maintaining Linux servers and macOS workstations. It is built on the reusable @chao.song/task-agent kernel. Task、Run、Session、SQLite、幂等和公共 CLI 生命周期由框架提供；本包只定义运维 Prompt、Tool 和风险策略。

The initial release supports system discovery, host file reads and writes, arbitrary approved Bash commands, persistent multi-turn sessions, per-operation approval, and process-scoped full-trust mode.

Requirements

• Node.js 22.19.0 or newer
• Linux or macOS
• An OpenAI-, Anthropic-, or Google-compatible model endpoint
• Normal host command availability for the requested probes (df, du, ps, ss/lsof/netstat, systemctl/launchctl, and journalctl/log as applicable)

Windows is not supported because Bash execution uses /bin/sh and the diagnostic tools target Linux and macOS.

Local installation from this repository

The package has not been published yet. To test the current source checkout:

npm install
npm run check
npm test
npm run build
npm link --workspace ops-agent
ops-agent --help

Remove the global development link with:

npm unlink -g ops-agent

After a public release, installation will be:

npm install -g ops-agent

Configure a model

init is optional. A complete environment-only configuration can run immediately:

export OPS_AGENT_BASE_URL="https://example.com/v1"
export OPS_AGENT_MODEL="model-name"
export OPS_AGENT_API_KEY="..."

ops-agent

The protocol defaults to OpenAI Chat Completions (openai-completions). openai-chat is accepted as an alias. Override it when needed:

export OPS_AGENT_PROTOCOL="anthropic-messages"

Product-specific variables have precedence over the config file. OPENAI_BASE_URL, OPENAI_MODEL, and OPENAI_API_KEY are also accepted as fallbacks when the corresponding OPS_AGENT_* variable is absent.

Supported environment variables:

OPS_AGENT_BASE_URL
OPS_AGENT_MODEL
OPS_AGENT_API_KEY
OPS_AGENT_PROTOCOL
OPS_AGENT_PROVIDER
OPS_AGENT_API_KEY_ENV
OPS_AGENT_TASKS_DIR
OPS_AGENT_CONTEXT_WINDOW
OPS_AGENT_MAX_TOKENS
OPS_AGENT_REASONING

OPS_AGENT_REASONING accepts true, false, 1, or 0.

You can persist a baseline configuration with init:

export OPS_AGENT_API_KEY="..."

ops-agent init \
  --base-url https://example.com/v1 \
  --protocol openai-completions \
  --model model-name

Running init again performs an incremental update. Explicit flags replace their corresponding values; omitted fields remain unchanged. For example, this changes only the model:

ops-agent init --model another-model

Use --reasoning to enable reasoning and --no-reasoning to disable a previously enabled value.

Supported protocol values are:

• openai-completions
• openai-responses
• anthropic-messages
• google-generative-ai

Optional initialization flags include --provider, --api-key-env, --api-key, --tasks-dir, --context-window, --max-tokens, --reasoning, and --no-reasoning.

--api-key stores the key in the product config and may expose it in shell history and process listings. The environment-variable flow avoids persisting the key value. Runtime environment overrides are not written back over an existing config file; only normal task metadata such as lastTask is updated.

Configuration is stored at ${XDG_CONFIG_HOME:-~/.config}/ops-agent/config.json with mode 0600. Task sessions default to ${XDG_DATA_HOME:-~/.local/share}/ops-agent/tasks, with private task directories and append-only event logs. 每个 Task 的正式控制状态位于 state/kernel.sqlite；Pi Session JSONL 和 events.jsonl 是会话/诊断记录，不是 Task 状态事实源。

Use the Agent

Start a persistent interactive session:

ops-agent

Run a single prompt:

ops-agent "检查 CPU、内存、磁盘和进程压力，不要修改系统"
ops-agent create "检查 nginx 状态和最近 30 分钟日志" --task nginx-001
ops-agent run "检查 nginx 状态和最近 30 分钟日志"

Continue and inspect tasks:

ops-agent continue --task <task-id> "继续定位根因"
ops-agent resume "继续定位根因"
ops-agent resume --task <task-id> "验证修复结果"
ops-agent status --task <task-id>
ops-agent wait --task <task-id>

run 是 create 的别名，resume 是 continue 的别名。它们调用同一个 TaskApplicationService，不会形成另一套状态或 Session。

当前 ops Scenario 没有 Durable Tool，因此虽然公共 CLI 会显示 jobs、work 和 cancel-job，正常 ops Task 不会创建 Job。ops-agent 也没有启用 media-agent 的 serve 命令；大多数运维 Tool 在一个前台 Run 内同步完成。

Clear managed local data

clear removes only local data managed by ops-agent:

ops-agent clear task --task <task-id>
ops-agent clear tasks
ops-agent clear config
ops-agent clear all

Preview exact paths and sizes without deleting:

ops-agent clear all --dry-run

Interactive deletion asks for confirmation. Non-interactive deletion is refused unless --yes (or -y) is present:

ops-agent clear tasks --yes

Scopes:

• task: one task directory selected by --task
• tasks: all valid direct task directories under the configured tasks directory; configuration is retained
• config: ${XDG_CONFIG_HOME:-~/.config}/ops-agent/config.json; task data is retained
• all: all managed task directories plus the product config file

The command refuses active tasks, unreadable run locks, symbolic-link task directories, and paths outside the managed roots. It preflights all selected targets before deleting any of them.

clear all does not mean "remove every trace." It does not remove files created or modified through host_write_file or Bash, shell history, npm installation/link state, operating-system logs, audit logs, backups, remote-host changes, or model-provider request logs. Those resources are outside the product's managed data boundary.

During a model or tool run:

• Esc aborts the current run, terminates an active Bash process group, preserves the session, and returns to the interactive prompt.
• Ctrl+C exits the CLI.
• /exit and /quit exit from the interactive prompt.
• ops-agent abort --task <task-id> requests cancellation of a background run or a run controlled from another terminal.

Approval and trust

The default mode is ask:

ops-agent
ops-agent run "restart nginx"

Approval behavior:

| Capability | Default ask mode | | --- | --- | | System, filesystem, process, port, service, and log probes | Runs without confirmation | | Ordinary bounded host file read | Runs without confirmation | | Read from a commonly sensitive path | Requires confirmation | | Host file write or append | Requires confirmation with path and content preview | | Arbitrary Bash command | Requires confirmation with command and working directory |

Operations requiring approval are denied when no TTY is available. A denial is final for that tool call.

Full trust skips every confirmation for the current CLI process only:

ops-agent --trust full
ops-agent run "apply the approved fix and verify it" --trust full

Full trust is not persisted. It gives the model the effective host access of the user running ops-agent; use it only with a trusted prompt, model endpoint, and machine context.

The audit log still records approval-policy checks in full-trust mode. These decisions are marked with policy: "full" and implicit: true; they do not represent an interactive terminal confirmation.

Operations capabilities

The built-in tools are:

• system_snapshot: OS, CPU, load, uptime, memory, and Linux memory-pressure facts
• filesystem_usage: mounted filesystem capacity and inode usage
• disk_hotspots: largest direct children under selected host roots
• process_snapshot: bounded process list sorted by CPU or memory
• listening_ports: listening TCP/UDP sockets and owning processes when available
• service_status: systemd or launchd service state
• recent_service_logs: bounded journald or macOS unified log window
• host_read_file: bounded UTF-8 reads from absolute host paths
• host_write_file: approved UTF-8 overwrite or append to absolute host paths
• bash: approved arbitrary /bin/sh -lc command execution

Bash runs with no stdin and no pseudo-terminal. Commands requiring an interactive password, terminal UI, or interactive sudo prompt will not work unless configured for non-interactive execution. SSH can be invoked through Bash and SSH_AUTH_SOCK is retained, but remote observations must be identified as remote by the Agent.

Credential-like environment variable names containing terms such as KEY, TOKEN, SECRET, PASSWORD, CREDENTIAL, or AUTH are removed from Bash subprocesses. This is defense in depth, not a secret-isolation guarantee; commands can still read files and other host resources available to the invoking user.

Safety boundary

ops-agent is not a sandbox. Approval prompts, path checks, output bounds, timeouts, and process cancellation reduce accidental harm but do not isolate arbitrary shell execution from the host.

For higher-risk use, run it as a dedicated non-root OS account or inside a container with explicit mounts, resource limits, and network policy. Do not expose a writable home directory, SSH credentials, cloud credentials, or a Docker socket to an untrusted prompt or model endpoint.

Host writes refuse final symbolic links, preserve the permissions of existing regular files, and create new files with mode 0600. These checks do not replace OS isolation or backups.

Task lifecycle and recovery

一次运维请求是一个 Run，长期排查由多个 Run 组成：

Task create
-> Run 1 取证并请求补充信息
-> Task waiting
-> continue
-> Run 2 执行进一步诊断或获批变更
-> complete_task / fail_task

Run 必须通过 Kernel control Tool 明确结束。自然停止会形成可恢复的 missing_run_disposition，而不是误报成功。进程退出后，Task 状态、waiting 原因和 Session 路径可以从 SQLite 恢复。

Esc 中止当前 Run 并保留 Session；它不回滚已经完成的主机修改。任何变更都必须在执行前设计验证和回滚，并在执行后用 Tool 结果确认。

Known limitations

• The current runtime dependency @earendil-works/[email protected] contains [email protected], affected by GHSA-mh99-v99m-4gvg (unbounded brace expansion denial of service). Default Pi extensions and resource discovery are disabled, reducing the reachable surface, but the vulnerable package remains installed. Upgrade is blocked until Pi publishes a fixed version and the runtime contract suite passes.
• Bash is non-interactive and does not provide a pseudo-terminal.
• Diagnostics depend on host commands and permissions; unavailable or restricted probes return structured failures rather than fabricated results.
• Sessions 和 Task 状态是本机持久化数据，不是分布式调度系统。ops Scenario 当前没有 Durable background Tool。
• This version has automated Linux/macOS-oriented tool tests, but should be soaked on representative workstations and servers before production use.