# @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

```ts
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
