pendingyou 0.16.0 → 0.18.0

package/dist/herdr/command.js

@@ -0,0 +1,301 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { reportThreads } from "../apps/codex-wake.js";
+import { APP_IDS, APP_NAMES } from "../apps/ids.js";
+import { configDir, readText, writeWhole } from "../files.js";
+import { badgesOn, clearHerdr, HERDR_SOURCE, herdrBin, herdrPane, herdrTarget, readPayload, setBadges, TOKEN_NAMES, writeHerdr, } from "../herdr.js";
+import { sessionName } from "../permission.js";
+import { presenceName } from "../presence.js";
+import { shimPath } from "../shim.js";
+import { VERSION } from "../version.js";
+import { badgedPanes, nextWaiting, readWaiting } from "./panes.js";
+import { agentView, CARD_ROW, hasBlock, herdrConfigPath, KEYS_SNIPPET, ownSidebar, pluginOff, pluginPlace, SIDEBAR_BLOCK, saveView, setPluginOff, TOAST_SNIPPET, toastDelivery, viewOn, withBlock, withoutBlock, } from "./plugin.js";
+import { cardsPopup } from "./popup.js";
+import { HerdrError, herdrRequest } from "./socket.js";
+import { pluginEnabled, stopWatcher, watch, watching } from "./watch.js";
+async function toast(place, title, body) {
+    if (!place.socket)
+        return;
+    await herdrRequest(place.socket, 'notification.show', {
+        title,
+        ...(body ? { body } : {}),
+        sound: 'none',
+    }).catch(() => { });
+}
+async function report(io, command) {
+    try {
+        const app = command.app ?? 'claude-code';
+        const at = command.at ?? io.now();
+        if (app !== 'claude-code') {
+            await reportThreads(io, app, { session: command.session ?? null, closed: command.closed, at });
+            return 0;
+        }
+        const pane = await herdrTarget(io);
+        if (!pane)
+            return 0;
+        if (command.closed) {
+            await clearHerdr(io, at, pane);
+            return 0;
+        }
+        const payload = readPayload(await io.readStdin(500).catch(() => ''));
+        const name = presenceName(payload?.name) ??
+            presenceName(command.agentName) ??
+            (await sessionName(command.transcript));
+        await writeHerdr(io, {
+            app,
+            ...(name ? { agent: name } : {}),
+            ...(payload ? { cards: payload.cards } : {}),
+            at,
+        }, pane);
+    }
+    catch { }
+    return 0;
+}
+async function next(_io, place) {
+    if (!place.socket)
+        throw new HerdrError('unreachable', 'Run this from Herdr.');
+    const { snapshot, waiting } = await readWaiting(place.socket);
+    const target = nextWaiting(waiting, snapshot.focusedPane);
+    if (!target) {
+        await toast(place, 'Pending You', 'Nothing in Herdr is waiting on you.');
+        return 0;
+    }
+    await herdrRequest(place.socket, 'pane.focus', { pane_id: target.paneId });
+    return 0;
+}
+async function popup(place, entrypoint) {
+    if (!place.socket)
+        throw new HerdrError('unreachable', 'Run this from Herdr.');
+    try {
+        await herdrRequest(place.socket, 'plugin.pane.open', {
+            plugin_id: place.id,
+            entrypoint,
+        });
+    }
+    catch (error) {
+        if (error instanceof HerdrError && error.code === 'ui_busy')
+            await toast(place, 'Pending You', 'Close what’s open in Herdr first, then try again.');
+        else
+            throw error;
+    }
+    return 0;
+}
+async function view(place, target) {
+    if (!place.socket)
+        throw new HerdrError('unreachable', 'Run this from Herdr.');
+    const on = target === 'on' ? true : target === 'off' ? false : !(await viewOn(place));
+    if (on)
+        await herdrRequest(place.socket, 'agent.view.set', agentView(place.id));
+    else
+        await herdrRequest(place.socket, 'agent.view.clear', { source: `plugin:${place.id}` }).catch(() => { });
+    await saveView(place, on);
+    await toast(place, 'Pending You', on ? 'Agents waiting on you come first in the Agents panel.' : 'The Agents panel is as it was.');
+    return 0;
+}
+async function clearAll(place, at) {
+    if (!place.socket)
+        return 0;
+    const { snapshot } = await readWaiting(place.socket);
+    let cleared = 0;
+    for (const pane of badgedPanes(snapshot))
+        try {
+            await herdrRequest(place.socket, 'pane.report_metadata', {
+                pane_id: pane.paneId,
+                source: HERDR_SOURCE,
+                tokens: Object.fromEntries(TOKEN_NAMES.map((name) => [name, null])),
+                clear_state_labels: true,
+                seq: at,
+            });
+            cleared++;
+        }
+        catch { }
+    return cleared;
+}
+async function reloadConfig(place) {
+    if (!place.socket)
+        return false;
+    return herdrRequest(place.socket, 'server.reload_config').then(() => true, () => false);
+}
+async function unconfigure(io, place) {
+    await setBadges(io, false);
+    await setPluginOff(place, true);
+    const stopped = await stopWatcher(place);
+    const cleared = await clearAll(place, io.now()).catch(() => 0);
+    if (place.socket)
+        await herdrRequest(place.socket, 'agent.view.clear', { source: `plugin:${place.id}` }).catch(() => { });
+    await saveView(place, false).catch(() => { });
+    const path = herdrConfigPath(io);
+    const doc = await readText(path).catch(() => null);
+    let removed = false;
+    if (doc !== null && hasBlock(doc)) {
+        await writeWhole(path, withoutBlock(doc));
+        removed = true;
+        await reloadConfig(place);
+    }
+    io.out(`Pending You: ${[
+        stopped ? 'stopped its watcher' : 'no watcher was running',
+        `took the badges off ${cleared} pane${cleared === 1 ? '' : 's'} and turned them off here`,
+        removed ? `took its sidebar row out of ${path}` : 'no sidebar row of its to take out',
+    ].join('; ')}.\n`);
+    await toast(place, 'Pending You is off in Herdr', `Badges, toasts and its sidebar row are gone. Remove the plugin itself with: herdr plugin unlink ${place.id} (or uninstall).`);
+    return 0;
+}
+const line = (mark, text) => `${mark} ${text}\n`;
+async function setup(io, place, options) {
+    const ask = async (question) => {
+        if (options.yes)
+            return true;
+        if (!io.interactive)
+            return false;
+        return /^y(es)?$/i.test((await io.ask(`${question} (y/N) `)).trim());
+    };
+    io.out('Pending You for Herdr: setup\n\n');
+    await setPluginOff(place, false);
+    if (!(await badgesOn(io))) {
+        await setBadges(io, true);
+        io.out(line('✓', 'Badges are back on: your agents mark their panes when they wait on you.'));
+    }
+    const path = herdrConfigPath(io);
+    const doc = (await readText(path).catch(() => null)) ?? '';
+    const delivery = toastDelivery(doc);
+    if (delivery === 'off')
+        io.out(`${line('!', `Herdr's toasts are off here (${path} doesn't turn them on).`)}  To see Pending You's toasts, add this to config.toml on the computer you attach from (here, or the one you run herdr --remote on):\n\n${indent(TOAST_SNIPPET)}\n`);
+    else if (delivery === 'unknown')
+        io.out(line('·', `Couldn't tell how ${path} delivers toasts; Pending You's follow it.`));
+    else
+        io.out(line('✓', `Toasts reach you here (delivery = "${delivery}").`));
+    if (hasBlock(doc))
+        io.out(line('✓', `The sidebar row is in ${path}.`));
+    else if (ownSidebar(doc))
+        io.out(`${line('·', `${path} sets the agents' sidebar rows itself, so the plugin leaves it alone.`)}  Add this row to its rows to show the card each agent waits on you for:\n\n    ${CARD_ROW},\n\n`);
+    else {
+        io.out(`\nHerdr's sidebar can show, under each agent waiting on you, the card it's waiting on. That's this block, added to ${path}:\n\n${indent(SIDEBAR_BLOCK)}\n`);
+        if (await ask('Add it?')) {
+            const written = await writeBlock(io, place, path, doc);
+            io.out(line(written.ok ? '✓' : '!', written.said));
+        }
+        else
+            io.out(line('·', 'Left config.toml as it was. Run setup again any time to add it.'));
+    }
+    io.out(`${line('·', "Herdr reads the sidebar's rows and toasts on the computer you attach from: attach from another one (herdr --remote) and they go in its config.toml.")}\n`);
+    io.out(`Keys: Herdr leaves your keybindings to you. Add these to config.toml to open your cards with prefix+y and jump to the next pane waiting on you with prefix+shift+y:\n\n${indent(KEYS_SNIPPET)}\n`);
+    if (place.socket && !(await viewOn(place))) {
+        if (await ask('Show agents waiting on you first in Herdr’s Agents panel?')) {
+            await view(place, 'on').catch(() => { });
+            io.out(line('✓', 'Agents waiting on you come first in the Agents panel.'));
+        }
+    }
+    if (place.socket && !(await watching(place)))
+        io.background(['herdr', 'watch']);
+    if (io.interactive && !options.yes)
+        await io.ask('\nPress Enter to close. ');
+    return 0;
+}
+const indent = (text) => text
+    .split('\n')
+    .map((each) => (each ? `    ${each}` : each))
+    .join('\n');
+async function writeBlock(io, place, path, doc) {
+    const before = await readText(path).catch(() => null);
+    await writeWhole(path, withBlock(doc));
+    const bin = herdrBin(io.env);
+    if (bin) {
+        const checked = await io.run(bin, ['config', 'check'], 10_000);
+        if (checked.code !== 0 && checked.code !== 2) {
+            if (before === null)
+                await writeWhole(path, '');
+            else
+                await writeWhole(path, before);
+            return { ok: false, said: `Herdr didn't take the block, so ${path} is as it was.` };
+        }
+    }
+    const reloaded = await reloadConfig(place);
+    return {
+        ok: true,
+        said: reloaded
+            ? `Added the sidebar row to ${path}; Herdr has it now.`
+            : `Added the sidebar row to ${path}. Reload Herdr's config (herdr server reload-config) to see it.`,
+    };
+}
+async function doctor(io, place, options) {
+    io.out(`Pending You for Herdr (pendingyou ${VERSION})\n\n`);
+    const pane = herdrPane(io.env);
+    if (!io.env.HERDR_PLUGIN_ID)
+        io.out(pane
+            ? line('✓', `In a Herdr pane (${pane.pane}).`)
+            : line('·', 'Not run from a Herdr pane: agents mark their panes when they run in one.'));
+    if (await pluginOff(place))
+        io.out(line('!', 'The plugin is off here (its unconfigure). Its setup turns it on again.'));
+    io.out((await badgesOn(io))
+        ? line('✓', 'Badges are on: agents in Herdr mark their panes when they wait on you.')
+        : line('!', 'Badges are off here (the plugin’s unconfigure). Its setup turns them on again.'));
+    const shim = await readFile(shimPath(io), 'utf8').catch(() => null);
+    io.out(shim
+        ? line('✓', `Your agents' hooks run ${shimPath(io)}.`)
+        : line('!', 'Pending You isn’t set up for your agents here: run npx -y pendingyou@latest init'));
+    const apps = [];
+    for (const app of APP_IDS)
+        if ((await readText(join(configDir(io), `${app}.json`)).catch(() => null)) !== null)
+            apps.push(app);
+    if (apps.length)
+        io.out(line('✓', `Set up here: ${apps.map((app) => APP_NAMES[app]).join(', ')}.`));
+    if (place.socket) {
+        try {
+            const pong = await herdrRequest(place.socket, 'ping');
+            io.out(line('✓', `Herdr ${String(pong?.version ?? '')} answers on its socket.`));
+            const enabled = await pluginEnabled(place.socket, place.id).catch(() => false);
+            io.out(enabled
+                ? line('✓', `The plugin (${place.id}) is enabled.`)
+                : line('!', `The plugin (${place.id}) isn't linked or is disabled.`));
+            const { snapshot, waiting } = await readWaiting(place.socket);
+            const badged = badgedPanes(snapshot).length;
+            io.out(line('·', `${badged} pane${badged === 1 ? '' : 's'} with Pending You's badges, ${waiting.length} waiting on you.`));
+            io.out((await watching(place))
+                ? line('✓', 'Its watcher is running (toasts when a pane gains a card).')
+                : line('!', 'Its watcher isn’t running: it starts with Herdr, or with setup.'));
+            io.out(line('·', `Its Agents view is ${(await viewOn(place)) ? 'on' : 'off'}.`));
+        }
+        catch (error) {
+            io.out(line('!', error instanceof HerdrError ? error.message : 'Herdr isn’t answering.'));
+        }
+    }
+    else
+        io.out(line('·', 'No Herdr socket here: run it from Herdr to check the plugin.'));
+    const path = herdrConfigPath(io);
+    const doc = await readText(path).catch(() => null);
+    const delivery = toastDelivery(doc ?? '');
+    io.out(delivery === 'off'
+        ? line('!', `Toasts are off in ${path}: setup says how to turn them on.`)
+        : line('·', `Toasts here: ${delivery}.`));
+    io.out(doc !== null && hasBlock(doc)
+        ? line('✓', `The sidebar row is in ${path}.`)
+        : line('·', `No sidebar row of the plugin's in ${path}: setup offers it.`));
+    if (options.wait && io.interactive)
+        await io.ask('\nPress Enter to close. ');
+    return 0;
+}
+export async function herdr(io, command) {
+    const place = pluginPlace(io);
+    switch (command.sub) {
+        case 'report':
+            return report(io, command);
+        case 'watch':
+            return watch(io, place, { ensure: command.ensure === true });
+        case 'event':
+            return watch(io, place, { ensure: true }).catch(() => 0);
+        case 'next':
+            return next(io, place);
+        case 'popup':
+            return popup(place, command.target ?? 'cards');
+        case 'open':
+            return cardsPopup(io, place, { origin: command.origin, demo: command.demo === true });
+        case 'view':
+            return view(place, command.target);
+        case 'setup':
+            return setup(io, place, { yes: command.yes === true });
+        case 'doctor':
+            return doctor(io, place, { wait: command.wait === true });
+        case 'unconfigure':
+            return unconfigure(io, place);
+    }
+}

