Move the turn engine into @openbot/toolkit, and split the largest server files

[guidovizoso]

What this changes

A refactor of the server toward packages: the code that runs a Bot's turn becomes its own workspace, @openbot/toolkit; shared/ becomes @openbot/shared; and the largest files are split. Three behaviour fixes to how turns hold their conversation's lock ride along, each in its own commit. They're described below and in the changelog.

Draft, because it's big (42 commits on main, 196 files) and is meant to be reviewed commit by commit, or split into the stacked PRs listed under Plan.

Benefits

The turn engine is safer to change

• The headless turn runner (routines, responsibilities, background research, wake-ups, group turns, approval resumes) now lives in toolkit/, outside the server.
  • A Biome rule stops it importing server code, Drizzle or Hono.
  • Code that needs CopilotKit lives in toolkit/src/copilotkit/, and a second rule keeps the toolkit core free of CopilotKit.
  • On main, loading run-turn.ts pulled in 49 server modules, including the database schema and all of copilot.ts.
• How a turn ended used to be a hand-ordered chain of throws. It's now one pure settle(evidence) → TurnOutcome (completed | failed | lockLost | timedOut | suspended | interrupted | empty), and conclude() is the only place an outcome becomes a reply or an error.
  • A new table test pins the order. Swapping two outcomes fails it; the existing suite didn't notice the swap.
• The pause and capability checks, the audit trail, the component gallery and the thread lock are passed in as ports (TurnAdmission, ComponentCatalog, ThreadLock) instead of read from module globals.

Behaviour fixes

• A network blip no longer stops a turn. The lock heartbeat (keepLease) stops a turn only when Intelligence answers 409 THREAD_LOCK_RENEWAL_FAILED, meaning the lock is now someone else's. A stopped turn is retried from the start, so a blip could make a Bot repeat a side effect.
• A Bot-to-Bot handoff now stops when it loses its lock, instead of writing into the other run, which on a relay is the person's own channel.
• A paused Bot's handoff never locks the person's conversation. Handoffs meet the same admission as every headless turn, before building the Bot, reading history or taking the lock.
• The headless lock asks for 120s, the lifetime Intelligence actually applies; the 20s it asked for never took effect.

No more 5,000-line files

	main	Here
plugins/store.ts	7962	49, plus plugin-store/ (model, shared context, five method groups)
plugins/composio-adapter.ts	4844	264, plus composio-vendor.ts and composio-client/
index.ts	3311	2505, plus seven wiring modules
plugins/routes.ts	2846	133, plus route-groups/ (six groups)
copilot.ts	2282	1867 (the agent classes moved to toolkit/src/copilotkit/agents.ts)

Each split was checked mechanically:

• the store keeps the same 42 methods in the same order
• the plugin router keeps the same 21 routes in the same registration order
• the Composio broker keeps the same 10 methods
• one file still imports @composio/core

index.ts is less fragile. It had 29 places that read a name declared further down. That worked only because the read happened later, at run time, and an extraction could turn any of them into a startup crash. They're down to 12. The ones left are real cycles (for example actorAgentResolver ↔ copilotRuntime), a hoisted function, or would mean moving 100–200 lines of startup for one reference.

Clearer contracts

• @openbot/shared has explicit exports. Nothing imports it through ../../../shared any more.
• Turn limits (TURN_LIMITS) and the shared OAuth and delivery timeouts are named. The routines sweep calculates its "abandoned run" cutoff from the turn timeout instead of keeping a hidden copy.
• The built-in Bot's OpenAI fallback model is named, with the reason it differs from the remote Bots' default.

More tests: 46 new: the uncovered waiting-on-interrupt branch, the handoff lock adapter, admission, the lease rule, settle, turnMessages / turnInput, and the provider-switch model fallbacks.

How to read it

The commits follow the phases, each ending where the next starts:

Phase	Commits	What
0	feb91d11 17481b1f	Tests before anything moves
1	fcbb9db0	shared/ → @openbot/shared
2	c33f0d3c … 684325dc	Cut the seams in place: lock adapter, history helpers, tool contracts, TurnAdmission
3	a9f5aee8 … 1b0329ba	Stage server/src/toolkit/, add the boundary rule
4	c90311ef	settle(), the lease, pure turnMessages / turnInput
5	654f3174	toolkit/ becomes the @openbot/toolkit workspace
6	9f378bf0 afb21822	Behaviour: the lease rule, handoff admission and lock loss
7	a1ceb39f … dc3d7523	Named limits, the 120s lock lifetime, the model fallback
8	722e2b09 … 876a2aee	Big-file splits, index.ts reordering, CopilotKit agents into the toolkit
	d6e9f0ba efd8ef8a	Merge of main, changelog

