@sirenodeck/sirenodeck 0.1.1-alpha.0

package/src/builtin-addons/coding-agents/providers/registry.ts

@@ -0,0 +1,120 @@
+// ponytail: see packages/addons/app-shortcuts/src/index.ts for context.
+import type { AgentProvider } from "../shared/state.js"
+import { ClaudeCodeProvider } from "./claude-code.js"
+import { OpenCodeProvider } from "./opencode.js"
+
+export interface ProviderRegistryConfig {
+  readonly opencodeUrl: string
+  readonly claudeCodeProjectsDir?: string
+  readonly spawnOpencodeIfMissing: boolean
+}
+
+export interface LoadProvidersResult {
+  readonly providers: ReadonlyMap<string, AgentProvider>
+  readonly spawnedChild: { kill: () => Promise<void> } | null
+}
+
+export interface LoadProvidersDeps {
+  readonly ensureOpencodeServer?: typeof import("./spawn").ensureOpencodeServer
+}
+
+const DEFAULT_OPENCODE_URL = "http://127.0.0.1:4096"
+const LEGACY_OPENCODE_URL = "http://127.0.0.1:4095"
+
+export const loadProviders = async (
+  config: ProviderRegistryConfig,
+  signal: AbortSignal,
+  deps: LoadProvidersDeps = {},
+): Promise<LoadProvidersResult> => {
+  const providers = new Map<string, AgentProvider>()
+  let spawnedChild: { kill: () => Promise<void> } | null = null
+  const configuredUrl = config.opencodeUrl ?? DEFAULT_OPENCODE_URL
+  const reachableUrl = await resolveOpencodeUrl(configuredUrl, signal)
+  const opencodeUrl = reachableUrl ?? configuredUrl
+
+  try {
+    providers.set("opencode", new OpenCodeProvider({ baseUrl: opencodeUrl }))
+  } catch {
+    // ponytail: client construction is synchronous and should not throw;
+    // if SDK import is broken at runtime, we just skip opencode.
+  }
+
+  if (!providers.has("opencode") || reachableUrl === null) {
+    if (!(await opencodeInstalled())) {
+      // CLI not on $PATH — skip spawn entirely; requirement check
+      // surfaces "opencode not installed" distinctly.
+      providers.delete("opencode")
+    } else if (config.spawnOpencodeIfMissing && !signal.aborted) {
+      try {
+        const ensure =
+          deps.ensureOpencodeServer ??
+          (await import("./spawn")).ensureOpencodeServer
+        const spawned = await ensure(opencodeUrl, signal)
+        if (spawned) {
+          spawnedChild = spawned.child
+          providers.set(
+            "opencode",
+            new OpenCodeProvider({ baseUrl: spawned.baseUrl }),
+          )
+        }
+      } catch {
+        // spawn failed; opencode will remain absent from the registry
+      }
+    } else {
+      providers.delete("opencode")
+    }
+  }
+
+  try {
+    providers.set(
+      "claude-code",
+      new ClaudeCodeProvider({
+        ...(config.claudeCodeProjectsDir !== undefined
+          ? { projectsDir: config.claudeCodeProjectsDir }
+          : {}),
+      }),
+    )
+  } catch {
+    // claude-code has no native deps; skip if chokidar somehow fails
+  }
+
+  return { providers, spawnedChild }
+}
+
+export const resolveOpencodeUrl = async (
+  preferredUrl: string,
+  signal: AbortSignal,
+): Promise<string | null> => {
+  const candidates =
+    preferredUrl === DEFAULT_OPENCODE_URL
+      ? [preferredUrl, LEGACY_OPENCODE_URL]
+      : [preferredUrl]
+  for (const url of candidates) {
+    if (await probeOpencodeHealth(url, signal)) return url
+  }
+  return null
+}
+
+const probeOpencodeHealth = async (
+  baseUrl: string,
+  signal: AbortSignal,
+): Promise<boolean> => {
+  try {
+    const res = await fetch(`${baseUrl}/global/health`, { signal })
+    if (!res.ok) return false
+    const body = (await res.json()) as { healthy?: boolean }
+    return body.healthy === true
+  } catch {
+    return false
+  }
+}
+
+// ponytail: the opencode CLI must be on $PATH for `opencode serve` to be
+// spawnable. Surfaced via manifest checks so the banner distinguishes
+// "CLI not installed" from "installed but no server running".
+export const opencodeInstalled = async (): Promise<boolean> => {
+  const { execFile } = await import("node:child_process")
+  return new Promise<boolean>((resolve) => {
+    execFile("which", ["opencode"], (err) => resolve(err === null))
+  })
+}

