@chanlerdev/scorel 0.0.1

package/docs/spec/ship/S0061-hosted-defaults-and-cli-command-surface.md

@@ -0,0 +1,208 @@
+# S0061: Hosted Defaults And CLI Command Surface
+
+## Goal
+
+Make the post-M8 user path match the deployed product:
+
+```text
+local terminal -> local Scorel Host -> official Relay -> hosted WebUI
+```
+
+The CLI should expose product concepts instead of implementation leakage:
+
+- `scorel` is the normal interactive project command, similar to `claude`.
+- `scorel host serve` starts this device's local Host and connects it to Relay by default.
+- `scorel pair <code>` authorizes the hosted WebUI Entry through the default Relay.
+- `scorel relay serve` is only for operating a self-hosted Relay service.
+
+## Current Deployment Baseline
+
+- Hosted WebUI: `https://scorel.chanler.dev`
+- Relay WebSocket URL: `wss://scorel-relay.chanler.dev`
+
+Self-hosted and development flows can override the Relay URL with `SCOREL_RELAY_URL` or `--relay <url>`.
+
+## Scope
+
+- Add first-class hosted defaults:
+  - official WebUI origin
+  - official Relay URL
+  - environment/config override for self-hosted deployments
+- Redesign user-facing CLI commands:
+  - `scorel` defaults to interactive project execution in `process.cwd()`
+  - `scorel chat` remains as an explicit alias for the same interactive mode
+  - `scorel host serve` replaces user-facing `scorel daemon serve`
+  - `scorel host serve` registers `process.cwd()` as the initial Project by default
+  - `scorel host serve` connects outbound to the official Relay by default
+  - `scorel host serve --no-relay` starts local-only
+  - `scorel host serve --relay <url>` uses a self-hosted Relay
+  - `scorel host serve --replace` stops an already-running local Host and starts a fresh one
+  - `scorel pair <code>` uses the official Relay by default
+  - `scorel pair <code> --relay <url>` remains for self-hosted Relay
+  - `scorel relay serve` runs a Relay service for self-hosting/development
+- Keep implementation aliases where needed:
+  - `scorel daemon ...` may remain as a compatibility/internal alias during pre-1.0
+  - docs and usage output must prefer `host`
+- Update CLI help, README, docs, and tests to match the new command model.
+- Keep `scorel up` as a development convenience for local Host + local WebUI, not the primary hosted user path.
+- Ensure previously landed S0061 Vercel install/build support is represented in the docs where relevant.
+
+## Non-Goals
+
+- Do not add accounts or OAuth.
+- Do not add hosted execution.
+- Do not make Relay store Project, Session, prompt, tool result, provider response, or replay state.
+- Do not implement desktop GUI.
+- Do not implement SSH remote bootstrap.
+- Do not introduce a second daemon/Host protocol.
+- Do not silently kill an actively running Host without an explicit replacement rule.
+
+## Contract
+
+### Normal CLI Execution
+
+```bash
+scorel
+```
+
+Runs interactive Scorel in the current shell directory. That directory is the current Project. The command should create/register the Project through the existing Host/project registry path as needed, not invent a separate cwd-only execution path.
+
+Explicit form:
+
+```bash
+scorel chat
+scorel chat --cwd <dir>
+```
+
+`--cwd` remains an advanced override. Product docs should teach `cd <project> && scorel`.
+
+### Local Host
+
+```bash
+scorel host serve
+```
+
+Starts this device's Scorel Host. Default behavior:
+
+- local WS Host starts with the existing persistent token/state model
+- `process.cwd()` is registered as the initial Project
+- Host connects outbound to the official Relay
+- Host keeps Relay connection alive with automatic reconnect
+- stdout prints local Host URL, device identity, Relay status, and hosted WebUI URL
+
+Local-only:
+
+```bash
+scorel host serve --no-relay
+```
+
+Self-hosted Relay:
+
+```bash
+scorel host serve --relay <relay-url>
+```
+
+Replacement:
+
+```bash
+scorel host serve --replace
+```
+
+If a previous Host state is stale/dead, `host serve` may clean it up automatically. If a Host is live, default behavior must not silently kill it. It should fail with a clear message telling the user to pass `--replace`.
+
+### Pairing
+
+```bash
+scorel pair <code>
+```
+
+Redeems a hosted WebUI pair code through the official Relay by default.
+
+Self-hosted override:
+
+```bash
+scorel pair <code> --relay <relay-url>
+```
+
+### Relay Operator
+
+```bash
+scorel relay serve
+```
+
+Runs a Relay service for self-hosting/development. This command maps to the existing `apps/relay` process and should expose host, port, and data-dir flags.
+
+## Acceptance Criteria
+
+- `scorel --help` shows `scorel`, `scorel host serve`, `scorel pair`, and `scorel relay serve` as the primary command surface.
+- `scorel` with no subcommand enters the same interactive project flow currently reached by `scorel chat`.
+- `scorel host serve` starts a local Host, registers the current cwd as an initial Project, and attempts Relay connection by default.
+- `scorel host serve --no-relay` starts without opening a Relay connection.
+- `scorel host serve --relay <url>` connects to the provided Relay.
+- `scorel host serve` auto-recovers stale daemon state but refuses to replace a live Host unless `--replace` is provided.
+- `scorel host serve --replace` stops the live previous Host and starts a fresh Host.
+- Relay reconnect is automatic after transient Relay socket loss.
+- `scorel pair <code>` works against the official Relay without requiring `--relay`.
+- `scorel pair <code> --relay <url>` still works for self-hosted Relay tests.
+- `scorel relay serve` can start the Relay service with a file-backed store.
+- `scorel daemon ...` aliases either continue to work or produce a clear pre-1.0 migration message; they must not be the documented primary path.
+- Root README and `docs/SHIP.md` quickstart no longer teach `scorel daemon serve --cwd --relay` as the user-facing hosted path.
+- Hosted WebUI quickstart references `https://scorel.chanler.dev`.
+
+## Test Requirements
+
+- CLI unit tests cover:
+  - no-subcommand `scorel` dispatches to chat/interactive flow
+  - `host serve` parses default Relay, `--no-relay`, `--relay`, and `--replace`
+  - live Host replacement requires `--replace`
+  - `pair` uses the default Relay when `--relay` is omitted
+  - `relay serve` parses host/port/data-dir and starts through the existing Relay server path
+- Daemon/Host tests cover Relay reconnect behavior without adding test-only product branches.
+- Existing Relay tests continue to use real local WebSocket servers and file stores.
+- Run:
+
+```bash
+pnpm typecheck
+pnpm test
+```
+
+- If hosted deploy readiness is claimed in this spec's implementation, also run the relevant Vercel/build verification command and record the exact command in a verification note.
+
+## Verification
+
+Completed on 2026-06-06:
+
+```bash
+pnpm --filter @scorel/app-cli test
+pnpm --filter @scorel/daemon test -- src/relay/host-client.test.ts
+pnpm typecheck
+pnpm test
+git diff --check
+```
+
+## Affected Paths
+
+- `apps/cli/src/index.ts`
+- `apps/cli/src/daemon-cli.ts`
+- `apps/cli/src/relay-cli.ts`
+- `apps/cli/src/up-cli.ts`
+- `apps/cli/src/*.test.ts`
+- `apps/relay/src/index.ts`
+- `packages/daemon/src/relay/*`
+- `packages/daemon/src/*`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+- `README.md`
+- `docs/README.md`
+- `docs/spec/relay.md`
+- `package.json`
+- `pnpm-lock.yaml`
+- `pnpm-workspace.yaml`
+
+## Risks
+
+- Renaming `daemon` to `host` can churn tests and docs. Keep aliases or explicit migration messages during pre-1.0.
+- Default Relay connection can make local startup depend on public service availability. `--no-relay` must be obvious and reliable.
+- `--replace` can interrupt running sessions. Do not make live-process replacement silent.
+- Treating no-subcommand `scorel` as chat must not hide parse errors for known commands.
+- Hosted defaults must not become hard-coded in places that prevent self-hosting.