package/dist/herdr/notice.js

@@ -0,0 +1,67 @@
+import { APP_NAMES } from "../apps/ids.js";
+import { cleanValue } from "../herdr.js";
+export const ASKED_QUIET_MS = 3 * 60_000;
+export const COALESCE_MS = 3000;
+export const TOAST_TITLE_MAX = 80;
+export const TOAST_BODY_MAX = 240;
+export const emptyNotices = () => ({ known: new Map(), pending: [], seeded: false });
+function cardsOf(waiting) {
+    const extra = Math.max(0, waiting.waiting - waiting.cards.length);
+    return [
+        ...waiting.cards,
+        ...Array.from({ length: extra }, (_, index) => `${waiting.paneId}#${waiting.cards.length + index + 1}`),
+    ];
+}
+export function look(state, waiting, now) {
+    const known = new Map();
+    const arrived = [];
+    for (const pane of waiting) {
+        const cards = cardsOf(pane);
+        known.set(pane.paneId, { ids: new Set(cards), count: pane.waiting });
+        if (!state.seeded)
+            continue;
+        const before = state.known.get(pane.paneId) ?? { ids: new Set(), count: 0 };
+        const gained = pane.waiting - before.count;
+        if (gained <= 0)
+            continue;
+        for (const requestId of cards.filter((id) => !before.ids.has(id)).slice(0, gained))
+            arrived.push({
+                requestId,
+                paneId: pane.paneId,
+                seen: now,
+                asked: pane.asked.includes(requestId),
+            });
+    }
+    const still = state.pending.filter((arrival) => known.get(arrival.paneId)?.ids.has(arrival.requestId));
+    return { known, pending: [...still, ...arrived], seeded: true };
+}
+const readyAt = (arrival) => arrival.seen + (arrival.asked ? ASKED_QUIET_MS : 0);
+const who = (pane) => pane.agent ?? (pane.app ? APP_NAMES[pane.app] : 'An agent');
+export function toastFor(arrivals, waiting) {
+    const panes = waiting.filter((pane) => arrivals.some((arrival) => arrival.paneId === pane.paneId));
+    const first = panes[0];
+    if (!first)
+        return null;
+    const more = first.waiting > 1 ? ` (+${first.waiting - 1} more)` : '';
+    const others = panes.length > 1 ? `, and ${panes.length - 1} more pane${panes.length > 2 ? 's' : ''}` : '';
+    const title = arrivals.length === 1
+        ? `Pending You · ${who(first)} is waiting on you`
+        : `Pending You · ${arrivals.length} new cards waiting on you`;
+    const body = `${first.card ?? 'A new card'}${more} · ${first.workspace} › ${first.tab}${others}`;
+    return { title: cleanValue(title, TOAST_TITLE_MAX), body: cleanValue(body, TOAST_BODY_MAX) };
+}
+export function due(state, waiting, now, viewingTab) {
+    const ready = state.pending.filter((arrival) => readyAt(arrival) <= now);
+    if (ready.length === 0)
+        return { toast: null, state };
+    const first = Math.min(...ready.map(readyAt));
+    if (now < first + COALESCE_MS)
+        return { toast: null, state };
+    const rest = state.pending.filter((arrival) => !ready.includes(arrival));
+    const tabOf = new Map(waiting.map((pane) => [pane.paneId, pane.tabId]));
+    const shown = ready.filter((arrival) => tabOf.get(arrival.paneId) !== viewingTab);
+    return {
+        toast: shown.length ? toastFor(shown, waiting) : null,
+        state: { ...state, pending: rest },
+    };
+}

