nonoka-cli 0.1.0__tar.gz → 0.2.2__tar.gz

{nonoka_cli-0.1.0 → nonoka_cli-0.2.2}/.gitignore

@@ -40,10 +40,20 @@ MANIFEST
 .coverage
 htmlcov/
 .tox/
+.codegraph/
+.ruff_cache/
 
 # OS
 .DS_Store
 Thumbs.db
 
 # Logs
-*.log
+*.log
+
+node_modules/
+dist/
+nonoka-cli-prev/
+
+# Private planning documents
+DESIGN.md
+REFACTOR.md

nonoka_cli-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fyerfyer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nonoka_cli-0.2.2/NOTICE

@@ -0,0 +1,41 @@
+nonoka-cli — OpenCode backend for the Nonoka Agent framework
+
+Copyright (c) 2026 fyerfyer
+
+This project is licensed under the MIT License (see LICENSE).
+
+Third-party software and attribution
+-------------------------------------
+
+1. OpenCode
+   - Repository: https://github.com/anomalyco/opencode
+   - License: MIT
+   - Copyright: OpenCode team and contributors
+   - The terminal TUI, desktop application, and OpenCode server/client
+     architecture are provided by OpenCode. nonoka-cli does not modify
+     OpenCode source code; it integrates via OpenCode's custom provider
+     mechanism and the Vercel AI SDK provider interface.
+
+2. Vercel AI SDK
+   - Repository: https://github.com/vercel/ai
+   - License: Apache License 2.0
+   - nonoka-opencode-provider implements the Vercel AI SDK provider API.
+
+3. LiteLLM
+   - Repository: https://github.com/BerriAI/litellm
+   - License: MIT
+   - Used by the underlying nonoka Agent framework for multi-provider LLM calls.
+
+4. MCP (Model Context Protocol)
+   - Repository: https://github.com/modelcontextprotocol
+   - License: MIT
+   - Used for tool server integration.
+
+Agent core
+----------
+The conversational agent core, execution engine, checkpoint/memory system,
+and tool framework are provided by the Nonoka Python Agent framework
+(https://pypi.org/project/nonoka/), independently developed by fyerfyer.
+
+This NOTICE file is provided for attribution purposes. If you distribute
+binaries or derivative works, please keep the above notices intact.

nonoka_cli-0.2.2/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: nonoka-cli
+Version: 0.2.2
+Summary: OpenCode backend for the Nonoka Agent framework
+License: MIT
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Requires-Dist: nonoka>=1.3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: structlog>=24.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# nonoka-cli
+
+OpenCode backend for the [Nonoka](https://pypi.org/project/nonoka/) Agent framework.
+
+`nonoka-cli` runs as a stdio NDJSON bridge server (`nonoka-cli --server`) that
+talks to the `nonoka-opencode-provider` TypeScript package. OpenCode uses the
+provider to drive Nonoka agents, with full support for tool cards and
+human-in-the-loop (HITL) approval.
+
+## Quick install
+
+The easiest way to get nonoka + OpenCode is the one-line installer:
+
+```bash
+curl -fsSL https://nonoka.dev/install.sh | bash
+```
+
+The installer will:
+
+1. Check Python 3.10+ and Node/npm.
+2. Install or update OpenCode.
+3. Install `nonoka-cli` and the OpenCode provider.
+4. Generate `~/.config/nonoka/config.yaml` and `~/.config/opencode/opencode.json`.
+
+After installing, configure your API key and run `opencode`:
+
+```bash
+# Interactive: it will ask for your key and save it to ~/.config/nonoka/.env
+nonoka-cli config init
+
+# Or set it manually
+export DEEPSEEK_API_KEY=<your-key>
+
+nonoka-cli doctor
+opencode
+```
+
+`nonoka-cli` automatically loads `~/.config/nonoka/.env` and `./.env` on startup,
+so you don't need to `export` every time if you save the key in `.env`.
+
+> To use `uv` instead of `pip`, or to run non-interactively, pass flags:
+> `curl -fsSL https://nonoka.dev/install.sh | bash -s -- --uv --yes`.
+
+## Manual installation
+
+```bash
+# Install nonoka-cli
+pip install nonoka-cli
+# or with uv
+uv pip install nonoka-cli
+
+# Install the OpenCode provider globally so OpenCode can load it
+npm install -g nonoka-opencode-provider
+```
+
+## Quick start
+
+1. Create your nonoka config (it will ask for your API key and save it to
+   `~/.config/nonoka/.env`):
+
+```bash
+nonoka-cli config init
+```
+
+For scripted setups, use the non-interactive mode (you'll still need to set the
+API key via `.env` or `export`):
+
+```bash
+nonoka-cli config init --yes --model deepseek-chat
+```
+
+2. Generate an OpenCode config in the current project or globally:
+
+```bash
+# Project-level
+nonoka-cli opencode init
+
+# User-level
+nonoka-cli opencode init --global
+```
+
+3. Make sure your model API key is exported, then run:
+
+```bash
+opencode
+```
+
+## `nonoka-cli doctor`
+
+Diagnose your installation and configuration:
+
+```bash
+nonoka-cli doctor
+```
+
+Example output:
+
+```
+nonoka-cli doctor
+✓ nonoka-cli 0.2.1
+✓ Python 3.11
+✓ opencode 1.16.2
+✓ provider nonoka-opencode-provider@0.2.0
+✓ config ~/.config/nonoka/config.yaml
+✓ API key DEEPSEEK_API_KEY set
+✓ OpenCode provider config in /home/user/.config/opencode/opencode.json
+```
+
+If anything is wrong, `doctor` prints a remedy line. To also verify the LLM API
+key with a real (small) call, use:
+
+```bash
+nonoka-cli doctor --check-llm
+```
+
+## Configuration
+
+### `nonoka-cli config init`
+
+Interactive wizard that writes `~/.config/nonoka/config.yaml`. It asks for a
+model identifier (e.g. `deepseek-chat`, `openai/gpt-4o`, `ollama/llama3.3`), a
+masked API key, and whether to save it to `~/.config/nonoka/.env` (recommended),
+directly in `config.yaml`, or skip saving. It also asks for a system prompt and
+whether to auto-approve all tool calls.
+
+Non-interactive example:
+
+```bash
+nonoka-cli config init --yes --model openai/gpt-4o
+```
+
+### `nonoka-cli config set <key> <value>`
+
+Update a single config value. Dotted keys are supported:
+
+```bash
+nonoka-cli config set model openai/gpt-4o
+nonoka-cli config set cli.theme light
+nonoka-cli config set hitl.dangerous_tools '["write_file", "execute_command"]'
+```
+
+### `nonoka-cli config show`
+
+Print the resolved configuration and its file path.
+
+### `nonoka-cli opencode init`
+
+Generate or merge an `opencode.json` in the current directory. The generated
+config points OpenCode at the `nonoka-opencode-provider` package and passes the
+nonoka config path to the backend.
+
+## OpenCode configuration
+
+A typical generated `opencode.json` looks like:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nonoka/default",
+  "provider": {
+    "nonoka": {
+      "npm": "nonoka-opencode-provider",
+      "name": "Nonoka",
+      "options": {
+        "serverCommand": ["nonoka-cli", "--server"],
+        "cwd": ".",
+        "configPath": "~/.config/nonoka/config.yaml"
+      },
+      "models": {
+        "default": { "name": "Nonoka deepseek-chat" }
+      }
+    }
+  },
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+## Human-in-the-loop
+
+When a tool call matches the `hitl.dangerous_tools` list in `nonoka.yaml`,
+nonoka pauses the turn and sends a `tool-approval-request` to OpenCode.
+OpenCode shows the tool card with an approval dialog; after the user decides,
+nonoka resumes the turn, executes approved tools, and returns the final answer.
+
+Example `nonoka.yaml`:
+
+```yaml
+model: "deepseek-chat"
+
+cli:
+  auto_approve: false
+
+hitl:
+  policy: interactive
+  dangerous_tools:
+    - write_file
+    - edit_file
+    - delete_file
+    - execute_command
+```
+
+Set `cli.auto_approve: true` (or `hitl.policy: auto`) to skip approval dialogs.
+
+## Development
+
+```bash
+# Install in editable mode
+uv pip install -e .
+
+# Run the bridge server
+nonoka-cli --server --config ./nonoka.yaml
+
+# Lint and test
+uv run --no-sync ruff check .
+uv run --no-sync pytest tests/unit
+```
+
+## Project layout
+
+```text
+src/nonoka_cli/
+├── bridge/          # NDJSON protocol, request handler, server
+├── commands/        # CLI subcommands (config, doctor, opencode)
+├── config/          # YAML config loading and Pydantic models
+├── core/            # Orchestrator, RunnerService, SessionService, ToolService, MCPService
+├── mcp/             # MCP server lifecycle manager
+├── sessions/        # Session metadata persistence
+├── skills/          # Skill loading and application
+├── tools/           # Built-in and local tool loader
+└── utils/           # Errors, logging
+
+packages/nonoka-opencode-provider/  # TypeScript provider for OpenCode
+install.sh                          # One-line installer
+```
+
+## License and attribution
+
+`nonoka-cli` and `nonoka-opencode-provider` are released under the MIT License.
+
+The terminal TUI and OpenCode client/server architecture are provided by
+[OpenCode](https://github.com/anomalyco/opencode) (MIT License). The agent
+core is provided by the [Nonoka](https://pypi.org/project/nonoka/) framework.
+
+See `LICENSE` and `NOTICE` for full details.

nonoka_cli-0.2.2/README.md

@@ -0,0 +1,247 @@
+# nonoka-cli
+
+OpenCode backend for the [Nonoka](https://pypi.org/project/nonoka/) Agent framework.
+
+`nonoka-cli` runs as a stdio NDJSON bridge server (`nonoka-cli --server`) that
+talks to the `nonoka-opencode-provider` TypeScript package. OpenCode uses the
+provider to drive Nonoka agents, with full support for tool cards and
+human-in-the-loop (HITL) approval.
+
+## Quick install
+
+The easiest way to get nonoka + OpenCode is the one-line installer:
+
+```bash
+curl -fsSL https://nonoka.dev/install.sh | bash
+```
+
+The installer will:
+
+1. Check Python 3.10+ and Node/npm.
+2. Install or update OpenCode.
+3. Install `nonoka-cli` and the OpenCode provider.
+4. Generate `~/.config/nonoka/config.yaml` and `~/.config/opencode/opencode.json`.
+
+After installing, configure your API key and run `opencode`:
+
+```bash
+# Interactive: it will ask for your key and save it to ~/.config/nonoka/.env
+nonoka-cli config init
+
+# Or set it manually
+export DEEPSEEK_API_KEY=<your-key>
+
+nonoka-cli doctor
+opencode
+```
+
+`nonoka-cli` automatically loads `~/.config/nonoka/.env` and `./.env` on startup,
+so you don't need to `export` every time if you save the key in `.env`.
+
+> To use `uv` instead of `pip`, or to run non-interactively, pass flags:
+> `curl -fsSL https://nonoka.dev/install.sh | bash -s -- --uv --yes`.
+
+## Manual installation
+
+```bash
+# Install nonoka-cli
+pip install nonoka-cli
+# or with uv
+uv pip install nonoka-cli
+
+# Install the OpenCode provider globally so OpenCode can load it
+npm install -g nonoka-opencode-provider
+```
+
+## Quick start
+
+1. Create your nonoka config (it will ask for your API key and save it to
+   `~/.config/nonoka/.env`):
+
+```bash
+nonoka-cli config init
+```
+
+For scripted setups, use the non-interactive mode (you'll still need to set the
+API key via `.env` or `export`):
+
+```bash
+nonoka-cli config init --yes --model deepseek-chat
+```
+
+2. Generate an OpenCode config in the current project or globally:
+
+```bash
+# Project-level
+nonoka-cli opencode init
+
+# User-level
+nonoka-cli opencode init --global
+```
+
+3. Make sure your model API key is exported, then run:
+
+```bash
+opencode
+```
+
+## `nonoka-cli doctor`
+
+Diagnose your installation and configuration:
+
+```bash
+nonoka-cli doctor
+```
+
+Example output:
+
+```
+nonoka-cli doctor
+✓ nonoka-cli 0.2.1
+✓ Python 3.11
+✓ opencode 1.16.2
+✓ provider nonoka-opencode-provider@0.2.0
+✓ config ~/.config/nonoka/config.yaml
+✓ API key DEEPSEEK_API_KEY set
+✓ OpenCode provider config in /home/user/.config/opencode/opencode.json
+```
+
+If anything is wrong, `doctor` prints a remedy line. To also verify the LLM API
+key with a real (small) call, use:
+
+```bash
+nonoka-cli doctor --check-llm
+```
+
+## Configuration
+
+### `nonoka-cli config init`
+
+Interactive wizard that writes `~/.config/nonoka/config.yaml`. It asks for a
+model identifier (e.g. `deepseek-chat`, `openai/gpt-4o`, `ollama/llama3.3`), a
+masked API key, and whether to save it to `~/.config/nonoka/.env` (recommended),
+directly in `config.yaml`, or skip saving. It also asks for a system prompt and
+whether to auto-approve all tool calls.
+
+Non-interactive example:
+
+```bash
+nonoka-cli config init --yes --model openai/gpt-4o
+```
+
+### `nonoka-cli config set <key> <value>`
+
+Update a single config value. Dotted keys are supported:
+
+```bash
+nonoka-cli config set model openai/gpt-4o
+nonoka-cli config set cli.theme light
+nonoka-cli config set hitl.dangerous_tools '["write_file", "execute_command"]'
+```
+
+### `nonoka-cli config show`
+
+Print the resolved configuration and its file path.
+
+### `nonoka-cli opencode init`
+
+Generate or merge an `opencode.json` in the current directory. The generated
+config points OpenCode at the `nonoka-opencode-provider` package and passes the
+nonoka config path to the backend.
+
+## OpenCode configuration
+
+A typical generated `opencode.json` looks like:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "model": "nonoka/default",
+  "provider": {
+    "nonoka": {
+      "npm": "nonoka-opencode-provider",
+      "name": "Nonoka",
+      "options": {
+        "serverCommand": ["nonoka-cli", "--server"],
+        "cwd": ".",
+        "configPath": "~/.config/nonoka/config.yaml"
+      },
+      "models": {
+        "default": { "name": "Nonoka deepseek-chat" }
+      }
+    }
+  },
+  "permission": {
+    "edit": "ask",
+    "bash": "ask"
+  }
+}
+```
+
+## Human-in-the-loop
+
+When a tool call matches the `hitl.dangerous_tools` list in `nonoka.yaml`,
+nonoka pauses the turn and sends a `tool-approval-request` to OpenCode.
+OpenCode shows the tool card with an approval dialog; after the user decides,
+nonoka resumes the turn, executes approved tools, and returns the final answer.
+
+Example `nonoka.yaml`:
+
+```yaml
+model: "deepseek-chat"
+
+cli:
+  auto_approve: false
+
+hitl:
+  policy: interactive
+  dangerous_tools:
+    - write_file
+    - edit_file
+    - delete_file
+    - execute_command
+```
+
+Set `cli.auto_approve: true` (or `hitl.policy: auto`) to skip approval dialogs.
+
+## Development
+
+```bash
+# Install in editable mode
+uv pip install -e .
+
+# Run the bridge server
+nonoka-cli --server --config ./nonoka.yaml
+
+# Lint and test
+uv run --no-sync ruff check .
+uv run --no-sync pytest tests/unit
+```
+
+## Project layout
+
+```text
+src/nonoka_cli/
+├── bridge/          # NDJSON protocol, request handler, server
+├── commands/        # CLI subcommands (config, doctor, opencode)
+├── config/          # YAML config loading and Pydantic models
+├── core/            # Orchestrator, RunnerService, SessionService, ToolService, MCPService
+├── mcp/             # MCP server lifecycle manager
+├── sessions/        # Session metadata persistence
+├── skills/          # Skill loading and application
+├── tools/           # Built-in and local tool loader
+└── utils/           # Errors, logging
+
+packages/nonoka-opencode-provider/  # TypeScript provider for OpenCode
+install.sh                          # One-line installer
+```
+
+## License and attribution
+
+`nonoka-cli` and `nonoka-opencode-provider` are released under the MIT License.
+
+The terminal TUI and OpenCode client/server architecture are provided by
+[OpenCode](https://github.com/anomalyco/opencode) (MIT License). The agent
+core is provided by the [Nonoka](https://pypi.org/project/nonoka/) framework.
+
+See `LICENSE` and `NOTICE` for full details.

nonoka_cli-0.2.2/TODO.md

@@ -0,0 +1,77 @@
+# nonoka-cli / OpenCode Provider — 已知未实现项
+
+> 当前为 Phase 1 验证版本，端到端文本回复已跑通。下面列出还需要补全或优化的地方，供后续迭代参考。
+
+## 1. OpenCode Provider 层
+
+### 1.1 Tool-call / Tool-result 透传
+- 现状：provider 只处理 `text_delta`、`finish`、`error` 三种 NDJSON 事件。
+- nonoka 后端自己有一个工具循环（read/bash/grep 等），它调用工具后会把结果写回自己的上下文，然后继续生成文本。
+- 问题：OpenCode 看不到 nonoka 的工具调用过程，也无法用 OpenCode 统一的工具权限/审批去管理。
+- 目标：把 nonoka 的 `tool_call` / `tool_result` 事件映射为 Vercel AI SDK 的 `tool-call` / `tool-result` stream parts，让 OpenCode 接管工具循环；或者提供一个开关让 nonoka 在 server 模式下禁用自带工具。
+
+### 1.2 Session 持久化
+- 现状：provider 每次 `doStream` 都会 `spawn` 一个新的 `nonoka-cli --server` 进程，旧的 session 上下文随着进程退出而丢失。
+- 影响：多轮对话时 nonoka 后端无法记住之前的对话内容（虽然 OpenCode 会把历史消息拼进 prompt，但 nonoka 内部的 agent 状态会丢失）。
+- 目标：让 provider 复用同一个 long-running server 进程，或在 `session_init` 后通过持久化存储恢复 session。
+
+### 1.3 错误与取消处理
+- `abortSignal` 目前会 kill 子进程，但 nonoka 后端对 SIGTERM/SIGKILL 的清理逻辑未充分测试。
+- 需要规范 `error` 事件的格式，并在 provider 里生成正确的 `error` stream part。
+- 子进程 stdout 解析失败的行当前被静默丢弃，应该记录日志或抛出。
+
+### 1.4 构建与分发
+- 当前只有 ESM 输出（`tsc` 编译到 `dist/`）。
+- 建议增加 CJS / dual-build，或直接用 `bun build` 打成单文件 bundle，避免用户环境里出现 `@ai-sdk/provider` 等依赖解析问题。
+- `package.json` 需要补齐 `exports`、`keywords`、`repository`、`bugs`、`homepage` 等字段。
+
+### 1.5 Provider 配置校验
+- `serverCommand` 目前支持字符串和数组，但没有校验命令是否为空、是否可执行。
+- `configPath` / `cwd` 等路径未做 exists 检查。
+- 建议用 `zod` 做一次配置 schema 校验。
+
+## 2. nonoka-cli `--server` 后端
+
+### 2.1 协议扩展
+- 当前 NDJSON 协议只有 `chat` 请求和 `session_init` / `text_delta` / `finish` / `error` 响应。
+- 需要增加：
+  - `tool_call` / `tool_result` 事件（配合 1.1）。
+  - `approval_request` / `approval_response` 事件，让 OpenCode 侧决定敏感操作。
+  - `thinking` / `reasoning` 事件（如果模型支持）。
+  - `usage` 字段（input/output tokens），让 OpenCode 统计消耗。
+
+### 2.2 并发与生命周期
+- `BridgeServer` 目前一个进程只处理一条请求然后退出。
+- 需要支持多条 NDJSON 请求顺序或并发处理，并正确维护 Orchestrator 生命周期。
+- 需要处理客户端断开、stdin EOF、子进程异常退出等边界情况。
+
+### 2.3 配置与模型
+- `nonoka.yaml` 里的 `model: deepseek-chat` 在 LiteLLM 某些版本下需要写成 `deepseek/deepseek-chat`。
+- 建议把 provider / base_url / api_key 也显式暴露到配置里，而不是只依赖环境变量。
+
+## 3. OpenCode 集成体验
+
+### 3.1 本地路径 vs npm 包名
+- 现在 `opencode.json` 里用绝对路径指向 provider 包，只是为了避免 OpenCode 去 npm registry 安装时卡死（当前环境有代理问题）。
+- 发布 npm 后应改回 `"npm": "@nonoka/opencode-provider"`，并验证 OpenCode 能自动安装。
+
+### 3.2 模型元数据
+- `models.default` 目前只有 `name`。
+- 应补齐 `limit.context`、`limit.output`、`modalities` 等，让 OpenCode 正确计算上下文窗口和费用。
+
+### 3.3 TUI 验证
+- 目前主要用 `opencode run` 非交互验证。
+- 需要在 TUI 里手动验证 `/models` 选择、`/connect` 流程、多轮对话渲染等。
+
+## 4. 测试
+
+- [ ] provider 单元测试（stream transformer、协议编解码）。
+- [ ] `nonoka-cli --server` 端到端测试（发送 NDJSON 请求，断言事件顺序）。
+- [ ] OpenCode 集成测试（用本地 registry 安装 provider 后跑 `opencode run`）。
+- [ ] 错误场景测试（无效命令、模型不可用、网络超时）。
+
+## 5. 文档
+
+- [ ] provider README（安装、配置、options 说明）。
+- [ ] nonoka-cli README 增加 `--server` 模式说明。
+- [ ] OpenCode 配置示例（本地路径 / npm 包名 / 私有 registry）。