@ethlete/agent-rules 0.1.0-next.27 → 0.1.0-next.28

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # @ethlete/agent-rules
 
+## 0.1.0-next.28
+
+### Minor Changes
+
+- New `mods` config key: `sync` turns on Claude Code mods that the package ships, starting with `e2e-progress`, a live Playwright run progress in the status line.
+- Add the consumer skill `e2e-triage`: read the failures file of the `@ethlete/cli` failure reporter, group the failures by error, fix the largest group first, and re-run only the failed spec files.
+- Add the `agent-sessions` skill and `ethlete-agents sessions`: agents in one checkout run in `tmux`, message each other, claim paths, and restart a session with a prompt. The `handoff` skill uses it to clear and resume.
+
+### Patch Changes
+
+- `agent-sessions restart` refuses a session the caller does not run in, and the handoff skill says how to read the own session name.
+- The `claude` and `codex` shell functions no longer switch your tmux client when a script or a one-shot flag such as `--version` calls them.
+- `agent-sessions run` starts `<name>-2`, `<name>-3` and so on when the session already has a terminal attached, so a second `claude` terminal gets its own agent.
+- The e2e-triage skill treats connection-refused groups on a local mock as infrastructure, and the e2e-progress mod shows the failure `detail`.
+- The handoff skill counts an open item as the next task, so an agent in tmux restarts itself with it instead of handing the prompt to the user.
+- A handoff self-restart now resumes with the installed skill name and keeps both the restart reason and the text after the slug.
+- In an agent-sessions tmux session, the context-warning hook tells the agent to save and restart itself, not to ask the user for `/clear`.
+- The `sdk-update` skill warns that after Angular 22, `a?.b` gives `undefined`, not `null`, which breaks pipes that treat the two differently.
+- Shorten the mailbox wake-up prompt: it runs `npx ethlete-agents sessions inbox <name>` or the `agents:sessions` script when one exists, and the full script path otherwise.
+- `et design shot --variants` takes `--round <key>` and `--variant <name>` to draw only the current round next to the merged row.
+- Reject and reopen single sketch variants with `et design sketch reject|reopen` or in Studio; a rejected variant keeps its reason, origin and history and can no longer be picked or merged.
+- The `agent-sessions` dispatcher waits when the prompt of an agent holds typed text or an open menu, and sends the wake-up line after the text is sent or cleared.
+
 ## 0.1.0-next.27
 
 ### Minor Changes

package/content/hooks/context-warning.py

@@ -93,6 +93,7 @@ a tool batch or the end of a turn.
 import json
 import os
 import re
+import subprocess
 import sys
 import tempfile
 
@@ -255,11 +256,39 @@ def handoff_skill(root):
     return "ethlete-handoff"
 
 
-def resolve_profile(profile, skill):
+SELF_RESTART = (
+    "you run in an agent-sessions tmux session, so do not hand this step to the user: apply the {handoff} skill's save "
+    "test, save if it calls for a file, then follow its 'Clear and resume on your own' section "
+    "and restart this session yourself with the agent-sessions `restart` command - with no file, "
+    "restart with a prompt that names the next step"
+)
+USER_DIRECTED_KEYS = ("recommend", "suggest", "save_now", "save_at_stop")
+
+
+def can_self_restart(root):
+    """True only in a tmux session the agent-sessions `restart` command can find and drive."""
+    if not os.environ.get("TMUX") or not root:
+        return False
+    if not any(
+        os.path.isfile(os.path.join(root, ".agents/skills", name, "agent-sessions.mjs"))
+        for name in ("ethlete-agent-sessions", "agent-sessions")
+    ):
+        return False
+    try:
+        session = subprocess.run(
+            ["tmux", "display-message", "-p", "#S"], capture_output=True, text=True, timeout=2
+        ).stdout.strip()
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return session.endswith("@" + re.sub(r"[.:]", "-", os.path.basename(os.path.normpath(root))))
+
+
+def resolve_profile(profile, skill, self_restart=False):
     """Fills the installed handoff skill's name into a profile's message fragments."""
