ag-ui-protocol / ag-ui-protocol/ag-ui

[Bug]: `onRunFailed` return type strips `stopPropagation`, unlike other lifecycle hooks

Abierto
#2,124 0 comentarios 0 reacciones 0 asignados Ver en GitHub
bug
Lenguaje dominante
Python
Estrellas
15.9k
Forks
1.4k
Merge medio
1 d 17 h
PR fusionados (30 d)
163

Descripción

### 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.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.