# Exports

> Classes, functions, constants, and types exported by the agent SDK package.

Source: https://maincode.com/docs/agent-sdk-exports
Section: Agent SDK · Matilda documentation

---

## Classes

| Export | Description |
| - | - |
| `Agent` | Named persona with static or dynamic instructions. |
| `Runner` | Main execution class. Holds `auth`, `files`, `conversations`, `feedback` resources. |
| `Session` | Multi-turn conversation wrapper with auto-managed `conversationId`. |
| `AgentAuth` | Managed auth: login, restore, token refresh, logout. |
| `MatildaAgentRunError` | HTTP-level failure (status, responseText). |
| `MatildaAgentStreamError` | SSE stream error (code, errors, partial result). |
| `SafetyReplaceError` | Safety filter replacement error (categories). |
| `MatildaObjectParseError` | Structured output parse/validation failure (raw, cause). |
| `MatildaCore` | Underlying API client (re-exported from `@matilda/api-client`). |
| `FilesResource` | File upload/retrieve resource. |
| `ConversationsResource` | Conversation list/retrieve/update/feedback resource. |
| `FeedbackResource` | Bug-report resource (`reportBug`). |

## Functions

| Export | Description |
| - | - |
| `run(agent, input, options?)` | Run an agent turn via `defaultRunner`. Returns `Promise<AgentRunResult>`. |
| `stream(agent, input, options?)` | Stream agent events via `defaultRunner`. Returns `AsyncGenerator<AgentRunEvent>`. |
| `streamText(agent, input, options?)` | Stream text deltas via `defaultRunner`. Returns `AsyncGenerator<string>`. |
| `runText(agent, input, options?)` | Run and return just the text via `defaultRunner`. Returns `Promise<string>`. |
| `streamObject(agent, input, schema, options?)` | Stream with structured output via `defaultRunner`. Returns `AsyncGenerator<AgentObjectEvent<T>>`. |
| `runObject(agent, input, schema, options?)` | Run with structured output via `defaultRunner`. Returns `Promise<AgentObjectResult<T>>`. |
| `createSession(agent, options?)` | Create a `Session`. |
| `buildAgentChatRequest(opts)` | Build a `ChatRequest` without executing. |
| `resumeAgentStream(streamId, lastEventId, handlers, options?)` | Resume a detached durable stream. |
| `configureClient(options)` | Configure the default `MatildaCore` singleton. |
| `getClientConfig()` | Get the default core's config. |
| `getDefaultCore()` | Get the default `MatildaCore` singleton. |
| `trustApiBaseUrl(rawUrl, policy?)` | Validate and brand a URL as trusted. |
| `createFileTokenStore(path)` | `0600` JSON file token store with cross-process lock. |
| `memoryStorage()` | In-memory `StorageAdapter`. |

## Constants

| Export | Value | Description |
| - | - | - |
| `DEFAULT_AGENT_PURPOSE` | `'code'` | Default agent purpose. |
| `DEFAULT_AGENT_STALL_TIMEOUT_MS` | `45_000` | Default SSE stall watchdog timeout. |
| `DEFAULT_MAX_TOOL_ROUNDTRIPS` | `25` | Default maximum tool roundtrips. |
| `DEFAULT_MAX_RETRIES` | `0` | Default maximum retries. |
| `DEFAULT_SUCCESS_REDIRECT` | `'https://matilda.maincode.com/cli/signed-in'` | Default browser login success redirect. |
| `MATILDA_API_VERSION_HEADER` | — | API version header name. |
| `MATILDA_CURRENT_API_VERSION` | — | Current API version string. |

## Instances

| Export | Description |
| - | - |
| `defaultRunner` | A `Runner` using the default `MatildaCore` singleton. |

## Types

| Export | Description |
| - | - |
| `AgentPurpose` | `'code' \| 'analysis' \| 'general'` |
| `AgentInstructions` | `string \| ((ctx: AgentRunContext) => string \| Promise<string>)` |
| `AgentRunContext` | Context passed to dynamic instructions. |
| `AgentOptions` | Constructor options for `Agent`. |
| `AgentRunOptions` | Options for `runner.run()` / `runner.stream()`. |
| `AgentRunEvent` | 22-variant discriminated union of stream events. |
| `AgentRunResult` | Result of an agent run. |
| `AgentObjectEvent<T>` | `AgentRunEvent` plus a final `{ type: 'object'; object: T }`. |
| `AgentObjectResult<T>` | `AgentRunResult` plus the validated `object`. |
| `AgentObjectRunOptions<T>` | `AgentRunOptions` with an embedded zod `schema`. |
| `AgentCallbacks` | Callback hooks for `run()`. |
| `BuildAgentChatRequestOptions` | Options for `buildAgentChatRequest()`. |
| `ToolHandler` | `(args, ctx) => Promise<ToolResult>` |
| `ToolHandlers` | `Record<string, ToolHandler>` |
| `ToolExecutionContext` | Context passed to tool handlers. |
| `ToolResult` | `{ content: string; isError?: boolean }` |
| `SessionOptions` | Options for `Session` / `createSession()`. |
| `FileUploadOptions` | Options for `files.upload()`. |
| `CoreSource` | `MatildaCore \| (() => MatildaCore)` |
| `BrowserLoginOptions` | Options for `auth.loginWithBrowser()`. |
| `DeviceLoginOptions` | Options for `auth.loginWithDeviceFlow()`. |
| `TokenSet` | `{ accessToken, refreshToken?, idToken?, expiresAt }` |
| `TokenManager` | Token manager interface. |
| `StorageAdapter` | Token persistence interface. |
| `LoginFlowEvent` | Login flow state event type. |
| `FileTokenStore` | File token store return type. |
| `ClientConfig` | Core config type (re-exported). |
| `GetToken` | Token provider function type (re-exported). |
| `TrustedApiBaseUrl` | Branded string type (re-exported). |
| `TrustedApiBaseUrlPolicy` | URL validation policy (re-exported). |
| `ApiMessage` | `{ role, content }` (re-exported). |
| `ChatRequest` | Chat request type (re-exported). |
| `ChatResponseMode` | `'auto' \| 'instant' \| 'deep'` (re-exported). |
| `ChatSseEvent` | SSE event type (re-exported). |
| `ChatSseEventName` | SSE event name type (re-exported). |
| `SafetyReplaceEvent` | Safety replace event type (re-exported). |
| `UsageEvent` | Token usage type (re-exported). |
| `ConversationListResponse` | Conversation list response (re-exported). |
| `ConversationRecord` | Full conversation record (re-exported). |
| `ConversationSummary` | Conversation summary (re-exported). |
| `FileAttachment` | File metadata (re-exported). |
| `FileCompleteResponse` | File upload result (re-exported). |
| `UploadFilesOptions` | Multi-file upload options (re-exported). |

## Error classes re-exported

| Export | Description |
| - | - |
| `AuthError` | OAuth error (code, retryable). Re-exported from client SDK. |