Add trajectory debug export

[ceej640]

Addresses #10.

Summary:

• Add python -m gently.debug to create trajectory-debugging bundles for a session id, prefix, or session directory.
• Summarize session artifacts and write transcript excerpts without copying large image/volume payloads.
• Infer relevant source files from tool calls in decision/interaction logs.
• Add a coding-agent debugging prompt template, docs, and unit tests.

Verification:

• .\.venv\Scripts\python.exe -m pytest tests/test_debug_export.py -q -p no:cacheprovider
• .\.venv\Scripts\python.exe -m gently.debug --help
• git diff --check

[pskeshu]

Need to also add profilers, to measuring which is doing what, and when.

…

On Sat, 30 May 2026 at 22:22, ceej640 ***@***.***> wrote: Addresses #10 <https://github.com/pskeshu/gently/issues/10>. Summary: - Add python -m gently.debug to create trajectory-debugging bundles for a session id, prefix, or session directory. - Summarize session artifacts and write transcript excerpts without copying large image/volume payloads. - Infer relevant source files from tool calls in decision/interaction logs. - Add a coding-agent debugging prompt template, docs, and unit tests. Verification: - .\.venv\Scripts\python.exe -m pytest tests/test_debug_export.py -q -p no:cacheprovider - .\.venv\Scripts\python.exe -m gently.debug --help - git diff --check ------------------------------ You can view, comment on, or merge this pull request online at: https://github.com/pskeshu/gently/pull/30 Commit Summary - 1616544 <pskeshu@1616544> Add trajectory debug export File Changes (6 files <https://github.com/pskeshu/gently/pull/30/files>) - *A* docs/trajectory-debugging.md <https://github.com/pskeshu/gently/pull/30/files#diff-e7822b0367353083d9fdbc9ad20e66045afc3bc938ddb2f6cc47c9d7ff2dbeab> (38) - *A* gently/debug/__init__.py <https://github.com/pskeshu/gently/pull/30/files#diff-66f25cc45dfa7a11505594a11b08c1f73dd8d7679a319138edd64bfef2020ef4> (9) - *A* gently/debug/__main__.py <https://github.com/pskeshu/gently/pull/30/files#diff-45e50a9c7da7a5047acf080b599bd68e0ecaf6e99f622602fa72a324758a755d> (7) - *A* gently/debug/analyzer.py <https://github.com/pskeshu/gently/pull/30/files#diff-2d9d482180f69a671e175af8a4f54a3c8abd281e0976705ed8fc7563cac21b86> (363) - *A* gently/debug/prompts/debugging_prompt.md <https://github.com/pskeshu/gently/pull/30/files#diff-9216904dd846ffe1069497cb78b1eefab4a2669871399fa6f754cb063effb688> (18) - *A* tests/test_debug_export.py <https://github.com/pskeshu/gently/pull/30/files#diff-e8139521ae14b3bd84df00b79df44e5ce472037752bf0038beace7d40e5166f8> (65) Patch Links: - https://github.com/pskeshu/gently/pull/30.patch - https://github.com/pskeshu/gently/pull/30.diff — Reply to this email directly, view it on GitHub <https://github.com/pskeshu/gently/pull/30?email_source=notifications&email_token=ABVNN4CQHCTL4EZ3VSS4MXD45OJQDA5CNFSNUABEM5UWIORPF5TWS5BNNB2WEL2QOVWGYUTFOF2WK43UF4ZTONZVGQYDSNJTGWTHEZLBONXW5KTTOVRHGY3SNFRGKZFFMV3GK3TUVRTG633UMVZF6Y3MNFRWW>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVNN4CCIH4Z4C7J5NFYDBL45OJQDAVCNFSM6AAAAACZUCRUNSVHI2DSMVQWIX3LMV43ASLTON2WKOZUGU2TMMZSHA4TQMY> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

-- Kesavan

[ceej640]

Yes. A debug bundle is much more useful if it includes profiling/timeline information, not just the exported artifacts after the fact.

The current PR helps package session evidence for debugging, but it does not yet instrument runtime spans. A follow-up should add a low-overhead profiler/trace log with correlation IDs across:

• LLM calls, including latency and token/model metadata where available
• tool calls and tool results
• hardware queue/device waits
• perception/image-processing steps
• file I/O and datastore writes
• UI/WebSocket events
• errors, retries, and cancellation paths

Then python -m gently.debug can include a timeline/table summary showing which subsystem did what and when, plus the raw span log for deeper analysis. That would answer the profiler question cleanly without overloading this export-only PR.

[ceej640]

Follow-up implemented from this thread in commit 2d66534.

I added profiler/timeline support to debug exports at the bundle layer:

• The exporter now discovers profile.jsonl and profile_spans.jsonl in a session.
• It writes profile_summary.json with span count, duration by component, and slowest spans.
• debug_context.md includes a Profile Summary section so a coding agent can see which subsystem did what and when.
• The span parser is permissive enough for LLM calls, tool calls, hardware waits, perception, file I/O, and UI/WebSocket events.

This does not instrument every runtime subsystem yet; it makes the debug bundle ready to consume those profiler spans.

Verification:

• pytest tests/test_debug_export.py -q -p no:cacheprovider
• python -m gently.debug --help
• git diff --check

[ceej640]

Follow-up implemented from the profiler thread in commit 993cb28.

What changed:

• Added a small profiler span writer in gently/debug/profiler.py.
• Instrumented ToolRegistry.execute() to record tool-call spans with component/name/start/end/duration/status/error metadata.
• Span output goes to the active FileStore session as profile_spans.jsonl when available, or to GENTLY_PROFILE_PATH when that environment variable is set.
• Updated trajectory-debugging docs and tests so debug exports can consume the runtime spans added here.

This still is not full-system profiling across LLM calls, hardware waits, perception, file I/O, and UI/WebSocket events, but it starts the runtime instrumentation at the common tool execution layer.

Verification:

• non-writing compile check for profiler, registry, and debug analyzer modules
• pytest tests/test_tool_registry.py tests/test_debug_export.py -q -p no:cacheprovider
• git diff --check