@mastra/core 1.4.0 → 1.5.0-alpha.1

package/dist/harness/harness.d.ts

@@ -0,0 +1,281 @@
+import type { z } from 'zod';
+import { Workspace } from '../workspace/workspace.js';
+import type { AvailableModel, HeartbeatHandler, HarnessConfig, HarnessEventListener, HarnessMessage, HarnessMode, HarnessSession, HarnessStateSchema, HarnessThread, ModelAuthStatus, PermissionPolicy, PermissionRules, ToolCategory } from './types.js';
+/**
+ * The Harness orchestrates multiple agent modes, shared state, memory, and storage.
+ * It's the core abstraction that a TUI (or other UI) controls.
+ *
+ * @example
+ * ```ts
+ * 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.sendMessage("Hello!")
+ * ```
+ */
+export declare class Harness<TState extends HarnessStateSchema = HarnessStateSchema> {
+    readonly id: string;
+    private config;
+    private state;
+    private currentModeId;
+    private currentThreadId;
+    private resourceId;
+    private listeners;
+    private abortController;
+    private abortRequested;
+    private currentRunId;
+    private currentOperationId;
+    private followUpQueue;
+    private pendingApprovalResolve;
+    private pendingApprovalToolName;
+    private pendingQuestions;
+    private pendingPlanApprovals;
+    private workspace;
+    private workspaceFn;
+    private workspaceInitialized;
+    private heartbeatTimers;
+    private tokenUsage;
+    private sessionGrantedCategories;
+    private sessionGrantedTools;
+    constructor(config: HarnessConfig<TState>);
+    /**
+     * Initialize the harness — loads storage and workspace.
+     * Must be called before using the harness.
+     */
+    init(): Promise<void>;
+    /**
+     * Select the most recent thread, or create one if none exist.
+     */
+    selectOrCreateThread(): Promise<HarnessThread>;
+    private getMemoryStorage;
+    /**
+     * Get current harness state (read-only snapshot).
+     */
+    getState(): Readonly<z.infer<TState>>;
+    /**
+     * Update harness state. Validates against schema if provided.
+     * Emits state_changed event.
+     */
+    setState(updates: Partial<z.infer<TState>>): Promise<void>;
+    private getSchemaDefaults;
+    getModes(): HarnessMode<TState>[];
+    getCurrentModeId(): string;
+    getCurrentMode(): HarnessMode<TState>;
+    /**
+     * Switch to a different mode.
+     * Aborts any in-progress generation and switches to the mode's default model.
+     */
+    switchMode(modeId: string): Promise<void>;
+    /**
+     * Load the stored model ID for a specific mode.
+     * Falls back to: thread metadata -> mode's defaultModelId -> current model.
+     */
+    private loadModeModelId;
+    /**
+     * Get the agent for the current mode.
+     */
+    private getCurrentAgent;
+    /**
+     * Get a short display name from the current model ID.
+     */
+    getModelName(): string;
+    /**
+     * Get the full model ID (e.g., "anthropic/claude-sonnet-4").
+     */
+    getFullModelId(): string;
+    /**
+     * Switch to a different model at runtime.
+     */
+    switchModel(modelId: string, scope?: 'global' | 'thread', modeId?: string): Promise<void>;
+    getCurrentModelId(): string;
+    hasModelSelected(): boolean;
+    /**
+     * Check if the current model's provider has authentication configured.
+     * Uses the provider registry's `apiKeyEnvVar` and the optional `modelAuthChecker` hook.
+     */
+    getCurrentModelAuthStatus(): Promise<ModelAuthStatus>;
+    /**
+     * Get all available models from the provider registry with auth status.
+     * Uses the optional `modelAuthChecker` and `modelUseCountProvider` hooks.
+     */
+    getAvailableModels(): Promise<AvailableModel[]>;
+    private getProviderApiKeyEnvVar;
+    getCurrentThreadId(): string | null;
+    getResourceId(): string;
+    setResourceId(resourceId: string): void;
+    createThread(title?: string): Promise<HarnessThread>;
+    renameThread(title: string): Promise<void>;
+    switchThread(threadId: string): Promise<void>;
+    listThreads(options?: {
+        allResources?: boolean;
+    }): Promise<HarnessThread[]>;
+    persistThreadSetting(key: string, value: unknown): Promise<void>;
+    private removeThreadSetting;
+    private loadThreadMetadata;
+    /**
+     * Load observational memory progress for the current thread.
+     * Reads the OM record and recent messages to reconstruct status,
+     * then emits an `om_status` event for the UI.
+     */
+    loadOMProgress(): Promise<void>;
+    /**
+     * Returns the observer model ID from state, falling back to omConfig defaults.
+     */
+    getObserverModelId(): string | undefined;
+    /**
+     * Returns the reflector model ID from state, falling back to omConfig defaults.
+     */
+    getReflectorModelId(): string | undefined;
+    /**
+     * Returns the observation threshold from state, falling back to omConfig defaults.
+     */
+    getObservationThreshold(): number | undefined;
+    /**
+     * Returns the reflection threshold from state, falling back to omConfig defaults.
+     */
+    getReflectionThreshold(): number | undefined;
+    /**
+     * Resolves the observer model ID to a language model instance via `resolveModel`.
+     */
+    getResolvedObserverModel(): import("../memory").MastraLanguageModel | undefined;
+    /**
+     * Resolves the reflector model ID to a language model instance via `resolveModel`.
+     */
+    getResolvedReflectorModel(): import("../memory").MastraLanguageModel | undefined;
+    getSubagentModelId(agentType?: string): string | null;
+    setSubagentModelId(modelId: string, agentType?: string): Promise<void>;
+    grantSessionCategory(category: ToolCategory): void;
+    grantSessionTool(toolName: string): void;
+    getSessionGrants(): {
+        categories: ToolCategory[];
+        tools: string[];
+    };
+    getToolCategory(toolName: string): ToolCategory | null;
+    setPermissionCategory(category: ToolCategory, policy: PermissionPolicy): void;
+    setPermissionTool(toolName: string, policy: PermissionPolicy): void;
+    getPermissionRules(): PermissionRules;
+    /**
+     * Resolve whether a tool call should be auto-approved, denied, or asked.
+     * Resolution chain: yolo → per-tool policy → session tool grant →
+     * session category grant → category policy → "ask"
+     */
+    private resolveToolApproval;
+    /**
+     * Send a message to the current agent.
+     * Streams the response and emits events.
+     */
+    sendMessage(content: string, options?: {
+        images?: Array<{
+            data: string;
+            mimeType: string;
+        }>;
+    }): Promise<void>;
+    getMessages(options?: {
+        limit?: number;
+    }): Promise<HarnessMessage[]>;
+    getMessagesForThread(threadId: string, options?: {
+        limit?: number;
+    }): Promise<HarnessMessage[]>;
+    getFirstUserMessageForThread(threadId: string): Promise<HarnessMessage | null>;
+    private convertToHarnessMessage;
+    /**
+     * Process a stream response (shared between sendMessage and tool approval).
+     */
+    private processStream;
+    /**
+     * Abort the current operation.
+     */
+    abort(): void;
+    /**
+     * Steer the agent mid-stream: aborts current run and sends a new message.
+     */
+    steer(content: string): Promise<void>;
+    /**
+     * Queue a follow-up message to be processed after the current operation completes.
+     */
+    followUp(content: string): Promise<void>;
+    getFollowUpCount(): number;
+    isRunning(): boolean;
+    getCurrentRunId(): string | null;
+    /**
+     * Respond to a pending tool approval from the UI.
+     * "always_allow_category" grants the tool's category for the rest of the session, then approves.
+     */
+    resolveToolApprovalDecision(decision: 'approve' | 'decline' | 'always_allow_category'): void;
+    /**
+     * Register a pending question resolver.
+     * Called by agent tools (e.g., ask_user) to pause execution until the UI responds.
+     */
+    registerQuestion(questionId: string, resolve: (answer: string) => void): void;
+    /**
+     * Resolve a pending question with the user's answer.
+     * Called by the UI when the user responds to a question dialog.
+     */
+    respondToQuestion(questionId: string, answer: string): void;
+    /**
+     * Register a pending plan approval resolver.
+     * Called by agent tools (e.g., submit_plan) to pause execution until approval.
+     */
+    registerPlanApproval(planId: string, resolve: (result: {
+        action: 'approved' | 'rejected';
+        feedback?: string;
+    }) => void): void;
+    /**
+     * Respond to a pending plan approval.
+     * On approval: switches to the default mode, then resolves the promise.
+     * On rejection: resolves with feedback (stays in current mode).
+     */
+    respondToPlanApproval(planId: string, response: {
+        action: 'approved' | 'rejected';
+        feedback?: string;
+    }): Promise<void>;
+    private handleToolApprove;
+    private handleToolDecline;
+    /**
+     * Subscribe to harness events. Returns an unsubscribe function.
+     */
+    subscribe(listener: HarnessEventListener): () => void;
+    private emit;
+    /**
+     * Build the toolsets object that includes built-in harness tools (ask_user, submit_plan,
+     * and optionally subagent) plus any user-configured tools.
+     * Used by sendMessage, handleToolApprove, and handleToolDecline.
+     */
+    private buildToolsets;
+    /**
+     * Build request context for agent execution.
+     * Tools can access harness state via requestContext.get('harness').
+     */
+    private buildRequestContext;
+    getTokenUsage(): {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    private persistTokenUsage;
+    getWorkspace(): Workspace | undefined;
+    hasWorkspace(): boolean;
+    isWorkspaceReady(): boolean;
+    destroyWorkspace(): Promise<void>;
+    private startHeartbeats;
+    registerHeartbeat(handler: HeartbeatHandler): void;
+    removeHeartbeat(id: string): Promise<void>;
+    stopHeartbeats(): Promise<void>;
+    getSession(): Promise<HarnessSession>;
+    private generateId;
+}
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../../src/harness/harness.ts"],"names":[],"mappings":"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"}