@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/coding-agents/global/backend.ts

@@ -0,0 +1,402 @@
+// ponytail: see packages/addons/app-shortcuts/src/index.ts for context.
+import type {
+  AddonGlobalPoller,
+  AddonGlobalService,
+  AddonGlobalSubscription,
+  AddonServiceContext,
+  AddonServiceMethod,
+} from "../types/types.js"
+import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { registerIconForDeck, getAssetByPath } from "@/core/icon-asset-registry"
+import { resolveDaemonPaths } from "@/util/daemon"
+import {
+  agentKey,
+  CHANNEL,
+  EMPTY_SNAPSHOT,
+  type Agent,
+  type AgentsSnapshot,
+  type ProviderId,
+} from "../shared/state.js"
+import { mergeSnapshot, listAgents } from "../shared/snapshot.js"
+import { deckTarget, setLiveCount } from "../shared/live-count.js"
+import { NotificationThrottle } from "../shared/notifier.js"
+import {
+  loadProviders,
+  type ProviderRegistryConfig,
+} from "../providers/registry.js"
+
+export const POLLER_INTERVAL_MS = 2000
+
+// ponytail: a wedged provider (hung fetch, wedged serve process) must not
+// freeze the poll loop — race each snapshot and keep the last-known list.
+const PROVIDER_SNAPSHOT_TIMEOUT_MS = 10_000
+
+interface GlobalState {
+  providers: Map<ProviderId, import("../shared/state.js").AgentProvider>
+  spawnedChild: { kill: () => Promise<void> } | null
+  unsubscribers: Array<() => void>
+  lastSnapshot: AgentsSnapshot
+  lastSeenStatus: Map<string, import("../shared/state.js").AgentStatus>
+  throttle: NotificationThrottle
+  context: AddonServiceContext | null
+  icons: Partial<Record<ProviderId, string>>
+}
+
+const state: GlobalState = {
+  providers: new Map(),
+  spawnedChild: null,
+  unsubscribers: [],
+  lastSnapshot: EMPTY_SNAPSHOT,
+  lastSeenStatus: new Map(),
+  throttle: new NotificationThrottle(),
+  context: null,
+  icons: {},
+}
+
+// ponytail: deck re-materialization tracking — when the live agent count
+// changes, ask the host to rebuild the (dynamic) agents deck so page count
+// follows reality. Debounced to avoid rebuild storms during rapid churn.
+let lastLiveCount = -1
+let rebuildTimer: ReturnType<typeof setTimeout> | null = null
+
+const REBUILD_DEBOUNCE_MS = 1500
+
+const syncLiveCountAndMaybeRebuild = (): void => {
+  const count = listAgents(state.lastSnapshot).length
+  setLiveCount(count)
+  if (count === lastLiveCount) return
+  const wasEmpty = lastLiveCount <= 0
+  lastLiveCount = count
+  if (rebuildTimer !== null) clearTimeout(rebuildTimer)
+
+  // ponytail: the deck bakes one tile per live agent at materialisation time,
+  // so it is only right if a rebuild happens AFTER the first provider scan
+  // lands. The debounce below is there to absorb churn, but it also applied to
+  // the very first 0 -> N transition — and the deck is first materialised at
+  // startup when the count is still 0. Whether you got one tile or seven then
+  // depended on how the first scan raced a single debounced rebuild, which is
+  // why the deck could show a lone tile while the summary counted seven.
+  //
+  // Agents appearing from nothing is not churn; rebuild for it at once and
+  // keep the debounce for everything after.
+  if (wasEmpty && count > 0) {
+    rebuildTimer = null
+    state.context?.requestDeckRebuild?.()
+    return
+  }
+  rebuildTimer = setTimeout(() => {
+    rebuildTimer = null
+    state.context?.requestDeckRebuild?.()
+  }, REBUILD_DEBOUNCE_MS)
+}
+
+// ponytail: register both provider logos as WS assets (absolute paths, so no
+// addonDirs needed) and publish their `asset://` ids in the snapshot. This is
+// the only path that works in BOTH dev (vite middleware) and real (screenshots)
+// mode — a bare `addon://` <img> would 404 in the real HTTP server.
+const registerProviderIcons = (): Partial<Record<ProviderId, string>> => {
+  const assets: Array<[ProviderId, string]> = [
+    ["opencode", "assets/opencode-dark-square.svg"],
+    ["claude-code", "assets/claude-code.svg"],
+  ]
+  const resolved: Array<[ProviderId, string]> = []
+  for (const [id, rel] of assets) {
+    try {
+      const full = fileURLToPath(new URL(`../${rel}`, import.meta.url))
+      registerIconForDeck(
+        [{ id: `${id}-logo`, type: "icon", config: { icon: full } }],
+        {},
+      )
+      const asset = getAssetByPath(full)
+      if (asset !== undefined) resolved.push([id, `asset://${asset.id}`])
+    } catch {
+      // icon registration is best-effort; tiles fall back to text labels
+    }
+  }
+  return Object.fromEntries(resolved) as Partial<Record<ProviderId, string>>
+}
+
+// --- reboot survival -------------------------------------------------------
+// ponytail: persists lastSnapshot + lastSeenStatus under dataDir
+// (XDG_STATE_HOME) so a systemd auto-restart after reboot rehydrates instead
+// of replaying every agent as a fresh notification and showing an empty deck
+// for one poll tick. No staleness cap — mergeSnapshot replaces per-provider
+// lists wholesale on first live fetch, so stale data self-heals within ~2s.
+
+const PERSISTED_FILE = "coding-agents-state.json"
+
+interface PersistedState {
+  snapshot: AgentsSnapshot
+  lastSeenStatus: Array<[string, import("../shared/state.js").AgentStatus]>
+}
+
+const persistedStateFile = (): string | null => {
+  try {
+    return join(resolveDaemonPaths().dataDir, PERSISTED_FILE)
+  } catch {
+    return null
+  }
+}
+
+const persistState = (): void => {
+  const file = persistedStateFile()
+  if (file === null) return
+  try {
+    const payload: PersistedState = {
+      snapshot: state.lastSnapshot,
+      lastSeenStatus: [...state.lastSeenStatus],
+    }
+    const tmp = `${file}.tmp.${process.pid}`
+    writeFileSync(tmp, JSON.stringify(payload), "utf8")
+    renameSync(tmp, file)
+  } catch {
+    // best-effort — disk full, perms, sandbox; never break the poll loop
+  }
+}
+
+const hydratePersisted = (): void => {
+  const file = persistedStateFile()
+  if (file === null) return
+  try {
+    if (!existsSync(file)) return
+    const raw = JSON.parse(
+      readFileSync(file, "utf8"),
+    ) as Partial<PersistedState>
+    if (
+      raw.snapshot &&
+      typeof raw.snapshot === "object" &&
+      typeof raw.snapshot.byProvider === "object" &&
+      raw.snapshot.byProvider !== null
+    ) {
+      // recompute attention + generatedAt from real statuses instead of
+      // trusting the serialized copy
+      state.lastSnapshot = mergeSnapshot(EMPTY_SNAPSHOT, {
+        opencode: raw.snapshot.byProvider["opencode"] ?? [],
+        "claude-code": raw.snapshot.byProvider["claude-code"] ?? [],
+      })
+    }
+    if (Array.isArray(raw.lastSeenStatus)) {
+      state.lastSeenStatus = new Map(raw.lastSeenStatus)
+    }
+  } catch {
+    // corrupt or unreadable → cold start; first publish overwrites the file
+  }
+}
+
+const setStateFromProviders = async (): Promise<void> => {
+  const next: Record<ProviderId, Agent[]> = {
+    opencode: [],
+    "claude-code": [],
+  }
+  for (const [id, provider] of state.providers) {
+    const lastKnown = state.lastSnapshot.byProvider[id] ?? []
+    try {
+      const agents = await Promise.race([
+        provider.fetchSnapshot(
+          state.context?.signal ?? new AbortController().signal,
+        ),
+        new Promise<readonly Agent[]>((resolve) =>
+          setTimeout(() => resolve(lastKnown), PROVIDER_SNAPSHOT_TIMEOUT_MS),
+        ),
+      ])
+      next[id] = [...agents]
+    } catch {
+      // provider transiently unavailable — keep last-known (don't wipe)
+      next[id] = [...lastKnown]
+    }
+  }
+  state.lastSnapshot = mergeSnapshot(state.lastSnapshot, next)
+  persistState()
+}
+
+const fireNotices = (snapshot: AgentsSnapshot): void => {
+  for (const list of Object.values(snapshot.byProvider)) {
+    for (const a of list) {
+      const k = agentKey(a)
+      const prev = state.lastSeenStatus.get(k)
+      if (prev === a.status) continue
+      state.lastSeenStatus.set(k, a.status)
+      state.throttle.evaluate({
+        providerId: a.providerId,
+        sessionId: a.sessionId,
+        status: a.status,
+        title: `${a.providerId === "opencode" ? "OpenCode" : "Claude Code"}: ${humanStatus(a.status)}`,
+        body: a.title,
+      })
+    }
+  }
+}
+
+const humanStatus = (s: import("../shared/state.js").AgentStatus): string => {
+  switch (s) {
+    case "idle":
+      return "Idle"
+    case "running":
+      return "Running"
+    case "waiting":
+      return "Waiting"
+    case "waiting_for_human":
+      return "Needs approval"
+    case "error":
+      return "Error"
+    case "compacting":
+      return "Compacting"
+  }
+}
+
+const publishSnapshot = (): AgentsSnapshot => {
+  syncLiveCountAndMaybeRebuild()
+  const payload: AgentsSnapshot = {
+    ...state.lastSnapshot,
+    icons: state.icons,
+  }
+  state.context?.publish(payload)
+  return payload
+}
+
+const poller: AddonGlobalPoller = {
+  id: "agents",
+  channel: CHANNEL,
+  intervalMs: POLLER_INTERVAL_MS,
+  poll: async (ctx: AddonServiceContext) => {
+    state.context = ctx
+    await setStateFromProviders()
+    fireNotices(state.lastSnapshot)
+    return publishSnapshot()
+  },
+}
+
+const subscription: AddonGlobalSubscription = {
+  channel: CHANNEL,
+  subscribe: (ctx: AddonServiceContext) => {
+    state.context = ctx
+    const unsubs: Array<() => void> = []
+    for (const [id, provider] of state.providers) {
+      const unsub = provider.subscribe(ctx.signal, () => {
+        void (async () => {
+          await setStateFromProviders()
+          fireNotices(state.lastSnapshot)
+          publishSnapshot()
+        })()
+      })
+      unsubs.push(unsub)
+      // record for unbind on addon unload (provider id captured for log only)
+      void id
+    }
+    state.unsubscribers = unsubs
+    return {
+      unsubscribe: () => {
+        for (const u of unsubs) {
+          try {
+            u()
+          } catch {
+            // ignore — provider may have already closed
+          }
+        }
+        state.unsubscribers = []
+      },
+    }
+  },
+}
+
+export const globalService: AddonGlobalService = {
+  pollers: [poller],
+  subscriptions: [subscription],
+  methods: {
+    getSnapshot: (() => state.lastSnapshot) as AddonServiceMethod,
+    getDeckTarget: (() => deckTarget()) as AddonServiceMethod,
+    dismissAttention: ((key: unknown) => {
+      if (typeof key !== "string") return
+      const [providerId, sessionId] = key.split(":")
+      if (!providerId || !sessionId) return
+      state.throttle.forget(providerId, sessionId)
+      state.lastSeenStatus.delete(key)
+    }) as AddonServiceMethod,
+  },
+  onLoad: async (ctx: AddonServiceContext, config?: unknown): Promise<void> => {
+    state.context = ctx
+    state.icons = registerProviderIcons()
+    hydratePersisted()
+    // ponytail: SIRENO_CAPTURE_FAKE_AGENTS=1 — capture-only stub. Bypasses
+    // provider polling and injects a deterministic agent list so web captures
+    // show realistic "Agents" tiles without a live opencode / claude-code.
+    if (process.env["SIRENO_CAPTURE_FAKE_AGENTS"] === "1") {
+      const now = Date.now()
+      const fake: Agent[] = [
+        {
+          sessionId: "sireno-capture-opencode-1",
+          providerId: "opencode" as ProviderId,
+          title: "Refactor capture pipeline",
+          status: "running" as const,
+          directory: "/works/sirenodeck",
+          updatedAt: now,
+          createdAt: now - 1000 * 60 * 12,
+        },
+        {
+          sessionId: "sireno-capture-opencode-2",
+          providerId: "opencode" as ProviderId,
+          title: "Fix flaky session tests",
+          status: "idle" as const,
+          directory: "/works/sirenodeck/packages/cli",
+          updatedAt: now - 1000 * 60 * 4,
+          createdAt: now - 1000 * 60 * 40,
+        },
+        {
+          sessionId: "sireno-capture-claude-1",
+          providerId: "claude-code" as ProviderId,
+          title: "Migrate themes",
+          status: "waiting_for_human" as const,
+          directory: "/works/sirenodeck/packages/web",
+          updatedAt: now - 1000 * 60 * 2,
+          createdAt: now - 1000 * 60 * 90,
+        },
+      ]
+      state.lastSnapshot = mergeSnapshot(state.lastSnapshot, {
+        opencode: fake.filter((a) => a.providerId === "opencode"),
+        "claude-code": fake.filter((a) => a.providerId === "claude-code"),
+      })
+      publishSnapshot()
+      return
+    }
+    state.lastSnapshot = mergeSnapshot(state.lastSnapshot, {
+      opencode: [],
+      "claude-code": [],
+    })
+    const cfg: ProviderRegistryConfig = (config as
+      | ProviderRegistryConfig
+      | undefined) ?? {
+      opencodeUrl: "http://127.0.0.1:4096",
+      spawnOpencodeIfMissing: true,
+    }
+    const loaded = await loadProviders(cfg, ctx.signal)
+    state.providers = loaded.providers as Map<ProviderId, never>
+    state.spawnedChild = loaded.spawnedChild
+    await setStateFromProviders()
+    publishSnapshot()
+  },
+  onUnload: (): void => {
+    for (const u of state.unsubscribers) {
+      try {
+        u()
+      } catch {
+        // ignore
+      }
+    }
+    state.unsubscribers = []
+    if (state.spawnedChild) {
+      void state.spawnedChild.kill().catch(() => {})
+      state.spawnedChild = null
+    }
+    state.providers.clear()
+    state.lastSnapshot = EMPTY_SNAPSHOT
+    state.lastSeenStatus.clear()
+    state.throttle.reset()
+    state.icons = {}
+    state.context = null
+    if (rebuildTimer !== null) clearTimeout(rebuildTimer)
+    rebuildTimer = null
+    lastLiveCount = -1
+  },
+}

