feat: port brain features — spine routing, exec security, actuator tools#3
feat: port brain features — spine routing, exec security, actuator tools#3siofra-seksbot merged 5 commits intomainfrom
Conversation
When BOTSTER_EXEC_VIA_SPINE=1 is set (along with SEKS_BROKER_URL and SEKS_BROKER_TOKEN), tool calls route through the broker to a remote actuator via POST /v1/command instead of executing locally. New files: - src/seks/spine-client.ts: HTTP client for broker command endpoint - src/seks/spine-exec-intercept.ts: Tool wrappers that intercept and route exec/process/read/write/edit through the spine Modified: - src/agents/pi-tools.ts: Wire up spine wrappers at tool assembly time Design: wrapper pattern — zero code paths change when spine is off. Brain sends sync HTTP to broker, broker relays via WS to actuator.
…raint) Codex used AgentTool<unknown, unknown> but unknown doesn't satisfy the TSchema constraint. Changed to AgentTool<any, any> to match codebase conventions (AgentState.tools uses AgentTool<any>). Added eslint-disable for the file since every function signature needs it. Added review notes in REVIEW.md.
…AL=1 - Invert BOTSTER_EXEC_VIA_SPINE opt-in to BOTSTER_EXEC_NORMAL opt-out - Remove SEKS_BROKER_TOKEN requirement (superego proxy injects real token) - Only SEKS_BROKER_URL needed for spine routing to activate
d7010a6 to
2c7b46b
Compare
- Add brain-level actuator_list/actuator_select guide (docs/tools/actuator-tools.md)
- Add 30 unit tests for spine-client.ts and spine-exec-intercept.ts
- getSpineConfig: env var handling, opt-out, normalisation, defaults
- spineExec: happy path, failure, timeout, HTTP errors, no-actuator guard
- createSpineExecTool: all result states, passthrough, arg forwarding
- createSpine{Process,Read,Write,Edit}Tool: capability routing
2c7b46b to
04b07f2
Compare
footgun-seksbot
left a comment
There was a problem hiding this comment.
Thorough review of all 6 files (1,228 additions). Here's my assessment:
spine-client.ts — Clean, defensive. Good normalization helpers (brokerUrl trailing slash strip, timeout validation). Error resolution chain (message → error → fallback) is solid. AbortController timeout pattern is correct with proper cleanup in finally block. The 'superego-proxy' default token is a reasonable sentinel.
spine-exec-intercept.ts — Well-structured routing layer. Key observations:
ensureActuatorAvailablecorrectly catches the null-result sentinel (no actuator)mapExecResultproperly handles all 4 status types (completed/failed/running/timeout) with appropriate detail structuresresolveExecTimeoutMscaps at 65s and adds 5s buffer over the user timeout — sensible- The
isAgentToolResultduck-typing check inmapGenericSpineResultallows passthrough of already-formatted results from the broker - All createSpine*Tool wrappers correctly guard on
baseExecuteexistence before wrapping
spine-client.test.ts (14 tests) — Good coverage: env var priority, normalization, happy path, failure, timeout (real AbortController), HTTP errors, unreachable broker, null result sentinel, request format verification.
spine-exec-intercept.test.ts (16 tests) — Properly mocks spine-client at module level. Covers all tool wrappers (exec/process/read/write/edit), all status paths, no-actuator guard, passthrough for undefined execute, and payload forwarding.
pi-tools.ts — Integration point is minimal and correct: conditional wrapping when getSpineConfig() returns non-null. The let reassignment pattern for exec/process tools is slightly unusual but works fine for conditional wrapping. Actuator tools (list/select) are registered only when spine is active — good.
docs/tools/actuator-tools.md — Clear, accurate, includes security model note about superego proxy boundary. Operator quick-check commands are a nice touch.
No issues found. The test coverage is comprehensive and well-structured. LGTM.
Summary
Ports 5 commits from
BotstersDev/botster-brainintobotster-ego(the official OpenClaw fork). These features exist in the older fork but were never brought across.This is PR 1 of 2. PR 2 will sync the fork with upstream
openclaw/openclaw.Commits
feat: spine routing for exec/process/read/write/edit toolsfix: use any instead of unknown for AgentTool generics (TSchema constraint)feat: default-secure exec routing — spine on unless BOTSTER_EXEC_NORMAL=1feat: actuator list and select tools (brain-level, via superego proxy)docs: add brain-level actuator_list/actuator_select guideWhat's Included
Spine routing — exec/process/read/write/edit tools proxy through the broker to a remote actuator when
BOTSTER_EXEC_VIA_SPINE=1. Default-secure:BOTSTER_EXEC_NORMAL=1is required to opt out of spine.Actuator tools —
actuator_listandactuator_selectas brain-level tools, routed through the superego proxy. Enables agents to manage their own actuator selection.What Was NOT Ported
Brain-specific packaging left behind intentionally:
feat: botster-brain CLI wrapper + config lobotomyrebrand: botster-brain → openclawfix: symlink resolution in wrapperNotes
REVIEW.md(FootGun's internal review artifact from brain's spine routing PR) was stripped from commit 2 — it's not appropriate at repo root.Testing
Will be validated end-to-end on Nira + mock agent after PR 2 (upstream sync) lands.