BonitoAgentsBonitoAgents

API​#

The user-facing surface is intentionally small: run a server, run the all-in-one dev rig, and wait on either.

BonitoAgents.serveFunction
julia
serve(; host, port, public_url, auth, state_dir, working_dir) → Bonito.Server

Start the BonitoAgents dashboard server, in one of three ways (identity.jl): for this machine (LocalAuth, the default: localhost only, whoever reaches it is the one account, and so is every worker); for a trusted network (NetworkAuth: any host, still no login, workers join with a credential from "Add worker"); or behind the login proxy the installer sets up (ProxyAuth(...), from <state_dir>/proxy.json: localhost only, Caddy + Authelia authenticate every request and say who it is from).

Routes: / — dashboard (workers + projects) /p/<projectid> — chat UI for one project /install — OS-sniffing bootstrap (curl … | sh / irm … | iex) /install.sh — bash wrapper (Linux / macOS) /install.ps1 — PowerShell wrapper (Windows) /install.jl — cross-platform worker installer (used by the wrappers) /w (WS) — the ONE connection each worker holds open: a WorkerLink carrying its control channel, its agents' ACP sessions and its file transfers (see workerclient.jl)

public_url is the base URL workers see (and what the install script tells them to dial back); behind the proxy it defaults to https://<domain>. manage_harnesses sends workers the agent adapters to keep installed (harness_spec). Off by default, so a test or dev server never has its workers download Node and npm packages; the server processes (start_server, the desktop app) turn it on.

state_dir overrides where workers.json / projects.json are persisted (default: ~/.local/share/bonitoagents-server). apps the apps the server runs, by type ((BonitoTodo.TodoApp, MyApp); see apps.jl). Passing this is explicit; by default the built-ins plus installed opt-in plugins are used ([bonitoagents] plugin = true). working_dir overrides where canonical project copies live on the server. Each project lives at <working_dir>/<name> and is mirrored onto the worker at <worker.projects_root>/<name>. (default: ~/bonitoagents-server)

source
BonitoAgents.dev_serverFunction
julia
dev_server(; port=nothing, name="dev", auto_open=false) -> DevHandle

Boot a self-contained BonitoAgents server + a local worker in this process. All state lives in mktempdir()-allocated directories and is removed when you call close(handle) (or when the Julia process exits — an atexit hook is registered).

The worker is a separate BonitoWorker.start() process: it dials the server's /w over loopback. No systemd, no install script.

proxy = DevProxy(...) puts the real login proxy in front, as an install has it: Caddy (with its own certificate authority) and Authelia, rendered from the same code, the worker coming in through Caddy with its credential, and handle.url Caddy's https://<domain>:<port>. The e2e items for the login use it.

network = true runs it the way a trusted network's server runs (NetworkAuth: no login, and the worker comes in with a credential "Add worker" issued, which the server checks itself), still on localhost.

