@sirenodeck/sirenodeck 0.1.1-alpha.0

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

@@ -0,0 +1,66 @@
+import {
+  agentKey,
+  type Agent,
+  type AgentStatus,
+  type AgentsSnapshot,
+  type ProviderId,
+} from "./state.js"
+
+export const mergeSnapshot = (
+  prev: AgentsSnapshot,
+  providers: Readonly<Record<ProviderId, readonly Agent[]>>,
+): AgentsSnapshot => {
+  const merged: Record<ProviderId, Agent[]> = {
+    opencode: [...prev.byProvider["opencode"]],
+    "claude-code": [...prev.byProvider["claude-code"]],
+  }
+  const seen = new Map<string, Agent>()
+  const attention: string[] = []
+
+  for (const id of Object.keys(providers) as ProviderId[]) {
+    const list: Agent[] = []
+    for (const a of providers[id]) {
+      const k = agentKey(a)
+      seen.set(k, a)
+      list.push(a)
+      if (a.status === "waiting_for_human" || a.status === "error") {
+        attention.push(k)
+      }
+    }
+    list.sort((x, y) => y.updatedAt - x.updatedAt)
+    merged[id] = list
+  }
+
+  return {
+    byProvider: merged,
+    attention,
+    generatedAt: Date.now(),
+  }
+}
+
+export const diffStatus = (
+  before: AgentStatus | undefined,
+  after: AgentStatus,
+): boolean => before !== after
+
+const byCreatedDesc = (a: Agent, b: Agent): number => {
+  const aCreated = a.createdAt ?? 0
+  const bCreated = b.createdAt ?? 0
+  if (aCreated !== bCreated) return bCreated - aCreated
+  return b.updatedAt - a.updatedAt
+}
+
+// ponytail: the agents deck is materialized once at startup with a fixed
+// number of slot tiles, so which agent fills each tile is resolved per
+// broadcast from the live snapshot. Ordered by creation date (newest first);
+// state is conveyed by the tile's color instead of ordering.
+export const listAgents = (snapshot: AgentsSnapshot): readonly Agent[] =>
+  [
+    ...snapshot.byProvider["opencode"],
+    ...snapshot.byProvider["claude-code"],
+  ].sort(byCreatedDesc)
+
+export const agentAtSlot = (
+  snapshot: AgentsSnapshot,
+  slot: number,
+): Agent | undefined => listAgents(snapshot)[slot]

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

@@ -0,0 +1,72 @@
+export type AgentStatus =
+  | "idle"
+  | "running"
+  | "waiting"
+  | "waiting_for_human"
+  | "error"
+  | "compacting"
+
+export type ProviderId = "opencode" | "claude-code"
+
+export interface Agent {
+  readonly sessionId: string
+  readonly instanceId?: string
+  readonly pid?: number
+  readonly providerId: ProviderId
+  readonly title: string
+  readonly status: AgentStatus
+  readonly directory?: string
+  readonly cost?: number
+  readonly contextTokens?: number
+  readonly contextPercent?: number
+  readonly createdAt?: number
+  readonly updatedAt: number
+  readonly lastMessagePreview?: string
+}
+
+export interface AgentsSnapshot {
+  readonly byProvider: Readonly<Record<ProviderId, readonly Agent[]>>
+  readonly attention: readonly string[]
+  readonly generatedAt: number
+  // ponytail: provider logo asset ids (asset://...) registered daemon-side so
+  // the frontend can render small `<Icon>` logos on tiles in dev AND real mode.
+  readonly icons?: Readonly<Partial<Record<ProviderId, string>>>
+}
+
+export const CHANNEL = "coding-agents:agents" as const
+
+export const KNOWN_PROVIDERS: readonly ProviderId[] = [
+  "opencode",
+  "claude-code",
+] as const
+
+export const notifiableStatus = (s: AgentStatus): boolean =>
+  s === "waiting_for_human" || s === "error"
+
+export const agentKey = (
+  a: Pick<Agent, "providerId" | "sessionId" | "instanceId">,
+): string => `${a.providerId}:${a.instanceId ?? a.sessionId}`
+
+export const EMPTY_SNAPSHOT: AgentsSnapshot = {
+  byProvider: { opencode: [], "claude-code": [] },
+  attention: [],
+  generatedAt: 0,
+}
+
+export interface CoreMethods {
+  notify(args: { title: string; body: string; sound?: boolean }): Promise<void>
+  runCommand(
+    command: string,
+    options?: { timeoutMs?: number },
+  ): Promise<unknown>
+  navigateToDeck(args: { id: string; addToHistory?: boolean }): void
+  goBack(): void
+}
+
+export interface AgentProvider {
+  readonly id: ProviderId
+  readonly displayName: string
+  readonly logoPath: string
+  fetchSnapshot(signal: AbortSignal): Promise<readonly Agent[]>
+  subscribe(signal: AbortSignal, onChange: () => void): () => void
+}

