feat: progressive disclosure for tool results — view registry + drilldown loop

[dgenio]

What changed

Closes #17 — implements the progressive disclosure loop connecting ViewSpec, ArtifactStore.drilldown(), and ResultEnvelope.views into a usable agent-facing workflow.

New files

• src/contextweaver/context/views.py — new module (287 lines):
  • ViewRegistry class mapping MIME content types to ViewSpec generators
  • Built-in generators: _json_views, _csv_views, _text_views, _binary_views
  • generate_views() convenience function (module-level default registry)
  • drilldown_tool_spec() — returns a SelectableItem for agent tool catalogs
  • _detect_content_type() — heuristic content-type detection for generic MIME types
• tests/test_views.py — 32 tests covering all generators, registry, detection, and tool spec

Modified files

• src/contextweaver/context/firewall.py — apply_firewall() now accepts optional view_registry param, auto-generates ViewSpec entries and populates envelope.views
• src/contextweaver/context/manager.py — added:
  • ContextManager.drilldown() / drilldown_sync() — wraps artifact_store.drilldown() with optional context injection (inject=True appends result as ContextItem)
  • ContextManager.view_registry property
  • Small outputs in ingest_tool_result() now stored in artifact store with auto-generated views
• src/contextweaver/context/__init__.py — exports ViewRegistry, generate_views, drilldown_tool_spec
• src/contextweaver/__init__.py — same new exports
• tests/test_manager.py — 12 new tests: drilldown basic/json_keys/inject/sync/errors, auto-views on ingest, chained drilldown
• CHANGELOG.md — updated [Unreleased]

Why

The building blocks for progressive disclosure existed (ViewSpec, drilldown(), ResultEnvelope.views) but were not connected. Agents received ResultEnvelope with empty views and no structured way to request follow-up slices. This change wires everything together:

ingest_tool_result(data)
  → apply_firewall(data) → artifact_store.put() → ArtifactRef
  → view_registry.generate_views(ref, data) → list[ViewSpec]
  → attach views to ResultEnvelope
  → agent sees: summary + available views

agent calls: drilldown(handle, selector)
  → artifact_store.drilldown() → slice text
  → optionally inject into context as ContextItem

How verified

ruff format --check src/ tests/ examples/  →  79 files already formatted
ruff check src/ tests/ examples/           →  All checks passed!
mypy src/                                  →  Success: no issues found in 41 source files
pytest -q                                  →  479 passed in 19.76s
python examples/*.py                       →  all exit 0
python -m contextweaver demo               →  exit 0

Tradeoffs / risks

• Small outputs are now stored in the artifact store (previously they weren't). This is intentional — enables drilldown on all tool results regardless of size.
• Content-type detection for application/octet-stream uses heuristics (JSON parse attempt, CSV sniffer). Conservative: falls back to text/plain for decodable text, keeps original MIME for binary.
• text/* prefix matching falls through to text/plain generator (e.g. text/markdown gets line-based views).

Acceptance criteria checklist

• Auto-generated ViewSpec entries during ingest_tool_result() / firewall
• View registry with built-in generators for JSON/CSV/text/binary
• Extensible: users can register custom view generators
• ContextManager.drilldown() method
• drilldown_tool_spec() helper
• ResultEnvelope.views populated automatically
• Drilldown results injectable as new ContextItem entries
• Full type hints and docstrings
• Tests: 32 view tests + 12 manager drilldown/auto-view tests

[Copilot]

Pull request overview

This PR implements the progressive disclosure loop for tool results, connecting ViewSpec, ViewRegistry, ArtifactStore.drilldown(), and ResultEnvelope.views into a usable agent-facing workflow. It closes issue #17 by wiring together the existing building blocks (which previously existed in isolation) into a cohesive agent-callable flow.

Changes:

• New src/contextweaver/context/views.py module introducing ViewRegistry, built-in MIME-type generators (_json_views, _csv_views, _text_views, _binary_views), content-type detection, generate_views(), and drilldown_tool_spec()
• ContextManager gains drilldown() / drilldown_sync() methods and a view_registry property; ingest_tool_result() now stores all outputs (not just large ones) in the artifact store with auto-generated views
• apply_firewall() / apply_firewall_to_batch() extended with an optional view_registry parameter to populate ResultEnvelope.views on the firewall path

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
src/contextweaver/context/views.py	New module: ViewRegistry, view generators, content-type detection, drilldown_tool_spec()
src/contextweaver/context/manager.py	Adds drilldown(), view_registry property; stores small outputs in artifact store with views
src/contextweaver/context/firewall.py	Extends apply_firewall[_to_batch]() with optional view_registry to populate envelope.views
src/contextweaver/context/__init__.py	Exports ViewRegistry, generate_views, drilldown_tool_spec
src/contextweaver/__init__.py	Same top-level exports
tests/test_views.py	32 tests for generators, registry, detection, serialization, and tool spec
tests/test_manager.py	12 new integration tests for drilldown and auto-view generation
CHANGELOG.md	Changelog entries for all new public API additions

---

You can also share your feedback on Copilot code review. Take the survey.