package/dist/herdr/panes.js

@@ -0,0 +1,121 @@
+import { APP_IDS } from "../apps/ids.js";
+import { PRESSING, TOKENS } from "../herdr.js";
+import { herdrRequest } from "./socket.js";
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const text = (value) => (typeof value === 'string' ? value : null);
+const count = (value) => typeof value === 'number' && Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+const placeOf = (value, key) => {
+    const id = text(value[key]);
+    if (!id)
+        return null;
+    return {
+        id,
+        label: text(value.label) ?? id,
+        number: count(value.number),
+        focused: value.focused === true,
+    };
+};
+export function readSnapshot(value) {
+    const snapshot = isObject(value) ? value : {};
+    const list = (key) => (Array.isArray(snapshot[key]) ? snapshot[key] : []).filter(isObject);
+    const tokensOf = (value) => Object.fromEntries(Object.entries(isObject(value) ? value : {}).filter((entry) => typeof entry[1] === 'string'));
+    return {
+        version: text(snapshot.version) ?? '',
+        focusedPane: text(snapshot.focused_pane_id),
+        focusedTab: text(snapshot.focused_tab_id),
+        focusedWorkspace: text(snapshot.focused_workspace_id),
+        workspaces: list('workspaces').flatMap((each) => {
+            const place = placeOf(each, 'workspace_id');
+            return place ? [place] : [];
+        }),
+        tabs: list('tabs').flatMap((each) => {
+            const place = placeOf(each, 'tab_id');
+            const workspaceId = text(each.workspace_id);
+            return place && workspaceId ? [{ ...place, workspaceId }] : [];
+        }),
+        panes: list('panes').flatMap((each) => {
+            const paneId = text(each.pane_id);
+            const workspaceId = text(each.workspace_id);
+            const tabId = text(each.tab_id);
+            if (!paneId || !workspaceId || !tabId)
+                return [];
+            return [
+                {
+                    paneId,
+                    workspaceId,
+                    tabId,
+                    focused: each.focused === true,
+                    agent: text(each.agent),
+                    status: text(each.agent_status),
+                    tokens: tokensOf(each.tokens),
+                },
+            ];
+        }),
+    };
+}
+const ids = (value) => (value ?? '')
+    .split(',')
+    .map((each) => each.trim())
+    .filter((each) => /^req_[A-Za-z0-9-]{1,40}$/.test(each));
+const pressingRank = (pressing) => pressing ? PRESSING.indexOf(pressing) : PRESSING.length;
+export function waitingIn(snapshot) {
+    const workspaces = new Map(snapshot.workspaces.map((each) => [each.id, each]));
+    const tabs = new Map(snapshot.tabs.map((each) => [each.id, each]));
+    const found = snapshot.panes.flatMap((pane, index) => {
+        const waiting = Number.parseInt(pane.tokens[TOKENS.waiting] ?? '', 10);
+        if (!Number.isFinite(waiting) || waiting < 1)
+            return [];
+        const app = pane.tokens[TOKENS.app];
+        const pressing = pane.tokens[TOKENS.urgency];
+        const workspace = workspaces.get(pane.workspaceId);
+        const tab = tabs.get(pane.tabId);
+        const entry = {
+            paneId: pane.paneId,
+            workspaceId: pane.workspaceId,
+            tabId: pane.tabId,
+            workspace: workspace?.label ?? pane.workspaceId,
+            tab: tab?.label ?? pane.tabId,
+            app: app && APP_IDS.includes(app) ? app : null,
+            agent: pane.tokens[TOKENS.agent] ?? null,
+            herdrAgent: pane.agent,
+            status: pane.status,
+            waiting,
+            card: pane.tokens[TOKENS.card] ?? null,
+            cards: ids(pane.tokens[TOKENS.cards]),
+            pressing: pressing && PRESSING.includes(pressing)
+                ? pressing
+                : null,
+            asked: ids(pane.tokens[TOKENS.asked]),
+            order: [
+                workspace?.number ?? Number.MAX_SAFE_INTEGER,
+                tab?.number ?? Number.MAX_SAFE_INTEGER,
+                index,
+            ],
+        };
+        return [entry];
+    });
+    found.sort((a, b) => {
+        const first = pressingRank(a.pressing) - pressingRank(b.pressing);
+        if (first)
+            return first;
+        if (a.waiting !== b.waiting)
+            return b.waiting - a.waiting;
+        for (let index = 0; index < a.order.length; index++)
+            if (a.order[index] !== b.order[index])
+                return (a.order[index] ?? 0) - (b.order[index] ?? 0);
+        return 0;
+    });
+    return found.map(({ order: _order, ...waiting }) => waiting);
+}
+export async function readWaiting(socket) {
+    const result = await herdrRequest(socket, 'session.snapshot');
+    const snapshot = readSnapshot(result?.snapshot);
+    return { snapshot, waiting: waitingIn(snapshot) };
+}
+export const badgedPanes = (snapshot) => snapshot.panes.filter((pane) => Object.keys(pane.tokens).some((name) => name.startsWith('py_')));
+export function nextWaiting(waiting, focused) {
+    if (waiting.length === 0)
+        return null;
+    const at = waiting.findIndex((each) => each.paneId === focused);
+    return waiting[(at + 1) % waiting.length] ?? null;
+}

