Extensions
Mob is a small kernel with extensions registered at compile time. Plugins add tools, commands, HTTP routes, configuration and background runs beside their own code, and the engine does not name them. Code from outside Mob comes in only through MCP servers: Mob ships as one binary, and loading code at run time would keep it from being compiled ahead of time.
DeepSeek Harness tools use an optional Bun process with the official Cordis runtime, connected over that same MCP boundary.
Adding a plugin is a directory under apps/mob/src, a HostPlugin (apps/mob/src/local.ts)
registered in apps/mob/src/plugins.ts, and a Plugin (packages/core/src/app/server.ts)
returned by attach; configuration is one Section
(packages/core/src/app/configuration.ts).
- A
Tool(packages/core/src/chat/tools.ts) is a model tool definition, an optionalpromptadded to the system prompt when the tool is offered, andrun.rungets aToolCallwith the parsed input, the stored part, the message, the store and the event sender. Its output and errors go back to the model, exceptAwaitingApproval, which ends the turn after an approval request, and anAbortTool, which ends the turn as a failure. A tool error after cancellation ends the turn as cancelled. availablesays when a tool is offered (plugin tools: while their plugin is enabled).ownerOnlylimits it to the owner’s turns.exposuremakes it direct, deferred untiltool_searchloads it, or hidden, andnamespacegroups deferred tools wheretool_searchis described; see Exposure and tool_search.- To ask for approval,
runcallsrequestApprovalwith the input the user will approve, andapprovedcarries out the call once approved.scopedecides which later calls a remembered approval covers. See Tools and approvals. ConversationService.toolsis aToolRegistry. Names are unique, andsandbox,tool_searchandhistory_searchare reserved: turns add those tools themselves. A turn offered two tools with one name fails.registerSourceadds tools that change while Mob runs, andregisterEntriesadds whattool_searchfinds besides tools, such as skills.
ConversationService.hooks run around every turn, in registration order:
beforeTurnmay add to the request’s system prompt before history is fitted to the context window. Recalling saved facts is one.beforeToolmay refuse an offered call; its error is handled as the tool’s own would be.afterTurnsees the saved reply and the turn’s error.
Native plugins contribute these typed callbacks through their hooks field;
registration appends them after existing core hooks.
Hooks are registered once, before serving, and keep the engine’s error handling.
Like tools, hooks that depend on optional configuration must check whether their
plugin is enabled; a hook is not gated on its plugin’s background run or
connection status.
The engine’s run (packages/core/src/chat/engine.ts) takes an Agent: the
tools and hooks of one turn.
Commands and routes
Section titled “Commands and routes”- A plugin’s
commandsjoin the server’s command registry and are listed after the server’s own. ACommand(packages/core/src/chat/commands.ts) names the clients it is offered in (interactiveis the web UI and the TUI) and returns Markdown or an action for the UI;replyJSONshows a value as indented JSON. ACommandErrorsets the HTTP status of a refusal. - A
Routeis an HTTP endpoint at/api/plugins/<plugin>/<path>.handlereturns a value for the JSON response or throws: aCommandErroror anHTTPErrorsets the status, any other error is the plugin’s service failing (502).body(packages/core/src/app/http.ts) reads a bounded JSON object, refusing a malformed body or fields not in its optionalkeyslist with 400 and one over its size limit with 413. A path may name a parameter asmessages/:uid; a path a plugin serves only by another method answers 405. - The server’s own routes are one Hono app (
packages/core/src/app/api.ts). Its type,AppType, is what@mob/client’s typed client (MobClient.api, built with Hono’shc) calls: paths, request bodies and answers are checked against the routes, so clients declare no copies of them. Plugin routes join at run time and are called by path. - Commands about plugins in general (
/plugins,/test,/deliveries,/clear-secret) and the configuration routes stay in the server.
Background runs
Section titled “Background runs”- A plugin that runs while it is enabled, such as a channel polling its app,
sets
background: anExtension(packages/core/src/app/extension.ts) with a name and astartthat reads the plugin’s current configuration and returns aServefunction, orundefinedwhen the configuration leaves it off. Servegets anAbortSignaland astatuscallback. It runs until the signal aborts, reporting what it is doing (shown by/api/plugins), and releases its resources before it returns.Extensionsstarts every registered extension in registration order (startAll), restarts one after its configuration is saved (reload), reports each one’s status (Disabled,Connecting…, then whatever the run reports) and stops them all in reverse order (close). Operations run one at a time, so a reload never races another, and a restart waits for the old run to return before callingstartagain.- A run that throws is reported; one that returns on its own is shown as
Stoppeduntil it is reloaded. Status reports from an earlier run are dropped. Nothing restarts afterclose.
Configuration sections
Section titled “Configuration sections”- A
Section(packages/core/src/app/configuration.ts) describes one plugin’s part of the saved configuration: its name, a title for menus and a label for messages, its zodschema, itssecrets, whether it is enabled, how an enabled configuration is validated beyond its shape, and how it is tested. - The schema is the only shape a submission may have: unknown fields, wrong
types and fractional numbers are refused with 400, and missing values take
the schema’s defaults. A plugin never saved has the defaults of an empty
object. A saved configuration that no longer parses is shown as defaults
but kept as saved until that plugin itself is saved again; saving one plugin
never rewrites another’s. The bundled plugins’ schemas are in
packages/core/src/app/plugin-config.ts, where clients take their types. - A
Secretnames a credential at a dotted path, theflagthat tells clients whether one is saved, and its owner: a blank submission keeps the saved credential only while the owner (such as an IMAP host and username) is unchanged. Clients never receive a credential, only its flag; flags they send back are dropped. updatePlugin, the connection test,/testand/clear-secretlook the plugin up by section.GET /api/pluginsreturnssections, each with its schema as JSON Schema.- The web UI builds the Telegram, Cloudflare and email configuration forms
from schema metadata:
titlelabels a field,descriptionhints at it, andsecretwithflagmakes a password field with a clear button. WeChat iLink signs in by QR code, so its form is its own.