The issue requests adding Bourse, an OpenAI‑compatible AI capacity reseller, to LiteLLM's official providers list and providing a dedicated documentation page. Currently users must use the generic openai_compatible workaround; a named provider entry would make discovery and configuration clearer.

Create a new provider documentation file (e.g., docs/providers/bourse.md) following the existing template, add Bourse to the providers list in the documentation navigation (mkdocs.yml), ensure the page includes base URL, authentication, model naming, and a short description. Verify the docs build successfully and that the new entry appears in the generated site.

Copy the frontmatter and structure from a similar provider doc (e.g., openai.md), keep content concise and accurate, link to Bourse's API guide, add the entry to the nav section under 'Providers', run `mkdocs build` locally to check for broken links or formatting issues, and submit a PR with a clear description.

The PythonTools.run_python_code method uses `safe_globals or globals()` and `safe_locals or locals()` for its execution namespace. Because the check is falsy‑or, passing an empty dict still falls back to the interpreter's full globals, which includes __builtins__ and allows arbitrary code execution when untrusted input is passed to the tool. This is a critical code‑injection vulnerability (CWE‑94).

1. Locate libs/agno/agno/tools/python.py and change the initialization of self.safe_globals and self.safe_locals to use an explicit None check (e.g., `self.safe_globals = safe_globals if safe_globals is not None else globals()`). 2. Ensure that providing an empty dict truly restricts the namespace (no __builtins__ unless explicitly added). 3. Add unit tests that verify: a) default behavior remains unchanged for backward compatibility (or add a deprecation warning if changing), b) explicit safe_globals={} does not contain __builtins__, c) attempting to execute `import os` via run_python_code raises NameError when safe_globals is empty. 4. Update any documentation or docstrings reflecting the behavior.

First reproduce the issue locally to confirm the vulnerability. Then make the smallest possible change to fix the namespace fallback. Write automated tests before and after the change to ensure the fix works and does not break existing usage. Keep the change isolated to the initialization logic; avoid modifying the exec call itself. If altering the default behavior could be a breaking change, consider adding a deprecation warning and preserving the old behavior for a release cycle, or make the change opt‑in via a new parameter. Finally, run the existing test suite to ensure no regressions.

The SDK's tools/list endpoint advertises JSON Schema draft-07 for Zod v4 schemas, even though Zod v4's native toJSONSchema() outputs the SEP-1613 default dialect 2020-12. This explicit downgrade causes strict MCP clients (which expect 2020-12) to reject tool definitions, rendering all tools unusable before any tool call is made.

Locate the two invocations of toJsonSchemaCompat in the MCP server code (likely src/server/mcp.ts) where inputSchema and outputSchema are converted for Zod v4 schemas. Add an explicit target option: { target: 'draft-2020-12' } to match SEP-1613 default. Add or update a test that registers a Zod v4 tool and asserts the advertised $schema in tools/list response is "http://json-schema.org/draft-2020-12#". Ensure existing Zod v3 behavior remains unchanged.

Reproduce the issue locally with a minimal server using Zod v4, verify the incorrect $schema. Apply the smallest possible change (only the target parameter). Run the full test suite to ensure no regression. Keep the Zod v3 path untouched, as it legitimately emits draft-07. Document the reasoning in a commit message referencing SEP-1613.

用户希望在 LlamaHub 集成页面中列出他们新发布的工具包 llama-index-tools-truth-bear-gauge，该工具包提供三个基于 Truth Bear GAUGE API 的工具（coverage_check、catalog_lookup、record_request），用于获取美国联邦机构的官方来源信号数据。目前该工具包尚未出现在官方集成列表中，导致潜在用户难以发现和使用。

定位 LlamaHub 集成文档或配置文件（如 docs/integrations.md 或 llama_hub/ 集成列表），按照现有条目的格式添加 llama-index-tools-truth-bear-gauge 的条目，包括名称、简要描述、PyPI 链接、源码链接以及工具功能概述；确保无拼写错误并保持风格一致；提交 PR 并按照项目的 PR 模板填写信息。

先浏览最近的类似增强 PR，了解所需的元数据格式；验证提供的 PyPI 和源码链接是否可访问；在本地尝试安装 llama-index-tools-truth-bear-gauge 并导入 TruthBearGaugeToolSpec 确保能正常工作；保持更改最小，只修改文档或列表文件；PR 描述中简要说明工具的价值和无额外依赖的特点；等待维护者审查并根据反馈做出微调。

The generic guardrail API can only block or accept whole tool calls; it cannot return a modified version of a tool call's arguments. This forces agents to either block an entire turn (losing useful work) or abandon the gateway's guardrail service, leaving sensitive data in tool arguments unguarded.

Review the contributor's branch, verify that GenericGuardrailAPIResponse gains a tool_calls field and that _build_guardrail_return_inputs forwards it, add unit tests for both request and response guardrail paths, ensure backward compatibility, and run the existing test suite.

Make minimal changes following existing patterns, keep the new field optional with default None, add tests covering scenarios where tool calls are modified and where they are unchanged, avoid breaking changes, and update any relevant documentation if needed.

Dify currently does not include Azerbaijani (az-AZ) among its UI locales, so users cannot select Azerbaijani in the console. The contributor has prepared a full set of translation files (37 files, 5960 strings) matching the existing en-US structure and listed the exact places that need updates (language config files, dayjs locale, and a Python constant). Adding this locale will make the platform accessible to Azerbaijani-speaking users.

Copy the provided az-AZ translation files into web/i18n/az-AZ; update web/i18n-config/languages.ts and web/i18n-config/language.ts to register the new locale; add the dayjs locale import in web/utils/format.ts; ensure the locale resource is exported in web/i18n-config/locale-resources/az-AZ.ts; add the corresponding timezone constant in api/constants/languages.py; run lint and any existing i18n tests to verify the new locale loads correctly.

First, run the existing i18n lint/validation script to confirm the translation files follow the required format (key order, plural branches). Make the minimal changes listed above, then start the dev server and switch the UI language to Azerbaijani to verify all strings appear correctly. If there are unit tests for language loading, add a test case for az-AZ. Keep the PR focused on the locale addition only, referencing this issue in the description.

The repository's automated Python dependency maintenance workflow has successfully generated updated dependency files and pushed them to the automation branch `automation/python-dependency-maintenance`. However, GitHub Actions lacks permission to create pull requests in this repo, so a maintainer must manually open a PR from that branch to merge the dependency updates. The issue provides the exact commands and PR description needed to do so.