package/docs/spec/ship/S0062-npm-package-and-release-workflow.md

@@ -0,0 +1,166 @@
+# S0062: Npm Package And Release Workflow
+
+## Goal
+
+Make the first public npm release path executable:
+
+```text
+pnpm release patch --dry-run
+pnpm release patch
+```
+
+The public package is one user-facing package named `@chanlerdev/scorel`. It installs the `scorel` CLI command and includes the CLI, local Host/daemon runtime, pairing command, and Relay operator command. Internal workspace packages remain unpublished for now.
+
+## Scope
+
+- Publish surface:
+  - root package name: `@chanlerdev/scorel`
+  - bin: `scorel`
+  - first version: `0.0.1`
+- Add package build:
+  - bundle `apps/cli/src/index.ts` to `dist/index.js`
+  - keep the generated bin executable
+  - do not require `tsx` at runtime
+- Add local release command:
+  - `pnpm release patch`
+  - `pnpm release minor`
+  - `pnpm release major`
+  - `--dry-run` validates without committing, tagging, pushing, or publishing
+  - `--no-publish` commits/tags without npm publish
+- Add npm pack smoke:
+  - pack the root package
+  - install it into a temporary project
+  - run `scorel --help`
+- Add manual GitHub Actions release workflow:
+  - `workflow_dispatch`
+  - default `bump=patch`
+  - default `dry_run=true`
+  - uses the same `pnpm release` command
+- Update docs/roadmap/changelog for release readiness.
+
+## Non-Goals
+
+- Do not publish `@scorel/protocol`, `@scorel/client`, `@scorel/core`, `@scorel/daemon`, `@scorel/app-cli`, or `@scorel/relay`.
+- Do not bundle hosted WebUI into the npm package.
+- Do not change hosted WebUI deployment. It remains a Vercel/monorepo build.
+- Do not implement accounts, OAuth, or hosted execution.
+- Do not automatically publish from CI unless the workflow is manually triggered with `dry_run=false`.
+
+## Contract
+
+### Package Build
+
+```bash
+pnpm build:package
+```
+
+must create:
+
+```text
+dist/index.js
+```
+
+The generated file must:
+
+- start with a node shebang
+- be executable
+- run without `tsx`
+- include internal workspace code needed by the CLI/Host/Relay commands
+
+### Release Command
+
+```bash
+pnpm release patch --dry-run
+```
+
+must:
+
+- require a clean working tree, except generated release artifacts it creates during the run
+- run repo checks
+- build WebUI
+- build the npm package
+- run npm pack smoke
+- compute the next version
+- report what would happen
+- not mutate package versions, changelog, git commit, git tag, push, or publish
+
+```bash
+pnpm release patch
+```
+
+must:
+
+- require clean working tree
+- run the same verification path
+- bump all package/app versions in lockstep
+- update `docs/CHANGELOG.md`
+- build the npm package
+- run npm pack smoke
+- commit `release: vX.Y.Z`
+- tag `vX.Y.Z`
+- publish the root `@chanlerdev/scorel` package to npm
+
+The release script may support `--no-publish` for preparing a release commit/tag without publishing.
+
+### GitHub Actions
+
+Manual workflow inputs:
+
+```text
+bump: patch | minor | major
+dry_run: true | false
+publish: true | false
+```
+
+The workflow must:
+
+- install pnpm from `packageManager`
+- run `pnpm install --frozen-lockfile`
+- run `pnpm release <bump> --dry-run` by default
+- require `NPM_TOKEN` only for a real publish
+
+## Acceptance Criteria
+
+- Root `package.json` is a publishable `@chanlerdev/scorel` package with `bin`, `files`, `engines`, and release/build scripts.
+- `pnpm build:package` creates an executable `dist/index.js`.
+- `node dist/index.js --help` works.
+- `pnpm pack:smoke` packs and installs the tarball into a temporary project, then runs `scorel --help`.
+- `pnpm release patch --dry-run` runs the full dry-run path and exits 0.
+- `.github/workflows/release.yml` exists and manually triggers the same release command.
+- `docs/ROADMAP.md` includes S0062 as Done only after verification.
+- `docs/CHANGELOG.md` records release infrastructure under Unreleased until the first release moves it to a version section.
+
+## Test Requirements
+
+Run:
+
+```bash
+pnpm build:package
+node dist/index.js --help
+pnpm pack:smoke
+pnpm release patch --dry-run
+pnpm typecheck
+pnpm test
+pnpm --filter @scorel/app-webui build
+git diff --check
+```
+
+## Affected Paths
+
+- `package.json`
+- `scripts/build-package.mjs`
+- `scripts/pack-smoke.mjs`
+- `scripts/release.mjs`
+- `.github/workflows/release.yml`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+- `docs/CHANGELOG.md`
+- `docs/spec/ship/S0062-npm-package-and-release-workflow.md`
+- `docs/plans/2026-06-07-s0062-npm-package-release.md`
+
+## Risks
+
+- Bundling can accidentally include development-only code. Keep `files` restricted to `dist`, README, and selected docs.
+- Publishing internal packages too early would create API stability pressure. Keep only root `@chanlerdev/scorel` public in S0062.
+- Real npm publish requires `chanlerdev` authentication locally or `NPM_TOKEN` in GitHub Actions.
+- A release script that mutates versions before verification can leave the repo dirty after failures. Run verification before mutation for normal release, and keep dry-run non-mutating.

