@soloco/client 0.1.0-canary.20260620104728

package/LICENSE

@@ -0,0 +1,30 @@
+Soloco Proprietary License
+
+Copyright (c) 2026 Soloco. All rights reserved.
+
+This software and its accompanying source code, documentation, assets, and
+configuration files are proprietary to Soloco.
+
+Soloco is not open source software. No license is granted to copy, modify,
+publish, distribute, sublicense, sell, host, or otherwise make this software
+available to any third party except as expressly authorized in writing by
+Soloco.
+
+Authorized users may install, run, and modify this software solely for Soloco's
+internal product development, testing, deployment, and operation.
+
+You may not:
+
+- Redistribute this repository or any substantial portion of it.
+- Publish the source code, packaged builds, templates, components, or derived
+  starter kits.
+- Use this software to create or offer a competing product based on Soloco's
+  proprietary source code, architecture, or product materials.
+- Remove or obscure copyright, license, or proprietary notices.
+- Reverse engineer, decompile, or attempt to extract source code from packaged
+  builds except where applicable law expressly prohibits this restriction.
+
+All rights not expressly granted are reserved by Soloco.
+
+If you believe you have received this software without authorization, stop using
+it and contact the Soloco project owner.

package/README.md

@@ -0,0 +1,60 @@
+# Soloco 客户端 daemon
+
+本地执行权威(architecture §3.1)。维护任务树/状态机/事件/产物,调度,通过 Adapter 启停本地 agent runtime。
+
+本目录以 `@soloco/client` 之名发布到 npm，是面向终端用户的客户端包；装好后命令行入口是 `soloco`。
+
+## 安装与使用（npm）
+
+需要 **Node ≥ 22.5**（用到内置 `node:sqlite`）。
+
+```bash
+# 不安装直接试（推荐先用 canary 通道验证）
+npx @soloco/client@canary --version
+npx @soloco/client@canary    # 启动 daemon，HTTP 监听 127.0.0.1:4318
+
+# 或全局安装（命令行入口是 soloco）
+npm i -g @soloco/client
+soloco                       # 启动
+soloco --version             # 查看版本
+soloco --help                # 用法与常用环境变量
+```
+
+零配置即可运行：无 `.env` / 无 OS env 时，内置默认值生效，状态写入 `~/.soloco/`（见下）。
+发布流程见仓库根 `docs/reference/2026-06-20-client-npm-packaging.md`。
+
+## 配置：环境变量
+
+daemon 面向 npm 用户必须零配置可启动：没有 `.env`、没有 OS env 时，代码内置默认值会自动生效，并把本地状态写入用户目录 `~/.soloco/`。环境变量只用于开发者、CI 或高级用户覆盖默认值。
+
+所有用户默认值的代码入口是 `src/config/defaults.ts` 的 `DEFAULT_DAEMON_CONFIG`。新增默认值或修改默认值时先改这个对象，再让 env resolver 读取它；不要在调用点散落新的 fallback 数字或路径。
+
+| 变量 | 默认 | 作用 |
+|---|---|---|
+| `SOLOCO_DAEMON_PORT` | `4318` | 本地 HTTP 端口 |
+| `SOLOCO_SERVER_BASE_URL` | `https://soloco.cloud` | Soloco 官网 / server 地址。默认使用 Vercel 上的官网后端；只有本地调试 `apps/server` 时才覆盖为 `http://localhost:3000` |
+| `SOLOCO_DAEMON_DB` | `~/.soloco/daemon.db` | SQLite 持久化路径（typed state） |
+| `SOLOCO_FILES_DIR` | `~/.soloco/files` | 产物文件库（artifact 内容，内容寻址） |
+| `SOLOCO_PLANNING_ROUNDS` | `5` | 首轮 Conductor 规划挑刺轮数（设 `1` = 只出一版、不挑刺，最快；上限 5） |
+| `SOLOCO_CYCLE_PLAN_ROUNDS` | `2` | 周期边界 replan 挑刺轮数（上限 2，保持 cycle 轻量） |
+| `SOLOCO_MAX_CYCLES` | `100` | 周期循环上限（跑飞兜底，上限 100） |
+| `SOLOCO_MAX_REPLANS` | `100` | 自治模式重规划次数上限（上限 100） |
+| `SOLOCO_RUN_TIMEOUT_MS` | （无） | 单次 agent 进程墙钟上限（毫秒）。**不设 = 永不超时**——长任务可能推理数小时，默认不杀进程；只有显式设置才启用 |
+| `SOLOCO_WORKSPACE_ALLOWED_ROOTS` | （仅 `~/.soloco/workspaces`） | PATH 风格 `:` 分隔的绝对目录列表，登记**额外**允许的显式启动工作目录（#142）。显式 cwd 必须 realpath 落在某个允许根之内才被接受，否则拒绝——杜绝把 executor 的工作区写权限交给 `~/.ssh`/`$HOME` 等敏感目录。敏感目标（`$HOME`/`~/.ssh`/`~/.aws`/`~/.config`/`~/.soloco`/`/`）即便其父目录被登记也按精确路径拒绝（§6.4 workspace 隔离硬策略） |
+
+显式请求参数（如 cycle body 的 `maxCycles`/`maxReplans`）优先级高于环境变量；环境变量高于内置默认。详见 architecture §6.2/§7.3（轮数/上限是 Run Policy 配置项，不写死内核）。
+
+## 设置方式
+
+**三种，按部署环境择一：**
+
+1. **零配置（npm 用户默认）**：`soloco daemon` 或等价启动命令即可运行；不需要 `.env`。状态默认进 `~/.soloco/daemon.db`，产物默认进 `~/.soloco/files`。
+2. **`.env` 文件（repo 本地开发推荐）**：复制 `.env.example` 为 `.env`，`pnpm dev` 会经 `--env-file=.env` 自动加载（Node 22 原生，无依赖）。`.env` 已被 gitignore。开发时如果希望把状态留在 repo 内，可设置 `SOLOCO_DAEMON_DB=./.soloco/daemon.db`。登录默认走 `https://soloco.cloud`，不需要本地启动 server。
+3. **命令行内联**：`SOLOCO_PLANNING_ROUNDS=1 SOLOCO_CYCLE_PLAN_ROUNDS=1 SOLOCO_DAEMON_PORT=4399 pnpm --dir apps/client-daemon dev`
+4. **OS 环境变量 / 客户端启动参数**：客户端打包后无 `.env` 时，由宿主进程注入这些变量即可，语义完全一致。
+
+## 启动
+
+```bash
+pnpm dev:daemon          # 默认配置：端口 4318，db ~/.soloco/daemon.db
+```