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

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

Aperta
#2,124 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub
bug
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.

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.