+    resolved = {**profile, **{key: SELF_RESTART for key in USER_DIRECTED_KEYS}} if self_restart else profile
     return {
         key: value.replace("{handoff}", skill) if isinstance(value, str) else value
-        for key, value in profile.items()
+        for key, value in resolved.items()
     }
 
 
@@ -821,7 +850,7 @@ def main():
     if disabled_locally(local_config):
         return
 
-    profile = resolve_profile(profile, handoff_skill(root))
+    profile = resolve_profile(profile, handoff_skill(root), self_restart=can_self_restart(root))
 
     claude_subagent = agent == "claude" and bool(data.get("agent_id"))
     if claude_subagent:

package/content/mods/.claude-plugin/marketplace.json

@@ -0,0 +1,11 @@
+{
+  "name": "ethlete",
+  "owner": { "name": "ethlete" },
+  "plugins": [
+    {
+      "name": "e2e-progress",
+      "source": "./plugins/e2e-progress",
+      "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane"
+    }
+  ]
+}

package/content/mods/plugins/e2e-progress/.claude-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "e2e-progress",
+  "version": "0.1.0-next.28",
+  "description": "Live Playwright e2e progress from a run log, as a status line entry and a pane",
+  "types": "./types/index.d.ts"
+}

package/content/mods/plugins/e2e-progress/hooks/hooks.json

@@ -0,0 +1 @@
+{ "modules": ["./register.tsx"] }

package/content/mods/plugins/e2e-progress/hooks/register.tsx

