Skip to content

API reference ​

Entry points ​

ImportContract
@korus-dev/multi-agent-sdkcreateHarness, HarnessUnsupportedError, TypedEventBus, TtlCache and the public types
/promptPure prompt authoring helpers for browser consumers.
/runtimeNode helpers that find a provider's executable and build the search path it runs with.
/testingHarnesses over scripted providers, for testing an application without a real provider.
/contractsCapability tables, session patches, guards and data helpers with no Node dependencies, for code that runs in a browser.
/codex, /claude, /cursor, /antigravityThat provider's own types, for apps that deliberately read provider-specific detail.

Paths in this table are appended to @korus-dev/multi-agent-sdk. An explicit exports map resolves the root and extensionless subpaths directly into the published build. Use root import type declarations for public types.

ts
import { createHarness } from '@korus-dev/multi-agent-sdk';
import type { HarnessEvent } from '@korus-dev/multi-agent-sdk';
import { normalizePromptContent } from '@korus-dev/multi-agent-sdk/prompt';

Browser code imports from /contracts, which loads no provider code or Node modules:

GroupExports
Session patchesapplySessionPatch, SessionPatchGapError, SessionPatchInvalidError
CapabilitiescodexHarnessCapabilities, claudeHarnessCapabilities, cursorHarnessCapabilities, antigravityHarnessCapabilities
ProvidersharnessProviders, isHarnessProvider
Conversation identitysessionConversationId, sessionConversationRef, sessionHasConversation, conversationSessionData, conversationRefId, sameConversationRef, isProviderSessionData, isProviderConversationRef
SubagentssubagentRef, subagentOfRef and the subagent* kind and status lists
RequestsAgentRequest conversions such as requestFromClientRequest and clientResponseFromAgentResponse
Safety and toolsisProviderSafetyReview, providerSafetyBlockMessage, toolOutputText

Shared contracts ​

The common application API is Harness, created by createHarness. Every provider (Codex, Claude, Cursor, Antigravity) is reached through it. Shared contracts are provider-neutral: Message, MessagePart, AgentRequest, AgentRequestResponse, ProviderApprovalRequest, ProviderApprovalDecision, Turn, PromptPart, PromptReferenceAttachment and ModelOption. Codex's own message and request shapes are available as CodexConversationMessage and CodexClientRequest from /codex, for apps that read Codex snapshots and events.

TtlCache and its TtlCacheOptions, TtlCacheRecord, TtlCacheScheduler, TtlCacheTimer and TtlCacheEvictionContext types are available from the root. The caller supplies cache identity, eviction policy and cleanup callbacks.

Factory ​

createHarness(provider, options): Harness

Providers are codex, claude, cursor, and antigravity. options.client.name is required. Optional fields include home, stateDirectory, context-dependent instructions and mcpServers, formatPrompt, isAppPlugin, presentToolCall, and named provider options. isAppPlugin(id) says which plugin mentions name a plugin the app provides itself: such a mention is never sent to the harness as one of its own plugins, and reaches the model through the prompt text. presentToolCall({ server, tool, input, result, state }) lets the app title its own MCP tool calls: it is asked when a call starts and when it ends, with the input and result as the harness reported them, and a string it returns becomes the call's metadata.displayTitle. Native provider configuration remains in those named options rather than becoming generic policy.

Each provider runs the CLI installed on the machine. To use another executable, name it in that provider's options: cursor.command, antigravity.command, or claude.launch.

Harness operations ​

GroupMethods
Session lifecycleopen, readSession, readSessionSnapshot, syncSession, updateDefaults, release, close
RestorationgetSessionData, restoreSession, getConversationRef, getRefData, restoreRef
Runtime and accountgetRuntimeStatus, authenticate, getAccountRateLimits, getBankedResets, useBankedReset, getCapabilities, getProviderCapabilities
CatalogslistModels, listSkills, listPlugins
Promptingrun, sendPrompt, steerPrompt, interrupt, continueInterruptedTurn, respondToRequest, setPermission, handlePromptCommand, preparePromptOptions
HistorylistConversations, resumeConversation, loadConversation, loadOlderHistory, loadTurnHistory, readConversationMessages, readConversationSummary, readConversationContent, reconcileConversations
Conversations and turnssetConversationTitle, archiveConversation, deleteConversation, setConversationStorage, forkConversation, deleteTurn, editTurn, retryTurn
Goals and reviewssetGoal, clearGoal, startReview
Scoped work and generationopenScope, executeScopedPrompt, disposeScopedSession, generateText, generateImage
Realtime and remote controlstartRealtime, getRemoteControl, setRemoteControl, startDevicePairing, checkDevicePairing, listPairedDevices, revokePairedDevice
EventsonEvent returns an unsubscribe function

Every session operation takes a handle owned by that harness. Every optional operation has a capability flag; an operation a provider does not support rejects with HarnessUnsupportedError. run returns a Run: its events and a result that settles when the turn ends. sendPrompt returns Admission, independently of terminal turn status. executeScopedPrompt returns only the turn's final answer as text. Request responses carry an ID and an explicit decision, answers, or cancellation outcome.

Capabilities ​

getCapabilities(session) says what the session's harness supports, in the same shape for every provider. Among the fields:

FieldMeaning
permissionsThe provider's own permission modes, each { id, dangerous? }. defaults.permission holds one of them and setPermission changes it.
folderScopedConversationsWhether conversations belong to a working folder, so their references carry a folder.
subagentTranscripts'inline', 'separate' or 'none': where a subagent's transcript can be read.
loginThe managed login methods authenticate can start.
workPhasesThe harness states each text part's work phase (commentary or final_answer). Where it is absent, text carries no phase and an app groups a turn's work itself, for example by its start time and duration.
turnHistoryTurns can arrive as summaries, and loadTurnHistory loads one turn's full items.

Conversation identity and account ​

Session data and conversation references name the conversation conversationId on every harness; Claude session data may also carry transcriptConversationId. authenticate returns account, the signed-in account for every harness:

ts
type Account = { kind: 'subscription' | 'apiKey' | 'cloud'; email?: string; plan?: string; team?: string };

See the consumer contract for detailed lifecycle rules and the published declarations for exact parameter/result types. Guides cover state/events, sessions, and tools.

Released under the Apache License 2.0.