Create a pull request from the automation branch `automation/python-dependency-maintenance` targeting `main` using the supplied `gh pr create` command (or manually via the GitHub UI). Verify that the PR builds and passes CI, then merge after review.

First, ensure the automation branch exists locally (`git fetch origin automation/python-dependency-maintenance`). Run the provided script or copy the PR body and title into a new PR. Confirm that the changes only affect dependency files (e.g., `python/uv.lock`, `pyproject.toml`). Run any relevant CI checks locally if possible, then request a quick review from a maintainer familiar with the Python workspace.

The issue questions the semantics of token columns (prompt_tokens, completion_tokens, total_tokens) in spend_logs rows when a response cache hit occurs. Currently, a cache hit logs spend=0 but replays the original token usage, causing token‑based reports to double‑count while cost‑based reports show zero. The author asks whether the token columns should represent actual provider consumption, served volume, or another basis, and requests clarification (or a possible code/doc change) to define the intended contract.

Examine the three code paths mentioned: proxy cost hook (setting spend=0 on cache_hit), caching handler (_async_log_cache_hit_on_callbacks) that invokes async_success_handler, and the logging utility (StandardLoggingPayload) that reads token columns from the cached result. Determine whether token columns should be zeroed for cache hits or kept as served volume. If the decision is to keep served volume, add clear documentation/comments in the relevant files (and possibly a docstring or README note) explaining the convention. No functional change is required unless the maintainers decide to alter the behavior.

1. Create a minimal reproduction (two identical calls with cache enabled) to confirm current behavior. 2. Locate the exact lines where token columns are populated for cache hits. 3. Decide on the intended basis after reviewing the code and discussion. 4. If documentation is sufficient, add inline comments or a docstring clarifying that token columns reflect served volume (or provider consumption) on cache hits. 5. Run existing tests to ensure no regression. 6. Submit a PR with the doc changes and optionally a test that asserts the current token‑column behavior.

The SDK's `mapMiniTarget` function defaults to JSON Schema draft-07 when no explicit target is provided, causing all `outputSchema` values generated by `McpServer` to carry a `$schema` URI pointing to draft-07. Clients that strictly validate against JSON Schema 2020-12 reject these schemas, rendering any MCP server that declares an `outputSchema` unusable (e.g., Claude Desktop, Claude Code).

1. Locate `src/server/zod-json-schema-compat.ts` and change the fallback in `mapMiniTarget` from `'draft-7'` to `'draft-2020-12'`. 2. Run the existing test suite to ensure no regressions. 3. Add a unit test (if none exists) that verifies `outputSchema` emitted by `McpServer` uses the 2020-12 schema URI. 4. Optionally, verify that `inputSchema` behavior remains unchanged and that the change does not break any downstream consumers.

First reproduce the issue locally by creating a minimal MCP server with an `outputSchema` and attempting a tool call from a client that enforces draft-2020-12 validation. After applying the one-line change, confirm the schema now uses `https://json-schema.org/draft/2020-12/schema`. Run the full test suite, check for any lint or type errors, and update the changelog if the project maintains one.

在 declarative CustomerSupport 示例中，escalate_agent 通过结构化输出（IsComplete + UserMessage）返回结果，但 host 目前只能通过 autoSend: true 获取原始 JSON 文本，无法统一提取 UserMessage 字段进行用户可见渲染。用户希望得到一种不依赖特定 agent 或字段名的、从 output 中统一获取用户友好文本的官方做法。

阅读 CustomerSupport.yaml 及其对应的 Python/.NET 示例，定位 host 渲染 output 的代码（如 autoSend 处理逻辑），确认是否已有机制指定输出字段作为用户可见消息；若无，则撰写文档或提出最小的输出规范扩展（例如 output.messageField），并给出在 host 中如何自行解构 JSON 的示例。

1. 运行样例以复现目前只能看到原始 JSON 的现象； 2. 搜索代码库中与 output.autoSend、responseObject 相关的处理函数； 3. 查看是否已有类似 `output: { messagePath: "UserMessage" }` 的字段或可通过模板引用实现； 4. 若无现成方案，记录最小变更方案并说明向维护者确认的步骤； 5. 保持更改仅限于文档或示例注释，除非维护者同意修改规范。

Operators need a way to disable new Responses API WebSocket connections without taking down the entire proxy. Currently there is no environment variable to reject these WS connections early, forcing operators to stop the whole service or change routing to prevent new sessions.

Locate the Responses WebSocket route handler in the proxy code (likely under litellm/proxy/routes/), add an early check for the environment variable LITELLM_DISABLE_RESPONSES_WEBSOCKET, and if set, reject the WebSocket with close code 1008 and reason 'Responses WebSocket is disabled' before any authentication or provider logic. Ensure existing behavior when the variable is unset or false. Add a unit/integration test that verifies the rejection and that other proxy routes remain functional. Update any relevant documentation or env var list.

Follow the pattern used for other environment-based feature flags in the project (e.g., using os.getenv with a default false). Keep the change minimal and isolated to the route handler. Test with a websockets client to confirm the close code and reason. Verify that HTTP routes (e.g., /v1/chat/completions) still work when the flag is set. If there is a shared middleware for WS authentication, place the check there to avoid duplication.

When a request handler throws an `McpError`, the SDK prefixes the error message with "MCP error <code>:" twice: once when the error is constructed and again when the client reconstructs the error from the JSON‑RPC response. This results in a client‑visible message like "MCP error -32601: MCP error -32601: Unknown tool: nope" instead of a single prefix.

Locate the server‑side error serialization logic (likely in src/shared/protocol.ts or similar) where a thrown `McpError` is turned into a JSON‑RPC error object. Modify the serialization to send the raw `error.message` (without the MCP prefix) so that the client only adds the prefix once when rebuilding the error. Ensure both the normal response path and the queued‑response path in `_onresponse` are updated. Add a regression test that verifies the wire message contains no prefix and the client‑visible message contains exactly one prefix for a handler that throws `McpError`.

First reproduce the issue locally with the provided snippet over `InMemoryTransport`. Identify the exact function that converts a thrown error to the JSON‑RPC error payload. Make the minimal change to strip the prefix only when serializing, preserving the existing `McpError` constructor behavior for local presentation. Run the existing test suite to ensure no regressions, then add the new test covering both v1 and v2 code paths. Keep the change backward‑compatible for v2 clients, which already handle the prefix correctly.

The @modelcontextprotocol/server@2.0.0 and @modelcontextprotocol/core@2.0.0 packages list MIT as their license in package.json, but the bundled LICENSE file indicates a contribution‑dependent MIT/Apache-2.0 coverage. This creates uncertainty about which license actually governs the distributions and whether the manifest labels need correction or additional notices are required for consumers.