Most commits are mechanical moves. Where code moved, it moved verbatim: the store and the Composio client were split with the TypeScript compiler's syntax tree, which keeps each node's exact text and comments. The commits that change behaviour are 9f378bf0, afb21822 and dc3d7523.

Plan

Next, in this refactor

1. Split this into stacked PRs, roughly by phase, so each lands on its own: phases 0–2, 3–5, 6 alone (behaviour), 7, then 8 per file.
2. Finish the harness. The toolkit governs a turn but doesn't yet assemble it. Prompt and context assembly, model selection and tool-set assembly are still in copilot.ts. Moving them in behind the ports already sketched (PromptContext, ModelConfig, ToolProvider) would let the toolkit take "this Bot, this person, this message" and return a finished turn.
3. Keep shrinking the large files. index.ts (2505), plugin-store/connections.ts (2495), app.ts (2005), plugin-store/servers.ts (1907) and copilot.ts's agent building.

After that: Slack, Teams and any other platform, through the Channels SDK

Reading OpenTag and @copilotkit/channels 0.11.0 for this work turned up two things:

• The OpenTag side of the pairing isn't public. OpenBot's pairing expects an openbot.sender context entry and /openbot/deliver and /openbot/membership endpoints. No public CopilotKit repository implements them, OpenTag included; upstream OpenTag sends a free-text sender label and has neither route. The confirm_write approval card does match.

• The runtime OpenBot already runs can host Channels. @copilotkit/runtime 1.77.0 accepts channels on the same Intelligence runtime OpenBot mounts. OpenBot could therefore declare its own Channel:

  • identifyUser would be the existing binding lookup, plus same-domain email auto-linking.
  • agent would be the person's Bot.
  • Approvals would come through onInterrupt, and charts through channels-ui.

  That would remove the OpenTag relay, the shared secret and most of delivery/opentag*.ts. It would also bring the SDK's Discord, Telegram and WhatsApp adapters. The open gap is messages a Bot starts on its own: the SDK says "Proactive delivery to subscribed conversations is not yet wired".

  The next step is a spike: one Channel inside mountCopilotRuntime, and checking whether a linked person can chat, approve an action from a card and get a chart back, with no OpenTag in between.

Where it runs

• New state that outlives a request? None. Two in-process caches moved without changing scope: the plugin store's token-exchange chains and OAuth client locks are still one per store, and the Composio directory cache is still one per client.
• What happens on the second replica? The same as on main. Turns still serialise on Intelligence's thread lock. The only change is when a turn gives up: on a 409 renewal (the lock is now another replica's or the person's), not on a network error. A handoff that loses its lock fails into the existing work-queue retry.
• Anything serialised? Still the platform's thread lock (SET … NX). Nothing new.
• Anything fanned out to a browser? No. The Bun server and its websocket dispatch moved unchanged into http-server.ts.
• New listener, port, or schedule? None. The handoff queue listener and every sweep are started by the same code, now in wiring modules.

Boundary and audit

• Every acting call still goes through the gateway. Tool execution, approvals and the computer tools moved without changing logic, and approvals are still decided by the approvals service.
• New refusals and failures write rows as before. A handoff refused at admission fails the same way it did when the check came after the lock (agent.handoff_failed), and a capability refusal is still final.
• Nothing new is trusted from the client.

Changelog

• Unreleased has "Bot turns hold their conversation more carefully", covering the three behaviour fixes and the lock lifetime. The rest moves code without changing behaviour.

Proof

Run on this branch after merging main:

bun run typecheck   # every workspace, including shared and toolkit: exit 0
bun run lint        # Biome, --error-on-warnings: clean
bun run format:check  # clean
bun run test        # 6946 pass, 62 skip, 0 fail (7008 tests, 595 files)

Tests ran against a dedicated pgvector database, migrated to 0056. The shared local Postgres runs out of connections under the full suite.

Other checks along the way:

