@jals1212/ci-local-pi 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,26 @@ 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
+
+- A `ci-local.config.sh` written after the session started is now followed:
+  `ci_local_run`, or the end of a turn, sets up the status line, the cards and
+  the end card, which before came only after a `/reload`. When nothing can
+  follow the run (no UI, or no events file), `ci_local_run` no longer promises
+  a footer or an end card. (#51)
+
 ## 0.3.0
 
 ### Changed

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,
@@ -89,12 +96,19 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
   // agent_start to agent_settled (in-run compaction and retries included).
   let delivery: ReturnType<typeof createDelivery> | undefined
   let runActive = false
+  // The reason of the session's session_start (createStatusLine reads it);
+  // undefined before one and after session_shutdown, when nothing is followed.
+  let startReason: string | undefined
   // The runs ci_local_run started, by pid, until their run shows in the events
   // file (seen) or they end. One that ends unseen, after the tool returned,
   // gets an end card of its own (exitCard): no event will ever name it. Each
   // 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
@@ -104,7 +118,10 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     runActive = false
     delivery?.boundary()
   })
-  pi.on('turn_end', async () => delivery?.boundary())
+  pi.on('turn_end', async (_event, ctx) => {
+    follow(ctx)
+    delivery?.boundary()
+  })
   pi.on('session_compact', async () => delivery?.boundary())
   pi.on('session_compact_failed', async () => delivery?.boundary())
 
@@ -167,6 +184,8 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     async execute(_id, params, signal, _onUpdate, ctx) {
       const found = findProject(ctx.cwd)
       if (!found) throw new Error(`no ci-local.config.sh with a literal CI_PROJECT at or above ${ctx.cwd}`)
+      // Followed before the launch, so the tracker is there when the run starts.
+      const followed = follow(ctx)
       const sessionId = ctx.sessionManager.getSessionId()
       const launch = launchRun({ repo: found.repo, args: params.args ?? [], sessionId })
       const tracked: Launch = Object.assign(launch, { seen: false, waiting: true, sessionId })
@@ -178,7 +197,7 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
         if (launch.pid !== undefined) launches.delete(launch.pid)
         if (launch.error) throw new Error(`cannot start ${launch.bin}: ${launch.error}`)
       }
-      return { content: [{ type: 'text', text: launchReport(result, launch, found.project) }], details: { kind: result.kind, pid: launch.pid } }
+      return { content: [{ type: 'text', text: launchReport(result, launch, found.project, { followed }) }], details: { kind: result.kind, pid: launch.pid } }
     },
   })
 
@@ -197,11 +216,25 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
   pi.on('session_start', async (event, ctx: ExtensionContext) => {
     stop()
     runActive = false
-    if (!ctx.hasUI) return
+    startReason = event.reason
+    follow(ctx)
+  })
+
+  /**
+   * Sets up what follows the runs of the session's repository (the tick timer,
+   * the status line, the cards, the delivery to the agent); true once it is
+   * running. session_start calls it, and so do ci_local_run and turn_end while
+   * nothing is followed yet: a ci-local.config.sh written during the session
+   * is picked up then, not only after a /reload (#51).
+   */
+  function follow(ctx: ExtensionContext): boolean {
+    if (timer) return true
+    if (startReason === undefined || !ctx.hasUI) return false
+    const reason = startReason
     const found = findProject(ctx.cwd)
-    if (!found) return
+    if (!found) return false
     const file = eventsFileFor(found.project, process.env, found.repo)
-    if (!file) return // CI_LOCAL_EVENTS=off, or no private cache: runs write no events
+    if (!file) return false // CI_LOCAL_EVENTS=off, or no private cache: runs write no events
     const tracker = createTracker()
     // Start cards this session already shows (a reload, a resumed session): not again.
     for (const entry of ctx.sessionManager.getBranch()) {
@@ -226,7 +259,12 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     // The status line leaves out a run already over whose result a session
     // already showed, and records each finished run it shows (see
     // createStatusLine in core.js).
-    const statusLine = createStatusLine({ file, sessionId, reason: event.reason })
+    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
@@ -237,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
@@ -309,10 +348,17 @@ function ciLocal(pi: ExtensionAPI, { launchWaitMs }: { launchWaitMs: number }) {
     tick()
     timer = setInterval(tick, POLL_MS)
     timer.unref?.()
-  })
+    return true
+  }
 
   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'
 
@@ -618,14 +619,21 @@ function endedLine(launch) {
   return `ci-local ${verb} ${howEnded(launch)} before a run started`
 }
 
-/** What ci_local_run tells the agent of a launch and how it stands. */
-export function launchReport(result, launch, project) {
+/**
+ * What ci_local_run tells the agent of a launch and how it stands. followed:
+ * whether this session follows the run (a footer and an end card will come).
+ */
+export function launchReport(result, launch, project, { followed = true } = {}) {
   const where = `Output: ${launch.output}.`
-  const follow = 'The footer follows it and its end card reaches you when it ends: do not poll, sleep or run `ci-local --status`.'
+  const follow = followed
+    ? 'The footer follows it and its end card reaches you when it ends: do not poll, sleep or run `ci-local --status`.'
+    : 'This session cannot follow it (no UI, or no events file to read), so no footer or end card will come: read its output, or ask ci_local_status.'
   if (result.kind === 'started')
     return `ci-local started (pid ${launch.pid}) for ${project}: ${stateText(result.run.state)}. ${follow} ${where}`
-  if (result.kind === 'waiting')
-    return `ci-local launched (pid ${launch.pid}) for ${project}, no event yet: another run of ${project} may hold its events file until it ends. ${follow} ${where}`
+  if (result.kind === 'waiting') {
+    const why = followed ? `: another run of ${project} may hold its events file until it ends` : ''
+    return `ci-local launched (pid ${launch.pid}) for ${project}, no event yet${why}. ${follow} ${where}`
+  }
   const tail = outputTail(launch.output)
   return [
     `${endedLine(launch)}. ${where}`,
@@ -656,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.0",
+  "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.0"
+  version: "0.4.0"
 ---
 
 ## Activation Contract