package/src/builtin-addons/coding-agents/global-entry.ts

@@ -0,0 +1,7 @@
+// Node-side entrypoint for the addon's global service. The bridge imports
+// this file (via the scanner's globalServiceEntry), so node-only imports
+// (fs, daemon paths) stay OUT of the browser graph — index.ts is imported
+// by the frontend's virtual addons/registry module, and any node builtin
+// reachable from there crashes the whole app ("externalized for browser
+// compatibility").
+export { globalService } from "./global/backend.js"

package/src/builtin-addons/coding-agents/hook/script.ts

@@ -0,0 +1,123 @@
+import { CLAUDE_HOOK_REGISTRATIONS } from "../shared/claude-hook-events.js"
+
+export const CLAUDE_HOOK_MARKER =
+  "SIRENODECK_INTEGRATION_ID=coding-agents-claude"
+export const CLAUDE_HOOK_VERSION = 1
+export const CLAUDE_HOOK_FILENAME = "sirenodeck-claude-hook.mjs"
+
+/**
+ * The hook script Claude Code runs. Node rather than sh: it needs real JSON
+ * parsing and an atomic write, and `node -e ''` is cheaper here than the
+ * python3 an existing third-party hook on this machine already pays.
+ *
+ * Invariants, in rough order of how badly they break the user if violated:
+ *  - it always exits 0. A non-zero hook exit surfaces as an error inside the
+ *    user's Claude Code session.
+ *  - it never writes to stdout. Several events treat stdout as a decision
+ *    payload or as context to feed the model.
+ *  - it does nothing at all for subagents, so harness activity is aggregated
+ *    into the parent session rather than surfacing as its own agent.
+ */
+export const claudeHookSource = `#!/usr/bin/env node
+// ${CLAUDE_HOOK_MARKER}-v${CLAUDE_HOOK_VERSION}
+// Managed by Sireno Deck. Reinstalling or updating the integration overwrites
+// this file — add custom hooks beside it rather than editing it.
+import { mkdirSync, renameSync, unlinkSync, writeFileSync } from "node:fs"
+import { execFileSync } from "node:child_process"
+import { homedir } from "node:os"
+import { join } from "node:path"
+
+const STATUS_BY_EVENT = ${JSON.stringify(
+  Object.fromEntries(CLAUDE_HOOK_REGISTRATIONS.map((r) => [r.event, r.status])),
+  null,
+  2,
+)}
+
+const dir = join(
+  process.env.XDG_STATE_HOME || join(homedir(), ".local", "state"),
+  "sirenodeck",
+  "coding-agents",
+)
+
+const readStdin = async () => {
+  const chunks = []
+  for await (const chunk of process.stdin) chunks.push(chunk)
+  return Buffer.concat(chunks).toString("utf8")
+}
+
+// Claude Code runs hooks through a shell, so process.ppid is the shell, not
+// claude. Walk up a few hops looking for it. Failure is not fatal: the reader
+// falls back to a time-based ceiling when pid is null.
+const findClaudePid = () => {
+  let pid = process.ppid
+  for (let hop = 0; hop < 5 && pid > 1; hop += 1) {
+    try {
+      const out = execFileSync("ps", ["-o", "ppid=,comm=", "-p", String(pid)], {
+        encoding: "utf8",
+        timeout: 1000,
+      }).trim()
+      const match = out.match(/^(\\d+)\\s+(.*)$/)
+      if (match === null) return null
+      if (/(^|\\/)claude$/.test(match[2].trim())) return pid
+      pid = Number(match[1])
+    } catch {
+      return null
+    }
+  }
+  return null
+}
+
+const main = async () => {
+  const event = process.argv[2] || ""
+  const status = STATUS_BY_EVENT[event]
+  if (status === undefined) return
+
+  let payload = {}
+  try {
+    const raw = await readStdin()
+    if (raw.trim()) payload = JSON.parse(raw)
+  } catch {
+    return
+  }
+
+  // Subagents are aggregated into their parent session, never reported alone.
+  if (payload.agent_id) return
+
+  const sessionId = payload.session_id
+  if (typeof sessionId !== "string" || sessionId.length === 0) return
+  const target = join(dir, "claude-" + sessionId + ".json")
+
+  if (status === null) {
+    try {
+      unlinkSync(target)
+    } catch {
+      // Already gone.
+    }
+    return
+  }
+
+  const lease = {
+    v: 1,
+    harness: "claude-code",
+    sessionId,
+    pid: findClaudePid(),
+    cwd: typeof payload.cwd === "string" ? payload.cwd : process.cwd(),
+    state: status,
+    event,
+    updatedAt: Date.now(),
+  }
+  if (typeof payload.transcript_path === "string") {
+    lease.transcriptPath = payload.transcript_path
+  }
+  if (typeof payload.permission_mode === "string") {
+    lease.permissionMode = payload.permission_mode
+  }
+
+  mkdirSync(dir, { recursive: true, mode: 0o700 })
+  const tmp = target + ".tmp"
+  writeFileSync(tmp, JSON.stringify(lease), { mode: 0o600 })
+  renameSync(tmp, target)
+}
+
+main().catch(() => {}).finally(() => process.exit(0))
+`

