ag-ui-protocol / ag-ui-protocol/ag-ui
[Bug]: `onRunFailed` return type strips `stopPropagation`, unlike other lifecycle hooks
- Lingua principale
- Python
- Stelle
- 15.9k
- Fork
- 1.4k
- Merge medio
- 1g 17h
- PR unite (30g)
- 163
Descrizione
### Pre-flight Checklist
- [x] I have searched [existing issues](https://github.com/ag-ui-protocol/ag-ui/issues) and this hasn't been reported yet.
- [x] I am using the **latest** version AG-UI.
### Describe the Bug
`AgentSubscriber.onRunFailed` (and `onRunInitialized`, `onRunFinalized`) return `Omit | void`, so `stopPropagation` can't be returned from these hooks — only from event hooks like `onEvent`, `onRunStartedEvent`, etc., which return the full `AgentStateMutation`.
```ts
onRunFailed?(params: { error: Error; } & AgentSubscriberParams): MaybePromise | void>;
```
This is a problem for `onRunFailed` specifically: when a run fails due to an intentional abort (e.g. user navigates away, or a new message supersedes the in-flight one), the subscriber needs a way to tell the agent to stop propagating that failure (e.g. to a global error boundary or toast) same as it can for a mid-stream `onRunErrorEvent`. Right now there's no supported way to do that from `onRunFailed`.
**Suggested fix**: widen `onRunFailed`'s return type to `MaybePromise`, matching the event hooks. (Whether `onRunInitialized`/`onRunFinalized` should also change is a separate question; `stopPropagation` may not make sense before a run starts or after it's fully finalized.)
### Steps to Reproduce
1. Install `@ag-ui/client@0.0.57`.
2. In a TypeScript file, implement an `AgentSubscriber` with a typed `onRunFailed` that returns `stopPropagation`:
```ts
import { AgentSubscriber } from "@ag-ui/client";
const subscriber: AgentSubscriber = {
onRunFailed: (params) => {
if (params.error.name === "AbortError") {
return { stopPropagation: true };
}
return undefined;
},
};
```
3. Run `tsc --noEmit`.
**Type error:**
```
Object literal may only specify known properties, and `stopPropagation` does not exist in type `Omit`.
```
`onRunFailed`'s declared return type is `MaybePromise | void>` in both `dist/index.d.ts` and `dist/index.d.mts`. It explicitly excludes the one field (`stopPropagation`) needed for this use case. (`onRunInitialized` and `onRunFinalized` have the same `Omit` restriction, but only `onRunFailed` is affected in practice since only a failed run needs to suppress default handling.)
### Expected Behavior
Compiles cleanly.
`onRunFailed` is the intended way to suppress the SDK's default error handling for a specific failure (e.g. an aborted run), same as `onEvent`/`onRunErrorEvent`/etc. can via their `AgentStateMutation` return type.
### Environment
```text
@ag-ui/client@0.0.57
```
### Screenshots
_No response_
### Logs & Errors
```shell
```
### Additional Context
Confirmed at runtime this isn't a design constraint — `agent.ts`'s `onError` handler already does `const mutation = onRunFailedMutation as AgentStateMutation;` and honors `mutation.stopPropagation === true`, so the implementation fully supports it; only the type signature blocks it.
**Current workaround**: we patch `dist/index.d.ts` locally to widen just `onRunFailed`'s return type so we can return `{ stopPropagation: true }` when an aborted run surfaces as a failure.
Guida per i contributori
Apri la guida per i contributori
Valutazione
Questa issue non è ancora stata valutata.