manage_harnesses = true has the server declare the agent adapters, which the worker then installs (off by default, so a dev server's worker downloads no Node).

apps are the apps the server runs, by type, as for serve. Omit it to use the built-ins plus opt-in packages installed in the active environment; pass it explicitly for an isolated development rig.

If claude-agent-acp isn't on PATH the dashboard still works (worker registration, sidebar, project import, file pickers); only opening a chat session against the worker will fail at the agent spawn step.

julia
h = BonitoAgents.dev_server(; port = 8138, auto_open = true)
# Click around in the browser...
close(h)

Or as a do-block (recommended, cleans up on exception / Ctrl+C):

julia
BonitoAgents.dev_server() do h
    BonitoAgents.wait!(h)   # blocks until Ctrl+C
end
source
BonitoAgents.wait!Function
julia
wait!(handle)

Block until Ctrl+C, then return so the caller's cleanup runs. Useful from scripts and bin wrappers that start a dev_server and should stay up until interrupted; from the REPL just keep the handle and run other code in parallel instead.

source

Everything else​#

BonitoAgents.AppUIStylesConstant
julia
AppUIStyles

The server's theme and shared control styles, for plugin-specific layouts using the public BonitoWidgets --bw-* theme variables. Components below include it automatically. Host theme overrides apply to plugin controls as well.

source
BonitoAgents.BUILTIN_APPSConstant

The apps a server runs unless told otherwise (serve(; apps)).

source
BonitoAgents.AppCallType
julia
AppCall

One call of an app tool: the server (call.server), the chat whose agent called it (call.caller, a ProjectInfo) and the arguments (call.args, a NamedTuple by the tool's parameters).

source
BonitoAgents.AppChatType

Only the app's own chat gets the tool.

source
BonitoAgents.AppContextType
julia
AppContext

What the server hands an app it starts, as MyApp(ctx): the server (ctx.server, for the platform functions like start_chat!) and the directory the app keeps its files in (ctx.dir, <state_dir>/apps/<app_id>, created on first write).

source
BonitoAgents.AppErrorType
julia
AppError(msg)

A request an app cannot do as asked: no such item, a folder that isn't there. An agent gets msg as its tool's error; the server log does not, since nothing went wrong on this side.

source
BonitoAgents.AppKeyedChatsType

The chats the app started with a key (see start_chat!) get the tool; in_scope checks the key with prefix.

source
BonitoAgents.AppToolType
julia
AppTool(name, description, params = (;); scope = EveryChat())

A tool an app adds to the agents' MCP: params is a NamedTuple of Params, scope a ToolScope. The name must be unique across the server's apps and BonitoMCP's own tools; prefixing it with the app's id keeps it so. A call runs call_tool(app, Val(name), call).

julia
AppTool(:notes_add, "Add a note.", (text = Param(String, "The note."),))
source
BonitoAgents.ChatComposerType

The composer: the message input with its attachments, send modes, queue, Stop and Send.

source
BonitoAgents.ChatFolderType
julia
ChatFolder

A folder chats run in: the worker (worker, a WorkerInfo, or nothing for one that was removed; worker_id either way), the folder on it (path), its chats with the most recently active first (chats, ProjectInfos) and when the last of them was active (last_active, unix time, 0 for never).

source
BonitoAgents.ChatHeaderType

The chat's header: title, folder, session pills, menu and the lens bar.

source
BonitoAgents.ChatNoticeType

The provider's warnings and errors about the chat's session, hidden until there is one.

source
BonitoAgents.ChatToolbarType

The row below the composer, filled by the chat module.

source
BonitoAgents.ChatTranscriptType

The message list: the transcript with its rail, the busy, thinking and waiting lines under the last message, and the taskbar floating over it. Takes the space its parent gives it (a flex child that grows).

source
BonitoAgents.EveryChatType

Every chat's agent gets the tool.

source
BonitoAgents.MeshViewerType
julia
MeshViewer(url, path; mode = InlineView())

three.js viewer for the model at url (format from path), with its toolbar, status line, styles and driver, so it works in any session. PanelView() fills its container; InlineView() is a box of its own height.

source
BonitoAgents.ParamType
julia
Param(T, description)
Param(T, description, default)

A parameter of an AppTool: an argument of Julia type T (String, Int, Float64 or Bool), required unless it has a default. The tool's JSON schema is made from it, and the call's argument is checked and converted to T before call_tool sees it.

source
BonitoAgents.ServerStateMethod
julia
ServerState(; state_dir, working_dir, auth = LocalAuth(), manage_harnesses = false,
              apps = BUILTIN_APPS) → ServerState

Construct a fresh state, loading workers + projects from state_dir (workers.json, projects.json). working_dir is created if missing. apps are the types of the apps the server runs (apps.jl), started here.

source
BonitoAgents.ToolScopeType
julia
ToolScope

Which chats' agents get a tool: EveryChat or AppChat. An app can define its own, with a method of in_scope(scope, app, chat::ProjectInfo).

source
BonitoAgents.UserType

A person using the dashboard.

source
BonitoAgents.AppButtonMethod
julia
AppButton(content...; variant=:primary, size=:normal, class="", attributes...)

A server-styled button. variant is :primary, :secondary, :ghost or :danger; size is :normal or :small. Other attributes (including reactive disabled, onclick, and plugin data attributes) pass through to the button.

julia
AppButton("Save"; onclick = js"e => $(saved).notify(true)")
source
BonitoAgents.AppCardMethod
julia
AppCard(content...; class="", tag=:div, attributes...)

A themed surface using the server's shared border, radius and shadow. Padding and layout belong to the caller. tag may be :div, :section or :article.

source
BonitoAgents.AppModalMethod
julia
AppModal(content::Function, open::Observable{Bool}; title="")

The same BonitoWidgets modal used by the server. Its body is built afresh on each open and removed on close; Escape, the close button and backdrop dismiss it. Set open[] or notify it from a browser controller to open/close it.

julia
AppModal(is_open; title = "Add account") do
    DOM.div(account_form())
end
source
BonitoAgents.app_allowedMethod
julia
app_allowed(app, user) -> Bool

May user use app: see it on the dashboard, and have its tools in their chats? Admins only by default: an app's state is the server's, so a member's agent reading it would read everyone's.

source
BonitoAgents.app_briefingMethod
julia
app_briefing(app, key) -> String

The briefing of the app's chat with key (see start_chat!): by default app_briefing(app) for the app's own chat (key "") and nothing for the chats it started.

source
BonitoAgents.app_briefingMethod

Markdown appended to the system prompt of the app chat's agent.

source
BonitoAgents.app_chatMethod
julia
app_chat(server, app) -> ProjectInfo | nothing

The app's chat: the newest one marked with its id and no key ("Continue on" leaves the original behind), or nothing before it was first opened.

source
BonitoAgents.app_descriptionMethod

A few lines about the app: its tile's details on the dashboard, and the setup dialog.

source
BonitoAgents.app_iconMethod
julia
app_icon(app) -> String | nothing

The app's logo: the path of a square picture file that ships with the app (an SVG or a PNG, e.g. joinpath(@__DIR__, "logo.svg")), shown on its dashboard tile and as its chat's icon. nothing (the default) gives a tile with the first letter of its title.

source
BonitoAgents.app_idFunction
julia
app_id(::Type{<:AgentApp}) -> String

The app's name for the machine: a short lowercase word, unique on the server. It marks the app's chat (ProjectInfo.app), names its directory and should prefix its tools' names. The one method an app must define, on its TYPE: the server needs it before the app exists, to find its directory.

source
BonitoAgents.app_titleMethod

What the app is called in the UI. Defaults to its id.

source
BonitoAgents.app_toolsMethod

The tools the app adds to agents' MCP: a Vector of AppTool.

source
BonitoAgents.atomic_write_jsonMethod
julia
atomic_write_json(path, data; mode = nothing)

Write data (anything JSON can encode, structs by their field names) to path as indented JSON, all or nothing: a crash leaves the old file or the new one, never half of one. Makes the directory if it is missing.

source
BonitoAgents.call_toolFunction
julia
call_tool(app, Val(name), call::AppCall) -> String | Dict

Run the app's tool name for call, whose args are the tool's parameters, checked and converted. Return the text the agent reads, or a whole MCP CallToolResult dict. Throw AppError for a call that cannot be done as asked.

source
BonitoAgents.caller_userMethod
julia
caller_user(call) -> User

The person whose chat made call. Always known: a chat whose owner has no account gets no app tools at all.

source
BonitoAgents.chat_file_urlMethod
julia
chat_file_url(view, path) -> String

The URL a browser loads file path from, on the worker the chat view shows runs on: for a pane that shows files, e.g. as media_element(url, mime, is_video).

source
BonitoAgents.chat_foldersMethod
julia
chat_folders(server, user) -> Vector{ChatFolder}

The folders user's chats run in, the most recently active first. Apps' chats are left out: their folders are the apps', not the user's projects.

source
BonitoAgents.chat_keyMethod
julia
chat_key(view) -> String

The key of the app chat view shows ("" for the app's own chat), for a chat_pane that lays out several chats of one app (see start_chat!).

source
BonitoAgents.chat_paneMethod
julia
chat_pane(app, view) -> DOM node(s)

The open chat pane of one tab: what view (that tab's copy of the chat's model) shows, for a chat of app, or nothing for an ordinary chat. An app implements its own method to lay its chat out. What it returns, one node or a tuple of them, is placed in the chat's root: a flex column filling the pane, with data-app set to the app's id for its styles.

The pieces it can use are the ordinary chat's, as components: ChatHeader, ChatNotice, ChatTranscript, ChatComposer and ChatToolbar. Each can appear once per pane, nested as deep as the layout wants.

source
BonitoAgents.chat_titleMethod

The title of chat pid, or nothing for a chat that is gone.

source
BonitoAgents.find_workerMethod
julia
find_worker(server, user, name) -> WorkerInfo | nothing

A worker user may use, by its id or its name (any case).

source
BonitoAgents.load_json_tolerantMethod
julia
load_json_tolerant(path, label[, T]) -> value | nothing

Read the JSON file path (as a T, a struct JSON maps by its field names, when given), or nothing when there is none. A file that does not parse (a crash before writes were atomic, a hand edit gone wrong) is moved aside as <file>.bad-<time> with a warning naming label, and also gives nothing: better to start empty than to refuse to start the server. Its counterpart is atomic_write_json.

source
BonitoAgents.register_app!Method

Register an app type from an opt-in plugin package. Registering twice is harmless.

source
BonitoAgents.registered_appsMethod

The app types registered by packages loaded as BonitoAgents plugins.

source
BonitoAgents.relative_time_labelMethod
julia
relative_time_label(t) -> String

How long ago unix time t was, for a label: "just now", "5m ago", "3h ago", "2d ago".

source
BonitoAgents.send_message!Method
julia
send_message!(view, text; mode = :done)

Send text to the chat as the user's message, as the composer does: queued until the agent is done with its turn by default.

source
BonitoAgents.show_chat!Method
julia
show_chat!(view, pid)

Show chat pid in the window view (a tab's view of a chat, as chat_pane gets it) is open in.

source
BonitoAgents.start_chat!Method
julia
start_chat!(server, owner, worker, path; title = "", prompt = "", app = nothing, key = "") -> ProjectInfo

A new chat in folder path on worker, belonging to owner, brought up and sent prompt as its first message. Throws AppError for a worker that isn't connected and for a path that isn't a folder there.

With app, the chat is one of that app's, told apart from its others by key (not empty: "" is the app's own chat): its pane is the app's chat_pane and its agent gets the app's briefing for that key (app_briefing) and the tools in scope for it (AppKeyedChats). The pane reads the key with chat_key.

source
BonitoAgents.switch_provider!Method
julia
switch_provider!(model::ChatModel, new_provider::BinAgent) -> Union{Nothing,String}

Switch the agent backend for a chat. The switch is transactional: it starts a fresh session under new_provider and persists the choice only after that session is live. If startup fails, it restores the previous provider and its resumable session id; a previously live chat is brought back up on that provider. Returns the failed startup's concrete error text, or nothing on success.

source
On this page