@hayasaka7/haya-pet 0.1.0

package/packages/protocol/src/messages.js

@@ -0,0 +1,156 @@
+export const AI_CLIENT_STATES = Object.freeze([
+  "idle",
+  "thinking",
+  "running_tool",
+  "editing_files",
+  "waiting_user",
+  "waiting_approval",
+  "reviewing",
+  "compacting",
+  "failed",
+  "success",
+  "stale",
+  "exited"
+]);
+
+export const STATE_SOURCES = Object.freeze([
+  "wrapper",
+  "pty_output",
+  "client_log",
+  "client_state",
+  "official_plugin",
+  "manual"
+]);
+
+export const PROTOCOL_MESSAGE_TYPES = Object.freeze([
+  "register",
+  "heartbeat",
+  "state",
+  "unregister",
+  // Control message (not session-scoped): asks the daemon to shut down.
+  "shutdown"
+]);
+
+const AI_CLIENT_STATE_SET = new Set(AI_CLIENT_STATES);
+const STATE_SOURCE_SET = new Set(STATE_SOURCES);
+const MESSAGE_TYPE_SET = new Set(PROTOCOL_MESSAGE_TYPES);
+
+export function isAiClientState(value) {
+  return AI_CLIENT_STATE_SET.has(value);
+}
+
+export function isStateSource(value) {
+  return STATE_SOURCE_SET.has(value);
+}
+
+export function validateProtocolMessage(message) {
+  const errors = [];
+
+  if (!isPlainObject(message)) {
+    return { ok: false, errors: ["message must be an object"] };
+  }
+
+  if (!MESSAGE_TYPE_SET.has(message.type)) {
+    return {
+      ok: false,
+      errors: [`Unknown protocol message type: ${String(message.type)}`]
+    };
+  }
+
+  // Control messages are daemon-wide, not tied to a session.
+  if (message.type === "shutdown") {
+    return { ok: true, errors: [] };
+  }
+
+  requireNonEmptyString(errors, message.sessionId, "sessionId");
+
+  switch (message.type) {
+    case "register":
+      validateRegisterMessage(errors, message);
+      break;
+    case "heartbeat":
+      requireFiniteNumber(errors, message.updatedAt, "updatedAt");
+      break;
+    case "state":
+      validateStateMessage(errors, message);
+      break;
+    case "unregister":
+      validateUnregisterMessage(errors, message);
+      break;
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+export function assertProtocolMessage(message) {
+  const result = validateProtocolMessage(message);
+  if (!result.ok) {
+    throw new Error(result.errors.join("; "));
+  }
+
+  return message;
+}
+
+function validateRegisterMessage(errors, message) {
+  requireNonEmptyString(errors, message.clientId, "clientId");
+  requireNonEmptyString(errors, message.clientDisplayName, "clientDisplayName");
+  requirePositiveInteger(errors, message.pid, "pid");
+
+  if (message.terminalPid !== undefined) {
+    requirePositiveInteger(errors, message.terminalPid, "terminalPid");
+  }
+
+  requireNonEmptyString(errors, message.cwd, "cwd");
+  requireNonEmptyString(errors, message.projectName, "projectName");
+  requireFiniteNumber(errors, message.startedAt, "startedAt");
+}
+
+function validateStateMessage(errors, message) {
+  if (!isAiClientState(message.state)) {
+    errors.push(`state must be one of: ${AI_CLIENT_STATES.join(", ")}`);
+  }
+
+  if (!isStateSource(message.source)) {
+    errors.push(`source must be one of: ${STATE_SOURCES.join(", ")}`);
+  }
+
+  if (typeof message.summary !== "undefined" && typeof message.summary !== "string") {
+    errors.push("summary must be a string when provided");
+  }
+
+  if (!Number.isFinite(message.confidence) || message.confidence < 0 || message.confidence > 1) {
+    errors.push("confidence must be a number from 0 to 1");
+  }
+
+  requireFiniteNumber(errors, message.updatedAt, "updatedAt");
+}
+
+function validateUnregisterMessage(errors, message) {
+  if (message.exitCode !== undefined && !Number.isInteger(message.exitCode)) {
+    errors.push("exitCode must be an integer when provided");
+  }
+
+  requireFiniteNumber(errors, message.finishedAt, "finishedAt");
+}
+
+function requireNonEmptyString(errors, value, fieldName) {
+  if (typeof value !== "string" || value.trim() === "") {
+    errors.push(`${fieldName} must be a non-empty string`);
+  }
+}
+
+function requireFiniteNumber(errors, value, fieldName) {
+  if (!Number.isFinite(value)) {
+    errors.push(`${fieldName} must be a finite number`);
+  }
+}
+
+function requirePositiveInteger(errors, value, fieldName) {
+  if (!Number.isInteger(value) || value <= 0) {
+    errors.push(`${fieldName} must be a positive integer`);
+  }
+}
+
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/protocol/test/messages.test.mjs

@@ -0,0 +1,112 @@
+import assert from "node:assert/strict";
+import { test } from "../../../test/harness.mjs";
+import {
+  AI_CLIENT_STATES,
+  STATE_SOURCES,
+  assertProtocolMessage,
+  isAiClientState,
+  isStateSource,
+  validateProtocolMessage
+} from "../src/messages.js";
+
+test("declares normalized AI states and state sources from the plan", () => {
+  assert.deepEqual(AI_CLIENT_STATES, [
+    "idle",
+    "thinking",
+    "running_tool",
+    "editing_files",
+    "waiting_user",
+    "waiting_approval",
+    "reviewing",
+    "compacting",
+    "failed",
+    "success",
+    "stale",
+    "exited"
+  ]);
+
+  assert.deepEqual(STATE_SOURCES, [
+    "wrapper",
+    "pty_output",
+    "client_log",
+    "client_state",
+    "official_plugin",
+    "manual"
+  ]);
+
+  assert.equal(isAiClientState("waiting_approval"), true);
+  assert.equal(isAiClientState("busy"), false);
+  assert.equal(isStateSource("wrapper"), true);
+  assert.equal(isStateSource("network"), false);
+});
+
+test("accepts valid lifecycle protocol messages", () => {
+  const messages = [
+    {
+      type: "register",
+      sessionId: "sess_abc123",
+      clientId: "generic",
+      clientDisplayName: "Generic",
+      pid: 12345,
+      terminalPid: 6789,
+      cwd: "D:\\Work\\project",
+      projectName: "project",
+      startedAt: 1780000000
+    },
+    {
+      type: "heartbeat",
+      sessionId: "sess_abc123",
+      updatedAt: 1780000010
+    },
+    {
+      type: "state",
+      sessionId: "sess_abc123",
+      state: "waiting_approval",
+      summary: "waiting for command approval",
+      confidence: 0.86,
+      source: "pty_output",
+      updatedAt: 1780000010
+    },
+    {
+      type: "unregister",
+      sessionId: "sess_abc123",
+      exitCode: 0,
+      finishedAt: 1780000200
+    }
+  ];
+
+  for (const message of messages) {
+    assert.deepEqual(validateProtocolMessage(message), { ok: true, errors: [] });
+    assert.equal(assertProtocolMessage(message), message);
+  }
+});
+
+test("reports all useful validation errors for invalid state messages", () => {
+  const result = validateProtocolMessage({
+    type: "state",
+    sessionId: "",
+    state: "busy",
+    confidence: 2,
+    source: "network",
+    updatedAt: "now"
+  });
+
+  assert.equal(result.ok, false);
+  assert.match(result.errors.join("\n"), /sessionId must be a non-empty string/);
+  assert.match(result.errors.join("\n"), /state must be one of/);
+  assert.match(result.errors.join("\n"), /confidence must be a number from 0 to 1/);
+  assert.match(result.errors.join("\n"), /source must be one of/);
+  assert.match(result.errors.join("\n"), /updatedAt must be a finite number/);
+});
+
+test("rejects unknown message types", () => {
+  assert.throws(
+    () => assertProtocolMessage({ type: "unknown", sessionId: "sess_abc123" }),
+    /Unknown protocol message type: unknown/
+  );
+});
+
+test("accepts a shutdown control message without a sessionId", () => {
+  assert.deepEqual(validateProtocolMessage({ type: "shutdown" }), { ok: true, errors: [] });
+  assert.deepEqual(assertProtocolMessage({ type: "shutdown" }), { type: "shutdown" });
+});

package/packages/session-core/src/bubble-linger.js

@@ -0,0 +1,47 @@
+// When an AI session's process finishes, its bubble should not vanish instantly
+// — the user wants to glimpse the final outcome (a green check or a red cross).
+// This pure resolver keeps an ended bubble visible for a short linger window,
+// then hides it, while the registry keeps the session around a little longer.
+//
+// It is stateless across calls: the caller threads `lingerState` (a map of
+// sessionId -> the timestamp the session was FIRST seen ended) back in each
+// time, and re-renders once at `nextWakeMs` so the bubble disappears on schedule
+// even if no new session event arrives.
+
+// Process-finished states. A turn merely going quiet is "idle" (still alive) and
+// is NOT included here, so live sessions never linger-out.
+export const ENDED_STATES = new Set(["exited", "success", "failed"]);
+
+const DEFAULT_LINGER_MS = 2000;
+
+export function resolveVisibleBubbles({ bubbles = [], now = Date.now(), lingerState = {}, lingerMs = DEFAULT_LINGER_MS } = {}) {
+  const visible = [];
+  const nextLingerState = {};
+  let nextWakeMs = Infinity;
+
+  for (const bubble of bubbles) {
+    if (!ENDED_STATES.has(bubble.state)) {
+      visible.push(bubble);
+      continue;
+    }
+
+    // Anchor the clock to the first ended state we saw, so a follow-up message
+    // (success -> exited) does not restart the countdown.
+    const since = lingerState[bubble.sessionId] ?? now;
+    nextLingerState[bubble.sessionId] = since;
+
+    const remaining = lingerMs - (now - since);
+    if (remaining > 0) {
+      visible.push(bubble);
+      nextWakeMs = Math.min(nextWakeMs, remaining);
+    }
+    // remaining <= 0 -> hidden, but kept in nextLingerState so a re-appearing
+    // payload (registry still holds the exited session) does not flash it back.
+  }
+
+  return {
+    visible,
+    lingerState: nextLingerState,
+    nextWakeMs: Number.isFinite(nextWakeMs) ? nextWakeMs : undefined
+  };
+}

package/packages/session-core/src/bubble-view.js

@@ -0,0 +1,79 @@
+import { mapAiStateToPetAction } from "../../pet-core/src/atlas.js";
+import { getSessionPriorityRank } from "./priority.js";
+import { buildSessionSummary, buildStatusLabel, formatElapsed } from "./summaries.js";
+
+// Collapses the full AI-state vocabulary into the four progress kinds the
+// bubble panel renders: a spinning "working" circle, a "done" check mark (held
+// until the next turn refreshes it), a yellow "attention" cue when the session
+// needs the user, and a red "failed" cross. Unknown states fall back to a
+// neutral "idle" dot rather than guessing.
+const STATUS_KIND_BY_STATE = Object.freeze({
+  thinking: "working",
+  running_tool: "working",
+  editing_files: "working",
+  reviewing: "working",
+  compacting: "working",
+  waiting_user: "attention",
+  waiting_approval: "attention",
+  stale: "attention",
+  failed: "failed",
+  idle: "done",
+  success: "done",
+  exited: "done"
+});
+
+export function resolveBubbleStatusKind(state) {
+  return STATUS_KIND_BY_STATE[state] ?? "idle";
+}
+
+export function buildBubbleView(session, now = Date.now(), options = {}) {
+  const elapsedMs = Math.max(0, numeric(now) - numeric(session.startedAt));
+
+  return {
+    sessionId: session.sessionId,
+    clientId: session.clientId,
+    clientName: session.clientDisplayName ?? session.clientId,
+    projectName: session.projectName,
+    state: session.state,
+    statusLabel: buildStatusLabel(session.state),
+    statusKind: resolveBubbleStatusKind(session.state),
+    summary: buildSessionSummary(session),
+    petAction: safePetAction(session.state),
+    elapsedMs,
+    elapsedLabel: formatElapsed(elapsedMs),
+    selected: options.selectedSessionId === session.sessionId
+  };
+}
+
+export function buildBubbleViews(sessions, now = Date.now(), options = {}) {
+  if (!Array.isArray(sessions)) {
+    throw new TypeError("sessions must be an array");
+  }
+
+  return sessions
+    .filter(Boolean)
+    .slice()
+    .sort(compareByPriority)
+    .map((session) => buildBubbleView(session, now, options));
+}
+
+function compareByPriority(left, right) {
+  const rankDelta = getSessionPriorityRank(left) - getSessionPriorityRank(right);
+  if (rankDelta !== 0) {
+    return rankDelta;
+  }
+
+  return numeric(right.updatedAt) - numeric(left.updatedAt);
+}
+
+function safePetAction(state) {
+  try {
+    return mapAiStateToPetAction(state);
+  } catch {
+    return "idle";
+  }
+}
+
+function numeric(value) {
+  return Number.isFinite(value) ? value : 0;
+}

package/packages/session-core/src/pet-state.js

@@ -0,0 +1,56 @@
+import { mapAiStateToPetAction } from "../../pet-core/src/atlas.js";
+
+// Sessions that are done — removed from the active bubble list.
+const TERMINAL_STATES = new Set(["exited", "success"]);
+
+// States that should NOT drive a looping stable action. success/exited are
+// terminal; failed is a timed reaction (a stray error must not pin the pet on
+// the "failed" animation forever).
+const NON_STABLE_STATES = new Set(["exited", "success", "failed"]);
+
+// States that play a one-shot reaction exactly once when first entered.
+const ONE_SHOT_BY_STATE = Object.freeze({
+  success: "jumping",
+  failed: "failed"
+});
+
+// Active-work states. Transitioning from one of these to idle means a turn
+// finished, which plays a "done" reaction (the session stays alive/idle).
+const WORKING_STATES = new Set(["thinking", "running_tool", "editing_files", "reviewing", "compacting"]);
+
+// Pure resolver for the global pet's stable action and one-shot reactions from
+// the current session bubbles. Tracks the previous per-session state so success
+// jumps / failure reactions fire once, then the pet settles to the most urgent
+// ongoing work, or idle when nothing is active.
+export function resolveCompanionPetState({ bubbles = [], prioritySessionId, previousStates = {} } = {}) {
+  const oneShots = [];
+  const nextStates = {};
+
+  for (const bubble of bubbles) {
+    nextStates[bubble.sessionId] = bubble.state;
+    const previous = previousStates[bubble.sessionId];
+    const reaction = ONE_SHOT_BY_STATE[bubble.state];
+
+    if (reaction && previous !== bubble.state) {
+      oneShots.push(reaction);
+    } else if (bubble.state === "idle" && WORKING_STATES.has(previous)) {
+      // A turn just finished (work went quiet) — celebrate, then settle to idle.
+      oneShots.push("jumping");
+    }
+  }
+
+  const activeBubbles = bubbles.filter((bubble) => !TERMINAL_STATES.has(bubble.state));
+  const drivable = activeBubbles.filter((bubble) => !NON_STABLE_STATES.has(bubble.state));
+  const priority = drivable.find((bubble) => bubble.sessionId === prioritySessionId) ?? drivable[0];
+  const stableAction = priority ? safeAction(priority.state) : "idle";
+
+  return { stableAction, oneShots, activeBubbles, nextStates };
+}
+
+function safeAction(state) {
+  try {
+    return mapAiStateToPetAction(state);
+  } catch {
+    return "idle";
+  }
+}

package/packages/session-core/src/priority.js

@@ -0,0 +1,56 @@
+const PRIORITY_RANKS = Object.freeze({
+  waiting_approval: 1,
+  waiting_user: 2,
+  failed: 3,
+  running_tool: 4,
+  editing_files: 4,
+  thinking: 5,
+  reviewing: 5,
+  compacting: 5,
+  success: 6,
+  stale: 6,
+  idle: 7,
+  exited: 8
+});
+
+export function getSessionPriorityRank(session) {
+  return PRIORITY_RANKS[session.state] ?? 6;
+}
+
+export function selectPrioritySession(sessions, options = {}) {
+  if (!Array.isArray(sessions)) {
+    throw new TypeError("sessions must be an array");
+  }
+
+  const candidates = sessions.filter(Boolean);
+  if (candidates.length === 0) {
+    return undefined;
+  }
+
+  if (options.pinnedSessionId) {
+    const pinnedSession = candidates.find((session) => session.sessionId === options.pinnedSessionId);
+    if (pinnedSession) {
+      return pinnedSession;
+    }
+  }
+
+  return candidates.slice().sort(compareSessionsByPriority)[0];
+}
+
+function compareSessionsByPriority(left, right) {
+  const rankDelta = getSessionPriorityRank(left) - getSessionPriorityRank(right);
+  if (rankDelta !== 0) {
+    return rankDelta;
+  }
+
+  const updatedDelta = numericTimestamp(right.updatedAt) - numericTimestamp(left.updatedAt);
+  if (updatedDelta !== 0) {
+    return updatedDelta;
+  }
+
+  return String(left.sessionId).localeCompare(String(right.sessionId));
+}
+
+function numericTimestamp(value) {
+  return Number.isFinite(value) ? value : 0;
+}

package/packages/session-core/src/registry.js

@@ -0,0 +1,144 @@
+import { assertProtocolMessage } from "../../protocol/src/messages.js";
+import { selectPrioritySession } from "./priority.js";
+
+const DEFAULT_STALE_AFTER_MS = 30_000;
+const DEFAULT_DROP_AFTER_MS = 120_000;
+
+export function createSessionRegistry(options = {}) {
+  return new SessionRegistry(options);
+}
+
+class SessionRegistry {
+  constructor(options) {
+    this.sessions = new Map();
+    this.staleAfterMs = options.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+    this.dropAfterMs = options.dropAfterMs ?? DEFAULT_DROP_AFTER_MS;
+  }
+
+  applyMessage(message) {
+    assertProtocolMessage(message);
+
+    switch (message.type) {
+      case "register":
+        return this.register(message);
+      case "heartbeat":
+        return this.applyHeartbeat(message);
+      case "state":
+        return this.applyState(message);
+      case "unregister":
+        return this.unregister(message);
+      default:
+        throw new Error(`Unsupported protocol message type: ${message.type}`);
+    }
+  }
+
+  getSession(sessionId) {
+    return snapshotSession(this.sessions.get(sessionId));
+  }
+
+  listSessions() {
+    return Array.from(this.sessions.values(), snapshotSession);
+  }
+
+  getPrioritySession(options = {}) {
+    return selectPrioritySession(this.listSessions(), options);
+  }
+
+  markStaleSessions(now) {
+    if (!Number.isFinite(now)) {
+      throw new TypeError("now must be a finite timestamp");
+    }
+
+    const staleSessions = [];
+
+    for (const [sessionId, session] of this.sessions) {
+      // Drop sessions with no real activity for dropAfterMs (dead wrappers that
+      // never sent unregister, or long-finished sessions) so the pet does not
+      // sit on a phantom session forever. The drop clock is based on the last
+      // real update — marking stale must NOT bump updatedAt, or it never elapses.
+      if (now - session.updatedAt > this.dropAfterMs) {
+        this.sessions.delete(sessionId);
+        continue;
+      }
+
+      if (session.state === "exited" || session.state === "stale") {
+        continue;
+      }
+
+      if (now - session.updatedAt > this.staleAfterMs) {
+        session.state = "stale";
+        session.source = "wrapper";
+        session.confidence = 0.3;
+        session.summary = "heartbeat stale";
+        staleSessions.push(snapshotSession(session));
+      }
+    }
+
+    return staleSessions;
+  }
+
+  register(message) {
+    const session = {
+      sessionId: message.sessionId,
+      clientId: message.clientId,
+      clientDisplayName: message.clientDisplayName,
+      pid: message.pid,
+      terminalPid: message.terminalPid,
+      cwd: message.cwd,
+      projectName: message.projectName,
+      state: "idle",
+      source: "wrapper",
+      startedAt: message.startedAt,
+      updatedAt: message.startedAt
+    };
+
+    this.sessions.set(message.sessionId, session);
+    return snapshotSession(session);
+  }
+
+  applyHeartbeat(message) {
+    const session = this.requireSession(message.sessionId);
+    session.updatedAt = message.updatedAt;
+    return snapshotSession(session);
+  }
+
+  applyState(message) {
+    const session = this.requireSession(message.sessionId);
+    session.state = message.state;
+    session.confidence = message.confidence;
+    session.source = message.source;
+    session.updatedAt = message.updatedAt;
+
+    if (Object.prototype.hasOwnProperty.call(message, "summary")) {
+      session.summary = message.summary;
+    } else {
+      delete session.summary;
+    }
+
+    return snapshotSession(session);
+  }
+
+  unregister(message) {
+    const session = this.requireSession(message.sessionId);
+    session.state = "exited";
+    session.source = "wrapper";
+    session.confidence = 1;
+    session.exitCode = message.exitCode;
+    session.finishedAt = message.finishedAt;
+    session.updatedAt = message.finishedAt;
+    return snapshotSession(session);
+  }
+
+  requireSession(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) {
+      throw new Error(`Unknown session: ${sessionId}`);
+    }
+
+    return session;
+  }
+}
+
+function snapshotSession(session) {
+  return session ? { ...session } : undefined;
+}