1. Examine the LICENSE file at the referenced commit to determine its exact terms and any Apache-2.0 clauses. 2. Check the package.json files for @modelcontextprotocol/server and @modelcontextprotocol/core to see their "license" field. 3. Identify any third‑party components that might be under Apache-2.0 or other licenses. 4. Decide whether the package.json license field should be changed (e.g., to "MIT" or "MIT OR Apache-2.0") or whether a NOTICE file with attribution is needed. 5. Update the manifests or add appropriate documentation, then submit a PR.

Use the commit SHA cc4b41617ce3601b1290d67216ea0b194a3cd9ac to ensure you’re looking at the exact versions. Verify the license text with a tool like licensee or manually read the LICENSE. If only MIT applies, keep the manifest as MIT; if Apache-2.0 code is present, adjust the license field to an SPDX expression or add a NOTICE with required attributions. Keep changes minimal, update only the affected packages, and include a test that confirms the license metadata matches the source.

The TypeScript SDK's `registerTool` (via `src/services/schema-dialect.ts`) advertises JSON Schema draft-07 in the `tools/list` response, while the MCP spec (SEP-1613) requires draft-2020-12. Strict clients that only accept draft-2020-12 reject the schema, rendering all tools unusable even though the SDK's own tests pass.

Locate `src/services/schema-dialect.ts`, find where the `$schema` property is set on outgoing `tools/list` payloads, change the hardcoded value from "http://json-schema.org/draft-07/schema#" to "https://json-schema.org/draft/2020-12/schema". Run the existing test suite (especially `server.test.ts`) to ensure no schema constructs that differ between drafts are used, and add a test verifying the emitted schema's `$schema` field. Update any relevant documentation or comments if needed.

First reproduce the issue by running a minimal server and inspecting the `tools/list` output to confirm draft-07. Apply the smallest possible change, run `npm test` and `npm run lint` to ensure no regressions, and keep the change limited to the dialect file. If the project has a contributing guide, follow its PR template and describe why the change is safe (referencing the existing schema validation assertions).

The README quickstart currently only shows a synchronous usage example. Adding a short async snippet would help new users who prefer or need to use the async API, making the quickstart more complete and aligned with the documentation that describes both sync and async usage.

编辑 README.md，在 quickstart 部分的同步示例之后插入提交的 async 示例代码块，确保代码格式正确且可直接运行。

先在本地克隆仓库，检查 README 的当前内容；插入代码后，运行该 async 示例（或使用 doctest）确保无语法错误；保持与现有风格一致（缩进、代码块标记）；提交 PR 时简要说明更改目的。

The CompactionProvider skips compaction when a ChatClientAgentSession has a non‑whitespace ConversationId. In the .NET agents code, a special sentinel value "_agent_local_chat_history" is set on the session to mark locally‑managed chat history, but the current guard treats it as a remote‑managed session and incorrectly prevents compaction. The issue asks whether this sentinel should be excluded from the skip logic.

Locate dotnet/src/Microsoft.Agents.AI/Compaction/CompactionProvider.cs lines 134‑135, find the constant LocalHistoryConversationId (likely defined in PerServiceCallChatHistoryPersistingChatClient.cs or a shared file), and modify the guard to also check that chatClientSession.ConversationId is not equal to the sentinel. Ensure the change does not break existing behavior by running relevant unit tests and, if needed, add a test that sets the sentinel ConversationId and verifies compaction proceeds.

First reproduce the behavior: set session.ConversationId to "_agent_local_chat_history" and confirm compaction is skipped. Then apply the minimal change, run the existing test suite to verify no regressions, and add a focused unit test for the sentinel case. Keep the change scoped to this file; avoid altering unrelated logic. Use string ordinal comparison for performance and clarity.

When AgentOS runs behind nginx (a common production reverse‑proxy setup), nginx buffers Server‑Sent Events (SSE) responses by default, causing streamed events to arrive in delayed bursts or only after the whole run finishes. This degrades user experience and can trigger idle timeouts. Adding the `X-Accel-Buffering: no` header to Agno's SSE responses disables nginx buffering for those responses, restoring token‑by‑token delivery without affecting direct connections or other proxies.

Locate all `StreamingResponse` constructions used for SSE endpoints in `os/routers` (agents, teams, workflows) and `os/interfaces` (a2a, agui). Add the header `X-Accel-Buffering: no` to each response, either directly or via a small helper/subclass that wraps `StreamingResponse`. Ensure the header is only added for SSE responses and verify that existing functionality remains unchanged.

Create a reusable function or custom `SSEStreamingResponse` class that injects the header, reducing duplication. Test by running the server locally and using `curl -N` or a simple HTML EventSource client to confirm immediate flushing. Add a unit test that checks the header is present on SSE responses. Keep changes minimal and avoid modifying non‑SSE routes.

The `ExperimentalClientTasks.getTaskResult` method declares its `resultSchema` parameter as optional, but when called without a schema it passes `undefined` to the internal protocol layer, which tries to read `._zod` from the undefined value and throws a TypeError. This makes the optional parameter unusable and forces callers to always supply a schema, contradicting the type signature.

1. Locate `src/experimental/tasks/client.ts` and examine `getTaskResult` implementation. 2. Compare with `getTask` and `listTasks` to see how they provide a default schema (likely `CallToolResultSchema`). 3. Modify `getTaskResult` to default `resultSchema` to `CallToolResultSchema` when undefined, both in the generic default and the runtime argument forwarded to `Protocol.getTaskResult`. 4. Update the corresponding server-side method if it has the same issue (optional schema passed to `Protocol.getTaskResult`). 5. Add or adjust a test that calls `getTaskResult` without a schema and asserts it succeeds. 6. Run existing tests and typecheck to ensure no regressions.

First reproduce the issue using the provided snippet to confirm the error. Then look at the existing `getTask`/`listTasks` implementations for the exact default schema they use. Make the smallest change that aligns the wrapper’s signature with the protected method’s requirement. Write a focused test before fixing to prevent regression. After the fix, run the full test suite and `npm run typecheck` to verify correctness.

In the v1.x TypeScript SDK, the validation of a tool result's `structuredContent` incorrectly runs even when `isError: true`, due to a missing `!result.isError` guard. This causes the client to throw an MCP error -32602 for error results that carry structured content, while the v2 SDK correctly skips validation for errors. The inconsistency leads to interoperability breaks between v1.x servers and clients, especially when tool validators are cached after a prior `tools/list` call.

