---
title: "Change log"
description: "This page lists user-visible changes to the Dex Agents packages, newest first;"
canonical_url: "https://docs.superdurable.io/zh-Hans/reference/agents/changelog/"
source: "docs/reference/agents/changelog.mdx"
locale: "zh-Hans"
---

# Change log

This page lists user-visible changes to the Dex Agents packages, newest first;
each section covers the changes since the previous release of this component.
All agents packages share one version line. The
[agents CHANGELOG](https://github.com/superdurable/dex/blob/main/agents/CHANGELOG.md)
in the repository has the full details of each release, including API names
and upgrade steps.

<a id="v0-5"></a>

## 0.5

Not released yet. The next release, agents/v0.5.0, ships these changes.

### Breaking

- Every package requires Dex SDK 1.45.0, so an application can use the SDK's **Join** helper with the agents packages, and for Worker-side Flow definition upload. The SDK version stays an exact pin. Before upgrading, read the breaking changes of SDK 1.43 and 1.45 in the [Python](https://docs.superdurable.io/zh-Hans/reference/python/changelog.md#v1-45), [TypeScript](https://docs.superdurable.io/zh-Hans/reference/typescript/changelog.md#v1-45), and [Go](https://docs.superdurable.io/zh-Hans/reference/go/changelog.md#v1-45) SDK change logs: since SDK 1.45, a Step type with "-" can no longer start SubFlows. The agents packages start none. Dex Server still needs protocol 4: server-zd 0.1.17 or later.
- Python and TypeScript cores: a Connector tool's default name now uses the Connector library's snake case, which also names the Python Step factories. An acronym stays one word: **listStoryIDs** becomes **list_story_ids**, not **list_story_i_d_s**, and **getHTTPResponse** becomes **get_http_response**. Only ASCII capitals start a word. A call stored under the old name finds no tool after the upgrade and ends as a removed tool's call does. To keep the old name, pass it as the tool's **name**. A recorded call then resumes under it. See [Name the tools](https://docs.superdurable.io/zh-Hans/reference/agents/connector-tools.md#connector-tools-offered).
- Python and TypeScript cores: a Mutation's **defect** now records **outcome_unknown** instead of **failed**, whatever **agent.branches** says, and is not retried. A Query's **defect** follows **agent.branches**: listed as **rejected** it is a rejection, otherwise it records **failed**. These rules, and the rule for **uncertain**, now apply before the required branches, so a **defect** or **uncertain** branch declared required no longer records **succeeded**. See [Outcomes](https://docs.superdurable.io/zh-Hans/agent-frameworks.md#connector-tools-outcomes).
- Python and TypeScript cores: a Mutation that uses the single-dispatch fence records **outcome_unknown** on every branch except the success branch when its fence checkpoints cannot prove that no request reached the provider. A single-attempt write records "not sent; the provider asked to retry later" only when a **notSent** or **canResend** marker shows that nothing was sent. **classify_connector_branch** (**classifyConnectorBranch**) takes a new optional **may_have_dispatched** (**mayHaveDispatched**).

### Added

- **McpToolSource** follows the Dex MCP conventions. A tool definition's **\_meta** key **io.superdurable.dex/effect** fixes the tool's effect class, and **io.superdurable.dex/approval: recommended** asks for approval, as a Connector manifest does. A session tool policy may raise such a tool's effect class or approval, but never lowers its effect class. Its writes run in the model's order. Servers without these keys behave as before.
- **McpToolSource.merge_tool_policies** (**mergeToolPolicies**) merges the application's tool policies by the same rule for a framework adapter.
- A tool result's **\_meta** key **io.superdurable.dex/outcome** set to **unknown** records **outcome_unknown**, and **rejected** records **failed**. Either wins over **isError**.
- The new npm package **@superdurable/dex-agents-pi** runs Pi agents on the built-in agent loop. Dex runs the agent loop, pi-ai makes each model call, and Pi tools run as Dex tool Steps.
- The Dex Agents CLI commands are published for the first time: **dex-agents-cli-core** and six commands on PyPI, and **@superdurable/dex-agents-cli-core** and six commands on npm. Each command runs one agent harness in the terminal, such as **dex-agents-claude-sdk** or **dex-agents-builtin**, with the connectors MCP server's tools and local file, shell, web fetch, and browser tools as Dex tool Steps.
- Python and TypeScript cores: user messages and tool results can carry images. Session state stores only an **AgentImageReference**; the bytes live in a **MediaStore**, such as **S3MediaStore** or **LocalDirectoryMediaStore**. The framework adapters, the built-in agent loop, and **McpToolSource** take an optional media store and show images to the model only when they have one. Send images only after every Worker of the Flow type runs 0.5.0. The Go core has no image input.

### Changed

- A tool task poll may raise **ToolOutcomeUnknownError**. The session records **outcome_unknown** and stops polling. It used to fail the poll attempt.
- The built-in agent loop has new names. The old names still work for one release, refer to the same objects, and are deprecated. Stored sessions, Flow types, and wire values are unchanged. Migrate as follows:
  - Python: module **dex_agents.stepwise** becomes **dex_agents.builtin_loop**. **StepwiseAgentRunner** becomes **BuiltinLoopAgentRunner**, **stepwise_agent_session_flow** becomes **builtin_agent_session_flow**, **stepwise_agent_session_options** becomes **builtin_agent_session_options**, and **encode_stepwise_message** and **decode_stepwise_message** become **encode_builtin_loop_message** and **decode_builtin_loop_message**. Each name read from the old module emits a **DeprecationWarning**.
  - TypeScript: subpath **@superdurable/dex-agents/stepwise** becomes **@superdurable/dex-agents/builtin-loop**. **StepwiseAgentRunner** becomes **BuiltinLoopAgentRunner**, and **createStepwiseAgentSessionFlow** becomes **createBuiltinAgentSessionFlow**.
  - Go: package **stepwise** becomes **builtinloop**. **StepwiseAgentRunner** becomes **BuiltinLoopAgentRunner**, **NewStepwiseAgentRunner** becomes **NewBuiltinLoopAgentRunner**, **NewStepwiseAgentSessionFlow** becomes **NewBuiltinAgentSessionFlow**, and **EncodeStepwiseMessage** and **DecodeStepwiseMessage** become **EncodeBuiltinLoopMessage** and **DecodeBuiltinLoopMessage**.
- Error texts of the built-in agent loop no longer say "Stepwise": a session message the loop cannot read is now a "built-in agent loop item" in the Python and Go cores and a "built-in loop item" in the TypeScript core. In the Go and TypeScript cores, the error for a framework run state the loop cannot read says "built-in loop". The Go core's panic messages for a nil model client or definition start with **builtinloop:** instead of **stepwise:**. Python loggers now sit under **dex_agents.builtin_loop**.

### Fixed

- Python and TypeScript Claude Agent SDK adapters: when the Claude Code CLI returns an error result, the turn's error now reads "the Claude Code CLI returned an error result (subtype ...)". It used to read "reported success" for an error result whose subtype is **success**, such as a failed login.

<a id="v0-4"></a>

## 0.4

Released 2026-11-10 as [agents/v0.4.0](https://github.com/superdurable/dex/releases/tag/agents%2Fv0.4.0).

### Added

- **ConnectorToolSource** in the Python and TypeScript cores offers reviewed Connector operations to an agent as tools. The application names each operation with **connector_tool** (**connectorTool**). Nothing is exposed by default, and an operation whose manifest lacks **agent.exposed** is refused when the agent is defined. Needs Connector SDK 0.9.0. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/connector-tools.md).
- Connector tool calls take their effect class and approval default from the Connector manifest, map the selected branch to **succeeded**, **failed**, or **outcome_unknown**, and cut results at 64 KiB by default. Connector writes of one model response run one at a time, in the model's order; once one does not succeed, the later ones record **failed** with **skipped** set. See [Connectors as tools](https://docs.superdurable.io/zh-Hans/agent-frameworks.md#connectors-as-tools).
- Every Python and TypeScript framework adapter takes tool sources, through **tool_sources** (**toolSources**), with a listing timeout of 10 seconds by default. Each call of a source tool runs once in its own tool Step.
- Tool call contract: **ToolOutcomeUnknownError**, **DeferredToolExecution.context**, **ToolCallStepOptions**, and the **AgentToolCall** fields **ordered_write**, **write_queued**, **skipped**, and **truncated_output_bytes**. Records written by 0.2 decode unchanged.

### Changed

- Claude Agent SDK adapters: an approved Claude Code tool resumes with its recorded arguments, the input that the hooks produced and the approval saw. A recorded call replays only as its own tool, at most once per segment. The application's PreToolUse hooks are not called for a resumed call that already has a final record.
- TypeScript Mastra: the new **mastraRunToolNames** names the tools Mastra adds itself. With **toolSources** or **mastraRunToolNames**, a **toolPolicies** key no longer allows such a tool by itself.
- TypeScript Vercel AI SDK: the **toolPolicies** type accepts any string key, so a source tool can have a policy.
- Python LangGraph: a model tool call without a tool call ID fails the **RunModel** attempt.

<a id="v0-3"></a>

## 0.3

Released 2026-11-09 as [agents/v0.3.0](https://github.com/superdurable/dex/releases/tag/agents%2Fv0.3.0).

### Added

- **render_session_flow_graph** (**renderSessionFlowGraph**) and the **dex-agents-session-graph** command render the session Flow graph for Dex Web, with Actions for **resolve_interrupt**, **answer_question**, **steer_user_message**, and **cancel_turn**. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/dex-web.md).
- Compaction in the OpenAI Agents SDK, Pydantic AI, LangChain and LangGraph, Google ADK, Vercel AI SDK, and Mastra adapters. Adapters compact only between turns. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/session-limits.md#compaction).
- **ModelSpendLimit** checks each model call before it runs and reports its usage after. A refused call ends the turn. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/spend-limits.md).
- **run_model_limit** (**runModelLimit**) sets the method timeout and attempts of **RunModel**. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/workers.md#long-model-calls).
- **AgentSessionClient.start_session** and **startAgentSession** make a new session searchable by the Step it waits in. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/approvals.md#find-sessions).

### Changed

- Every package requires Dex SDK 1.38.0.
- A session over the server's state limit fails with the reason: its status becomes **failed**, and new messages raise **AgentSessionFailedError**. Upgrade every reader of a session before the Workers that write **failed**. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/session-limits.md#at-the-limit).

<a id="v0-2"></a>

## 0.2

Released 2026-11-05 as [agents/v0.2.0](https://github.com/superdurable/dex/releases/tag/agents%2Fv0.2.0).

### Breaking

- Stop every 0.1 Worker of a Flow type before any 0.2 Worker starts. 0.2 moves older messages into **AgentMessageChunks**, which a 0.1 Worker cannot read. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/upgrades.md).

### Added

- The built-in agent loop, with questions, durable waits, plans and plan mode, MCP tool sources, and a scripted demo model.
- Steering and turn cancellation: **steer_user_message** and **cancel_turn**.
- Tool tasks: a tool can start long work and the session polls it in **PollToolTask**.
- Context compaction with the **CompactContext** Step, and message retention through **retained_message_limit**. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/session-limits.md#compaction).
- Messages are stored in chunks (**AgentMessageChunks**), so storing a message writes only that message.
- UI stream adapters for the AI SDK **useChat** and plain Server-Sent Events, which resume through the Dex resume token.
- OpenTelemetry GenAI spans for model calls and tool calls.
- The Go core, with the built-in agent loop and OpenAI and Anthropic model clients.
- A call whose tool Step never reached a Worker records **failed**, with an error that starts "the tool did not run, so it is safe to call again". [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/failures.md#never-run-outcome-unknown).

### Changed

- Every package requires Dex SDK 1.35.0.
- **resolve_interrupt** and **answer_question** can raise **RpcLockConflictError**. **AgentSessionClient** retries it for 5 seconds. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/approvals.md#rpc-locks).

<a id="v0-1"></a>

## 0.1

Released 2026-11-01 as [agents/v0.1.0](https://github.com/superdurable/dex/releases/tag/agents%2Fv0.1.0).

### Added

- First release. Python packages **dex-agents**, **dex-agents-openai-agents**, **dex-agents-pydantic-ai**, **dex-agents-langgraph**, **dex-agents-google-adk**, and **dex-agents-claude-agent-sdk**. TypeScript packages **@superdurable/dex-agents**, **@superdurable/dex-agents-vercel-ai**, **@superdurable/dex-agents-openai-agents**, **@superdurable/dex-agents-mastra**, and **@superdurable/dex-agents-claude-agent-sdk**. Each model call is one Dex Step and each tool call is its own Step. [Reference](https://docs.superdurable.io/zh-Hans/reference/agents/install.md).