deepseek-harness/website/zh-CN/api/cordis/events.md

<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->

# Events

The event system mixed into every context. Harness-defined events are cataloged on [Harness events](../harness/events.md).

### ctx.parallel(name, ...args)

```ts website-api
parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>
```

Dispatch an event, running all listeners concurrently.

- `name` — the event name.
- `args` — arguments passed to every listener.

**Returns** a promise resolving once every listener has settled.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L43)

### ctx.emit(name, ...args)

```ts website-api
emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): void
```

Dispatch an event synchronously, ignoring listener return values.

- `name` — the event name.
- `args` — arguments passed to every listener.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L52)

### ctx.serial(name, ...args)

```ts website-api
serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
```

Dispatch an event, awaiting listeners in order until one bails.

- `name` — the event name.
- `args` — arguments passed to each listener.

**Returns** the first bail value (non-null, non-false, non-undefined), if any.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L62)

### ctx.bail(name, ...args)

```ts website-api
bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
```

Dispatch an event, calling listeners in order until one bails.

- `name` — the event name.
- `args` — arguments passed to each listener.

**Returns** the first bail value (non-null, non-false, non-undefined), if any.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L72)

### ctx.waterfall(name, ...args)

```ts website-api
waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
```

Dispatch an event whose last argument is a `next` continuation.
Each listener wraps the rest of the chain: calling `next()` invokes the next listener (finally the built-in behavior); not calling it vetoes.

- `name` — the event name.
- `args` — listener arguments; the final one is the innermost `next`.

**Returns** the outermost listener's return value.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L85)

### ctx.on(name, listener, options?)

```ts website-api
on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
```

Register an event listener owned by the current fiber.

- `name` — the event name to listen for.
- `listener` — called with the dispatch arguments.
- `options` — listener options; a boolean is shorthand for `prepend`.

**Returns** a disposer removing the listener; `true` if it was still registered.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L96)

### ctx.once(name, listener, options?)

```ts website-api
once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
```

Same as `on()`, but the listener disposes itself after its first call.

- `name` — the event name to listen for.
- `listener` — called at most once with the dispatch arguments.
- `options` — listener options; a boolean is shorthand for `prepend`.

**Returns** a disposer removing the listener; `true` if it was still registered.

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L105)

## EventOptions

Options accepted by `ctx.on()` and `ctx.once()`.

```ts website-api
interface EventOptions {
  /** Add the listener before existing listeners for the same event. */
  prepend?: boolean
  /** Receive the event regardless of context filter checks. */
  global?: boolean
}
```

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L111)

## DispatchMode

Event dispatch strategy used by the event service.
`emit` runs synchronous listeners without awaiting them, `parallel` awaits all listeners together, `serial` awaits them in order until one bails, `bail` stops on the first synchronous bail value, and `waterfall` composes listeners around a final `next` callback.

```ts website-api
type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
```

[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/vendor/cordis/src/events.ts#L31)