@best-agent/server

Transport adapters over the shared runtime.

Main Exports

• AppServer
• createAppServer(...)
• runStdioServer(...)
• runHttpServer(...)
• handleRpcRequest(...)
• runSocketDaemon(...)
• readDaemonMetadata(...)
• AcpServer
• createAcpServer(...)
• runStdioAcpServer(...)

Features

• stdio app-server
• HTTP + SSE app-server
• native-socket or named-pipe daemon-backed app-server
• stdio acp-server
• shared reverse-RPC hosted-plugin bridge across stdio and daemon app-server transports
• current HTTP adapter coverage for:
  • initialize, host status, and runtime metadata discovery
  • approval grant listing and revocation
  • project-memory get/set/clear
  • team-memory shared-store GET/PATCH keyed by normalized git remote
  • project-memory sync diagnostics surfaced on memory.get/set/clear
  • thread start, rename, metadata update, detail, history, handoff, diagnostics, compaction, resume, and event catch-up
  • fork plus archive, unarchive, and purge lifecycle operations
  • queued-turn enqueue, dequeue, and listing plus scratch pruning
  • thread mode updates plus plan draft read, todo update, export, approve, and reject
  • deep-research report and evidence reads plus generic thread evidence reads
  • turn run, interrupt, and steer
  • approval and ask-user responses
  • SSE turn streams that carry queue and workspace lifecycle events such as turn.queued and workspace.file.updated
• shared runtime factory wiring for:
  • cwd
  • storageRoot
  • provider config
  • guardian config
  • programmatic webSearch adapter plus webSearchAvailability gate
  • extension manifests
  • hosted plugins
• runtime event forwarding for:
  • turns
  • approvals
  • plan drafts and approval lifecycle
  • workflows
  • research
  • telemetry
  • compaction
  • child-thread deltas
• HTTP auth boundary:
  • loopback hosts (127.0.0.1, ::1, localhost) remain no-auth by default
  • non-loopback runHttpServer(...) requires BEST_AGENT_HTTP_TOKEN
  • authenticated JSON routes require Authorization: Bearer <token>
  • authenticated SSE routes also accept ?access_token=<token>

Example

import { runHttpServer } from "@best-agent/server";

await runHttpServer({
  cwd: process.cwd(),
  host: "127.0.0.1",
  port: 3000,
  storageRoot: "/tmp/best-agent-demo",
});

For non-loopback hosts, export BEST_AGENT_HTTP_TOKEN before starting the server.

External search hosts should inject capability, not just a vendor key string. The intended shape is:

import { createAppServer } from "@best-agent/server";

await createAppServer({
  providerConfig,
  webSearchAvailability: () => Boolean(searchConfig.apiKey),
  webSearch: async (input) => await searchBackend(input, searchConfig),
});

If searchConfig.apiKey changes while the process stays alive, the next turn should see the updated web-search capability. See /Users/Simon/Github/best-agent/docs/architecture/web-search-capability-and-configuration.md for the full contract.

Does Not Own

• independent business logic
• a second runtime
• separate policy or tool implementations

server stays thin: it maps requests and notifications onto one shared AgentRuntime, whether the transport is stdio, HTTP+SSE, a local daemon socket, or ACP stdio.