@best-agent/engine

Runtime core for best-agent.

Main Exports

Runtime:

• AgentRuntime
• createAgentProfileRegistry()
• AgentProfileInput

Storage and memory:

• LocalThreadStore
• LocalThreadMemory
• resolveWorkspaceStorageRoot()
• DEFAULT_STORAGE_DIRECTORY_NAME

Tools, skills, and hosted contributions:

• ToolRegistry
• createDefaultToolRegistry()
• createCommandToolDefinition()
• createMcpToolDefinition()
• SkillRegistry
• createHostedContributionBundle()
• defineTool(...)
• defineSkill(...)

Policy, sandbox, and provider:

• RuntimePolicy
• createDefaultRuntimePolicy()
• DEFAULT_ALLOWED_TOOLS
• LocalSandbox
• createModelProvider()
• OpenAiSdkProvider
• AnthropicSdkProvider
• GoogleSdkProvider

Prompting:

• compilePrompt()

Features

• persisted thread lifecycle with SQLite-backed storage
• thread modes:
  • default
  • plan
• approvals, queue/steer controls, sandboxing, and workspace grounding
• segmented memory, compaction, handoff snapshots, and diagnostics
• project-scoped cross-session memory injection via authoritative memory.md, next-session candidate consolidation, generated-section freshness metadata, and a stale-memory eval gate
• built-in workflows and deep research
• built-in lightweight LSP tools for TypeScript/JavaScript navigation plus Python diagnostics and symbol search, with soft fallback for unsupported files
• fetch-url(format:"rich"), web-search with native OpenAI or runtime-provided adapter execution, deep-research workflow budgeting, soft-unavailable fallback, and prompt-cache diagnostics/benchmarking in the shared tool/runtime path
• provider-backed turns plus runtime-owned tool execution
• hosted-contribution, skill, extension, and MCP normalization into one runtime
• hosted PreToolUse / PostToolUse hooks and Guardian-backed model-assisted approval assessments with an offline eval corpus
• composable-runtime primitives:
  • AgentDefinition inputs normalized through createAgentProfileRegistry()
  • ToolRegistry conflict strategies
  • createDefaultToolRegistry({ excludeBuiltIns, noBuiltIns, extraTools })
  • AgentDefinition.loopKind = "advanced" for custom advanced-phase runs
  • AgentDefinition.maxToolSteps for per-agent provider loop limits
  • AgentDefinition.modelStrategy for per-agent routing overrides
  • customLoops and AgentDefinition.customLoopId for custom turn-loop replacement
  • per-agent permission overlays and project .best-agent/agents loading

Example

import { AgentRuntime } from "@best-agent/engine";

const runtime = new AgentRuntime({
  cwd: process.cwd(),
  storageRoot: "/tmp/best-agent-demo",
});

const { thread } = await runtime.startThread({ title: "Demo" });
const result = await runtime.runTurn({
  threadId: thread.id,
  prompt: 'tool:echo {"text":"hello"}',
});

console.log(result.turn.status);

Internal Layout

• agent/: built-in profiles and routing
• core/: thread, approval, queue, and research stores
• memory/: summaries, working memory, telemetry, compaction, segmented cache
• plugin/: local and hosted plugin normalization
• policy/: capability evaluation
• prompt/: prompt directives and project instructions
• provider/: AI SDK-backed model providers
• runtime/: turn execution and event emission
• sandbox/: filesystem and subprocess enforcement
• skill/: installed skill registry
• tool/: built-in tool registry and structured input handling

Does Not Own

• transport protocols
• CLI UX
• external SDK process management