Files
skills/orchestrator/kvb_orchestrator/asking.py
T
Kevin Veen-BirkenbachandClaude Opus 5.5 af3555e88b feat(orchestrator): reveal withheld diff content under a passkey signature (019)
staged_diff masks only the secret rule hits and seals each masked file's clear patch apart; reviews and asks store the sealed patches next to their diff, delete them once the item leaves pending, and the hub sweeps orphans. POST /api/diffs/<kind>/<id>/reveal/sign and /reveal hand the clear patches to a signed request; page-diff.js offers Reveal per hidden file and Reveal all, keeps the clear text in the page only and forgets it once the item leaves the inbox. Requirement 019, unit, hub and e2e tests.

Accepted MEDUSA false positives (security.py accept after kvb-think-criticize, 2026-11-17): approval.py FTSCAN-231 WEB-SSRF RH005; permission_hook.py MM-SCAN-058 WEB-SSRF RH005; staged_diff.py SAST-ENV-001 AI-BACKDOOR-006 B603; hub.py MEX-SCAN-1167 INF-SCAN-589; page-load.js EXA002; hub_case.py TC001-TC009 INF-SCAN-2057/2206/2440/2457 EXA002 EXA006 PL002 B603 FTSC-SCAN-089.

🎯 Fix: 92 %
💥 Break: 4 %
💸 Tokens: –
⏱️ Velocity: –
🛡️ Security: 100 %
🏆 Score: 88
🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 %

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 19:04:35 +00:00

143 lines
6.5 KiB
Python

from __future__ import annotations
import time
from .choosing import EVERYONE, answer_text
from .diffs import sealed_file, store_diff, store_sealed, valid_diff, valid_sealed
from .errors import Conflict, Missing, ToolError
from .fields import (
COMMAND_LIMIT,
PATH_LIMIT,
WAIT_CAP,
bounded,
decode,
expect,
field,
instant,
message_text,
seconds,
visible,
)
from .signed import ask_signed
ASK_LIFETIME = 3600
DESCRIPTION_LIMIT = 1000
OPTION_LIMIT = 12
ASK_TEXTS = {"command": COMMAND_LIMIT, "cwd": PATH_LIMIT, "session": 200, "agent": 200}
ANSWERS = {"allow": "allowed", "deny": "denied"}
def ask_state(ask: dict, now: float) -> dict:
status = "expired" if ask["status"] == "pending" and ask["expires"] <= now else ask["status"]
return {"id": ask["id"], "status": status, "decided": ask["decided"], "proof": ask.get("proof"), "channel": ask.get("channel", ""), "reason": ask.get("reason", ""), "to": ask.get("to", "")}
def ask_row(ask: dict, names: dict[str, str]) -> dict:
keys = ("id", "tool", "command", "cwd", "session", "created_ts", "expires")
return {**{key: ask[key] for key in keys}, "agent": names.get(ask["session"], ""), "subagent": ask["agent"]}
def decision_state(decision: dict) -> dict:
"""Returns:
The status and choice, with the id and text of the operator's
passkey-signed answer when a click chose it, else None for both.
"""
message = decision.get("message")
answer = None if message is None else answer_text(decision, decision["choice"])
return {**{key: decision[key] for key in ("id", "status", "choice", "decided")}, "message": message, "answer": answer}
def decision_row(decision: dict) -> dict:
return {key: decision[key] for key in ("id", "question", "options", "agent", "created_ts")}
def option_of(option: object) -> dict:
if not isinstance(option, dict):
raise ToolError("every option must be an object with label and description")
expect(option, ("label", "description"))
label = field(option, "label").strip()
description = bounded(option, "description", DESCRIPTION_LIMIT).strip()
visible({"description": description})
return {"label": label, "description": description}
class Asking:
def ask(self, body: bytes) -> dict:
payload = decode(body)
diff = valid_diff(payload.pop("diff")) if "diff" in payload else None
sealed = valid_sealed(payload.pop("sealed"), diff) if "sealed" in payload else {}
expect(payload, ("tool", *ASK_TEXTS, "timeout"))
values = {name: bounded(payload, name, limit) for name, limit in ASK_TEXTS.items()}
visible(values)
lifetime = seconds(payload, "timeout", ASK_LIFETIME)
created = time.time()
fields = {**values, "tool": field(payload, "tool").strip(), "status": "pending", "decided": None, "proof": None, "diff_files": None if diff is None else len(diff)}
with self.asks.changed:
ask_id = self.asks.fresh()
if diff is not None:
store_diff(self.reviews.pages, "ask", ask_id, diff)
if sealed:
store_sealed(self.reviews.pages, "ask", ask_id, sealed)
record = self.asks.insert(ask_id, {**fields, "created_ts": created, "expires": created + lifetime})
self.automate("ask", record)
return {"id": record["id"], "status": record["status"]}
def ask_wait(self, ask_id: str, query: dict[str, list[str]]) -> dict:
wait = instant(query, "wait")
record = self.asks.get(ask_id)
if record is None:
raise Missing(ask_id)
left = max(record["expires"] - time.time(), 0.0)
record = self.asks.wait(ask_id, min(wait or 0.0, WAIT_CAP, left))
state = ask_state(record, time.time())
if state["status"] == "expired":
sealed_file(self.reviews.pages, "ask", ask_id).unlink(missing_ok=True)
return state
def settle(self, kind_name: str, item_id: str, verb: str, body: bytes) -> dict:
if kind_name == "asks" and verb in ANSWERS:
record = self.asks.get(item_id)
if record is None:
raise Missing(item_id)
if ask_state(record, time.time())["status"] == "expired":
raise Conflict(ask_state(record, time.time()))
proof = None
if verb == "allow":
payload = decode(body)
expect(payload, ("proof",))
proof = self.covered(payload["proof"], [ask_signed(record)], time.time())
decided, changed = self.asks.decide(item_id, {"status": ANSWERS[verb], "proof": proof})
if not changed:
raise Conflict(ask_state(decided, time.time()))
return ask_state(decided, time.time())
raise Missing(verb)
def decision_request(self, arguments: dict) -> dict:
expect(arguments, ("question", "options", "agent", "recommended"))
question = message_text(arguments, "question")
visible({"question": question})
options = arguments["options"]
if not isinstance(options, list) or not 1 <= len(options) <= OPTION_LIMIT:
raise ToolError(f"options must be a list of 1 to {OPTION_LIMIT} objects")
parsed = [option_of(option) for option in options]
if len({option["label"] for option in parsed}) != len(parsed):
raise ToolError("option labels must be distinct")
recommended = arguments["recommended"]
if not isinstance(recommended, str) or recommended.strip() not in ["", *(option["label"] for option in parsed)]:
raise ToolError("recommended must be one of the option labels or an empty string")
asker = field(arguments, "agent").strip()
if EVERYONE in asker:
raise ToolError(f"agent names the asking agent, never a name with {EVERYONE}")
fields = {"question": question, "options": parsed, "agent": asker, "recommended": recommended.strip()}
record = self.decisions.add({**fields, "status": "pending", "choice": None, "decided": None, "created_ts": time.time()})
self.automate("decision", record)
return {"id": record["id"], "status": record["status"], "url": self.url()}
def decision_wait(self, arguments: dict) -> dict:
expect(arguments, ("id", "timeout_seconds"))
decision_id = field(arguments, "id")
record = self.decisions.wait(decision_id, seconds(arguments, "timeout_seconds", WAIT_CAP))
if record is None:
raise ToolError(f"no decision {decision_id}")
return decision_state(record)