Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
83 changes: 79 additions & 4 deletions loopx/capabilities/manager_context/inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,11 @@


TOOL_NAME = "loopx_manager_read"
_TODO_DETAIL_GUIDANCE = (
"For an oversized exact local Todo, follow its read_reference. Concatenate "
"detail_page.text from offset zero through EOF with the same source_revision, "
"then parse the complete JSON record before deciding; a fragment is not the full task. "
)
READ_TOOL = {
"type": "function",
"name": TOOL_NAME,
Expand All @@ -35,6 +40,7 @@
"to answer progress and priority questions. Paginate with next_offset. "
"An oversized portfolio row is incomplete; resolve attention read_reference "
"to recover complete decision terms before deciding or acting. "
+ _TODO_DETAIL_GUIDANCE +
"Use view=report_source with a closed window_start/window_end for a frozen periodic-report "
"source over all authorized local Goals including stopped ones, current tasks, window deliveries "
"and their associated tasks, and handoff receipts. Copy source.source_revision when paging. "
Expand All @@ -54,7 +60,7 @@
"include_outcome_gaps": {"type": "boolean", "description": "Local deliveries: include recorded outcome_gap counterevidence alongside progress. Default false for ordinary delivery queries; report_source always includes it. Observations and untyped host failures are not delivery outcomes."},
"window_start": {"type": "string", "description": "Local deliveries/report_source: exact inclusive ISO-8601 timestamp with offset. Pair with window_end instead of days, e.g. a frozen report window."},
"window_end": {"type": "string", "description": "Local deliveries/report_source: exact exclusive ISO-8601 timestamp with offset. Boundaries do not move while paging; report_source requires a closed window."},
"expected_source_revision": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Local deliveries/report_source: copy source.source_revision from the first page onto subsequent pages. A conflicting response requires restarting this read, not merging pages from different snapshots."},
"expected_source_revision": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Local deliveries/report_source: copy source.source_revision when paging. Exact local Todo: copy its read_reference; this revision selects bounded JSON detail pages, where offset counts Unicode characters. Follow detail_page.next_read. On conflict restart the exact read; never merge revisions."},
"delivery_ref": {"type": "string", "pattern": "^sha256:[a-f0-9]{64}$", "description": "Local deliveries only: use an observed row's source_ref to recover its full permitted recorded_details and evidence references within the same read window/revision. Does not read referenced artifacts or prove the recorded claims."},
"goal_id": {"type": "string"},
"agent_id": {"type": "string", "minLength": 1,
Expand Down Expand Up @@ -90,7 +96,8 @@
"The Goal row carries its lifecycle readback: reached milestones with evidence refs and the phase "
"(starting/qualifying/waiting_owner/closing/closed), or a typed unavailable gap naming why. "
"Use view=agents to find registered peers, then view=agent_route with exact goal_id and agent_id to observe an existing local host binding. A route is not execution readiness. "
"Paginate with next_offset. No cross-Goal access, shell, writes or execution authority."}
"Paginate with next_offset. " + _TODO_DETAIL_GUIDANCE +
"No cross-Goal access, shell, writes or execution authority."}


# The published tool schema is the contract the caller sees, so the reader takes
Expand Down Expand Up @@ -187,7 +194,15 @@ def rejected_read_arguments(arguments: dict[str, Any]) -> list[str]:
rejected.append("include_outcome_gaps:must_be_a_boolean")
if not isinstance(arguments.get("source_id", "local"), str):
rejected.append("source_id:must_be_a_string")
exact_arguments = {"window_start", "window_end", "expected_source_revision", "delivery_ref"} & arguments.keys()
detail_read = view == "todos" and "expected_source_revision" in arguments
if detail_read:
if not arguments.get("goal_id") or not arguments.get("todo_id"):
rejected.append("expected_source_revision:requires_exact_todo")
if arguments.get("source_id", "local") != "local":
rejected.append("expected_source_revision:only_for_source_local")
exact_arguments = {"window_start", "window_end", "delivery_ref"} & arguments.keys()
if "expected_source_revision" in arguments and not detail_read:
exact_arguments.add("expected_source_revision")
for name in sorted(exact_arguments):
if view not in {"deliveries", "report_source"} or name == "delivery_ref" and view != "deliveries":
rejected.append(f"{name}:only_for_view_deliveries" if name == "delivery_ref" else f"{name}:only_for_view_deliveries_or_report_source")
Expand Down Expand Up @@ -219,6 +234,41 @@ def rejected_read_arguments(arguments: dict[str, Any]) -> list[str]:
return rejected


