fix: context-aware command visibility for agent executor and planner

[sanchit056]

Two related fixes that make the command lists shown to the agent and the planner context-aware:

• Executor: re-scope the ReAct agent's available_commands to the current context whenever it changes (set_current_*, go_up, reset_context) via a context-change observer on the Workflow, so the agent never acts on a stale command list after a mid-trajectory switch.
• Planner: build_query_with_next_steps now uses get_all_contexts_command_display_text so the planner sees every available context's commands

Summary by Sourcery

Make agent and planner command visibility context-aware to avoid stale or incomplete command lists.

Enhancements:

• Add a workflow-level context change listener mechanism to notify observers on command context switches.
• Re-scope the ReAct executor agent's available_commands to the current context whenever the workflow context changes.
• Expose a command display helper that lists commands grouped by all contexts, not just the active one, for planner consumption.
• Ensure the ReAct agent's inputs reference the active run's argument dict so mid-run updates affect the ongoing trajectory.

[sourcery-ai]

🧙 Sourcery has finished reviewing your pull request!

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The context change listener mechanism on Workflow only ever appends to _context_change_listeners and doesn’t expose any way to deregister or use weak references, which could cause long‑lived references to execution contexts/agents; consider adding a remove/unsubscribe API or using weakrefs to avoid leaks for short‑lived workflows.
• In _notify_context_change, you currently log only the exception message ({exc}); capturing exc_info=True or logging the full traceback would make diagnosing listener failures much easier while still honoring the “must never break context switching” requirement.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The context change listener mechanism on `Workflow` only ever appends to `_context_change_listeners` and doesn’t expose any way to deregister or use weak references, which could cause long‑lived references to execution contexts/agents; consider adding a remove/unsubscribe API or using weakrefs to avoid leaks for short‑lived workflows.
- In `_notify_context_change`, you currently log only the exception message (`{exc}`); capturing `exc_info=True` or logging the full traceback would make diagnosing listener failures much easier while still honoring the “must never break context switching” requirement.

## Individual Comments

### Comment 1
<location path="fastworkflow/command_metadata_api.py" line_range="680-681" />
<code_context>
+                sections.append("\n".join(parts))
+
+            return "\n\n".join(sections)
+        except Exception as e:  # callers must never break on metadata assembly
+            return base_text
+
     @staticmethod
</code_context>
<issue_to_address>
**suggestion (bug_risk):** Log or surface minimal details when falling back after an exception

Catching all exceptions and returning `base_text` protects callers, but it also hides routing/CRD problems entirely. Please add at least a debug or warning log (with sensitive details redacted) so misconfigurations can be detected while still maintaining the "never break" behavior for metadata assembly.

Suggested implementation:

```python
            return "\n\n".join(sections)
        except Exception as e:  # callers must never break on metadata assembly
            logger.warning(
                "Failed to assemble command metadata; falling back to base_text.",
                exc_info=True,
            )
            return base_text

```

To make this compile and follow existing logging conventions, ensure that:
1. A module-level logger is defined, for example:
   `logger = logging.getLogger(__name__)`
2. The `logging` module is imported at the top of `fastworkflow/command_metadata_api.py` if it is not already:
   `import logging`
If this file already uses a different logging helper or framework (e.g. a shared `logger` from your codebase), replace the `logger` usage in this patch with that existing logger instance instead.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}

[sourcery-ai]

suggestion (bug_risk): Log or surface minimal details when falling back after an exception

Catching all exceptions and returning base_text protects callers, but it also hides routing/CRD problems entirely. Please add at least a debug or warning log (with sensitive details redacted) so misconfigurations can be detected while still maintaining the "never break" behavior for metadata assembly.

Suggested implementation:

            return "\n\n".join(sections)
        except Exception as e:  # callers must never break on metadata assembly
            logger.warning(
                "Failed to assemble command metadata; falling back to base_text.",
                exc_info=True,
            )
            return base_text

To make this compile and follow existing logging conventions, ensure that:

1. A module-level logger is defined, for example:
   logger = logging.getLogger(__name__)
2. The logging module is imported at the top of fastworkflow/command_metadata_api.py if it is not already:
   import logging
   If this file already uses a different logging helper or framework (e.g. a shared logger from your codebase), replace the logger usage in this patch with that existing logger instance instead.

[drawal1]

closed. I made the recommended change to the PR and resubmitted as 2.30.1