package/src/builtin-addons/coding-agents/providers/spawn.ts

@@ -0,0 +1,112 @@
+import { execa, type ExecaError } from "execa"
+
+export class NotReachableError extends Error {
+  override readonly name = "NotReachableError"
+  constructor(message: string) {
+    super(message)
+  }
+}
+
+export interface SpawnedServer {
+  readonly baseUrl: string
+  readonly child: { kill: () => Promise<void> }
+}
+
+interface ExecaChild {
+  kill: () => Promise<unknown>
+}
+
+interface SpawnDeps {
+  readonly fetchImpl?: typeof fetch
+  readonly execaImpl?: (cmd: string, args: ReadonlyArray<string>) => ExecaChild
+  readonly sleep?: (ms: number) => Promise<void>
+}
+
+const defaultSleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms))
+
+export const ensureOpencodeServer = async (
+  baseUrl: string,
+  signal: AbortSignal,
+  deps: SpawnDeps = {},
+): Promise<SpawnedServer | null> => {
+  const fetchImpl = deps.fetchImpl ?? fetch
+  const sleep = deps.sleep ?? defaultSleep
+
+  if (await isReachable(baseUrl, fetchImpl, signal)) return null
+
+  if (signal.aborted) throw new AbortError()
+
+  const port = parsePort(baseUrl)
+  const child: ExecaChild = deps.execaImpl
+    ? deps.execaImpl("opencode", ["serve", "--port", String(port)])
+    : (execa("opencode", [
+        "serve",
+        "--port",
+        String(port),
+      ]) as unknown as ExecaChild)
+
+  // ponytail: execa's returned promise rejects when the child exits
+  // non-zero (e.g. a broken opencode-ai postinstall exits 1 instantly).
+  // We never await `child` directly — reachability is polled via
+  // /global/health — so the floating rejection would surface as
+  // unhandledRejection and kill the daemon. Attach a sink; failures are
+  // reported by the probe loop below and the addon's checks entry.
+  void Promise.resolve(child).catch(() => undefined)
+
+  const deadline = Date.now() + 5000
+  while (Date.now() < deadline) {
+    if (signal.aborted) {
+      await child.kill().catch(() => undefined)
+      throw new AbortError()
+    }
+    if (await isReachable(baseUrl, fetchImpl, signal)) {
+      return {
+        baseUrl,
+        child: {
+          kill: async () => {
+            await child.kill().catch(() => undefined)
+          },
+        },
+      }
+    }
+    await sleep(200)
+  }
+  await child.kill().catch(() => undefined)
+  throw new NotReachableError(
+    `opencode serve did not become reachable at ${baseUrl} within 5 s`,
+  )
+}
+
+const isReachable = async (
+  baseUrl: string,
+  fetchImpl: typeof fetch,
+  signal: AbortSignal,
+): Promise<boolean> => {
+  try {
+    const res = await fetchImpl(`${baseUrl}/global/health`, { signal })
+    if (!res.ok) return false
+    const body = (await res.json()) as { healthy?: boolean }
+    return body.healthy === true
+  } catch (err) {
+    if ((err as ExecaError | undefined)?.shortMessage) return false
+    return false
+  }
+}
+
+const parsePort = (baseUrl: string): number => {
+  try {
+    const parsed = new URL(baseUrl)
+    const port = Number.parseInt(parsed.port, 10)
+    return Number.isFinite(port) && port > 0 ? port : 4096
+  } catch {
+    return 4096
+  }
+}
+
+export class AbortError extends Error {
+  override readonly name = "AbortError"
+  constructor() {
+    super("aborted")
+  }
+}

package/src/builtin-addons/coding-agents/shared/claude-hook-events.ts