@@ -0,0 +1,442 @@
+import { atom, read, update } from 'claude-code';
+import type { EngineInterface, Register, Timer } from 'claude-code';
+
+import type { Progress } from '../types';
+
+const PANE = 'e2e-progress';
+const HANDOFFS = ['.claude/handoffs', '.agents/handoffs'];
+const WORKTREES = '.claude/worktrees';
+const TICK_MS = 5000;
+const STALE_MS = 15_000;
+const HIDE_AFTER_MS = 60_000;
+const MIN_ETA_TESTS = 5;
+const MIN_ETA_MS = 30_000;
+const MAX_CANDIDATES = 12;
+const STALLED_MS = 15 * 60_000;
+const runs = atom({ plugin: 'e2e-progress', key: 'runs' } as const, []);
+const pinnedPath = atom({ plugin: 'e2e-progress', key: 'path' } as const, null);
+
+const count = (text: string, re: RegExp) => (text.match(re) ?? []).length;
+const summary = (text: string, word: string) => {
+  const hit = text.match(new RegExp(`^\\s+(\\d+) ${word}\\b`, 'm'));
+  return hit ? Number(hit[1]) : undefined;
+};
+
+const doneOf = (p: Progress) => p.passed + p.failed + p.skipped;
+
+const FAIL_LINE = /✘\s+\d+\s+\[[^\]]+\]\s+›\s+(\S+?):(\d+):\d+\s+›\s+(.*)$/;
+const TEST_DECLARATION = /\btest(\.\w+)?\(/;
+const indentOf = (line: string) => line.length - line.trimStart().length;
+
+const titleOf = (rest: string) =>
+  (
+    rest
+      .replace(/\s+@\S+.*$/, '')
+      .replace(/\s+\([\d.]+m?s\)$/, '')
+      .split(' › ')
+      .pop() ?? ''
+  ).trim();
+
+const declaresAt = (source: string[], index: number, title: string) => {
+  if (!TEST_DECLARATION.test(source[index] ?? '')) return false;
+  const head = source.slice(index, index + 3).join('\n');
+  return head.includes(title.slice(0, 25)) || head.includes('`');
+};
+
+const callsTestFail = (source: string[], index: number) => {
+  const declaration = source[index] ?? '';
+  if (/\btest\.fail\(/.test(declaration)) return true;
+  const indent = indentOf(declaration);
+  for (const line of source.slice(index + 1)) {
+    if (line.trim() !== '' && indentOf(line) <= indent && !/=>\s*\{\s*$/.test(line)) return false;
+    if (/\btest\.fail\(/.test(line)) return true;
+  }
+  return false;
+};
+
+const sourceCache = new Map<string, string[] | null>();
+
+async function sourceOf($: EngineInterface, path: string) {
+  if (!sourceCache.has(path))
+    sourceCache.set(
+      path,
+      await $.fs.read(path).then(
+        (t) => t.split('\n'),
+        () => null,
+      ),
+    );
+  return sourceCache.get(path) ?? null;
+}
+
+async function rootsFor($: EngineInterface, logPath: string) {
+  const at = Math.max(...HANDOFFS.map((dir) => logPath.indexOf(dir)));
+  const own = at > 0 ? logPath.slice(0, at) : '';
+  const worktrees = await $.fs.list(WORKTREES).catch(() => []);
+  const all = [own, '', ...worktrees.filter((d) => d.kind === 'dir').map((d) => `${WORKTREES}/${d.name}/`)];
+  return [...new Set(all)];
+}
+
+async function expectedFailures($: EngineInterface, logPath: string, text: string) {
+  const expected = new Set<string>();
+  const failLines = text.split('\n').filter((line) => FAIL_LINE.test(line));
+  if (failLines.length === 0) return expected;
+  const roots = await rootsFor($, logPath);
+  for (const line of failLines) {
+    const [, file = '', lineNo = '0', rest = ''] = line.match(FAIL_LINE) ?? [];
+    const index = Number(lineNo) - 1;
+    const title = titleOf(rest);
+    for (const root of roots) {
+      const source = await sourceOf($, `${root}${file}`);
+      if (source === null || !declaresAt(source, index, title)) continue;
+      if (callsTestFail(source, index)) expected.add(line);
+      break;
+    }
+  }
+  return expected;
+}
+
+const parse = (
+  path: string,
+  text: string,
+  expected: Set<string>,
+  mtimeMs: number,
+  nowMs: number,
+  last: Progress | null,
+): Progress => {
+  const isDone = /^\s+\d+ (passed|failed|did not run)\b/m.test(text) || /^EXIT \d+/m.test(text);
+  const lines = text.split('\n');
+  const listFailures = lines
+    .filter((line) => line.includes('✘') && !expected.has(line))
+    .map((line) => line.replace(/^.*?✘\s+\d+\s+\[[^\]]+\]\s+›\s+/, '').replace(/\s+@\S+.*$/, ''));
+  const lineFailures = new Map<string, string>();
+  for (const line of lines) {
+    const hit = line.match(/^\s+(\d+)\) \[[^\]]+\] › (.*)$/);
+    if (hit?.[1] && hit[2]) lineFailures.set(hit[1], hit[2].replace(/\s+@\S+.*$/, '').replace(/\s*─+\s*$/, ''));
+  }
+  const failures = isDone && lineFailures.size > 0 ? [...lineFailures.values()] : listFailures;
+  const started = Math.max(0, ...[...text.matchAll(/^\[(\d+)\/\d+\]/gm)].map((m) => Number(m[1])));
+  const ticks = count(text, /✓/g);
+  const p = {
+    path,
+    total: Number(text.match(/Running (\d+) tests?/)?.[1] ?? 0),
+    passed: summary(text, 'passed') ?? (ticks > 0 ? ticks + expected.size : Math.max(0, started - failures.length)),
+    failed: summary(text, 'failed') ?? failures.length,
+    skipped: summary(text, 'skipped') ?? (ticks > 0 ? count(text, /^\s+-\s+\d+\s/gm) : 0),
+    flaky: summary(text, 'flaky') ?? 0,
+    didNotRun: summary(text, 'did not run') ?? 0,
+    workers: Number(text.match(/Running \d+ tests? using (\d+) workers?/)?.[1] ?? 1),
+    duration: text.match(/^\s+\d+ passed \(([^)]+)\)/m)?.[1],
+    expected: expected.size,
+    isDone,
+    failures,
+    mtimeMs,
+    firstSeenMs: nowMs,
+    firstDone: 0,
+  };
+  const isSameRun =
+    last !== null &&
+    last.path === path &&
+    !last.isDone &&
+    Number.isFinite(last.firstSeenMs) &&
+    Number.isFinite(last.firstDone) &&
+    doneOf(p) >= last.firstDone;
+  return isSameRun
+    ? { ...p, firstSeenMs: last.firstSeenMs, firstDone: last.firstDone }
+    : { ...p, firstDone: doneOf(p) };
+};
+
+const FAILURES_FILE_LINE = /^\[failure-reporter\] Writing failures to (.+)$/m;
+
+type FailureRecord = { test: string; location: string; error?: string; detail?: string | null };
+
+const recordsOf = (text: string): FailureRecord[] =>
+  text.split('\n').flatMap((line) => {
+    if (line.trim() === '') return [];
+    try {
+      const record = JSON.parse(line);
+      return typeof record?.test === 'string' && typeof record?.location === 'string' ? [record] : [];
+    } catch {
+      return [];
+    }
+  });
+
+const firstErrorLine = (error: string | undefined) =>
+  (error ?? '')
+    .split('\n')
+    .find((line) => line.trim() !== '')
+    ?.replace(/^Error:\s*/, '')
+    .trim() ?? '';
+
+const failuresOf = (records: FailureRecord[]) => {
+  const latest = new Map<string, FailureRecord>();
+  for (const record of records) latest.set(`${record.location} › ${record.test}`, record);
+  return [...latest].map(([key, record]) => {
+    const error = firstErrorLine(record.error);
+    const line = error ? `${key} — ${error}` : key;
+    return record.detail ? `${line} (${record.detail})` : line;
+  });
+};
+
+async function withRecords($: EngineInterface, p: Progress, text: string): Promise<Progress> {
+  const file = text.match(FAILURES_FILE_LINE)?.[1]?.trim();
+  if (!file) return p;
+  const records = await $.fs.read(file).then(recordsOf, () => undefined);
+  if (records === undefined) return p;
+  const failures = failuresOf(records);
+  return { ...p, failures, failed: summary(text, 'failed') ?? failures.length };
+}
+
+const remainingMs = (p: Progress, nowMs: number) => {
+  const doneSince = doneOf(p) - p.firstDone;
+  const elapsed = nowMs - p.firstSeenMs;
+  if (p.isDone || doneSince < MIN_ETA_TESTS || elapsed < MIN_ETA_MS) return undefined;
+  return ((p.total - doneOf(p)) / doneSince) * elapsed;
+};
+
+const formatEta = (ms: number | undefined) => {
+  if (ms === undefined) return '';
+  const minutes = Math.round(ms / 60_000);
+  return minutes < 1 ? ' ~<1m left' : ` ~${minutes}m left`;
+};
+
+type LogFile = { path: string; mtimeMs: number };
+
+async function logsUnder($: EngineInterface, dir: string, depth: number): Promise<LogFile[]> {
+  const entries = await $.fs.list(dir).catch(() => []);
+  const files = entries
+    .filter((f) => f.kind === 'file' && f.name.endsWith('.log'))
+    .map((f) => ({ path: `${dir}/${f.name}`, mtimeMs: f.mtimeMs }));
+  if (depth === 0) return files;
+  const nested = await Promise.all(
+    entries.filter((d) => d.kind === 'dir').map((d) => logsUnder($, `${dir}/${d.name}`, depth - 1)),
+  );
+  return [...files, ...nested.flat()];
+}
+
+async function baseDirs($: EngineInterface) {
+  const bases = new Set([await $.session.root()]);
+  let dir = await $.session.cwd();
+  for (let up = 0; up <= 3 && dir !== ''; up++) {
+    bases.add(dir);
+    dir = dir.slice(0, dir.lastIndexOf('/'));
+  }
+  return [...bases];
+}
+
+async function handoffDirs($: EngineInterface) {
+  const perBase = await Promise.all(
+    (await baseDirs($)).map(async (base) => {
+      const worktrees = await $.fs.list(`${base}/${WORKTREES}`).catch(() => []);
+      const roots = [base, ...worktrees.filter((d) => d.kind === 'dir').map((d) => `${base}/${WORKTREES}/${d.name}`)];
+      return roots.flatMap((root) => HANDOFFS.map((dir) => `${root}/${dir}`));
+    }),
+  );
+  return perBase.flat();
+}
+
+const nameOf = (path: string) => (path.split('/').pop() ?? path).replace(/\.log$/, '');
+
+const isRunLog = (text: string) => /^Running \d+ tests?/m.test(text);
+
+const notRunLogs = new Map<string, number>();
+
+async function candidateLogs($: EngineInterface) {
+  const perDir = await Promise.all((await handoffDirs($)).map((dir) => logsUnder($, dir, 2)));
+  const unique = new Map(perDir.flat().map((log) => [log.path, log]));
+  return [...unique.values()].sort((a, b) => b.mtimeMs - a.mtimeMs).slice(0, MAX_CANDIDATES);
+}
+
+async function newestLog($: EngineInterface) {
+  for (const log of await candidateLogs($)) {
+    if (isRunLog(await $.fs.read(log.path).catch(() => ''))) return log;
+  }
+  return undefined;
+}
+
+async function pinnedLog($: EngineInterface): Promise<LogFile | undefined> {
+  const pinned = await read($, pinnedPath);
+  if (pinned === null) return undefined;
+  const stat = await $.fs.stat(pinned).catch(() => undefined);
+  const newest = await newestLog($);
+  if (newest !== undefined && newest.path !== pinned && (stat === undefined || newest.mtimeMs > stat.mtimeMs)) {
+    await update($, pinnedPath, () => null);
+    return undefined;
+  }
+  return stat === undefined ? undefined : { path: pinned, mtimeMs: stat.mtimeMs };
+}
+
+const isVisible = (p: Progress, nowMs: number) =>
+  p.isDone ? nowMs - p.mtimeMs <= HIDE_AFTER_MS : nowMs - p.mtimeMs <= STALLED_MS;
+
+let isHidden = false;
+let timer: Timer | undefined;
+let lastTickMs = 0;
+let shownStatus: string | undefined | null = null;
+
+function setStatus($: EngineInterface, text: string | undefined) {
+  if (text === shownStatus) return;
+  shownStatus = text;
+  $.ui.status(text);
+}
+
+const statusOf = (p: Progress, nowMs: number) =>
+  `${nameOf(p.path)} w${p.workers} ${p.isDone ? `done ${p.duration ?? ''}`.trim() : `${doneOf(p)}/${p.total}`} ✓${p.passed} ✘${p.failed}` +
+  `${p.flaky ? ` ~${p.flaky}` : ''}${p.skipped ? ` -${p.skipped}` : ''}${p.didNotRun ? ` ⊘${p.didNotRun}` : ''}${formatEta(remainingMs(p, nowMs))}`;
+
+async function tick($: EngineInterface) {
+  const nowMs = await $.clock.now();
+  const pinned = await pinnedLog($);
+  const logs = pinned ? [pinned] : await candidateLogs($);
+  const last = new Map((await read($, runs)).map((p) => [p.path, p]));
+  const next: Progress[] = [];
+  for (const log of logs) {
+    const previous = last.get(log.path);
+    if (previous?.mtimeMs === log.mtimeMs) {
+      next.push(previous);
+      continue;
+    }
+    if (notRunLogs.get(log.path) === log.mtimeMs) continue;
+    const text = await $.fs.read(log.path).catch(() => '');
+    if (!isRunLog(text)) {
+      notRunLogs.set(log.path, log.mtimeMs);
+      continue;
+    }
+    sourceCache.clear();
+    const parsed = parse(
+      log.path,
+      text,
+      await expectedFailures($, log.path, text),
+      log.mtimeMs,
+      nowMs,
+      previous ?? null,
+    );
+    next.push(await withRecords($, parsed, text));
+  }
+  const visible = next.filter((p) => isVisible(p, nowMs)).sort((a, b) => a.path.localeCompare(b.path));
+  await update($, runs, () => visible);
+
+  if (visible.length === 0) {
+    setStatus($, undefined);
+    if (!isHidden) {
+      isHidden = true;
+      await $.ui.close({ id: PANE }).catch(() => undefined);
+    }
+    return;
+  }
+
+  isHidden = false;
+  setStatus($, `e2e ${visible.map((p) => statusOf(p, nowMs)).join('  │  ')}`);
+}
+
+async function run($: EngineInterface) {
+  lastTickMs = await $.clock.now();
+  try {
+    await tick($);
+  } catch (error) {
+    setStatus($, `e2e-progress failed: ${String(error)}`);
+  }
+}
+
+function start($: EngineInterface) {
+  timer?.cancel();
+  timer = $.clock.every(TICK_MS, () => run($));
+}
+
+async function revive($: EngineInterface) {
+  if ((await $.clock.now()) - lastTickMs < STALE_MS) return;
+  start($);
+  await run($);
+}
+
+export const register: Register = (on) => {
+  on('session.start', async ($, e, next) => {
+    await $.command.register({
+      name: 'e2e',
+      description:
+        'Show e2e run progress. Optional arg: a log path to pin; "auto" removes the pin; "off" clears the status',
+    });
+    start($);
+    return next(e);
+  });
+
+  on('prompt.submit', async ($, e, next) => {
+    await revive($);
+    return next(e);
+  });
+
+  on('tool.call', async ($, e, next) => {
+    await revive($);
+    return next(e);
+  });
+
+  on('turn.complete', async ($, e, next) => {
+    await revive($);
+    return next(e);
+  });
+
+  on('command.run', { command: 'e2e' }, async ($, e) => {
+    const arg = e.args.trim();
+    if (arg === 'off') {
+      setStatus($, undefined);
+      return { text: 'e2e status cleared until the log changes.' };
+    }
+    if (arg === 'auto') {
+      await update($, pinnedPath, () => null);
+      start($);
+      await run($);
+      return { text: `Pin removed. Watching the newest logs under ${HANDOFFS.join(' and ')}.` };
+    }
+    if (arg !== '') await update($, pinnedPath, () => arg);
+    start($);
+    await $.ui.open({ id: PANE, title: 'E2E progress' });
+    return { text: arg ? `Watching ${arg}.` : 'E2E progress pane opened.' };
+  });
+
+  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
+    const { Box, Text } = $.ui.resolve(e);
+    const shown = await read($, runs);
+    if (shown.length === 0)
+      return (
+        <Text dimColor>
+          No active run log under {HANDOFFS.join(' or ')}, also in {WORKTREES}/*.
+        </Text>
+      );
+
+    const nowMs = await $.clock.now();
+    const room = Math.max(1, Math.floor(((e.viewport?.rows ?? 24) - 6 * shown.length) / shown.length));
+    return (
+      <Box flexDirection="column">
+        {shown.map((p) => {
+          const done = doneOf(p);
+          return (
+            <Box flexDirection="column" marginBottom={1}>
+              <Text bold>
+                {nameOf(p.path)} <Text dimColor>· {p.workers} workers</Text>
+              </Text>
+              <Text dimColor wrap="truncate-start">
+                {p.path}
+              </Text>
+              <Text>
+                {p.isDone ? `finished in ${p.duration ?? '?'}` : `${done} / ${p.total}`}
+                {p.total > 0 && !p.isDone ? ` (${Math.round((done / p.total) * 100)}%)` : ''}
+                {formatEta(remainingMs(p, nowMs))}
+              </Text>
+              <Text>
+                <Text color="green">✓ {p.passed}</Text> <Text color="red">✘ {p.failed}</Text>{' '}
+                <Text dimColor>- {p.skipped} skipped</Text>
+                {p.didNotRun > 0 ? <Text color="yellow"> ⊘ {p.didNotRun} did not run</Text> : ''}
+                {p.flaky > 0 ? <Text color="yellow"> ~ {p.flaky} flaky</Text> : ''}
+              </Text>
+              {p.expected > 0 && <Text dimColor>{p.expected} expected failures (test.fail) counted as passed</Text>}
+              {p.failures.slice(-room).map((f) => (
+                <Text color="red" wrap="truncate-end">
+                  ✘ {f}
+                </Text>
+              ))}
+            </Box>
+          );
+        })}
+      </Box>
+    );
+  });
+};

package/content/mods/plugins/e2e-progress/tsconfig.json

@@ -0,0 +1,3 @@
+{
+  "extends": "./.claude-plugin/types/tsconfig.json"
+}

package/content/mods/plugins/e2e-progress/types/index.d.ts

@@ -0,0 +1,23 @@
+export type Progress = {
+  path: string;
+  total: number;
+  passed: number;
+  failed: number;
+  skipped: number;
+  flaky: number;
+  didNotRun: number;
+  workers: number;
+  duration: string | undefined;
+  expected: number;
+  isDone: boolean;
+  failures: string[];
+  mtimeMs: number;
+  firstSeenMs: number;
+  firstDone: number;
+};
+
+declare module 'claude-code' {
+  interface PluginState {
+    'e2e-progress': { runs: Progress[]; path: string | null };
+  }
+}

package/content/rules/agent-sessions-wake-up.md

@@ -0,0 +1,11 @@
+---
+name: agent-sessions-wake-up
+description: A prompt that says "New mailbox message for <name>" means run the inbox command in it and act on the result; read the agent-sessions skill before you edit a file another agent may edit.
+kind: rule
+scope: both
+---
+
+## Agent sessions
+
+If a prompt says `New mailbox message for <name>`, run the `inbox` command in that prompt and act on
+the messages. Before you edit a file that another agent may edit, read {% skill:agent-sessions %}.

package/content/skills/agent-sessions/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: agent-sessions
+description: Run agents in tmux sessions of one checkout, message them, wake idle ones, restart a session with a prompt, and claim paths so two agents do not overwrite each other. Read before you edit a shared file while another agent may be active, and when the user says "mailbox", "coordinate with the other agent", "claim a file", "hand off to the other agent", or "restart the session".
+kind: skill
+scope: both
+---
+
+# Agent sessions
+
+One script, {%resource:agent-sessions.mjs%}, does three jobs for the agents of one checkout:
+
+- **Sessions.** It runs each agent in a `tmux` session, and it can clear a session and start it with a prompt.
+- **Messages.** Agents send each other messages through an append-only JSON-lines file, the mailbox. A dispatcher wakes an idle agent.
+- **Claims.** An agent announces the paths it edits, so two agents do not overwrite each other.
+
+Below, `<skill-dir>` is the directory this file sits in, and `<name>` is your own sender name. Where
+the `ethlete-agents` package is a dependency, `npx ethlete-agents sessions <command>` runs the same
+script, so you do not need `<skill-dir>`. The older name `npx ethlete-agents mailbox` works too.
+
+```bash
+node <skill-dir>/agent-sessions.mjs run <name> <command...>
+node <skill-dir>/agent-sessions.mjs up <name>[=<command>]...
+node <skill-dir>/agent-sessions.mjs restart <name> [--after <seconds>] <prompt...>
+node <skill-dir>/agent-sessions.mjs down [<name>...]
+node <skill-dir>/agent-sessions.mjs shell-install [<agent>...] [--file <path>] [--remove] [--dry-run]
+node <skill-dir>/agent-sessions.mjs shell-init [<agent>...]
+node <skill-dir>/agent-sessions.mjs send <name> [--to <agent>] '<message>'
+node <skill-dir>/agent-sessions.mjs inbox <name> [--wait <seconds>]
+node <skill-dir>/agent-sessions.mjs read [--last <n>] [--all]
+node <skill-dir>/agent-sessions.mjs watch <name>
+node <skill-dir>/agent-sessions.mjs dispatch
+node <skill-dir>/agent-sessions.mjs claim <name> <path...> [--ttl <hours>] [--force]
+node <skill-dir>/agent-sessions.mjs release <name> [path...]
+node <skill-dir>/agent-sessions.mjs claims
+```
+
+## Quick start for a person
+
+Nothing runs until you start it, so a person who does not use this does nothing. To try it:
+
+1. Run `node <skill-dir>/agent-sessions.mjs shell-install`. It adds one function per agent to your shell file.
+2. Open a new terminal. In the repo, type `claude` or `codex` as usual. The function starts the agent in a `tmux` session and starts the dispatcher.
+3. Ask one agent to message the other. An idle agent wakes when a message carries `--to <agent>`.
+4. Run `node <skill-dir>/agent-sessions.mjs down` to stop the dispatcher. Run `shell-install --remove` to undo step 1.
+
+## Sessions
+
+`run <name> <command...>` starts the command in the `tmux` session `<name>@<repo>`, or attaches if it runs already. It also starts the dispatcher when none runs. Session names carry the repo name, so `codex` in two repos never collides. If that session has a terminal attached already, `run` starts `<name>-2`, then `<name>-3`, and so on. A detached session is attached again. So a second `claude` terminal gets its own agent.
+
+`up codex=codex gemini=gemini` starts a detached `tmux` session per agent, named like its sender name, and runs the command in it. It also starts a session named `mailbox-dispatch` that runs `dispatch`. A running session is left alone. Attach to a session with `tmux attach -t <name>`. Detach with `Ctrl-b`, then `d`. The session and its agent keep running. Use `down` to stop the dispatcher and the named sessions.
+
+`restart <name> <prompt...>` types the clear command (`/clear`, or `/new` for a `codex` name) and then the prompt into the session `<name>@<repo>` after `--after` seconds (default 5). The command returns at once, so end your turn after it. An agent uses it to clear itself and resume from its saved work state. It refuses any session other than the caller's own (from `$TMUX_PANE`), and the error names the caller's own sender name. Background commands of the old session still report into the new one.
+
+`shell-install` writes one shell function per agent into `~/.zshrc` or `~/.bashrc`, between two marker lines. A second run replaces the block, and `--remove` deletes it. Use `--file` for another startup file and `--dry-run` to preview. After a new terminal opens, typing `claude` or `codex` in a repo with this skill runs the agent through `run`. Elsewhere the function starts the plain command. Run `shell-install` only when the user asks: it changes a file the user owns. `shell-init` prints the same functions without writing a file.
+
+Choose a `<name>` that no other agent uses, for example `agent-a` or `agent-b`. Two sessions with one name look like one agent.
+
+## Messages
+
+The mailbox file is `.ethlete/mailbox.jsonl` in the git root. The first write also creates `.ethlete/.gitignore`, so the file stays out of git. Set `AGENT_MAILBOX` to use another path. For two Claude Code sessions, the `SendMessage` tool is the better channel. The mailbox is for agents that cannot reach each other directly.
+
+An idle agent cannot read the mailbox. One `dispatch` process outside every agent fixes this. It polls the mailbox for free. When a message carries `--to <agent>`, it waits a short grace period and then, if the agent has not read the message, types a wake-up line into the `tmux` session `<agent>@<repo>`, or a session named only `<agent>`. The agent then runs `inbox` and acts. A message without `--to` wakes nobody.
+
+If the prompt of the agent holds typed text, the dispatcher waits until that text is sent or cleared. It checks again every 2 seconds. An open menu, for example a permission dialog, also makes it wait. If the agent is in the middle of a turn, the wake-up line waits as its next prompt. An agent in a `tmux` session does not need the `--wait` loop, which costs a turn at every timeout. If you wait for an answer in a session without `tmux`, run `inbox <name> --wait 120`: it blocks until a message arrives or 120 seconds pass. If it prints "No new messages.", run it again. A background `--wait` ends after one message, so it is not a lasting watch.
+
+- `inbox` keeps one cursor per sender name, so it never repeats a message. The first call shows the last 20.
+- `read` shows the last 20 messages. Use `--all` for the full history.
+- `send` with no message reads it from standard input, so a long message needs no shell quoting.
+- `watch` is optional. It runs until you stop it. In Claude Code, start it with the `Monitor` tool, so a new message wakes the session. Without such a feature, rely on `inbox`.
+- Never rewrite or truncate the file. Only the script appends to it.
+- Keep credentials and personal data out of the mailbox.
+
+## Claims
+
+1. At the start of a task, run `claims` and `inbox`. They show what other agents hold and said.
+2. Before you edit a file, run `claim` with the exact paths. A directory path claims everything below it. `claim` also prints the messages you have not seen yet.
+3. If `claim` reports a conflict, do not edit. Run `send` to ask the holder for a handoff, then wait.
+4. After each larger step, run `inbox` again. Most agents cannot wake on new output, so you must pull messages yourself.
+5. When you finish, run `release`. A claim also expires after 4 hours, or after `--ttl` hours.
+
+A claim is advisory, not a lock. `--force` claims over another agent: use it only after the holder agreed. Silence is not approval. Acknowledge each handoff in words. No agent starts automatically. The user starts each one.