def _todo_detail_revision(row: dict[str, Any], source: dict[str, Any]) -> str:
# Bind both native source and permitted projection, so an old owner-only
# cursor cannot continue into a different redaction/presentation scope.
encoded = json.dumps([source["source_revision"], row], ensure_ascii=False, sort_keys=True)
return "sha256:" + hashlib.sha256(encoded.encode()).hexdigest()


def _todo_detail_page(row: dict[str, Any], arguments: dict[str, Any], revision: str) -> dict[str, Any]:
"""Page transport encoding only; canonical selection and redaction stay in Core."""
text = json.dumps(row, ensure_ascii=False, sort_keys=True)
offset = arguments.get("offset", 0)
if offset >= len(text):
return {"ok": False, "error": "todo_detail_offset_out_of_range"}
reference = {**arguments, "source_id": "local"}

def page(end: int) -> dict[str, Any]:
return {"offset": offset, "next_offset": end if end < len(text) else None,
"total_characters": len(text), "source_revision": revision,
"text": text[offset:end], "eof": end == len(text),
"next_read": {**reference, "offset": end} if end < len(text) else None}

# The JSON string escapes quotes/control characters again. Budget the
# encoded page, not just the original text, without splitting Unicode.
low, high = offset, min(len(text), offset + 24000)
while low < high:
end = (low + high + 1) // 2
if len(json.dumps(page(end), ensure_ascii=False)) <= 24000:
low = end
else:
high = end - 1
if low == offset:
return {"ok": False, "error": "todo_detail_page_unavailable"}
return {"ok": True, "detail_page": page(low)}


