Skip to content

The agent that grows with you

fix(gateway): serve clarify.lock so TUI/Desktop can answer a clarify batch

Teknium5ee7fa8dd8c4
diff --git a/gateway/session_clarify_batch.py b/gateway/session_clarify_batch.py
index 960f6b63850..16afdeda66a 100644
--- a/gateway/session_clarify_batch.py
+++ b/gateway/session_clarify_batch.py
@@ -25,8 +25,10 @@ def ask_clarify_batch(turn, questions) -> dict:
return {"answers": {}, "outcome": "cancelled"}
wire = [{key: entry.get(key) for key in _QUESTION_KEYS if entry.get(key) is not None} for entry in questions]
timeout = get_clarify_timeout()
+ # ``qids``: the viewer's batch panel locks each answer with ``clarify.lock`` (#140400).
result = ask_viewer_result(live.event_stream, session_id, "clarify", {"questions": wire},
- cancelled=interrupted, timeout=timeout if timeout > 0 else None)
+ cancelled=interrupted, timeout=timeout if timeout > 0 else None,
+ qids=[entry["qid"] for entry in questions])
if result is None:
return {"answers": {}, "outcome": "cancelled" if interrupted() else "timed_out"}
answers = result.get("answers")
diff --git a/gateway/session_clarify_lock.py b/gateway/session_clarify_lock.py
new file mode 100644
index 00000000000..aaab65c0d21
--- /dev/null
+++ b/gateway/session_clarify_lock.py
@@ -0,0 +1,45 @@
+"""``clarify.lock`` on the session owner (#140400).
+
+The owner sends a local viewer's clarify batch as one ``clarify`` server request
+(``gateway/session_clarify_batch.py``). Ink's batch panel and Desktop's batch card answer it one
+question at a time with ``clarify.lock {request_id, question_id, answer}`` (``ClarifyLockParams`` /
+``ClarifyLockResult``), as they did against main's sidecar; the owner had no such verb, so every
+answer was refused as an unknown method and the turn waited out ``clarify_timeout``. Only a viewer
+attached to the request's session with ``session:respond`` may lock its answers.
+"""
+import json
+
+from gateway.session_contract import SessionRef
+from hermes_state_runtime import RuntimeStoreError
+
+_FIELDS = frozenset({'request_id', 'question_id', 'answer', 'profile'})
+
+
+async def clarify_lock(connection, ref, params):
+ from gateway.session_sudo_prompt import lock_answer
+ request_id, question_id = params.get('request_id'), params.get('question_id')
+ # ``profile`` naming another served profile was routed to its owner by ``dispatch``.
+ if (set(params) - _FIELDS or not isinstance(request_id, str) or not request_id
+ or not isinstance(question_id, str) or not question_id
+ or not isinstance(params.get('profile', ''), (str, type(None)))):
+ raise RuntimeStoreError('invalid_params')
+ answer = params.get('answer', '')
+ if answer is not None and not isinstance(answer, str):
+ answer = json.dumps(answer, ensure_ascii=False)
+ authority, actor = connection.authority, connection.actor
+
+ def entitled(session_id):
+ try:
+ authority.authorize(actor, SessionRef(authority.profile_id, session_id), 'session:respond')
+ except RuntimeStoreError:
+ return False
+ live = authority.sessions.get(session_id)
+ return live is not None and actor in live.subscribers.values()
+ try:
+ remaining = lock_answer(request_id, question_id, answer, session_ok=entitled)
+ except ValueError:
+ raise RuntimeStoreError('invalid_params') from None
+ if remaining is None:
+ # The wait already ended (timeout / cancel) while the card was still visible: not an error.
+ return {'status': 'expired'}
+ return {'status': 'ok', 'remaining': remaining}
diff --git a/gateway/session_controls.py b/gateway/session_controls.py
index 1e50687d966..6b2f3ef7054 100644
--- a/gateway/session_controls.py
+++ b/gateway/session_controls.py
@@ -188,6 +188,8 @@ class AuthorityConnection:
handlers['session.automation'] = partial(automation, self)
from gateway.session_reactions import react
handlers['message.react'] = partial(react, self)
+ from gateway.session_clarify_lock import clarify_lock
+ handlers['clarify.lock'] = partial(clarify_lock, self)
from gateway.session_control_actions import control
handlers['session.control'] = partial(control, self)
return handlers
diff --git a/gateway/session_sudo_prompt.py b/gateway/session_sudo_prompt.py
index 97bf74a06be..e50aaaebc4f 100644
--- a/gateway/session_sudo_prompt.py
+++ b/gateway/session_sudo_prompt.py
@@ -22,13 +22,16 @@ _POLL_S = 0.25
class _Pending:
- __slots__ = ("event", "result", "session_id", "value")
+ __slots__ = ("event", "locked", "qids", "result", "session_id", "value")
- def __init__(self, session_id):
+ def __init__(self, session_id, qids=None):
self.event = threading.Event()
self.session_id = session_id
self.value = ""
self.result = None
+ # A batch clarify: its question ids and the answers ``clarify.lock`` has locked so far.
+ self.qids = tuple(qids) if qids else None
+ self.locked = {}
_lock = threading.Lock()
@@ -50,6 +53,11 @@ def resolve(frame, *, session_ok=lambda session_id: True) -> bool:
return False
_open.pop(frame["id"], None)
result = frame.get("result") if "error" not in frame else None
+ if pending.qids is not None and pending.locked and isinstance(result, dict):
+ # Answers locked early belong to the final set even when the closing frame omits them
+ # (a cancel after two locks keeps those two), as main's ``server_requests`` merged them.
+ answers = result.get("answers") if isinstance(result.get("answers"), dict) else {}
+ result = {**result, "answers": {**pending.locked, **answers}}
value = result.get("value") if isinstance(result, dict) else ""
pending.value = value if isinstance(value, str) else ""
pending.result = result if isinstance(result, dict) else None
@@ -70,18 +78,41 @@ def ask_viewer(events, session_id, method, params, *, cancelled=lambda: False, t
return pending.value if pending is not None else ""
-def ask_viewer_result(events, session_id, method, params, *, cancelled=lambda: False, timeout=SUDO_TIMEOUT_S):
+def ask_viewer_result(events, session_id, method, params, *, cancelled=lambda: False, timeout=SUDO_TIMEOUT_S,
+ qids=None):
"""The same round trip for a structured answer (``clarify``: ``ClarifyResult``): the viewer's
- ``result`` dict, or None on interrupt, timeout, an error response or no attached viewer."""
- pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout)
+ ``result`` dict, or None on interrupt, timeout, an error response or no attached viewer.
+ ``qids`` makes it a batch: ``lock_answer`` (the ``clarify.lock`` verb) answers it per question."""
+ pending = _ask(events, session_id, method, params, cancelled=cancelled, timeout=timeout, qids=qids)
return pending.result if pending is not None else None
-def _ask(events, session_id, method, params, *, cancelled, timeout):
+def lock_answer(request_id, question_id, answer, *, session_ok=lambda session_id: False):
+ """Lock one answer of an open batch request (``clarify.lock``; editable until the last lock;
+ ``None`` = skipped). Returns the question ids still unanswered; the lock that empties it settles
+ the request with ``{answers, outcome: submitted}``. ``None`` when no open batch has that id or the
+ caller may not answer its session (expired or foreign); ``ValueError`` for an unknown question id."""
+ with _lock:
+ pending = _open.get(request_id)
+ if pending is None or pending.qids is None or not session_ok(pending.session_id):
+ return None
+ if question_id not in pending.qids:
+ raise ValueError(question_id)
+ pending.locked[question_id] = answer
+ remaining = [qid for qid in pending.qids if qid not in pending.locked]
+ if not remaining:
+ _open.pop(request_id, None)
+ pending.result = {"answers": dict(pending.locked), "outcome": "submitted"}
+ if not remaining:
+ pending.event.set()
+ return remaining
+
+
+def _ask(events, session_id, method, params, *, cancelled, timeout, qids=None):
if not events.fanout.transports():
return None
request_id = f"srq-{uuid.uuid4().hex[:12]}"
- pending = _Pending(session_id)
+ pending = _Pending(session_id, qids)
with _lock:
_open[request_id] = pending
events.fanout.write({"jsonrpc": "2.0", "id": request_id, "method": method,
diff --git a/tests/gateway/fixtures/authority_clarify_lock_peer.py b/tests/gateway/fixtures/authority_clarify_lock_peer.py
new file mode 100644
index 00000000000..037538c5e13
--- /dev/null
+++ b/tests/gateway/fixtures/authority_clarify_lock_peer.py
@@ -0,0 +1,143 @@
+"""#140400 end to end: a `hermes chat`-shaped turn's clarify batch answered from a second viewer.
+
+Real GatewayRunner + session API WebSocket, a loopback model asking two questions, the real clarify
+tool. Socket A creates a ``cli`` session and submits with ``clarify_batch`` (what GatewayAgent sends);
+socket B (the Ink TUI / Desktop window) gets the one ``clarify`` server request and answers it per
+question with ``clarify.lock``, the verb those windows send.
+"""
+import asyncio
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import json
+import os
+from pathlib import Path
+import threading
+import traceback
+import time
+
+
+class ModelPeer(BaseHTTPRequestHandler):
+ def log_message(self, *args):
+ pass
+
+ def do_GET(self):
+ self.send_response(200)
+ self.end_headers()
+ self.wfile.write(b'{"data": []}')
+
+ def do_POST(self):
+ body = json.loads(self.rfile.read(int(self.headers['Content-Length'])))
+ messages = body.get('messages', [])
+ self.server.requests.append(messages)
+ asking = bool(messages) and not any(m['role'] == 'tool' for m in messages)
+ message = {'role': 'assistant', 'content': 'CLARIFY_FINISHED'}
+ if asking:
+ message = {'role': 'assistant', 'content': None, 'tool_calls': [{
+ 'index': 0, 'id': 'owned-clarify', 'type': 'function', 'function': {
+ 'name': 'clarify', 'arguments': json.dumps({'questions': [
+ {'question': 'Pick a color', 'choices': ['blue', 'green']},
+ {'question': 'Pick a size'}]})}}]}
+ self.send_response(200)
+ self.send_header('Content-Type', 'text/event-stream' if body.get('stream') else 'application/json')
+ self.end_headers()
+ if body.get('stream'):
+ for delta, finish in [(message, None), ({}, 'tool_calls' if asking else 'stop')]:
+ frame = {'id': 'local', 'object': 'chat.completion.chunk', 'created': 1,
+ 'model': 'local', 'choices': [{'index': 0, 'delta': delta, 'finish_reason': finish}]}
+ self.wfile.write(('data: ' + json.dumps(frame) + '\n\n').encode())
+ self.wfile.write(b'data: [DONE]\n\n')
+ else:
+ self.wfile.write(json.dumps({'id': 'local', 'choices': [{'index': 0, 'message': message,
+ 'finish_reason': 'tool_calls' if asking else 'stop'}]}).encode())
+ self.wfile.flush()
+
+
+async def probe(peer):
+ import websockets
+ from gateway.run import GatewayRunner
+ from gateway.run_api import start_gateway_api, stop_gateway_api
+ from gateway.session_authority import initialize_session_authority
+ from hermes_cli import web_server
+
+ runner = GatewayRunner()
+ authority = await initialize_session_authority(runner, profile_id=os.environ['HERMES_HOME'], instance_id='lock')
+ api = await start_gateway_api(runner)
+ url = api.api_origin.replace('http:', 'ws:') + '/api/ws?token=' + web_server._SESSION_TOKEN
+ frames = {}
+
+ async def rpc(ws, rid, method, **params):
+ await ws.send(json.dumps({'jsonrpc': '2.0', 'id': rid, 'method': method, 'params': params}))
+ async with asyncio.timeout(20):
+ while True:
+ frame = json.loads(await ws.recv())
+ frames.setdefault(id(ws), []).append(frame)
+ if frame.get('id') == rid and 'method' not in frame:
+ return frame
+
+ async def server_request(ws, method):
+ for frame in frames.get(id(ws), []):
+ if frame.get('method') == method and isinstance(frame.get('id'), str):
+ return frame
+ async with asyncio.timeout(20):
+ while True:
+ frame = json.loads(await ws.recv())
+ frames.setdefault(id(ws), []).append(frame)
+ if frame.get('method') == method and isinstance(frame.get('id'), str):
+ return frame
+
+ a = b = None
+ sid = None
+ try:
+ a, b = await websockets.connect(url), await websockets.connect(url)
+ created = await rpc(a, 1, 'session.create', source='cli', request_id='create-1', cwd=os.getcwd())
+ assert 'result' in created, created
+ sid = created['result']['session_id']
+ assert 'result' in await rpc(b, 1, 'session.resume', session_id=sid)
+ submitted = await rpc(a, 2, 'prompt.submit', session_id=sid, input_id='ask-1', text='Ask me',
+ clarify_batch=True)
+ assert 'result' in submitted, submitted
+ request = await server_request(b, 'clarify')
+ rid, questions = request['id'], request['params']['questions']
+ assert [q['question'] for q in questions] == ['Pick a color', 'Pick a size'], questions
+ first = await rpc(b, 3, 'clarify.lock', request_id=rid, question_id=questions[0]['qid'], answer='green')
+ assert first.get('result', {}).get('remaining') == [questions[1]['qid']], first
+ last = await rpc(b, 4, 'clarify.lock', request_id=rid, question_id=questions[1]['qid'], answer='large')
+ assert last.get('result') == {'status': 'ok', 'remaining': []}, last
+ await asyncio.wait_for(authority.sessions[sid].task, 20)
+ tools = [m for messages in peer.requests for m in messages if m['role'] == 'tool']
+ dumped = json.dumps(tools)
+ assert 'green' in dumped and 'large' in dumped and 'submitted' in dumped, tools
+ Path(os.environ['HERMES_HOME'], 'lock-passed').write_text('both locked answers reached the real model')
+ finally:
+ task = authority.sessions[sid].task if sid in authority.sessions else None
+ if task is not None and not task.done():
+ task.cancel()
+ for ws in (a, b):
+ if ws is not None:
+ await ws.close()
+ await stop_gateway_api(api)
+
+
+def main():
+ peer = ThreadingHTTPServer(('127.0.0.1', 0), ModelPeer)
+ peer.requests = []
+ threading.Thread(target=peer.serve_forever, daemon=True).start()
+ url = f'http://127.0.0.1:{peer.server_port}/v1'
+ os.environ.update(OPENAI_API_KEY='loopback-only', OPENAI_BASE_URL=url)
+ Path(os.environ['HERMES_HOME'], 'config.yaml').write_text(
+ f'model:\n default: local\n provider: custom\n base_url: {url}\n'
+ 'agent:\n clarify_timeout: 25\nauxiliary:\n title_generation:\n enabled: false\n')
+ try:
+ asyncio.run(probe(peer))
+ finally:
+ peer.shutdown()
+ peer.server_close()
+
+
+if __name__ == '__main__':
+ status = 0
+ try:
+ main()
+ except BaseException:
+ traceback.print_exc()
+ status = 1
+ os._exit(status)
diff --git a/tests/gateway/test_clarify_lock_owner.py b/tests/gateway/test_clarify_lock_owner.py
new file mode 100644
index 00000000000..d915bff1fcd
--- /dev/null
+++ b/tests/gateway/test_clarify_lock_owner.py
@@ -0,0 +1,126 @@
+"""#140400: the batch ``clarify`` request a local viewer gets is answered with ``clarify.lock``.
+
+Ink's batch panel and Desktop's batch card lock each answer with ``clarify.lock {request_id,
+question_id, answer}``. The owner's ``AuthorityConnection.dispatch`` had no such verb (``-32601
+unknown method``), so every answer was refused and the turn sat out ``clarify_timeout``. Driven
+through the real dispatcher against a real ``ask_clarify_batch`` wait.
+"""
+import asyncio
+import os
+from pathlib import Path
+import subprocess
+import sys
+import threading
+from types import SimpleNamespace
+
+import pytest
+
+from gateway.config import Platform
+from tests.gateway.test_surface_admission import _authority
+
+QUESTIONS = [{'qid': 'q0', 'question': 'colour?', 'choices': ['red', 'blue'], 'multi_select': False},
+ {'qid': 'q1', 'question': 'size?', 'choices': None, 'multi_select': False}]
+
+
+class _Peer:
+ def __init__(self):
+ self.frames = []
+
+ def write(self, frame):
+ self.frames.append(frame)
+ return True
+
+ def close(self):
+ pass
+
+
+async def _wait_for(predicate, timeout=5.0):
+ loop = asyncio.get_running_loop()
+ deadline = loop.time() + timeout
+ while not predicate():
+ assert loop.time() < deadline
+ await asyncio.sleep(0.01)
+
+
+def _start_batch(authority):
+ from gateway.session_clarify_batch import ask_clarify_batch
+ peer = _Peer()
+ authority.sessions['s'].event_stream.fanout.attach(peer)
+ turn = SimpleNamespace(_approval_owner=(authority, 's', 1), _ctx=SimpleNamespace(
+ source=SimpleNamespace(platform=Platform.LOCAL), agent_holder=[SimpleNamespace(_interrupt_requested=False)]))
+ out = {}
+ worker = threading.Thread(target=lambda: out.update(ask_clarify_batch(turn, QUESTIONS)), daemon=True)
+ worker.start()
+ return peer, worker, out
+
+
+async def _lock(connection, rid, qid, answer, n):
+ return await connection.dispatch({'id': n, 'method': 'clarify.lock', 'params': {
+ 'request_id': rid, 'question_id': qid, 'answer': answer}})
+
+
+async def test_clarify_lock_answers_the_owner_batch_request(tmp_path, monkeypatch):
+ from gateway.session_controls import AuthorityConnection
+
+ async def answer(event):
+ return 'ok'
+ authority = await _authority(tmp_path, monkeypatch, answer)
+ connection = AuthorityConnection(authority, object(), {'user_id': 'owner'})
+ try:
+ await connection.dispatch({'id': 1, 'method': 'session.resume', 'params': {'session_id': 's'}})
+ peer, worker, out = _start_batch(authority)
+ await _wait_for(lambda: any(f.get('method') == 'clarify' for f in peer.frames))
+ rid = next(f['id'] for f in peer.frames if f.get('method') == 'clarify')
+
+ first = await _lock(connection, rid, 'q0', 'blue', 2)
+ assert first.get('result') == {'status': 'ok', 'remaining': ['q1']}, first
+ # Revisit before the last lock: the newer answer wins.
+ assert (await _lock(connection, rid, 'q0', 'red', 3))['result']['remaining'] == ['q1']
+ unknown = await _lock(connection, rid, 'zz', 'x', 4)
+ assert unknown['error']['message'] == 'invalid_params', unknown
+ last = await _lock(connection, rid, 'q1', None, 5)
+ assert last.get('result') == {'status': 'ok', 'remaining': []}, last
+ await asyncio.to_thread(worker.join, 5)
+ assert out == {'answers': {'q0': 'red', 'q1': None}, 'outcome': 'submitted'}
+ late = await _lock(connection, rid, 'q1', 'late', 6)
+ assert late.get('result') == {'status': 'expired'}, late
+ finally:
+ await connection.close()
+
+
+async def test_a_viewer_without_the_session_cannot_lock_its_answers(tmp_path, monkeypatch):
+ from gateway.session_controls import AuthorityConnection
+ from gateway.session_sudo_prompt import resolve
+
+ async def answer(event):
+ return 'ok'
+ authority = await _authority(tmp_path, monkeypatch, answer)
+ outsider = AuthorityConnection(authority, object(), {'user_id': 'someone-else'})
+ try:
+ peer, worker, out = _start_batch(authority)
+ await _wait_for(lambda: any(f.get('method') == 'clarify' for f in peer.frames))
+ rid = next(f['id'] for f in peer.frames if f.get('method') == 'clarify')
+ refused = await _lock(outsider, rid, 'q0', 'red', 2)
+ assert refused.get('result') == {'status': 'expired'}, refused
+ resolve({'jsonrpc': '2.0', 'id': rid, 'result': {}}) # the session's own viewer cancels
+ await asyncio.to_thread(worker.join, 5)
+ assert out['answers'] == {}
+ finally:
+ await outsider.close()
+
+
+def test_cli_turn_batch_answered_by_clarify_lock_from_a_second_viewer_end_to_end(tmp_path):
+ """Real gateway process path: the locked answers reach the real model's tool result."""
+ home, state = tmp_path / 'home', tmp_path / 'state'
+ home.mkdir()
+ state.mkdir()
+ repo = Path(__file__).resolve().parents[2]
+ env = {key: os.environ[key] for key in ('PATH', 'LANG', 'TZ') if key in os.environ}
+ env.update(HOME=str(home), USERPROFILE=str(home), HERMES_HOME=str(state), PYTHONPATH=str(repo))
+ result = subprocess.run(
+ [sys.executable, str(Path(__file__).parent / 'fixtures' / 'authority_clarify_lock_peer.py')],
+ cwd=tmp_path, env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=90, check=False)
+ assert result.returncode == 0, result.stdout + result.stderr
+ assert (state / 'lock-passed').read_text() == 'both locked answers reached the real model'