@@ -0,0 +1,55 @@
+import type { AgentStatus } from "./state.js"
+
+/**
+ * Claude Code hook events this integration registers, and the status each
+ * implies. Every event below was verified present in the installed binary.
+ *
+ * Two deliberate omissions:
+ *
+ * - `PostToolUse` is not registered. `PreToolUse` already proves the session
+ *   is running and `Stop` returns it to idle, so registering both would
+ *   roughly double the hook invocations for no extra signal.
+ * - `Notification/idle_prompt` is not registered. It fires about a minute
+ *   after `Stop` on a session that is already idle; mapping it to
+ *   `waiting_for_human` would turn every idle session into an attention state
+ *   and make the summary tile meaningless.
+ *
+ * `SubagentStart`/`SubagentStop` are likewise absent: subagents are aggregated
+ * into their parent session, never surfaced separately.
+ */
+export interface ClaudeHookRegistration {
+  readonly event: string
+  /** Claude Code matcher, when the event supports one. */
+  readonly matcher?: string
+  /** `null` means "remove the lease" rather than set a status. */
+  readonly status: AgentStatus | null
+}
+
+export const CLAUDE_HOOK_REGISTRATIONS: ReadonlyArray<ClaudeHookRegistration> =
+  [
+    {
+      event: "SessionStart",
+      matcher: "startup|resume|clear|fork",
+      status: "idle",
+    },
+    { event: "UserPromptSubmit", status: "running" },
+    { event: "PreToolUse", matcher: "*", status: "running" },
+    { event: "PermissionRequest", status: "waiting_for_human" },
+    {
+      event: "Notification",
+      matcher: "permission_prompt",
+      status: "waiting_for_human",
+    },
+    { event: "PreCompact", status: "compacting" },
+    { event: "PostCompact", status: "running" },
+    { event: "Stop", status: "idle" },
+    { event: "StopFailure", status: "error" },
+    { event: "SessionEnd", status: null },
+  ]
+
+export const statusForHookEvent = (
+  event: string,
+): AgentStatus | null | undefined => {
+  const hit = CLAUDE_HOOK_REGISTRATIONS.find((r) => r.event === event)
+  return hit === undefined ? undefined : hit.status
+}

package/src/builtin-addons/coding-agents/shared/claude-status.ts

