efba9fab0a
scripts/gen-website-api.ts renders website/zh-CN/api/{cordis,harness}/* and the
api-sidebar.json fragment the VitePress config imports, so pages and navigation
can never drift from the code: signatures, @param/@returns prose, dispatch
modes, and GitHub source links are extracted, never transcribed, and the
generator hard-errors on any rendered member missing docs. verify-website-api
(doc-sync + run-gates) is the freshness gate.
Replaces the hand-written zh api pages (7 pages covering 7 of 15 services,
with phantom APIs: Context.current/Context.events, agent/post-step, tool/call,
compact/*, llm/pre-request none of which exist) with generated English
references: 5 cordis pages, 15 per-service pages, and a 35-event catalog
grouped by scope. The hand-written hub api/index.md stays and now indexes the
full surface; zh for these pages arrives with the unified translation flow.
5.3 KiB
Events
The event system mixed into every context. Harness-defined events are cataloged on Harness events.
ctx.parallel(name, ...args)
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.
ctx.emit(name, ...args)
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.
ctx.serial(name, ...args)
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.
ctx.bail(name, ...args)
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.
ctx.waterfall(name, ...args)
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 innermostnext.
Returns the outermost listener's return value.
ctx.on(name, listener, options?)
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 forprepend.
Returns a disposer removing the listener; true if it was still registered.
ctx.once(name, listener, options?)
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 forprepend.
Returns a disposer removing the listener; true if it was still registered.
EventOptions
Options accepted by ctx.on() and ctx.once().
interface EventOptions {
/** Add the listener before existing listeners for the same event. */
prepend?: boolean
/** Receive the event regardless of context filter checks. */
global?: boolean
}
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.
type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'