@chanlerdev/scorel 0.0.4 → 0.0.6

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.4",
+  "version": "0.0.6",
   "description": "Replayable, recoverable, remotely controllable AI Agent workspace.",
   "type": "module",
   "packageManager": "pnpm@11.1.2",