@hayasaka7/haya-pet 0.1.0

package/docs/architecture.md

@@ -0,0 +1,144 @@
+# Architecture
+
+How Haya Pet is put together. For installing and using it, see the
+[README](../README.md); this doc is for contributors and the curious.
+
+## Pipeline
+
+```text
+AI terminal clients
+    → client adapters        (normalize behavior into a common event model)
+    → haya-petd daemon         (sessions, priority, pet state, IPC)
+    → shared pet runtime     (assets, animation, interaction)
+    → desktop overlay        (global pet + session bubbles)
+```
+
+You launch any AI CLI through the `haya-pet` wrapper. The wrapper registers a
+session and reports lifecycle/activity events to the daemon over local IPC (a
+named pipe on Windows, a unix socket elsewhere). The first `haya-pet run`
+**auto-starts the daemon/overlay**, so users only ever type `haya-pet run …`.
+
+| Component | Responsibility |
+|---|---|
+| `haya-pet` (CLI) | Wrapper: launches clients, registers sessions, reports events, auto-starts the companion. |
+| `haya-petd` (companion) | Global daemon + overlay: owns sessions, pet state, windows, IPC. |
+| adapters | Translate client-specific behavior into the common state model. |
+| pet-core | Loads pet assets, computes frames, drives animation state. |
+| session-core | Tracks sessions, priority, summaries, bubble view models, linger. |
+| task-core | Task status, events, approvals, replies, control gating (reply/approval UI is parked). |
+| platform-core | Per-OS paths, capabilities, and fallback tiers. |
+
+## Normalized state model
+
+Every client maps to a shared state vocabulary that drives the pet animation and
+the bubble status icons:
+
+`idle`, `thinking`, `running_tool`, `editing_files`, `waiting_user`,
+`waiting_approval`, `reviewing`, `compacting`, `failed`, `success`, `stale`,
+`exited`.
+
+Bubbles collapse these into four status kinds: **working** (spinner), **done**
+(check), **attention** (yellow), **failed** (red cross).
+
+## Adapter support tiers
+
+The daemon never bakes in client-specific logic; adapters provide as much fidelity
+as each client allows:
+
+| Tier | Source | Fidelity |
+|---|---|---|
+| L1 | Process wrapper (lifecycle only) | session exists / exit code |
+| L2 | PTY output observation (`--observe`, default) | activity-based working/idle |
+| L3 | Client logs / state files | client-specific (future) |
+| L4 | Official plugin/hooks | richest (future) |
+
+L2 is **activity-based**: any visible output → *working*; a short quiet window →
+*idle*; success/failure come from the real exit code, never from scraping output
+text. Keyword heuristics exist but are opt-in (unreliable on rich TUIs). See
+[known-issues.md](known-issues.md) for the current L2/PTY tradeoffs.
+
+## Overlay model
+
+The overlay is a transparent, always-on-top window spanning the work area, kept
+click-through except over the pet and bubble chips (via `setIgnoreMouseEvents`
+with mouse-move forwarding). The pet is positioned inside the window and dragged
+via CSS; the bubble panel is placed on whichever side of the pet has room so it
+stays fully on-screen. The pet currently lives on a single display's work area.
+
+## Distribution & runtime dependencies
+
+- `electron` is a **runtime dependency** (not just a dev tool), because
+  `haya-pet run` launches the overlay by spawning `electron <companion>`.
+- `node-pty` is **optional**: live observation (L2) uses it, and degrades to L1
+  lifecycle tracking when it's absent.
+- Auto-start can be disabled with `HAYA_PET_NO_AUTOSTART=1`; `haya-pet start` /
+  `haya-pet stop` control the overlay explicitly.
+
+See [publishing.md](publishing.md) for the npm release process.
+
+## Project structure
+
+```text
+packages/
+  protocol/        IPC message types + validation
+  pet-core/        atlas, manifest, validation, animator, animation-state
+  session-core/    registry, priority, summaries, bubble views, linger, pet-state
+  task-core/       task status, events, store, approvals, replies, controls
+  adapters/        client info, heuristics, capabilities, output observer, routing
+  daemon-core/     IPC server/transport, runtime bridge, singleton
+  platform-core/   platform, paths, capabilities
+apps/
+  cli/             haya-pet entrypoint + parser (run / start / stop / pets)
+  companion/       Electron overlay app (main + renderer)
+  pet-preview/     static preview scaffold
+native/
+  win-window-helper/   Windows terminal-window helper (.NET, implemented)
+  mac-window-helper/   macOS helper (contract documented)
+  linux-window-helper/ Linux X11/Wayland helper (contract documented)
+assets/
+  fallback-pet/    bundled fallback pet manifest
+```
+
+There are no per-package `package.json` files — packages import each other by
+relative path, which is also why the whole tree ships as one npm package.
+
+## Platform support
+
+| Feature | Windows | macOS | Linux X11 | Linux Wayland |
+|---|---|---|---|---|
+| Protocol / session core | ✅ | ✅ | ✅ | ✅ |
+| Generic CLI wrapper | ✅ | ✅ | ✅ | ✅ |
+| Local daemon IPC | named pipe | unix socket | unix socket | unix socket |
+| Transparent overlay | ✅ | ✅ | ✅ | best-effort |
+| Terminal attachment | ✅ helper | 🔜 | 🔜 | fallback |
+
+See [cross-os-qa.md](cross-os-qa.md) for the full test matrix.
+
+## Native window helpers
+
+Optional per-OS helpers locate terminal windows so bubbles can attach near them.
+
+```powershell
+# Windows (.NET SDK 10, net10.0-windows):
+cd native\win-window-helper
+dotnet build -c Release
+# -> bin/Release/net10.0-windows/haya-pet-win-window-helper.exe
+```
+
+macOS (Swift/AppKit) and Linux (X11/Wayland) helpers have documented contracts
+but are not yet implemented.
+
+## Status & roadmap
+
+Implemented and tested: shared core, CLI wrapper (run/start/stop/pets),
+auto-start, daemon IPC + shutdown, adapters, PTY-based live observation,
+Codex-style session bubbles, the Electron overlay, and the Windows terminal
+helper. In progress:
+
+- Bidirectional IPC so the daemon routes replies/approvals back to the wrapper
+  (re-enabling the parked reply/approval UI).
+- macOS (Swift/AppKit) and Linux X11 terminal helpers.
+- Faithful PTY passthrough (see [known-issues.md](known-issues.md)).
+- Production overlay/IPC validation across all platforms.
+
+See [`../PROGRESS.md`](../PROGRESS.md) for the detailed log.

