Skip to content

The agent that grows with you

fix(gateway): declare clarify.lock as a canonical verb so the dispatcher checks its params

Tekniumadf44edf03bb
diff --git a/apps/shared/src/gateway-contract.generated.ts b/apps/shared/src/gateway-contract.generated.ts
index 3d4b930f831..408f6110a56 100644
--- a/apps/shared/src/gateway-contract.generated.ts
+++ b/apps/shared/src/gateway-contract.generated.ts
@@ -6688,6 +6688,8 @@ export interface CanonicalRpcMethods {
'a2a.forward': { params: A2aForwardParams; result: A2aForwardResult }
'approval.respond': { params: CanonicalApprovalParams; result: PromptResponseResult }
'bot_relay.deliver': { params: CanonicalBotDeliverParams; result: CanonicalBotDeliverResult }
+ /** Lock one answer of the owner's batch clarify request (editable until every question is locked); only a viewer attached to that session with session:respond may lock. */
+ 'clarify.lock': { params: ClarifyLockParams; result: ClarifyLockResult }
/** Generation-fenced answer to a pending clarify prompt (empty answer = skipped). */
'clarify.respond': { params: ClarifyRespondParams; result: PromptResponseResult }
/** Fire-only: a recognized command the classic CLI or the TUI runs itself; the gateway fires `pre_command` for it in the session's profile after replying (`queued` false: not fired). */
@@ -6759,6 +6761,7 @@ export const CANONICAL_RPC_METHODS = [
'a2a.forward',
'approval.respond',
'bot_relay.deliver',
+ 'clarify.lock',
'clarify.respond',
'command.observe',
'config.get',
diff --git a/apps/shared/src/gateway-contract.openrpc.json b/apps/shared/src/gateway-contract.openrpc.json
index 5fe1c7b2f0a..40cfed7af53 100644
--- a/apps/shared/src/gateway-contract.openrpc.json
+++ b/apps/shared/src/gateway-contract.openrpc.json
@@ -46721,6 +46721,24 @@
}
}
},
+ {
+ "name": "clarify.lock",
+ "summary": "Lock one answer of the owner's batch clarify request (editable until every question is locked); only a viewer attached to that session with session:respond may lock.",
+ "params": [
+ {
+ "name": "params",
+ "schema": {
+ "$ref": "#/components/schemas/ClarifyLockParams"
+ }
+ }
+ ],
+ "result": {
+ "name": "result",
+ "schema": {
+ "$ref": "#/components/schemas/ClarifyLockResult"
+ }
+ }
+ },
{
"name": "clarify.respond",
"summary": "Generation-fenced answer to a pending clarify prompt (empty answer = skipped).",
diff --git a/gateway/session_clarify_lock.py b/gateway/session_clarify_lock.py
index e1d9a99697d..a9891acca3a 100644
--- a/gateway/session_clarify_lock.py
+++ b/gateway/session_clarify_lock.py
@@ -12,16 +12,14 @@ 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, owned_by
- request_id, question_id = params.get('request_id'), params.get('question_id')
+ # The dispatcher already refused unknown keys and mistyped fields against the declared
+ # ``ClarifyLockParams`` (``tui_gateway/contracts/canonical.py``); a missing or empty id is ours to refuse.
# ``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)))):
+ request_id, question_id = params.get('request_id'), params.get('question_id')
+ if not isinstance(request_id, str) or not request_id or not isinstance(question_id, str) or not question_id:
raise RuntimeStoreError('invalid_params')
answer = params.get('answer', '')
if answer is not None and not isinstance(answer, str):
diff --git a/tests/gateway/test_clarify_lock_owner.py b/tests/gateway/test_clarify_lock_owner.py
index 2335ff82c03..b8695ae7c34 100644
--- a/tests/gateway/test_clarify_lock_owner.py
+++ b/tests/gateway/test_clarify_lock_owner.py
@@ -165,3 +165,33 @@ async def test_another_profiles_viewer_of_the_same_session_id_cannot_answer(tmp_
finally:
await own.close()
await foreign.close()
+
+
+async def test_clarify_lock_params_are_checked_by_the_declared_canonical_contract(tmp_path, monkeypatch):
+ """``clarify.lock`` is a declared ``CANONICAL_METHODS`` verb: the dispatcher refuses an unknown key or a
+ mistyped field from ``ClarifyLockParams`` (``4001`` naming the field) before the handler runs."""
+ from gateway.session_controls import AuthorityConnection
+ from tui_gateway.contracts.registry import CANONICAL_METHODS
+ from tui_gateway.contracts.prompt_voice import ClarifyLockParams, ClarifyLockResult
+
+ assert CANONICAL_METHODS['clarify.lock'].params is ClarifyLockParams
+ assert CANONICAL_METHODS['clarify.lock'].result is ClarifyLockResult
+
+ async def answer(event):
+ return 'ok'
+ authority = await _authority(tmp_path, monkeypatch, answer)
+ connection = AuthorityConnection(authority, object(), {'user_id': 'owner'})
+ try:
+ extra = await connection.dispatch({'id': 1, 'method': 'clarify.lock', 'params': {
+ 'request_id': 'srq-x', 'question_id': 'q0', 'answer': 'a', 'bogus': 1}})
+ assert extra['error']['data'] == {'reason': 'invalid_params', 'fields': ['bogus']}, extra
+ typed = await connection.dispatch({'id': 2, 'method': 'clarify.lock', 'params': {
+ 'request_id': 7, 'question_id': 'q0'}})
+ assert typed['error']['data'] == {'reason': 'invalid_params', 'fields': ['request_id']}, typed
+ # A well-formed lock for a request nobody waits on is still the handler's own ``expired``.
+ late = await connection.dispatch({'id': 3, 'method': 'clarify.lock', 'params': {
+ 'request_id': 'srq-x', 'question_id': 'q0', 'answer': None}})
+ assert late['result'] == {'status': 'expired'}, late
+ finally:
+ await connection.close()
diff --git a/tui_gateway/contracts/canonical.py b/tui_gateway/contracts/canonical.py
index e36623ee1d1..e4dfe831ded 100644
--- a/tui_gateway/contracts/canonical.py
+++ b/tui_gateway/contracts/canonical.py
@@ -15,6 +15,7 @@ from .base import JsonValue, Params, Result
from .common import McpServerStatus, OpenModel, ProjectRef
from .events import SkinPayload
from .groups_bot_relay import RoomParams, RoomTaskReceipt
+from .prompt_voice import ClarifyLockParams, ClarifyLockResult
from .registry import canonical_method
# ── admissions ────────────────────────────────────────────────────────────────────────────────
@@ -341,6 +342,12 @@ class PromptResponseResult(Result):
canonical_method("clarify.respond", params=ClarifyRespondParams, result=PromptResponseResult,
doc="Generation-fenced answer to a pending clarify prompt (empty answer = skipped).")
+# The owner serves the sidecar's ``clarify.lock`` wire unchanged (``gateway/session_clarify_lock.py``):
+# declaring it here lets the dispatcher refuse a mistyped or unknown key before the handler runs.
+canonical_method("clarify.lock", params=ClarifyLockParams, result=ClarifyLockResult,
+ doc="Lock one answer of the owner's batch clarify request (editable until every question is "
+ "locked); only a viewer attached to that session with session:respond may lock.")
+
# ── cron / kanban / a2a producers ─────────────────────────────────────────────────────────────