pendingyou 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # Changelog
 
+## 0.17.0 (2026-10-05)
+
+- Herdr: an agent running in a Herdr pane (`HERDR_ENV=1` with `HERDR_BIN_PATH` and `HERDR_PANE_ID`) marks its pane with
+  what it's waiting on you for, as display-only metadata (`src/herdr.ts`): `"$HERDR_BIN_PATH" pane report-metadata
+  "$HERDR_PANE_ID" --source pendingyou` with `py_app`, `py_agent` (the name the session goes by with Pending You),
+  `py_waiting` (how many cards wait on you), `py_card` (the most pressing one's title, redacted as permission cards' words
+  are and cut to 80 characters), `py_cards` (their request ids, as many as fit in 80 characters), `py_urgency`
+  (`blocking`, else `now`, `today` or `whenever`) and `py_asked` (those also asked in the conversation), and the state
+  labels `idle` and `done` read "waiting on you" while something waits (`--agent` keeps them to the pane's own agent).
+  Cleared when nothing waits and as the session ends. Herdr's program is run with an argument list, given one second,
+  its outcome never thrown, and a hook only starts it in the background; `--seq` (the moment, in milliseconds) keeps a
+  late write from winning, and `--ttl-ms 900000` lets tokens nobody repeats expire. Herdr's limits are kept: one source,
+  7 tokens a report, its token names, 80 characters a value.
+  - Claude Code: init's copy of the wake mod writes them whenever they change and every 5 minutes, through the hooks'
+    script (`herdr report --app claude-code`, the session's cards on stdin), learning how pressing each card is from
+    post_request and update_request; the session-start hook names the session in the background (from its transcript);
+    the SessionEnd hook clears them in the background.
+  - Codex: its card hook (`posted`) marks the thread as the pane's and writes them in the background; the thread's
+    keeper writes them with each live (it now starts in Herdr even without a connection here, and keeps on for them when
+    Pending You won't take its presence) and clears them as Codex quits; the listener writes them once a card is
+    answered.
+  - OpenCode and Pi: through what their plugin and extension already run: `posted` after each card call, `presence
+    --state live` (the heartbeat) and `closed`, and the listener. A pane's badges are every session of the app marked
+    there: OpenCode runs several in one pane.
+  - `<app>-threads.json` remembers each card's urgency, whether it blocks and whether it was asked in the conversation,
+    and the Herdr pane each session runs in; `herdr.json` whether the badges are off here.
+- `pendingyou herdr <what>`: the Pending You plugin for Herdr's commands (`src/herdr/`), which its manifest runs through
+  the hooks' script. `next` focuses the next pane waiting on you (blocking first, then by urgency); `open` is the popup
+  that lists them (Enter opens the card in Pending You through a terminal hyperlink, `t` takes you to the pane; `--demo`
+  shows made-up cards); `popup <pane>` opens one of the plugin's popups; `setup` checks Herdr's toasts, offers the
+  sidebar row (`$py_card`) as a managed block in Herdr's `config.toml`, written only with a yes and checked with `herdr
+  config check`, and prints the keybindings to add yourself; `doctor` says what's set up (also by hand in a terminal);
+  `view` turns the plugin's Agents view on or off; `watch` is the watcher (one per Herdr server, held by a lease) that
+  raises Herdr's toast when a pane gains a card, never for the tab you're looking at, cards that arrive together in one,
+  a card also asked in the conversation after 3 minutes; `event` makes sure it runs; `unconfigure` stops it, takes the
+  badges off every pane and turns them off here, clears the view, and takes the block out. Read-only: nothing asks
+  Pending You anything. Herdr's socket API through `HERDR_SOCKET_PATH`.
+- Tests never reach a real Herdr: the test setup drops every `HERDR_*` variable from their environment.
+
 ## 0.16.0 (2026-10-05)
 
 - A word on one of your own cards that's neither an answer nor your person's (guide 2.32): `/mcp/cli/answers` marks it

package/README.md

@@ -284,6 +284,29 @@ It's never in your way: the hooks only start it in the background, each send giv
 You from before presence is taken quietly. A sign-in that only hears (`--oauth`) sends nothing. `npx pendingyou status`
 has a Presence line for each agent.
 
+## In Herdr
+
+Since 0.17.0, an agent running in a [Herdr](https://herdr.dev) pane marks its pane with what it's waiting on you for,
+so Herdr's sidebar and Agents panel can show it: display-only metadata Herdr keeps on this computer (`herdr agent list`
+shows it), written with Herdr's own command line:
+
+- `py_app` and `py_agent`: the app and the name the session goes by with Pending You;
+- `py_waiting`: how many of its cards wait on you; `py_card` the most pressing one's title (anything that looks like a
+  secret taken out, at most 80 characters); `py_cards` their request ids; `py_urgency` how pressing (`blocking`, `now`,
+  `today`, `whenever`); `py_asked` the ones it also asked you in its conversation;
+- and its state reads "waiting on you" instead of idle or done while something waits.
+
+Claude Code's wake mod writes them whenever they change, Codex's card hook and keeper, OpenCode's plugin and Pi's
+extension through the commands they already run; every 5 minutes again, and they're taken off when nothing waits and as
+the session ends. Herdr is given one second for each, never through a shell, and never waited on by a hook; it forgets
+them after 15 minutes unless told again.
+
+The Pending You plugin for Herdr puts them to use: the card on each waiting agent's row in the sidebar, a toast when a
+pane gains one, a key to the next pane waiting on you, a popup that lists them (Enter opens the card in Pending You), and
+an Agents view with them first. Its commands are this command line's: `npx pendingyou herdr doctor` says what's set
+up. Its `unconfigure` takes the badges off every pane and stops writing them on this computer; its setup turns them on
+again.
+
 ## How Claude Code hears your answer
 
 **Claude Code 2.1.287 or later: the wake mod.** There's nothing to run. In each session the mod learns the cards
@@ -407,6 +430,7 @@ its environment. A failing command is tried twice more, then skipped. `--once` s
 | `stopcheck` | The Stop hook: items for you left only in chat (`--app`) |
 | `uninstall` | Remove what `init` added, and sign out (`--app`) |
 | `mcp --app <app>` | The stdio bridge: a local MCP server for an agent that can't run a headers helper (OpenCode, Pi), which passes each message on to Pending You with that agent's own sign-in here (`--check`) |
+| `herdr doctor` | Pending You in Herdr: the badges, the plugin, its toasts and its sidebar row. The plugin runs `herdr next`, `open`, `setup`, `view` and `unconfigure`; the agents' writers `herdr report` |
 
 Every command takes `--origin` (default `https://www.pendingyou.com`, or `$PENDINGYOU_ORIGIN`). `--app` takes
 `claude-code`, `codex`, `opencode` or `pi` (several with commas where a command sets up or reports several); with none,