package/docs/known-issues.md

@@ -0,0 +1,49 @@
+# Known Issues (deferred)
+
+Issues found in live use that are **recorded for later** — not yet fixed. The
+decision on *how* to fix is pending.
+
+## 1. Terminal scrolling breaks when running a CLI through `haya-pet run` (observe/PTY mode)
+
+- **Symptom:** While a CLI is running under `haya-pet run` (default `--observe`), the
+  terminal window can no longer scroll normally.
+- **Trigger:** Only in observe (PTY) mode. The plain `--no-observe` path
+  (`stdio: "inherit"`) does not have this problem.
+- **Diagnosis:** Observe mode runs the CLI inside a `node-pty`/ConPTY pseudo-terminal
+  with a fixed `cols × rows` and tees its output to our `stdout`
+  (`packages/cli-core/src/pty-runner.js`). Full-screen TUIs (Claude Code, Codex)
+  render into that fixed grid, so the outer terminal's scrollback only ever sees
+  redraws of the grid rather than a growing transcript — there is effectively
+  nothing meaningful to scroll. On Windows there is an extra layer: shims are run
+  as `cmd /d /s /c "<shim> ..."` *inside* the PTY, so `cmd.exe` is the PTY's
+  foreground process and the TUI is its child.
+- **Notes for a future fix:** Tools like `script`/`asciinema` interpose a PTY
+  without breaking the terminal, so a faithful passthrough is achievable. Avenues:
+  resolve the shim and spawn the real executable directly in the PTY (drop the
+  `cmd /c` layer); verify `cols/rows` always match the host; revisit whether
+  observe should be the default for interactive TUIs vs. native passthrough.
+
+## 2. Backspace deletes a whole word instead of one character (observe/PTY mode)
+
+- **Symptom:** While a CLI is running under `haya-pet run`, pressing Backspace
+  deletes an entire word rather than a single character.
+- **Trigger:** Only in observe (PTY) mode. Native (`--no-observe`) is unaffected.
+- **Diagnosis:** stdin is put in raw mode and forwarded byte-for-byte into the PTY
+  (`pty-runner.js` `forwardInput` → `child.write(chunk.toString("utf8"))`). The
+  whole-word deletion points to a key-encoding/line-discipline mismatch between the
+  host terminal (Windows Terminal/conhost) and the nested ConPTY (and possibly the
+  intermediate `cmd /c`) — e.g. Backspace `0x7f`/`0x08` being interpreted by the
+  inner app as a word-delete (Ctrl+W `0x17` / Alt+Backspace `ESC 0x7f`), or input
+  bytes being re-segmented across `data` events.
+- **Notes for a future fix:** Forward stdin as raw bytes without a UTF-8 round-trip;
+  audit the exact bytes the host sends for Backspace vs. what the inner app receives
+  (a small PTY echo harness); consider removing the `cmd /c` layer; re-evaluate
+  raw-mode handling. Hard to fully verify without interactive testing.
+
+## Shared root cause & the open decision
+
+Both issues stem from observe mode interposing a pseudo-terminal on an interactive
+session. The plain wrapper path avoids them entirely but cannot report fine-grained
+"thinking / running tools" status. The open product decision: **native terminal by
+default (perfect fidelity, coarser status) vs. keep PTY observation default and
+invest in faithful passthrough.** Deferred until the maintainer decides.