• Boots: after each index.ts move, the server booted against the test database and served /health and /api/me with no "before initialization" errors. Handoff delivery was enabled, so its startup ran.
• Mutation checks: a deliberate break in the waiting-on-interrupt branch, the 409 rule in the lock adapter, the handoff lock-loss stop and the settle order each failed the new tests, as intended.
• Boundary rules: probe files proved them. Core imports of @copilotkit/runtime and ./copilotkit/* were rejected, a copilotkit-folder import of server code was rejected, and the allowed imports passed.
• Docker: the server image builds, and @openbot/toolkit and @openbot/shared resolve inside it with their own dependencies.

Not verified: the computer stream and channel websocket paths through the moved http-server.ts. No test reaches them through index.ts, and the boot check doesn't open a socket.

[davidmckayv]

Requesting changes for one blocker: Desktop can't install a release that contains this. The refactor itself checks out.

What I verified on this branch

• The moves are verbatim. A scripted syntax-tree comparison against main:

  • all 123 plugin-store units and all 61 Composio units match;
  • the 21 routes match on method, path, middleware and order, and their 32 handlers match;
  • http-server.ts matches main's Bun.serve block apart from two re-wrapped lines;
  • 99 of the 132 modified TS files change nothing but import paths.

• index.ts startup is unchanged. The 8 top-level awaits keep their order, and none of the three reassigned variables is passed into a wiring module by value.

• settle() matches main. It reproduces main's order of throws, error objects and side effects, apart from the intended lease change.

• The tests catch regressions. I re-broke each fix: the lease stopping on any failure, the handoff ignoring lock loss, admission after the lock, and two outcomes in settle swapped. The tests caught every one.

• The merge from main lost nothing. #776, #751, #775 and #780 are intact.

• Same dependencies. The lockfile resolves the same package@version set as main; three packages only swapped which version is hoisted.

• Both Dockerfiles build and start, and every toolkit and shared module resolves inside them. CI skipped image and component dockerfiles, which run only with the full-ci label, so I built both by hand.

• It works live. I booted it on a local stack and drove it in the browser:

  • a chat turn;
  • a two-Bot group turn through the toolkit runner;
  • the computer stream websocket, both frames and input;
  • live updates over /api/channels/events;
  • demonstration recording capture.

  All of it worked, which covers the two paths the description lists as unverified. I didn't exercise an approval resume.

Blocker

1. Desktop install fails.
   • Desktop copies a fixed list of folders from the release tarball (desktop/src-tauri/src/deployment.rs:175-187), and toolkit isn't on it.
   • It then runs bun install --frozen-lockfile at the root, which now stops with error: Workspace not found "toolkit". Even past that, the server's @openbot/toolkit/* imports wouldn't resolve.
   • I reproduced it from the copied tree; main's tree installs fine. CI misses it because the startup jobs use the full checkout.
   • Fix: add "toolkit" to ALSO_COPIED. Also add shared and toolkit to PACKAGES in desktop/src-tauri/src/preparation.rs:14, so a dependency change in either triggers a reinstall.

Should fix

2. The lease fails open, with no time limit (inline on toolkit/src/lease.ts).
3. The toolkit core can import CopilotKit code through its own package name (inline on biome.json).

Nits

4. runtimeModel is now computed before normalizeModelBaseUrls() runs (inline).
5. Setting the headless lock lifetime back to 20s fails no test. routine-run-turn.test.ts:766 and thread-lock.test.ts:157 compare against the constant itself, so a literal 120 would pin it.

[guidovizoso]

Thanks, all five fixed in 0bc802f, 7b18de8, 2976821, 68dc477 and 135cbe2. Full suite: 6950 pass, 0 fail.

[davidmckayv]

Thanks, all five check out on 135cbe2.

• Desktop: toolkit is copied into a deployment, shared and toolkit are in PACKAGES, and the fixture lays out both folders.
• Lease: this is what I suggested. A renewal that lands late extends the lock only from when it was asked for, which is the right cautious choice. With the lifetime check removed, two lease tests and the hung-renewal handoff test fail.
• Lint: the self-reference probe is now flagged.
• Model URLs: normalizeModelBaseUrls() runs right before runtimeModel again.
• Lock lifetime: 120 is pinned as a literal in both tests.

The lease, settle, thread-lock, handoff and turn-runner suites pass locally: 34 toolkit tests and 74 server tests.

Optional follow-up, not blocking: a lapse is only noticed on a tick, so a turn can run up to one interval past the lifetime: 15s for a turn, 30s for a handoff. Comparing against lifetimeMs - everyMs would stop it before the lock lapses rather than after.

Approving. app (macos), app (windows) and the Python harness job were still running when I looked.