package/docs/spec/tools.md

@@ -0,0 +1,173 @@
+# 工具系统：内置工具 + MCP
+
+> 上游：`architecture.md`
+> 主题：Agent 的能力边界由工具决定。这份文档说明 Scorel 如何定义、组织、接入工具。
+
+---
+
+## 1. 设计目标
+
+工具系统需要同时回答三个问题：
+
+1. **怎么定义**——工具签名、参数、返回值如何描述给 LLM 和 runtime
+2. **怎么组合**——哪些工具默认开启、哪些按需加载
+3. **怎么扩展**——外部 MCP 服务器如何无缝接入
+
+三个问题都 **复用 pi-ai + pi-agent-core 已有的抽象**，Scorel 不重新发明；但上层代码只依赖 Scorel 自己 re-export / adapter 后的类型，避免把底层包名泄漏到 app、daemon、extension。
+
+**M2 / S0012 不做权限审批、沙箱和快照恢复**：先把 Coding Agent Alpha 跑通，让用户能在本地工作区完成真实搜索、读写、命令验证和 Todo 进度跟踪。当前安全边界来自清晰工具语义、read coverage / stale check、精确编辑失败规则、超时与输出截断，而不是恢复机制。
+
+---
+
+## 2. 工具定义：复用 `AgentTool` 语义
+
+Scorel 对外暴露自己的 `AgentTool` / `Type` adapter，语义对齐 pi-ai 的 `Tool` + pi-agent-core 的 `AgentTool`：
+
+```typescript
+import { Type, type AgentTool } from '@scorel/core/tools';
+
+const readTool: AgentTool = {
+  name: 'Read',
+  label: 'Read File',
+  description: '读取文件内容',
+  parameters: Type.Object({
+    file_path: Type.String(),
+    offset: Type.Optional(Type.Number()),
+    limit: Type.Optional(Type.Number()),
+    full: Type.Optional(Type.Boolean()),
+  }),
+  execute: async (toolCallId, args, signal, onUpdate) => {
+    const content = await fs.readFile(args.path, 'utf-8');
+    return {
+      content: [{ type: 'text', text: content }],
+      details: { path: args.path, size: content.length },
+    };
+  },
+};
+```
+
+参数用 TypeBox 风格表达，底层 adapter 负责转成 provider 需要的 JSON Schema。
+
+---
+
+## 3. 内置工具集
+
+M2 落地七个用户可见工具，语义参考 Claude Code 的基础 coding 工具，但按 Scorel 的 daemon/client/session 边界实现：
+
+| 工具 | 说明 | 执行模式 | M2 关键约束 |
+|------|------|---------|------------|
+| `Read` | 读取文本文件，支持行范围 | parallel | 只读文件不读目录；结果带稳定行号；默认最多返回 2000 个完整行，并同时受当前模型 context window 1% 的估算 token 预算限制；`full: true` 使用 10% 预算；无 context window 时 fallback 为 200000；token 估算按带行号的返回文本计算，暂按约 3 字符/token；预算截断只按整行回退；结果带 startLine/endLine/totalLines/truncated/nextOffset/canWrite/estimatedTokens/tokenBudget；同一文件版本下读段可累积，覆盖完整文件后解锁写入 |
+| `Write` | 创建新文件或完整重写文件 | sequential | 写既有文件前必须已读覆盖完整当前文件；读后文件被外部修改必须失败；模型侧结果不返回旧/新完整内容；优先用 `Edit` 修改既有文件 |
+| `Edit` | 精确字符串替换 | sequential | 编辑前必须已读覆盖完整当前文件；读后文件被外部修改必须失败；`old_string` 不存在或不唯一时失败，除非显式 replace_all；模型侧结果只返回成功与替换计数 |
+| `Bash` | 命令执行 | sequential | 指定 cwd；超时保护；输出截断；失败作为 tool result 返回 |
+| `Glob` | 按文件名 / glob pattern 找文件 | parallel | 基于 ripgrep file discovery；返回结构化路径列表；排序稳定；支持分页 |
+| `Grep` | 基于 ripgrep 的内容搜索 | parallel | 支持 glob/type/-A/-B/-C/context/-n/-i/multiline 过滤；支持 content/files/count 输出；限制结果数量，并用 max-columns 控制超长行 |
+| `TodoWrite` | 完整替换 Todo List | sequential | 参数是完整 todos；返回 oldTodos/currentTodos；全 completed 时系统清空 currentTodos |
+
+**执行模式**：只读工具 parallel、写类或有副作用的工具 sequential。底层 pi-agent-core 已有对应抽象时优先复用，Scorel 只通过 adapter 透出，不自建复杂调度。
+
+**工具使用原则**：
+- 读文件用 `Read`，不要让 `Bash` 代替 `cat` / `head` / `tail`。长文件默认截断；继续阅读用 `offset`，同一版本下读段覆盖完整文件后即可写。`full: true` 请求一次读完整文件，并使用 10% context window 预算。`Read` 不会为了满足预算截断单行；如果单行过长会失败并提示换搜索/专用工具。
+- 改既有文件优先用 `Edit`，不要让 `Bash` 代替 `sed -i` / heredoc / redirect。
+- `Write` 只用于创建新文件或完整重写。
+- 找文件用 `Glob`，搜内容用 `Grep`；不要把常规搜索塞进 `Bash rg/find`。
+- `Bash` 负责构建、测试、Git 状态、项目脚本等命令型工作。
+- 多步骤 coding task 用 `TodoWrite` 记录当前计划和状态；CLI 必须能展示这些变化。
+
+**M2 之后再扩展**：`LS`、Web、LSP、notebook、subagent、MCP 动态工具等能力在基础 coding loop 稳定后再补齐。
+
+---
+
+## 4. 工具集预设
+
+通过配置选择一组工具启用：
+
+| 预设 | 包含 |
+|------|------|
+| `coding` | `Read` / `Write` / `Edit` / `Bash` / `Glob` / `Grep` / `TodoWrite` |
+| `readonly` | `Read` / `Glob` / `Grep` |
+| `all` | 内置 + 已连接的 MCP（M2 后） |
+| `none` | 不启用任何工具 |
+
+预设在 `config.toml` 的 `[tools]` 段声明（见 `spec/extensions.md §5`）。Extension 可以额外追加工具。
+
+---
+
+## 5. MCP 集成（M2 后）
+
+pi-ai 本身不内置 MCP，Scorel 自己接——TypeScript 生态的 MCP SDK 已经成熟，接入成本不高。
+
+MCP 不属于 M2。M2 先把内置 coding 工具和 session/daemon/client/CLI 主链路跑通；MCP 在后续 ecosystem 阶段接入。
+
+### 5.1 MCP 工具转换
+
+每个 MCP 服务器暴露的 tool 被包装成一条 `AgentTool`：
+
+```typescript
+function mcpToAgentTool(client: McpClient, tool: McpTool): AgentTool {
+  return {
+    name: `${client.name}_${tool.name}`,
+    label: tool.name,
+    description: tool.description,
+    parameters: convertJsonSchemaToTypeBox(tool.inputSchema),
+    execute: async (_, args) => {
+      const result = await client.callTool(tool.name, args);
+      return {
+        content: result.content,
+        details: { server: client.name, tool: tool.name },
+      };
+    },
+  };
+}
+```
+
+MCP 生态里很多 server 用 Zod / 原生 JSON Schema，Scorel 工具签名统一在 TypeBox 风格 schema。JSON Schema 到 TypeBox 的转换由 adapter 层负责。
+
+### 5.2 后续：启动时加载
+
+```typescript
+interface McpServerConfig {
+  name: string;
+  transport: 'sse' | 'stdio';
+  url?: string;            // sse
+  command?: string;        // stdio
+}
+```
+
+所有配置的 MCP 服务器在 session 启动时连接并加载工具描述，全部作为 `all` 预设的一部分。是否进入 `coding` 预设，需要等内置 M2 工具稳定后再决定。
+
+### 5.3 更后续：按需分级加载
+
+初期不做的：按 keyword 触发的 **Tier 2** 动态加载（`transformContext` 拦截用户消息，命中关键词才 attach 对应工具）。
+
+延后的理由：
+- 初期 MCP 服务器数量可控，工具描述全加载也不会撑爆 system prompt
+- 分级策略依赖真实使用数据调参，在没有数据前先简单做
+
+---
+
+## 6. 错误是数据
+
+工具执行失败时 **不抛异常**，而是返回包含错误信息的 `content`。pi-agent-core 会把错误编码成 `ToolResultMessage.isError` / `AssistantMessage.stopReason`，LLM 下一轮可以读取并决定是否重试。
+
+这条原则和 `architecture.md §6` 的"错误是数据，不是异常"对齐——异常通道只保留给真正的编程错误（例如参数类型不对），业务失败都走数据通道。
+
+---
+
+## 7. 初期范围与延后项
+
+**初期落地**
+- M2/S0012 内置工具集：`Read` / `Write` / `Edit` / `Bash` / `Glob` / `Grep` / `TodoWrite`
+- 工具集预设：`coding` / `readonly` / `all` / `none`
+
+**延后**
+- `LS` 等便利只读工具
+- WebFetch / WebSearch、LSP、notebook editing、worktree mode
+- **权限审批（PermissionPolicy）**：默认全允许，后期补黑名单 / 询问 / 拒绝规则
+- MCP 启动时加载
+- MCP Tier 2 按需加载
+- Subagent 工具（工具内 `new Agent()` 递归调用，隔离上下文）
+
+---
+
+*工具系统的复杂度主要在"组合与扩展"，定义层复用 pi 栈语义，但通过 Scorel adapter 固化边界。*

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@chanlerdev/scorel",
+  "version": "0.0.1",
+  "description": "Replayable, recoverable, remotely controllable AI Agent workspace.",
+  "type": "module",
+  "packageManager": "pnpm@11.1.2",
+  "bin": {
+    "scorel": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "docs/SHIP.md",
+    "docs/ROADMAP.md",
+    "docs/CHANGELOG.md",
+    "docs/spec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ChanlerDev/Scorel.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@mariozechner/pi-ai": "0.73.1",
+    "ws": "^8.21.0"
+  },
+  "scripts": {
+    "build:package": "node scripts/build-package.mjs",
+    "check": "pnpm typecheck && pnpm test",
+    "pack:smoke": "node scripts/pack-smoke.mjs",
+    "release": "node scripts/release.mjs",
+    "typecheck": "pnpm -r typecheck",
+    "test": "pnpm -r test",
+    "verify:m8-relay": "node --import tsx scripts/verify-m8-relay-e2e.ts",
+    "scorel": "node --import tsx apps/cli/src/index.ts",
+    "dev": "node --import tsx apps/cli/src/index.ts up"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "esbuild": "0.28.0",
+    "next": "^14.2.35",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "4.0.13"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  }
+}