Harness class

Added in: @mastra/[email protected]

:::warning

The Harness class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.

:::

The Harness class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.

Usage example

import { Harness } from '@mastra/core/harness'
import { LibSQLStore } from '@mastra/libsql'
import { z } from 'zod'

const harness = new Harness({
  id: 'my-coding-agent',
  storage: new LibSQLStore({ url: 'file:./data.db' }),
  stateSchema: z.object({
    currentModelId: z.string().optional(),
  }),
  modes: [
    { id: 'plan', name: 'Plan', default: true, agent: planAgent },
    { id: 'build', name: 'Build', agent: buildAgent },
  ],
})

harness.subscribe(event => {
  if (event.type === 'message_update') {
    renderMessage(event.message)
  }
})

await harness.init()
await harness.selectOrCreateThread()
await harness.sendMessage({ content: 'Hello!' })

Constructor parameters

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Unique identifier for this harness instance.', }, { name: 'resourceId', type: 'string', description: 'Resource ID for grouping threads (e.g., project identifier). Threads are scoped to this resource ID. Defaults to id.', isOptional: true, }, { name: 'storage', type: 'MastraCompositeStore', description: 'Storage backend for persistence (threads, messages, state).', isOptional: true, }, { name: 'stateSchema', type: 'z.ZodObject', description: 'Zod schema defining the shape of harness state. Used for validation and extracting defaults.', isOptional: true, }, { name: 'initialState', type: 'Partial<z.infer<TState>>', description: 'Initial state values. Must conform to the schema if provided.', isOptional: true, }, { name: 'memory', type: 'MastraMemory', description: "Memory configuration shared across all modes. Propagated to mode agents that don't have their own memory.", isOptional: true, }, { name: 'modes', type: 'HarnessMode[]', description: 'Available agent modes. At least one mode is required. Each mode defines an agent and optional defaults.', properties: [ { type: 'HarnessMode', parameters: [ { name: 'id', type: 'string', description: 'Unique identifier for this mode (e.g., "plan", "build").', }, { name: 'name', type: 'string', description: 'Human-readable name for display.', isOptional: true, }, { name: 'default', type: 'boolean', description: 'Whether this is the default mode when the harness starts.', isOptional: true, defaultValue: 'false', }, { name: 'defaultModelId', type: 'string', description: 'Default model ID for this mode (e.g., "anthropic/claude-sonnet-4-20250514"). Used when no per-mode model has been explicitly selected.', isOptional: true, }, { name: 'color', type: 'string', description: 'Hex color for the mode indicator (e.g., "#7c3aed").', isOptional: true, }, { name: 'agent', type: 'Agent | ((state) => Agent)', description: 'The agent for this mode. It can be a static Agent instance or a function that receives harness state and returns an Agent.', }, ], }, ], }, { name: 'tools', type: 'ToolsInput | ((ctx) => ToolsInput)', description: 'Tools available to all agents across all modes. It can be a static tools object or a dynamic function that receives the request context.', isOptional: true, }, { name: 'workspace', type: 'Workspace | WorkspaceConfig | ((ctx) => Workspace)', description: 'Workspace configuration. Accepts a pre-constructed Workspace, a WorkspaceConfig for the harness to construct internally, or a dynamic factory function.', isOptional: true, }, { name: 'subagents', type: 'HarnessSubagent[]', description: 'Subagent definitions. When provided, the harness creates a built-in subagent tool that parent agents can call to spawn focused subagents.', isOptional: true, properties: [ { type: 'HarnessSubagent', parameters: [ { name: 'id', type: 'string', description: 'Unique identifier for this subagent type (e.g., "explore", "execute").', }, { name: 'name', type: 'string', description: 'Human-readable name shown in tool output.', }, { name: 'description', type: 'string', description: 'Description of what this subagent does. Used in the auto-generated tool description.', }, { name: 'instructions', type: 'string', description: 'System prompt for this subagent.', }, { name: 'tools', type: 'ToolsInput', description: 'Tools this subagent has direct access to.', isOptional: true, }, { name: 'allowedHarnessTools', type: 'string[]', description: "Tool IDs from the harness's shared tools config. Merged with tools above to let subagents use a subset of harness tools.", isOptional: true, }, { name: 'allowedWorkspaceTools', type: 'string[]', description: 'Workspace tool names the subagent is allowed to use. Uses the exposed names (after any renames via workspace tool config). When set, workspace tools not in this list are hidden from the model. Non-workspace tools are never affected. When omitted, all workspace tools are visible.', isOptional: true, }, { name: 'defaultModelId', type: 'string', description: 'Default model ID for this subagent type.', isOptional: true, }, { name: 'maxSteps', type: 'number', description: 'Optional maximum number of steps for the spawned subagent. Defaults to 50 when omitted.', isOptional: true, }, { name: 'stopWhen', type: "LoopOptions['stopWhen']", description: 'Optional stop condition for the spawned subagent.', isOptional: true, }, ], }, ], }, { name: 'resolveModel', type: '(modelId: string) => MastraLanguageModel', description: 'Converts a model ID string (e.g., "anthropic/claude-sonnet-4") to a language model instance. Used by subagents and observational memory model resolution.', isOptional: true, }, { name: 'omConfig', type: 'HarnessOMConfig', description: 'Default configuration for observational memory (observer/reflector model IDs and thresholds).', isOptional: true, }, { name: 'heartbeatHandlers', type: 'HeartbeatHandler[]', description: 'Periodic background tasks started during init(). Use for gateway sync, cache refresh, and similar tasks.', isOptional: true, }, { name: 'idGenerator', type: '() => string', description: 'Custom ID generator for Harness-managed IDs such as threads and mode-run identifiers.', isOptional: true, defaultValue: 'timestamp + random string', }, { name: 'modelAuthChecker', type: 'ModelAuthChecker', description: 'Custom auth checker for model providers. Return true/false to override the default environment variable check, or undefined to fall back to defaults.', isOptional: true, }, { name: 'modelUseCountProvider', type: 'ModelUseCountProvider', description: 'Provides per-model use counts for sorting and display in listAvailableModels().', isOptional: true, }, { name: 'toolCategoryResolver', type: '(toolName: string) => ToolCategory | null', description: "Maps tool names to permission categories ('read', 'edit', 'execute', 'mcp', 'other'). Used by the permission system to resolve category-level policies.", isOptional: true, }, { name: 'threadLock', type: '{ acquire, release }', description: 'Thread locking callbacks to prevent concurrent access from multiple processes. acquire should throw if the lock is held.', isOptional: true, }, ]} />

