pub type BeforeAgentStartFn = extern "C" fn(event_json: StbStringRef, out: *mut StbString, user_data: *mut c_void) -> i32;Expand description
before_agent_start handler signature. Unlike EventHandlerFn
(fire-and-forget, i32 only), this carries an owning out so the plugin can
hand back a system prompt to install for the run — pi’s
BeforeAgentStartEventResult (extensions/types.ts:1394), whose
systemPrompt becomes forceSystemPrompt (runner.ts:1347).
event_json is a borrowed envelope with the same fields the
EventTag::BeforeAgentStart broadcast carries (prompt, imageCount,
sessionId, host) plus the live systemPrompt the run would otherwise
use. out is plugin-produced JSON {"systemPrompt": "..."} (or an empty
object for “no change”), reclaimed via the plugin_free_string the host
stored at registration.
Returns 0 on success (host reads out); nonzero on a handled error (host
logs the plugin’s message and leaves the prompt untouched, then continues the
fan-out — mirrors pi, which isolates a throwing handler).
Replacement, not append: the returned text becomes the system prompt. A
plugin that wants to append reads event_json.systemPrompt and returns the
two concatenated, which is what pi requires of its extensions too.
SAFETY: the plugin warrants user_data is valid for the registry’s lifetime
and the handler is callable from any thread.