agent¶

Functions¶

agent.add_skill_dirs(dirs) — Register additional skill roots: directories whose immediate subdirectories each hold a SKILL.md. Calls accumulate, and these take precedence over skills found under the prompts directory.
agent.add_skill_files(paths) — Register individual SKILL.md files to load as skills. Calls accumulate, and these take precedence over discovered skill roots.
agent.append_system_prompt(text) — Set text appended after the base system prompt. The last call wins; takes precedence over ~/.config/wallah/APPEND_SYSTEM.md but not --append-system/--append-system-file.
agent.configure_compaction(settings) — Set the context-compaction policy. The last call wins.
agent.configure_display(settings) — Set the transcript display policy: how settled blocks commit to scrollback. The last call wins.
agent.configure_kagi(settings) — Set the kagi_search policy (API key, size cap, timeout). The key may come from the environment, e.g. api_key = os.getenv('KAGI_API_KEY'). The last call wins.
agent.configure_keys(settings) — Set the TUI key bindings. Each field names an action and the press (or list of presses) that triggers it; an omitted action keeps its default and an empty list unbinds it. The last call wins.
agent.configure_startup_banner(settings) — Set the startup-banner policy. The last call wins.
agent.configure_theme(settings) — Set the theme policy (appearance, per-appearance syntect theme). The last call wins.
agent.configure_webfetch(settings) — Set the webfetch policy (SSRF allowances, size cap, timeout). The last call wins.
agent.default_watchdog() -> {max_consecutive_errors: number?, max_rounds_without_success: number?, refractory_rounds: number?, refractory_seconds: number?, repeat_sentence_window: number?, repeat_sentence_threshold: number?, repeat_sentence_threshold_loose: number?, min_sentence_chars: number?, min_armed_sentences: number?, repeat_call_window: number?, repeat_call_threshold: number?, repeat_call_max_len: number?, max_think_nudges: number?, interrupt_on_cap: boolean?, nudge_text: string?, break_loop_text: string?}? — Returns the watchdog policy set by agent.set_default_watchdog, or nil when none was set. A personality can adopt it explicitly by writing watchdog = agent.default_watchdog(); when unset that reads as nil, leaving the personality's watchdog off.
agent.on(name, handler) — Register a handler for a host event (e.g. discover_providers).
agent.set_default_watchdog(spec) — Set the harness watchdog policy for the built-in default personality, the personality active when there isn't any config personality selected. The last call wins. It governs only the default.
agent.set_max_agent_spawn_recursion(depth) — Set how deep sub-agent spawning may recurse: a spawned agent at this depth may not itself spawn. The last call wins; a negative value clamps to zero, forbidding spawning entirely.
agent.set_prompts_dir(dir) — Set the directory searched for per-project AGENTS.md prompt files. The last call wins; takes precedence over ~/.config/wallah/prompts.
agent.set_system_prompt(system) — Override the base system prompt. The last call wins; takes precedence over ~/.config/wallah/SYSTEM.md but not --system/--system-file.
agent.show_confirmation(prompt, options) -> string — Ask the user to choose one of options (e.g. from a tool_call handler, to gate a sensitive call on approval), pausing this Lua call until they answer. Shows an overlay in the TUI; fails with an error when no interactive TUI is running to show it, or options is empty.