@chanlerdev/scorel 0.0.5 → 0.0.6

package/docs/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## Unreleased
 
+## 0.0.6 - 2026-06-23
+
+### Highlights
+
+- Packed GUI now bundles its own CLI runtime, enabling fully self-contained local Host startup without Node.js or global CLI.
+- Agents can now use the `snip` tool to hide completed user turns from future context — reducing token waste and keeping conversations focused.
+
+### Changes
+
+- GUI now bundles its own CLI runtime for fully self-contained Host startup (no Node.js or global CLI required).
+- Added `snip` tool that agents can call to mark a completed user turn as hidden from future LLM context.
+- Protocol version incremented to 4 with new `context_control` event and `hide_user_turn` operation.
+- UI (GUI and WebUI) now hides model-only text blocks (like `snip` reminders) from the visible transcript.
+- Provider adapters now pass each tool's own parameter schema instead of hardcoding tool-specific parameters.
+
+### Fixes
+
+- Increased Host startup timeout from 10s to 30s to prevent timeouts in slower development environments.
+
+### Breaking Changes
+
+- Protocol version incremented from 3 to 4; requires protocol-version-aware clients.
+- Packaged GUI no longer accepts `SCOREL_CLI_ENTRYPOINT` or `SCOREL_NODE_PATH` environment variables.
+
+### Verification
+
+- Unit and release tests verify bundled CLI usage in packaged GUI, snip tool end-to-end behavior, hidden spans in context builds, protocol version bump, and UI projector rendering.
+
+### Internal
+
+- Added planned spec S0107 for system reminder unification (documentation only).
+
 ## 0.0.5 - 2026-06-19
 
 ### Highlights

package/docs/ROADMAP.md