package/src/builtin-addons/coding-agents/sirenodeck.json

@@ -0,0 +1,6 @@
+{
+  "kind": "addon",
+  "apiVersion": 1,
+  "name": "coding-agents",
+  "entry": "manifest.ts"
+}

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

@@ -0,0 +1,33 @@
+// ponytail: as a builtin of the cli, this addon re-exports the runtime's
+// type surface directly. The previous third-party addon shipped a
+// minimal local mirror because third-party packages must not reach into
+// the cli's @/ path aliases — builtins don't have that constraint.
+export type {
+  AddonButtonService,
+  AddonButtonServiceContext,
+  AddonButtonTypeDef,
+  AddonButtonTypeDefAny,
+  AddonButtonTypeService,
+  AddonCheck,
+  AddonCheckResult,
+  AddonDeckDefinition,
+  AddonDeckEntry,
+  AddonDeckEntryCtx,
+  AddonDeckFactory,
+  AddonFrontend,
+  AddonFrontendButton,
+  AddonFrontendButtonProps,
+  AddonGeneratedDeck,
+  AddonGlobalPoller,
+  AddonGlobalService,
+  AddonGlobalSubscription,
+  AddonGestureEvent,
+  AddonLoadIssue,
+  AddonManifest,
+  AddonManifestKind,
+  AddonManifestV1,
+  AddonServiceContext,
+  AddonServiceMethod,
+  AddonKind,
+  GestureKind,
+} from "@/addon/api"

package/src/builtin-addons/core/README.md

@@ -0,0 +1,89 @@
+# core
+
+**Internal-only addon.** Provides the foundational button types every deck depends on. The runtime injects `core:change-deck` automatically (the reserved `n-1` slot); `core:action` and `core:toggle` are user-facing but the runtime also uses them internally for things like the settings back button.
+
+If you're writing user-facing config, you only need `core:action` and `core:change-deck`. The other two are runtime-managed.
+
+## Buttons
+
+| Type                | Description                                                                                                                                           |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `core:change-deck`  | Navigate to another deck. Internal: the reserved `n-1` slot.                                                                                          |
+| `core:action`       | Run a shell command (xdg-open, google-chrome, etc.)                                                                                                   |
+| `core:toggle`       | Toggle a stateful button. Two modes: legacy `{key,default}` boolean flip, or `statusCommand`/`states` polled status display with per-state tap action |
+| `core:page-nav`     | Internal: next/previous deck navigation                                                                                                               |
+| `core:media-sample` | Internal: a sample media-player button used in tests                                                                                                  |
+
+## Config
+
+### `core:action`
+
+Requires at least one of `icon` or `label`. Command goes in `actions.tap`
+(also accepts `type://<combo-or-text>` URIs for keystroke shortcuts).
+
+```yaml
+- position: 1
+  type: core:action
+  actions:
+    tap: "xdg-open https://example.com"
+  config:
+    label: Open
+    icon: icon://globe
+```
+
+### `core:change-deck`
+
+```yaml
+- position: 9
+  type: core:change-deck
+  config:
+    deck: emoji
+```
+
+`deck` must reference a deck id defined in the same `config.yml` under `decks:`.
+
+### `core:toggle`
+
+Two shapes are supported.
+
+**Status mode (recommended):** poll a command, match its trimmed stdout against
+`states`, render the matched state's label/icon, and run the matched state's
+`onTap` on user tap. Per-button `intervalMs` (default 2000) bounds how often
+`statusCommand` runs.
+
+```yaml
+- position: 1
+  type: core:toggle
+  config:
+    statusCommand: "playerctl status"
+    intervalMs: 2000
+    timeoutMs: 5000
+    states:
+      Playing:
+        label: "<xl>$(playerctl title)</xl>"
+        icon: "icon://play"
+        onTap: "playerctl pause"
+      Paused:
+        label: "Paused"
+        icon: "icon://pause"
+        onTap: "playerctl play"
+```
+
+Each state entry must declare at least one of `label` or `icon`. `onTap` is
+optional — if omitted, tapping still triggers a republish so the deck reflects
+the latest status without waiting for the next tick.
+
+**Legacy mode:** keep the runtime boolean flip.
+
+```yaml
+- position: 1
+  type: core:toggle
+  config:
+    key: my-flag
+    default: false
+```
+
+## See also
+
+- [Internal settings](../internal-settings/README.md) — overlay deck
+- [Session](../session/README.md) — `session:locked` deck

