@best-agent/protocol

Shared public contract for best-agent.

Main Exports

Authoring helpers:

• defineTool(...)
• defineSkill(...)
• plain ContributionDefinition objects

Key public types:

• thread and turn types:
  • Thread
  • ThreadDetail
  • ThreadListItem
  • ThreadMode
  • TurnStatus
• discovery and config:
  • ProviderConfig
  • AgentDefinition
  • AgentDefinitionModelStrategy
  • AgentLoopKind
  • AgentProfileSummary
  • ToolConflictStrategy
  • ToolSummary
  • SkillSummary
  • ExtensionSummary
  • McpServerSummary
• runtime events:
  • EventEnvelope
  • ServerEventType
  • approval, workflow, research, telemetry, and compaction event shapes
• cross-session memory and approvals:
  • ProjectMemoryRecord
  • GuardianAssessment
  • HostedPreToolUseRequest
  • HostedPostToolUseRequest
• graph-owned kernel types:
  • PlanProjection
  • NodeContract
  • ClosurePolicy
  • Verdict
  • VerdictRecord
  • ContinuitySnapshot
  • NodePacket
• request and response types for:
  • thread lifecycle
  • approvals
  • run/stream/interrupt/queue/steer
  • diagnostics and compaction
  • research queries
  • RpcMethodMap for method-to-params/result dispatch typing

Features

• one typed contract shared by app-server, acp-server, sdk-ts, hosted contributions, and runtime internals
• one method-to-params/result map shared by server, sdk-ts, and gateway clients
• structured tool inputs via inputSchema
• composition primitives for AgentDefinition and tool conflict handling
• first-class thread modes, queue/steer controls, diagnostics, telemetry, workflows, and research

Example

import { defineSkill, defineTool, type ContributionDefinition, type ProviderConfig } from "@best-agent/protocol";

const provider: ProviderConfig = {
  kind: "openai",
  model: "gpt-5-mini",
};

const echoTool = defineTool({
  name: "echo-json",
  description: "Echo text from a JSON payload.",
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "string" },
    },
    required: ["text"],
  },
});

const summarySkill = defineSkill({
  id: "concise",
  name: "Concise",
  description: "Respond briefly.",
  content: "Keep answers short.",
});

export const contribution: ContributionDefinition = {
  name: "demo",
  tools: [echoTool],
  skills: [summarySkill],
};

Does Not Own

• runtime logic
• storage implementations
• provider calls
• tool execution

If a type must cross a process boundary, it belongs here.