Properties

<PropertiesTable content={[ { name: 'id', type: 'string', description: 'Harness identifier, set at construction.', }, ]} />

Methods

Lifecycle

init()

Initialize the harness. Loads storage, initializes the workspace, propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the harness.

await harness.init()

selectOrCreateThread()

Select the most recent thread for the current resource, or create one if none exist. Loads thread metadata and acquires a thread lock.

const thread = await harness.selectOrCreateThread()

destroy()

Stop all heartbeat handlers and clean up resources.

await harness.destroy()

State

getState()

Return a read-only snapshot of the current harness state.

const state = harness.getState()

setState(updates)

Update the harness state. Validates against stateSchema if provided, and emits a state_changed event with the new state and changed keys.

await harness.setState({ currentModelId: 'anthropic/claude-sonnet-4-6' })

Modes

listModes()

Return all configured HarnessMode instances.

const modes = harness.listModes()

getCurrentModeId()

Return the ID of the currently active mode.

const modeId = harness.getCurrentModeId()

getCurrentMode()

Return the HarnessMode object for the current mode.

const mode = harness.getCurrentMode()

switchMode({ modeId })

Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits mode_changed and model_changed events.

await harness.switchMode({ modeId: 'build' })

Models

getCurrentModelId()

Return the ID of the currently selected model from state.

const modelId = harness.getCurrentModelId()

getModelName()

Return a short display name from the current model ID. For example, "claude-sonnet-4" from "anthropic/claude-sonnet-4".

const name = harness.getModelName()

getFullModelId()

Return the complete model ID string.

const fullId = harness.getFullModelId()

hasModelSelected()

Check if a model ID is currently selected.

if (harness.hasModelSelected()) {
  // Ready to send messages
}

switchModel({ modelId, scope?, modeId? })

Switch the active model. When scope is 'thread', the model ID is persisted to thread metadata so it's restored when switching back. Emits a model_changed event.

// Set for current session only
await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6' })

// Persist to the current thread
await harness.switchModel({ modelId: 'anthropic/claude-sonnet-4-6', scope: 'thread' })

getCurrentModelAuthStatus()

Check if the current model's provider has authentication configured. Uses modelAuthChecker if provided, falling back to environment variable checks from the provider registry.

const status = await harness.getCurrentModelAuthStatus()
// { hasAuth: true, apiKeyEnvVar: 'ANTHROPIC_API_KEY' }

listAvailableModels()

Retrieve all available models from the provider registry, including their authentication status and use counts.

const models = await harness.listAvailableModels()
// [{ id, provider, modelName, hasApiKey, apiKeyEnvVar, useCount }]

Threads

getCurrentThreadId()