package/src/builtin-addons/core/buttons/action/backend.ts

@@ -0,0 +1,7 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+} satisfies AddonButtonTypeService

package/src/builtin-addons/core/buttons/action/config.ts

@@ -0,0 +1,13 @@
+import { z } from "zod"
+
+import { IconSourceSchema } from "@/config/schemas"
+
+export const configSchema = z
+  .object({
+    icon: IconSourceSchema.optional(),
+    label: z.string().optional(),
+  })
+  .refine((c) => Boolean(c.icon) || Boolean(c.label), {
+    message: "core:action requires at least one of 'icon' or 'label'",
+  })
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/core/buttons/action/frontend.tsx

@@ -0,0 +1,16 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { IconLabelSurface } from "@/ui/index"
+
+type Config = { icon?: string; label?: string }
+
+const CoreActionButtonFrontend: AddonFrontendButton<Config> = ({ config }) => {
+  const { icon, label } = config ?? {}
+  return (
+    <IconLabelSurface
+      {...(icon !== undefined ? { source: icon } : {})}
+      label={label ?? ""}
+    />
+  )
+}
+
+export default CoreActionButtonFrontend

package/src/builtin-addons/core/buttons/change-deck/backend.ts

@@ -0,0 +1,18 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: ({ config, publish, buttonId, position }) => {
+    publish("runtime:navigate-deck", {
+      deckId: config.deck,
+      addToHistory: config.addToHistory ?? true,
+      buttonId,
+      position,
+    })
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/core/buttons/change-deck/config.ts

@@ -0,0 +1,15 @@
+import { z } from "zod"
+
+import { IconSourceSchema } from "@/config/schemas"
+
+export const configSchema = z
+  .object({
+    deck: z.string().min(1),
+    addToHistory: z.boolean().default(true).meta({ internal: true }),
+    icon: IconSourceSchema.optional(),
+    label: z.string().optional(),
+  })
+  .refine((c) => Boolean(c.icon) || Boolean(c.label), {
+    message: "core:change-deck requires at least one of 'icon' or 'label'",
+  })
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/core/buttons/change-deck/frontend.tsx

@@ -0,0 +1,18 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { IconLabelSurface } from "@/ui/index"
+
+type Config = { icon?: string; label?: string }
+
+const CoreChangeDeckButtonFrontend: AddonFrontendButton<Config> = ({
+  config,
+}) => {
+  const { icon, label } = config ?? {}
+  return (
+    <IconLabelSurface
+      {...(icon !== undefined ? { source: icon } : {})}
+      label={label ?? ""}
+    />
+  )
+}
+
+export default CoreChangeDeckButtonFrontend

package/src/builtin-addons/core/buttons/media-sample/backend.ts

@@ -0,0 +1,8 @@
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+export default {
+  configSchema,
+  onTap: async () => {},
+} satisfies AddonButtonTypeService

package/src/builtin-addons/core/buttons/media-sample/config.ts

@@ -0,0 +1,7 @@
+import { z } from "zod"
+
+export const configSchema = z.object({
+  channel: z.string().min(1),
+  fallback: z.unknown().optional(),
+})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/core/buttons/media-sample/frontend.tsx

@@ -0,0 +1,2 @@
+import { NullButton } from "@/api/react"
+export default NullButton

package/src/builtin-addons/core/buttons/page-nav/backend.ts

@@ -0,0 +1,28 @@
+import { z } from "zod"
+import type { AddonButtonTypeService } from "@/addon/api"
+
+import { configSchema } from "./config"
+
+type Config = z.infer<typeof configSchema>
+
+export default {
+  configSchema,
+  onTap: ({ config, publish, buttonId, position }) => {
+    const { nextDeckId } = config as Config
+    publish("runtime:navigate-deck", {
+      deckId: nextDeckId,
+      addToHistory: false,
+      buttonId,
+      position,
+    })
+  },
+  onHold: ({ config, publish, buttonId, position }) => {
+    const { prevDeckId } = config as Config
+    publish("runtime:navigate-deck", {
+      deckId: prevDeckId,
+      addToHistory: false,
+      buttonId,
+      position,
+    })
+  },
+} satisfies AddonButtonTypeService<Config>

package/src/builtin-addons/core/buttons/page-nav/config.ts

@@ -0,0 +1,9 @@
+import { z } from "zod"
+
+export const configSchema = z.object({
+  currentPage: z.number().min(1),
+  totalPages: z.number().min(1),
+  prevDeckId: z.string().min(1),
+  nextDeckId: z.string().min(1),
+})
+export type ConfigSchema = z.infer<typeof configSchema>

package/src/builtin-addons/core/buttons/page-nav/frontend.tsx

@@ -0,0 +1,68 @@
+import type { AddonFrontendButton } from "@/addon/api"
+import { cn, Icon, TapIndicator, TapIndicatorType, Text } from "@/ui"
+
+type Config = {
+  currentPage: number
+  totalPages: number
+  prevDeckId: string
+  nextDeckId: string
+}
+
+type NavActionProps = {
+  dir: "next" | "prev"
+}
+
+const icons: Record<NavActionProps["dir"], string> = {
+  next: "chevron-right",
+  prev: "chevron-left",
+}
+
+const tapTypes: Record<NavActionProps["dir"], TapIndicatorType> = {
+  next: "tap",
+  prev: "hold",
+}
+
+const NavAction = ({ dir = "prev" }: NavActionProps) => {
+  const icon = icons[dir]
+  const tapType = tapTypes[dir]
+
+  return (
+    <div
+      className={cn(
+        "flex items-center gap-0",
+        dir === "prev" ? "flex-row" : "flex-row-reverse",
+      )}
+    >
+      <Icon source={`icon://${icon}`} size={30} />
+      <TapIndicator type={tapType} size="xs" />
+    </div>
+  )
+}
+
+const PageIndicator = ({
+  current,
+  total,
+}: {
+  current: number
+  total: number
+}) => <Text size="md" tone="muted" text={`*${current}* / ${total}`} />
+
+const PageNavButtonFrontend: AddonFrontendButton<Config> = ({ config }) => {
+  const { currentPage, totalPages } = config
+  const isFirstPage = currentPage === 1
+  const isLastPage = currentPage === totalPages
+
+  return (
+    <div className="size-full flex flex-col gap-0.5 justify-center items-center">
+      <div className={cn(isFirstPage ? "invisible" : "visible", "-ml-7")}>
+        <NavAction dir="prev" />
+      </div>
+      <PageIndicator current={currentPage} total={totalPages} />
+      <div className={cn(isLastPage ? "invisible" : "visible", "ml-7")}>
+        <NavAction dir="next" />
+      </div>
+    </div>
+  )
+}
+
+export default PageNavButtonFrontend

package/src/builtin-addons/core/buttons/toggle/backend.ts

@@ -0,0 +1,119 @@
+import type { Methods } from "@/deck/methods"
+import type { Store } from "@/core/store"
+import type {
+  AddonButtonServiceContext,
+  AddonButtonTypeService,
+} from "@/addon/api"
+
+import {
+  configSchema,
+  isStatusToggleConfig,
+  type ConfigSchema,
+  type LegacyToggleConfig,
+  type StatusToggleConfig,
+} from "./config"
+
+// ponytail: bridge namespaces addon-global methods as `${addonName}:${methodName}`.
+// core addon's method names are `register` / `unregister` / `republish` / `lookup`,
+// so the namespaced keys are `core:register` etc.
+const REG_METHOD = "core:register"
+const UNREG_METHOD = "core:unregister"
+const REPUBLISH_METHOD = "core:republish"
+const LOOKUP_METHOD = "core:lookup"
+
+interface ToggleStateLike {
+  readonly raw: string
+  readonly state: string | undefined
+  readonly error?: string
+  readonly at: number
+}
+
+export default {
+  configSchema,
+  onMount: (ctx: AddonButtonServiceContext<ConfigSchema>) => {
+    if (!isStatusToggleConfig(ctx.config)) return
+    const register = (
+      ctx.methods as unknown as Record<
+        string,
+        ((...a: unknown[]) => unknown) | undefined
+      >
+    )[REG_METHOD]
+    register?.(ctx.buttonId, ctx.config)
+  },
+  dispose: (ctx: AddonButtonServiceContext<ConfigSchema>) => {
+    if (!isStatusToggleConfig(ctx.config)) return
+    const unregister = (
+      ctx.methods as unknown as Record<
+        string,
+        ((...a: unknown[]) => unknown) | undefined
+      >
+    )[UNREG_METHOD]
+    unregister?.(ctx.buttonId)
+  },
+  onTap: async (ctx: AddonButtonServiceContext<ConfigSchema>) => {
+    const { config, methods, store, coreMethods, buttonId } =
+      ctx as unknown as {
+        config: ConfigSchema
+        methods: Methods
+        store: Store
+        coreMethods: Methods
+        buttonId: string
+      }
+    if (!isStatusToggleConfig(config)) {
+      await legacyTap({ config: config as LegacyToggleConfig, methods, store })
+      return
+    }
+    await statusTap({ config, methods, coreMethods, buttonId }, config)
+  },
+} satisfies AddonButtonTypeService<ConfigSchema>
+
+const legacyTap = async (ctx: {
+  config: LegacyToggleConfig
+  methods: Methods
+  store: Store
+}): Promise<void> => {
+  const scope = ctx.store.buttonScope<boolean>("core", ctx.config.key)
+  const current = scope.get("value") ?? ctx.config.default
+  scope.set("value", !current)
+  ctx.methods.invalidate()
+}
+
+const statusTap = async (
+  ctx: {
+    config: StatusToggleConfig
+    methods: Methods
+    coreMethods: Methods
+    buttonId: string
+  },
+  config: StatusToggleConfig,
+): Promise<void> => {
+  const lookup = (
+    ctx.methods as unknown as Record<
+      string,
+      ((...a: unknown[]) => unknown) | undefined
+    >
+  )[LOOKUP_METHOD] as
+    | ((id: unknown) => Promise<ToggleStateLike | null>)
+    | undefined
+  let stateKey: string | undefined
+  if (lookup !== undefined) {
+    const current = await lookup(ctx.buttonId)
+    stateKey = current?.state
+  }
+  const entry = stateKey !== undefined ? config.states[stateKey] : undefined
+  const command = entry?.onTap
+  const republish = (
+    ctx.methods as unknown as Record<
+      string,
+      ((...a: unknown[]) => unknown) | undefined
+    >
+  )[REPUBLISH_METHOD] as ((buttonId?: unknown) => void) | undefined
+  if (command === undefined || command.length === 0) {
+    republish?.(ctx.buttonId)
+    return
+  }
+  await ctx.coreMethods.runCommand(command, {
+    timeoutMs: config.timeoutMs,
+  } as Parameters<typeof ctx.coreMethods.runCommand>[1])
+  republish?.(ctx.buttonId)
+}

package/src/builtin-addons/core/buttons/toggle/config.ts

@@ -0,0 +1,57 @@
+import { z } from "zod"
+
+export const TOGGLE_DEFAULT_INTERVAL_MS = 2000
+export const TOGGLE_DEFAULT_TIMEOUT_MS = 5000
+
+export const StatusToggleStateSchema = z
+  .object({
+    label: z.string().min(1).optional(),
+    icon: z.string().min(1).optional(),
+    onTap: z.string().min(1).optional(),
+  })
+  .strict()
+  .refine((s) => s.label !== undefined || s.icon !== undefined, {
+    message: "each state requires at least one of `label` or `icon`",
+  })
+
+export type StatusToggleState = z.infer<typeof StatusToggleStateSchema>
+
+export const StatusToggleConfigSchema = z
+  .object({
+    statusCommand: z.string().min(1),
+    intervalMs: z.number().int().positive().optional(),
+    timeoutMs: z.number().int().positive().optional(),
+    states: z.record(z.string().min(1), StatusToggleStateSchema),
+  })
+  .strict()
+  .refine((c) => Object.keys(c.states).length > 0, {
+    message: "`states` must declare at least one entry",
+  })
+
+export type StatusToggleConfig = z.infer<typeof StatusToggleConfigSchema>
+
+export const LegacyToggleConfigSchema = z
+  .object({
+    key: z.string().min(1),
+    default: z.boolean().default(false),
+  })
+  .strict()
+
+export type LegacyToggleConfig = z.infer<typeof LegacyToggleConfigSchema>
+
+export const configSchema = z.union([
+  StatusToggleConfigSchema,
+  LegacyToggleConfigSchema,
+])
+
+export type ConfigSchema = z.infer<typeof configSchema>
+
+export const isStatusToggleConfig = (
+  value: unknown,
+): value is StatusToggleConfig =>
+  StatusToggleConfigSchema.safeParse(value).success
+
+export const isLegacyToggleConfig = (
+  value: unknown,
+): value is LegacyToggleConfig =>
+  LegacyToggleConfigSchema.safeParse(value).success