dotbotRun Module

A DotBot run driven from a boot rather than from the DotBot panel.

Purpose

start_instance { world, prompt } (the engine's --agent dotbot --agent-prompt <text>) hands the prompt to DotBot, the agent the engine ships in its DotBot panel, as the first message of a fresh conversation. resume (--agent-resume) sends a message into the conversation this world's run already holds. The editor starts the run as it comes up; a browser engine is handed it by the proxy once the engine answers.

DotBot is a plugin inside the engine, so a run is the plugin's own surface used in order:

1. wait for the plugin to load, and on a boot whose host hands DotBot its own Claude accounts (--agent-accounts-seeded, the seeded option; the development proxy does for every engine it starts), wait for them to reach DotBot;
2. find the DotBot agent the boot named (dotbot is DotBot on its first Claude account, dotbot-chatgpt on its first ChatGPT account) and check an account is connected to it. A boot that names an account (--agent-account, the account option) runs on the agent of that provider holding it (dotbot-claude~2 for the second connected Claude account). An account is named by its agent, its account key (anthropic-claude~2), the name it carries in the DotBot panel, or its email; an account the host provides is held as dotbot-claude~<id> and is named by the host's id for it too (the id claude_usage reports). A resume continues the recorded conversation on the account it names, else on the agent the conversation last ran on;
3. open a new conversation (/new), set the model and thinking level the boot asked for. DotBot keeps what it is set to as the model and thinking level it runs that account on from then on, its panel included, and a boot that names no model runs the one it already holds;
4. send the prompt.

The prompt the page hands over

In a browser, the page hosting the engine can hand the editor's agent its first prompt: origozero.ai's /create posts the idea a person typed as { type: "agent_prompt", prompt, world } on the engine's worker channel (docs/engine-launch-spec.md). The editor serves it (watchHanded, started with the editor) as a run of its own: once the plugin has loaded and an account is connected to it, it goes to the agent the person's own first message in the DotBot panel would (their default account when it is usable, else the first DotBot agent with an account connected whose sign-in has not run out, on a browser engine the agent included with OrigoZero) as the first message of a new conversation of the world, and the page is told sent, or refused with the reason. A prompt for a world other than the one the engine is bound to is refused. The browser keeps that the world's prompt was sent, so a reload or a second tab sends it no second time.

What a run records

• The conversation, in this machine's agent-session store under (world guid, dock slot 1), with harness naming the DotBot agent, once the first event of the prompt's turn names it. A resume reads it and records it again, as this engine's run of the slot, with harness naming the agent the conversation now runs on.
• The account the run spends, on its prompt and launch entries (account: who it is and the key DotBot holds it under), which agent_run_report names.
• Every prompt and every turn event of that conversation (streamed text fragments aside: a turn's done carries the whole answer), one JSON line each, through agentSessions.record, at <config dir>/agent-transcripts/<agent>_<conversation>.jsonl, named after the address the conversation was opened under, so a resumed run, on any account, adds to the same transcript. agent_run_report reads it: turns, tokens, tool calls with their timings, failures, the skills opened and the guides read.
• Its state: the last entry recorded is the in-engine agent's state in GET /engine/status (agent.run), which instance_health prints.

When a run cannot start

It is refused, sends nothing, and records the reason as its state:

• the engine is bound to no world (DotBot acts through the live agent endpoint a world-bound engine publishes);
• the plugin did not load, or had not after five minutes;
• the host's Claude accounts did not reach DotBot, or had not after five minutes;
• no account is connected to the DotBot agent named. An account is connected once on a machine, in the DotBot panel, and every later run uses it. A run asPanel waits up to five minutes for one to connect;
• the account the boot named is not one DotBot holds connected, or names more than one (the refusal lists the accounts connected to the agent, and says why a host account whose sign-in lapsed is not connected);
• DotBot refused the model or the thinking level the boot named;
• a resume found no DotBot conversation recorded for the world and slot.

Functions

• dotbotRun.start(opts): start a run in the background. opts is { agent, worldGuid, slot?, prompt?, resume?, model?, effort?, account?, seeded?, asPanel? }; asPanel runs on the agent a person's panel message would, in place of agent and account. One run per engine.
• dotbotRun.watchHanded(): serve the prompts the page hosting this engine hands over, once per engine.
• dotbotRun.serveHanded(deps): serve one waiting prompt over the caller's deps, for tests.
• dotbotRun.panelAgent(agents): the agent a person's panel message starts a conversation on, from DotBot's agents answer.
• dotbotRun.startArmed(): start the run this boot's settings arm, if any.
• dotbotRun.agentFor(name): the DotBot agent id an agent name runs.
• dotbotRun.new(deps): a run over a transport of the caller's, for tests.