Locate the validation block in `src/client/index.ts` (around line 740) and add `!result.isError` to the condition. Check the same logic in `experimental/tasks/client.ts` and apply the fix there if needed. Add unit tests that reproduce both scenarios: calling a tool that returns an error with structuredContent, with and without a prior `tools/list` to populate `_cachedToolOutputValidators`. Ensure existing tests pass and linting succeeds.

First reproduce the issue locally using the provided snippet to confirm the bug. Make the minimal change (two-line guard) and run the full test suite to verify no regressions. Add tests that cover error results with structuredContent under both cached and uncached validator states. Follow the project's coding style, include a clear PR description referencing issue #2748, and request review from maintainers.

The llama-index-callbacks-langfuse package still uses the legacy LlamaIndexCallbackHandler and pins langfuse<3, creating a second tracing stack that diverges from the current OpenTelemetry/OpenInference instrumentation. Users need a clear deprecation path to migrate to the supported langfuse>=4.7 with openinference-instrumentation-llama-index and LlamaIndexInstrumentor.

Mark the package as deprecated in a final release (add deprecation warning, update version), remove the langfuse<3 constraint, update README and docs to point to the OpenTelemetry/OpenInference integration, add a migration example, ensure CI/tests pass, and optionally add a changelog entry.

Check existing deprecation patterns in the repo, add a warnings.warn call in the package's __init__, follow semantic versioning for a final release, run the smoke-test migration example, verify no breaking changes for existing users beyond the deprecation notice, and keep the PR focused and small.

The Dispatcher class in llama_index_instrumentation/dispatcher.py uses mutable default arguments (list literals) in both Pydantic Field defaults and its __init__ parameters. This causes the default lists to be shared across instances when the constructor overrides the field default for span_handlers, leading to unintended cross-instance state mutation and preventing the intended default [NullSpanHandler()] from being applied.

1. 修改 dispatcher.py 中的 Pydantic Field 声明，将 default=[] 改为 default_factory=list，将 default=[NullSpanHandler()] 改为 default_factory=lambda: [NullSpanHandler()]； 2. 将 __init__ 中的 event_handlers 和 span_handlers 参数默认值改为 None，并在函数体里根据是否为 None 分别赋予 [] 或 [NullSpanHandler()]； 3. 添加单元测试验证两个 Dispatcher 实例的 handlers 是否互相独立，以及 span_handlers 默认是否包含 NullSpanHandler()； 4. 运行现有测试确保无回归。

先使用提供的复现脚本确认 bug 存在；查看文件上下文确认无其他依赖这些默认值的代码；改动后运行完整测试套件；确保更改向后兼容（仅修复默认值，不改变显式传入参数的行为）；在 PR 描述中引用此 issue 并说明修复思路。

The CustomAdapterOptions type incorrectly marks client, defaultHeaders, apiKey, etc. as never, which prevents passing authentication headers when using a custom transport. As a result, the SDK's internal client used during hydration (e.g., for client.threads.getHistory) lacks Authorization, causing 401 errors on self‑hosted endpoints that require auth, silently breaking subgraph/subagent discovery.

Locate the type definition for CustomAdapterOptions in the langgraph-sdk stream types (e.g., src/stream/types.ts or similar). Change the never typings for client, defaultHeaders, apiKey, callerOptions, fetch to their appropriate types (allowing ClientConfig fields). Ensure the change does not break existing usage, run the TypeScript compiler and the existing test suite to verify no regressions.

First reproduce the issue by setting up a minimal example with a custom transport that requires auth on getHistory. Then locate the type file, apply the minimal type fix, run tsc and the repo's test suite (including browser/react tests) to confirm everything passes. If adding a test, include a case that verifies headers are forwarded when using CustomAdapterOptions with useStream.

llama-index-readers-oxylabs 这个包的发布流水线断了：仓库 main 已经到 0.2.1，但 PyPI 上还停留在 0.1.2（2025-05-02 之后没再发过）。更糟的是，唯一可装的 0.1.2 在 Python 3.10/3.11 下直接 SyntaxError（f-string 表达式里含反斜杠，PEP 701 到 3.12 才放开），而声明支持的 requires-python 却包含 3.10/3.11，导致 pip 装上后一 import 就崩。代码里的修复其实早已合进 main，只是从来没发布，属于「改好了但用户拿不到」的发布问题，而不是缺代码修复。

代码层面基本无事可做：f-string 的修复已在 main 合并，不要重复修。真正有价值的贡献是补一道防线——检查仓库 CI（.github/workflows 下各 reader 包的测试 job）是否覆盖 Python 3.10/3.11，若没有，给 oxylabs reader 加一个 3.10/3.11 的导入/冒烟测试 job，防止未来再发一个语法损坏的包。其次是核对发布配置里该包是否被遗漏在 release 流程之外（issue 作者明确怀疑这一点）。真正的『重发到 PyPI』只能由维护者执行，贡献者做不了。

先在 Python 3.10/3.11 干净 venv 里复现 `pip install llama-index-readers-oxylabs==0.1.2` 后的 import 报错；然后去 main 读 `llama_index/readers/oxylabs/utils.py:45` 附近确认修复 commit 已存在（不要再为已修 bug 开 PR）；查 CI 的 matrix python-version 是否含 3.10/3.11；若要动发布配置，先看仓库 release 脚本里其他 reader 包是怎么被列出的，保持最小改动；PR 里说明这是回归防护而非功能变更。

OpenAI's Responses API can perform server-side compaction when `contextManagement` is enabled, emitting an opaque encrypted compaction item that must be persisted across subsequent requests. Mastra currently does not preserve this item: its stream normalization ignores unknown provider `custom` chunks, and `buildMessagesFromChunks` drops them, causing the compaction state to be lost before the next tool step, user turn, or memory reload. This prevents end-to-end use of OpenAI's compaction feature, which improves reasoning retention and reduces token usage for agent workloads.

Add typed OpenAI provider options for `contextManagement`; ensure built‑in OpenAI string models resolve via an AI SDK v7 provider that supports the option; define a canonical Mastra representation for provider‑native/custom content that retains `kind` and `providerMetadata` without treating the opaque value as text; modify stream normalization (aisdk/v5/transform.ts) to pass through `custom` chunks; update `buildMessagesFromChunks.ts` to preserve compaction items; propagate them through `MessageList`, memory persistence/reload, and model‑facing prompt conversion; restore the compaction item when constructing the next AI SDK v7 prompt; add unit and integration tests to verify compaction state survives multiple steps; update documentation and type definitions.