def agent_work_summary(agent: dict[str, Any]) -> dict[str, Any]:
"""Keep the existing quota projection small; never infer live presence."""
verified = agent.get("source_verified") is True
Expand Down Expand Up @@ -709,7 +759,7 @@ def read(self, tool: str, arguments: Any) -> dict[str, Any]:
goal_id,
owner_scope=self.owner_scope,
limit=limit,
offset=offset,
offset=0 if "expected_source_revision" in arguments else offset,
todo_id=arguments.get("todo_id"),
query=arguments.get("query", ""),
)
Expand Down Expand Up @@ -749,6 +799,24 @@ def read(self, tool: str, arguments: Any) -> dict[str, Any]:
page = [{**r, "todo_title": titles.get(r.get("todo_id"))} for r in page]
if not self.scope_valid():
return {"ok": False, "error": "authorization_changed"}
if view == "todos" and "expected_source_revision" in arguments:
if source.get("status") != "read":
return {"ok": False, "error": "todo_detail_unavailable"}
if len(page) != 1:
return {"ok": False, "error": "todo_detail_unavailable"}
revision = _todo_detail_revision(page[0], source)
if revision != arguments["expected_source_revision"]:
return {"ok": False, "error": "todo_detail_revision_mismatch"}
result = _todo_detail_page(page[0], arguments, revision)
if not result["ok"]:
return result
if not self.scope_valid():
return {"ok": False, "error": "authorization_changed"}
result.update({"view": view, "goal_id": goal_id, "source": source,
"rows": [], "matched": matched, "unknown": True, "source_id": "local",
"source_host": "local", "note": _TODO_DETAIL_GUIDANCE})
self.record(result)
return result
# Trim whole rows, never malformed JSON or undisclosed byte truncation.
while len(page) > 1 and len(json.dumps(page, ensure_ascii=False)) > 24000:
page.pop()
Expand All @@ -764,6 +832,13 @@ def read(self, tool: str, arguments: Any) -> dict[str, Any]:
"details": "omitted_due_to_size",
}
page[i] = _oversized_portfolio_index(row, gap) if view == "portfolio" else gap
if view == "todos" and arguments.get("todo_id") and source.get("source_revision"):
page[i]["read_reference"] = {
"view": "todos", "source_id": "local", "goal_id": goal_id,
"todo_id": arguments["todo_id"], "offset": 0,
"expected_source_revision": _todo_detail_revision(row, source),
}
page[i]["read_instruction"] = _TODO_DETAIL_GUIDANCE
# Building an oversized index crosses the typed presentation owner;
# a grant revoked during that read must suppress the entire response.
if view == "portfolio" and oversized and not self.scope_valid():
Expand Down
113 changes: 110 additions & 3 deletions tests/test_chat_manager_inspection.py
Original file line number Diff line number Diff line change
Expand Up @@ -453,7 +453,7 @@ def test_oversized_exact_todo_is_unknown_without_exposing_private_detail(tmp_pat
isolate_sqlite_runtime(tmp_path, monkeypatch)
registry, runtime, _ = promoted_create_fixture(tmp_path, provider=provider)
text = "[P0] Review the proposal before proceeding."
note = "Preserve the accepted decision and its stop condition. " * 650
note = 'Preserve "accepted" decisions. 中文🧭\n\\ Stop. ' * 900 + "Final stop condition."
created = add_goal_todo(
registry_path=registry, runtime_root_arg=str(runtime), goal_id="goal-a",
role="user", text=text, note=note, task_class="user_gate",
Expand All @@ -477,15 +477,94 @@ def test_oversized_exact_todo_is_unknown_without_exposing_private_detail(tmp_pat
assert result["oversized_rows"] == [0] and result["next_offset"] is None
assert result["unknown"] is True
assert note not in json.dumps(result) and len(json.dumps(result)) < 24000
# The transport must expose every permitted character, including escaping,
# without raising its encoded page budget or requiring cached state.
expected = details.read_manager_goal_details(
registry, runtime, "goal-a", owner_scope=True, todo_id=todo_id,
)["todos"][0]
reference = result["rows"][0]["read_reference"]
revision = reference["expected_source_revision"]
fragments = []
cursor = 0
while reference:
fresh = ManagerInspection(
context=tool.context, registry_path=registry, runtime_root=runtime,
owner_scope=True, scope_valid=lambda: True, record=lambda _: None,
)
part = fresh.read(CONTEXT_TOOL_NAME, reference)
assert part["ok"], part
fragment = part["detail_page"]
assert fragment["offset"] == cursor
assert fragment["source_revision"] == revision
assert len(json.dumps(fragment, ensure_ascii=False)) <= 24000
fragments.append(fragment["text"])
cursor += len(fragment["text"])
reference = fragment["next_read"]
assert fragment["next_offset"] == (cursor if reference else None)
assert fragment["eof"] == (reference is None)
assert len(fragments) > 1
assert cursor == fragment["total_characters"]
assert json.loads("".join(fragments)) == expected
assert expected["continuation"].endswith("Final stop condition.")
tool.owner_scope = False
external = tool.read(CONTEXT_TOOL_NAME, exact)
assert external["unknown"] is False and external["rows"][0]["title"] == text
assert "continuation" not in external["rows"][0]
assert external["oversized_rows"] == []
assert tool.read(CONTEXT_TOOL_NAME, result["rows"][0]["read_reference"]) == {
"ok": False, "error": "todo_detail_revision_mismatch"}
assert len(records) == 3
assert read_canonical_todos_if_promoted(runtime_root=runtime, goal_id="goal-a") == before


def test_todo_detail_rechecks_revision_scope_and_encoded_bounds(tmp_path, monkeypatch):
row = {"todo_id": "todo_report", "status": "open", "text": "Review",
"note": "A decision. " * 3000}
monkeypatch.setattr(details, "list_goal_todos", _todo_read_fixture([row]))
tool, records = inspector(tmp_path)
tool.owner_scope = True
exact = {"view": "todos", "goal_id": "alpha", "todo_id": "todo_report"}
reference = tool.read(TOOL_NAME, exact)["rows"][0]["read_reference"]
first = tool.read(TOOL_NAME, reference)["detail_page"]
following = first["next_read"]
assert following
row["note"] += " Do not publish."
count = len(records)
assert tool.read(TOOL_NAME, following) == {"ok": False, "error": "todo_detail_revision_mismatch"}
assert len(records) == count
reference = tool.read(TOOL_NAME, exact)["rows"][0]["read_reference"]
assert tool.read(TOOL_NAME, reference)["ok"]
assert tool.read(TOOL_NAME, {**reference, "offset": 10**9}) == {
"ok": False, "error": "todo_detail_offset_out_of_range"}
# Revocation during the canonical read withholds all fragments and logs.
grants = iter([True, False])
tool.scope_valid = lambda: next(grants)
count = len(records)
assert tool.read(TOOL_NAME, reference) == {"ok": False, "error": "authorization_changed"}
assert len(records) == count
tool.scope_valid = lambda: True
row["status"] = "done"
reference = tool.read(TOOL_NAME, exact)["rows"][0]["read_reference"]
assert tool.read(TOOL_NAME, reference)["ok"] # Read, never resume completed work.
monkeypatch.setattr(details, "list_goal_todos", lambda **_: {"ok": False})
assert tool.read(TOOL_NAME, reference) == {"ok": False, "error": "todo_detail_unavailable"}


@pytest.mark.parametrize("changes", [
{"offset": True}, {"offset": -1}, {"offset": 0.5},
{"query": "other"}, {"source_id": "ssh:other"}, {"view": "portfolio"},
{"todo_id": None}, {"expected_source_revision": "bad"},
{"expected_source_revision": None},
])
def test_invalid_todo_detail_does_not_read_core(tmp_path, monkeypatch, changes):
monkeypatch.setattr(details, "list_goal_todos", lambda **_: pytest.fail("No source read"))
tool, records = inspector(tmp_path)
args = {"view": "todos", "goal_id": "alpha", "todo_id": "todo_report",
"offset": 0, "expected_source_revision": "sha256:" + "a" * 64, **changes}
assert tool.read(TOOL_NAME, args)["error"] == "invalid_arguments"
assert not records


def test_agent_work_summary_bounds_content_without_inventing_execution():
summary = agent_work_summary({"agent_id": "worker", "source_verified": True,
"todos": [{"todo_id": "todo_1", "title": "x" * 25000,
Expand Down Expand Up @@ -870,7 +949,7 @@ class Process:
)


@pytest.mark.parametrize("read_view", ["todos", "todos_exact", "agents", "agent_route", "deliveries_window", "report_source"])
@pytest.mark.parametrize("read_view", ["todos", "todos_exact", "todos_paged", "agents", "agent_route", "deliveries_window", "report_source"])
def test_manager_runtime_installs_tool_and_records_real_subprocess_read(
monkeypatch, tmp_path, read_view
):
Expand Down Expand Up @@ -934,6 +1013,30 @@ def test_manager_runtime_installs_tool_and_records_real_subprocess_read(
"'view':'todos','goal_id':'alpha'", "'view':'todos','goal_id':'alpha','todo_id':'todo_sample'").replace(
"evidence['rows'][0]['title'] == 'Check the sample result'",
"evidence['rows'][0]['continuation'].endswith('Keep this a draft; do not publish.')"))
if read_view == "todos_paged":
fake.write_text(fake.read_text().replace(
"import json, sys", "import json, sys\nfragments = []\nrevision = None").replace(
"'view':'todos','goal_id':'alpha'", "'view':'todos','goal_id':'alpha','todo_id':'todo_sample'").replace(
" assert evidence['rows'][0]['title'] == 'Check the sample result'",
""" if 'detail_page' in evidence:
part = evidence['detail_page']
assert part['offset'] == sum(map(len, fragments))
assert revision == part['source_revision']
fragments.append(part['text'])
reference = part['next_read']
else:
assert evidence['unknown']
reference = evidence['rows'][0]['read_reference']
revision = reference['expected_source_revision']
if reference:
print(json.dumps({'id':900,'method':'item/tool/call','params':{
'threadId':'fixture-thread','turnId':'fixture-turn','tool':'loopx_manager_read',
'arguments':reference}}), flush=True)
continue
assert len(fragments) > 1
task = json.loads(''.join(fragments))
assert task['continuation'].endswith('Keep this a draft; do not publish.')
assert len(task['continuation']) > 30000"""))
if read_view == "deliveries_window":
fake.write_text(fake.read_text().replace(
"'view':'todos','goal_id':'alpha'",
Expand Down Expand Up @@ -965,7 +1068,7 @@ def collect(*args, **kwargs):
"todo_id": "todo_sample",
"text": "Check the sample result",
"status": "open",
"note": "Public background. " * 30 + "Keep this a draft; do not publish.",
"note": "Public background. " * (1800 if read_view == "todos_paged" else 30) + "Keep this a draft; do not publish.",
},
]),
)
Expand Down Expand Up @@ -1020,6 +1123,10 @@ def collect(*args, **kwargs):
assert len(reads) == 1
assert reads[0]["payload"]["reason"] == "no_binding"
assert reads[0]["payload"]["authority"] == "locator_only"
elif read_view == "todos_paged":
assert reads[0]["payload"]["rows"][0]["status"] == "oversized_record"
assert len(reads) > 2
assert reads[-1]["payload"]["detail_page"]["eof"] is True
else:
assert len(reads) == 1
assert reads[0]["payload"]["rows"][0]["agent_id" if read_view == "agents" else "todo_id"] == ("review-worker" if read_view == "agents" else "todo_sample")
Expand Down
Loading