clawrun AGENTS.md

AGENTS.md — Agent Interface & Implementation Guide

Agent Interface

Defined in packages/agent/src/types.ts. Every agent implementation must implement this interface.

interface Agent {
  readonly id: string;
  readonly name: string;
  readonly channelsConfigKey: string;
  readonly daemonPort: number;

  // Provisioning
  provision(sandbox, root, opts: ProvisionOpts): Promise<void>;

  // Messaging
  sendMessage(sandbox, root, message, opts?): Promise<AgentResponse>;
  streamMessage(sandbox, root, message, writer: UIMessageStreamWriter, opts?): Promise<void>;

  // Conversation threads
  listThreads(sandbox, root, opts?): Promise<ThreadInfo[]>;
  getThread(sandbox, root, threadId, opts?): Promise<UIMessage[]>;

  // Daemon and cron
  getDaemonCommand(root, opts?): DaemonCommand;
  listCronJobs(sandbox, root, opts?): Promise<CronJob[]>;

  // Tools
  getAvailableTools(): Tool[];
  getEnabledTools(agentDir): Tool[];
  getToolDomains(agentDir): Tool[];

  // Configuration and setup
  getMonitorConfig(root): MonitorConfig;
  getProviders(): ProviderInfo[];
  getDefaultModel(provider): string;
  getCuratedModels(provider): CuratedModel[];
  getModelsFetchEndpoint(provider, apiUrl?): { url, authHeader } | null;
  getSupportedChannels(): ChannelInfo[];
  writeSetupConfig(agentDir, data: AgentSetupData): void;
  readSetup(agentDir): { provider?; channels?; cost? } | null;

  // Bundling and dependencies
  getLocalOwnedFiles(): string[];
  getBundleFiles(): string[];
  getBinaryBundlePaths(): string[];
  getInstallDependencies(): Record<string, string>;
  getSeedDirectory(): string | null;

  // Dashboard API (called via daemon HTTP endpoints)
  getStatus(sandbox, root, opts?): Promise<AgentStatus>;
  getConfig(sandbox, root, opts?): Promise<AgentConfig>;
  listTools(sandbox, root, opts?): Promise<ToolsResult>;
  createCronJob(sandbox, root, job, opts?): Promise<CronJob>;
  deleteCronJob(sandbox, root, id, opts?): Promise<void>;
  listMemories(sandbox, root, query?, opts?): Promise<MemoryEntryInfo[]>;
  createMemory(sandbox, root, entry, opts?): Promise<void>;
  deleteMemory(sandbox, root, key, opts?): Promise<void>;
  getCostInfo(sandbox, root, opts?): Promise<CostInfo>;
  runDiagnostics(sandbox, root, opts?): Promise<DiagResult[]>;
}