Sigma-Reveal workspace observation

Install the component:

pip install git+https://github.com/Hoyant-Su/Agentic-Sigma-Reveal.git

Run against a task workspace explicitly approved for reading:

sigma-reveal ./workspace --task "Analyze sales.csv with Python" --budget-chars 2400

The workspace is recursively inspected up to depth four. File previews contain the first line, capped at 80 characters after reading up to 160 bytes. Use a prepared task workspace containing material the model may read. Traversal follows filesystem symlinks. File content is untrusted task data; preserve the receiving agent's instruction hierarchy.

Pass the returned text as initial workspace context before the first action. Continue obtaining current shell observations as execution changes files. This component produces a static initial view.

For Python integration:

from sigma_reveal import reveal

initial_context = reveal("./workspace", "Analyze sales.csv with Python", budget_chars=2400)

The return value is a plain text tree with selected file previews. An empty string means no node fits. Errors reading required filesystem inputs propagate.

The reference implementation scores task-name matches, depth, and extension/task-type compatibility. Exact tree knapsack maximizes their summed score under ancestor closure and an additive rendering budget. Each line, including a newline allowance, is rounded up to 16-character buckets; the budget is rounded down. The Python string character count of the returned tree stays within the budget. Token counts depend on the receiving model's tokenizer. Worst-case dynamic programming time is O(N B²), with N tree nodes and B budget buckets.

Source: Learning CLI Agents with Structured Action Credit under Selective Observation, section 3.2. This standalone extraction preserves the original scoring, traversal, rendering, and optimization at the default budget. Budgets below 16 characters return an empty view. The paper formulates a token-budget objective; its released implementation uses character buckets. This package exposes that implementation's units explicitly.

Method reference

The following entry identifies the paper introducing the workspace observation method used here.

@article{su2026structuredactioncredit,
  title = {Learning CLI Agents with Structured Action Credit under Selective Observation},
  author = {Su, Haoyang and Wen, Ying},
  year = {2026},
  journal = {arXiv preprint arXiv:2605.08013},
  doi = {10.48550/arXiv.2605.08013},
  url = {https://arxiv.org/abs/2605.08013}
}