First reproduce the behavior by enabling `contextManagement` on a direct AI SDK v7 OpenAI model and confirming that a `custom` chunk with `kind: 'openai.compaction'` appears in the stream; follow existing patterns for handling provider‑specific content in Mastra (e.g., how reasoning items are preserved); keep changes minimal and backward‑compatible; add tests that simulate a multi‑step agent workflow where compaction is triggered and verify that the compaction item is present in the input of the subsequent request; run the existing test suite to ensure no regressions; coordinate with maintainers on any needed version bumps for `@ai-sdk/openai`.

AWS Bedrock AgentCore 和 Azure Foundry 只允许通过单一固定端点（如 /invocations）调用代理，导致 Mastra Studio 的聊天播放页、追踪查看器、HITL 暂停运行等需要访问 /api/* 路径的功能在部署后不可用。目前的唯一办法是运行一个完整的 Mastra 服务器“双胞胎”来为 Studio 提供这些接口，这会造成代码、凭证和基础设施的重复。此功能若能实现，开发者只需部署单实例即可拥有完整的 Studio 体验，显著降低运维成本和复杂度。

1. 调研 Studio 当前对后端 API 的调用方式（请求路径、方法、头、体、SSE 流）。 2. 在 Studio 客户端添加单端点模式的封装函数，将原始 REST 请求封装为 JSON（如 {method, path, headers, body}）并 POST 到 /invocations。 3. 在服务器端（Mastra 框架）新增中间件或路由，解析 /invocations 请求体，恢复原始请求并交给内部路由处理，原样返回响应（包括 SSE 流，若平台支持透传则直接转发，否则进行缓冲）。 4. 添加配置开关（例如 studio.singleEndpoint = true）以切换该行为，确保默认不影响现有部署。 5. 编写单元/集成测试覆盖普通请求、JSON 负载、SSE 流以及错误情况。 6. 更新文档说明在 AgentCore/Foundry 环境下如何启用单端点 Studio。 7. 验证在本地模拟单端点服务器（如使用 Express mock）和实际的 AgentCore/Foundry 环境下功能正常。

首先在本地启动一个最小的 Mastra agent 并使用现有 Studio 确认其对 /api/* 的请求细节；接着阅读 @mastra/studio 包中的网络层（如 http.ts 或 apiClient.ts）确定改动点；实现时保持对现有 API 的完全兼容，仅在启用单端点模式时走封装路径；优先实现非流式请求以快速验证，再处理 SSE 流，必要时查看平台文档或做小实验确认其对 SSE 的透传能力；提交 PR 前运行完整的测试套件并检查类型安全；在 PR 描述中明确说明配置方式和局限（如 SSE 是否受平台限制），并邀请维护者对实现细节进行审阅。

AgentOS's A2A interface is enabled without authentication by default. When a2a_interface=True and no credentials are configured, the A2A endpoints (agent discovery and remote invocation) are reachable by any network client, allowing unauthenticated discovery, agent execution, and potential remote code execution. This matches CWE-306 (Missing Authentication for Critical Function) with a CVSS 9.8 rating.

1. Examine app.py (auth_configured logic) and a2a.py (router mounting) to understand the authentication condition. 2. Decide on a fix: either enforce authentication when a2a_interface=True (e.g., require authorization or generate a default security key) or provide a clear opt-out mechanism. 3. Modify the relevant code to ensure middleware is installed for A2A when no auth is present, or raise a warning/error. 4. Add tests to verify that unauthenticated requests to A2A endpoints are rejected. 5. Update the cookbook documentation to include authentication configuration.

First, reproduce the issue with a minimal server and unauthenticated client calls. Then read the authentication and A2A code paths. Make minimal, focused changes. Ensure tests cover both authenticated and unauthenticated scenarios. Update any relevant documentation.

The agent orchestration loop in agno executes every tool call requested by the model immediately, because the default confirmation gate (requires_confirmation) is off and there is no global policy to pause or approve tool execution. This allows an attacker who can influence the model's output (e.g., via prompt injection) to trigger arbitrary code execution through tools like PythonTools, which ultimately calls exec() on user‑supplied code.

Modify the tool definition defaults to make requires_confirmation opt‑out for dangerous tools, or add a global safe‑mode flag that forces a confirmation pause unless explicitly disabled. Update libs/agno/agno/models/base.py run_function_calls to respect the new default, adjust libs/agno/agno/tools/function.py and libs/agno/agno/tools/toolkit.py default values, add unit tests that verify a tool call is paused when no confirmation is set, and ensure existing opt‑in behavior remains unchanged. Update documentation to reflect the new security‑by‑default behavior.

First reproduce the issue with a minimal script that mocks a model requesting a PythonTools call and confirms the code runs without pause. Then locate the exact default values mentioned in the issue, change them to a safe default (e.g., requires_confirmation=True for code‑executing tools) or introduce a configuration flag. Run the existing test suite to ensure no regression, add new tests for the confirmation pause, and manually test both the patched and opt‑out paths. Finally, update any relevant README or security docs.

The `CodingTools.run_shell()` method fails to properly validate command arguments when `restrict_to_base_dir=True`. Its `_check_command()` function unconditionally skips any token that starts with '-', allowing an allowed interpreter like `python` combined with a flag such as `-c` to bypass the sandbox check. After the check passes, the raw command string is executed via `subprocess.run(..., shell=True)`, enabling an attacker to write or execute arbitrary files outside the intended base directory.

1. Reproduce the PoC locally to confirm the bypass. 2. Examine `_check_command()` in `libs/agno/agno/tools/coding.py` to understand the flag‑skipping logic. 3. Design a fix that either validates arguments after flag parsing or rejects dangerous flag/interpreter combinations while preserving legitimate usage. 4. Update unit tests to cover the new validation and ensure existing functionality remains intact. 5. Run the full test suite and verify no regressions. 6. Prepare a PR with clear description of the security fix.

First reproduce the issue to confirm the vulnerability. Read the surrounding code to understand the intended sandbox behavior. Make the smallest possible change that blocks the injection vector (e.g., treat flag tokens as part of the command for path checks or implement an allowlist of safe flags). Add both positive and negative test cases. Keep the change backward‑compatible for legitimate use cases. Communicate the fix rationale in the PR and reference the related stalled PRs (#8468, #9472).

The /api/v1/agui endpoint streams text and reasoning content but does not stream intermediate output when client tools are used to generate HTML. As a result, the frontend receives no events while the model is executing tools, causing a noticeable delay and poor user experience.

Locate the agui endpoint handler and the tool execution pipeline; identify where streaming is currently applied (TEXT_MESSAGE_CONTENT, reasoning_content); modify the tool call logic to yield partial HTML or intermediate states as streaming events (e.g., via async generator or SSE); ensure the frontend can consume these events; add unit/integration tests to verify streaming behavior for HTML generation with tool calls; update any relevant documentation.

First reproduce the issue by calling the agui endpoint with a tool that generates HTML and confirm lack of intermediate events; trace the code path from request to tool execution to response; implement minimal changes that inject streaming events without breaking existing text streaming; run existing test suite to ensure no regressions; add a test that asserts events are emitted during tool execution; keep changes backward compatible and follow the project's async patterns.

When an agent using OpenAIResponses is served via AgentOS, the streaming response includes reasoning token usage but omits the actual reasoning events (start, content deltas, completion). Locally, both agent.arun and agent.aprint_response correctly stream reasoning content, indicating the model generates it but AgentOS drops it before sending to the client.

Examine AgentOS streaming endpoints to see where model response chunks are transformed; update libs/agno/agno/agent/_response.py's handle_model_response_chunk to emit reasoning start, content, and complete events alongside output content; add unit/integration tests that verify reasoning events appear in the AgentOS stream; ensure existing tests still pass.

Reproduce the issue locally by running AgentOS dev server and connecting a client; add logging to confirm reasoning chunks are received from the model; follow the existing pattern for creating events (e.g., create_reasoning_start_event); keep changes minimal and aligned with current event emission; run the test suite and update any documentation if the streaming contract changes.

During long-running browser automation tasks, performance degrades because the agent repeatedly serializes the entire DOM, accumulates an ever-growing LLM message history, and fetches browser state on every step even when unchanged. This leads to increasing latency, higher token usage, and excessive memory allocation, negatively impacting scalability for large sites or extended workflows.

Profile the current agent loop to locate DOM extraction/serialization, message history building, and browser state query code; implement incremental DOM diffing via mutation observers or cached snapshots; add a bounded message history with summarization; introduce a simple browser state cache invalidated on navigation/input/mutation; reduce temporary object allocations using generators or object reuse; add benchmarks and tests to verify performance improvements.

First reproduce the slowdown with a controllable large DOM (e.g., a page with many elements) and a multi-step agent task; use profiling tools (cProfile, memory_profiler) to quantify bottlenecks; make minimal, focused changes behind feature flags if needed; ensure existing tests pass and add performance regression tests; discuss approach with maintainers before large refactors.

When a client resumes an HTTP stream using a Last-Event-ID, the replayed request stream remains open indefinitely even after all correlated responses have been delivered or stored. This prevents the polling loop from converging and can cause race conditions where responses are missed, duplicated, or never terminate after closeSSEStream polling.

Locate the replayEvents handler and stream management code in the TypeScript SDK. Add logic to close/dispose of a replayed request stream when the _requestToStreamMapping (or equivalent) shows zero in‑flight requests for that stream. Ensure the close follows the same cleanup path used elsewhere (e.g., stream cancel callbacks). Write deterministic unit/integration tests covering the replay/store visibility race, successor dedup transfer, post‑poll completion, and the close‑after‑replay scenario for both main and v1.x branches.

First reproduce the issue by adding a test that sends a request, replays it with Last-Event-ID, and verifies the stream is closed after all responses are received. Keep changes minimal: only invoke the existing stream‑close function when the request mapping becomes empty. Follow the project's testing and linting conventions, run the full test suite, and ensure no regression in existing stream handling. Coordinate with maintainers if any API‑surface concerns arise.

DeerFlow allows users to install .skill packages but provides no way to export a saved custom skill from the UI. After editing a skill, the original uploaded package becomes stale, forcing users to manually locate files on disk and re‑package them for backup, transfer, or sharing. The request is to add an export feature that creates a portable .skill ZIP archive of the current saved skill, with a preview showing contents, size, requirements, and revision safety checks.

Implement the export API endpoints (GET /api/skills/custom/{name}/export-manifest and GET /api/skills/custom/{name}/export?expected_revision=…) with revision conflict handling, size/entry limits, and thread‑safe ZIP generation under the skill mutation lock. Add a UI dialog in Settings → Skills → Custom with Export button, preview pane (filename, file/directory counts, size, paginated paths, declared requirements, blockers), download button that shows revision conflict if the skill changed after preview, and appropriate cancellation/dismissal behavior. Write unit and integration tests for the API, UI tests for the dialog, and update documentation. Ensure the generated ZIP preserves executable flags, normalizes permissions, and respects filesystem boundaries (no symlinks, hardlinks, special files, nested skill roots).

First examine the existing PR #5332 to understand the current implementation baseline. Reproduce the issue locally by creating a custom skill, editing it, and verifying that no export option exists. Implement the backend endpoints first, adding revision checks and locking, then the frontend preview/download dialog. Keep changes small and focused: reuse existing skill storage and ZIP utilities where possible. Add tests that simulate concurrent skill updates to confirm 409 conflict on stale revision. Run the test suite and ensure no regressions. Follow the project's coding style and update any relevant README or API docs. Finally, request review from maintainers via the existing PR.

The payloads of write_file and str_replace tool calls (content, old_str, new_str) remain in the model‑bound AIMessage even when the call is blocked by the read‑before‑write gate or after a successful write. This wastes tokens because the same large arguments are repeatedly fed to the model and are never removed by existing middleware, which only truncates ToolMessage output or summaries.

Implement Step 1 of the proposal: (1) modify ReadBeforeWriteMiddleware to attach a `deerflow_write_block` marker to the error ToolMessage it returns for blocked calls; (2) create a shared helper in `agents/middlewares/tool_call_args.py` that rewrites all surfaces of an AIMessage (structured tool_calls, additional_kwargs["tool_calls"], Anthropic tool_use blocks, tool_call_chunks) replacing the payload fields with a short deterministic placeholder when the marker is present; (3) hook this helper into the model‑bound request path (e.g., in `wrap_model_call` or a dedicated middleware) so the placeholder is used only for the LLM context while the original arguments stay in graph state, tool receipts, checkpoints, and the journal; (4) add two config options (`read_before_write.elide_blocked_payloads` default true, `read_before_write.elide_min_chars` default 2000); (5) write unit tests verifying placeholder insertion, preservation of original args for hashing/checkpointing, and that successful writes are unaffected (step 2 deferred); (6) update any relevant documentation.

First reproduce the issue by attempting a write_file on an unread file and inspecting the AIMessage that reaches the model to confirm the full payload is present. Follow the existing middleware pattern: keep changes limited to the model‑bound request, avoid altering ToolMessage or state. Ensure the helper updates all four AIMessage surfaces consistently so strict providers cannot see mismatches. Test multi-surface rewrite, config flag behavior, and that tool call hashing and checkpoint snapshots retain the original arguments. Run the full test suite to guard against regressions.

AgentOS ships with authentication disabled by default (authorization=False and os_security_key=None). This causes the AuthMiddleware to never be installed and the per‑route dependency to always return True, exposing all REST endpoints (configuration, sessions, agent runs) to unauthenticated users. An attacker can read/modify agent configurations, session histories, and execute arbitrary agent runs, leading to critical confidentiality, integrity, and availability impacts.

Locate auth.py (lines 238-239) and app.py (lines 1235-1240) to understand the auth gate logic; change the default values (e.g., set authorization=True or require os_security_key) so that auth_configured evaluates to True unless explicitly disabled; add unit tests that verify AuthMiddleware is installed when no override is given and that /info returns auth_mode not equal to 'none'; update any relevant documentation or example code to reflect the new secure default.

First reproduce the issue using the provided commands to confirm auth_mode:none; make the smallest possible change to the default configuration; write tests that assert the middleware is present and that endpoints now require authentication (or at least report a non‑none auth mode); run the full test suite to ensure no regressions; if the change is backward‑incompatible, document the required opt‑out mechanism and update examples/cookbook accordingly.

The CodingTools.run_shell method uses an incomplete denylist of shell operators and then passes the command string to subprocess.run with shell=True. An attacker can bypass the denylist by encoding dangerous characters with chr() (e.g., python -c "exec(chr(...)+chr(...))") which contains no denylisted substrings, allowing arbitrary command execution on the host with the agno process privileges. This affects any application that accepts untrusted input for the command argument, including prompt‑injection scenarios.

1. Reproduce the PoC to confirm the bypass. 2. Examine agno/tools/coding.py: _check_command, run_shell, and the DEFAULT_ALLOWED_COMMANDS/denylist logic. 3. Replace the flawed denylist/substring check with a proper validation approach: either (a) switch to an allowlist of safe commands and disallow shell=True, using subprocess.run with a list of args, or (b) implement robust shell‑metacharacter detection (including encoded forms) before allowing shell=True. 4. Update unit tests to cover the bypass attempts and ensure existing legitimate uses still work. 5. Update documentation if the default behavior changes (e.g., note that restricted mode now safely blocks chr‑encoded payloads).

First, reproduce the issue locally using the provided script. Then read the coding.py file to understand the current validation flow and where the command is passed to subprocess.run. Implement the smallest change that eliminates shell=True or properly validates the command string—preferably using an allowlist and avoiding shell=True altogether. Write tests that attempt various obfuscations (chr, hex, unicode, base64) and verify they are rejected. Run the existing test suite to ensure no regression. Finally, open a PR with a clear description of the security fix, referencing CWE‑78 and the issue number.

RLM 模块目前没有将对话历史暴露给语言模型，导致其无法在推理过程中利用之前的轮次信息。用户希望在 RLM 中加入对 dspy.History 的一等支持，使语言模型能够看到随着对话积累而构建的消息历史，这与 ReActV2 中已经实现的机制类似。这样可以实现跨运行的持续交互，并且可以加入类似 #10217 提议的压缩钩子。

需要先查看 ReActV2 中如何使用 dspy.History 来构造 prompt，然后定位 RLM 模块中生成 LM 输入的位置（例如 core/rlm.py 中的循环），在该位置加入历史信息的拼接或注入；随后编写单元测试验证历史是否被正确传递且不破坏现有功能；最后更新文档或 README 说明新特性的使用方式。

首先复现现有 RLM 的行为，确保所有现有测试通过；参考 ReActV2 的实现路径，做最小的修改，只在必要的地方加入 History；在修改后运行完整的测试套件，特别是针对 RLM 的测试；如果有相关的示例或 notebook，更新它们以展示新功能；在提交 PR 前与维护者确认修改范围和是否需要额外的兼容性注意。

When `enableJsonResponse: true` is used on a stateful Streamable HTTP transport, the JSON-response path in `send()` resolves the pending response via `resolveJson` but never calls the stream mapping's `cleanup`. This leaves a `_streamMapping` entry leaked until the transport is closed. Conversely, during transport shutdown (`close()`), the mapping's `cleanup` removes the entry without settling the pending `Promise<Response>`, causing in‑flight JSON-mode POST requests to hang. The bug affects both the main branch and the v1.x line, leading to resource leaks and hanging HTTP requests.

1. Locate the Streamable HTTP implementation files: `packages/server/src/server/streamableHttp.ts` (main) and `src/server/webStandardStreamableHttp.ts` (v1.x). 2. Examine the JSON-response branch of `send()` to ensure it calls `stream.cleanup()` after `resolveJson`. 3. Examine the `cleanup()` method to ensure it settles any pending `resolveJson` promise (e.g., with a 503 error) before deleting the mapping. 4. Add or adjust unit/integration tests that verify: a) after a successful JSON-mode POST, `_streamMapping` size returns to zero; b) closing the transport during an in-flight JSON-mode POST results in the request receiving a 503 JSON‑RPC error and no hanging connection. 5. Run the existing test suite to confirm no regressions. 6. Submit a PR for v1.x (and optionally a backport to main if needed).

First reproduce the leak and hang locally using a minimal test that enables `enableJsonResponse`. Then study the fix already applied to main (commit #2286) to understand the exact pattern of calling `cleanup` after `resolveJson`. Apply the smallest possible change to v1.x that mirrors this pattern and also modifies `cleanup` to settle pending promises. Write regression tests before making changes to guarantee they catch the issue. Keep the change focused on the two methods; avoid refactoring unrelated code. Communicate intent in the PR description, referencing the original issue and any related draft PRs.

The SQLDatabase class assumes a single-catalog connection when initializing its SQLAlchemy inspector and reflecting metadata. In Trino, which supports multiple catalogs, this causes failures because the inspector is bound to only one catalog and schema names must be qualified as 'catalog.schema'. As a result, users cannot perform unified semantic table retrieval across all Trino catalogs using LlamaIndex's SQLDatabase/SQLTableNodeMapping.

创建 TrinoSQLDatabase 作为 SQLDatabase 的子类；在初始化时跳过父类的 inspector/reflect 调用，而是通过 Trino 的 information_schema 执行跨目录 UNION 查询来构建 MetaData；重写 get_single_table_info 和 get_table_columns 以使用自定义的元数据；保留 run_sql、insert_into_table 等其他方法不变；添加单元测试验证在模拟 Trino 环境下的目录感知行为；更新文档以说明该子类的用法。

首先阅读 llama_index/schema/SQLDatabase.py 了解 __init__、_inspector 和 _metadata 的使用；在本地使用一个 mock Trino 引擎或 Docker 中的 Trino 实例复现问题；确保子类遵循 Liskov 替换原则，所有继承的方法在新元数据下仍能正常工作；编写针对 get_single_table_info 和 get_table_columns 的测试，验证跨目录表的检索；在 PR 中包含更新的使用示例和任何必要的依赖说明。

在 1.16.1 自托管版中，通过 service API 作为 END_USER 调用已发布的 Advanced Chat 应用时，知识检索节点返回的图片附件不会被传递给 LLM 节点，导致工作流节点输入中缺少 #context_files# 键（键完全 absent）。同一工作流在 Studio preview（身份为 ACCOUNT）下可以正常获取附件。根本原因是 FileAccessScope 使用的 ContextVar 在 graphon 工作线程（threading.Thread）中没有被传播，导致端用户的段授权检查失败，附件加载器返回空列表。

1. 定位 graphon 工作线程的创建位置（graphon/engine/worker.py 中的 Worker 类）。 2. 在线程启前捕获当前的 contextvars.Context（使用 copy_context()），并在线程目标函数内通过 context.run() 执行实际的任务，以确保 FileAccessScope 等 ContextVar 对工作线程可见。 3. 修改 Worker.run 或 _run_tasks 方法，使其在捕获的上下文中执行节点加载和段访问检查。 4. 在本地重现问题：发布应用，以 END_USER 身份通过 /v1/chat-messages 调用，确认 #context_files# 出现；同时验证 ACCOUNT（Studio preview）和其他身份不受影响。 5. 编写单元测试或集成测试，断言在模拟 END_USER 调用时，段授权检查能够正确获取 granted_retriever_segment_ids。 6. 运行现有测试套件确保无回归。

作最小改动，仅在线程启动处注入上下文；避免修改业务逻辑。添加注释解释为何需要 copy_context，防止以后误删。确保修改不影响其他使用 threading.Thread 的地方（如需保持原有行为，可仅对 graphon Worker 分支做改动）。提交前跑完整的 CI，并手动检查日志确认没有出现 ContextVar 为 None 的情况。

When enable_jwt_auth is enabled, LiteLLM proxy acts as an OAuth 2.0 resource server but does not disclose which identity provider it trusts. Native clients (CLIs, IDE plugins, etc.) must manually maintain a mapping from the proxy URL to the IdP issuer and client ID for each environment, leading to drift and duplicated effort. The missing discovery mechanism forces every new client to re-implement this table.

Add a new route at /.well-known/oauth-protected-resource that returns JSON derived from existing JWT auth configuration (resource = PROXY_BASE_URL, authorization_servers = litellm_jwtauth.issuers[].issuer, bearer_methods_supported = ['header'], scopes_supported = ['openid']). Modify the JWT authentication middleware to include a WWW-Authenticate: Bearer resource_metadata="<proxy>/.well-known/oauth-protected-resource" header on 401 responses (and add error="invalid_token" when a token is present but invalid). Optionally support per‑issuer public client metadata configuration. Write unit tests for the endpoint and header injection, and update documentation to reflect the new discovery flow.

Reuse the existing litellm_jwtauth config structures to avoid adding new required fields. Follow RFC 9728 exactly for the JSON shape and header format. Ensure the change is backward‑compatible: when enable_jwt_auth is off, the endpoint should return 404 or not be registered. Test both successful and failed authentication paths to verify the header appears correctly. Add a simple integration test that proxies a request to /v1/models without a token and checks the WWW‑Authenticate header. Update the README or a dedicated docs page with an example of how a native client can use the discovery document.

When a hosted .NET agent uses a pre‑registered toolbox with a per‑user OAuth MCP connection, the consent link generated in the oauth_consent_request is tied to the container's system‑assigned managed identity instead of the calling user. This causes the sign‑in flow to fail with 'Code <id> not found' because the OAuth proxy creates the consent session for the managed identity, while the user’s token is never associated with the consent. The bug blocks any user‑specific toolbox usage from hosted agents, forcing work‑arounds that bypass the intended consent flow.

Locate the consent‑link generation code in the Foundry toolbox proxy (likely in FoundryToolboxBearerTokenHandler or AgentFrameworkResponseHandler). Verify that the user context (userId) from the inbound request is not being forwarded when building the OAuth consent session. Modify the relevant handler to propagate the caller’s user identity (or the x‑agent‑foundry‑call‑id that maps to it) so the proxy creates the consent session for the correct principal. Add unit/integration tests that simulate a hosted agent call with a user token and assert that the resulting consent link contains the user’s object ID. Ensure existing tests still pass and update the skipped ToolboxOAuthConsentHostedAgentTests to validate successful consent completion.

First reproduce the issue using the provided code sample in a local dev environment with logging to capture the userId in the token cache and the consent link. Keep changes minimal: only adjust the flow that attaches user context to the OAuth session. Run the existing test suite to avoid regressions, and add a test that covers the end‑to‑end consent completion scenario. Follow the repo’s PR template, reference the issue number, and clearly describe the fix and test coverage in the PR description.

The `createDurableAgent` API does not expose the `shouldPersistSnapshot` option that controls whether workflow snapshots are written to storage for each status. Currently, durable agents always persist snapshots for `pending`, `paused`, `suspended`, and `running` states, causing unnecessary storage writes and latency when auto‑recovery is disabled. Users need a way to opt out of persisting `running` snapshots while retaining the ability to resume from `suspended` or HITL states.

Locate the `createDurableAgent` implementation and its internal call to `createDurableAgenticWorkflow`. Add an optional `shouldPersistSnapshot` (or `persistRunningSnapshots`) field to the durable agent options type, forward it to the workflow creation call, and update the default behavior to preserve existing semantics. Add TypeScript definitions, update any relevant tests, and document the new option in the Durable Agent reference.

First reproduce the current behavior by creating a durable agent and observing snapshot writes in storage (e.g., Postgres). Then implement the change with minimal code: add the option, pass it through, and ensure the default mirrors the existing `running` persistence. Write a unit test that verifies snapshot persistence is skipped for `running` when the flag is false, while still persisting for `pending`, `paused`, `suspended`. Finally, run the existing test suite to ensure no regression.