@@ -434,7 +458,10 @@ Pi session waits on, and (0.14.0) the names it went by and its folder, kept 12 h
 (ids, names, folders and titles: never an answer or a note); `pi/` Pi's extension; and `cli/` the hooks' copy of the
 command line. `init`, `status` and the hooks read `~/.claude.json` (and a folder's `.mcp.json`, and
 `~/.claude/settings.json`'s enabled plugins), `~/.codex/config.toml`, OpenCode's config and Pi's `mcp.json` only to see
-whether the agent has a `pendingyou` MCP server and where it points. With a sign-in that only hears, the hooks and
+whether the agent has a `pendingyou` MCP server and where it points. In a Herdr pane (0.17.0) the agents' writers hand
+Herdr's own command line, on this computer, the badges above: a card's title (redacted, 80 characters at most) and its
+request id, never an answer or a note; `<app>-threads.json` remembers the pane each session runs in, and `herdr.json`
+whether the badges are off. With a sign-in that only hears, the hooks and
 listeners tell this computer's handed questions from another's by its names: its hostname, the names its sign-ins by
 code were given, a Mac's own name (`scutil --get ComputerName`) and, outside a hook, Tailscale's (`tailscale status`). For a permission prompt's card, the worker reads
 the end of the Claude Code session's transcript only for the name the session gave Pending You, and `git remote

package/dist/apps/codex-wake.js

@@ -7,6 +7,7 @@ import { connectionMachine, readCredential } from "../credentials.js";
 import { configDir, readJson, withLock, writeWhole } from "../files.js";
 import { clip, delegatedOf, isClosed, noticeOf } from "../format.js";
 import { chooseThread, goesBy, HANDED_FOR_MS, handedCard, handedMessage, namesAnotherComputer, } from "../handed.js";
+import { clearHerdr, herdrTarget, isUrgency, PANE_ID, reportCommand, writeHerdr, } from "../herdr.js";
 import { macName, tailscaleName } from "../remote.js";
 import { claimHanded, markHanded, momentOf, releaseHanded, wasHanded } from "../state.js";
 import { findCodex } from "./codex-app.js";
@@ -55,6 +56,7 @@ function threadOf(value) {
         at: value.at,
         ...(names.length ? { names: names.slice(-NAMES) } : {}),
         ...(typeof value.cwd === 'string' && value.cwd ? { cwd: value.cwd } : {}),
+        ...(typeof value.herdr === 'string' && PANE_ID.test(value.herdr) ? { herdr: value.herdr } : {}),
     };
 }
 async function load(io, app) {
@@ -155,6 +157,7 @@ export async function posted(io, options) {
         const requestId = [output?.requestId, args.requestId].find((id) => typeof id === 'string' && REQUEST_ID.test(id));
         const cwd = text(input.cwd, 1000);
         const now = io.now();
+        const pane = await herdrTarget(io);
         await change(io, app, (state) => {
             if (turn && call !== 'cancel_request') {
                 const record = state.turns[turn] ?? { at: now, cards: [] };
@@ -171,19 +174,29 @@ export async function posted(io, options) {
                     const before = waiting.cards[requestId];
                     const name = nameOf(args) ?? before?.name;
                     const title = text(args.title, 400) ?? text(reopen?.title, 400) ?? before?.title;
+                    const urgency = isUrgency(args.urgency) ? args.urgency : before?.urgency;
+                    const blocking = typeof args.blocking === 'boolean' ? args.blocking : before?.blocking;
+                    const askedFirst = call === 'post_request' ? askedIn(args) : before?.askedFirst;
                     waiting.cards[requestId] = {
                         ...(name ? { name } : {}),
                         ...(title ? { title } : {}),
                         at: now,
+                        ...(urgency ? { urgency } : {}),
+                        ...(blocking ? { blocking } : {}),
+                        ...(askedFirst ? { askedFirst } : {}),
                     };
                 }
             }
             if (cwd)
                 waiting.cwd = cwd;
+            if (pane)
+                waiting.herdr = pane.pane;
             waiting.origin = options.origin;
             waiting.at = now;
             state.threads[thread] = waiting;
         });
+        if (pane)
+            io.background(reportCommand(app, { session: thread, at: now }));
         if (app === 'codex')
             await keepListening(io, options.origin, thread);
         return 0;
@@ -192,6 +205,60 @@ export async function posted(io, options) {
         return 0;
     }
 }
+function askedIn(args) {
+    let asked = args.askedFirst;
+    if (typeof asked === 'string')
+        try {
+            asked = JSON.parse(asked);
+        }
+        catch {
+            return false;
+        }
+    return isObject(asked);
+}
+export async function reportThreads(io, app, options) {
+    try {
+        const pane = await herdrTarget(io);
+        if (!pane)
+            return 'off';
+        const session = options.session && THREAD.test(options.session) ? options.session : null;
+        let state = await load(io, app);
+        const known = session ? state.threads[session] : undefined;
+        if (session && known) {
+            const wanted = options.closed
+                ? known.herdr === pane.pane
+                    ? undefined
+                    : known.herdr
+                : pane.pane;
+            if (wanted !== known.herdr)
+                state = await change(io, app, (next) => {
+                    const thread = next.threads[session];
+                    if (!thread)
+                        return;
+                    if (wanted)
+                        thread.herdr = wanted;
+                    else
+                        delete thread.herdr;
+                });
+        }
+        const here = Object.values(state.threads).filter((thread) => thread.herdr === pane.pane);
+        if (here.length === 0 && options.closed)
+            return await clearHerdr(io, options.at, pane);
+        const newest = [...here].sort((a, b) => b.at - a.at)[0];
+        const cards = here.flatMap((thread) => Object.entries(thread.cards).map(([requestId, card]) => ({
+            requestId,
+            ...(typeof card.title === 'string' ? { title: card.title } : {}),
+            ...(isUrgency(card.urgency) ? { urgency: card.urgency } : {}),
+            ...(card.blocking === true ? { blocking: true } : {}),
+            ...(card.askedFirst === true ? { askedFirst: true } : {}),
+            at: typeof card.at === 'number' ? card.at : 0,
+        })));
+        return await writeHerdr(io, { app, agent: newest?.names?.at(-1) ?? null, cards, at: options.at }, pane);
+    }
+    catch {
+        return 'failed';
+    }
+}
 export async function touchThread(io, app, thread, cwd) {
     try {
         if (!THREAD.test(thread) || !(await load(io, app)).threads[thread])
@@ -532,9 +599,12 @@ export async function listen(io, options) {
                 else
                     ready.push({ heard, card });
             }
-            const gone = () => change(io, app, (state) => {
-                delete state.threads[thread];
-            });
+            const gone = async () => {
+                await change(io, app, (state) => {
+                    delete state.threads[thread];
+                });
+                await reportThreads(io, app, { at: io.now() });
+            };
             const message = wakeMessage(ready);
             if (message) {
                 if (!(await deliver(message, ready.map(({ heard }) => heard.requestId)))) {
@@ -556,13 +626,15 @@ export async function listen(io, options) {
             for (const heard of requests)
                 if (cards[heard.requestId] && isClosed(heard) && !done.includes(heard.requestId))
                     done.push(heard.requestId);
-            if (done.length)
+            if (done.length) {
                 await change(io, app, (state) => {
                     const waiting = state.threads[thread];
                     if (waiting)
                         for (const id of done)
                             delete waiting.cards[id];
                 });
+                await reportThreads(io, app, { at: io.now() });
+            }
             if (io.now() - started > PATIENT_AFTER_MS)
                 await io.sleep(PATIENT_PAUSE_MS, signal);
         }

package/dist/args.js

@@ -1,7 +1,20 @@
-import { APP_IDS, APP_NAMES, isAppId } from "./apps/ids.js";
+import { APP_IDS, APP_NAMES, DEFAULT_APP, isAppId } from "./apps/ids.js";
 export const DEFAULT_ORIGIN = 'https://www.pendingyou.com';
 export const DEFAULT_TIMEOUT_MS = 4 * 60 * 60 * 1000;
 const MAX_TIMEOUT_MS = 24 * 60 * 60 * 1000;
+export const HERDR_SUBS = [
+    'report',
+    'next',
+    'open',
+    'setup',
+    'doctor',
+    'unconfigure',
+    'watch',
+    'event',
+    'view',
+    'popup',
+];
+export const HERDR_POPUPS = ['cards', 'setup', 'doctor', 'demo'];
 export class UsageError extends Error {
     name = 'UsageError';
 }
@@ -66,6 +79,7 @@ const COMMANDS = new Set([
     'notify',
     'permission-card',
     'presence',
+    'herdr',
 ]);
 const FLAGS = {
     help: {},
@@ -121,6 +135,19 @@ const FLAGS = {
     refresh: { origin: true, force: false, app: true },
     'mcp-headers': { origin: true, check: false, app: true },
     mcp: { origin: true, app: true, check: false },
+    herdr: {
+        origin: true,
+        app: true,
+        session: true,
+        transcript: true,
+        name: true,
+        state: true,
+        at: true,
+        demo: false,
+        yes: false,
+        wait: false,
+        ensure: false,
+    },
 };
 const VALUE_OPTIONS = new Set([
     'origin',
@@ -381,6 +408,8 @@ export function parseArgs(argv, env = {}) {
         case 'mcp':
             none();
             return { name: 'mcp', origin, ...app(), check: flags.has('check') };
+        case 'herdr':
+            return herdrCommand(origin, positional, flags, app);
         case 'init':
             none();
             return {
@@ -415,6 +444,87 @@ export function parseArgs(argv, env = {}) {
     }
     throw new UsageError(`There’s no “${first}” command.`);
 }
+function herdrCommand(origin, positional, flags, app) {
+    const [sub, target, ...extra] = positional;
+    if (sub === undefined)
+        throw new UsageError('herdr needs what to do, like: pendingyou herdr doctor');
+    if (!HERDR_SUBS.includes(sub))
+        throw new UsageError(`herdr has no “${sub}”. Use ${HERDR_SUBS.join(', ')}.`);
+    const allowed = {
+        report: ['app', 'session', 'transcript', 'name', 'state', 'at'],
+        next: [],
+        open: ['demo'],
+        setup: ['yes'],
+        doctor: ['wait'],
+        unconfigure: [],
+        watch: ['ensure'],
+        event: [],
+        view: [],
+        popup: [],
+    };
+    for (const key of flags.keys())
+        if (key !== 'origin' && !allowed[sub].includes(key))
+            throw new UsageError(`herdr ${sub} has no --${key} option.`);
+    const command = { name: 'herdr', origin, sub: sub };
+    const takes = (choices) => {
+        if (extra.length || (target !== undefined && !choices?.includes(target)))
+            throw new UsageError(choices
+                ? `herdr ${sub} takes ${choices.join(' or ')}.`
+                : `herdr ${sub} takes no “${target ?? extra[0]}”.`);
+    };
+    const text = (key) => {
+        const value = flags.get(key);
+        return typeof value === 'string' ? value : undefined;
+    };
+    switch (command.sub) {
+        case 'report': {
+            takes(null);
+            const session = text('session');
+            if (session !== undefined && !THREAD.test(session))
+                throw new UsageError('herdr report needs a session id, like: --session 0199a1b2-…');
+            const state = text('state');
+            if (state !== undefined && state !== 'live' && state !== 'closed')
+                throw new UsageError('--state is live or closed.');
+            const at = text('at');
+            if (at !== undefined && !/^\d{1,16}$/.test(at))
+                throw new UsageError('--at needs a number.');
+            const transcript = text('transcript');
+            const agentName = text('name');
+            return {
+                ...command,
+                app: app().app ?? DEFAULT_APP,
+                ...(session ? { session } : {}),
+                ...(transcript ? { transcript } : {}),
+                ...(agentName ? { agentName } : {}),
+                closed: state === 'closed',
+                ...(at ? { at: Number(at) } : {}),
+            };
+        }
+        case 'popup':
+            if (target === undefined)
+                throw new UsageError(`herdr popup needs a pane: ${HERDR_POPUPS.join(', ')}.`);
+            takes(HERDR_POPUPS);
+            return { ...command, target };
+        case 'view':
+            takes(['on', 'off']);
+            return target ? { ...command, target } : command;
+        case 'open':
+            takes(null);
+            return { ...command, demo: flags.has('demo') };
+        case 'setup':
+            takes(null);
+            return { ...command, yes: flags.has('yes') };
+        case 'doctor':
+            takes(null);
+            return { ...command, wait: flags.has('wait') };
+        case 'watch':
+            takes(null);
+            return { ...command, ensure: flags.has('ensure') };
+        default:
+            takes(null);
+            return command;
+    }
+}
 export const USAGE = `pendingyou: Pending You for your coding agents (Claude Code, Codex, OpenCode and Pi)
 
   npx -y pendingyou@latest init
@@ -440,6 +550,9 @@ export const USAGE = `pendingyou: Pending You for your coding agents (Claude Cod
   npx pendingyou mcp --app <app>
                                A stdio MCP server for an agent that can't run a headers helper: it
                                passes each message on to Pending You with that agent's sign-in here
+  npx pendingyou herdr doctor  Pending You in Herdr: the badges on your agents' panes, the plugin, its
+                               toasts and its sidebar row. The plugin runs herdr next, open, setup,
+                               view and unconfigure
 
 Apps (for --app): ${APP_IDS.map((app) => `${app} (${APP_NAMES[app]})`).join(', ')}.