Return the ID of the currently active thread.

const threadId = harness.getCurrentThreadId()

createThread({ title? })

Create a new thread. Initializes thread metadata, saves it to storage, acquires a thread lock, and emits a thread_created event.

const thread = await harness.createThread({ title: 'New conversation' })

switchThread({ threadId })

Switch to a different thread. Aborts any in-progress operations, acquires a lock on the new thread, releases the lock on the previous thread, loads the thread's metadata, and emits a thread_changed event.

await harness.switchThread({ threadId: 'thread-abc123' })

listThreads(options?)

List threads from storage. By default, only threads for the current resource are returned.

// List threads for current resource
const threads = await harness.listThreads()

// List all threads across resources
const allThreads = await harness.listThreads({ allResources: true })

renameThread({ title })

Update the title of the current thread.

await harness.renameThread({ title: 'Updated title' })

cloneThread({ sourceThreadId?, title?, resourceId? })

Clone an existing thread and switch to the clone. Copies all messages, acquires a lock on the new thread, releases the lock on the previous thread, and emits a thread_created event. If sourceThreadId is omitted, the current thread is cloned. When Observational Memory is enabled, OM records are cloned with remapped message IDs.

// Clone the current thread
const cloned = await harness.cloneThread()

// Clone a specific thread with a custom title
const cloned = await harness.cloneThread({
  sourceThreadId: 'thread-abc123',
  title: 'Alternative approach',
})

See Memory.cloneThread() for details on what gets cloned.

getResourceId()

Return the current resource ID.

const resourceId = harness.getResourceId()

setResourceId({ resourceId })

Set the resource ID and clear the current thread.

harness.setResourceId({ resourceId: 'project-xyz' })

getSession()

Return current session information including thread ID, mode ID, and the list of threads.

const session = await harness.getSession()
// { currentThreadId, currentModeId, threads }

Messages

sendMessage({ content, files?, requestContext? })

Send a message to the current agent. Creates a thread if none exists, builds a RequestContext and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically. If you provide requestContext, the harness forwards it to tools and subagents during the run.

await harness.sendMessage({ content: 'Explain the authentication flow' })

listMessages(options?)

Retrieve messages for the current thread.

const messages = await harness.listMessages()

// Limit to the last 50 messages
const recent = await harness.listMessages({ limit: 50 })

listMessagesForThread({ threadId, limit? })

Retrieve messages for a specific thread.

const messages = await harness.listMessagesForThread({ threadId: 'thread-abc123' })

getFirstUserMessageForThread({ threadId })

Retrieve the first user message for a given thread.

const firstMsg = await harness.getFirstUserMessageForThread({ threadId: 'thread-abc123' })

Memory

The memory property exposes thread management operations. These are also available as top-level methods on the harness.

memory.createThread({ title? })

Create a new thread. Same as harness.createThread().

memory.switchThread({ threadId })

Switch to a different thread. Same as harness.switchThread().

memory.listThreads(options?)

List threads from storage. Same as harness.listThreads().

memory.renameThread({ title })

Update the title of the current thread. Same as harness.renameThread().

memory.deleteThread({ threadId })

Delete a thread and all its messages from storage. If the deleted thread is the currently active thread, the thread lock is released and the harness clears its active thread. Emits a thread_deleted event.

await harness.memory.deleteThread({ threadId: 'thread-abc123' })

Flow control

abort()

Abort any in-progress generation.

harness.abort()

steer({ content, requestContext? })

Steer the agent mid-stream by injecting an instruction into the current generation.

harness.steer({ content: 'Focus on security implications' })

followUp({ content, requestContext? })

Queue a follow-up message to be sent after the current generation completes. If no operation is running, sends the message immediately.

harness.followUp({ content: 'Now apply those changes' })

Tool approvals

respondToToolApproval({ decision, requestContext? })

Respond to a pending tool approval request. Called when a tool_approval_required event is received.

harness.respondToToolApproval({ decision: 'approve' })
harness.respondToToolApproval({ decision: 'decline' })

Questions and plans

respondToQuestion({ questionId, answer })

Respond to a pending question from the ask_user built-in tool.

harness.respondToQuestion({ questionId: 'q-123', answer: 'Yes, proceed with the refactor' })

respondToPlanApproval({ planId, response })

Respond to a pending plan approval from the submit_plan built-in tool. The response object contains action ('approved' or 'rejected') and an optional feedback string.

harness.respondToPlanApproval({ planId: 'plan-123', response: { action: 'approved' } })
harness.respondToPlanApproval({
  planId: 'plan-123',
  response: { action: 'rejected', feedback: 'Needs more detail' },
})

