@hayasaka7/haya-pet 0.1.0

package/packages/app-state/src/state.js

@@ -0,0 +1,80 @@
+// Pure runtime state shape shared by the companion app and the CLI: global pet
+// position/selection, per-session bubble positions, and settings. All updates
+// return new objects (no mutation).
+
+export function createDefaultPositionState() {
+  return {
+    globalPet: {
+      open: true,
+      selectedPetId: undefined,
+      manual: false
+    },
+    sessions: {},
+    settings: {
+      displayMode: "hybrid",
+      attachBubblesToTerminals: true
+    }
+  };
+}
+
+export function updateGlobalPetPosition(state, position) {
+  return {
+    ...state,
+    globalPet: {
+      ...state.globalPet,
+      x: position.x,
+      y: position.y,
+      width: position.width,
+      height: position.height,
+      displayId: position.displayId,
+      manual: true
+    }
+  };
+}
+
+export function setSelectedPet(state, petId) {
+  return {
+    ...state,
+    globalPet: {
+      ...state.globalPet,
+      selectedPetId: petId
+    }
+  };
+}
+
+export function getSelectedPetId(state) {
+  return state?.globalPet?.selectedPetId;
+}
+
+export function serializePositionState(state) {
+  return `${JSON.stringify(state, null, 2)}\n`;
+}
+
+export function parsePositionState(text) {
+  const defaults = createDefaultPositionState();
+
+  try {
+    const parsed = JSON.parse(text);
+    if (!isPlainObject(parsed) || !isPlainObject(parsed.globalPet)) {
+      return defaults;
+    }
+
+    return {
+      globalPet: {
+        ...defaults.globalPet,
+        ...parsed.globalPet
+      },
+      sessions: isPlainObject(parsed.sessions) ? parsed.sessions : defaults.sessions,
+      settings: {
+        ...defaults.settings,
+        ...(isPlainObject(parsed.settings) ? parsed.settings : {})
+      }
+    };
+  } catch {
+    return defaults;
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/app-state/test/state.test.mjs

@@ -0,0 +1,36 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  createDefaultPositionState,
+  getSelectedPetId,
+  setSelectedPet
+} from "../src/state.js";
+
+test("default state has no selected pet", () => {
+  assert.equal(getSelectedPetId(createDefaultPositionState()), undefined);
+});
+
+test("setSelectedPet stores the id immutably", () => {
+  const state = createDefaultPositionState();
+  const next = setSelectedPet(state, "cat");
+
+  assert.equal(getSelectedPetId(next), "cat");
+  // original is untouched
+  assert.equal(getSelectedPetId(state), undefined);
+  assert.notEqual(next.globalPet, state.globalPet);
+});
+
+test("setSelectedPet preserves other globalPet fields", () => {
+  const state = { ...createDefaultPositionState(), globalPet: { open: true, x: 10, y: 20, manual: true } };
+  const next = setSelectedPet(state, "dog");
+
+  assert.equal(next.globalPet.x, 10);
+  assert.equal(next.globalPet.y, 20);
+  assert.equal(next.globalPet.manual, true);
+  assert.equal(next.globalPet.selectedPetId, "dog");
+});
+
+test("getSelectedPetId tolerates missing state", () => {
+  assert.equal(getSelectedPetId(undefined), undefined);
+  assert.equal(getSelectedPetId({}), undefined);
+});

package/packages/cli-core/src/companion-launcher.js

@@ -0,0 +1,69 @@
+// Orchestrates "connect to the companion, auto-starting it if it isn't running"
+// so `haya-pet run` works without anyone manually launching the overlay first.
+//
+// Pure and dependency-injected: the caller supplies how to `connect` (open an
+// IPC client, throwing if nothing is listening) and how to `launch` (spawn the
+// companion). This keeps the real Electron/IPC wiring out of the tested logic.
+
+const DEFAULT_ATTEMPTS = 25; // attempts * intervalMs ≈ how long we wait for boot
+const DEFAULT_INTERVAL_MS = 200;
+
+export async function ensureCompanionConnection({
+  connect,
+  launch,
+  autoStart = true,
+  attempts = DEFAULT_ATTEMPTS,
+  intervalMs = DEFAULT_INTERVAL_MS,
+  sleep = defaultSleep
+} = {}) {
+  if (typeof connect !== "function") {
+    throw new TypeError("connect must be a function");
+  }
+
+  // 1) Already running? Use it as-is.
+  const existing = await tryConnect(connect);
+  if (existing) {
+    return { client: existing, started: false };
+  }
+
+  if (!autoStart || typeof launch !== "function") {
+    return { client: null, started: false };
+  }
+
+  // 2) Launch the companion. A launch failure (e.g. Electron not installed)
+  //    must not break the wrapped command — degrade to "no pet".
+  try {
+    await launch();
+  } catch (error) {
+    return { client: null, started: false, error };
+  }
+
+  // 3) Poll until it's listening, or give up (still letting the command run).
+  for (let i = 0; i < attempts; i += 1) {
+    await sleep(intervalMs);
+    const client = await tryConnect(connect);
+    if (client) {
+      return { client, started: true };
+    }
+  }
+
+  return { client: null, started: false, timedOut: true };
+}
+
+async function tryConnect(connect) {
+  try {
+    return await connect();
+  } catch {
+    return null;
+  }
+}
+
+function defaultSleep(ms) {
+  // Deliberately NOT unref'd: during the connect-retry poll this timer is often
+  // the only pending handle, and an unref'd timer would let Node exit the
+  // process mid-poll (before the wrapped command ever runs). The timer is
+  // short-lived and always settles, so it can't hang the process.
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/packages/cli-core/src/pty-runner.js

@@ -0,0 +1,96 @@
+// Thin wrapper around the optional `node-pty` native module. Runs a command in
+// a real pseudo-terminal so interactive CLIs keep their TTY (colors, prompts,
+// TUIs) while we also observe a copy of the output. node-pty is loaded lazily
+// and treated as optional — callers fall back to a plain spawn if it is absent.
+
+let ptyModulePromise;
+
+async function loadPty() {
+  if (!ptyModulePromise) {
+    ptyModulePromise = import("node-pty")
+      .then((mod) => mod.default ?? mod)
+      .catch(() => null);
+  }
+  return ptyModulePromise;
+}
+
+export async function isPtyAvailable() {
+  return Boolean(await loadPty());
+}
+
+export async function spawnPty({ command, args = [], cwd, env = process.env, onData, onInput, cols, rows } = {}) {
+  const pty = await loadPty();
+  if (!pty) {
+    throw new Error("node-pty is not available");
+  }
+
+  const child = pty.spawn(command, args, {
+    name: "xterm-color",
+    cols: cols ?? process.stdout.columns ?? 80,
+    rows: rows ?? process.stdout.rows ?? 30,
+    cwd,
+    env
+  });
+
+  // Tee PTY output: write to the terminal and hand a copy to the observer.
+  child.onData((data) => {
+    process.stdout.write(data);
+    if (onData) {
+      onData(data);
+    }
+  });
+
+  // Forward the user's keystrokes into the PTY.
+  const stdin = process.stdin;
+  const hadRawMode = stdin.isRaw;
+  if (stdin.isTTY && typeof stdin.setRawMode === "function") {
+    stdin.setRawMode(true);
+  }
+  stdin.resume();
+  // Don't let an open stdin keep the process alive after the child exits — the
+  // PTY handle keeps the event loop alive while the command is actually running.
+  if (typeof stdin.unref === "function") {
+    stdin.unref();
+  }
+  const forwardInput = (chunk) => {
+    if (onInput) {
+      // Let the observer know the user is typing, so it doesn't mistake the
+      // PTY's echo of these keystrokes for AI activity.
+      onInput(chunk);
+    }
+    child.write(chunk.toString("utf8"));
+  };
+  stdin.on("data", forwardInput);
+
+  const handleResize = () => {
+    try {
+      child.resize(process.stdout.columns ?? 80, process.stdout.rows ?? 30);
+    } catch {
+      // ignore transient resize errors
+    }
+  };
+  process.stdout.on("resize", handleResize);
+
+  const exit = new Promise((resolve) => {
+    child.onExit(({ exitCode, signal }) => {
+      stdin.off("data", forwardInput);
+      if (stdin.isTTY && typeof stdin.setRawMode === "function") {
+        try {
+          stdin.setRawMode(Boolean(hadRawMode));
+        } catch {
+          // ignore
+        }
+      }
+      stdin.pause();
+      process.stdout.off("resize", handleResize);
+      resolve({ exitCode, signal });
+    });
+  });
+
+  return {
+    pid: child.pid,
+    exit,
+    write: (data) => child.write(data),
+    kill: () => child.kill()
+  };
+}

package/packages/cli-core/src/run-command.js

@@ -0,0 +1,353 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { basename } from "node:path";
+import { assertProtocolMessage } from "../../protocol/src/messages.js";
+import { createOutputObserver } from "../../adapters/src/output-observer.js";
+import { stripAnsi } from "./strip-ansi.js";
+import { isPtyAvailable, spawnPty as defaultSpawnPty } from "./pty-runner.js";
+
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5_000;
+
+export async function runGenericCommand(options) {
+  const {
+    command,
+    args = [],
+    cwd = process.cwd(),
+    clientId = "generic",
+    clientDisplayName = "Generic",
+    sessionId = `sess_${randomUUID()}`,
+    heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS,
+    now = Date.now,
+    send,
+    stdio = "inherit",
+    shell: shellOption,
+    observe = false,
+    spawnPty
+  } = options ?? {};
+
+  if (typeof command !== "string" || command.trim() === "") {
+    throw new Error("command must be a non-empty string");
+  }
+
+  if (!Array.isArray(args)) {
+    throw new TypeError("args must be an array");
+  }
+
+  if (typeof send !== "function") {
+    throw new TypeError("send must be a function");
+  }
+
+  // On Windows, AI CLIs are usually .cmd/.ps1 shims (e.g. `claude`, `codex`),
+  // which neither Node's spawn nor node-pty can launch directly — run them
+  // through the shell so PATHEXT resolution works. Direct .exe paths (incl.
+  // process.execPath in tests) keep shell off so argument quoting is untouched.
+  const isWindows = process.platform === "win32";
+  const useShell = shellOption ?? (isWindows && !/\.(exe|com)$/i.test(command));
+
+  // Level 2: observe the CLI's output through a PTY to infer live state
+  // (thinking / running_tool / waiting_approval / ...). Only when a PTY launcher
+  // is available; otherwise we fall back to the plain wrapper.
+  if (observe) {
+    const ptyLauncher = spawnPty ?? ((await isPtyAvailable()) ? defaultSpawnPty : undefined);
+    if (ptyLauncher) {
+      return runObservedCommand({
+        command,
+        args,
+        cwd,
+        useShell,
+        clientId,
+        clientDisplayName,
+        sessionId,
+        heartbeatIntervalMs,
+        now,
+        send,
+        spawnPty: ptyLauncher
+      });
+    }
+    process.stderr.write(
+      "haya-pet: live observation requested but node-pty is unavailable; running without live state.\n"
+    );
+  }
+
+  // With shell:true Node concatenates an args array without escaping (DEP0190),
+  // so when we need a shell we pass a single, pre-quoted command string instead.
+  const child = useShell
+    ? spawn(buildShellCommand(command, args), { cwd, stdio, shell: true })
+    : spawn(command, args, { cwd, stdio });
+  const closePromise = waitForClose(child);
+
+  if (!child.pid) {
+    // The command could not be launched at all (e.g. not found). Don't send an
+    // invalid register message; report the failure and preserve the exit code.
+    const closeResult = await closePromise;
+    return {
+      sessionId,
+      pid: undefined,
+      exitCode: normalizeExitCode(closeResult),
+      signal: closeResult.signal
+    };
+  }
+
+  const startedAt = now();
+  const projectName = basename(cwd) || cwd;
+
+  await sendProtocolMessage(send, {
+    type: "register",
+    sessionId,
+    clientId,
+    clientDisplayName,
+    pid: child.pid,
+    cwd,
+    projectName,
+    startedAt
+  });
+
+  // A Level 1 wrapper cannot observe what the CLI is actually doing, so it must
+  // not claim "running". "idle" = session exists but no active work detected.
+  // PTY/log adapters refine this later.
+  await sendProtocolMessage(send, {
+    type: "state",
+    sessionId,
+    state: "idle",
+    summary: "session started",
+    confidence: 0.4,
+    source: "wrapper",
+    updatedAt: now()
+  });
+
+  await sendProtocolMessage(send, {
+    type: "heartbeat",
+    sessionId,
+    updatedAt: now()
+  });
+
+  const timer = setInterval(() => {
+    sendProtocolMessage(send, {
+      type: "heartbeat",
+      sessionId,
+      updatedAt: now()
+    }).catch(() => {
+      clearInterval(timer);
+    });
+  }, heartbeatIntervalMs);
+
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+
+  const closeResult = await closePromise;
+  clearInterval(timer);
+
+  const exitCode = normalizeExitCode(closeResult);
+  const finalState = exitCode === 0 ? "success" : "failed";
+  const summary = buildExitSummary(closeResult, exitCode);
+
+  await sendProtocolMessage(send, {
+    type: "state",
+    sessionId,
+    state: finalState,
+    summary,
+    confidence: 1,
+    source: "wrapper",
+    updatedAt: now()
+  });
+
+  await sendProtocolMessage(send, {
+    type: "unregister",
+    sessionId,
+    exitCode,
+    finishedAt: now()
+  });
+
+  return {
+    sessionId,
+    pid: child.pid,
+    exitCode,
+    signal: closeResult.signal
+  };
+}
+
+async function runObservedCommand({
+  command,
+  args,
+  cwd,
+  useShell,
+  clientId,
+  clientDisplayName,
+  sessionId,
+  heartbeatIntervalMs,
+  now,
+  send,
+  spawnPty
+}) {
+  const startedAt = now();
+  const projectName = basename(cwd) || cwd;
+
+  // node-pty cannot resolve .cmd/.ps1 shims either, so wrap them in the shell.
+  let ptyCommand = command;
+  let ptyArgs = args;
+  if (useShell) {
+    ptyCommand = process.env.ComSpec || "cmd.exe";
+    ptyArgs = ["/d", "/s", "/c", buildShellCommand(command, args)];
+  }
+
+  // Buffer observed state until the session is registered, so the daemon never
+  // receives a state for an unknown session (output can arrive before register).
+  let registered = false;
+  let pendingState;
+
+  const emitState = (event) => {
+    sendProtocolMessage(send, {
+      type: "state",
+      sessionId,
+      state: event.state,
+      summary: event.summary,
+      confidence: event.confidence,
+      source: "pty_output",
+      updatedAt: event.updatedAt
+    }).catch(() => {});
+  };
+
+  const observer = createOutputObserver({
+    clientId,
+    now,
+    onState: (event) => {
+      if (registered) {
+        emitState(event);
+      } else {
+        pendingState = event;
+      }
+    }
+  });
+
+  const handle = await spawnPty({
+    command: ptyCommand,
+    args: ptyArgs,
+    cwd,
+    onData: (data) => observer.push(stripAnsi(data.toString())),
+    onInput: () => observer.noteInput()
+  });
+
+  await sendProtocolMessage(send, {
+    type: "register",
+    sessionId,
+    clientId,
+    clientDisplayName,
+    pid: handle.pid,
+    cwd,
+    projectName,
+    startedAt
+  });
+
+  await sendProtocolMessage(send, {
+    type: "state",
+    sessionId,
+    state: "idle",
+    summary: "session started",
+    confidence: 0.4,
+    source: "wrapper",
+    updatedAt: now()
+  });
+
+  registered = true;
+  if (pendingState) {
+    emitState(pendingState);
+    pendingState = undefined;
+  }
+
+  await sendProtocolMessage(send, { type: "heartbeat", sessionId, updatedAt: now() });
+
+  const timer = setInterval(() => {
+    sendProtocolMessage(send, { type: "heartbeat", sessionId, updatedAt: now() }).catch(() => {
+      clearInterval(timer);
+    });
+  }, heartbeatIntervalMs);
+  if (typeof timer.unref === "function") {
+    timer.unref();
+  }
+
+  const { exitCode, signal } = await handle.exit;
+  clearInterval(timer);
+  observer.stop();
+
+  const finalExitCode = Number.isInteger(exitCode) ? exitCode : 1;
+  const finalState = finalExitCode === 0 ? "success" : "failed";
+
+  await sendProtocolMessage(send, {
+    type: "state",
+    sessionId,
+    state: finalState,
+    summary: finalExitCode === 0 ? "process exited successfully" : `process exited with code ${finalExitCode}`,
+    confidence: 1,
+    source: "wrapper",
+    updatedAt: now()
+  });
+
+  await sendProtocolMessage(send, {
+    type: "unregister",
+    sessionId,
+    exitCode: finalExitCode,
+    finishedAt: now()
+  });
+
+  return { sessionId, pid: handle.pid, exitCode: finalExitCode, signal };
+}
+
+async function sendProtocolMessage(send, message) {
+  await send(assertProtocolMessage(message));
+}
+
+function waitForClose(child) {
+  return new Promise((resolve) => {
+    let spawnError;
+
+    child.once("error", (error) => {
+      spawnError = error;
+    });
+
+    child.once("close", (code, signal) => {
+      resolve({ code, signal, error: spawnError });
+    });
+  });
+}
+
+// Builds a single shell command line with each token quoted for the Windows
+// command processor (the only platform we default the shell on).
+function buildShellCommand(command, args) {
+  return [command, ...args].map(quoteShellArg).join(" ");
+}
+
+function quoteShellArg(arg) {
+  const value = String(arg);
+  if (value === "") {
+    return '""';
+  }
+  if (!/[\s"&|<>^()%!]/.test(value)) {
+    return value;
+  }
+  return `"${value.replace(/"/g, '""')}"`;
+}
+
+function normalizeExitCode(closeResult) {
+  if (Number.isInteger(closeResult.code)) {
+    return closeResult.code;
+  }
+
+  return 1;
+}
+
+function buildExitSummary(closeResult, exitCode) {
+  if (closeResult.error) {
+    return `process failed to start: ${closeResult.error.message}`;
+  }
+
+  if (closeResult.signal) {
+    return `process terminated by signal ${closeResult.signal}`;
+  }
+
+  if (exitCode === 0) {
+    return "process exited successfully";
+  }
+
+  return `process exited with code ${exitCode}`;
+}

package/packages/cli-core/src/strip-ansi.js

@@ -0,0 +1,16 @@
+// Removes ANSI/VT escape sequences (CSI, OSC, and single-char escapes) that a
+// PTY emits, so the output observer matches against plain text. Newlines are
+// preserved for line splitting.
+const ANSI_PATTERN = new RegExp(
+  [
+    // OSC sequences: ESC ] ... BEL  or  ESC ] ... ESC \
+    "[\\u001B\\u009B]\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+    // CSI and other escape sequences
+    "[\\u001B\\u009B][[\\]()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-PR-TZcf-ntqry=><~]"
+  ].join("|"),
+  "g"
+);
+
+export function stripAnsi(input) {
+  return String(input).replace(ANSI_PATTERN, "");
+}