@jals1212/ci-local-pi 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,16 @@ add or change behaviour and a patch version fixes.
 
 ## Unreleased
 
+## 0.4.0
+
+### Added
+
+- Herdr sidebar: in a Herdr pane, the status line is also the pane's `$ci`
+  metadata token while a run is in flight and for 5 minutes after it ends, so
+  a `["$ci"]` row in Herdr's Agents sidebar shows ci-local next to the
+  agent. Display only, refreshed with a 30-second TTL, and cleared when the
+  session ends. (#54)
+
 ## 0.3.1
 
 ### Fixed

package/README.md

@@ -35,6 +35,26 @@ runs ci-local or Docker itself:
   shows it where it lists extension statuses: Gentle Shell, for one, under
   **Integrations** in the sidebar's Status card (or in its bottom bar on a
   narrow terminal).
+- **Herdr sidebar**: in a [Herdr](https://herdr.dev) pane (`HERDR_ENV=1`,
+  `HERDR_PANE_ID`, `HERDR_SOCKET_PATH`), the status line is also the pane's
+  `ci` metadata token while a run is queued or running, and its result for 5
+  minutes after it ends. The token is display only: the agent's state in
+  Herdr does not change. It is reported again every 10 seconds with a
+  30-second TTL, so it goes away when Pi does. To show it, add a `$ci` row to
+  the Agents sidebar in Herdr's `config.toml`, then run `herdr server reload-config`:
+
+  ```toml
+  [ui.sidebar.agents]
+  rows = [
+    ["state_icon", "machine", "workspace", "tab"],
+    ["agent"],
+    [{ token = "$ci", rules = [
+      { contains = "✗", fg = "#f38ba8" },
+      { contains = "✓", fg = "#a6e3a1" },
+      { contains = "⧗", fg = "#f9e2af" },
+    ] }],
+  ]
+  ```
 - **Only the session's own runs** get the cards and the notification, and
   reach the agent: runs this session started. A run started from Pi's bash
   tool names its session (ci-local records Pi's `PI_SESSION_ID` as `session`

package/extensions/ci-local.ts

@@ -13,6 +13,9 @@
 //   this session's process (a background job, even orphaned). Another
 //   session's run in the same repository, or one started in a terminal, shows
 //   in the status line alone.
+// - Herdr: in a pane Herdr runs, the status line is also the pane's `$ci`
+//   metadata token while a run is in flight and for 5 minutes after it ends,
+//   so a `["$ci"]` row in Herdr's Agents sidebar shows it (display only).
 // - When a run starts: a card in the transcript when it is starting (or
 //   waiting for its turn), another when its steps start; for you only (session
 //   entries, never in the model's context, never repeated after a reload).
@@ -42,6 +45,8 @@ import {
   LAUNCH_WAIT_MS,
   WAKE_TEXT,
   cardContent,
+  createHerdrLine,
+  createHerdrPublisher,
   createDelivery,
   createStatusLine,
   createTracker,
@@ -49,6 +54,8 @@ import {
   eventsFileFor,
   exitCard,
   findProject,
+  herdrPane,
+  herdrSend,
   launchReport,
   launchRun,
   ownsRun,
@@ -98,6 +105,10 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
   // belongs to the session that started it; another session drops it.
   type Launch = ReturnType<typeof launchRun> & { seen: boolean; waiting: boolean; sessionId: string }
   const launches = new Map<number, Launch>()
+  // In a Herdr pane, the footer line is also the pane's `$ci` sidebar token
+  // (see createHerdrLine in core.js); null elsewhere. Read when a session
+  // starts following, so a test or a moved pane gets its own.
+  let herdr: { pane: string; socket: string; publisher: ReturnType<typeof createHerdrPublisher> } | undefined
 
   pi.on('agent_start', async () => {
     runActive = true
@@ -249,6 +260,11 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     // already showed, and records each finished run it shows (see
     // createStatusLine in core.js).
     const statusLine = createStatusLine({ file, sessionId, reason })
+    const pane = herdrPane(process.env)
+    if (pane && (herdr?.pane !== pane.pane || herdr.socket !== pane.socket)) {
+      herdr = { ...pane, publisher: createHerdrPublisher({ send: herdrSend(pane) }) }
+    }
+    const herdrLine = pane ? createHerdrLine() : undefined
 
     const tick = () => {
       let run
@@ -259,6 +275,7 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
       }
       const { footer, changed } = statusLine.update(run)
       if (changed) ctx.ui.setStatus(KEY, footer)
+      if (herdrLine) herdr?.publisher.update(herdrLine.text(run))
       settleLaunches(run)
       // Only this session's own runs get cards and reach the agent, as Gentle
       // AI's job notices go only to the session that started the job. Another
@@ -336,6 +353,11 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
 
   pi.on('session_shutdown', async () => {
     stop()
+    // The sidebar token goes with the session (its TTL would end it anyway).
+    if (herdr) {
+      herdr.publisher.update(null)
+      await herdr.publisher.idle()
+    }
     startReason = undefined
     delete (globalThis as Record<symbol, unknown>)[FLAG]
   })

package/extensions/core.js

@@ -19,6 +19,7 @@ import {
   statSync,
   writeFileSync,
 } from 'node:fs'
+import { createConnection } from 'node:net'
 import { tmpdir } from 'node:os'
 import { dirname, isAbsolute, join } from 'node:path'
 
@@ -663,3 +664,153 @@ export function exitCard({ pid, code, signal = null, output, tail = outputTail(o
     },
   }
 }
+
+// Herdr (https://herdr.dev): in a pane Herdr runs, the footer line is also the
+// pane's `$ci` metadata token, so a row `["$ci"]` in Herdr's Agents sidebar
+// shows the run. A token is display only: it never touches the agent's state.
+
+/** The token's name, as a sidebar row names it: `$ci`. */
+export const HERDR_TOKEN = 'ci'
+/** Who reports the token. No sequence numbers: one sender, one report at a time. */
+export const HERDR_SOURCE = 'ci-local'
+/** Herdr drops the token this long after the last report: a Pi gone leaves nothing behind. */
+export const HERDR_TTL_MS = 30_000
+/** A token unchanged is reported again this often, well inside its TTL. */
+export const HERDR_REFRESH_MS = 10_000
+/** How long a run's result stays in the sidebar after the run ends. */
+export const HERDR_RESULT_MS = 5 * 60_000
+/** Herdr keeps at most this many characters of a token. */
+export const HERDR_TOKEN_MAX = 80
+
+/** The pane and socket of the Herdr pane this process runs in, or null outside one. */
+export function herdrPane(env = process.env) {
+  const pane = env.HERDR_PANE_ID?.trim()
+  const socket = env.HERDR_SOCKET_PATH?.trim()
+  return env.HERDR_ENV === '1' && pane && socket ? { pane, socket } : null
+}
+
+function clip(text) {
+  const chars = [...text]
+  return chars.length <= HERDR_TOKEN_MAX ? text : chars.slice(0, HERDR_TOKEN_MAX - 1).join('') + '…'
+}
+
+/**
+ * What the token says for a run: the footer line while it is in flight, and
+ * its result for HERDR_RESULT_MS after it ended (by its end event; a run that
+ * stopped without one, from when this session saw it stop). Null otherwise:
+ * no run, or a result older than that, or a run found already stopped.
+ */
+export function createHerdrLine({ now = Date.now } = {}) {
+  let flying // the key of the last run seen in flight
+  const endedAt = new Map()
+  return {
+    text(run) {
+      if (!run) return null
+      if (!FINISHED.has(run.state.state)) {
+        flying = run.key
+        return clip(footerText(run.state))
+      }
+      if (!endedAt.has(run.key)) {
+        const ended = Date.parse(run.state.end?.ts ?? '')
+        endedAt.clear()
+        endedAt.set(run.key, Number.isFinite(ended) ? ended : run.key === flying ? now() : null)
+      }
+      const ended = endedAt.get(run.key)
+      return ended !== null && now() - ended < HERDR_RESULT_MS ? clip(footerText(run.state)) : null
+    },
+  }
+}
+
+/** The socket request that sets the token (with its TTL), or clears it (null). */
+export function herdrReport(pane, value) {
+  const params = { pane_id: pane, source: HERDR_SOURCE, tokens: { [HERDR_TOKEN]: value } }
+  if (value !== null) params.ttl_ms = HERDR_TTL_MS
+  return { method: 'pane.report_metadata', params }
+}
+
+let herdrRequests = 0
+
+/**
+ * A sender of the token to Herdr's socket (one JSON line, one reply): resolves
+ * true when Herdr accepted it, false on any error or after `timeoutMs`.
+ */
+export function herdrSend({ pane, socket }, { timeoutMs = 2000 } = {}) {
+  return (value) =>
+    new Promise((resolve) => {
+      const id = `ci-local-${process.pid}-${++herdrRequests}`
+      let reply = ''
+      let done = false
+      const finish = (ok) => {
+        if (done) return
+        done = true
+        clearTimeout(timer)
+        conn.destroy()
+        resolve(ok)
+      }
+      const conn = createConnection(socket)
+      const timer = setTimeout(() => finish(false), timeoutMs)
+      timer.unref?.()
+      conn.on('connect', () => conn.write(JSON.stringify({ id, ...herdrReport(pane, value) }) + '\n'))
+      conn.on('data', (data) => {
+        reply += data
+        const end = reply.indexOf('\n')
+        if (end < 0) return
+        try {
+          const answer = JSON.parse(reply.slice(0, end))
+          finish(answer.id === id && answer.result?.type === 'ok')
+        } catch {
+          finish(false)
+        }
+      })
+      conn.on('error', () => finish(false))
+      conn.on('close', () => finish(false))
+    })
+}
+
+/**
+ * Keeps Herdr's token in step with `update(value)` (null clears it): a report
+ * when the value changes, again every HERDR_REFRESH_MS while it stays, one
+ * report at a time (the latest value waits for the one on its way). A failed
+ * report is tried again at the next update. `idle()` resolves once nothing is
+ * on its way.
+ */
+export function createHerdrPublisher({ send, now = Date.now, refreshMs = HERDR_REFRESH_MS }) {
+  let shown = null // what Herdr has
+  let sentAt = 0
+  let inFlight = null
+  let pending // the value to report once inFlight is done
+  const update = (value) => {
+    if (inFlight) {
+      pending = value
+      return
+    }
+    const due = value !== shown || (value !== null && now() - sentAt >= refreshMs)
+    if (!due) return
+    let sending
+    try {
+      sending = Promise.resolve(send(value))
+    } catch {
+      sending = Promise.resolve(false)
+    }
+    inFlight = sending
+      .catch(() => false)
+      .then((ok) => {
+        if (ok) {
+          shown = value
+          sentAt = now()
+        }
+        inFlight = null
+        if (pending !== undefined) {
+          const next = pending
+          pending = undefined
+          update(next)
+        }
+      })
+  }
+  return {
+    update,
+    async idle() {
+      while (inFlight) await inFlight
+    },
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jals1212/ci-local-pi",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Pi extension and skill for @jals1212/ci-local: the state of this repository's ci-local run in Pi's status line, cards and a read-only tool for the agent.",
   "license": "MIT",
   "author": "jals1212",

package/skills/ci-local/SKILL.md

@@ -4,7 +4,7 @@ description: "Trigger: ci-local, run CI locally, ci-local.config.sh, CI_PROJECT,
 license: MIT
 metadata:
   author: jals1212
-  version: "0.3.1"
+  version: "0.4.0"
 ---
 
 ## Activation Contract