package/docs/publishing.md

@@ -0,0 +1,48 @@
+# Publishing
+
+How Haya Pet is released to npm. Most users never need this — see the
+[README](../README.md) to install and use it.
+
+## Release flow
+
+Releases are automated by [`.github/workflows/release.yml`](../.github/workflows/release.yml):
+pushing a `v*` tag triggers a workflow that installs, runs the tests, checks the
+tag matches `package.json`, and publishes to npm.
+
+```bash
+npm version patch        # bumps package.json + creates tag vX.Y.Z
+git push --follow-tags   # pushes the tag → triggers the release workflow
+```
+
+The workflow installs with `ELECTRON_SKIP_BINARY_DOWNLOAD=1` (the ~150 MB binary
+isn't needed to test or publish) and publishes with
+`npm publish --provenance --access public` using the `NPM_TOKEN` secret.
+
+## One-time setup
+
+1. **`NPM_TOKEN` secret** — create an npm *automation* (or granular publish) token
+   at npmjs.com and add it under GitHub → repo Settings → Secrets and variables →
+   Actions → `NPM_TOKEN`.
+2. **Package name** — confirm the name in `package.json` is available
+   (`npm view <name>`); rename or use a scope (`@you/haya-pet`) if taken. The
+   workflow already passes `--access public` for scoped packages.
+3. **`private` removed** — `npm publish` refuses private packages; the root
+   `package.json` must not have `"private": true` (already removed).
+4. **Provenance / public repo** — `--provenance` requires a public repo and the
+   `id-token: write` permission (set in the workflow). Drop `--provenance` if the
+   repo is private.
+
+## Notes
+
+- **Local registry mirror.** If your local npm points at a mirror (e.g.
+  `registry.npmmirror.com`), don't `npm publish` locally — the workflow targets
+  `registry.npmjs.org` explicitly, which is what you want.
+- **Lockfile sync.** After changing dependencies in `package.json`, refresh the
+  lockfile (`npm install --package-lock-only`) and commit it, or CI's `npm ci`
+  will fail on the mismatch.
+- **Tarball contents.** The package ships the whole tree (`apps/` + `packages/`)
+  because modules import each other by relative path. Test files are currently
+  included; add a `"files"` allowlist to `package.json` to trim the tarball to
+  runtime code only.
+- **Runtime deps.** `electron` is a dependency (the CLI launches it); `node-pty`
+  is optional (native build; live observation degrades gracefully without it).

package/docs/screenshots/README.md

@@ -0,0 +1,7 @@
+Place screenshot PNGs referenced by the root README here (~800px wide):
+
+- `hero.png` — wide shot: the pet on the desktop with a couple of session bubbles
+- `pet-overlay.png` — the pet reacting to the highest-priority session
+- `session-bubbles.png` — bubbles expanded, showing per-session status icons
+- `folder-collapsed.png` — bubbles folded away beside the pet
+- `tray-menu.png` — the tray menu (show/hide, pets, reset position, Quit)

package/docs/troubleshooting.md

@@ -0,0 +1,36 @@
+# Troubleshooting
+
+Quick fixes for common issues. See also [known-issues.md](known-issues.md) for
+deferred problems with known root causes.
+
+| Symptom | Fix |
+|---|---|
+| `haya-pet: command not found` | Install globally (`npm i -g …`), or in a source checkout run `npm link` in the repo root, or call the file directly: `node <repo>/apps/cli/src/haya-pet.js`. |
+| Running a CLI starts the pet but not the command | Fixed — update to the latest version. (Was caused by the auto-start poll exiting early.) |
+| Pet doesn't react to a session | Launch the CLI via `haya-pet run …`. If the overlay didn't auto-start, run `haya-pet start`, or check `HAYA_PET_NO_AUTOSTART` isn't set. |
+| Pet shows a blue placeholder box | No spritesheet found — add a pet (see the README); behaviour is otherwise correct. |
+| Pet is off-screen / can't find it | Tray icon → **Reset Position**. |
+| Can't exit the pet | `haya-pet stop`, or right-click the tray icon → **Quit**. |
+| `haya-pet pets` shows "No pets found" | Add a pet folder with **both** `pet.json` and a spritesheet to a search path. |
+| Terminal scroll / backspace odd while a CLI runs under `haya-pet run` | Known PTY-observation tradeoff — see [known-issues.md](known-issues.md). Workaround: `haya-pet run --no-observe …`. |
+| `ENOENT … electron\path.txt` | Electron's install extraction was interrupted — see below. |
+
+## Fixing a broken Electron install
+
+If launching the overlay fails with `ENOENT … node_modules\electron\path.txt`,
+the Electron binary downloaded but extraction left `dist/` empty. The cached zip
+is fine, so re-extract it without re-downloading (PowerShell, from the repo root):
+
+```powershell
+$cache = Get-ChildItem "$env:LOCALAPPDATA\electron\Cache" -Recurse -Filter "electron-*.zip" |
+         Sort-Object LastWriteTime -Descending | Select-Object -First 1
+$dist  = "node_modules\electron\dist"
+Remove-Item -Recurse -Force $dist -ErrorAction SilentlyContinue
+New-Item -ItemType Directory $dist | Out-Null
+Expand-Archive -Path $cache.FullName -DestinationPath $dist -Force
+Set-Content "node_modules\electron\path.txt" "electron.exe" -NoNewline
+node_modules\.bin\electron --version            # should print the version
+```
+
+If `electron.exe` is missing even after a clean `Expand-Archive`, your antivirus
+likely quarantined it — allow `node_modules\electron\dist\electron.exe` and retry.

package/native/README.md

@@ -0,0 +1,80 @@
+# Native Window Helpers
+
+Terminal-window discovery is platform-specific and is isolated behind small,
+optional native helper processes. The JavaScript runtime never links native
+code directly; it spawns a helper and talks to it over a line-delimited JSON
+protocol on stdin/stdout. This keeps the daemon portable and lets the helper be
+written in the most appropriate language per OS (C#/Win32, Swift/AppKit, C/Xlib).
+
+The `apps/companion/src/main/terminal-locator.js` facade decides *which* helper
+strategy applies per platform (`win32-window-helper`, `macos-accessibility-helper`,
+`x11-window-helper`, or `manual-fallback`). When the strategy is implemented, the
+main process spawns the matching helper and uses this contract.
+
+## Transport
+
+- One JSON object per line (`\n`-delimited), UTF-8, on both stdin and stdout.
+- The helper is long-lived: it reads requests until stdin closes.
+- The helper must never write anything but protocol JSON to stdout. Diagnostics
+  go to stderr.
+
+## Requests
+
+```json
+{ "id": "req_1", "op": "capabilities" }
+```
+
+```json
+{ "id": "req_2", "op": "locate", "pid": 12345, "terminalPid": 5678 }
+```
+
+| Field | Meaning |
+|---|---|
+| `id` | Opaque correlation id echoed back in the response. |
+| `op` | `"capabilities"` or `"locate"`. |
+| `pid` | AI client process id (walk its parent tree to the terminal). |
+| `terminalPid` | Optional known terminal pid hint. |
+
+## Responses
+
+Capabilities:
+
+```json
+{ "id": "req_1", "ok": true, "capabilities": { "locate": true, "follow": false, "permission": "granted" } }
+```
+
+Locate (found):
+
+```json
+{
+  "id": "req_2",
+  "ok": true,
+  "window": {
+    "x": 100,
+    "y": 200,
+    "width": 1200,
+    "height": 760,
+    "displayId": "primary",
+    "title": "pwsh — project",
+    "confidence": 0.8
+  }
+}
+```
+
+Locate (not found / unsupported / permission denied):
+
+```json
+{ "id": "req_2", "ok": false, "error": "not_found" }
+```
+
+`error` is one of: `not_found`, `unsupported`, `permission_denied`, `invalid_request`.
+
+## Rules
+
+- Coordinates are in OS virtual-screen pixels; the runtime converts to the pet's
+  display/DPI space using `display-manager.js`.
+- A helper that cannot resolve a window must return `ok:false`, never guess.
+- `permission` in capabilities lets the UI explain why attachment is unavailable
+  (e.g. macOS Accessibility not granted) and fall back to manual/cluster bubbles.
+- Helpers are best-effort. The runtime always supports manual bubble positioning
+  when a helper reports `unsupported` or `permission_denied`.

package/native/linux-window-helper/README.md

@@ -0,0 +1,29 @@
+# Linux Window Helper
+
+Strategy ids: `x11-window-helper` (X11, best-effort) and `manual-fallback` (Wayland).
+
+Implements the shared helper protocol in [`../README.md`](../README.md).
+
+## Responsibility
+
+- On X11: discover terminal windows through Xlib (`_NET_WM_PID`, `XGetWindowProperty`)
+  or a `wmctrl`/`xdotool`-style approach, match the tracked process tree, and
+  return window bounds.
+- On Wayland: report limited capability instead of assuming global window
+  positioning works.
+
+## Implementation notes
+
+- Suggested language: C with Xlib/XCB, or a thin wrapper over `wmctrl`/`xdotool`.
+- X11: match `_NET_WM_PID` against the AI client's parent terminal pid; read
+  geometry via `XGetGeometry` + `XTranslateCoordinates` for absolute coordinates.
+- Wayland: most compositors block global window enumeration/positioning. The
+  helper should answer `capabilities` with `{ "locate": false }` and return
+  `{ "ok": false, "error": "unsupported" }` for `locate`, so the runtime uses
+  global pet + cluster/manual bubbles.
+
+## Protocol mapping
+
+- X11 `op: "capabilities"` → `{ "locate": true, "follow": false, "permission": "granted" }`.
+- Wayland `op: "capabilities"` → `{ "locate": false, "follow": false, "permission": "granted" }`.
+- `op: "locate"` → `window` rect on X11 when found, otherwise `not_found` / `unsupported`.

package/native/mac-window-helper/README.md

@@ -0,0 +1,30 @@
+# macOS Window Helper
+
+Strategy id: `macos-accessibility-helper` (best-effort).
+
+Implements the shared helper protocol in [`../README.md`](../README.md).
+
+## Responsibility
+
+- Locate Terminal.app, iTerm2, VS Code, or other terminal windows for tracked
+  process trees.
+- Use the Accessibility API (`AXUIElement`) or `CGWindowListCopyWindowInfo`
+  where permission is available.
+- Return window bounds and permission status for bubble attachment.
+
+## Implementation notes
+
+- Suggested language: Swift with AppKit/ApplicationServices.
+- Accessibility requires the user to grant permission in System Settings →
+  Privacy & Security → Accessibility. When not granted, return
+  `{ "ok": false, "error": "permission_denied" }` and report
+  `"permission": "denied"` from `capabilities` so the UI can prompt the user.
+- Handle Retina scale: report points and include the backing scale so the
+  runtime can map to device pixels.
+- Spaces/full-screen windows may be undiscoverable; return `not_found` rather
+  than guessing.
+
+## Protocol mapping
+
+- `op: "capabilities"` → `{ "locate": true, "follow": false, "permission": "granted" | "denied" }`.
+- `op: "locate"` → `window` rect on success, or `permission_denied` / `not_found`.