@@ -600,6 +600,9 @@ M5 WebUI 的正式产品方向记录在 [`S0030`](spec/ship/S0030-webui-product-
 | M9.F1.24 | [`S0102`](spec/ship/S0102-device-only-config.md) | Config 彻底收敛为设备级唯一配置，移除 Project config 运行时语义 | Done |
 | M9.F1.25 | [`S0103`](spec/ship/S0103-daemon-lifecycle-and-settings-resilience.md) | Daemon 生命周期按入口区分，并修复 GUI Settings remote 切换黑屏风险 | Done |
 | M9.F1.26 | [`S0105`](spec/ship/S0105-cli-update-and-gui-release.md) | CLI 命令面统一补齐、NPM 手动/自动更新、GUI release 打包和增量更新框架 | Done |
+| M9.F1.27 | [`S0106`](spec/ship/S0106-snip-context-control.md) | `context_control` 持久事件和 `snip` tool，让 agent 隐藏已完成 user turn 的未来 LLM context 投影 | Done |
+| M9.F1.28 | [`S0107`](spec/ship/S0107-system-reminder-unification.md) | 统一 system reminder 的持久化、构造、LLM 投影和 UI visibility 语义 | Planned |
+| M9.F1.29 | [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI release 内置同版本 CLI runtime，packaged GUI 用 bundle 内可执行文件启动本地 Host | Active |
 
 **Not in M9 Follow-up**:
 
@@ -779,6 +782,9 @@ HTTP adapter 必须映射已有 Host use cases，不复制领域逻辑。
 | [`S0103`](spec/ship/S0103-daemon-lifecycle-and-settings-resilience.md) | Daemon lifecycle and Settings resilience | Done |
 | [`S0104`](spec/ship/S0104-tool-result-artifacts.md) | Tool result artifacts for oversized Bash output | Done |
 | [`S0105`](spec/ship/S0105-cli-update-and-gui-release.md) | CLI update and GUI release | Done |
+| [`S0106`](spec/ship/S0106-snip-context-control.md) | Snip context control | Done |
+| [`S0107`](spec/ship/S0107-system-reminder-unification.md) | System reminder unification | Planned |
+| [`S0108`](spec/ship/S0108-gui-bundled-cli-runtime.md) | GUI bundled CLI runtime | Active |
 
 ---
 

package/docs/SHIP.md

@@ -209,6 +209,7 @@ pnpm release patch --no-generate-notes
 - 执行 WebUI production build
 - 执行 GUI production build
 - 构建 public `scorel` npm package
+- 将同版本 public `scorel` CLI runtime vendored 进 GUI app bundle，供 packaged GUI 用 bundle 内绝对路径启动本机 Host
 - 执行 `npm pack` 安装烟雾测试
 - bump 所有 package version
 - 构建 GUI macOS dmg / zip release assets，并生成 `latest-mac.yml` 与 blockmap 增量更新 metadata

package/docs/spec/events.md

@@ -143,7 +143,22 @@ interface CompactEvent extends PersistentEventBase {
 
 构建 context 时：从 leaf 往 root 走，遇到 CompactEvent → 注入 summary，停止继续向上。旧事件仍在 JSONL 中（可查阅），但不进入 LLM context。
 
-### 4.5 `channel_inject` — 外部来源元数据
+### 4.5 `context_control` — 控制上下文投影
+
+```typescript
+interface ContextControlEvent extends PersistentEventBase {
+  type: "context_control";
+  operation: "hide_user_turn";
+  anchorUserEventId: EventId;
+  throughEventId: EventId;
+  actor: "agent" | "user" | "system";
+  reason?: string;
+}
+```
+
+`hide_user_turn` 隐藏一个已完成 user turn span：从 `anchorUserEventId` 开始，到同一路径下一条 `user_message` 前一条事件结束。它只影响未来 `buildContext()` 的 LLM 输入投影；原始 JSONL 事件仍保留并可用于 UI、审计和 resync。
+
+### 4.6 `channel_inject` — 外部来源元数据
 
 ```typescript
 interface ChannelInjectEvent extends PersistentEventBase {
@@ -340,6 +355,7 @@ type LlmAction =
 | `rewind` | `skip` | "回退到此处" 标记 |
 | `branch` | `skip` | "切换分支" 标记 |
 | `compact` | `barrier` — 注入 summary，停止向上遍历 | "已压缩" 折叠块 |
+| `context_control` | `filter` — 从未来 LLM context 中排除指定 user turn span | "已 snip" 标记 |
 | `channel_inject` | `skip` | 来源 badge "from Telegram" |
 | `session_info` | `skip` | "模型切换为 X" 通知 |
 | `custom` | `skip` | Extension 自定义 |

package/docs/spec/session.md

@@ -345,6 +345,17 @@ if (estimateTokens(compactCandidates) > threshold) {
 - 在 compact 点之前分叉的其他分支不受影响
 - 旧事件仍在 JSONL 中，可供历史浏览
 
+### 6.3 Snip Context Control
+
+`snip` 不删除 JSONL。它 append `context_control operation="hide_user_turn"`，让后续 `buildContext()` 在 active path 上过滤一个已完成 user turn span。
+
+安全边界：
+
+- 目标必须是当前 active path 上的 `user_message`。
+- 目标之后必须存在下一条 `user_message`，因此不能 snip 当前正在执行的 turn。
+- 隐藏范围是目标 `user_message` 到下一条 `user_message` 前一条事件，保证 tool_call / tool_result 成对隐藏，不留下孤儿工具结果。
+- 原始事件仍保留在 JSONL 中，UI 和审计可以继续查看。
+
 ---
 
 ## 7. 两层消息在本模块的落点
@@ -355,6 +366,7 @@ if (estimateTokens(compactCandidates) > threshold) {
 - buildContext 通用遍历时调用每个 event 的 handler，不 hardcode 任何类型
 - `rewind` / `branch` / `channel_inject` / `session_info` / `custom` → `skip`（不进入 LLM）
 - `compact` → `barrier`（注入 summary，停止向上）
+- `context_control` → `filter`（从未来 LLM context 排除指定 user turn span）
 - `message`（meta.source = "steer"）→ `merge_prev`（合入前一条 tool_result 的 `<system-reminder>`）
 
 换言之，应用层能玩的花样很多，LLM 始终只看到 handler 声明要暴露的内容。

package/docs/spec/ship/S0106-snip-context-control.md

@@ -0,0 +1,113 @@
+# S0106: Snip Context Control
+
+## Goal
+
+Let long-running sessions remove a completed user turn from future model context without deleting the underlying session record.
+
+The business value is context hygiene: when an earlier user turn led the agent down a noisy or obsolete path, the user or agent can mark that whole turn as no longer relevant so future model calls stop paying attention to it. The original JSONL remains the evidence chain for UI, audit, resync, and debugging.
+
+## Scope
+
+### Stable User Turn References
+
+Every persisted `user_message` already has a durable `EventId`. S0106 treats that event id as the source of truth for snip targeting. The model-facing id is a stable short alias derived from the real `EventId`; the alias resolves back to the real event id but is not a storage key.
+
+When the Host creates a `user_message`, it appends a model-only text block to that same persisted message:
+
+```text
+<system-reminder>
+snip.userMessageId: u_...
+</system-reminder>
+```
+
+The block is persisted with the message so future `buildContext()` replays do not rewrite earlier user messages and do not invalidate prompt-cache prefixes. UI projectors hide model-only text blocks from the visible transcript.
+
+### Context Control Event
+
+Add a persistent control event:
+
+```ts
+type ContextControlEvent = {
+  type: "context_control";
+  operation: "hide_user_turn";
+  anchorUserEventId: EventId;
+  throughEventId: EventId;
+  actor: "agent" | "user" | "system";
+  reason?: string;
+};
+```
+
+The event is append-only and does not participate in the conversation tree. `buildContext()` folds these events as control state and filters the active path before producing LLM messages.
+
+`hide_user_turn` semantics:
+
+- `anchorUserEventId` must identify a `user_message` on the active session path.
+- The hidden span starts at that user event.
+- The hidden span ends at the event before the next `user_message` on the same path, or the active leaf when there is no later user message.
+- The resolved end is stored as `throughEventId`.
+- The span is hidden from future `buildContext()` calls after the control event is appended.
+- Original events stay in JSONL and continue to be visible through session replay and UI projection.
+
+### `snip` Tool
+
+Expose a lazily available `Snip` runtime tool that lets the agent request hiding a completed user turn from future context. The tool accepts:
+
+```json
+{ "userMessageId": "u_...", "reason": "optional short reason" }
+```
+
+The Host validates the request, resolves the model-visible short alias to a target span, appends a `context_control` event, and returns a tool result describing what changed. The tool result is still part of the current turn; the hidden span disappears on the next context build.
+
+The tool is session-context control, not a generic coding tool. It must be registered by the Host with access to the current lane, not by `createCodingTools()`.
+
+Tool parameter schemas are owned by `AgentTool` definitions. Provider adapters must pass through the tool's declared schema instead of hard-coding behavior for specific tool names such as `snip`.
+
+## Not In Scope
+
+- Physically deleting, truncating, or rewriting historical JSONL.
+- Arbitrary single-message deletion.
+- Snipping across branches.
+- User-facing GUI controls for browsing snipped spans.
+- A CLI slash command.
+- Automatic snip heuristics.
+- Reusing `compact` for snip. Compact summarizes old context; snip excludes a specific user turn.
+
+## Acceptance Criteria
+
+- `PersistentEvent` includes `context_control`.
+- Session replay folds `hide_user_turn` events into control state.
+- `buildContext()` excludes the hidden user-turn span from future LLM context.
+- The excluded span can include assistant tool calls and tool results without leaving orphan tool results in context.
+- JSONL remains append-only; original user/assistant/tool events remain loadable after snip.
+- Repeated snip of the same target is idempotent enough to keep context stable.
+- Invalid targets fail as tool errors and do not append control events.
+- `snip` is registered by the Host and can append `context_control` from a real runtime tool call path.
+- The model can discover snippable user turn ids from its normal context projection; tests must not rely on out-of-band `send_message` response data.
+- User turn ids are persisted at user-message creation time, so replaying the same turn in later provider calls does not change that message and preserves prompt-cache stability.
+- Model-only short id blocks are hidden from WebUI and GUI transcript projection.
+- The `snip` `AgentTool` schema exposes `userMessageId` and optional `reason`, and provider adapters preserve tool-owned schemas without name-specific branches.
+- Full validation passes with `pnpm typecheck && pnpm test`.
+
+## Testing Requirements
+
+- Core session tests for context-control parsing, replay, and context filtering.
+- Protocol tests for exhaustive event handling.
+- Daemon embedded test proving `snip` appends `context_control` and the next provider call no longer receives the hidden turn.
+
+## Impacted Files
+
+- `packages/protocol/src/events.ts`
+- `packages/protocol/src/index.test.ts`
+- `packages/core/src/session/index.ts`
+- `packages/core/src/session/session.test.ts`
+- `packages/core/src/tools/index.ts`
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/embedded/embedded.test.ts`
+- `docs/ROADMAP.md`
+- `README.md`
+
+## Risks And Boundaries
+
+- Hiding the wrong turn is worse than compacting too much. Target resolution must use real `EventId`s and reject non-user targets.
+- Tool-call/tool-result pairing can be broken by arbitrary deletion. This spec only hides full user-turn spans.
+- Snip is context projection, not evidence deletion. UI and session replay must still show the original events unless a later explicit product decision adds a separate display filter.

package/docs/spec/ship/S0107-system-reminder-unification.md

@@ -0,0 +1,112 @@
+# S0107: System Reminder Unification
+
+## Goal
+
+Unify how Scorel represents, persists, projects, and displays system reminders.
+
+The business value is prompt and transcript hygiene: runtime guidance should reach the model through one stable contract, without ad-hoc `<system-reminder>` string construction scattered across daemon, session replay, tool-result merge paths, or future context-control features. UI should consistently hide or display reminder evidence based on explicit visibility, not by parsing model-facing text.
+
+## Scope
+
+### Reminder Source Model
+
+Define one internal reminder representation for model-facing non-user guidance.
+
+Current sources include:
+
+- `harness_item` events such as memory, channel context, skill listing, skill delta, and steer.
+- Compact summary messages.
+- Model-only metadata attached to a specific `user_message`, such as `snip.userMessageId`.
+- Future runtime guidance that should be visible to the model but not necessarily displayed as transcript text.
+
+The new contract must preserve the existing product distinction:
+
+- Some reminders are standalone session events (`harness_item`).
+- Some reminders are attached to a specific message to preserve prompt-cache prefix stability.
+- Some reminders can merge into a previous `tool_result`.
+
+### Single Renderer
+
+Move `<system-reminder>` wrapping behind a single public core helper or equivalent abstraction. Callers should provide reminder content and placement intent, not hand-write:
+
+```text
+<system-reminder>
+...
+</system-reminder>
+```
+
+The renderer must keep the existing prompt contract:
+
+```text
+<system-reminder>
+content
+</system-reminder>
+```
+
+Any future format change must happen in one place.
+
+### Visibility And Projection
+
+Clarify and consolidate visibility semantics:
+
+- `harness_item.visibility` controls whether the harness event is displayed as transcript evidence.
+- Message-level model-only blocks are included in LLM context but hidden from WebUI and GUI transcript projection.
+- Display projectors must not parse `<system-reminder>` text to decide visibility.
+- Provider adapters should receive already-rendered model-facing text or a normalized reminder block from core, not duplicate reminder formatting.
+
+### Prompt Cache Stability
+
+Reminder placement must not rewrite older model context on later turns.
+
+For reminders attached to a specific persisted message, the model-facing block must be created when that message is persisted. Later `buildContext()` calls may clone or filter it, but must not mutate historical messages based on later session state.
+
+## Not In Scope
+
+- Changing snip semantics from S0106.
+- Replacing `harness_item` with a new event type unless the implementation proves the existing event cannot express the contract.
+- Changing provider-level system prompt assembly.
+- UI controls for browsing hidden reminders.
+- Backfilling or migrating old session JSONL files.
+- Renaming `<system-reminder>` in the model-facing prompt.
+
+## Acceptance Criteria
+
+- No daemon or feature code hand-writes `<system-reminder>` strings.
+- `buildContext()` uses the shared reminder renderer for `harness_item` and compact summaries.
+- Snip's model-only user-message id block uses the shared reminder renderer or normalized reminder block.
+- WebUI and GUI hide model-only message blocks without parsing reminder text.
+- Existing harness visibility behavior stays intact:
+  - hidden harness items do not render as visible turns;
+  - display harness items still render as lightweight transcript evidence.
+- Prompt-cache stability is preserved for message-attached reminders: replaying the same persisted user message in later provider calls produces the same content.
+- Provider adapters do not own system-reminder formatting rules.
+- `pnpm typecheck && pnpm test` passes.
+
+## Testing Requirements
+
+- Core session tests for the shared reminder renderer and `buildContext()` conversion.
+- Daemon embedded test proving snip's message-attached reminder remains stable across later turns.
+- WebUI and GUI projector tests proving model-only blocks are hidden while display harness items remain visible.
+- Regression test or static check that common runtime paths no longer hand-write `<system-reminder>` literals outside the shared renderer and tests/docs.
+
+## Impacted Files
+
+- `packages/core/src/session/index.ts`
+- `packages/core/src/session/session.test.ts`
+- `packages/core/src/tools/index.ts` or a new core reminder module
+- `packages/daemon/src/index.ts`
+- `packages/daemon/src/embedded/embedded.test.ts`
+- `apps/webui/lib/events/projector.ts`
+- `apps/webui/lib/events/projector.test.ts`
+- `apps/gui/src/renderer/chatbox/projector.ts`
+- `apps/gui/src/renderer/chatbox/projector.test.ts`
+- `docs/spec/events.md`
+- `docs/spec/session.md`
+- `README.md`
+
+## Risks And Boundaries
+
+- Reminder placement affects prompt-cache behavior. A cleanup that moves snip ids from persisted user messages into later dynamic `buildContext()` injection would regress S0106.
+- Tool-result merge behavior is easy to break. The implementation must preserve valid assistant tool-call / tool-result replay.
+- UI should use explicit visibility metadata, not text parsing. Parsing `<system-reminder>` in UI would make display behavior depend on prompt formatting.
+- A broader content-block redesign may be attractive, but S0107 should stay focused on unifying reminder construction and projection.

package/docs/spec/ship/S0108-gui-bundled-cli-runtime.md

@@ -0,0 +1,108 @@
+# S0108: GUI Bundled CLI Runtime
+
+## Goal
+
+Make the packaged desktop GUI self-contained for local Host startup.
+
+The business value is that installing `Scorel.app` is enough to use the local GUI path. Users must not need a terminal-launched environment, a global `node`, a global `scorel`, or the source repository layout for GUI Settings and local Project workflows to work.
+
+## Scope
+
+- Vendor the same-version public `scorel` CLI release artifact into the macOS GUI bundle.
+- Make packaged GUI startup resolve the local Host launcher from the app bundle, not from `PATH`.
+- Keep development startup convenient through the existing source CLI path.
+- Remove the packaged-build requirement for `SCOREL_CLI_ENTRYPOINT`.
+- Add release/package tests proving the GUI bundle contract references `Contents/Resources/scorel`.
+- Add a regression test for Finder/Dock-like startup where `PATH` does not contain Node.
+
+## Not In Scope
+
+- Publishing the GUI through npm.
+- Replacing the CLI with a separate `scorel-host` binary.
+- Changing `scorel host start` daemon lifecycle semantics.
+- Changing the public CLI command surface.
+- Adding LaunchAgent/login-item restart supervision.
+- Supporting Windows/Linux GUI packaging in this spec.
+
+## Contract
+
+The packaged macOS app contains:
+
+```text
+Scorel.app
+  Contents/Resources/
+    scorel      # launcher script
+    scorel.js   # bundled CLI artifact
+    app.asar
+```
+
+Packaged GUI starts the local singleton Host with the bundle-owned executable:
+
+```text
+Contents/Resources/scorel host start --port 0 --cwd <bootstrap-project> --idle-timeout-ms <ms> --no-relay
+```
+
+Development GUI may continue to use the source entrypoint:
+
+```text
+node --import tsx apps/cli/src/index.ts host start ...
+```
+
+The packaged path must not depend on:
+
+- `node` being discoverable in `PATH`;
+- `scorel` being globally installed;
+- `SCOREL_NODE_PATH`;
+- `SCOREL_CLI_ENTRYPOINT`;
+- `apps/cli/src/index.ts` existing inside the app bundle.
+
+## Acceptance Criteria
+
+- `apps/gui` Electron Builder config includes a generated `.runtime` directory containing `scorel` and `scorel.js` in `Contents/Resources`.
+- The bundled `scorel` launcher uses the app's own Electron executable with `ELECTRON_RUN_AS_NODE=1` to run the built CLI artifact as `scorel.js`.
+- Packaged GUI resolves the Host launcher to `process.resourcesPath/scorel`.
+- Packaged GUI spawns `scorel` directly and does not prepend `node`, `tsx`, or source entrypoint args.
+- Development GUI still supports `SCOREL_CLI_ENTRYPOINT` and `SCOREL_NODE_PATH` for local debugging.
+- A unit test proves packaged Host startup uses the bundle CLI even with an empty/minimal `PATH`.
+- Release tests prove the GUI package depends on the built CLI artifact and bundle destination.
+- `docs/SHIP.md`, `docs/ROADMAP.md`, and `README.md` describe that GUI release assets include a bundled same-version CLI runtime.
+
+## Test Requirements
+
+```bash
+pnpm --filter @scorel/app-gui test -- src/main/host-launcher.test.ts
+node --test scripts/release-gui.test.mjs
+pnpm --filter @scorel/app-gui build
+pnpm build:package
+git diff --check
+```
+
+Full release readiness still uses:
+
+```bash
+pnpm typecheck && pnpm test
+pnpm release patch --dry-run
+```
+
+## Impacted Files
+
+- `apps/gui/package.json`
+- `apps/gui/src/main.ts`
+- `apps/gui/src/main/host-launcher.ts`
+- `apps/gui/src/main/host-launcher.test.ts`
+- `apps/gui/scripts/build-runtime.mjs`
+- `apps/gui/scripts/build-runtime.node-test.mjs`
+- `scripts/release-gui.test.mjs`
+- `docs/SHIP.md`
+- `docs/ROADMAP.md`
+- `README.md`
+
+## Risks And Boundaries
+
+- The vendored CLI must be built before `electron-builder` runs. Release flow already runs `pnpm build:package`; local `dist:mac` must do the same or fail clearly.
+- The bundled CLI runs under Electron's Node mode. A fully native/self-contained CLI binary remains a possible future hardening step, but the packaged GUI no longer depends on user `PATH` for Node.
+- The GUI must never call the user's global `scorel`, because that can drift from the GUI version and mutate the local Host contract.
+
+## Status
+
+Active.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chanlerdev/scorel",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "description": "Replayable, recoverable, remotely controllable AI Agent workspace.",
   "type": "module",
   "packageManager": "pnpm@11.1.2",