@@ -0,0 +1,236 @@
+import type { AgentStatus } from "./state.js"
+
+export interface ClaudeJsonlEntry {
+  readonly type: string
+  readonly subtype?: string
+  readonly message?: {
+    readonly role?: string
+    readonly content?: unknown
+  }
+  readonly toolUse?: unknown
+  readonly toolResult?: unknown
+  readonly permissionRequest?: unknown
+  readonly error?: { readonly message?: string }
+  readonly rateLimit?: unknown
+  readonly costUSD?: number
+  readonly cwd?: string
+  readonly timestamp?: string | number
+}
+
+// ponytail: real claude jsonl has none of the v1 phantom shapes. The
+// signals that exist (verified against ~/.claude/projects) are:
+//   • message.content as an ARRAY of blocks — tool_use blocks carry id+name
+//   • user tool_result blocks resolve a pending tool_use
+//   • system entries with subtype "turn_duration" mark the turn finished
+//   • progress entries stream while a tool/step runs
+// Stalled (needs-human) heuristics below still work on the edge where a
+// permission prompt ends the turn as a pending tool_use.
+const IDLE_AFTER_MS = 30 * 60 * 1000
+// ponytail: a pending non-AskUserQuestion tool longer than this is stuck on
+// a permission prompt or a slow tool → surface as "waiting".
+const STALLED_MS = 90 * 1000
+
+interface ToolUseBlock {
+  readonly type?: string
+  readonly id?: string
+  readonly name?: string
+}
+
+const textFromContent = (content: unknown, max = 60): string | undefined => {
+  if (typeof content === "string") {
+    return content.length > max ? `${content.slice(0, max - 1)}…` : content
+  }
+  if (Array.isArray(content)) {
+    const parts: string[] = []
+    for (const part of content) {
+      if (typeof part === "string") {
+        parts.push(part)
+      } else if (
+        part !== null &&
+        typeof part === "object" &&
+        "type" in part &&
+        (part as { type: unknown }).type === "text"
+      ) {
+        const text = (part as { text?: unknown }).text
+        if (typeof text === "string") parts.push(text)
+      }
+    }
+    const joined = parts.join(" ")
+    return joined.length > max ? `${joined.slice(0, max - 1)}…` : joined
+  }
+  return undefined
+}
+
+const lastTimestamp = (
+  entries: readonly ClaudeJsonlEntry[],
+): number | undefined => {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const ts = entries[i]?.timestamp
+    if (typeof ts === "number") return ts
+    if (typeof ts === "string") {
+      const parsed = Date.parse(ts)
+      if (!Number.isNaN(parsed)) return parsed
+    }
+  }
+  return undefined
+}
+
+const firstTimestamp = (
+  entries: readonly ClaudeJsonlEntry[],
+): number | undefined => {
+  for (const e of entries) {
+    const ts = e?.timestamp
+    if (typeof ts === "number") return ts
+    if (typeof ts === "string") {
+      const parsed = Date.parse(ts)
+      if (!Number.isNaN(parsed)) return parsed
+    }
+  }
+  return undefined
+}
+
+const lastAssistantText = (
+  entries: readonly ClaudeJsonlEntry[],
+): string | undefined => {
+  for (let i = entries.length - 1; i >= 0; i -= 1) {
+    const e = entries[i]
+    if (e?.type !== "assistant") continue
+    const text = textFromContent(e.message?.content)
+    if (text !== undefined) return text
+  }
+  return undefined
+}
+
+interface PendingTool {
+  readonly id: string
+  readonly name: string
+}
+
+// ponytail: track tool_use blocks until their matching tool_result. A tool
+// still pending at the end of the stream is what the agent is doing right now.
+const pendingToolUses = (
+  entries: readonly ClaudeJsonlEntry[],
+): readonly PendingTool[] => {
+  const pending = new Map<string, string>()
+  for (const e of entries) {
+    if (e.type === "assistant") {
+      const content = e.message?.content
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (
+            typeof block !== "object" ||
+            block === null ||
+            (block as ToolUseBlock).type !== "tool_use"
+          ) {
+            continue
+          }
+          const b = block as ToolUseBlock
+          if (typeof b.id === "string" && typeof b.name === "string") {
+            pending.set(b.id, b.name)
+          }
+        }
+      }
+    } else if (e.type === "user") {
+      const content = e.message?.content
+      if (Array.isArray(content)) {
+        for (const block of content) {
+          if (
+            typeof block !== "object" ||
+            block === null ||
+            (block as { type?: string }).type !== "tool_result"
+          ) {
+            continue
+          }
+          const id = (block as { tool_use_id?: unknown }).tool_use_id
+          if (typeof id === "string") pending.delete(id)
+        }
+      }
+    }
+  }
+  return [...pending.entries()].map(([id, name]) => ({ id, name }))
+}
+
+export interface ClaudeDeriveResult {
+  readonly status: AgentStatus
+  readonly preview?: string
+  readonly updatedAt: number
+  readonly cost?: number
+  readonly cwd?: string
+  readonly createdAt?: number
+}
+
+export const deriveClaudeStatus = (
+  entries: readonly ClaudeJsonlEntry[],
+  now: number = Date.now(),
+  // ponytail: some transcripts carry no timestamps at all (three exist on the
+  // reporting machine, one last touched a week ago). Falling back to `now` made
+  // them permanently "live" — always inside the recency window, always on the
+  // deck. The caller passes the file's mtime instead, which is the honest
+  // answer to "when did this session last do anything".
+  fallbackTimestamp?: number,
+): ClaudeDeriveResult | null => {
+  if (entries.length === 0) return null
+
+  const last = entries[entries.length - 1]!
+  const ts = lastTimestamp(entries) ?? fallbackTimestamp ?? now
+  let status: AgentStatus = "idle"
+  let preview: string | undefined
+
+  const pending = pendingToolUses(entries)
+  const pendingAsk = pending.find((t) => t.name === "AskUserQuestion")
+  if (pendingAsk !== undefined) {
+    status = "waiting_for_human"
+    preview = "asking for your input"
+  } else if (last.type === "error") {
+    status = "error"
+    preview =
+      (typeof last.error?.message === "string" && last.error.message) ||
+      "session error"
+  } else if (typeof last.rateLimit !== "undefined") {
+    status = "waiting"
+  } else if (last.type === "system" && last.subtype === "turn_duration") {
+    // ponytail: turn finished — agent await
+    status = "idle"
+    preview = lastAssistantText(entries) ?? preview
+  } else if (last.type === "progress") {
+    status = "running"
+  } else if (pending.length > 0) {
+    // A non-AskUserQuestion tool is still open: running now, "waiting" once
+    // it stalls (permission prompt / hung tool).
+    const stalled = now - ts > STALLED_MS
+    status = stalled ? "waiting" : "running"
+    const toolName = pending[pending.length - 1]?.name
+    preview = toolName !== undefined ? `running ${toolName}` : undefined
+  } else if (last.type === "user") {
+    // Agent hasn't replied yet — mid-turn.
+    status = "running"
+  } else if (last.type === "assistant") {
+    preview = textFromContent(last.message?.content)
+    status = "idle"
+  }
+
+  if (now - ts > IDLE_AFTER_MS) {
+    status = "idle"
+  }
+
+  // ponytail: costUSD is per-assistant-message; sum gives a rough session
+  // total. Not every version files cost on every message — absent values
+  // just don't accrue.
+  let cost = 0
+  for (const e of entries) {
+    if (typeof e.costUSD === "number" && Number.isFinite(e.costUSD)) {
+      cost += e.costUSD
+    }
+  }
+  const cwd = entries.find((e) => typeof e.cwd === "string")?.cwd
+  const createdAt = firstTimestamp(entries)
+
+  return {
+    status,
+    preview,
+    updatedAt: ts,
+    ...(cost > 0 ? { cost } : {}),
+    ...(cwd !== undefined && cwd.length > 0 ? { cwd } : {}),
+    ...(createdAt !== undefined ? { createdAt } : {}),
+  }
+}