package/src/builtin-addons/coding-agents/index.ts

@@ -0,0 +1,15 @@
+import type { AddonRegistry } from "@/addon/registry"
+
+import { manifest } from "./manifest.js"
+
+// ponytail: the global service lives in global-entry.ts, NOT here — this
+// module is imported by the frontend's virtual addons/registry, and node
+// builtins reachable from index.ts crash the browser bundle. The bridge
+// finds the node-side entry via the scanner's globalServiceEntry.
+
+export const registerCodingAgentsAddon = (registry: AddonRegistry): void => {
+  registry.load(manifest)
+}
+
+export { manifest } from "./manifest.js"
+export default manifest

package/src/builtin-addons/coding-agents/manifest.ts

@@ -0,0 +1,115 @@
+// ponytail: see packages/addons/app-shortcuts/src/index.ts for context.
+// This module is imported by the frontend's virtual addons/registry, so the
+// import graph reachable from here must stay browser-safe: no static imports
+// of node builtins or node-only modules. Node-side pieces (globalService,
+// provider registry) live behind global-entry.ts / dynamic imports.
+import agentBackend from "./buttons/agent/backend.js"
+import agentFrontend from "./buttons/agent/frontend.js"
+import summaryBackend from "./buttons/summary/backend.js"
+import summaryFrontend from "./buttons/summary/frontend.js"
+import { createAgentsDecks } from "./decks/agents.js"
+import type { AddonManifestV1 } from "./types/types.js"
+
+const probeOpencodeReachable = async (): Promise<{
+  available: boolean
+  reason?: string
+}> => {
+  for (const url of ["http://127.0.0.1:4096", "http://127.0.0.1:4095"]) {
+    try {
+      const res = await fetch(`${url}/global/health`, {
+        signal: AbortSignal.timeout(2000),
+      })
+      if (!res.ok) continue
+      const body = (await res.json()) as { healthy?: boolean }
+      if (body.healthy === true) return { available: true }
+    } catch {
+      // Try the other supported local server port.
+    }
+  }
+  return { available: false, reason: "unreachable" }
+}
+
+const probeClaudeProjectsDir = async (): Promise<{
+  available: boolean
+  reason?: string
+}> => {
+  const { readdir } = await import("node:fs/promises")
+  const path = `${process.env["HOME"] ?? "~"}/.claude/projects`
+  try {
+    await readdir(path)
+    return { available: true }
+  } catch (err) {
+    return {
+      available: false,
+      reason: err instanceof Error ? err.message : `${path} unreadable`,
+    }
+  }
+}
+
+export const manifest = {
+  apiVersion: 1,
+  name: "coding-agents",
+  buttonTypes: {
+    "coding-agents:summary": {
+      frontend:
+        summaryFrontend as unknown as AddonManifestV1["buttonTypes"][string]["frontend"],
+      service:
+        summaryBackend as unknown as AddonManifestV1["buttonTypes"][string]["service"],
+      name: "summary",
+    },
+    "coding-agents:agent": {
+      frontend:
+        agentFrontend as unknown as AddonManifestV1["buttonTypes"][string]["frontend"],
+      service:
+        agentBackend as unknown as AddonManifestV1["buttonTypes"][string]["service"],
+      name: "agent",
+    },
+  },
+  decks: [
+    {
+      createDecks:
+        createAgentsDecks as unknown as AddonManifestV1["decks"] extends ReadonlyArray<
+          infer D
+        >
+          ? D extends { createDecks?: infer F }
+            ? F
+            : never
+          : never,
+    },
+  ] as unknown as AddonManifestV1["decks"],
+  checks: [
+    { name: "opencode-reachable", check: probeOpencodeReachable },
+    {
+      name: "opencode-installed",
+      // ponytail: dynamic import keeps providers/registry (node-only) out of
+      // the browser graph — the check body only ever runs on the daemon side.
+      check: async () => {
+        const { opencodeInstalled } = await import("./providers/registry.js")
+        const installed = await opencodeInstalled()
+        return installed
+          ? { available: true }
+          : { available: false, reason: "opencode CLI not found on $PATH" }
+      },
+    },
+    { name: "claude-code-projects-readable", check: probeClaudeProjectsDir },
+    {
+      // ponytail: distinguishes "reading transcripts and guessing" from
+      // "being told". Without the hooks the provider still works, but status
+      // is derived from file tails and lags a turn behind.
+      name: "claude-code-hooks",
+      check: async () => {
+        const { isClaudeHookInstalled, isClaudeHookEnabled } =
+          await import("@/cli/coding-agents-onboarding")
+        return isClaudeHookInstalled() && isClaudeHookEnabled()
+          ? { available: true }
+          : {
+              available: false,
+              reason:
+                "Claude Code session hooks not installed — status falls back to reading transcripts. Run `sirenodeck system-requirements` to add them.",
+            }
+      },
+    },
+  ],
+} satisfies AddonManifestV1
+
+export default manifest