ODS V3 Pre-Release: Public testing and refinement ahead of the official V3 launch. Turn your PC, Mac, or Linux box into a private AI server.
Python ai-agentsamdcomfyuidockerllama-cppllmlocal-ain8nnvidiaopen-webuiragself-hostedspeech-to-textstrix-halotext-to-speechworkflow-automation
fix(model-router): a fixable tool-call mistake gets told and retried instead of ending the turn (#8199)
Mike Bradleyaeda4e7e859e
diff --git a/ods/extensions/services/model-router/app/main.py b/ods/extensions/services/model-router/app/main.pyindex 30ce5aecd..8500cc1c9 100644--- a/ods/extensions/services/model-router/app/main.py+++ b/ods/extensions/services/model-router/app/main.py@@ -24,6 +24,7 @@ from __future__ import annotationsimport asyncioimport base64+import copyimport hashlibimport hmacimport json@@ -40,7 +41,7 @@ from typing import Any, AsyncIteratorimport anyioimport httpxfrom jsonschema import validators as jsonschema_validators-from jsonschema.exceptions import SchemaError, ValidationError+from jsonschema.exceptions import SchemaError, ValidationError, best_matchfrom fastapi import FastAPI, Request, Responsefrom fastapi.responses import JSONResponse, StreamingResponsefrom .completed_tool_sse import (@@ -336,6 +337,303 @@ def _repaired_tool_decision_invalid(return False+# A rejected tool decision is described by its shape only, for the router log+# and for the repair feedback: function names, the JSON Schema keyword that+# failed, the path to that point and argument key names. Argument values never+# appear in either; they can carry page or prompt text. The feedback names only+# what the request's own tool schemas declare.+_DIAGNOSTIC_NAME = re.compile(r"[A-Za-z0-9_.:-]{1,64}")+_MAX_DIAGNOSTIC_NAMES = 16+# A complete call whose only fault is its arguments against the offered+# function's schema can be repaired a second time; a model often fixes such a+# call once it is told which rule failed. Any other rejection keeps one repair.+_SCHEMA_REPAIR_LIMIT = 2+_BOUND_RULES = {"minLength", "maxLength", "minItems", "maxItems", "minimum", "maximum",+ "exclusiveMinimum", "exclusiveMaximum", "minProperties", "maxProperties"}+++def _diagnostic_names(values: Any) -> list[str]:+ """Bounded log form of model-produced names and indices, never a value."""+ names = [str(value) if type(value) is int+ else value if isinstance(value, str) and _DIAGNOSTIC_NAME.fullmatch(value)+ else "?" for value in values]+ return names[:_MAX_DIAGNOSTIC_NAMES] + (["..."] if len(names) > _MAX_DIAGNOSTIC_NAMES else [])+++def _declared_names(values: Any, declared: set[str]) -> list[str]:+ """Log form of argument keys and paths: indices and names the schema declares.++ Any other key comes from the arguments themselves (a map-shaped schema keys+ by contact, file or user name), so it may be user data and logs as "*".+ """+ names = [str(value) if type(value) is int+ else value if isinstance(value, str) and value in declared and _DIAGNOSTIC_NAME.fullmatch(value)+ else "*" for value in values]+ return names[:_MAX_DIAGNOSTIC_NAMES] + (["..."] if len(names) > _MAX_DIAGNOSTIC_NAMES else [])+++def _offered_function_schemas(payload: dict[str, Any]) -> dict[str, Any]:+ offered = payload.get("tools")+ return {+ item["function"]["name"]: item["function"].get("parameters")+ for item in (offered if isinstance(offered, list) else [])+ if isinstance(item, dict) and item.get("type") == "function"+ and isinstance(item.get("function"), dict)+ and isinstance(item["function"].get("name"), str)+ }+++def _declared_property_names(schema: Any) -> set[str]:+ """Every property name a schema declares, at any depth (bounded walk)."""+ names: set[str] = set()+ pending, visited = [schema], 0+ while pending and visited < 4096:+ node = pending.pop()+ visited += 1+ if isinstance(node, dict):+ properties = node.get("properties")+ if isinstance(properties, dict):+ names.update(key for key in properties if isinstance(key, str))+ pending.extend(node.values())+ elif isinstance(node, list):+ pending.extend(node)+ return names+++def _closest_schema_error(error: ValidationError) -> ValidationError:+ """For oneOf/anyOf, the error of the one alternative the value came closest to."""+ for _ in range(8):+ if error.validator not in ("oneOf", "anyOf") or not error.context:+ return error+ branches: dict[Any, list[ValidationError]] = {}+ for child in error.context:+ branch = child.relative_schema_path[0] if child.relative_schema_path else None+ branches.setdefault(branch, []).append(child)+ fewest = min(len(errors) for errors in branches.values())+ closest = [errors for errors in branches.values() if len(errors) == fewest]+ if len(closest) != 1:+ return error+ error = best_match(closest[0])+ return error+++def _described_schema_error(error: ValidationError) -> dict[str, Any]:+ """The failed keyword, with a feedback clause built from schema names only."""+ rule, value, instance = str(error.validator), error.validator_value, error.instance+ described: dict[str, Any] = {"rule": rule}+ if rule == "required" and isinstance(value, list):+ missing = [name for name in value if isinstance(name, str)+ and not (isinstance(instance, dict) and name in instance)]+ described["missing"] = missing[:_MAX_DIAGNOSTIC_NAMES]+ described["detail"] = ("it is missing the required "+ + ("property " if len(missing) == 1 else "properties ")+ + ", ".join(missing[:8]))+ elif rule == "additionalProperties":+ declared = error.schema.get("properties") if isinstance(error.schema, dict) else None+ declared = declared if isinstance(declared, dict) else {}+ if isinstance(instance, dict):+ # Undeclared keys come from the arguments and may be user data: count them only.+ described["unexpected"] = sum(1 for key in instance if isinstance(key, str) and key not in declared)+ allowed = sorted(key for key in declared if isinstance(key, str))+ described["detail"] = ("it has a property its schema does not allow"+ + ("; use only " + ", ".join(allowed[:24]) if allowed else ""))+ elif rule == "enum" and isinstance(value, list):+ options = [json.dumps(option, ensure_ascii=False)[:64] for option in value[:24]]+ described["detail"] = ("the value must be one of " + ", ".join(options)+ + (", ..." if len(value) > 24 else ""))+ elif rule == "const":+ described["detail"] = "the value must be exactly " + json.dumps(value, ensure_ascii=False)[:64]+ elif rule == "type" and isinstance(value, (str, list)):+ types = [value] if isinstance(value, str) else [kind for kind in value if isinstance(kind, str)]+ described["detail"] = "the value must be of type " + " or ".join(types)+ elif rule in ("oneOf", "anyOf") and isinstance(value, list):+ forms = ["{" + ", ".join(branch["required"]) + "}" for branch in value[:8]+ if isinstance(branch, dict) and isinstance(branch.get("required"), list)+ and branch["required"] and all(isinstance(name, str) for name in branch["required"])]+ described["detail"] = ("it must match exactly one of its allowed forms"+ + (": " + " or ".join(forms) if forms else ""))+ elif rule in _BOUND_RULES and type(value) in (int, float):+ described["detail"] = f"the value does not meet its {rule} of {value}"+ elif rule == "pattern" and isinstance(value, str):+ described["detail"] = "the value must match the pattern " + value[:120]+ else:+ described["detail"] = f"the value does not satisfy its {rule} rule"+ return described+++def _schema_path_text(path: Any, declared: set[str]) -> str:+ """steps[3].locator, naming only properties the schema declares."""+ text = ""+ for part in path:+ if type(part) is int:+ text += f"[{part}]"+ else:+ name = part if isinstance(part, str) and part in declared and _DIAGNOSTIC_NAME.fullmatch(part) else "*"+ text += ("." if text else "") + name+ return text or "the top level"+++def _type_only_tools(payload: dict[str, Any]) -> list[Any]:+ """The offered tools with each schema reduced to its property types.++ The native envelope parser reads a string property verbatim and any other+ as JSON. With every constraint removed, an envelope that parses this way+ failed only its schema."""+ tools = []+ for item in payload.get("tools") or []:+ function = item.get("function") if isinstance(item, dict) else None+ schema = function.get("parameters") if isinstance(function, dict) else None+ properties = schema.get("properties") if isinstance(schema, dict) else None+ if not isinstance(properties, dict):+ tools.append(item)+ continue+ reduced = {key: {"type": "string"} if isinstance(value, dict) and value.get("type") == "string" else {}+ for key, value in properties.items()}+ tools.append({**item, "function": {**function, "parameters": {"type": "object", "properties": reduced}}})+ return tools+++def _structured_calls(+ completion: dict[str, Any], payload: dict[str, Any],+) -> tuple[list[dict[str, Any]] | None, dict[str, Any] | None]:+ """The calls of a structured decision, or why its envelope was rejected.++ Mirrors the checks of _repaired_tool_decision_invalid before its schema check.+ """+ def protocol(rule: str) -> tuple[None, dict[str, Any]]:+ return None, {"kind": "protocol", "channel": "structured", "rule": rule}++ choices = completion.get("choices")+ if not isinstance(choices, list) or len(choices) != 1:+ return protocol("choices")+ choice = choices[0]+ message = choice.get("message") if isinstance(choice, dict) else None+ if not isinstance(message, dict) or message.get("role") != "assistant":+ return protocol("message")+ content = message.get("content")+ if isinstance(content, str) and content.strip().startswith("<tool_call>"):+ return None, {"kind": "native-markup", "channel": "native"}+ calls = message.get("tool_calls")+ if calls is None:+ return protocol("answer")+ if not isinstance(calls, list) or not calls or choice.get("finish_reason") != "tool_calls":+ return protocol("finish_reason")+ if payload.get("parallel_tool_calls") is False and len(calls) > 1:+ return protocol("parallel_tool_calls")+ for call in calls:+ function = call.get("function") if isinstance(call, dict) else None+ if (not isinstance(function, dict) or not isinstance(call.get("id"), str) or not call["id"]+ or call.get("type") != "function" or not isinstance(function.get("name"), str)+ or not isinstance(function.get("arguments"), str)):+ return protocol("call")+ tool_choice = payload.get("tool_choice")+ forced = tool_choice.get("function") if isinstance(tool_choice, dict) else None+ forced_name = forced.get("name") if isinstance(forced, dict) else None+ if forced_name is not None and any(call["function"]["name"] != forced_name for call in calls):+ return protocol("tool_choice")+ return calls, None+++def _tool_decision_rejection(+ completion: dict[str, Any], payload: dict[str, Any],+) -> dict[str, Any]:+ """Why _repaired_tool_decision_invalid rejected a decision, by shape only.++ kind is "schema" when every call names an offered function with a JSON+ object of arguments and only that function's schema failed; otherwise+ "unknown-function", "arguments", "native-markup" or "protocol" (with the+ fixed name of the failed check). Side-effect free.+ """+ offered = _offered_function_schemas(payload)+ native_names = _complete_native_envelope_names(completion)+ if native_names is not None:+ channel, names = "native", native_names+ else:+ calls, envelope_rejection = _structured_calls(completion, payload)+ if envelope_rejection is not None:+ return envelope_rejection+ channel, names = "structured", [call["function"]["name"] for call in calls]+ functions = _diagnostic_names(names)+ if any(name not in offered for name in names):+ return {"kind": "unknown-function", "channel": channel, "functions": functions}+ if native_names is not None:+ parsed = copy.deepcopy(completion)+ if not _normalize_native_tool_markup(parsed, {**payload, "tools": _type_only_tools(payload)}):+ return {"kind": "native-markup", "channel": channel, "functions": functions}+ calls = parsed["choices"][0]["message"]["tool_calls"]+ for call in calls:+ name, schema = call["function"]["name"], offered[call["function"]["name"]]+ if not isinstance(schema, dict) or _schema_has_references(schema):+ return {"kind": "protocol", "channel": channel, "rule": "schema", "functions": functions}+ try:+ args = json.loads(call["function"]["arguments"])+ except ValueError:+ return {"kind": "arguments", "channel": channel, "functions": functions}+ validator_class = jsonschema_validators.validator_for(schema)+ try:+ validator_class.check_schema(schema)+ except SchemaError:+ return {"kind": "protocol", "channel": channel, "rule": "schema", "functions": functions}+ try:+ error = best_match(validator_class(schema).iter_errors(args))+ except (ValueError, TypeError):+ # The validator cannot evaluate these arguments (NaN against multipleOf);+ # _repaired_tool_decision_invalid rejects them alike: one ordinary repair.+ return {"kind": "protocol", "channel": channel, "rule": "unevaluable", "functions": functions}+ if error is None:+ continue+ error = _closest_schema_error(error)+ declared = _declared_property_names(schema)+ return {+ "kind": "schema", "channel": channel, "functions": functions, "function": name,+ "at": "/".join(_declared_names(error.absolute_path, declared)),+ "where": _schema_path_text(error.absolute_path, declared),+ "keys": _declared_names(sorted(args), declared) if isinstance(args, dict) else [],+ "keysAt": _declared_names(sorted(error.instance), declared) if isinstance(error.instance, dict) else [],+ **_described_schema_error(error),+ }+ return {"kind": "protocol", "channel": channel, "rule": "unclassified", "functions": functions}+++def _log_tool_rejection(stage: str, rejection: dict[str, Any]) -> None:+ """One bounded line per rejected decision: names, rule and path, no values."""+ fields = {key: rejection[key] for key in (+ "kind", "channel", "rule", "functions", "at", "missing", "unexpected", "keys", "keysAt",+ ) if key in rejection}+ if "function" in rejection:+ fields["function"] = _diagnostic_names([rejection["function"]])[0]+ logger.warning("Rejected model tool decision (%s): %s", stage,+ json.dumps(fields, sort_keys=True, separators=(",", ":")))+++def _tool_repair_feedback(+ rejection: dict[str, Any], payload: dict[str, Any], native_names: list[str] | None,+) -> str:+ """The repair instruction for this rejection, from schema names only."""+ if rejection.get("kind") == "schema":+ return (+ "Tool protocol error: your previous completion was discarded before any tool ran. "+ f"The arguments for {rejection['function']} did not satisfy its JSON parameter "+ f"schema at {rejection['where']}: {rejection['detail']}. Call it again through "+ "the API tool-call channel with arguments that follow that attached schema "+ "exactly. Respect tool_choice and parallel_tool_calls. If tool_choice permits "+ "it and no tool is appropriate, answer normally."+ )+ if native_names is not None:+ return _native_tool_repair_feedback(native_names, payload)+ if rejection.get("kind") == "unknown-function":+ # The offered names come from the request; the rejected one is not repeated.+ return (+ "Tool protocol error: your previous completion was discarded before any tool ran. "+ "It named a function that this request does not offer. Available function names: "+ + ", ".join(_offered_function_schemas(payload)) + ". Return a valid function call "+ "through the API tool-call channel using exactly the provided tools and their "+ "JSON parameter schemas. Respect tool_choice and parallel_tool_calls. If "+ "tool_choice permits it and no tool is appropriate, answer normally."+ )+ return _structured_tool_repair_feedback()++app = FastAPI(title="ODS Model Router", docs_url=None, redoc_url=None,openapi_url=None)@@ -1892,6 +2190,7 @@ async def _forward_inner(request: Request, path: str, payload: dict[str, Any],invalid = _repaired_tool_decision_invalid(complete, payload)if (invalid and _complete_native_envelope_names(complete) is Noneand not _complete_structured_tool_decision(complete)):+ _log_tool_rejection("stream", _tool_decision_rejection(complete, payload))_finish_probe_attempt(attempt_handle, "stream-error",streaming_upstream.status_code)return JSONResponse({"error": {@@ -2056,9 +2355,11 @@ async def _forward_inner(request: Request, path: str, payload: dict[str, Any],status_code=502, headers=ods_headers,), False- # One bounded protocol repair is allowed only before the agent has seen a- # tool call. A complete native envelope is a model decision, not an- # executed action; no host/tool operation is replayed here.+ # Bounded protocol repair, only before the agent has seen a tool call: one+ # repair, or _SCHEMA_REPAIR_LIMIT while the latest decision's only fault is+ # its arguments against the offered schema. A complete native envelope is a+ # model decision, not an executed action; no host/tool operation is+ # replayed here. Every rejected decision is logged by shape, never values.if (path == "/v1/chat/completions"and route["backendKind"] == "llama-server"and _repairable_native_tool_request(payload)@@ -2084,49 +2385,55 @@ async def _forward_inner(request: Request, path: str, payload: dict[str, Any],return JSONResponse({'error': {'message': 'Backend response identity changed','type': 'response_identity_mismatch', 'code': '502'}},status_code=502, headers=ods_headers), False- remaining = UPSTREAM_TIMEOUT_SECONDS - (time.monotonic() - telemetry_started)- if remaining <= 0:- return JSONResponse({"error": {- "message": "Upstream model runtime timed out during tool protocol repair",- "type": "upstream_timeout", "code": "504",- }}, status_code=504, headers=ods_headers), False- repair_payload = {**payload, "stream": False,- "messages": [*payload["messages"], {"role": "user",- "content": (_structured_tool_repair_feedback() if structured_invalid- else _native_tool_repair_feedback(native_names, payload))}]}- repair_payload.pop("stream_options", None)- repair_handle = None- try:- repair_body = json.dumps(repair_payload).encode("utf-8")- repair_handle = _begin_probe_attempt(- probe_id, request_id, next_attempt, repair_body, route,- )- upstream = await client.post(- url, content=repair_body,- headers=headers, timeout=remaining,- )- _finish_probe_attempt(repair_handle, "complete", upstream.status_code)- # The common response parser must attribute the repaired- # response to this send, not to the original tool decision.- attempt_handle = repair_handle- response_metadata = {"failed": False}- except asyncio.CancelledError:- _finish_probe_attempt(repair_handle, "cancelled")- raise- except httpx.TimeoutException:- _finish_probe_attempt(repair_handle, "timeout")- return JSONResponse({"error": {- "message": "Upstream model runtime timed out during tool protocol repair",- "type": "upstream_timeout", "code": "504",- }}, status_code=504, headers=ods_headers), False- except httpx.HTTPError as exc:- _finish_probe_attempt(repair_handle, "transport-error")- logger.warning("Upstream model runtime unavailable during tool protocol repair: %s", exc)- return JSONResponse({"error": {- "message": "Upstream model runtime unavailable during tool protocol repair",- "type": "upstream_unavailable", "code": "502",- }}, status_code=502, headers=ods_headers), False- if 200 <= upstream.status_code < 300:+ rejection = _tool_decision_rejection(initial_decision, payload)+ _log_tool_rejection("initial", rejection)+ repairs = 0+ while True:+ repairs += 1+ remaining = UPSTREAM_TIMEOUT_SECONDS - (time.monotonic() - telemetry_started)+ if remaining <= 0:+ return JSONResponse({"error": {+ "message": "Upstream model runtime timed out during tool protocol repair",+ "type": "upstream_timeout", "code": "504",+ }}, status_code=504, headers=ods_headers), False+ repair_payload = {**payload, "stream": False,+ "messages": [*payload["messages"], {"role": "user",+ "content": _tool_repair_feedback(rejection, payload, native_names)}]}+ repair_payload.pop("stream_options", None)+ repair_handle = None+ try:+ repair_body = json.dumps(repair_payload).encode("utf-8")+ repair_handle = _begin_probe_attempt(+ probe_id, request_id, next_attempt, repair_body, route,+ )+ next_attempt += 1+ upstream = await client.post(+ url, content=repair_body,+ headers=headers, timeout=remaining,+ )+ _finish_probe_attempt(repair_handle, "complete", upstream.status_code)+ # The common response parser must attribute the repaired+ # response to this send, not to the original tool decision.+ attempt_handle = repair_handle+ response_metadata = {"failed": False}+ except asyncio.CancelledError:+ _finish_probe_attempt(repair_handle, "cancelled")+ raise+ except httpx.TimeoutException:+ _finish_probe_attempt(repair_handle, "timeout")+ return JSONResponse({"error": {+ "message": "Upstream model runtime timed out during tool protocol repair",+ "type": "upstream_timeout", "code": "504",+ }}, status_code=504, headers=ods_headers), False+ except httpx.HTTPError as exc:+ _finish_probe_attempt(repair_handle, "transport-error")+ logger.warning("Upstream model runtime unavailable during tool protocol repair: %s", exc)+ return JSONResponse({"error": {+ "message": "Upstream model runtime unavailable during tool protocol repair",+ "type": "upstream_unavailable", "code": "502",+ }}, status_code=502, headers=ods_headers), False+ if not 200 <= upstream.status_code < 300:+ breaktry:repaired = json.loads(upstream.content.decode("utf-8"))except (ValueError, UnicodeDecodeError):@@ -2139,12 +2446,19 @@ async def _forward_inner(request: Request, path: str, payload: dict[str, Any],"message": "Backend response identity changed","type": "response_identity_mismatch", "code": "502",}}, status_code=502, headers=ods_headers), False- if (not isinstance(repaired, dict)- or _repaired_tool_decision_invalid(repaired, payload)):+ if (isinstance(repaired, dict)+ and not _repaired_tool_decision_invalid(repaired, payload)):+ break+ rejection = (_tool_decision_rejection(repaired, payload)+ if isinstance(repaired, dict) else {"kind": "protocol", "rule": "response"})+ _log_tool_rejection(f"repair {repairs}", rejection)+ if repairs >= (_SCHEMA_REPAIR_LIMIT if rejection["kind"] == "schema" else 1):return JSONResponse({"error": {- "message": "Model returned an invalid tool decision after one protocol repair",+ "message": "Model returned an invalid tool decision after "+ + ("one protocol repair" if repairs == 1 else f"{repairs} protocol repairs"),"type": "tool_protocol_invalid", "code": "502",}}, status_code=502, headers=ods_headers), False+ native_names = _complete_native_envelope_names(repaired)response_model = Noneresponse_usage = {diff --git a/ods/extensions/services/model-router/tests/test_structured_tool_repair.py b/ods/extensions/services/model-router/tests/test_structured_tool_repair.pyindex 68c4fdc76..418252f6a 100644--- a/ods/extensions/services/model-router/tests/test_structured_tool_repair.py+++ b/ods/extensions/services/model-router/tests/test_structured_tool_repair.py@@ -129,3 +129,165 @@ def test_forced_tool_and_parallel_policy_survive_repair(router):assert response.status_code == 200 and len(sent) == 2assert sent[1]["tool_choice"] == {"type": "function", "function": {"name": "lookup"}}assert sent[1]["parallel_tool_calls"] is False+++# RTX Spark, 2026-10-25: three completions in a row failed "after one protocol+# repair" with HTTP 502, which ended the Portal turn, while the engine answered+# 200 each time. Nothing said which call or rule was wrong, and the generic+# repair text did not tell the model either.+INSPECT = [{"type": "function", "function": {"name": "inspect", "parameters": {+ "type": "object", "additionalProperties": False, "required": ["siteId", "steps"],+ "properties": {"siteId": {"type": "string"}, "steps": {"type": "array", "items": {+ "type": "object", "additionalProperties": False, "required": ["action", "locator"],+ "properties": {"action": {"type": "string", "enum": ["click", "assert-text"]},+ "expectedText": {"type": "string"},+ "locator": {"oneOf": [+ {"type": "object", "additionalProperties": False, "required": ["selector"],+ "properties": {"selector": {"type": "string"}}},+ {"type": "object", "additionalProperties": False,+ "required": ["role", "name", "exact"],+ "properties": {"role": {"type": "string"}, "name": {"type": "string"},+ "exact": {"const": True}}}]}}}}}}}}]+SECRET = "PRIVATE-PAGE-TEXT"+++def inspect_args(locator, **step):+ return json.dumps({"siteId": "site-1", "steps": [{"action": "click", "locator": locator, **step}]})+++def sequence(router, decisions, *, stream=True, tools=TOOLS):+ """Serve `decisions` in order; more sends than decisions fail the test."""+ mod, client, write_state, _ = router+ write_state()+ sent = []+ def handler(request):+ body = json.loads(request.content)+ sent.append(body)+ assert len(sent) <= len(decisions), "more protocol repairs than allowed"+ return wire_response(decisions[len(sent) - 1], body.get("stream", False))+ asyncio.run(mod.app.state.http.aclose())+ mod.app.state.http = httpx.AsyncClient(transport=httpx.MockTransport(handler))+ response = client.post("/v1/chat/completions", json={"model": "ods/current", "stream": stream,+ "tools": tools, "messages": [{"role": "user", "content": "Check the page."}]})+ return response, sent++[email protected]("stream", [False, True])+def test_a_schema_mistake_gets_a_second_repair_that_names_its_rule(router, stream):+ missing = decision("inspect", inspect_args({"role": "button", "name": SECRET}))+ extra = decision("inspect", inspect_args({"selector": "#start"}, description=SECRET))+ fixed = decision("inspect", inspect_args({"role": "button", "name": "Start", "exact": True}))+ response, sent = sequence(router, [missing, extra, fixed], stream=stream, tools=INSPECT)+ assert response.status_code == 200 and len(sent) == 3+ assert "Start" in response.text and SECRET not in response.text, "the fixed call reaches the agent"+ first, second = (body["messages"][-1]["content"] for body in sent[1:])+ assert all(body["messages"][:-1] == sent[0]["messages"] for body in sent[1:]), "one feedback message each"+ assert "discarded before any tool ran" in first and "discarded before any tool ran" in second+ assert "inspect" in first and "at steps[0].locator: it is missing the required property exact" in first+ assert "at steps[0]: it has a property its schema does not allow; use only action, expectedText, locator" in second+ for feedback in (first, second):+ assert SECRET not in feedback and "description" not in feedback, "never an argument value or invented key"++[email protected]("stream", [False, True])+def test_schema_repairs_are_bounded_and_expose_no_call(router, stream):+ wrong = decision("inspect", inspect_args({"role": "button", "name": "Start", "exact": "true"}))+ response, sent = sequence(router, [wrong, wrong, wrong], stream=stream, tools=INSPECT)+ assert response.status_code == 502 and len(sent) == 3+ assert response.json()["error"] == {"message": "Model returned an invalid tool decision after 2 protocol repairs",+ "type": "tool_protocol_invalid", "code": "502"}+ assert "call-1" not in response.text+ assert "steps[0].locator.exact: the value must be exactly true" in sent[2]["messages"][-1]["content"]++[email protected]("second", [decision("unknown-model-function"), decision(args='{"key":')])+def test_only_a_schema_mistake_earns_the_second_repair(router, second):+ response, sent = sequence(router, [decision(args='{"key":7}'), second, decision()], stream=False)+ assert response.status_code == 502 and len(sent) == 2+ assert response.json()["error"]["message"] == "Model returned an invalid tool decision after one protocol repair"+++def test_an_unknown_function_repair_lists_the_offered_names_but_never_the_invented_one(router):+ response, sent = sequence(router, [decision("unknown-model-function"), decision()], stream=False)+ assert response.status_code == 200 and len(sent) == 2+ feedback = sent[1]["messages"][-1]["content"]+ assert "Available function names: lookup." in feedback and "unknown-model-function" not in feedback+++def test_every_rejected_decision_is_logged_by_shape_never_by_value(router, caplog):+ missing = decision("inspect", inspect_args({"role": "button", "name": SECRET}))+ extra = decision("inspect", inspect_args({"selector": "#start"}, **{"note": SECRET}))+ with caplog.at_level("WARNING", logger="ods-model-router"):+ response, sent = sequence(router, [missing, extra, extra], stream=False, tools=INSPECT)+ assert response.status_code == 502 and len(sent) == 3+ lines = [record.getMessage() for record in caplog.records if "Rejected model tool decision" in record.getMessage()]+ assert len(lines) == 3+ assert all(SECRET not in line and "Start" not in line and "#start" not in line for line in lines)+ initial = json.loads(lines[0].split(": ", 1)[1])+ assert lines[0].startswith("Rejected model tool decision (initial)")+ assert initial == {"kind": "schema", "channel": "structured", "function": "inspect", "functions": ["inspect"],+ "rule": "required", "at": "steps/0/locator", "missing": ["exact"],+ "keys": ["siteId", "steps"], "keysAt": ["name", "role"]}+ repaired = json.loads(lines[2].split(": ", 1)[1])+ assert lines[2].startswith("Rejected model tool decision (repair 2)")+ assert repaired["rule"] == "additionalProperties" and repaired["at"] == "steps/0"+ assert repaired["unexpected"] == 1 and "note" not in lines[2], "undeclared keys are counted, never named"+++MAP = [{"type": "function", "function": {"name": "save", "parameters": {+ "type": "object", "properties": {"contacts": {"type": "object",+ "additionalProperties": {"type": "object", "required": ["phone"],+ "properties": {"phone": {"type": "string"}}}}}}}}]+++def test_keys_that_come_from_the_arguments_are_never_logged(router, caplog):+ # A map-shaped schema keys by user data: a contact name must not reach the log.+ bad = decision("save", '{"contacts":{"alice.smith":{"note":"x"}}}')+ with caplog.at_level("WARNING", logger="ods-model-router"):+ response, _ = sequence(router, [bad, bad, bad], stream=False, tools=MAP)+ assert response.status_code == 502+ lines = [record.getMessage() for record in caplog.records if "Rejected model tool decision" in record.getMessage()]+ assert lines and all("alice" not in line for line in lines)+ initial = json.loads(lines[0].split(": ", 1)[1])+ assert (initial["at"], initial["keys"], initial["keysAt"]) == ("contacts/*", ["contacts"], ["*"]), initial+++NUM = [{"type": "function", "function": {"name": "lookup", "parameters": {+ "type": "object", "required": ["x"], "properties": {"x": {"type": "number", "multipleOf": 0.5}}}}}]++[email protected]("stream", [False, True])+def test_arguments_the_validator_cannot_evaluate_get_one_ordinary_repair(router, stream):+ # jsonschema raises on NaN against multipleOf; the classifier must not turn that into a 500.+ response, sent = sequence(router, [decision(args='{"x": NaN}'), decision(args='{"x": 1.5}')],+ stream=stream, tools=NUM)+ assert response.status_code == 200 and len(sent) == 2+++def test_an_unknown_function_and_bad_arguments_are_logged_without_their_text(router, caplog):+ with caplog.at_level("WARNING", logger="ods-model-router"):+ response, _ = sequence(router, [decision("unknown function " + SECRET), decision(args='{"key":"' + SECRET)],+ stream=False)+ assert response.status_code == 502+ lines = [record.getMessage() for record in caplog.records if "Rejected model tool decision" in record.getMessage()]+ assert [json.loads(line.split(": ", 1)[1]) for line in lines] == [+ {"kind": "unknown-function", "channel": "structured", "functions": ["?"]},+ {"kind": "arguments", "channel": "structured", "functions": ["lookup"]}]+ assert all(SECRET not in line for line in lines)+++def test_a_native_envelope_with_a_schema_mistake_also_gets_the_second_repair(router):+ def native(parameters):+ content = "<tool_call>\n<function=lookup>\n" + "".join(+ f"<parameter={key}>\n{value}\n</parameter>\n" for key, value in parameters.items()) + "</function>\n</tool_call>"+ return {"id": "native", "model": "Concrete.gguf", "choices": [{"index": 0, "finish_reason": "stop",+ "message": {"role": "assistant", "content": content}}]}+ tools = [{"type": "function", "function": {"name": "lookup", "parameters": {"type": "object",+ "required": ["key", "limit"], "properties": {"key": {"type": "string"}, "limit": {"type": "integer"}}}}}]+ response, sent = sequence(router, [native({"key": SECRET}), native({"key": "ok", "limit": '"ten"'}),+ native({"key": "ok", "limit": 3})], stream=False, tools=tools)+ assert response.status_code == 200 and len(sent) == 3+ assert response.json()["choices"][0]["message"]["tool_calls"][0]["function"]["name"] == "lookup"+ assert "at the top level: it is missing the required property limit" in sent[1]["messages"][-1]["content"]+ assert "at limit: the value must be of type integer" in sent[2]["messages"][-1]["content"]+ assert all(SECRET not in body["messages"][-1]["content"] for body in sent[1:])diff --git a/ods/extensions/services/pixel-agent/host/preview-inspection-protocol.md b/ods/extensions/services/pixel-agent/host/preview-inspection-protocol.mdindex 12456d3c6..3b84c3a03 100644--- a/ods/extensions/services/pixel-agent/host/preview-inspection-protocol.md+++ b/ods/extensions/services/pixel-agent/host/preview-inspection-protocol.md@@ -16,7 +16,9 @@ add `value`; `download` adds `path`, `expectedBytes` and `expectedSha256`;`press` adds `key` and an optional `holdMs`; `assert-painted` adds nothing(see the sections below). A locator is either`{selector: "CSS"}` or `{role: "button", name: "Show items", exact: true}`.-Semantic roles are+The tool also accepts a role/name locator without `exact` and a selector with+`exact: true`, which match the same element, and always sends these two forms+(`workspace-preview-inspect.mjs`); `exact: false` stays invalid. Semantic roles areallowlisted. There are no URLs, executable expressions, shell commands, imagenames, host paths, or Docker arguments in this protocol.diff --git a/ods/extensions/services/pixel-agent/plugin/workspace-preview-inspect.mjs b/ods/extensions/services/pixel-agent/plugin/workspace-preview-inspect.mjsindex e60213e53..a897001cd 100644--- a/ods/extensions/services/pixel-agent/plugin/workspace-preview-inspect.mjs+++ b/ods/extensions/services/pixel-agent/plugin/workspace-preview-inspect.mjs@@ -324,10 +324,11 @@ const INPUT_HINTS = new Map([['unsupported inspection navigation','path is allowed only for a final download assertion. The inspector opens the published snapshot entry page and has no navigation or reload action. Verify supported in-page interactions and report cross-reload persistence as unverified; do not simulate a reload or use sibling test pages as persistence evidence.'],['invalid inspection step','Each step needs action and locator; assert-text additionally requires expectedText (normalized visible text, 1 to 256 characters); select-option or fill requires value (exact option value or synthetic text, 0 to 256 printable characters); download must be last and requires path, expectedBytes and expectedSha256 for one existing snapshot PDF/ZIP up to 4 MiB; press requires key (ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space, Enter, Escape, Tab, one lowercase letter a-z or one digit 0-9; no modifiers, chords or text) and accepts holdMs (integer 0 to 1000 milliseconds, default 100); assert-painted takes only action and locator.'],['invalid CSS locator','Use one non-empty CSS selector of 1 to 256 printable characters, without Playwright engine prefixes or chaining.'],- ['invalid semantic locator','Use a supported role, exact accessible name and exact:true, or a CSS selector.'],+ ['invalid CSS locator exact','A CSS locator has no matching mode: omit exact or use exact:true.'],+ ['invalid semantic locator','Use a supported role and its exact accessible name ({role, name}, exact:true optional), or a CSS selector ({selector}).'],['invalid semantic locator role','Use a supported role (button, link, checkbox, radio, textbox, combobox, heading, tab or switch), or a CSS selector.'],['invalid semantic locator name','Role/name locators require a non-empty accessible name of 1 to 120 printable characters. For an unnamed control, use a unique CSS selector from the actual source. Do not invent a name or change the page only to satisfy a locator.'],- ['invalid semantic locator exact','Exact role/name locators require exact:true. Use the actual accessible name, or a unique CSS selector from the source.'],+ ['invalid semantic locator exact','Role/name locators always match the exact accessible name: omit exact or use exact:true; exact:false is not supported. Use the actual accessible name, or a unique CSS selector from the source.'],['inspection request too large','Split the plan into smaller inspections.'],]);// Diagnose only fixed schema fields, never reflect argument values. One error@@ -341,17 +342,24 @@ function inspectionStepProblem(step,index,count) {if(step.action==='press' && !pressValid(step)) return problem('invalid inspection step',PRESS_KEYS.includes(step.key)?'holdMs':'key');if(step.action==='assert-text' && (!printable(step.expectedText,256) || step.expectedText.replace(/\s+/g,' ').trim()!==step.expectedText)) return problem('invalid inspection step','expectedText');if(['select-option','fill'].includes(step.action) && !optionValue(step.value)) return problem('invalid inspection step','value');- const l=step.locator;- if(exact(l,['selector'])) {+ // exact is optional: role/name locators always match the exact accessible+ // name and a CSS selector has no other mode, so models that omit exact, or+ // add exact:true to a selector, lose nothing. exact:false stays invalid.+ const l=step.locator, flag=l && typeof l==='object' && !Array.isArray(l) && Object.hasOwn(l,'exact') ? ['exact'] : [];+ if(exact(l,['selector',...flag])) {if(!printable(l.selector,256)||l.selector.includes('>>')||/^[A-Za-z_-]+=/.test(l.selector)) return problem('invalid CSS locator','locator.selector');+ if(flag.length && l.exact!==true) return problem('invalid CSS locator exact','locator.exact');} else {- if(!exact(l,['role','name','exact'])) return problem('invalid semantic locator','locator');+ if(!exact(l,['role','name',...flag])) return problem('invalid semantic locator','locator');if(!roles.has(l.role)) return problem('invalid semantic locator role','locator.role');if(!printable(l.name,120)) return problem('invalid semantic locator name','locator.name');- if(l.exact!==true) return problem('invalid semantic locator exact','locator.exact');+ if(flag.length && l.exact!==true) return problem('invalid semantic locator exact','locator.exact');}return undefined;}+// The capsule protocol takes exactly {selector} or {role, name, exact:true}+// (preview_inspection_protocol.py); the plan hash and receipt bind that form.+const protocolLocator = l => Object.hasOwn(l,'selector') ? {selector:l.selector} : {role:l.role,name:l.name,exact:true};export function normalizeWorkspacePreviewInspectionParams(params) {if(!exact(params,['siteId','sha256','viewport','steps'])) throw Error('invalid preview inspection fields');if(typeof params.sha256!=='string'||!/^[a-f0-9]{64}$/.test(params.sha256)) throw Error('invalid preview inspection digest');@@ -364,7 +372,9 @@ export function normalizeWorkspacePreviewInspectionParams(params) {if(problem) problems.push(problem);}if(problems.length) throw Object.assign(Error(problems[0].reason),{inputHints:problems.map(problem=>problem.hint)});- const request={schemaVersion:1,action:'inspect',...params};+ const steps=params.steps.map(step=>isDeepStrictEqual(protocolLocator(step.locator),step.locator)+ ? step : {...step,locator:protocolLocator(step.locator)});+ const request={schemaVersion:1,action:'inspect',...params,steps};if(Buffer.byteLength(canonical(request))>8192) throw Error('inspection request too large');return request;}@@ -484,8 +494,8 @@ export function createWorkspacePreviewInspectTool({request,transport='unix',tranif(!['unix','native'].includes(transport))throw Error('invalid inspection transport');request??=transport==='unix'?unixRequest:nativeRequest;return {name:'pixel_ods_workspace_preview_inspect',- description:'Inspect an already published owned snapshot using bounded CSS or exact accessible role/name locators. Pass its exact siteId and sha256 from publication. Each step accepts action and locator. assert-text also requires expectedText: the exact visible innerText after whitespace is collapsed and trimmed, 1 to 256 characters. This reads rendered text, not the value of an input field. For counters or status labels, use assert-text before and after clicking (for example 0, click Somar, 1, click Zerar, 0). For a visible editable native text/search/number input or textarea, use fill with value (0 to 256 printable characters), then click and assert the resulting text. Use synthetic test data only, never passwords, credentials or personal/payment data. Password/file/email and other input types, sensitive autocomplete fields, readonly/disabled fields and contenteditable are unsupported. For number fields use finite decimal or exponent strings with a dot separator, or empty to clear; do not use commas, NaN or Infinity. Min/max/step-invalid values are allowed for negative tests: boolean constraint flags report them without declaring the form valid. Fill emits input/change events without key events and does not submit forms. For keyboard controls such as a canvas game, use press with key: ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space, Enter, Escape, Tab, one lowercase letter or one digit (no modifiers or text). Its locator is the rendered element that receives the keys, such as the game canvas, its container, the page body or a button; press focuses the preview page and that element, then sends real keydown/keyup events, which also reach window and document listeners. Optional holdMs (0 to 1000, default 100) keeps the key down, since many games read held keys once per animation frame. Press refuses text fields; use fill for those. Several presses may run in a row (for example Space to start, then ArrowRight), but follow the last one with assert-text, assert-visible/assert-hidden or assert-painted on the visible result; a key press alone proves no result. A start click needs its own assertion before the first press (for example click Start, assert-visible on the game screen or assert-painted on its canvas, then press): a click followed directly by a press does not count as behavior evidence. To check that a canvas game, chart or other drawing renders at all, use assert-painted (action and locator only) on the rendered element that draws, after the presses or start click that begin it (it can be that click\'s assertion): it captures that element\'s on-screen content box, inside the viewport and any rounded corners and including anything covering it, and passes when the box shows at least two colors within the observation window. One color fails as uniform_paint, for example a blank or black canvas. It reports only bounded color statistics and a fingerprint, never an image, and it is not image recognition: a background without its sprites still passes, so also assert visible state such as a score with assert-text. Two assert-painted steps of one element around a press show whether its paint changed. For a visible enabled native single-select, use select-option with value set to one exact option value (empty is allowed), then assert the dependent text. Do not add buttons merely because a test needs to select an option. Custom comboboxes and multiple selects are not supported. To verify delivery bytes use one final download step with path (a snapshot-relative PDF or ZIP), expectedBytes (1 to 4194304) and expectedSha256 (full SHA-256 of that file). The snapshot must already contain exactly those bytes. The download step performs the click itself. Do not precede it with an ordinary click on the download control; use any visibility/text assertions followed directly by download. This captures exactly one download privately inside the capsule; it does not download to the user computer or validate PDF quality or ZIP contents. Blob/data URLs, external URLs and additional downloads are unsupported. Ordinary click steps still cancel downloads; a blocked download is unverified, not a website failure. This runs the real page script in Chromium; test visible UI effects with fill, click, press and behavior assertions. Script, style and head metadata elements are normally not rendered; their visibility says nothing about whether page JavaScript executed. Do not replace the real page script with a reimplementation in another language. A locator is {selector:"#actual-id"} or {role:"button",name:"Exact source name",exact:true}; exact:false is invalid. Immediately after publication, check each requested interaction with an initial state assertion, the relevant click or press, then an explicit postcondition assertion matching the requested behavior. For downloads, the final download action supplies both the click and byte verification; omit a separate click. Read actual selectors and state changes from the source; do not guess them. Do not wait until finalization. Each locator must match exactly one element. Exact role/name locators match rendered elements; assert-hidden also matches hidden ones, so one role/name can be asserted hidden, clicked into view, then asserted visible. Visibility assertions test CSS layout visibility, not pixel paint, occlusion or clipping. The result also lists the rendered colors of the page by area at a desktop view as first loaded; use them to confirm a requested color change is actually visible. A click alone proves no behavioral result. Rendered hidden attributes are diagnostic; intentional CSS overrides are not automatically errors. Uncaught page script errors are reported and leave interactions unverified. When ODS declares the selected model able to read images, the result also carries one JPEG screenshot (about one megapixel at most, at most 3 per run) of the whole preview viewport, taken after the steps that ran: look at it before saying how the page looks. Otherwise the result says why it has none. Unavailable inspection is unverified, never success. No URLs or JavaScript accepted.',- parameters:{type:'object',additionalProperties:false,required:['siteId','sha256','viewport','steps'],properties:{siteId:{type:'string',pattern:'^site-[a-f0-9]{24}$'},sha256:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Full snapshot sha256 from the same publication receipt; not entrySha256 or a site suffix.'},viewport:{type:'object',additionalProperties:false,required:['width','height'],properties:{width:{type:'integer',minimum:240,maximum:1920},height:{type:'integer',minimum:240,maximum:1920}}},steps:{type:'array',minItems:1,maxItems:12,items:{type:'object',additionalProperties:false,required:['action','locator'],properties:{action:{type:'string',enum:['assert-visible','assert-hidden','assert-text','click','select-option','fill','download','press','assert-painted']},key:{type:'string',enum:[...PRESS_KEYS],description:'Required only for press; one unmodified key.'},holdMs:{type:'integer',minimum:0,maximum:MAX_PRESS_HOLD_MS,description:'Optional for press; milliseconds the key stays down (default 100).'},path:{type:'string',maxLength:512,description:'Required only for a single final download step; exact existing snapshot-relative PDF or ZIP path.'},expectedBytes:{type:'integer',minimum:1,maximum:4194304,description:'Required only for download; byte length of the existing snapshot file.'},expectedSha256:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Required only for download; SHA-256 of the existing snapshot file, not the full snapshot hash.'},value:{type:'string',maxLength:256,description:'Required only for select-option or fill; exact option value or synthetic printable field text, including empty string.'},expectedText:{type:'string',minLength:1,maxLength:256,description:'Required only for assert-text; exact normalized visible text.'},locator:{oneOf:[{type:'object',additionalProperties:false,required:['selector'],properties:{selector:{type:'string',minLength:1,maxLength:256}}},{type:'object',additionalProperties:false,required:['role','name','exact'],properties:{role:{type:'string',enum:[...roles]},name:{type:'string',minLength:1,maxLength:120},exact:{const:true}}}]}}}}}},+ description:'Inspect an already published owned snapshot using bounded CSS or exact accessible role/name locators. Pass its exact siteId and sha256 from publication. Each step accepts action and locator. assert-text also requires expectedText: the exact visible innerText after whitespace is collapsed and trimmed, 1 to 256 characters. This reads rendered text, not the value of an input field. For counters or status labels, use assert-text before and after clicking (for example 0, click Somar, 1, click Zerar, 0). For a visible editable native text/search/number input or textarea, use fill with value (0 to 256 printable characters), then click and assert the resulting text. Use synthetic test data only, never passwords, credentials or personal/payment data. Password/file/email and other input types, sensitive autocomplete fields, readonly/disabled fields and contenteditable are unsupported. For number fields use finite decimal or exponent strings with a dot separator, or empty to clear; do not use commas, NaN or Infinity. Min/max/step-invalid values are allowed for negative tests: boolean constraint flags report them without declaring the form valid. Fill emits input/change events without key events and does not submit forms. For keyboard controls such as a canvas game, use press with key: ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Space, Enter, Escape, Tab, one lowercase letter or one digit (no modifiers or text). Its locator is the rendered element that receives the keys, such as the game canvas, its container, the page body or a button; press focuses the preview page and that element, then sends real keydown/keyup events, which also reach window and document listeners. Optional holdMs (0 to 1000, default 100) keeps the key down, since many games read held keys once per animation frame. Press refuses text fields; use fill for those. Several presses may run in a row (for example Space to start, then ArrowRight), but follow the last one with assert-text, assert-visible/assert-hidden or assert-painted on the visible result; a key press alone proves no result. A start click needs its own assertion before the first press (for example click Start, assert-visible on the game screen or assert-painted on its canvas, then press): a click followed directly by a press does not count as behavior evidence. To check that a canvas game, chart or other drawing renders at all, use assert-painted (action and locator only) on the rendered element that draws, after the presses or start click that begin it (it can be that click\'s assertion): it captures that element\'s on-screen content box, inside the viewport and any rounded corners and including anything covering it, and passes when the box shows at least two colors within the observation window. One color fails as uniform_paint, for example a blank or black canvas. It reports only bounded color statistics and a fingerprint, never an image, and it is not image recognition: a background without its sprites still passes, so also assert visible state such as a score with assert-text. Two assert-painted steps of one element around a press show whether its paint changed. For a visible enabled native single-select, use select-option with value set to one exact option value (empty is allowed), then assert the dependent text. Do not add buttons merely because a test needs to select an option. Custom comboboxes and multiple selects are not supported. To verify delivery bytes use one final download step with path (a snapshot-relative PDF or ZIP), expectedBytes (1 to 4194304) and expectedSha256 (full SHA-256 of that file). The snapshot must already contain exactly those bytes. The download step performs the click itself. Do not precede it with an ordinary click on the download control; use any visibility/text assertions followed directly by download. This captures exactly one download privately inside the capsule; it does not download to the user computer or validate PDF quality or ZIP contents. Blob/data URLs, external URLs and additional downloads are unsupported. Ordinary click steps still cancel downloads; a blocked download is unverified, not a website failure. This runs the real page script in Chromium; test visible UI effects with fill, click, press and behavior assertions. Script, style and head metadata elements are normally not rendered; their visibility says nothing about whether page JavaScript executed. Do not replace the real page script with a reimplementation in another language. A locator is {selector:"#actual-id"} or {role:"button",name:"Exact source name"}; role/name always match the exact accessible name, so exact:true is optional and exact:false is invalid. Immediately after publication, check each requested interaction with an initial state assertion, the relevant click or press, then an explicit postcondition assertion matching the requested behavior. For downloads, the final download action supplies both the click and byte verification; omit a separate click. Read actual selectors and state changes from the source; do not guess them. Do not wait until finalization. Each locator must match exactly one element. Exact role/name locators match rendered elements; assert-hidden also matches hidden ones, so one role/name can be asserted hidden, clicked into view, then asserted visible. Visibility assertions test CSS layout visibility, not pixel paint, occlusion or clipping. The result also lists the rendered colors of the page by area at a desktop view as first loaded; use them to confirm a requested color change is actually visible. A click alone proves no behavioral result. Rendered hidden attributes are diagnostic; intentional CSS overrides are not automatically errors. Uncaught page script errors are reported and leave interactions unverified. When ODS declares the selected model able to read images, the result also carries one JPEG screenshot (about one megapixel at most, at most 3 per run) of the whole preview viewport, taken after the steps that ran: look at it before saying how the page looks. Otherwise the result says why it has none. Unavailable inspection is unverified, never success. No URLs or JavaScript accepted.',+ parameters:{type:'object',additionalProperties:false,required:['siteId','sha256','viewport','steps'],properties:{siteId:{type:'string',pattern:'^site-[a-f0-9]{24}$'},sha256:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Full snapshot sha256 from the same publication receipt; not entrySha256 or a site suffix.'},viewport:{type:'object',additionalProperties:false,required:['width','height'],properties:{width:{type:'integer',minimum:240,maximum:1920},height:{type:'integer',minimum:240,maximum:1920}}},steps:{type:'array',minItems:1,maxItems:12,items:{type:'object',additionalProperties:false,required:['action','locator'],properties:{action:{type:'string',enum:['assert-visible','assert-hidden','assert-text','click','select-option','fill','download','press','assert-painted']},key:{type:'string',enum:[...PRESS_KEYS],description:'Required only for press; one unmodified key.'},holdMs:{type:'integer',minimum:0,maximum:MAX_PRESS_HOLD_MS,description:'Optional for press; milliseconds the key stays down (default 100).'},path:{type:'string',maxLength:512,description:'Required only for a single final download step; exact existing snapshot-relative PDF or ZIP path.'},expectedBytes:{type:'integer',minimum:1,maximum:4194304,description:'Required only for download; byte length of the existing snapshot file.'},expectedSha256:{type:'string',pattern:'^[a-f0-9]{64}$',description:'Required only for download; SHA-256 of the existing snapshot file, not the full snapshot hash.'},value:{type:'string',maxLength:256,description:'Required only for select-option or fill; exact option value or synthetic printable field text, including empty string.'},expectedText:{type:'string',minLength:1,maxLength:256,description:'Required only for assert-text; exact normalized visible text.'},locator:{oneOf:[{type:'object',additionalProperties:false,required:['selector'],properties:{selector:{type:'string',minLength:1,maxLength:256},exact:{const:true}}},{type:'object',additionalProperties:false,required:['role','name'],properties:{role:{type:'string',enum:[...roles]},name:{type:'string',minLength:1,maxLength:120},exact:{const:true}}}]}}}}}},execute:async(toolCallId,params,signal)=>{let normalized;// Bad model arguments are not evidence that the installed broker is down.diff --git a/ods/extensions/services/pixel-agent/tests/preview_inspection_input_recovery.test.mjs b/ods/extensions/services/pixel-agent/tests/preview_inspection_input_recovery.test.mjsindex 109b7b831..0bf509f56 100644--- a/ods/extensions/services/pixel-agent/tests/preview_inspection_input_recovery.test.mjs+++ b/ods/extensions/services/pixel-agent/tests/preview_inspection_input_recovery.test.mjs@@ -1,6 +1,7 @@import test from 'node:test';import assert from 'node:assert/strict';-import {createWorkspacePreviewInspectTool} from '../plugin/workspace-preview-inspect.mjs';+import {createWorkspacePreviewInspectTool, hasVisibilityTransitionPlan, inspectionPlanHash,+ normalizeWorkspacePreviewInspectionParams as normalize} from '../plugin/workspace-preview-inspect.mjs';const valid = () => ({siteId:'site-'+ 'a'.repeat(24),sha256:'a'.repeat(64),viewport:{width:800,height:600},steps:[{action:'assert-hidden',locator:{selector:'#details'}}]});@@ -95,6 +96,59 @@ test('inspection tool schema excludes empty CSS selectors and accessible names',assert.equal(schema.oneOf[1].properties.name.minLength,1);});+// RTX Spark, 2026-10-25: the model router rejected three completions in a row+// against this tool's schema before any tool ran, and the Portal turn ended.+// One likely cause: role/name locators required exact as the constant true, and+// models often leave it out, or add exact:true to a CSS selector. Neither+// changes what is matched: role/name always match the exact accessible name,+// and a selector has no other mode. exact:false, other keys and mixed forms+// stay invalid.+test('role/name locators may omit exact and selectors may carry exact:true; the inspector gets the protocol form',async()=>{+ const calls=[];+ const tool=createWorkspacePreviewInspectTool({request:async request=>{calls.push(structuredClone(request));throw Error('offline fixture');}});+ const params={...valid(),steps:[+ {action:'assert-hidden',locator:{selector:'#details',exact:true}},+ {action:'click',locator:{role:'button',name:'Show details'}},+ {action:'assert-visible',locator:{selector:'#details'}},+ ]};+ const before=structuredClone(params);+ const result=await tool.execute('lenient',params);+ assert.equal(result.details.errorCode,'unavailable','accepted and sent; only the offline fixture failed');+ assert.deepEqual(params,before,'the caller arguments are never changed');+ assert.deepEqual(calls[0].steps.map(step=>step.locator),+ [{selector:'#details'},{role:'button',name:'Show details',exact:true},{selector:'#details'}]);+ const strict={...valid(),steps:[+ {action:'assert-hidden',locator:{selector:'#details'}},+ {action:'click',locator:{role:'button',name:'Show details',exact:true}},+ {action:'assert-visible',locator:{selector:'#details'}},+ ]};+ assert.deepEqual(normalize(params),normalize(strict),'one plan, whichever form the model used');+ assert.equal(inspectionPlanHash(normalize(params)),inspectionPlanHash(normalize(strict)));+ assert.equal(hasVisibilityTransitionPlan(normalize(params)),true,'the two #details assertions name one element');+});++test('exact:false, extra keys and mixed locator forms stay invalid, with a hint naming the field',async()=>{+ const tool=createWorkspacePreviewInspectTool({request:async()=>assert.fail('an invalid plan must not run')});+ for(const [locator,field] of [+ [{role:'button',name:'Start',exact:false},'locator.exact'],+ [{selector:'#start',exact:false},'locator.exact'],+ [{role:'button',name:'Start',level:1},'locator'],+ [{role:'button',name:'Start',exact:true,description:'the start button'},'locator'],+ [{selector:'#start',role:'button',name:'Start'},'locator'],+ [{role:'button'},'locator'],+ [{name:'Start'},'locator'],+ [{},'locator'],+ ]) {+ const params={...valid(),steps:[{action:'click',locator}]};+ assert.throws(()=>normalize(params),undefined,JSON.stringify(locator));+ const text=(await tool.execute('invalid',params)).content[0].text;+ assert.ok(text.includes(`Step 1 (steps[0].${field})`),`${JSON.stringify(locator)}: ${text.slice(0,200)}`);+ }+ const schema=createWorkspacePreviewInspectTool().parameters.properties.steps.items.properties.locator;+ assert.deepEqual(schema.oneOf.map(form=>[form.required,form.additionalProperties,form.properties.exact]),+ [[['selector'],false,{const:true}],[['role','name'],false,{const:true}]]);+});+test('bounded step diagnostics identify fields without reflecting untrusted argument text',async()=>{const tool=createWorkspacePreviewInspectTool({request:async()=>assert.fail('invalid plan must not run')});const marker='UNTRUSTED_ARGUMENT_DO_NOT_REPEAT';