Story
As an XMD maintainer debugging a running document, I want to inspect the live Effection operation tree below the journal, so I can investigate active work, resource ownership, cancellation, and teardown that durable history alone does not explain.
Example
A Prompt has recorded its result, but the command has not returned because provider cleanup is still waiting. The journal shows the completed turn. Runtime inspection shows the active operation ancestry and the work that remains during teardown, with enough labels or source information to locate its owner.
Another example starts two concurrent document branches and cancels one. Inspection helps distinguish the cancelled branch's remaining cleanup from the sibling that is still running.
Current gap
XMD's journal and REPL show durable execution history and selected live observations. They do not expose the underlying Effection tree for general debugging. Internal operations and resource teardown may remain active between durable events or after a result is recorded.
The upstream Effection inspector provides live tree inspection and recordings. Its fit to XMD's installed Effection version, runtime entrypoints, and compiled distribution needs investigation before choosing an integration.
Accepted direction
- Integrate with the Effection inspector where practical rather than create a second generic operation-tree inspector.
- Keep runtime observations distinct from the durable journal. A recording of an Effection tree is diagnostic evidence and does not become XMD replay history.
- Expose useful operation ancestry and lifecycle information. Determine what additional labels or metadata are needed to associate live work with an XMD component and source location.
- Observation preserves execution results, durable recording, permission enforcement, ownership, cancellation, and teardown behavior. Inspector resources have an explicit lifetime and are released when inspection ends.
- Source and journal associations may be absent. Several runtime operations may belong to one journaled effect; an apparent one-to-one mapping is not a required model.
- Integration is optional for ordinary execution. Its absence does not prevent documents from running.
Open design questions
- Which inspector hooks are available in the installed Effection version, including separately loaded package copies?
- What is the smallest useful initial host: a Deno source command, Node/Bun, the compiled binary, or a shared integration across them?
- How does an operator enable and connect to inspection, and who owns the observer's transport and shutdown?
- What tree state and context information does the inspector already expose? Which operation names, middleware installation labels, waits, or source locations need instrumentation?
- How much source/journal correlation belongs in the first delivery, and what information should be omitted or filtered from diagnostic displays and recordings?
- Should any debugger controls be exposed? This Story initially concerns observation; pause, stepping, and execution control require a separate explicit decision.
Evidence and completion
Use a deterministic document with nested work, two concurrent branches, and a resource whose cleanup can be held by a test-controlled signal. Inspect the live ancestry while work runs, cancel one branch, observe its held teardown, release the signal, and observe that branch disappear while its sibling continues.
Include a case where a durable result exists while cleanup is still active. This distinguishes runtime observation from another journal projection. Compare execution outcomes and journal behavior with inspection enabled and disabled, and verify observer shutdown leaves no listener, server, or background task owned by the integration.
The first design deliverable records the upstream capability and version assessment, a working inspection experiment, the proposed operator experience and host scope, instrumentation gaps, and the recommended delivery boundary. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
This is an independent follow-up Story with open design choices. Its companions are #892 (typed context requirements) and #893 (source relationships). Neither is required to start inspector integration; connecting all three is a later decision.
The shared distinction is: types describe required behavior, a source index describes code relationships, runtime inspection describes actual activity, and the journal describes durable execution history.
Out of scope
Changing replay or journal formats, replacing the REPL history projection, inspecting historical Workspace files, implementing a new generic Effection debugger, and adding execution controls without further product review.
Story
As an XMD maintainer debugging a running document, I want to inspect the live Effection operation tree below the journal, so I can investigate active work, resource ownership, cancellation, and teardown that durable history alone does not explain.
Example
A Prompt has recorded its result, but the command has not returned because provider cleanup is still waiting. The journal shows the completed turn. Runtime inspection shows the active operation ancestry and the work that remains during teardown, with enough labels or source information to locate its owner.
Another example starts two concurrent document branches and cancels one. Inspection helps distinguish the cancelled branch's remaining cleanup from the sibling that is still running.
Current gap
XMD's journal and REPL show durable execution history and selected live observations. They do not expose the underlying Effection tree for general debugging. Internal operations and resource teardown may remain active between durable events or after a result is recorded.
The upstream Effection inspector provides live tree inspection and recordings. Its fit to XMD's installed Effection version, runtime entrypoints, and compiled distribution needs investigation before choosing an integration.
Accepted direction
Open design questions
Evidence and completion
Use a deterministic document with nested work, two concurrent branches, and a resource whose cleanup can be held by a test-controlled signal. Inspect the live ancestry while work runs, cancel one branch, observe its held teardown, release the signal, and observe that branch disappear while its sibling continues.
Include a case where a durable result exists while cleanup is still active. This distinguishes runtime observation from another journal projection. Compare execution outcomes and journal behavior with inspection enabled and disabled, and verify observer shutdown leaves no listener, server, or background task owned by the integration.
The first design deliverable records the upstream capability and version assessment, a working inspection experiment, the proposed operator experience and host scope, instrumentation gaps, and the recommended delivery boundary. Product interface and architecture review settle the design before an implementation handoff is finalized.
References and relationships
packages/core/src/execute.ts,packages/core/src/agent/function-components.ts, andpackages/acp/src/provider.ts: execution and provider lifetimes to inspect.packages/cli/src/repl/session.tsandpackages/cli/src/repl/agent.ts: existing execution ownership and selected live observations.architecture.mdsections State ownership and Replay and effect transactions.This is an independent follow-up Story with open design choices. Its companions are #892 (typed context requirements) and #893 (source relationships). Neither is required to start inspector integration; connecting all three is a later decision.
The shared distinction is: types describe required behavior, a source index describes code relationships, runtime inspection describes actual activity, and the journal describes durable execution history.
Out of scope
Changing replay or journal formats, replacing the REPL history projection, inspecting historical Workspace files, implementing a new generic Effection debugger, and adding execution controls without further product review.