package/src/builtin-addons/coding-agents/shared/live-count.ts

@@ -0,0 +1,39 @@
+// ponytail: bridge between the global backend (which sees live agent counts)
+// and createAgentsDecks (which materializes the deck once per rebuild). The
+// backend records the count and page shape here; the deck factory reads them
+// to decide how many pages to materialize.
+// ponytail: the backend and the deck factory are loaded through two module
+// graphs (register-builtins package import vs addon-loader file-path import),
+// so plain module state duplicates. Keep the single store on globalThis so
+// both graphs share one set of counters.
+export const AGENTS_DECK_BASE = "coding-agents:agents"
+
+interface LiveCountStore {
+  liveCount: number
+  pageCount: number
+}
+
+const GLOBAL_KEY = "__sirenoCodingAgentsLiveCount"
+
+const store = (): LiveCountStore => {
+  const g = globalThis as unknown as Record<string, LiveCountStore | undefined>
+  g[GLOBAL_KEY] ??= { liveCount: 0, pageCount: 1 }
+  return g[GLOBAL_KEY] as LiveCountStore
+}
+
+export const setLiveCount = (n: number): void => {
+  store().liveCount = n
+}
+
+export const getLiveCount = (): number => store().liveCount
+
+export const setPageCount = (n: number): void => {
+  store().pageCount = n
+}
+
+export const getPageCount = (): number => store().pageCount
+
+// ponytail: the deck id the summary button should navigate to. Pagination
+// names pages `base-pN`; a single page keeps the base id.
+export const deckTarget = (): string =>
+  store().pageCount > 1 ? `${AGENTS_DECK_BASE}-p1` : AGENTS_DECK_BASE

package/src/builtin-addons/coding-agents/shared/notifier.ts

