feat(operator): report each operator row outcome back to the agent that queued it

operator.py stores the adding session's name and id with the row. Done,
cancel and failure go to that stored name and pinned session id, never
re-resolved: a radio post by default, a call when that session picked it
with radio.py feedback set call. The caller's own parts are dropped. The
hub counts unanswered calls per session id.

MEDUSA: 34 findings accepted after an independent review, 0 true
positives: 3x CGS-SCAN-029 by design (operator-confirmed runner in
operator.py execute and its call), 2x CGS-SCAN-030 (exec inside the name
execute), CODEGEN-SCAN-003 and CGS-SCAN-028 (open inside Popen),
3x CGS-SCAN-040 (prompt loops end), 4x GENAI-SCAN-1270 (rasci.database()
JSON register), 20x FLA-SCAN-055 (dba inside the word feedback).

🎯 Fix: 93 %
💥 Break: 4 %
💸 Cost: 100 %
⏱️ Time: 100 %
🛡️ Security: 100 %
🏆 Score: 89
🚦 Gate: ✅ 90/5, cost and time <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Kevin Veen-BirkenbachandClaude Opus 5.5 committed 2026-11-13 06:42:51 +00:00
1 parent 3418738993
commit 7d70e07b4c
14 files changed
+833 -95

No files matched your search