package/dist/herdr/plugin.js

@@ -0,0 +1,119 @@
+import { rm, stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import { configDir, readJson, writeWhole } from "../files.js";
+import { definedInline, tableSpans, tableValues } from "../toml.js";
+export const PLUGIN_ID = 'pendingyou.herdr';
+export function pluginPlace(io) {
+    const id = io.env.HERDR_PLUGIN_ID || PLUGIN_ID;
+    return {
+        id,
+        stateDir: io.env.HERDR_PLUGIN_STATE_DIR || join(configDir(io), 'herdr-plugin'),
+        socket: io.env.HERDR_SOCKET_PATH || null,
+    };
+}
+export function herdrConfigPath(io) {
+    if (io.env.HERDR_CONFIG_PATH)
+        return io.env.HERDR_CONFIG_PATH;
+    return join(io.env.XDG_CONFIG_HOME || join(io.home, '.config'), 'herdr', 'config.toml');
+}
+export const BLOCK_START = '# >>> Pending You for Herdr';
+export const BLOCK_END = '# <<< Pending You for Herdr';
+export const CARD_ROW = '[{ token = "$py_card", fg = "#e0a526" }]';
+export const SIDEBAR_BLOCK = `${BLOCK_START} (added by the plugin's setup; its "unconfigure" takes it out again)
+[ui.sidebar.agents]
+rows = [
+  ["state_icon", "machine", "workspace", "tab"],
+  ["agent", "state_text"],
+  ${CARD_ROW},
+]
+${BLOCK_END}
+`;
+function blockSpan(doc) {
+    const start = doc.indexOf(BLOCK_START);
+    if (start < 0 || (start > 0 && doc[start - 1] !== '\n'))
+        return null;
+    const close = doc.indexOf(BLOCK_END, start);
+    if (close < 0)
+        return null;
+    const newline = doc.indexOf('\n', close);
+    return { start, end: newline < 0 ? doc.length : newline + 1 };
+}
+export const hasBlock = (doc) => blockSpan(doc) !== null;
+export function ownSidebar(doc) {
+    const path = ['ui', 'sidebar', 'agents'];
+    const without = withoutBlock(doc);
+    return tableSpans(without, path).length > 0 || definedInline(without, path);
+}
+export function withBlock(doc) {
+    if (hasBlock(doc))
+        return doc;
+    const gap = doc === '' ? '' : doc.endsWith('\n\n') ? '' : doc.endsWith('\n') ? '\n' : '\n\n';
+    return `${doc}${gap}${SIDEBAR_BLOCK}`;
+}
+export function withoutBlock(doc) {
+    const span = blockSpan(doc);
+    if (!span)
+        return doc;
+    let before = doc.slice(0, span.start);
+    const after = doc.slice(span.end);
+    if (after === '' && before.endsWith('\n\n'))
+        before = before.slice(0, -1);
+    return before + after;
+}
+export function toastDelivery(doc) {
+    if (definedInline(doc, ['ui', 'toast']))
+        return 'unknown';
+    const delivery = tableValues(doc, ['ui', 'toast']).delivery;
+    if (delivery === undefined)
+        return 'off';
+    return typeof delivery === 'string' ? delivery : 'unknown';
+}
+export const TOAST_SNIPPET = `[ui.toast]
+delivery = "herdr"
+`;
+export const KEYS_SNIPPET = `[[keys.command]]
+key = "prefix+y"
+type = "plugin_action"
+command = "${PLUGIN_ID}.open"
+description = "Pending You: what's waiting on you"
+
+[[keys.command]]
+key = "prefix+shift+y"
+type = "plugin_action"
+command = "${PLUGIN_ID}.next"
+description = "Pending You: next pane waiting on you"
+`;
+export function agentView(pluginId) {
+    return {
+        source: `plugin:${pluginId}`,
+        label: 'waiting on you',
+        filter: {
+            op: 'any',
+            filters: [
+                { op: 'exists', field: { token: 'py_waiting' } },
+                { op: 'eq', field: 'status', value: 'blocked' },
+            ],
+        },
+        sort: [
+            { field: { token: 'py_urgency' }, order: 'asc' },
+            { field: 'attention', order: 'desc' },
+            { field: 'state_change_seq', order: 'desc' },
+        ],
+    };
+}
+const settingsPath = (place) => join(place.stateDir, 'settings.json');
+export async function viewOn(place) {
+    const settings = await readJson(settingsPath(place)).catch(() => null);
+    return settings?.view === true;
+}
+export async function saveView(place, on) {
+    await writeWhole(settingsPath(place), `${JSON.stringify({ version: 1, view: on }, null, 2)}\n`);
+}
+const offPath = (place) => join(place.stateDir, 'off');
+export const pluginOff = (place) => stat(offPath(place)).then(() => true, () => false);
+export async function setPluginOff(place, off) {
+    if (off)
+        await writeWhole(offPath(place), 'Pending You is off in Herdr: its setup turns it on.\n');
+    else
+        await rm(offPath(place), { force: true });
+}