@@ -0,0 +1,58 @@
+import type { AgentStatus } from "./state.js"
+
+interface NotifierHooks {
+  readonly notify: (args: {
+    title: string
+    body: string
+    sound?: boolean
+  }) => Promise<void> | void
+  readonly now: () => number
+}
+
+export class NotificationThrottle {
+  readonly #hooks: NotifierHooks
+  readonly #last: Map<string, AgentStatus> = new Map<string, AgentStatus>()
+
+  constructor(hooks: Partial<NotifierHooks> = {}) {
+    this.#hooks = {
+      now: hooks.now ?? (() => Date.now()),
+      notify:
+        hooks.notify ??
+        (() => {
+          // ponytail: no-op fallback so tests / null-provider mode don't crash.
+        }),
+    }
+  }
+
+  // ponytail: keys on (providerId, sessionId, status) so the same agent
+  // transitioning into the same status twice doesn't re-fire — but a
+  // different status for the same agent always notifies.
+  evaluate(input: {
+    providerId: string
+    sessionId: string
+    status: AgentStatus
+    title: string
+    body: string
+    sound?: boolean
+    attentionOnly?: boolean
+  }): boolean {
+    const { providerId, sessionId, status, title, body, sound } = input
+    if (input.attentionOnly !== false) {
+      if (status !== "waiting_for_human" && status !== "error") return false
+    }
+    const key = `${providerId}:${sessionId}`
+    const last = this.#last.get(key)
+    if (last === status) return false
+    this.#last.set(key, status)
+    void this.#hooks.notify({ title, body, sound })
+    return true
+  }
+
+  forget(providerId: string, sessionId: string): void {
+    this.#last.delete(`${providerId}:${sessionId}`)
+  }
+
+  reset(): void {
+    this.#last.clear()
+  }
+}

package/src/builtin-addons/coding-agents/shared/opencode-status.ts

@@ -0,0 +1,82 @@
+import type { AgentStatus } from "./state.js"
+
+export interface OpencodeEventStatusBusy {
+  readonly type: "busy"
+}
+
+export interface OpencodeEventStatusIdle {
+  readonly type: "idle"
+}
+
+export interface OpencodeEventStatusRetry {
+  readonly type: "retry"
+  readonly attempt: number
+  readonly message: string
+  readonly next: number
+}
+
+export type OpencodeSessionStatus =
+  | OpencodeEventStatusIdle
+  | OpencodeEventStatusBusy
+  | OpencodeEventStatusRetry
+
+export type OpencodeEvent =
+  | {
+      readonly type: "session.status"
+      readonly properties: {
+        readonly sessionID: string
+        readonly status: OpencodeSessionStatus
+      }
+    }
+  | {
+      readonly type: "session.idle"
+      readonly properties: { readonly sessionID: string }
+    }
+  | {
+      readonly type: "session.compacted"
+      readonly properties: { readonly sessionID: string }
+    }
+  | {
+      readonly type: "session.error"
+      readonly properties: {
+        readonly sessionID: string
+        readonly message?: string
+      }
+    }
+  | {
+      readonly type: "permission.updated"
+      readonly properties: {
+        readonly sessionID: string
+        readonly id: string
+        readonly status: "pending" | "approved" | "denied"
+      }
+    }
+
+export const opencodeEventToStatus = (
+  evt: OpencodeEvent,
+): { readonly status: AgentStatus; readonly sessionId: string } | null => {
+  if (evt.type === "session.status") {
+    const s = evt.properties.status
+    if (s.type === "busy")
+      return { status: "running", sessionId: evt.properties.sessionID }
+    if (s.type === "idle")
+      return { status: "idle", sessionId: evt.properties.sessionID }
+    if (s.type === "retry")
+      return { status: "waiting", sessionId: evt.properties.sessionID }
+  }
+  if (evt.type === "session.idle") {
+    return { status: "idle", sessionId: evt.properties.sessionID }
+  }
+  if (evt.type === "session.compacted") {
+    return { status: "compacting", sessionId: evt.properties.sessionID }
+  }
+  if (evt.type === "session.error") {
+    return { status: "error", sessionId: evt.properties.sessionID }
+  }
+  if (evt.type === "permission.updated") {
+    const status: AgentStatus =
+      evt.properties.status === "pending" ? "waiting_for_human" : "idle"
+    return { status, sessionId: evt.properties.sessionID }
+  }
+  return null
+}