+21 -2
View File
@@ -14,6 +14,7 @@ CONSOLE = ("id", "status", "code", "output", "created_ts", "started", "finished"
TASK_JOB = "task"
GATE_JOB = "gate"
CHANGES = (TASK_JOB, GATE_JOB)
USAGE = 2
def runner_job(job: dict) -> dict:
@@ -92,9 +93,27 @@ class Jobs:
job, changed = self.jobs.transition(job_id, "running", {"status": status, "code": code, "output": output, "finished": time.time()})
if not changed:
raise Conflict({"id": job_id, "status": job["status"]})
command_done = status == "done" and job.get("kind") not in CHANGES
runs = [self.scripts.run(OPERATOR_SCRIPT, ["done", job["task"].removeprefix(OPERATOR)])] if command_done else []
runs = self.close_row(job, status, code)
tail = "\n".join(output.splitlines()[-20:])
self.log.add({"kind": "run", "title": f"{status}: {job['command'][:200]}", "text": tail, "ref": {"job": job_id, "task": job["task"], "code": code, "status": status}})
told = self.tell_applied(job) if job.get("kind") == TASK_JOB else []
return {"id": job_id, "status": status, "code": code, "runs": runs, "told": told}
def close_row(self, job: dict, status: str, code: int | None) -> list[dict]:
"""Returns:
The operator.py runs that report the end of an operator command
job on its row: `ran` on exit 0, then an older operator.py's
`done` when `ran` is its usage error; `failed` on any other exit;
none for a refused job or a task or gate change.
"""
if job.get("kind") in CHANGES or status not in ("done", "failed"):
return []
slug = job["task"].removeprefix(OPERATOR)
shown = [slug, f"--command={job['command']}", f"--dir={job['directory']}"]
if status == "failed":
why = f"killed by signal {-code}" if code < 0 else f"exit {code}"
return [self.scripts.run(OPERATOR_SCRIPT, ["failed", *shown, "--why", why])]
runs = [self.scripts.run(OPERATOR_SCRIPT, ["ran", *shown])]
if runs[0]["code"] == USAGE:
runs.append(self.scripts.run(OPERATOR_SCRIPT, ["done", slug]))
return runs
+9 -3
View File
@@ -33,15 +33,21 @@ def read_snapshot(path: Path, now: float) -> dict[str, dict]:
def unanswered(news: list[dict], now: float) -> list[tuple[str, float]]:
"""Returns:
(callee name, call time) of every call older than UNANSWERED that its
callee never receipted.
(callee, call time) of every call older than UNANSWERED without a
receipt: one per session id in `to_sessions`, answered by any
receipt of that call; else one per name in `to`.
"""
receipts = {(agent(row.get("from")), round(epoch(row.get("call")) or 0, 3)) for row in news if row.get("class") == "receipt"}
answered = {call for _, call in receipts}
late = []
for row in news:
ts = epoch(row.get("ts"))
if row.get("class") != "call" or ts is None or now - ts < UNANSWERED or not isinstance(row.get("to"), list):
continue
sessions = [sid for sid in row["to_sessions"] if isinstance(sid, str)] if isinstance(row.get("to_sessions"), list) else []
if sessions:
late += [(sid, ts) for sid in sessions if round(ts, 3) not in answered]
continue
late += [(name, ts) for name in map(agent, row["to"]) if name and (name, round(ts, 3)) not in receipts]
return late
@@ -75,7 +81,7 @@ def presence(sessions: dict[str, dict], parts: dict[str, str], mode: str, claims
busy = record.get("status") == "busy"
stamp = record.get("statusUpdatedAt")
updated = (epoch(stamp / 1000) if isinstance(stamp, int | float) and not isinstance(stamp, bool) else None) or 0
called = names.get(sid, set()) | {agent(record.get("name"))}
called = names.get(sid, set()) | {agent(record.get("name")), sid}
if (busy and now - updated > STALE) or any(name in called and ts > updated for name, ts in late):
states[sid] = "unreachable"
continue
+3 -3
View File
@@ -43,7 +43,7 @@ OFFICES_UNIT="${NAME}-offices"
SESSIONS_UNIT="${NAME}-sessions"
RESOURCES_UNIT="${NAME}-resources"
INSTALLED_SKILLS="${HOME}/.claude/skills"
HOST_SCRIPTS=(kvb-org-organize/scripts/council.py kvb-org-organize/scripts/nofollow.py kvb-org-rasci/scripts/rasci.py)
HOST_SCRIPTS=(kvb-org-organize/scripts/council.py kvb-org-organize/scripts/nofollow.py kvb-org-rasci/scripts/rasci.py kvb-org-operator/scripts/operator.py kvb-org-radio/scripts/radio.py)
TREE_DIR="${HOME}/.local/state/pkgmgr/tree"
PKGMGR_REPO="${PKGMGR_REPO:-https://github.com/kevinveenbirkenbach/package-manager.git}"
IMAGE="${NAME}:local"
@@ -271,7 +271,7 @@ offices_unit() {
fi
if ! skills_current; then
systemctl --user disable --now "${OFFICES_UNIT}.path" >/dev/null 2>&1 || true
warn "skills: ${INSTALLED_SKILLS} holds other council.py, nofollow.py or rasci.py than this tree; run 'make install' to enable ${OFFICES_UNIT}.path."
warn "skills: ${INSTALLED_SKILLS} holds other council.py, nofollow.py, rasci.py, operator.py or radio.py than this tree; run 'make install' to enable ${OFFICES_UNIT}.path."
return 0
fi
cp -f "${HUB}/systemd/${OFFICES_UNIT}.service" "${HUB}/systemd/${OFFICES_UNIT}.path" "${UNITS}/"
@@ -304,7 +304,7 @@ runner() {
fi
if ! skills_current; then
systemctl --user disable --now "${RUNNER}" >/dev/null 2>&1 || true
warn "skills: ${INSTALLED_SKILLS} holds other council.py, nofollow.py or rasci.py than this tree; run 'make install' to enable ${RUNNER}."
warn "skills: ${INSTALLED_SKILLS} holds other council.py, nofollow.py, rasci.py, operator.py or radio.py than this tree; run 'make install' to enable ${RUNNER}."
return 1
fi
cp -f "${HUB}/systemd/${RUNNER}" "${UNITS}/"
+6 -6
View File
@@ -12,9 +12,9 @@ so collecting them needs no messages.
```bash
operator.py add <slug> --dir <abs dir> --command "<cmd>" --reason "<why>" --check <kind>[:<arg>]
operator.py list [--json]
operator.py list [--json] [--session <id>]
operator.py run
operator.py done <slug>
operator.py done <slug> [--session <id>]
```
## What counts
@@ -52,10 +52,10 @@ order (commits, pushes, installs, binaries, removals, manual steps), one
operator reports a `manual` step done, run `operator.py done <slug>`.
`run` is the operator's script, never an agent's; `run.md` next to this
file says what it shows and asks. A post from Operator that cancels your
row, or reports its command failed, took the row out of the queue: fix the
cause it names, then re-add the corrected command under the same slug or
drop the step; never re-add it unchanged.
file says what it shows and asks. Operator reports each outcome of your row
through your `radio.py feedback` channel. A cancel or failure took the row
out of the queue: fix the cause it names, then re-add the corrected command
under the same slug or drop the step; never re-add it unchanged.
Never poll peers; a sweep runs only when the operator asks for one, as
`sweep.md` next to this file says.
+17 -7
View File
@@ -6,21 +6,31 @@ removal deletes, the repository state), and runs the command only on `y`;
`d` shows the full diff, `s` skips, `c` cancels with a reason the operator
must give (empty goes back), `q` stops. Nothing answers for the operator.
Every message goes to each agent holding A through its `radio.py feedback`
channel.
- **Done**: exit 0 sets the row `done` once its check passes and sends
"Operator ran operator/<slug>: done"; a check not passing yet keeps the
row open and says so.
- **Cancel**: sets the row `stopped` with the reason under `cancelled` and
posts "Operator cancelled operator/<slug> (...): <reason>" to every agent
holding A. That agent treats it as the operator's rejection of exactly
that step.
sends "Operator cancelled operator/<slug> (...): <reason>". That agent
treats it as the operator's rejection of exactly that step.
- **Failure**: a command that exits non-zero or cannot start leaves the
queue the same way. The row is set `stopped` with the exit under
`failed` and posted to every agent holding A with the request to queue
the corrected command. `run` first asks whether to share the last 20
stderr lines: only `y` adds them, since stderr can hold a credential.
`failed` and sent with the request to queue the corrected command.
`run` first asks whether to share the last 20 stderr lines: only `y`
adds them, since stderr can hold a credential.
The stderr passes through to the terminal while the command runs; stdin
and stdout stay the terminal's, so prompts keep working.
- **Interrupt**: exit 130 or a signal is the operator's own abort; the row
stays open and nothing is posted.
stays open and nothing is sent.
- **Queue**: a heavy command can be held in `queue.py`; on the grant `run`
asks again. Exit 75 from a held step means nothing ran, never a failure.
`add` under the same slug reopens the row and clears `cancelled` and
`failed`.
The hub's runner reports through `ran` and `failed`: exit 0 closes the row
from any status but done, whatever its check; exit 130 and signals count
as failures. Any agent of the same user can forge `ran`, `failed` or
`done`: the register and the radio are writable by every agent already.
+248 -61
View File
@@ -4,8 +4,9 @@
Environment:
AGENTS_COUNCIL_ROOT: council directory of the kvb-org-rasci register, read
by rasci.py; the rows are its tasks operator/<slug>.
CLAUDE_CODE_SESSION_ID: the adding session, recorded as A; other runtimes
pass --session.
CLAUDE_CODE_SESSION_ID: the calling session: add records it as A, list
and done leave it out of their messages; other runtimes pass
--session.
NO_COLOR: when set and not empty, run prints without colors
(https://no-color.org).
PATH: searched by the binary check.
@@ -15,7 +16,8 @@ Environment:
Args:
add <slug> --dir <abs dir> --command "<cmd>" --reason "<why>"
--check <kind>[:<arg>] [--session <id>]: record a command, or update
the row of that slug, as queued with Operator R and the adder A.
the row of that slug, as queued with Operator R and the adder A, its
session id under `sessions`.
Kinds, never a shell command:
pushed:<repo dir> `git rev-list --count @{u}..HEAD` is 0 there;
no upstream counts as open.
@@ -32,8 +34,8 @@ Args:
on PATH, a path to one or a shell builtin and holds no <placeholder>;
an alias, a slash command or prose is refused, and an older row
holding one stays in the table only.
list [--json]: run the check of every queued or blocked operator row and
set the passing ones done.
list [--json] [--session <id>]: run the check of every queued or blocked
operator row and set the passing ones done, with a message.
run: walk the open rows that hold a directory and a command, in list
order. Per row it prints a separator line with number and task, then
directory, command, reason and check in a label column (control
@@ -44,17 +46,17 @@ Args:
[s]kip / [c]ancel / [d]iff / [q]uit; d shows the full diff. A repo
whose git config names filter commands gets no preview. c asks for a
reason (empty: back to the question), sets the row as shown stopped
with it and posts it through `radio.py post` as Operator to every
agent holding A, the agent that added the row; a row changed since it
was shown is not cancelled. y runs the command in its directory,
with it and sends it as a message; a row changed since it was shown
is not cancelled. y runs the command in its directory,
its stderr passed through and its last FAILED_LINES lines kept, then
sets the row done when its check passes (manual: when the command
exits 0). A command that exits non-zero or cannot start leaves the
exits 0), else keeps it open, with a message either way. A command
that exits non-zero or cannot start leaves the
queue the same way: the row is set stopped with the exit under
`failed`, posted to every agent holding A with the request to queue
`failed`, sent as a message with the request to queue
the corrected command under the same slug; the stderr lines join it
only when the operator answers y to sharing them. Exit 130 or a
signal is the operator's interrupt: the row stays open.
signal is the operator's interrupt: the row stays open, no message.
A command
the kvb-org-organize watch config calls heavy also shows the memory
stage and the position, id, status, task and eta_min columns of
@@ -70,7 +72,22 @@ Args:
the row's directory; a row no longer open with exactly that
directory, check and command runs nothing, nor does a question left
unanswered for GRANT_SECONDS.
done <slug>: mark a row done, whatever its check.
done <slug> [--session <id>]: mark a row done, whatever its check, with
a message unless it was done; a stale `failed` or `cancelled` goes
as in ran. Without a session the caller is Operator.
ran <slug> --command "<cmd>" --dir <dir>: the hub's report of a job
that exited 0: the row set done from every status but done and
whatever its check, which the hub cannot run without the host's
repos, PATH and installed dirs; a stale `failed` or `cancelled`
goes.
failed <slug> --why "<text>" --command "<cmd>" --dir <dir>: the hub's
report of a job that failed: the row set stopped with why and no
output lines under `failed`, sent as a message like a failure in run.
Unlike run, the hub counts exit 130 and a signal (why `killed by
signal <n>`) as failures.
ran and failed change a row only while it holds exactly that command
and directory, failed only while it is open; else nothing changes
and nobody is told.
Output:
list: the open rows as `| # | Directory | Command | Why | Check |`, rows
@@ -79,6 +96,19 @@ Output:
each holding `cd <dir>` and the command, and a last block with the
`run` invocation. `operator: nothing open` when none is. --json
prints the same rows as a JSON list.
message: one line from Operator through `radio.py feedback send` to
every agent holding A but Operator and the caller, by the party name
and the session id `add` stored (--sid), never resolved again; a
party name the caller holds now is left out and the id alone, as
the --to label too, carries the message:
run and ran done: `Operator ran <row>: done`
run, check open: `Operator ran <row>; exit 0, but <check> does
not pass yet; the row stays open`
list: `<row> done: its check <check> passes`, and on stderr
`operator: <row> done; <how it went>`
done: `<row> marked done by <caller name>`
cancel, failure and failed: the reason or the error.
A row changed or closed since it was shown gets no message.
Exit codes:
0 done, 2 usage error. granted: the command's exit code, or 75
@@ -116,6 +146,7 @@ RASCI = SKILLS / "kvb-org-rasci" / "scripts" / "rasci.py"
WATCH = SKILLS / "kvb-org-organize" / "scripts" / "watch.py"
QUEUE = SKILLS / "kvb-org-queue" / "scripts" / "queue.py"
RADIO = SKILLS / "kvb-org-radio" / "scripts" / "radio.py"
COUNCIL = SKILLS / "kvb-org-organize" / "scripts" / "council.py"
HOLD_KIND = "operator"
HOLD_SESSION = "Operator"
NOT_RUN = 75
@@ -135,6 +166,8 @@ NAME = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._+-]*$")
COMMIT = re.compile(r"\bcommit\b")
ASSIGNMENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
SLOT = re.compile(r"<[A-Za-z][^<>]*>")
SENT = re.compile(r"^sent (call|post) to (.+)$")
WAKE = "wake: SendMessage to "
BUILTINS = frozenset({".", ":", "cd", "exec", "exit", "export", "set", "source", "umask"})
HEADER = "| # | Directory | Command | Why | Check |"
GIT = ["git", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null", "-c", "log.showSignature=false", "--no-pager", "--no-optional-locks"]
@@ -287,24 +320,40 @@ def cmd_add(rasci: ModuleType, args: argparse.Namespace) -> int:
roles[rasci.OPERATOR] = rasci.letters_of(roles.get(rasci.OPERATOR, ""), "R")
roles[party] = rasci.letters_of(roles.get(party, ""), "A")
entry["roles"] = {p: v for p, v in roles.items() if v}
entry["sessions"] = {party: sid}
rasci.apply_status(entry, "queued")
print(f"added {task}")
return 0
def open_rows(rasci: ModuleType) -> list[dict]:
def open_rows(rasci: ModuleType, caller: str | None) -> list[dict]:
"""Args:
caller: the session left out of the messages for rows whose check
passes, None for the operator.
Returns:
The open operator rows in list order, once the passing ones are
set done.
"""
rows = {
task: row for task, row in rasci.merged(include_done=False).items()
if task.startswith(PREFIX) and row["status"] in OPEN
}
checks = {task: row.get("check") or "manual" for task, row in rows.items()}
finished = {task for task, check in checks.items() if not problem(check) and passed(check)}
closed = {}
if finished:
with rasci.database() as tasks:
for task in finished:
entry = tasks.get(task)
if entry and entry.get("check") == checks[task] and entry.get("status") in OPEN:
rasci.apply_status(entry, "done")
closed[task] = accountable(rasci, entry)
for task, holders in sorted(closed.items()):
agents = addressees(holders, caller)
if agents:
text = f"{visible(task, '')} done: its check {visible(checks[task], '')} passes"
print(f"operator: {visible(task, '')} done; {told(agents, text, 'the result')}", file=sys.stderr)
def rank(task: str) -> tuple:
kind = "manual" if problem(checks[task]) else checks[task].partition(":")[0]
@@ -325,7 +374,7 @@ def open_rows(rasci: ModuleType) -> list[dict]:
def cmd_list(rasci: ModuleType, args: argparse.Namespace) -> int:
listed = open_rows(rasci)
listed = open_rows(rasci, os.environ.get("CLAUDE_CODE_SESSION_ID") or args.session)
if args.json:
print(json.dumps(listed, indent=1))
return 0
@@ -542,41 +591,148 @@ def decide(row: dict, holdable: bool, read: Callable[[str], str | None]) -> tupl
return answer, reason
def stop(rasci: ModuleType, row: dict, key: str, value: object) -> list[str] | None:
def accountable(rasci: ModuleType, entry: dict) -> list[tuple[str, str | None]]:
"""Returns:
The agents holding A on the row, once the row as shown is set
stopped with value under key; None when it changed or closed since
it was shown, which leaves it as it is.
Every party but Operator holding A on the register entry, with the
session id `add` stored for it, None on a row from before that.
"""
sessions = entry.get("sessions") if isinstance(entry.get("sessions"), dict) else {}
found = []
for party, letters in sorted(entry.get("roles", {}).items()):
sid = sessions.get(party)
if "A" in letters and party != rasci.OPERATOR:
found.append((party, sid if isinstance(sid, str) else None))
return found
def addressees(holders: list[tuple[str, str | None]], caller: str | None) -> list[tuple[str, str | None]]:
"""Args:
holders: the parties holding A and their stored session ids.
caller: the session running this script, None for the operator.
Returns:
Each holder's address as stored when the row was added, the name for
--to and the session id, without the caller's own parts: a holder
whose session is the caller is left out, a party name that is the
caller's current name gives way to the session id as the --to label.
"""
live = module("council", COUNCIL).live_sessions()
me = {caller, live.get(caller) or caller} if caller else set()
return sorted((sid if party in me else party, sid) for party, sid in holders if sid not in me and (sid or party not in me))
def as_operator() -> dict[str, str]:
"""Returns:
This script's environment without CLAUDE_CODE_SESSION_ID, for the
children that act as Operator.
"""
return {key: value for key, value in os.environ.items() if key != "CLAUDE_CODE_SESSION_ID"}
def sent_to(name: str, sid: str | None, text: str) -> str:
"""Returns:
How text went from Operator through the agent's radio feedback
channel: `<name> as a <class>`, or `<name> queued as a call;` and
the radio's wake lines when no listener takes the call.
Raises:
OSError: the radio did not start or failed.
"""
sent = subprocess.run(
[sys.executable, str(RADIO), "feedback", "send", f"--to={name}", *([f"--sid={sid}"] if sid else []), f"--session={HOLD_SESSION}", text],
capture_output=True, text=True, env=as_operator(), check=False,
)
if sent.returncode != 0:
raise OSError(sent.stderr.strip())
lines = sent.stdout.splitlines()
found = next(filter(None, map(SENT.match, lines)), None)
how = found[1] if found else "post"
wakes = [visible(line, "") for line in lines if line.startswith(WAKE)]
if how == "call" and wakes:
return f"{visible(name, '')} queued as a call; " + "; ".join(wakes)
return f"{visible(name, '')} as a {how}"
def told(agents: list[tuple[str, str | None]], text: str, what: str) -> str:
"""Args:
agents: each agent's name and stored session id, None on a row from
before that field.
Returns:
How text went to the agents, named as what.
"""
if not agents:
return "no agent holds A, so nothing was sent"
ways, errors = [], []
for name, sid in agents:
try:
ways.append(sent_to(name, sid, text))
except OSError as error:
errors.append(f"the message to {visible(name, '')} failed: {visible(str(error), '')}")
return "; ".join(([f"{what} went to {', '.join(ways)}"] if ways else []) + errors)
def reported(agents: list[tuple[str, str | None]], text: str) -> str:
"""Returns:
"; " and how text went to the agents, or "" when there is none.
"""
return f"; {told(agents, text, 'the result')}" if agents else ""
def finish(rasci: ModuleType, entry: dict) -> None:
rasci.apply_status(entry, "done")
entry.pop("failed", None)
entry.pop("cancelled", None)
def settle(rasci: ModuleType, row: dict, status: str | None, fields: dict, statuses: tuple[str, ...]) -> list[tuple[str, str | None]] | None:
"""Args:
status: the status the row gets, None to keep it.
fields: the keys the row gets besides.
statuses: the statuses the row may have to be settled.
Returns:
The agents holding A on the row once the row as shown is settled;
None when it changed or left statuses since it was shown, which
leaves it as it is.
"""
with rasci.database() as tasks:
entry = tasks.get(row["task"])
shown = (row["command"], row["directory"], row["check"])
if not entry or entry.get("status") not in OPEN or (entry.get("title"), entry.get("workdir"), entry.get("check") or "manual") != shown:
if not entry or entry.get("status") not in statuses or (entry.get("title"), entry.get("workdir"), entry.get("check") or "manual") != shown:
return None
rasci.apply_status(entry, "stopped")
entry[key] = value
return sorted(party for party, letters in entry.get("roles", {}).items() if "A" in letters and party != rasci.OPERATOR)
if status == "done":
finish(rasci, entry)
elif status:
rasci.apply_status(entry, status)
entry.update(fields)
holders = accountable(rasci, entry)
return addressees(holders, None)
def told(agents: list[str], text: str, what: str) -> str:
"""Returns:
How text went as a post from Operator through the radio to the
agents, named as what.
def succeeded(rasci: ModuleType, row: dict, hub: bool) -> str:
"""Args:
hub: the hub's report: the row closes whatever its check and from
every status but done; else only while open and once its check
passes (manual: at once).
Returns:
What an exit 0 did: the row as shown set done, or kept open while
its check does not pass, the agents holding A told either way; a
row changed or closed since it was shown stays as it is and nobody
is told.
"""
if not agents:
return "no agent holds A, so nothing was posted"
env = {key: value for key, value in os.environ.items() if key != "CLAUDE_CODE_SESSION_ID"}
who = visible(", ".join(agents), "")
try:
sent = subprocess.run(
[sys.executable, str(RADIO), "post", *(f"--to={agent}" for agent in agents), f"--session={HOLD_SESSION}", text],
capture_output=True, text=True, env=env, check=False,
)
except OSError as error:
return f"the post to {who} failed: {visible(str(error), '')}"
if sent.returncode != 0:
return f"the post to {who} failed: {visible(sent.stderr.strip(), '')}"
return f"{what} went to {who} as a post"
name = visible(row["task"], "")
check = "manual" if problem(row["check"]) else row["check"]
complete = hub or check == "manual" or passed(check)
statuses = tuple(status for status in rasci.STATUSES if status != "done") if hub else OPEN
agents = settle(rasci, row, "done" if complete else None, {}, statuses)
if agents is None:
return f"ran {name}; it changed or closed meanwhile and stays as it is"
if complete:
return f"done {name}" + reported(agents, f"Operator ran {name}: done")
pending = f"{visible(check, '')} does not pass yet; the row stays open"
return f"ran {name}, but {pending}" + reported(agents, f"Operator ran {name}; exit 0, but {pending}")
def shown_as(row: dict) -> str:
@@ -589,7 +745,7 @@ def cancel(rasci: ModuleType, row: dict, reason: str) -> str:
reason posted through the radio to every agent holding A on it.
"""
name = visible(row["task"], "")
agents = stop(rasci, row, "cancelled", reason)
agents = settle(rasci, row, "stopped", {"cancelled": reason}, OPEN)
if agents is None:
return f"{name} changed or closed since it was shown; nothing cancelled"
return f"cancelled {name}; " + told(agents, f"Operator cancelled {shown_as(row)}: {visible(reason, '')}", "the reason")
@@ -608,8 +764,11 @@ def chunk_of(source: int) -> bytes | None:
return b""
def execute(argv: list[str], directory: str) -> tuple[int, list[str]]:
"""Returns:
def execute(argv: list[str], directory: str, env: dict[str, str] | None) -> tuple[int, list[str]]:
"""Args:
env: the command's environment, None for this script's own.
Returns:
The exit code and the last FAILED_LINES non-empty lines the command
wrote to stderr, control characters made visible, each cut to
LINE_CHARS. Stdin and stdout stay the terminal's; stderr reaches the
@@ -621,7 +780,7 @@ def execute(argv: list[str], directory: str) -> tuple[int, list[str]]:
Raises:
OSError: the command did not start.
"""
child = subprocess.Popen(argv, cwd=directory, stderr=subprocess.PIPE)
child = subprocess.Popen(argv, cwd=directory, env=env, stderr=subprocess.PIPE)
kept = b""
with child:
source = child.stderr.fileno()
@@ -681,7 +840,7 @@ def failure(rasci: ModuleType, row: dict, why: str, lines: list[str]) -> str:
marked as command output.
"""
name = visible(row["task"], "")
agents = stop(rasci, row, "failed", {"why": why, "output": lines})
agents = settle(rasci, row, "stopped", {"failed": {"why": why, "output": lines}}, OPEN)
if agents is None:
return f"failed {name}: {why}; it changed or closed meanwhile and stays as it is"
slug = visible(row["task"].removeprefix(PREFIX), "")
@@ -715,7 +874,7 @@ def review(row: dict, holdable: bool, read: Callable[[str], str | None]) -> str:
def cmd_granted(rasci: ModuleType, args: argparse.Namespace) -> int:
shell = os.environ.get("SHELL")
approved = [
row for row in open_rows(rasci)
row for row in open_rows(rasci, None)
if runnable(row) and (row["task"], row["directory"], row["check"]) == (args.task, args.dir, args.check)
and args.argv == [shell, "-ic", row["command"]]
]
@@ -741,18 +900,11 @@ def cmd_granted(rasci: ModuleType, args: argparse.Namespace) -> int:
return subprocess.run(args.argv, cwd=row["directory"], check=False).returncode
def close(rasci: ModuleType, task: str) -> None:
with rasci.database() as tasks:
entry = tasks.get(task)
if entry and entry.get("status") in OPEN:
rasci.apply_status(entry, "done")
def cmd_run(rasci: ModuleType, args: argparse.Namespace) -> int:
shell = os.environ.get("SHELL")
if not shell:
fail("SHELL is not set; run executes each command in the operator's own shell")
steps = [row for row in open_rows(rasci) if runnable(row)]
steps = [row for row in open_rows(rasci, None) if runnable(row)]
if not steps:
print("operator: nothing to run")
return 0
@@ -780,7 +932,7 @@ def cmd_run(rasci: ModuleType, args: argparse.Namespace) -> int:
continue
argv = held(row, shell) if answer == "h" else [shell, "-ic", row["command"]]
try:
code, lines = execute(argv, row["directory"])
code, lines = execute(argv, row["directory"], as_operator() if answer == "h" else None)
except OSError as error:
print(failure(rasci, row, "no start", [visible(str(error), "")]))
continue
@@ -790,21 +942,48 @@ def cmd_run(rasci: ModuleType, args: argparse.Namespace) -> int:
print(f"interrupted {name}: exit {code}; the row stays open")
elif code != 0:
print(failure(rasci, row, f"exit {code}", shared(lines, typed)))
elif check == "manual" or passed(check):
close(rasci, row["task"])
print(f"done {name}")
else:
print(f"ran {name}, but {visible(check, '')} does not pass yet; the row stays open")
print(succeeded(rasci, row, False))
return 0
def cmd_done(rasci: ModuleType, args: argparse.Namespace) -> int:
task = task_of(rasci, args.slug)
caller = os.environ.get("CLAUDE_CODE_SESSION_ID") or args.session
with rasci.database() as tasks:
if task not in tasks:
fail(f"{task}: not in the register")
rasci.apply_status(tasks[task], "done")
print(f"done {task}")
closing = tasks[task].get("status") != "done"
finish(rasci, tasks[task])
holders = accountable(rasci, tasks[task])
by = (module("council", COUNCIL).live_sessions().get(caller) or caller) if caller else HOLD_SESSION
agents = addressees(holders, caller) if closing else []
print(f"done {task}" + reported(agents, f"{visible(task, '')} marked done by {visible(by, '')}"))
return 0
def ran_row(rasci: ModuleType, args: argparse.Namespace) -> dict:
"""Returns:
The row as the hub's job ran it: slug, --command and --dir, with the
register's current check.
"""
task = task_of(rasci, args.slug)
entry = rasci.load().get(task)
if entry is None:
fail(f"{task}: not in the register")
return {"task": task, "command": args.command, "directory": args.dir, "check": entry.get("check") or "manual"}
def cmd_ran(rasci: ModuleType, args: argparse.Namespace) -> int:
print(succeeded(rasci, ran_row(rasci, args), True))
return 0
def cmd_failed(rasci: ModuleType, args: argparse.Namespace) -> int:
why = visible(" ".join(args.why.split()), "")
if not why:
fail("--why must not be empty")
print(failure(rasci, ran_row(rasci, args), why, []))
return 0
@@ -819,6 +998,7 @@ def main() -> int:
p.set_defaults(func=cmd_add)
p = sub.add_parser("list")
p.add_argument("--json", action="store_true")
p.add_argument("--session")
p.set_defaults(func=cmd_list)
p = sub.add_parser("run")
p.set_defaults(func=cmd_run)
@@ -830,7 +1010,14 @@ def main() -> int:
p.set_defaults(func=cmd_granted)
p = sub.add_parser("done")
p.add_argument("slug")
p.add_argument("--session")
p.set_defaults(func=cmd_done)
for name, func, flags in (("ran", cmd_ran, ("--command", "--dir")), ("failed", cmd_failed, ("--why", "--command", "--dir"))):
p = sub.add_parser(name)
p.add_argument("slug")
for flag in flags:
p.add_argument(flag, required=True)
p.set_defaults(func=func)
args = parser.parse_args()
return args.func(module("rasci", RASCI), args)
+2
View File
@@ -47,6 +47,8 @@ clear another agent's mayday; `--force` only on the operator's order.
## Rules
- Pick the lowest class that does the job; the post first.
- `radio.py feedback set call|post` picks how outcomes of your queued operator
commands reach you, post unless set; `feedback show` prints it.
- For an addressee no listener wakes yet, `send` prints `wake: SendMessage
to <name>`: send that peer the same text once with your runtime's message
tool.
+80 -11
View File
@@ -47,6 +47,16 @@ Args:
The mayday's sender and its helpers pass. Never fails.
show [--all] [--session <id>]: print the active silence and the
undelivered rows, or every kept row, without delivering them.
feedback set post|call [--session <id>]: store how outcomes of the
session's queued operator commands reach it, in <root>/feedback.json;
post unless set.
feedback show [--session <id>]: print the session's channel.
feedback send "<text>" --to <name> ... [--sid <id>] [--session <id>]: send
text to each name as a call when the session --sid names, else the
name, set call, else as a post. --sid, with a single --to, pins that
session: the row keeps the name in `to` and the id in `to_sessions`
and reaches both, the session under any later name and whoever holds
the name, with no liveness check; its wake line adds `(session <id>)`.
Delivering a call stores a receipt in the caller's post.
@@ -86,6 +96,7 @@ STATE = ROOT / "radio-seen"
LISTEN = ROOT / "radio-listen"
SILENCE = ROOT / "radio-silence.json"
NOTIFIED = ROOT / "radio-notified"
FEEDBACK = ROOT / "feedback.json"
ORGANIZE = Path(__file__).resolve().parents[2] / "kvb-org-organize" / "scripts"
SELF = Path(__file__).resolve()
RADIO = ("mayday", "pan-pan", "security", "call", "broadcast")
@@ -93,6 +104,7 @@ MAIL = ("post", "newsletter", "receipt")
ALARMS = ("mayday", "pan-pan", "security")
ADDRESSED = ("call", "post", "receipt")
SEND = ("call", "broadcast", "security", "pan-pan", "mayday", "direct")
FEEDBACKS = ("post", "call")
VERSION = 2
WRITERS = ("Edit", "Write", "MultiEdit", "NotebookEdit")
SHELL = re.compile(r"[;&|`$()<>\n\r\\\"]")
@@ -202,8 +214,12 @@ def targets(row: dict) -> list:
return row["to"] if isinstance(row.get("to"), list) else []
def for_me(row: dict, name: str) -> bool:
return row.get("from") != name and (not targets(row) or name in targets(row))
def sessions_of(row: dict) -> list[str]:
return listed(row.get("to_sessions"))
def for_me(row: dict, name: str, sid: str) -> bool:
return row.get("from") != name and (not targets(row) or name in targets(row) or sid in sessions_of(row))
def read_json(path: Path) -> dict:
@@ -318,13 +334,18 @@ def listening(sid: str) -> bool:
return True
def unreached(cls: str, to: list[str], sender: str) -> list[str]:
def unreached(cls: str, to: list[str], sender: str, sessions: list[str]) -> list[str]:
"""Returns:
Each addressee no live listener of its name or of the row's sessions
takes the row for, followed by `(session <id>)` when it has sessions.
"""
live = council().live_sessions()
if cls in ADDRESSED:
targets = [(name, [sid for sid, label in live.items() if name in (label, sid)]) for name in to]
targets = [(name, [*sessions, *(sid for sid, label in live.items() if name in (label, sid))]) for name in to]
else:
targets = [(name or sid, [sid]) for sid, name in live.items() if sid != sender]
return [name for name, sids in targets if not any(map(listening, sids))]
pinned = f" (session {', '.join(sessions)})" if sessions else ""
return [f"{name}{pinned}" for name, sids in targets if not any(map(listening, sids))]
def store(entries: list[dict]) -> float:
@@ -339,7 +360,11 @@ def store(entries: list[dict]) -> float:
return entries[-1]["ts"]
def transmit(cls: str, to: list[str], text: str, caller: str | None) -> int:
def transmit(cls: str, to: list[str], text: str, caller: str | None, sessions: list[str]) -> int:
"""Args:
sessions: the session ids of the addressees, kept under
`to_sessions` beside their names; none keeps the row as before.
"""
if cls in ADDRESSED and not to:
fail(f"{cls} needs --to")
if cls not in ADDRESSED and to:
@@ -351,7 +376,7 @@ def transmit(cls: str, to: list[str], text: str, caller: str | None) -> int:
sender = name_of(sid)
ROOT.mkdir(parents=True, exist_ok=True)
with organize("nofollow").locked(ROOT, LOCK, 0o600, None):
ts = store([{"from": sender, "to": to, "text": text, "class": cls, "v": VERSION}])
ts = store([{"from": sender, "to": to, "text": text, "class": cls, "v": VERSION, **({"to_sessions": sessions} if sessions else {})}])
if cls == "mayday":
write_atomic(
SILENCE,
@@ -359,7 +384,7 @@ def transmit(cls: str, to: list[str], text: str, caller: str | None) -> int:
)
print(f"sent {cls} to {', '.join(to) or 'all'}")
if cls in RADIO:
for name in unreached(cls, to, sid):
for name in unreached(cls, to, sid, sessions):
print(f"wake: SendMessage to {clip(name)}")
return 0
@@ -370,11 +395,11 @@ def cmd_send(args: argparse.Namespace) -> int:
cls = "call" if args.wake else "post"
elif args.wake:
fail("--wake only with direct; a call always wakes")
return transmit(cls, args.to or [], args.text, args.session)
return transmit(cls, args.to or [], args.text, args.session, [])
def cmd_post(args: argparse.Namespace) -> int:
return transmit("post" if args.to else "newsletter", args.to or [], args.text, args.session)
return transmit("post" if args.to else "newsletter", args.to or [], args.text, args.session, [])
def cmd_clear(args: argparse.Namespace) -> int:
@@ -413,7 +438,7 @@ def cmd_assist(args: argparse.Namespace) -> int:
def pending(sid: str, name: str, state: dict, family: str) -> list[dict]:
floor = max(prompt_mark(sid), time.time() - WINDOW, mark(state, family))
return [row for row in items() if channel(row) == family and row["ts"] > floor and for_me(row, name)]
return [row for row in items() if channel(row) == family and row["ts"] > floor and for_me(row, name, sid)]
def take(sid: str, family: str) -> list[dict]:
@@ -586,6 +611,36 @@ def cmd_show(args: argparse.Namespace) -> int:
return 0
def feedback_of(chosen: dict, sid: str) -> str:
return "call" if chosen.get(sid) == "call" else "post"
def cmd_feedback_set(args: argparse.Namespace) -> int:
sid, _ = council().caller(args.session)
ROOT.mkdir(parents=True, exist_ok=True)
with organize("nofollow").locked(ROOT, LOCK, 0o600, None):
chosen = read_json(FEEDBACK)
chosen[sid] = args.channel
write_atomic(FEEDBACK, json.dumps(chosen, sort_keys=True))
print(f"feedback: {args.channel}")
return 0
def cmd_feedback_show(args: argparse.Namespace) -> int:
sid, _ = council().caller(args.session)
print(feedback_of(read_json(FEEDBACK), sid))
return 0
def cmd_feedback_send(args: argparse.Namespace) -> int:
if args.sid and len(args.to) != 1:
fail("--sid takes a single --to")
chosen = read_json(FEEDBACK)
for name in args.to:
transmit(feedback_of(chosen, args.sid or name), [name], args.text, args.session, [args.sid] if args.sid else [])
return 0
def main() -> int:
parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
sub = parser.add_subparsers(dest="command", required=True)
@@ -620,6 +675,20 @@ def main() -> int:
p.add_argument("--all", action="store_true")
p.add_argument("--session")
p.set_defaults(func=cmd_show)
feedback = sub.add_parser("feedback").add_subparsers(dest="action", required=True)
p = feedback.add_parser("set")
p.add_argument("channel", choices=FEEDBACKS)
p.add_argument("--session")
p.set_defaults(func=cmd_feedback_set)
p = feedback.add_parser("show")
p.add_argument("--session")
p.set_defaults(func=cmd_feedback_show)
p = feedback.add_parser("send")
p.add_argument("text")
p.add_argument("--to", action="append", required=True)
p.add_argument("--sid")
p.add_argument("--session")
p.set_defaults(func=cmd_feedback_send)
args = parser.parse_args()
os.environ["PATH"] = organize("hookpath").trusted(os.environ.get("PATH", ""))
refused = organize("watch").guard_root(hook=args.command in ("hook", "tool", "mailbox", "listen", "block"))
+47
View File
@@ -78,6 +78,53 @@ class TestHubConsole(HubCase):
self.assertEqual(console, output[-skill_scripts.OUTPUT_LIMIT :])
self.assertEqual(console, snapshot["jobs"][-1]["output"])
def test_only_a_done_or_failed_command_job_reports_the_command_and_directory_it_ran(self):
self.register("queued")
fields = {"task": "operator/greet", "command": COMMAND, "directory": str(self.outside), "sha256": DIGEST, "status": "running", "proof": None}
jobs = [
self.httpd.hub.jobs.add({**fields, **extra, "code": None, "output": "", "created_ts": time.time(), "started": time.time(), "finished": None, "dismissed": False})
for extra in ({}, {}, {}, {}, {}, {"kind": "gate", "argv": []})
]
reports = (
{"output": "token-42\n", "code": 0, "refused": False}, {"output": "token-42\n", "code": 3, "refused": False},
{"output": "", "code": -9, "refused": False}, {"output": "", "code": 130, "refused": False},
{"output": "token-42\n", "code": None, "refused": True}, {"output": "", "code": 1, "refused": False},
)
answers = [self.runner(f"/api/runner/{job['id']}/report", report) for job, report in zip(jobs, reports)]
self.assertEqual([(status, body["status"], len(body["runs"])) for status, body in answers], [
(200, "done", 1), (200, "failed", 1), (200, "failed", 1), (200, "failed", 1), (200, "refused", 0), (200, "failed", 0),
])
shown = ["greet", f"--command={COMMAND}", f"--dir={self.outside}"]
self.assertEqual(self.scripts.calls, [
(skill_scripts.OPERATOR_SCRIPT, ["ran", *shown]),
(skill_scripts.OPERATOR_SCRIPT, ["failed", *shown, "--why", "exit 3"]),
(skill_scripts.OPERATOR_SCRIPT, ["failed", *shown, "--why", "killed by signal 9"]),
(skill_scripts.OPERATOR_SCRIPT, ["failed", *shown, "--why", "exit 130"]),
])
self.assertNotIn("token-42", json.dumps(self.scripts.calls))
def test_an_older_installed_operator_without_ran_still_closes_the_row_through_done(self):
self.register("queued")
fields = {"task": "operator/greet", "command": COMMAND, "directory": str(self.outside), "sha256": DIGEST, "status": "running", "proof": None}
jobs = [
self.httpd.hub.jobs.add({**fields, "code": None, "output": "", "created_ts": time.time(), "started": time.time(), "finished": None, "dismissed": False})
for _ in range(2)
]
self.scripts.code = 2
done = self.runner(f"/api/runner/{jobs[0]['id']}/report", {"output": "", "code": 0, "refused": False})[1]
failed = self.runner(f"/api/runner/{jobs[1]['id']}/report", {"output": "", "code": 1, "refused": False})[1]
shown = ["greet", f"--command={COMMAND}", f"--dir={self.outside}"]
self.assertEqual(self.scripts.calls, [
(skill_scripts.OPERATOR_SCRIPT, ["ran", *shown]),
(skill_scripts.OPERATOR_SCRIPT, ["done", "greet"]),
(skill_scripts.OPERATOR_SCRIPT, ["failed", *shown, "--why", "exit 1"]),
])
self.assertEqual((len(done["runs"]), len(failed["runs"])), (2, 1))
self.scripts.code = 1
job = self.httpd.hub.jobs.add({**fields, "code": None, "output": "", "created_ts": time.time(), "started": time.time(), "finished": None, "dismissed": False})
self.runner(f"/api/runner/{job['id']}/report", {"output": "", "code": 0, "refused": False})
self.assertEqual(self.scripts.calls[-1], (skill_scripts.OPERATOR_SCRIPT, ["ran", *shown]))
def test_jobs_from_before_the_console_stay_out_of_the_inbox(self):
self.register("done")
fields = {"task": "operator/greet", "command": COMMAND, "directory": str(self.outside), "sha256": DIGEST, "status": "done", "proof": None}
+1 -1
View File
@@ -63,7 +63,7 @@ class TestHubExecutors(HubCase):
job = self.snapshot()["jobs"][-1]
self.assertEqual((job["status"], job["code"], job["output"]), ("done", 0, "hello\nworld\n"))
self.assertNotIn("proof", job)
self.assertEqual(self.scripts.calls[-1], (skill_scripts.OPERATOR_SCRIPT, ["done", "greet"]))
self.assertEqual(self.scripts.calls[-1], (skill_scripts.OPERATOR_SCRIPT, ["ran", "greet", f"--command={command}", f"--dir={self.outside}"]))
claim = {**self.client(), "Content-Type": "application/json"}
self.assertEqual(self.call("POST", f"/api/runner/{job['id']}/claim", b"{}", claim)[0], 409)
self.assertEqual(self.call("POST", f"/api/runner/{job['id']}/claim", b"{}", {**self.guard(self.host), "Content-Type": "application/json"})[0], 403)
+8
View File
@@ -64,6 +64,14 @@ class TestPresence(unittest.TestCase):
self.assertEqual(self.states({"later": record("later", "idle", FRESH, "Later")}, {}, "day", claims, news), {"later": "alive"})
self.assertEqual(self.states({"later": record("later", "idle", OLD, "Later")}, {}, "day", claims, news), {"later": "unreachable"})
def test_a_call_to_a_session_id_is_answered_by_its_receipt_under_a_new_name_and_flags_only_that_session(self):
call = NOW - 700
sessions = {"s1": record("s1", "idle", OLD, "Uno"), "sB": record("sB", "idle", OLD, "One")}
taken = [{"ts": call, "from": "Operator", "to": ["One"], "to_sessions": ["s1"], "class": "call"}]
receipt = {"ts": call + 2, "from": "Uno", "to": ["Operator"], "class": "receipt", "call": call}
self.assertEqual(self.states(sessions, {}, "day", [], [*taken, receipt]), {"s1": "alive", "sB": "alive"})
self.assertEqual(self.states(sessions, {}, "day", [], taken), {"s1": "unreachable", "sB": "alive"})
def test_a_record_without_running_true_is_dead(self):
for value in (False, None, "yes", 1):
with self.subTest(value=value):
+273
View File
@@ -125,6 +125,21 @@ class TestOperator(unittest.TestCase):
def _register(self) -> dict[str, dict]:
return json.loads((self.root / "rasci.json").read_text(encoding="utf-8"))
def _session(self, sid: str, name: str) -> None:
(self.home / ".claude" / "sessions" / f"{sid}.json").write_text(json.dumps({"sessionId": sid, "name": name}), encoding="utf-8")
def _as(self, sid: str | None, *args: str) -> subprocess.CompletedProcess:
env = {key: value for key, value in self.env.items() if key != "CLAUDE_CODE_SESSION_ID"}
return subprocess.run(
[sys.executable, str(OPERATOR), *args], capture_output=True, text=True,
env={**env, "CLAUDE_CODE_SESSION_ID": sid} if sid else env, cwd=self.tmp.name, check=False,
)
def _messages(self) -> list[tuple]:
news = self.root / "news.jsonl"
lines = news.read_text(encoding="utf-8").splitlines() if news.exists() else []
return [(row["class"], row["from"], row["to"], row["text"]) for row in map(json.loads, lines)]
def test_checks_close_rows_once_their_condition_holds(self):
for name in ("pipx", "git-sign-push"):
(self.bin / name).write_text("#!/bin/sh\n", encoding="utf-8")
@@ -542,6 +557,37 @@ class TestOperator(unittest.TestCase):
self.assertEqual(self._open(), ["operator/heavy"])
self.assertFalse((self.root / "queue-history.jsonl").exists())
def test_hold_queues_the_command_as_operator_without_the_claude_session(self):
self._queue_config({"operator": 0})
work = self.base / "work"
work.mkdir()
self._add("heavy", work, "touch heavy", "build", "manual")
fake = self.base / "queue.py"
fake.write_text(
"import json, os, sys\n"
"with open(sys.argv[0] + '.calls', 'a', encoding='utf-8') as calls:\n"
" calls.write(json.dumps([sys.argv[1:3], os.environ.get('CLAUDE_CODE_SESSION_ID')]) + '\\n')\n"
"sys.exit(75 if sys.argv[1] == 'hold' else 0)\n",
encoding="utf-8",
)
wrapper = (
"import importlib.util, sys\n"
"spec = importlib.util.spec_from_file_location('kvb_operator', sys.argv[1])\n"
"operator = importlib.util.module_from_spec(spec)\n"
"spec.loader.exec_module(operator)\n"
"operator.QUEUE = operator.Path(sys.argv[2])\n"
"sys.argv = [sys.argv[1], 'run']\n"
"sys.exit(operator.main())\n"
)
result = subprocess.run(
[sys.executable, "-c", wrapper, str(OPERATOR), str(fake)], input="h\n", capture_output=True, text=True,
env={**self.env, "SHELL": "/bin/sh"}, cwd=self.tmp.name, check=False,
)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("not run operator/heavy", result.stdout)
calls = [json.loads(line) for line in (self.base / "queue.py.calls").read_text(encoding="utf-8").splitlines()]
self.assertEqual(calls, [[["list"], "s1"], [["hold", "--kind"], None]])
def test_run_offers_no_hold_while_the_config_lacks_the_operator_kind(self):
self._queue_config({"test": 0})
work = self.base / "work"
@@ -592,6 +638,233 @@ class TestOperator(unittest.TestCase):
self.assertTrue((work / "heavy").exists())
self.assertFalse((self.base / "heavy").exists() or (work / "other").exists())
def test_a_done_run_reaches_the_renamed_adder_by_its_stored_name_and_session_through_its_feedback_channel(self):
work = self.base / "work"
work.mkdir()
self._add("go", work, "true", "r", "manual")
self._add("later", work, "true", "r", "manual")
self.assertEqual(self._register()["operator/go"]["sessions"], {"One": "s1"})
self._session("s1", "Uno")
radio = REPO_ROOT / "skills" / "kvb-org-radio" / "scripts" / "radio.py"
chosen = subprocess.run([sys.executable, str(radio), "feedback", "set", "call"], capture_output=True, text=True, env=self.env, check=False)
self.assertEqual(chosen.returncode, 0, chosen.stderr)
listener = self.root / "radio-listen" / "s1.pid"
listener.parent.mkdir()
listener.write_text(str(os.getpid()), encoding="utf-8")
result = self._feed("y\ns\n")
self.assertEqual(result.returncode, 0, result.stderr)
self.assertIn("done operator/go; the result went to One as a call", result.stdout)
self.assertIn("skipped operator/later", result.stdout)
self.assertEqual(self._messages(), [("call", "Operator", ["One"], "Operator ran operator/go: done")])
radio = REPO_ROOT / "skills" / "kvb-org-radio" / "scripts" / "radio.py"
seen = subprocess.run([sys.executable, str(radio), "show"], capture_output=True, text=True, env=self.env, check=False)
self.assertEqual([line.split(" ", 3)[3] for line in seen.stdout.splitlines()], ["Operator to One: Operator ran operator/go: done"], seen.stderr)
def test_an_older_row_without_a_session_reaches_its_party_name_and_an_open_check_is_reported(self):
stale = self.base / "stale"
stale.write_text("x", encoding="utf-8")
self._add("old", self.base, "true", "r", f"absent:{stale}")
register = self._register()
register["operator/old"].pop("sessions")
(self.root / "rasci.json").write_text(json.dumps(register), encoding="utf-8")
self._session("s1", "Uno")
result = self._feed("y\n")
self.assertEqual(result.returncode, 0, result.stderr)
pending = f"absent:{stale} does not pass yet; the row stays open"
self.assertIn(f"ran operator/old, but {pending}; the result went to One as a post", result.stdout)
self.assertEqual(self._messages(), [("post", "Operator", ["One"], f"Operator ran operator/old; exit 0, but {pending}")])
self.assertEqual(self._open(), ["operator/old"])
def test_list_and_done_tell_every_holder_but_the_caller(self):
self._session("s2", "Two")
stale = self.base / "stale"
stale.write_text("x", encoding="utf-8")
for slug in ("mine", "theirs"):
self._add(slug, self.base, "true", "r", f"absent:{stale}")
self._add("manual", self.base, "true", "r", "manual")
self._add("hub", self.base, "true", "r", "manual")
self._add("self", self.base, "true", "r", "manual")
stale.unlink()
self.assertEqual(self._out("list", "--json")[0], "[")
self._add("mine", self.base, "true", "r", f"absent:{self.base / 'gone'}")
self.assertEqual(self._as(None, "list", "--session", "s1").stderr, "")
self.assertEqual(self._messages(), [])
self._add("theirs", self.base, "true", "r", f"absent:{self.base / 'gone'}")
listed = self._as("s2", "list", "--json")
self.assertEqual((listed.returncode, listed.stderr), (0, "operator: operator/theirs done; the result went to One as a post\n"))
self.assertEqual([row["task"] for row in json.loads(listed.stdout)], ["operator/manual", "operator/hub", "operator/self"])
self.assertEqual(self._as("s2", "done", "manual").stdout, "done operator/manual; the result went to One as a post\n")
self.assertEqual(self._as("s2", "done", "manual").stdout, "done operator/manual\n")
self.assertEqual(self._as(None, "done", "hub").returncode, 0)
self.assertEqual(self._out("done", "self"), ["done operator/self"])
self.assertEqual(self._messages(), [
("post", "Operator", ["One"], f"operator/theirs done: its check absent:{self.base / 'gone'} passes"),
("post", "Operator", ["One"], "operator/manual marked done by Two"),
("post", "Operator", ["One"], "operator/hub marked done by Operator"),
])
self._add("flag", self.base, "true", "r", "manual")
self.assertEqual(self._as(None, "done", "flag", "--session", "s2").returncode, 0)
self.assertEqual(self._messages()[-1][-1], "operator/flag marked done by Two")
self._add("late", self.base, "true", "r", f"absent:{self.base / 'gone'}")
victim = self.base / "victim"
victim.write_text("keep", encoding="utf-8")
(self.root / "news.lock").unlink()
(self.root / "news.lock").symlink_to(victim)
unsent = self._as("s2", "list")
self.assertEqual(unsent.returncode, 0, unsent.stderr)
self.assertRegex(unsent.stderr, r"^operator: operator/late done; the message to One failed: .+\n$")
self.assertEqual(victim.read_text(encoding="utf-8"), "keep")
def test_failed_stops_only_the_row_the_hub_ran_and_tells_the_adder(self):
work = self.base / "work"
work.mkdir()
self._add("break", work, "false", "r", "manual")
self._add("moved", work, "true", "r", "manual")
shown = ("--command", "false", "--dir", str(work))
result = self._as(None, "failed", "break", "--why", "exit 3", *shown)
self.assertEqual(result.returncode, 0, result.stderr)
self.assertEqual(result.stdout, "failed operator/break: exit 3; removed from the queue, the error went to One as a post\n")
for args in (("--command", "true", "--dir", str(self.base)), ("--command", "echo evil", "--dir", str(work))):
with self.subTest(args=args):
stale = self._as(None, "failed", "moved", "--why", "exit 1", *args)
self.assertIn("it changed or closed meanwhile and stays as it is", stale.stdout)
register = self._register()
self.assertEqual((register["operator/break"]["status"], register["operator/break"]["failed"]), ("stopped", {"why": "exit 3", "output": []}))
self.assertEqual((register["operator/moved"]["status"], "failed" in register["operator/moved"]), ("queued", False))
self.assertEqual(self._messages(), [("post", "Operator", ["One"], (
f"Operator ran operator/break (false in {work}); it failed with exit 3 and left the operator queue. "
"The operator shared no stderr lines. Find the cause, then queue the corrected command with operator.py add break, or drop the step."
))])
again = self._as(None, "failed", "break", "--why", "exit 3", *shown)
self.assertIn("it changed or closed meanwhile and stays as it is", again.stdout)
self.assertEqual(len(self._messages()), 1)
for args in (("failed", "missing", "--why", "exit 1", *shown), ("failed", "break", "--why", " ", *shown), ("failed", "break", "--why", "exit 1")):
with self.subTest(args=args):
self.assertEqual(self._as(None, *args).returncode, 2)
def test_ran_in_the_hub_container_closes_whatever_the_check_and_reaches_the_pinned_session_and_the_stored_name(self):
tool = self.bin / "kvb-host-only-tool"
tool.write_text("#!/bin/sh\n", encoding="utf-8")
tool.chmod(0o755)
self._add("go", self.base, "true", "r", "manual")
self._add("inst", self.base, "true", "r", "binary:kvb-host-only-tool")
self._add("other", self.base, "true", "r", "manual")
radio = REPO_ROOT / "skills" / "kvb-org-radio" / "scripts" / "radio.py"
chosen = subprocess.run([sys.executable, str(radio), "feedback", "set", "call"], capture_output=True, text=True, env=self.env, check=False)
self.assertEqual(chosen.returncode, 0, chosen.stderr)
self._session("s1", "Uno")
hub_home = self.base / "hub-home"
hub_home.mkdir()
hub = {"PATH": "/usr/bin:/bin", "HOME": str(hub_home), "AGENTS_COUNCIL_ROOT": str(self.root)}
def ran(*args: str) -> str:
result = subprocess.run([sys.executable, str(OPERATOR), "ran", *args], capture_output=True, text=True, env=hub, cwd=self.tmp.name, check=False)
self.assertEqual(result.returncode, 0, result.stderr)
return result.stdout
shown = ("--command", "true", "--dir", str(self.base))
wake = "wake: SendMessage to One (session s1)"
self.assertEqual(ran("go", *shown), f"done operator/go; the result went to One queued as a call; {wake}\n")
self.assertEqual(ran("inst", *shown), f"done operator/inst; the result went to One queued as a call; {wake}\n")
self.assertEqual(ran("other", "--command", "true", "--dir", str(hub_home)), "ran operator/other; it changed or closed meanwhile and stays as it is\n")
self.assertEqual(self._open(), ["operator/other"])
self.assertEqual(self._messages(), [
("call", "Operator", ["One"], "Operator ran operator/go: done"),
("call", "Operator", ["One"], "Operator ran operator/inst: done"),
])
rows = [json.loads(line) for line in (self.root / "news.jsonl").read_text(encoding="utf-8").splitlines()]
self.assertEqual([row["to_sessions"] for row in rows], [["s1"], ["s1"]])
self._session("s2", "One")
self._session("s3", "Uno")
expected = ["Operator to One: Operator ran operator/go: done", "Operator to One: Operator ran operator/inst: done"]
for sid, seen in (("s1", expected), ("s2", expected), ("s3", [])):
with self.subTest(sid=sid):
read = subprocess.run([sys.executable, str(radio), "show"], capture_output=True, text=True, env={**self.env, "CLAUDE_CODE_SESSION_ID": sid}, check=False)
self.assertEqual([line.split(" ", 3)[3] for line in read.stdout.splitlines()], seen, read.stderr)
view = (
"import json, sys\n"
"sys.path.insert(0, sys.argv[1])\n"
"from kvb_orchestrator.council import radio_rows\n"
"rows = [json.loads(line) for line in open(sys.argv[2], encoding='utf-8')]\n"
"print(json.dumps([row['to'] for row in radio_rows(rows, 0, 1e12)]))\n"
)
hub_view = subprocess.run(
[sys.executable, "-c", view, str(REPO_ROOT / "orchestrator"), str(self.root / "news.jsonl")],
capture_output=True, text=True, env={**hub, "PYTHONDONTWRITEBYTECODE": "1"}, check=False,
)
self.assertEqual(json.loads(hub_view.stdout or "null"), [["One"], ["One"]], hub_view.stderr)
for args in (("ran", "missing", *shown), ("ran", "go", "--command", "true")):
with self.subTest(args=args):
self.assertEqual(self._as(None, *args).returncode, 2)
def test_done_leaves_out_the_caller_by_session_id_and_by_name_each_on_its_own(self):
self._add("by-sid", self.base, "true", "r", "manual")
self._add("by-name", self.base, "true", "r", "manual")
register = self._register()
register["operator/by-name"].pop("sessions")
(self.root / "rasci.json").write_text(json.dumps(register), encoding="utf-8")
hub_home = self.base / "hub-home"
hub_home.mkdir()
hub = {"PATH": "/usr/bin:/bin", "HOME": str(hub_home), "AGENTS_COUNCIL_ROOT": str(self.root)}
by_sid = subprocess.run([sys.executable, str(OPERATOR), "done", "by-sid", "--session", "s1"], capture_output=True, text=True, env=hub, check=False)
self.assertEqual((by_sid.returncode, by_sid.stdout), (0, "done operator/by-sid\n"), by_sid.stderr)
self.assertEqual(self._out("done", "by-name"), ["done operator/by-name"])
self.assertEqual(self._messages(), [])
def test_done_by_the_successor_holding_the_stored_name_reaches_the_renamed_adder_by_its_session_only(self):
self._add("go", self.base, "true", "r", "manual")
self._session("s1", "Uno")
self._session("s2", "One")
done = self._as("s2", "done", "go")
self.assertEqual((done.returncode, done.stdout), (0, "done operator/go; the result went to s1 as a post\n"), done.stderr)
self.assertEqual(self._messages(), [("post", "Operator", ["s1"], "operator/go marked done by One")])
radio = REPO_ROOT / "skills" / "kvb-org-radio" / "scripts" / "radio.py"
for sid, seen in (("s1", 1), ("s2", 0)):
with self.subTest(sid=sid):
read = subprocess.run([sys.executable, str(radio), "show"], capture_output=True, text=True, env={**self.env, "CLAUDE_CODE_SESSION_ID": sid}, check=False)
self.assertEqual(len(read.stdout.splitlines()), seen, read.stderr)
self._add("own", self.base, "true", "r", "manual")
self.assertEqual(self._as("s1", "done", "own").stdout, "done operator/own\n")
self.assertEqual(len(self._messages()), 1)
def test_ran_closes_a_stopped_or_running_row_the_hub_ran_and_tells_the_adder(self):
for slug in ("stopped", "running", "done"):
self._add(slug, self.base, "true", "r", "manual")
register = self._register()
for slug in ("stopped", "running", "done"):
register[f"operator/{slug}"]["status"] = slug
register["operator/stopped"].update(failed={"why": "exit 1", "output": []}, cancelled="wrong repo")
(self.root / "rasci.json").write_text(json.dumps(register), encoding="utf-8")
shown = ("--command", "true", "--dir", str(self.base))
for slug in ("stopped", "running"):
with self.subTest(slug=slug):
self.assertEqual(self._as(None, "ran", slug, *shown).stdout, f"done operator/{slug}; the result went to One as a post\n")
entry = self._register()[f"operator/{slug}"]
self.assertEqual((entry["status"], "failed" in entry, "cancelled" in entry), ("done", False, False))
self.assertEqual(self._as(None, "ran", "done", *shown).stdout, "ran operator/done; it changed or closed meanwhile and stays as it is\n")
self.assertEqual([message[3] for message in self._messages()], ["Operator ran operator/stopped: done", "Operator ran operator/running: done"])
def test_done_drops_the_stale_failure_of_a_stopped_row_like_ran(self):
self._add("go", self.base, "false", "r", "manual")
self.assertEqual(self._as(None, "failed", "go", "--why", "exit 1", "--command", "false", "--dir", str(self.base)).returncode, 0)
register = self._register()
register["operator/go"]["cancelled"] = "wrong repo"
(self.root / "rasci.json").write_text(json.dumps(register), encoding="utf-8")
self.assertEqual(self._out("done", "go"), ["done operator/go"])
entry = self._register()["operator/go"]
self.assertEqual((entry["status"], "failed" in entry, "cancelled" in entry), ("done", False, False))
def test_feedback_for_an_ended_adder_reaches_the_session_now_holding_its_name(self):
self._add("go", self.base, "true", "r", "manual")
sessions = self.home / ".claude" / "sessions"
(sessions / "s1.json").unlink()
self._session("s2", "One")
self.assertEqual(self._as(None, "failed", "go", "--why", "exit 1", "--command", "true", "--dir", str(self.base)).returncode, 0)
radio = REPO_ROOT / "skills" / "kvb-org-radio" / "scripts" / "radio.py"
seen = subprocess.run([sys.executable, str(radio), "show"], capture_output=True, text=True, env={**self.env, "CLAUDE_CODE_SESSION_ID": "s2"}, check=False)
self.assertEqual(len(seen.stdout.splitlines()), 1, seen.stderr)
self.assertIn("Operator to One: Operator ran operator/go (true in", seen.stdout)
def test_run_needs_shell(self):
self._add("x", self.base, "true", "r", "manual")
result = subprocess.run(
+4 -1
View File
@@ -13,7 +13,10 @@ from pathlib import Path
REPO_ROOT = Path(__file__).resolve().parents[1]
SCRIPT = REPO_ROOT / "scripts" / "orchestrator.sh"
HOST_SCRIPTS = ("kvb-org-organize/scripts/council.py", "kvb-org-organize/scripts/nofollow.py", "kvb-org-rasci/scripts/rasci.py")
HOST_SCRIPTS = (
"kvb-org-organize/scripts/council.py", "kvb-org-organize/scripts/nofollow.py", "kvb-org-rasci/scripts/rasci.py",
"kvb-org-operator/scripts/operator.py", "kvb-org-radio/scripts/radio.py",
)
OLD = "kvb-hub"
NEW = "kvb-orchestrator"
STUB = r'''#!/usr/bin/env python3
+114
View File
@@ -649,6 +649,120 @@ class TestRadio(unittest.TestCase):
self.assertEqual(quiet.returncode, 0)
self.assertIn("council hooks stay off", quiet.stdout)
def test_feedback_is_a_post_unless_the_session_set_call(self):
self.assertEqual(self._send("s2", "feedback", "show"), ["post"])
self.assertEqual(self._send("s2", "feedback", "set", "call"), ["feedback: call"])
self.assertEqual(self._send("x9", "feedback", "set", "post"), ["feedback: post"])
self.assertEqual((self._send("s2", "feedback", "show"), self._send("s3", "feedback", "show")), (["call"], ["post"]))
self.assertEqual(self._send(None, "feedback", "show", "--session", "s2"), ["call"])
self.assertEqual(json.loads((self.root / "feedback.json").read_text(encoding="utf-8")), {"s2": "call", "x9": "post"})
for args in (("feedback", "set", "radio"), ("feedback", "send", "text"), ("feedback", "send", " ", "--to", "Two"), ("feedback",)):
with self.subTest(args=args):
self.assertEqual(self._cli("s1", *args).returncode, 2)
def test_a_pinned_row_reaches_its_session_under_any_name_and_whoever_holds_its_stored_name(self):
self._send("s2", "feedback", "set", "call")
hub_home = self.home.parent / "hub-home"
hub_home.mkdir()
hub = {**self._env(None), "HOME": str(hub_home)}
def send(*args: str) -> subprocess.CompletedProcess:
return subprocess.run(
[sys.executable, str(RADIO), "feedback", "send", "ran x", *args, "--session", "Operator"],
capture_output=True, text=True, env=hub, check=False, timeout=30,
)
self.assertEqual(send("--to", "Two", "--sid", "s2").stdout.splitlines(), ["sent call to Two", "wake: SendMessage to Two (session s2)"])
self.assertEqual(send("--to", "Three", "--sid", "s3").stdout.splitlines(), ["sent post to Three"])
self.assertEqual(send("--to", "Two", "--to", "Three", "--sid", "s2").returncode, 2)
self.assertEqual([(row["class"], row["to"], row["to_sessions"]) for row in self._rows()], [("call", ["Two"], ["s2"]), ("post", ["Three"], ["s3"])])
sessions = self.home / ".claude" / "sessions"
for sid, name in (("s2", "Deux"), ("s3", "Two"), ("s4", "Deux")):
(sessions / f"{sid}.json").write_text(json.dumps({"sessionId": sid, "name": name}), encoding="utf-8")
self.assertEqual(self._send(None, "show", "--all")[0].split(" ", 3)[3], "Operator to Two: ran x")
self.assertEqual(self._prompt("s2"), ["CALL Operator to Two: ran x"])
self.assertEqual(self._prompt("s3"), ["CALL Operator to Two: ran x"])
self.assertEqual(self._mailbox("s3"), (2, ["POST Operator to Three: ran x"]))
self.assertEqual((self._prompt("s4"), self._mailbox("s4")), ([], (0, [])))
self.assertEqual((self._prompt("s1"), self._mailbox("s1")), ([], (0, [])))
self._send("s1", "post", "plain", "--to", "Two")
self.assertNotIn("to_sessions", self._rows()[-1])
def test_a_row_for_an_ended_adder_reaches_whoever_holds_its_stored_name_on_the_adders_channel(self):
sessions = self.home / ".claude" / "sessions"
self._send(None, "feedback", "set", "call", "--session", "s2")
self._send(None, "feedback", "set", "post", "--session", "s3")
(sessions / "s2.json").unlink()
(sessions / "s3.json").write_text(json.dumps({"sessionId": "s3", "name": "Two"}), encoding="utf-8")
self.assertEqual(self._send("s1", "feedback", "send", "ran x", "--to", "Two", "--sid", "s2"), ["sent call to Two", "wake: SendMessage to Two (session s2)"])
self._pidfile("s3").parent.mkdir(parents=True)
self._pidfile("s3").write_text(str(os.getpid()), encoding="utf-8")
self.assertEqual(self._send("s1", "feedback", "send", "ran y", "--to", "Two", "--sid", "s2"), ["sent call to Two"])
self.assertEqual(self._prompt("s3"), ["CALL One to Two: ran x", "CALL One to Two: ran y"])
self.assertEqual(self._prompt("s1"), [])
def test_a_row_pinned_to_a_codex_session_reaches_it_by_its_id(self):
self._send(None, "feedback", "set", "call", "--session", "codex-1")
self.assertEqual(
self._send("s1", "feedback", "send", "ran x", "--to", "Codex", "--sid", "codex-1"),
["sent call to Codex", "wake: SendMessage to Codex (session codex-1)"],
)
self.assertEqual([strip(line) for line in self._send(None, "show", "--session", "codex-1")], ["CALL One to Codex: ran x"])
self.assertEqual(self._send(None, "show", "--session", "codex-2"), [])
def test_a_row_whose_session_ids_are_no_strings_falls_back_to_its_names(self):
self.root.mkdir(mode=0o700)
rows = [
{"from": "X", "to": ["Two"], "to_sessions": sessions, "text": f"t{n}", "class": "post", "v": 2, "ts": time.time() - 10 + n}
for n, sessions in enumerate(([1], [["x"]], None))
]
(self.root / "news.jsonl").write_text("".join(json.dumps(row) + "\n" for row in rows), encoding="utf-8")
(self.root / "news.jsonl").chmod(0o600)
self.assertEqual(self._mailbox("s2"), (2, ["POST X to Two: t0", "POST X to Two: t1", "POST X to Two: t2"]))
self.assertEqual(self._mailbox("s3"), (0, []))
def test_a_row_reaches_its_session_and_its_name_when_no_session_is_known_as_live(self):
self._send("s1", "feedback", "send", "ran x", "--to", "Two", "--sid", "s2")
hub_home = self.home.parent / "hub-home"
hub_home.mkdir()
def shown(session: str) -> list[str]:
done = subprocess.run(
[sys.executable, str(RADIO), "show", "--session", session], capture_output=True, text=True,
env={**self._env(None), "HOME": str(hub_home)}, check=False, timeout=30,
)
self.assertEqual(done.returncode, 0, done.stderr)
return [strip(line) for line in done.stdout.splitlines()]
self.assertEqual((shown("s2"), shown("Two"), shown("s3")), (["POST One to Two: ran x"], ["POST One to Two: ran x"], []))
def test_a_pinned_call_wakes_nobody_while_a_listener_of_its_session_or_its_name_runs(self):
self._pidfile("s2").parent.mkdir(parents=True)
self._pidfile("s2").write_text(str(os.getpid()), encoding="utf-8")
(self.home / ".claude" / "sessions" / "s9.json").write_text(json.dumps({"sessionId": "s9", "name": "Nine"}), encoding="utf-8")
self._send(None, "feedback", "set", "call", "--session", "s9")
self._send("s2", "feedback", "set", "call")
hub_home = self.home.parent / "hub-home"
hub_home.mkdir()
sent = subprocess.run(
[sys.executable, str(RADIO), "feedback", "send", "ran x", "--to", "Two", "--sid", "s2", "--session", "Operator"],
capture_output=True, text=True, env={**self._env(None), "HOME": str(hub_home)}, check=False, timeout=30,
)
self.assertEqual(sent.stdout.splitlines(), ["sent call to Two"], sent.stderr)
self.assertEqual(self._send("s1", "feedback", "send", "ran y", "--to", "Two", "--sid", "s9"), ["sent call to Two"])
self.assertEqual(self._send("s1", "feedback", "send", "ran z", "--to", "Nine", "--sid", "s9"), ["sent call to Nine", "wake: SendMessage to Nine (session s9)"])
def test_feedback_send_without_a_session_takes_the_channel_the_name_set(self):
self._send("s2", "feedback", "set", "call")
self._send(None, "feedback", "set", "call", "--session", "codex-1")
self.assertEqual(
self._send("s1", "feedback", "send", "ran x", "--to", "Two", "--to", "Gone", "--to", "codex-1"),
["sent post to Two", "sent post to Gone", "sent call to codex-1", "wake: SendMessage to codex-1"],
)
self.assertEqual([strip(line) for line in self._send(None, "show", "--session", "codex-1")], ["CALL One to codex-1: ran x"])
self.assertEqual(self._mailbox("s2"), (2, ["POST One to Two: ran x"]))
self.assertNotIn("to_sessions", self._rows()[-1])
if __name__ == "__main__":
unittest.main()