Permissions

grantSessionCategory({ category })

Grant a tool category for the current session. Tools in this category are auto-approved without prompting.

harness.grantSessionCategory({ category: 'edit' })

grantSessionTool({ toolName })

Grant a specific tool for the current session.

harness.grantSessionTool({ toolName: 'mastra_workspace_execute_command' })

getSessionGrants()

Return currently granted session categories and tools.

const grants = harness.getSessionGrants()
// { categories: Set<string>, tools: Set<string> }

setPermissionForCategory({ category, policy })

Set the permission policy for a tool category.

harness.setPermissionForCategory({ category: 'execute', policy: 'ask' })

setPermissionForTool({ toolName, policy })

Set the permission policy for a specific tool. Per-tool policies take precedence over category policies.

harness.setPermissionForTool({ toolName: 'dangerous_tool', policy: 'deny' })

getPermissionRules()

Return the current permission rules.

const rules = harness.getPermissionRules()
// { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }

getToolCategory({ toolName })

Resolve a tool's category using the configured toolCategoryResolver.

const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_file' })
// 'edit'

Workspace

getWorkspace()

Return the current workspace instance, or undefined if no workspace is configured or it hasn't been resolved yet.

const workspace = harness.getWorkspace()

resolveWorkspace({ requestContext? })

Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory and caches the result so getWorkspace() returns it. Returns the resolved workspace or undefined if none is configured.

const workspace = await harness.resolveWorkspace()

hasWorkspace()

Return whether a workspace is configured (static, config-based, or dynamic).

if (harness.hasWorkspace()) {
  const workspace = await harness.resolveWorkspace()
}

isWorkspaceReady()

Return whether the workspace is ready to use. For dynamic workspaces (factory function), always returns true. For static workspaces, returns true after init() succeeds.

if (harness.isWorkspaceReady()) {
  const workspace = harness.getWorkspace()
}

destroyWorkspace()

Destroy the workspace and release resources. Only applies to static workspaces — dynamic workspaces aren't destroyed.

await harness.destroyWorkspace()

Observational Memory

loadOMProgress()

Load observational memory records for the current thread and emit an om_status event with reconstructed progress.

await harness.loadOMProgress()

getObservationalMemoryRecord()

Return the full ObservationalMemoryRecord for the current thread and resource, or null if no thread is selected or no record exists.

const record = await harness.getObservationalMemoryRecord()

if (record) {
  console.log(record.activeObservations)
  console.log(record.generationCount)
  console.log(record.observationTokenCount)
}

getObserverModelId()

Return the observer model ID from state or the default from omConfig.

const modelId = harness.getObserverModelId()

getReflectorModelId()

Return the reflector model ID from state or the default from omConfig.

const modelId = harness.getReflectorModelId()

switchObserverModel({ modelId })

Switch the observer model. Persists the setting to thread metadata and emits an om_model_changed event.

await harness.switchObserverModel({ modelId: 'anthropic/claude-haiku-3.5' })

switchReflectorModel({ modelId })

Switch the reflector model. Persists the setting to thread metadata and emits an om_model_changed event.

await harness.switchReflectorModel({ modelId: 'anthropic/claude-haiku-3.5' })

getObservationThreshold()

Return the observation threshold in tokens from state or the default from omConfig.

const threshold = harness.getObservationThreshold()

getReflectionThreshold()

Return the reflection threshold in tokens from state or the default from omConfig.

const threshold = harness.getReflectionThreshold()

Subagents

getSubagentModelId({ agentType? })

Retrieve the subagent model ID. Prioritizes per-type settings over the global setting.

const modelId = harness.getSubagentModelId({ agentType: 'explore' })

setSubagentModelId({ modelId, agentType? })

Set the subagent model ID. Pass an agentType to set a per-type override, or omit it to set the global default. Persists to thread settings and emits a subagent_model_changed event.

// Set global subagent model
await harness.setSubagentModelId({ modelId: 'anthropic/claude-sonnet-4-6' })

// Set per-type model
await harness.setSubagentModelId({ modelId: 'anthropic/claude-haiku-3.5', agentType: 'explore' })

Events

subscribe(listener)

Register an event listener. Returns an unsubscribe function.

const unsubscribe = harness.subscribe(event => {
  switch (event.type) {
    case 'message_update':
      renderMessage(event.message)
      break
    case 'tool_approval_required':
      showApprovalPrompt(event.toolName)
      break
    case 'error':
      console.error(event.error)
      break
  }
})

// Later:
unsubscribe()

Events

The harness emits events through registered listeners. The following table lists the available event types:

Built-in tools

The harness provides built-in tools to agents in every mode: